@charcuterie/ui 3.34.0 → 4.1.0

package/src/Main/Main.stories.tsx

@@ -16,6 +16,7 @@ import {
   RailNavigation,
 } from "../shell.storyHelpers.tsx"
 import { Main } from "./Main.tsx"
+import { ScrollMemoryProvider } from "./ScrollMemoryProvider.tsx"
 
 const CONTENT_WIDTH_OPTIONS = [
   "sm",
@@ -173,17 +174,42 @@ const EPISODE_TITLES = Array.from(
 
 type HistoryEntry = {
   episode: string | null
+  isExpanded: boolean
   key: string
 }
 
+const SPECIAL_TITLES = Array.from(
+  { length: 8 },
+  (_unused, index) => `Special ${index + 1}`,
+)
+
+const toPath = (entry: HistoryEntry) =>
+  entry.episode === null
+    ? "/library"
+    : `/library/${entry.episode}`
+
 /**
- * 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.
+ * A history stack, small enough to read and honest about the two
+ * things that matter.
+ *
+ * **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.
+ *
+ * **Expanding the specials is a NEW entry on the SAME path.** That
+ * is what `setSearchParams` does for a filter chip or an expanded
+ * group, and it is the case that has to leave the scrollport alone.
+ * The key is one the memory has never seen, so a memory that read
+ * "unseen ⇒ top" would throw the reader to the top of the list
+ * every time they opened a group.
+ *
+ * The toggle sits in the **header**, not in the list, and that is
+ * not decoration: a control inside the scrollport is scrolled into
+ * view before it is pressed, which moves the very offset the demo
+ * is about. It cost an hour of chasing a bug that was the driver's.
  *
- * `contentDelayMs` is the second half of the problem. A real list
- * is fetched, so the commit that changes the route draws an empty
+ * `contentDelayMs` is the other 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
@@ -195,7 +221,7 @@ const ScrollMemoryDemo = ({
   contentDelayMs: number
 }) => {
   const [entries, setEntries] = useState<HistoryEntry[]>([
-    { episode: null, key: "entry-1" },
+    { episode: null, isExpanded: false, key: "entry-1" },
   ])
   const [entryIndex, setEntryIndex] = useState(0)
   const [isContentReady, setIsContentReady] = useState(
@@ -220,70 +246,103 @@ const ScrollMemoryDemo = ({
     }
   }, [contentDelayMs])
 
-  const open = (episode: string) => {
-    const opened = [
+  const push = (pushed: Omit<HistoryEntry, "key">) => {
+    const stack = [
       ...entries.slice(0, entryIndex + 1),
-      { episode, key: `entry-${entries.length + 1}` },
+      { ...pushed, key: `entry-${entries.length + 1}` },
     ]
 
-    setEntries(opened)
-    setEntryIndex(opened.length - 1)
+    setEntries(stack)
+    setEntryIndex(stack.length - 1)
   }
 
-  return (
-    <Shell>
-      <Header
-        actions={
-          <Button
-            appearance="outline"
-            isDisabled={entryIndex === 0}
-            onClick={() => {
-              setEntryIndex(entryIndex - 1)
-            }}
-            size="sm"
-          >
-            Back
-          </Button>
-        }
-        heading="Library"
-      />
+  const titles = entry?.isExpanded
+    ? [...EPISODE_TITLES, ...SPECIAL_TITLES]
+    : EPISODE_TITLES
 
-      <Main scrollKey={entry?.key}>
-        {!isContentReady && <Spinner label="Loading" />}
+  return (
+    <ScrollMemoryProvider
+      entry={{
+        key: entry?.key ?? "entry-1",
+        path: entry ? toPath(entry) : "/library",
+      }}
+    >
+      <Shell>
+        <Header
+          actions={
+            <>
+              <Button
+                appearance="outline"
+                isDisabled={entryIndex === 0}
+                onClick={() => {
+                  setEntryIndex(entryIndex - 1)
+                }}
+                size="sm"
+              >
+                Back
+              </Button>
 
-        {isContentReady && entry?.episode == null && (
-          <div className="flex flex-col gap-3">
-            {EPISODE_TITLES.map((title) => (
-              <Card
-                heading={title}
-                key={title}
-                padding="sm"
+              <Button
+                appearance="outline"
+                isDisabled={entry?.episode != null}
+                onClick={() => {
+                  push({
+                    episode: null,
+                    isExpanded: !entry?.isExpanded,
+                  })
+                }}
+                size="sm"
               >
-                <Button
-                  appearance="ghost"
-                  onClick={() => {
-                    open(title)
-                  }}
-                  size="sm"
+                {entry?.isExpanded
+                  ? "Collapse the specials"
+                  : "Expand the specials"}
+              </Button>
+            </>
+          }
+          heading="Library"
+        />
+
+        <Main>
+          {!isContentReady && <Spinner label="Loading" />}
+
+          {isContentReady && entry?.episode == null && (
+            <div className="flex flex-col gap-3">
+              {titles.map((title) => (
+                <Card
+                  heading={title}
+                  key={title}
+                  padding="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>
+                  <Button
+                    appearance="ghost"
+                    onClick={() => {
+                      push({
+                        episode: title,
+                        isExpanded:
+                          entry?.isExpanded ?? false,
+                      })
+                    }}
+                    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>
+    </ScrollMemoryProvider>
   )
 }
 
@@ -292,10 +351,16 @@ const ScrollMemoryDemo = ({
  *
  * `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.
+ * so without a `ScrollMemoryProvider` 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.
+ *
+ * Then scroll again and press **Expand the specials**. That is a
+ * new history entry on the same page, and the scrollport does not
+ * move — a filter is not a navigation, however the router files
+ * it.
  */
 export const ScrollMemory: Story = {
   render: () => <ScrollMemoryDemo contentDelayMs={0} />,

package/src/Main/Main.test.tsx

@@ -305,6 +305,64 @@ test("a restore waits for content that arrives after the navigation", async () =
   })
 })
 
