@charcuterie/ui 3.34.0 → 4.0.0

package/src/Main/scrollMemory.ts

@@ -1,73 +1,131 @@
 /**
- * What the browser will not remember for you.
+ * What the browser will not remember for you, and the one thing it
+ * would never have got wrong.
  *
- * `Shell` gives `<main>` the page's only vertical scrollport, so
- * the header and the rails stay put while the content moves —
- * that is the whole reason `Shell.test.tsx` asserts "only main
- * scrolls vertically, keeping the rail available".
- *
- * It costs exactly one thing, and this module is it. A browser
- * remembers **the document scroller's** offset per history entry
- * and puts it back on Back. It does that for a cross-document
- * load, and `history.scrollRestoration` is the switch for it. It
- * does **not** do it for an arbitrary element with
- * `overflow-y: auto`, and it does not do it at all for a
- * same-document `pushState` navigation, which is every link press
- * in a single-page app. So a page that scrolls its own `<main>`
- * loses the reader's place on Back, and no browser setting brings
- * it back:
+ * `Shell` gives `<main>` the page's only vertical scrollport, so the
+ * header and the rails stay put while the content moves — that is
+ * what `Shell.test.tsx` asserts. It costs exactly one thing, and
+ * this module is it. A browser remembers **the document scroller's**
+ * offset per history entry and puts it back on Back. It does not do
+ * that for an arbitrary element with `overflow-y: auto`, and it does
+ * not do it at all for a same-document `pushState` navigation, which
+ * is every link press in a single-page app:
  *
  * > *"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?"*
  *
- * The offsets are held **in memory**, not in `sessionStorage`. A
- * history key survives a reload, but the DOM it described does
- * not: the app re-fetches, re-measures and often re-orders, so a
- * pixel offset from before the reload points at a different row.
- * Restoring a stale number is worse than restoring nothing,
- * because it looks deliberate.
+ * ## An entry remembers its PATH as well as its offset
+ *
+ * Not decoration — the second field is what keeps this from being a
+ * worse bug than the one it fixes. A history entry is not a page. A
+ * filter chip, an expanded group, a selected tab: each writes a
+ * search param, and **`setSearchParams` navigates**, so each mints a
+ * history entry the memory has never seen. Treating an unseen entry
+ * as "start at the top" therefore threw the reader to the top of the
+ * list every time they opened a group — which is exactly what
+ * shipped, and what the path comparison exists to prevent.
+ *
+ * So the rule is about the PAGE, not the entry:
+ *
+ *  - **An entry we have seen** → its remembered offset. This is the
+ *    whole feature: Back and Forward land where you left them.
+ *  - **A new entry on the SAME path** → leave the scrollport alone.
+ *    A search param changed; the reader did not go anywhere. This is
+ *    also precisely what the app did before this memory existed, so
+ *    it can never be a regression.
+ *  - **A new entry on a DIFFERENT path** → the top. A page you have
+ *    not seen starts at its beginning, which is what a browser does
+ *    for a document.
+ *
+ * ## The offsets are in memory, never `sessionStorage`
+ *
+ * A history key survives a reload; the DOM it described does not.
+ * The app re-fetches, re-measures and often re-orders, so a pixel
+ * offset from before the reload points at a different row. Restoring
+ * a stale number is worse than restoring nothing, because it looks
+ * deliberate.
  */
 
 /**
  * How many history entries keep an offset. A reader goes back
  * through a handful of screens, never fifty, so this is a ceiling
  * against a long session rather than a working set — the map holds
- * one small number per entry and evicts the least recently
- * written.
+ * one small record per entry and evicts the least recently written.
  */
 const REMEMBERED_ENTRY_LIMIT = 50
 
