@charcuterie/ui 0.1.0

package/src/Card/Card.test.tsx

@@ -0,0 +1,56 @@
+import { composeStories } from "@storybook/react"
+import { expect } from "storybook/test"
+import { test } from "vitest"
+
+import { mountStory } from "../mountStory.testHelpers.ts"
+import { expectAgentDrivable } from "../testing/index.ts"
+import * as stories from "./Card.stories.tsx"
+
+const { AllStates, Default, Interactive } =
+  composeStories(stories)
+
+test("a heading turns the card into a named landmark", async () => {
+  const { canvas } = await mountStory(Default)
+
+  expectAgentDrivable(canvas, {
+    name: "Bay 3",
+    role: "region",
+  })
+})
+
+test("a card with no heading is not a landmark", async () => {
+  const { canvas } = await mountStory(AllStates)
+
+  // Four cards on the board, three of them named. A `<section>` with
+  // no accessible name is not a region at all — which is the point:
+  // the component does not pretend to be one it cannot name.
+  await expect(canvas.getAllByRole("region")).toHaveLength(
+    3,
+  )
+})
+
+/**
+ * Two identical "Start rip" buttons on one page, disambiguated only
+ * by the region each sits in.
+ */
+test("region scoping disambiguates two identical buttons", async () => {
+  const { canvas } = await mountStory(Interactive)
+
+  const bayFour = expectAgentDrivable(canvas, {
+    name: "Bay 4",
+    role: "region",
+  })
+
+  const scoped = bayFour.querySelectorAll("button")
+
+  await expect(scoped).toHaveLength(1)
+
+  // And the progress bar inside that region is the one named for it,
+  // so an agent reading a value off a 16-bay tower reads the right
+  // bay's.
+  await expect(
+    canvas.getByRole("progressbar", {
+      name: "Bay 4 progress",
+    }),
+  ).toHaveAttribute("aria-valuenow", "40")
+})

package/src/Card/Card.tsx

