chore(docs): add CSS-only stepper docs

.changeset/shaggy-weeks-grab.md

@@ -0,0 +1,5 @@
+---
+'@swisspost/design-system-documentation': minor
+---
+
+Added documentation for the CSS-only stepper and deprecated the stepper based on ng-bootstrap progress bar.

packages/documentation/src/stories/components/stepper/stepper.docs.mdx

@@ -1,56 +1,47 @@
-import { Meta, Source } from '@storybook/blocks';
-import { PostTabHeader, PostTabPanel, PostTabs } from '@swisspost/design-system-components-react';
-import StylesPackageImport from '@/shared/styles-package-import.mdx';
+import { Canvas, Controls, Meta } from '@storybook/blocks';
 import PostComponentDemoLink from '@/shared/post-component-demo-link.mdx';
-import NgbComponentImport from '@/shared/nb-bootstrap/ngb-component-import.mdx';
-import * as stepperStories from './stepper.stories';
-import stepperTemplate from './stepper-template.sample.html?raw';
-import stepperComponent from './stepper-component.sample?raw';
+import StylesPackageImport from '@/shared/styles-package-import.mdx';
+import * as StepperStories from './stepper.stories';
 
-<Meta of={stepperStories} />
+<Meta of={StepperStories} />
 
 <div className="docs-title">
   # Stepper
 
   <nav>
-    <link-design of={JSON.stringify(stepperStories)}></link-design>
-    <PostComponentDemoLink component="stepper" />
+    <link-design of={JSON.stringify(StepperStories)}></link-design>
   </nav>
 </div>
 
-<p className="lead">Conveys progress through numbered steps.</p>
+<p className="lead">The stepped progression component provides an interactive visual overview a process. It shows at a glance the amount of steps a user is required to go trough, and serves as a guide for each step, indicating its status.</p>
+
+<div className="alert alert-warning mb-bigger-big">
+  <p className="alert-heading">The stepper previously used ng-bootstrap's progressbar component, this has been deprecated in favor of the CSS-only stepper documented below.</p>
+  <div className="d-flex justify-content-end"><PostComponentDemoLink component="stepper" /></div>
+</div>
 
-<div className="alert alert-info mb-bigger-big">
-  <p className="alert-heading">The stepper uses ng-bootstrap's progressbar component.</p>
+<Canvas sourceState="shown" of={StepperStories.Default} />
+<div className="hide-col-default">
+  <Controls of={StepperStories.Default} />
 </div>
 
-<ul>
-  <li>
-    <a href="#component-import" target="_self">Component Import</a>
-  </li>
-  <li>
-    <a href="#style-imports" target="_self">Style Imports</a>
-  </li>
-  <li>
-    <a href="#example" target="_self">Example</a>
-  </li>
-</ul>
+<StylesPackageImport components={['stepper']} />
+
+## Examples
+
+### Navigational Stepper
 
-<NgbComponentImport module="NgbProgressbarModule" />
+You can use a stepper to allow users to navigate to specific steps.
+To do so, use `a` elements for the `.stepper-link` of the steps you want to be navigable, and use `span` for the step you want not to be navigable.
+Then, wrap the stepper inside a `<nav>`.
 
-<StylesPackageImport components={["progress", "stepper"]} />
+However, it is better not to use an `a` for the current step since the user is already on the page.
 
-## Example
+<Canvas of={StepperStories.NavigationalStepper} />
 
-<PostTabs>
-  <PostTabHeader slot="tabs" panel="template">template.html</PostTabHeader>
-  <PostTabPanel name="template">
-    <Source code={stepperTemplate} language="html"/>
-  </PostTabPanel>
+### Informational Stepper
 
-  <PostTabHeader slot="tabs" panel="component">component.ts</PostTabHeader>
-  <PostTabPanel name="component">
-    <Source code={stepperComponent} language="typescript"/>
-  </PostTabPanel>
-</PostTabs>
+If you wish to display the stepper for informational purposes only, you can use `<span>` elements for the `.stepper-link` on all the steps.
+In this case, there's no need to wrap the stepper inside a `<nav>`.
 
+<Canvas of={StepperStories.InformationalStepper} />

packages/documentation/src/stories/components/stepper/stepper.stories.ts

@@ -1,22 +1,134 @@
-import type { StoryObj } from '@storybook/web-components';
+import { Args, StoryObj } from '@storybook/web-components';
 import { html } from 'lit';
 import { MetaComponent } from '@root/types';
