@charcuterie/ui 3.34.0 → 4.1.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/Main/Main.mdx

@@ -148,7 +148,7 @@ region, so the table is announced as a thing rather than as loose content.
 position. Without it, Safari and Firefox scroll to `<main>` and leave the next Tab back up
 in the header — which looks exactly like a skip link that works.
 
-## `scrollKey` — the reader's place, kept
+## The reader's place, kept
 
 <Canvas of={MainStories.ScrollMemory} />
 
@@ -166,17 +166,45 @@ changes it. The owner, on Docket:
 > "If I scroll, click on an item, then go back, it resets me to the top. […] It should
 > remember where the scroll position was previously. Isn't this handled by Chrome already?"
 
-Pass the history entry's key and it is:
+**There is no prop for it.** The history entry arrives on a context, and
+`ReactRouterAdapter` puts it at the app root beside the link seam:
 
 ```tsx
-const location = useLocation()
+import { ReactRouterAdapter } from "@charcuterie/ui/react-router"
 
-<Main scrollKey={location.key}>
-  <Outlet />
-</Main>
+<BrowserRouter>
+  <ReactRouterAdapter>
+    <Routes>…</Routes>
+  </ReactRouterAdapter>
+</BrowserRouter>
 ```
 
-Omit it and nothing is remembered, which is right for a page with no history to remember.
+It was a prop for one release — `scrollKey` — and that release is the argument against a
+prop. One app wired it and the other three carried on losing the reader's place with the
+library sitting right there supporting it. Render no provider and nothing is remembered,
+which is right for an app with no history to remember.
+
+An app on another router wires `ScrollMemoryProvider` itself, with any value that identifies
+the history **entry** rather than the URL:
+
+```tsx
+<ScrollMemoryProvider entry={{ key: historyKey, path: location }}>
+  <App />
+</ScrollMemoryProvider>
+```
+
+### A filter is not a navigation
+
+A filter chip, an expanded group and a selected tab each write a search param, and
+`setSearchParams` **navigates** — so each one mints a history entry the memory has never
+seen. Read as "unseen ⇒ start at the top", pressing a filter throws the reader to the top of
+the list they were reading. That shipped, and it is why an entry remembers its **path**:
+
+| The entry | What happens |
+| --- | --- |
+| One we have seen | Its remembered offset. Back and Forward land where you left them. |
+| New, **same** path | Nothing. The scrollport is left exactly where the reader put it. |
+| New, **different** path | The top, which is what a browser does for a new document. |
 
 ### It has to wait for the content