From 02c3ddfc0d91402371793ccd5da31bf0763a082a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jan=20Kry=C5=A1p=C3=ADn?= <crishpeen@gmail.com>
Date: Thu, 23 Nov 2023 16:37:57 +0100
Subject: [PATCH] Feat(web): Extend Tooltip Floating UI example, deprecate CSS
 modifiers and side corners names

 #DS-618
---
 .../web/src/scss/components/Tooltip/README.md |  71 ++++++--
 .../src/scss/components/Tooltip/_Tooltip.scss |  28 ++-
 .../Tooltip/floating-ui-example.mjs           |  86 +++++++++-
 .../src/scss/components/Tooltip/index.html    | 160 +++++++++++-------
 .../web/src/scss/settings/_dictionaries.scss  |   8 +-
 .../web/src/scss/settings/_feature-flags.scss |   1 +
 .../tools/__tests__/_dictionaries.test.scss   |  26 ++-
 .../scss/tools/__tests__/_placement.test.scss | 100 ++++++++++-
 .../web/src/scss/tools/_dictionaries.scss     |   8 +
 packages/web/src/scss/tools/_placement.scss   | 119 +++++++++++--
 10 files changed, 492 insertions(+), 115 deletions(-)

diff --git a/packages/web/src/scss/components/Tooltip/README.md b/packages/web/src/scss/components/Tooltip/README.md
index 5476f7a1b7..5169bdd90b 100644
--- a/packages/web/src/scss/components/Tooltip/README.md
+++ b/packages/web/src/scss/components/Tooltip/README.md
@@ -3,12 +3,32 @@
 Bare Tooltip HTML:
 
 ```html
-<div class="Tooltip Tooltip--top">
+<div class="Tooltip" data-spirit-placement="top">
   Hello there!
   <span class="Tooltip__arrow"></span>
 </div>
 ```
 
+## Feature Flag: Data Selector Placement
+
+Tooltip placement is currently using CSS modifiers. In the future it will be using `data-spirit-placement`
+attribute in order to make the placement independent of the component and compatible with Floating UI.
+To enable this behavior now you can use the feature flag, either set the `$tooltip-enable-data-placement`
+feature flag to `true` or use the `spirit-feature-tooltip-enable-data-placement` CSS class on any parent of the Tooltip.
+
+For more info, see main [README][readme-feature-flags].
+
+## ⚠️ DEPRECATION NOTICE
+
+CSS modifiers `Tooltip--top`, `Tooltip--rightTop`, `Tooltip--bottom`, etc. are deprecated and will be
+removed in the next major release. Use `data-spirit-placement` attribute instead.
+
+Also both axis side placements are renamed from `top-left`, `top-right`, `right-top`, `right-bottom`,
+etc. to `top-start`, `top-end`, `right-start`, `right-end`, etc. Old names are deprecated and will be
+removed in the next major release.
+
+[What are deprecations?][readme-deprecations]
+
 ## Linking with Content
 
 To display a Tooltip along your content, simply place it in the DOM next to it.
@@ -32,7 +52,7 @@ improved accessibility.
 ```html
 <div class="TooltipWrapper d-inline-block">
   <a href="#" aria-describedby="my-tooltip">I have a tooltip!</a>
-  <div id="my-tooltip" class="Tooltip Tooltip--top">
+  <div id="my-tooltip" class="Tooltip" data-spirit-placement="top">
     Hello there!
     <span class="Tooltip__arrow"></span>
   </div>
@@ -41,14 +61,14 @@ improved accessibility.
 
 ## Placement
 
-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.
+Tooltip 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.
 
-For JS-controlled positioning please use the `data-spirit-placement` attribute instead of CSS modifiers (more on that
-[below](#advanced-positioning)).
+For JS-controlled positioning please use the `data-spirit-placement-controlled` attribute instead of specifying the placement
+using the `data-spirit-placement` modifiers (more on that [below](#advanced-positioning)).
 
 ```html
-<div class="Tooltip Tooltip--rightTop">
+<div class="Tooltip" data-spirit-placement="right-start">
   Tooltip on right
   <span class="Tooltip__arrow"></span>
 </div>
@@ -65,7 +85,7 @@ Tooltip HTML right after it.
 ```html
 <div class="TooltipWrapper d-inline-block">
   <a href="#" class="TooltipTarget" aria-describedby="my-tooltip-on-hover">I have a tooltip!</a>
-  <div id="my-tooltip-on-hover" class="Tooltip Tooltip--top">
+  <div id="my-tooltip-on-hover" class="Tooltip" data-spirit-placement="top">
     Hello there!
     <span class="Tooltip__arrow"></span>
   </div>
@@ -78,7 +98,7 @@ Add `tabindex="0"` to non-focusable elements to ensure keyboard accessibility.
 ```html
 <div class="TooltipWrapper d-inline-block">
   <span class="TooltipTarget" aria-describedby="my-tooltip-on-focus" tabindex="0">I have a tooltip!</span>
-  <div id="my-tooltip-on-focus" class="Tooltip Tooltip--top">
+  <div id="my-tooltip-on-focus" class="Tooltip" data-spirit-placement="top">
     Hello there!
     <span class="Tooltip__arrow"></span>
   </div>
@@ -95,7 +115,7 @@ Tooltip. As a workaround, you'll want to trigger the Tooltip from a wrapper
   <div class="TooltipTarget" aria-describedby="my-tooltip-for-disabled-button" tabindex="0">
     <button type="button" disabled>I have a tooltip though I'm disabled</button>
   </div>
-  <div id="my-tooltip-for-disabled-button" class="Tooltip Tooltip--top">
+  <div id="my-tooltip-for-disabled-button" class="Tooltip" data-spirit-placement="top">
     Hello there!
     <span class="Tooltip__arrow"></span>
   </div>
@@ -114,7 +134,7 @@ kind of task Tooltip responds to interaction classes `is-hidden` and
 <button type="button" id="tooltip-trigger" data-spirit-target="#my-js-controlled-tooltip">Toggle tooltip</button>
 <div class="TooltipWrapper d-inline-block">
   <div aria-describedby="my-js-controlled-tooltip">I have an externally-triggered tooltip</div>
