Feat(web-twig): Deprecate non-flow-relative placements in Dropdown …

…#DS-1132 Use flow-relative placement values instead, e.g. `top-left` is now `top-start`.
lmc-eu · Feb 15, 2024 · 8e171ed · 8e171ed
1 parent eab44eb
commit 8e171ed
Show file tree

Hide file tree

Showing 11 changed files with 71 additions and 69 deletions.
diff --git a/packages/web-twig/src/Resources/components/Dropdown/Dropdown.twig b/packages/web-twig/src/Resources/components/Dropdown/Dropdown.twig
@@ -2,49 +2,42 @@
 {%- set props = props | default([]) -%}
 {%- set _fullWidthMode = props.fullWidthMode | default(null)  -%}
 {%- set _elementType = props.elementType | default('div') -%}
-{%- set _placement = props.placement | default('bottom-left') -%}
+{%- set _placement = props.placement | default('bottom-start') -%}
 
 {# Class names #}
 {%- set _rootClassName = _spiritClassPrefix ~ 'Dropdown' -%}
-{%- set _topClassName = _spiritClassPrefix ~ 'Dropdown--top' -%}
-{%- set _topLeftClassName = _spiritClassPrefix ~ 'Dropdown--topLeft' -%}
-{%- set _topRightClassName = _spiritClassPrefix ~ 'Dropdown--topRight' -%}
-{%- set _bottomClassName = _spiritClassPrefix ~ 'Dropdown--bottom' -%}
-{%- set _bottomLeftClassName = _spiritClassPrefix ~ 'Dropdown--bottomLeft' -%}
-{%- set _bottomRightClassName = _spiritClassPrefix ~ 'Dropdown--bottomRight' -%}
-{%- set _leftClassName = _spiritClassPrefix ~ 'Dropdown--left' -%}
-{%- set _leftTopClassName = _spiritClassPrefix ~ 'Dropdown--leftTop' -%}
-{%- set _leftBottomClassName = _spiritClassPrefix ~ 'Dropdown--leftBottom' -%}
-{%- set _rightClassName = _spiritClassPrefix ~ 'Dropdown--right' -%}
-{%- set _rightTopClassName = _spiritClassPrefix ~ 'Dropdown--rightTop' -%}
-{%- set _rightBottomClassName = _spiritClassPrefix ~ 'Dropdown--rightBottom' -%}
 
 {# Attributes #}
 {%- set _dataFullWidthModeAttr = _fullWidthMode ? 'data-spirit-fullwidthmode="' ~ _fullWidthMode | escape('html_attr') ~ '"' : null -%}
+{%- set _dataPlacementAttr = _placement ? 'data-spirit-placement="' ~ _placement | escape('html_attr') ~ '"' : null -%}
 
 {# Miscellaneous #}
 {%- set _styleProps = useStyleProps(props) -%}
-{%- set _placementClassNames = {
-    'top': _topClassName,
-    'top-left': _topLeftClassName,
-    'top-right': _topRightClassName,
-    'bottom': _bottomClassName,
-    'bottom-left': _bottomLeftClassName,
-    'bottom-right': _bottomRightClassName,
-    'left': _leftClassName,
-    'left-top': _leftTopClassName,
-    'left-bottom': _leftBottomClassName,
-    'right': _rightClassName,
-    'right-top': _rightTopClassName,
-    'right-bottom': _rightBottomClassName,
-} -%}
-{%- set _classNames = [ _rootClassName, _placementClassNames[_placement], _styleProps.className ] -%}
+{%- set _classNames = [ _rootClassName, _styleProps.className ] -%}
+{%- set _mainPropsWithoutReservedAttributes = props | filter((value, prop) => prop not in ['data-spirit-placement']) -%}
+
+{# Deprecations #}
+{% set deprecatedPlacements = {
+    'top-left': 'top-start',
+    'top-right': 'top-end',
+    'right-top': 'right-start',
+    'right-bottom': 'right-end',
+    'bottom-left': 'bottom-start',
+    'bottom-right': 'bottom-end',
+    'left-top': 'left-start',
+    'left-bottom': 'left-end',
+} %}
+
+{% if deprecatedPlacements[_placement] is defined %}
+    {% deprecated 'Dropdown: Non-flow-relative values (e.g. "' ~ _placement ~ '") of the "placement" property are deprecated and will be removed in the next major version. Use a flow-relative placement (e.g. "' ~ deprecatedPlacements[_placement] ~ '") instead.' %}
+{% endif %}
 
 <{{ _elementType }}
-    {{ mainProps(props) }}
+    {{ mainProps(_mainPropsWithoutReservedAttributes) }}
     {{ styleProp(_styleProps) }}
     {{ classProp(_classNames) }}
     {{ _dataFullWidthModeAttr | raw }}
+    {{ _dataPlacementAttr | raw }}
 >
     {%- block content %}{% endblock -%}
 </{{ _elementType }}>
diff --git a/packages/web-twig/src/Resources/components/Dropdown/README.md b/packages/web-twig/src/Resources/components/Dropdown/README.md
@@ -25,7 +25,7 @@ Advanced example usage with positioning:
 ```twig
 <DropdownWrapper>
   <Button data-spirit-toggle="dropdown" data-spirit-target="DropdownExample" aria-controls="DropdownExample" aria-expanded="false">Open Dropdown</Button>
-  <Dropdown elementType="span" id="DropdownExample" placement="top-right" fullWidthMode="all">Dropdown Content</Dropdown>
+  <Dropdown elementType="span" id="DropdownExample" placement="top-end" fullWidthMode="all">Dropdown Content</Dropdown>
 </DropdownWrapper>
 ```
 
@@ -47,17 +47,25 @@ attributes to register trigger events.
 
 ### Dropdown
 
-| Name            | Type                                         | Default       | Required | Description                           |
-| --------------- | -------------------------------------------- | ------------- | -------- | ------------------------------------- |
-| `elementType`   | `string`                                     | `div`         | ✕        | HTML tag to render                    |
-| `fullWidthMode` | `string`                                     | —             | ✕        | Full-width mode [off,mobile-only,all] |
-| `id`            | `string`                                     | —             | ✔        | Dropdown ID                           |
-| `placement`     | [Placement Dictionary][dictionary-placement] | `bottom-left` | ✕        | Placement of the dropdown             |
+| Name            | Type                                         | Default        | Required | Description                           |
+| --------------- | -------------------------------------------- | -------------- | -------- | ------------------------------------- |
+| `elementType`   | `string`                                     | `div`          | ✕        | HTML tag to render                    |
+| `fullWidthMode` | `string`                                     | —              | ✕        | Full-width mode [off,mobile-only,all] |
+| `id`            | `string`                                     | —              | ✔        | Dropdown ID                           |
+| `placement`     | [Placement Dictionary][dictionary-placement] | `bottom-start` | ✕        | Placement of the dropdown             |
 
 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]
 and [escape hatches][readme-escape-hatches].
 
+#### ⚠️ DEPRECATION NOTICE
+
+Both cross-axis placements are renamed from `top-left`, `top-right`, `right-top`, `right-bottom`,
+etc. to `top-start`, `top-end`, `right-start`, `right-end`, etc. The old names are deprecated and will be
+removed in the next major release.
+
+[What are deprecations?][readme-deprecations]
+
 ### Trigger attributes
 
 | Name                 | Type     | Default    | Required | Description                |
@@ -98,6 +106,7 @@ Or, feel free to write the controlling script yourself.
 [dropdown]: https://github.com/lmc-eu/spirit-design-system/tree/main/packages/web/src/scss/components/Dropdown
 [item]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web-twig/src/Resources/components/Item/README.md
 [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/tree/main/packages/web-twig/README.md#deprecations
 [readme-style-props]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web-twig/README.md#style-props
 [readme-escape-hatches]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web-twig/README.md#escape-hatches
 [web-js-api]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web/src/scss/components/Dropdown/README.md#javascript

diff --git a/packages/web-twig/src/Resources/components/Dropdown/__tests__/__fixtures__/dropdown.twig b/packages/web-twig/src/Resources/components/Dropdown/__tests__/__fixtures__/dropdown.twig
@@ -5,7 +5,7 @@
     elementType="aside"
     fullWidthMode="mobile-only"
     id="my-dropdown"
-    placement="top-right"
+    placement="top-end"
 >
     content
 </Dropdown>
diff --git a/...eb-twig/src/Resources/components/Dropdown/__tests__/__snapshots__/dropdown.twig.snap.html b/...eb-twig/src/Resources/components/Dropdown/__tests__/__snapshots__/dropdown.twig.snap.html
@@ -5,12 +5,12 @@
     </title>
   </head>
   <body>
-    <div class="Dropdown Dropdown--bottomLeft">
+    <div class="Dropdown" data-spirit-placement="bottom-start">
       content
     </div>
     <!-- Render with all props -->
 
-    <aside id="my-dropdown" class="Dropdown Dropdown--topRight" data-spirit-fullwidthmode="mobile-only">
+    <aside id="my-dropdown" class="Dropdown" data-spirit-fullwidthmode="mobile-only" data-spirit-placement="top-end">
       content
     </aside>
   </body>

diff --git a/packages/web-twig/src/Resources/components/Dropdown/stories/DropdownDisabledAutoclose.twig b/packages/web-twig/src/Resources/components/Dropdown/stories/DropdownDisabledAutoclose.twig
@@ -1,12 +1,12 @@
 <DropdownWrapper>
     <Button
         data-spirit-toggle="dropdown"
-        data-spirit-target="#dropdownDisabledAutoClose"
+        data-spirit-target="#dropdown-disabled-auto-close"
         data-spirit-autoclose="true"
     >
         Button as anchor
     </Button>
-    <Dropdown id="dropdownDisabledAutoClose">
+    <Dropdown id="dropdown-disabled-auto-close">
         <Item elementType="a" href="#" iconName="info" label="Information" />
         <Item elementType="a" href="#" iconName="link" label="Bibendum aliquam, fusce integer sit amet congue non nulla aliquet enim" />
         <Item elementType="a" href="#" iconName="profile" label="Profile" />

diff --git a/...ges/web-twig/src/Resources/components/Dropdown/stories/DropdownFeatureEnhancedShadow.twig b/...ges/web-twig/src/Resources/components/Dropdown/stories/DropdownFeatureEnhancedShadow.twig
@@ -2,11 +2,11 @@
     <DropdownWrapper>
         <Button
             data-spirit-toggle="dropdown"
-            data-spirit-target="#dropdownEnhancedShadow"
+            data-spirit-target="#dropdown-enhanced-shadow"
         >
             Finibus quis imperdiet, semper imperdiet aliquam
         </Button>
-        <Dropdown id="dropdownEnhancedShadow" placement="top-left">
+        <Dropdown id="dropdown-enhanced-shadow" placement="top-start">
             <Item elementType="a" href="#" iconName="info" label="Information" />
             <Item elementType="a" href="#" iconName="link" label="Bibendum aliquam, fusce integer sit amet congue non nulla aliquet enim" />
             <Item elementType="a" href="#" iconName="profile" label="Profile" />

diff --git a/packages/web-twig/src/Resources/components/Dropdown/stories/DropdownFullwidthAll.twig b/packages/web-twig/src/Resources/components/Dropdown/stories/DropdownFullwidthAll.twig
@@ -1,11 +1,11 @@
 <DropdownWrapper>
     <Button
         data-spirit-toggle="dropdown"
-        data-spirit-target="#dropdownFullWidthModeAll"
+        data-spirit-target="#dropdown-full-width-mode-all"
     >
         Finibus quis imperdiet, semper imperdiet aliquam
     </Button>
-    <Dropdown id="dropdownFullWidthModeAll" fullWidthMode="all" placement="top-left">
+    <Dropdown id="dropdown-full-width-mode-all" fullWidthMode="all" placement="top-start">
         <Item elementType="a" href="#" iconName="info" label="Information" />
         <Item elementType="a" href="#" iconName="link" label="Bibendum aliquam, fusce integer sit amet congue non nulla aliquet enim" />
         <Item elementType="a" href="#" iconName="profile" label="Profile" />

diff --git a/packages/web-twig/src/Resources/components/Dropdown/stories/DropdownFullwidthMobileOnly.twig b/packages/web-twig/src/Resources/components/Dropdown/stories/DropdownFullwidthMobileOnly.twig
@@ -1,11 +1,11 @@
 <DropdownWrapper>
     <Button
         data-spirit-toggle="dropdown"
-        data-spirit-target="#dropdownFullWidthModeMobile"
+        data-spirit-target="#dropdown-full-width-mode-mobile"
     >
         Finibus quis imperdiet, semper imperdiet aliquam
     </Button>
-    <Dropdown id="dropdownFullWidthModeMobile" fullWidthMode="mobile-only" placement="top-left">
+    <Dropdown id="dropdown-full-width-mode-mobile" fullWidthMode="mobile-only" placement="top-start">
         <Item elementType="a" href="#" iconName="info" label="Information" />
         <Item elementType="a" href="#" iconName="link" label="Bibendum aliquam, fusce integer sit amet congue non nulla aliquet enim" />
         <Item elementType="a" href="#" iconName="profile" label="Profile" />

diff --git a/packages/web-twig/src/Resources/components/Dropdown/stories/DropdownLongerContent.twig b/packages/web-twig/src/Resources/components/Dropdown/stories/DropdownLongerContent.twig
@@ -1,11 +1,11 @@
 <DropdownWrapper>
     <Button
         data-spirit-toggle="dropdown"
-        data-spirit-target="#dropdownLonger"
+        data-spirit-target="#dropdown-longer"
     >
         Button as anchor
     </Button>
-    <Dropdown id="dropdownLonger">
+    <Dropdown id="dropdown-longer">
         <Item elementType="a" href="#" iconName="info" label="Bibendum aliquam, fusce integer sit amet congue non nulla aliquet enim" />
         <Item elementType="a" href="#" iconName="link" label="Nulla condimentum, purus commodo cursus non nulla rhoncus" />
         <Item elementType="a" href="#" iconName="profile" label="Mauris nunc, elementum enim in lacinia vitae quam placerat sem, euismod accumsan" />

diff --git a/packages/web-twig/src/Resources/components/Dropdown/stories/DropdownPlacements.twig b/packages/web-twig/src/Resources/components/Dropdown/stories/DropdownPlacements.twig
@@ -2,43 +2,43 @@
     <Grid cols="3" marginX="auto" UNSAFE_style="align-items: center; justify-items: center; max-width: 40rem;">
         <GridItem columnStart="2" rowStart="1">
 
-            <Radio name="placement" isLabelHidden value="topLeft" id="placement_top_left" label="top-left"/>
-            <Radio name="placement" isLabelHidden value="top" id="placement_top" label="top"/>
-            <Radio name="placement" isLabelHidden value="topRight" id="placement_top_right" label="top-right"/>
+            <Radio name="placement" isLabelHidden value="top-start" id="placement-top-start" label="top-start"/>
+            <Radio name="placement" isLabelHidden value="top" id="placement-top" label="top"/>
+            <Radio name="placement" isLabelHidden value="top-end" id="placement-top-end" label="top-end"/>
 
         </GridItem>
         <GridItem columnStart="2" rowStart="3">
 
-            <Radio name="placement" isLabelHidden value="bottomLeft" id="placement_bottom_left" label="bottom-left" isChecked />
-            <Radio name="placement" isLabelHidden value="bottom" id="placement_bottom" label="bottom" />
-            <Radio name="placement" isLabelHidden value="bottomRight" id="placement_bottom_right" label="bottom-right"/>
+            <Radio name="placement" isLabelHidden value="bottom-start" id="placement-bottom-start" label="bottom-start" isChecked />
+            <Radio name="placement" isLabelHidden value="bottom" id="placement-bottom" label="bottom" />
+            <Radio name="placement" isLabelHidden value="bottom-end" id="placement-bottom-end" label="bottom-end"/>
 
         </GridItem>
         <GridItem columnStart="1" rowStart="2" UNSAFE_style="display: flex; flex-direction: column; justify-self: start;">
 
-            <Radio name="placement" isLabelHidden value="leftTop" id="placement_left_top" label="left-top"/>
-            <Radio name="placement" isLabelHidden value="left" id="placement_left" label="left"/>
-            <Radio name="placement" isLabelHidden value="leftBottom" id="placement_left_bottom" label="left-bottom"/>
+            <Radio name="placement" isLabelHidden value="left-start" id="placement-left-start" label="left-start"/>
+            <Radio name="placement" isLabelHidden value="left" id="placement-left" label="left"/>
+            <Radio name="placement" isLabelHidden value="left-end" id="placement-left-end" label="left-end"/>
 
         </GridItem>
         <GridItem columnStart="3" rowStart="2" UNSAFE_style="display: flex; flex-direction: column; justify-self: end;">
 
-            <Radio name="placement" isLabelHidden value="rightTop" id="placement_right_top" label="right-top"/>
-            <Radio name="placement" isLabelHidden value="right" id="placement_right" label="right"/>
-            <Radio name="placement" isLabelHidden value="rightBottom" id="placement_right_bottom" label="right-bottom"/>
+            <Radio name="placement" isLabelHidden value="right-start" id="placement-right-start" label="right-start"/>
+            <Radio name="placement" isLabelHidden value="right" id="placement-right" label="right"/>
+            <Radio name="placement" isLabelHidden value="right-end" id="placement-right-end" label="right-end"/>
 
         </GridItem>
         <GridItem columnStart="2" rowStart="2">
 
             <DropdownWrapper UNSAFE_style="margin: 8rem auto">
                 <Button
                     data-spirit-toggle="dropdown"
-                    data-spirit-target="#dropdown_placements_example"
+                    data-spirit-target="#dropdown-placements-example"
                     data-spirit-autoclose="false"
                 >
-                    <span id="dropdown_placements_example_text" style="white-space: nowrap">bottom-left</span>
+                    <span id="dropdown-placements-example-text" style="white-space: nowrap">bottom-left</span>
                 </Button>
-                <Dropdown id="dropdown_placements_example">
+                <Dropdown id="dropdown-placements-example">
                     <Item elementType="a" href="#" label="Action" />
                     <Item elementType="a" href="#" label="Another action" />
                     <Item elementType="a" href="#" label="Something else here" />
@@ -55,10 +55,10 @@
     radios.forEach(radio => {
         radio.addEventListener('change', () => {
             const placement = radio.value;
-            const dropdown = document.getElementById('dropdown_placements_example');
-            const placementText = document.getElementById('dropdown_placements_example_text');
+            const dropdown = document.getElementById('dropdown-placements-example');
+            const placementText = document.getElementById('dropdown-placements-example-text');
 
-            dropdown.classList.replace(dropdown.classList[1], `Dropdown--${placement}`);
+            dropdown.dataset.spiritPlacement = placement;
             placementText.textContent = placement.split(/(?=[A-Z])/).join('-').toLowerCase();
         });
     });

diff --git a/packages/web-twig/src/Resources/components/Dropdown/stories/DropdownVariousItems.twig b/packages/web-twig/src/Resources/components/Dropdown/stories/DropdownVariousItems.twig
@@ -1,11 +1,11 @@
 <DropdownWrapper>
     <Button
         data-spirit-toggle="dropdown"
-        data-spirit-target="#dropdownVariousItems"
+        data-spirit-target="#dropdown-various-items"
     >
         Button as anchor
     </Button>
-    <Dropdown id="dropdownVariousItems">
+    <Dropdown id="dropdown-various-items">
         <Item elementType="a" href="#" label="Plain text" />
         <Item elementType="a" href="#" iconName="info" label="Item with icon" />
         <Checkbox id="checkbox-item" name="checkbox-item" label="Item with checkbox" isItem />