@charcuterie/ui 3.30.0 → 3.32.0

package/dist/tileStyles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tileStyles.d.ts","sourceRoot":"","sources":["../src/tileStyles.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AAEtD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,kBAAkB,EAAE,MAAM,CACrC,WAAW,EACX,MAAM,CAKP,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,cAAc,6DACiC,CAAA;AAE5D,eAAO,MAAM,oBAAoB,EAAE,MAAM,CACvC,WAAW,EACX,MAAM,CAKP,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,EAAE,MAAM,CACvC,WAAW,EACX,MAAM,CAKP,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,WAAW,EAAE,MAAM,CAItD,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,kBAAkB,gGACgE,CAAA;AAE/F,8DAA8D;AAC9D,eAAO,MAAM,6BAA6B,uCACJ,CAAA"}

package/dist/tileStyles.js

@@ -0,0 +1,98 @@
+/**
+ * The tile shape, shared by the two components that draw it.
+ *
+ * A tile is a bordered card carrying a name and a line of help, laid
+ * out in a grid that gains columns with its CONTAINER. `RadioGroup`
+ * draws one per option when `itemShape="tile"`; `ActionTiles` draws
+ * one per action. The two must be the **same box** — a page that puts
+ * "which activity" beside "what would you like to do" would otherwise
+ * show two cards with different padding, different corners and
+ * different gaps, which is the drift this file exists to make
+ * impossible.
+ *
+ * Same argument as `CONTROL_BASE_CLASS`, which `Button` and
+ * `ButtonLink` share for the same reason: "identical" spelled as two
+ * copies of one string is a promise that survives exactly one edit.
+ *
+ * These were `RadioGroup`'s private constants until `ActionTiles`
+ * shipped. Nothing about their values changed on the way out.
+ */
+/**
+ * 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.
+ *
+ * This is also the whole reason `ActionTiles` exists rather than a
+ * `Button` with a `className`: a `Button` is sized by
+ * `h-(--control-height-md)` and carries **no block padding at all**,
+ * so an app that reaches for `height: auto` to let one wrap gets a
+ * two-line card with `padding: 0` down its block axis and no error
+ * anywhere. QueuePilot's queue-type chooser shipped exactly that.
+ */
+export const TILE_PADDING_CLASS = {
+    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 layered over it is a
+ * **border and a surface**, never colour alone — the same reason
+ * `Stepper` refuses to say "done" with a hue.
+ */
+export const TILE_BOX_CLASS = "rounded-lg border border-border-subtle bg-surface-raised";
+export const TILE_TEXT_SIZE_CLASS = {
+    sm: "text-sm",
+    md: "text-md",
+    lg: "text-lg",
+};
+/**
+ * One step down from the tile'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.
+ */
+export const TILE_HINT_TEXT_CLASS = {
+    sm: "text-xs",
+    md: "text-xs",
+    lg: "text-sm",
+};
+/**
+ * Wider than a list's 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.
+ */
+export const TILE_GAP_CLASS = {
+    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 tile set is a bounded group
+ * inside a form section or a first step, where the only question is
+ * how many fit across the box it was given.
+ */
+export const TILE_COLUMNS_CLASS = "grid-cols-[repeat(auto-fill,minmax(min(var(--charcuterie-tile-min-inline-size),100%),1fr))]";
+/** The property `TILE_COLUMNS_CLASS` reads its floor from. */
+export const TILE_MIN_INLINE_SIZE_PROPERTY = "--charcuterie-tile-min-inline-size";
+//# sourceMappingURL=tileStyles.js.map

package/dist/tileStyles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tileStyles.js","sourceRoot":"","sources":["../src/tileStyles.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAG3B;IACF,EAAE,EAAE,aAAa;IACjB,EAAE,EAAE,aAAa;IACjB,EAAE,EAAE,aAAa;CAClB,CAAA;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,cAAc,GACzB,0DAA0D,CAAA;AAE5D,MAAM,CAAC,MAAM,oBAAoB,GAG7B;IACF,EAAE,EAAE,SAAS;IACb,EAAE,EAAE,SAAS;IACb,EAAE,EAAE,SAAS;CACd,CAAA;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAG7B;IACF,EAAE,EAAE,SAAS;IACb,EAAE,EAAE,SAAS;IACb,EAAE,EAAE,SAAS;CACd,CAAA;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,cAAc,GAAgC;IACzD,EAAE,EAAE,SAAS;IACb,EAAE,EAAE,OAAO;IACX,EAAE,EAAE,OAAO;CACZ,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAC7B,6FAA6F,CAAA;AAE/F,8DAA8D;AAC9D,MAAM,CAAC,MAAM,6BAA6B,GACxC,oCAAoC,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@charcuterie/ui",
-  "version": "3.30.0",
+  "version": "3.32.0",
   "description": "The Charcuterie components. Tokens for look, @charcuterie/logic for state, ARIA that agents can actually drive.",
   "license": "MIT",
   "type": "module",

package/src/ActionTiles/ActionTiles.mdx

@@ -0,0 +1,131 @@
+import { Canvas, Controls, Meta } from "@storybook/addon-docs/blocks";
+
+import * as ActionTilesStories from "./ActionTiles.stories";
+
+<Meta of={ActionTilesStories} />
+
+# ActionTiles
+
+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`](/docs/components-controls-radiogroup--docs)'s `itemShape="tile"` with
+the radio taken away. The 2026-08-25 record 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"*.
+
+<Canvas of={ActionTilesStories.Default} />
+
+## Props
+
+<Controls />
+
+## 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.
+
+A first step that opens the next step is the second kind. QueuePilot's "Queue type" chooser
+— *Picks* or *Rules*, and the editor for the one you press opens immediately — is the case
+this component was built for; that same app's Tonight activity filter stays a `RadioGroup`,
+because it holds a value the Go button below it reads.
+
+<Canvas of={ActionTilesStories.BesideTheRadioTile} />
+
+## 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**. It
+is a one-line control by contract, which is what keeps every control on a form row the same
+height at every density.
+
+So an app that wants a wrapping two-line card reaches for `height: auto` — and that deletes
+the height and leaves `padding: 0` down the block axis. The title sits flush against the top
+border and the description flush against the bottom one. Nothing reports it: the class really
+is in the DOM, TypeScript never reads the CSS, and unstyled-but-present markup passes axe.
+
+That shipped in QueuePilot's queue-type chooser and is what this component exists to have
+made impossible. `ActionTiles.test.tsx` reads the padding off `getComputedStyle` in a real
+browser for the same reason.
+
+<Canvas of={ActionTilesStories.AllStates} />
+
+## The box is shared, and asserted rather than trusted
+
+`tileStyles.ts` holds the padding, the border, the radius, the surface, the type ramp, the
+hint ramp, the gap and the grid; `RadioGroup` and `ActionTiles` both read it. Two tile sets
+on one page have to be the same card, and "identical" spelled as two copies of one string is
+a promise that survives exactly one edit — the same argument `CONTROL_BASE_CLASS` settles
+between `Button` and `ButtonLink`.
+
+The test compares **computed** styles of an action tile and a resting radio tile, not class
+names. A class-name assertion passes while the paint is wrong.
+
+## `href` makes the tile a real anchor
+
+Middle-click, ctrl-click, "open in a new tab", "copy link address" and the status bar all
+come from the element rather than from the paint — the standing
+[buttons are actions, links are navigation](/docs/guides-routing--docs) rule. A same-origin
+destination goes through the injected `RouterLink`; an external one or a fragment falls back
+to a plain `<a>`, because pushing `https://…` or `#credits` onto the history stack navigates
+the SPA to a route that does not exist.
+
+A set may mix links and buttons. `isDisabled` on a link drops the `href` entirely rather than
+shipping a focusable anchor that silently ignores clicks, and keeps `role="link"` plus
+`aria-disabled` so it is *announced* as unavailable rather than vanishing from the tree.
+
+<Canvas of={ActionTilesStories.Links} />
+
+## `role="group"`, and no roving tabindex
+
+These are ordinary buttons and anchors, so the platform already owns the keyboard: Tab
+reaches **each** tile, Enter and Space press a button, Enter follows a link.
+
+A radio group borrows one tab stop and moves its 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.
+
+The group takes a required `label`, which names the set — "Queue type", "Pick a tool" — the
+way a `radiogroup` is named. A set of unnamed tiles is a pile of buttons.
+
+## A tile may lead with an icon
+
+`icon` is `aria-hidden` by construction, because the name it sits above is inside the same
+tile — an announced icon is the label read twice. The library still ships no icons; apps
+bring their own.
+
+<Canvas of={ActionTilesStories.WithIcons} />
+
+## The grid takes its columns from the container
+
+`repeat(auto-fill, minmax(min(var(--charcuterie-tile-min-inline-size), 100%), 1fr))` — the
+same constant `RadioGroup`'s tile shape uses, and each of its three parts is load-bearing:
+
+- **`auto-fill`, not `auto-fit`.** `auto-fit` collapses the empty tracks and lets the
+  survivors share the whole row, so six tiles in a 2560px container become six 420px slabs —
+  the full-width-row shape in a new costume.
+- **`min(…, 100%)`.** Without it the 200px floor overflows a container narrower than one
+  tile, which is a horizontal scrollbar in the Narrow View.
+- **A custom property, not an interpolated class.** Tailwind scans source *text* for complete
+  class strings, so `` `grid-cols-[…${n}px…]` `` generates nothing, paints nothing and
+  reports nothing.
+
+This is **not** `useAdaptiveColumns`. That hook buys a column with **height**, for an
+unbounded gallery that is going to scroll; a tile set is a bounded group inside a form section
+or a first step, where the only question is how many fit across the box it was given.
+
+<Canvas of={ActionTilesStories.Responsive} />
+
+## What this deliberately does not do
+
+- **Hold a selection.** That is `RadioGroup itemShape="tile"`, and giving these tiles
+  `aria-checked` would be the mistake the 2026-08-25 record refused.
+- **Toggle per tile.** A multi-select tile is a checkbox group and a different record.
+- **Carry artwork.** That is [`MediaTile`](/docs/components-data-mediatile--docs).
+
+<Canvas of={ActionTilesStories.Interactive} />

package/src/ActionTiles/ActionTiles.stories.tsx

@@ -0,0 +1,311 @@
+import type { Meta, StoryObj } from "@storybook/react"
+
+import { controlSizeArgType } from "../argTypes.storyHelpers.ts"
+import {
+  ContainerBoard,
+  StoryCell,
+  StoryGrid,
+  StorySection,
+} from "../board.storyHelpers.tsx"
+import {
+  InboxIcon,
+  PlayIcon,
+  SearchIcon,
+} from "../icons.storyHelpers.tsx"
+import { RadioGroup } from "../RadioGroup/RadioGroup.tsx"
+import type { ActionTileItem } from "./ActionTiles.tsx"
+import { ActionTiles } from "./ActionTiles.tsx"
+
+/**
+ * The shape this component was built for: a first step that opens
+ * the next step. Nothing stays selected, because nothing was chosen
+ * — the page moved on.
+ */
+const QUEUE_TYPE_ITEMS: ActionTileItem[] = [
+  {
+    hint: "Choose titles yourself, then arrange them in priority and random lanes.",
+    label: "Picks",
+    value: "picks",
+  },
+  {
+    hint: "Set eligibility filters and let the app select matching titles.",
+    label: "Rules",
+    value: "rules",
+  },
+]
+
+/** A tile may lead with an icon. The library ships none. */
+const START_ITEMS: ActionTileItem[] = [
+  {
+    hint: "Everything that arrived since the last run.",
+    icon: <InboxIcon />,
+    label: "New arrivals",
+    value: "new",
+  },
+  {
+    hint: "Whatever the saved query matches today.",
+    icon: <SearchIcon />,
+    label: "Saved search",
+    value: "search",
+  },
+  {
+    hint: "Pick up where the last session stopped.",
+    icon: <PlayIcon />,
+    label: "Continue",
+    value: "continue",
+  },
+]
+
+/**
+ * A tile that carries an `href` is a real `<a href>`, so
+ * middle-click, ctrl-click and "copy link address" all work. The
+ * same set may mix links and buttons.
+ */
+const TOOL_ITEMS: ActionTileItem[] = [
+  {
+    hint: "Read a container's tracks and say what would change.",
+    href: "/tools/inspect",
+    label: "Inspect",
+    value: "inspect",
+  },
+  {
+    hint: "Rewrite the container without touching a stream.",
+    href: "/tools/remux",
+    label: "Remux",
+    value: "remux",
+  },
+  {
+    hint: "The reference, on the upstream site.",
+    href: "https://example.com/docs",
+    isExternal: true,
+    label: "Read the docs",
+    value: "docs",
+  },
+]
+
+const meta = {
+  title: "Components/Actions/ActionTiles",
+  component: ActionTiles,
+  parameters: { layout: "padded" },
+  argTypes: { size: controlSizeArgType },
+  // The component's own defaults, restated — Storybook does not seed
+  // `args` from docgen, so an unstated default shows in the props
+  // table with nothing selected in its control.
+  args: {
+    minTileInlineSize: 200,
+    size: "md",
+  },
+} satisfies Meta<typeof ActionTiles>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+export const Default: Story = {
+  args: { items: QUEUE_TYPE_ITEMS, label: "Queue type" },
+}
+
+export const AllVariants: Story = {
+  args: { items: QUEUE_TYPE_ITEMS, label: "Queue type" },
+  render: (controlProps) => (
+    <StorySection title="Three sizes, all reading the density axis rather than hardcoding a length — the same three a RadioGroup tile has, from the same tokens.">
+      <StoryGrid columns={3}>
+        {(["sm", "md", "lg"] as const).map((size) => (
+          <StoryCell
+            align="stretch"
+            key={size}
+            label={size}
+          >
+            <ActionTiles
+              {...controlProps}
+              label={`Queue type at ${size}`}
+              minTileInlineSize={160}
+              size={size}
+            />
+          </StoryCell>
+        ))}
+      </StoryGrid>
+    </StorySection>
+  ),
+}
+
+/**
+ * A tile may lead with an icon. The library ships none — these are
+ * story-only SVGs, exactly what an app passes — and the icon is
+ * `aria-hidden` by construction, because the name it sits above is
+ * inside the same tile.
+ */
+export const WithIcons: Story = {
+  args: { items: START_ITEMS, label: "Where to start" },
+}
+
+/**
+ * `href` makes the tile an anchor rather than a button, routed
+ * through the injected `RouterLink` when the destination is the
+ * router's. An `isExternal` tile falls back to a plain `<a
+ * target="_blank">` and says so to a screen reader.
+ */
+export const Links: Story = {
+  args: { items: TOOL_ITEMS, label: "Pick a tool" },
+}
+
+export const AllStates: Story = {
+  args: { items: QUEUE_TYPE_ITEMS, label: "Queue type" },
+  render: (controlProps) => (
+    <StorySection title="What varies is what a tile does and whether it can be pressed. Nothing here is 'selected' — that state belongs to RadioGroup itemShape='tile'.">
+      <StoryGrid columns={2}>
+        <StoryCell align="stretch" label="two actions">
+          <ActionTiles
+            {...controlProps}
+            label="Queue type"
+          />
+        </StoryCell>
+
+        <StoryCell align="stretch" label="no hint">
+          <ActionTiles
+            {...controlProps}
+            items={[
+              { label: "Picks", value: "picks" },
+              { label: "Rules", value: "rules" },
+            ]}
+            label="Queue type, names only"
+          />
+        </StoryCell>
+
+        <StoryCell align="stretch" label="a disabled tile">
+          <ActionTiles
+            {...controlProps}
+            items={[
+              QUEUE_TYPE_ITEMS[0] as ActionTileItem,
+              {
+                hint: "No provider is configured to filter on.",
+                isDisabled: true,
+                label: "Rules",
+                value: "rules",
+              },
+            ]}
+            label="Queue type with Rules unavailable"
+          />
+        </StoryCell>
+
+        <StoryCell align="stretch" label="a disabled link">
+          <ActionTiles
+            {...controlProps}
+            items={[
+              {
+                hint: "Read a container's tracks and say what would change.",
+                href: "/tools/inspect",
+                label: "Inspect",
+                value: "inspect",
+              },
+              {
+                hint: "Nothing is loaded to remux yet.",
+                href: "/tools/remux",
+                isDisabled: true,
+                label: "Remux",
+                value: "remux",
+              },
+            ]}
+            label="Pick a tool with Remux unavailable"
+          />
+        </StoryCell>
+
+        <StoryCell align="stretch" label="links">
+          <ActionTiles
+            {...controlProps}
+            items={TOOL_ITEMS}
+            label="Pick a tool"
+          />
+        </StoryCell>
+
+        <StoryCell align="stretch" label="icons">
+          <ActionTiles
+            {...controlProps}
+            items={START_ITEMS}
+            label="Where to start"
+          />
+        </StoryCell>
+      </StoryGrid>
+    </StorySection>
+  ),
+}
+
+/**
+ * The two tile components, side by side, which is the comparison a
+ * reader choosing between them actually needs.
+ *
+ * The box is the **same box** — `tileStyles.ts` holds the padding,
+ * the border, the radius, the surface, the type ramp and the grid,
+ * and both components read it. What differs is everything the box is
+ * not: one announces "1 of 2" and keeps a tile selected, the other
+ * presses and is done.
+ */
+export const BesideTheRadioTile: Story = {
+  args: { items: QUEUE_TYPE_ITEMS, label: "Queue type" },
+  render: (controlProps) => (
+    <StorySection title="One box, two controls. Only the resting radio tile matches — a checked one wears the accent edge, which is the state ActionTiles has none of.">
+      <StoryGrid columns={2}>
+        <StoryCell
+          align="stretch"
+          label="ActionTiles — presses and is done"
+        >
+          <ActionTiles {...controlProps} />
+        </StoryCell>
+
+        <StoryCell
+          align="stretch"
+          label="RadioGroup itemShape='tile' — holds a value"
+        >
+          <RadioGroup
+            itemShape="tile"
+            items={QUEUE_TYPE_ITEMS.map(
+              ({ hint, label, value }) => ({
+                hint,
+                label,
+                value,
+              }),
+            )}
+            label="Queue type, as radios"
+            size={controlProps.size}
+          />
+        </StoryCell>
+      </StoryGrid>
+    </StorySection>
+  ),
+}
+
+/**
+ * Column count comes from the **container**, never the window — the
+ * standing rule for any list of cards, and the reason this board
+ * varies a wrapper's width rather than the viewport's.
+ *
+ * At the 200px default floor: one track at 15rem, one at 24rem, two
+ * at 34rem. `auto-fill` and deliberately not `auto-fit`, so the
+ * tiles keep their size in a container with room to spare instead of
+ * stretching to fill it. Same formula as the `RadioGroup` tile, from
+ * the same constant.
+ */
+export const Responsive: Story = {
+  args: { items: START_ITEMS, label: "Where to start" },
+  render: (controlProps) => (
+    <ContainerBoard>
+      {(width) => (
+        <ActionTiles
+          {...controlProps}
+          label={`Where to start at ${width}`}
+        />
+      )}
+    </ContainerBoard>
+  ),
+}
+
+/**
+ * The complete keyboard path, and it is the platform's: Tab reaches
+ * **each** tile, Enter and Space press a button one, Enter follows a
+ * link one. There is no roving tabindex here — a radio group borrows
+ * one tab stop because exactly one of its options is true at a time,
+ * and nothing here is true.
+ */
+export const Interactive: Story = {
+  args: { items: QUEUE_TYPE_ITEMS, label: "Queue type" },
+}