@charcuterie/ui 3.31.0 → 3.33.0

package/src/ActionTiles/ActionTiles.tsx

@@ -0,0 +1,292 @@
+import type { ControlSize } from "@charcuterie/tokens"
+import type { CSSProperties, ReactNode } from "react"
+
+import { FOCUS_RING_CLASS } from "../intentStyles.ts"
+import { useRouterLink } from "../RouterLink/RouterLinkProvider.tsx"
+import { getIsRoutedHref } from "../RouterLink/routerLink.ts"
+import {
+  TILE_BOX_CLASS,
+  TILE_COLUMNS_CLASS,
+  TILE_GAP_CLASS,
+  TILE_HINT_TEXT_CLASS,
+  TILE_MIN_INLINE_SIZE_PROPERTY,
+  TILE_PADDING_CLASS,
+  TILE_TEXT_SIZE_CLASS,
+} from "../tileStyles.ts"
+import { toClassName } from "../toClassName.ts"
+import { VisuallyHidden } from "../VisuallyHidden/VisuallyHidden.tsx"
+
+export type ActionTileItem = {
+  /**
+   * A line of help under the name. Drawn one step down the type ramp
+   * in `content-muted`, **inside** the tile — so `getByRole` computes
+   * it into the accessible name. A hint a screen reader never reads
+   * is a hint half the audience does not have.
+   */
+  hint?: ReactNode
+  /**
+   * Makes this tile a real `<a href>`: middle-click, ctrl-click,
+   * "open in new tab", "copy link address" and the status bar all
+   * come from the element rather than from the paint. Routed through
+   * the injected `RouterLink` when the destination is same-origin and
+   * not a fragment.
+   *
+   * Without one, the tile is a `<button>` that calls the set's
+   * `onChoose`. A set may mix the two.
+   */
+  href?: string
+  /**
+   * Leading content, above the name. A `Badge`, an app's own icon, a
+   * count.
+   *
+   * `aria-hidden` by construction: the name it sits above is inside
+   * the same tile, so an announced icon is the label read twice.
+   */
+  icon?: ReactNode
+  isDisabled?: boolean
+  /** Opens in a new tab, and says so to a screen reader. `href` only. */
+  isExternal?: boolean
+  label: ReactNode
+  /**
+   * Identity. The React key, and what `onChoose` is handed.
+   *
+   * Required even on a tile that navigates, so a set can mix the two
+   * without one half losing its key — the same reason `RadioItem`
+   * carries one.
+   */
+  value: string
+}
+
+export type ActionTilesProps = {
+  className?: string
+  items: readonly ActionTileItem[]
+  /** The set's accessible name. Required. */
+  label: string
+  /**
+   * The narrowest a tile track may be, in CSS px.
+   *
+   * It is the grid's floor and not the tile's width: tracks below it
+   * are not created, and the ones that are share the row evenly.
+   */
+  minTileInlineSize?: number
+  /** Fired by a tile that carries no `href`. */
+  onChoose?: (value: string) => void
+  /** What `isExternal` announces. Not shown. */
+  newTabLabel?: string
+  size?: ControlSize
+}
+
+/**
+ * A set of ACTIONS drawn as tiles — a bordered card carrying a name
+ * and a line of help, in a grid that gains columns with its
+ * container.
+ *
+ * This is `RadioGroup`'s `itemShape="tile"` with the radio taken
+ * away. The
+ * [2026-08-25 record](../../../../docs/decisions/2026-08-25-a-choice-tile-is-a-radiogroup-shape-not-a-third-component.md)
+ * that made the choice tile a `RadioGroup` shape named this case
+ * under *"What this deliberately does not cover"* — mux-magic's "Pick
+ * a tool" tiles are `<a href>` and points-market's are `<Link>`, and
+ * *"a link is not a radio, and giving one `aria-checked` would be
+ * worse than the paint it replaced"*. So the box is shared through
+ * `tileStyles.ts` and nothing else is.
+ *
+ * ### Which of the two you want
+ *
+ * Ask what a press does.
+ *
+ *  - It **records a value** the user will then submit, or that
+ *    filters what is below it — `RadioGroup itemShape="tile"`. The
+ *    set announces "3 of 6", the arrow keys move the choice, and one
+ *    tile stays selected.
+ *  - It **goes somewhere or starts something** — this. Nothing stays
+ *    selected, because nothing was chosen: the page moved on. Tab
+ *    reaches each tile, Enter and Space press it, and a `href` tile
+ *    is a real anchor.
+ *
+ * A first step that opens the next step is the second kind, which is
+ * why QueuePilot's "Queue type" chooser is here and its Tonight
+ * activity filter is not.
+ *
+ * ### Why this is not a `Button` with a `className`
+ *
+ * A `Button` is sized by `h-(--control-height-md)` and carries **no
+ * block padding at all** — one line of text, by contract. An app that
+ * wants a wrapping two-line card reaches for `height: auto`, which
+ * deletes the height and leaves `padding: 0` down the block axis:
+ * a title flush against the top border and a description flush
+ * against the bottom one, with nothing to report it. That shipped in
+ * QueuePilot and is what this component exists to have made
+ * impossible.
+ *
+ * ### `role="group"`, and no roving tabindex
+ *
+ * These are ordinary buttons and anchors, so the platform already
+ * owns the keyboard: Tab reaches each one, Enter and Space press it,
+ * and a link opens in a new tab on ctrl-click. A radio group borrows
+ * one tab stop and moves the choice with the arrow keys because
+ * exactly one of its options is true at a time; nothing here is
+ * true, so imposing that model would only cost a keyboard user the
+ * ability to Tab to the second tile.
+ */
+export const ActionTiles = ({
+  className,
+  items,
+  label,
+  minTileInlineSize = 200,
+  newTabLabel = "(opens in a new tab)",
+  onChoose,
+  size = "md",
+}: ActionTilesProps): ReactNode => {
+  const RouterLink = useRouterLink()
+
+  return (
+    // biome-ignore lint/a11y/useSemanticElements: the semantic element for `group` is `<fieldset>`, which is a form-control grouping — it drags `<legend>` semantics, a border and form-reset behaviour onto a set of buttons and links that is not a form. Same call `Menu`'s group, `AccordionSection` and `BoardLaneList` already made.
+    <div
+      aria-label={label}
+      className={toClassName(
+        "grid",
+        TILE_COLUMNS_CLASS,
+        TILE_GAP_CLASS[size],
+        className,
+      )}
+      role="group"
+      style={
+        {
+          [TILE_MIN_INLINE_SIZE_PROPERTY]: `${minTileInlineSize}px`,
+        } as CSSProperties
+      }
+    >
+      {items.map(
+        ({
+          hint,
+          href,
+          icon,
+          isDisabled = false,
+          isExternal = false,
+          label: tileLabel,
+          value,
+        }) => {
+          const tileClassName = toClassName(
+            // `flex`, not `inline-flex`: a grid item stretches to its
+            // track, and an inline box would sit at max-content
+            // inside it. `min-w-0` with `wrap-anywhere` below,
+            // because a grid item's automatic minimum is its
+            // min-content width — one unbroken token would otherwise
+            // set the track's floor and shove the grid out of its
+            // container.
+            "flex min-w-0 flex-col gap-0.5 text-start wrap-anywhere transition-colors duration-(--duration-fast) ease-standard",
+            TILE_BOX_CLASS,
+            TILE_PADDING_CLASS[size],
+            TILE_TEXT_SIZE_CLASS[size],
+            // Disabled turns the whole tile down with `opacity-60`,
+            // the same family treatment as `Checkbox`, `Switch` and
+            // the radio tile, rather than fading the border to a
+            // token that disappeared on a pale theme.
+            isDisabled
+              ? "cursor-not-allowed opacity-60"
+              : "cursor-pointer hover:border-border-strong",
+            FOCUS_RING_CLASS,
+          )
+
+          const content = (
+            <>
+              {icon === undefined ? null : (
+                <span aria-hidden className="flex">
+                  {icon}
+                </span>
+              )}
+
+              <span className="font-semibold text-content-primary">
+                {tileLabel}
+              </span>
+
+              {hint === undefined ? null : (
+                <span
+                  className={toClassName(
+                    "font-normal text-content-muted",
+                    TILE_HINT_TEXT_CLASS[size],
+                  )}
+                >
+                  {hint}
+                </span>
+              )}
+
+              {isExternal && href !== undefined ? (
+                <VisuallyHidden>
+                  {newTabLabel}
+                </VisuallyHidden>
+              ) : null}
+            </>
+          )
+
+          if (href !== undefined && !isDisabled) {
+            // An external destination or a fragment is never the
+            // router's — pushing `https://…` or `#credits` onto the
+            // history stack navigates the SPA to a route that does
+            // not exist. Same destination test as `ButtonLink`.
+            const LinkElement =
+              isExternal || !getIsRoutedHref(href)
+                ? "a"
+                : RouterLink
+
+            return (
+              <LinkElement
+                className={tileClassName}
+                href={href}
+                key={value}
+                // `noreferrer` alongside `noopener` on purpose:
+                // `noopener` closes the `window.opener` hole, and
+                // `noreferrer` is what keeps a private app's URL out
+                // of the destination's logs.
+                rel={
+                  isExternal
+                    ? "noopener noreferrer"
+                    : undefined
+                }
+                target={isExternal ? "_blank" : undefined}
+              >
+                {content}
+              </LinkElement>
+            )
+          }
+
+          if (href !== undefined) {
+            // `isDisabled` drops `href` entirely rather than shipping
+            // a focusable anchor that silently ignores clicks — an
+            // anchor with no `href` is inert by the platform's own
+            // rules, and the explicit `role`/`aria-disabled` keeps it
+            // *announced* as a link that is currently unavailable
+            // rather than vanishing from the tree. `ButtonLink`'s
+            // rule, unchanged.
+            return (
+              // biome-ignore lint/a11y/useValidAnchor: dropping `href` is the point. A disabled anchor that keeps one is focusable and silently ignores clicks; without one it is inert and out of the tab order by the platform's own rules, and the explicit `role`/`aria-disabled` keeps it announced rather than removed from the tree. `ButtonLink` makes the same call.
+              <a
+                aria-disabled="true"
+                className={tileClassName}
+                key={value}
+                role="link"
+              >
+                {content}
+              </a>
+            )
+          }
+
+          return (
+            <button
+              className={tileClassName}
+              disabled={isDisabled}
+              key={value}
+              onClick={() => {
+                onChoose?.(value)
+              }}
+              type="button"
+            >
+              {content}
+            </button>
+          )
+        },
+      )}
+    </div>
+  )
+}