+import { ifDefined } from 'lit/directives/if-defined.js';
+import { useArgs } from '@storybook/preview-api';
+
+const steps = ['Sender', 'Product', 'Other details', 'Order summary'];
 
 const meta: MetaComponent = {
   id: '7dc546d9-e248-4d06-befe-3ad62fcd310f',
   title: 'Components/Stepper',
   tags: ['package:Angular'],
+  render: renderStepper,
   parameters: {
     badges: [],
     design: {
       type: 'figma',
       url: 'https://www.figma.com/file/xZ0IW0MJO0vnFicmrHiKaY/Components-Post?type=design&node-id=20952-29106&mode=design&t=38qLaYwWdirTcHdb-4',
     },
   },
+  args: {
+    currentStepNumber: 3,
+    navigableSteps: 'all',
+    processName: 'Registration Form',
+  },
+  argTypes: {
+    navigableSteps: {
+      name: 'Navigable Steps',
+      description: 'Defines which steps in the current process the user can navigate to.',
+      control: {
+        type: 'radio',
+        labels: {
+          all: 'All steps',
+          completedOnly: 'Completed Steps only',
+          none: 'None',
+        },
+      },
+      options: ['all', 'completedOnly', 'none'],
+      table: {
+        category: 'General',
+      },
+    },
+    currentStepNumber: {
+      name: 'Current Step Number',
+      description: 'The number of the step the user is currently at in the process.',
+      control: {
+        type: 'select',
+      },
+      options: Object.keys(steps).map(key => parseInt(key, 10) + 1),
+      table: {
+        category: 'General',
+      },
+    },
+    processName: {
+      name: 'Process Name',
+      description:
+        'A straightforward, self-explanatory name for the current process, used for assistive technologies.',
+      control: {
+        type: 'text',
+      },
+      table: {
+        category: 'General',
+      },
+    },
+  },
 };
-
 export default meta;
 
-export const Default: StoryObj = {
-  render: () => html``,
+// RENDERER
+function getStepperItem(args: Args, step: string, index: number) {
+  const currentStepIndex = args.currentStepNumber - 1;
+  const isCompletedStep = index < currentStepIndex;
+  const isCurrentStep = index === currentStepIndex;
+  const isNextStep = index > currentStepIndex;
+  const isLink =
+    (isCompletedStep && args.navigableSteps !== 'none') ||
+    (isNextStep && args.navigableSteps === 'all');
+
+  let status = 'Current';
+  if (isCompletedStep) status = 'Completed';
+  if (isNextStep) status = 'Next';
+
+  const text = html`<span class="visually-hidden">${status} step:</span> ${step}`;
+
+  return html`
+    <li aria-current=${ifDefined(isCurrentStep ? 'step' : undefined)} class="stepper-item">
+      ${isLink
+        ? html` <a class="stepper-link" href="../step-${index + 1}"> ${text} </a> `
+        : html`<span class="stepper-link">${text}</span>`}
+    </li>
+  `;
+}
+
+function renderStepper(args: Args) {
+  const [_, updateArgs] = useArgs();
+
+  setTimeout(() => {
+    const stepperLinks = document.querySelectorAll('.stepper-link');
+    stepperLinks.forEach((link, index) => {
+      if (link.tagName === 'SPAN') return;
+
+      link.addEventListener('click', e => {
+        e.preventDefault();
+        updateArgs({ currentStepNumber: index + 1 });
+      });
+    });
+  });
+
+  const isNav = args.navigableSteps !== 'none';
+  const stepper = html`<ol
+    class="stepper"
+    aria-label=${ifDefined(isNav ? undefined : args.processName + ' Progress')}
+  >
+    ${steps.map((step, index) => getStepperItem(args, step, index))}
+  </ol>`;
+
+  return args.navigableSteps === 'none'
+    ? stepper
+    : html` <nav aria-label="${args.processName}">${stepper}</nav> `;
+}
+
+export const Default: StoryObj = {};
+
+export const NavigationalStepper: StoryObj = {
+  args: {
+    navigableSteps: 'completedOnly',
+  },
+};
+
+export const InformationalStepper: StoryObj = {
+  args: {
+    navigableSteps: 'none',
+  },
 };

packages/styles/src/components/stepper.scss

@@ -71,7 +71,15 @@
   // stepper indicator
   &::before {
     counter-increment: step-index;
-    content: counter(step-index);
+
+    @supports (content: 'x' / 'y') {
+      content: counter(step-index) / '';
+    }
+
+    @supports not (content: 'x' / 'y') {
+      content: counter(step-index);
+    }
+
     display: flex;
     align-items: center;
     justify-content: center;