From f1ef52d6bc9a39a7bada9345b0de3c48ecba0296 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Kry=C5=A1p=C3=ADn?= Date: Tue, 21 May 2024 11:21:47 +0200 Subject: [PATCH] BREAKING CHANGE(web-twig): Turn off scrolling inside ModalDialog by default #DS-1184 --- docs/migrations/web-twig/MIGRATION-v3.md | 3 + packages/web-twig/DEPRECATIONS-v3.md | 13 -- .../components/Modal/Modal.stories.twig | 2 +- .../components/Modal/ModalDialog.twig | 4 +- .../src/Resources/components/Modal/README.md | 150 ++++++++------- .../__tests__/__fixtures__/modalDefault.twig | 2 +- .../__snapshots__/modalDefault.twig.snap.html | 2 +- .../Modal/stories/ModalDefault.twig | 62 ++++--- .../stories/ModalScrollingLongContent.twig | 171 +++++++----------- 9 files changed, 179 insertions(+), 230 deletions(-) diff --git a/docs/migrations/web-twig/MIGRATION-v3.md b/docs/migrations/web-twig/MIGRATION-v3.md index fc86bf439f..9ce94aa746 100644 --- a/docs/migrations/web-twig/MIGRATION-v3.md +++ b/docs/migrations/web-twig/MIGRATION-v3.md @@ -190,6 +190,9 @@ It is possible to re-enable the inside scrolling by adding the `isScrollable` pr Add `isScrollable` prop to the `ModalDialog` component. +If you use `ScrollView` for scrolling the content of your modal, you must also make the +`ModalDialog` scrollable by setting the `isScrollable` prop. + ### Modal: ModalDialog Uniform Appearance The uniform `ModalDialog` appearance replaced the current behavior. Current mobile appearance diff --git a/packages/web-twig/DEPRECATIONS-v3.md b/packages/web-twig/DEPRECATIONS-v3.md index 4dd7c68913..548ee4b888 100644 --- a/packages/web-twig/DEPRECATIONS-v3.md +++ b/packages/web-twig/DEPRECATIONS-v3.md @@ -59,19 +59,6 @@ Use: See [`Tooltip` documentation][tooltip-readme] for more details and examples. -### ModalDialog `isScrollable` Prop - -The `isScrollable` prop will be set to `false` by default in the next major release and the ModalDialog will be made -non-scrollable by default. It will be possible to re-enable the inside scrolling by adding the `isScrollable` prop. - -#### Migration Guide - -Add `isScrollable` prop to the `ModalDialog` component. - -#### Migration Guide - -Either install newer version of the `spirit-icons` package or add `danger` named icon to your project's icons. - [dropdown-readme]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web-twig/src/Resources/components/Dropdown/README.md [readme-deprecations]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web-twig/README.md#deprecations [tooltip-readme]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web-twig/src/Resources/components/Tooltip/README.md diff --git a/packages/web-twig/src/Resources/components/Modal/Modal.stories.twig b/packages/web-twig/src/Resources/components/Modal/Modal.stories.twig index 107ed6dcc8..94c8bf852f 100644 --- a/packages/web-twig/src/Resources/components/Modal/Modal.stories.twig +++ b/packages/web-twig/src/Resources/components/Modal/Modal.stories.twig @@ -40,7 +40,7 @@ } const toggleScrolling = (selector) => { - document.querySelector(selector).classList.toggle('ModalDialog--nonScrollable'); + document.querySelector(selector).classList.toggle('ModalDialog--scrollable'); } diff --git a/packages/web-twig/src/Resources/components/Modal/ModalDialog.twig b/packages/web-twig/src/Resources/components/Modal/ModalDialog.twig index ab40352b54..82146e02b3 100644 --- a/packages/web-twig/src/Resources/components/Modal/ModalDialog.twig +++ b/packages/web-twig/src/Resources/components/Modal/ModalDialog.twig @@ -3,7 +3,7 @@ {%- set _elementType = props.elementType | default('article') -%} {%- set _isDockedOnMobile = props.isDockedOnMobile | default(false) -%} {%- set _isExpandedOnMobile = props.isExpandedOnMobile | default(false) -%} -{%- set _isScrollable = props.isScrollable ?? true -%} +{%- set _isScrollable = props.isScrollable | default(false) -%} {%- set _maxHeightFromTabletUp = props.maxHeightFromTabletUp | default(null) -%} {%- set _preferredHeightOnMobile = props.preferredHeightOnMobile | default(null) -%} {%- set _preferredHeightFromTabletUp = props.preferredHeightFromTabletUp | default(null) -%} @@ -12,7 +12,7 @@ {%- set _rootClassName = _spiritClassPrefix ~ 'ModalDialog' -%} {%- set _rootDockOnMobileClassName = _isDockedOnMobile ? _spiritClassPrefix ~ 'ModalDialog--dockOnMobile' : null -%} {%- set _rootExpandOnMobileClassName = _isExpandedOnMobile ? _spiritClassPrefix ~ 'ModalDialog--expandOnMobile' : null -%} -{%- set _rootScrollableClassName = _isScrollable ? null : _spiritClassPrefix ~ 'ModalDialog--nonScrollable' -%} +{%- set _rootScrollableClassName = _isScrollable ? _spiritClassPrefix ~ 'ModalDialog--scrollable' : null -%} {# Miscellaneous #} {%- set _styleProps = useStyleProps(props) -%} diff --git a/packages/web-twig/src/Resources/components/Modal/README.md b/packages/web-twig/src/Resources/components/Modal/README.md index c1484da4f9..b169bac8c2 100644 --- a/packages/web-twig/src/Resources/components/Modal/README.md +++ b/packages/web-twig/src/Resources/components/Modal/README.md @@ -96,7 +96,7 @@ On mobile screens, Modal can be docked to the bottom of the viewport using the ` #### Expanded Variant -By default the docked dialog on mobile screens shrinks to fit the height of its content +By default, the docked dialog on mobile screens shrinks to fit the height of its content (if smaller than the viewport). Use the `isExpandedOnMobile` option to expand the dialog on mobile. ```twig @@ -105,66 +105,26 @@ By default the docked dialog on mobile screens shrinks to fit the height of its ``` -### Custom Height - -By default, Modal expands to fit the height of its content, as long as it fits the viewport (see [more below](#custom-max-height)). -You can override this behavior by setting a preferred height using the following options: - -- `preferredHeightOnMobile` for mobile screens, and -- `preferredHeightFromTabletUp` for tablet screens and up. - -This is useful for Modals with dynamic content, e.g. a list of items that can be added or removed, or a multistep wizard. - -```twig - - … - -``` - -πŸ‘‰ Please note the preferred height options are ignored when scrolling inside ModalDialog is -[turned off](#disable-scrolling-inside-modaldialog). - -πŸ‘‰ Please note the custom height values are considered **preferred:** Modal will not expand beyond the viewport height. - -### Custom Max Height - -The default maximum height of Modal is: - -- viewport height minus 1100 spacing on mobile screens, and -- 600 px on tablet screens and up (shrunk if necessary). - -You can use the `maxHeightFromTabletUp` option to override the max height on tablet screens and up: - -```twig - - … - -``` - -πŸ‘‰ Please note the max height is ignored when scrolling inside ModalDialog is [turned off](#disable-scrolling-inside-modaldialog). - -πŸ‘‰ Please note the max height on mobile screens is currently not customizable. Let us know if you need this feature! πŸ™ - ### API -| Name | Type | Default | Required | Description | -| ----------------------------- | ----------------------------- | --------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- | -| `accept-charset` | `string` | `null` | βœ• | `elementType="form"` only: Character encodings to use for form submission (intentionally in kebab-case) | -| `action` | `string` | `null` | βœ• | `elementType="form"` only: URL to use for form submission | -| `autocomplete` | `string` | `null` | βœ• | `elementType="form"` only: [Automated assistance in filling][autocomplete-attr] | -| `elementType` | `string` | `article` | βœ• | HTML tag to render | -| `enctype` | `string` | `null` | βœ• | `elementType="form"` only: Encoding to use for form submission | -| `isDockedOnMobile` | `bool` | `false` | βœ• | [REQUIRES FEATURE FLAG](#feature-flag-uniform-appearance-on-all-breakpoints): Dock the ModalDialog to the bottom of the screen on mobile | -| `isExpandedOnMobile` | `bool` | `false` | βœ• | If the ModalDialog should expand on mobile. Overrides any height defined by `preferredHeightOnMobile`. | -| `isScrollable` | `bool` | `true` | βœ• | If the ModalDialog should be scrollable. If set to `false`, the dialog will not scroll and will expand to fit the content. | -| `maxHeightFromTabletUp` | `string` | `null` | βœ• | Max height of the modal. Accepts any valid CSS value. | -| `method` | [`get` \| `post` \| `dialog`] | `null` | βœ• | `elementType="form"` only: HTTP method to use for form submission | -| `name` | `string` | `null` | βœ• | `elementType="form"` only: Name of the form | -| `novalidate` | `void` | `null` | βœ• | `elementType="form"` only: [If the dialog should have validation disabled][novalidate-attr] | -| `preferredHeightFromTabletUp` | `string` | `null` | βœ• | Preferred height of the modal on tablet and larger. Accepts any valid CSS value. | -| `preferredHeightOnMobile` | `string` | `null` | βœ• | Preferred height of the modal on mobile. Accepts any valid CSS value. | -| `rel` | `string` | `null` | βœ• | `elementType="form"` only: Relationship between the current document and the linked resource | -| `target` | `string` | `null` | βœ• | `elementType="form"` only: Browsing context for form submission | +| Name | Type | Default | Required | Description | +| ----------------------------- | ----------------------------- | --------- | -------- | -------------------------------------------------------------------------------------------------------------------------- | +| `accept-charset` | `string` | `null` | βœ• | `elementType="form"` only: Character encodings to use for form submission (intentionally in kebab-case) | +| `action` | `string` | `null` | βœ• | `elementType="form"` only: URL to use for form submission | +| `autocomplete` | `string` | `null` | βœ• | `elementType="form"` only: [Automated assistance in filling][autocomplete-attr] | +| `elementType` | `string` | `article` | βœ• | HTML tag to render | +| `enctype` | `string` | `null` | βœ• | `elementType="form"` only: Encoding to use for form submission | +| `isDockedOnMobile` | `bool` | `false` | βœ• | Dock the ModalDialog to the bottom of the screen on mobile | +| `isExpandedOnMobile` | `bool` | `false` | βœ• | If the ModalDialog should expand on mobile. Overrides any height defined by `preferredHeightOnMobile`. | +| `isScrollable` | `bool` | `true` | βœ• | If the ModalDialog should be scrollable. If set to `false`, the dialog will not scroll and will expand to fit the content. | +| `maxHeightFromTabletUp` | `string` | `null` | βœ• | Max height of the modal. Accepts any valid CSS value. | +| `method` | [`get` \| `post` \| `dialog`] | `null` | βœ• | `elementType="form"` only: HTTP method to use for form submission | +| `name` | `string` | `null` | βœ• | `elementType="form"` only: Name of the form | +| `novalidate` | `void` | `null` | βœ• | `elementType="form"` only: [If the dialog should have validation disabled][novalidate-attr] | +| `preferredHeightFromTabletUp` | `string` | `null` | βœ• | Preferred height of the modal on tablet and larger. Accepts any valid CSS value. | +| `preferredHeightOnMobile` | `string` | `null` | βœ• | Preferred height of the modal on mobile. Accepts any valid CSS value. | +| `rel` | `string` | `null` | βœ• | `elementType="form"` only: Relationship between the current document and the linked resource | +| `target` | `string` | `null` | βœ• | `elementType="form"` only: Browsing context for form submission | On top of the API options, the components accept [additional attributes][readme-additional-attributes]. If you need more control over the styling of a component, you can use [style props][readme-style-props] @@ -307,7 +267,18 @@ Use our JavaScript plugin to open your Modal, e.g.: ## Scrolling Long Content -When Modals become too long for the user's viewport or device, they automatically scroll independently of the page itself. +In case the content is longer than user's viewport or device, the ModalBody will expand to fit the height of its content +and the whole ModalDialog will scroll. + +### Enable Scrolling Inside ModalDialog + +Scrolling inside ModalDialog can be turned on by adding the `isScrollable` prop: + +```twig + + … + +``` ### Scrolling with ScrollView @@ -315,32 +286,60 @@ To make content overflow more obvious to users, you can wrap the ModalBody conte takes over the responsibility for scrolling and provides visual overflow decorators, e.g.: ```twig - - - …Long content… - - + + … + + + …Long content… + + + … + ``` -### Disable Scrolling Inside ModalDialog +### Custom Height + +By default, ModalDialog grows to the height of its content until it reaches the [maximum height](#custom-max-height) +limit. + +You can set a custom preferred height of ModalDialog using a custom property: + +- `preferredHeightOnMobile` for mobile screens, and +- `preferredHeightFromTabletUp` for tablet screens and up. -Scrolling inside ModalDialog can be turned off by setting the `ModalDialog` prop `isScrollable` to `false`: +This is useful for Modals with dynamic content, e.g. a list of items that can be added or removed, or a multistep wizard. ```twig - - + + … ``` -This way, the ModalBody will expand to fit the height of its content and the whole ModalDialog will scroll in case the -content is longer than user's viewport. +⚠️ This feature is only available for ModalDialogs with the `isScrollable` prop. + +πŸ‘‰ Please note the custom height values are considered **preferred**. Scrollable ModalDialog will never expand beyond +the viewport height. See the [Custom Max Height](#custom-max-height) section for more information. + +### Custom Max Height + +The default maximum height of a scrollable ModalDialog is **600 px**, as long as it can fit the viewport. + +If the viewport is smaller, scrollable ModalDialog will shrink to fit the viewport. In such case, the ModalDialog height +will calculate as "viewport height (`100dvh`) minus 1100 spacing". -πŸ‘‰ Please note that this modifier class can produce unexpected results when used in combination with ScrollView. +You can use the prop `maxHeightFromTabletUp` to override the default maximum height limit on tablet +screens and up: + +```twig + + … + +``` -#### ⚠️ DEPRECATION NOTICE +⚠️ This feature is only available for ModalDialogs with the `isScrollable` prop. -The `isScrollable` prop will be set to `false` by default in the next major release and the ModalDialog will be made -non-scrollable by default. It will be possible to re-enable the inside scrolling by adding the `isScrollable` prop. +πŸ‘‰ If a [custom height](#custom-height) is set, the custom max height is only applied if it's smaller than the custom +height. ## Stacking Modals @@ -413,7 +412,6 @@ Or, feel free to write the controlling script yourself. [modal]: https://github.com/lmc-eu/spirit-design-system/tree/main/packages/web/src/scss/components/Modal [novalidate-attr]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/form#novalidate [readme-additional-attributes]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web-twig/README.md#additional-attributes -[readme-deprecations]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web-twig/README.md#deprecations [readme-escape-hatches]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web-twig/README.md#escape-hatches [readme-feature-flags]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web/README.md#feature-flags [readme-style-props]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web-twig/README.md#style-props diff --git a/packages/web-twig/src/Resources/components/Modal/__tests__/__fixtures__/modalDefault.twig b/packages/web-twig/src/Resources/components/Modal/__tests__/__fixtures__/modalDefault.twig index dbefac6448..cefca22500 100644 --- a/packages/web-twig/src/Resources/components/Modal/__tests__/__fixtures__/modalDefault.twig +++ b/packages/web-twig/src/Resources/components/Modal/__tests__/__fixtures__/modalDefault.twig @@ -43,7 +43,7 @@ elementType="form" isDockedOnMobile isExpandedOnMobile - isScrollable={ false } + isScrollable maxHeightFromTabletUp="700px" method="dialog" preferredHeightOnMobile="400px" diff --git a/packages/web-twig/src/Resources/components/Modal/__tests__/__snapshots__/modalDefault.twig.snap.html b/packages/web-twig/src/Resources/components/Modal/__tests__/__snapshots__/modalDefault.twig.snap.html index 1f0fc84430..0c86650b01 100644 --- a/packages/web-twig/src/Resources/components/Modal/__tests__/__snapshots__/modalDefault.twig.snap.html +++ b/packages/web-twig/src/Resources/components/Modal/__tests__/__snapshots__/modalDefault.twig.snap.html @@ -59,7 +59,7 @@