@@ -0,0 +1,142 @@
+import { useUniqueId } from "@charcuterie/logic"
+import type {
+  ElevationStep,
+  SurfaceRole,
+} from "@charcuterie/tokens"
+import type {
+  ComponentPropsWithRef,
+  ReactNode,
+} from "react"
+
+import { toClassName } from "../toClassName.ts"
+
+export type CardSurface = Extract<
+  SurfaceRole,
+  "base" | "raised" | "sunken"
+>
+
+export type CardPadding = "lg" | "md" | "none" | "sm"
+
+export type CardProps = ComponentPropsWithRef<"section"> & {
+  /** Buttons or a badge, laid out beside the heading. */
+  actions?: ReactNode
+  elevation?: ElevationStep
+  footer?: ReactNode
+  heading?: string
+  headingLevel?: 2 | 3 | 4
+  padding?: CardPadding
+  surface?: CardSurface
+}
+
+const SURFACE_CLASS: Record<CardSurface, string> = {
+  base: "bg-surface-base",
+  raised: "bg-surface-raised",
+  sunken: "bg-surface-sunken",
+}
+
+/**
+ * Exported only so the story can derive its `elevation` control from
+ * the same map the component indexes — `ElevationStep` comes from
+ * `@charcuterie/tokens`, which react-docgen will not follow, so the
+ * options have to be stated and this is the one statement of them
+ * that cannot drift.
+ */
+export const ELEVATION_CLASS: Record<
+  ElevationStep,
+  string
+> = {
+  none: "shadow-none",
+  low: "shadow-low",
+  medium: "shadow-medium",
+  high: "shadow-high",
+}
+
+const PADDING_CLASS: Record<CardPadding, string> = {
+  none: "p-0",
+  sm: "p-3",
+  md: "p-4",
+  lg: "p-6",
+}
+
+/**
+ * Five repos, and the reason this is a P0 rather than a nicety is
+ * the `<section>`: give a card a heading and it becomes a landmark,
+ * so `getByRole("region", { name: "Bay 3" })` scopes every
+ * subsequent query to that card. Without it, an agent driving a
+ * 16-bay tower has sixteen identical "Start" buttons and no way to
+ * say which one it means.
+ *
+ * `aria-labelledby` rather than `aria-label`, because the heading is
+ * on screen already and stating the name twice is how the two drift
+ * apart.
+ *
+ * **Density is not a prop here.** mux-magic's inventory turned up a
+ * `CardDensityProvider` in the withdrawn bambuddy evidence, and it
+ * is the wrong shape for this fleet: density is a global axis on
+ * `<html>`, so a compact bay list is `data-density="compact"` on the
+ * page, not a context around the cards. `padding` remains a prop
+ * because a card wrapping a poster grid genuinely has none, which is
+ * a layout fact rather than a density one.
+ */
+export const Card = ({
+  actions,
+  children,
+  className,
+  elevation = "low",
+  footer,
+  heading,
+  headingLevel = 2,
+  padding = "md",
+  surface = "raised",
+  ...sectionProps
+}: CardProps): ReactNode => {
+  const headingId = useUniqueId()
+
+  const Heading = `h${headingLevel}` as const
+
+  return (
+    <section
+      {...sectionProps}
+      aria-labelledby={heading ? headingId : undefined}
+      className={toClassName(
+        // `@container` here, not on a wrapper, is what lets the
+        // header stack at narrow widths *inside a wide viewport* —
+        // a card in a sidebar and the same card full-bleed are the
+        // case a media query cannot tell apart, and the fleet's
+        // poster grids get it wrong at intermediate widths today.
+        "@container flex flex-col gap-3 rounded-lg border border-border-subtle text-content-primary",
+        SURFACE_CLASS[surface],
+        ELEVATION_CLASS[elevation],
+        PADDING_CLASS[padding],
+        className,
+      )}
+    >
+      {heading || actions ? (
+        <header className="flex flex-col gap-2 cq-sm:flex-row cq-sm:items-start cq-sm:justify-between">
+          {heading ? (
+            <Heading
+              className="font-semibold text-md leading-tight"
+              id={headingId}
+            >
+              {heading}
+            </Heading>
+          ) : null}
+
+          {actions ? (
+            <div className="flex shrink-0 items-center gap-1">
+              {actions}
+            </div>
+          ) : null}
+        </header>
+      ) : null}
+
+      {children}
+
+      {footer ? (
+        <footer className="border-t border-border-subtle pt-3 text-content-secondary text-sm">
+          {footer}
+        </footer>
+      ) : null}
+    </section>
+  )
+}

package/src/EmptyState/EmptyState.mdx

@@ -0,0 +1,40 @@
+import { Canvas, Controls, Meta } from "@storybook/addon-docs/blocks";
+
+import * as EmptyStateStories from "./EmptyState.stories";
+
+<Meta of={EmptyStateStories} />
+
+# EmptyState
+
+**Six repos, eleven-plus copies** — plex-channels alone has five `li.empty`s and castkit
+six `.idle`s. Every copy is a bare string in a `<div>`, so "no results", "not started yet",
+and "the socket died" all look identical and none of them is findable by role.
+
+Designed fresh rather than ported: the two repos that had a real `EmptyState` with typed
+variants were bambuddy and spoolbuddy, which are upstream projects rather than Kevin's
+code, so that evidence was withdrawn from the plan.
+
+<Canvas of={EmptyStateStories.Default} />
+
+## Props
+
+<Controls />
+
+## Why there is no `variant`
+
+"Empty" and "failed" differ in wording and in whether there is a retry button — both props
+already. A `variant="error"` that only changes a colour invites callers to encode the
+meaning in the colour alone, which is the one thing a colour cannot carry.
+
+<Canvas of={EmptyStateStories.AllVariants} />
+
+## The heading is the handle
+
+`headingLevel` is the caller's, because only the caller knows what this sits under. A real
+heading makes `getByRole("heading", { name: "No discs queued" })` work, where `getByText`
+against eleven copies of "Nothing here" does not.
+
+The `md` size gains air past `--cq-md`, so the same component is tight in a 15rem sidebar
+and generous filling a dashboard — decided by the panel, not the window.
+
+<Canvas of={EmptyStateStories.Responsive} />

