@charcuterie/ui 3.5.0 → 3.7.0

package/src/Stepper/Stepper.stories.tsx

@@ -0,0 +1,224 @@
+import type { Meta, StoryObj } from "@storybook/react"
+import { useState } from "react"
+import { Button } from "../Button/Button.tsx"
+import {
+  ContainerBoard,
+  StoryCell,
+  StoryGrid,
+  StorySection,
+} from "../board.storyHelpers.tsx"
+import { Card } from "../Card/Card.tsx"
+import type { Step } from "./Stepper.tsx"
+import { Stepper } from "./Stepper.tsx"
+
+const RIP: Step[] = [
+  {
+    description: "3 of 3 discs read",
+    key: "rip",
+    label: "Rip",
+    status: "done",
+  },
+  {
+    description: "2 of 5 titles tagged",
+    key: "tag",
+    label: "Tag",
+    status: "current",
+  },
+  {
+    description: "Opens when Tag is finished",
+    key: "file",
+    label: "File",
+    status: "upcoming",
+  },
+]
+
+const meta = {
+  title: "Components/Data/Stepper",
+  component: Stepper,
+  parameters: { layout: "padded" },
+  args: {
+    headingLevel: 3,
+    label: "Ingest sequence",
+    orientation: "vertical",
+    steps: RIP,
+  },
+} satisfies Meta<typeof Stepper>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+/**
+ * The marker is the ordinal and never a tick — this library ships
+ * no icons and no symbol glyphs, and a `✓` the font lacks renders
+ * as an empty box in the one position where an empty box reads as
+ * an error.
+ */
+export const Default: Story = {}
+
+export const AllVariants: Story = {
+  render: (stepperProps) => (
+    <StorySection title="Four statuses, two orientations, and the case the component exists for: steps that CARRY something.">
+      <StoryGrid columns={2}>
+        <StoryCell align="stretch" label="vertical">
+          <Stepper {...stepperProps} />
+        </StoryCell>
+
+        <StoryCell
+          align="stretch"
+          label="orientation=horizontal"
+        >
+          <Stepper
+            {...stepperProps}
+            label="Ingest sequence, across"
+            orientation="horizontal"
+          />
+        </StoryCell>
+
+        <StoryCell align="stretch" label="status=blocked">
+          {/* Blocked is not a worse `upcoming`. Its turn HAS come
+              and something is in the way — a thing to go and fix
+              rather than a thing to wait for. */}
+          <Stepper
+            {...stepperProps}
+            label="A sequence held up"
+            steps={[
+              { key: "a", label: "Rip", status: "done" },
+              {
+                description:
+                  "Waiting on Rip, which has no titles yet — add one, or delete the step",
+                key: "b",
+                label: "Tag",
+                status: "blocked",
+              },
+              {
+                key: "c",
+                label: "File",
+                status: "upcoming",
+              },
+            ]}
+          />
+        </StoryCell>
+
+        <StoryCell
+          align="stretch"
+          label="steps that carry content"
+        >
+          <Stepper
+            {...stepperProps}
+            label="A sequence with its work under it"
+            steps={[
+              {
+                content: (
+                  <Card>Read the disc into an ISO</Card>
+                ),
+                key: "a",
+                label: "Rip",
+                status: "done",
+              },
+              {
+                content: <Card>Match each title</Card>,
+                key: "b",
+                label: "Tag",
+                status: "current",
+              },
+            ]}
+          />
+        </StoryCell>
+      </StoryGrid>
+    </StorySection>
+  ),
+}
+
+export const AllStates: Story = {
+  render: (stepperProps) => (
+    <StorySection title="Every status beside every other, so the four are legible as a set rather than one at a time.">
+      <Stepper
+        {...stepperProps}
+        label="Every status"
+        steps={[
+          { key: "a", label: "Done", status: "done" },
+          {
+            key: "b",
+            label: "In progress",
+            status: "current",
+          },
+          { key: "c", label: "Blocked", status: "blocked" },
+          {
+            key: "d",
+            label: "Not started",
+            status: "upcoming",
+          },
+        ]}
+      />
+    </StorySection>
+  ),
+}
+
+/**
+ * `horizontal` is a REQUEST. Below `cq-md` it falls back to the
+ * column, because four steps side by side in a narrow container
+ * squash into `2. / De- / dupe` — measured, in the app this
+ * component came out of.
+ */
+export const Responsive: Story = {
+  args: { orientation: "horizontal" },
+  render: (stepperProps) => (
+    <ContainerBoard>
+      <Stepper {...stepperProps} />
+    </ContainerBoard>
+  ),
+}
+
+/**
+ * The whole keyboard path, which is the point of the headings: a
+ * stepper is a document outline, not a widget. There is nothing to
+ * focus and nothing to arrow between — advancing is the app's
+ * operation, and the component only reports where the sequence got
+ * to.
+ */
+export const Interactive: Story = {
+  render: (stepperProps) => {
+    const [reached, setReached] = useState(1)
+
+    return (
+      <div className="flex flex-col gap-3">
+        <div className="flex gap-2">
+          <Button
+            isDisabled={reached === 0}
+            onClick={() => {
+              setReached((was) => was - 1)
+            }}
+            type="button"
+          >
+            Back
+          </Button>
+          <Button
+            intent="accent"
+            isDisabled={reached === RIP.length}
+            onClick={() => {
+              setReached((was) => was + 1)
+            }}
+            type="button"
+          >
+            Advance
+          </Button>
+        </div>
+
+        <Stepper
+          {...stepperProps}
+          steps={RIP.map((step, index) => ({
+            ...step,
+            description: undefined,
+            status:
+              index < reached
+                ? ("done" as const)
+                : index === reached
+                  ? ("current" as const)
+                  : ("upcoming" as const),
+          }))}
+        />
+      </div>
+    )
+  },
+}

