@charcuterie/ui 0.1.0

package/src/Alert/Alert.stories.tsx

@@ -0,0 +1,218 @@
+import type { Meta, StoryObj } from "@storybook/react"
+
+import {
+  intentArgType,
+  toStoryChoice,
+} from "../argTypes.storyHelpers.ts"
+import { Button } from "../Button/Button.tsx"
+import {
+  ContainerBoard,
+  StoryCell,
+  StoryGrid,
+  StorySection,
+} from "../board.storyHelpers.tsx"
+import { Alert } from "./Alert.tsx"
+
+const INTENTS = [
+  "neutral",
+  "accent",
+  "success",
+  "warning",
+  "danger",
+  "info",
+] as const
+
+const meta = {
+  title: "Components/Alert",
+  component: Alert,
+  parameters: { layout: "padded" },
+  argTypes: {
+    intent: intentArgType,
+    size: toStoryChoice(["sm", "md"] as const),
+  },
+  // The component's own defaults, restated — Storybook does not seed
+  // `args` from docgen, so an unstated default shows in the props
+  // table with nothing selected in its control.
+  args: {
+    intent: "neutral",
+    size: "md",
+  },
+} satisfies Meta<typeof Alert>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+/**
+ * rip-deck's grouped tower alert, verbatim: one trouble, the bays it
+ * touches, and whether the house speakers already said it out loud.
+ */
+export const Default: Story = {
+  args: {
+    description: "4 bays · 3, 4, 5, 6 · confirmed",
+    heading:
+      "Four bays stalled at once — check the USB hub's power",
+    intent: "danger",
+  },
+}
+
+export const AllVariants: Story = {
+  args: { heading: "The disc may need cleaning" },
+  render: (alertProps) => (
+    <StorySection title="Six intents. rip-deck declares this map twice, in two files, with hardcoded hexes and no light mode.">
+      <StoryGrid columns={3}>
+        {INTENTS.map((intent) => (
+          <StoryCell
+            align="stretch"
+            key={intent}
+            label={intent}
+          >
+            <Alert
+              {...alertProps}
+              heading={`intent: ${intent}`}
+              intent={intent}
+            />
+          </StoryCell>
+        ))}
+      </StoryGrid>
+    </StorySection>
+  ),
+}
+
+/**
+ * Every part is optional except the sentence, and `size="sm"` is the
+ * in-card form — rip-deck's verdict chip, which sits under a bay's
+ * progress bar rather than at the top of the page.
+ */
+export const AllStates: Story = {
+  args: { heading: "The disc may need cleaning" },
+  render: (alertProps) => (
+    <StorySection title="An alert is static: no hover, no focus, no disabled. What varies is which parts are present.">
+      <StoryGrid columns={2}>
+        <StoryCell align="stretch" label="heading only">
+          <Alert {...alertProps} intent="warning" />
+        </StoryCell>
+
+        <StoryCell
+          align="stretch"
+          label="heading + description"
+        >
+          <Alert
+            {...alertProps}
+            description="Bay 4 · suspected"
+            intent="warning"
+          />
+        </StoryCell>
+
+        <StoryCell align="stretch" label="with evidence">
+          <Alert
+            {...alertProps}
+            details={[
+              "3 read errors in 40 s",
+              "throughput 1.2x against a 6.0x baseline",
+            ]}
+            intent="warning"
+          />
+        </StoryCell>
+
+        <StoryCell align="stretch" label="with an action">
+          <Alert
+            {...alertProps}
+            actions={
+              <Button size="sm" appearance="outline">
+                Open trays
+              </Button>
+            }
+            description="2 discs · slots 4, 7"
+            heading="There are still discs in the tower"
+            intent="info"
+          />
+        </StoryCell>
+
+        <StoryCell
+          align="stretch"
+          label='size="sm" — the in-card verdict'
+        >
+          <Alert
+            {...alertProps}
+            details={["seen on bays 3 and 7"]}
+            heading="Part of the tower-wide problem above."
+            intent="danger"
+            size="sm"
+          />
+        </StoryCell>
+
+        <StoryCell
+          align="stretch"
+          label="label ⇒ a named landmark"
+        >
+          <Alert
+            {...alertProps}
+            heading="The USB bus is flapping"
+            intent="danger"
+            label="USB connection alert"
+          />
+        </StoryCell>
+      </StoryGrid>
+    </StorySection>
+  ),
+}
+
+/**
+ * The `@container` claim: actions sit beside the sentence when there
+ * is room and drop under it when there is not — and the width that
+ * decides is the **panel's**, not the window's. A banner in a
+ * sidebar and the same banner full-bleed is exactly the pair a media
+ * query cannot tell apart.
+ */
+export const Responsive: Story = {
+  args: {
+    description: "2 discs · slots 4, 7",
+    heading: "There are still discs in the tower",
+    intent: "info",
+  },
+  render: (alertProps) => (
+    <ContainerBoard>
+      {(width) => (
+        <Alert
+          {...alertProps}
+          actions={
+            <Button size="sm" appearance="outline">
+              Open trays
+            </Button>
+          }
+          label={`Discs still in the tower at ${width}`}
+        />
+      )}
+    </ContainerBoard>
+  ),
+}
+
+/**
+ * An alert is not interactive, so what there is to drive is what it
+ * *contains*. The action is an ordinary `Button` and stays reachable
+ * by role and name from inside the landmark — which is the whole
+ * reason `label` exists.
+ */
+export const Interactive: Story = {
+  args: {
+    details: [
+      "3 read errors in 40 s",
+      "throughput 1.2x against a 6.0x baseline",
+    ],
+    heading:
+      "Bay 7 is reading with errors — clean the disc",
+    intent: "warning",
+    label: "Bay 7 verdict",
+  },
+  render: (alertProps) => (
+    <Alert
+      {...alertProps}
+      actions={
+        <Button size="sm" appearance="outline">
+          Retry in another bay
+        </Button>
+      }
+    />
+  ),
+}

