Web Docs - Stepper Component

.changeset/four-jokes-wait.md

@@ -0,0 +1,7 @@
+---
+"@hashicorp/design-system-components": minor
+---
+
+`Stepper::List` - Added `Stepper::List` component and related sub-components
+
+`Stepper::Navigation` - Added `Stepper::Navigation` component and related sub-components

packages/components/package.json

@@ -292,6 +292,11 @@
       "./components/hds/side-nav/portal/index.js": "./dist/_app_/components/hds/side-nav/portal/index.js",
       "./components/hds/side-nav/portal/target.js": "./dist/_app_/components/hds/side-nav/portal/target.js",
       "./components/hds/side-nav/toggle-button.js": "./dist/_app_/components/hds/side-nav/toggle-button.js",
+      "./components/hds/stepper/list/index.js": "./dist/_app_/components/hds/stepper/list/index.js",
+      "./components/hds/stepper/list/step.js": "./dist/_app_/components/hds/stepper/list/step.js",
+      "./components/hds/stepper/nav/index.js": "./dist/_app_/components/hds/stepper/nav/index.js",
+      "./components/hds/stepper/nav/panel.js": "./dist/_app_/components/hds/stepper/nav/panel.js",
+      "./components/hds/stepper/nav/step.js": "./dist/_app_/components/hds/stepper/nav/step.js",
       "./components/hds/stepper/step/indicator.js": "./dist/_app_/components/hds/stepper/step/indicator.js",
       "./components/hds/stepper/task/indicator.js": "./dist/_app_/components/hds/stepper/task/indicator.js",
       "./components/hds/table/index.js": "./dist/_app_/components/hds/table/index.js",

packages/components/src/components.ts

@@ -257,6 +257,11 @@ export { default as HdsSideNavPortalTarget } from './components/hds/side-nav/por
 export { default as HdsSideNavToggleButton } from './components/hds/side-nav/toggle-button.ts';
 
 // Stepper
+export { default as HdsStepperList } from './components/hds/stepper/list/index.ts';
+export { default as HdsStepperListStep } from './components/hds/stepper/list/step.ts';
+export { default as HdsStepperNav } from './components/hds/stepper/nav/index.ts';
+export { default as HdsStepperNavPanel } from './components/hds/stepper/nav/panel.ts';
+export { default as HdsStepperNavStep } from './components/hds/stepper/nav/step.ts';
 export { default as HdsStepperStepIndicator } from './components/hds/stepper/step/indicator.ts';
 export { default as HdsStepperTaskIndicator } from './components/hds/stepper/task/indicator.ts';
 export * from './components/hds/stepper/types.ts';

packages/components/src/components/hds/stepper/list/index.hbs

@@ -0,0 +1,17 @@
+{{!
+  Copyright (c) HashiCorp, Inc.
+  SPDX-License-Identifier: MPL-2.0
+}}
+<ol class="hds-stepper-list" aria-label={{@ariaLabel}} ...attributes>
+  {{yield
+    (hash
+      Step=(component
+        "hds/stepper/list/step"
+        titleTag=this.titleTag
+        stepIds=this._stepIds
+        didInsertNode=this.didInsertStep
+        willDestroyNode=this.willDestroyStep
+      )
+    )
+  }}
+</ol>

packages/components/src/components/hds/stepper/list/index.ts