package/src/EmptyState/EmptyState.stories.tsx

@@ -0,0 +1,183 @@
+import type { Meta, StoryObj } from "@storybook/react"
+import { Button } from "../Button/Button.tsx"
+import {
+  ContainerBoard,
+  StoryCell,
+  StoryGrid,
+  StorySection,
+} from "../board.storyHelpers.tsx"
+import { Card } from "../Card/Card.tsx"
+import {
+  AlertIcon,
+  InboxIcon,
+  PlayIcon,
+  SearchIcon,
+} from "../icons.storyHelpers.tsx"
+import { EmptyState } from "./EmptyState.tsx"
+
+const meta = {
+  title: "Components/EmptyState",
+  component: EmptyState,
+  parameters: { layout: "padded" },
+  args: { headingLevel: 2, size: "md" },
+} satisfies Meta<typeof EmptyState>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+/**
+ * The heading is the handle. Eleven copies of "Nothing here" in a
+ * `<div>` are indistinguishable to an agent; a named heading is not.
+ */
+export const Default: Story = {
+  args: {
+    description:
+      "Insert a disc and rip-deck will pick it up automatically.",
+    heading: "No discs queued",
+  },
+}
+
+/**
+ * There is no `variant` prop, on purpose: "empty" and "failed"
+ * differ in wording and in whether there is a retry button, both of
+ * which are props already. A `variant="error"` that only changes a
+ * colour invites callers to encode the meaning in the colour alone,
+ * which is the one thing a colour cannot carry.
+ */
+export const AllVariants: Story = {
+  args: { heading: "No discs queued" },
+  render: () => (
+    <StorySection title="The four real cases from the inventory — plex-channels' empty queue, castkit's idle panel, a filtered search, and a dead socket.">
+      <StoryGrid columns={2}>
+        <StoryCell align="stretch" label="empty">
+          <EmptyState
+            description="Insert a disc and rip-deck will pick it up automatically."
+            heading="No discs queued"
+            icon={<InboxIcon />}
+          />
+        </StoryCell>
+
+        <StoryCell
+          align="stretch"
+          label="idle — nothing has happened yet"
+        >
+          <EmptyState
+            description="The channel is connected and waiting for its first playback."
+            heading="Nothing playing"
+            icon={<PlayIcon />}
+          />
+        </StoryCell>
+
+        <StoryCell
+          align="stretch"
+          label="filtered to nothing"
+        >
+          <EmptyState
+            action={
+              <Button appearance="soft" size="sm">
+                Clear filters
+              </Button>
+            }
+            description="No titles match “blade” with the 4K filter on."
+            heading="No matches"
+            icon={<SearchIcon />}
+          />
+        </StoryCell>
+
+        <StoryCell align="stretch" label="failed">
+          <EmptyState
+            action={
+              <Button intent="danger" size="sm">
+                Reconnect
+              </Button>
+            }
+            description="The websocket closed after 3 retries. Nothing has been lost — the tower keeps ripping."
+            heading="Lost the connection"
+            icon={<AlertIcon />}
+          />
+        </StoryCell>
+      </StoryGrid>
+    </StorySection>
+  ),
+}
+
+export const AllStates: Story = {
+  args: { heading: "No discs queued" },
+  render: () => (
+    <StoryGrid columns={2}>
+      <StoryCell
+        align="stretch"
+        label="sm — inside a panel"
+      >
+        <Card heading="Tower alerts" padding="sm">
+          <EmptyState heading="No alerts" size="sm" />
+        </Card>
+      </StoryCell>
+
+      <StoryCell align="stretch" label="md — heading only">
+        <EmptyState heading="No discs queued" />
+      </StoryCell>
+
+      <StoryCell
+        align="stretch"
+        label="md — with description"
+      >
+        <EmptyState
+          description="Insert a disc and rip-deck will pick it up automatically."
+          heading="No discs queued"
+        />
+      </StoryCell>
+
+      <StoryCell
+        align="stretch"
+        label="md — icon, description, action"
+      >
+        <EmptyState
+          action={<Button size="sm">Scan drives</Button>}
+          description="Insert a disc and rip-deck will pick it up automatically."
+          heading="No discs queued"
+          icon={<InboxIcon />}
+        />
+      </StoryCell>
+    </StoryGrid>
+  ),
+}
+
+/**
+ * The container-query story that actually changes something: the
+ * `md` size gains air past `--cq-md`, so the same component is
+ * appropriately tight in a 15rem sidebar and appropriately generous
+ * filling a dashboard — decided by the panel, not by the window.
+ */
+export const Responsive: Story = {
+  args: { heading: "No discs queued" },
+  render: () => (
+    <ContainerBoard>
+      <Card padding="none">
+        <EmptyState
+          description="Insert a disc and rip-deck will pick it up automatically."
+          heading="No discs queued"
+          icon={<InboxIcon />}
+        />
+      </Card>
+    </ContainerBoard>
+  ),
+}
+
+/**
+ * Two things an agent needs from an empty state: read *why* it is
+ * empty, and reach the way out. So the heading carries the reason
+ * and Tab lands on the action.
+ */
+export const Interactive: Story = {
+  args: { heading: "No discs queued" },
+  render: (emptyStateProps) => (
+    <EmptyState
+      {...emptyStateProps}
+      action={<Button size="sm">Scan drives</Button>}
+      description="Insert a disc and rip-deck will pick it up automatically."
+      headingLevel={3}
+    />
+  ),
+}

