[docs] Expand ref behavior

docs/src/modules/utils/generateMarkdown.js

@@ -273,9 +273,13 @@ function generateProps(reactAPI) {
     return textProps;
   }, text);
 
-  text = `${text}\nThe \`ref\` is ${
-    reactAPI.forwardsRefTo == null ? '**not** ' : ''
-  }forwarded to the root element.\n`;
+  let refHint = 'The `ref` is forwarded to the root element.';
+  if (reactAPI.forwardsRefTo == null) {
+    refHint = 'The component cannot hold a ref.';
+  } else if (reactAPI.forwardsRefTo === 'React.Component') {
+    refHint = 'The `ref` is attached to a component class.';
+  }
+  text = `${text}\n${refHint}\n`;
 
   if (reactAPI.spread) {
     text = `${text}

docs/src/modules/utils/parseTest.js

@@ -47,13 +47,23 @@ function findConformanceDescriptor(program) {
   return descriptor;
 }
 
-// extracts the property of window.*
+/**
+ *
+ * @param {import('@babel/core').Node} valueNode
+ */
 function getRefInstance(valueNode) {
   if (!babel.types.isMemberExpression(valueNode)) {
-    throw new Error('Expected window.*Element in refInstanceOf');
+    throw new Error('Expected a member expression in refInstanceof');
   }
 
-  return valueNode.property.name;
+  switch (valueNode.object.name) {
+    case 'window':
+      return valueNode.property.name;
+    case 'React':
+      return `React.${valueNode.property.name}`;
+    default:
+      throw new Error(`Unrecognized member expression starting with '${valueNode.object.name}'`);
+  }
 }
 
 /**

pages/api/click-away-listener.md

@@ -24,7 +24,7 @@ For instance, if you need to hide a menu when people click anywhere else on your
 | <span class="prop-name required">onClickAway&nbsp;*</span> | <span class="prop-type">func</span> |  | Callback fired when a "click away" event is detected. |
 | <span class="prop-name">touchEvent</span> | <span class="prop-type">enum:&nbsp;'onTouchStart'&nbsp;&#124;<br>&nbsp;'onTouchEnd'&nbsp;&#124;<br>&nbsp;false<br></span> | <span class="prop-default">'onTouchEnd'</span> | The touch event to listen to. You can disable the listener by providing `false`. |
 
-The `ref` is **not** forwarded to the root element.
+The component cannot hold a ref.
 
 Any other properties supplied will be spread to the root element ([EventListener](https://github.com/oliviertassinari/react-event-listener/)).
 

pages/api/collapse.md

@@ -27,7 +27,7 @@ It uses [react-transition-group](https://github.com/reactjs/react-transition-gro
 | <span class="prop-name">in</span> | <span class="prop-type">bool</span> |  | If `true`, the component will transition in. |
 | <span class="prop-name">timeout</span> | <span class="prop-type">union:&nbsp;number&nbsp;&#124;<br>&nbsp;{ enter?: number, exit?: number }&nbsp;&#124;<br>&nbsp;enum:&nbsp;'auto'<br><br></span> | <span class="prop-default">duration.standard</span> | The duration for the transition, in milliseconds. You may specify a single timeout for all transitions, or individually with an object.<br>Set to 'auto' to automatically calculate transition time based on height. |
 
-The `ref` is **not** forwarded to the root element.
+The component cannot hold a ref.
 
 Any other properties supplied will be spread to the root element ([Transition](https://reactcommunity.org/react-transition-group/#Transition)).
 

pages/api/css-baseline.md

@@ -20,7 +20,7 @@ Kickstart an elegant, consistent, and simple baseline to build upon.
 |:-----|:-----|:--------|:------------|
 | <span class="prop-name">children</span> | <span class="prop-type">node</span> | <span class="prop-default">null</span> | You can wrap a node. |
 
-The `ref` is **not** forwarded to the root element.
+The component cannot hold a ref.
 
 
 ## Demos

pages/api/dialog-content-text.md

@@ -21,7 +21,7 @@ import DialogContentText from '@material-ui/core/DialogContentText';
 | <span class="prop-name">children</span> | <span class="prop-type">node</span> |  | The content of the component. |
 | <span class="prop-name">classes</span> | <span class="prop-type">object</span> |  | Override or extend the styles applied to the component. See [CSS API](#css) below for more details. |
 
-The `ref` is **not** forwarded to the root element.
+The component cannot hold a ref.
 
 Any other properties supplied will be spread to the root element ([Typography](/api/typography/)).
 

pages/api/fade.md

@@ -23,7 +23,7 @@ It uses [react-transition-group](https://github.com/reactjs/react-transition-gro
 | <span class="prop-name">in</span> | <span class="prop-type">bool</span> |  | If `true`, the component will transition in. |
 | <span class="prop-name">timeout</span> | <span class="prop-type">union:&nbsp;number&nbsp;&#124;<br>&nbsp;{ enter?: number, exit?: number }<br></span> | <span class="prop-default">{  enter: duration.enteringScreen,  exit: duration.leavingScreen,}</span> | The duration for the transition, in milliseconds. You may specify a single timeout for all transitions, or individually with an object. |
 
-The `ref` is **not** forwarded to the root element.
+The component cannot hold a ref.
 
 Any other properties supplied will be spread to the root element ([Transition](https://reactcommunity.org/react-transition-group/#Transition)).
 

pages/api/grow.md

@@ -24,7 +24,7 @@ It uses [react-transition-group](https://github.com/reactjs/react-transition-gro
 | <span class="prop-name">in</span> | <span class="prop-type">bool</span> |  | If `true`, show the component; triggers the enter or exit animation. |
 | <span class="prop-name">timeout</span> | <span class="prop-type">union:&nbsp;number&nbsp;&#124;<br>&nbsp;{ enter?: number, exit?: number }&nbsp;&#124;<br>&nbsp;enum:&nbsp;'auto'<br><br></span> | <span class="prop-default">'auto'</span> | The duration for the transition, in milliseconds. You may specify a single timeout for all transitions, or individually with an object.<br>Set to 'auto' to automatically calculate transition time based on height. |
 
-The `ref` is **not** forwarded to the root element.
+The component cannot hold a ref.
 
 Any other properties supplied will be spread to the root element ([Transition](https://reactcommunity.org/react-transition-group/#Transition)).
 

pages/api/hidden.md

@@ -33,7 +33,7 @@ Responsively hides children based on the selected implementation.
 | <span class="prop-name">xsDown</span> | <span class="prop-type">bool</span> | <span class="prop-default">false</span> | If true, screens this size and down will be hidden. |
 | <span class="prop-name">xsUp</span> | <span class="prop-type">bool</span> | <span class="prop-default">false</span> | If true, screens this size and up will be hidden. |
 
-The `ref` is **not** forwarded to the root element.
+The component cannot hold a ref.
 
 Any other properties supplied will be spread to the root element (native element).
 

pages/api/list-item-avatar.md

@@ -22,7 +22,7 @@ and `align-items="flex-start"` mode styles to `Avatar`.
 | <span class="prop-name required">children&nbsp;*</span> | <span class="prop-type">element</span> |  | The content of the component – normally `Avatar`. |
 | <span class="prop-name">classes</span> | <span class="prop-type">object</span> |  | Override or extend the styles applied to the component. See [CSS API](#css) below for more details. |
 
-The `ref` is **not** forwarded to the root element.
+The component cannot hold a ref.
 
 Any other properties supplied will be spread to the root element (native element).
 

pages/api/no-ssr.md

@@ -28,7 +28,7 @@ This component can be useful in a variety of situations:
 | <span class="prop-name">defer</span> | <span class="prop-type">bool</span> | <span class="prop-default">false</span> | If `true`, the component will not only prevent server-side rendering. It will also defer the rendering of the children into a different screen frame. |
 | <span class="prop-name">fallback</span> | <span class="prop-type">node</span> | <span class="prop-default">null</span> | The fallback content to display. |
 
-The `ref` is **not** forwarded to the root element.
+The component cannot hold a ref.
 
 
 ## Demos

pages/api/popper.md

@@ -29,7 +29,7 @@ Poppers rely on the 3rd party library [Popper.js](https://github.com/FezVrasta/p
 | <span class="prop-name">popperOptions</span> | <span class="prop-type">object</span> |  | Options provided to the [`popper.js`](https://github.com/FezVrasta/popper.js) instance. |
 | <span class="prop-name">transition</span> | <span class="prop-type">bool</span> | <span class="prop-default">false</span> | Help supporting a react-transition-group/Transition component. |
 
-The `ref` is forwarded to the root element.
+The `ref` is attached to a component class.
 
 Any other properties supplied will be spread to the root element (native element).
 

pages/api/portal.md

@@ -24,7 +24,7 @@ that exists outside the DOM hierarchy of the parent component.
 | <span class="prop-name">disablePortal</span> | <span class="prop-type">bool</span> | <span class="prop-default">false</span> | Disable the portal behavior. The children stay within it's parent DOM hierarchy. |
 | <span class="prop-name">onRendered</span> | <span class="prop-type">func</span> |  | Callback fired once the children has been mounted into the `container`. |
 
-The `ref` is **not** forwarded to the root element.
+The component cannot hold a ref.
 
 
 ## Demos

pages/api/root-ref.md

@@ -48,6 +48,6 @@ class MyComponent extends React.Component {
 | <span class="prop-name required">children&nbsp;*</span> | <span class="prop-type">element</span> |  | The wrapped element. |
 | <span class="prop-name required">rootRef&nbsp;*</span> | <span class="prop-type">union:&nbsp;func&nbsp;&#124;<br>&nbsp;object<br></span> |  | Provide a way to access the DOM node of the wrapped element. You can provide a callback ref or a `React.createRef()` ref. |
 
-The `ref` is **not** forwarded to the root element.
+The component cannot hold a ref.
 
 

pages/api/slide.md

@@ -24,7 +24,7 @@ It uses [react-transition-group](https://github.com/reactjs/react-transition-gro
 | <span class="prop-name">in</span> | <span class="prop-type">bool</span> |  | If `true`, show the component; triggers the enter or exit animation. |
 | <span class="prop-name">timeout</span> | <span class="prop-type">union:&nbsp;number&nbsp;&#124;<br>&nbsp;{ enter?: number, exit?: number }<br></span> | <span class="prop-default">{  enter: duration.enteringScreen,  exit: duration.leavingScreen,}</span> | The duration for the transition, in milliseconds. You may specify a single timeout for all transitions, or individually with an object. |
 
-The `ref` is forwarded to the root element.
+The `ref` is attached to a component class.
 
 Any other properties supplied will be spread to the root element ([Transition](https://reactcommunity.org/react-transition-group/#Transition)).
 

pages/api/swipeable-drawer.md

@@ -30,7 +30,7 @@ import SwipeableDrawer from '@material-ui/core/SwipeableDrawer';
 | <span class="prop-name">swipeAreaWidth</span> | <span class="prop-type">number</span> | <span class="prop-default">20</span> | The width of the left most (or right most) area in pixels where the drawer can be swiped open from. |
 | <span class="prop-name">transitionDuration</span> | <span class="prop-type">union:&nbsp;number&nbsp;&#124;<br>&nbsp;{ enter?: number, exit?: number }<br></span> | <span class="prop-default">{ enter: duration.enteringScreen, exit: duration.leavingScreen }</span> | The duration for the transition, in milliseconds. You may specify a single timeout for all transitions, or individually with an object. |
 
-The `ref` is forwarded to the root element.
+The `ref` is attached to a component class.
 
 Any other properties supplied will be spread to the root element ([Drawer](/api/drawer/)).
 

pages/api/tooltip.md

@@ -38,7 +38,7 @@ import Tooltip from '@material-ui/core/Tooltip';
 | <span class="prop-name">TransitionComponent</span> | <span class="prop-type">elementType</span> | <span class="prop-default">Grow</span> | The component used for the transition. |
 | <span class="prop-name">TransitionProps</span> | <span class="prop-type">object</span> |  | Properties applied to the `Transition` element. |
 
-The `ref` is **not** forwarded to the root element.
+The component cannot hold a ref.
 
 Any other properties supplied will be spread to the root element (native element).
 

pages/api/touch-ripple.md

@@ -21,7 +21,7 @@ import TouchRipple from '@material-ui/core/ButtonBase/TouchRipple';
 | <span class="prop-name">center</span> | <span class="prop-type">bool</span> | <span class="prop-default">false</span> | If `true`, the ripple starts at the center of the component rather than at the point of interaction. |
 | <span class="prop-name">classes</span> | <span class="prop-type">object</span> |  | Override or extend the styles applied to the component. See [CSS API](#css) below for more details. |
 
-The `ref` is **not** forwarded to the root element.
+The component cannot hold a ref.
 
 Any other properties supplied will be spread to the root element (native element).
 

pages/api/zoom.md

@@ -24,7 +24,7 @@ It uses [react-transition-group](https://github.com/reactjs/react-transition-gro
 | <span class="prop-name">in</span> | <span class="prop-type">bool</span> |  | If `true`, the component will transition in. |
 | <span class="prop-name">timeout</span> | <span class="prop-type">union:&nbsp;number&nbsp;&#124;<br>&nbsp;{ enter?: number, exit?: number }<br></span> | <span class="prop-default">{  enter: duration.enteringScreen,  exit: duration.leavingScreen,}</span> | The duration for the transition, in milliseconds. You may specify a single timeout for all transitions, or individually with an object. |
 
-The `ref` is **not** forwarded to the root element.
+The component cannot hold a ref.
 
 Any other properties supplied will be spread to the root element ([Transition](https://reactcommunity.org/react-transition-group/#Transition)).
 

pages/lab/api/slider.md

@@ -32,7 +32,7 @@ import Slider from '@material-ui/lab/Slider';
 | <span class="prop-name">valueReducer</span> | <span class="prop-type">func</span> | <span class="prop-default">function defaultValueReducer(rawValue, props) {  const { disabled, step } = props;  if (disabled) {    return null;  }  if (step) {    return roundToStep(rawValue, step);  }  return Number(rawValue.toFixed(3));}</span> | the reducer used to process the value emitted from the slider. If `null` or the same value is returned no change is emitted.<br><br>**Signature:**<br>`function(rawValue: number, props: SliderProps, event: Event) => void`<br>*rawValue:* value in [min, max]<br>*props:* current props of the Slider<br>*event:* the event the change was triggered from |
 | <span class="prop-name">vertical</span> | <span class="prop-type">bool</span> |  | If `true`, the slider will be vertical. |
 
-The `ref` is **not** forwarded to the root element.
+The component cannot hold a ref.
 
 Any other properties supplied will be spread to the root element (native element).
 

pages/lab/api/speed-dial-action.md

@@ -27,7 +27,7 @@ import SpeedDialAction from '@material-ui/lab/SpeedDialAction';
 | <span class="prop-name">tooltipPlacement</span> | <span class="prop-type">enum:&nbsp;'bottom-end', 'bottom-start', 'bottom', 'left-end', 'left-start', 'left', 'right-end', 'right-start', 'right', 'top-end', 'top-start', 'top'<br></span> | <span class="prop-default">'left'</span> | Placement of the tooltip. |
 | <span class="prop-name required">tooltipTitle&nbsp;*</span> | <span class="prop-type">node</span> |  | Label to display in the tooltip. |
 
-The `ref` is **not** forwarded to the root element.
+The component cannot hold a ref.
 
 Any other properties supplied will be spread to the root element ([Tooltip](/api/tooltip/)).
 

pages/lab/api/speed-dial-icon.md

@@ -22,7 +22,7 @@ import SpeedDialIcon from '@material-ui/lab/SpeedDialIcon';
 | <span class="prop-name">icon</span> | <span class="prop-type">node</span> |  | The icon to display in the SpeedDial Floating Action Button. |
 | <span class="prop-name">openIcon</span> | <span class="prop-type">node</span> |  | The icon to display in the SpeedDial Floating Action Button when the SpeedDial is open. |
 
-The `ref` is **not** forwarded to the root element.
+The component cannot hold a ref.
 
 Any other properties supplied will be spread to the root element (native element).
 

pages/lab/api/speed-dial.md

@@ -32,7 +32,7 @@ import SpeedDial from '@material-ui/lab/SpeedDial';
 | <span class="prop-name">transitionDuration</span> | <span class="prop-type">union:&nbsp;number&nbsp;&#124;<br>&nbsp;{ enter?: number, exit?: number }<br></span> | <span class="prop-default">{  enter: duration.enteringScreen,  exit: duration.leavingScreen,}</span> | The duration for the transition, in milliseconds. You may specify a single timeout for all transitions, or individually with an object. |
 | <span class="prop-name">TransitionProps</span> | <span class="prop-type">object</span> |  | Properties applied to the `Transition` element. |
 
-The `ref` is **not** forwarded to the root element.
+The component cannot hold a ref.
 
 Any other properties supplied will be spread to the root element (native element).
 

pages/lab/api/toggle-button-group.md

@@ -24,7 +24,7 @@ import ToggleButtonGroup from '@material-ui/lab/ToggleButtonGroup';
 | <span class="prop-name">onChange</span> | <span class="prop-type">func</span> |  | Callback fired when the value changes.<br><br>**Signature:**<br>`function(event: object, value: object) => void`<br>*event:* The event source of the callback<br>*value:* of the selected buttons. When `exclusive` is true this is a single value; when false an array of selected values. If no value is selected and `exclusive` is true the value is null; when false an empty array. |
 | <span class="prop-name">value</span> | <span class="prop-type">any</span> |  | The currently selected value within the group or an array of selected values when `exclusive` is false. |
 
-The `ref` is **not** forwarded to the root element.
+The component cannot hold a ref.
 
 Any other properties supplied will be spread to the root element (native element).
 

pages/lab/api/toggle-button.md

@@ -26,7 +26,7 @@ import ToggleButton from '@material-ui/lab/ToggleButton';
 | <span class="prop-name">selected</span> | <span class="prop-type">bool</span> |  | If `true`, the button will be rendered in an active state. |
 | <span class="prop-name required">value&nbsp;*</span> | <span class="prop-type">any</span> |  | The value to associate with the button when selected in a ToggleButtonGroup. |
 
-The `ref` is **not** forwarded to the root element.
+The component cannot hold a ref.
 
 Any other properties supplied will be spread to the root element ([ButtonBase](/api/button-base/)).