Repository: react
Issue: findDOMNode deprecation
Labels: Type: Feature Request

## Timeline
1. <= 16.3: `findDOMNode` is *discouraged* but accepted for certain use cases
2. 16.3 (2018-03-28): `forwardRef` is introduced:
  It can be used in HOCs to avoid using `findDOMNode` on the enhanced component
3. 16.6 (2018-10-23): `findDOMNode` is deprecated in `React.StrictMode`
4. 16.7.alpha (2018-10-24): `React.Concurrent` mode is released:
  This mode *extends* `React.StrictMode` in a way that `findDOMNode` is deprecated in that mode too.
5. 16.8 (Q2 2019): stable `React.Concurrent` mode
  
## findDOMNode use cases
If you have more use cases please let me know. I only started with some examples from `mui-org/material-ui`.
### with a planned alternative
- focus handling (React Fire, "exploratory phase") 
- passive event listeners ([facebook/react#6436]). "Passive events will likely be a part of [React Fire]." - [facebook/react#13525]

## State of `forwardRef`
`react` has 3.4M downloads/week.

### `hoist-non-react-statics` (3.9M downloads/week; not clear what percentage is 2.x)
A utility mainly used in HOCs and [encouraged to use in the official react docs](https://reactjs.org/docs/higher-order-components.html#static-methods-must-be-copied-over). However everyone stuck at `2.x` will likely encounter issues with `forwardRef` since that version
does not handle any `react@^16.3` features. ^3.2.0 should have no issues apart from some minor
issues with propTypes hoisting from `forwardRef` to `forwardRef`. The latest stable from zeit/next still uses that outdated version. However the latest canary for 7.0.3 does not.

### react-docgen (400k downloads/week)
Not recognized as a valid component definition. PR open at [reactjs/react-docgen#311].

### react-redux (1.4M downloads/week)
`connect` does properly forward their refs in the beta release of 6.x. No timeline for stable release given
however 3 betas have already been released so it's probably soon.

### react-router (1.4M downloads/week)
`withRouter` is planned to forward refs ([ReactTraining/react-router#6056#issuecomment-435524678]).
However no comment about the other components and no major release candidate is published.

### display name
`React.forwardRef` components are recognized by `react-devtools`. However when wrapped
in a HOC it's very likely that the display name is lost. See [facebook/react#14319]

### The issue
**Assumptions:**
- you are not in control of your whole component tree i.e. you use components from 3rd party libraries
- you want to use `React.ConcurrentMode`
- Usable includes production and development. It specifically means for development that deprecation warnings in a component
  make that component not usable in development mode because of all the *noise* it adds in those cases.
  *Noise* because it's not actionable if that component is from a 3rd party library.

If none of those applies to you then you probably don't have an issue with `findDOMNode` deprecation.

The mode of a partial tree can only be made more restrictive but not loosened up. If
you wrap your tree in `React.StrictMode` and use a component from a 3rd party library
that 3rd party library has to be `React.StrictMode` compliant too. 

This means that you can't use `React.StrictMode` effectiveley. This might be ok since it's for development only anyway and has no implications for production. However Concurrent mode can have actual implications for production.  Since it is new and the community wants to use new things libraries have to make sure that they are strict mode compliant too.

In addition between the relase of an alternative in the form of `React.forwardRef` and the deprecation only 7 months have passed. One could argue that this is plenty of time but (at least from my perspective) the work on migrating from `findDOMNode` to refs and `forwardRef` was postponed because `findDOMNode` was not deprecated yet.  However the actual deprecation happened one day before the release of `unstable_ConcurrentMode` virtually giving no time to migrate. ~We'll have to see when a stable `16.7` release will happen but assuming this happens today only a month has passed between deprecation and *virtual* removal.~ [React 16.x Roadmap] was release pointing towards Q2 2019 as a release date of stable `React.Concurrent` mode. This relaxes pressure for library maintainers quite a bit IMO.

### Conclusion
Refs are not a viable upgrade path to replace `findDOMNode` yet. 
Until refs are usable without headaches from forwarding refs `findDOMNode` should be undeprecated.

## Releated
- [forwarding Refs guide on official react docs](https://reactjs.org/docs/forwarding-refs.html)
- [findDOMNode API documentation](https://reactjs.org/docs/react-dom.html#finddomnode) (includes arguments against usage)
- [pull request that deprecated findDOMNode](https://github.com/facebook/react/pull/13841)

[facebook/react#6436]: https://github.com/facebook/react/issues/6436
[facebook/react#13525]: https://github.com/facebook/react/issues/13525
[facebook/react#14319]: https://github.com/facebook/react/issues/14319
[reactjs/react-docgen#311]: https://github.com/reactjs/react-docgen/pull/311
[ReactTraining/react-router#6056#issuecomment-435524678]: https://github.com/ReactTraining/react-router/issues/6056#issuecomment-435524678
[React 16.x Roadmap]: https://reactjs.org/blog/2018/11/27/react-16-roadmap.html