From 6b3a134bda1fff17b74d8132d545f83fb56aaef1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jan=20Kry=C5=A1p=C3=ADn?= <crishpeen@gmail.com>
Date: Thu, 8 Feb 2024 15:02:04 +0100
Subject: [PATCH] Feat(web): Deprecate Dropdown non flow and modifier placement
 DS-1132

Use data attribute to set the placement now.
Use flow placement values, e.g. `top-left` is now `top-start`.
---
 .../src/scss/components/Dropdown/README.md    |  65 ++++++----
 .../src/scss/components/Dropdown/index.html   | 117 +++++++++---------
 .../web/src/scss/components/Item/README.md    |   2 +-
 3 files changed, 104 insertions(+), 80 deletions(-)

diff --git a/packages/web/src/scss/components/Dropdown/README.md b/packages/web/src/scss/components/Dropdown/README.md
index 52dc2f1240..f78760398d 100644
--- a/packages/web/src/scss/components/Dropdown/README.md
+++ b/packages/web/src/scss/components/Dropdown/README.md
@@ -6,14 +6,14 @@
 <div class="DropdownWrapper">
   <button
     data-spirit-toggle="dropdown"
-    data-spirit-target="#dropdownDefault"
+    data-spirit-target="#dropdown-default"
     class="Button Button--primary Button--medium"
     aria-expanded="false"
-    aria-controls="#dropdownDefault"
+    aria-controls="dropdown-default"
   >
     Button as anchor
   </button>
-  <div class="Dropdown Dropdown--bottomLeft" id="dropdownDefault">
+  <div class="Dropdown" data-spirit-placement="bottom-start" id="dropdown-default">
     <a href="#" class="d-flex mb-400">
       <svg width="24" height="24" aria-hidden="true" class="mr-400">
         <use xlink:href="/icons/svg/sprite.svg#info" />
@@ -42,20 +42,20 @@
 </div>
 ```
 
-## Usage with top-right align
+## Usage with top-end align
 
 ```html
 <div class="DropdownWrapper">
   <button
     data-spirit-toggle="dropdown"
-    data-spirit-target="#dropdownTopRight"
+    data-spirit-target="#dropdown-top-end"
     class="Button Button--primary Button--medium"
     aria-expanded="false"
-    aria-controls="#dropdownTopRight"
+    aria-controls="dropdown-top-end"
   >
     Button as anchor
   </button>
-  <div class="Dropdown Dropdown--topRight" id="dropdownTopRight">
+  <div class="Dropdown" data-spirit-placement="top-end" id="dropdown-top-end">
     <a href="#" class="d-flex mb-400">
       <svg width="24" height="24" aria-hidden="true" class="mr-400">
         <use xlink:href="/icons/svg/sprite.svg#info" />
@@ -90,15 +90,15 @@
 <div class="DropdownWrapper">
   <button
     data-spirit-toggle="dropdown"
-    data-spirit-target="#dropdownDisabledAutoClose"
+    data-spirit-target="#dropdown-disabled-auto-close"
     class="Button Button--primary Button--medium"
     aria-expanded="false"
-    aria-controls="#dropdownDisabledAutoClose"
+    aria-controls="dropdown-disabled-auto-close"
     data-spirit-autoclose="true"
   >
     Button as anchor
   </button>
-  <div class="Dropdown Dropdown--bottomLeft" id="dropdownDisabledAutoClose">
+  <div class="Dropdown" data-spirit-placement="bottom-start" id="dropdown-disabled-auto-close">
     <a href="#" class="d-flex mb-400">
       <svg width="24" height="24" aria-hidden="true" class="mr-400">
         <use xlink:href="/icons/svg/sprite.svg#info" />
@@ -133,14 +133,19 @@
 <div class="DropdownWrapper">
   <button
     data-spirit-toggle="dropdown"
-    data-spirit-target="#dropdownFullWidthModeAll"
+    data-spirit-target="#dropdown-full-width-mode-all"
     class="Button Button--primary Button--medium"
     aria-expanded="false"
-    aria-controls="#dropdownFullWidthModeAll"
+    aria-controls="dropdown-full-width-mode-all"
   >
     Finibus quis imperdiet, semper imperdiet aliquam
   </button>
