Added a vertical stepper component.

Author: Kemal Pajevic

libs/designsystem/shared/src/translation/translation.interface.ts

@@ -12,4 +12,7 @@ export interface Translation {
   characters: string;
   outOf: string;
   entered: string;
+  stepCompleted: string;
+  stepInProgress: string;
+  stepPending: string;
 }

libs/designsystem/shared/src/translation/translations/da.ts

@@ -14,4 +14,7 @@ export const da: Translation = {
   characters: 'Tegn',
   outOf: 'af',
   entered: 'indtastet',
+  stepCompleted: 'Gennemført',
+  stepInProgress: 'I gang',
+  stepPending: 'Afventer',
 };

libs/designsystem/shared/src/translation/translations/de.ts

@@ -14,4 +14,7 @@ export const de: Translation = {
   characters: 'Zeichen',
   outOf: 'von',
   entered: 'eingegeben',
+  stepCompleted: 'Abgeschlossen',
+  stepInProgress: 'In Bearbeitung',
+  stepPending: 'Ausstehend',
 };

libs/designsystem/shared/src/translation/translations/en.ts

@@ -14,4 +14,7 @@ export const en: Translation = {
   characters: 'Characters',
   outOf: 'out of',
   entered: 'entered',
+  stepCompleted: 'Completed',
+  stepInProgress: 'In progress',
+  stepPending: 'Pending',
 };

libs/extensions/angular/vertical-stepper/ng-package.json

@@ -0,0 +1,5 @@
+{
+  "lib": {
+    "entryFile": "src/index.ts"
+  }
+}

libs/extensions/angular/vertical-stepper/src/index.ts

@@ -0,0 +1,2 @@
+export { VerticalStepperComponent } from './vertical-stepper.component';
+export { VerticalStepperStep } from './vertical-stepper.types';

libs/extensions/angular/vertical-stepper/src/vertical-stepper.component.html

@@ -0,0 +1,27 @@
+<ol class="steps">
+  @for (step of stepStates(); track step.title; let i = $index) {
+    <li
+      class="step"
+      [class.completed]="step.completed"
+      [class.active]="step.active"
+      [class.has-description]="step.description"
+      [attr.aria-labelledby]="'step-title-' + i"
+      [attr.aria-describedby]="'step-status-' + i"
+    >
+      <span class="kirby-visually-hidden" [id]="'step-status-' + i">
+        {{ statusLabel(step) }}
+      </span>
+      <div class="status">
+        <kirby-icon name="verify" size="sm"></kirby-icon>
+      </div>
+      <div class="text">
+        <p [id]="'step-title-' + i" class="title kirby-text-normal">
+          {{ step.title }}
+        </p>
+        @if (step.description) {
+          <p class="description kirby-text-xsmall">{{ step.description }}</p>
+        }
+      </div>
+    </li>
+  }
+</ol>

libs/extensions/angular/vertical-stepper/src/vertical-stepper.component.scss