@@ -0,0 +1,52 @@
+/**
+ * Copyright (c) HashiCorp, Inc.
+ * SPDX-License-Identifier: MPL-2.0
+ */
+
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { action } from '@ember/object';
+import { schedule } from '@ember/runloop';
+import type { ComponentLike } from '@glint/template';
+import type { HdsStepperListStepSignature } from './step';
+
+import { HdsStepperTitleTagValues } from '../types.ts';
+import type { HdsStepperTitleTags, HdsStepperListStepIds } from '../types.ts';
+
+export interface HdsStepperListSignature {
+  Args: {
+    titleTag?: HdsStepperTitleTags;
+    ariaLabel: string;
+  };
+  Blocks: {
+    default: [
+      {
+        Step?: ComponentLike<HdsStepperListStepSignature>;
+      },
+    ];
+  };
+  Element: HTMLElement;
+}
+
+export default class HdsStepperList extends Component<HdsStepperListSignature> {
+  @tracked private _stepIds: HdsStepperListStepIds = [];
+
+  get titleTag(): HdsStepperTitleTags {
+    return this.args.titleTag ?? HdsStepperTitleTagValues.Div;
+  }
+
+  @action
+  didInsertStep(element: HTMLElement): void {
+    // eslint-disable-next-line ember/no-runloop
+    schedule('afterRender', (): void => {
+      this._stepIds = [...this._stepIds, element.id];
+    });
+  }
+
+  @action
+  willDestroyStep(element: HTMLElement): void {
+    this._stepIds = this._stepIds.filter(
+      (stepId): boolean => stepId !== element.id
+    );
+  }
+}

packages/components/src/components/hds/stepper/list/step.hbs

@@ -0,0 +1,32 @@
+{{!
+  Copyright (c) HashiCorp, Inc.
+  SPDX-License-Identifier: MPL-2.0
+}}
+<li class={{this.classNames}} ...attributes id={{this._stepId}} {{this._setUpStep @didInsertNode @willDestroyNode}}>
+  <div class="hds-stepper-list__step-progress">
+    <Hds::Stepper::Step::Indicator
+      @text="{{this.stepNumber}}"
+      @status={{this.status}}
+      @isInteractive={{false}}
+      class="hds-stepper-list__step-indicator"
+    />
+  </div>
+  <div class="hds-stepper-list__step-text">
+    <Hds::Text::Body class="hds-stepper-list__step-title" @tag={{this.titleTag}} @size="200" @weight="semibold">
+      {{yield to="title"}}
+      <span class="sr-only">{{this.statusSrOnlyText}}</span>
+    </Hds::Text::Body>
+    <Hds::Text::Body
+      class="hds-stepper-list__step-description"
+      @tag="div"
+      @size="100"
+      @weight="regular"
+      @color="regular"
+    >
+      {{yield to="description"}}
+    </Hds::Text::Body>
+    <div class="hds-stepper-list__step-content">
+      {{yield to="content"}}
+    </div>
+  </div>
+</li>

packages/components/src/components/hds/stepper/list/step.ts

@@ -0,0 +1,96 @@
+/**
+ * Copyright (c) HashiCorp, Inc.
+ * SPDX-License-Identifier: MPL-2.0
+ */
+
+import Component from '@glimmer/component';
+import { assert } from '@ember/debug';
+import { guidFor } from '@ember/object/internals';
+import { modifier } from 'ember-modifier';
+
+import {
+  HdsStepperStatusesValues,
+  HdsStepperTitleTagValues,
+} from '../types.ts';
+import {
+  type HdsStepperStatuses,
+  type HdsStepperTitleTags,
+  type HdsStepperListStepIds,
+  HdsStepperStatusToSrOnlyText,
+} from '../types.ts';
+
+export const DEFAULT_STATUS = HdsStepperStatusesValues.Incomplete;
+export const STATUSES: string[] = Object.values(HdsStepperStatusesValues);
+export const MAPPING_STATUS_TO_SR_ONLY_TEXT = HdsStepperStatusToSrOnlyText;
+
+export interface HdsStepperListStepSignature {
+  Args: {
+    status: HdsStepperStatusesValues;
+    titleTag?: HdsStepperTitleTags;
+    stepIds?: HdsStepperListStepIds;
+    didInsertNode?: (element: HTMLElement) => void;
+    willDestroyNode?: (element: HTMLElement) => void;
+  };
+  Blocks: {
+    title: [];
+    description?: [];
+    content?: [];
+  };
+  Element: HTMLElement;
+}
+
+export default class HdsStepperListStep extends Component<HdsStepperListStepSignature> {
+  private _stepId = 'step-' + guidFor(this);
+
+  private _setUpStep = modifier(
+    (
+      element: HTMLElement,
+      [insertCallbackFunction, destoryCallbackFunction]
+    ) => {
+      if (typeof insertCallbackFunction === 'function') {
+        insertCallbackFunction(element);
+      }
+
+      return () => {
+        if (typeof destoryCallbackFunction === 'function') {
+          destoryCallbackFunction(element);
+        }
+      };
+    }
+  );
+
+  get stepNumber(): number | undefined {
+    return this.args.stepIds
+      ? this.args.stepIds.indexOf(this._stepId) + 1
+      : undefined;
+  }
+
+  get status(): HdsStepperStatuses {
+    const { status = DEFAULT_STATUS } = this.args;
+
+    assert(
+      `@status for "Hds::Stepper::List::Step" must be one of the following: ${STATUSES.join(
+        ', '
+      )}; received: ${status}`,
+      STATUSES.includes(status)
+    );
+
+    return status;
+  }
+
+  get statusSrOnlyText(): string {
+    return MAPPING_STATUS_TO_SR_ONLY_TEXT[this.status];
+  }
+
+  get titleTag(): HdsStepperTitleTags {
+    return this.args.titleTag ?? HdsStepperTitleTagValues.Div;
+  }
+
+  get classNames(): string {
+    const classes = ['hds-stepper-list__step'];
+
+    classes.push(`hds-stepper-list__step--${this.status}`);
+
+    return classes.join(' ');
+  }
+}