-  <div class="Dropdown Dropdown--topLeft" id="dropdownFullWidthModeAll" data-spirit-fullwidthmode="all">
+  <div
+    class="Dropdown"
+    data-spirit-placement="top-start"
+    id="dropdown-full-width-mode-all"
+    data-spirit-fullwidthmode="all"
+  >
     <a href="#" class="d-flex mb-400">
       <svg width="24" height="24" aria-hidden="true" class="mr-400">
         <use xlink:href="/icons/svg/sprite.svg#info" />
@@ -175,14 +180,19 @@
 <div class="DropdownWrapper">
   <button
     data-spirit-toggle="dropdown"
-    data-spirit-target="#dropdownFullWidthModeMobile"
+    data-spirit-target="#dropdown-full-width-mode-mobile"
     class="Button Button--primary Button--medium"
     aria-expanded="false"
-    aria-controls="#dropdownFullWidthModeMobile"
+    aria-controls="dropdown-full-width-mode-mobile"
   >
     Finibus quis imperdiet, semper imperdiet aliquam
   </button>
-  <div class="Dropdown Dropdown--topLeft" id="dropdownFullWidthModeMobile" data-spirit-fullwidthmode="mobile-only">
+  <div
+    class="Dropdown"
+    data-spirit-placement="top-start"
+    id="dropdown-full-width-mode-mobile"
+    data-spirit-fullwidthmode="mobile-only"
+  >
     <a href="#" class="d-flex mb-400">
       <svg width="24" height="24" aria-hidden="true" class="mr-400">
         <use xlink:href="/icons/svg/sprite.svg#info" />
@@ -217,14 +227,14 @@
 <div class="DropdownWrapper">
   <button
     data-spirit-toggle="dropdown"
-    data-spirit-target="#dropdownDefault"
+    data-spirit-target="#dropdown-default"
     class="Button Button--primary Button--medium"
     aria-expanded="false"
-    aria-controls="#dropdownDefault"
+    aria-controls="dropdown-default"
   >
     Button as anchor
   </button>
-  <div class="Dropdown Dropdown--bottomLeft" id="dropdownDefault">
+  <div class="Dropdown" data-spirit-placement="bottom-start" id="dropdown-default">
     <a href="#" class="Item">
       <span class="Item__icon Item__icon--start">
         <svg width="24" height="24" aria-hidden="true">
@@ -239,14 +249,27 @@
 
 ## Placement
 
-Dropdown implements the [Placement Dictionary][dictionary-placement] for placement. The dictionary values are used as CSS
-modifiers in the camelCase format: `Dropdown--top`, `Dropdown--rightTop`, `Dropdown--leftBottom`, etc.
+Dropdown implements the [Placement Dictionary][dictionary-placement] for placement. The dictionary values are used as
+a value of data attribute `data-spirit-placement`, e.g. `data-spirit-placement="top"`, `data-spirit-placement="right-end"`, etc.
 
 ### ⚠️ DEPRECATION NOTICE
 
 Current class combinations (`Dropdown--top.Dropdown--left`, `.Dropdown--top.Dropdown--right`,
 `.Dropdown--bottom.Dropdown--left`, `.Dropdown--bottom.Dropdown--right`) will be removed in the next major release.
 
+[What are deprecations?][readme-deprecations]
+
+### ⚠️ DEPRECATION NOTICE
+
+CSS modifiers `Dropdown--top`, `Dropdown--rightTop`, `Dropdown--bottom`, etc. are deprecated and will be
+removed in the next major release. Use `data-spirit-placement` attribute instead.
+
+Also, all cross-axis placements have been 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]
+
 ## Feature Flag: Enhanced Shadow
 
 The enhanced shadow feature is disabled by default. To enable it, either set the `$dropdown-enable-enhanced-shadow`
diff --git a/packages/web/src/scss/components/Dropdown/index.html b/packages/web/src/scss/components/Dropdown/index.html
index f57c51ba01..e8365b12c3 100644
--- a/packages/web/src/scss/components/Dropdown/index.html
+++ b/packages/web/src/scss/components/Dropdown/index.html
@@ -9,44 +9,44 @@ <h2 class="docs-Heading">Placements</h2>
         <div class="Grid Grid--cols-3 mx-auto" style="align-items: center; justify-items: center; max-width: 40rem;">
           <div class="GridItem" style="--grid-item-column-start: 2; --grid-item-row-start: 1">
 
