Document deprecation of findDOMNode

We might want to open an RFC for fragment refs which could solve the one
remaining use case in a better way but at least let us get the deprecation
in.

Author: sebmarkbage

content/docs/reference-react-dom.md

@@ -86,6 +86,10 @@ Remove a mounted React component from the DOM and clean up its event handlers an
 
 ### `findDOMNode()`
 
+> Note:
+>
+> `findDOMNode` is an escape hatch used to access the underlying DOM node. In most cases, use of this escape hatch is discouraged because it pierces the component abstraction. [It has been deprecated in `StrictMode`.](/docs/strict-mode.html#warning-about-deprecated-finddomnode-usage)
+
 ```javascript
 ReactDOM.findDOMNode(component)
 ```
@@ -95,8 +99,6 @@ When a component renders to `null` or `false`, `findDOMNode` returns `null`. Whe
 
 > Note:
 >
-> `findDOMNode` is an escape hatch used to access the underlying DOM node. In most cases, use of this escape hatch is discouraged because it pierces the component abstraction.
->
 > `findDOMNode` only works on mounted components (that is, components that have been placed in the DOM). If you try to call this on a component that has not been mounted yet (like calling `findDOMNode()` in `render()` on a component that has yet to be created) an exception will be thrown.
 >
 > `findDOMNode` cannot be used on function components.

content/docs/refs-and-the-dom.md

@@ -199,7 +199,7 @@ If you use React 16.3 or higher, we recommend to use [ref forwarding](/docs/forw
 
 If you use React 16.2 or lower, or if you need more flexibility than provided by ref forwarding, you can use [this alternative approach](https://gist.github.com/gaearon/1a018a023347fe1c2476073330cc5509) and explicitly pass a ref as a differently named prop.
 
-When possible, we advise against exposing DOM nodes, but it can be a useful escape hatch. Note that this approach requires you to add some code to the child component. If you have absolutely no control over the child component implementation, your last option is to use [`findDOMNode()`](/docs/react-dom.html#finddomnode), but it is discouraged.
+When possible, we advise against exposing DOM nodes, but it can be a useful escape hatch. Note that this approach requires you to add some code to the child component. If you have absolutely no control over the child component implementation, your last option is to use [`findDOMNode()`](/docs/react-dom.html#finddomnode), but it is discouraged and deprecated in [`StrictMode`](/docs/strict-mode.html#warning-about-deprecated-finddomnode-usage).
 
 ### Callback Refs
 

content/docs/strict-mode.md

@@ -18,6 +18,7 @@ In the above example, strict mode checks will *not* be run against the `Header`
 `StrictMode` currently helps with:
 * [Identifying components with unsafe lifecycles](#identifying-unsafe-lifecycles)
 * [Warning about legacy string ref API usage](#warning-about-legacy-string-ref-api-usage)
+* [Warning about deprecated findDOMNode usage](#warning-about-deprecated-finddomnode-usage)
 * [Detecting unexpected side effects](#detecting-unexpected-side-effects)
 * [Detecting legacy context API](#detecting-legacy-context-api)
 
@@ -50,6 +51,32 @@ Since object refs were largely added as a replacement for string refs, strict mo
 
 [Learn more about the new `createRef` API here.](/docs/refs-and-the-dom.html)
 
+### Warning about deprecated findDOMNode usage
+
+React used to support `findDOMNode` to search the tree for a DOM node given a class instance. Normally you don't need this because you can [attach a ref directly to a DOM node](/docs/refs-and-the-dom.html#creating-refs).
+
+`findDOMNode` can also be used on class components but this was breaking abstraction levels by allowing a parent to demand that certain children was rendered. It creates a refactoring hazard where you can't change the implementation details of a component because a parent might be reaching into its DOM node. `findDOMNode` only returns the first child, but with the use of Fragments, it is possible for a component to render multiple DOM nodes. `findDOMNode` is a one time read API. It only gave you an answer when you asked for it. If a child component renders a different node, there is no way to handle this change. Therefore `findDOMNode` only worked if components always return a single DOM node that never changes.
+
+You can instead make this explicit by pass a ref to your custom component and pass that along to the DOM using [ref forwarding](/docs/forwarding-refs.html#forwarding-refs-to-dom-components).
+
+You can also add a wrapper DOM node in your component and attach a ref directly to it.
+
+```javascript{4,7}
+class MyComponent extends React.Component {
+  constructor(props) {
+    super(props);
+    this.wrapper = React.createRef();
+  }
+  render() {
+    return <div ref={this.wrapper}>{this.props.children}</div>;
+  }
+}
+```
+
+> Note:
+>
+> In CSS, the [`display: contents`](https://developer.mozilla.org/en-US/docs/Web/CSS/display#display_contents) attribute can be used if you don't want the node to be part of the layout.
+
 ### Detecting unexpected side effects
 
 Conceptually, React does work in two phases: