Feat(web-twig): Introduce optional uniform appearance of Modal

Add `spirit-feature-modal-enable-uniform-dialog` feature class to enable uniform appearance of `Modal` across all breakpoints. Current mobile design is then accessible using the `isDockedOnMobile` property.
lmc-eu · Jan 9, 2024 · c5ff3bc · c5ff3bc
1 parent bb7d413
commit c5ff3bc
Show file tree

Hide file tree

Showing 6 changed files with 120 additions and 18 deletions.
diff --git a/packages/web-twig/src/Resources/components/Modal/Modal.stories.twig b/packages/web-twig/src/Resources/components/Modal/Modal.stories.twig
@@ -18,4 +18,8 @@
         {% include '@components/Modal/stories/ModalDisabledBackdropClick.twig' %}
     </DocsSection>
 
+    <DocsSection title="Feature Flag: Uniform Modal on Mobile">
+        {% include '@components/Modal/stories/ModalUniformModalOnMobile.twig' %}
+    </DocsSection>
+
 {% endblock %}
diff --git a/packages/web-twig/src/Resources/components/Modal/ModalDialog.twig b/packages/web-twig/src/Resources/components/Modal/ModalDialog.twig
@@ -1,18 +1,20 @@
 {# API #}
 {%- set props = props | default([]) -%}
 {%- set _elementType = props.elementType | default('article') -%}
+{%- set _isDockedOnMobile = props.isDockedOnMobile | default(false) -%}
 {%- set _isExpandedOnMobile = props.isExpandedOnMobile ?? true -%}
 {%- set _maxHeightFromTabletUp = props.maxHeightFromTabletUp | default(null) -%}
 {%- set _preferredHeightOnMobile = props.preferredHeightOnMobile | default(null) -%}
 {%- set _preferredHeightFromTabletUp = props.preferredHeightFromTabletUp | default(null) -%}
 
 {# Class names #}
 {%- set _rootClassName = _spiritClassPrefix ~ 'ModalDialog' -%}
+{%- set _rootDockOnMobileClassName = _isDockedOnMobile ? _spiritClassPrefix ~ 'ModalDialog--dockOnMobile' : null -%}
 {%- set _rootExpandOnMobileClassName = _isExpandedOnMobile ? _spiritClassPrefix ~ 'ModalDialog--expandOnMobile' : null -%}
 
 {# Miscellaneous #}
 {%- set _styleProps = useStyleProps(props) -%}
-{%- set _classNames = [ _rootClassName, _rootExpandOnMobileClassName, _styleProps.className ] -%}
+{%- set _classNames = [ _rootClassName, _rootDockOnMobileClassName, _rootExpandOnMobileClassName, _styleProps.className ] -%}
 {%- set _allowedAttributes = _elementType == 'form' ? [
     'accept-charset',
     'action',

diff --git a/packages/web-twig/src/Resources/components/Modal/README.md b/packages/web-twig/src/Resources/components/Modal/README.md
@@ -108,22 +108,23 @@ You can use the `maxHeightFromTabletUp` option to override the max height on tab
 
 ### 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                                          |
-| `isExpandedOnMobile`          | `bool`                        | `true`    | ✕        | If the ModalDialog should expand on mobile. Overrides any height defined by `preferredHeightOnMobile`.  |
-| `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`   | ✕        | [REQUIRES FEATURE FLAG](#feature-flag-uniform-appearance-on-all-breakpoints): Dock the ModalDialog to the bottom of the screen on mobile |
+| `isExpandedOnMobile`          | `bool`                        | `true`    | ✕        | If the ModalDialog should expand on mobile. Overrides any height defined by `preferredHeightOnMobile`.                                   |
+| `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, you can add `data-*` or `aria-*` attributes to
 further extend the component's descriptiveness and accessibility. Also, UNSAFE styling props are available,
@@ -321,6 +322,21 @@ When you put it all together:
 </Modal>
 ```
 
+## Feature Flag: Uniform Appearance on All Breakpoints
+
+The uniform appearance of modal dialog on all breakpoints is disabled by default. To enable it, either set the
+`$modal-enable-uniform-dialog` feature flag to `true` or use the `spirit-modal-enable-uniform-dialog` CSS class on any
+parent of the modal.
+
+For more info, see main [README][readme-feature-flags].
+
+### ⚠️ DEPRECATION NOTICE
+
+The uniform dialog appearance will replace current behavior in the next major release. Current mobile appearance will
+remain accessible via the `isDockedOnMobile` property.
+
+[What are deprecations?][readme-deprecations]
+
 ## JavaScript Plugin
 
 For full functionality, you need to provide Spirit JavaScript:
@@ -345,3 +361,5 @@ Or, feel free to write the controlling script yourself.
 [dictionary-alignment]: https://github.com/lmc-eu/spirit-design-system/blob/main/docs/DICTIONARIES.md#alignment
 [escape-hatches]: https://github.com/lmc-eu/spirit-design-system/tree/main/packages/web-twig/README.md#escape-hatches
 [scroll-view]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web-twig/src/Resources/components/ScrollView/README.md
+[readme-deprecations]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web-twig/README.md#deprecations
+[readme-feature-flags]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web/README.md#feature-flags
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
@@ -41,6 +41,7 @@
     <ModalDialog
         autocomplete="on"
         elementType="form"
+        isDockedOnMobile
         isExpandedOnMobile={ false }
         maxHeightFromTabletUp="700px"
         method="dialog"

diff --git a/...b-twig/src/Resources/components/Modal/__tests__/__snapshots__/modalDefault.twig.snap.html b/...b-twig/src/Resources/components/Modal/__tests__/__snapshots__/modalDefault.twig.snap.html
@@ -59,7 +59,7 @@ <h2 class="ModalHeader__title" id="modal-example-title">
     <!-- Render with all props -->
 
     <dialog class="Modal" id="modal-example-2" aria-labelledby="modal-example-2-title">
-      <form autocomplete="on" method="dialog" class="ModalDialog custom-class" style="--modal-max-height-tablet: 700px;--modal-preferred-height-mobile: 400px;--modal-preferred-height-tablet: 500px;outline: 5px solid blue; outline-offset: -5px;">
+      <form autocomplete="on" method="dialog" class="ModalDialog ModalDialog--dockOnMobile custom-class" style="--modal-max-height-tablet: 700px;--modal-preferred-height-mobile: 400px;--modal-preferred-height-tablet: 500px;outline: 5px solid blue; outline-offset: -5px;">
         <header class="ModalHeader">
           <h2 class="ModalHeader__title" id="modal-example-2-title">
             Title of the Modal

diff --git a/packages/web-twig/src/Resources/components/Modal/stories/ModalUniformModalOnMobile.twig b/packages/web-twig/src/Resources/components/Modal/stories/ModalUniformModalOnMobile.twig
@@ -0,0 +1,77 @@
+<div class="spirit-feature-modal-enable-uniform-dialog" style="display: contents"><!-- Set `display: contents` to enable parent stack layout. -->
+    <Button data-spirit-toggle="modal" data-spirit-target="#example-uniform">
+        Open Modal
+    </Button>
+
+    <Button data-spirit-toggle="modal" data-spirit-target="#example-docked">
+        Open Docked Modal (mobile only)
+    </Button>
+
+    <Modal id="example-uniform" titleId="example-uniform-title">
+        <ModalDialog>
+            <ModalHeader modalId="example-uniform" titleId="example-uniform-title">
+                Modal Title
+            </ModalHeader>
+            <ModalBody>
+
+                <!-- Content: start -->
+                <p>
+                    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?
+                </p>
+                <!-- Content: end -->
+
+            </ModalBody>
+            <ModalFooter description="Optional description">
+                <Button
+                    data-spirit-dismiss="modal"
+                    data-spirit-target="#example-uniform"
+                >
+                    Primary action
+                </Button>
+                <Button
+                    color="secondary"
+                    data-spirit-dismiss="modal"
+                    data-spirit-target="#example-uniform"
+                >
+                    Secondary action
+                </Button>
+            </ModalFooter>
+        </ModalDialog>
+    </Modal>
+
+    <Modal id="example-docked" titleId="example-docked-title">
+        <ModalDialog isDockedOnMobile>
+            <ModalHeader modalId="example-docked" titleId="example-docked-title">
+                Modal Title
+            </ModalHeader>
+            <ModalBody>
+
+                <!-- Content: start -->
+                <p>
+                    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?
+                </p>
+                <!-- Content: end -->
+
+            </ModalBody>
+            <ModalFooter description="Optional description">
+                <Button
+                    data-spirit-dismiss="modal"
+                    data-spirit-target="#example-docked"
+                >
+                    Primary action
+                </Button>
+                <Button
+                    color="secondary"
+                    data-spirit-dismiss="modal"
+                    data-spirit-target="#example-docked"
+                >
+                    Secondary action
+                </Button>
+            </ModalFooter>
+        </ModalDialog>
+    </Modal>
+</div>