@charcuterie/ui 3.4.1 → 3.6.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/markdownEditorCodeMirror/MarkdownEditorCodeMirror.mdx

@@ -98,6 +98,34 @@ blank line at the top and bottom of the block that reads as a rendering bug. A l
 stays, because hiding `-` turns an unordered list into indented prose — Obsidian substitutes
 a `•`, which means choosing a width, and this component has no business choosing one.
 
+## Tables render, and the caret edits them
+
+<Canvas of={MarkdownEditorCodeMirrorStories.Tables} />
+
+A table is the one construct on this surface whose meaning is *geometry*. Every other
+decoration hangs on text CodeMirror draws anyway; a column cannot, because column two's text
+is on four separate lines. So the pipes stop being drawn and a real `<table>` is drawn
+instead — alignment from the delimiter row, and `**bold**`, `` `code` ``, links and images
+rendering inside the cells exactly as they do in a paragraph.
+
+**Click a cell and the markdown comes back with the caret in that cell.** That is the same
+trade as a link or an image, and it is the only way in: you cannot edit a column you cannot
+see. Arrow keys work too — Down from the line above enters at the top row, Up from below
+enters at the bottom — because CodeMirror otherwise steps *over* a block widget and the
+table would be unreachable without a mouse.
+
+Three decisions worth knowing:
+
+- **The widest row wins, not the header.** GFM drops cells past the header's width. An
+  editor that did the same would put text you typed on screen nowhere, so short rows gain
+  empty cells instead and nothing is ever hidden.
+- **An empty cell keeps its column.** The parser emits no cell node for `| |`; the `|`
+  positions are what the columns are read from, so a blank cell does not shift the row.
+- **A wide table scrolls inside its own block** rather than pushing the editor sideways.
+
+`\|` — the only way to put a pipe *in* a cell — now conceals its backslash like any other
+marker, in tables and everywhere else.
+
 ## Clicking a link opens it
 
 Obsidian's behaviour, not VS Code's: where the markup is hidden, a link that looks like a

package/src/markdownEditorCodeMirror/MarkdownEditorCodeMirror.stories.tsx

@@ -47,6 +47,28 @@ ip -br addr show
 Replacement rails ordered from https://example.invalid/product?id=1234
 `
 
+/**
+ * Alignment from the delimiter row, inline markup inside cells, a
+ * deliberately blank cell, and a row that is one column short —
+ * every table decision in one fixture.
+ */
+const TABLES = `## Rack inventory
+
+| Port | Goes to | **Speed** | Notes |
+| :--- | :---: | ---: | --- |
+| 1 | uplink | 10G | swapped \`2026-08-19\` |
+| 2 |  | 1G | see [the runbook](https://example.invalid/runbook) |
+| 3 | shelf | 1G |
+| 4 | ~~spare~~ | — | pulled \\| relabel |
+
+A table with no outer pipes is still a table:
+
+Disk | Size
+--- | ---:
+front-left | 18 TB
+front-right | 18 TB
+`
+
 const meta = {
   title: "Components/Controls/MarkdownEditorCodeMirror",
   component: MarkdownEditorCodeMirror,
@@ -145,3 +167,23 @@ export const CaretReveal: Story = {
     label: "Description",
   },
 }
+
+/**
+ * The construct whose meaning is geometry.
+ *
+ * Everything else on this surface is a decoration hung on text that
+ * is drawn anyway — a column is not, because column two's text is
+ * on four separate lines. So the pipes stop being drawn and a real
+ * table is drawn instead, alignment and all, with `**bold**` and
+ * links rendering inside the cells like anywhere else.
+ *
+ * Click a cell and the markdown comes back with the caret in that
+ * cell — the same trade the rest of the surface makes for a link or
+ * an image.
+ */
+export const Tables: Story = {
+  args: {
+    defaultValue: TABLES,
+    label: "Description",
+  },
+}