@charcuterie/ui 3.23.0 → 3.24.0

package/src/Board/Board.test.tsx

@@ -20,6 +20,7 @@ const {
   Interactive,
   MarkdownTitles,
   LinkedLaneHeadings,
+  MoveHandleByWidth,
   Responsive,
 } = composeStories(stories)
 
@@ -467,3 +468,84 @@ test("draws a project's colour on the card's own edge", async () => {
     }),
   )
 })
+
+/**
+ * The handle wears the gesture that can succeed, and nothing else.
+ *
+ * This is the bug QueuePilot shipped twice, from both directions. A
+ * `≡` grip in a one-lane board taught a drag with nowhere to land —
+ * *"There's no right-click or anything. How do I move these?"* — and
+ * taking the grip away at every width broke the wide board, where
+ * dragging is exactly what a person reaches for.
+ *
+ * Both affordances are in the DOM at both widths and CSS decides,
+ * so this asserts on what is PAINTED. A container query is the only
+ * honest way to ask: the two boards below sit in a 72rem frame and a
+ * 24rem frame inside one window that never moves.
+ */
+test("a wide board's handle is the app's grip, not the word", async () => {
+  const { canvas } = await mountStory(MoveHandleByWidth)
+
+  const handle = within(
+    canvas.getByRole("region", {
+      name: "Today, wide enough to drag",
+    }),
+  ).getByRole("button", {
+    name: "Move Retire the second scheduler and fold its jobs into the broker, currently in Todo",
+  })
+
+  await expect(
+    within(handle).getByText("Move"),
+  ).not.toBeVisible()
+
+  await expect(handle.querySelector("svg")).toBeVisible()
+
+  // And it is still the SQUARE icon button it was before the word
+  // joined it in the DOM. `sizing` is a prop and cannot be two
+  // values, so the button is `control`-sized underneath and takes
+  // `ICON_CONTROL_SIZE_CLASS`'s width and `px-0` back at this width.
+  // Getting that wrong costs every card in every lane ~20px of
+  // title, silently — this board renders pixel-identically to the
+  // one before the change, and that is the assertion.
+  await expect(handle.offsetWidth).toBe(handle.offsetHeight)
+})
+
+test("a one-lane board's handle says Move, whatever the app passed", async () => {
+  const { canvas } = await mountStory(MoveHandleByWidth)
+
+  const handle = within(
+    canvas.getByRole("region", {
+      name: "Today, one lane at a time",
+    }),
+  ).getByRole("button", {
+    name: "Move Retire the second scheduler and fold its jobs into the broker, currently in Todo",
+  })
+
+  await expect(
+    within(handle).getByText("Move"),
+  ).toBeVisible()
+
+  await expect(
+    handle.querySelector("svg"),
+  ).not.toBeVisible()
+})
+
+/**
+ * The name is the same sentence at both widths, and that is the
+ * point of putting the whole of it in a `VisuallyHidden` while both
+ * visible affordances are `aria-hidden`.
+ *
+ * Left to the visible text, the handle would be called "Move X"
+ * wide and "Move Move X" narrow — one control with two names, one
+ * `getByRole` query that works in one layout and not the other, and
+ * a screen-reader user hearing the word twice.
+ */
+test("the handle has one name at both widths", async () => {
+  const { canvas } = await mountStory(MoveHandleByWidth)
+
+  await expect(
+    canvas.getAllByRole("button", {
+      name: "Move Retire the second scheduler and fold its jobs into the broker, currently in Todo",
+    }),
+  ).toHaveLength(2)
+})

package/src/Board/Board.tsx

