[docs] Document ref forwarding (requirements)

[eps1lon]

Close #14415

---

TODO:

• ClickAwayListener child ref (and derived components)
• ref forwarding in "API Design Approach"
• https://next.material-ui.com/getting-started/faq/#how-can-i-access-the-dom-element

[mui-pr-bot]

No bundle size changes comparing 5236588...64e2488

Generated by 🚫 dangerJS against 64e2488

[oliviertassinari]

Should we add a soft deprecation message for RootRef in the documentation? https://next.material-ui.com/api/root-ref/#rootref-api

[mbrookes]

"?" in a review comment means I wasn't sure...

[mbrookes]

Suggested change

	and a designated prop in your class component to forward the `ref` to a built-in
	and a designated prop in your class component to forward the `ref` to a DOM element.

?

[eps1lon]

I'll be honest I don't know how to properly explain this. Maybe I'm using the term ref wrong maybe it isn't well defined.

If I refer to the term ref then I mean the return value from e.g. React.createRef(). So the ref is the full object { current: instance }. What we end up is attaching the ref object { current: ... } to the host component i.e. <div ref={{ current: ... }} />. Or in other words the ref is the thing you pass to the ref prop¹ of a component. You'll probably still catch me doing <Component ref={ref => ...} /> where naming the parameter ref is probably a misnomer. <Component ref={current => ...} /> should be clearer.

The DOM element will then be ref.current. Or more generally ref.current will point to the component instance. For host components rendered with react-dom it will be an instance of a DOM Element.

Please tell me if that doesn't make sense. In the end the most important thing is that we don't confuse the reader. It's not that important to be technically accurate but that one understands how to fix the issue at hand.

¹ ref gets a special treatment so calling it a ref might not be 100% accurate.

[eps1lon]

Suggested change

	and a designated prop in your class component to forward the `ref` to a built-in
	and a designated prop in your class component to forward the `ref` to a DOM

[mbrookes]

What I found confusing was the terminology "built-in component". What exactly does that refer to?

(I also overlooked the fact that a ref is a pointer to the full object, not just a discrete DOM element, so my suggested replacement wasn't any more helpful.)

updated