Feat(web): Introduce Placement dictionary and use it in Dropdown and Tooltip #DS-923

docs/DICTIONARIES.md

@@ -7,19 +7,19 @@ This project uses `dictionaries` to unify props between different components.
 - A given property is not a dictionary by itself. The property is contained in the dictionary. That is, the Action Primary Default color is contained in the Action Primary dictionary entry.
 - Products can extend their dictionaries.
 
-## List of dictionaries
+## List of Dictionaries
 
-- [Size](#size)
+- [Alignment](#alignment)
 - [Color](#color)
+- [Placement](#placement)
+- [Size](#size)
 - [Validation](#validation)
-- [Alignment](#alignment)
 
-### Size
+### Alignment
 
-| Dictionary    | Values                               | Code name    |
-| ------------- | ------------------------------------ | ------------ |
-| Size          | `small`, `medium`, `large`           | Size         |
-| Size Extended | Size Dictionary + `xsmall`, `xlarge` | SizeExtended |
+| Dictionary | Values                    | Code name  |
+| ---------- | ------------------------- | ---------- |
+| AlignmentX | `left`, `center`, `right` | AlignmentX |
 
 ### Color
 
@@ -30,14 +30,21 @@ This project uses `dictionaries` to unify props between different components.
 | Emotion Color     | `success`, `informative`, `warning`, `danger`                    | EmotionColor    |
 | Text Color        | `primary`, `secondary`, `primary-inverted`, `secondary-inverted` | TextColor       |
 
+### Placement
+
+| Dictionary | Values                                                                                                                                           | Code name |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | --------- |
+| Placement  | `top`, `top-left`, `top-right`, `bottom`, `bottom-left`, `bottom-right`, `left`, `left-top`, `left-bottom`, `right`, `right-top`, `right-bottom` | Placement |
+
+### Size
+
+| Dictionary    | Values                               | Code name    |
+| ------------- | ------------------------------------ | ------------ |
+| Size          | `small`, `medium`, `large`           | Size         |
+| Size Extended | Size Dictionary + `xsmall`, `xlarge` | SizeExtended |
+
 ### Validation
 
 | Dictionary | Values                         | Code name  |
 | ---------- | ------------------------------ | ---------- |
 | Validation | `success`, `warning`, `danger` | Validation |
-
-### Alignment
-
-| Dictionary | Values                    | Code name  |
-| ---------- | ------------------------- | ---------- |
-| AlignmentX | `left`, `center`, `right` | AlignmentX |

packages/web/src/scss/components/Dropdown/README.md

@@ -13,7 +13,7 @@
   >
     Button as anchor
   </button>
-  <div class="Dropdown Dropdown--bottom Dropdown--left" id="dropdownDefault">
+  <div class="Dropdown Dropdown--bottomLeft" id="dropdownDefault">
     <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" />
@@ -55,7 +55,7 @@
   >
     Button as anchor
   </button>
-  <div class="Dropdown Dropdown--top Dropdown--right" id="dropdownTopRight">
+  <div class="Dropdown Dropdown--topRight" id="dropdownTopRight">
     <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" />
@@ -98,7 +98,7 @@
   >
     Button as anchor
   </button>
-  <div class="Dropdown Dropdown--bottom Dropdown--left" id="dropdownDisabledAutoClose">
+  <div class="Dropdown Dropdown--bottomLeft" id="dropdownDisabledAutoClose">
     <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" />
@@ -140,7 +140,7 @@
   >
     Finibus quis imperdiet, semper imperdiet aliquam
   </button>
-  <div class="Dropdown Dropdown--top Dropdown--left" id="dropdownFullWidthModeAll" data-spirit-fullwidthmode="all">
+  <div class="Dropdown Dropdown--topLeft" id="dropdownFullWidthModeAll" 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" />
@@ -182,11 +182,7 @@
   >
     Finibus quis imperdiet, semper imperdiet aliquam
   </button>
-  <div
-    class="Dropdown Dropdown--top Dropdown--left"
-    id="dropdownFullWidthModeMobile"
-    data-spirit-fullwidthmode="mobile-only"
-  >
+  <div class="Dropdown Dropdown--topLeft" id="dropdownFullWidthModeMobile" 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" />
@@ -215,9 +211,15 @@
 </div>
 ```
 
-## Align
+## 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 content can be vertically aligned with `.Dropdown--top` or `.Dropdown--bottom` and horizontally `.Dropdown--left` or `.Dropdown--right` side of parent.
+### ⚠️ 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.
 
 ## JavaScript
 
@@ -275,3 +277,5 @@ myDropdownEl.addEventListener('hidden.dropdown', () => {
 
 dropdown.hide();
 ```
+
+[dictionary-placement]: https://github.com/lmc-eu/spirit-design-system/tree/main/docs/DICTIONARIES.md#placement

packages/web/src/scss/components/Dropdown/_Dropdown.scss

@@ -1,10 +1,12 @@
 @use 'sass:map';
 @use '../../tools/breakpoint';
+@use '../../tools/dictionaries';
+@use '../../tools/placement';
 @use 'theme' as theme;
 
 .Dropdown {
-    position: absolute;
-    z-index: 1;
+    @include placement.child();
+
     display: none;
     width: max-content;
     padding: theme.$padding;
@@ -27,20 +29,26 @@
     display: block;
 }
 
-.Dropdown--top {
-    bottom: 100%;
-    margin-bottom: theme.$offset;
+@include dictionaries.generate-placements(
+    $class-name: 'Dropdown',
+    $dictionary-values: theme.$placement-dictionary,
+    $offset: theme.$offset
+);
+
+// @deprecated The class combination will be removed in the next major version.
+// Migration: delete all placement class combinations below.
+.Dropdown--top.Dropdown--left {
+    @include placement.child-variant($prefix: 'dropdown', $placement: 'top-left', $offset: theme.$offset);
 }
 
-.Dropdown--right {
-    right: 0;
+.Dropdown--top.Dropdown--right {
+    @include placement.child-variant($prefix: 'dropdown', $placement: 'top-right', $offset: theme.$offset);
 }
 
-.Dropdown--bottom {
-    top: 100%;
-    margin-top: theme.$offset;
+.Dropdown--bottom.Dropdown--left {
+    @include placement.child-variant($prefix: 'dropdown', $placement: 'bottom-left', $offset: theme.$offset);
 }
 
-.Dropdown--left {
-    left: 0;
+.Dropdown--bottom.Dropdown--right {
+    @include placement.child-variant($prefix: 'dropdown', $placement: 'bottom-right', $offset: theme.$offset);
 }

packages/web/src/scss/components/Dropdown/_DropdownWrapper.scss

@@ -1,3 +1,5 @@
+@use '../../tools/placement';
+
 .DropdownWrapper {
-    position: relative;
+    @include placement.parent();
 }

packages/web/src/scss/components/Dropdown/_theme.scss

@@ -1,8 +1,10 @@
 @use '@tokens' as tokens;
+@use '../../settings/dictionaries';
 
 $breakpoints: tokens.$breakpoints;
 $offset: tokens.$space-400;
 $padding: tokens.$space-600;
 $border-radius: tokens.$radius-200;
 $background: tokens.$background-basic;
 $shadow: tokens.$shadow-100;
+$placement-dictionary: dictionaries.$placement;

packages/web/src/scss/components/Dropdown/index.html

@@ -13,7 +13,7 @@ <h2 class="docs-Heading">Basic usage with default align</h2>
     >
       Button as anchor
     </button>
-    <div class="Dropdown Dropdown--bottom Dropdown--left" id="dropdownDefault">
+    <div class="Dropdown Dropdown--bottomLeft" id="dropdownDefault">
       <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" />
@@ -55,7 +55,7 @@ <h2 class="docs-Heading">Usage with align to top right</h2>
     >
       Button as anchor
     </button>
-    <div class="Dropdown Dropdown--top Dropdown--right" id="dropdownTopRight">
+    <div class="Dropdown Dropdown--topRight" id="dropdownTopRight">
       <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" />
@@ -98,7 +98,7 @@ <h2 class="docs-Heading">Usage with disabled auto close</h2>
     >
       Button as anchor
     </button>
-    <div class="Dropdown Dropdown--bottom Dropdown--left" id="dropdownDisabledAutoClose">
+    <div class="Dropdown Dropdown--bottomLeft" id="dropdownDisabledAutoClose">
       <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" />
@@ -140,7 +140,7 @@ <h2 class="docs-Heading">Longer content</h2>
     >
       Button as anchor
     </button>
-    <div class="Dropdown Dropdown--bottom Dropdown--left" id="dropdownLonger">
+    <div class="Dropdown Dropdown--bottomLeft" id="dropdownLonger">
       <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" />

packages/web/src/scss/components/Tooltip/README.md

@@ -41,14 +41,14 @@ improved accessibility.
 
 ## Placement
 
-Available placements are: top, right, bottom, and left. To apply the desired
-placement, just pick a corresponding CSS modifier: `Tooltip--top`,
-`Tooltip--right`, `Tooltip--bottom`, or `Tooltip--left`. For JS-controlled
-positioning please use the `data-spirit-placement` attribute instead (more on that
-below).
+Tooltip implements the [Placement Dictionary][dictionary-placement] for placement. The dictionary values are used as CSS
+modifiers in the camelCase format: `Tooltip--top`, `Tooltip--rightTop`, `Tooltip--leftBottom`, etc.
+
+For JS-controlled positioning please use the `data-spirit-placement` attribute instead of CSS modifiers (more on that
+[below](#advanced-positioning)).
 
 ```html
-<div class="Tooltip Tooltip--right">
+<div class="Tooltip Tooltip--rightTop">
   Tooltip on right
   <span class="Tooltip__arrow"></span>
 </div>
@@ -172,7 +172,7 @@ purpose.
 
 When controlling Tooltip position with JavaScript, use `data-spirit-placement`
 attribute instead of CSS modifiers (`Tooltip--top` etc.) to set Tooltip
-placement. Supported values are `top`, `bottom`, `left`, and `right`.
+placement. All [Placement Dictionary][dictionary-placement] values are supported.
 
 ```html
 <div id="my-advanced-tooltip" class="Tooltip" data-spirit-placement="top">
@@ -228,4 +228,5 @@ tooltip.hide();
 ```
 
 [example]: https://spirit-design-system-demo.netlify.app/src/scss/components/tooltip/#advanced-positioning
+[dictionary-placement]: https://github.com/lmc-eu/spirit-design-system/tree/main/docs/DICTIONARIES.md#placement
 [floating-ui]: https://floating-ui.com