@charcuterie/ui 0.1.0

package/src/Button/Button.stories.tsx

@@ -0,0 +1,175 @@
+import type { Meta, StoryObj } from "@storybook/react"
+
+import {
+  controlSizeArgType,
+  intentArgType,
+} from "../argTypes.storyHelpers.ts"
+import {
+  ContainerBoard,
+  StoryCell,
+  StoryGrid,
+  StoryRow,
+  StorySection,
+} from "../board.storyHelpers.tsx"
+import type { IntentAppearance } from "../intentStyles.ts"
+import { Button } from "./Button.tsx"
+
+const INTENTS = [
+  "neutral",
+  "accent",
+  "success",
+  "warning",
+  "danger",
+  "info",
+] as const
+
+const APPEARANCES: IntentAppearance[] = [
+  "solid",
+  "soft",
+  "outline",
+  "ghost",
+]
+
+const meta = {
+  title: "Components/Button",
+  component: Button,
+  parameters: { layout: "padded" },
+  argTypes: {
+    intent: intentArgType,
+    size: controlSizeArgType,
+  },
+  // The component's own defaults, restated. Storybook has not
+  // seeded `args` from a docgen `defaultValue` since v7, so without
+  // this the props table prints `"solid"` in the Default column
+  // while the radio beside it has nothing selected.
+  args: {
+    appearance: "solid",
+    intent: "accent",
+    isDisabled: false,
+    isFullWidth: false,
+    isLoading: false,
+    size: "md",
+    sizing: "control",
+  },
+} satisfies Meta<typeof Button>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+export const Default: Story = {
+  args: { children: "Start rip" },
+}
+
+export const AllVariants: Story = {
+  args: { children: "Start rip" },
+  render: (buttonProps) => (
+    <StorySection title="Six intents x four appearances. The whole of seven repos' worth of primary/secondary/danger/ghost.">
+      <StoryGrid columns={4}>
+        {APPEARANCES.flatMap((appearance) =>
+          INTENTS.map((intent) => (
+            <StoryCell
+              key={`${appearance}-${intent}`}
+              label={`${appearance} · ${intent}`}
+            >
+              <Button
+                {...buttonProps}
+                appearance={appearance}
+                intent={intent}
+              >
+                {intent}
+              </Button>
+            </StoryCell>
+          )),
+        )}
+      </StoryGrid>
+    </StorySection>
+  ),
+}
+
+export const AllSizes: Story = {
+  args: { children: "Start rip" },
+  render: (buttonProps) => (
+    <StorySection title="Sizes come from the density axis — flip Density in the toolbar and every one of these changes with no prop change and no re-render.">
+      <StoryRow>
+        <Button {...buttonProps} size="sm">
+          Small
+        </Button>
+
+        <Button {...buttonProps} size="md">
+          Medium
+        </Button>
+
+        <Button {...buttonProps} size="lg">
+          Large
+        </Button>
+      </StoryRow>
+    </StorySection>
+  ),
+}
+
+/**
+ * Hover, active, and focus are real here, not simulated: the
+ * pseudo-states addon forces them, which is the only way to review
+ * a hover colour in a static board.
+ *
+ * `focusVisible` is forced the same way rather than tabbed to. A
+ * board that has to be *driven* to show its states is a test
+ * wearing a demo's clothes — and the tab count silently depended on
+ * how many focusable cells sat above it.
+ */
+export const AllStates: Story = {
+  args: { children: "Start rip" },
+  parameters: {
+    pseudo: {
+      active: ["#active"],
+      focusVisible: ["#focus-target"],
+      hover: ["#hover"],
+    },
+  },
+  render: (buttonProps) => (
+    <StoryGrid columns={3}>
+      <StoryCell label="default">
+        <Button {...buttonProps} />
+      </StoryCell>
+
+      <StoryCell label="hover (forced)">
+        <Button {...buttonProps} id="hover" />
+      </StoryCell>
+
+      <StoryCell label="active (forced)">
+        <Button {...buttonProps} id="active" />
+      </StoryCell>
+
+      <StoryCell label="focus-visible (forced)">
+        <Button {...buttonProps} id="focus-target" />
+      </StoryCell>
+
+      <StoryCell label="disabled">
+        <Button {...buttonProps} isDisabled />
+      </StoryCell>
+
+      <StoryCell label="loading">
+        <Button {...buttonProps} isLoading />
+      </StoryCell>
+    </StoryGrid>
+  ),
+}
+
+/**
+ * Disabled *and* announced. The spinner's label lives in a
+ * `role="status"`, so a screen reader hears the work start rather
+ * than only seeing it.
+ */
+export const Loading: Story = {
+  args: { children: "Ripping disc 3", isLoading: true },
+}
+
+export const Responsive: Story = {
+  args: { children: "Start rip", isFullWidth: true },
+  render: (buttonProps) => (
+    <ContainerBoard>
+      <Button {...buttonProps} />
+    </ContainerBoard>
+  ),
+}

