@charcuterie/ui 3.33.0 → 4.0.0

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/sliderStyles.ts

@@ -0,0 +1,69 @@
+/**
+ * The paint `Slider` and `RangeSlider` share.
+ *
+ * The two are separate components because their **focus models** are
+ * different — one `role="slider"` on the track against two of them in
+ * a `role="group"`, one tab stop against two
+ * ([decision](../../../docs/decisions/2026-09-01-a-two-thumb-range-is-its-own-component-and-shares-the-bar.md)).
+ * What is identical is the bar: a sunken rounded track, an intent
+ * fill inside it, and a round thumb pulled back by half its own
+ * width.
+ *
+ * Held here rather than copied for the reason `tileStyles.ts` exists:
+ * "the two look the same" spelled as two class strings is a promise
+ * that survives exactly one edit. `RangeSlider.test.tsx` compares the
+ * two thumbs as **computed** styles, so a class-name refactor cannot
+ * quietly break it either.
+ *
+ * No focus ring here. It is the one part of the bar the two do not
+ * share — `Slider` rings the track, because the track is the widget;
+ * `RangeSlider` rings each thumb, because each thumb is.
+ */
+
+export type SliderSize = "lg" | "md" | "sm"
+
+/** The bar itself. A `sm` bar is 2px; that is not a hit target. */
+export const SLIDER_TRACK_SIZE_CLASS: Record<
+  SliderSize,
+  string
+> = {
+  sm: "h-1",
+  md: "h-2",
+  lg: "h-3",
+}
+
+export const SLIDER_THUMB_SIZE_CLASS: Record<
+  SliderSize,
+  string
+> = {
+  sm: "size-3",
+  md: "size-4",
+  lg: "size-5",
+}
+
+/** Half of each `SLIDER_THUMB_SIZE_CLASS`, as the inline-start pull-back. */
+export const SLIDER_THUMB_OFFSET: Record<
+  SliderSize,
+  string
+> = {
+  sm: "-0.375rem",
+  md: "-0.5rem",
+  lg: "-0.625rem",
+}
+
+/**
+ * The row the bar sits in, which is taller than the bar: a 2px track
+ * is not a pointer target, and a finger is 44px. The height comes
+ * from the shared control-size system, so `[data-density]` decides
+ * it — never `MIN_TOUCH_TARGET_CLASS`, which would make this control
+ * taller than the ones beside it at desktop density
+ * ([decision](../../../docs/decisions/2026-08-05-controls-share-one-height-no-per-component-touch-floor.md)).
+ */
+export const SLIDER_ROW_CLASS =
+  "relative flex w-full touch-none cursor-pointer items-center rounded-full min-h-(--control-height-sm)"
+
+export const SLIDER_TRACK_CLASS =
+  "w-full overflow-hidden rounded-full bg-surface-sunken"
+
+export const SLIDER_THUMB_CLASS =
+  "absolute rounded-full border-2 border-surface-raised shadow-sm"

package/src/sourceRules.test.ts

@@ -375,8 +375,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`,
@@ -545,7 +547,31 @@ test("the barrel is the only place components are re-exported", async () => {
   // what it deliberately does not cover — a tile that navigates is
   // not a radio, and giving one `aria-checked` would be worse than
   // the paint it replaced.
-  expect(componentNames.length).toBe(62)
+  //
+  // `TimecodeInput` — a typed media position, with an `isRange` mode
+  // for a section of a file — is +1 -> 63. `timecode.ts` is its
+  // member and stays out of this count by the `<Name>/<Name>.tsx`
+  // rule, while still being exported from the barrel: the fleet
+  // spells the *printing* half five times over (queuepilot twice,
+  // castkit, mux-magic twice) and a read-only surface needs the
+  // formatter without the field.
+  //
+  // `RangeSlider` is +1 -> 64. `Slider`'s own record said a two-thumb
+  // range is *"a different widget with its own focus model"*, and the
+  // focus model is exactly what makes it a component rather than an
+  // `isRange` mode: one `role="slider"` on the track becomes two of
+  // them on the thumbs inside a `role="group"`, and one tab stop
+  // becomes two. So this shares the ARITHMETIC (`sliderValue.ts`,
+  // called rather than copied) and the BAR (`sliderStyles.ts`, the
+  // same extraction `tileStyles.ts` is), and nothing else.
+  // `rangeSliderValue.ts` is its member and stays out of this count
+  // by the `<Name>/<Name>.tsx` rule. It lands beside `TimecodeInput`
+  // rather than instead of it: the two halves of QueuePilot's clip
+  // editor are a typed field and a dragged bar over one value, and
+  // `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)
 
   for (const name of componentNames) {
     expect(barrel).toContain(`export { ${name} }`)