package/src/EmptyState/EmptyState.test.tsx

@@ -0,0 +1,41 @@
+import { composeStories } from "@storybook/react"
+import { expect, userEvent } from "storybook/test"
+import { test } from "vitest"
+
+import { mountStory } from "../mountStory.testHelpers.ts"
+import { expectAgentDrivable } from "../testing/index.ts"
+import * as stories from "./EmptyState.stories.tsx"
+
+const { Default, Interactive } = composeStories(stories)
+
+test("the heading is the handle", async () => {
+  const { canvas } = await mountStory(Default)
+
+  expectAgentDrivable(canvas, {
+    name: "No discs queued",
+    role: "heading",
+  })
+})
+
+test("the heading level is the caller's, and Tab reaches the way out", async () => {
+  const { canvas } = await mountStory(Interactive)
+
+  // `headingLevel` is a prop rather than a guess, because an empty
+  // state nested in a card is not an `<h2>` — and a document whose
+  // heading levels skip is one a screen-reader user cannot skim.
+  await expect(
+    canvas.getByRole("heading", {
+      level: 3,
+      name: "No discs queued",
+    }),
+  ).toBeVisible()
+
+  const action = expectAgentDrivable(canvas, {
+    name: "Scan drives",
+    role: "button",
+  })
+
+  await userEvent.tab()
+
+  await expect(action).toHaveFocus()
+})

package/src/EmptyState/EmptyState.tsx