package/src/Button/Button.test.tsx

@@ -0,0 +1,114 @@
+import {
+  composeStories,
+  composeStory,
+} from "@storybook/react"
+import { expect, fn, userEvent } from "storybook/test"
+import { test } from "vitest"
+
+import { mountStory } from "../mountStory.testHelpers.ts"
+import { expectAgentDrivable } from "../testing/index.ts"
+import meta, * as stories from "./Button.stories.tsx"
+
+const { AllStates, Default, Loading } =
+  composeStories(stories)
+
+test("is drivable by role and name", async () => {
+  const { canvas } = await mountStory(Default)
+
+  expectAgentDrivable(canvas, {
+    name: "Start rip",
+    role: "button",
+  })
+})
+
+/**
+ * The keyboard contract, asserted rather than assumed: Tab reaches
+ * it, Enter activates, Space activates. Every hand-rolled
+ * `<div onClick>` in the fleet fails all three.
+ */
+test("Tab reaches it, and Enter and Space both activate", async () => {
+  const onClick = fn()
+
+  const { canvas } = await mountStory(
+    composeStory(
+      { args: { children: "Start rip", onClick } },
+      meta,
+    ),
+  )
+
+  const button = expectAgentDrivable(canvas, {
+    name: "Start rip",
+    role: "button",
+  })
+
+  await userEvent.tab()
+
+  await expect(button).toHaveFocus()
+
+  await userEvent.keyboard("{Enter}")
+
+  await expect(onClick).toHaveBeenCalledTimes(1)
+
+  await userEvent.keyboard(" ")
+
+  await expect(onClick).toHaveBeenCalledTimes(2)
+})
+
+test("a disabled button is skipped by Tab and ignores a click", async () => {
+  const onClick = fn()
+
+  const { canvas } = await mountStory(
+    composeStory(
+      {
+        args: {
+          children: "Start rip",
+          isDisabled: true,
+          onClick,
+        },
+      },
+      meta,
+    ),
+  )
+
+  const button = canvas.getByRole("button", {
+    name: "Start rip",
+  })
+
+  await userEvent.click(button)
+
+  // A `<div role="button">` with a guard clause looks the same and
+  // is not the same: a real `disabled` is skipped by Tab, ignored
+  // by click, and reported to AT.
+  await expect(onClick).not.toHaveBeenCalled()
+  await expect(button).toBeDisabled()
+
+  await userEvent.tab()
+
+  await expect(button).not.toHaveFocus()
+})
+
+test("loading disables the button and announces the work", async () => {
+  const { canvas } = await mountStory(Loading)
+
+  const button = expectAgentDrivable(canvas, {
+    name: /Ripping disc 3/,
+    role: "button",
+  })
+
+  await expect(button).toBeDisabled()
+  await expect(button).toHaveAttribute("aria-busy", "true")
+
+  // The spinner's label lives in a `role="status"`, so a screen
+  // reader hears the work start rather than only seeing it.
+  await expect(
+    canvas.getByRole("status"),
+  ).toBeInTheDocument()
+})
+
+test("the states board really renders a busy button", async () => {
+  const { canvas } = await mountStory(AllStates)
+
+  await expect(
+    canvas.getByRole("button", { name: /loading/i }),
+  ).toHaveAttribute("aria-busy", "true")
+})

package/src/Button/Button.tsx