package/src/Stepper/Stepper.test.tsx

@@ -0,0 +1,112 @@
+import { composeStories } from "@storybook/react"
+import { expect, userEvent } from "storybook/test"
+import { test } from "vitest"
+
+import { expectNoAxeViolations } from "../expectNoAxeViolations.testHelpers.ts"
+import { mountStory } from "../mountStory.testHelpers.ts"
+import * as stories from "./Stepper.stories.tsx"
+
+const { AllStates, Default, Interactive, Responsive } =
+  composeStories(stories)
+
+test("the sequence is an ordered list with a name", async () => {
+  const { canvas } = await mountStory(Default)
+
+  // A `<ol>`, not a stack of divs: the ORDER is the meaning, and a
+  // screen reader announcing "list, 3 items" is what carries it.
+  await expect(
+    canvas.getByRole("list", { name: "Ingest sequence" }),
+  ).toBeVisible()
+  await expect(
+    canvas.getAllByRole("listitem"),
+  ).toHaveLength(3)
+})
+
+test("each step is a heading at the level the caller asked for", async () => {
+  const { canvas } = await mountStory(Default)
+
+  await expect(
+    canvas.getByRole("heading", { level: 3, name: /Rip/ }),
+  ).toBeVisible()
+})
+
+/**
+ * The rule this component turns on. Four statuses painted as four
+ * marker colours is a WCAG 1.4.1 failure however clear it looks,
+ * so every status reaches a screen reader as a word — and that is
+ * also the only channel that survives greyscale and the ePaper
+ * build.
+ */
+test("every status is a word, not only a colour", async () => {
+  const { canvas } = await mountStory(AllStates)
+
+  for (const status of [
+    "Done",
+    "In progress",
+    "Blocked",
+    "Not started",
+  ]) {
+    // Twice each: once as the step's visible label in this story,
+    // once as the visually-hidden status.
+    await expect(
+      canvas.getAllByText(status).length,
+    ).toBeGreaterThanOrEqual(2)
+  }
+})
+
+test("the marker is the ordinal, so it renders in a font with no tick glyph", async () => {
+  const { canvas } = await mountStory(Default)
+
+  // Not `✓`. `docs/decisions/2026-07-29-ship-no-icons-and-no-symbol-
+  // glyphs.md` — a glyph the font lacks paints as an empty box, and
+  // an empty box in the "done" position reads as an error.
+  await expect(canvas.getByText("1")).toBeVisible()
+  await expect(canvas.getByText("3")).toBeVisible()
+})
+
+/**
+ * The last step must not draw a connector into empty space. A real
+ * element rather than a `::before` is what makes this assertable at
+ * all — a pseudo-element has nothing to count.
+ */
+test("the last step draws no connector", async () => {
+  const { canvas } = await mountStory(Default)
+
+  const connectors = canvas
+    .getAllByRole("listitem")
+    .map((item: HTMLElement) =>
+      item.querySelector("span[aria-hidden='true']"),
+    )
+
+  await expect(connectors.filter(Boolean)).toHaveLength(2)
+  await expect(connectors[2]).toBeNull()
+})
+
+test("advancing moves which step is current", async () => {
+  const { canvas } = await mountStory(Interactive)
+
+  const heading = () =>
+    canvas.getByRole("heading", { level: 3, name: /Tag/ })
+
+  await expect(heading()).toBeVisible()
+
+  await userEvent.click(
+    canvas.getByRole("button", { name: "Advance" }),
+  )
+
+  // Tag was current and is now done — the status word is the
+  // assertion, because it is the only channel that is not a colour.
+  await expect(
+    heading().textContent?.includes("Done"),
+  ).toBe(true)
+})
+
+test("no axe violations, in either orientation", async () => {
+  const vertical = await mountStory(Default)
+
+  await expectNoAxeViolations(vertical.canvasElement)
+
+  const horizontal = await mountStory(Responsive)
+
+  await expectNoAxeViolations(horizontal.canvasElement)
+})

