@crewlethq/ui 0.49.1 → 0.50.0

package/README.md

@@ -204,6 +204,20 @@ places:
 - A surface that pans or zooms dispatches `LAYER_REPOSITION_EVENT` on its host
   when the content beneath it moves, and every panel anchored inside follows.
 
+## Changes in 0.50.0
+
+The pieces of a setup a person walks step by step, first used by the brand setup.
+
+**`SetupWizard` is new**: a page of its own for a setup walked step by step. The header is a `PageHeader` title with the trail above it (`trail`) and the draft's status (`status`) and the way out (`actions`) beside it. The rail is a `nav` named by `stepsLabel`, holding a vertical `Stepper` of `steps` with `current`, `reached` and `onSelect`. The content is a `section` named by the step's `heading`, with a `lead` sentence and the step's fields (`children`) in one column of at most 640px. The optional `aside` is a complementary landmark named by `asideLabel` (required with it), held in view beside the content. The `footer` holds the step's actions at the bottom of the view, above the device's safe area. From 70rem of the wizard's own width the rail, the content and the aside stand side by side (240px, the content, 320px); under that, as in a 1024px window beside the application's rail, the aside moves under the content. Under the phone breakpoint the rail becomes a row of steps under "Step 3 of 6 · Colours" (`labels.progress`) and the aside folds into a disclosure (`labels.asideToggle`, "Preview"). Focus moves to the step's heading when the step changes, and the step's content and the aside start one heading level under it.
+
+**`Stepper` takes `orientation`, a per-step `status` and `description`, and `onSelect`.** `orientation="vertical"` draws a column of rows: a 20px mark per step (the check, the dot, the warning glyph, or the step's number) on a hairline that joins them, the label beside it, and the description and the status words under it, with the current row lifted as the sidebar's is. A step's `status` (`done`, `current`, `upcoming`, `optional` or `attention`) draws it where its position does not say it all: an optional step says "Optional" (`optionalLabel`), and one that needs attention carries the warning glyph on the warning tint and says "Needs attention" (`attentionLabel`); in a row the words are said rather than shown. The current step is always drawn current, and `status: 'current'` on any other step is refused. With `onSelect`, every visited step (the current one, every step before it, and every step up to `reached`) is a button, the current one carrying `aria-current="step"`, and a step not reached yet stays words rather than a disabled button. The horizontal row draws exactly as before; its step-still-to-come class is now `crewlet-stepper__step--upcoming` (it was `--later`).
+
+**`ContrastBadge` takes `advisory`**: under its scale's AA floor the badge reads "Low" in the warning tone with the warning glyph (`crewlet-contrast-badge--low`), rather than "AA large text" or "Fails" in the danger tone, for a pair a person is told about and may keep. A pair that blocks leaves it off and keeps today's behaviour. `labels.levels` now takes any of the level words on its own (`ContrastBadgeLabelsInput`), and the drawn level is typed `ContrastBadgeLevel`.
+
+**`EditingStatus` takes `savedAt`**: with nothing unsaved and no save in flight, the status says how long ago the last save landed (`labels.saved`, "Saved 2m ago"; "Draft · Saved 2m ago" with `labels.editing` "Draft"). The time follows the shared clock and is hidden from the live region, which says "Saved" (`labels.savedSpoken`) once rather than every minute.
+
+**`@crewlethq/tokens` exports `nearestContrastShade(hex, ground, min)`**: the colour nearest `hex` that clears `min` against `ground`, keeping its hue and moving only its OKLab lightness, or `null` when no shade can. `#00baba` on `#f6f7fb` gives `#007f7f` at 4.5:1. It is the one implementation a "Use #007f7f (4.51:1)" suggestion is computed with; see the tokens README.
+
 ## Changes in 0.49.1
 
 **`@crewlethq/tokens` keeps its palettes and its theme registry in modules of their own.** The `themes` object (both palettes, every value) was generated into the same module as `themeRegistry`, `themeGroups`, `DEFAULT_THEME_ID` and `isThemeId`, and a bundler keeps a module whole in the chunk that first needs it: an application that reads the registry at boot (a theme preference) carried every palette value in its entry as soon as any later screen imported `themes` (since 0.47.0, `LogoSlot`), about 8 KB raw and 2 KB gzipped on every first paint of the engine dashboard. `themes` now comes from a module of its own (`dist/palettes.js`), so a consumer of the registry never carries it and the palettes land in the chunk that uses them. The package's exports are unchanged: `import { themes, themeRegistry } from '@crewlethq/tokens'` works as before.

package/dist/ContrastBadge/ContrastBadge.d.ts

@@ -9,6 +9,11 @@ export type ContrastScale = 'body' | 'large';
  * 3:1 but not 4.5:1), or under every floor its scale has.
  */
 export type ContrastLevel = 'aaa' | 'aa' | 'aa-large' | 'fail';
