@charcuterie/ui 3.29.0 → 3.30.0

package/src/Main/Main.stories.tsx

@@ -1,11 +1,14 @@
 import type { Meta, StoryObj } from "@storybook/react"
+import { useEffect, useState } from "react"
 
 import { toStoryChoice } from "../argTypes.storyHelpers.ts"
+import { Button } from "../Button/Button.tsx"
 import { Card } from "../Card/Card.tsx"
 import { Header } from "../Header/Header.tsx"
 import { Rail } from "../Rail/Rail.tsx"
 import { toMaxInlineSize } from "../Shell/contentWidth.ts"
 import { Shell } from "../Shell/Shell.tsx"
+import { Spinner } from "../Spinner/Spinner.tsx"
 import {
   HeaderSchemeToggle,
   OverflowingContent,
@@ -162,3 +165,152 @@ export const Interactive: Story = {
     </Shell>
   ),
 }
+
+const EPISODE_TITLES = Array.from(
+  { length: 40 },
+  (_unused, index) => `Episode ${index + 1}`,
+)
+
+type HistoryEntry = {
+  episode: string | null
+  key: string
+}
+
+/**
+ * A history stack, small enough to read and honest about the one
+ * thing that matters: **Back returns to the entry it left, with
+ * the key it had.** That key is what the offset is filed under,
+ * and reusing it is the whole mechanism.
+ *
+ * `contentDelayMs` is the second half of the problem. A real list
+ * is fetched, so the commit that changes the route draws an empty
+ * scrollport and the rows land later — an offset applied against
+ * that clamps to `0`. Set it and the restore has to wait for the
+ * content, which is the case the `ResizeObserver` in
+ * `useScrollMemory` exists for.
+ */
+const ScrollMemoryDemo = ({
+  contentDelayMs,
+}: {
+  contentDelayMs: number
+}) => {
+  const [entries, setEntries] = useState<HistoryEntry[]>([
+    { episode: null, key: "entry-1" },
+  ])
+  const [entryIndex, setEntryIndex] = useState(0)
+  const [isContentReady, setIsContentReady] = useState(
+    contentDelayMs === 0,
+  )
+
+  const entry = entries[entryIndex]
+
+  useEffect(() => {
+    if (contentDelayMs === 0) {
+      return undefined
+    }
+
+    setIsContentReady(false)
+
+    const timer = globalThis.setTimeout(() => {
+      setIsContentReady(true)
+    }, contentDelayMs)
+
+    return () => {
+      globalThis.clearTimeout(timer)
+    }
+  }, [contentDelayMs])
+
+  const open = (episode: string) => {
+    const opened = [
+      ...entries.slice(0, entryIndex + 1),
+      { episode, key: `entry-${entries.length + 1}` },
+    ]
+
+    setEntries(opened)
+    setEntryIndex(opened.length - 1)
+  }
+
+  return (
+    <Shell>
+      <Header
+        actions={
+          <Button
+            appearance="outline"
+            isDisabled={entryIndex === 0}
+            onClick={() => {
+              setEntryIndex(entryIndex - 1)
+            }}
+            size="sm"
+          >
+            Back
+          </Button>
+        }
+        heading="Library"
+      />
+
+      <Main scrollKey={entry?.key}>
+        {!isContentReady && <Spinner label="Loading" />}
+
+        {isContentReady && entry?.episode == null && (
+          <div className="flex flex-col gap-3">
+            {EPISODE_TITLES.map((title) => (
+              <Card
+                heading={title}
+                key={title}
+                padding="sm"
+              >
+                <Button
+                  appearance="ghost"
+                  onClick={() => {
+                    open(title)
+                  }}
+                  size="sm"
+                >
+                  Open {title}
+                </Button>
+              </Card>
+            ))}
+          </div>
+        )}
+
+        {isContentReady && entry?.episode != null && (
+          <Card heading={entry.episode}>
+            <p className="text-content-secondary text-sm">
+              A page short enough that the scrollport
+              collapses behind it. Press Back: the list
+              returns to where it was, not to the top.
+            </p>
+          </Card>
+        )}
+      </Main>
+    </Shell>
+  )
+}
+
+/**
+ * The reader's place, kept.
+ *
+ * `Shell` makes `<main>` the page's only vertical scrollport, and
+ * a browser restores the **document** scroller and nothing else —
+ * so without `scrollKey` this list comes back at the top every
+ * time, in every browser, with no setting that changes it.
+ *
+ * Scroll the list, open an episode, then press Back.
+ */
+export const ScrollMemory: Story = {
+  render: () => <ScrollMemoryDemo contentDelayMs={0} />,
+}
+
+/**
+ * The same thing, with the rows arriving 250ms late — which is
+ * what a fetched list does, and what makes a naive
+ * `scrollTop = offset` do nothing at all.
+ *
+ * Back lands on an empty scrollport with no room for the offset,
+ * so the browser clamps it to `0`. The restore therefore re-applies
+ * as the content grows and stops the moment the offset lands, or
+ * the moment the reader scrolls.
+ */
+export const ScrollMemoryWithLateContent: Story = {
+  render: () => <ScrollMemoryDemo contentDelayMs={250} />,
+}