-
+

Title of the Modal diff --git a/packages/web-twig/src/Resources/components/Modal/stories/ModalDefault.twig b/packages/web-twig/src/Resources/components/Modal/stories/ModalDefault.twig index 0bab950530..2bbf11979d 100644 --- a/packages/web-twig/src/Resources/components/Modal/stories/ModalDefault.twig +++ b/packages/web-twig/src/Resources/components/Modal/stories/ModalDefault.twig @@ -37,8 +37,8 @@ - - + + @@ -64,7 +64,7 @@ @@ -97,46 +97,52 @@ - - - - - Modal with Custom Height + + + + Modal Title -

- This modal has a custom height of 400px. -

- The max height cannot be customized on mobile though. -

-

- This modal has a custom height of 500px. -

- The max height of this modal is 700px. +

+ Lorem ipsum dolor sit amet, consectetur adipisicing elit. Aliquam at excepturi laudantium magnam mollitia + perferendis reprehenderit, voluptate. Cum delectus dicta ducimus eligendi excepturi natus perferendis + provident unde. Eveniet, iste, molestiae?

+ + + + + + + + - - diff --git a/packages/web-twig/src/Resources/components/Modal/stories/ModalScrollingLongContent.twig b/packages/web-twig/src/Resources/components/Modal/stories/ModalScrollingLongContent.twig index f982a44a5d..01b81529e3 100644 --- a/packages/web-twig/src/Resources/components/Modal/stories/ModalScrollingLongContent.twig +++ b/packages/web-twig/src/Resources/components/Modal/stories/ModalScrollingLongContent.twig @@ -7,6 +7,47 @@ Lorem ipsum dolor sit amet, consectetur adipisicing elit. Aliquam at excepturi laudantium magnam mollitia perferendis reprehenderit, voluptate. Cum delectus dicta + + + + {%- for i in range(1,9) -%} +

+ Lorem ipsum dolor sit amet, consectetur adipisicing elit. Aliquam at excepturi laudantium magnam mollitia + perferendis reprehenderit, voluptate. Cum delectus dicta ducimus eligendi excepturi natus perferendis + provident unde. Eveniet, iste, molestiae? +

+ {%- endfor -%} + + + + + + + + + + + + + + + + Lorem ipsum dolor sit amet, consectetur adipisicing elit. Aliquam at excepturi laudantium magnam mollitia + perferendis reprehenderit, voluptate. Cum delectus dicta + @@ -20,27 +61,7 @@ perferendis reprehenderit, voluptate. Cum delectus dicta ducimus eligendi excepturi natus perferendis provident unde. Eveniet, iste, molestiae?

-

- Lorem ipsum dolor sit amet, consectetur adipisicing elit. Aliquam at excepturi laudantium magnam mollitia - perferendis reprehenderit, voluptate. Cum delectus dicta ducimus eligendi excepturi natus perferendis - provident unde. Eveniet, iste, molestiae? -

-

- Lorem ipsum dolor sit amet, consectetur adipisicing elit. Aliquam at excepturi laudantium magnam mollitia - perferendis reprehenderit, voluptate. Cum delectus dicta ducimus eligendi excepturi natus perferendis - provident unde. Eveniet, iste, molestiae? -

