@charcuterie/ui 3.34.0 → 4.1.0

package/src/RadioGroup/RadioGroup.stories.tsx

@@ -139,6 +139,45 @@ export const Tiles: Story = {
   },
 }
 
+/**
+ * The tile at all three sizes.
+ *
+ * `AllVariants` above covers the three heights of a **row**, and
+ * every tile story took the default `md` — so the largest tile had
+ * no snapshot at all, and `TILE_PADDING_CLASS.lg` could be changed
+ * without a single pixel moving in the report. It was, on
+ * 2026-09-02, when `lg` grew to a landing-page tile's padding.
+ *
+ * The padding is shared with `ActionTiles` through `tileStyles.ts`,
+ * which is the promise this board is here to photograph.
+ */
+export const TileSizes: Story = {
+  args: {
+    items: IMPORT_ITEMS,
+    itemShape: "tile",
+    label: "On import",
+  },
+  render: (controlProps) => (
+    <StorySection title="One box at three sizes, and the same box ActionTiles reads from.">
+      <StoryGrid columns={3}>
+        {(["sm", "md", "lg"] as const).map((size) => (
+          <StoryCell
+            align="stretch"
+            key={size}
+            label={size}
+          >
+            <RadioGroup
+              {...controlProps}
+              label={`On import at ${size}`}
+              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

package/src/RouterLink/RouterLink.mdx

@@ -27,38 +27,68 @@ point — so an app that never imports this path never resolves it.
 yarn add @charcuterie/ui react-router
 ```
 
+**One component at the root**, and it must sit **inside** the router:
+
 ```tsx
 // src/main.tsx
-import { RouterLinkProvider } from "@charcuterie/ui"
-import { ReactRouterLink } from "@charcuterie/ui/react-router"
+import { ReactRouterAdapter } from "@charcuterie/ui/react-router"
 import { StrictMode } from "react"
 import { createRoot } from "react-dom/client"
-import {
-  createBrowserRouter,
-  RouterProvider,
-} from "react-router"
+import { BrowserRouter } from "react-router"
 
-import { routes } from "./routes.tsx"
-
-const router = createBrowserRouter(routes)
+import { App } from "./App.tsx"
 
 createRoot(document.getElementById("root")).render(
   <StrictMode>
-    <RouterLinkProvider link={ReactRouterLink}>
-      <RouterProvider router={router} />
-    </RouterLinkProvider>
+    <BrowserRouter>
+      <ReactRouterAdapter>
+        <App />
+      </ReactRouterAdapter>
+    </BrowserRouter>
   </StrictMode>,
 )
 ```
 
-`RouterLinkProvider` goes **outside** `RouterProvider` here on purpose: it is plain React
-context and needs no router of its own, and putting it outermost means a link rendered by a
-route element and a link rendered by an app-level chrome component both see it.
+Inside, because it reads `useLocation()`. Above the routes, because what it provides belongs
+to the whole app — a link rendered by a route element and a link rendered by app-level
+chrome both see it.
 
 Already on `react-router-dom` v7, as bambuddy is? Nothing changes. `react-router-dom` v7 is
 a re-export shim over `react-router`, and the adapter imports `Link` from the latter, so one
 import covers both installs.
 
+### Two seams, and why they arrive together
+
+The adapter wires the **link seam** and the **scroll memory**, because a per-seam opt-in is
+what the fleet has already failed at. `Main`'s scroll memory shipped as a `scrollKey` prop;
+one app wired it, and the other three carried on losing the reader's place with the library
+sitting right there supporting it. One name at the root means a seam added later arrives in
+every app that already renders this, on its next release.
+
+`RouterLinkProvider`, `ReactRouterLink` and `ScrollMemoryProvider` all stay exported for an
+app that wants one half.
+
+### On `createBrowserRouter`
+
+`RouterProvider` takes no children, so the adapter goes in the root route's element:
+
+```tsx
+const routes = [
+  {
+    element: (
+      <ReactRouterAdapter>
+        <Outlet />
+      </ReactRouterAdapter>
+    ),
+    children: appRoutes,
+  },
+]
+```
+
+An app that wants only the link seam can keep `RouterLinkProvider` outside `RouterProvider`
+instead, as it did before this adapter existed — that provider is plain React context and
+needs no router of its own.
+
 That is the whole integration. Every link in the app is now soft:
 
 ```tsx
@@ -166,6 +196,10 @@ asserts `getByRole("link", { name: … })` and its `href` with no router in the
 With a provider, inject a stand-in that marks what it was handed — `TextLink.stories.tsx`'s
 `Routed` story is exactly that, and `TextLink.test.tsx` reads it.
 
+The scroll memory is the same: no provider, no memory. A test that wants it renders
+`ScrollMemoryProvider` with a `{ key, path }` it controls, rather than a router — which is
+what `Main.stories.tsx` does.
+
 ## API
 
 | Export | From | What |
@@ -175,4 +209,7 @@ With a provider, inject a stand-in that marks what it was handed — `TextLink.s
 | `RouterLinkComponent` / `RouterLinkProps` | `@charcuterie/ui` | The contract: `ComponentPropsWithRef<"a">` with `href` required. |
 | `AnchorLink` | `@charcuterie/ui` | The plain `<a href>` default. |
 | `getIsRoutedHref(href)` | `@charcuterie/ui` | The destination test above. |
-| `ReactRouterLink` | `@charcuterie/ui/react-router` | The one shipped adapter. Optional peer. |
+| `ScrollMemoryProvider` | `@charcuterie/ui` | The scroll seam. `entry` is `{ key, path }` for the current history entry. |
+| `ScrollEntry` | `@charcuterie/ui` | That pair's type. |
+| `ReactRouterAdapter` | `@charcuterie/ui/react-router` | Both seams, wired. The one thing an app renders. Optional peer. |
+| `ReactRouterLink` | `@charcuterie/ui/react-router` | The link adapter alone. Optional peer. |

package/src/categoricalStyles.ts

@@ -242,3 +242,60 @@ export const CATEGORICAL_CONTENT_CLASS: Record<
   9: "text-categorical-9-content",
   10: "text-categorical-10-content",
 }
+
+/**
+ * The hover BORDER, which `CATEGORICAL_HOVER_CLASS` deliberately
+ * does not carry.
+ *
+ * That map answers "what does this surface do under the pointer",
+ * and a `Badge` has no border state to change. A tile does: it is a
+ * bordered card, and the whole point of colouring one is that the
+ * box reacts in its own hue rather than in the neutral
+ * `border-strong` every other box uses. Kept separate rather than
+ * added as a fifth appearance key, because an appearance is a claim
+ * about the fill and this is not one.
+ *
+ * Written out in full for the reason this file opens with.
+ */
+export const CATEGORICAL_HOVER_BORDER_CLASS: Record<
+  CategoricalIndex,
+  string
+> = {
+  1: "hover:border-categorical-1-border",
+  2: "hover:border-categorical-2-border",
+  3: "hover:border-categorical-3-border",
+  4: "hover:border-categorical-4-border",
+  5: "hover:border-categorical-5-border",
+  6: "hover:border-categorical-6-border",
+  7: "hover:border-categorical-7-border",
+  8: "hover:border-categorical-8-border",
+  9: "hover:border-categorical-9-border",
+  10: "hover:border-categorical-10-border",
+}
+
+/**
+ * A halo the width of a ring, in the hue's SURFACE.
+ *
+ * `surface` and not `border`: this sits directly against the solid
+ * fill it surrounds, so it is a soft step out of the colour rather
+ * than a second line around it. `PortraitTiles` draws it around a
+ * face, where a hard outline reads as a frame and this reads as
+ * light.
+ *
+ * Written out in full for the reason this file opens with.
+ */
+export const CATEGORICAL_RING_CLASS: Record<
+  CategoricalIndex,
+  string
+> = {
+  1: "ring-categorical-1-surface",
+  2: "ring-categorical-2-surface",
+  3: "ring-categorical-3-surface",
+  4: "ring-categorical-4-surface",
+  5: "ring-categorical-5-surface",
+  6: "ring-categorical-6-surface",
+  7: "ring-categorical-7-surface",
+  8: "ring-categorical-8-surface",
+  9: "ring-categorical-9-surface",
+  10: "ring-categorical-10-surface",
+}

package/src/index.ts

@@ -39,6 +39,7 @@ export type {
 export { Accordion } from "./Accordion/Accordion.tsx"
 export type {
   ActionTileItem,
+  ActionTilesAccent,
   ActionTilesProps,
 } from "./ActionTiles/ActionTiles.tsx"
 export { ActionTiles } from "./ActionTiles/ActionTiles.tsx"
@@ -129,7 +130,9 @@ export { copyText } from "./CopyButton/copyText.ts"
 export {
   CATEGORICAL_APPEARANCE_CLASS,
   CATEGORICAL_CONTENT_CLASS,
+  CATEGORICAL_HOVER_BORDER_CLASS,
   CATEGORICAL_HOVER_CLASS,
+  CATEGORICAL_RING_CLASS,
   CATEGORICAL_SOLID_FILL_CLASS,
 } from "./categoricalStyles.ts"
 export type { BadgeSize } from "./controlStyles.ts"
@@ -253,6 +256,9 @@ export type {
 export { LogViewer } from "./LogViewer/LogViewer.tsx"
 export type { MainProps } from "./Main/Main.tsx"
 export { Main } from "./Main/Main.tsx"
+export type { ScrollMemoryProviderProps } from "./Main/ScrollMemoryProvider.tsx"
+export { ScrollMemoryProvider } from "./Main/ScrollMemoryProvider.tsx"
+export type { ScrollEntry } from "./Main/scrollMemory.ts"
 export type {
   MarkdownEditorProps,
   MarkdownImageUpload,
@@ -322,6 +328,12 @@ export type {
 export { Picker } from "./Picker/Picker.tsx"
 export type { PopoverProps } from "./Popover/Popover.tsx"
 export { Popover } from "./Popover/Popover.tsx"
+export type {
+  PortraitTileItem,
+  PortraitTilesLayout,
+  PortraitTilesProps,
+} from "./PortraitTiles/PortraitTiles.tsx"
+export { PortraitTiles } from "./PortraitTiles/PortraitTiles.tsx"
 export type {
   ProgressBarProps,
   ProgressBarSize,

package/src/reactRouter/ReactRouterAdapter.stories.tsx

@@ -0,0 +1,120 @@
+import type { Meta, StoryObj } from "@storybook/react"
+import {
+  MemoryRouter,
+  Route,
+  Routes,
+  useNavigate,
+} from "react-router"
+
+import { Button } from "../Button/Button.tsx"
+import { Card } from "../Card/Card.tsx"
+import { Header } from "../Header/Header.tsx"
+import { Main } from "../Main/Main.tsx"
+import { Shell } from "../Shell/Shell.tsx"
+import { TextLink } from "../TextLink/TextLink.tsx"
+import { ReactRouterAdapter } from "./ReactRouterAdapter.tsx"
+
+/**
+ * The one component an app on react-router renders at its root.
+ *
+ * `Main.stories.tsx` proves the scroll memory against a hand-rolled
+ * history stack, which is the right subject for the mechanism. This
+ * one proves the **wiring**: a real router, a real `useLocation()`,
+ * and both seams arriving from one component — the piece that ships
+ * broken silently, because a page whose links still work and whose
+ * list still scrolls looks fine.
+ *
+ * `MemoryRouter` rather than `BrowserRouter`, so the story does not
+ * write to the Storybook page's own history.
+ */
+const meta = {
+  component: ReactRouterAdapter,
+  parameters: {
+    layout: "fullscreen",
+  },
+  title: "Components/Layout/ReactRouterAdapter",
+} satisfies Meta<typeof ReactRouterAdapter>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+const EPISODE_TITLES = Array.from(
+  { length: 40 },
+  (_unused, index) => `Episode ${index + 1}`,
+)
+
+const BackControl = () => {
+  const navigate = useNavigate()
+
+  return (
+    <Button
+      appearance="outline"
+      onClick={() => {
+        void navigate(-1)
+      }}
+      size="sm"
+    >
+      Back
+    </Button>
+  )
+}
+
+const EpisodeList = () => (
+  <Main>
+    <div className="flex flex-col gap-3">
+      {EPISODE_TITLES.map((title) => (
+        <Card heading={title} key={title} padding="sm">
+          <TextLink href={`/library/${title}`}>
+            Open {title}
+          </TextLink>
+        </Card>
+      ))}
+    </div>
+  </Main>
+)
+
+const EpisodePage = () => (
+  <Main>
+    <Card heading="Episode">
+      <p className="text-content-secondary text-sm">
+        Short enough that the scrollport collapses behind
+        it. Press Back.
+      </p>
+    </Card>
+  </Main>
+)
+
+/**
+ * Scroll the list, press a link, then press Back.
+ *
+ * Nothing on this page is told about scrolling or about the router.
+ * `TextLink` becomes a soft navigation and `Main` keeps the
+ * reader's place because `ReactRouterAdapter` is above them both.
+ */
+export const Default: Story = {
+  render: () => (
+    <MemoryRouter initialEntries={["/library"]}>
+      <ReactRouterAdapter>
+        <Shell>
+          <Header
+            actions={<BackControl />}
+            heading="Library"
+          />
+
+          <Routes>
+            <Route
+              element={<EpisodeList />}
+              path="/library"
+            />
+
+            <Route
+              element={<EpisodePage />}
+              path="/library/:episode"
+            />
+          </Routes>
+        </Shell>
+      </ReactRouterAdapter>
+    </MemoryRouter>
+  ),
+}

package/src/reactRouter/ReactRouterAdapter.test.tsx

@@ -0,0 +1,92 @@
+import { composeStories } from "@storybook/react"
+import { expect, userEvent, waitFor } from "storybook/test"
+import { afterEach, test } from "vitest"
+
+import { forgetScrollOffsets } from "../Main/scrollMemory.ts"
+import { mountStory } from "../mountStory.testHelpers.ts"
+import { expectAgentDrivable } from "../testing/index.ts"
+import {
+  DESKTOP,
+  setViewport,
+} from "../viewport.testHelpers.ts"
+import * as stories from "./ReactRouterAdapter.stories.tsx"
+
+const { Default } = composeStories(stories)
+
+// The offsets are module state, so they outlive a mount. A test
+// must not.
+afterEach(() => {
+  forgetScrollOffsets()
+})
+
+/**
+ * The wiring, against a real router.
+ *
+ * `Main.test.tsx` proves the scroll mechanism against a hand-rolled
+ * history stack — the right subject for a `ResizeObserver` and a
+ * clamped offset. What it cannot prove is that the entry reaches
+ * `Main` at all when the value comes from `useLocation()` rather
+ * than from a story's own `useState`. That is the seam every app
+ * now depends on, and it is the kind that fails quietly: the links
+ * still navigate and the list still scrolls.
+ */
+test("an app renders one component and gets both seams", async () => {
+  await setViewport(DESKTOP)
+
+  const { canvas } = await mountStory(Default)
+
+  const main = canvas.getByRole("main")
+
+  // The link seam: react-router's `<Link>` renders an `<a href>`,
+  // so this is also what an unwired app looks like — the assertion
+  // that separates them is the absence of a page load below.
+  const link = expectAgentDrivable(canvas, {
+    name: "Open Episode 12",
+    role: "link",
+  })
+
+  await expect(link).toHaveAttribute(
+    "href",
+    "/library/Episode 12",
+  )
+
+  main.scrollTop = 900
+
+  await waitFor(async () => {
+    await expect(main.scrollTop).toBe(900)
+  })
+
+  await new Promise((resolve) => {
+    globalThis.requestAnimationFrame(() => {
+      globalThis.requestAnimationFrame(resolve)
+    })
+  })
+
+  await userEvent.click(link)
+
+  // A soft navigation: the route changed inside the same document.
+  // A plain `<a>` would have left the story mounted and unchanged.
+  //
+  // `waitFor`, because the route commit is a state update and the
+  // click resolves before it. It passed locally and failed on CI
+  // for exactly that reason.
+  await waitFor(async () => {
+    await expect(
+      canvas.getByRole("heading", { name: "Episode" }),
+    ).toBeVisible()
+  })
+
+  await userEvent.click(
+    expectAgentDrivable(canvas, {
+      name: "Back",
+      role: "button",
+    }),
+  )
+
+  // The scroll seam, from the same one component.
+  await waitFor(async () => {
+    await expect(canvas.getByRole("main").scrollTop).toBe(
+      900,
+    )
+  })
+})

package/src/reactRouter/ReactRouterAdapter.tsx

@@ -0,0 +1,66 @@
+import type { ReactNode } from "react"
+import { useLocation } from "react-router"
+
+import { ScrollMemoryProvider } from "../Main/ScrollMemoryProvider.tsx"
+import { RouterLinkProvider } from "../RouterLink/RouterLinkProvider.tsx"
+import { ReactRouterLink } from "./ReactRouterLink.tsx"
+
+export type ReactRouterAdapterProps = {
+  children?: ReactNode
+}
+
+/**
+ * Every seam this library has, wired to react-router, in one
+ * component at the app root.
+ *
+ * ```tsx
+ * <BrowserRouter>
+ *   <ReactRouterAdapter>
+ *     <Routes>…</Routes>
+ *   </ReactRouterAdapter>
+ * </BrowserRouter>
+ * ```
+ *
+ * It must sit **inside** the router, because it reads
+ * `useLocation()`, and **outside** the routes, because what it
+ * provides belongs to the whole app.
+ *
+ * ## Why one component and not two providers
+ *
+ * There are two seams today — the link seam and the scroll memory —
+ * and the fleet proved that a per-app opt-in does not reach the
+ * fleet. `Main`'s scroll memory shipped as a `scrollKey` prop, one
+ * app wired it, and the other three kept losing the reader's place
+ * with the library sitting right there supporting it. A seam an app
+ * has to know about is a seam most apps will not have.
+ *
+ * So the root wiring is one name to remember, and a seam added later
+ * arrives in every app that already renders this on its next
+ * release. `RouterLinkProvider`, `ReactRouterLink` and
+ * `ScrollMemoryProvider` all stay exported for an app that wants one
+ * half, or that renders its own root for another reason.
+ *
+ * ## What it does NOT do
+ *
+ * It does not render a router, and it takes no route table. This
+ * library has no opinion about either, and an app that wants
+ * `createBrowserRouter` should keep it.
+ */
+export const ReactRouterAdapter = ({
+  children,
+}: ReactRouterAdapterProps): ReactNode => {
+  const location = useLocation()
+
+  return (
+    <RouterLinkProvider link={ReactRouterLink}>
+      <ScrollMemoryProvider
+        entry={{
+          key: location.key,
+          path: location.pathname,
+        }}
+      >
+        {children}
+      </ScrollMemoryProvider>
+    </RouterLinkProvider>
+  )
+}

package/src/reactRouter/index.ts

@@ -1,6 +1,6 @@
 /**
- * `@charcuterie/ui/react-router` — the react-router adapter for the
- * link seam.
+ * `@charcuterie/ui/react-router` — the react-router adapter for this
+ * library's seams.
  *
  * **A subpath export with an optional peer dependency**, and both
  * halves of that matter. The base package must stay router-free: the
@@ -13,17 +13,23 @@
  * asserts exactly that — the main entry is measured for what it
  * reaches, so this cannot leak into it by accident.
  *
- * The wiring is one provider at the app root; `Guides/Routing` in
+ * The wiring is one component at the app root; `Guides/Routing` in
  * Storybook is the copy-pasteable version.
  *
  * ```tsx
- * import { RouterLinkProvider } from "@charcuterie/ui"
- * import { ReactRouterLink } from "@charcuterie/ui/react-router"
+ * import { ReactRouterAdapter } from "@charcuterie/ui/react-router"
  *
- * <RouterLinkProvider link={ReactRouterLink}>
- *   <RouterProvider router={router} />
- * </RouterLinkProvider>
+ * <BrowserRouter>
+ *   <ReactRouterAdapter>
+ *     <Routes>…</Routes>
+ *   </ReactRouterAdapter>
+ * </BrowserRouter>
  * ```
+ *
+ * `ReactRouterLink` stays exported for an app that wires
+ * `RouterLinkProvider` itself.
  */
 
+export type { ReactRouterAdapterProps } from "./ReactRouterAdapter.tsx"
+export { ReactRouterAdapter } from "./ReactRouterAdapter.tsx"
 export { ReactRouterLink } from "./ReactRouterLink.tsx"

package/src/sourceRules.test.ts

@@ -236,6 +236,14 @@ test("a container-query component is never storied in a shrink-to-fit cell", ()
     "Main",
     "MarkdownEditor",
     "MediaTile",
+    // `PortraitTiles` declares its container on the SET rather than
+    // on a tile, and that is the whole design: the question is not
+    // "how wide is this one face" but "does this picker have room to
+    // stack". A phone shows one full-width column of rows; a wall
+    // display shows a row of tall columns. Querying a tile would
+    // answer neither, because a track is about the same width in
+    // both.
+    "PortraitTiles",
     // `Stepper`'s container is the one that decides whether a
     // `horizontal` sequence is actually horizontal. Below `--cq-md`
     // it falls back to the vertical column, because four steps side
@@ -375,8 +383,10 @@ test("the barrel is the only place components are re-exported", async () => {
   // and `ButtonLink`, both a real `<a href>`, differing in paint
   // rather than semantics: +2 -> 38, on top of `AdaptiveGrid`'s 36.
   // `AnchorLink`,
-  // `RouterLinkProvider`, and `ReactRouterLink` are the seam rather
-  // than components anybody stories, and live in `RouterLink/` and
+  // `RouterLinkProvider`, `ReactRouterLink`, `ScrollMemoryProvider`
+  // and `ReactRouterAdapter` are the router seam rather
+  // than components anybody stories, and live in `RouterLink/`,
+  // `Main/` and
   // `reactRouter/` — outside this count by the `<Name>/<Name>.tsx`
   // rule, exactly as `Overlay/`'s parts are.
   // The unified app shell adds four: `Shell`, `Header`, `Rail`,
@@ -569,7 +579,13 @@ test("the barrel is the only place components are re-exported", async () => {
   // `isRange` is right there and wrong here for a reason that is
   // written down — a second text field is still a text field, while a
   // second thumb cannot share one `aria-valuenow`.
-  expect(componentNames.length).toBe(64)
+  //
+  // `PortraitTiles` is +1 -> 65. It is the points-market kid picker:
+  // a face, a name and one number, which is a different question
+  // from `ActionTiles`' "what do you want to do" and would have
+  // meant one component whose icon is sometimes a 20px glyph beside
+  // a title and sometimes a 144px circle above it.
+  expect(componentNames.length).toBe(65)
 
   for (const name of componentNames) {
     expect(barrel).toContain(`export { ${name} }`)

package/src/tileStyles.ts

@@ -38,7 +38,36 @@ export const TILE_PADDING_CLASS: Record<
 > = {
   sm: "px-3 py-2.5",
   md: "px-3.5 py-3",
-  lg: "px-4 py-3.5",
+  // `lg` is the landing-page tile — mux-magic's "Pick a tool",
+  // Gallery Downloader's two cards — where the tile is the only
+  // thing on the page and reads as a panel rather than as a row.
+  // It was `px-4 py-3.5`, which is a control's padding wearing a
+  // card's name, and the owner called the result "very boring"
+  // when it shipped in QueuePilot.
+  lg: "px-6 py-5",
+}
+
+/**
+ * What a tile with an accent edge adds to its LEADING padding.
+ *
+ * The bar is drawn by `Card`'s accent-edge pseudo-element, which is
+ * an overlay rather than a border — so it takes no space in the box
+ * model and lands on top of the text unless the tile makes room for
+ * it. `Card` has the same arrangement and the same answer.
+ *
+ * A separate map rather than a second full padding scale, because
+ * only the leading side changes and the shared box is the promise
+ * the 2026-09-01 record made. It is applied ONLY when an edge is
+ * drawn: a radio tile has no bar, and giving it this padding would
+ * be dead space on the side its own control sits on.
+ */
+export const TILE_ACCENT_EDGE_PADDING_CLASS: Record<
+  ControlSize,
+  string
+> = {
+  sm: "ps-4",
+  md: "ps-4.5",
+  lg: "ps-7",
 }
 
 /**