-            <label for="placement_top_left" class="Radio">
-              <input type="radio" name="placement" value="topLeft" id="placement_top_left" class="Radio__input" />
+            <label for="placement-top-start" class="Radio">
+              <input type="radio" name="placement" value="top-start" id="placement-top-start" class="Radio__input" />
               <span class="Radio__text">
-                <span class="Radio__label Radio__label--hidden">top-left</span>
+                <span class="Radio__label Radio__label--hidden">top-start</span>
               </span>
             </label>
-            <label for="placement_top" class="Radio">
-              <input type="radio" name="placement" value="top" id="placement_top" class="Radio__input" />
+            <label for="placement-top" class="Radio">
+              <input type="radio" name="placement" value="top" id="placement-top" class="Radio__input" />
               <span class="Radio__text">
                 <span class="Radio__label Radio__label--hidden">top</span>
               </span>
             </label>
-            <label for="placement_top_right" class="Radio">
-              <input type="radio" name="placement" value="topRight" id="placement_top_right" class="Radio__input" />
+            <label for="placement-top-end" class="Radio">
+              <input type="radio" name="placement" value="top-end" id="placement-top-end" class="Radio__input" />
               <span class="Radio__text">
-                <span class="Radio__label Radio__label--hidden">top-right</span>
+                <span class="Radio__label Radio__label--hidden">top-end</span>
               </span>
             </label>
 
           </div>
           <div class="GridItem" style="--grid-item-column-start: 2; --grid-item-row-start: 3">
 
-            <label for="placement_bottom_left" class="Radio">
-              <input type="radio" name="placement" value="bottomLeft" id="placement_bottom_left" class="Radio__input" checked />
+            <label for="placement-bottom-start" class="Radio">
+              <input type="radio" name="placement" value="bottom-start" id="placement-bottom-start" class="Radio__input" checked />
               <span class="Radio__text">
-                <span class="Radio__label Radio__label--hidden">bottom-left</span>
+                <span class="Radio__label Radio__label--hidden">bottom-start</span>
               </span>
             </label>
-            <label for="placement_bottom" class="Radio">
-              <input type="radio" name="placement" value="bottom" id="placement_bottom" class="Radio__input" />
+            <label for="placement-bottom" class="Radio">
+              <input type="radio" name="placement" value="bottom" id="placement-bottom" class="Radio__input" />
               <span class="Radio__text">
                 <span class="Radio__label Radio__label--hidden">bottom</span>
               </span>
             </label>
-            <label for="placement_bottom_right" class="Radio">
-              <input type="radio" name="placement" value="bottomRight" id="placement_bottom_right" class="Radio__input" />
+            <label for="placement-bottom-end" class="Radio">
+              <input type="radio" name="placement" value="bottom-end" id="placement-bottom-end" class="Radio__input" />
               <span class="Radio__text">
-                <span class="Radio__label Radio__label--hidden">bottom-right</span>
+                <span class="Radio__label Radio__label--hidden">bottom-end</span>
               </span>
             </label>
 
@@ -62,22 +62,22 @@ <h2 class="docs-Heading">Placements</h2>
             "
           >
 
-            <label for="placement_left_top" class="Radio">
-              <input type="radio" name="placement" value="leftTop" id="placement_left_top" class="Radio__input" />
+            <label for="placement-left-start" class="Radio">
+              <input type="radio" name="placement" value="left-start" id="placement-left-start" class="Radio__input" />
               <span class="Radio__text">
-                <span class="Radio__label Radio__label--hidden">left-top</span>
+                <span class="Radio__label Radio__label--hidden">left-start</span>
               </span>
             </label>
-            <label for="placement_left" class="Radio">
-              <input type="radio" name="placement" value="left" id="placement_left" class="Radio__input" />
+            <label for="placement-left" class="Radio">
+              <input type="radio" name="placement" value="left" id="placement-left" class="Radio__input" />
               <span class="Radio__text">
                 <span class="Radio__label Radio__label--hidden">left</span>
               </span>
             </label>
-            <label for="placement_left_bottom" class="Radio">
-              <input type="radio" name="placement" value="leftBottom" id="placement_left_bottom" class="Radio__input" />
+            <label for="placement-left-end" class="Radio">
+              <input type="radio" name="placement" value="left-end" id="placement-left-end" class="Radio__input" />
               <span class="Radio__text">
-                <span class="Radio__label Radio__label--hidden">left-bottom</span>
+                <span class="Radio__label Radio__label--hidden">left-end</span>
               </span>
             </label>
 