package/src/Stepper/Stepper.tsx

@@ -0,0 +1,246 @@
+import type { ReactNode } from "react"
+
+import { toClassName } from "../toClassName.ts"
+import { VisuallyHidden } from "../VisuallyHidden/VisuallyHidden.tsx"
+
+/**
+ * Where a step sits in the sequence.
+ *
+ * `blocked` is not a worse `upcoming`. Upcoming means "its turn has
+ * not come"; blocked means "its turn has come and something is in
+ * the way", which is a thing to go and fix rather than a thing to
+ * wait for. Docket's phases need exactly this split — a phase gated
+ * behind an unfinished one, versus a phase gated behind an EMPTY
+ * one, where the second is a mistake somebody has to correct.
+ */
+export type StepStatus =
+  | "blocked"
+  | "current"
+  | "done"
+  | "upcoming"
+
+export type Step = {
+  /** What the marker shows instead of its ordinal position. */
+  readonly marker?: ReactNode
+  readonly key: string
+  readonly label: ReactNode
+  /** One line under the label — why it is blocked, what it is
+   * waiting on, when it finished. */
+  readonly description?: ReactNode
+  /**
+   * What BELONGS to this step: the tasks in a phase, the fields in
+   * a form stage, the checks in a pipeline.
+   *
+   * The reason this component is not a `ProgressBar` with a legend.
+   * A bar says a sequence is half done; only the contents say which
+   * things go together and which one is next.
+   */
+  readonly content?: ReactNode
+  readonly status?: StepStatus
+}
+
+export type StepperOrientation = "horizontal" | "vertical"
+
+export type StepperProps = {
+  readonly className?: string
+  /**
+   * What level the step labels are. The caller's, because only the
+   * caller knows what the stepper sits under — one below a page
+   * `<h1>` wants `2`, one inside an already-deep section wants `4`.
+   * Getting it wrong is an axe `heading-order` failure and a broken
+   * screen-reader outline.
+   */
+  readonly headingLevel?: 2 | 3 | 4 | 5
+  /** The list's accessible name. Required — an unnamed sequence of
+   * numbers is a sequence of numbers. */
+  readonly label: string
+  /**
+   * `horizontal` is a REQUEST, not a promise: it collapses to
+   * vertical below `cq-md`, because four steps side by side in a
+   * narrow container squash into unreadable slivers (`2. / De- /
+   * dupe`, measured). A step carrying `content` should stay
+   * vertical — a column cannot hold a list.
+   */
+  readonly orientation?: StepperOrientation
+  readonly steps: readonly Step[]
+}
+
+/**
+ * An ordered sequence of steps, with what belongs to each one.
+ *
+ * ### Why the status is never colour alone
+ *
+ * Four states painted only as four marker colours is a WCAG 1.4.1
+ * failure however clear it looks, so each status reaches a screen
+ * reader as a word — `VisuallyHidden`, next to the label — and gets
+ * a second visual channel besides hue: a **filled** marker for done
+ * and current, an **outlined** one for upcoming and blocked, and a
+ * connector that is solid behind finished work and dashed ahead of
+ * it.
+ *
+ * ### Why the marker is a number and never a tick
+ *
+ * This library
+ * [ships no icons and no symbol glyphs](../../../../docs/decisions/2026-07-29-ship-no-icons-and-no-symbol-glyphs.md).
+ * A `✓` renders as an empty box wherever the font lacks it — which
+ * includes the sandbox chromium, the kiosk image and the ePaper
+ * build — and an empty box in the "done" position reads as an error.
+ * The ordinal always renders. An app that owns a glyph set can pass
+ * one as `marker`.
+ *
+ * ### Why the connector is an element
+ *
+ * Not a `::before`. `styles.css` is reserved for the handful of
+ * visuals a Tailwind utility genuinely cannot express — the looping
+ * animations and the scrollbar — and a line between two markers is
+ * not one of them. A real `<span aria-hidden>` also stops the last
+ * step drawing a connector into empty space, which is a
+ * `:not(:last-child)` selector nobody remembers to write.
+ */
+export const Stepper = ({
+  className,
+  headingLevel = 3,
+  label,
+  orientation = "vertical",
+  steps,
+}: StepperProps) => {
+  const Heading = `h${headingLevel}` as "h3"
+  const isHorizontal = orientation === "horizontal"
+
+  return (
+    // The container is a WRAPPER, never the `<ol>` itself.
+    //
+    // An element cannot answer its own container query: declaring
+    // `container-type` on the list makes it the query container for
+    // its DESCENDANTS, and `cq-md:` on the list resolves against
+    // whatever container is further up — usually none. The first
+    // version of this component put both on the `<ol>`, and the
+    // result was a horizontal stepper whose CONNECTORS went
+    // horizontal (they are children, so they matched) while the
+    // list stayed a column. Valid CSS, no error, nothing for axe or
+    // a DOM test to say, and obvious the moment it was rendered.
+    // `Board` carries the same note for the same reason.
+    <div className={toClassName("@container", className)}>
+      <ol
+        aria-label={label}
+        className={toClassName(
+          "flex list-none flex-col gap-5 p-0",
+          // Horizontal is the WIDE answer only. Below `cq-md` this
+          // falls back to the column, which is the same rule
+          // `Board` follows and for the same reason: the owner
+          // browses zoomed in, so a window's width is not the
+          // number of pixels anything actually has.
+          isHorizontal && "cq-md:flex-row cq-md:gap-0",
+        )}
+      >
+        {steps.map((step, index) => {
+          const status = step.status ?? "upcoming"
+          const isLast = index === steps.length - 1
+
+          return (
+            <li
+              className={toClassName(
+                "relative grid grid-cols-[auto_minmax(0,1fr)] grid-rows-[auto_minmax(0,1fr)] gap-x-3",
+                isHorizontal &&
+                  "cq-md:flex cq-md:min-w-0 cq-md:flex-1 cq-md:flex-col cq-md:gap-y-2",
+                // Blocked and upcoming recede; the step you can act
+                // on is the one that keeps full contrast. Opacity
+                // rather than a muted token so the step's own
+                // contents dim with it — a task list at full strength
+                // under a dimmed heading reads as startable.
+                (status === "blocked" ||
+                  status === "upcoming") &&
+                  "opacity-70",
+              )}
+              key={step.key}
+            >
+              <span
+                className={toClassName(
+                  "col-start-1 row-start-1 grid size-7 place-items-center rounded-full border text-sm tabular-nums",
+                  STATUS_MARKER_CLASS[status],
+                  isHorizontal && "cq-md:col-start-1",
+                )}
+              >
+                {step.marker ?? index + 1}
+              </span>
+
+              {/* Absent on the last step, so nothing draws a line
+                into empty space. */}
+              {isLast ? null : (
+                <span
+                  aria-hidden
+                  className={toClassName(
+                    "col-start-1 row-start-2 my-1 w-0.5 justify-self-center rounded-full",
+                    // Solid behind finished work, dashed ahead of it
+                    // — the second visual channel that keeps this
+                    // from being colour alone.
+                    status === "done"
+                      ? "bg-intent-success-solid"
+                      : "bg-border-subtle",
+                    isHorizontal &&
+                      "cq-md:absolute cq-md:top-3.5 cq-md:start-7 cq-md:my-0 cq-md:h-0.5 cq-md:w-[calc(100%-1.75rem)]",
+                  )}
+                />
+              )}
+
+              <div
+                className={toClassName(
+                  "col-start-2 row-span-2 row-start-1 min-w-0",
+                  isHorizontal && "cq-md:col-start-1",
+                )}
+              >
+                <Heading className="m-0 flex flex-wrap items-center gap-2 text-md font-medium text-content-primary">
+                  {step.label}
+
+                  {/* The status as a WORD. Four marker colours is
+                    four colours as far as assistive technology is
+                    concerned, and this is the only channel that
+                    survives a screen reader, a greyscale print and
+                    the ePaper build at once. */}
+                  <VisuallyHidden>
+                    {STATUS_LABEL[status]}
+                  </VisuallyHidden>
+                </Heading>
+
+                {step.description == null ? null : (
+                  <p className="mt-0.5 mb-0 text-sm text-content-secondary">
+                    {step.description}
+                  </p>
+                )}
+
+                {step.content == null ? null : (
+                  <div className="mt-2">{step.content}</div>
+                )}
+              </div>
+            </li>
+          )
+        })}
+      </ol>
+    </div>
+  )
+}
+
+/**
+ * Written out in full, never interpolated. Tailwind v4 scans source
+ * text for COMPLETE class strings, so `` `bg-intent-${x}-solid` ``
+ * generates nothing at all and the element paints transparent with
+ * no error and no failing test —
+ * `tailwindCandidates.test.ts` is what makes this near-duplication
+ * safe to keep.
+ */
+const STATUS_MARKER_CLASS: Record<StepStatus, string> = {
+  blocked:
+    "border-intent-warning-border bg-intent-warning-surface text-intent-warning-content",
+  current:
+    "border-intent-accent-border bg-intent-accent-surface text-intent-accent-content",
+  done: "border-intent-success-border bg-intent-success-solid text-intent-success-on-solid",
+  upcoming:
+    "border-border-subtle bg-surface-raised text-content-secondary",
+}
+
+const STATUS_LABEL: Record<StepStatus, string> = {
+  blocked: "Blocked",
+  current: "In progress",
+  done: "Done",
+  upcoming: "Not started",
+}

