@charcuterie/ui 3.0.0 → 3.2.0

package/src/Badge/Badge.test.tsx

@@ -8,8 +8,13 @@ import { test } from "vitest"
 import { mountStory } from "../mountStory.testHelpers.ts"
 import meta, * as stories from "./Badge.stories.tsx"
 
-const { Default, Interactive, Responsive } =
-  composeStories(stories)
+const {
+  Categorical,
+  CategoricalLabels,
+  Default,
+  Interactive,
+  Responsive,
+} = composeStories(stories)
 
 test("the text is queryable, which is what an agent matches on", async () => {
   const { canvas } = await mountStory(Default)
@@ -151,3 +156,153 @@ test("the responsive board shows both modes at three widths", async () => {
     canvas.getAllByText(LONG_LABEL),
   ).toHaveLength(6)
 })
+
+// ---------------------------------------------------------------
+// The categorical family
+// ---------------------------------------------------------------
+
+/**
+ * The assertion this component most needs, and the one every other
+ * test here structurally cannot make.
+ *
+ * Docket shipped `--color-danger-9` — a Radix-style step Charcuterie
+ * has never had. It resolved to nothing, painted transparent, and
+ * passed every "is the badge rendered" check in the suite, because
+ * a rendered element with no background is still a rendered
+ * element. `getByText` cannot see it. `toBeVisible` cannot see it.
+ * The only thing that can is asking the browser what colour it
+ * actually painted.
+ */
+const getPaintedColours = (badge: HTMLElement) => {
+  const style = globalThis.getComputedStyle(badge)
+
+  return {
+    background: style.backgroundColor,
+    border: style.borderTopColor,
+    text: style.color,
+  }
+}
+
+const TRANSPARENT = "rgba(0, 0, 0, 0)"
+
+test("a categorical badge paints a real colour, not a name that resolves to nothing", async () => {
+  const { canvas } = await mountStory(
+    composeStory(
+      { args: { categorical: 5, children: "Homelab" } },
+      meta,
+    ),
+  )
+
+  const badge = canvas.getByText("Homelab")
+    .parentElement as HTMLElement
+
+  const painted = getPaintedColours(badge)
+
+  expect(painted.background).not.toBe(TRANSPARENT)
+
+  expect(painted.border).not.toBe(TRANSPARENT)
+
+  // …and it is *the token's* value, not merely some colour. A
+  // utility resolving to an inherited or UA default would clear the
+  // check above and still be the bug.
+  const expected = globalThis
+    .getComputedStyle(document.documentElement)
+    .getPropertyValue("--color-categorical-5-surface")
+    .trim()
+
+  expect(expected).toMatch(/^#[0-9A-Fa-f]{6}$/)
+
+  const [red, green, blue] = [1, 3, 5].map((offset) =>
+    Number.parseInt(expected.slice(offset, offset + 2), 16),
+  )
+
+  expect(painted.background).toBe(
+    `rgb(${red}, ${green}, ${blue})`,
+  )
+})
+
+test("ten indexes paint ten different colours", async () => {
+  // The DOM half of the distinctness gate in `@charcuterie/tokens`.
+  // That one measures the token values; this one measures what the
+  // browser did with them, which is where an index silently falling
+  // back to its neighbour's utility would show up.
+  const { canvas } = await mountStory(Categorical)
+
+  const solids = new Set(
+    canvas
+      .getAllByText(
+        /^(Red|Orange|Amber|Lime|Green|Teal|Blue|Indigo|Purple|Pink)$/,
+      )
+      .map(
+        (label: HTMLElement) =>
+          getPaintedColours(
+            label.parentElement as HTMLElement,
+          ).background,
+      ),
+  )
+
+  solids.delete(TRANSPARENT)
+
+  // Three appearances x ten indexes, and `outline` is transparent
+  // by design — so twenty painted fills, all different.
+  expect(solids.size).toBe(20)
+})
+
+test("the same label name always gets the same colour", async () => {
+  // The whole point of `getCategoricalIndex`: a hundred rows that
+  // predate the feature need no migration, and the answer must not
+  // move between renders, machines, or a server-rendered copy.
+  const first = await mountStory(CategoricalLabels)
+
+  const firstColour = getPaintedColours(
+    first.canvas.getByText("Homelab")
+      .parentElement as HTMLElement,
+  ).background
+
+  const second = await mountStory(CategoricalLabels)
+
+  expect(
+    getPaintedColours(
+      second.canvas.getByText("Homelab")
+        .parentElement as HTMLElement,
+    ).background,
+  ).toBe(firstColour)
+
+  // And two different names do not all collapse onto one colour,
+  // which a stable-but-useless hash would also satisfy.
+  expect(
+    getPaintedColours(
+      second.canvas.getByText("Errands")
+        .parentElement as HTMLElement,
+    ).background,
+  ).not.toBe(firstColour)
+})
+
+test("a categorical badge keeps every behaviour an intent badge has", async () => {
+  // `overflow`, `size` and the clipping readout are the component's,
+  // not the intent's — but a new prop threaded through a class map
+  // is exactly where that quietly stops being true.
+  const { canvasElement } = await mountStory(
+    composeStory(
+      {
+        args: {
+          categorical: 8,
+          children: LONG_LABEL,
+          overflow: "truncate",
+        },
+      },
+      meta,
+    ),
+  )
+
+  canvasElement.style.inlineSize = "10rem"
+
+  const badge =
+    canvasElement.firstElementChild as HTMLElement
+
+  await waitFor(() => {
+    expect(badge).toHaveAttribute("title", LONG_LABEL)
+  })
+
+  expect(badge.textContent).toBe(LONG_LABEL)
+})

package/src/Badge/Badge.tsx

@@ -1,9 +1,13 @@
-import type { IntentName } from "@charcuterie/tokens"
+import type {
+  CategoricalIndex,
+  IntentName,
+} from "@charcuterie/tokens"
 import type {
   ComponentPropsWithRef,
   ReactNode,
 } from "react"
 
+import { CATEGORICAL_APPEARANCE_CLASS } from "../categoricalStyles.ts"
 import type { BadgeSize } from "../controlStyles.ts"
 import { BADGE_SIZE_CLASS } from "../controlStyles.ts"
 import type { IntentAppearance } from "../intentStyles.ts"
@@ -13,6 +17,22 @@ import { useIsTextClipped } from "./useIsTextClipped.ts"
 
 export type BadgeProps = ComponentPropsWithRef<"span"> & {
   appearance?: Exclude<IntentAppearance, "ghost">
+  /**
+   * A numbered, **non-semantic** colour: 1–10, no meaning attached.
+   *
+   * For a badge whose colour the user picked — a Docket label, a
+   * project, a chart series — where `intent` would be a lie. A
+   * "Homelab" label is not a `danger`, and the palette is curated
+   * and contrast-gated in both schemes precisely so the user cannot
+   * pick one that is unreadable. `getCategoricalIndex(key)` from
+   * `@charcuterie/tokens` is the stable fallback for a row nobody
+   * has chosen a colour for yet.
+   *
+   * Mutually exclusive with `intent` **in the type**: a badge is one
+   * colour, and passing both is a question with no answer rather
+   * than a precedence rule to remember.
+   */
+  categorical?: CategoricalIndex
   children: ReactNode
   icon?: ReactNode
   intent?: IntentName
@@ -28,7 +48,14 @@ export type BadgeProps = ComponentPropsWithRef<"span"> & {
    */
   overflow?: "truncate" | "wrap"
   size?: BadgeSize
-}
+  /**
+   * The exclusivity, and it is deliberately the *only* thing this
+   * arm says. Both props stay declared above so `react-docgen` can
+   * see them and `storyControls.test.ts` can require a control for
+   * each; this arm's whole job is to refuse the case where both
+   * arrive with a value.
+   */
+} & ({ categorical?: never } | { intent?: never })
 
 /**
  * Four repos, and rip-deck declares the **identical** `TONE_CLASS`
@@ -54,6 +81,16 @@ export type BadgeProps = ComponentPropsWithRef<"span"> & {
  * asserts the text is queryable, which is what an agent actually
  * matches on.
  *
+ * **`intent` or `categorical`, never both.** The two families are
+ * both seven roles wide and both paint a pill, and they answer
+ * opposite questions: an intent is a *claim* the design system
+ * makes (`danger` says what happens if you press the thing), and a
+ * categorical index is a claim about nothing at all — it is a
+ * colour a user picked for a label. Which is why the exclusivity is
+ * in the type rather than in a precedence rule: a badge is one
+ * colour, and `<Badge intent="danger" categorical={3}>` is a
+ * question with no answer.
+ *
  * **It is capped at its container.** `shrink-0` and
  * `whitespace-nowrap` alone let a long label paint straight through
  * the neighbouring column — no clipping, no error, just a pill lying
@@ -62,6 +99,7 @@ export type BadgeProps = ComponentPropsWithRef<"span"> & {
  */
 export const Badge = ({
   appearance = "soft",
+  categorical,
   children,
   className,
   icon,
@@ -87,7 +125,15 @@ export const Badge = ({
             "rounded-2xl"
           : "rounded-full",
         BADGE_SIZE_CLASS[size],
-        INTENT_APPEARANCE_CLASS[intent][appearance],
+        // A ternary rather than a merged map: the two are indexed
+        // by different keys, and `undefined` is the only honest
+        // discriminant once the type has already refused the case
+        // where both arrive.
+        categorical === undefined
+          ? INTENT_APPEARANCE_CLASS[intent][appearance]
+          : CATEGORICAL_APPEARANCE_CLASS[categorical][
+              appearance
+            ],
         className,
       )}
       // Only when something is actually hidden. A tooltip on every

package/src/Board/Board.mdx

@@ -0,0 +1,199 @@
+import { Canvas, Controls, Meta } from "@storybook/addon-docs/blocks";
+
+import * as BoardStories from "./Board.stories";
+
+<Meta of={BoardStories} />
+
+# Board
+
+Lanes of cards, sized by their **container**, moved by keyboard or by pointer — and with
+**no drag-and-drop dependency**.
+
+<Canvas of={BoardStories.Default} />
+
+## Props
+
+<Controls />
+
+## The container rule, and why it is the whole component
+
+There is no media query anywhere in `Board`, `BoardCard` or `BoardLaneList`, and adding one
+would be a defect rather than a shortcut. Two facts make window width useless here, and they
+compound:
+
+- **A lane in a three-up board is narrow on any monitor.** Three lanes across a 1600px window
+  is ~500px each — a phone's worth of room, on a 4K display, maximised.
+- **A zoomed browser lies about pixels.** A 1500px window at 175% zoom is ~860 effective CSS
+  pixels, so the number a `@media` query reads is not the number of pixels anything has.
+
+So there are **two nested containers**, answering two different questions:
+
+| Container | Decides |
+| --- | --- |
+| the board's own box | how many lanes are on screen — three-up at `cq-lg`, otherwise one lane and a segmented control |
+| each lane's wrapper | what shape a card is — two lines, one line, or its own card |
+
+`Responsive` is the only honest way to show it: three fixed-width panels inside one browser
+window that never moves. Resizing the viewport would prove nothing, because the thing that
+changed is the component's container, not the window.
+
+<Canvas of={BoardStories.Responsive} />
+
+The narrow panel there is **not a phone**. It is the same board in a sidebar, in a split
+window, or on a display somebody has zoomed to 175% — and a media query cannot tell any of
+those apart from a maximised 4K window.
+
+### The three card shapes
+
+Straight from the consumer requirement, which is specific because the owner answered *"which
+row style?"* with **"all three, depending"**:
+
+| The lane is | The card is |
+| --- | --- |
+| narrower than `cq-sm` (24rem) | **two lines** — title clamped to two, metadata underneath, trailing slot beside it |
+| `cq-sm` to `cq-lg` | **one line** — title ellipsised, metadata right-aligned |
+| `cq-lg` (48rem) and wider | **a card** — its own border, surface and elevation instead of a divider in a list |
+
+It dissolved a bug rather than only satisfying a taste: a *fixed* two-line row collapsed its
+title to `a…` inside a narrow lane, because the metadata beside it could not shrink. A card
+sized by its container has no such state to be in.
+
+### The wrappers are load-bearing
+
+A container query matches **descendants only**, never the element that declares the
+container. So the lane's panel cannot be the container *and* take its own frame off at
+`cq-lg`; the `@container` sits on a wrapper `<div>` and the panel inside it does the
+querying. Same reason `EmptyState` has one. Written on one element it compiles, generates
+real CSS, and silently never fires — which is why `sourceRules.test.ts` fails on it.
+
+## Moving a card, and the drag-and-drop decision
+
+**No DnD library is taken as a dependency.** The full reasoning — licence, provenance, bundle
+cost, and what a general DnD library would actually be buying for one card going into one
+lane — is in
+[the decision record](https://github.com/Sawtaytoes/charcuterie/blob/master/docs/decisions/2026-08-19-the-board-owns-the-move-and-takes-no-drag-and-drop-dependency.md).
+
+The move is one control with two drivers, and they commit through the same `onMove`:
+
+1. **A `Menu` on every card**, listing the other lanes. This is the **primary** path, not an
+   accessible alternative to a real one. It is the only one that works from the keyboard, the
+   only one a screen reader can drive, the only one that works on touch without a long-press
+   convention nobody discovers — and the only one available in the Narrow View, where the
+   other lanes are not on screen to drop onto.
+2. **Pointer dragging from the same handle.** Pointer Events, so mouse, touch and pen are one
+   code path, with `setPointerCapture` so the drag survives the pointer leaving the card.
+   Escape abandons it.
+
+<Canvas of={BoardStories.Interactive} />
+
+Every move is announced in a `role="status"` region that names the **destination and the
+position** — "Moved *X* to In Progress, position 3 of 6." That is the feedback a sighted user
+gets free from watching the card land, and the thing almost every drag implementation forgets
+to say out loud.
+
+### Why not `draggable="true"`
+
+The zero-dependency instinct, and the wrong one. HTML5 drag-and-drop does not fire on touch at
+all, its drag image is a browser-drawn ghost with no styling hook worth using, and
+`dataTransfer` is readable only inside a real `drop` — which makes a live drop indicator
+awkward. Pointer Events cost the same (nothing) and cover every input.
+
+### The move handle is a word by default
+
+`Board` ships **no icon**, because a `⋮` renders as nothing where the font lacks it — this
+sandbox's chromium, the kiosk image, the ePaper build
+([decision](https://github.com/Sawtaytoes/charcuterie/blob/master/docs/decisions/2026-07-29-ship-no-icons-and-no-symbol-glyphs.md)).
+An app that already owns a glyph set passes `moveIcon` and buys back ~55px a row, which in a
+500px lane is the difference between twenty characters of title and thirty.
+
+<Canvas of={BoardStories.AllVariants} />
+
+**No `onMove` means read-only**, all or nothing: no handles, no menus, no drag. A per-card
+`isMovable` would put the decision in the data, where a card that cannot move looks identical
+to one nobody has thought about.
+
+## Where the line is drawn
+
+`Board` owns lanes, counts, truncation, empty states and the move. It does **not** own:
+
+| Not here | Because |
+| --- | --- |
+| **Data** | It is a view of a list the consumer owns. `onMove` hands back a `fromIndex`/`toIndex` pair; the consumer splices. |
+| **Virtualisation** | A lane truncates by construction — `itemCount` is the true total, `items` is what you chose to paint, and the difference becomes "+ n more". *"Long lanes truncate with an honest `+ n more` rather than scrolling forever."* There is nothing left to window. |
+| **The cross-lane "needs attention" panel** | It reaches across every lane, so it is not a lane; it is absent when empty, so the board cannot reserve room for it; and it is already `Alert`. Composing it keeps `Board` about lanes and keeps the banner reusable above a list that is not a board. |
+| **Sorting and filtering** | Both are operations on the array you pass in. |
+
+<Canvas of={BoardStories.InBoardScreen} />
+
+That story is the copy-wholesale template: a page heading, an `Alert` for what needs
+attention, and the board under it with `headingLevel={2}` so the outline stays whole.
+
+## `toIndex` is already corrected for the removal
+
+The most common bug in a hand-rolled board, folded into the component instead:
+
+```tsx
+<Board
+  label="Today"
+  lanes={lanes}
+  onMove={(move) => {
+    setLanes((current) =>
+      current.map((lane) => {
+        const kept =
+          lane.key === move.fromLaneKey
+            ? lane.items.filter((item) => item.key !== move.itemKey)
+            : lane.items
+
+        if (lane.key !== move.toLaneKey) {
+          return { ...lane, items: kept }
+        }
+
+        return {
+          ...lane,
+          items: [
+            ...kept.slice(0, move.toIndex),
+            moved,
+            ...kept.slice(move.toIndex),
+          ],
+        }
+      }),
+    )
+  }}
+/>
+```
+
+No arithmetic. A within-lane move quoted against the un-spliced list is one too high for every
+position below the origin, so the component subtracts it once, in
+[`toSettledIndex`](https://github.com/Sawtaytoes/charcuterie/blob/master/packages/ui/src/Board/boardMove.ts),
+which is unit-tested in Node against fixtures — including the tie where a card dropped back on
+its own midpoint must be **no move at all**.
+
+## Accessibility
+
+- The board is a **named landmark**; each lane is a `role="group"`, not a second landmark. A
+  board with four `region`s buries the page's real ones, and two boards on one page put two
+  landmarks called "Todo" in the document. Same call the
+  [accordion panel](https://github.com/Sawtaytoes/charcuterie/blob/master/docs/decisions/2026-07-31-an-accordion-panel-is-a-group-not-a-landmark.md)
+  made. It is a `<div role="group">` rather than a `<section role="group">` because axe's
+  `landmark-unique` matches `section[aria-labelledby]` on the element and audits it as a
+  landmark even after the role is overridden.
+- **The priority bar's meaning is in words.** `accentIntent` paints it; `accentLabel` puts the
+  same fact in a `VisuallyHidden`, because colour alone fails WCAG 1.4.1 and is invisible to
+  every screen reader. Do the same for anything you put in `marks` — a bare coloured dot is
+  the identical failure.
+- **`headingLevel` is yours.** Only the caller knows what the board sits under; an `<h3>`
+  directly below the page `<h1>` is an axe `heading-order` failure.
+- Every move handle's accessible name says *which* card and *where it is now*. Thirty controls
+  named "Move" are thirty indistinguishable buttons to a screen reader and to
+  `getByRole("button", { name })`.
+
+<Canvas of={BoardStories.AllStates} />
+
+## Never invent a token name
+
+The colour families here are `--color-intent-<intent>-<role>`, plus `surface`, `content` and
+`border`. **There is no numeric scale.** Docket's first board painted every priority bar with
+`--color-danger-9`, a Radix-style name this token set has never had, so every bar was
+transparent — while every "is it rendered" assertion passed and only looking at the image
+caught it. `accentIntent` is typed as `IntentName` for exactly that reason: a wrong value is a
+compile error rather than an invisible rectangle.