@charcuterie/ui 3.14.4 → 3.16.0

package/src/RadioGroup/RadioGroup.tsx

@@ -4,13 +4,40 @@ import {
   useSinglePicker,
 } from "@charcuterie/logic"
 import type { ControlSize } from "@charcuterie/tokens"
-import type { ReactNode } from "react"
+import type { CSSProperties, ReactNode } from "react"
 import { useCallback, useEffect, useRef } from "react"
 
 import { toClassName } from "../toClassName.ts"
 import { RadioGroupOption } from "./RadioGroupOption.tsx"
 
+/**
+ * Which shape the options are drawn in. The control is the same
+ * `radiogroup` either way — this is layout, and it is a prop rather
+ * than a second component because nothing about the semantics, the
+ * keyboard model or the element changes with it.
+ *
+ *  - `row` — the default. Each option is a line of prose beside its
+ *    radio, stacked down the page. The form-length list.
+ *  - `tile` — each option is a bordered card carrying a name, an
+ *    optional line of help and a selected surface, and the group is
+ *    a grid that gains columns with the CONTAINER's width.
+ */
+export type RadioItemShape = "row" | "tile"
+
 export type RadioItem = {
+  /**
+   * A line of help under the label. Drawn one step down the type
+   * ramp in `content-muted`, inside the option's accessible name —
+   * a hint a screen reader never reads is a hint half the audience
+   * does not have.
+   */
+  hint?: ReactNode
+  /**
+   * Leading content, before the name. A `Badge`, an app's own icon,
+   * a count. `tile` only: a row already leads with its radio, and a
+   * second leading mark either side of it has nowhere to sit.
+   */
+  icon?: ReactNode
   /**
    * A disabled option is simply **not registered** with the roving
    * group, so the arrow keys skip it without any command in
@@ -24,6 +51,11 @@ export type RadioItem = {
 
 export type RadioGroupProps = {
   className?: string
+  /**
+   * Draws each option as a card in a grid instead of a row in a
+   * stack. Defaults to `row`.
+   */
+  itemShape?: RadioItemShape
   items: readonly RadioItem[]
   /**
    * Shows which option is chosen at full contrast but refuses to move
@@ -34,6 +66,13 @@ export type RadioGroupProps = {
   isReadOnly?: boolean
   /** The group's accessible name. Required. */
   label: string
+  /**
+   * The narrowest a tile track may be, in CSS px. `tile` only.
+   *
+   * 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
   onChange?: (selectedValue: string | null) => void
   /** **Initial** only. Charcuterie owns it from then on. */
   selectedValue?: string
@@ -46,6 +85,47 @@ 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`.
@@ -67,12 +147,24 @@ const GAP_CLASS: Record<ControlSize, string> = {
  * choice from a named set is a radio group, and its arrow keys both
  * move focus and check — APG's one activation mode, the same reason
  * `SegmentedControl` has no `manual` prop.
+ *
+ * ### `itemShape="tile"` is the choice tile
+ *
+ * A bordered card carrying a name, a line of help and a selected
+ * surface, in a grid that gains columns with its container. It is a
+ * prop and not a third component because **only the box changes**:
+ * the element, the role, the roving tabindex, selection-follows-focus
+ * 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.
  */
 export const RadioGroup = ({
   className,
+  itemShape = "row",
   items,
   isReadOnly = false,
   label,
+  minTileInlineSize = 200,
   onChange,
   selectedValue,
   size = "md",
@@ -83,6 +175,8 @@ export const RadioGroup = ({
     new Map<string, HTMLButtonElement>(),
   )
 
+  const isTile = itemShape === "tile"
+
   const initialValue =
     selectedValue ??
     items.find((one) => !one.isDisabled)?.value ??
@@ -152,8 +246,10 @@ export const RadioGroup = ({
       aria-label={label}
       aria-readonly={isReadOnly || undefined}
       className={toClassName(
-        "flex flex-col",
-        GAP_CLASS[size],
+        isTile
+          ? toClassName("grid", TILE_COLUMNS_CLASS)
+          : "flex flex-col",
+        isTile ? TILE_GAP_CLASS[size] : GAP_CLASS[size],
         className,
       )}
       onKeyDown={(keyEvent) => {
@@ -193,6 +289,13 @@ export const RadioGroup = ({
         }
       }}
       ref={groupRef}
+      style={
+        isTile
+          ? ({
+              "--charcuterie-tile-min-inline-size": `${minTileInlineSize}px`,
+            } as CSSProperties)
+          : undefined
+      }
       role="radiogroup"
     >
       {items.map((item) => (
@@ -200,6 +303,7 @@ export const RadioGroup = ({
           isChecked={checkedValue === item.value}
           isReadOnly={isReadOnly}
           item={item}
+          itemShape={itemShape}
           key={item.value}
           onChoose={chooseOption}
           registerFocus={focus.register}

package/src/RadioGroup/RadioGroupOption.tsx

@@ -4,12 +4,16 @@ import { useEffect } from "react"
 
 import { FOCUS_RING_CLASS } from "../intentStyles.ts"
 import { toClassName } from "../toClassName.ts"
-import type { RadioItem } from "./RadioGroup.tsx"
+import type {
+  RadioItem,
+  RadioItemShape,
+} from "./RadioGroup.tsx"
 
 export type RadioGroupOptionProps = {
   isChecked: boolean
   isReadOnly: boolean
   item: RadioItem
+  itemShape: RadioItemShape
   onChoose: (value: string) => void
   /** `RovingFocus.register` — membership of the arrow-key group. */
   registerFocus: (value: string) => () => void
@@ -44,6 +48,36 @@ const TEXT_SIZE_CLASS: Record<ControlSize, string> = {
   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.
@@ -52,11 +86,22 @@ const TEXT_SIZE_CLASS: Record<ControlSize, string> = {
  * with a background, so the checked dot can be centred by the grid
  * and sized independently of the ring — a filled `bg-intent-accent`
  * ring with no inner dot reads as a checkbox, not a radio.
+ *
+ * ### The tile shape is the same element with a border
+ *
+ * `itemShape="tile"` swaps `inline-flex` for `flex` — a grid item
+ * stretches to its track, and an inline box would sit at
+ * max-content inside it — adds the card's padding and border, and
+ * moves the ring to the top of a two-line label. The radio dot is
+ * still there and is still the thing a screen reader reads: a tile
+ * with its border taken away is this row, which is why the two are
+ * one component.
  */
 export const RadioGroupOption = ({
   isChecked,
   isReadOnly,
   item,
+  itemShape,
   onChoose,
   registerFocus,
   registerSelection,
@@ -64,7 +109,15 @@ export const RadioGroupOption = ({
   tabIndex,
   trackElement,
 }: RadioGroupOptionProps): ReactNode => {
-  const { isDisabled = false, label, value } = item
+  const {
+    hint,
+    icon,
+    isDisabled = false,
+    label,
+    value,
+  } = item
+
+  const isTile = itemShape === "tile"
 
   useEffect(
     () => registerSelection(value),
@@ -84,7 +137,21 @@ export const RadioGroupOption = ({
     <button
       aria-checked={isChecked}
       className={toClassName(
-        "inline-flex items-center gap-2 rounded-sm text-content-secondary text-start transition-colors duration-(--duration-fast) ease-standard",
+        "gap-2 text-content-secondary text-start transition-colors duration-(--duration-fast) ease-standard",
+        isTile
+          ? toClassName(
+              "flex min-w-0 items-start",
+              TILE_BOX_CLASS,
+              TILE_PADDING_CLASS[size],
+            )
+          : toClassName(
+              "inline-flex rounded-sm",
+              // A hint puts a second line under the label, and a ring
+              // centred against both sits beside neither.
+              hint === undefined
+                ? "items-center"
+                : "items-start",
+            ),
         TEXT_SIZE_CLASS[size],
         // Disabled turns the whole option down with `opacity-60`, the
         // same family treatment as `Checkbox` and `Switch`, rather than
@@ -95,7 +162,18 @@ export const RadioGroupOption = ({
           ? "cursor-not-allowed opacity-60"
           : isReadOnly
             ? "cursor-default"
-            : "cursor-pointer hover:text-content-primary",
+            : isTile
+              ? "cursor-pointer hover:border-border-strong"
+              : "cursor-pointer hover:text-content-primary",
+        // The selected tile carries the accent on its EDGE and lifts
+        // its surface. A tile that said "chosen" with a background
+        // alone would be the one state a monochrome ePaper build
+        // cannot show at all.
+        isTile && isChecked
+          ? isReadOnly
+            ? "border-intent-neutral-solid bg-surface-overlay"
+            : "border-intent-accent-solid bg-surface-overlay"
+          : "",
         FOCUS_RING_CLASS,
       )}
       disabled={isDisabled}
@@ -142,7 +220,46 @@ export const RadioGroupOption = ({
         />
       </span>
 
-      <span>{label}</span>
+      {hint === undefined && !isTile ? (
+        <span>{label}</span>
+      ) : (
+        // `min-w-0` and `wrap-anywhere` together, because a grid
+        // item's automatic minimum is its min-content width: one
+        // unbroken token — a path, a URL, a title with no spaces —
+        // otherwise sets the track's floor and shoves the grid out
+        // of its container.
+        <span className="flex min-w-0 flex-col gap-0.5 wrap-anywhere">
+          {icon !== undefined && isTile ? (
+            // Decorative by construction: the name it sits beside is
+            // in the same button, so an announced icon is the label
+            // read twice.
+            <span aria-hidden className="flex">
+              {icon}
+            </span>
+          ) : null}
+
+          <span
+            className={
+              isTile
+                ? "font-semibold text-content-primary"
+                : undefined
+            }
+          >
+            {label}
+          </span>
+
+          {hint === undefined ? null : (
+            <span
+              className={toClassName(
+                "font-normal text-content-muted",
+                HINT_TEXT_CLASS[size],
+              )}
+            >
+              {hint}
+            </span>
+          )}
+        </span>
+      )}
     </button>
   )
 }

package/src/Stepper/Stepper.test.tsx

@@ -82,6 +82,23 @@ test("the last step draws no connector", async () => {
   await expect(connectors[2]).toBeNull()
 })
 
+test("each step carries its key into the DOM, so a re-order can animate", async () => {
+  const { canvas } = await mountStory(Default)
+
+  // React's `key` never reaches the markup. Without this attribute
+  // a caller who re-orders `steps` has no way to say which `<li>`
+  // is which, and `useFlipList` — which matches on exactly this
+  // attribute — would fall back to pairing items by POSITION,
+  // measure a delta of zero for every one, and animate nothing.
+  await expect(
+    canvas
+      .getAllByRole("listitem")
+      .map((item: HTMLElement) =>
+        item.getAttribute("data-flip-key"),
+      ),
+  ).toEqual(["rip", "tag", "file"])
+})
+
 test("advancing moves which step is current", async () => {
   const { canvas } = await mountStory(Interactive)
 

package/src/Stepper/Stepper.tsx

@@ -1,3 +1,4 @@
+import { FLIP_KEY_ATTRIBUTE } from "@charcuterie/logic"
 import type { ReactNode } from "react"
 
 import { toClassName } from "../toClassName.ts"
@@ -138,7 +139,27 @@ export const Stepper = ({
           const isLast = index === steps.length - 1
 
           return (
+            /*
+             * `data-flip-key` carries `step.key` into the DOM so a
+             * re-ordered stepper can animate with `useFlipList`
+             * from `@charcuterie/logic`, which matches items on
+             * exactly this attribute.
+             *
+             * Emitted always, not behind a prop. React's `key` is
+             * invisible to the DOM, so without this a caller who
+             * re-orders `steps` has no way to say which `<li>` is
+             * which — and FLIP matched by POSITION pairs every item
+             * with whatever now sits where it used to be, measures
+             * a delta of zero, and animates nothing. Docket's phase
+             * list is the case: the owner reported *"when I move
+             * them up and down, there's no animation"*, and the
+             * step's identity never reached the markup.
+             *
+             * A data attribute on a list item costs nothing when
+             * nobody reads it, which is why it is not opt-in.
+             */
             <li
+              {...{ [FLIP_KEY_ATTRIBUTE]: step.key }}
               className={toClassName(
                 "relative grid grid-cols-[auto_minmax(0,1fr)] grid-rows-[auto_minmax(0,1fr)] gap-x-3",
                 isHorizontal &&