package/src/Main/Main.test.tsx

@@ -1,6 +1,6 @@
 import { composeStories } from "@storybook/react"
-import { expect, userEvent } from "storybook/test"
-import { afterAll, test } from "vitest"
+import { expect, userEvent, waitFor } from "storybook/test"
+import { afterAll, afterEach, test } from "vitest"
 
 import { expectNoAxeViolations } from "../expectNoAxeViolations.testHelpers.ts"
 import { mountStory } from "../mountStory.testHelpers.ts"
@@ -11,14 +11,26 @@ import {
   setViewport,
 } from "../viewport.testHelpers.ts"
 import * as stories from "./Main.stories.tsx"
+import { forgetScrollOffsets } from "./scrollMemory.ts"
 
-const { Default, Interactive, Responsive } =
-  composeStories(stories)
+const {
+  Default,
+  Interactive,
+  Responsive,
+  ScrollMemory,
+  ScrollMemoryWithLateContent,
+} = composeStories(stories)
 
 afterAll(async () => {
   await setViewport(DESKTOP)
 })
 
+// The offsets are module state, so they outlive a mount. A test
+// must not.
+afterEach(() => {
+  forgetScrollOffsets()
+})
+
 test("the content column is capped at the token, not at the window", async () => {
   await setViewport(DESKTOP)
 
@@ -165,3 +177,182 @@ test("main takes focus from a skip link without joining the tab order", async ()
 
   await expectNoAxeViolations(canvasElement)
 })
+
+/**
+ * A `scroll` event is dispatched at the next rendering step, not
+ * at the assignment, so a test that scrolls and immediately
+ * navigates measures the listener before it has been told
+ * anything.
+ */
+const scrollTo = async (
+  element: HTMLElement,
+  offset: number,
+) => {
+  element.scrollTop = offset
+
+  await waitFor(async () => {
+    await expect(element.scrollTop).toBe(offset)
+  })
+
+  await new Promise((resolve) => {
+    globalThis.requestAnimationFrame(() => {
+      globalThis.requestAnimationFrame(resolve)
+    })
+  })
+}
+
+/**
+ * The whole point, and the thing no browser does for you.
+ *
+ * `Shell` makes `<main>` the page's only vertical scrollport.
+ * `history.scrollRestoration` governs the **document** scroller, so
+ * it has nothing to say about this element — and it says nothing at
+ * all about a same-document navigation, which is every link press
+ * in a single-page app.
+ */
+test("back returns the list to where it was scrolled, not to the top", async () => {
+  await setViewport(DESKTOP)
+
+  const { canvas, canvasElement } =
+    await mountStory(ScrollMemory)
+
+  const main = canvas.getByRole("main")
+
+  // The fixture genuinely scrolls, or the assertion below would
+  // pass against a page that was never long enough to lose a
+  // place in.
+  await expect(main.scrollHeight).toBeGreaterThan(
+    main.clientHeight + 900,
+  )
+
+  await scrollTo(main, 900)
+
+  await userEvent.click(
+    expectAgentDrivable(canvas, {
+      name: "Open Episode 12",
+      role: "button",
+    }),
+  )
+
+  await expect(
+    canvas.getByRole("heading", { name: "Episode 12" }),
+  ).toBeVisible()
+
+  await userEvent.click(
+    expectAgentDrivable(canvas, {
+      name: "Back",
+      role: "button",
+    }),
+  )
+
+  await waitFor(async () => {
+    await expect(main.scrollTop).toBe(900)
+  })
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+/**
+ * The failure a naive `scrollTop = offset` produces, and the
+ * reason `useScrollMemory` keeps a `ResizeObserver` rather than
+ * writing the number once.
+ *
+ * Back commits before the rows arrive, so the scrollport has no
+ * room for the offset and the browser clamps the write to `0`.
+ * Every assertion a one-shot restore could make still passes — the
+ * offset was remembered, the write happened — and the reader is
+ * looking at the top of the list.
+ */
+test("a restore waits for content that arrives after the navigation", async () => {
+  await setViewport(DESKTOP)
+
+  const { canvas } = await mountStory(
+    ScrollMemoryWithLateContent,
+  )
+
+  const main = await waitFor(() => canvas.getByRole("main"))
+
+  await waitFor(async () => {
+    await expect(
+      canvas.getByRole("heading", { name: "Episode 1" }),
+    ).toBeVisible()
+  })
+
+  await scrollTo(main, 900)
+
+  await userEvent.click(
+    expectAgentDrivable(canvas, {
+      name: "Open Episode 12",
+      role: "button",
+    }),
+  )
+
+  await userEvent.click(
+    expectAgentDrivable(canvas, {
+      name: "Back",
+      role: "button",
+    }),
+  )
+
+  // No assertion on the intermediate `0`: whether the rows have
+  // landed by this line depends on how loaded the machine is, and
+  // a test that reads the clock is a test that fails on CI. What
+  // proves the wait is load-bearing is that deleting the
+  // `ResizeObserver` from `useScrollMemory` fails **this** test and
+  // no other.
+  await waitFor(async () => {
+    await expect(main.scrollTop).toBe(900)
+  })
+})
+
+/**
+ * A restore that outlives the reader's first scroll is a page that
+ * fights them. Anything the reader does to the scrollport ends it.
+ */
+test("a reader scrolling during a restore keeps their own position", async () => {
+  await setViewport(DESKTOP)
+
+  const { canvas } = await mountStory(
+    ScrollMemoryWithLateContent,
+  )
+
+  await waitFor(async () => {
+    await expect(
+      canvas.getByRole("heading", { name: "Episode 1" }),
+    ).toBeVisible()
+  })
+
+  const main = canvas.getByRole("main")
+
+  await scrollTo(main, 900)
+
+  await userEvent.click(
+    expectAgentDrivable(canvas, {
+      name: "Open Episode 12",
+      role: "button",
+    }),
+  )
+
+  await userEvent.click(
+    expectAgentDrivable(canvas, {
+      name: "Back",
+      role: "button",
+    }),
+  )
+
+  // Before the rows land, so the restore is still pending.
+  main.dispatchEvent(
+    new WheelEvent("wheel", { bubbles: true }),
+  )
+
+  await waitFor(async () => {
+    await expect(
+      canvas.getByRole("heading", { name: "Episode 1" }),
+    ).toBeVisible()
+  })
+
+  await scrollTo(main, 200)
+
+  // Given up, rather than dragging the reader back to 900.
+  await expect(main.scrollTop).toBe(200)
+})

package/src/Main/Main.tsx

@@ -1,7 +1,12 @@
-import { useUniqueId } from "@charcuterie/logic"
+import {
+  type MergeableRef,
+  mergeRefs,
+  useUniqueId,
+} from "@charcuterie/logic"
 import {
   type ComponentPropsWithRef,
   type ReactNode,
+  type RefCallback,
   useContext,
 } from "react"
 
@@ -12,9 +17,20 @@ import {
 } from "../Shell/contentWidth.ts"
 import { ShellContext } from "../Shell/shellContext.ts"
 import { toClassName } from "../toClassName.ts"
+import { useScrollMemory } from "./useScrollMemory.ts"
 
 export type MainProps = ComponentPropsWithRef<"main"> & {
   contentWidth?: ContentWidth
+  /**
+   * The history entry this page belongs to — react-router's
+   * `useLocation().key`, and the same value under a different
+   * router. Given it, `<main>` remembers where each entry was
+   * scrolled to and puts the offset back on Back and Forward.
+   *
+   * Omit it and nothing is remembered, which is the right default
+   * for a page with no history to remember.
+   */
+  scrollKey?: string
 }
 
 /**
@@ -94,6 +110,30 @@ export type MainProps = ComponentPropsWithRef<"main"> & {
  *    an app's own fixed chrome belongs in `Shell`, beside `Main`
  *    rather than in it.
  *
+ * ## It remembers where each history entry was scrolled to
+ *
+ * `Shell` gives this element the page's only vertical scrollport,
+ * so the header and the rails stay put while the content moves.
+ * The browser's own scroll restoration does not follow it there: a
+ * browser remembers **the document scroller's** offset per history
+ * entry, and `<main>` is not the document scroller. It also does
+ * not restore anything at all across a same-document `pushState`
+ * navigation, which is every link press in a single-page app. Back
+ * therefore lands at the top of a list the reader had scrolled
+ * half-way down, and no browser setting changes that.
+ *
+ * Pass `scrollKey` — react-router's `useLocation().key` — and the
+ * offset comes back. `useScrollMemory.ts` holds the mechanism and
+ * `scrollMemory.ts` the reasoning.
+ *
+ * ```tsx
+ * const location = useLocation()
+ *
+ * <Main scrollKey={location.key}>
+ *   <Outlet />
+ * </Main>
+ * ```
+ *
  * ## Two more things it does, both one line
  *
  * `tabIndex={-1}` so `Shell`'s skip link moves **focus** and not
@@ -128,9 +168,12 @@ export const Main = ({
   className,
   contentWidth,
   id,
+  ref,
+  scrollKey,
   ...mainProps
 }: MainProps): ReactNode => {
   const shell = useContext(ShellContext)
+  const setScrollport = useScrollMemory(scrollKey)
 
   // Always called, never conditionally: a `Main` outside a `Shell`
   // still needs an id an app can point its own skip link at.
@@ -150,6 +193,20 @@ export const Main = ({
         className,
       )}
       id={id ?? shell?.mainId ?? fallbackId}
+      // A caller's `ref` is a subscription, not a value, so the
+      // scroll memory composes with it rather than replacing it.
+      //
+      // The cast is `mergeRefs`' prop-merging signature, where
+      // every value is `unknown`; a caller's `ref` is narrower than
+      // that, never wider.
+      ref={
+        ref
+          ? (mergeRefs(
+              ref as MergeableRef,
+              setScrollport,
+            ) as RefCallback<HTMLElement>)
+          : setScrollport
+      }
       tabIndex={-1}
     >
       {/*

package/src/Main/scrollMemory.test.ts

@@ -0,0 +1,59 @@
+import { afterEach, expect, test } from "vitest"
+
+import {
+  forgetScrollOffsets,
+  recallScrollOffset,
+  rememberScrollOffset,
+} from "./scrollMemory.ts"
+
+afterEach(() => {
+  forgetScrollOffsets()
+})
+
+test("an entry nobody has scrolled recalls the top", () => {
+  expect(recallScrollOffset("entry-never-seen")).toBe(0)
+})
+
+test("an entry recalls the offset it was last left at", () => {
+  rememberScrollOffset("entry-1", 900)
+  rememberScrollOffset("entry-1", 1240)
+
+  expect(recallScrollOffset("entry-1")).toBe(1240)
+})
+
+/**
+ * A long session pushes a new history entry per link press, and
+ * every one of them would otherwise keep a number forever. The
+ * eviction is least-recently-*written*, which is why re-writing an
+ * entry has to move it to the end — a plain `Map.set` on an
+ * existing key keeps its original position, so the entry the
+ * reader is using would age out while it was in use.
+ */
+test("a long session evicts the least recently written entry", () => {
+  for (let index = 0; index < 60; index += 1) {
+    rememberScrollOffset(`entry-${index}`, index * 10)
+  }
+
+  // Written first, never re-written: gone.
+  expect(recallScrollOffset("entry-0")).toBe(0)
+
+  // Inside the last fifty: kept.
+  expect(recallScrollOffset("entry-59")).toBe(590)
+  expect(recallScrollOffset("entry-10")).toBe(100)
+})
+
+test("re-writing an entry saves it from eviction", () => {
+  rememberScrollOffset("entry-old", 500)
+
+  for (let index = 0; index < 49; index += 1) {
+    rememberScrollOffset(`entry-${index}`, index * 10)
+  }
+
+  rememberScrollOffset("entry-old", 640)
+
+  for (let index = 49; index < 60; index += 1) {
+    rememberScrollOffset(`entry-${index}`, index * 10)
+  }
+
+  expect(recallScrollOffset("entry-old")).toBe(640)
+})

package/src/Main/scrollMemory.ts

@@ -0,0 +1,73 @@
+/**
+ * What the browser will not remember for you.
+ *
+ * `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:
+ *
+ * > *"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.
+ */
+
+/**
+ * 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.
+ */
+const REMEMBERED_ENTRY_LIMIT = 50
+
+const rememberedOffsets = new Map<string, number>()
+
+export const rememberScrollOffset = (
+  key: string,
+  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)
+
+  for (const oldestKey of rememberedOffsets.keys()) {
+    if (rememberedOffsets.size <= REMEMBERED_ENTRY_LIMIT) {
+      break
+    }
+
+    rememberedOffsets.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.
+ */
+export const recallScrollOffset = (key: string) =>
+  rememberedOffsets.get(key) ?? 0
+
+/** Test-only. Module state outlives a mount; a test must not. */
+export const forgetScrollOffsets = () => {
+  rememberedOffsets.clear()
+}