package/src/Alert/Alert.test.tsx

@@ -0,0 +1,112 @@
+import { composeStories } from "@storybook/react"
+import { expect } from "storybook/test"
+import { test } from "vitest"
+
+import { expectNoAxeViolations } from "../expectNoAxeViolations.testHelpers.ts"
+import { mountStory } from "../mountStory.testHelpers.ts"
+import { expectAgentDrivable } from "../testing/index.ts"
+import * as stories from "./Alert.stories.tsx"
+
+const { AllStates, Default, Interactive, Responsive } =
+  composeStories(stories)
+
+test("a labelled alert is a landmark an agent can scope to", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(Interactive)
+
+  const alert = expectAgentDrivable(canvas, {
+    name: "Bay 7 verdict",
+    role: "region",
+  })
+
+  // The whole reason `label` exists: the action inside is reachable
+  // *through* the alert, which is what disambiguates one of nine
+  // identical "Retry" buttons on a nine-bay tower.
+  await expect(alert).toContainElement(
+    expectAgentDrivable(canvas, {
+      name: "Retry in another bay",
+      role: "button",
+    }),
+  )
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+test("an unlabelled alert is not a landmark", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(Default)
+
+  // A block, deliberately. Nine bay cards each holding a named
+  // region called "Part of the tower-wide problem above." is axe's
+  // `landmark-unique`, so the default has to be the quiet one.
+  await expect(
+    canvas.queryAllByRole("region"),
+  ).toHaveLength(0)
+
+  await expect(
+    canvas.getByText(
+      "Four bays stalled at once — check the USB hub's power",
+    ),
+  ).toBeVisible()
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+test("the evidence is a list, and repeated evidence still renders", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(Interactive)
+
+  const list = canvas.getByRole("list")
+
+  await expect(
+    canvas.getAllByRole("listitem"),
+  ).toHaveLength(2)
+
+  await expect(list).toHaveTextContent(
+    "3 read errors in 40 s",
+  )
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+/**
+ * Six landmarks in one board, and every one of them differently
+ * named — because two `<section>`s sharing a name is a violation
+ * rather than a duplicate, which is exactly why the default is a
+ * plain block.
+ */
+test("the whole variants board is clean under axe", async () => {
+  const { canvasElement } = await mountStory(AllStates)
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+test("the actions drop below the sentence in a narrow container", async () => {
+  const { canvas } = await mountStory(Responsive)
+
+  const narrow = expectAgentDrivable(canvas, {
+    name: "Discs still in the tower at 15rem",
+    role: "region",
+  })
+
+  const wide = expectAgentDrivable(canvas, {
+    name: "Discs still in the tower at 34rem",
+    role: "region",
+  })
+
+  const getRowDirection = (alert: HTMLElement) =>
+    globalThis.getComputedStyle(
+      alert.firstElementChild as HTMLElement,
+    ).flexDirection
+
+  // The **axis**, not the height. The first draft of this test
+  // compared the two rows' heights and passed with `cq-sm:flex-row`
+  // deleted — because at 15rem the sentence wraps onto more lines
+  // whatever the button does, so it was measuring text wrapping and
+  // calling it a container query. This is the thing itself: at 15rem
+  // the button sits under the text, at 34rem beside it, and the
+  // width that decided is the panel's rather than the window's.
+  await expect(getRowDirection(narrow)).toBe("column")
+
+  await expect(getRowDirection(wide)).toBe("row")
+})

package/src/Alert/Alert.tsx

@@ -0,0 +1,166 @@
+import type { IntentName } from "@charcuterie/tokens"
+import type {
+  ComponentPropsWithRef,
+  ReactNode,
+} from "react"
+
+import { INTENT_APPEARANCE_CLASS } from "../intentStyles.ts"
+import { toClassName } from "../toClassName.ts"
+
+export type AlertSize = "md" | "sm"
+
+export type AlertProps = Omit<
+  ComponentPropsWithRef<"section">,
+  "children"
+> & {
+  /** Buttons. Laid out beside the text at `cq-sm` and up. */
+  actions?: ReactNode
+  /** The quiet second line — counts, timestamps, provenance. */
+  description?: ReactNode
+  /**
+   * The evidence, one line each. A list rather than a paragraph
+   * because that is what it is, and because a screen reader then
+   * announces "list, 3 items" instead of running three measurements
+   * together into one sentence.
+   */
+  details?: readonly string[]
+  /**
+   * The sentence. A `ReactNode` rather than a `string` because
+   * rip-deck's verdicts qualify themselves inline — *"…(suspected —
+   * retry in another drive to confirm)"* — and splitting that across
+   * two props would let the qualifier drift away from the claim it
+   * qualifies.
+   */
+  heading: ReactNode
+  intent?: IntentName
+  /**
+   * Present ⇒ this is a **named landmark** and
+   * `getByRole("region", { name })` finds it. Absent ⇒ a plain
+   * block, because a `<section>` with no accessible name is
+   * `generic` rather than `region`. See below; the default is
+   * deliberate.
+   */
+  label?: string
+  size?: AlertSize
+}
+
+const SIZE_CLASS: Record<AlertSize, string> = {
+  sm: "gap-0.5 rounded-md px-2 py-1 text-sm",
+  md: "gap-1 rounded-xl px-3.5 py-2.5 text-md",
+}
+
+/**
+ * The thing four of rip-deck's components each spell differently,
+ * and the reason `TONE_CLASS` was declared twice in one package.
+ *
+ * `TowerAlerts`, `UsbAlertBanner`, `LoadedDiscsBanner` and
+ * `VerdictBadge` are one shape: an intent-coloured block holding a
+ * sentence, a quieter line under it, and sometimes a list of
+ * evidence. Two of them carried a byte-identical `TONE_CLASS` map of
+ * hardcoded hexes and `amber-`/`red-` utilities; mux-magic spells the
+ * same idea a third way in `statusClassMap`. Here it is
+ * `INTENT_APPEARANCE_CLASS`, which every other component in this
+ * package already reads.
+ *
+ * ### It is a block by default, and a landmark only when named
+ *
+ * `label` is what decides, because the evidence divides cleanly:
+ *
+ *  - The **banners** are one alert at the top of a page and want to
+ *    be addressable — `getByRole("region", { name: "USB connection
+ *    alert" })`. They pass a `label`.
+ *  - The **verdict** renders inside every bay card, and one of its
+ *    two forms is the single sentence *"Part of the tower-wide
+ *    problem above."* Nine landmarks sharing one name is axe's
+ *    `landmark-unique`, so it passes none.
+ *
+ * A component that always took the landmark would have made the
+ * second case fail its own a11y gate, and one that never took it
+ * would leave three `<section aria-label>` wrappers hand-rolled in
+ * the consumer — which is what rip-deck has today.
+ *
+ * ### The heading is not a heading element
+ *
+ * An alert's headline is a *sentence* — "Bay 7 is reading with
+ * errors; clean the disc and try again" — not a node in the document
+ * outline. Nine bays' worth of those as `<h3>`s builds a table of
+ * contents out of nine complaints, which is worse for a screen
+ * reader than no outline entry at all. `Card` and `EmptyState` take
+ * a real `headingLevel` precisely because their headings *are* short
+ * outline nodes; this one is styled text, and `label` is how it
+ * becomes findable.
+ *
+ * ### It does not announce, and that is a component boundary
+ *
+ * No `role="alert"`, no `aria-live`. A live region takes **no
+ * accessible name from its content**
+ * ([decision](../../../docs/decisions/2026-07-29-status-regions-carry-an-aria-label.md)),
+ * so an announcing variant would need a name that duplicates the
+ * sentence it is announcing — and `role="alert"` on a `<section>`
+ * overrides the landmark, so it cannot be both. A thing that
+ * interrupts you is a `Toast` (M6). This is a thing that is *on the
+ * page*.
+ */
+export const Alert = ({
+  actions,
+  className,
+  description,
+  details,
+  heading,
+  intent = "neutral",
+  label,
+  size = "md",
+  ...sectionProps
+}: AlertProps): ReactNode => {
+  return (
+    // Always a `<section>`, and the landmark still depends on
+    // `label` — because HTML already says so. A `<section>` maps to
+    // `region` **only when it has an accessible name**; without one
+    // it is `generic`, which is exactly the "plain block" the
+    // in-card verdict wants. Branching the element type here would
+    // have been a second, weaker statement of a rule the platform
+    // already enforces.
+    <section
+      {...sectionProps}
+      aria-label={label}
+      className={toClassName(
+        // `@container` so the actions drop below the text in a
+        // sidebar and sit beside it full-bleed — the case a media
+        // query cannot tell apart.
+        "@container border",
+        INTENT_APPEARANCE_CLASS[intent].soft,
+        SIZE_CLASS[size],
+        className,
+      )}
+    >
+      <div className="flex flex-col gap-2 cq-sm:flex-row cq-sm:items-start cq-sm:justify-between">
+        <div className="flex min-w-0 flex-col">
+          <p className="m-0 font-semibold">{heading}</p>
+
+          {description ? (
+            <p className="m-0 text-sm opacity-80">
+              {description}
+            </p>
+          ) : null}
+        </div>
+
+        {actions ? (
+          <div className="flex shrink-0 items-center gap-1">
+            {actions}
+          </div>
+        ) : null}
+      </div>
+
+      {details && details.length > 0 ? (
+        <ul className="m-0 list-none p-0 text-sm opacity-80">
+          {details.map((line, index) => (
+            // The line's own text is not a key: evidence repeats.
+            // Two drives reporting "3 read errors" is the normal
+            // case, not an edge one.
+            <li key={`${String(index)}-${line}`}>{line}</li>
+          ))}
+        </ul>
+      ) : null}
+    </section>
+  )
+}

package/src/Badge/Badge.mdx

@@ -0,0 +1,43 @@
+import { Canvas, Controls, Meta } from "@storybook/addon-docs/blocks";
+
+import * as BadgeStories from "./Badge.stories";
+
+<Meta of={BadgeStories} />
+
+# Badge
+
+Four repos, and rip-deck declares the **identical** `TONE_CLASS` map twice —
+`VerdictBadge.tsx` and `TowerAlerts.tsx`, same five hardcoded hexes, related only by
+copy-paste. mux-magic's `statusClassMap` is the same idea spelled a third way, keyed by a
+bare `string`, so an unrecognised status renders with no colour and no error.
+
+<Canvas of={BadgeStories.Default} />
+
+## Props
+
+<Controls />
+
+## Where the status half lives
+
+`intent` covers the colour. Which *state* maps to which intent — and what it is called in
+English — lives in `statusIntent.ts` as exhaustive switches over the machines
+`@charcuterie/logic` ships:
+
+```tsx
+<Badge intent={getAsyncIntent(status)}>{getAsyncLabel(status)}</Badge>
+```
+
+That is the whole of mux-magic's `StatusBadge`, and adding a state to the machine is a
+compile error here rather than a blank pill in production.
+
+<Canvas of={BadgeStories.Interactive} />
+
+## No implicit role
+
+A badge is a word about something else. It is not a live region, and `role="status"` would
+make every re-render announce itself. Where a status genuinely needs announcing, that is
+`LiveStatusIndicator`; where a badge needs a name beyond its text, `aria-label` still
+works. Hover styling is deliberately absent too — `INTENT_HOVER_CLASS` is opt-in, so a
+verdict pill cannot imply it is clickable.
+
+<Canvas of={BadgeStories.AllVariants} />