+/**
+ * What the badge draws: a level, or `low`, which an ADVISORY badge draws for
+ * a pair under its scale's AA floor in place of `aa-large` or `fail`.
+ */
+export type ContrastBadgeLevel = ContrastLevel | 'low';
 /**
  * The level a measured ratio reaches, on the floors `@crewlethq/tokens`
  * exports. The ratio is compared UNROUNDED: a pair that passes only once
@@ -27,7 +32,7 @@ export declare function contrastRatio(foreground: string, background: string): n
  */
 export declare function formatContrastRatio(ratio: number): string;
 export interface ContrastBadgeLabels {
-    levels: Record<ContrastLevel, string>;
+    levels: Record<ContrastBadgeLevel, string>;
     /** Said for a pair that cannot be measured (a colour not set yet). */
     unmeasured: string;
     /** The ratio, said in words: "4.49 to 1". */
@@ -35,6 +40,10 @@ export interface ContrastBadgeLabels {
     /** The letters the sample draws the pair with. */
     sample: string;
 }
+/** The words a caller may replace: any of them, and any of the level words. */
+export type ContrastBadgeLabelsInput = Partial<Omit<ContrastBadgeLabels, 'levels'>> & {
+    levels?: Partial<Record<ContrastBadgeLevel, string>> | undefined;
+};
 export interface ContrastBadgeProps {
     /** The colour read: text, a logo, an accent. `#rrggbb`. */
     foreground: string;
@@ -44,8 +53,16 @@ export interface ContrastBadgeProps {
     label?: string | undefined;
     /** What it is read as: body text (the default), or large text and marks. */
     scale?: ContrastScale | undefined;
+    /**
+     * The pair is a warning and never a block: under its scale's AA floor it
+     * reads "Low" in the warning tone, rather than "AA large text" or "Fails"
+     * in the danger tone. For a pair a person is told about and allowed to
+     * keep, such as a brand's primary on its light ground; a pair that blocks
+     * (a brand's text on its light ground) leaves it off and keeps "Fails".
+     */
+    advisory?: boolean | undefined;
     className?: string | undefined;
-    labels?: Partial<ContrastBadgeLabels> | undefined;
+    labels?: ContrastBadgeLabelsInput | undefined;
 }
 /**
  * Whether one colour reads on another: a sample of the pair, the measured
@@ -56,8 +73,13 @@ export interface ContrastBadgeProps {
  * every theme to, and the floors from its `WCAG_CONTRAST`, so the badge an
  * administrator reads and the gate a theme passes never disagree.
  *
+ * BLOCKING OR ADVISORY. By default a pair under every floor "Fails" in the
+ * danger tone. An `advisory` pair is one a person may keep: under its AA
+ * floor it reads "Low" in the warning tone with the warning glyph, so a
+ * screen of pairs tells the one that blocks from the ones that only warn.
+ *
  * THE LEVEL IS A WORD AND A GLYPH, never the tint alone, and the ratio is
  * said as "4.49 to 1" rather than read out as punctuation. The sample is
  * decoration: it shows the pair, and the words say how it measures.
  */
-export declare function ContrastBadge({ foreground, background, label, scale, className, labels }: ContrastBadgeProps): import("react").JSX.Element;
+export declare function ContrastBadge({ foreground, background, label, scale, advisory, className, labels, }: ContrastBadgeProps): import("react").JSX.Element;

package/dist/ContrastBadge/index.d.ts

@@ -1,3 +1,3 @@
 import './ContrastBadge.css';
 export { ContrastBadge, contrastLevel, contrastRatio, formatContrastRatio } from './ContrastBadge.js';
-export type { ContrastBadgeLabels, ContrastBadgeProps, ContrastLevel, ContrastScale } from './ContrastBadge.js';
+export type { ContrastBadgeLabels, ContrastBadgeLabelsInput, ContrastBadgeLevel, ContrastBadgeProps, ContrastLevel, ContrastScale, } from './ContrastBadge.js';

package/dist/ContrastBadge/index.js

@@ -1,4 +1,4 @@
-export { ContrastBadge, contrastLevel, contrastRatio, formatContrastRatio } from '../chunk-B235ANDO.js';
+export { ContrastBadge, contrastLevel, contrastRatio, formatContrastRatio } from '../chunk-NSSOWQCJ.js';
 import '../chunk-KYIAFNU7.js';
 import '../chunk-UZMNR366.js';
 import '../chunk-WIATRXEJ.js';

package/dist/EditingStatus/EditingStatus.d.ts

@@ -1,14 +1,28 @@
+import { type TimeValue } from '../RelativeTime/index.js';
 /** Every string the status draws. */
 export interface EditingStatusLabels {
     editing: string;
     unsaved: string;
     saving: string;
+    /** Shown once the last save landed, with how long ago: "Saved 2 min ago". */
+    saved: (ago: string) => string;
+    /**
+     * Said in its place: the time is shown and not announced, so a screen
+     * reader hears "Saved" when the save lands rather than every minute after.
+     */
+    savedSpoken: string;
 }
 export interface EditingStatusProps {
     /** Whether anything differs from what was opened. */
     dirty: boolean;
     /** Whether a save is in flight. */
     saving?: boolean | undefined;
+    /**
+     * When the last save landed. Given, a status with nothing unsaved and no
+     * save in flight says how long ago: a draft that keeps itself, as a setup
+     * wizard's does ("Draft · Saved 2 min ago" with `labels.editing` "Draft").
+     */
+    savedAt?: TimeValue;
     labels?: Partial<EditingStatusLabels> | undefined;
     className?: string | undefined;
 }
@@ -22,4 +36,4 @@ export interface EditingStatusProps {
  * from saved to unsaved without being interrupted. On a narrow bar the words
  * fold away and the dot stays, named by the same words.
  */
-export declare function EditingStatus({ dirty, saving, labels, className }: EditingStatusProps): import("react").JSX.Element;
+export declare function EditingStatus({ dirty, saving, savedAt, labels, className }: EditingStatusProps): import("react").JSX.Element;

package/dist/EditingStatus/index.js

@@ -1,3 +1,5 @@
-export { EditingStatus } from '../chunk-MULOZYHL.js';
+export { EditingStatus } from '../chunk-MMOXWAUG.js';
+import '../chunk-3CZ7XAVY.js';
+import '../chunk-EUCC37WY.js';
 import '../chunk-BZFWDIV6.js';
 import '../chunk-ODEQTPFM.js';

package/dist/InlineEditor/index.js

@@ -1,5 +1,7 @@
-export { INLINE_EDITOR_LABELS, InlineEditor } from '../chunk-7P336RA5.js';
-import '../chunk-MULOZYHL.js';
+export { INLINE_EDITOR_LABELS, InlineEditor } from '../chunk-QGRA2RHC.js';
+import '../chunk-MMOXWAUG.js';
+import '../chunk-3CZ7XAVY.js';
+import '../chunk-EUCC37WY.js';
 import '../chunk-SMBKXWML.js';
 import '../chunk-OMV5W53A.js';
 import '../chunk-OG6CL3EB.js';

package/dist/LogoSlot/index.js

@@ -1,6 +1,6 @@
-export { LogoSlot } from '../chunk-ITI2Z44C.js';
+export { LogoSlot } from '../chunk-BEAXJARF.js';
 import '../chunk-THDGBD6Y.js';
-import '../chunk-B235ANDO.js';
+import '../chunk-NSSOWQCJ.js';
 import '../chunk-KYIAFNU7.js';
 import '../chunk-UZMNR366.js';
 import '../chunk-WIATRXEJ.js';

package/dist/RichEditor/index.js

@@ -1,4 +1,4 @@
-export { RichEditor, preloadRichEditor } from '../chunk-7PCDKRNB.js';
+export { RichEditor, preloadRichEditor } from '../chunk-JWNYI7UD.js';
 export { RICH_EDITOR_LABELS, richEditorLabels } from '../chunk-CSQTDGTS.js';
 import '../chunk-BAKPMH3S.js';
 import '../chunk-SZZRIHGT.js';

package/dist/SetupWizard/SetupWizard.d.ts

@@ -0,0 +1,77 @@
+import { type HTMLAttributes, type ReactNode } from 'react';
+import { type StepperStep } from '../Stepper/index.js';
+import { type HeadingLevel } from '../utils/headingLevel.js';
+export interface SetupWizardLabels {
+    /** Where the reader is, above the steps on a phone, before the step's name: "Step 3 of 6". */
+    progress: (position: number, total: number) => string;
+    /** The disclosure the aside folds into on a phone: "Preview". */
+    asideToggle: string;
+}
+export interface SetupWizardProps extends Omit<HTMLAttributes<HTMLDivElement>, 'title' | 'onSelect'> {
+    /** What is being set up: "Set up your brand". The page's heading. */
+    title: ReactNode;
+    /**
+     * The title's heading level. It follows the surrounding level by default,
+     * as `PageHeader` does; the step's heading is one level under it, and the
+     * step's own content and the aside start one level under that.
+     */
+    headingLevel?: HeadingLevel | undefined;
+    /** Where the page sits, above the title: a `Breadcrumb` "Company › Brand › Set up". */
+    trail?: ReactNode;
+    /** The draft's state, beside the actions: an `EditingStatus` "Draft saved 2 min ago". */
+    status?: ReactNode;
+    /** What leaves the wizard: Exit. */
+    actions?: ReactNode;
+    /** Every step, in order, as `Stepper` takes them (with a status and a description each where it has one). */
+    steps: readonly StepperStep[];
+    /** The step shown, by its id. */
+    current: string;
+    /** The furthest step visited, by its id, so the steps up to it stay buttons after walking back. `current` by default. */
+    reached?: string | undefined;
+    /** Called with a visited step's id when the reader picks it in the rail. Left out, the rail is words only. */
+    onSelect?: ((id: string) => void) | undefined;
+    /** What the steps are, for the navigation landmark and the list: "Setup steps". */
+    stepsLabel: string;
+    /** The step's heading: "Colours". */
+    heading: ReactNode;
+    /** One sentence under the heading saying why the step matters. */
+    lead?: ReactNode;
+    /** The step's content: its fields. */
+    children: ReactNode;
+    /** Beside the content on a wide page, under it on a narrower one, folded into a disclosure on a phone: a live preview. */
+    aside?: ReactNode;
+    /** What the aside is, for its complementary landmark: "Preview of your draft". Required with `aside`. */
+    asideLabel?: string | undefined;
+    /** The step's actions, held at the bottom of the view: Back, Skip for now, Continue. */
+    footer: ReactNode;
+    labels?: Partial<SetupWizardLabels> | undefined;
+}
+/**
+ * A setup a person walks step by step on a page of its own: a brand, an
+ * integration, a company.
+ *
+ * FIVE PARTS, EACH A LANDMARK OR A HEADING. The header is the page's title
+ * (a `PageHeader`) with the trail above it and the draft's status and the way
+ * out beside it. The rail is a `nav` holding a vertical `Stepper`, with every
+ * visited step a button. The content is a `section` named by the step's
+ * heading, with a lead sentence and the step's fields in one column of at
+ * most 640px. The aside is a complementary landmark named by `asideLabel`,
+ * held in view beside the content. The footer holds the step's actions at the
+ * bottom of the view, above the device's safe area.
+ *
+ * THREE SHAPES. On a wide page the rail, the content and the aside stand side
+ * by side (240px, the content, 320px). Where the wizard has under 70rem of its
+ * own width, which is a 1024px window beside the application's rail, the aside
+ * moves under the content and the rail stays: a container query, because the
+ * room is the page's and not the window's, as in `AsideLayout`. Under the
+ * phone breakpoint the rail becomes a row of steps above the content, under a
+ * line that says "Step 3 of 6 · Colours", and the aside folds into a
+ * disclosure, so the fields come first. Which element a phone draws is decided
+ * in `useMediaMatch`, the one subscription for that question; how it is laid
+ * out is decided in the stylesheet, at the same breakpoint token.
+ *
+ * FOCUS FOLLOWS THE STEP. When the step changes, focus moves to its heading,
+ * so a keyboard or screen reader user starts on the new step rather than on a
+ * Continue button that now belongs to it; the first render takes no focus.
+ */
+export declare function SetupWizard({ title, headingLevel, trail, status, actions, steps, current, reached, onSelect, stepsLabel, heading, lead, children, aside, asideLabel, footer, labels, className, ...rest }: SetupWizardProps): import("react").JSX.Element;

package/dist/SetupWizard/index.d.ts

@@ -0,0 +1,3 @@
+import './SetupWizard.css';
+export { SetupWizard } from './SetupWizard.js';
+export type { SetupWizardLabels, SetupWizardProps } from './SetupWizard.js';

package/dist/SetupWizard/index.js

@@ -0,0 +1,11 @@
+export { SetupWizard } from '../chunk-KKHCUHWS.js';
+import '../chunk-LDGQIDIZ.js';
+import '../chunk-DKB73KZI.js';
+import '../chunk-WIATRXEJ.js';
+import '../chunk-OGXHZHRX.js';
+import '../chunk-FZVJDJFN.js';
+import '../chunk-BHHIIK3M.js';
+import '../chunk-PQADV6P6.js';
+import '../chunk-RTPQDNW3.js';
+import '../chunk-BZFWDIV6.js';
+import '../chunk-ODEQTPFM.js';

package/dist/SetupWizard-Y5BTXZX5.css

@@ -0,0 +1,197 @@
+/*
+ * SetupWizard: a setup walked step by step on a page of its own
+ * (SetupWizard.tsx).
+ *
+ * THE GRID. The header across the top, the footer across the bottom, and
+ * between them the rail (240px), the content (one column, at most 640px) and,
+ * from 70rem of the wizard's own width, the aside (320px). Under 70rem the
+ * aside takes the row under the content and the rail runs down beside both.
+ * Under the phone breakpoint every part is one column, in reading order.
+ */
+
+.crewlet-setup-wizard {
+  container-type: inline-size;
+  min-width: 0;
+}
+
+.crewlet-setup-wizard__frame {
+  display: grid;
+  grid-template-columns: 240px minmax(0, 1fr);
+  grid-template-areas:
+    'head head'
+    'rail content'
+    'rail aside'
+    'foot foot';
+  grid-template-rows: auto auto 1fr auto;
+  column-gap: var(--spacing-8);
+  row-gap: var(--spacing-6);
+  min-width: 0;
+}
+
+.crewlet-setup-wizard__head {
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-2);
+  grid-area: head;
+  min-width: 0;
+}
+
+.crewlet-setup-wizard__status {
+  display: inline-flex;
+  align-items: center;
+}
+
+/*
+ * THE RAIL stays in view while the content scrolls past it, as a column of
+ * the steps a reader can go back to.
+ */
+.crewlet-setup-wizard__rail {
+  position: sticky;
+  top: var(--spacing-5);
+  align-self: start;
+  grid-area: rail;
+  min-width: 0;
+}
+
+.crewlet-setup-wizard__content {
+  display: flex;
+  flex-direction: column;
+  grid-area: content;
+  box-sizing: border-box;
+  width: 100%;
+  max-width: 640px;
+  min-width: 0;
+}
+
+.crewlet-setup-wizard__heading {
+  margin: 0;
+  color: var(--color-text-primary);
+  font-family: var(--font-family-sans);
+  font-size: var(--font-size-lg);
+  font-weight: var(--font-weight-semibold);
+  line-height: var(--font-line-height-tight);
+}
+
+/*
+ * The heading takes focus when the step changes. It keeps the browser's own
+ * focus treatment: after a press nothing is drawn, and after a key the ring
+ * shows where the reader now is.
+ */
+
+.crewlet-setup-wizard__lead {
+  margin: var(--spacing-2) 0 0;
+  max-width: var(--size-measure);
+  color: var(--color-text-secondary);
+  font-family: var(--font-family-sans);
+  font-size: var(--font-size-sm);
+  line-height: var(--font-line-height-body);
+}
+
+.crewlet-setup-wizard__body {
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-6);
+  margin-top: var(--spacing-6);
+  min-width: 0;
+}
+
+/* UNDER THE CONTENT, the aside is set off by one hairline, as AsideLayout's is. */
+.crewlet-setup-wizard__aside {
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-4);
+  grid-area: aside;
+  box-sizing: border-box;
+  max-width: 640px;
+  min-width: 0;
+  padding-top: var(--spacing-6);
+  border-top: 1px solid var(--color-border-default);
+}
+
+/*
+ * THE FOOTER holds the step's actions at the bottom of the view while the
+ * content scrolls under it, on the sheet's own ground with a hairline above,
+ * and clears the device's safe area where it has one.
+ */
+.crewlet-setup-wizard__footer {
+  position: sticky;
+  bottom: 0;
+  z-index: var(--z-index-sticky);
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  justify-content: flex-end;
+  gap: var(--spacing-2);
+  grid-area: foot;
+  padding: var(--spacing-3) 0 calc(var(--spacing-3) + env(safe-area-inset-bottom, var(--spacing-0)));
+  border-top: 1px solid var(--color-border-default);
+  background: var(--color-surface-background);
+}
+
+/* BESIDE THE CONTENT, from 70rem of the wizard's own width: the aside holds in view. */
+@container (min-width: 70rem) {
+  .crewlet-setup-wizard__frame {
+    grid-template-columns: 240px minmax(0, 1fr) 320px;
+    grid-template-areas:
+      'head head head'
+      'rail content aside'
+      'foot foot foot';
+    grid-template-rows: auto 1fr auto;
+  }
+
+  .crewlet-setup-wizard__aside {
+    position: sticky;
+    top: var(--spacing-5);
+    align-self: start;
+    padding-top: 0;
+    border-top: 0;
+  }
+}
+
+/*
+ * ON A PHONE, one column in reading order: where the reader is, the step, the
+ * folded preview, and the actions. The rail is a row of steps under the
+ * position line, and scrolls away with the page rather than covering it.
+ */
+@media (width < 640px) {
+  .crewlet-setup-wizard__frame {
+    grid-template-columns: minmax(0, 1fr);
+    grid-template-areas:
+      'head'
+      'rail'
+      'content'
+      'aside'
+      'foot';
+    grid-template-rows: auto;
+    row-gap: var(--spacing-5);
+  }
+
+  .crewlet-setup-wizard__rail {
+    position: static;
+    display: flex;
+    flex-direction: column;
+    gap: var(--spacing-2);
+  }
+
+  .crewlet-setup-wizard__preview {
+    grid-area: aside;
+    min-width: 0;
+  }
+
+  .crewlet-setup-wizard__preview .crewlet-setup-wizard__aside {
+    padding-top: 0;
+    border-top: 0;
+  }
+}
+
+.crewlet-setup-wizard__position {
+  margin: 0;
+  color: var(--color-text-secondary);
+  font-family: var(--font-family-sans);
+  font-size: var(--font-size-xs);
+  font-weight: var(--font-weight-medium);
+}
+
+.crewlet-setup-wizard__position-step {
+  color: var(--color-text-primary);
+}