@@ -0,0 +1,114 @@
+import type {
+  ComponentPropsWithRef,
+  ReactNode,
+} from "react"
+
+import { toClassName } from "../toClassName.ts"
+
+export type EmptyStateSize = "md" | "sm"
+
+export type EmptyStateProps = Omit<
+  ComponentPropsWithRef<"div">,
+  "children"
+> & {
+  /** Buttons, usually. Rendered under the description. */
+  action?: ReactNode
+  description?: ReactNode
+  /**
+   * A real heading element, and the level is the caller's because
+   * only the caller knows what it sits under. Getting this wrong
+   * breaks a screen reader's document outline, which is how the
+   * fleet's `<h2>`-with-a-`<button>`-inside pattern happened.
+   */
+  headingLevel?: 2 | 3 | 4
+  heading: string
+  icon?: ReactNode
+  size?: EmptyStateSize
+}
+
+const SIZE_CLASS: Record<EmptyStateSize, string> = {
+  sm: "gap-2 px-4 py-6 text-sm",
+  // An empty state in a 300px panel and the same one filling a
+  // dashboard want different air. Container-relative, so it is the
+  // *panel* that decides rather than the window.
+  md: "gap-3 px-6 py-10 text-md cq-md:gap-4 cq-md:px-8 cq-md:py-14",
+}
+
+/**
+ * **Six repos, eleven-plus copies** — plex-channels alone has five
+ * `li.empty`s and castkit six `.idle`s — and not one of them is a
+ * component. Every copy is a bare string in a `<div>`, so "no
+ * results" and "not started yet" and "the socket died" all look
+ * identical, and none of them is findable by role.
+ *
+ * Designed fresh rather than ported: the two repos that had a real
+ * `EmptyState` with typed variants were bambuddy and spoolbuddy,
+ * which are upstream projects rather than Kevin's code, so that
+ * evidence was withdrawn from the plan.
+ *
+ * The shape is deliberately flat — icon, heading, description,
+ * action — with **no variant enum**. An "empty" and an "error" empty
+ * state differ in wording and in whether there is a retry button,
+ * both of which are props already; a `variant="error"` that only
+ * changes a colour invites callers to encode meaning in the colour
+ * alone, which is the one thing a colour cannot carry.
+ *
+ * The heading is what makes it agent-drivable:
+ * `getByRole("heading", { name: "No discs queued" })` works, where
+ * `getByText` against eleven copies of "Nothing here" does not.
+ */
+export const EmptyState = ({
+  action,
+  className,
+  description,
+  heading,
+  headingLevel = 2,
+  icon,
+  size = "md",
+  ...divProps
+}: EmptyStateProps): ReactNode => {
+  const Heading = `h${headingLevel}` as const
+
+  return (
+    <div
+      {...divProps}
+      className={toClassName("@container", className)}
+    >
+      {/* The container and the thing querying it **cannot be the same
+          element** — a container query only matches descendants, so
+          `@container cq-md:px-8` on one `<div>` silently never fires.
+          Nothing errors, the padding just stays small forever. Hence
+          the wrapper: `className` stays on the outer element where a
+          consumer expects it, and the size classes move inside. */}
+      <div
+        className={toClassName(
+          "flex flex-col items-center justify-center text-center",
+          SIZE_CLASS[size],
+        )}
+      >
+        {icon ? (
+          <span
+            aria-hidden="true"
+            className="text-content-muted"
+          >
+            {icon}
+          </span>
+        ) : null}
+
+        <Heading className="font-semibold text-content-primary">
+          {heading}
+        </Heading>
+
+        {description ? (
+          <p className="max-w-prose text-content-secondary">
+            {description}
+          </p>
+        ) : null}
+
+        {action ? (
+          <div className="mt-1">{action}</div>
+        ) : null}
+      </div>
+    </div>
+  )
+}

package/src/IconButton/IconButton.mdx

@@ -0,0 +1,34 @@
+import { Canvas, Controls, Meta } from "@storybook/addon-docs/blocks";
+
+import * as IconButtonStories from "./IconButton.stories";
+
+<Meta of={IconButtonStories} />
+
+# IconButton
+
+Three repos, three strategies, **no names**: mux-magic hand-writes five SVG components,
+castkit keeps an `ICON_PATHS` map, and plex-channels renders raw glyphs (`↶`, `↷`, `▶`,
+`⚙`, `≡`) straight into a `<button>`.
+
+A screen reader announces the last of those as "↶", and
+`getByRole("button", { name: "Undo" })` finds nothing at all. That is the concrete reason
+the fleet is not agent-drivable today, and the reason this component exists as something
+other than `<Button sizing="icon">`.
+
+<Canvas of={IconButtonStories.Default} />
+
+## Props
+
+<Controls />
+
+## The one rule
+
+`label` is **required**, is a `string`, and becomes `aria-label`. There is no way to render
+this component without a name, which is the point: the type system asks the question that
+three hand-rolled versions forgot.
+
+The library ships **no icons**. `children` is whatever the app already has — lucide (ISC)
+is the fleet recommendation — and it is hidden from assistive technology, because the label
+already names the control.
+
+<Canvas of={IconButtonStories.AllVariants} />