diff --git a/docs/scripts/buildApi.js b/docs/scripts/buildApi.js index ed72a3950c52c8..e77f71abd9ac38 100644 --- a/docs/scripts/buildApi.js +++ b/docs/scripts/buildApi.js @@ -7,6 +7,7 @@ import { parse as docgenParse } from 'react-docgen'; import generateMarkdown from '../src/modules/utils/generateMarkdown'; import { findPagesMarkdown, findComponents } from '../src/modules/utils/find'; import { getHeaders } from '../src/modules/utils/parseMarkdown'; +import parseTest from '../src/modules/utils/parseTest'; import createMuiTheme from '../../packages/material-ui/src/styles/createMuiTheme'; import getStylesCreator from '../../packages/material-ui-styles/src/getStylesCreator'; @@ -73,7 +74,7 @@ function getInheritance(src) { }; } -function buildDocs(options) { +async function buildDocs(options) { const { component: componentObject, pagesMarkdown } = options; const src = readFileSync(componentObject.filename, 'utf8'); @@ -143,6 +144,10 @@ function buildDocs(options) { reactAPI.src = src; reactAPI.spread = spread; + const testInfo = await parseTest(componentObject.filename); + // no Object.assign to visually check for collisions + reactAPI.forwardsRefTo = testInfo.forwardsRefTo; + // if (reactAPI.name !== 'TableCell') { // return; // } @@ -199,7 +204,11 @@ function run() { const components = findComponents(path.resolve(rootDirectory, args[2])); components.forEach(component => { - buildDocs({ component, pagesMarkdown }); + buildDocs({ component, pagesMarkdown }).catch(error => { + console.warn(`error building docs for ${component.filename}`); + console.error(error); + process.exit(1); + }); }); } diff --git a/docs/src/modules/utils/generateMarkdown.js b/docs/src/modules/utils/generateMarkdown.js index d7a53d29c922cd..37eb1fd7438825 100644 --- a/docs/src/modules/utils/generateMarkdown.js +++ b/docs/src/modules/utils/generateMarkdown.js @@ -273,6 +273,14 @@ function generateProps(reactAPI) { return textProps; }, text); + 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} Any other properties supplied will be spread to the root element (${ diff --git a/docs/src/modules/utils/parseTest.js b/docs/src/modules/utils/parseTest.js new file mode 100644 index 00000000000000..23ecbffdfff7c1 --- /dev/null +++ b/docs/src/modules/utils/parseTest.js @@ -0,0 +1,102 @@ +import * as babel from '@babel/core'; +import { readFile } from 'fs-extra'; +import * as path from 'path'; + +const workspaceRoot = path.join(__dirname, '../../../../'); +const babelConfigPath = path.join(workspaceRoot, 'babel.config.js'); + +function withExtension(filepath, extension) { + return path.join( + path.dirname(filepath), + path.basename(filepath, path.extname(filepath)) + extension, + ); +} + +/** + * @param {string} filename + * @param {string} configFilePath + */ +async function parseWithConfig(filename, configFilePath) { + const source = await readFile(filename, { encoding: 'utf8' }); + const partialConfig = babel.loadPartialConfig({ + configFile: configFilePath, + filename, + }); + return babel.parseAsync(source, partialConfig.options); +} + +function findConformanceDescriptor(program) { + const { types: t } = babel; + + let descriptor = {}; + babel.traverse(program, { + CallExpression(babelPath) { + const { node: callExpression } = babelPath; + const { callee } = callExpression; + if (t.isIdentifier(callee) && callee.name === 'describeConformance') { + // describeConformance(element, () => options); + descriptor = callExpression.arguments[1].body; + } + }, + }); + + if (descriptor.type != null && !t.isObjectExpression(descriptor)) { + throw new Error(`Expected an object expression as a descriptor but found ${descriptor.type}`); + } + + return descriptor; +} + +/** + * + * @param {import('@babel/core').Node} valueNode + */ +function getRefInstance(valueNode) { + if (!babel.types.isMemberExpression(valueNode)) { + throw new Error('Expected a member expression in refInstanceof'); + } + + 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}'`); + } +} + +/** + * @typedef {Object} ParseResult + * @property {string?} forwardsRefTo + */ + +/** + * + * @param {string} componentFilename + * @returns {ParseResult} + */ +export default async function parseTest(componentFilename) { + const testFilename = withExtension(componentFilename, '.test.js'); + const babelParseResult = await parseWithConfig(testFilename, babelConfigPath); + const descriptor = findConformanceDescriptor(babelParseResult.program); + + const result = { + forwardsRefTo: undefined, + }; + + const { properties = [] } = descriptor; + properties.forEach(property => { + const key = property.key.name; + + switch (key) { + case 'refInstanceof': + result.forwardsRefTo = getRefInstance(property.value); + break; + default: + break; + } + }); + + return result; +} diff --git a/packages/material-ui/src/ButtonBase/TouchRipple.test.js b/packages/material-ui/src/ButtonBase/TouchRipple.test.js index 2d25aa51b6ecd3..cb25be88b1de78 100644 --- a/packages/material-ui/src/ButtonBase/TouchRipple.test.js +++ b/packages/material-ui/src/ButtonBase/TouchRipple.test.js @@ -4,7 +4,7 @@ import { assert } from 'chai'; import { createShallow, createMount, - findOutermostIntrinsic, + describeConformance, getClasses, unwrap, } from '@material-ui/core/test-utils'; @@ -29,17 +29,13 @@ describe('', () => { mount.cleanUp(); }); - it('should render a span', () => { - const wrapper = mount(); - const root = findOutermostIntrinsic(wrapper); - assert.strictEqual(root.type(), 'span'); - assert.strictEqual(root.hasClass(classes.root), true); - }); - - it('should render the custom className', () => { - const wrapper = mount(); - assert.strictEqual(findOutermostIntrinsic(wrapper).hasClass('test-class-name'), true); - }); + describeConformance(, () => ({ + classes, + inheritComponent: 'span', + mount, + refInstanceof: React.Component, + testComponentPropWith: false, + })); describe('prop: center', () => { it('should should compute the right ripple dimensions', () => { diff --git a/pages/api/app-bar.md b/pages/api/app-bar.md index 9ca19737fd4264..c8406eb4ed1b30 100644 --- a/pages/api/app-bar.md +++ b/pages/api/app-bar.md @@ -23,6 +23,8 @@ import AppBar from '@material-ui/core/AppBar'; | color | enum: 'inherit' |
 'primary' |
 'secondary' |
 'default'
 | 'primary' | The color of the component. It supports those theme colors that make sense for this component. | | position | enum: 'fixed', 'absolute', 'sticky', 'static', 'relative'
 | 'fixed' | The positioning type. The behavior of the different options is described [in the MDN web docs](https://developer.mozilla.org/en-US/docs/Learn/CSS/CSS_layout/Positioning). Note: `sticky` is not universally supported and will fall back to `static` when unavailable. | +The `ref` is forwarded to the root element. + Any other properties supplied will be spread to the root element ([Paper](/api/paper/)). ## CSS diff --git a/pages/api/avatar.md b/pages/api/avatar.md index e245947fe39b02..4087aa00dcad84 100644 --- a/pages/api/avatar.md +++ b/pages/api/avatar.md @@ -27,6 +27,8 @@ import Avatar from '@material-ui/core/Avatar'; | src | string | | The `src` attribute for the `img` element. | | srcSet | string | | The `srcSet` attribute for the `img` element. | +The `ref` is forwarded to the root element. + Any other properties supplied will be spread to the root element (native element). ## CSS diff --git a/pages/api/backdrop.md b/pages/api/backdrop.md index d760773c429967..700f69a36c7e35 100644 --- a/pages/api/backdrop.md +++ b/pages/api/backdrop.md @@ -23,6 +23,8 @@ import Backdrop from '@material-ui/core/Backdrop'; | open * | bool | | If `true`, the backdrop is open. | | transitionDuration | union: number |
 { enter?: number, exit?: number }
 | | 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. + Any other properties supplied will be spread to the root element (native element). ## CSS diff --git a/pages/api/badge.md b/pages/api/badge.md index 424ac7d26eb10a..c0b2db04602e39 100644 --- a/pages/api/badge.md +++ b/pages/api/badge.md @@ -28,6 +28,8 @@ import Badge from '@material-ui/core/Badge'; | showZero | bool | false | Controls whether the badge is hidden when `badgeContent` is zero. | | variant | enum: 'standard' |
 'dot'
 | 'standard' | The variant to use. | +The `ref` is forwarded to the root element. + Any other properties supplied will be spread to the root element (native element). ## CSS diff --git a/pages/api/bottom-navigation-action.md b/pages/api/bottom-navigation-action.md index 7f677e9820c6a7..759435c10dea60 100644 --- a/pages/api/bottom-navigation-action.md +++ b/pages/api/bottom-navigation-action.md @@ -25,6 +25,8 @@ import BottomNavigationAction from '@material-ui/core/BottomNavigationAction'; | showLabel | bool | | If `true`, the `BottomNavigationAction` will show its label. By default, only the selected `BottomNavigationAction` inside `BottomNavigation` will show its label. | | value | any | | You can provide your own value. Otherwise, we fallback to the child position index. | +The `ref` is forwarded to the root element. + Any other properties supplied will be spread to the root element ([ButtonBase](/api/button-base/)). ## CSS diff --git a/pages/api/bottom-navigation.md b/pages/api/bottom-navigation.md index 1230333b0d19c9..4e9c9136fa6782 100644 --- a/pages/api/bottom-navigation.md +++ b/pages/api/bottom-navigation.md @@ -25,6 +25,8 @@ import BottomNavigation from '@material-ui/core/BottomNavigation'; | showLabels | bool | false | If `true`, all `BottomNavigationAction`s will show their labels. By default, only the selected `BottomNavigationAction` will show its label. | | value | any | | The value of the currently selected `BottomNavigationAction`. | +The `ref` is forwarded to the root element. + Any other properties supplied will be spread to the root element (native element). ## CSS diff --git a/pages/api/breadcrumbs.md b/pages/api/breadcrumbs.md index a108c1c7bc96de..08a8b674f2eb29 100644 --- a/pages/api/breadcrumbs.md +++ b/pages/api/breadcrumbs.md @@ -26,6 +26,8 @@ import Breadcrumbs from '@material-ui/core/Breadcrumbs'; | maxItems | number | 8 | Specifies the maximum number of breadcrumbs to display. When there are more than the maximum number, only the first and last will be shown, with an ellipsis in between. | | separator | node | '/' | Custom separator node. | +The `ref` is forwarded to the root element. + Any other properties supplied will be spread to the root element (native element). ## Demos diff --git a/pages/api/button-base.md b/pages/api/button-base.md index 0d75a712462947..68f3e265b6cef8 100644 --- a/pages/api/button-base.md +++ b/pages/api/button-base.md @@ -35,6 +35,8 @@ It contains a load of style reset and some focus/ripple logic. | TouchRippleProps | object | | Properties applied to the `TouchRipple` element. | | type | enum: 'submit' |
 'reset' |
 'button'
 | 'button' | Used to control the button's purpose. This property passes the value to the `type` attribute of the native button component. | +The `ref` is forwarded to the root element. + Any other properties supplied will be spread to the root element (native element). ## CSS diff --git a/pages/api/button.md b/pages/api/button.md index 9190ac6305ab98..21bf8ecc8c31a5 100644 --- a/pages/api/button.md +++ b/pages/api/button.md @@ -30,6 +30,8 @@ import Button from '@material-ui/core/Button'; | size | enum: 'small' |
 'medium' |
 'large'
 | 'medium' | The size of the button. `small` is equivalent to the dense button styling. | | variant | enum: 'text' |
 'outlined' |
 'contained'
 | 'text' | The variant to use. | +The `ref` is forwarded to the root element. + Any other properties supplied will be spread to the root element ([ButtonBase](/api/button-base/)). ## CSS diff --git a/pages/api/card-action-area.md b/pages/api/card-action-area.md index 1a8de968cfad97..99a80a4f5f36c7 100644 --- a/pages/api/card-action-area.md +++ b/pages/api/card-action-area.md @@ -21,6 +21,8 @@ import CardActionArea from '@material-ui/core/CardActionArea'; | children | node | | The content of the component. | | classes | object | | Override or extend the styles applied to the component. See [CSS API](#css) below for more details. | +The `ref` is forwarded to the root element. + Any other properties supplied will be spread to the root element ([ButtonBase](/api/button-base/)). ## CSS diff --git a/pages/api/card-actions.md b/pages/api/card-actions.md index 9b98c0d386584d..7e4c17b2c32e91 100644 --- a/pages/api/card-actions.md +++ b/pages/api/card-actions.md @@ -22,6 +22,8 @@ import CardActions from '@material-ui/core/CardActions'; | classes | object | | Override or extend the styles applied to the component. See [CSS API](#css) below for more details. | | disableActionSpacing | bool | false | If `true`, the card actions do not have additional margin. | +The `ref` is forwarded to the root element. + Any other properties supplied will be spread to the root element (native element). ## CSS diff --git a/pages/api/card-content.md b/pages/api/card-content.md index 579dbb7cf0bcf3..14ad04f7d6b527 100644 --- a/pages/api/card-content.md +++ b/pages/api/card-content.md @@ -21,6 +21,8 @@ import CardContent from '@material-ui/core/CardContent'; | classes | object | | Override or extend the styles applied to the component. See [CSS API](#css) below for more details. | | component | elementType | 'div' | The component used for the root node. Either a string to use a DOM element or a component. | +The `ref` is forwarded to the root element. + Any other properties supplied will be spread to the root element (native element). ## CSS diff --git a/pages/api/card-header.md b/pages/api/card-header.md index 162359827d3cbc..b1bf3fd893492d 100644 --- a/pages/api/card-header.md +++ b/pages/api/card-header.md @@ -28,6 +28,8 @@ import CardHeader from '@material-ui/core/CardHeader'; | title | node | | The content of the Card Title. | | titleTypographyProps | object | | These props will be forwarded to the title (as long as disableTypography is not `true`). | +The `ref` is forwarded to the root element. + Any other properties supplied will be spread to the root element (native element). ## CSS diff --git a/pages/api/card-media.md b/pages/api/card-media.md index 3a104391b676de..e6a29f020c2912 100644 --- a/pages/api/card-media.md +++ b/pages/api/card-media.md @@ -23,6 +23,8 @@ import CardMedia from '@material-ui/core/CardMedia'; | image | string | | Image to be displayed as a background image. Either `image` or `src` prop must be specified. Note that caller must specify height otherwise the image will not be visible. | | src | string | | An alias for `image` property. Available only with media components. Media components: `video`, `audio`, `picture`, `iframe`, `img`. | +The `ref` is forwarded to the root element. + Any other properties supplied will be spread to the root element (native element). ## CSS diff --git a/pages/api/card.md b/pages/api/card.md index 68a0da73fdfa10..9dd03abd45caf0 100644 --- a/pages/api/card.md +++ b/pages/api/card.md @@ -21,6 +21,8 @@ import Card from '@material-ui/core/Card'; | classes | object | | Override or extend the styles applied to the component. See [CSS API](#css) below for more details. | | raised | bool | false | If `true`, the card will use raised styling. | +The `ref` is forwarded to the root element. + Any other properties supplied will be spread to the root element ([Paper](/api/paper/)). ## CSS diff --git a/pages/api/checkbox.md b/pages/api/checkbox.md index 37f8249d5e8e3f..dabbc7c0492507 100644 --- a/pages/api/checkbox.md +++ b/pages/api/checkbox.md @@ -34,6 +34,8 @@ import Checkbox from '@material-ui/core/Checkbox'; | type | string | | The input component property `type`. | | value | string | | The value of the component. | +The `ref` is forwarded to the root element. + Any other properties supplied will be spread to the root element ([IconButton](/api/icon-button/)). ## CSS diff --git a/pages/api/chip.md b/pages/api/chip.md index 14d123b8db31bc..0e42aa77fc23e0 100644 --- a/pages/api/chip.md +++ b/pages/api/chip.md @@ -30,6 +30,8 @@ Chips represent complex entities in small blocks, such as a contact. | onDelete | func | | Callback function fired when the delete icon is clicked. If set, the delete icon will be shown. | | variant | enum: 'default' |
 'outlined'
 | 'default' | The variant to use. | +The `ref` is forwarded to the root element. + Any other properties supplied will be spread to the root element (native element). ## CSS diff --git a/pages/api/circular-progress.md b/pages/api/circular-progress.md index 041ee73294f714..f6aaa6d0b6c33c 100644 --- a/pages/api/circular-progress.md +++ b/pages/api/circular-progress.md @@ -30,6 +30,8 @@ attribute to `true` on that region until it has finished loading. | value | number | 0 | The value of the progress indicator for the determinate and static variants. Value between 0 and 100. | | variant | enum: 'determinate' |
 'indeterminate' |
 'static'
 | 'indeterminate' | The variant to use. Use indeterminate when there is no progress value. | +The `ref` is forwarded to the root element. + Any other properties supplied will be spread to the root element (native element). ## CSS diff --git a/pages/api/click-away-listener.md b/pages/api/click-away-listener.md index fc08c757aeeeb4..beb63d1ddc6a4a 100644 --- a/pages/api/click-away-listener.md +++ b/pages/api/click-away-listener.md @@ -24,6 +24,8 @@ For instance, if you need to hide a menu when people click anywhere else on your | onClickAway * | func | | Callback fired when a "click away" event is detected. | | touchEvent | enum: 'onTouchStart' |
 'onTouchEnd' |
 false
 | 'onTouchEnd' | The touch event to listen to. You can disable the listener by providing `false`. | +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/)). ## Inheritance diff --git a/pages/api/collapse.md b/pages/api/collapse.md index 57bcf17e3b91ff..f0e9aa1cb22354 100644 --- a/pages/api/collapse.md +++ b/pages/api/collapse.md @@ -27,6 +27,8 @@ It uses [react-transition-group](https://github.com/reactjs/react-transition-gro | in | bool | | If `true`, the component will transition in. | | timeout | union: number |
 { enter?: number, exit?: number } |
 enum: 'auto'

 | duration.standard | The duration for the transition, in milliseconds. You may specify a single timeout for all transitions, or individually with an object.
Set to 'auto' to automatically calculate transition time based on height. | +The `ref` is forwarded to the root element. + Any other properties supplied will be spread to the root element ([Transition](https://reactcommunity.org/react-transition-group/#Transition)). ## CSS diff --git a/pages/api/container.md b/pages/api/container.md index 2ccf1b7dc12d56..76681f9a7ede57 100644 --- a/pages/api/container.md +++ b/pages/api/container.md @@ -24,6 +24,8 @@ import Container from '@material-ui/core/Container'; | fixed | bool | false | Set the max-width to match the min-width of the current breakpoint. This is useful if you'd prefer to design for a fixed set of sizes instead of trying to accommodate a fully fluid viewport. It's fluid by default. | | maxWidth | enum: 'xs', 'sm', 'md', 'lg', 'xl', false
 | 'lg' | Determine the max-width of the container. The container width grows with the size of the screen. Set to `false` to disable `maxWidth`. | +The `ref` is forwarded to the root element. + Any other properties supplied will be spread to the root element (native element). ## CSS diff --git a/pages/api/css-baseline.md b/pages/api/css-baseline.md index 5ece1f688a7e64..71836d5d2ad726 100644 --- a/pages/api/css-baseline.md +++ b/pages/api/css-baseline.md @@ -20,6 +20,8 @@ Kickstart an elegant, consistent, and simple baseline to build upon. |:-----|:-----|:--------|:------------| | children | node | null | You can wrap a node. | +The component cannot hold a ref. + ## Demos diff --git a/pages/api/dialog-actions.md b/pages/api/dialog-actions.md index a23aeefea6abd6..905b311cd41bb4 100644 --- a/pages/api/dialog-actions.md +++ b/pages/api/dialog-actions.md @@ -22,6 +22,8 @@ import DialogActions from '@material-ui/core/DialogActions'; | classes | object | | Override or extend the styles applied to the component. See [CSS API](#css) below for more details. | | disableActionSpacing | bool | false | If `true`, the dialog actions do not have additional margin. | +The `ref` is forwarded to the root element. + Any other properties supplied will be spread to the root element (native element). ## CSS diff --git a/pages/api/dialog-content-text.md b/pages/api/dialog-content-text.md index 426df6ced15b94..7ba6927b5043fe 100644 --- a/pages/api/dialog-content-text.md +++ b/pages/api/dialog-content-text.md @@ -21,6 +21,8 @@ import DialogContentText from '@material-ui/core/DialogContentText'; | children | node | | The content of the component. | | classes | object | | Override or extend the styles applied to the component. See [CSS API](#css) below for more details. | +The component cannot hold a ref. + Any other properties supplied will be spread to the root element ([Typography](/api/typography/)). ## CSS diff --git a/pages/api/dialog-content.md b/pages/api/dialog-content.md index 800270569c08b0..3cd22d42ca9825 100644 --- a/pages/api/dialog-content.md +++ b/pages/api/dialog-content.md @@ -22,6 +22,8 @@ import DialogContent from '@material-ui/core/DialogContent'; | classes | object | | Override or extend the styles applied to the component. See [CSS API](#css) below for more details. | | dividers | bool | false | Display the top and bottom dividers. | +The `ref` is forwarded to the root element. + Any other properties supplied will be spread to the root element (native element). ## CSS diff --git a/pages/api/dialog-title.md b/pages/api/dialog-title.md index 25dd0104a6e893..7e0e6df45395e5 100644 --- a/pages/api/dialog-title.md +++ b/pages/api/dialog-title.md @@ -22,6 +22,8 @@ import DialogTitle from '@material-ui/core/DialogTitle'; | classes | object | | Override or extend the styles applied to the component. See [CSS API](#css) below for more details. | | disableTypography | bool | false | If `true`, the children won't be wrapped by a typography component. For instance, this can be useful to render an h4 instead of the default h2. | +The `ref` is forwarded to the root element. + Any other properties supplied will be spread to the root element (native element). ## CSS diff --git a/pages/api/dialog.md b/pages/api/dialog.md index ebd2b905f311f6..0544263761f05b 100644 --- a/pages/api/dialog.md +++ b/pages/api/dialog.md @@ -42,6 +42,8 @@ Dialogs are overlaid modal paper based components with a backdrop. | transitionDuration | union: number |
 { enter?: number, exit?: number }
 | { enter: duration.enteringScreen, exit: duration.leavingScreen } | The duration for the transition, in milliseconds. You may specify a single timeout for all transitions, or individually with an object. | | TransitionProps | object | | Properties applied to the `Transition` element. | +The `ref` is forwarded to the root element. + Any other properties supplied will be spread to the root element ([Modal](/api/modal/)). ## CSS diff --git a/pages/api/divider.md b/pages/api/divider.md index 10bbe766c7bcfb..1e4f5e538a214a 100644 --- a/pages/api/divider.md +++ b/pages/api/divider.md @@ -24,6 +24,8 @@ import Divider from '@material-ui/core/Divider'; | light | bool | false | If `true`, the divider will have a lighter color. | | variant | enum: 'fullWidth' |
 'inset' |
 'middle'
 | 'fullWidth' | The variant to use. | +The `ref` is forwarded to the root element. + Any other properties supplied will be spread to the root element (native element). ## CSS diff --git a/pages/api/drawer.md b/pages/api/drawer.md index 214bed6872e6cc..af04cb6e314f08 100644 --- a/pages/api/drawer.md +++ b/pages/api/drawer.md @@ -31,6 +31,8 @@ when `variant="temporary"` is set. | transitionDuration | union: number |
 { enter?: number, exit?: number }
 | { enter: duration.enteringScreen, exit: duration.leavingScreen } | The duration for the transition, in milliseconds. You may specify a single timeout for all transitions, or individually with an object. | | variant | enum: 'permanent' |
 'persistent' |
 'temporary'
 | 'temporary' | The variant to use. | +The `ref` is forwarded to the root element. + Any other properties supplied will be spread to the root element (native element). ## CSS diff --git a/pages/api/expansion-panel-actions.md b/pages/api/expansion-panel-actions.md index 9ffd4482ffd666..36c5cb25c9212a 100644 --- a/pages/api/expansion-panel-actions.md +++ b/pages/api/expansion-panel-actions.md @@ -21,6 +21,8 @@ import ExpansionPanelActions from '@material-ui/core/ExpansionPanelActions'; | children * | node | | The content of the component. | | classes | object | | Override or extend the styles applied to the component. See [CSS API](#css) below for more details. | +The `ref` is forwarded to the root element. + Any other properties supplied will be spread to the root element (native element). ## CSS diff --git a/pages/api/expansion-panel-details.md b/pages/api/expansion-panel-details.md index 411412bdd65aeb..a7fc314d5f600f 100644 --- a/pages/api/expansion-panel-details.md +++ b/pages/api/expansion-panel-details.md @@ -21,6 +21,8 @@ import ExpansionPanelDetails from '@material-ui/core/ExpansionPanelDetails'; | children * | node | | The content of the expansion panel details. | | classes | object | | Override or extend the styles applied to the component. See [CSS API](#css) below for more details. | +The `ref` is forwarded to the root element. + Any other properties supplied will be spread to the root element (native element). ## CSS diff --git a/pages/api/expansion-panel-summary.md b/pages/api/expansion-panel-summary.md index 8decd8e9ed828c..90bb8c6f2545b3 100644 --- a/pages/api/expansion-panel-summary.md +++ b/pages/api/expansion-panel-summary.md @@ -23,6 +23,8 @@ import ExpansionPanelSummary from '@material-ui/core/ExpansionPanelSummary'; | expandIcon | node | | The icon to display as the expand indicator. | | IconButtonProps | object | | Properties applied to the `IconButton` element wrapping the expand icon. | +The `ref` is forwarded to the root element. + Any other properties supplied will be spread to the root element ([ButtonBase](/api/button-base/)). ## CSS diff --git a/pages/api/expansion-panel.md b/pages/api/expansion-panel.md index 3a76cc739aa16c..8ce55f9f8781a7 100644 --- a/pages/api/expansion-panel.md +++ b/pages/api/expansion-panel.md @@ -27,6 +27,8 @@ import ExpansionPanel from '@material-ui/core/ExpansionPanel'; | TransitionComponent | elementType | Collapse | The component used for the collapse effect. | | TransitionProps | object | | Properties applied to the `Transition` element. | +The `ref` is forwarded to the root element. + Any other properties supplied will be spread to the root element ([Paper](/api/paper/)). ## CSS diff --git a/pages/api/fab.md b/pages/api/fab.md index a925aecc11767a..7538a9807bfbb3 100644 --- a/pages/api/fab.md +++ b/pages/api/fab.md @@ -29,6 +29,8 @@ import Fab from '@material-ui/core/Fab'; | size | enum: 'small' |
 'medium' |
 'large'
 | 'large' | The size of the button. `small` is equivalent to the dense button styling. | | variant | enum: 'round' |
 'extended'
 | 'round' | The variant to use. | +The `ref` is forwarded to the root element. + Any other properties supplied will be spread to the root element ([ButtonBase](/api/button-base/)). ## CSS diff --git a/pages/api/fade.md b/pages/api/fade.md index edbb2d6267f3a0..61089edaa1c43a 100644 --- a/pages/api/fade.md +++ b/pages/api/fade.md @@ -23,6 +23,8 @@ It uses [react-transition-group](https://github.com/reactjs/react-transition-gro | in | bool | | If `true`, the component will transition in. | | timeout | union: number |
 { enter?: number, exit?: number }
 | { enter: duration.enteringScreen, exit: duration.leavingScreen,} | The duration for the transition, in milliseconds. You may specify a single timeout for all transitions, or individually with an object. | +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)). ## Inheritance diff --git a/pages/api/filled-input.md b/pages/api/filled-input.md index f7f447a7086b1c..f29208273d320d 100644 --- a/pages/api/filled-input.md +++ b/pages/api/filled-input.md @@ -45,6 +45,8 @@ import FilledInput from '@material-ui/core/FilledInput'; | type | string | | Type of the `input` element. It should be [a valid HTML5 input type](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#Form_%3Cinput%3E_types). | | value | union: string, number, bool, object, arrayOf
 | | The value of the `input` element, required for a controlled component. | +The `ref` is forwarded to the root element. + Any other properties supplied will be spread to the root element ([InputBase](/api/input-base/)). ## CSS diff --git a/pages/api/form-control-label.md b/pages/api/form-control-label.md index 67a090d26569ae..1152ad2daf8d3c 100644 --- a/pages/api/form-control-label.md +++ b/pages/api/form-control-label.md @@ -30,6 +30,8 @@ Use this component if you want to display an extra label. | onChange | func | | Callback fired when the state is changed.

**Signature:**
`function(event: object, checked: boolean) => void`
*event:* The event source of the callback. You can pull out the new value by accessing `event.target.checked`.
*checked:* The `checked` value of the switch | | value | string | | The value of the component. | +The `ref` is forwarded to the root element. + Any other properties supplied will be spread to the root element (native element). ## CSS diff --git a/pages/api/form-control.md b/pages/api/form-control.md index 8f00cd60697ed9..2e8c64e578a297 100644 --- a/pages/api/form-control.md +++ b/pages/api/form-control.md @@ -37,6 +37,8 @@ This context is used by the following components: | required | bool | false | If `true`, the label will indicate that the input is required. | | variant | enum: 'standard' |
 'outlined' |
 'filled'
 | 'standard' | The variant to use. | +The `ref` is forwarded to the root element. + Any other properties supplied will be spread to the root element (native element). ## CSS diff --git a/pages/api/form-group.md b/pages/api/form-group.md index 7a56f47a924743..445c77ca81c669 100644 --- a/pages/api/form-group.md +++ b/pages/api/form-group.md @@ -24,6 +24,8 @@ For the `Radio`, you should be using the `RadioGroup` component instead of this | classes | object | | Override or extend the styles applied to the component. See [CSS API](#css) below for more details. | | row | bool | false | Display group of elements in a compact row. | +The `ref` is forwarded to the root element. + Any other properties supplied will be spread to the root element (native element). ## CSS diff --git a/pages/api/form-helper-text.md b/pages/api/form-helper-text.md index 053dcac18ea5c3..7b7d3d64890f71 100644 --- a/pages/api/form-helper-text.md +++ b/pages/api/form-helper-text.md @@ -29,6 +29,8 @@ import FormHelperText from '@material-ui/core/FormHelperText'; | required | bool | | If `true`, the helper text should use required classes key. | | variant | enum: 'standard' |
 'outlined' |
 'filled'
 | | The variant to use. | +The `ref` is forwarded to the root element. + Any other properties supplied will be spread to the root element (native element). ## CSS diff --git a/pages/api/form-label.md b/pages/api/form-label.md index bfbeb891e4cb66..97e49476449a4b 100644 --- a/pages/api/form-label.md +++ b/pages/api/form-label.md @@ -27,6 +27,8 @@ import FormLabel from '@material-ui/core/FormLabel'; | focused | bool | | If `true`, the input of this label is focused (used by `FormGroup` components). | | required | bool | | If `true`, the label will indicate that the input is required. | +The `ref` is forwarded to the root element. + Any other properties supplied will be spread to the root element (native element). ## CSS diff --git a/pages/api/grid-list-tile-bar.md b/pages/api/grid-list-tile-bar.md index be13a086c82741..19cbc0918fab28 100644 --- a/pages/api/grid-list-tile-bar.md +++ b/pages/api/grid-list-tile-bar.md @@ -25,6 +25,8 @@ import GridListTileBar from '@material-ui/core/GridListTileBar'; | title | node | | Title to be displayed on tile. | | titlePosition | enum: 'top' |
 'bottom'
 | 'bottom' | Position of the title bar. | +The `ref` is forwarded to the root element. + Any other properties supplied will be spread to the root element (native element). ## CSS diff --git a/pages/api/grid-list-tile.md b/pages/api/grid-list-tile.md index 0fb0fcb21b97dd..5af2398952eb06 100644 --- a/pages/api/grid-list-tile.md +++ b/pages/api/grid-list-tile.md @@ -24,6 +24,8 @@ import GridListTile from '@material-ui/core/GridListTile'; | component | elementType | 'li' | The component used for the root node. Either a string to use a DOM element or a component. | | rows | number | 1 | Height of the tile in number of grid cells. | +The `ref` is forwarded to the root element. + Any other properties supplied will be spread to the root element (native element). ## CSS diff --git a/pages/api/grid-list.md b/pages/api/grid-list.md index 788a5c6a0cb599..9454043a5e60e2 100644 --- a/pages/api/grid-list.md +++ b/pages/api/grid-list.md @@ -25,6 +25,8 @@ import GridList from '@material-ui/core/GridList'; | component | elementType | 'ul' | The component used for the root node. Either a string to use a DOM element or a component. | | spacing | number | 4 | Number of px for the spacing between tiles. | +The `ref` is forwarded to the root element. + Any other properties supplied will be spread to the root element (native element). ## CSS diff --git a/pages/api/grid.md b/pages/api/grid.md index 1d230663d883f8..359557d775ca0a 100644 --- a/pages/api/grid.md +++ b/pages/api/grid.md @@ -36,6 +36,8 @@ import Grid from '@material-ui/core/Grid'; | xs | enum: false, 'auto', true, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12
 | false | Defines the number of grids the component is going to use. It's applied for all the screen sizes with the lowest priority. | | zeroMinWidth | bool | false | If `true`, it sets `min-width: 0` on the item. Refer to the limitations section of the documentation to better understand the use case. | +The `ref` is forwarded to the root element. + Any other properties supplied will be spread to the root element (native element). ## CSS diff --git a/pages/api/grow.md b/pages/api/grow.md index 62b3639669f8bc..26172b5b7233f4 100644 --- a/pages/api/grow.md +++ b/pages/api/grow.md @@ -24,6 +24,8 @@ It uses [react-transition-group](https://github.com/reactjs/react-transition-gro | in | bool | | If `true`, show the component; triggers the enter or exit animation. | | timeout | union: number |
 { enter?: number, exit?: number } |
 enum: 'auto'

 | 'auto' | The duration for the transition, in milliseconds. You may specify a single timeout for all transitions, or individually with an object.
Set to 'auto' to automatically calculate transition time based on height. | +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)). ## Inheritance diff --git a/pages/api/hidden.md b/pages/api/hidden.md index b86413756655b7..5f664f53f0c235 100644 --- a/pages/api/hidden.md +++ b/pages/api/hidden.md @@ -33,6 +33,8 @@ Responsively hides children based on the selected implementation. | xsDown | bool | false | If true, screens this size and down will be hidden. | | xsUp | bool | false | If true, screens this size and up will be hidden. | +The component cannot hold a ref. + Any other properties supplied will be spread to the root element (native element). ## Demos diff --git a/pages/api/icon-button.md b/pages/api/icon-button.md index f76d3e7478d748..337bc8ccd21401 100644 --- a/pages/api/icon-button.md +++ b/pages/api/icon-button.md @@ -26,6 +26,8 @@ regarding the available icon options. | edge | enum: 'start' |
 'end' |
 false
 | | If given, uses a negative margin to counteract the padding on one side (this is often helpful for aligning the left or right side of the icon with content above or below, without ruining the border size and shape). | | size | enum: 'small' |
 'medium'
 | 'medium' | The size of the button. `small` is equivalent to the dense button styling. | +The `ref` is forwarded to the root element. + Any other properties supplied will be spread to the root element ([ButtonBase](/api/button-base/)). ## CSS diff --git a/pages/api/icon.md b/pages/api/icon.md index eb76194aec93ac..eed510b22b56b2 100644 --- a/pages/api/icon.md +++ b/pages/api/icon.md @@ -24,6 +24,8 @@ import Icon from '@material-ui/core/Icon'; | component | elementType | 'span' | The component used for the root node. Either a string to use a DOM element or a component. | | fontSize | enum: 'inherit' |
 'default' |
 'small' |
 'large'
 | 'default' | The fontSize applied to the icon. Defaults to 24px, but can be configure to inherit font size. | +The `ref` is forwarded to the root element. + Any other properties supplied will be spread to the root element (native element). ## CSS diff --git a/pages/api/input-adornment.md b/pages/api/input-adornment.md index e22279650b81a7..5976b4f6aab83c 100644 --- a/pages/api/input-adornment.md +++ b/pages/api/input-adornment.md @@ -26,6 +26,8 @@ import InputAdornment from '@material-ui/core/InputAdornment'; | position | enum: 'start' |
 'end'
 | | The position this adornment should appear relative to the `Input`. | | variant | enum: 'standard' |
 'outlined' |
 'filled'
 | | The variant to use. Note: If you are using the `TextField` component or the `FormControl` component you do not have to set this manually. | +The `ref` is forwarded to the root element. + Any other properties supplied will be spread to the root element (native element). ## CSS diff --git a/pages/api/input-base.md b/pages/api/input-base.md index 2383aac6819138..22fff9f30222da 100644 --- a/pages/api/input-base.md +++ b/pages/api/input-base.md @@ -46,6 +46,8 @@ It contains a load of style reset and some state logic. | type | string | 'text' | Type of the `input` element. It should be [a valid HTML5 input type](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#Form_%3Cinput%3E_types). | | value | union: string, number, bool, object, arrayOf
 | | The value of the `input` element, required for a controlled component. | +The `ref` is forwarded to the root element. + Any other properties supplied will be spread to the root element (native element). ## CSS diff --git a/pages/api/input-label.md b/pages/api/input-label.md index e49aa1133440ec..f9603a691539cd 100644 --- a/pages/api/input-label.md +++ b/pages/api/input-label.md @@ -29,6 +29,8 @@ import InputLabel from '@material-ui/core/InputLabel'; | shrink | bool | | If `true`, the label is shrunk. | | variant | enum: 'standard' |
 'outlined' |
 'filled'
 | | The variant to use. | +The `ref` is forwarded to the root element. + Any other properties supplied will be spread to the root element ([FormLabel](/api/form-label/)). ## CSS diff --git a/pages/api/input.md b/pages/api/input.md index 4e241775541d7d..92bbb519f68be5 100644 --- a/pages/api/input.md +++ b/pages/api/input.md @@ -45,6 +45,8 @@ import Input from '@material-ui/core/Input'; | type | string | | Type of the `input` element. It should be [a valid HTML5 input type](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#Form_%3Cinput%3E_types). | | value | union: string, number, bool, object, arrayOf
 | | The value of the `input` element, required for a controlled component. | +The `ref` is forwarded to the root element. + Any other properties supplied will be spread to the root element ([InputBase](/api/input-base/)). ## CSS diff --git a/pages/api/linear-progress.md b/pages/api/linear-progress.md index d410e3116e3600..25be3b20bcb727 100644 --- a/pages/api/linear-progress.md +++ b/pages/api/linear-progress.md @@ -28,6 +28,8 @@ attribute to `true` on that region until it has finished loading. | valueBuffer | number | | The value for the buffer variant. Value between 0 and 100. | | variant | enum: 'determinate' |
 'indeterminate' |
 'buffer' |
 'query'
 | 'indeterminate' | The variant to use. Use indeterminate or query when there is no progress value. | +The `ref` is forwarded to the root element. + Any other properties supplied will be spread to the root element (native element). ## CSS diff --git a/pages/api/link.md b/pages/api/link.md index ba810fd0c9ac81..c5afd7c1a157c6 100644 --- a/pages/api/link.md +++ b/pages/api/link.md @@ -26,6 +26,8 @@ import Link from '@material-ui/core/Link'; | underline | enum: 'none' |
 'hover' |
 'always'
 | 'hover' | Controls when the link should have an underline. | | variant | string | 'inherit' | Applies the theme typography styles. | +The `ref` is forwarded to the root element. + Any other properties supplied will be spread to the root element ([Typography](/api/typography/)). ## CSS diff --git a/pages/api/list-item-avatar.md b/pages/api/list-item-avatar.md index c3e209df6fa908..3bfa0160c0b2e3 100644 --- a/pages/api/list-item-avatar.md +++ b/pages/api/list-item-avatar.md @@ -22,6 +22,8 @@ and `align-items="flex-start"` mode styles to `Avatar`. | children * | element | | The content of the component – normally `Avatar`. | | classes | object | | Override or extend the styles applied to the component. See [CSS API](#css) below for more details. | +The component cannot hold a ref. + Any other properties supplied will be spread to the root element (native element). ## CSS diff --git a/pages/api/list-item-icon.md b/pages/api/list-item-icon.md index f150463fd7dfb2..e5809debb4423f 100644 --- a/pages/api/list-item-icon.md +++ b/pages/api/list-item-icon.md @@ -21,6 +21,8 @@ A simple wrapper to apply `List` styles to an `Icon` or `SvgIcon`. | children * | element | | The content of the component, normally `Icon`, `SvgIcon`, or a `@material-ui/icons` SVG icon element. | | classes | object | | Override or extend the styles applied to the component. See [CSS API](#css) below for more details. | +The `ref` is forwarded to the root element. + Any other properties supplied will be spread to the root element (native element). ## CSS diff --git a/pages/api/list-item-secondary-action.md b/pages/api/list-item-secondary-action.md index c4c761148cdea6..877604224ecf58 100644 --- a/pages/api/list-item-secondary-action.md +++ b/pages/api/list-item-secondary-action.md @@ -21,6 +21,8 @@ Must be used as the last child of ListItem to function properly. | children | node | | The content of the component, normally an `IconButton` or selection control. | | classes | object | | Override or extend the styles applied to the component. See [CSS API](#css) below for more details. | +The `ref` is forwarded to the root element. + Any other properties supplied will be spread to the root element (native element). ## CSS diff --git a/pages/api/list-item-text.md b/pages/api/list-item-text.md index 7f4a35e09f8449..9caddfe933c431 100644 --- a/pages/api/list-item-text.md +++ b/pages/api/list-item-text.md @@ -27,6 +27,8 @@ import ListItemText from '@material-ui/core/ListItemText'; | secondary | node | | The secondary content element. | | secondaryTypographyProps | object | | These props will be forwarded to the secondary typography component (as long as disableTypography is not `true`). | +The `ref` is forwarded to the root element. + Any other properties supplied will be spread to the root element (native element). ## CSS diff --git a/pages/api/list-item.md b/pages/api/list-item.md index c2560522501966..a7aafbb5416c5c 100644 --- a/pages/api/list-item.md +++ b/pages/api/list-item.md @@ -31,6 +31,8 @@ Uses an additional container component if `ListItemSecondaryAction` is the last | divider | bool | false | If `true`, a 1px light border is added to the bottom of the list item. | | selected | bool | false | Use to apply selected styling. | +The `ref` is forwarded to the root element. + Any other properties supplied will be spread to the root element (native element). ## CSS diff --git a/pages/api/list-subheader.md b/pages/api/list-subheader.md index b6836014429776..1f5e101f84fcbe 100644 --- a/pages/api/list-subheader.md +++ b/pages/api/list-subheader.md @@ -26,6 +26,8 @@ import ListSubheader from '@material-ui/core/ListSubheader'; | disableSticky | bool | false | If `true`, the List Subheader will not stick to the top during scroll. | | inset | bool | false | If `true`, the List Subheader will be indented. | +The `ref` is forwarded to the root element. + Any other properties supplied will be spread to the root element (native element). ## CSS diff --git a/pages/api/list.md b/pages/api/list.md index ec188ffdde7087..53f2f1ff521745 100644 --- a/pages/api/list.md +++ b/pages/api/list.md @@ -25,6 +25,8 @@ import List from '@material-ui/core/List'; | disablePadding | bool | false | If `true`, vertical padding will be removed from the list. | | subheader | node | | The content of the subheader, normally `ListSubheader`. | +The `ref` is forwarded to the root element. + Any other properties supplied will be spread to the root element (native element). ## CSS diff --git a/pages/api/menu-item.md b/pages/api/menu-item.md index ea830b6600a248..f7b4b18dc52258 100644 --- a/pages/api/menu-item.md +++ b/pages/api/menu-item.md @@ -23,6 +23,8 @@ import MenuItem from '@material-ui/core/MenuItem'; | component | elementType | 'li' | The component used for the root node. Either a string to use a DOM element or a component. | | disableGutters | bool | false | If `true`, the left and right padding is removed. | +The `ref` is forwarded to the root element. + Any other properties supplied will be spread to the root element ([ListItem](/api/list-item/)). ## CSS diff --git a/pages/api/menu-list.md b/pages/api/menu-list.md index f7d887207583e0..35008f12922e74 100644 --- a/pages/api/menu-list.md +++ b/pages/api/menu-list.md @@ -21,6 +21,8 @@ import MenuList from '@material-ui/core/MenuList'; | children | node | | MenuList contents, normally `MenuItem`s. | | disableListWrap | bool | false | If `true`, the menu items will not wrap focus. | +The `ref` is forwarded to the root element. + Any other properties supplied will be spread to the root element ([List](/api/list/)). ## Inheritance diff --git a/pages/api/menu.md b/pages/api/menu.md index 459cc538916820..039c66e25d7112 100644 --- a/pages/api/menu.md +++ b/pages/api/menu.md @@ -34,6 +34,8 @@ import Menu from '@material-ui/core/Menu'; | PopoverClasses | object | | `classes` property applied to the [`Popover`](/api/popover/) element. | | transitionDuration | union: number |
 { enter?: number, exit?: number } |
 enum: 'auto'

 | 'auto' | The length of the transition in `ms`, or 'auto' | +The `ref` is forwarded to the root element. + Any other properties supplied will be spread to the root element ([Popover](/api/popover/)). ## CSS diff --git a/pages/api/mobile-stepper.md b/pages/api/mobile-stepper.md index 87f227aff131e1..1b2ea3584d77aa 100644 --- a/pages/api/mobile-stepper.md +++ b/pages/api/mobile-stepper.md @@ -27,6 +27,8 @@ import MobileStepper from '@material-ui/core/MobileStepper'; | steps * | number | | The total steps. | | variant | enum: 'text' |
 'dots' |
 'progress'
 | 'dots' | The variant to use. | +The `ref` is forwarded to the root element. + Any other properties supplied will be spread to the root element ([Paper](/api/paper/)). ## CSS diff --git a/pages/api/modal.md b/pages/api/modal.md index 89add7c536bc51..e0670ffb396172 100644 --- a/pages/api/modal.md +++ b/pages/api/modal.md @@ -48,6 +48,8 @@ This component shares many concepts with [react-overlays](https://react-bootstra | onRendered | func | | Callback fired once the children has been mounted into the `container`. It signals that the `open={true}` property took effect. | | open * | bool | | If `true`, the modal is open. | +The `ref` is forwarded to the root element. + Any other properties supplied will be spread to the root element (native element). ## CSS diff --git a/pages/api/native-select.md b/pages/api/native-select.md index 6a7e8ece891dbe..89d0051cdf88e6 100644 --- a/pages/api/native-select.md +++ b/pages/api/native-select.md @@ -27,6 +27,8 @@ An alternative to `