@@ -0,0 +1,117 @@
+$status-size: var(--kirby-spacing-l);
+$status-margin-end: var(--kirby-spacing-s);
+$line-width: 1px;
+
+:host {
+  display: block;
+
+  // Allows the step indicators to blend into the surrounding surface. Override if placed on a non-default background.
+  --kirby-x-vertical-stepper-background-color: var(--kirby-white);
+}
+
+.title {
+  font-weight: var(--kirby-font-weight-bold);
+  margin-bottom: 0;
+}
+
+.description {
+  margin-bottom: 0;
+  white-space: pre-wrap;
+}
+
+.status {
+  flex: 1 1 calc(#{$status-size} + #{$status-margin-end});
+  height: $status-size;
+  max-width: $status-size;
+  margin-inline-end: $status-margin-end;
+  border-radius: var(--kirby-border-radius-circle);
+  border: solid $line-width var(--kirby-medium);
+  background-color: var(--kirby-x-vertical-stepper-background-color);
+  display: flex;
+  justify-content: center;
+  align-items: center;
+
+  > * {
+    display: none;
+  }
+}
+
+ul > li,
+ol > li {
+  margin: 0;
+}
+
+.steps {
+  list-style: none;
+  padding: 0;
+  color: var(--kirby-text-color-semi-dark);
+
+  .step {
+    position: relative;
+    display: flex;
+    align-items: center;
+    flex-wrap: wrap;
+
+    &.has-description {
+      align-items: flex-start;
+
+      .text {
+        margin-top: -6px;
+      }
+    }
+
+    > *:not(.status) {
+      flex: 1;
+    }
+  }
+
+  .step:not(:last-child) {
+    padding-bottom: var(--kirby-spacing-m);
+
+    // Line between the steps
+    &::before {
+      content: '';
+      position: absolute;
+      border-inline-start: $line-width dashed var(--kirby-semi-dark);
+      height: 100%;
+      top: 50%;
+      inset-inline-start: calc(#{$status-size} * 0.5);
+      z-index: -1;
+    }
+
+    &.completed::before {
+      border-inline-start: $line-width solid var(--kirby-black);
+    }
+
+    &.has-description::before {
+      top: 0;
+    }
+  }
+}
+
+.step.completed,
+.step.active {
+  color: var(--kirby-text-color-black);
+}
+
+.step.completed .status {
+  background-color: var(--kirby-x-vertical-stepper-background-color);
+  border-color: var(--kirby-x-vertical-stepper-background-color);
+
+  kirby-icon {
+    display: flex;
+  }
+}
+
+.step.active .status {
+  background-color: var(--kirby-black);
+  border-color: var(--kirby-black);
+
+  &::after {
+    content: '';
+    width: calc(#{$status-size} * 0.2);
+    height: calc(#{$status-size} * 0.2);
+    background-color: var(--kirby-white);
+    border-radius: var(--kirby-border-radius-circle);
+  }
+}

libs/extensions/angular/vertical-stepper/src/vertical-stepper.component.spec.ts

@@ -0,0 +1,82 @@
+import { createHostFactory, SpectatorHost } from '@ngneat/spectator/jest';
+import { VerticalStepperComponent } from './vertical-stepper.component';
+import { VerticalStepperStep } from './vertical-stepper.types';
+
+describe('VerticalStepperComponent', () => {
+  let spectator: SpectatorHost<VerticalStepperComponent>;
+  const createHost = createHostFactory({
+    component: VerticalStepperComponent,
+  });
+
+  const steps: VerticalStepperStep[] = [
+    { title: 'Horse', description: '' },
+    { title: 'Dog', description: 'A cosy animal' },
+    { title: 'Mosquito', description: 'An annoying animal' },
+    { title: 'Leopard', description: 'A cool animal' },
+  ];
+
+  function createComponent(activeIndex: number) {
+    spectator = createHost(
+      `<kirby-x-vertical-stepper [steps]="steps" [activeIndex]="activeIndex"></kirby-x-vertical-stepper>`,
+      { hostProps: { steps, activeIndex } }
+    );
+  }
+
+  it('should create', () => {
+    createComponent(0);
+    expect(spectator.component).toBeTruthy();
+  });
+
+  it('should render a step for each item, with title and description', () => {
+    createComponent(0);
+    const titles = spectator.queryAll('.step .title');
+    const descriptions = spectator.queryAll('.step .description');
+
+    expect(titles).toHaveLength(4);
+    expect(titles[0].textContent?.trim()).toEqual('Horse');
+    expect(titles[1].textContent?.trim()).toEqual('Dog');
+
+    // Steps without a description should not render the description element
+    expect(descriptions).toHaveLength(3);
+    expect(descriptions[0].textContent?.trim()).toEqual('A cosy animal');
+  });
+
+  describe('when no steps are completed', () => {
+    beforeEach(() => createComponent(0));
+
+    it('should not have any completed steps', () => {
+      expect(spectator.query('.step.completed')).toBeNull();
+    });
+
+    it('should have the first step active', () => {
+      expect(spectator.query('.step.active .title')?.textContent?.trim()).toEqual('Horse');
+    });
+  });
+
+  describe('when the first step is completed', () => {
+    beforeEach(() => createComponent(1));
+
+    it('should mark the first step as completed', () => {
+      expect(spectator.query('.step.completed .title')?.textContent?.trim()).toEqual('Horse');
+    });
+
+    it('should mark the second step as active', () => {
+      expect(spectator.query('.step.active .title')?.textContent?.trim()).toEqual('Dog');
+    });
+  });
+
+  describe('when the first two steps are completed', () => {
+    beforeEach(() => createComponent(2));
+
+    it('should mark the first two steps as completed', () => {
+      const completedTitles = spectator.queryAll('.step.completed .title');
+      expect(completedTitles).toHaveLength(2);
+      expect(completedTitles[0].textContent?.trim()).toEqual('Horse');
+      expect(completedTitles[1].textContent?.trim()).toEqual('Dog');
+    });
+
+    it('should mark the third step as active', () => {
+      expect(spectator.query('.step.active .title')?.textContent?.trim()).toEqual('Mosquito');
+    });
+  });
+});

libs/extensions/angular/vertical-stepper/src/vertical-stepper.component.stories.ts

@@ -0,0 +1,67 @@
+import { type Meta, type StoryObj } from '@storybook/angular';
+import { VerticalStepperComponent } from '@kirbydesign/extensions-angular/vertical-stepper';
+
+/**
+ * The vertical stepper visualizes progress through a sequential flow, such as an order or onboarding process.
+ * Each step can be pending, active (in progress), or completed.
+ *
+ * ## Usage Guidelines
+ * - Use the vertical stepper to communicate _where_ a user is in a multi-step flow, not to navigate between steps.
+ * - Keep step titles short. Use the optional description to add supporting detail for a step.
+ */
+const meta: Meta<VerticalStepperComponent> = {
+  component: VerticalStepperComponent,
+  title: 'Components/Vertical Stepper',
+  args: {
+    steps: [
+      { title: 'Order received' },
+      { title: 'Processing order', description: 'Your order is being processed.' },
+      { title: 'Order sent', description: 'Your order is on its way to you.' },
+      { title: 'Order delivered' },
+    ],
+    activeIndex: 1,
+  },
+  argTypes: {
+    activeIndex: { control: { type: 'number', min: 0 } },
+  },
+};
+export default meta;
+type Story = StoryObj<VerticalStepperComponent>;
+
+/**
+ * By default, steps before `activeIndex` are shown as completed, the step at `activeIndex` is shown as active/in-progress,
+ * and the remaining steps are shown as pending.
+ */
+export const Default: Story = {};
+
+/**
+ * All steps are shown as pending when `activeIndex` is `0`.
+ */
+export const FirstStepActive: Story = {
+  args: {
+    activeIndex: 0,
+  },
+};
+
+/**
+ * All steps are shown as completed when `activeIndex` is equal to, or greater than, the number of steps.
+ */
+export const AllStepsCompleted: Story = {
+  args: {
+    activeIndex: 4,
+  },
+};
+
+/**
+ * Steps can optionally have a description providing more detail, shown below the title.
+ */
+export const WithoutDescriptions: Story = {
+  args: {
+    steps: [
+      { title: 'Order received' },
+      { title: 'Processing order' },
+      { title: 'Order sent' },
+      { title: 'Order delivered' },
+    ],
+  },
+};