-

- Lorem ipsum dolor sit amet, consectetur adipisicing elit. Aliquam at excepturi laudantium magnam mollitia - perferendis reprehenderit, voluptate. Cum delectus dicta ducimus eligendi excepturi natus perferendis - provident unde. Eveniet, iste, molestiae? -

-

- Lorem ipsum dolor sit amet, consectetur adipisicing elit. Aliquam at excepturi laudantium magnam mollitia - perferendis reprehenderit, voluptate. Cum delectus dicta ducimus eligendi excepturi natus perferendis - provident unde. Eveniet, iste, molestiae? -

-

+

Lorem ipsum dolor sit amet, consectetur adipisicing elit. Aliquam at excepturi laudantium magnam mollitia perferendis reprehenderit, voluptate. Cum delectus dicta ducimus eligendi excepturi natus perferendis provident unde. Eveniet, iste, molestiae? @@ -56,14 +77,14 @@ @@ -76,11 +97,11 @@ - + Modal with ScrollView - + @@ -146,106 +167,40 @@ - - - - - Lorem ipsum dolor sit amet, consectetur adipisicing elit. Aliquam at excepturi laudantium magnam mollitia - perferendis reprehenderit, voluptate. Cum delectus dicta + + + + Modal with Custom Height -

- Lorem ipsum dolor sit amet, consectetur adipisicing elit. Aliquam at excepturi laudantium magnam mollitia - perferendis reprehenderit, voluptate. Cum delectus dicta ducimus eligendi excepturi natus perferendis - provident unde. Eveniet, iste, molestiae? -