package/src/AdaptiveGrid/useAdaptiveColumns.ts

@@ -240,6 +240,22 @@ export const useAdaptiveColumns = <
    * ⚠️ Never the element `contentMaxInlineSize` is applied to.
    */
   containerRef: RefObject<ContainerElement | null>
+  /**
+   * Has the container been given a box yet?
+   *
+   * False in two situations that look identical from here and are
+   * both "no measurement has happened": the frame before
+   * `ResizeObserver` delivers its first record, and any time the
+   * container sits inside a `display: none` ancestor — which is
+   * what the `hidden` attribute is, and what a tab panel, a
+   * collapsed disclosure and a closed `<details>` all use.
+   *
+   * The distinction matters because a zero inline size is not a
+   * measurement of zero. It is the absence of one, and a consumer
+   * that treats it as a number lays out for a 0px container and
+   * then reads the correction as a change.
+   */
+  isLaidOut: boolean
   /** What was picked, `"auto"` included. */
   choice: ColumnChoice
   setChoice: (choice: ColumnChoice) => void
@@ -350,6 +366,7 @@ export const useAdaptiveColumns = <
       gutterInlineSize,
       singleInlineSize,
     }),
+    isLaidOut: availableInlineSize > 0,
     setChoice,
   }
 }

package/src/RadioGroup/RadioGroup.mdx