@@ -0,0 +1,125 @@
+import type {
+  ControlSize,
+  IntentName,
+} from "@charcuterie/tokens"
+import type {
+  ComponentPropsWithRef,
+  ReactNode,
+} from "react"
+
+import {
+  CONTROL_SIZE_CLASS,
+  ICON_CONTROL_SIZE_CLASS,
+} from "../controlStyles.ts"
+import type { IntentAppearance } from "../intentStyles.ts"
+import {
+  DISABLED_CLASS,
+  FOCUS_RING_CLASS,
+  INTENT_APPEARANCE_CLASS,
+  INTENT_HOVER_CLASS,
+} from "../intentStyles.ts"
+import { Spinner } from "../Spinner/Spinner.tsx"
+import { toClassName } from "../toClassName.ts"
+
+export type ButtonProps = Omit<
+  ComponentPropsWithRef<"button">,
+  "disabled"
+> & {
+  appearance?: IntentAppearance
+  iconEnd?: ReactNode
+  iconStart?: ReactNode
+  intent?: IntentName
+  isDisabled?: boolean
+  isFullWidth?: boolean
+  isLoading?: boolean
+  /** What the spinner announces. Not shown. */
+  loadingLabel?: string
+  size?: ControlSize
+  /**
+   * Two sizing modes rather than a second component's worth of
+   * markup. `icon` is square on the control height with no inline
+   * padding, which is what lines an `IconButton` up with the text
+   * button beside it in a toolbar.
+   *
+   * It lives here rather than in `IconButton` because appending a
+   * competing `size-*`/`px-0` to this component's `className` would
+   * be a specificity coin-flip: two utilities setting the same
+   * property, and the winner decided by Tailwind's internal
+   * ordering rather than by the caller.
+   */
+  sizing?: "control" | "icon"
+}
+
+/**
+ * Hand-rolled in **seven repos**, each with its own
+ * primary/secondary/danger/ghost, and this is the component that
+ * erases the most duplication in the fleet.
+ *
+ * Four decisions worth knowing, all of them fixing something an
+ * inventoried repo gets wrong:
+ *
+ *  - **`type="button"` by default.** A `<button>` inside a form
+ *    submits it unless told otherwise, and "clicking the copy icon
+ *    reloaded the page" is a bug every app in the fleet has shipped
+ *    at least once.
+ *  - **`isLoading` disables and announces.** The button goes
+ *    `aria-busy`, the spinner replaces `iconStart` rather than
+ *    being appended (so the label does not jump), and the label
+ *    itself stays — a spinner that swallows the text leaves the
+ *    user unsure what they pressed.
+ *  - **`focus-visible`, never `focus`.** See `FOCUS_RING_CLASS`.
+ *  - **Sizing comes from the density axis**, not from a prop table:
+ *    `size="md"` is 2.25rem on a desktop and 3.25rem on the kiosk,
+ *    with no prop change. `MIN_TOUCH_TARGET_CLASS` is available for
+ *    a control that must clear 44px regardless.
+ *
+ * The accessible name is the children. `IconButton` exists because
+ * a glyph is not a name, and enforcing that in *this* component's
+ * types would mean rejecting `<Button>{icon} Copy</Button>`, which
+ * is fine.
+ */
+export const Button = ({
+  appearance = "solid",
+  children,
+  className,
+  iconEnd,
+  iconStart,
+  intent = "accent",
+  isDisabled = false,
+  isFullWidth = false,
+  isLoading = false,
+  loadingLabel = "Loading…",
+  size = "md",
+  sizing = "control",
+  type = "button",
+  ...buttonProps
+}: ButtonProps): ReactNode => (
+  <button
+    {...buttonProps}
+    aria-busy={isLoading || undefined}
+    className={toClassName(
+      "inline-flex cursor-pointer items-center justify-center rounded-md border font-medium whitespace-nowrap transition-colors duration-(--duration-fast) ease-standard select-none",
+      sizing === "icon"
+        ? ICON_CONTROL_SIZE_CLASS[size]
+        : CONTROL_SIZE_CLASS[size],
+      INTENT_APPEARANCE_CLASS[intent][appearance],
+      INTENT_HOVER_CLASS[intent][appearance],
+      FOCUS_RING_CLASS,
+      DISABLED_CLASS,
+      isFullWidth && "w-full",
+      className,
+    )}
+    disabled={isDisabled || isLoading}
+    type={type}
+  >
+    {isLoading ? (
+      <Spinner label={loadingLabel} size={size} />
+    ) : (
+      iconStart
+    )}
+
+    {children}
+
+    {iconEnd}
+  </button>
+)