package/dist/Stepper/Stepper.d.ts

@@ -12,6 +12,16 @@ import type { Tone } from '../utils/tone.js';
  * but `aria-current`, which nobody sees.
  */
 export type StepperTone = Exclude<Tone, 'neutral'>;
+/**
+ * Where one step stands. `done`, `current` and `upcoming` are what a step's
+ * position against `current` already says; `optional` is a step that may be
+ * skipped and has not been completed, drawn quietly with the word "Optional";
+ * `attention` is a step with something to look at again (a low-contrast pair,
+ * a refused file), drawn with a warning glyph and the words "Needs attention".
+ */
+export type StepperStatus = 'done' | 'current' | 'upcoming' | 'optional' | 'attention';
+/** How the steps are laid out: a row of pills, or a column of rows with a mark each. */
+export type StepperOrientation = 'horizontal' | 'vertical';
 /** One step of the sequence. */
 export interface StepperStep {
     /** What tells two steps apart, unique within the stepper: `execute`, `review`. */
@@ -21,15 +31,26 @@ export interface StepperStep {
      * round 7 of 25", "Context 0.8s".
      */
     label: ReactNode;
+    /**
+     * Where the step stands, when its position does not say it all. Left out,
+     * a step before `current` is `done` and one after it is `upcoming`. The
+     * current step is always drawn current: `attention` or `optional` on it adds
+     * the warning glyph or the word "Optional" to it, and `current` on any other
+     * step is refused, since only `current` names the step under way.
+     */
+    status?: StepperStatus | undefined;
+    /** A line under the label, in the vertical orientation only: "Name and tagline". */
+    description?: ReactNode;
 }
-export interface StepperProps extends Omit<HTMLAttributes<HTMLOListElement>, 'children'> {
+export interface StepperProps extends Omit<HTMLAttributes<HTMLOListElement>, 'children' | 'onSelect'> {
     /** Every step, in order. */
     steps: readonly StepperStep[];
     /**
      * The step under way, by its id. Every step before it is done and every
-     * step after it is still to come. `null` once EVERY step is done, which is
-     * how a finished run is drawn: a turn's history in a task's timeline reads
-     * "Execute ✓ — Review ✓" with nothing current.
+     * step after it is still to come, unless a step's `status` says otherwise.
+     * `null` once EVERY step is done, which is how a finished run is drawn: a
+     * turn's history in a task's timeline reads "Execute ✓, Review ✓" with
+     * nothing current.
      */
     current: string | null;
     /**
@@ -47,32 +68,60 @@ export interface StepperProps extends Omit<HTMLAttributes<HTMLOListElement>, 'ch
      * motion preference.
      */
     pulse?: boolean | undefined;
+    /** A row of pills (the default), or a column of rows, as a setup wizard's rail draws it. */
+    orientation?: StepperOrientation | undefined;
+    /**
+     * Called with a step's id when a reader picks it. Given, every VISITED step
+     * (the current one, every step before it, and every step up to `reached`)
+     * is a button; a step not visited yet stays words, reachable only by
+     * whatever moves the sequence on, never a disabled button that is a tab stop
+     * with nothing behind it.
+     */
+    onSelect?: ((id: string) => void) | undefined;
+    /**
+     * The furthest step a reader has visited, by its id, for a sequence they
+     * can walk back through and forward again: on step 2 after reaching step 5,
+     * steps 3 to 5 are still buttons. `current` by default.
+     */
+    reached?: string | undefined;
     /**
      * Said before a finished step's words, where the check glyph stands for a
      * reader who sees it: "Done Context".
      */
     doneLabel?: string | undefined;
+    /** Said after an optional step's words, and shown under them in the vertical orientation. "Optional" by default. */
+    optionalLabel?: string | undefined;
+    /** Said after the words of a step that needs attention, and shown under them vertically. "Needs attention" by default. */
+    attentionLabel?: string | undefined;
 }
 /**
- * Where a sequence has got to: the phases of a turn, the stages of a run.
+ * Where a sequence has got to: the phases of a turn, the stages of a run, the
+ * steps of a setup a person walks themselves.
  *
  * AN ORDERED LIST, because the order IS the information: a step's position
  * says whether it is behind the current one or ahead of it, and a list says
  * how many there are before a reader has heard any of them. The step under
  * way carries `aria-current="step"`, the one value ARIA gives this exact
  * meaning, and it is on exactly one step while the sequence is running and on
- * none once it has finished.
+ * none once it has finished. When the steps are buttons it is on the button,
+ * which is what a reader focuses and so what tells them.
  *
- * THREE STATES, EACH DRAWN TWO WAYS, so colour is never the only carrier. A
+ * EVERY STATE IS DRAWN TWO WAYS, so colour is never the only carrier. A
  * finished step is the secondary ink with a check, and says "Done" before its
  * words to a screen reader, where the check stands for a reader who sees it.
  * The current step is its tone's soft tint under the tone's ink with the
- * tone's dot, and is `aria-current`. A step still to come is the tertiary ink
- * and nothing else. The hairline round the chips, and the short rule between
- * two of them, are the design's quiet furniture.
+ * tone's dot. A step still to come is the tertiary ink and nothing else; an
+ * optional one says "Optional", and one that needs attention carries the
+ * warning glyph on the warning tint and says "Needs attention".
+ *
+ * TWO ORIENTATIONS. The row is the approved design's pills joined by a short
+ * rule. The column is a setup wizard's rail: a 20px mark per step (the check,
+ * the dot, the warning glyph or the step's number) on a hairline that joins
+ * them, the label beside it, and a description and the status words under
+ * the label.
  *
  * THE TONE IS DRAWN, NEVER SPOKEN: a reader hears which step is current, not
  * that it is in the warning hue. A current step whose state is anything but
  * ordinary work says so in its own words ("Review · sent back").
  */
-export declare function Stepper({ steps, current, label, tone, pulse, doneLabel, className, ...rest }: StepperProps): import("react").JSX.Element | null;
+export declare function Stepper({ steps, current, label, tone, pulse, orientation, onSelect, reached, doneLabel, optionalLabel, attentionLabel, className, ...rest }: StepperProps): import("react").JSX.Element | null;

package/dist/Stepper/index.d.ts

@@ -1,3 +1,3 @@
 import './Stepper.css';
 export { Stepper } from './Stepper.js';
-export type { StepperProps, StepperStep, StepperTone } from './Stepper.js';
+export type { StepperOrientation, StepperProps, StepperStatus, StepperStep, StepperTone } from './Stepper.js';

package/dist/Stepper/index.js

@@ -1,4 +1,4 @@
-export { Stepper } from '../chunk-5QWIJSQM.js';
+export { Stepper } from '../chunk-LDGQIDIZ.js';
 import '../chunk-WIATRXEJ.js';
 import '../chunk-BZFWDIV6.js';
 import '../chunk-ODEQTPFM.js';