-  <div id="my-js-controlled-tooltip" class="Tooltip Tooltip--top is-hidden">
+  <div id="my-js-controlled-tooltip" class="Tooltip is-hidden" data-spirit-placement="top">
     Hello there!
     <span class="Tooltip__arrow"></span>
   </div>
@@ -141,7 +161,7 @@ Tooltip can be made dismissible by following these steps:
    attributes on the closing button.
 
 ```html
-<div id="my-dismissible-tooltip" class="Tooltip Tooltip--right Tooltip--dismissible">
+<div id="my-dismissible-tooltip" class="Tooltip Tooltip--dismissible" data-spirit-placement="right">
   Close me
   <button
     type="button"
@@ -181,9 +201,32 @@ placement. All [Placement Dictionary][dictionary-placement] values are supported
 </div>
 ```
 
+If you have the [Data Selector Placement feature flag](#feature-flag-data-selector-placement) enabled,
+set `data-spirit-placement-controlled` on the `.Tooltip` to control it and prevent conflicts with
+the default CSS positioning.
+
+```html
+<div id="my-advanced-tooltip" class="Tooltip" data-spirit-placement-controlled>
+  Hello there!
+  <span class="Tooltip__arrow"></span>
+</div>
+```
+
+### Arrow
+
+When controlling Tooltip arrow with JavaScript, set `data-spirit-element="arrow"`
+on the `.Tooltip__arrow` to control it and prevent conflicts with the default CSS positioning.
+
+```html
+<div id="my-advanced-tooltip" class="Tooltip" data-spirit-placement-controlled>
+  Hello there!
+  <span class="Tooltip__arrow" data-spirit-element="arrow"></span>
+</div>
+```
+
 ### Example
 
-💻 Check our minimum [example] that uses external library
+💻 Check our [example] that uses external library
 [Floating UI][floating-ui] (see the [JS source](./floating-ui-example.mjs)).
 
 👉 Please consult [Floating UI][floating-ui] documentation to understand how it
@@ -230,3 +273,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
+[readme-feature-flags]: https://github.com/lmc-eu/spirit-design-system/tree/main/packages/web/README.md#feature-flags
+[readme-deprecations]: https://github.com/lmc-eu/spirit-design-system/tree/main/packages/web/README.md#deprecations
diff --git a/packages/web/src/scss/components/Tooltip/_Tooltip.scss b/packages/web/src/scss/components/Tooltip/_Tooltip.scss
index f6ce698c92..fcae1768e0 100644
--- a/packages/web/src/scss/components/Tooltip/_Tooltip.scss
+++ b/packages/web/src/scss/components/Tooltip/_Tooltip.scss
@@ -5,6 +5,7 @@
 // 2. Reuse already generated custom properties to allow overriding the arrow appearance live in the browser.
 
 @use 'sass:math';
+@use '../../settings/feature-flags';
 @use '../../tools/dictionaries';
 @use '../../tools/placement';
 @use '../../tools/reset';
@@ -82,10 +83,33 @@
 }
 
 // Controlled placement