package/src/Card/Card.mdx

@@ -0,0 +1,53 @@
+import { Canvas, Controls, Meta } from "@storybook/addon-docs/blocks";
+
+import * as CardStories from "./Card.stories";
+
+<Meta of={CardStories} />
+
+# Card
+
+Five repos, and the reason it is P0 is the `<section>`: give a card a heading and it becomes
+a **landmark**, so `getByRole("region", { name: "Bay 3" })` scopes every query inside it.
+Without that, an agent driving a 16-bay tower sees sixteen identical "Start" buttons and no
+way to say which one it means. The `Interactive` story asserts exactly that.
+
+<Canvas of={CardStories.Default} />
+
+## Props
+
+<Controls />
+
+## Density is not a prop
+
+The withdrawn bambuddy evidence included a `CardDensityProvider`, 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 rather than a context around the cards. `padding`
+stays a prop because a card wrapping a poster grid genuinely has none — a layout fact, not
+a density one.
+
+## Names must be unique
+
+Two `<section>`s sharing an accessible name is axe's `landmark-unique`, and it is a real
+finding rather than a technicality: a screen-reader user navigating by landmark gets two
+"Bay 3" regions and no way to tell them apart. A card with no heading is not a landmark at
+all, deliberately — it has nothing to be named.
+
+`raised` means *more separated from base*, not *lighter*, which is why light mode's base is
+`#F5F7FA` and its raised is white.
+
+<Canvas of={CardStories.AllVariants} />
+
+## Container queries, not media queries
+
+> **One constraint that comes with the territory.** `container-type: inline-size` implies
+> `contain: inline-size`, so a `Card` may not be sized by its own contents. In a grid track,
+> a block flow, or a `flex-1` slot it is fine — that is nearly every real placement. Drop one
+> into a shrink-to-fit parent (`items-start`, an `inline-flex` row) and it collapses to
+> min-content, wrapping every line after one word. Give it a definite inline size there.
+
+
+The header stacks below `--cq-sm` and sits on one row above it, and the container is the
+**card**. The same card in a sidebar and full-bleed on a dashboard is the case a media query
+cannot tell apart, and it is where the fleet's poster grids look wrong today.
+
+<Canvas of={CardStories.Responsive} />

package/src/Card/Card.stories.tsx

