diff --git a/docs/scripts/buildApi.js b/docs/scripts/buildApi.js index 2e48be5c2e7362..03dc6b04fc198e 100644 --- a/docs/scripts/buildApi.js +++ b/docs/scripts/buildApi.js @@ -136,7 +136,7 @@ async function annotateComponentDefinition(component, api) { ); const jsdoc = `/** - * ${api.description} + * ${api.description.replace(/\n/g, '\n * ')} * * Demos: * - ${demos diff --git a/packages/material-ui/src/ButtonBase/ButtonBase.d.ts b/packages/material-ui/src/ButtonBase/ButtonBase.d.ts index bf904acea489a1..af59c26e18c1c9 100644 --- a/packages/material-ui/src/ButtonBase/ButtonBase.d.ts +++ b/packages/material-ui/src/ButtonBase/ButtonBase.d.ts @@ -40,15 +40,15 @@ export type ExtendButtonBase = (( /** * `ButtonBase` contains as few styles as possible. -It aims to be a simple building block for creating a button. -It contains a load of style reset and some focus/ripple logic. + * It aims to be a simple building block for creating a button. + * It contains a load of style reset and some focus/ripple logic. * * Demos: * - {@link https://material-ui.com/components/buttons Buttons} * * API: * - {@link https://material-ui.com/api/ButtonBase ButtonBase API} - * + * */ declare const ButtonBase: ExtendButtonBase; diff --git a/packages/material-ui/src/CircularProgress/CircularProgress.d.ts b/packages/material-ui/src/CircularProgress/CircularProgress.d.ts index 49c49677836d77..16569344a1d680 100644 --- a/packages/material-ui/src/CircularProgress/CircularProgress.d.ts +++ b/packages/material-ui/src/CircularProgress/CircularProgress.d.ts @@ -25,17 +25,17 @@ export type CircularProgressClassKey = /** * ## ARIA - -If the progress bar is describing the loading progress of a particular region of a page, -you should use `aria-describedby` to point to the progress bar, and set the `aria-busy` -attribute to `true` on that region until it has finished loading. + * + * If the progress bar is describing the loading progress of a particular region of a page, + * you should use `aria-describedby` to point to the progress bar, and set the `aria-busy` + * attribute to `true` on that region until it has finished loading. * * Demos: * - {@link https://material-ui.com/components/progress Progress} * * API: * - {@link https://material-ui.com/api/CircularProgress CircularProgress API} - * + * */ declare const CircularProgress: React.ComponentType; diff --git a/packages/material-ui/src/ClickAwayListener/ClickAwayListener.d.ts b/packages/material-ui/src/ClickAwayListener/ClickAwayListener.d.ts index 7111965a9edd94..f37d43c95b8a3f 100644 --- a/packages/material-ui/src/ClickAwayListener/ClickAwayListener.d.ts +++ b/packages/material-ui/src/ClickAwayListener/ClickAwayListener.d.ts @@ -9,7 +9,7 @@ export interface ClickAwayListenerProps { /** * Listen for click events that occur somewhere in the document, outside of the element itself. -For instance, if you need to hide a menu when people click anywhere else on your page. + * For instance, if you need to hide a menu when people click anywhere else on your page. * * Demos: * - {@link https://material-ui.com/components/click-away-listener Click Away Listener} @@ -17,7 +17,7 @@ For instance, if you need to hide a menu when people click anywhere else on your * * API: * - {@link https://material-ui.com/api/ClickAwayListener ClickAwayListener API} - * + * */ declare const ClickAwayListener: React.ComponentType; diff --git a/packages/material-ui/src/Collapse/Collapse.d.ts b/packages/material-ui/src/Collapse/Collapse.d.ts index ed86c509942bf8..779b1da212762b 100644 --- a/packages/material-ui/src/Collapse/Collapse.d.ts +++ b/packages/material-ui/src/Collapse/Collapse.d.ts @@ -15,8 +15,8 @@ export type CollapseClassKey = 'container' | 'entered' | 'hidden' | 'wrapper' | /** * The Collapse transition is used by the -[Vertical Stepper](/components/steppers/#vertical-stepper) StepContent component. -It uses [react-transition-group](https://github.com/reactjs/react-transition-group) internally. + * [Vertical Stepper](/components/steppers/#vertical-stepper) StepContent component. + * It uses [react-transition-group](https://github.com/reactjs/react-transition-group) internally. * * Demos: * - {@link https://material-ui.com/components/cards Cards} diff --git a/packages/material-ui/src/Drawer/Drawer.d.ts b/packages/material-ui/src/Drawer/Drawer.d.ts index c991547b564975..44de0009de12d0 100644 --- a/packages/material-ui/src/Drawer/Drawer.d.ts +++ b/packages/material-ui/src/Drawer/Drawer.d.ts @@ -40,14 +40,14 @@ export type DrawerClassKey = /** * The props of the [Modal](/api/modal/) component are available -when `variant="temporary"` is set. + * when `variant="temporary"` is set. * * Demos: * - {@link https://material-ui.com/components/drawers Drawers} * * API: * - {@link https://material-ui.com/api/Drawer Drawer API} - * + * */ declare const Drawer: React.ComponentType; diff --git a/packages/material-ui/src/Fade/Fade.d.ts b/packages/material-ui/src/Fade/Fade.d.ts index 3ef64142536e04..52582474881a3c 100644 --- a/packages/material-ui/src/Fade/Fade.d.ts +++ b/packages/material-ui/src/Fade/Fade.d.ts @@ -9,7 +9,7 @@ export interface FadeProps extends TransitionProps { /** * The Fade transition is used by the [Modal](/components/modal/) component. -It uses [react-transition-group](https://github.com/reactjs/react-transition-group) internally. + * It uses [react-transition-group](https://github.com/reactjs/react-transition-group) internally. * * Demos: * - {@link https://material-ui.com/components/transitions Transitions} diff --git a/packages/material-ui/src/FormControl/FormControl.d.ts b/packages/material-ui/src/FormControl/FormControl.d.ts index 053e2efefa8b4f..d00ed4fc47b32e 100644 --- a/packages/material-ui/src/FormControl/FormControl.d.ts +++ b/packages/material-ui/src/FormControl/FormControl.d.ts @@ -20,26 +20,26 @@ export interface FormControlTypeMap

/** * Provides context such as filled/focused/error/required for form inputs. -Relying on the context provides high flexibility and ensures that the state always stays -consistent across the children of the `FormControl`. -This context is used by the following components: - - - FormLabel - - FormHelperText - - Input - - InputLabel - -You can find one composition example below and more going to [the demos](/components/text-fields/#components). - -```jsx - - Email address - - We'll never share your email. - -``` - -⚠️Only one input can be used within a FormControl. + * Relying on the context provides high flexibility and ensures that the state always stays + * consistent across the children of the `FormControl`. + * This context is used by the following components: + * + * - FormLabel + * - FormHelperText + * - Input + * - InputLabel + * + * You can find one composition example below and more going to [the demos](/components/text-fields/#components). + * + * ```jsx + * + * Email address + * + * We'll never share your email. + * + * ``` + * + * ⚠️Only one input can be used within a FormControl. * * Demos: * - {@link https://material-ui.com/components/checkboxes Checkboxes} @@ -49,7 +49,7 @@ You can find one composition example below and more going to [the demos](/compon * * API: * - {@link https://material-ui.com/api/FormControl FormControl API} - * + * */ declare const FormControl: OverridableComponent; diff --git a/packages/material-ui/src/FormControlLabel/FormControlLabel.d.ts b/packages/material-ui/src/FormControlLabel/FormControlLabel.d.ts index 2a4a18acbaee46..05446607bb10d8 100644 --- a/packages/material-ui/src/FormControlLabel/FormControlLabel.d.ts +++ b/packages/material-ui/src/FormControlLabel/FormControlLabel.d.ts @@ -28,7 +28,7 @@ export type FormControlLabelClassKey = /** * Drop in replacement of the `Radio`, `Switch` and `Checkbox` component. -Use this component if you want to display an extra label. + * Use this component if you want to display an extra label. * * Demos: * - {@link https://material-ui.com/components/checkboxes Checkboxes} @@ -37,7 +37,7 @@ Use this component if you want to display an extra label. * * API: * - {@link https://material-ui.com/api/FormControlLabel FormControlLabel API} - * + * */ declare const FormControlLabel: React.ComponentType; diff --git a/packages/material-ui/src/FormGroup/FormGroup.d.ts b/packages/material-ui/src/FormGroup/FormGroup.d.ts index 3e17065c6f2b74..4d5a1866a59d9e 100644 --- a/packages/material-ui/src/FormGroup/FormGroup.d.ts +++ b/packages/material-ui/src/FormGroup/FormGroup.d.ts @@ -10,8 +10,8 @@ export type FormGroupClassKey = 'root' | 'row'; /** * `FormGroup` wraps controls such as `Checkbox` and `Switch`. -It provides compact row layout. -For the `Radio`, you should be using the `RadioGroup` component instead of this one. + * It provides compact row layout. + * For the `Radio`, you should be using the `RadioGroup` component instead of this one. * * Demos: * - {@link https://material-ui.com/components/checkboxes Checkboxes} @@ -19,7 +19,7 @@ For the `Radio`, you should be using the `RadioGroup` component instead of this * * API: * - {@link https://material-ui.com/api/FormGroup FormGroup API} - * + * */ declare const FormGroup: React.ComponentType; diff --git a/packages/material-ui/src/Grow/Grow.d.ts b/packages/material-ui/src/Grow/Grow.d.ts index 45d6cb6da0d0b3..d81e012af3fce0 100644 --- a/packages/material-ui/src/Grow/Grow.d.ts +++ b/packages/material-ui/src/Grow/Grow.d.ts @@ -11,8 +11,8 @@ export interface GrowProps extends Omit { /** * The Grow transition is used by the [Tooltip](/components/tooltips/) and -[Popover](/components/popover/) components. -It uses [react-transition-group](https://github.com/reactjs/react-transition-group) internally. + * [Popover](/components/popover/) components. + * It uses [react-transition-group](https://github.com/reactjs/react-transition-group) internally. * * Demos: * - {@link https://material-ui.com/components/popover Popover} diff --git a/packages/material-ui/src/IconButton/IconButton.d.ts b/packages/material-ui/src/IconButton/IconButton.d.ts index 39dc763be221e5..96a6c93439bfac 100644 --- a/packages/material-ui/src/IconButton/IconButton.d.ts +++ b/packages/material-ui/src/IconButton/IconButton.d.ts @@ -18,7 +18,7 @@ export type IconButtonTypeMap< /** * Refer to the [Icons](/components/icons/) section of the documentation -regarding the available icon options. + * regarding the available icon options. * * Demos: * - {@link https://material-ui.com/components/buttons Buttons} diff --git a/packages/material-ui/src/InputBase/InputBase.d.ts b/packages/material-ui/src/InputBase/InputBase.d.ts index 49aaaabade405c..b698c5d4b559f2 100644 --- a/packages/material-ui/src/InputBase/InputBase.d.ts +++ b/packages/material-ui/src/InputBase/InputBase.d.ts @@ -80,15 +80,15 @@ export type InputBaseClassKey = /** * `InputBase` contains as few styles as possible. -It aims to be a simple building block for creating an input. -It contains a load of style reset and some state logic. + * It aims to be a simple building block for creating an input. + * It contains a load of style reset and some state logic. * * Demos: * - {@link https://material-ui.com/components/text-fields Text Fields} * * API: * - {@link https://material-ui.com/api/InputBase InputBase API} - * + * */ declare const InputBase: React.ComponentType; diff --git a/packages/material-ui/src/LinearProgress/LinearProgress.d.ts b/packages/material-ui/src/LinearProgress/LinearProgress.d.ts index f022446292537a..b2440dfdb7aa72 100644 --- a/packages/material-ui/src/LinearProgress/LinearProgress.d.ts +++ b/packages/material-ui/src/LinearProgress/LinearProgress.d.ts @@ -31,17 +31,17 @@ export type LinearProgressClassKey = /** * ## ARIA - -If the progress bar is describing the loading progress of a particular region of a page, -you should use `aria-describedby` to point to the progress bar, and set the `aria-busy` -attribute to `true` on that region until it has finished loading. + * + * If the progress bar is describing the loading progress of a particular region of a page, + * you should use `aria-describedby` to point to the progress bar, and set the `aria-busy` + * attribute to `true` on that region until it has finished loading. * * Demos: * - {@link https://material-ui.com/components/progress Progress} * * API: * - {@link https://material-ui.com/api/LinearProgress LinearProgress API} - * + * */ declare const LinearProgress: React.ComponentType; diff --git a/packages/material-ui/src/MenuList/MenuList.d.ts b/packages/material-ui/src/MenuList/MenuList.d.ts index ef834bec77d5ca..624b028caf1ccd 100644 --- a/packages/material-ui/src/MenuList/MenuList.d.ts +++ b/packages/material-ui/src/MenuList/MenuList.d.ts @@ -13,9 +13,9 @@ export type MenuListClassKey = ListClassKey; /** * A permanently displayed menu following https://www.w3.org/TR/wai-aria-practices/#menubutton. -It's exposed to help customization of the [`Menu`](/api/menu/) component. If you -use it separately you need to move focus into the component manually. Once -the focus is placed inside the component it is fully keyboard accessible. + * It's exposed to help customization of the [`Menu`](/api/menu/) component. If you + * use it separately you need to move focus into the component manually. Once + * the focus is placed inside the component it is fully keyboard accessible. * * Demos: * - {@link https://material-ui.com/components/menus Menus} diff --git a/packages/material-ui/src/Modal/Modal.d.ts b/packages/material-ui/src/Modal/Modal.d.ts index 238653d3298700..1ed280e033c5ce 100644 --- a/packages/material-ui/src/Modal/Modal.d.ts +++ b/packages/material-ui/src/Modal/Modal.d.ts @@ -31,23 +31,23 @@ export interface ModalProps /** * Modal is a lower-level construct that is leveraged by the following components: - -- [Dialog](/api/dialog/) -- [Drawer](/api/drawer/) -- [Menu](/api/menu/) -- [Popover](/api/popover/) - -If you are creating a modal dialog, you probably want to use the [Dialog](/api/dialog/) component -rather than directly using Modal. - -This component shares many concepts with [react-overlays](https://react-bootstrap.github.io/react-overlays/#modals). + * + * - [Dialog](/api/dialog/) + * - [Drawer](/api/drawer/) + * - [Menu](/api/menu/) + * - [Popover](/api/popover/) + * + * If you are creating a modal dialog, you probably want to use the [Dialog](/api/dialog/) component + * rather than directly using Modal. + * + * This component shares many concepts with [react-overlays](https://react-bootstrap.github.io/react-overlays/#modals). * * Demos: * - {@link https://material-ui.com/components/modal Modal} * * API: * - {@link https://material-ui.com/api/Modal Modal API} - * + * */ declare const Modal: React.ComponentType; diff --git a/packages/material-ui/src/NoSsr/NoSsr.d.ts b/packages/material-ui/src/NoSsr/NoSsr.d.ts index 408d8450551792..b32da0539c4c94 100644 --- a/packages/material-ui/src/NoSsr/NoSsr.d.ts +++ b/packages/material-ui/src/NoSsr/NoSsr.d.ts @@ -8,19 +8,19 @@ export interface NoSsrProps { /** * NoSsr purposely removes components from the subject of Server Side Rendering (SSR). - -This component can be useful in a variety of situations: -- Escape hatch for broken dependencies not supporting SSR. -- Improve the time-to-first paint on the client by only rendering above the fold. -- Reduce the rendering time on the server. -- Under too heavy server load, you can turn on service degradation. + * + * This component can be useful in a variety of situations: + * - Escape hatch for broken dependencies not supporting SSR. + * - Improve the time-to-first paint on the client by only rendering above the fold. + * - Reduce the rendering time on the server. + * - Under too heavy server load, you can turn on service degradation. * * Demos: * - {@link https://material-ui.com/components/no-ssr No Ssr} * * API: * - {@link https://material-ui.com/api/NoSsr NoSsr API} - * + * */ declare const NoSsr: React.ComponentType; diff --git a/packages/material-ui/src/Portal/Portal.d.ts b/packages/material-ui/src/Portal/Portal.d.ts index 9d2ccabd23bd16..4bcf598e75f823 100644 --- a/packages/material-ui/src/Portal/Portal.d.ts +++ b/packages/material-ui/src/Portal/Portal.d.ts @@ -27,13 +27,13 @@ export interface PortalProps { /** * Portals provide a first-class way to render children into a DOM node -that exists outside the DOM hierarchy of the parent component. + * that exists outside the DOM hierarchy of the parent component. * * Demos: * - {@link https://material-ui.com/components/portal Portal} * * API: * - {@link https://material-ui.com/api/Portal Portal API} - * + * */ export default function Portal(props: PortalProps): JSX.Element; diff --git a/packages/material-ui/src/RootRef/RootRef.d.ts b/packages/material-ui/src/RootRef/RootRef.d.ts index 41876374bc7257..36459ad04d563b 100644 --- a/packages/material-ui/src/RootRef/RootRef.d.ts +++ b/packages/material-ui/src/RootRef/RootRef.d.ts @@ -6,42 +6,42 @@ export interface RootRefProps { /** * ⚠️⚠️⚠️ -If you want the DOM element of a Material-UI component check out -[FAQ: How can I access the DOM element?](/getting-started/faq/#how-can-i-access-the-dom-element) -first. - -This component uses `findDOMNode` which is deprecated in React.StrictMode. - -Helper component to allow attaching a ref to a -wrapped element to access the underlying DOM element. - -It's highly inspired by https://github.com/facebook/react/issues/11401#issuecomment-340543801. -For example: -```jsx -import React from 'react'; -import RootRef from '@material-ui/core/RootRef'; - -function MyComponent() { - const domRef = React.useRef(); - - React.useEffect(() => { - console.log(domRef.current); // DOM node - }, []); - - return ( - - - - ); -} -``` + * If you want the DOM element of a Material-UI component check out + * [FAQ: How can I access the DOM element?](/getting-started/faq/#how-can-i-access-the-dom-element) + * first. + * + * This component uses `findDOMNode` which is deprecated in React.StrictMode. + * + * Helper component to allow attaching a ref to a + * wrapped element to access the underlying DOM element. + * + * It's highly inspired by https://github.com/facebook/react/issues/11401#issuecomment-340543801. + * For example: + * ```jsx + * import React from 'react'; + * import RootRef from '@material-ui/core/RootRef'; + * + * function MyComponent() { + * const domRef = React.useRef(); + * + * React.useEffect(() => { + * console.log(domRef.current); // DOM node + * }, []); + * + * return ( + * + * + * + * ); + * } + * ``` * * Demos: - * - + * - * * API: * - {@link https://material-ui.com/api/RootRef RootRef API} - * + * */ declare const RootRef: React.ComponentType; diff --git a/packages/material-ui/src/Slide/Slide.d.ts b/packages/material-ui/src/Slide/Slide.d.ts index 99802002290858..aec04dc3c3f9d2 100644 --- a/packages/material-ui/src/Slide/Slide.d.ts +++ b/packages/material-ui/src/Slide/Slide.d.ts @@ -10,7 +10,7 @@ export interface SlideProps extends TransitionProps { /** * The Slide transition is used by the [Drawer](/components/drawers/) component. -It uses [react-transition-group](https://github.com/reactjs/react-transition-group) internally. + * It uses [react-transition-group](https://github.com/reactjs/react-transition-group) internally. * * Demos: * - {@link https://material-ui.com/components/dialogs Dialogs} diff --git a/packages/material-ui/src/TableCell/TableCell.d.ts b/packages/material-ui/src/TableCell/TableCell.d.ts index 2b20b3607e8d41..16528e3907b26c 100644 --- a/packages/material-ui/src/TableCell/TableCell.d.ts +++ b/packages/material-ui/src/TableCell/TableCell.d.ts @@ -43,14 +43,14 @@ export type TableCellClassKey = /** * The component renders a `` element when the parent context is a header -or otherwise a `` element. + * or otherwise a `` element. * * Demos: * - {@link https://material-ui.com/components/tables Tables} * * API: * - {@link https://material-ui.com/api/TableCell TableCell API} - * + * */ declare const TableCell: React.ComponentType; diff --git a/packages/material-ui/src/TableRow/TableRow.d.ts b/packages/material-ui/src/TableRow/TableRow.d.ts index 8bf5cea2713933..7c05b27547c6da 100644 --- a/packages/material-ui/src/TableRow/TableRow.d.ts +++ b/packages/material-ui/src/TableRow/TableRow.d.ts @@ -13,14 +13,14 @@ export type TableRowClassKey = 'root' | 'selected' | 'hover' | 'head' | 'footer' /** * Will automatically set dynamic row height -based on the material table element parent (head, body, etc). + * based on the material table element parent (head, body, etc). * * Demos: * - {@link https://material-ui.com/components/tables Tables} * * API: * - {@link https://material-ui.com/api/TableRow TableRow API} - * + * */ declare const TableRow: React.ComponentType; diff --git a/packages/material-ui/src/TextField/TextField.d.ts b/packages/material-ui/src/TextField/TextField.d.ts index 3e8a7183bf6f43..753c7f28d23b44 100644 --- a/packages/material-ui/src/TextField/TextField.d.ts +++ b/packages/material-ui/src/TextField/TextField.d.ts @@ -76,35 +76,35 @@ export type TextFieldClassKey = 'root'; /** * The `TextField` is a convenience wrapper for the most common cases (80%). -It cannot be all things to all people, otherwise the API would grow out of control. - -## Advanced Configuration - -It's important to understand that the text field is a simple abstraction -on top of the following components: - -- [FormControl](/api/form-control/) -- [InputLabel](/api/input-label/) -- [FilledInput](/api/filled-input/) -- [OutlinedInput](/api/outlined-input/) -- [Input](/api/input/) -- [FormHelperText](/api/form-helper-text/) - -If you wish to alter the props applied to the `input` element, you can do so as follows: - -```jsx -const inputProps = { - step: 300, -}; - -return ; -``` - -For advanced cases, please look at the source of TextField by clicking on the -"Edit this page" button above. Consider either: - -- using the upper case props for passing values directly to the components -- using the underlying components directly as shown in the demos + * It cannot be all things to all people, otherwise the API would grow out of control. + * + * ## Advanced Configuration + * + * It's important to understand that the text field is a simple abstraction + * on top of the following components: + * + * - [FormControl](/api/form-control/) + * - [InputLabel](/api/input-label/) + * - [FilledInput](/api/filled-input/) + * - [OutlinedInput](/api/outlined-input/) + * - [Input](/api/input/) + * - [FormHelperText](/api/form-helper-text/) + * + * If you wish to alter the props applied to the `input` element, you can do so as follows: + * + * ```jsx + * const inputProps = { + * step: 300, + * }; + * + * return ; + * ``` + * + * For advanced cases, please look at the source of TextField by clicking on the + * "Edit this page" button above. Consider either: + * + * - using the upper case props for passing values directly to the components + * - using the underlying components directly as shown in the demos * * Demos: * - {@link https://material-ui.com/components/autocomplete Autocomplete} diff --git a/packages/material-ui/src/Zoom/Zoom.d.ts b/packages/material-ui/src/Zoom/Zoom.d.ts index 7ed0f6928274ba..8bbb87562595f5 100644 --- a/packages/material-ui/src/Zoom/Zoom.d.ts +++ b/packages/material-ui/src/Zoom/Zoom.d.ts @@ -9,8 +9,8 @@ export interface ZoomProps extends TransitionProps { /** * The Zoom transition can be used for the floating variant of the -[Button](/components/buttons/#floating-action-buttons) component. -It uses [react-transition-group](https://github.com/reactjs/react-transition-group) internally. + * [Button](/components/buttons/#floating-action-buttons) component. + * It uses [react-transition-group](https://github.com/reactjs/react-transition-group) internally. * * Demos: * - {@link https://material-ui.com/components/transitions Transitions}