Refactor(web, web-react): Introduce Shape Variant dictionary and use it for NavigationAction

Author: adamkudrna

docs/DICTIONARIES.md

@@ -16,6 +16,7 @@ This project uses `dictionaries` to unify props between different components.
 - [Placement](#placement)
 - [Size](#size)
 - [Validation](#validation)
+- [Variant](#variant)
 
 ### Alignment
 
@@ -81,6 +82,7 @@ This project uses `dictionaries` to unify props between different components.
 
 ### Variant
 
-| Dictionary   | Values            | Code name   |
-| ------------ | ----------------- | ----------- |
-| Fill Variant | `fill`, `outline` | FillVariant |
+| Dictionary    | Values            | Code name    |
+| ------------- | ----------------- | ------------ |
+| Fill Variant  | `fill`, `outline` | FillVariant  |
+| Shape Variant | `box`, `pill`     | ShapeVariant |

packages/web-react/src/components/Navigation/NavigationAction.tsx

@@ -1,16 +1,16 @@
 'use client';
 
 import React, { ElementType, forwardRef, ReactElement } from 'react';
+import { ShapeVariants } from '../../constants';
 import { useStyleProps } from '../../hooks';
 import { PolymorphicRef, SpiritNavigationActionProps } from '../../types';
 import { mergeStyleProps } from '../../utils';
-import { NavigationActionVariants } from './constants';
 import { useNavigationActionProps } from './useNavigationActionProps';
 import { useNavigationStyleProps } from './useNavigationStyleProps';
 
 const defaultProps: Partial<SpiritNavigationActionProps> = {
   elementType: 'a',
-  variant: NavigationActionVariants.BOX,
+  variant: ShapeVariants.BOX,
 };
 
 /* We need an exception for components exported with forwardRef */

packages/web-react/src/components/Navigation/README.md

@@ -34,7 +34,7 @@ it will apply a gap between them.
 | Name        | Type                                                                                       | Default      | Required | Description                   |
 | ----------- | ------------------------------------------------------------------------------------------ | ------------ | -------- | ----------------------------- |
 | `children`  | \[`ReactElement<HTMLLIElement>` \| `ReactElement<NavigationItem>` \| Array of these types] | `null`       | ✓        | Content of the Navigation     |
-| `direction` | [Direction dictionary][direction-dictionary]                                               | `horizontal` | ✕        | Orientation of the Navigation |
+| `direction` | [Direction dictionary][dictionary-direction]                                               | `horizontal` | ✕        | Orientation of the Navigation |
 
 The components accept [additional attributes][readme-additional-attributes].
 If you need more control over the styling of a component, you can use [style props][readme-style-props]
@@ -107,16 +107,16 @@ inherit the height of the `Header`.
 
 ### API
 
-| Name          | Type                              | Default | Required | Description                     |
-| ------------- | --------------------------------- | ------- | -------- | ------------------------------- |
-| `children`    | \[`string` \| `ReactNode`]        | `null`  | ✓        | Content of the NavigationAction |
-| `elementType` | `ElementType`                     | `a`     | ✕        | Type of element used as         |
-| `href`        | `string`                          | -       | ✕        | URL of the link                 |
-| `isDisabled`  | `boolean`                         | `false` | ✕        | Whether the action is disabled  |
-| `isSelected`  | `boolean`                         | `false` | ✕        | Whether the action is selected  |
-| `ref`         | `ForwardedRef<HTMLAnchorElement>` | —       | ✕        | Anchor element reference        |
-| `target`      | `string`                          | `null`  | ✕        | Link target                     |
-| `variant`     | \[`box` \| `pill`]                | `box`   | ✕        | Variant of the NavigationAction |
+| Name          | Type                                           | Default | Required | Description                     |
+| ------------- | ---------------------------------------------- | ------- | -------- | ------------------------------- |
+| `children`    | \[`string` \| `ReactNode`]                     | `null`  | ✓        | Content of the NavigationAction |
+| `elementType` | `ElementType`                                  | `a`     | ✕        | Type of element used as         |
+| `href`        | `string`                                       | -       | ✕        | URL of the link                 |
+| `isDisabled`  | `bool`                                         | `false` | ✕        | Whether the action is disabled  |
+| `isSelected`  | `bool`                                         | `false` | ✕        | Whether the action is selected  |
+| `ref`         | `ForwardedRef<HTMLAnchorElement>`              | —       | ✕        | Anchor element reference        |
+| `target`      | `string`                                       | `null`  | ✕        | Link target                     |
+| `variant`     | [Shape Variant Dictionary][dictionary-variant] | `box`   | ✕        | Variant of the NavigationAction |
 
 The components accept [additional attributes][readme-additional-attributes].
 If you need more control over the styling of a component, you can use [style props][readme-style-props]
@@ -207,7 +207,8 @@ With Buttons:
 </Navigation>
 ```
 
-[direction-dictionary]: https://github.com/lmc-eu/spirit-design-system/blob/main/docs/DICTIONARIES.md#direction
+[dictionary-direction]: https://github.com/lmc-eu/spirit-design-system/blob/main/docs/DICTIONARIES.md#direction
+[dictionary-variant]: https://github.com/lmc-eu/spirit-design-system/tree/main/docs/DICTIONARIES.md#variant
 [readme-additional-attributes]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web-react/README.md#additional-attributes
 [readme-escape-hatches]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web-react/README.md#escape-hatches
 [readme-style-props]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web-react/README.md#style-props

packages/web-react/src/components/Navigation/__tests__/useNavigationStyleProps.test.ts

@@ -1,17 +1,16 @@
 import { renderHook } from '@testing-library/react';
-import { Direction } from '../../../constants';
+import { Direction, ShapeVariants } from '../../../constants';
 import { SpiritNavigationActionProps } from '../../../types';
-import { NavigationActionVariants } from '../constants';
 import { useNavigationStyleProps } from '../useNavigationStyleProps';
 
 const navigationActionVariantDataProvider = [
   {
-    variant: NavigationActionVariants.BOX,
+    variant: ShapeVariants.BOX,
     className: 'NavigationAction--box',
     description: 'box variant',
   },
   {
-    variant: NavigationActionVariants.PILL,
+    variant: ShapeVariants.PILL,
     className: 'NavigationAction--pill',
     description: 'pill variant',
   },
@@ -49,7 +48,7 @@ describe('useNavigationStyleProps', () => {
   );
 
   it('should return pill variant default class', () => {
-    const props = { variant: NavigationActionVariants.PILL };
+    const props = { variant: ShapeVariants.PILL };
     const { result } = renderHook(() => useNavigationStyleProps(props));
 
     expect(result.current.classProps.action).toBe('NavigationAction NavigationAction--pill');

packages/web-react/src/components/Navigation/constants.ts

@@ -1,7 +1,7 @@
 import { Markdown } from '@storybook/blocks';
 import type { Meta, StoryObj } from '@storybook/react';
 import React from 'react';
-import { NavigationActionVariants } from '../constants';
+import { ShapeVariants } from '../../../constants';
 import Navigation from '../Navigation';
 import NavigationAction from '../NavigationAction';
 import NavigationItem from '../NavigationItem';
@@ -30,17 +30,17 @@ const meta: Meta<typeof NavigationAction> = {
     },
     variant: {
       control: 'select',
-      options: [...Object.values(NavigationActionVariants)],
+      options: [...Object.values(ShapeVariants)],
       table: {
-        defaultValue: { summary: NavigationActionVariants.BOX },
+        defaultValue: { summary: ShapeVariants.BOX },
       },
     },
   },
   args: {
     children: 'Link',
     isDisabled: false,
     isSelected: false,
-    variant: NavigationActionVariants.BOX,
+    variant: ShapeVariants.BOX,
   },
 };
 

packages/web-react/src/components/Navigation/stories/NavigationAction.stories.tsx

@@ -1,5 +1,5 @@
 import classNames from 'classnames';
-import { AlignmentYExtended, Direction } from '../../constants';
+import { AlignmentYExtended, Direction, ShapeVariants } from '../../constants';
 import { AlignmentPropertyType, useAlignmentClass, useClassNamePrefix } from '../../hooks';
 import {
   DirectionDictionaryType,
@@ -8,7 +8,6 @@ import {
   SpiritNavigationItemAlignmentYType,
   SpiritNavigationItemProps,
 } from '../../types';
-import { NavigationActionVariants } from './constants';
 
 export interface UseNavigationStyleProps {
   alignmentY?: SpiritNavigationItemAlignmentYType;
@@ -35,7 +34,7 @@ export const useNavigationStyleProps = ({
   isSquare = false,
   alignmentY = AlignmentYExtended.CENTER,
   direction = Direction.HORIZONTAL,
-  variant = NavigationActionVariants.BOX,
+  variant = ShapeVariants.BOX,
   ...restProps
 }: UseNavigationStyleProps): UseNavigationStyleReturn => {
   const navigationClass = useClassNamePrefix('Navigation');

packages/web-react/src/components/Navigation/useNavigationStyleProps.ts

@@ -1,16 +1,15 @@
 import React from 'react';
-import { Direction } from '../../../../constants';
+import { Direction, ShapeVariants } from '../../../../constants';
 import { NavigationActionVariantsType, SpiritNavigationProps } from '../../../../types';
 import { Navigation, NavigationAction, NavigationItem } from '../../../Navigation';
-import { NavigationActionVariants } from '../../../Navigation/constants';
 
 interface MainNavigationProps extends Partial<SpiritNavigationProps> {
   variant?: NavigationActionVariantsType;
 }
 
 export const MainNavigation = ({
   direction = Direction.HORIZONTAL,
-  variant = NavigationActionVariants.BOX,
+  variant = ShapeVariants.BOX,
 }: Partial<MainNavigationProps>) => (
   <Navigation
     aria-label="Main Navigation"

packages/web-react/src/components/UNSTABLE_Header/demo/HeaderWithNavigation/MainNavigation.tsx

@@ -2,7 +2,6 @@ import React, { useState } from 'react';
 import { Container } from '../../Container';
 import { Drawer, DrawerCloseButton, DrawerPanel } from '../../Drawer';
 import { Flex } from '../../Flex';
-import { NavigationActionVariants } from '../../Navigation/constants';
 import { ProductLogo } from '../../ProductLogo';
 import { defaultSvgLogo } from '../../ProductLogo/demo/ProductLogoDefault';
 import { Stack } from '../../Stack';
@@ -26,7 +25,7 @@ const HeaderWithPillNavigation = () => {
             <UNSTABLE_HeaderLogo href="#">
               <ProductLogo>{defaultSvgLogo}</ProductLogo>
             </UNSTABLE_HeaderLogo>
-            <MainNavigation variant={NavigationActionVariants.PILL} />
+            <MainNavigation variant="pill" />
             <SecondaryHorizontalNavigation id="drawer-navigation-pill" handleOpenDrawer={() => setDrawerOpen(true)} />
           </Flex>
         </Container>
@@ -37,7 +36,7 @@ const HeaderWithPillNavigation = () => {
           <DrawerCloseButton />
           <Stack hasIntermediateDividers hasSpacing marginY="space-900" spacing="space-900">
             <ProfileNavigation />
-            <MainNavigation direction="vertical" variant={NavigationActionVariants.PILL} />
+            <MainNavigation direction="vertical" variant="pill" />
             <SecondaryVerticalNavigation />
           </Stack>
         </DrawerPanel>

packages/web-react/src/components/UNSTABLE_Header/demo/HeaderWithPillNavigation.tsx

@@ -138,3 +138,8 @@ export const FillVariants = {
   FILL: 'fill',
   OUTLINE: 'outline',
 } as const;
+
+export const ShapeVariants = {
+  BOX: 'box',
+  PILL: 'pill',
+} as const;

packages/web-react/src/constants/dictionaries.ts

@@ -1,21 +1,20 @@
 import { ElementType, ReactElement, ReactNode } from 'react';
 import { NavigationItem } from '../components';
-import { NavigationActionVariants } from '../components/Navigation/constants';
 import { LinkTarget } from './link';
 import {
   AlignmentYExtendedDictionaryType,
   AriaLabelingProps,
   ChildrenProps,
   DirectionDictionaryType,
+  ShapeVariantDictionaryType,
   SpiritPolymorphicElementPropsWithRef,
   StyleProps,
   TransferProps,
 } from './shared';
 
-export type NavigationActionVariantsKeys = keyof typeof NavigationActionVariants;
-export type NavigationActionVariantsType<T = undefined> =
-  | (typeof NavigationActionVariants)[NavigationActionVariantsKeys]
-  | T;
+type NonNullableShapeVariant = NonNullable<ShapeVariantDictionaryType>;
+
+export type NavigationActionVariantsType = NonNullableShapeVariant | Record<string, NonNullableShapeVariant>;
 
 export interface NavigationActionBaseProps extends ChildrenProps, StyleProps, AriaLabelingProps, TransferProps {
   /** NavigationAction's href attribute */

packages/web-react/src/types/navigation.ts

@@ -3,23 +3,39 @@ import {
   AlignmentXExtended,
   AlignmentY,
   AlignmentYExtended,
+  BackgroundColors,
   BorderColors,
+  BorderRadii,
+  BorderStyles,
+  BorderWidths,
   ComponentButtonColors,
   EmotionColors,
   Emphasis,
   LinkColors,
   Placements,
+  ShapeVariants,
   Sizes,
   SizesExtended,
+  TextAlignments,
   TextColors,
   ValidationStates,
-  BackgroundColors,
-  BorderStyles,
-  BorderRadii,
-  BorderWidths,
-  TextAlignments,
 } from '../../constants';
 
+/**
+ * Allow autocomplete for string literals.
+ *
+ * This is a Typescript quirk.
+ *
+ * @see { @link https://github.com/microsoft/TypeScript/issues/29729}
+ *
+ * When you want to allow any string, but still give suggestions for known string literals.
+ * This works because it prevents TypeScript from eagerly collapsing string | "literal" into just string.
+ * It behaves exactly the same way as string, but with autocomplete added.
+ * Someday, string | "literal" will just work.
+ */
+// eslint-disable-next-line @typescript-eslint/ban-types
+type AutocompleteStringLiteral = string & {};
+
 /* Alignment */
 export type AlignmentXDictionaryKeys = keyof typeof AlignmentX;
 export type AlignmentXDictionaryType<T = undefined> = (typeof AlignmentX)[AlignmentXDictionaryKeys] | T;
@@ -105,3 +121,7 @@ export type ValidationStatesDictionaryKeys = keyof typeof ValidationStates;
 export type ValidationStatesDictionaryType<T = undefined> =
   | (typeof ValidationStates)[ValidationStatesDictionaryKeys]
   | T;
+
+/* Variant */
+export type ShapeVariantDictionaryKeys = keyof typeof ShapeVariants;
+export type ShapeVariantDictionaryType = (typeof ShapeVariants)[ShapeVariantDictionaryKeys] | AutocompleteStringLiteral;

packages/web-react/src/types/shared/dictionaries.ts

@@ -3,6 +3,8 @@
 //    so we need to disable pointer events on it.
 // 3. We want the selected and expanded states to override the hover and active states.
 
+@use '@tokens' as tokens;
+@use '../../tools/dictionaries';
 @use '../../tools/reset';
 @use '../../tools/typography';
 @use 'theme';
@@ -16,7 +18,10 @@
     display: flex;
     gap: theme.$action-gap;
     align-items: center;
+    padding: var(--#{tokens.$css-variable-prefix}navigation-action-padding-y)
+        var(--#{tokens.$css-variable-prefix}navigation-action-padding-x);
     color: theme.$action-color-state-default;
+    border-radius: var(--#{tokens.$css-variable-prefix}navigation-action-border-radius);
     background-color: theme.$action-background-color-state-default;
 
     @media (hover: hover) {
@@ -34,17 +39,28 @@
     }
 }
 
-.NavigationAction--pill {
-    padding-block: theme.$action-pill-padding-y;
-    border-radius: theme.$action-pill-border-radius;
-}
-
 .NavigationAction--box::after {
     content: '';
     position: absolute;
     background-color: theme.$action-stripe-background-color-state-default;
 }
 
+.Navigation--horizontal {
+    @include dictionaries.generate-variants(
+        $class-name: 'NavigationAction',
+        $dictionary-values: theme.$action-shape-variant-dictionary,
+        $config: theme.$horizontal-action-shape-variant-config
+    );
+}
+
+.Navigation--vertical {
+    @include dictionaries.generate-variants(
+        $class-name: 'NavigationAction',
+        $dictionary-values: theme.$action-shape-variant-dictionary,
+        $config: theme.$vertical-action-shape-variant-config
+    );
+}
+
 // stylelint-disable-next-line selector-max-compound-selectors, selector-max-specificity -- 1.
 .Navigation--vertical
     > ul
@@ -72,7 +88,6 @@
     @include typography.generate(theme.$horizontal-action-typography);
 
     justify-content: center;
-    padding-inline: theme.$action-padding-x;
 }
 
 .Navigation--horizontal .NavigationAction--box::after {
@@ -85,7 +100,6 @@
     @include typography.generate(theme.$vertical-action-typography);
 
     justify-content: space-between;
-    padding-block: theme.$vertical-action-spacing-y;
 
     &::after {
         inset-block: 0;
@@ -95,15 +109,6 @@
     }
 }
 
-.Navigation--vertical .NavigationAction--box {
-    padding-inline: theme.$vertical-action-box-padding-x;
-    border-radius: theme.$vertical-action-box-border-radius;
-}
-
-.Navigation--vertical .NavigationAction--pill {
-    padding-inline: theme.$vertical-action-pill-padding-x;
-}
-
 .Navigation--horizontal .NavigationAction--box:hover::after {
     @media (hover: hover) {
         background-color: theme.$horizontal-action-stripe-background-color-state-hover;