@@ -93,22 +93,22 @@ <h2 class="docs-Heading">Placements</h2>
             "
           >
 
-            <label for="placement_right_top" class="Radio">
-              <input type="radio" name="placement" value="rightTop" id="placement_right_top" class="Radio__input" />
+            <label for="placement-right-start" class="Radio">
+              <input type="radio" name="placement" value="right-start" id="placement-right-start" class="Radio__input" />
               <span class="Radio__text">
-                <span class="Radio__label Radio__label--hidden">right-top</span>
+                <span class="Radio__label Radio__label--hidden">right-start</span>
               </span>
             </label>
-            <label for="placement_right" class="Radio">
-              <input type="radio" name="placement" value="right" id="placement_right" class="Radio__input" />
+            <label for="placement-right" class="Radio">
+              <input type="radio" name="placement" value="right" id="placement-right" class="Radio__input" />
               <span class="Radio__text">
                 <span class="Radio__label Radio__label--hidden">right</span>
               </span>
             </label>
-            <label for="placement_right_bottom" class="Radio">
-              <input type="radio" name="placement" value="rightBottom" id="placement_right_bottom" class="Radio__input" />
+            <label for="placement-right-end" class="Radio">
+              <input type="radio" name="placement" value="right-end" id="placement-right-end" class="Radio__input" />
               <span class="Radio__text">
-                <span class="Radio__label Radio__label--hidden">right-bottom</span>
+                <span class="Radio__label Radio__label--hidden">right-end</span>
               </span>
             </label>
 
@@ -119,15 +119,15 @@ <h2 class="docs-Heading">Placements</h2>
               <button
                 type="button"
                 data-spirit-toggle="dropdown"
-                data-spirit-target="#dropdown_placements_example"
+                data-spirit-target="#dropdown-placements-example"
                 data-spirit-autoclose="false"
                 class="Button Button--primary Button--medium"
                 aria-expanded="false"
-                aria-controls="#dropdown_placements_example"
+                aria-controls="dropdown-placements-example"
               >
-                <span id="dropdown_placements_example_text" style="white-space: nowrap">bottom-left</span>
+                <span id="dropdown-placements-example-text" style="white-space: nowrap">bottom-start</span>
               </button>
-              <div class="Dropdown Dropdown--bottomLeft" id="dropdown_placements_example">
+              <div class="Dropdown" data-spirit-placement="bottom-start" id="dropdown-placements-example">
                 <a href="#" class="Item">
                   <span class="Item__label">Action</span>
                 </a>
@@ -150,10 +150,10 @@ <h2 class="docs-Heading">Placements</h2>
         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();
           });
         });
@@ -171,15 +171,15 @@ <h2 class="docs-Heading">Various items</h2>
         <button
           type="button"
           data-spirit-toggle="dropdown"
-          data-spirit-target="#dropdownVariousItems"
+          data-spirit-target="#dropdown-various-items"
           class="Button Button--primary Button--medium"
           aria-expanded="false"
-          aria-controls="#dropdownVariousItems"
+          aria-controls="dropdown-various-items"
           data-spirit-autoclose="true"
         >
           Button as anchor
         </button>
-        <div class="Dropdown Dropdown--bottomLeft" id="dropdownVariousItems">
+        <div class="Dropdown" data-spirit-placement="bottom-start" id="dropdown-various-items">
           <a href="#" class="Item">
             <span class="Item__label">Plain text</span>
           </a>
@@ -216,15 +216,15 @@ <h2 class="docs-Heading">Usage with disabled auto close</h2>
         <button
           type="button"
           data-spirit-toggle="dropdown"
-          data-spirit-target="#dropdownDisabledAutoClose"
+          data-spirit-target="#dropdown-disabled-auto-close"
           class="Button Button--primary Button--medium"
           aria-expanded="false"
-          aria-controls="#dropdownDisabledAutoClose"
+          aria-controls="dropdown-disabled-auto-close"
           data-spirit-autoclose="true"
         >
           Button as anchor
         </button>
-        <div class="Dropdown Dropdown--bottomLeft" id="dropdownDisabledAutoClose">
+        <div class="Dropdown" data-spirit-placement="bottom-start" id="dropdown-disabled-auto-close">
           <a href="#" class="Item">
             <span class="Item__icon Item__icon--start">
               <svg width="24" height="24" aria-hidden="true">
