@charcuterie/ui 3.34.0 → 4.0.0

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

@@ -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`,