@charcuterie/ui 3.31.0 → 3.32.0

package/src/ActionTiles/ActionTiles.test.tsx

@@ -0,0 +1,292 @@
+import { composeStories } from "@storybook/react"
+import { expect, userEvent, waitFor } from "storybook/test"
+import { test } from "vitest"
+
+import { expectNoAxeViolations } from "../expectNoAxeViolations.testHelpers.ts"
+import { mountStory } from "../mountStory.testHelpers.ts"
+import { expectAgentDrivable } from "../testing/index.ts"
+import * as stories from "./ActionTiles.stories.tsx"
+
+const {
+  AllStates,
+  BesideTheRadioTile,
+  Default,
+  Interactive,
+  Links,
+  Responsive,
+  WithIcons,
+} = composeStories(stories)
+
+test("it is a named group of pressable tiles", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(Default)
+
+  const group = expectAgentDrivable(canvas, {
+    name: "Queue type",
+    role: "group",
+  })
+
+  await expect(
+    group.querySelectorAll("button"),
+  ).toHaveLength(2)
+
+  // Nothing here is selected, and nothing claims to be. The whole
+  // reason this is not a `RadioGroup` in a costume.
+  await expect(
+    group.querySelector(
+      "[aria-checked], [aria-pressed], [role='radio']",
+    ),
+  ).toBeNull()
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+test("a tile's hint is part of its accessible name", async () => {
+  const { canvas } = await mountStory(Default)
+
+  // The reason the hint is rendered inside the tile rather than
+  // beside it: a hint a screen reader never reads is a hint half the
+  // audience does not have. `getByRole` computes the name from
+  // contents, so this query only passes if it is in there.
+  expectAgentDrivable(canvas, {
+    name: "Picks Choose titles yourself, then arrange them in priority and random lanes.",
+    role: "button",
+  })
+})
+
+test("a tile icon is decoration and stays out of the name", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(WithIcons)
+
+  // Named by its words alone. An icon that joined the name would
+  // make this query fail, which is the whole reason it is
+  // `aria-hidden`.
+  expectAgentDrivable(canvas, {
+    name: "New arrivals Everything that arrived since the last run.",
+    role: "button",
+  })
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+test("every tile is its own tab stop, and Enter and Space press it", async () => {
+  const { canvas } = await mountStory(Interactive)
+
+  const group = expectAgentDrivable(canvas, {
+    name: "Queue type",
+    role: "group",
+  })
+
+  const tiles = Array.from(
+    group.querySelectorAll<HTMLButtonElement>("button"),
+  )
+
+  // The opposite of the roving-tabindex rule, on purpose: a radio
+  // group borrows one tab stop because exactly one option is true at
+  // a time, and nothing here is true. Every tile must be reachable
+  // by Tab.
+  await expect(
+    tiles.filter((one) => one.tabIndex === 0),
+  ).toHaveLength(2)
+
+  tiles[0]?.focus()
+
+  await userEvent.tab()
+
+  await waitFor(() => {
+    expect(tiles[1]).toHaveFocus()
+  })
+
+  // Enter and Space are the platform's, because these are real
+  // `<button>`s — the two things the hand-rolled `<div role=button>`
+  // versions in the fleet re-implement by hand.
+  await userEvent.keyboard("{Enter}")
+
+  await userEvent.keyboard(" ")
+})
+
+test("a disabled tile cannot be pressed", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(AllStates)
+
+  const group = expectAgentDrivable(canvas, {
+    name: "Queue type with Rules unavailable",
+    role: "group",
+  })
+
+  const rules = Array.from(
+    group.querySelectorAll<HTMLButtonElement>("button"),
+  ).find((one) => one.textContent?.startsWith("Rules"))
+
+  await expect(rules).toBeDisabled()
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+test("an href tile is a real anchor, and an external one says so", async () => {
+  const { canvas, canvasElement } = await mountStory(Links)
+
+  const group = expectAgentDrivable(canvas, {
+    name: "Pick a tool",
+    role: "group",
+  })
+
+  const inspect = expectAgentDrivable(canvas, {
+    name: "Inspect Read a container's tracks and say what would change.",
+    role: "link",
+  })
+
+  // A real `<a href>`, so middle-click, ctrl-click, "open in a new
+  // tab" and "copy link address" come from the element rather than
+  // from the paint.
+  await expect(inspect.tagName).toBe("A")
+
+  await expect(inspect).toHaveAttribute(
+    "href",
+    "/tools/inspect",
+  )
+
+  const external = Array.from(
+    group.querySelectorAll<HTMLAnchorElement>("a"),
+  ).find((one) => one.target === "_blank")
+
+  // `noreferrer` alongside `noopener`: the first closes the
+  // `window.opener` hole, the second keeps a private app's URL out of
+  // the destination's logs.
+  await expect(external).toHaveAttribute(
+    "rel",
+    "noopener noreferrer",
+  )
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+test("a disabled link drops its href and stays announced as a link", async () => {
+  const { canvas } = await mountStory(AllStates)
+
+  const remux = expectAgentDrivable(canvas, {
+    name: "Remux Nothing is loaded to remux yet.",
+    role: "link",
+  })
+
+  // An anchor with no `href` is inert and out of the tab order by the
+  // platform's own rules — better than a focusable one that silently
+  // ignores clicks. The explicit role keeps it *announced* rather
+  // than vanishing from the tree.
+  await expect(remux).not.toHaveAttribute("href")
+
+  await expect(remux).toHaveAttribute(
+    "aria-disabled",
+    "true",
+  )
+})
+
+/**
+ * The box is shared with `RadioGroup itemShape="tile"` through
+ * `tileStyles.ts`, and "shared" is asserted as **computed** styles
+ * rather than trusted — the same discipline `ButtonLink.test.tsx`
+ * applies to `Button`. Two copies of one string is a promise that
+ * survives exactly one edit.
+ */
+test("an action tile is the same box as a resting radio tile", async () => {
+  const { canvas } = await mountStory(BesideTheRadioTile)
+
+  const actionTile = expectAgentDrivable(canvas, {
+    name: "Picks Choose titles yourself, then arrange them in priority and random lanes.",
+    role: "button",
+  })
+
+  const radioGroup = expectAgentDrivable(canvas, {
+    name: "Queue type, as radios",
+    role: "radiogroup",
+  })
+
+  // The SECOND radio tile, because `RadioGroup` checks its first
+  // option on mount and a checked tile wears the accent edge. A
+  // RESTING tile is what these two must match.
+  const radioTile =
+    radioGroup.querySelectorAll<HTMLElement>(
+      '[role="radio"]',
+    )[1]
+
+  if (!radioTile) {
+    throw new Error("the radio tile did not render")
+  }
+
+  const action = getComputedStyle(actionTile)
+
+  const radio = getComputedStyle(radioTile)
+
+  await expect(action.paddingTop).toBe(radio.paddingTop)
+
+  await expect(action.paddingBottom).toBe(
+    radio.paddingBottom,
+  )
+
+  await expect(action.paddingInlineStart).toBe(
+    radio.paddingInlineStart,
+  )
+
+  await expect(action.borderTopWidth).toBe(
+    radio.borderTopWidth,
+  )
+
+  await expect(action.borderTopColor).toBe(
+    radio.borderTopColor,
+  )
+
+  await expect(action.borderTopLeftRadius).toBe(
+    radio.borderTopLeftRadius,
+  )
+
+  await expect(action.backgroundColor).toBe(
+    radio.backgroundColor,
+  )
+
+  await expect(action.fontSize).toBe(radio.fontSize)
+
+  // The padding is the whole point. A `Button` with `height: auto` —
+  // the shape this component replaces — computes to `0px` here, with
+  // the title flush against the top border.
+  await expect(
+    Number.parseFloat(action.paddingTop),
+  ).toBeGreaterThan(0)
+})
+
+test("the column count comes from the container, not the window", async () => {
+  const { canvas } = await mountStory(Responsive)
+
+  const getColumnCount = (name: string) =>
+    getComputedStyle(
+      expectAgentDrivable(canvas, { name, role: "group" }),
+    ).gridTemplateColumns.split(" ").length
+
+  // One viewport, three container widths, and the answer changes
+  // with the container. Every panel is the same window.
+  await expect(
+    getColumnCount("Where to start at 15rem"),
+  ).toBe(1)
+
+  await expect(
+    getColumnCount("Where to start at 34rem"),
+  ).toBe(2)
+})
+
+test("a tile grid never overflows a container narrower than one tile", async () => {
+  const { canvas } = await mountStory(Responsive)
+
+  const group = expectAgentDrivable(canvas, {
+    name: "Where to start at 15rem",
+    role: "group",
+  })
+
+  // The case that matters is the `min(…, 100%)` in the track floor,
+  // which is what stops a 200px floor from becoming a horizontal
+  // scrollbar in the Narrow View.
+  await expect(
+    group.getBoundingClientRect().width,
+  ).toBeLessThanOrEqual(
+    (group.parentElement?.getBoundingClientRect().width ??
+      0) + 1,
+  )
+})

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/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
       }