+/**
+ * The regression the first release of this shipped, and the reason
+ * an entry remembers its path.
+ *
+ * A filter chip, an expanded group and a selected tab each write a
+ * search param, and `setSearchParams` **navigates** — so pressing
+ * one mints a history entry the memory has never seen, on the page
+ * the reader is already looking at. Read as "unseen ⇒ start at the
+ * top", the list jumped to the top every time the reader opened a
+ * group. Measured live on Docket: scrolled to 1200, pressed a group
+ * toggle, landed at 0.
+ *
+ * The toggle is in the header rather than in the list on purpose.
+ * A control inside the scrollport is scrolled into view before it
+ * is pressed, so the driver moves the offset and the test proves
+ * nothing.
+ *
+ * Leaving the scrollport alone is also exactly what the page did
+ * before any of this existed, so this answer cannot itself be a
+ * regression.
+ */
+test("expanding a group is a new history entry that does not move the scrollport", async () => {
+  await setViewport(DESKTOP)
+
+  const { canvas } = await mountStory(ScrollMemory)
+
+  const main = canvas.getByRole("main")
+
+  await scrollTo(main, 900)
+
+  await userEvent.click(
+    expectAgentDrivable(canvas, {
+      name: "Expand the specials",
+      role: "button",
+    }),
+  )
+
+  // The expansion happened, so this is a real new entry rather than
+  // a press that did nothing.
+  await expect(
+    expectAgentDrivable(canvas, {
+      name: "Collapse the specials",
+      role: "button",
+    }),
+  ).toBeVisible()
+
+  // Still where the reader put it. `waitFor` would hide a jump that
+  // corrects itself, so this is read directly after two rendering
+  // steps.
+  await new Promise((resolve) => {
+    globalThis.requestAnimationFrame(() => {
+      globalThis.requestAnimationFrame(resolve)
+    })
+  })
+
+  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.

package/src/Main/Main.tsx

@@ -17,20 +17,11 @@ import {
 } from "../Shell/contentWidth.ts"
 import { ShellContext } from "../Shell/shellContext.ts"
 import { toClassName } from "../toClassName.ts"
+import { ScrollMemoryContext } from "./scrollMemoryContext.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
 }
 
 /**
@@ -122,18 +113,27 @@ export type MainProps = ComponentPropsWithRef<"main"> & {
  * 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.
+ * So this element remembers it, and **there is no prop for it**.
+ * The history entry arrives on `ScrollMemoryContext`, which
+ * `ReactRouterAdapter` puts at the app root:
  *
  * ```tsx
- * const location = useLocation()
- *
- * <Main scrollKey={location.key}>
- *   <Outlet />
- * </Main>
+ * <BrowserRouter>
+ *   <ReactRouterAdapter>
+ *     <Routes>…</Routes>
+ *   </ReactRouterAdapter>
+ * </BrowserRouter>
  * ```
  *
+ * It was a prop for one release — `scrollKey` — and that release is
+ * the argument against a prop. One app wired it; the other three
+ * carried on losing the reader's place with the library sitting
+ * right there supporting it. Render no provider and nothing is
+ * remembered, which is what an app with no router should get.
+ *
+ * `useScrollMemory.ts` holds the mechanism and `scrollMemory.ts`
+ * the reasoning.
+ *
  * ## Two more things it does, both one line
  *
  * `tabIndex={-1}` so `Shell`'s skip link moves **focus** and not
@@ -169,11 +169,11 @@ export const Main = ({
   contentWidth,
   id,
   ref,
-  scrollKey,
   ...mainProps
 }: MainProps): ReactNode => {
   const shell = useContext(ShellContext)
-  const setScrollport = useScrollMemory(scrollKey)
+  const scrollEntry = useContext(ScrollMemoryContext)
+  const setScrollport = useScrollMemory(scrollEntry)
 
   // Always called, never conditionally: a `Main` outside a `Shell`
   // still needs an id an app can point its own skip link at.

package/src/Main/ScrollMemoryProvider.tsx

@@ -0,0 +1,48 @@
+import type { ReactNode } from "react"
+
+import type { ScrollEntry } from "./scrollMemory.ts"
+import { ScrollMemoryContext } from "./scrollMemoryContext.ts"
+
+export type ScrollMemoryProviderProps = {
+  children?: ReactNode
+  /**
+   * The history entry the page is showing, and the path it belongs
+   * to. Under react-router both come straight off `useLocation()`.
+   */
+  entry: ScrollEntry
+}
+
+/**
+ * Tell every `Main` below this which history entry it is showing,
+ * so Back and Forward return the reader to where they were.
+ *
+ * An app that uses react-router should not render this directly —
+ * `ReactRouterAdapter` in the `./react-router` subpath wires it,
+ * along with the link seam, in one component at the root. This is
+ * the router-free half, for an app on a different router:
+ *
+ * ```tsx
+ * const [location] = useLocation()   // wouter, say
+ *
+ * <ScrollMemoryProvider
+ *   entry={{ key: historyKey, path: location }}
+ * >
+ *   <App />
+ * </ScrollMemoryProvider>
+ * ```
+ *
+ * **`key` must identify the history entry, not the URL.** Two visits
+ * to the same list are two entries and the reader may leave them at
+ * different offsets; a key derived from the path would give the
+ * second visit the first one's position and could not tell Back from
+ * Forward. A router that exposes no such key can pass a counter it
+ * increments on every push and restores on every pop.
+ */
+export const ScrollMemoryProvider = ({
+  children,
+  entry,
+}: ScrollMemoryProviderProps): ReactNode => (
+  <ScrollMemoryContext.Provider value={entry}>
+    {children}
+  </ScrollMemoryContext.Provider>
+)