-

- Lorem ipsum dolor sit amet, consectetur adipisicing elit. Aliquam at excepturi laudantium magnam mollitia - perferendis reprehenderit, voluptate. Cum delectus dicta ducimus eligendi excepturi natus perferendis - provident unde. Eveniet, iste, molestiae? +

+ This modal has a custom height of 400px.

-

- Lorem ipsum dolor sit amet, consectetur adipisicing elit. Aliquam at excepturi laudantium magnam mollitia - perferendis reprehenderit, voluptate. Cum delectus dicta ducimus eligendi excepturi natus perferendis - provident unde. Eveniet, iste, molestiae? -

-

- Lorem ipsum dolor sit amet, consectetur adipisicing elit. Aliquam at excepturi laudantium magnam mollitia - perferendis reprehenderit, voluptate. Cum delectus dicta ducimus eligendi excepturi natus perferendis - provident unde. Eveniet, iste, molestiae? +

+ This modal has a custom height of 500px.

- - - - - - - - - - - - Modal Title - - - - -

- Lorem ipsum dolor sit amet, consectetur adipisicing elit. Aliquam at excepturi laudantium magnam mollitia - perferendis reprehenderit, voluptate. Cum delectus dicta ducimus eligendi excepturi natus perferendis - provident unde. Eveniet, iste, molestiae? -

- - - - - - - - - - - - -