@charcuterie/ui 3.22.0 → 3.24.0

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/Board/useBoardDrag.ts

@@ -140,8 +140,23 @@ export const getIndicatorOffset = (
 }
 
 export const useBoardDrag = ({
+  itemSelector = "[data-board-card]",
   onDrop,
 }: {
+  /**
+   * How a registered list's draggable children are found, so a
+   * consumer that is not a board can reuse this geometry instead
+   * of forking it. `ReorderList` passes `[data-reorder-item]` and
+   * registers a single lane; the default is the board's own
+   * marker, so `Board` reads exactly as it did before this
+   * parameter existed.
+   *
+   * It is a `data-` attribute on both sides rather than a class,
+   * for the reason `BoardCard` already gives: a class is a style
+   * and a consumer's tooling may rename it, and this is a
+   * contract with a hit test.
+   */
+  itemSelector?: string
   onDrop: (
     origin: BoardDragOrigin,
     target: BoardDropTarget,
@@ -207,7 +222,7 @@ export const useBoardDrag = ({
       laneElements.current,
       ([key, element]) => {
         const cardElements = Array.from(
-          element.querySelectorAll("[data-board-card]"),
+          element.querySelectorAll(itemSelector),
         )
 
         return {
@@ -222,7 +237,7 @@ export const useBoardDrag = ({
         }
       },
     )
-  }, [])
+  }, [itemSelector])
 
   const moveTo = useCallback(
     (point: { x: number; y: number }) => {

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.