package/src/Main/scrollMemory.test.ts

@@ -1,24 +1,66 @@
 import { afterEach, expect, test } from "vitest"
 
 import {
+  enterScrollEntry,
   forgetScrollOffsets,
-  recallScrollOffset,
   rememberScrollOffset,
+  resolveScrollOffset,
 } from "./scrollMemory.ts"
 
 afterEach(() => {
   forgetScrollOffsets()
 })
 
-test("an entry nobody has scrolled recalls the top", () => {
-  expect(recallScrollOffset("entry-never-seen")).toBe(0)
+const toEntry = (key: string, path = "/backlog") => ({
+  key,
+  path,
+})
+
+test("the first page a reader opens starts at the top", () => {
+  expect(resolveScrollOffset(toEntry("entry-1"))).toBe(0)
 })
 
 test("an entry recalls the offset it was last left at", () => {
-  rememberScrollOffset("entry-1", 900)
-  rememberScrollOffset("entry-1", 1240)
+  rememberScrollOffset(toEntry("entry-1"), 900)
+  rememberScrollOffset(toEntry("entry-1"), 1240)
+
+  expect(resolveScrollOffset(toEntry("entry-1"))).toBe(1240)
+})
+
+test("a page the reader has not seen starts at the top", () => {
+  enterScrollEntry(toEntry("entry-1", "/backlog"))
+
+  expect(
+    resolveScrollOffset(toEntry("entry-2", "/tasks/9")),
+  ).toBe(0)
+})
+
+/**
+ * The defect this whole field exists for, and it shipped: a filter
+ * chip, an expanded group and a selected tab all write a search
+ * param, `setSearchParams` navigates, and the new entry is one the
+ * memory has never seen. Read as "unseen ⇒ top", opening a group
+ * threw the reader to the top of the list they were reading.
+ *
+ * `null` is a third answer — **leave the scrollport alone** — and
+ * it is what the page did before any of this existed, so it cannot
+ * be a regression.
+ */
+test("a new entry on the same page leaves the scrollport alone", () => {
+  enterScrollEntry(toEntry("entry-1", "/backlog"))
+
+  expect(
+    resolveScrollOffset(toEntry("entry-2", "/backlog")),
+  ).toBeNull()
+})
+
+test("a remembered entry beats the page comparison", () => {
+  rememberScrollOffset(toEntry("entry-1", "/backlog"), 1240)
+  enterScrollEntry(toEntry("entry-2", "/backlog"))
 
-  expect(recallScrollOffset("entry-1")).toBe(1240)
+  expect(
+    resolveScrollOffset(toEntry("entry-1", "/backlog")),
+  ).toBe(1240)
 })
 
 /**
@@ -31,29 +73,41 @@ test("an entry recalls the offset it was last left at", () => {
  */
 test("a long session evicts the least recently written entry", () => {
   for (let index = 0; index < 60; index += 1) {
-    rememberScrollOffset(`entry-${index}`, index * 10)
+    rememberScrollOffset(
+      toEntry(`entry-${index}`),
+      index * 10,
+    )
   }
 
-  // Written first, never re-written: gone.
-  expect(recallScrollOffset("entry-0")).toBe(0)
+  // Written first, never re-written: gone, so it falls through to
+  // the page comparison and starts at the top.
+  expect(resolveScrollOffset(toEntry("entry-0"))).toBe(0)
 
   // Inside the last fifty: kept.
-  expect(recallScrollOffset("entry-59")).toBe(590)
-  expect(recallScrollOffset("entry-10")).toBe(100)
+  expect(resolveScrollOffset(toEntry("entry-59"))).toBe(590)
+  expect(resolveScrollOffset(toEntry("entry-10"))).toBe(100)
 })
 
 test("re-writing an entry saves it from eviction", () => {
-  rememberScrollOffset("entry-old", 500)
+  rememberScrollOffset(toEntry("entry-old"), 500)
 
   for (let index = 0; index < 49; index += 1) {
-    rememberScrollOffset(`entry-${index}`, index * 10)
+    rememberScrollOffset(
+      toEntry(`entry-${index}`),
+      index * 10,
+    )
   }
 
-  rememberScrollOffset("entry-old", 640)
+  rememberScrollOffset(toEntry("entry-old"), 640)
 
   for (let index = 49; index < 60; index += 1) {
-    rememberScrollOffset(`entry-${index}`, index * 10)
+    rememberScrollOffset(
+      toEntry(`entry-${index}`),
+      index * 10,
+    )
   }
 
-  expect(recallScrollOffset("entry-old")).toBe(640)
+  expect(resolveScrollOffset(toEntry("entry-old"))).toBe(
+    640,
+  )
 })