@@ -44,12 +44,15 @@ export type BoardProps = {
   label: string
   lanes: readonly BoardLane[]
   /**
-   * What the move handle shows instead of the word "Move". The
-   * library ships no icons and no symbol glyphs in a default —
+   * What the move handle shows **while the lanes are side by side**.
+   * Below `cq-lg` the handle says "Move" whatever this is, because
+   * there is nowhere to drag to — see `BoardCard`.
+   *
+   * The library ships no icons and no symbol glyphs in a default —
    * they render as nothing where the font lacks them, which
    * includes this sandbox's chromium, the kiosk image and the
    * ePaper build — so the default is a word and an app that owns a
-   * glyph set passes one. On a dense board it is worth ~55px a row.
+   * glyph set passes one. On a dense board it is worth ~35px a row.
    */
   moveIcon?: ReactNode
   /**
@@ -216,7 +219,24 @@ export const Board = ({
   return (
     <section
       aria-label={label}
-      className={toClassName("@container", className)}
+      /*
+       * `@container/board`, and the NAME is what a card's move
+       * handle needs.
+       *
+       * An unnamed container query matches the nearest ancestor
+       * container, and between this box and a card there is a
+       * second one — the lane's, one level down, which decides what
+       * shape a card is. So a `cq-lg:` written inside `BoardCard`
+       * asks about the LANE, and the answer is inverted against the
+       * question the handle has to ask: in a three-up board a lane
+       * is ~280px, and in the Narrow View the single lane is the
+       * whole board. Naming this one lets the handle query past the
+       * lane to the box that actually decides how many lanes are on
+       * screen. Naming changes nothing else — a named container
+       * still answers an unnamed query, which is why the segmented
+       * control and the lanes below keep their plain `cq-lg:`.
+       */
+      className={toClassName("@container/board", className)}
     >
       <div className="flex flex-col gap-3">
         {/*

package/src/Board/BoardCard.tsx

@@ -147,13 +147,16 @@ export type BoardCardProps = {
   item: BoardItem
   laneLabel: string
   /**
-   * Shown on the move handle instead of the word "Move". The
-   * library ships no icons, so the default is words — a `⋮` renders
-   * as nothing where the font lacks it, which includes the kiosk
-   * image and the ePaper build. An app that already owns a glyph
-   * set passes one and buys back the ~55px per row that a word
-   * costs, which in a 500px lane is the difference between twenty
-   * characters of title and thirty.
+   * Shown on the move handle **while the lanes are side by side**,
+   * instead of the word "Move". Below the board's `cq-lg` the word
+   * comes back whatever this is — see the handle section below.
+   *
+   * The library ships no icons, so the default is words — a `⋮`
+   * renders as nothing where the font lacks it, which includes the
+   * kiosk image and the ePaper build. An app that already owns a
+   * glyph set passes one and buys back the ~35px per row that a
+   * word costs, which in a 500px lane is several characters of
+   * title.
    */
   moveIcon?: ReactNode
   /** The lanes this card can be sent to — never its own. */
@@ -205,6 +208,38 @@ export type BoardCardProps = {
  * on screen at all. Dragging from it moves the card directly. Both
  * commit through the same callback, so there is no second code path
  * to keep honest and neither is a fallback for the other.
+ *
+ * ### What it WEARS depends on whether a drag can succeed
+ *
+ * The two drivers are not equally available at every width, so the
+ * handle does not claim they are:
+ *
+ * | The board is | The handle shows | Because |
+ * | --- | --- | --- |
+ * | `cq-lg` and wider — lanes side by side | the app's `moveIcon` | the other lanes are on screen, so a drag has somewhere to land, and a grip glyph teaches that gesture |
+ * | narrower — one lane and a segmented control | the word **Move** | there is nothing on screen to drop onto, so the only gesture the glyph teaches is the one that cannot work |
+ *
+ * That table is a bug report. QueuePilot shipped a `≡` handle in a
+ * one-lane board and the owner could not move anybody: *"I can't
+ * seem to drag 'n drop the names from Everyone Else anywhere else.
+ * There's no right-click or anything. How do I move these?"* The
+ * first fix took the glyph away everywhere, which was the wrong
+ * half — *"I think the drag handles were fine, but now you have it
+ * in a 3-column mode, so dragging would work, but it has this
+ * 'move' button instead."*
+ *
+ * Both are in the DOM and CSS picks; neither is rendered from a
+ * measurement. A `ResizeObserver` would get the first paint wrong,
+ * and a kiosk Pi shows that. Both are `aria-hidden`, and the
+ * handle's whole accessible name comes from the `VisuallyHidden`
+ * beside them — so the name is the same sentence at every width,
+ * which is what keeps one `getByRole` query working in both
+ * layouts.
+ *
+ * The query is against the **board's** container, named `board`,
+ * not the lane's. A lane in a three-up board is narrow and the
+ * Narrow View's single lane is wide, so the nearer container
+ * answers this question exactly backwards.
  */
 export const BoardCard = ({
   item,
@@ -346,12 +381,29 @@ export const BoardCard = ({
                     <Button
                       appearance="ghost"
                       intent="neutral"
-                      // `touch-none` so a touch drag is a drag
-                      // rather than a page scroll. Only the handle
-                      // needs it; the rest of the gesture is covered
-                      // by `preventDefault` on the captured
-                      // `pointermove`.
-                      className="touch-none opacity-70 group-hover:opacity-100"
+                      className={toClassName(
+                        // `touch-none` so a touch drag is a drag
+                        // rather than a page scroll. Only the handle
+                        // needs it; the rest of the gesture is
+                        // covered by `preventDefault` on the
+                        // captured `pointermove`.
+                        "touch-none opacity-70 group-hover:opacity-100",
+                        // `sizing` is a prop and cannot be two
+                        // things at once, so the button stays
+                        // `control`-sized — which is what the word
+                        // needs — and takes `icon` sizing back at
+                        // the width where the glyph is what is
+                        // showing. These are the two utilities
+                        // `ICON_CONTROL_SIZE_CLASS.sm` is, minus the
+                        // height `CONTROL_SIZE_CLASS.sm` already
+                        // set. Deterministic rather than a
+                        // specificity coin-flip: Tailwind orders a
+                        // variant after the utility it varies, which
+                        // is the same thing the lane's own
+                        // `cq-lg:p-0` relies on.
+                        moveIcon != null &&
+                          "@min-[48rem]/board:w-(--control-height-sm) @min-[48rem]/board:px-0",
+                      )}
                       onClick={() => {
                         setIsMenuVisible(
                           (isVisible) => !isVisible,
@@ -361,23 +413,53 @@ export const BoardCard = ({
                         onStartDrag?.(pointerEvent)
                       }}
                       size="sm"
-                      sizing={moveIcon ? "icon" : "control"}
+                      sizing="control"
                     >
-                      {moveIcon ?? "Move"}
+                      {moveIcon == null ? null : (
+                        // `hidden` first, so a browser with no
+                        // container-query support — and every test
+                        // renderer that does not lay out — keeps the
+                        // word, which is the affordance that works
+                        // everywhere.
+                        //
+                        // `contents` rather than `inline`: the glyph
+                        // stays a direct flex child of the button,
+                        // so it centres the way it did when it was
+                        // the button's only content.
+                        <span
+                          aria-hidden="true"
+                          className="hidden @min-[48rem]/board:contents"
+                        >
+                          {moveIcon}
+                        </span>
+                      )}
+
+                      <span
+                        aria-hidden="true"
+                        className={toClassName(
+                          moveIcon != null &&
+                            "@min-[48rem]/board:hidden",
+                        )}
+                      >
+                        Move
+                      </span>
 
                       {/*
                        * Thirty controls all named "Move" is thirty
                        * indistinguishable buttons to a screen reader
                        * and to `getByRole("button", { name })`, so
                        * the accessible name says *which* card and
-                       * where it currently is. With an icon this is
-                       * the whole name; with the word it qualifies
-                       * it.
+                       * where it currently is.
+                       *
+                       * The whole name lives here, and both visible
+                       * affordances are `aria-hidden`, because which
+                       * of them is painted is a CSS answer that the
+                       * accessible name must not depend on — a
+                       * handle called "Move X" wide and "Move Move
+                       * X" narrow is one control with two names.
                        */}
                       <VisuallyHidden>
-                        {moveIcon
-                          ? `Move ${item.title}, currently in ${laneLabel}`
-                          : ` ${item.title}, currently in ${laneLabel}`}
+                        {`Move ${item.title}, currently in ${laneLabel}`}
                       </VisuallyHidden>
                     </Button>
                   }

package/src/Board/boardMoveHandleContainer.test.ts

@@ -0,0 +1,54 @@
+import { readFile } from "node:fs/promises"
+import { join } from "node:path"
+
+import { containerQuery } from "@charcuterie/tokens/src/scales.ts"
+import { expect, test } from "vitest"
+
+/**
+ * The move handle swaps its glyph for the word "Move" at the width
+ * where the lanes stop being side by side — and it has to be the
+ * SAME width the lanes themselves use, or there is a band where the
+ * board is one lane and the handle still teaches a drag.
+ *
+ * Two literals cannot be shared: a container query's threshold is
+ * resolved before custom properties exist, so
+ * `@container (min-inline-size: var(--cq-lg))` is invalid CSS and
+ * `48rem` has to be written out. The lanes get theirs from the
+ * generated `cq-lg` variant; the handle writes Tailwind's own
+ * `@min-[…]/board:`, because that is the only form that can name a
+ * container. This test is what keeps the two from drifting.
+ */
+const directory = import.meta.dirname
+
+test("the handle's own breakpoint is the scale's `cq-lg`, spelled out", async () => {
+  const source = await readFile(
+    join(directory, "BoardCard.tsx"),
+    "utf8",
+  )
+
+  const thresholds = [
+    ...source.matchAll(/@min-\[([^\]]+)\]\/board:/g),
+  ].map((match) => match[1])
+
+  // The mutation guard: a refactor that renames the variant would
+  // otherwise turn the assertion below into `[] === []`.
+  expect(thresholds.length).toBeGreaterThan(0)
+
+  expect([...new Set(thresholds)]).toEqual([
+    containerQuery.lg,
+  ])
+})
+
+/**
+ * The other half. A named query with no container of that name
+ * never matches anything — no error, no warning, and the handle
+ * silently keeps whichever affordance the base classes gave it.
+ */
+test("the board declares the `board` container the handle queries", async () => {
+  const source = await readFile(
+    join(directory, "Board.tsx"),
+    "utf8",
+  )
+
+  expect(source).toContain('"@container/board"')
+})

package/src/Nav/Nav.mdx

@@ -0,0 +1,169 @@
+import { Canvas, Controls, Meta } from "@storybook/addon-docs/blocks";
+
+import * as NavStories from "./Nav.stories";
+
+<Meta of={NavStories} />
+
+# Nav
+
+The app's destinations. A header row, a side rail, a collapsed rail, a strip along the foot
+of a phone, or a panel behind one control — the same list, drawn where it fits.
+
+> **This replaces [`NavBar`](?path=/docs/components-layout-navbar--docs)**, which shipped the
+> header row on its own and is deprecated as of this release. `bar` is `Nav`'s default
+> layout and behaves identically, down to the measured whole-row fold — see *`bar` folds
+> whole* below.
+
+<Canvas of={NavStories.Default} />
+
+## Props
+
+<Controls />
+
+## What was actually missing
+
+`Shell` / `Header` / `Rail` / `Main` shipped the page frame on 2026-08-10 and left **the
+rail empty**. Twelve UI repos, and exactly two have a `<nav>` at all: Docket hand-rolled a
+row of `NavLink`s with the collapse rule in its own stylesheet, Folio hand-rolled another,
+and the other ten have no destinations anywhere.
+
+The two that exist already disagree. Docket *wraps* below its breakpoint, so its header
+stands three lines tall on a phone — which is not a decision anybody made, it is what
+`flex-wrap` does when nobody writes the other rule.
+
+## Every item is a real link
+
+<Canvas of={NavStories.AllVariants} />
+
+`<a href>`, through the injected `RouterLinkProvider` — the same seam `TextLink` and
+`ButtonLink` take, so an app injects its router once and every destination in the library
+routes.
+
+Not a `<button onClick={navigate}>`. That is what mux-magic and QueuePilot do today, it is
+**identical in a screenshot**, and it loses middle-click, ctrl-click, "open in a new tab",
+the status bar preview, and "copy link address". See
+[buttons are actions, links are navigation](?path=/docs/guides-routing--docs).
+
+An `isExternal` item is the exception the seam already knows: a plain anchor,
+`target="_blank"`, `rel="noopener noreferrer"`. Pushing `https://…` onto a router's history
+navigates the SPA to a route that does not exist.
+
+## `icon`, and `NavRailItem`
+
+`NavItem` keeps `icon` optional, because a `bar` never takes the label away — Docket's nine
+destinations are words, and inventing nine glyphs to satisfy a type would be worse than the
+problem.
+
+A rail is the other case. `railIcons` is one `--control-height-lg` square and shows nothing
+else, so an item with no glyph is a blank square that still navigates, and there is no visual
+defect to notice because the row reads as padding. **Annotate a rail's array as
+`NavRailItem[]`** — the same shape with `icon` made required — and the type checker catches
+it before somebody drags a window narrow.
+
+`items` is deliberately **not** discriminated on `layout`. The main call site passes
+`layout={navLayout.layout}` straight from `useNavLayout`, which is a variable and not a
+literal, so a union that split the item type by layout would force a `switch` at the one
+place this component exists to make short.
+
+The library still ships no icons — lucide (ISC) is the fleet recommendation, and a glyph in
+a default renders as nothing where the font lacks it.
+
+## `bar` folds whole, and it is measured
+
+There is no `collapseAt` and no media query on this axis. The bar reads the width its links
+actually have and folds when their sum stops fitting, so a longer label, a tenth destination,
+a `data-density="kiosk"` or a reader at 175% browser zoom each move the fold on their own.
+mux-magic collapses at a hardcoded `480px` and plex-channels at `760px`, and neither number
+has a reason.
+
+It folds **whole** rather than progressively, unlike `Toolbar`. `Toolbar`'s items are ranked;
+a nav's order is the shape of the product — Docket's reads as the pipeline, Triage → Backlog
+→ Phases → Board → Archives — and half of that behind a button is a rule no reader can learn.
+
+⚠️ **A `bar` must not be sized by its own contents.** It measures its own box to decide what
+to draw in it, so a container that shrink-wraps makes the answer its own input: put it in a
+`minmax(0, 1fr)` grid track or a `flex-1 min-w-0` row.
+
+## The current destination is announced
+
+<Canvas of={NavStories.AllStates} />
+
+`aria-current="page"`, and a background. One without the other is WCAG 1.4.1, and a
+`font-weight` swap alone is exactly that failure.
+
+Matching is two rules:
+
+1. An exact path wins — `/board` on `/board`.
+2. Otherwise the **longest path-segment prefix** wins. `/board` matches `/board/inProgress`
+   and does **not** match `/boardgames`, because `games` is not a new segment. Longest, so
+   an app with `/settings` and `/settings/labels` marks the deeper one.
+
+The root is exempt from rule 2: `/` prefixes every path in the app, so a permissive root
+would mark Home current on every screen and the state would carry no information.
+
+Query and fragment are stripped first. A destination and a filtered view of it are the same
+place — `/board?lane=todo` is still Board, which is the case that breaks first in a real app.
+
+**And exactly one item is current.** `getIsCurrentHref` answers for a single link, so a nav
+holding both `/settings` and `/settings/labels` gets `true` twice while the reader is on the
+deeper one — which is what `NavBar` shipped. `resolveActiveKey` is the whole-list answer and
+takes the **deepest** match, by path rather than by array position, so the product's own
+order never decides which destination lights up.
+
+Both are exported, so an app can assert its own table without mounting anything.
+
+## Three widths, one rule — `useNavLayout`
+
+<Canvas of={NavStories.Responsive} />
+
+```tsx
+const nav = useNavLayout({ storageKey: "queuepilot-nav" })
+
+// nav.layout: "rail" | "railIcons" | "menu"
+// nav.isCollapsed, nav.mode, nav.setMode, nav.toggle
+```
+
+| Width | `layout` | What the app renders |
+| --- | --- | --- |
+| `>= 64rem` | `rail` | a `Rail` holding a `Nav` |
+| `>= 48rem` | `railIcons` | the same `Rail`, narrower |
+| below | `menu` | a trigger in the `Header` |
+
+`toggle()` overrides the width and the choice is remembered under `storageKey`. The
+override does **not** reach the narrow state — `expanded` on a 390px screen is a 212px rail
+beside 178px of content — and the remembered value is kept rather than cleared, so rotating
+a tablet back to landscape restores the rail the reader asked for.
+
+**Why the app still places it.** The placement genuinely differs and the rule does not. The
+`menu` state puts a control in the header, which is a different corner of `Shell`'s grid
+from a side rail, and no amount of restyling moves an element across a grid. So the library
+owns *which* state is right, at what width, with what override, remembered where; the app
+owns two `if`s.
+
+## The narrow panel is a `Popover`, not a `Menu`
+
+<Canvas of={NavStories.Interactive} />
+
+`Menu`'s items are `onSelect` callbacks on `<button>`s. That is right for what a menu
+usually holds — undo, redo, a scheme cycle — and wrong for a destination, for every reason
+in *Every item is a real link* above.
+
+So `layout="menu"` is a `Popover`: anchored, dismissable, portalled to the body, and
+`modal={false}` so the caret is not trapped. It is a disclosure, not a dialog somebody has
+to answer. Escape and an outside press both close it.
+
+Give the trigger a real name. A bare hamburger is a glyph, and a glyph is not a name — the
+reason `IconButton` requires `label`.
+
+## When to use which layout
+
+| Layout | For |
+| --- | --- |
+| `bar` | three to six destinations, and a grid that wants every pixel — ai-usage, folio, mux-magic, portly-controllers. Folds itself; needs no `useNavLayout`. |
+| `rail` / `railIcons` | seven or more, or a pipeline you read down — Docket, mail-sifter, QueuePilot |
+| `bottom` | three or four you switch between constantly, in the Narrow View only |
+| `menu` | the Narrow View of a `rail` app |
+
+`bottom` is deliberately not the default narrow answer. It costs a permanent strip of the
+screen, and it earns that only when the destinations are few and the switching is constant.
+An app you settle into for an evening wants the panel.