Skip to content

Commit 026998f

Browse files
improve props's description
1 parent 6577ea5 commit 026998f

File tree

14 files changed

+75
-63
lines changed

14 files changed

+75
-63
lines changed

docs/pages/api-docs/menu.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ The `MuiMenu` name can be used for providing [default props](/customization/glob
2828

2929
| Name | Type | Default | Description |
3030
|:-----|:-----|:--------|:------------|
31-
| <span class="prop-name">anchorEl</span> | <span class="prop-type">HTML element<br>&#124;&nbsp;func</span> | | The DOM element used to set the position of the menu. |
31+
| <span class="prop-name">anchorEl</span> | <span class="prop-type">HTML element<br>&#124;&nbsp;func</span> | | This is a DOM element, or a function that returns it. It's used to set the position of the menu. |
3232
| <span class="prop-name">autoFocus</span> | <span class="prop-type">bool</span> | <span class="prop-default">true</span> | If `true` (Default) will focus the `[role="menu"]` if no focusable child is found. Disabled children are not focusable. If you set this prop to `false` focus will be placed on the parent modal container. This has severe accessibility implications and should only be considered if you manage focus otherwise. |
3333
| <span class="prop-name">children</span> | <span class="prop-type">node</span> | | Menu contents, normally `MenuItem`s. |
3434
| <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. |

docs/pages/api-docs/modal.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ This component shares many concepts with [react-overlays](https://react-bootstra
4040
| <span class="prop-name">BackdropProps</span> | <span class="prop-type">object</span> | | Props applied to the [`Backdrop`](/api/backdrop/) element. |
4141
| <span class="prop-name required">children&nbsp;*</span> | <span class="prop-type">element</span> | | A single child content element.<br>⚠️ [Needs to be able to hold a ref](/guides/composition/#caveat-with-refs). |
4242
| <span class="prop-name">closeAfterTransition</span> | <span class="prop-type">bool</span> | <span class="prop-default">false</span> | When set to true the Modal waits until a nested Transition is completed before closing. |
43-
| <span class="prop-name">container</span> | <span class="prop-type">object<br>&#124;&nbsp;func</span> | | A node, component instance, or function that returns either. The `container` will have the portal children appended to it. |
43+
| <span class="prop-name">container</span> | <span class="prop-type">HTML element<br>&#124;&nbsp;React.Component<br>&#124;&nbsp;func</span> | | A HTML element, component instance, or function that returns either. The `container` will have the portal children appended to it.<br>By default, it uses the body of the top-level document object, so it's simply `document.body` most of the time. |
4444
| <span class="prop-name">disableAutoFocus</span> | <span class="prop-type">bool</span> | <span class="prop-default">false</span> | If `true`, the modal will not automatically shift focus to itself when it opens, and replace it to the last focused element when it closes. This also works correctly with any modal children that have the `disableAutoFocus` prop.<br>Generally this should never be set to `true` as it makes the modal less accessible to assistive technologies, like screen readers. |
4545
| <span class="prop-name">disableBackdropClick</span> | <span class="prop-type">bool</span> | <span class="prop-default">false</span> | If `true`, clicking the backdrop will not fire any callback. |
4646
| <span class="prop-name">disableEnforceFocus</span> | <span class="prop-type">bool</span> | <span class="prop-default">false</span> | If `true`, the modal will not prevent focus from leaving the modal while open.<br>Generally this should never be set to `true` as it makes the modal less accessible to assistive technologies, like screen readers. |

docs/pages/api-docs/popover.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -29,13 +29,13 @@ The `MuiPopover` name can be used for providing [default props](/customization/g
2929
| Name | Type | Default | Description |
3030
|:-----|:-----|:--------|:------------|
3131
| <span class="prop-name">action</span> | <span class="prop-type">ref</span> | | A ref for imperative actions. It currently only supports updatePosition() action. |
32-
| <span class="prop-name">anchorEl</span> | <span class="prop-type">HTML element<br>&#124;&nbsp;func</span> | | This is the DOM element, or a function that returns it, that may be used to set the position of the popover. |
32+
| <span class="prop-name">anchorEl</span> | <span class="prop-type">HTML element<br>&#124;&nbsp;func</span> | | This is a DOM element, or a function that returns it. It's used to set the position of the popover. |
3333
| <span class="prop-name">anchorOrigin</span> | <span class="prop-type">{ horizontal: 'center'<br>&#124;&nbsp;'left'<br>&#124;&nbsp;'right'<br>&#124;&nbsp;number, vertical: 'bottom'<br>&#124;&nbsp;'center'<br>&#124;&nbsp;'top'<br>&#124;&nbsp;number }</span> | <span class="prop-default">{ vertical: 'top', horizontal: 'left',}</span> | This is the point on the anchor where the popover's `anchorEl` will attach to. This is not used when the anchorReference is 'anchorPosition'.<br>Options: vertical: [top, center, bottom]; horizontal: [left, center, right]. |
3434
| <span class="prop-name">anchorPosition</span> | <span class="prop-type">{ left: number, top: number }</span> | | This is the position that may be used to set the position of the popover. The coordinates are relative to the application's client area. |
3535
| <span class="prop-name">anchorReference</span> | <span class="prop-type">'anchorEl'<br>&#124;&nbsp;'anchorPosition'<br>&#124;&nbsp;'none'</span> | <span class="prop-default">'anchorEl'</span> | This determines which anchor prop to refer to to set the position of the popover. |
3636
| <span class="prop-name">children</span> | <span class="prop-type">node</span> | | The content of the component. |
3737
| <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. |
38-
| <span class="prop-name">container</span> | <span class="prop-type">func<br>&#124;&nbsp;React.Component<br>&#124;&nbsp;HTML element</span> | | A node, component instance, or function that returns either. The `container` will passed to the Modal component. By default, it uses the body of the anchorEl's top-level document object, so it's simply `document.body` most of the time. |
38+
| <span class="prop-name">container</span> | <span class="prop-type">HTML element<br>&#124;&nbsp;React.Component<br>&#124;&nbsp;func</span> | | A HTML element, component instance, or function that returns either. The `container` will passed to the Modal component.<br>By default, it uses the body of the anchorEl's top-level document object, so it's simply `document.body` most of the time. |
3939
| <span class="prop-name">elevation</span> | <span class="prop-type">number</span> | <span class="prop-default">8</span> | The elevation of the popover. |
4040
| <span class="prop-name">getContentAnchorEl</span> | <span class="prop-type">func</span> | | This function is called in order to retrieve the content anchor element. It's the opposite of the `anchorEl` prop. The content anchor element should be an element inside the popover. It's used to correctly scroll and set the position of the popover. The positioning strategy tries to make the content anchor element just above the anchor element. |
4141
| <span class="prop-name">marginThreshold</span> | <span class="prop-type">number</span> | <span class="prop-default">16</span> | Specifies how close to the edge of the window the popover can appear. |

docs/pages/api-docs/popper.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ Poppers rely on the 3rd party library [Popper.js](https://popper.js.org/docs/v1/
2626

2727
| Name | Type | Default | Description |
2828
|:-----|:-----|:--------|:------------|
29-
| <span class="prop-name">anchorEl</span> | <span class="prop-type">object<br>&#124;&nbsp;func</span> | | This is the reference element, or a function that returns it, that may be used to set the position of the popover. The return value will passed as the reference object of the Popper instance.<br>The reference element should be an HTML element instance or a [referenceObject](https://popper.js.org/docs/v1/#referenceObject). |
29+
| <span class="prop-name">anchorEl</span> | <span class="prop-type">HTML element<br>&#124;&nbsp;object<br>&#124;&nbsp;func</span> | | A HTML element, [referenceObject](https://popper.js.org/docs/v1/#referenceObject), or a function that returns either. It's used to set the position of the popper. The return value will passed as the reference object of the Popper instance. |
3030
| <span class="prop-name required">children&nbsp;*</span> | <span class="prop-type">node<br>&#124;&nbsp;func</span> | | Popper render function or node. |
3131
| <span class="prop-name">container</span> | <span class="prop-type">func<br>&#124;&nbsp;React.Component<br>&#124;&nbsp;HTML element</span> | | A node, component instance, or function that returns either. The `container` will passed to the Modal component. By default, it uses the body of the anchorEl's top-level document object, so it's simply `document.body` most of the time. |
3232
| <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. |

docs/pages/api-docs/portal.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ that exists outside the DOM hierarchy of the parent component.
2828
| Name | Type | Default | Description |
2929
|:-----|:-----|:--------|:------------|
3030
| <span class="prop-name">children</span> | <span class="prop-type">node</span> | | The children to render into the `container`. |
31-
| <span class="prop-name">container</span> | <span class="prop-type">HTML element<br>&#124;&nbsp;React.Component<br>&#124;&nbsp;func</span> | | A HTML element, component instance, or function that returns either. The `container` will have the portal children appended to it. By default, it uses the body of the top-level document object, so it's simply `document.body` most of the time. |
31+
| <span class="prop-name">container</span> | <span class="prop-type">HTML element<br>&#124;&nbsp;React.Component<br>&#124;&nbsp;func</span> | | A HTML element, component instance, or function that returns either. The `container` will have the portal children appended to it.<br>By default, it uses the body of the top-level document object, so it's simply `document.body` most of the time. |
3232
| <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. |
3333
| <span class="prop-name">onRendered</span> | <span class="prop-type">func</span> | | Callback fired once the children has been mounted into the `container`.<br>This prop will be deprecated and removed in v5, the ref can be used instead. |
3434

packages/material-ui/src/Menu/Menu.d.ts

+2-1
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,8 @@ import { TransitionHandlerProps, TransitionProps } from '../transitions/transiti
88
export interface MenuProps
99
extends StandardProps<PopoverProps & Partial<TransitionHandlerProps>, MenuClassKey> {
1010
/**
11-
* The DOM element used to set the position of the menu.
11+
* This is a DOM element, or a function that returns it.
12+
* It's used to set the position of the menu.
1213
* @document
1314
*/
1415
anchorEl?: PopoverProps['anchorEl'];

packages/material-ui/src/Menu/Menu.js

+2-1
Original file line numberDiff line numberDiff line change
@@ -172,7 +172,8 @@ Menu.propTypes = {
172172
// | To update them edit the d.ts file and run "yarn proptypes" |
173173
// ----------------------------------------------------------------------
174174
/**
175-
* The DOM element used to set the position of the menu.
175+
* This is a DOM element, or a function that returns it.
176+
* It's used to set the position of the menu.
176177
*/
177178
anchorEl: PropTypes /* @typescript-to-proptypes-ignore */.oneOfType([
178179
HTMLElementType,

packages/material-ui/src/Modal/Modal.js

+10-3
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@ import * as React from 'react';
22
import * as ReactDOM from 'react-dom';
33
import PropTypes from 'prop-types';
44
import { getThemeProps, useTheme } from '@material-ui/styles';
5-
import { elementAcceptingRef } from '@material-ui/utils';
5+
import { elementAcceptingRef, HTMLElementType } from '@material-ui/utils';
66
import ownerDocument from '../utils/ownerDocument';
77
import Portal from '../Portal';
88
import createChainedFunction from '../utils/createChainedFunction';
@@ -273,10 +273,17 @@ Modal.propTypes = {
273273
*/
274274
closeAfterTransition: PropTypes.bool,
275275
/**
276-
* A node, component instance, or function that returns either.
276+
* A HTML element, component instance, or function that returns either.
277277
* The `container` will have the portal children appended to it.
278+
*
279+
* By default, it uses the body of the top-level document object,
280+
* so it's simply `document.body` most of the time.
278281
*/
279-
container: PropTypes.oneOfType([PropTypes.object, PropTypes.func]),
282+
container: PropTypes /* @typescript-to-proptypes-ignore */.oneOfType([
283+
HTMLElementType,
284+
PropTypes.instanceOf(React.Component),
285+
PropTypes.func,
286+
]),
280287
/**
281288
* If `true`, the modal will not automatically shift focus to itself when it opens, and
282289
* replace it to the last focused element when it closes.

packages/material-ui/src/Popover/Popover.d.ts

+4-3
Original file line numberDiff line numberDiff line change
@@ -24,8 +24,8 @@ export interface PopoverProps
2424
*/
2525
action?: React.Ref<PopoverActions>;
2626
/**
27-
* This is the DOM element, or a function that returns the DOM element,
28-
* that may be used to set the position of the popover.
27+
* This is a DOM element, or a function that returns it.
28+
* It's used to set the position of the popover.
2929
*/
3030
anchorEl?: null | Element | ((element: Element) => Element);
3131
/**
@@ -55,8 +55,9 @@ export interface PopoverProps
5555
*/
5656
children?: React.ReactNode;
5757
/**
58-
* A node, component instance, or function that returns either.
58+
* A HTML element, component instance, or function that returns either.
5959
* The `container` will passed to the Modal component.
60+
*
6061
* By default, it uses the body of the anchorEl's top-level document object,
6162
* so it's simply `document.body` most of the time.
6263
*/

packages/material-ui/src/Popover/Popover.js

+6-5
Original file line numberDiff line numberDiff line change
@@ -436,8 +436,8 @@ Popover.propTypes = {
436436
*/
437437
action: refType,
438438
/**
439-
* This is the DOM element, or a function that returns it,
440-
* that may be used to set the position of the popover.
439+
* This is a DOM element, or a function that returns it.
440+
* It's used to set the position of the popover.
441441
*/
442442
anchorEl: chainPropTypes(PropTypes.oneOfType([HTMLElementType, PropTypes.func]), (props) => {
443443
if (props.open && (!props.anchorReference || props.anchorReference === 'anchorEl')) {
@@ -519,15 +519,16 @@ Popover.propTypes = {
519519
*/
520520
className: PropTypes.string,
521521
/**
522-
* A node, component instance, or function that returns either.
522+
* A HTML element, component instance, or function that returns either.
523523
* The `container` will passed to the Modal component.
524+
*
524525
* By default, it uses the body of the anchorEl's top-level document object,
525526
* so it's simply `document.body` most of the time.
526527
*/
527528
container: PropTypes /* @typescript-to-proptypes-ignore */.oneOfType([
528-
PropTypes.func,
529-
PropTypes.instanceOf(React.Component),
530529
HTMLElementType,
530+
PropTypes.instanceOf(React.Component),
531+
PropTypes.func,
531532
]),
532533
/**
533534
* The elevation of the popover.

packages/material-ui/src/Popper/Popper.d.ts

+4-6
Original file line numberDiff line numberDiff line change
@@ -19,12 +19,10 @@ export type PopperPlacementType =
1919

2020
export interface PopperProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'children'> {
2121
/**
22-
* This is the reference element, or a function that returns the reference element,
23-
* that may be used to set the position of the popover.
24-
* The return value will passed as the reference object of the Popper
25-
* instance.
26-
*
27-
* The reference element should be an HTML element instance or a [referenceObject](https://popper.js.org/docs/v1/#referenceObject).
22+
* A HTML element, [referenceObject](https://popper.js.org/docs/v1/#referenceObject),
23+
* or a function that returns either.
24+
* It's used to set the position of the popper.
25+
* The return value will passed as the reference object of the Popper instance.
2826
*/
2927
anchorEl?: null | ReferenceObject | (() => ReferenceObject);
3028
/**

packages/material-ui/src/Popper/Popper.js

+38-37
Original file line numberDiff line numberDiff line change
@@ -230,53 +230,54 @@ Popper.propTypes = {
230230
// | To update them edit the d.ts file and run "yarn proptypes" |
231231
// ----------------------------------------------------------------------
232232
/**
233-
* This is the reference element, or a function that returns it,
234-
* that may be used to set the position of the popover.
235-
* The return value will passed as the reference object of the Popper
236-
* instance.
237-
*
238-
* The reference element should be an HTML element instance or a [referenceObject](https://popper.js.org/docs/v1/#referenceObject).
233+
* A HTML element, [referenceObject](https://popper.js.org/docs/v1/#referenceObject),
234+
* or a function that returns either.
235+
* It's used to set the position of the popper.
236+
* The return value will passed as the reference object of the Popper instance.
239237
*/
240-
anchorEl: chainPropTypes(PropTypes.oneOfType([PropTypes.object, PropTypes.func]), (props) => {
241-
if (props.open) {
242-
const resolvedAnchorEl = getAnchorEl(props.anchorEl);
243-
244-
if (resolvedAnchorEl && resolvedAnchorEl.nodeType === 1) {
245-
const box = resolvedAnchorEl.getBoundingClientRect();
246-
247-
if (
248-
process.env.NODE_ENV !== 'test' &&
249-
box.top === 0 &&
250-
box.left === 0 &&
251-
box.right === 0 &&
252-
box.bottom === 0
238+
anchorEl: chainPropTypes(
239+
PropTypes.oneOfType([HTMLElementType, PropTypes.object, PropTypes.func]),
240+
(props) => {
241+
if (props.open) {
242+
const resolvedAnchorEl = getAnchorEl(props.anchorEl);
243+
244+
if (resolvedAnchorEl && resolvedAnchorEl.nodeType === 1) {
245+
const box = resolvedAnchorEl.getBoundingClientRect();
246+
247+
if (
248+
process.env.NODE_ENV !== 'test' &&
249+
box.top === 0 &&
250+
box.left === 0 &&
251+
box.right === 0 &&
252+
box.bottom === 0
253+
) {
254+
return new Error(
255+
[
256+
'Material-UI: the `anchorEl` prop provided to the component is invalid.',
257+
'The anchor element should be part of the document layout.',
258+
"Make sure the element is present in the document or that it's not display none.",
259+
].join('\n'),
260+
);
261+
}
262+
} else if (
263+
!resolvedAnchorEl ||
264+
typeof resolvedAnchorEl.clientWidth !== 'number' ||
265+
typeof resolvedAnchorEl.clientHeight !== 'number' ||
266+
typeof resolvedAnchorEl.getBoundingClientRect !== 'function'
253267
) {
254268
return new Error(
255269
[
256270
'Material-UI: the `anchorEl` prop provided to the component is invalid.',
257-
'The anchor element should be part of the document layout.',
258-
"Make sure the element is present in the document or that it's not display none.",
271+
'It should be an HTML element instance or a referenceObject ',
272+
'(https://popper.js.org/docs/v1/#referenceObject).',
259273
].join('\n'),
260274
);
261275
}
262-
} else if (
263-
!resolvedAnchorEl ||
264-
typeof resolvedAnchorEl.clientWidth !== 'number' ||
265-
typeof resolvedAnchorEl.clientHeight !== 'number' ||
266-
typeof resolvedAnchorEl.getBoundingClientRect !== 'function'
267-
) {
268-
return new Error(
269-
[
270-
'Material-UI: the `anchorEl` prop provided to the component is invalid.',
271-
'It should be an HTML element instance or a referenceObject ',
272-
'(https://popper.js.org/docs/v1/#referenceObject).',
273-
].join('\n'),
274-
);
275276
}
276-
}
277277

278-
return null;
279-
}),
278+
return null;
279+
},
280+
),
280281
/**
281282
* Popper render function or node.
282283
*/

packages/material-ui/src/Portal/Portal.d.ts

+2-1
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,9 @@ export interface PortalProps {
66
*/
77
children?: React.ReactNode;
88
/**
9-
* A node, component instance, or function that returns either.
9+
* A HTML element, component instance, or function that returns either.
1010
* The `container` will have the portal children appended to it.
11+
*
1112
* By default, it uses the body of the top-level document object,
1213
* so it's simply `document.body` most of the time.
1314
*/

packages/material-ui/src/Portal/Portal.js

+1
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,7 @@ Portal.propTypes = {
6969
/**
7070
* A HTML element, component instance, or function that returns either.
7171
* The `container` will have the portal children appended to it.
72+
*
7273
* By default, it uses the body of the top-level document object,
7374
* so it's simply `document.body` most of the time.
7475
*/

0 commit comments

Comments
 (0)