package/src/index.ts

@@ -328,6 +328,13 @@ export type {
 export { SortableTableHeader } from "./SortableTableHeader/SortableTableHeader.tsx"
 export type { SpinnerProps } from "./Spinner/Spinner.tsx"
 export { Spinner } from "./Spinner/Spinner.tsx"
+export type {
+  Step,
+  StepperOrientation,
+  StepperProps,
+  StepStatus,
+} from "./Stepper/Stepper.tsx"
+export { Stepper } from "./Stepper/Stepper.tsx"
 export type {
   SwatchAppearance,
   SwatchProps,

package/src/slotProps.ts

@@ -127,13 +127,27 @@ export type SlotProps = Pick<
  * inner one won. The outer panel had no anchor and rendered in the
  * corner of the viewport — no error, no failing test, and it looks
  * like a CSS bug.
+ *
+ * ### A wrapping component uses it too, and keeps its own prop type
+ *
+ * `receivedProps` is generic in `ReceivedProps extends SlotProps`
+ * rather than plain `SlotProps`, so the return type carries whatever
+ * the caller actually holds instead of narrowing it to the five keys.
+ * `FieldGroup` is the reason: it does not clone, its rest props land
+ * on its own `<fieldset>`, and it writes an `aria-describedby` that
+ * has to **join** a caller's rather than replace it. Narrowing to
+ * `SlotProps` on the way out would have dropped `disabled`, `form`,
+ * `name` and every `data-*` from the type of the object it spreads
+ * onto that element — the props would still arrive at runtime, and
+ * only the type would have lied.
  */
 export const mergeSlotProps = <
+  ReceivedProps extends SlotProps,
   OwnProps extends Record<string, unknown>,
 >(
-  receivedProps: SlotProps,
+  receivedProps: ReceivedProps,
   ownProps: OwnProps,
-): OwnProps & SlotProps => {
+): OwnProps & ReceivedProps => {
   const definedOwnProps = Object.fromEntries(
     Object.entries(ownProps).filter(
       ([, value]) => value !== undefined,

package/src/sourceRules.test.ts

@@ -236,6 +236,13 @@ test("a container-query component is never storied in a shrink-to-fit cell", ()
     "Main",
     "MarkdownEditor",
     "MediaTile",
+    // `Stepper`'s container is the one that decides whether a
+    // `horizontal` sequence is actually horizontal. Below `--cq-md`
+    // it falls back to the vertical column, because four steps side
+    // by side in a narrow container squash into `2. / De- / dupe` —
+    // measured in Docket, before any of the steps contained
+    // anything.
+    "Stepper",
   ])
 
   // `StoryCell`s are never nested, so the lazy match really does
@@ -430,7 +437,7 @@ test("the barrel is the only place components are re-exported", async () => {
   // `useBoardDrag.ts` are its members and stay out of this count and
   // the barrel by the `<Name>/<Name>.tsx` rule, exactly as
   // `ToolbarSlot` and `QueryBuilderRow` do.
-  expect(componentNames.length).toBe(49)
+  expect(componentNames.length).toBe(50)
 
   for (const name of componentNames) {
     expect(barrel).toContain(`export { ${name} }`)