From 5b136c901c367d82f1365b86351d75231f781c8b Mon Sep 17 00:00:00 2001 From: Tamas Kovacs Date: Thu, 15 Aug 2024 09:42:01 +0200 Subject: [PATCH] docs(ui-modal,ui-tray): function based examples are added to Modal and Tray Closes: INSTUI-4149 --- packages/ui-modal/src/Modal/README.md | 988 ++++++++++++++++++++------ packages/ui-tray/src/Tray/README.md | 118 ++- 2 files changed, 850 insertions(+), 256 deletions(-) diff --git a/packages/ui-modal/src/Modal/README.md b/packages/ui-modal/src/Modal/README.md index ae9dbda406..7ad9b8af22 100644 --- a/packages/ui-modal/src/Modal/README.md +++ b/packages/ui-modal/src/Modal/README.md @@ -8,79 +8,154 @@ overlays the application content and applies a mask to it. The default `padding` of the Modal content is `medium` but can be overridden by using the `padding` prop on the `` if the use case requires it. -```js ---- -type: example ---- -const fpo = lorem.paragraphs(5) +- ```js + const fpo = lorem.paragraphs(5) -class Example extends React.Component { - constructor (props) { - super(props) + class Example extends React.Component { + constructor(props) { + super(props) - this.state = { - open: false + this.state = { + open: false + } } - } - handleButtonClick = () => { - this.setState(function (state) { - return { open: !state.open } - }) - }; + handleButtonClick = () => { + this.setState(function (state) { + return { open: !state.open } + }) + } - handleFormSubmit = e => { - e.preventDefault() - console.log('form submitted') - this.setState(state => ({ open: false })) - } + handleFormSubmit = (e) => { + e.preventDefault() + console.log('form submitted') + this.setState((state) => ({ open: false })) + } - renderCloseButton () { - return ( - - ) + renderCloseButton() { + return ( + + ) + } + + render() { + return ( +
+ + { + this.setState({ open: false }) + }} + onSubmit={this.handleFormSubmit} + size="auto" + label="Modal Dialog: Hello World" + shouldCloseOnDocumentClick + > + + {this.renderCloseButton()} + Hello World + + + + {fpo} + + + + + + +
+ ) + } } - render () { + render() + ``` + +- ```js + const fpo = lorem.paragraphs(5) + const Example = () => { + const [open, setOpen] = useState(false) + + const handleButtonClick = () => { + setOpen((state) => !state) + } + + const handleFormSubmit = (e) => { + e.preventDefault() + console.log('form submitted') + setOpen(false) + } + + const renderCloseButton = () => { + return ( + + ) + } + return (
- { this.setState({ open: false }) }} - onSubmit={this.handleFormSubmit} + open={open} + onDismiss={() => { + setOpen(false) + }} + onSubmit={handleFormSubmit} size="auto" label="Modal Dialog: Hello World" shouldCloseOnDocumentClick > - {this.renderCloseButton()} + {renderCloseButton()} Hello World - + {fpo} - - + +
) } -} -render() -``` + render() + ``` ### Constraining Modal to a parent element @@ -88,47 +163,171 @@ By default, Modals are positioned relative to the document body. Setting the `constrain` property to `parent` will constrain the Modal within the element it is mounted from (specified via the `mountNode` property). Note: in these cases, the `mountNode` element should have an explicit `height` set: Because Modal is absolutely positioned, it has no height of its own. -```js ---- -type: example ---- -const fpo = lorem.paragraphs(1) -class Example extends React.Component { - constructor (props) { - super(props) +- ```js + const fpo = lorem.paragraphs(1) + class Example extends React.Component { + constructor(props) { + super(props) - this.state = { - open: false, - size: 'auto' + this.state = { + open: false, + size: 'auto' + } + } + + handleButtonClick = () => { + this.setState(function (state) { + return { open: !state.open } + }) + } + + renderCloseButton() { + return ( + + ) } - } - handleButtonClick = () => { - this.setState(function (state) { - return { open: !state.open } - }) + render() { + return ( +
+ + { + this.setState({ open: false }) + }} + size="fullscreen" + label="Modal Dialog: Hello World" + shouldCloseOnDocumentClick + mountNode={() => document.getElementById('constrainExample')} + constrain="parent" + > + + {this.renderCloseButton()} + This Modal is constrained to a parent + + + + {fpo} + + + + + + + + + +
+ ) + } } - renderCloseButton () { - return ( - - ) + class ModalAutoCompleteExample extends React.Component { + state = { + isShowingOptions: false + } + + handleShowOptions = () => { + this.setState({ isShowingOptions: true }) + } + handleHideOptions = () => { + this.setState({ isShowingOptions: false }) + } + render() { + const options = [ + 'Alabama', + 'Alaska', + 'American Samoa', + 'Arizona', + 'Arkansas', + 'California', + 'Colorado', + 'Connecticut', + 'Delaware', + 'District Of Columbia', + 'Federated States Of Micronesia', + 'Florida', + 'Georgia', + 'Guam', + 'Hawaii', + 'Idaho', + 'Illinois' + ] + + return ( + + ) + } } - render () { + render() + ``` + +- ```js + const fpo = lorem.paragraphs(1) + const Example = () => { + const [open, setOpen] = useState(false) + const [size, setSize] = useState('auto') + + const handleButtonClick = () => { + setOpen((state) => !state) + } + + const renderCloseButton = () => { + return ( + + ) + } return (
- { this.setState({ open: false }) }} + open={open} + onDismiss={() => { + setOpen(false) + }} size="fullscreen" label="Modal Dialog: Hello World" shouldCloseOnDocumentClick @@ -136,16 +335,22 @@ class Example extends React.Component { constrain="parent" > - {this.renderCloseButton()} + {renderCloseButton()} This Modal is constrained to a parent - {fpo} + + {fpo} + - - + + - + id="constrainExample" + >
) } -} -class ModalAutoCompleteExample extends React.Component { - state = { - isShowingOptions: false - } + const ModalAutoCompleteExample = (props) => { + const [isShowingOptions, setIsShowingOptions] = useState(false) + + const handleShowOptions = () => { + setIsShowingOptions(true) + } + const handleHideOptions = () => { + setIsShowingOptions(false) + } - handleShowOptions = () => { - this.setState({ isShowingOptions: true }) - } - handleHideOptions = () => { - this.setState({ isShowingOptions: false }) - } - render () { const options = [ - 'Alabama', 'Alaska', 'American Samoa', 'Arizona', - 'Arkansas', 'California', 'Colorado', 'Connecticut', - 'Delaware', 'District Of Columbia', - 'Federated States Of Micronesia', 'Florida', 'Georgia', - 'Guam', 'Hawaii', 'Idaho', 'Illinois' + 'Alabama', + 'Alaska', + 'American Samoa', + 'Arizona', + 'Arkansas', + 'California', + 'Colorado', + 'Connecticut', + 'Delaware', + 'District Of Columbia', + 'Federated States Of Micronesia', + 'Florida', + 'Georgia', + 'Guam', + 'Hawaii', + 'Idaho', + 'Illinois' ] - return ( - {options.map((label, index) => ( {label} @@ -192,10 +410,9 @@ class ModalAutoCompleteExample extends React.Component { ) } -} -render() -``` + render() + ``` ### Media (images, etc.) inside Modals @@ -203,34 +420,100 @@ render() **If you are displaying small, relatively uniform images or videos inside Modal, the default settings should work well.** Modal.Body will expand to the height of the media you're displaying. If there is overflow, scrollbars will be available. -```js ---- -type: example ---- -class Example extends React.Component { - constructor (props) { - super(props) +- ```js + class Example extends React.Component { + constructor(props) { + super(props) - this.state = { - open: false + this.state = { + open: false + } + } + + handleButtonClick = () => { + this.setState(function (state) { + return { open: !state.open } + }) } - } - handleButtonClick = () => { - this.setState(function (state) { - return { open: !state.open } - }) + render() { + return ( +
+ + { + this.setState({ open: false }) + }} + size="auto" + label="Modal Dialog: Hello Media" + shouldCloseOnDocumentClick + variant="inverse" + > + + + + + A small image + + + + + + + + + + + + + + +
+ ) + } } - render () { + render() + ``` + +- ```js + const Example = () => { + const [open, setOpen] = useState(false) + + const handleButtonClick = () => { + setOpen((state) => !state) + } + return (
- { this.setState({ open: false }) }} + open={open} + onDismiss={() => { + setOpen(false) + }} size="auto" label="Modal Dialog: Hello Media" shouldCloseOnDocumentClick @@ -239,14 +522,16 @@ class Example extends React.Component { - A small image + + A small image + @@ -260,60 +545,205 @@ class Example extends React.Component { /> - +
) } -} -render() -``` + render() + ``` **When you have to display large media inside the Modal (or have no control over the size of the media)**, set `overflow` to `fit`. Doing so makes Modal.Body fill 100% of the available width and height, enabling you to use the [Img](#Img) component's `constrain` property to fit the image inside Modal.Body. > `` uses CSS's [`object-fit`](https://developer.mozilla.org/en-US/docs/Web/CSS/object-fit) for its constrain property. If you're not using ``, add an `object-fit` rule to your media, and it will work with `overflow="fit"`. -```js ---- -type: example ---- -class Example extends React.Component { - constructor (props) { - super(props) +- ```js + class Example extends React.Component { + constructor(props) { + super(props) - this.state = { - open: false, - imageFit: 'cover', - modalSize: 'fullscreen' + this.state = { + open: false, + imageFit: 'cover', + modalSize: 'fullscreen' + } } - } - handleButtonClick = () => { - this.setState(function (state) { - return { open: !state.open } - }) - } + handleButtonClick = () => { + this.setState(function (state) { + return { open: !state.open } + }) + } - handleImageFitChange = (event, value) => { - this.setState({ imageFit: value }) - } + handleImageFitChange = (event, value) => { + this.setState({ imageFit: value }) + } - handleModalSizeChange = (event, value) => { - this.setState({ modalSize: value }) + handleModalSizeChange = (event, value) => { + this.setState({ modalSize: value }) + } + + render() { + return ( +
+ + Media Modal + + } + rowSpacing="medium" + > + + + + + + + + + + + + + + { + this.setState({ open: false }) + }} + size={this.state.modalSize} + label="Modal Dialog: Hello Media" + shouldCloseOnDocumentClick + variant="inverse" + overflow="fit" + > + + + + + + + + + + This Modal Contains Media + + + + + + + + + + + + + + + + + + +
+ ) + } } - render () { + render() + ``` + +- ```js + const Example = () => { + const [open, setOpen] = useState(false) + const [imageFit, setImageFit] = useState('cover') + const [modalSize, setModalSize] = useState('fullscreen') + + const handleButtonClick = () => { + setOpen((state) => !state) + } + + const handleImageFitChange = (event, value) => { + setImageFit(value) + } + + const handleModalSizeChange = (event, value) => { + setModalSize(value) + } + return (
Media Modal} + description={ + + Media Modal + + } rowSpacing="medium" > - { this.setState({ open: false }) }} - size={this.state.modalSize} + open={open} + onDismiss={() => { + setOpen(false) + }} + size={modalSize} label="Modal Dialog: Hello Media" shouldCloseOnDocumentClick variant="inverse" @@ -353,10 +785,16 @@ class Example extends React.Component { - + - This Modal Contains Media + + This Modal Contains Media + @@ -383,91 +821,188 @@ class Example extends React.Component { withBorder={false} renderIcon={IconXSolid} screenReaderLabel="Close" - onClick={this.handleButtonClick} + onClick={handleButtonClick} /> - + - +
) } -} -render() -``` + render() + ``` ### Small viewports On smaller viewports (like mobile devices or scaled-up UI), we don't want to lose space because of padding and margins. In order to achieve that, use `size="fullscreen"` on the Modal and set the `spacing` property of Modal.Header to `compact`. -```js ---- -type: example ---- -const fpo = lorem.paragraphs(1) -class Example extends React.Component { - constructor (props) { - super(props) +- ```js + const fpo = lorem.paragraphs(1) + class Example extends React.Component { + constructor(props) { + super(props) - this.state = { - open: false, - smallViewport: true + this.state = { + open: false, + smallViewport: true + } } - } - toggleOpen = () => { - this.setState(function (state) { - return { open: !state.open } - }) - } + toggleOpen = () => { + this.setState(function (state) { + return { open: !state.open } + }) + } - toggleViewport = async () => { - await this.setState(function (state) { - return { smallViewport: !state.smallViewport } - }) - } + toggleViewport = async () => { + await this.setState(function (state) { + return { smallViewport: !state.smallViewport } + }) + } - renderCloseButton () { - return ( - - ) + renderCloseButton() { + return ( + + ) + } + + render() { + return ( +
+ + + { + if (event.target.id !== 'toggleViewportButton') { + this.setState({ open: false }) + } + }} + label="Modal Dialog: Hello World" + shouldCloseOnDocumentClick + mountNode={() => document.getElementById('viewportExample')} + constrain="parent" + > + + {this.renderCloseButton()} + {this.state.smallViewport ? ( + + This Modal is optimized for small viewport + + ) : ( + This is a default size Modal + )} + + + + {fpo} + + + + + + + + + +
+ ) + } } - render () { + render() + ``` + +- ```js + const fpo = lorem.paragraphs(1) + const Example = () => { + const [open, setOpen] = useState(false) + const [smallViewport, setSmallViewport] = useState(true) + + const toggleOpen = () => { + setOpen((state) => !state) + } + + const toggleViewport = () => { + setSmallViewport((state) => !state) + } + + const renderCloseButton = () => { + return ( + + ) + } + return (
- { if (event.target.id !== 'toggleViewportButton') { - this.setState({ open: false }) + setOpen(false) } }} label="Modal Dialog: Hello World" @@ -475,19 +1010,28 @@ class Example extends React.Component { mountNode={() => document.getElementById('viewportExample')} constrain="parent" > - - {this.renderCloseButton()} - {this.state.smallViewport - ? This Modal is optimized for small viewport - : This is a default size Modal - } + + {renderCloseButton()} + {smallViewport ? ( + + This Modal is optimized for small viewport + + ) : ( + This is a default size Modal + )} - {fpo} + + {fpo} + - - + + @@ -495,19 +1039,17 @@ class Example extends React.Component { background="primary-inverse" margin="medium auto none" display="block" - width={this.state.smallViewport ? '20rem' : '50rem'} + width={smallViewport ? '20rem' : '50rem'} height="37.5rem" borderWidth="large" id="viewportExample" - > - + >
) } -} -render() -``` + render() + ``` ### Guidelines diff --git a/packages/ui-tray/src/Tray/README.md b/packages/ui-tray/src/Tray/README.md index 987c76f774..dd9e16d3e6 100644 --- a/packages/ui-tray/src/Tray/README.md +++ b/packages/ui-tray/src/Tray/README.md @@ -6,27 +6,85 @@ The Tray is an actionable container that is triggered by click and does not need > Note that the `size` property only applies when the Tray is positioned at `start` or `end` and defines the width of the Tray. -```js ---- -type: example ---- -const FPO = lorem.paragraph() -class Example extends React.Component { - constructor (props) { - super(props) - this.state = { - open: false +- ```js + const FPO = lorem.paragraph() + class Example extends React.Component { + constructor(props) { + super(props) + this.state = { + open: false + } } - } - hideTray = () => { - this.setState({ - open: false - }) + hideTray = () => { + this.setState({ + open: false + }) + } + + renderCloseButton() { + return ( + + + Hello + + + + + + ) + } + + render() { + return ( +
+ + { + this.setState({ open: false }) + }} + size="small" + placement="start" + > + + {this.renderCloseButton()} + + {FPO} + + + +
+ ) + } } - renderCloseButton () { - return ( + render() + ``` + +- ```js + const FPO = lorem.paragraph() + + const Example = () => { + const [open, setOpen] = useState(false) + + const hideTray = () => { + setOpen(false) + } + + const renderCloseButton = () => ( Hello @@ -36,41 +94,35 @@ class Example extends React.Component { placement="end" offset="small" screenReaderLabel="Close" - onClick={this.hideTray} + onClick={hideTray} /> ) - } - render () { return (
- + { this.setState({ open: false }) }} + open={open} + onDismiss={() => setOpen(false)} size="small" placement="start" > - {this.renderCloseButton()} - {FPO} + {renderCloseButton()} + + {FPO} +
) } -} -render() -``` + render() + ``` ### Guidelines