-const rememberedOffsets = new Map<string, number>()
+export type ScrollEntry = {
+  /** The history entry — react-router's `useLocation().key`. */
+  key: string
+  /** The page it belongs to — `useLocation().pathname`. */
+  path: string
+}
+
+type RememberedEntry = {
+  offset: number
+  path: string
+}
+
+const rememberedEntries = new Map<string, RememberedEntry>()
+
+/**
+ * The entry the scrollport is showing. Module state rather than a
+ * ref, because the question it answers — *did the reader change page
+ * or only a search param?* — is asked by the incoming entry's effect
+ * about the OUTGOING one, and by then the outgoing effect has
+ * already been cleaned up.
+ */
+let currentEntry: ScrollEntry | null = null
 
 export const rememberScrollOffset = (
-  key: string,
+  entry: ScrollEntry,
   offset: number,
 ) => {
-  // Delete before set, so insertion order is least-recent-first
-  // and the eviction below takes the right one. A plain `set` on
-  // an existing key keeps its original position.
-  rememberedOffsets.delete(key)
-  rememberedOffsets.set(key, offset)
+  // Delete before set, so insertion order is least-recent-first and
+  // the eviction below takes the right one. A plain `set` on an
+  // existing key keeps its original position.
+  rememberedEntries.delete(entry.key)
+  rememberedEntries.set(entry.key, {
+    offset,
+    path: entry.path,
+  })
 
-  for (const oldestKey of rememberedOffsets.keys()) {
-    if (rememberedOffsets.size <= REMEMBERED_ENTRY_LIMIT) {
+  for (const oldestKey of rememberedEntries.keys()) {
+    if (rememberedEntries.size <= REMEMBERED_ENTRY_LIMIT) {
       break
     }
 
-    rememberedOffsets.delete(oldestKey)
+    rememberedEntries.delete(oldestKey)
   }
 }
 
 /**
- * `0` for an entry nobody has scrolled, which is also the right
- * answer for an entry nobody has *seen* — a link press lands at
- * the top of the new page.
+ * Where the scrollport should go for this entry, or `null` for
+ * **leave it alone** — which is a third answer rather than a missing
+ * one, and the difference between a search param and a page.
  */
-export const recallScrollOffset = (key: string) =>
-  rememberedOffsets.get(key) ?? 0
+export const resolveScrollOffset = (entry: ScrollEntry) => {
+  const remembered = rememberedEntries.get(entry.key)
+
+  if (remembered) {
+    return remembered.offset
+  }
+
+  const isSamePage =
+    currentEntry !== null &&
+    currentEntry.path === entry.path
+
+  return isSamePage ? null : 0
+}
+
+/** Called by the hook once it owns the scrollport for this entry. */
+export const enterScrollEntry = (entry: ScrollEntry) => {
+  currentEntry = entry
+}
 
 /** Test-only. Module state outlives a mount; a test must not. */
 export const forgetScrollOffsets = () => {
-  rememberedOffsets.clear()
+  rememberedEntries.clear()
+  currentEntry = null
 }

package/src/Main/scrollMemoryContext.ts

@@ -0,0 +1,21 @@
+import { createContext } from "react"
+
+import type { ScrollEntry } from "./scrollMemory.ts"
+
+/**
+ * How the history entry reaches `Main` without `Main` knowing a
+ * router exists.
+ *
+ * `@charcuterie/ui`'s main entry is router-free and stays that way —
+ * `sourceRules.test.ts` asserts it, and the fleet runs five
+ * different routers. So the entry arrives as a plain
+ * `{ key, path }`, and the one component that knows how to read it
+ * from react-router lives in the `./react-router` subpath.
+ *
+ * A context rather than a prop, because the alternative is a prop
+ * every app has to remember on every `Main` it renders. It was a
+ * prop first, exactly once, and three of the four apps that needed
+ * it did not have it.
+ */
+export const ScrollMemoryContext =
+  createContext<ScrollEntry | null>(null)

package/src/Main/useScrollMemory.ts

@@ -1,8 +1,10 @@
 import { useCallback, useLayoutEffect, useRef } from "react"
 
 import {
-  recallScrollOffset,
+  enterScrollEntry,
   rememberScrollOffset,
+  resolveScrollOffset,
+  type ScrollEntry,
 } from "./scrollMemory.ts"
 
 /**
@@ -11,11 +13,11 @@ import {
  *
  * The offset cannot be applied until the scrollport is tall enough
  * to hold it, and on a client-rendered page it is not: the commit
- * that changes the route draws a skeleton, and the rows land a
- * fetch later. So the restore re-applies as the content grows, and
- * gives up after this. A page that takes longer than three seconds
- * to fill has already been read from the top, and moving it then
- * is a worse answer than leaving it where the reader put it.
+ * that changes the route draws a skeleton, and the rows land a fetch
+ * later. So the restore re-applies as the content grows, and gives
+ * up after this. A page that takes longer than three seconds to fill
+ * has already been read from the top, and moving it then is a worse
+ * answer than leaving it where the reader put it.
  */
 const RESTORE_WINDOW_MS = 3000
 
@@ -28,41 +30,42 @@ const READER_INTENT_EVENTS = [
 ] as const
 
 /**
- * Remember where this history entry was scrolled to, and put it
- * back when the reader returns to it.
+ * Remember where this history entry was scrolled to, and put it back
+ * when the reader returns to it.
  *
- * `scrollMemory.ts` says why the browser will not. This is the
- * part that has to survive the two things a real page does:
+ * `scrollMemory.ts` says why the browser will not, and what an entry
+ * that has never been seen should do. This is the part that has to
+ * survive the two things a real page does:
  *
  *  1. **The content arrives late.** An offset applied against a
- *     600px skeleton clamps to `0` and looks like it did nothing.
- *     A `ResizeObserver` on the scrollport and on its content
- *     column re-applies the offset every time either grows, until
- *     the offset lands or the window closes.
- *  2. **The reader scrolls during all that.** Any wheel, touch,
- *     key or pointer press ends the restore immediately. The
- *     alternative is a page that jumps out from under somebody who
- *     has already started reading.
+ *     600px skeleton clamps to `0` and looks like it did nothing. A
+ *     `ResizeObserver` on the scrollport and on its content column
+ *     re-applies the offset every time either grows, until the
+ *     offset lands or the window closes.
+ *  2. **The reader scrolls during all that.** Any wheel, touch, key
+ *     or pointer press ends the restore immediately. The alternative
+ *     is a page that jumps out from under somebody who has already
+ *     started reading.
  *
  * The save is a passive `scroll` listener, suppressed while a
  * restore is in flight. Without that suppression the feature eats
  * itself: writing `scrollTop` on a still-short page clamps to `0`
- * and fires a `scroll` event reading `0`, which would be saved
- * over the very offset being restored.
+ * and fires a `scroll` event reading `0`, which would be saved over
+ * the very offset being restored.
  *
- * @param scrollKey Identifies the history entry — react-router's
- *   `useLocation().key`. `undefined` turns the memory off, which is
- *   what an app with no router gets.
+ * @param entry The history entry and the page it belongs to.
+ *   `null` turns the memory off, which is what an app that renders
+ *   no `ScrollMemoryProvider` gets.
  */
 export const useScrollMemory = (
-  scrollKey: string | undefined,
+  entry: ScrollEntry | null | undefined,
 ) => {
   const elementRef = useRef<HTMLElement | null>(null)
   const isRestoringRef = useRef(false)
 
-  // A ref rather than a query for the `<main>` id: the effect
-  // below runs in the same commit that mounts the node, and only a
-  // ref can say which node that was.
+  // A ref rather than a query for the `<main>` id: the effect below
+  // runs in the same commit that mounts the node, and only a ref can
+  // say which node that was.
   //
   // `unknown` in, narrowed here, so the returned function is both a
   // `RefCallback<HTMLElement>` and something `mergeRefs` accepts —
@@ -73,18 +76,43 @@ export const useScrollMemory = (
       node instanceof HTMLElement ? node : null
   }, [])
 
+  const key = entry?.key
+  const path = entry?.path
+
   useLayoutEffect(() => {
     const element = elementRef.current
 
-    if (!element || scrollKey === undefined) {
+    if (
+      !element ||
+      key === undefined ||
+      path === undefined
+    ) {
       return undefined
     }
 
-    const offset = recallScrollOffset(scrollKey)
-
-    // The arrow defers the read of `applyOffset`, so the three
-    // pieces can be declared in the order they depend on each
-    // other rather than in the order they are used.
+    const currentEntry = { key, path }
+
+    // `null` means leave the scrollport alone: a search param
+    // changed and the reader did not go anywhere. It is read BEFORE
+    // this entry becomes the current one, because the answer depends
+    // on the page the reader is arriving from.
+    const offset = resolveScrollOffset(currentEntry)
+
+    enterScrollEntry(currentEntry)
+
+    // Seed the entry now rather than waiting for a `scroll` event.
+    // A reader who opens a group and then follows a link never
+    // scrolls in between, so without this the entry they came from
+    // is one the memory has never seen — and Back would send them to
+    // the top of a list they were half-way down.
+    rememberScrollOffset(
+      currentEntry,
+      offset ?? element.scrollTop,
+    )
+
+    // The arrow defers the read of `applyOffset`, so the pieces can
+    // be declared in the order they depend on each other rather than
+    // in the order they are used.
     const observer = new ResizeObserver(() => {
       applyOffset()
     })
@@ -93,12 +121,9 @@ export const useScrollMemory = (
       stopRestoring()
     }, RESTORE_WINDOW_MS)
 
-    const stopRestoring = () => {
-      if (!isRestoringRef.current) {
-        return
-      }
+    let isRestoring = offset !== null
 
-      isRestoringRef.current = false
+    const teardown = () => {
       observer.disconnect()
       globalThis.clearTimeout(deadline)
 
@@ -110,8 +135,18 @@ export const useScrollMemory = (
       }
     }
 
+    const stopRestoring = () => {
+      if (!isRestoring) {
+        return
+      }
+
+      isRestoring = false
+      isRestoringRef.current = false
+      teardown()
+    }
+
     const applyOffset = () => {
-      if (!isRestoringRef.current) {
+      if (!isRestoring || offset === null) {
         return
       }
 
@@ -128,10 +163,10 @@ export const useScrollMemory = (
         return
       }
 
-      rememberScrollOffset(scrollKey, element.scrollTop)
+      rememberScrollOffset(currentEntry, element.scrollTop)
     }
 
-    isRestoringRef.current = true
+    isRestoringRef.current = isRestoring
 
     for (const eventName of READER_INTENT_EVENTS) {
       element.addEventListener(eventName, stopRestoring, {
@@ -155,10 +190,15 @@ export const useScrollMemory = (
     applyOffset()
 
     return () => {
-      stopRestoring()
+      // Unconditional, unlike `stopRestoring` — a restore that
+      // already landed still has an observer and four listeners on
+      // an element the next entry is about to use, and a stale
+      // observer that survives its effect applies a stale offset.
+      isRestoring = false
+      teardown()
       element.removeEventListener("scroll", onScroll)
     }
-  }, [scrollKey])
+  }, [key, path])
 
   return setElement
 }

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

@@ -253,6 +253,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,

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>
+  ),
+}