@charcuterie/ui 3.33.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/RangeSlider/RangeSlider.mdx

@@ -0,0 +1,85 @@
+import { Canvas, Controls, Meta } from "@storybook/addon-docs/blocks";
+
+import * as RangeSliderStories from "./RangeSlider.stories";
+
+<Meta of={RangeSliderStories} />
+
+# RangeSlider
+
+A span picked out along a bar, with an independently focusable handle at each end.
+
+It exists because QueuePilot plays **only a section** of a video: a user drags two handles
+over a film's runtime to choose where a clip starts and ends, and has to see the section
+they typed into a `TimecodeInput` beside it. So the shape this is built for is a media
+timeline — a bar spanning the whole runtime, two thumbs, and the chosen span painted
+between them.
+
+<Canvas of={RangeSliderStories.Default} />
+
+## Props
+
+<Controls />
+
+## Why this is a component and not `Slider isRange`
+
+`Combobox`'s `isMultiple` and `DatePicker`'s `isRange` are **modes**, and the test that
+made them modes is written down: the widget's ARIA role does not change, and the two shapes
+share nearly everything. Both halves of that test fail here.
+
+[`Slider` puts `role="slider"`, the tab stop and the pointer target on the **track**](?path=/docs/components-controls-slider--docs),
+because one track reports one value. Two values cannot live on one accessible object — so
+here the role moves to the thumbs, the track becomes a `role="group"` carrying the label,
+and the tab stops go from one to two. A mode that rewrote its own role would break
+`getByRole("slider", { name })` in every consumer that had used the single-value one.
+
+`Slider`'s own record says it plainly: *"a two-thumb range is a different widget with its
+own focus model"*.
+
+What the two genuinely share is the **arithmetic** (`Slider/sliderValue.ts`, called rather
+than copied, so both snap on the same grid) and the **bar** (`sliderStyles.ts`). The test
+compares the two thumbs as computed styles, not as class names.
+
+<Canvas of={RangeSliderStories.BesideTheSlider} />
+
+## The thumbs clamp, they do not swap
+
+A thumb dragged past its partner stops **on** it. The range collapses to zero width, both
+handles keep their identities, and the next press opens it again from whichever side that
+press lands on.
+
+Swapping is the other defensible answer and is the wrong one here. The two handles are a
+clip's start and its end, read alongside a field that names them; a drag that silently
+renamed the handle under the pointer would move a number the user is reading somewhere
+else. On the keyboard it is plainer still — swapping means one ArrowRight moves the *other*
+thumb, and the element with focus is no longer the value that changed.
+
+Each thumb reports the other as its own `aria-valuemin` / `aria-valuemax`, which is how a
+screen reader is told where this handle stops.
+
+<Canvas of={RangeSliderStories.AllStates} />
+
+## Drag does not commit
+
+`onChange` fires on every movement — each arrow key, each pointer sample. `onChangeEnd`
+fires once, on release or key up.
+
+The same split `Slider` settled, for the same reason: a clip preview that re-seeks a player
+from `onChange` issues one seek per pointer sample and arrives at the right frame **last**,
+behind a queue of stale ones. While a drag is in flight the component paints from its own
+value rather than from `value`, so a caller that commits on `onChangeEnd` alone still sees
+the thumbs follow the pointer.
+
+<Canvas of={RangeSliderStories.Interactive} />
+
+## The app owns the data
+
+`valueFormat` turns a number into whatever the value **is** — `21:14`, `$40`, `3.5 km`. The
+component never learns what a timecode is: it knows a number, and the app knows what the
+number means. That one function feeds `aria-valuetext` and the shown span both.
+
+`ticks` is the same division. A tick is `{ label?, value }` and nothing else, so a film's
+chapters are the offsets the app already has. There is no chapter model in here, and the
+marks are `aria-hidden` — each thumb already announces its own position, so a screen reader
+reading the marks between them would be reading the picture.
+
+<Canvas of={RangeSliderStories.AllVariants} />