From 75d5de985d6668d92f239d2ba983022a8ab43e91 Mon Sep 17 00:00:00 2001 From: hitesh Date: Sun, 12 Jan 2020 22:33:08 +0530 Subject: [PATCH] docs: Improve transition documentation Resolves #17047 --- docs/pages/api/dialog.md | 4 ++-- docs/pages/api/expansion-panel.md | 4 ++-- docs/pages/api/popover.md | 4 ++-- docs/pages/api/snackbar.md | 4 ++-- docs/pages/api/speed-dial.md | 4 ++-- docs/pages/api/step-content.md | 4 ++-- docs/pages/api/tooltip.md | 4 ++-- docs/pages/api/tree-item.md | 2 +- docs/src/pages/components/transitions/transitions.md | 11 ++++++++++- packages/material-ui-lab/src/SpeedDial/SpeedDial.d.ts | 3 ++- packages/material-ui-lab/src/SpeedDial/SpeedDial.js | 3 ++- packages/material-ui-lab/src/TreeItem/TreeItem.d.ts | 1 + packages/material-ui-lab/src/TreeItem/TreeItem.js | 1 + packages/material-ui/src/Dialog/Dialog.js | 3 ++- .../material-ui/src/ExpansionPanel/ExpansionPanel.js | 3 ++- packages/material-ui/src/Popover/Popover.js | 3 ++- packages/material-ui/src/Snackbar/Snackbar.js | 3 ++- packages/material-ui/src/StepContent/StepContent.js | 3 ++- packages/material-ui/src/Tooltip/Tooltip.js | 3 ++- 19 files changed, 43 insertions(+), 24 deletions(-) diff --git a/docs/pages/api/dialog.md b/docs/pages/api/dialog.md index 9861764aa0e827..f9dd056316c006 100644 --- a/docs/pages/api/dialog.md +++ b/docs/pages/api/dialog.md @@ -46,9 +46,9 @@ Dialogs are overlaid modal paper based components with a backdrop. | PaperComponent | elementType | Paper | The component used to render the body of the dialog. | | PaperProps | object | {} | Props applied to the [`Paper`](/api/paper/) element. | | scroll | 'body'
| 'paper' | 'paper' | Determine the container for scrolling the dialog. | -| TransitionComponent | elementType | Fade | The component used for the transition. | +| TransitionComponent | elementType | Fade | The component used for the transition. [Follow our guide](/components/transitions/#transitioncomponent-prop) to learn more about the requirements for this component. | | transitionDuration | 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 | | Props applied to the `Transition` element. | +| TransitionProps | object | | Props applied to the [`Transition`](http://reactcommunity.org/react-transition-group/transition#Transition-props) element. | The `ref` is forwarded to the root element. diff --git a/docs/pages/api/expansion-panel.md b/docs/pages/api/expansion-panel.md index babde76e6d9ab8..af487f7e851c12 100644 --- a/docs/pages/api/expansion-panel.md +++ b/docs/pages/api/expansion-panel.md @@ -30,8 +30,8 @@ You can learn more about the difference by [reading this guide](/guides/minimizi | disabled | bool | false | If `true`, the panel will be displayed in a disabled state. | | expanded | bool | | If `true`, expands the panel, otherwise collapse it. Setting this prop enables control over the panel. | | onChange | func | | Callback fired when the expand/collapse state is changed.

**Signature:**
`function(event: object, expanded: boolean) => void`
*event:* The event source of the callback.
*expanded:* The `expanded` state of the panel. | -| TransitionComponent | elementType | Collapse | The component used for the collapse effect. | -| TransitionProps | object | | Props applied to the `Transition` element. | +| TransitionComponent | elementType | Collapse | The component used for the collapse effect. [Follow our guide](/components/transitions/#transitioncomponent-prop) to learn more about the requirements for this component. | +| TransitionProps | object | | Props applied to the [`Transition`](http://reactcommunity.org/react-transition-group/transition#Transition-props) element. | The `ref` is forwarded to the root element. diff --git a/docs/pages/api/popover.md b/docs/pages/api/popover.md index 49bd300d585df5..115d61da477f2a 100644 --- a/docs/pages/api/popover.md +++ b/docs/pages/api/popover.md @@ -45,9 +45,9 @@ You can learn more about the difference by [reading this guide](/guides/minimizi | open * | bool | | If `true`, the popover is visible. | | PaperProps | { component?: element type } | {} | Props applied to the [`Paper`](/api/paper/) element. | | transformOrigin | { horizontal: number
| 'left'
| 'center'
| 'right', vertical: number
| 'top'
| 'center'
| 'bottom' } | { vertical: 'top', horizontal: 'left',} | This is the point on the popover which will attach to the anchor's origin.
Options: vertical: [top, center, bottom, x(px)]; horizontal: [left, center, right, x(px)]. | -| TransitionComponent | elementType | Grow | The component used for the transition. | +| TransitionComponent | elementType | Grow | The component used for the transition. [Follow our guide](/components/transitions/#transitioncomponent-prop) to learn more about the requirements for this component. | | transitionDuration | number
| { enter?: number, exit?: number }
| 'auto' | 'auto' | Set to 'auto' to automatically calculate transition time based on height. | -| TransitionProps | object | {} | Props applied to the `Transition` element. | +| TransitionProps | object | {} | Props applied to the [`Transition`](http://reactcommunity.org/react-transition-group/transition#Transition-props) element. | The `ref` is forwarded to the root element. diff --git a/docs/pages/api/snackbar.md b/docs/pages/api/snackbar.md index 872413236b8062..d63e9874b12ea1 100644 --- a/docs/pages/api/snackbar.md +++ b/docs/pages/api/snackbar.md @@ -43,9 +43,9 @@ You can learn more about the difference by [reading this guide](/guides/minimizi | onExiting | func | | Callback fired when the transition is exiting. | | open | bool | | If `true`, `Snackbar` is open. | | resumeHideDuration | number | | The number of milliseconds to wait before dismissing after user interaction. If `autoHideDuration` prop isn't specified, it does nothing. If `autoHideDuration` prop is specified but `resumeHideDuration` isn't, we default to `autoHideDuration / 2` ms. | -| TransitionComponent | elementType | Grow | The component used for the transition. | +| TransitionComponent | elementType | Grow | The component used for the transition. [Follow our guide](/components/transitions/#transitioncomponent-prop) to learn more about the requirements for this component. | | transitionDuration | 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 | | Props applied to the `Transition` element. | +| TransitionProps | object | | Props applied to the [`Transition`](http://reactcommunity.org/react-transition-group/transition#Transition-props) element. | The `ref` is forwarded to the root element. diff --git a/docs/pages/api/speed-dial.md b/docs/pages/api/speed-dial.md index aa6096e6628eb3..54e423a1bb8321 100644 --- a/docs/pages/api/speed-dial.md +++ b/docs/pages/api/speed-dial.md @@ -35,9 +35,9 @@ You can learn more about the difference by [reading this guide](/guides/minimizi | onOpen | func | | Callback fired when the component requests to be open.

**Signature:**
`function(event: object, reason: string) => void`
*event:* The event source of the callback.
*reason:* Can be: `"toggle"`, `"focus"`, `"mouseEnter"`. | | open * | bool | | If `true`, the SpeedDial is open. | | openIcon | node | | The icon to display in the SpeedDial Fab when the SpeedDial is open. | -| TransitionComponent | elementType | Zoom | The component used for the transition. | +| TransitionComponent | elementType | Zoom | The component used for the transition. [Follow our guide](/components/transitions/#transitioncomponent-prop) to learn more about the requirements for this component. | | transitionDuration | number
| { appear?: 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 | | Props applied to the `Transition` element. | +| TransitionProps | object | | Props applied to the [`Transition`](http://reactcommunity.org/react-transition-group/transition#Transition-props) element. | The `ref` is forwarded to the root element. diff --git a/docs/pages/api/step-content.md b/docs/pages/api/step-content.md index 2a745071f30a60..c6fde6c1ff3a6d 100644 --- a/docs/pages/api/step-content.md +++ b/docs/pages/api/step-content.md @@ -26,9 +26,9 @@ You can learn more about the difference by [reading this guide](/guides/minimizi |:-----|:-----|:--------|:------------| | children | node | | Step content. | | classes | object | | Override or extend the styles applied to the component. See [CSS API](#css) below for more details. | -| TransitionComponent | elementType | Collapse | The component used for the transition. | +| TransitionComponent | elementType | Collapse | The component used for the transition. [Follow our guide](/components/transitions/#transitioncomponent-prop) to learn more about the requirements for this component. | | transitionDuration | number
| { enter?: number, exit?: number }
| 'auto' | 'auto' | Adjust the duration of the content expand transition. Passed as a prop to the transition component.
Set to 'auto' to automatically calculate transition time based on height. | -| TransitionProps | object | | Props applied to the `Transition` element. | +| TransitionProps | object | | Props applied to the [`Transition`](http://reactcommunity.org/react-transition-group/transition#Transition-props) element. | The `ref` is forwarded to the root element. diff --git a/docs/pages/api/tooltip.md b/docs/pages/api/tooltip.md index aeb35d6931008b..674a3f6ed381b2 100644 --- a/docs/pages/api/tooltip.md +++ b/docs/pages/api/tooltip.md @@ -42,8 +42,8 @@ You can learn more about the difference by [reading this guide](/guides/minimizi | placement | 'bottom-end'
| 'bottom-start'
| 'bottom'
| 'left-end'
| 'left-start'
| 'left'
| 'right-end'
| 'right-start'
| 'right'
| 'top-end'
| 'top-start'
| 'top' | 'bottom' | Tooltip placement. | | PopperProps | object | | Props applied to the [`Popper`](/api/popper/) element. | | title * | node | | Tooltip title. Zero-length titles string are never displayed. | -| TransitionComponent | elementType | Grow | The component used for the transition. | -| TransitionProps | object | | Props applied to the `Transition` element. | +| TransitionComponent | elementType | Grow | The component used for the transition. [Follow our guide](/components/transitions/#transitioncomponent-prop) to learn more about the requirements for this component. | +| TransitionProps | object | | Props applied to the [`Transition`](http://reactcommunity.org/react-transition-group/transition#Transition-props) element. | The `ref` is forwarded to the root element. diff --git a/docs/pages/api/tree-item.md b/docs/pages/api/tree-item.md index 55d17b667ad763..466d18d2d97f9c 100644 --- a/docs/pages/api/tree-item.md +++ b/docs/pages/api/tree-item.md @@ -32,7 +32,7 @@ You can learn more about the difference by [reading this guide](/guides/minimizi | icon | node | | The icon to display next to the tree node's label. | | label | node | | The tree node label. | | nodeId * | string | | The id of the node. | -| TransitionComponent | elementType | Collapse | The component used for the transition. | +| TransitionComponent | elementType | Collapse | The component used for the transition. [Follow our guide](/components/transitions/#transitioncomponent-prop) to learn more about the requirements for this component. | The `ref` is forwarded to the root element. diff --git a/docs/src/pages/components/transitions/transitions.md b/docs/src/pages/components/transitions/transitions.md index 59092b1d3aa05e..d00139fdf84214 100644 --- a/docs/src/pages/components/transitions/transitions.md +++ b/docs/src/pages/components/transitions/transitions.md @@ -63,7 +63,7 @@ the `timeout` property to change the entry speed. Slide in from the edge of the screen. The `direction` property controls which edge of the screen the transition starts from. -The Transition component's `mountOnEnter` property prevents the child component from being mounted +The Transition component's `mountOnEnter` property prevents the child component from being mounted until `in` is `true`. This prevents the relatively positioned component from scrolling into view from it's off-screen position. Similarly the `unmountOnExit` property removes the component from the DOM after it has been transition off screen. @@ -77,3 +77,12 @@ Expand outwards from the center of the child element. This example also demonstrates how to delay the enter transition. {{"demo": "pages/components/transitions/SimpleZoom.js", "bg": true}} + +## TransitionComponent prop + +A few of the Material-UI components accept a `TransitionComponent` prop to customize the transition. You can use any of the above components or a home-made one. +It should respect the following conditions: +Accepts an `in` prop. This corresponds to the open / close state. +Call the `onEnter` callback prop when the enter transition starts. +Call the `onExited` callback prop when the exit transition is completed. +These two callbacks allow to unmount the children when in a closed state and fully transitioned. diff --git a/packages/material-ui-lab/src/SpeedDial/SpeedDial.d.ts b/packages/material-ui-lab/src/SpeedDial/SpeedDial.d.ts index c508218b2bb500..7b66476d30c329 100644 --- a/packages/material-ui-lab/src/SpeedDial/SpeedDial.d.ts +++ b/packages/material-ui-lab/src/SpeedDial/SpeedDial.d.ts @@ -63,6 +63,7 @@ export interface SpeedDialProps openIcon?: React.ReactNode; /** * The component used for the transition. + * [Follow our guide](/components/transitions/#transitioncomponent-prop) to learn more about the requirements for this component. */ TransitionComponent?: React.ComponentType; /** @@ -71,7 +72,7 @@ export interface SpeedDialProps */ transitionDuration?: TransitionProps['timeout']; /** - * Props applied to the `Transition` element. + * Props applied to the [`Transition`](http://reactcommunity.org/react-transition-group/transition#Transition-props) element. */ TransitionProps?: TransitionProps; } diff --git a/packages/material-ui-lab/src/SpeedDial/SpeedDial.js b/packages/material-ui-lab/src/SpeedDial/SpeedDial.js index 8988d44cda7c5d..24643a1456ce8e 100644 --- a/packages/material-ui-lab/src/SpeedDial/SpeedDial.js +++ b/packages/material-ui-lab/src/SpeedDial/SpeedDial.js @@ -438,6 +438,7 @@ SpeedDial.propTypes = { openIcon: PropTypes.node, /** * The component used for the transition. + * [Follow our guide](/components/transitions/#transitioncomponent-prop) to learn more about the requirements for this component. */ TransitionComponent: PropTypes.elementType, /** @@ -453,7 +454,7 @@ SpeedDial.propTypes = { }), ]), /** - * Props applied to the `Transition` element. + * Props applied to the [`Transition`](http://reactcommunity.org/react-transition-group/transition#Transition-props) element. */ TransitionProps: PropTypes.object, }; diff --git a/packages/material-ui-lab/src/TreeItem/TreeItem.d.ts b/packages/material-ui-lab/src/TreeItem/TreeItem.d.ts index 96a38e574f8e70..bfdb57e9850112 100644 --- a/packages/material-ui-lab/src/TreeItem/TreeItem.d.ts +++ b/packages/material-ui-lab/src/TreeItem/TreeItem.d.ts @@ -30,6 +30,7 @@ export interface TreeItemProps nodeId: string; /** * The component used for the transition. + * [Follow our guide](/components/transitions/#transitioncomponent-prop) to learn more about the requirements for this component. */ TransitionComponent?: React.ComponentType; } diff --git a/packages/material-ui-lab/src/TreeItem/TreeItem.js b/packages/material-ui-lab/src/TreeItem/TreeItem.js index a17b8935f2705d..a11cde445d21bd 100644 --- a/packages/material-ui-lab/src/TreeItem/TreeItem.js +++ b/packages/material-ui-lab/src/TreeItem/TreeItem.js @@ -362,6 +362,7 @@ TreeItem.propTypes = { onKeyDown: PropTypes.func, /** * The component used for the transition. + * [Follow our guide](/components/transitions/#transitioncomponent-prop) to learn more about the requirements for this component. */ TransitionComponent: PropTypes.elementType, }; diff --git a/packages/material-ui/src/Dialog/Dialog.js b/packages/material-ui/src/Dialog/Dialog.js index 6c8eefaf4637f6..3c37ed60582580 100644 --- a/packages/material-ui/src/Dialog/Dialog.js +++ b/packages/material-ui/src/Dialog/Dialog.js @@ -371,6 +371,7 @@ Dialog.propTypes = { scroll: PropTypes.oneOf(['body', 'paper']), /** * The component used for the transition. + * [Follow our guide](/components/transitions/#transitioncomponent-prop) to learn more about the requirements for this component. */ TransitionComponent: PropTypes.elementType, /** @@ -382,7 +383,7 @@ Dialog.propTypes = { PropTypes.shape({ enter: PropTypes.number, exit: PropTypes.number }), ]), /** - * Props applied to the `Transition` element. + * Props applied to the [`Transition`](http://reactcommunity.org/react-transition-group/transition#Transition-props) element. */ TransitionProps: PropTypes.object, }; diff --git a/packages/material-ui/src/ExpansionPanel/ExpansionPanel.js b/packages/material-ui/src/ExpansionPanel/ExpansionPanel.js index 65a1c452648887..ac0a3b540e31d8 100644 --- a/packages/material-ui/src/ExpansionPanel/ExpansionPanel.js +++ b/packages/material-ui/src/ExpansionPanel/ExpansionPanel.js @@ -202,10 +202,11 @@ ExpansionPanel.propTypes = { square: PropTypes.bool, /** * The component used for the collapse effect. + * [Follow our guide](/components/transitions/#transitioncomponent-prop) to learn more about the requirements for this component. */ TransitionComponent: PropTypes.elementType, /** - * Props applied to the `Transition` element. + * Props applied to the [`Transition`](http://reactcommunity.org/react-transition-group/transition#Transition-props) element. */ TransitionProps: PropTypes.object, }; diff --git a/packages/material-ui/src/Popover/Popover.js b/packages/material-ui/src/Popover/Popover.js index 7651a5cedb5ac6..0373db9110d4d4 100644 --- a/packages/material-ui/src/Popover/Popover.js +++ b/packages/material-ui/src/Popover/Popover.js @@ -593,6 +593,7 @@ Popover.propTypes = { }), /** * The component used for the transition. + * [Follow our guide](/components/transitions/#transitioncomponent-prop) to learn more about the requirements for this component. */ TransitionComponent: PropTypes.elementType, /** @@ -604,7 +605,7 @@ Popover.propTypes = { PropTypes.oneOf(['auto']), ]), /** - * Props applied to the `Transition` element. + * Props applied to the [`Transition`](http://reactcommunity.org/react-transition-group/transition#Transition-props) element. */ TransitionProps: PropTypes.object, }; diff --git a/packages/material-ui/src/Snackbar/Snackbar.js b/packages/material-ui/src/Snackbar/Snackbar.js index 275be180eaa94e..deb0283854e79c 100644 --- a/packages/material-ui/src/Snackbar/Snackbar.js +++ b/packages/material-ui/src/Snackbar/Snackbar.js @@ -362,6 +362,7 @@ Snackbar.propTypes = { resumeHideDuration: PropTypes.number, /** * The component used for the transition. + * [Follow our guide](/components/transitions/#transitioncomponent-prop) to learn more about the requirements for this component. */ TransitionComponent: PropTypes.elementType, /** @@ -373,7 +374,7 @@ Snackbar.propTypes = { PropTypes.shape({ enter: PropTypes.number, exit: PropTypes.number }), ]), /** - * Props applied to the `Transition` element. + * Props applied to the [`Transition`](http://reactcommunity.org/react-transition-group/transition#Transition-props) element. */ TransitionProps: PropTypes.object, }; diff --git a/packages/material-ui/src/StepContent/StepContent.js b/packages/material-ui/src/StepContent/StepContent.js index e86db9c7b551e5..1b02e9e9ae4899 100644 --- a/packages/material-ui/src/StepContent/StepContent.js +++ b/packages/material-ui/src/StepContent/StepContent.js @@ -112,6 +112,7 @@ StepContent.propTypes = { orientation: PropTypes.oneOf(['horizontal', 'vertical']), /** * The component used for the transition. + * [Follow our guide](/components/transitions/#transitioncomponent-prop) to learn more about the requirements for this component. */ TransitionComponent: PropTypes.elementType, /** @@ -126,7 +127,7 @@ StepContent.propTypes = { PropTypes.oneOf(['auto']), ]), /** - * Props applied to the `Transition` element. + * Props applied to the [`Transition`](http://reactcommunity.org/react-transition-group/transition#Transition-props) element. */ TransitionProps: PropTypes.object, }; diff --git a/packages/material-ui/src/Tooltip/Tooltip.js b/packages/material-ui/src/Tooltip/Tooltip.js index 70829de9c6eede..e9250abb8e149d 100644 --- a/packages/material-ui/src/Tooltip/Tooltip.js +++ b/packages/material-ui/src/Tooltip/Tooltip.js @@ -629,10 +629,11 @@ Tooltip.propTypes = { title: PropTypes.node.isRequired, /** * The component used for the transition. + * [Follow our guide](/components/transitions/#transitioncomponent-prop) to learn more about the requirements for this component. */ TransitionComponent: PropTypes.elementType, /** - * Props applied to the `Transition` element. + * Props applied to the [`Transition`](http://reactcommunity.org/react-transition-group/transition#Transition-props) element. */ TransitionProps: PropTypes.object, };