From 68d6a9f21cb13f20c4dc66f7b38aaae0af20dc3c Mon Sep 17 00:00:00 2001 From: udaymattam Date: Sat, 24 Sep 2022 00:03:25 +0530 Subject: [PATCH 1/3] Modelmanager and disclose manager hight props --- packages/terra-application/CHANGELOG.md | 3 + .../app/components.2/ModalManager.app.mdx | 57 +++++++++++++++++++ .../DisclosureManagerContext.app.mdx | 4 ++ 3 files changed, 64 insertions(+) diff --git a/packages/terra-application/CHANGELOG.md b/packages/terra-application/CHANGELOG.md index 30f6b3c06..ad5b5cc92 100644 --- a/packages/terra-application/CHANGELOG.md +++ b/packages/terra-application/CHANGELOG.md @@ -2,6 +2,9 @@ ## Unreleased +* Changed + * Updated documentation for terra-application-ModelManager. + * Added * Added user action utility button. diff --git a/packages/terra-application/src/terra-dev-site/app/components.2/ModalManager.app.mdx b/packages/terra-application/src/terra-dev-site/app/components.2/ModalManager.app.mdx index 403baa569..6da1083a4 100644 --- a/packages/terra-application/src/terra-dev-site/app/components.2/ModalManager.app.mdx +++ b/packages/terra-application/src/terra-dev-site/app/components.2/ModalManager.app.mdx @@ -82,6 +82,63 @@ The provided component will be rendered below the standard ActionHeader and abov provide additional context to every disclosed component. This component is provided once to the ModalManager instance, not on a per-disclosure basis, and each component in the disclosure stack will be decorated with the same accessory component. +### Static Height vs. Dynamic Height + +Terra-Model-Manager was intentionally designed to have static preset heights in order to work in conjunction with Terra content that can adjust responsively using the [terra-responsive-element](https://engineering.cerner.com/terra-ui/components/cerner-terra-core-docs/responsive-element/about), as well as any conditionally positioned UI elements like a [popup](https://engineering.cerner.com/terra-ui/components/cerner-terra-framework-docs/popup/popup), [multi-select dropdown](https://engineering.cerner.com/terra-ui/components/cerner-terra-core-docs/form-select/multi-select), or [date picker](https://engineering.cerner.com/terra-ui/components/cerner-terra-framework-docs/date-picker/date-picker). Having static preset heights allows for Terra to quickly present modal content without requiring extensive browser multiple-render drawing calculations that results in poor application performance. + +Some may be used to other libraries that commonly offer simple modals that can adjust the modal's height dynamically based on the content provided, but those situations only work well for when content is designed for a single presentation (i.e. is not responsive), and ones that have no higher z-index layers that require position calculation relative to the base content (i.e. no popups with pointers). + +### Creating Modal Content + +The Modal-Manager is intended for content which has regularly composed & designed layouts, including responsive variations. It is very grid-based, so it comes with standard heights and widths to accommodate the highly-structured assembly of content. + +When the preset size of the modal's width or height is _larger_ than the available device-screen or viewport (e.g. if you shrink down your window smaller than what the modal size was set to be), at that point the modal-manager will then "stick" near to the edge of the viewport as it's outer size and not flow offscreen. It is recommended to build the inner content with a responsive design, so when the modal is smaller than it’s preset size, the content will then know to adapt and adjust to alternate layouts accordingly to the new maximum available height and/or width as the outer size. If content is not built responsively, or if you intentionally build the content to overflow in one direction, it will then force scrolling inside of the modal. Scrolling is perfectly acceptable, but should be limited to one direction, preferably vertical-only. + +The key thing to remember is that the Modal-Manager, similar to a page layout, works based on the "**outside-in**" layout principal, which allows the _inside_ content to respond when the _outside_ container changes in size. The Modal-Manager unfortunately cannot simultaneously also follow the "**inside-out**" layout principal, which would mean the _outside_ container height grows or shrinks based on the _inside_ content size. The reason is that the inside content cannot dictate what size it would like to be at the same as as listening for when it no longer has any space remaining, which is required in order to be able to change itself to a new layout, and cannot do both (or at least not without attempting many redraws). Designers are encouraged to create structured and grid based layout designs that work well for the modal layout size options that best utilize space, similar to designing base pages within applications. + +### Sizing: Height & Width Options + +The Terra-Modal-Manager has two methods of setting the preferred modal height & width. The first method is by choosing from a list of easy shorthand size options that combine a predefined height and width pair, which works standard application screen ratios. The second method is more advanced and provides the ability to choose from a list of grid-based dimensions to set the height and width independently. _(Note: all values used for Modal-Manager are true pixels and not rem (relative em) units.)_ +Using the `size` prop within the [disclose argument API](/application/terra-application/contexts/disclosure-manager-context#disclosure-props) allows the consumer to provide a simpler implementation to set the modal preferred dimension, and typically might be used for common application disclosures of similarly sized content. _(Note: `size` should not be provided if `dimensions` are specified.)_ + +|`size` prop: Shorthand options|pixel dimensions| +|---|---| +|`tiny`| w: 320px, h: 240px | +|`small`| w: 640px, h: 420px | +|`medium`| w: 960px, h: 600px | +|**default**| w: 1120px, h: 690px _(modal size if no other details are provided)_ | +|`large`| w: 1280px, h: 870px | +|`huge`| w: 1600px, h: 960px | +|`fullscreen`| w: screen width less ~10px, h: screen height less ~10px | + +For application content that needs more specific dimensional control of modal sizes, using the `dimension` prop within the [disclose argument API](/application/terra-application/contexts/disclosure-manager-context#disclose-props) will be the implementation to choose. Consumers supply a simple object that contains both height wand width values: `{ height: '480', width: '600' }`. _(Note: `dimensions` should not be provided if a `size` is specified.)_ + +|`dimensions` prop: Width options|pixel dimensions| +|---|---| +|`width: '320'`| w: 320px, h: -- | +|`width: '480'`| w: 480px, h: -- | +|`width: '560'`| w: 560px, h: -- | +|`width: '640'`| w: 640px, h: -- | +|`width: '800'`| w: 800px, h: -- | +|`width: '960'`| w: 960px, h: -- | +|`width: '1120'`| w: 1120px, h: -- | +|`width: '1280'`| w: 1280px, h: -- | +|`width: '1440'`| w: 1440px, h: -- | +|`width: '1600'`| w: 1600px, h: -- | +|`width: '1760'`| w: 1760px, h: -- | +|`width: '1920'`| w: 1920px, h: -- | + +|`dimensions` prop: Height options|pixel dimensions| +|---|---| +|`height: '240'`| w: --, h: 240px | +|`height: '420'`| w: --, h: 420px | +|`height: '600'`| w: --, h: 600px | +|`height: '690'`| w: --, h: 690px | +|`height: '780'`| w: --, h: 780px | +|`height: '870'`| w: --, h: 870px | +|`height: '960'`| w: --, h: 960px | +|`height: '1140'`| w: --, h: 1140px | + ### Example ```jsx diff --git a/packages/terra-application/src/terra-dev-site/app/contexts.2/DisclosureManagerContext.app.mdx b/packages/terra-application/src/terra-dev-site/app/contexts.2/DisclosureManagerContext.app.mdx index 02cc76dd8..5316db8a9 100644 --- a/packages/terra-application/src/terra-dev-site/app/contexts.2/DisclosureManagerContext.app.mdx +++ b/packages/terra-application/src/terra-dev-site/app/contexts.2/DisclosureManagerContext.app.mdx @@ -99,6 +99,8 @@ disclosureManager.disclose({ }) ``` +### Disclose props + `disclose` Argument API: |Key|Is Required|Value| @@ -108,6 +110,8 @@ disclosureManager.disclose({ |`dimensions`|optional|An Object containing explicit `height` and `width` values for the disclosure. These values may not be honored due to the disclosure type or the available viewport size. `dimensions` should not be provided if a `size` is specified.
Supported `height` values include: `'240'`, `'420'`, `'600'`, `'690'`, `'780'`, `'870'`, `'960'`, `'1140'`.
Supported `width` values include: `'320'`, `'480'`, `'560'`, `'640'`, `'800'`, `'960'`, `'1120'`, `'1280'`, `'1440'`, `'1600'`, `'1760'`, `'1920'`.| |`content`|**required**|An Object containing a key and a component describing the component to be disclosed. See the `content` API below.| +### Content props + `content` Object API: |Key|Is Required|Value| From 87462c498b051c6f90e9351acf7c51b4433f0297 Mon Sep 17 00:00:00 2001 From: udaymattam Date: Sat, 24 Sep 2022 00:40:03 +0530 Subject: [PATCH 2/3] minor changes --- packages/terra-application/CHANGELOG.md | 2 +- .../src/terra-dev-site/app/components.2/ModalManager.app.mdx | 3 ++- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/packages/terra-application/CHANGELOG.md b/packages/terra-application/CHANGELOG.md index ad5b5cc92..9d6edfd0c 100644 --- a/packages/terra-application/CHANGELOG.md +++ b/packages/terra-application/CHANGELOG.md @@ -3,7 +3,7 @@ ## Unreleased * Changed - * Updated documentation for terra-application-ModelManager. + * Updated size explanations for ModalManager managed by DisclosureManagerContext. * Added * Added user action utility button. diff --git a/packages/terra-application/src/terra-dev-site/app/components.2/ModalManager.app.mdx b/packages/terra-application/src/terra-dev-site/app/components.2/ModalManager.app.mdx index 6da1083a4..352e389fa 100644 --- a/packages/terra-application/src/terra-dev-site/app/components.2/ModalManager.app.mdx +++ b/packages/terra-application/src/terra-dev-site/app/components.2/ModalManager.app.mdx @@ -98,7 +98,8 @@ The key thing to remember is that the Modal-Manager, similar to a page layout, w ### Sizing: Height & Width Options -The Terra-Modal-Manager has two methods of setting the preferred modal height & width. The first method is by choosing from a list of easy shorthand size options that combine a predefined height and width pair, which works standard application screen ratios. The second method is more advanced and provides the ability to choose from a list of grid-based dimensions to set the height and width independently. _(Note: all values used for Modal-Manager are true pixels and not rem (relative em) units.)_ +The Terra-Modal-Manager has two methods of setting the preferred modal height & width. The first method is by choosing from a list of easy shorthand size options that combine a predefined height and width pair, which works standard application screen ratios. The second method is more advanced and provides the ability to choose from a list of grid-based dimensions to set the height and width independently. _(Note: all values used for Modal-Manager are true pixels and not rem, relative em units.)_ + Using the `size` prop within the [disclose argument API](/application/terra-application/contexts/disclosure-manager-context#disclosure-props) allows the consumer to provide a simpler implementation to set the modal preferred dimension, and typically might be used for common application disclosures of similarly sized content. _(Note: `size` should not be provided if `dimensions` are specified.)_ |`size` prop: Shorthand options|pixel dimensions| From 32b371d55bc0ea2c19e5ebf3c88d8e652b13ea11 Mon Sep 17 00:00:00 2001 From: udaymattam Date: Sat, 24 Sep 2022 00:52:41 +0530 Subject: [PATCH 3/3] ModelManager --- .../app/components.2/ModalManager.app.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/packages/terra-application/src/terra-dev-site/app/components.2/ModalManager.app.mdx b/packages/terra-application/src/terra-dev-site/app/components.2/ModalManager.app.mdx index 352e389fa..3363210c7 100644 --- a/packages/terra-application/src/terra-dev-site/app/components.2/ModalManager.app.mdx +++ b/packages/terra-application/src/terra-dev-site/app/components.2/ModalManager.app.mdx @@ -84,21 +84,21 @@ and each component in the disclosure stack will be decorated with the same acces ### Static Height vs. Dynamic Height -Terra-Model-Manager was intentionally designed to have static preset heights in order to work in conjunction with Terra content that can adjust responsively using the [terra-responsive-element](https://engineering.cerner.com/terra-ui/components/cerner-terra-core-docs/responsive-element/about), as well as any conditionally positioned UI elements like a [popup](https://engineering.cerner.com/terra-ui/components/cerner-terra-framework-docs/popup/popup), [multi-select dropdown](https://engineering.cerner.com/terra-ui/components/cerner-terra-core-docs/form-select/multi-select), or [date picker](https://engineering.cerner.com/terra-ui/components/cerner-terra-framework-docs/date-picker/date-picker). Having static preset heights allows for Terra to quickly present modal content without requiring extensive browser multiple-render drawing calculations that results in poor application performance. +ModalManager was intentionally designed to have static preset heights in order to work in conjunction with Terra content that can adjust responsively using the [terra-responsive-element](https://engineering.cerner.com/terra-ui/components/cerner-terra-core-docs/responsive-element/about), as well as any conditionally positioned UI elements like a [popup](https://engineering.cerner.com/terra-ui/components/cerner-terra-framework-docs/popup/popup), [multi-select dropdown](https://engineering.cerner.com/terra-ui/components/cerner-terra-core-docs/form-select/multi-select), or [date picker](https://engineering.cerner.com/terra-ui/components/cerner-terra-framework-docs/date-picker/date-picker). Having static preset heights allows for Terra to quickly present modal content without requiring extensive browser multiple-render drawing calculations that results in poor application performance. Some may be used to other libraries that commonly offer simple modals that can adjust the modal's height dynamically based on the content provided, but those situations only work well for when content is designed for a single presentation (i.e. is not responsive), and ones that have no higher z-index layers that require position calculation relative to the base content (i.e. no popups with pointers). ### Creating Modal Content -The Modal-Manager is intended for content which has regularly composed & designed layouts, including responsive variations. It is very grid-based, so it comes with standard heights and widths to accommodate the highly-structured assembly of content. +The ModalManager is intended for content which has regularly composed & designed layouts, including responsive variations. It is very grid-based, so it comes with standard heights and widths to accommodate the highly-structured assembly of content. -When the preset size of the modal's width or height is _larger_ than the available device-screen or viewport (e.g. if you shrink down your window smaller than what the modal size was set to be), at that point the modal-manager will then "stick" near to the edge of the viewport as it's outer size and not flow offscreen. It is recommended to build the inner content with a responsive design, so when the modal is smaller than it’s preset size, the content will then know to adapt and adjust to alternate layouts accordingly to the new maximum available height and/or width as the outer size. If content is not built responsively, or if you intentionally build the content to overflow in one direction, it will then force scrolling inside of the modal. Scrolling is perfectly acceptable, but should be limited to one direction, preferably vertical-only. +When the preset size of the modal's width or height is _larger_ than the available device-screen or viewport (e.g. if you shrink down your window smaller than what the modal size was set to be), at that point the ModalManager will then "stick" near to the edge of the viewport as it's outer size and not flow offscreen. It is recommended to build the inner content with a responsive design, so when the modal is smaller than it’s preset size, the content will then know to adapt and adjust to alternate layouts accordingly to the new maximum available height and/or width as the outer size. If content is not built responsively, or if you intentionally build the content to overflow in one direction, it will then force scrolling inside of the modal. Scrolling is perfectly acceptable, but should be limited to one direction, preferably vertical-only. -The key thing to remember is that the Modal-Manager, similar to a page layout, works based on the "**outside-in**" layout principal, which allows the _inside_ content to respond when the _outside_ container changes in size. The Modal-Manager unfortunately cannot simultaneously also follow the "**inside-out**" layout principal, which would mean the _outside_ container height grows or shrinks based on the _inside_ content size. The reason is that the inside content cannot dictate what size it would like to be at the same as as listening for when it no longer has any space remaining, which is required in order to be able to change itself to a new layout, and cannot do both (or at least not without attempting many redraws). Designers are encouraged to create structured and grid based layout designs that work well for the modal layout size options that best utilize space, similar to designing base pages within applications. +The key thing to remember is that the ModalManager, similar to a page layout, works based on the "**outside-in**" layout principal, which allows the _inside_ content to respond when the _outside_ container changes in size. The ModalManager unfortunately cannot simultaneously also follow the "**inside-out**" layout principal, which would mean the _outside_ container height grows or shrinks based on the _inside_ content size. The reason is that the inside content cannot dictate what size it would like to be at the same as as listening for when it no longer has any space remaining, which is required in order to be able to change itself to a new layout, and cannot do both (or at least not without attempting many redraws). Designers are encouraged to create structured and grid based layout designs that work well for the modal layout size options that best utilize space, similar to designing base pages within applications. ### Sizing: Height & Width Options -The Terra-Modal-Manager has two methods of setting the preferred modal height & width. The first method is by choosing from a list of easy shorthand size options that combine a predefined height and width pair, which works standard application screen ratios. The second method is more advanced and provides the ability to choose from a list of grid-based dimensions to set the height and width independently. _(Note: all values used for Modal-Manager are true pixels and not rem, relative em units.)_ +The ModalManager has two methods of setting the preferred modal height & width. The first method is by choosing from a list of easy shorthand size options that combine a predefined height and width pair, which works standard application screen ratios. The second method is more advanced and provides the ability to choose from a list of grid-based dimensions to set the height and width independently. _(Note: all values used for ModalManager are true pixels and not rem, relative em units.)_ Using the `size` prop within the [disclose argument API](/application/terra-application/contexts/disclosure-manager-context#disclosure-props) allows the consumer to provide a simpler implementation to set the modal preferred dimension, and typically might be used for common application disclosures of similarly sized content. _(Note: `size` should not be provided if `dimensions` are specified.)_