@charcuterie/ui 4.0.0 → 4.2.0

package/src/ActionTiles/ActionTiles.tsx

@@ -1,10 +1,24 @@
-import type { ControlSize } from "@charcuterie/tokens"
+import type {
+  CategoricalIndex,
+  ControlSize,
+} from "@charcuterie/tokens"
+import {
+  CATEGORICAL_INDEX_COUNT,
+  CATEGORICAL_INDEXES,
+} from "@charcuterie/tokens"
 import type { CSSProperties, ReactNode } from "react"
 
+import { getAccentEdgeClassName } from "../Card/cardAccentEdge.ts"
+import {
+  CATEGORICAL_CONTENT_CLASS,
+  CATEGORICAL_HOVER_BORDER_CLASS,
+  CATEGORICAL_HOVER_CLASS,
+} from "../categoricalStyles.ts"
 import { FOCUS_RING_CLASS } from "../intentStyles.ts"
 import { useRouterLink } from "../RouterLink/RouterLinkProvider.tsx"
 import { getIsRoutedHref } from "../RouterLink/routerLink.ts"
 import {
+  TILE_ACCENT_EDGE_PADDING_CLASS,
   TILE_BOX_CLASS,
   TILE_COLUMNS_CLASS,
   TILE_GAP_CLASS,
@@ -17,6 +31,20 @@ import { toClassName } from "../toClassName.ts"
 import { VisuallyHidden } from "../VisuallyHidden/VisuallyHidden.tsx"
 
 export type ActionTileItem = {
+  /**
+   * Which of the ten hues this tile wears, overriding the one its
+   * position would have given it.
+   *
+   * Reach for it when a tile's colour means something outside the
+   * set — a destination that is red everywhere else in the app, a
+   * pair that must not drift apart when a third tile is inserted
+   * between them. An overridden tile keeps its hue and the rest go
+   * on walking the palette in order, so naming one does not force
+   * naming all of them.
+   *
+   * Ignored when the set is `accent="none"`.
+   */
+  categorical?: CategoricalIndex
   /**
    * A line of help under the name. Drawn one step down the type ramp
    * in `content-muted`, **inside** the tile — so `getByRole` computes
@@ -36,10 +64,15 @@ export type ActionTileItem = {
    */
   href?: string
   /**
-   * Leading content, above the name. A `Badge`, an app's own icon, a
-   * count.
+   * Leading content, drawn **beside** the name rather than above it.
+   * A glyph, a `Badge`, a count.
+   *
+   * Takes the tile's hue, so an app passes a `stroke="currentColor"`
+   * path and states no colour of its own. Size is the app's: around
+   * 22px at `md` and 30px at `lg` reads the way the fleet's
+   * hand-rolled tool cards did.
    *
-   * `aria-hidden` by construction: the name it sits above is inside
+   * `aria-hidden` by construction: the name it sits beside is inside
    * the same tile, so an announced icon is the label read twice.
    */
   icon?: ReactNode
@@ -57,7 +90,23 @@ export type ActionTileItem = {
   value: string
 }
 
+/**
+ * Where a tile's colour comes from.
+ *
+ *  - `auto` — the set walks the ten-hue categorical palette in
+ *    order, so eight tiles get eight colours and no call site does
+ *    any work. An item may still name its own with `categorical`.
+ *  - `none` — no bar, no hue, and the neutral `border-strong`
+ *    hover every other box uses.
+ */
+export type ActionTilesAccent = "auto" | "none"
+
 export type ActionTilesProps = {
+  /**
+   * Whether the set colours itself. `auto` by default — see
+   * {@link ActionTilesAccent}.
+   */
+  accent?: ActionTilesAccent
   className?: string
   items: readonly ActionTileItem[]
   /** The set's accessible name. Required. */
@@ -77,9 +126,51 @@ export type ActionTilesProps = {
 }
 
 /**
- * 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.
+ * The gap between the icon and the name it sits beside.
+ *
+ * Local to this component rather than in `tileStyles.ts`, because a
+ * radio tile's inner layout is a control beside a label and has no
+ * head row to space. The shared file owns the BOX; this is what goes
+ * in it.
+ */
+const HEAD_GAP_CLASS: Record<ControlSize, string> = {
+  sm: "gap-2",
+  md: "gap-2.5",
+  lg: "gap-3",
+}
+
+/** The gap between the head row and the hint under it. */
+const STACK_GAP_CLASS: Record<ControlSize, string> = {
+  sm: "gap-1",
+  md: "gap-1",
+  lg: "gap-2",
+}
+
+/**
+ * The hue a tile wears when it did not name one: its position in
+ * the set, wrapping at ten.
+ *
+ * Position rather than `getCategoricalIndex(value)`. That helper
+ * hashes a key so a row keeps its colour forever across a list
+ * nobody controls the order of — right for Docket's labels, wrong
+ * here, because a hash of two tile values can collide and hand a
+ * two-tile set the same colour twice. A tile set is short, ordered,
+ * and written out in the source; the eye reads it as a row, so the
+ * palette is walked as one.
+ */
+const getTileCategorical = (
+  item: ActionTileItem,
+  position: number,
+): CategoricalIndex =>
+  item.categorical ??
+  (CATEGORICAL_INDEXES[
+    position % CATEGORICAL_INDEX_COUNT
+  ] as CategoricalIndex)
+
+/**
+ * A set of ACTIONS drawn as tiles — a bordered card carrying a
+ * colour bar, an icon beside its 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
@@ -108,6 +199,30 @@ export type ActionTilesProps = {
  * why QueuePilot's "Queue type" chooser is here and its Tonight
  * activity filter is not.
  *
+ * ### The colour is the point, and it is not decoration
+ *
+ * The first version of this component was neutral, and the owner's
+ * verdict on it was *"very boring, not colorful"*. Three apps had
+ * already answered the question themselves — mux-magic, Gallery
+ * Downloader and points-market all colour their tiles by hand — so
+ * the paint is now the library's and every one of them can stop.
+ *
+ * A tile wears a **bar down its leading edge**, drawn by `Card`'s
+ * accent-edge pseudo-element so a tile and a card on the same page
+ * are the same bar rather than two that nearly match. Its icon takes
+ * the same hue, and the box hovers in it too. The hue comes from the
+ * ten-wide categorical palette, taken **in order**, which is why a
+ * set of eight needs no colour props at all. See
+ * [the tile paint record](../../../../docs/decisions/2026-09-02-an-action-tile-is-coloured-and-the-icon-sits-beside-the-name.md)
+ * for the four other paints that were drawn and rejected.
+ *
+ * `categorical` and not `intent`, for the reason
+ * [`cardAccentEdge.ts`](../Card/cardAccentEdge.ts) gives: an intent
+ * is a *claim* — `danger` says what happens if you press the thing —
+ * and "Builder" beside "Jobs" is making no claim about either. Ten
+ * numbered hues say only "these are different from each other",
+ * which is exactly what a tile set means.
+ *
  * ### Why this is not a `Button` with a `className`
  *
  * A `Button` is sized by `h-(--control-height-md)` and carries **no
@@ -130,6 +245,7 @@ export type ActionTilesProps = {
  * ability to Tab to the second tile.
  */
 export const ActionTiles = ({
+  accent = "auto",
   className,
   items,
   label,
@@ -157,8 +273,8 @@ export const ActionTiles = ({
         } as CSSProperties
       }
     >
-      {items.map(
-        ({
+      {items.map((item, position) => {
+        const {
           hint,
           href,
           icon,
@@ -166,127 +282,175 @@ export const ActionTiles = ({
           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,
-          )
+        } = item
 
-          const content = (
-            <>
-              {icon === undefined ? null : (
-                <span aria-hidden className="flex">
-                  {icon}
-                </span>
-              )}
+        const categorical =
+          accent === "none"
+            ? null
+            : getTileCategorical(item, position)
 
-              <span className="font-semibold text-content-primary">
-                {tileLabel}
-              </span>
+        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 text-start wrap-anywhere transition-colors duration-(--duration-fast) ease-standard",
+          STACK_GAP_CLASS[size],
+          TILE_BOX_CLASS,
+          TILE_PADDING_CLASS[size],
+          TILE_TEXT_SIZE_CLASS[size],
+          // The bar is an overlay and takes no space in the box
+          // model, so the tile makes room for it or the text lands
+          // on top of it.
+          categorical === null
+            ? null
+            : toClassName(
+                getAccentEdgeClassName({ categorical }),
+                TILE_ACCENT_EDGE_PADDING_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. It also drops
+          // every hover class: a tile that cannot be pressed must
+          // not light up under the pointer.
+          isDisabled
+            ? "cursor-not-allowed opacity-60"
+            : toClassName(
+                "cursor-pointer",
+                categorical === null
+                  ? "hover:border-border-strong"
+                  : toClassName(
+                      CATEGORICAL_HOVER_BORDER_CLASS[
+                        categorical
+                      ],
+                      CATEGORICAL_HOVER_CLASS[categorical]
+                        .ghost,
+                    ),
+              ),
+          FOCUS_RING_CLASS,
+        )
 
-              {hint === undefined ? null : (
+        const content = (
+          <>
+            {/* The head row. The icon sits BESIDE the name rather
+                than above it, which is how all three apps that had
+                grown this card by hand drew it, and how the owner
+                asked for it back: "I like how Mux-Magic looks today
+                with the icon to the left of the title." */}
+            <span
+              className={toClassName(
+                "flex min-w-0 items-center",
+                HEAD_GAP_CLASS[size],
+              )}
+            >
+              {icon === undefined ? null : (
                 <span
+                  aria-hidden
                   className={toClassName(
-                    "font-normal text-content-muted",
-                    TILE_HINT_TEXT_CLASS[size],
+                    "flex shrink-0",
+                    categorical === null
+                      ? null
+                      : CATEGORICAL_CONTENT_CLASS[
+                          categorical
+                        ],
                   )}
                 >
-                  {hint}
+                  {icon}
                 </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
+              <span className="min-w-0 font-semibold text-content-primary">
+                {tileLabel}
+              </span>
+            </span>
 
-            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}
+            {hint === undefined ? null : (
+              <span
+                className={toClassName(
+                  "font-normal text-content-muted",
+                  TILE_HINT_TEXT_CLASS[size],
+                )}
               >
-                {content}
-              </LinkElement>
-            )
-          }
+                {hint}
+              </span>
+            )}
 
-          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>
-            )
-          }
+            {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 (
-            <button
+            <LinkElement
               className={tileClassName}
-              disabled={isDisabled}
+              href={href}
               key={value}
-              onClick={() => {
-                onChoose?.(value)
-              }}
-              type="button"
+              // `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}
-            </button>
+            </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/PortraitTiles/PortraitAvatar.tsx

@@ -0,0 +1,49 @@
+import type { ReactNode } from "react"
+import { useState } from "react"
+
+/**
+ * The face, and the one piece of this component that holds state.
+ *
+ * A portrait grid is the shape that cannot absorb a broken image:
+ * a missing `<img>` is a torn hole where a person's face was, next
+ * to nine that rendered. `onError` is the only signal a browser
+ * gives for a 404, a wrong content type, or a file the user's
+ * network stripped — so the fallback the caller already supplied for
+ * "no picture" covers "no picture *today*" as well.
+ *
+ * Its own component because the state is per portrait. Hoisting it
+ * to a `Record<string, boolean>` in the set would re-render every
+ * tile whenever any one image failed.
+ */
+export const PortraitAvatar = ({
+  className,
+  imageSrc,
+  initials,
+}: {
+  className: string
+  imageSrc: string | undefined
+  initials: ReactNode
+}): ReactNode => {
+  const [isImageBroken, setIsImageBroken] = useState(false)
+
+  if (imageSrc === undefined || isImageBroken) {
+    return (
+      <span aria-hidden className={className}>
+        {initials}
+      </span>
+    )
+  }
+
+  return (
+    <img
+      // The name is beside it, inside the same tile, so an alt here
+      // is the name announced twice.
+      alt=""
+      className={className}
+      onError={() => {
+        setIsImageBroken(true)
+      }}
+      src={imageSrc}
+    />
+  )
+}

package/src/PortraitTiles/PortraitTiles.mdx

@@ -0,0 +1,153 @@
+import { Canvas, Controls, Meta } from "@storybook/addon-docs/blocks";
+
+import * as PortraitTilesStories from "./PortraitTiles.stories";
+
+<Meta of={PortraitTilesStories} />
+
+# PortraitTiles
+
+A set of **people** — or of anything else picked by its face — drawn as round pictures with a
+name and one big number.
+
+points-market's "Who's shopping?" is the shape this is taken from. It had been hand-rolled
+there since the app was built, and it is the third tile shape the fleet grew on its own,
+after mux-magic's and Gallery Downloader's "Pick a tool" cards.
+
+<Canvas of={PortraitTilesStories.Default} />
+
+## Props
+
+<Controls />
+
+## Why this is not an `ActionTiles` variant
+
+The two answer different questions.
+
+- [`ActionTiles`](/docs/components-actions-actiontiles--docs) asks **what do you want to
+  do** — a name, a line of help, an icon that illustrates a verb.
+- This asks **who is this** — a face, and one number that decides it. There is no
+  description, because a person is not explained.
+
+Collapsing them would mean one component whose `icon` is sometimes a 20px glyph beside the
+title and sometimes a 144px circle above it, with `hint` meaning "what this does" in one mode
+and "points" in the other. That is two components wearing one name.
+
+What they **do** share is the box: `tileStyles.ts` holds the border, the radius, the surface
+and the `auto-fill` grid, and both read it. A page carrying both does not show two different
+cards.
+
+## It scales, and the scaling is the point
+
+Two axes carry it, and neither is a pixel count in an app.
+
+**The container.** `layout="auto"` is a row while the set is narrow and a column once it has
+room, off a `cq-sm` (24rem) query on the set itself. Nothing reads the viewport, so a picker
+in a 320px sidebar on a 2560px monitor gets the row form — which is right, and which a media
+query would have got wrong.
+
+**The density.** Every length is a token, so `data-density="kiosk"` grows the type ramp
+underneath it: `text-2xl` is 30px at `comfortable` and 38px at `kiosk`. points-market runs
+`kiosk` today, and that is where its big numbers come from.
+
+<Canvas of={PortraitTilesStories.Responsive} />
+
+The container and the element querying it **cannot be the same box** — a container query
+matches descendants only. The set renders a wrapper for that reason, the same arrangement
+`EmptyState` uses, and `className` stays on the outer element where a consumer expects it.
+
+<Canvas of={PortraitTilesStories.AllVariants} />
+
+## The colour is the person's, not the position's
+
+A portrait takes the next hue from the ten-wide
+[categorical palette](/docs/foundations-colour--docs) when it names none, which costs a call
+site nothing and is the right default for a list assembled on the fly.
+
+It is the **wrong** default for a household. Add a fifth member and the first four change
+colour — and their colour was the thing the picker was being read by, faster than the names
+were. Any set whose subjects persist should store a `categorical` per subject and pass it,
+the same call Docket makes for a project.
+
+`categorical` and not `intent`: an intent is a claim the design system makes — `danger` says
+what happens if you press the thing — and a person is not a warning.
+
+<Canvas of={PortraitTilesStories.NamedHues} />
+
+### When the colour is not ours to choose
+
+Some colours are not a design decision at all. points-market colours each child to match the
+**NFC card they physically tap**, by a settled household decision, so the picker on the wall
+and the card in their hand have to agree. Ten audited hues cannot promise that, and
+re-theming the colour would be re-theming the card.
+
+That is what `color` is for, and it is the same line
+[`Swatch`](/docs/components-data-swatch--docs) draws: a colour that arrived from the world is
+data, not a token. It reaches the paint through custom properties on the tile, because
+Tailwind generates its CSS at build time from source text and a colour out of a database is
+not in the source.
+
+Three things happen to that one colour, and only the first uses it raw.
+
+- The **fill** is the colour, exactly.
+- The **initials** are black or white, whichever the fill can carry — which is why the third
+  portrait below has white letters and the other two have black. Pass six-digit hex:
+  `getReadableTextColour` measures hex and nothing else, and falls back to white on anything
+  it cannot parse rather than throwing inside your render.
+- The **number** is the colour mixed toward the scheme's own text colour, so a pale card
+  colour is still readable on a pale surface — and, in the dark scheme, is pulled the other
+  way instead.
+
+Reach for this arm only when the colour is a **fact about the subject**. A colour that is
+merely a choice is `categorical`, and it gets re-theming and a contrast guarantee for free.
+
+<Canvas of={PortraitTilesStories.DataColours} />
+
+## A picture, and what happens when it 404s
+
+`imageSrc` draws a photo; `initials` draws a letter on the hue's solid fill. A portrait grid
+is the shape that cannot absorb a broken image — a missing `<img>` is a torn hole where a
+face was, next to three that loaded — so a load error falls back to the initials the caller
+already supplied.
+
+The `<img>` is `alt=""` on purpose. The name is beside it inside the same tile, so an alt
+here is the name announced twice.
+
+<Canvas of={PortraitTilesStories.WithPictures} />
+
+## The keyboard is the platform's
+
+`href` makes a portrait a real `<a href>`, routed through the injected `RouterLink` for a
+same-origin destination — so middle-click, ctrl-click, "open in a new tab" and "copy link
+address" come from the element rather than from the paint. Without one it is a `<button>`
+that calls `onChoose`. A set may mix the two.
+
+Tab reaches **each** portrait. There is no roving tabindex, for the same reason `ActionTiles`
+has none: a radio group borrows one tab stop because exactly one of its options is true at a
+time, and nothing here is true.
+
+The group takes a required `label` naming the set — "Who's shopping?" — and `stat` is drawn
+inside the tile with its `hint` so both are part of the accessible name. "1,240" on its own
+tells a screen-reader user nothing.
+
+<Canvas of={PortraitTilesStories.AllStates} />
+
+## The lift, and who does not get it
+
+Hovering raises the portrait and casts a shadow. It is the one piece of motion in this
+library, kept because it is the thing the owner pointed at in points-market when this moved
+in here.
+
+`motion-reduce:hover:translate-y-0` turns the movement off for anyone who has asked the OS
+for less. The shadow and the coloured border stay, so the hover is still legible without it.
+
+<Canvas of={PortraitTilesStories.Interactive} />
+
+## What this deliberately does not do
+
+- **Hold a selection.** Nothing here is checked; the page moved on. A picker that keeps a
+  value is `RadioGroup itemShape="tile"`.
+- **Guarantee contrast on a `color` you supply.** The palette arm is audited in both schemes;
+  the data arm cannot be, because the colour is not ours. The initials are picked to suit the
+  fill and the number is pulled toward readable, and that is the whole of what it can promise.
+- **Crop or focus a face.** `object-fit: cover` centres, and that is all. An app that needs a
+  focal point owns the crop.