@@ -272,14 +272,14 @@ <h2 class="docs-Heading">Longer content</h2>
         <button
           type="button"
           data-spirit-toggle="dropdown"
-          data-spirit-target="#dropdownLonger"
+          data-spirit-target="#dropdown-longer"
           class="Button Button--primary Button--medium"
           aria-expanded="false"
-          aria-controls="#dropdownLonger"
+          aria-controls="dropdown-longer"
         >
           Button as anchor
         </button>
-        <div class="Dropdown Dropdown--bottomLeft" id="dropdownLonger">
+        <div class="Dropdown" data-spirit-placement="bottom-start" id="dropdown-longer">
           <a href="#" class="Item">
             <span class="Item__icon Item__icon--start">
               <svg width="24" height="24" aria-hidden="true">
@@ -327,14 +327,14 @@ <h2 class="docs-Heading">Full-width mode 'all'</h2>
         <button
           type="button"
           data-spirit-toggle="dropdown"
-          data-spirit-target="#dropdownFullWidthModeAll"
+          data-spirit-target="#dropdown-full-width-mode-all"
           class="Button Button--primary Button--medium"
           aria-expanded="false"
-          aria-controls="#dropdownFullWidthModeAll"
+          aria-controls="dropdown-full-width-mode-all"
         >
           Finibus quis imperdiet, semper imperdiet aliquam
         </button>
-        <div class="Dropdown Dropdown--top Dropdown--left" id="dropdownFullWidthModeAll" data-spirit-fullwidthmode="all">
+        <div class="Dropdown" data-spirit-placement="top-start" id="dropdown-full-width-mode-all" data-spirit-fullwidthmode="all">
           <a href="#" class="Item">
             <span class="Item__icon Item__icon--start">
               <svg width="24" height="24" aria-hidden="true">
@@ -382,16 +382,17 @@ <h2 class="docs-Heading">Full-width mode 'mobile-only'</h2>
         <button
           type="button"
           data-spirit-toggle="dropdown"
-          data-spirit-target="#dropdownFullWidthModeMobile"
+          data-spirit-target="#dropdown-full-width-mode-mobile"
           class="Button Button--primary Button--medium"
           aria-expanded="false"
-          aria-controls="#dropdownFullWidthModeMobile"
+          aria-controls="dropdown-full-width-mode-mobile"
         >
           Finibus quis imperdiet, semper imperdiet aliquam
         </button>
         <div
-          class="Dropdown Dropdown--top Dropdown--left"
-          id="dropdownFullWidthModeMobile"
+          class="Dropdown"
+          id="dropdown-full-width-mode-mobile"
+          data-spirit-placement="top-start"
           data-spirit-fullwidthmode="mobile-only"
         >
           <a href="#" class="Item">
@@ -442,14 +443,14 @@ <h2 class="docs-Heading">Feature Flag: Enhanced Shadow</h2>
           <button
             type="button"
             data-spirit-toggle="dropdown"
-            data-spirit-target="#dropdownEnhancedShadow"
+            data-spirit-target="#dropdown-enhanced-shadow"
             class="Button Button--primary Button--medium"
             aria-expanded="false"
-            aria-controls="#dropdownEnhancedShadow"
+            aria-controls="dropdown-enhanced-shadow"
           >
             Finibus quis imperdiet, semper imperdiet aliquam
           </button>
-          <div class="Dropdown Dropdown--top Dropdown--left" id="dropdownEnhancedShadow">
+          <div class="Dropdown" data-spirit-placement="top-start"  id="dropdown-enhanced-shadow">
             <a href="#" class="Item">
               <span class="Item__icon Item__icon--start">
                 <svg width="24" height="24" aria-hidden="true">
diff --git a/packages/web/src/scss/components/Item/README.md b/packages/web/src/scss/components/Item/README.md
index ac7e1e7976..e963e01c1a 100644
--- a/packages/web/src/scss/components/Item/README.md
+++ b/packages/web/src/scss/components/Item/README.md
@@ -117,7 +117,7 @@ Usage in [Dropdown] component:
   >
     Button as anchor
   </button>
-  <div class="Dropdown Dropdown--bottomLeft" id="dropdownDefault">
+  <div class="Dropdown" id="dropdownDefault" data-spirit-placement="bottom-start">
     <a href="#" class="Item">
       <span class="Item__icon Item__icon--start">
         <svg width="24" height="24" aria-hidden="true">