feat(docs, styles): improve position utilities. (#6002)

## 📄 Description

The _position_ utility classes allow defining the inset of an element.
The classes available are
- top-[position]
- bottom-[position]
- start-[position]
- end-[position]

where [position] can be 0, 50, or 100.

The goal was to improve these _position_ utilities and their
documentation by:

- `inline-*` and `block-*` properties: Replaced `top`, `bottom`, `right`
and `left` with
`inset-block-start`, `inset-block-end`, `inset-inline-start` and
`inset-inline-end`.
- Added a control for the `bottom-*` and `end-* classes` in the
_position_ utility documentation.

Consequently classes for `bottom` and `end` were added to the SCSS
variables on styles.

---------

Co-authored-by: Alona Zherdetska <[email protected]>

Author: bucknatt

.changeset/busy-lines-pick.md

@@ -0,0 +1,9 @@
+---
+'@swisspost/design-system-documentation': minor
+'@swisspost/design-system-styles': minor
+---
+
+Added missing `bottom` and `end` controls to position utilities for complete configuration. 
+Replaced empty label option with `unset` for better clarity across all position controls (`top`, `bottom`, `start`, `end`). 
+Position utilities now use logical CSS inset properties (inset-block-start, inset-block-end, inset-inline-start, inset-inline-end). 
+This means `start` and `end` follow the writing direction — left in LTR and right in RTL.

.gitignore

@@ -31,4 +31,7 @@ styles/stylelint-report.txt
 .netlify
 
 # Turborepo
-.turbo
+.turbo
+
+# Intellij IDEA
+.idea

packages/documentation/src/stories/utilities/position/position.stories.ts

@@ -9,8 +9,10 @@ const meta: MetaExtended = {
   title: 'Utilities/Position',
   args: {
     position: 'absolute',
-    start: '50',
     top: '0',
+    bottom: 'unset',
+    start: '50',
+    end: 'unset',
     translateMiddle: 'both',
   },
   argTypes: {
@@ -31,90 +33,83 @@ const meta: MetaExtended = {
       control: {
         type: 'select',
       },
-      options: ['', '0', '50', '100'],
+      options: ['unset', '0', '50', '100'],
       table: {
         category: 'General',
       },
-      if: {
-        arg: 'bottom',
-        truthy: false,
-      },
     },
     bottom: {
       name: 'Bottom',
       description: 'Sets the distance from bottom. ',
       control: {
         type: 'select',
       },
-      options: ['', '0', '50', '100'],
+      options: ['unset', '0', '50', '100'],
       table: {
         category: 'General',
       },
-      if: {
-        arg: 'top',
-        truthy: false,
-      },
     },
     start: {
       name: 'Start',
       description: 'Sets the distance from start (left in LTR). ',
       control: {
         type: 'select',
       },
-      options: ['', '0', '50', '100'],
+      options: ['unset', '0', '50', '100'],
       table: {
         category: 'General',
       },
-      if: {
-        arg: 'end',
-        truthy: false,
-      },
     },
     end: {
       name: 'End',
       description: 'Sets the distance from end (right in LTR). ',
       control: {
         type: 'select',
       },
-      options: ['', '0', '50', '100'],
+      options: ['unset', '0', '50', '100'],
       table: {
         category: 'General',
       },
-      if: {
-        arg: 'start',
-        truthy: false,
-      },
     },
     translateMiddle: {
       name: 'Translate middle',
       description: 'Set to true to center align an element based on its x and y position.',
       control: {
         type: 'select',
       },
-      options: ['', 'both', 'x', 'y'],
+      options: ['unset', 'both', 'x', 'y'],
       table: {
         category: 'General',
       },
     },
   },
   render: (args: Args) => {
-    let translateMiddleValue = '';
+    let classes = '';
+    if (args.start !== 'unset') {
+      classes += ' start-' + args.start;
+    }
+
+    if (args.end !== 'unset') {
+      classes += ' end-' + args.end;
+    }
+
+    if (args.top !== 'unset') {
+      classes += ' top-' + args.top;
+    }
+
+    if (args.bottom !== 'unset') {
+      classes += ' bottom-' + args.bottom;
+    }
+
     if (args.translateMiddle === 'both') {
-      translateMiddleValue = ' translate-middle';
+      classes += ' translate-middle';
     } else if (args.translateMiddle === 'x') {
-      translateMiddleValue = ' translate-middle-x';
+      classes += ' translate-middle-x';
     } else if (args.translateMiddle === 'y') {
-      translateMiddleValue = ' translate-middle-y';
+      classes += ' translate-middle-y';
     }
-    return html`
-      <div
-        class="my-element position-${args.position} ${args.top
-          ? 'top-' + args.top
-          : ''}${args.bottom ? 'bottom-' + args.bottom : ''} ${args.start
-          ? 'start-' + args.start
-          : ''}${args.end ? 'end-' + args.end : ''}${translateMiddleValue}"
-      ></div>
-    `;
+
+    return html` <div class="my-element position-${args.position}${classes}"></div> `;
   },
 };
 
@@ -124,23 +119,22 @@ type Story = StoryObj;
 
 export const Default: Story = {
   decorators: [
-    (story, context) =>
-      html`
-        <div class="position-outer-container position-outer-container-${context.args.position}">
-          ${context.args.position === 'fixed'
-            ? html`<img src="../images/browser-bg-top.png" />`
-            : ''}
-          <div class="position-container position-relative">
-            ${story()}
-            ${bombArgs({
-              start: ['0', '50', '100'],
-              top: ['0', '50', '100'],
-            }).map(
-              args => html` <div class="pos-element top-${args.top} start-${args.start}"></div> `,
-            )}
-          </div>
+    (story, context) => html`
+      <div class="position-outer-container position-outer-container-${context.args.position}">
+        ${context.args.position === 'fixed' ? html`<img src="../images/browser-bg-top.png" />` : ''}
+        <div class="position-container position-relative">
+          ${story()}
+          ${bombArgs({
+            start: ['0', '50', '100'],
+            bottom: ['0', '50', '100'],
+            top: ['0', '50', '100'],
+            end: ['0', '50', '100'],
+          }).map(
+            args => html` <div class="pos-element top-${args.top} start-${args.start}"></div> `,
+          )}
         </div>
-      `,
+      </div>
+    `,
   ],
 };
 
@@ -149,7 +143,7 @@ export const TranslateMiddle: Story = {
     story => html` <div class="translate-middle-container position-relative">${story()}</div> `,
   ],
   render: () => {
-    return html`<div class="position-absolute start-50 top-50"></div>
+    return html` <div class="position-absolute start-50 top-50"></div>
       <div class="position-absolute start-50 top-50 translate-middle"></div>`;
   },
 };

packages/documentation/src/stories/utilities/position/position.styles.scss

@@ -61,9 +61,16 @@
 
     .my-element {
       background: post.$yellow;
+      min-width: 2rem;
+      min-height: 2rem;
+      border-radius: post.$border-radius;
+    }
+
+    .position-relative & {
       width: 2rem;
       height: 2rem;
-      border-radius: post.$border-radius;
+      min-width: unset;
+      min-height: unset;
     }
   }
 

packages/styles/src/utilities/_variables.scss

@@ -446,20 +446,22 @@ $utilities: (
     values: static relative absolute fixed sticky,
   ),
   'top': (
-    property: top,
+    property: inset-block-start,
+    class: top,
     values: $position-values,
   ),
   'bottom': (
-    property: bottom,
+    property: inset-block-end,
+    class: bottom,
     values: $position-values,
   ),
   'start': (
-    property: left,
+    property: inset-inline-start,
     class: start,
     values: $position-values,
   ),
   'end': (
-    property: right,
+    property: inset-inline-end,
     class: end,
     values: $position-values,
   ),