-.Tooltip[data-spirit-placement] {
-    @include placement.child-controlled($prefix: 'tooltip');
+// @deprecated The feature flag will be removed in the next major version.
+// Migration: delete this feature flag condition
+@if feature-flags.$tooltip-enable-data-placement {
+    .Tooltip[data-spirit-placement-controlled] {
+        @include placement.child-controlled($prefix: 'tooltip', $offset: theme.$arrow-height);
+    }
+} @else {
+    // @deprecated The feature flag will be removed in the next major version.
+    // Migration: delete this selector
+    // stylelint-disable-next-line selector-max-specificity
+    .Tooltip[data-spirit-placement]:not(.spirit-feature-tooltip-enable-data-placement .Tooltip[data-spirit-placement]) {
+        @include placement.child-controlled($prefix: 'tooltip');
+    }
+}
+
+// @deprecated The feature flag will be removed in the next major version.
+// Migration: delete this feature class selector
+.spirit-feature-tooltip-enable-data-placement .Tooltip[data-spirit-placement-controlled] {
+    @include placement.child-controlled($prefix: 'tooltip', $offset: theme.$arrow-height);
+}
+
+.Tooltip[data-spirit-placement-controlled] .Tooltip__arrow {
+    @include placement.arrow-controlled();
 }
 
+// @deprecated This is deprecated and will be removed in the next major version
+// Migration: delete this mixin
 @include dictionaries.generate-controlled-placements(
     $class-name: 'Tooltip',
     $dictionary-values: theme.$placement-dictionary,
diff --git a/packages/web/src/scss/components/Tooltip/floating-ui-example.mjs b/packages/web/src/scss/components/Tooltip/floating-ui-example.mjs
index bce260c706..fe92095248 100644
--- a/packages/web/src/scss/components/Tooltip/floating-ui-example.mjs
+++ b/packages/web/src/scss/components/Tooltip/floating-ui-example.mjs
@@ -1,23 +1,99 @@
 // To fully understand Floating UI and its options, please consult Floating UI docs:
 // @see https://floating-ui.com
 
-import { autoUpdate, computePosition, flip } from 'https://cdn.skypack.dev/@floating-ui/dom@1.5.3';
+import {
+  arrow,
+  autoUpdate,
+  computePosition,
+  flip,
+  offset,
+  limitShift,
+  shift,
+  size,
+} from 'https://cdn.skypack.dev/@floating-ui/dom@1.5.3';
 
 const button = document.getElementById('my-button');
 const tooltip = document.getElementById('my-advanced-tooltip');
+const select = document.getElementById('my-advanced-select');
+const viewport = document.getElementById('my-advanced-viewport');
+const content = document.getElementById('my-advanced-content');
+const arrowEl = tooltip.querySelector('[data-spirit-element="arrow"]');
 
-const cleanup = autoUpdate(button, tooltip, () => {
+const tooltipComputedStyle = window.getComputedStyle(tooltip);
+const tooltipMaxWidth = parseInt(tooltipComputedStyle.maxWidth, 10);
+const tooltipOffset = parseInt(tooltipComputedStyle.getPropertyValue('--tooltip-offset'), 10);
+const arrowCornerOffset = parseInt(
+  window.getComputedStyle(arrowEl).getPropertyValue('--tooltip-arrow-corner-offset'),
+  10,
+);
+
+function updateTooltipPosition() {
   computePosition(button, tooltip, {
-    placement: 'top',
-    middleware: [flip()],
-  }).then(({ x, y, placement }) => {
+    placement: tooltip.dataset.spiritPlacement,
+    middleware: [
+      offset(tooltipOffset),
+      flip({
+        crossAxis: false,
+      }),
+      shift({
+        limiter: limitShift({
+          offset: ({ rects }) => ({
+            mainAxis: rects.reference.height,
+          }),
+        }),
+      }),
+      size({
+        apply({ availableWidth }) {
+          Object.assign(tooltip.style, {
+            maxWidth: `${tooltipMaxWidth < availableWidth ? tooltipMaxWidth : availableWidth}px`,
+          });
+        },
+      }),
+      arrow({ element: arrowEl, padding: arrowCornerOffset }), // arrow() should be placed at the end
+    ],
+  }).then(({ x, y, middlewareData, placement }) => {
     Object.assign(tooltip.style, {
       top: `${y}px`,
       left: `${x}px`,
     });
 
+    const side = placement.split('-')[0];
+
+    const staticSide = {
+      top: 'bottom',
+      right: 'left',
+      bottom: 'top',
+      left: 'right',
+    }[side];
+
+    if (middlewareData.arrow) {
+      const offset =
+        staticSide === 'top' || staticSide === 'bottom'
+          ? arrowEl.offsetHeight
+          : (arrowEl.offsetHeight + arrowEl.offsetWidth) / 2;
+      const { x, y } = middlewareData.arrow;
+      Object.assign(arrowEl.style, {
+        left: x != null ? `${x}px` : '',
+        top: y != null ? `${y}px` : '',
+        bottom: '',
+        right: '',
+        [staticSide]: `-${offset}px`,
+      });
+    }
+
     tooltip.dataset.spiritPlacement = placement;
   });
+}
+
+window.onload = () => {
+  viewport.scrollLeft = (content.offsetWidth - viewport.offsetWidth) / 2;
+};
+
+const cleanup = autoUpdate(button, tooltip, updateTooltipPosition);
+
+select.addEventListener('change', () => {
+  tooltip.dataset.spiritPlacement = select.value;
+  updateTooltipPosition();
 });
 
 // Call cleanup function when tooltip is removed from DOM.
diff --git a/packages/web/src/scss/components/Tooltip/index.html b/packages/web/src/scss/components/Tooltip/index.html
index 0bb63a4f9e..d335340971 100644
--- a/packages/web/src/scss/components/Tooltip/index.html
+++ b/packages/web/src/scss/components/Tooltip/index.html
@@ -1,6 +1,6 @@
 {{#> layout/plain }}
 
-  <section class="docs-Section">
+  <section class="docs-Section spirit-feature-tooltip-enable-data-placement">
 
     <h2 class="docs-Heading">Placements</h2>
 
@@ -10,10 +10,10 @@ <h2 class="docs-Heading">Placements</h2>
         <div class="Grid Grid--cols-3 mx-auto" style="align-items: center; justify-items: center; max-width: 30rem;">
           <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">
@@ -22,20 +22,20 @@ <h2 class="docs-Heading">Placements</h2>
                 <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" />
+            <label for="placement_bottom_start" class="Radio">
+              <input type="radio" name="placement" value="bottom-start" id="placement_bottom_start" class="Radio__input" />
               <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">
@@ -44,10 +44,10 @@ <h2 class="docs-Heading">Placements</h2>
                 <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>
 
@@ -63,10 +63,10 @@ <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">
@@ -75,10 +75,10 @@ <h2 class="docs-Heading">Placements</h2>
                 <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>
 
@@ -94,10 +94,10 @@ <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">
@@ -106,10 +106,10 @@ <h2 class="docs-Heading">Placements</h2>
                 <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>
 
@@ -121,7 +121,7 @@ <h2 class="docs-Heading">Placements</h2>
                 Click<br />
                 the dots!
               </div>
-              <div class="Tooltip Tooltip--bottom" id="tooltip_placements_example">
+              <div class="Tooltip" id="tooltip_placements_example" data-spirit-placement="bottom">
                 <span id="tooltip_placements_example_text">bottom</span>
                 <span class="Tooltip__arrow"></span>
               </div>
@@ -140,8 +140,8 @@ <h2 class="docs-Heading">Placements</h2>
             const tooltip = document.getElementById('tooltip_placements_example');
             const tooltipText = document.getElementById('tooltip_placements_example_text');
 
-            tooltip.classList.replace(tooltip.classList[1], `Tooltip--${placement}`);
-            tooltipText.textContent = placement.split(/(?=[A-Z])/).join('-').toLowerCase();
+            tooltip.dataset.spiritPlacement = placement;
+            tooltipText.textContent = placement;
           });
         });
       </script>
@@ -149,7 +149,7 @@ <h2 class="docs-Heading">Placements</h2>
     </div>
   </section>
 
-  <section class="docs-Section">
+  <section class="docs-Section spirit-feature-tooltip-enable-data-placement">
 
     <h2 class="docs-Heading">Static Tooltip (No Interaction)</h2>
 
@@ -160,19 +160,19 @@ <h2 class="docs-Heading">Static Tooltip (No Interaction)</h2>
           Tooltips<br />
           all day long…
         </div>
-        <div class="Tooltip Tooltip--top">
+        <div class="Tooltip" data-spirit-placement="top">
           Hello there!
           <span class="Tooltip__arrow"></span>
         </div>
-        <div class="Tooltip Tooltip--right">
+        <div class="Tooltip" data-spirit-placement="right">
           Hello there!
           <span class="Tooltip__arrow"></span>
         </div>
-        <div class="Tooltip Tooltip--bottom">
+        <div class="Tooltip" data-spirit-placement="bottom">
           Hello there! There is slightly more text in this tooltip.
           <span class="Tooltip__arrow"></span>
         </div>
-        <div class="Tooltip Tooltip--left">
+        <div class="Tooltip" data-spirit-placement="left">
           Hello there!
           <span class="Tooltip__arrow"></span>
         </div>
@@ -182,7 +182,7 @@ <h2 class="docs-Heading">Static Tooltip (No Interaction)</h2>
 
   </section>
 
-  <section class="docs-Section">
+  <section class="docs-Section spirit-feature-tooltip-enable-data-placement">
 
     <h2 class="docs-Heading">Tooltip on Hover (Pure CSS)</h2>
 
@@ -193,7 +193,7 @@ <h2 class="docs-Heading">Tooltip on Hover (Pure CSS)</h2>
           <button type="button" class="Button Button--primary Button--medium TooltipTarget" aria-describedby="my-tooltip-hover-top">
             Tooltip on top
           </button>
-          <div id="my-tooltip-hover-top" class="Tooltip Tooltip--top">
+          <div id="my-tooltip-hover-top" class="Tooltip" data-spirit-placement="top">
             Hello there!
             <span class="Tooltip__arrow"></span>
           </div>
@@ -202,7 +202,7 @@ <h2 class="docs-Heading">Tooltip on Hover (Pure CSS)</h2>
           <button type="button" class="Button Button--primary Button--medium TooltipTarget" aria-describedby="my-tooltip-hover-right">
             Tooltip on right
           </button>
-          <div id="my-tooltip-hover-right" class="Tooltip Tooltip--right">
+          <div id="my-tooltip-hover-right" class="Tooltip" data-spirit-placement="right">
             Hello there!
             <span class="Tooltip__arrow"></span>
           </div>
@@ -211,7 +211,7 @@ <h2 class="docs-Heading">Tooltip on Hover (Pure CSS)</h2>
           <button type="button" class="Button Button--primary Button--medium TooltipTarget" aria-describedby="my-tooltip-hover-bottom">
             Tooltip on bottom
           </button>
-          <div id="my-tooltip-hover-bottom" class="Tooltip Tooltip--bottom">
+          <div id="my-tooltip-hover-bottom" class="Tooltip" data-spirit-placement="bottom">
             Hello there!
             <span class="Tooltip__arrow"></span>
           </div>
@@ -220,7 +220,7 @@ <h2 class="docs-Heading">Tooltip on Hover (Pure CSS)</h2>
           <button type="button" class="Button Button--primary Button--medium TooltipTarget" aria-describedby="my-tooltip-hover-left">
             Tooltip on left
           </button>
-          <div id="my-tooltip-hover-left" class="Tooltip Tooltip--left">
+          <div id="my-tooltip-hover-left" class="Tooltip" data-spirit-placement="left">
             Hello there!
             <span class="Tooltip__arrow"></span>
           </div>
@@ -231,7 +231,7 @@ <h2 class="docs-Heading">Tooltip on Hover (Pure CSS)</h2>
 
   </section>
 
-  <section class="docs-Section">
+  <section class="docs-Section spirit-feature-tooltip-enable-data-placement">
 
     <h2 class="docs-Heading">Tooltip on Click (JavaScript)</h2>
 
@@ -251,7 +251,7 @@ <h2 class="docs-Heading">Tooltip on Click (JavaScript)</h2>
         <div class="docs-Box" aria-describedby="my-js-controlled-tooltip">
           I have an externally-triggered tooltip
         </div>
-        <div id="my-js-controlled-tooltip" class="Tooltip Tooltip--bottom is-hidden">
+        <div id="my-js-controlled-tooltip" class="Tooltip is-hidden" data-spirit-placement="bottom">
           Hello there!
           <span class="Tooltip__arrow"></span>
         </div>
@@ -261,7 +261,7 @@ <h2 class="docs-Heading">Tooltip on Click (JavaScript)</h2>
 
   </section>
 
-  <section class="docs-Section">
+  <section class="docs-Section spirit-feature-tooltip-enable-data-placement">
 
     <h2 class="docs-Heading">Dismissible Tooltip</h2>
 
@@ -269,7 +269,7 @@ <h2 class="docs-Heading">Dismissible Tooltip</h2>
 
       <div class="TooltipWrapper d-inline-block">
         <button class="Button Button--primary Button--medium" aria-describedby="my-dismissible-tooltip">I have a tooltip 😎</button>
-        <div id="my-dismissible-tooltip" class="Tooltip Tooltip--right Tooltip--dismissible">
+        <div id="my-dismissible-tooltip" class="Tooltip Tooltip--dismissible" data-spirit-placement="right">
           Close me
           <button
             type="button"
@@ -292,7 +292,7 @@ <h2 class="docs-Heading">Dismissible Tooltip</h2>
 
   </section>
 
-  <section class="docs-Section">
+  <section class="docs-Section spirit-feature-tooltip-enable-data-placement">
 
     <h2 class="docs-Heading">Dismissible Tooltip via JS API</h2>
 
@@ -305,7 +305,7 @@ <h2 class="docs-Heading">Dismissible Tooltip via JS API</h2>
 
       <div class="TooltipWrapper d-inline-block">
         <button id="my-dismissible-button" class="Button Button--primary Button--medium" aria-describedby="my-dismissible-tooltip2">I have a tooltip 😎</button>
-        <div id="my-dismissible-tooltip2" class="Tooltip Tooltip--right Tooltip--dismissible is-hidden">
+        <div id="my-dismissible-tooltip2" class="Tooltip Tooltip--dismissible is-hidden" data-spirit-placement="right">
           Close me
           <button
             id="my-dismissible-tooltip2-button"
@@ -328,52 +328,88 @@ <h2 class="docs-Heading">Dismissible Tooltip via JS API</h2>
 
   </section>
 
-  <section id="advanced-positioning" class="docs-Section">
+  <section id="full-floating-ui" class="docs-Section spirit-feature-tooltip-enable-data-placement">
 
-    <h2 class="docs-Heading">Advanced Positioning</h2>
+    <h2 class="docs-Heading">Full Floating UI Usage</h2>
 
-    <div class="docs-Stack docs-Stack--start">
+    <div class="docs-Stack docs-Stack--stretch">
 
-      <p>
+      <p class="mb-0">
         The following example is using external library <a href="https://floating-ui.com">Floating UI</a>.
+        Try scrolling the frame or resizing the window to see how the Tooltip behaves. The Floating UI
+        library is trying to keep the Tooltip in the viewport and it is also flipping, shifting and
+        resizing the Tooltip when it is not possible to keep it in the viewport.
       </p>
 
-      <p>
-        🖱 Try scrolling the example to see how Tooltip placement is updated.
-      </p>
+      <div class="Alert Alert--informative" role="alert">
+        <svg width="24" height="24">
+          <use xlink:href="/icons/svg/sprite.svg#info" />
+        </svg>
+        <div>
+          Please note that the Floating UI library is trying to point the arrow to the center
+          of the trigger element. This is not possible to achieve in CSS only so our behavior
+          is slightly different for tooltips not using Floating UI.
+        </div>
+      </div>
+
+      <div class="Select">
+        <label for="my-advanced-select" class="Select__label">Suggested placement</label>
+        <div class="Select__inputContainer">
+          <select id="my-advanced-select" name="advanced-placement" class="Select__input">
+            <option value="top-start" selected>top-start</option>
+            <option value="top">top</option>
+            <option value="top-end">top-end</option>
+            <option value="right-start">right-start</option>
+            <option value="right">right</option>
+            <option value="right-end">right-end</option>
+            <option value="bottom-start">bottom-start</option>
+            <option value="bottom">bottom</option>
+            <option value="bottom-end">bottom-end</option>
+            <option value="left-start">left-start</option>
+            <option value="left">left</option>
+            <option value="left-end">left-end</option>
+          </select>
+          <div class="Select__icon">
+            <svg width="24" height="24" aria-hidden="true">
+              <use xlink:href="/icons/svg/sprite.svg#chevron-down" />
+            </svg>
+          </div>
+        </div>
+      </div>
 
       <script type="module" src="floating-ui-example.mjs"></script>
 
       <style>
         .example-viewport {
-          width: 40rem;
+          width: 100%;
           max-width: 100%;
-          height: 10rem;
+          height: 30rem;
           overflow: auto;
         }
 
         .example-content {
           position: relative;
-          width: 100%;
-          height: 20rem;
-          padding-block: 7rem;
+          width: 300%;
+          height: 60rem;
+          padding-block: 12rem;
           text-align: center;
         }
       </style>
 
-      <div class="example-viewport bg-cover">
-        <div class="example-content">
+      <div class="example-viewport bg-cover" id="my-advanced-viewport">
+        <div class="example-content" id="my-advanced-content">
           <button
             type="button"
             id="my-button"
             class="Button Button--primary Button--medium"
             aria-describedby="my-advanced-tooltip"
           >
-            I have a flipping tooltip!
+            I have a Floating tooltip!
           </button>
-          <div id="my-advanced-tooltip" class="Tooltip" data-spirit-placement="top">
-            Hello there!
-            <span class="Tooltip__arrow"></span>
+          <div id="my-advanced-tooltip" class="Tooltip" data-spirit-placement="top-start" data-spirit-placement-controlled>
+            This long tooltip is flipping, resizing and shifting to stay in the viewport.
+            Also its arrow is always trying to point to the center of the trigger.
+            <span class="Tooltip__arrow" data-spirit-element="arrow"></span>
           </div>
         </div>
       </div>
diff --git a/packages/web/src/scss/settings/_dictionaries.scss b/packages/web/src/scss/settings/_dictionaries.scss
index f1351aa463..29d8ff27aa 100644
--- a/packages/web/src/scss/settings/_dictionaries.scss
+++ b/packages/web/src/scss/settings/_dictionaries.scss
@@ -2,13 +2,17 @@
 @use '@tokens' as tokens;
 
 $_placement-sides: top, bottom, left, right;
-$_placement-side-corners: top-left, top-right, bottom-left, bottom-right, left-top, left-bottom, right-top, right-bottom;
+$_placement-side-corners: top-start, top-end, bottom-start, bottom-end, left-start, left-end, right-start, right-end;
+
+// @deprecated This variable is deprecated and will be removed in the next major version
+$_placement-side-corners-deprecated: top-left, top-right, bottom-left, bottom-right, left-top, left-bottom, right-top,
+    right-bottom;
 $_size-extended: xsmall, xlarge;
 
 $action-colors: primary, secondary, tertiary, inverted;
 $action-link-colors: primary, secondary, inverted;
 $emotion-colors: success, informative, warning, danger;
-$placement: list.join($_placement-sides, $_placement-side-corners);
+$placement: list.join(list.join($_placement-sides, $_placement-side-corners), $_placement-side-corners-deprecated);
 $size: small, medium, large;
 $size-extended: list.join($size, $_size-extended);
 $text-colors: primary, secondary, primary-inverted, secondary-inverted;
diff --git a/packages/web/src/scss/settings/_feature-flags.scss b/packages/web/src/scss/settings/_feature-flags.scss
index f108d4c6fd..4c7a10a2fe 100644
--- a/packages/web/src/scss/settings/_feature-flags.scss
+++ b/packages/web/src/scss/settings/_feature-flags.scss
@@ -1 +1,2 @@
 $dropdown-enable-enhanced-shadow: false !default;
+$tooltip-enable-data-placement: false !default;
diff --git a/packages/web/src/scss/tools/__tests__/_dictionaries.test.scss b/packages/web/src/scss/tools/__tests__/_dictionaries.test.scss
index 73b069d109..185fc6e951 100644
--- a/packages/web/src/scss/tools/__tests__/_dictionaries.test.scss
+++ b/packages/web/src/scss/tools/__tests__/_dictionaries.test.scss
@@ -1,4 +1,4 @@
-// stylelint-disable scss/at-mixin-argumentless-call-parentheses
+// stylelint-disable scss/at-mixin-argumentless-call-parentheses -- We need to allow this to make sass-true work
 @use 'true';
 @use '../../settings/dictionaries' as dictionaries-settings;
 @use '../dictionaries';
@@ -101,6 +101,7 @@
             }
 
             @include true.expect {
+                .Test[data-spirit-placement='top-left'],
                 .Test--topLeft {
                     --test-offset: 0;
 
@@ -110,13 +111,24 @@
                 }
             }
         }