@@ -0,0 +1,207 @@
+import type { Meta, StoryObj } from "@storybook/react"
+
+import { toStoryChoice } from "../argTypes.storyHelpers.ts"
+import { Badge } from "../Badge/Badge.tsx"
+import { Button } from "../Button/Button.tsx"
+import {
+  ContainerBoard,
+  StoryCell,
+  StoryGrid,
+  StorySection,
+} from "../board.storyHelpers.tsx"
+import { IconButton } from "../IconButton/IconButton.tsx"
+import { SettingsIcon } from "../icons.storyHelpers.tsx"
+import { ProgressBar } from "../ProgressBar/ProgressBar.tsx"
+import { Card, ELEVATION_CLASS } from "./Card.tsx"
+
+const meta = {
+  title: "Components/Card",
+  component: Card,
+  parameters: { layout: "padded" },
+  argTypes: {
+    elevation: toStoryChoice(
+      Object.keys(
+        ELEVATION_CLASS,
+      ) as (keyof typeof ELEVATION_CLASS)[],
+    ),
+  },
+  args: {
+    elevation: "low",
+    headingLevel: 2,
+    padding: "md",
+    surface: "raised",
+  },
+} satisfies Meta<typeof Card>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+export const Default: Story = {
+  args: {
+    children: (
+      <p className="text-content-secondary text-sm">
+        Ripping <em>Blade Runner (1982)</em> — title 4 of 9.
+      </p>
+    ),
+    heading: "Bay 3",
+  },
+}
+
+export const AllVariants: Story = {
+  args: { children: "Content" },
+  render: () => (
+    <StorySection title="Three surfaces x four elevations. `raised` means more separated from base, not lighter — which is why light mode's base is #F5F7FA and its raised is white.">
+      <StoryGrid columns={3}>
+        {(["base", "raised", "sunken"] as const).flatMap(
+          (surface) =>
+            (
+              ["none", "low", "medium", "high"] as const
+            ).map((elevation) => (
+              <StoryCell
+                align="stretch"
+                key={`${surface}-${elevation}`}
+                label={`${surface} · ${elevation}`}
+              >
+                <Card
+                  elevation={elevation}
+                  // Distinct, because two `<section>`s sharing an
+                  // accessible name is an axe `landmark-unique`
+                  // violation — a real one: a screen-reader user
+                  // navigating by landmark gets two "raised"
+                  // regions and no way to tell them apart.
+                  heading={`${surface} · ${elevation}`}
+                  surface={surface}
+                >
+                  <p className="text-content-secondary text-sm">
+                    shadow-{elevation}
+                  </p>
+                </Card>
+              </StoryCell>
+            )),
+        )}
+      </StoryGrid>
+    </StorySection>
+  ),
+}
+
+export const AllStates: Story = {
+  args: { children: "Content" },
+  render: () => (
+    <StoryGrid columns={2}>
+      <StoryCell align="stretch" label="heading only">
+        <Card heading="Bay 1" />
+      </StoryCell>
+
+      <StoryCell
+        align="stretch"
+        label="no heading — not a landmark, by design"
+      >
+        <Card>
+          <p className="text-content-secondary text-sm">
+            A card with no name cannot be a region, so it is
+            not pretending to be one.
+          </p>
+        </Card>
+      </StoryCell>
+
+      <StoryCell
+        align="stretch"
+        label="heading + actions + footer"
+      >
+        <Card
+          actions={
+            <>
+              <Badge intent="info" size="sm">
+                ripping
+              </Badge>
+
+              <IconButton
+                appearance="ghost"
+                label="Bay 3 settings"
+                size="sm"
+              >
+                <SettingsIcon />
+              </IconButton>
+            </>
+          }
+          footer="Started 14:02 · MakeMKV 1.17.8"
+          heading="Bay 2"
+        >
+          <ProgressBar
+            isValueShown
+            label="Ripping title 4 of 9"
+            value={47}
+          />
+        </Card>
+      </StoryCell>
+
+      <StoryCell
+        align="stretch"
+        label="padding=none — for a poster grid"
+      >
+        <Card heading="Recently added" padding="none">
+          <div className="h-16 rounded-md bg-surface-sunken" />
+        </Card>
+      </StoryCell>
+    </StoryGrid>
+  ),
+}
+
+/**
+ * The header stacks below `--cq-sm` and sits on one row above it —
+ * and the container is the *card*, not the window, which is the case
+ * a media query genuinely cannot express: the same card in a sidebar
+ * and full-bleed on a dashboard.
+ */
+export const Responsive: Story = {
+  args: { children: "Content" },
+  render: () => (
+    <ContainerBoard>
+      {(width) => (
+        <Card
+          actions={
+            <Button appearance="soft" size="sm">
+              Start rip
+            </Button>
+          }
+          heading={`Bay 3 at ${width} — Blade Runner (1982)`}
+        >
+          <ProgressBar
+            label={`Ripping title 4 of 9 at ${width}`}
+            value={47}
+          />
+        </Card>
+      )}
+    </ContainerBoard>
+  ),
+}
+
+/**
+ * Two identical "Start rip" buttons on one page.
+ *
+ * Unscoped, `getByRole("button", { name: "Start rip" })` is
+ * ambiguous — which is exactly what `expectAgentDrivable` refuses.
+ * Scoping by region is the fix, and it only exists because the cards
+ * are named. That is the whole a11y argument for this component: an
+ * agent driving a 16-bay tower can say *which* "Start" it means.
+ */
+export const Interactive: Story = {
+  args: { children: "Content" },
+  render: () => (
+    <div className="flex flex-col gap-3">
+      {[3, 4].map((bay) => (
+        <Card
+          actions={<Button size="sm">Start rip</Button>}
+          heading={`Bay ${bay}`}
+          key={bay}
+        >
+          <ProgressBar
+            label={`Bay ${bay} progress`}
+            value={bay * 10}
+          />
+        </Card>
+      ))}
+    </div>
+  ),
+}