@@ -59,6 +59,13 @@ tile with its border taken away is a row.
 no radio affordance, options too short to carry a sentence. A tile is this control with a
 border, which is a different reason.
 
+[`ActionTiles`](/docs/components-actions-actiontiles--docs) is the same tile that **acts**
+rather than holds a value, and it *does* earn its own file: invert every clause of the
+paragraph above — no `radio` role, no roving tabindex, no selection-follows-focus, no
+`isReadOnly` — and the box is all that is left in common. The two read it from one
+`tileStyles.ts`. Ask what a press does: records a value something below reads, or goes
+somewhere and is done.
+
 <Canvas of={RadioGroupStories.Tiles} />
 
 Four apps in the fleet had each hand-painted this shape — ten instances between them — and

package/src/RadioGroup/RadioGroup.tsx

@@ -7,6 +7,11 @@ import type { ControlSize } from "@charcuterie/tokens"
 import type { CSSProperties, ReactNode } from "react"
 import { useCallback, useEffect, useRef } from "react"
 
+import {
+  TILE_COLUMNS_CLASS,
+  TILE_GAP_CLASS,
+  TILE_MIN_INLINE_SIZE_PROPERTY,
+} from "../tileStyles.ts"
 import { toClassName } from "../toClassName.ts"
 import { RadioGroupOption } from "./RadioGroupOption.tsx"
 