-    }
-}
 
-// Create Test classes in order to test extend in next mixin test
-.Test--topLeft,
-.Test--bottomRight {
-    position: relative;
+        @include true.assert {
+            @include true.output {
+                @include dictionaries.generate-placements('Test', ('top-start'));
+            }
+
+            @include true.expect {
+                .Test[data-spirit-placement='top-start'],
+                .Test--topStart {
+                    --test-offset: 0;
+
+                    inset: auto auto 100% 0;
+                    translate: var(--test-offset-orthogonal, 0) calc(-1 * var(--test-offset, 0));
+                    transform-origin: bottom;
+                }
+            }
+        }
+    }
 }
 
 @include true.describe('generate-controlled-placements mixin') {
diff --git a/packages/web/src/scss/tools/__tests__/_placement.test.scss b/packages/web/src/scss/tools/__tests__/_placement.test.scss
index 729d31f0cf..2f744b9cac 100644
--- a/packages/web/src/scss/tools/__tests__/_placement.test.scss
+++ b/packages/web/src/scss/tools/__tests__/_placement.test.scss
@@ -3,20 +3,28 @@
 @use '../placement';
 
 @include true.describe('placement functions and mixins') {
-    @include true.it('should returns correct values for inverse function') {
+    @include true.it('should return correct inverse placements') {
         @include true.assert {
             @include true.output {
                 $inverse-top: placement.inverse('top');
-                $inverse-bottom-left: placement.inverse('bottom-left');
+                $inverse-bottom-start: placement.inverse('bottom-start');
+                $inverse-left-end: placement.inverse('left-end');
+
+                // Testing with main-axis-only and hyphenation
+                $inverse-top-start-hyphen: placement.inverse('top-start', true, true);
+                $inverse-top-start-space: placement.inverse('top-start', true, false);
             }
             @include true.expect {
                 $inverse-top: 'bottom';
-                $inverse-bottom-left: 'top-right';
+                $inverse-bottom-start: 'top';
+                $inverse-left-end: 'right';
+                $inverse-top-start-hyphen: 'bottom-start';
+                $inverse-top-start-space: 'bottom start';
             }
         }
     }
 
-    @include true.it('should return parent position') {
+    @include true.it('should apply relative positioning to parent') {
         @include true.assert {
             @include true.output {
                 .parent-test {
@@ -31,23 +39,23 @@
         }
     }
 
-    @include true.it('should return child position with z-index') {
+    @include true.it('should apply absolute positioning to child with z-index') {
         @include true.assert {
             @include true.output {
                 .child-test {
-                    @include placement.child(2);
+                    @include placement.child(3);
                 }
             }
             @include true.expect {
                 .child-test {
                     position: absolute;
-                    z-index: 2;
+                    z-index: 3;
                 }
             }
         }
     }
 
-    @include true.it('should return child-variant with correct styles') {
+    @include true.it('should apply custom styles to child variant') {
         @include true.assert {
             @include true.output {
                 .child-variant-test {
@@ -65,4 +73,80 @@
             }
         }
     }
+
+    @include true.it('should apply controlled styles to child') {
+        @include true.assert {
+            @include true.output {
+                .child-controlled-test {
+                    @include placement.child-controlled('test', 10px);
+                }
+            }
+            @include true.expect {
+                .child-controlled-test {
+                    --test-offset-orthogonal: 0;
+
+                    inset: unset;
+
+                    --test-offset: 10px;
+
+                    translate: unset;
+                }
+            }
+        }
+    }
+
+    @include true.it('should apply styles to arrow') {
+        @include true.assert {
+            @include true.output {
+                .arrow-test {
+                    @include placement.arrow('test', '10px', '10px', '5px');
+                }
+            }
+            @include true.expect {
+                .arrow-test {
+                    --test-arrow-width: 10px;
+                    --test-arrow-height: 10px;
+                    --test-arrow-corner-offset: 5px;
+
+                    position: absolute;
+                    transform-origin: bottom center;
+                }
+            }
+        }
+    }
+
+    @include true.it('should apply variant styles to arrow') {
+        @include true.assert {
+            @include true.output {
+                .arrow-variant-test {
+                    @include placement.arrow-variant('test', 'top');
+                }
+            }
+            @include true.expect {
+                .arrow-variant-test {
+                    inset: auto auto 100% 50%;
+                    translate: -50% 0%;
+                    rotate: z 0deg;
+                }
+            }
+        }
+    }
+
+    @include true.it('should apply controlled styles to arrow') {
+        @include true.assert {
+            @include true.output {
+                .arrow-controlled-test {
+                    @include placement.arrow-controlled();
+                }
+            }
+
+            @include true.expect {
+                .arrow-controlled-test {
+                    inset: unset;
+                    translate: unset;
+                    transform-origin: center;
+                }
+            }
+        }
+    }
 }
diff --git a/packages/web/src/scss/tools/_dictionaries.scss b/packages/web/src/scss/tools/_dictionaries.scss
index 4f96dae537..2738671d85 100644
--- a/packages/web/src/scss/tools/_dictionaries.scss
+++ b/packages/web/src/scss/tools/_dictionaries.scss
@@ -181,11 +181,17 @@
     @each $placement in $dictionary-values {
         $placement-modifier: spirit-string.convert-kebab-case-to-camel-case($placement);
 
+        .#{$class-name}[data-spirit-placement='#{$placement}'],
+        // @deprecated CSS modifier classes are deprecated and will be removed in the next major version
+        // Migration: delete this selector
         .#{$class-name}--#{$placement-modifier} {
             @include placement.child-variant($prefix, $placement, $offset);
         }
 
         @if $has-arrow {
+            .#{$class-name}[data-spirit-placement='#{$placement}'] > .#{$class-name}__arrow,
+            // @deprecated CSS modifier classes are deprecated and will be removed in the next major version
+            // Migration: delete this selector
             .#{$class-name}--#{$placement-modifier} > .#{$class-name}__arrow {
                 @include placement.arrow-variant($prefix, placement.inverse($placement, $main-axis-only: true));
             }
@@ -193,6 +199,8 @@
     }
 }
 
+// @deprecated This mixin is deprecated and will be removed in the next major version
+// Migration: delete this mixin
 // Mixin to generate controlled placement classes based on a dictionary
 // Parameters are:
 // * $class-name: the name of the component class to generate
diff --git a/packages/web/src/scss/tools/_placement.scss b/packages/web/src/scss/tools/_placement.scss
index 60b0d5d44e..8bc2d706b4 100644
--- a/packages/web/src/scss/tools/_placement.scss
+++ b/packages/web/src/scss/tools/_placement.scss
@@ -21,32 +21,64 @@
 
 $_arrow-rotate-map: (
     top: 0deg,
+    top-start: 0deg,
+    top-end: 0deg,
+    bottom: 180deg,
+    bottom-start: 180deg,
+    bottom-end: 180deg,
+    left: -90deg,
+    left-start: -90deg,
+    left-end: -90deg,
+    right: 90deg,
+    right-start: 90deg,
+    right-end: 90deg,
+    // Deprecated in favor of top-start, will be removed in the next major version
     top-left: 0deg,
+    // Deprecated in favor of top-end, will be removed in the next major version
     top-right: 0deg,
-    bottom: 180deg,
+    // Deprecated in favor of bottom-start, will be removed in the next major version
     bottom-left: 180deg,
+    // Deprecated in favor of bottom-end, will be removed in the next major version
     bottom-right: 180deg,
-    left: -90deg,
+    // Deprecated in favor of left-start, will be removed in the next major version
     left-top: -90deg,
+    // Deprecated in favor of left-end, will be removed in the next major version
     left-bottom: -90deg,
-    right: 90deg,
+    // Deprecated in favor of right-start, will be removed in the next major version
     right-top: 90deg,
+    // Deprecated in favor of right-end, will be removed in the next major version
     right-bottom: 90deg,
 );
 
 // 1.2
 $_inset-map: (
     top: auto auto 100% 50%,
+    top-start: auto auto 100% 0,
+    top-end: auto 0 100% auto,
+    bottom: 100% auto auto 50%,
+    bottom-start: 100% auto auto 0,
+    bottom-end: 100% 0 auto auto,
+    left: 50% 100% auto auto,
+    left-start: 0 100% auto auto,
+    left-end: auto 100% 0 auto,
+    right: 50% auto auto 100%,
+    right-start: 0 auto auto 100%,
+    right-end: auto auto 0 100%,
+    // Deprecated in favor of top-start, will be removed in the next major version
     top-left: auto auto 100% 0,
+    // Deprecated in favor of top-end, will be removed in the next major version
     top-right: auto 0 100% auto,
-    bottom: 100% auto auto 50%,
+    // Deprecated in favor of bottom-start, will be removed in the next major version
     bottom-left: 100% auto auto 0,
+    // Deprecated in favor of bottom-end, will be removed in the next major version
     bottom-right: 100% 0 auto auto,
-    left: 50% 100% auto auto,
+    // Deprecated in favor of left-start, will be removed in the next major version
     left-top: 0 100% auto auto,
+    // Deprecated in favor of left-end, will be removed in the next major version
     left-bottom: auto 100% 0 auto,
-    right: 50% auto auto 100%,
+    // Deprecated in favor of right-start, will be removed in the next major version
     right-top: 0 auto auto 100%,
+    // Deprecated in favor of right-end, will be removed in the next major version
     right-bottom: auto auto 0 100%,
 );
 
@@ -60,25 +92,51 @@ $_placement-inverse-map: (
 @function -get-arrow-translate-map($prefix) {
     @return (
         top: -50% 0%,
+        top-start: var(--#{$prefix}-arrow-corner-offset) 0%,
+        top-end: calc(-1 * var(--#{$prefix}-arrow-corner-offset)) 0%,
+        bottom: -50% -100%,
+        bottom-start: var(--#{$prefix}-arrow-corner-offset) -100%,
+        bottom-end: calc(-1 * var(--#{$prefix}-arrow-corner-offset)) -100%,
+        left: 50% -100%,
+        left-start: calc(var(--#{$prefix}-arrow-width) / 2)
+            calc(
+                var(--#{$prefix}-arrow-width) / 2 - var(--#{$prefix}-arrow-height) +
+                    var(--#{$prefix}-arrow-corner-offset)
+            ),
+        left-end: calc(var(--#{$prefix}-arrow-width) / 2)
+            calc(var(--#{$prefix}-arrow-width) / -2 - var(--#{$prefix}-arrow-corner-offset)),
+        right: -50% -100%,
+        right-start: calc(var(--#{$prefix}-arrow-width) / -2)
+            calc(
+                var(--#{$prefix}-arrow-width) / 2 - var(--#{$prefix}-arrow-height) +
+                    var(--#{$prefix}-arrow-corner-offset)
+            ),
+        right-end: calc(var(--#{$prefix}-arrow-width) / -2)
+            calc(var(--#{$prefix}-arrow-width) / -2 - var(--#{$prefix}-arrow-corner-offset)),
+        // Deprecated in favor of top-start, will be removed in the next major version
         top-left: var(--#{$prefix}-arrow-corner-offset) 0%,
+        // Deprecated in favor of top-end, will be removed in the next major version
         top-right: calc(-1 * var(--#{$prefix}-arrow-corner-offset)) 0%,
-        bottom: -50% -100%,
+        // Deprecated in favor of bottom-start, will be removed in the next major version
         bottom-left: var(--#{$prefix}-arrow-corner-offset) -100%,
+        // Deprecated in favor of bottom-end, will be removed in the next major version
         bottom-right: calc(-1 * var(--#{$prefix}-arrow-corner-offset)) -100%,
-        left: 50% -100%,
+        // Deprecated in favor of left-start, will be removed in the next major version
         left-top: calc(var(--#{$prefix}-arrow-width) / 2)
             calc(
                 var(--#{$prefix}-arrow-width) / 2 - var(--#{$prefix}-arrow-height) +
                     var(--#{$prefix}-arrow-corner-offset)
             ),
+        // Deprecated in favor of left-end, will be removed in the next major version
         left-bottom: calc(var(--#{$prefix}-arrow-width) / 2)
             calc(var(--#{$prefix}-arrow-width) / -2 - var(--#{$prefix}-arrow-corner-offset)),
-        right: -50% -100%,
+        // Deprecated in favor of right-start, will be removed in the next major version
         right-top: calc(var(--#{$prefix}-arrow-width) / -2)
             calc(
                 var(--#{$prefix}-arrow-width) / 2 - var(--#{$prefix}-arrow-height) +
                     var(--#{$prefix}-arrow-corner-offset)
             ),
+        // Deprecated in favor of right-end, will be removed in the next major version
         right-bottom: calc(var(--#{$prefix}-arrow-width) / -2)
             calc(var(--#{$prefix}-arrow-width) / -2 - var(--#{$prefix}-arrow-corner-offset))
     );
@@ -88,25 +146,41 @@ $_placement-inverse-map: (
 @function -get-child-translate-map($prefix) {
     @return (
         top: var(--#{$prefix}-offset-orthogonal, -50%) calc(-1 * var(--#{$prefix}-offset, 0)),
+        top-start: var(--#{$prefix}-offset-orthogonal, 0) calc(-1 * var(--#{$prefix}-offset, 0)),
+        top-end: var(--#{$prefix}-offset-orthogonal, 0) calc(-1 * var(--#{$prefix}-offset, 0)),
+        bottom: var(--#{$prefix}-offset-orthogonal, -50%) var(--#{$prefix}-offset, 0),
+        bottom-start: var(--#{$prefix}-offset-orthogonal, 0) var(--#{$prefix}-offset, 0),
+        bottom-end: var(--#{$prefix}-offset-orthogonal, 0) var(--#{$prefix}-offset, 0),
+        left: calc(-1 * var(--#{$prefix}-offset, 0)) var(--#{$prefix}-offset-orthogonal, -50%),
+        left-start: calc(-1 * var(--#{$prefix}-offset, 0)) var(--#{$prefix}-offset-orthogonal, 0),
+        left-end: calc(-1 * var(--#{$prefix}-offset, 0)) var(--#{$prefix}-offset-orthogonal, 0),
+        right: var(--#{$prefix}-offset, 0) var(--#{$prefix}-offset-orthogonal, -50%),
+        right-start: var(--#{$prefix}-offset, 0) var(--#{$prefix}-offset-orthogonal, 0),
+        right-end: var(--#{$prefix}-offset, 0) var(--#{$prefix}-offset-orthogonal, 0),
+        // Deprecated in favor of top-start, will be removed in the next major version
         top-left: var(--#{$prefix}-offset-orthogonal, 0) calc(-1 * var(--#{$prefix}-offset, 0)),
+        // Deprecated in favor of top-end, will be removed in the next major version
         top-right: var(--#{$prefix}-offset-orthogonal, 0) calc(-1 * var(--#{$prefix}-offset, 0)),
-        bottom: var(--#{$prefix}-offset-orthogonal, -50%) var(--#{$prefix}-offset, 0),
+        // Deprecated in favor of bottom-start, will be removed in the next major version
         bottom-left: var(--#{$prefix}-offset-orthogonal, 0) var(--#{$prefix}-offset, 0),
+        // Deprecated in favor of bottom-end, will be removed in the next major version
         bottom-right: var(--#{$prefix}-offset-orthogonal, 0) var(--#{$prefix}-offset, 0),
-        left: calc(-1 * var(--#{$prefix}-offset, 0)) var(--#{$prefix}-offset-orthogonal, -50%),
+        // Deprecated in favor of left-start, will be removed in the next major version
         left-top: calc(-1 * var(--#{$prefix}-offset, 0)) var(--#{$prefix}-offset-orthogonal, 0),
+        // Deprecated in favor of left-end, will be removed in the next major version
         left-bottom: calc(-1 * var(--#{$prefix}-offset, 0)) var(--#{$prefix}-offset-orthogonal, 0),
-        right: var(--#{$prefix}-offset, 0) var(--#{$prefix}-offset-orthogonal, -50%),
+        // Deprecated in favor of right-start, will be removed in the next major version
         right-top: var(--#{$prefix}-offset, 0) var(--#{$prefix}-offset-orthogonal, 0),
+        // Deprecated in favor of right-end, will be removed in the next major version
         right-bottom: var(--#{$prefix}-offset, 0) var(--#{$prefix}-offset-orthogonal, 0)
     );
 }
 
 // Function to return an inverse placement name
 // Example: inverse('top') will return 'bottom'
-// Example: inverse('top-left') will return 'bottom-right'
-// Example: inverse('top-left', true) will return 'bottom-left'
-// Example: inverse('top-left', true, false) will return 'bottom left'
+// Example: inverse('top-start') will return 'bottom'
+// Example: inverse('top-start', true) will return 'bottom-start'
+// Example: inverse('top-start', true, false) will return 'bottom start'
 @function inverse($placement, $main-axis-only: false, $hyphenate: true) {
     $hyphen: '-';
     $placement-chunks: string.split($placement, $hyphen);
@@ -146,10 +220,17 @@ $_placement-inverse-map: (
     transform-origin: string.unquote(inverse($placement, $hyphenate: false));
 }
 
-@mixin child-controlled($prefix) {
+@mixin child-controlled($prefix, $offset: 0) {
     --#{$prefix}-offset-orthogonal: 0; // 2.
 
     inset: unset; // 2.
+
+    // @deprecated This condition is deprecated because in the next major version offset will be always set
+    @if $offset != 0 {
+        --#{$prefix}-offset: #{$offset}; // 2.
+
+        translate: unset; // 2.
+    }
 }
 
 @mixin arrow($prefix, $width, $height, $corner-offset) {
@@ -166,3 +247,9 @@ $_placement-inverse-map: (
     translate: map.get(-get-arrow-translate-map($prefix), $placement); // 1.3
     rotate: z map.get($_arrow-rotate-map, $placement);
 }
+
+@mixin arrow-controlled() {
+    inset: unset; // 2.
+    translate: unset; // 2.
+    transform-origin: center; // 2.
+}