packages/components/src/components/hds/stepper/nav/index.hbs

@@ -0,0 +1,76 @@
+{{!
+  Copyright (c) HashiCorp, Inc.
+  SPDX-License-Identifier: MPL-2.0
+}}
+<div
+  class={{this.classNames}}
+  ...attributes
+  {{style --progress-bar-width=this.progressBarWidthStyle}}
+  {{this._setUpStepperNav}}
+>
+  <ol class="hds-stepper-nav__list" aria-label={{@ariaLabel}} role={{if this.isInteractive "tablist"}}>
+    {{#if @steps}}
+      {{#each @steps as |step|}}
+        <Hds::Stepper::Nav::Step
+          @currentStep={{this.currentStep}}
+          @isNavInteractive={{this.isInteractive}}
+          @titleTag={{this.titleTag}}
+          @didInsertNode={{this.didInsertStep}}
+          @willDestroyNode={{this.willDestroyStep}}
+          @stepIds={{this._stepIds}}
+          @panelIds={{this._panelIds}}
+          @onStepChange={{@onStepChange}}
+          @onKeyUp={{this.onKeyUp}}
+        >
+          <:title>{{step.title}}</:title>
+          <:description>{{step.description}}</:description>
+        </Hds::Stepper::Nav::Step>
+      {{/each}}
+    {{else}}
+      {{yield
+        (hash
+          Step=(component
+            "hds/stepper/nav/step"
+            currentStep=this.currentStep
+            isNavInteractive=this.isInteractive
+            titleTag=this.titleTag
+            stepIds=this._stepIds
+            panelIds=this._panelIds
+            didInsertNode=this.didInsertStep
+            willDestroyNode=this.willDestroyStep
+            onStepChange=@onStepChange
+            onKeyUp=this.onKeyUp
+          )
+        )
+      }}
+    {{/if}}
+  </ol>
+  {{#if (and @steps (has-block "body"))}}
+    {{#each @steps}}
+      <Hds::Stepper::Nav::Panel
+        @currentStep={{this.currentStep}}
+        @isNavInteractive={{this.isInteractive}}
+        @stepIds={{this._stepIds}}
+        @panelIds={{this._panelIds}}
+        @didInsertNode={{this.didInsertPanel}}
+        @willDestroyNode={{this.willDestroyPanel}}
+      >
+        {{yield to="body"}}
+      </Hds::Stepper::Nav::Panel>
+    {{/each}}
+  {{else}}
+    {{yield
+      (hash
+        Panel=(component
+          "hds/stepper/nav/panel"
+          currentStep=this.currentStep
+          isNavInteractive=this.isInteractive
+          stepIds=this._stepIds
+          panelIds=this._panelIds
+          didInsertNode=this.didInsertPanel
+          willDestroyNode=this.willDestroyPanel
+        )
+      )
+    }}
+  {{/if}}
+</div>