@@ -85,47 +90,6 @@ const GAP_CLASS: Record<ControlSize, string> = {
   lg: "gap-2",
 }
 
-/**
- * Wider than the row gaps: rows are separated by their leading, and
- * tiles by nothing but the gap, so the same 6px that reads as a list
- * reads as a seam between two cards.
- */
-const TILE_GAP_CLASS: Record<ControlSize, string> = {
-  sm: "gap-1.5",
-  md: "gap-2",
-  lg: "gap-3",
-}
-
-/**
- * `auto-fill`, and deliberately not `auto-fit`.
- *
- * `auto-fit` collapses the empty tracks and lets the ones that
- * remain share the whole row, so six tiles in a 2560px container
- * become six 420px slabs — the full-width-row shape in a new
- * costume. `auto-fill` keeps the empty tracks, so a tile stays a
- * tile and the grid simply has room to spare.
- *
- * `min(…, 100%)` is what stops the floor overflowing a container
- * narrower than one tile, which is the Narrow View and is otherwise
- * a horizontal scrollbar on a phone.
- *
- * The floor arrives as a custom property rather than an interpolated
- * class because Tailwind scans source *text* for complete class
- * strings: `` `grid-cols-[…${n}px…]` `` generates nothing, paints
- * nothing and reports nothing. One written-out literal reading
- * `var(--charcuterie-tile-min-inline-size)` covers every width an
- * app can ask for — the same reason `Card`'s accent edge goes
- * through one property.
- *
- * This is **not** `useAdaptiveColumns`, and the difference is the
- * question being asked. That hook buys a column with height, for an
- * unbounded gallery that will scroll; a radio group is a bounded set
- * of options inside a form section, where the only question is how
- * many fit across the box it was given.
- */
-const TILE_COLUMNS_CLASS =
-  "grid-cols-[repeat(auto-fill,minmax(min(var(--charcuterie-tile-min-inline-size),100%),1fr))]"
-
 /**
  * One choice out of many, each on its own row with a label the size
  * of prose — the stacked sibling of `SegmentedControl`.
@@ -157,6 +121,16 @@ const TILE_COLUMNS_CLASS =
  * and `isReadOnly` are the ones already tested here. `SegmentedControl`
  * earns its own file by being a different control — one connected
  * strip, no radio affordance; a tile is this control with a border.
+ *
+ * ### A tile that ACTS is `ActionTiles`
+ *
+ * Same box, read from `tileStyles.ts`, and nothing else in common:
+ * no `radio` role, no roving tabindex, no selection to follow focus,
+ * no read-only. Ask what a press does. It records a value something
+ * below reads — this. It goes somewhere or starts something, and
+ * nothing stays selected — `ActionTiles`. Inverting every clause of
+ * the paragraph above is what earned that one its own file
+ * (`docs/decisions/2026-09-01-a-tile-that-acts-is-its-own-component-and-shares-only-the-box.md`).
  */
 export const RadioGroup = ({
   className,
@@ -292,7 +266,7 @@ export const RadioGroup = ({
       style={
         isTile
           ? ({
-              "--charcuterie-tile-min-inline-size": `${minTileInlineSize}px`,
+              [TILE_MIN_INLINE_SIZE_PROPERTY]: `${minTileInlineSize}px`,
             } as CSSProperties)
           : undefined
       }

package/src/RadioGroup/RadioGroupOption.tsx

@@ -3,6 +3,12 @@ import type { ReactNode } from "react"
 import { useEffect } from "react"
 
 import { FOCUS_RING_CLASS } from "../intentStyles.ts"
+import {
+  TILE_BOX_CLASS,
+  TILE_HINT_TEXT_CLASS,
+  TILE_PADDING_CLASS,
+  TILE_TEXT_SIZE_CLASS,
+} from "../tileStyles.ts"
 import { toClassName } from "../toClassName.ts"
 import type {
   RadioItem,
@@ -42,42 +48,6 @@ const DOT_SIZE_CLASS: Record<ControlSize, string> = {
   lg: "size-2.5",
 }
 
-const TEXT_SIZE_CLASS: Record<ControlSize, string> = {
-  sm: "text-sm",
-  md: "text-md",
-  lg: "text-lg",
-}
-
-/**
- * One step down from the option's own text, and never below `xs`:
- * a hint that keeps shrinking with the density axis is the 11px
- * caption the 2026-08-10 ramp rebuild exists to have removed.
- */
-const HINT_TEXT_CLASS: Record<ControlSize, string> = {
-  sm: "text-xs",
-  md: "text-xs",
-  lg: "text-sm",
-}
-
-/**
- * A tile is a card, so its padding is a card's rather than a
- * control's — enough that the border reads as a box around content
- * and not as an outline on a line of text.
- */
-const TILE_PADDING_CLASS: Record<ControlSize, string> = {
-  sm: "px-3 py-2.5",
-  md: "px-3.5 py-3",
-  lg: "px-4 py-3.5",
-}
-
-/**
- * The box, and only the box. Every state below it is a **border and
- * a surface**, never colour alone — the same reason `Stepper`
- * refuses to say "done" with a hue.
- */
-const TILE_BOX_CLASS =
-  "rounded-lg border border-border-subtle bg-surface-raised"
-
 /**
  * Its own file for the same reason `SegmentedOption` is: **both
  * registrations are effects**, and an effect cannot run in a loop.
@@ -152,7 +122,7 @@ export const RadioGroupOption = ({
                 ? "items-center"
                 : "items-start",
             ),
-        TEXT_SIZE_CLASS[size],
+        TILE_TEXT_SIZE_CLASS[size],
         // Disabled turns the whole option down with `opacity-60`, the
         // same family treatment as `Checkbox` and `Switch`, rather than
         // fading the ring to a token that disappeared on a pale theme.
@@ -252,7 +222,7 @@ export const RadioGroupOption = ({
             <span
               className={toClassName(
                 "font-normal text-content-muted",
-                HINT_TEXT_CLASS[size],
+                TILE_HINT_TEXT_CLASS[size],
               )}
             >
               {hint}

package/src/VirtualizedGrid/VirtualizedGrid.mdx

@@ -59,6 +59,27 @@ wrong and every row is offset by the chrome above it.
 
 <Canvas of={VirtualizedGridStories.InShellScrollRegion} />
 
+## It waits for a box before it measures anything
+
+`display: none` gives an element no boxes, and the `hidden` attribute is `display: none`.
+So a grid inside a hidden tab panel, a collapsed disclosure or a closed `<details>` cannot
+be measured at all: its container reads 0px wide and every mounted row reads 0px tall.
+
+That is the absence of a measurement, not a measurement of zero, and the difference is not
+academic. Revealing the panel corrects every one of those numbers at once, and a
+virtualizer is entitled to read a correction as a **resize** — the one event it may move
+the scroll position for. It then compensates for growth that never happened and scrolls the
+page. Docket's Triage bar is where this was found: switching tabs moved `Main` by up to
+1,190px and took the tab bar off the top of the screen.
+
+So the grid mounts nothing until its container has a box. Put a grid in a tab panel and the
+panel holds no rows while it is put away; the rows arrive with the box and are measured once,
+correctly. The cost is that a revealed grid re-measures from its estimate rather than
+resuming a cache, which is exactly what a routed tab already does.
+
+<Canvas of={VirtualizedGridStories.InHiddenTabPanel} />
+
+
 ## The column rule is inherited, not reimplemented
 
 <Canvas of={VirtualizedGridStories.AllVariants} />

package/src/VirtualizedGrid/VirtualizedGrid.stories.tsx

@@ -10,6 +10,7 @@ import { Header } from "../Header/Header.tsx"
 import { Main } from "../Main/Main.tsx"
 import { SegmentedControl } from "../SegmentedControl/SegmentedControl.tsx"
 import { Shell } from "../Shell/Shell.tsx"
+import { Tabs } from "../Tabs/Tabs.tsx"
 import { VirtualizedGrid } from "./VirtualizedGrid.tsx"
 
 /**
@@ -130,6 +131,69 @@ export const InShellScrollRegion: Story = {
   ),
 }
 
+/**
+ * Two grids in a tab bar, one of them hidden — the shape that found
+ * the scroll bug.
+ *
+ * A `hidden` panel is `display: none`, so the grid inside it has no
+ * box: its container measures 0px wide (one column) and every
+ * mounted row measures 0px tall. Revealing the panel corrects all
+ * of that at once, and a virtualizer is entitled to read a
+ * correction as a resize and compensate the scroll position for it.
+ *
+ * Docket's Triage bar is where it showed: clicking a tab scrolled
+ * `Main` down 266px and put the tab bar off the top of the screen.
+ * So the claim this story exists to hold is one number — **switching
+ * tabs leaves `Main.scrollTop` where it was.**
+ *
+ * The chrome above the grid is not decoration either. The false
+ * adjustment is roughly the distance from the top of the scroll
+ * region to the top of the grid, so a story with the grid flush
+ * against the top of `Main` would have had nothing to measure and
+ * would have passed while the bug was still there.
+ */
+export const InHiddenTabPanel: Story = {
+  parameters: { layout: "fullscreen" },
+  render: (gridProps) => (
+    <Shell contentWidth="full">
+      <Header heading="Bays" />
+
+      <Main>
+        <p className="text-content-secondary text-sm">
+          Switching tabs must not move the page.
+        </p>
+
+        <Tabs
+          label="Bay views"
+          tabs={[
+            {
+              content: (
+                <VirtualizedGrid
+                  {...gridProps}
+                  label="Loaded bays"
+                />
+              ),
+              key: "loaded",
+              label: "Loaded",
+            },
+            {
+              content: (
+                <VirtualizedGrid
+                  {...gridProps}
+                  items={MANY_ITEMS.slice(0, 48)}
+                  label="Reserved bays"
+                />
+              ),
+              key: "reserved",
+              label: "Reserved",
+            },
+          ]}
+        />
+      </Main>
+    </Shell>
+  ),
+}
+
 /**
  * The same 2,000 items at three window heights.
  *