@charcuterie/ui 3.29.0 → 3.30.0

package/dist/Main/Main.d.ts

@@ -2,6 +2,16 @@ import { type ComponentPropsWithRef, type ReactNode } from "react";
 import { type ContentWidth } from "../Shell/contentWidth.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;
 };
 /**
  * The `<main>` landmark and the content column.
@@ -80,6 +90,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
@@ -109,5 +143,5 @@ export type MainProps = ComponentPropsWithRef<"main"> & {
  * wrap, so a wide one goes in an `overflow-x-auto` wrapper, which
  * `Main.mdx` shows.
  */
-export declare const Main: ({ children, className, contentWidth, id, ...mainProps }: MainProps) => ReactNode;
+export declare const Main: ({ children, className, contentWidth, id, ref, scrollKey, ...mainProps }: MainProps) => ReactNode;
 //# sourceMappingURL=Main.d.ts.map

package/dist/Main/Main.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Main.d.ts","sourceRoot":"","sources":["../../src/Main/Main.tsx"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,qBAAqB,EAC1B,KAAK,SAAS,EAEf,MAAM,OAAO,CAAA;AAEd,OAAO,EACL,KAAK,YAAY,EAGlB,MAAM,0BAA0B,CAAA;AAIjC,MAAM,MAAM,SAAS,GAAG,qBAAqB,CAAC,MAAM,CAAC,GAAG;IACtD,YAAY,CAAC,EAAE,YAAY,CAAA;CAC5B,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyGG;AACH,eAAO,MAAM,IAAI,GAAI,yDAMlB,SAAS,KAAG,SA0Cd,CAAA"}
+{"version":3,"file":"Main.d.ts","sourceRoot":"","sources":["../../src/Main/Main.tsx"],"names":[],"mappings":"AAKA,OAAO,EACL,KAAK,qBAAqB,EAC1B,KAAK,SAAS,EAGf,MAAM,OAAO,CAAA;AAEd,OAAO,EACL,KAAK,YAAY,EAGlB,MAAM,0BAA0B,CAAA;AAKjC,MAAM,MAAM,SAAS,GAAG,qBAAqB,CAAC,MAAM,CAAC,GAAG;IACtD,YAAY,CAAC,EAAE,YAAY,CAAA;IAC3B;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiIG;AACH,eAAO,MAAM,IAAI,GAAI,yEAQlB,SAAS,KAAG,SAyDd,CAAA"}

package/dist/Main/Main.js

@@ -1,9 +1,10 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { useUniqueId } from "@charcuterie/logic";
+import { mergeRefs, useUniqueId, } from "@charcuterie/logic";
 import { useContext, } from "react";
 import { DEFAULT_CONTENT_WIDTH, toMaxInlineSize, } from "../Shell/contentWidth.js";
 import { ShellContext } from "../Shell/shellContext.js";
 import { toClassName } from "../toClassName.js";
+import { useScrollMemory } from "./useScrollMemory.js";
 /**
  * The `<main>` landmark and the content column.
  *
@@ -81,6 +82,30 @@ import { toClassName } from "../toClassName.js";
  *    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
@@ -110,14 +135,24 @@ import { toClassName } from "../toClassName.js";
  * wrap, so a wide one goes in an `overflow-x-auto` wrapper, which
  * `Main.mdx` shows.
  */
-export const Main = ({ children, className, contentWidth, id, ...mainProps }) => {
+export const Main = ({ children, className, contentWidth, id, ref, scrollKey, ...mainProps }) => {
     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.
     const fallbackId = useUniqueId();
     const maxInlineSize = toMaxInlineSize(contentWidth ??
         shell?.contentWidth ??
         DEFAULT_CONTENT_WIDTH);
-    return (_jsx("main", { ...mainProps, className: toClassName("charcuterie-scrollbar col-start-1 row-start-3 min-h-0 min-w-0 overflow-y-auto md:col-start-2 md:row-start-2", className), id: id ?? shell?.mainId ?? fallbackId, tabIndex: -1, children: _jsx("div", { className: "@container mx-auto flex w-full min-w-0 flex-col gap-6 wrap-anywhere px-4 py-6 sm:px-6", style: { maxInlineSize }, children: children }) }));
+    return (_jsx("main", { ...mainProps, className: toClassName("charcuterie-scrollbar col-start-1 row-start-3 min-h-0 min-w-0 overflow-y-auto md:col-start-2 md:row-start-2", 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, setScrollport)
+            : setScrollport, tabIndex: -1, children: _jsx("div", { className: "@container mx-auto flex w-full min-w-0 flex-col gap-6 wrap-anywhere px-4 py-6 sm:px-6", style: { maxInlineSize }, children: children }) }));
 };
 //# sourceMappingURL=Main.js.map

package/dist/Main/Main.js.map

@@ -1 +1 @@
-{"version":3,"file":"Main.js","sourceRoot":"","sources":["../../src/Main/Main.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAChD,OAAO,EAGL,UAAU,GACX,MAAM,OAAO,CAAA;AAEd,OAAO,EAEL,qBAAqB,EACrB,eAAe,GAChB,MAAM,0BAA0B,CAAA;AACjC,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAA;AACvD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAM/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyGG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG,CAAC,EACnB,QAAQ,EACR,SAAS,EACT,YAAY,EACZ,EAAE,EACF,GAAG,SAAS,EACF,EAAa,EAAE;IACzB,MAAM,KAAK,GAAG,UAAU,CAAC,YAAY,CAAC,CAAA;IAEtC,iEAAiE;IACjE,2DAA2D;IAC3D,MAAM,UAAU,GAAG,WAAW,EAAE,CAAA;IAEhC,MAAM,aAAa,GAAG,eAAe,CACnC,YAAY;QACV,KAAK,EAAE,YAAY;QACnB,qBAAqB,CACxB,CAAA;IAED,OAAO,CACL,kBACM,SAAS,EACb,SAAS,EAAE,WAAW,CACpB,6GAA6G,EAC7G,SAAS,CACV,EACD,EAAE,EAAE,EAAE,IAAI,KAAK,EAAE,MAAM,IAAI,UAAU,EACrC,QAAQ,EAAE,CAAC,CAAC,YAaZ,cACE,SAAS,EAAC,uFAAuF,EACjG,KAAK,EAAE,EAAE,aAAa,EAAE,YAEvB,QAAQ,GACL,GACD,CACR,CAAA;AACH,CAAC,CAAA"}
+{"version":3,"file":"Main.js","sourceRoot":"","sources":["../../src/Main/Main.tsx"],"names":[],"mappings":";AAAA,OAAO,EAEL,SAAS,EACT,WAAW,GACZ,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EAIL,UAAU,GACX,MAAM,OAAO,CAAA;AAEd,OAAO,EAEL,qBAAqB,EACrB,eAAe,GAChB,MAAM,0BAA0B,CAAA;AACjC,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAA;AACvD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAC/C,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAgBtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiIG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG,CAAC,EACnB,QAAQ,EACR,SAAS,EACT,YAAY,EACZ,EAAE,EACF,GAAG,EACH,SAAS,EACT,GAAG,SAAS,EACF,EAAa,EAAE;IACzB,MAAM,KAAK,GAAG,UAAU,CAAC,YAAY,CAAC,CAAA;IACtC,MAAM,aAAa,GAAG,eAAe,CAAC,SAAS,CAAC,CAAA;IAEhD,iEAAiE;IACjE,2DAA2D;IAC3D,MAAM,UAAU,GAAG,WAAW,EAAE,CAAA;IAEhC,MAAM,aAAa,GAAG,eAAe,CACnC,YAAY;QACV,KAAK,EAAE,YAAY;QACnB,qBAAqB,CACxB,CAAA;IAED,OAAO,CACL,kBACM,SAAS,EACb,SAAS,EAAE,WAAW,CACpB,6GAA6G,EAC7G,SAAS,CACV,EACD,EAAE,EAAE,EAAE,IAAI,KAAK,EAAE,MAAM,IAAI,UAAU;QACrC,0DAA0D;QAC1D,2DAA2D;QAC3D,EAAE;QACF,yDAAyD;QACzD,8DAA8D;QAC9D,qBAAqB;QACrB,GAAG,EACD,GAAG;YACD,CAAC,CAAE,SAAS,CACR,GAAmB,EACnB,aAAa,CACe;YAChC,CAAC,CAAC,aAAa,EAEnB,QAAQ,EAAE,CAAC,CAAC,YAaZ,cACE,SAAS,EAAC,uFAAuF,EACjG,KAAK,EAAE,EAAE,aAAa,EAAE,YAEvB,QAAQ,GACL,GACD,CACR,CAAA;AACH,CAAC,CAAA"}

package/dist/Main/scrollMemory.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 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.
+ */
+export declare const rememberScrollOffset: (key: string, offset: number) => void;
+/**
+ * `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 declare const recallScrollOffset: (key: string) => number;
+/** Test-only. Module state outlives a mount; a test must not. */
+export declare const forgetScrollOffsets: () => void;
+//# sourceMappingURL=scrollMemory.d.ts.map

package/dist/Main/scrollMemory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scrollMemory.d.ts","sourceRoot":"","sources":["../../src/Main/scrollMemory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAaH,eAAO,MAAM,oBAAoB,GAC/B,KAAK,MAAM,EACX,QAAQ,MAAM,SAef,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,GAAI,KAAK,MAAM,WACb,CAAA;AAEjC,iEAAiE;AACjE,eAAO,MAAM,mBAAmB,YAE/B,CAAA"}

package/dist/Main/scrollMemory.js

@@ -0,0 +1,63 @@
+/**
+ * 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();
+export const rememberScrollOffset = (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.
+    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) => rememberedOffsets.get(key) ?? 0;
+/** Test-only. Module state outlives a mount; a test must not. */
+export const forgetScrollOffsets = () => {
+    rememberedOffsets.clear();
+};
+//# sourceMappingURL=scrollMemory.js.map

package/dist/Main/scrollMemory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scrollMemory.js","sourceRoot":"","sources":["../../src/Main/scrollMemory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH;;;;;;GAMG;AACH,MAAM,sBAAsB,GAAG,EAAE,CAAA;AAEjC,MAAM,iBAAiB,GAAG,IAAI,GAAG,EAAkB,CAAA;AAEnD,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAClC,GAAW,EACX,MAAc,EACd,EAAE;IACF,8DAA8D;IAC9D,+DAA+D;IAC/D,+CAA+C;IAC/C,iBAAiB,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;IAC7B,iBAAiB,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAA;IAElC,KAAK,MAAM,SAAS,IAAI,iBAAiB,CAAC,IAAI,EAAE,EAAE,CAAC;QACjD,IAAI,iBAAiB,CAAC,IAAI,IAAI,sBAAsB,EAAE,CAAC;YACrD,MAAK;QACP,CAAC;QAED,iBAAiB,CAAC,MAAM,CAAC,SAAS,CAAC,CAAA;IACrC,CAAC;AACH,CAAC,CAAA;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,GAAW,EAAE,EAAE,CAChD,iBAAiB,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;AAEjC,iEAAiE;AACjE,MAAM,CAAC,MAAM,mBAAmB,GAAG,GAAG,EAAE;IACtC,iBAAiB,CAAC,KAAK,EAAE,CAAA;AAC3B,CAAC,CAAA"}

package/dist/Main/useScrollMemory.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 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:
+ *
+ *  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.
+ *
+ * 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.
+ *
+ * @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.
+ */
+export declare const useScrollMemory: (scrollKey: string | undefined) => (node: unknown) => void;
+//# sourceMappingURL=useScrollMemory.d.ts.map

package/dist/Main/useScrollMemory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useScrollMemory.d.ts","sourceRoot":"","sources":["../../src/Main/useScrollMemory.ts"],"names":[],"mappings":"AA6BA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,eAAe,GAC1B,WAAW,MAAM,GAAG,SAAS,YAaS,OAAO,SA6F9C,CAAA"}

package/dist/Main/useScrollMemory.js

@@ -0,0 +1,131 @@
+import { useCallback, useLayoutEffect, useRef } from "react";
+import { recallScrollOffset, rememberScrollOffset, } from "./scrollMemory.js";
+/**
+ * How long a restore keeps trying while the content is still
+ * arriving.
+ *
+ * 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.
+ */
+const RESTORE_WINDOW_MS = 3000;
+/** A scroll the reader asked for. It ends the restore at once. */
+const READER_INTENT_EVENTS = [
+    "keydown",
+    "pointerdown",
+    "touchstart",
+    "wheel",
+];
+/**
+ * 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:
+ *
+ *  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.
+ *
+ * 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.
+ *
+ * @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.
+ */
+export const useScrollMemory = (scrollKey) => {
+    const elementRef = useRef(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.
+    //
+    // `unknown` in, narrowed here, so the returned function is both a
+    // `RefCallback<HTMLElement>` and something `mergeRefs` accepts —
+    // that library's merge is typed for the prop-merging path, where
+    // every value is `unknown`.
+    const setElement = useCallback((node) => {
+        elementRef.current =
+            node instanceof HTMLElement ? node : null;
+    }, []);
+    useLayoutEffect(() => {
+        const element = elementRef.current;
+        if (!element || scrollKey === 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 observer = new ResizeObserver(() => {
+            applyOffset();
+        });
+        const deadline = globalThis.setTimeout(() => {
+            stopRestoring();
+        }, RESTORE_WINDOW_MS);
+        const stopRestoring = () => {
+            if (!isRestoringRef.current) {
+                return;
+            }
+            isRestoringRef.current = false;
+            observer.disconnect();
+            globalThis.clearTimeout(deadline);
+            for (const eventName of READER_INTENT_EVENTS) {
+                element.removeEventListener(eventName, stopRestoring);
+            }
+        };
+        const applyOffset = () => {
+            if (!isRestoringRef.current) {
+                return;
+            }
+            element.scrollTop = offset;
+            // Landed. Anything further would only fight the reader.
+            if (element.scrollTop === offset) {
+                stopRestoring();
+            }
+        };
+        const onScroll = () => {
+            if (isRestoringRef.current) {
+                return;
+            }
+            rememberScrollOffset(scrollKey, element.scrollTop);
+        };
+        isRestoringRef.current = true;
+        for (const eventName of READER_INTENT_EVENTS) {
+            element.addEventListener(eventName, stopRestoring, {
+                passive: true,
+            });
+        }
+        // The scrollport's own height changes with the window; its
+        // content column's changes when the rows land. Both move the
+        // ceiling the offset is clamped against.
+        observer.observe(element);
+        for (const child of Array.from(element.children)) {
+            observer.observe(child);
+        }
+        element.addEventListener("scroll", onScroll, {
+            passive: true,
+        });
+        applyOffset();
+        return () => {
+            stopRestoring();
+            element.removeEventListener("scroll", onScroll);
+        };
+    }, [scrollKey]);
+    return setElement;
+};
+//# sourceMappingURL=useScrollMemory.js.map

package/dist/Main/useScrollMemory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useScrollMemory.js","sourceRoot":"","sources":["../../src/Main/useScrollMemory.ts"],"names":[],"mappings":"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"}

package/dist/SearchInput/SearchInput.d.ts

@@ -1,5 +1,6 @@
 import type { ControlSize } from "@charcuterie/tokens";
 import { type ComponentPropsWithRef, type ReactNode } from "react";
+export type SearchInputSize = Exclude<ControlSize, "sm">;
 export type SearchInputProps = Omit<ComponentPropsWithRef<"input">, "size" | "type"> & {
     /** The app-owned glyph inside the clear button. */
     clearIcon: ReactNode;
@@ -7,7 +8,8 @@ export type SearchInputProps = Omit<ComponentPropsWithRef<"input">, "size" | "ty
     /** Override value-derived visibility for an uncontrolled input. */
     isClearVisible?: boolean;
     onClear: () => void;
-    size?: ControlSize;
+    /** Search and clear targets are never smaller than the medium control size. */
+    size?: SearchInputSize;
 };
 /**
  * A search field whose clear affordance is a real, labelled icon

package/dist/SearchInput/SearchInput.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SearchInput.d.ts","sourceRoot":"","sources":["../../src/SearchInput/SearchInput.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AACtD,OAAO,EACL,KAAK,qBAAqB,EAC1B,KAAK,SAAS,EAEf,MAAM,OAAO,CAAA;AAed,MAAM,MAAM,gBAAgB,GAAG,IAAI,CACjC,qBAAqB,CAAC,OAAO,CAAC,EAC9B,MAAM,GAAG,MAAM,CAChB,GAAG;IACF,mDAAmD;IACnD,SAAS,EAAE,SAAS,CAAA;IACpB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,mEAAmE;IACnE,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB,OAAO,EAAE,MAAM,IAAI,CAAA;IACnB,IAAI,CAAC,EAAE,WAAW,CAAA;CACnB,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,WAAW,GAAI,8GAWzB,gBAAgB,KAAG,SAmDrB,CAAA"}
+{"version":3,"file":"SearchInput.d.ts","sourceRoot":"","sources":["../../src/SearchInput/SearchInput.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AACtD,OAAO,EACL,KAAK,qBAAqB,EAC1B,KAAK,SAAS,EAEf,MAAM,OAAO,CAAA;AASd,MAAM,MAAM,eAAe,GAAG,OAAO,CAAC,WAAW,EAAE,IAAI,CAAC,CAAA;AAOxD,MAAM,MAAM,gBAAgB,GAAG,IAAI,CACjC,qBAAqB,CAAC,OAAO,CAAC,EAC9B,MAAM,GAAG,MAAM,CAChB,GAAG;IACF,mDAAmD;IACnD,SAAS,EAAE,SAAS,CAAA;IACpB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,mEAAmE;IACnE,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB,OAAO,EAAE,MAAM,IAAI,CAAA;IACnB,+EAA+E;IAC/E,IAAI,CAAC,EAAE,eAAe,CAAA;CACvB,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,WAAW,GAAI,8GAWzB,gBAAgB,KAAG,SAmDrB,CAAA"}

package/dist/SearchInput/SearchInput.js

@@ -4,7 +4,6 @@ import { IconButton } from "../IconButton/IconButton.js";
 import { DISABLED_CLASS, FOCUS_RING_CLASS, } from "../intentStyles.js";
 import { toClassName } from "../toClassName.js";
 const INPUT_SIZE_CLASS = {
-    sm: "h-(--control-height-sm) ps-(--control-padding-inline-sm) pe-(--control-height-sm) text-sm",
     md: "h-(--control-height-md) ps-(--control-padding-inline-md) pe-(--control-height-md) text-md",
     lg: "h-(--control-height-lg) ps-(--control-padding-inline-lg) pe-(--control-height-lg) text-lg",
 };

package/dist/SearchInput/SearchInput.js.map

@@ -1 +1 @@
-{"version":3,"file":"SearchInput.js","sourceRoot":"","sources":["../../src/SearchInput/SearchInput.tsx"],"names":[],"mappings":";AACA,OAAO,EAGL,MAAM,GACP,MAAM,OAAO,CAAA;AAEd,OAAO,EAAE,UAAU,EAAE,MAAM,6BAA8B,CAAA;AACzD,OAAO,EACL,cAAc,EACd,gBAAgB,GACjB,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAE/C,MAAM,gBAAgB,GAAgC;IACpD,EAAE,EAAE,2FAA2F;IAC/F,EAAE,EAAE,2FAA2F;IAC/F,EAAE,EAAE,2FAA2F;CAChG,CAAA;AAeD;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,EAC1B,SAAS,EACT,SAAS,EACT,UAAU,GAAG,cAAc,EAC3B,YAAY,EACZ,cAAc,EACd,OAAO,EACP,GAAG,EACH,IAAI,GAAG,IAAI,EACX,KAAK,EACL,GAAG,UAAU,EACI,EAAa,EAAE;IAChC,MAAM,QAAQ,GAAG,MAAM,CAAmB,IAAI,CAAC,CAAA;IAC/C,MAAM,QAAQ,GACZ,cAAc;QACd,MAAM,CAAC,KAAK,IAAI,YAAY,IAAI,EAAE,CAAC,CAAC,MAAM,GAAG,CAAC,CAAA;IAEhD,MAAM,WAAW,GAAG,CAAC,IAA6B,EAAE,EAAE;QACpD,QAAQ,CAAC,OAAO,GAAG,IAAI,CAAA;QAEvB,IAAI,OAAO,GAAG,KAAK,UAAU;YAAE,GAAG,CAAC,IAAI,CAAC,CAAA;aACnC,IAAI,GAAG;YAAE,GAAG,CAAC,OAAO,GAAG,IAAI,CAAA;IAClC,CAAC,CAAA;IAED,OAAO,CACL,gBACE,SAAS,EAAE,WAAW,CAAC,gBAAgB,EAAE,SAAS,CAAC,aAEnD,mBACM,UAAU,EACd,SAAS,EAAE,WAAW,CACpB,+TAA+T,EAC/T,gBAAgB,CAAC,IAAI,CAAC,EACtB,gBAAgB,EAChB,cAAc,CACf,EACD,YAAY,EAAE,YAAY,EAC1B,GAAG,EAAE,WAAW,EAChB,IAAI,EAAC,QAAQ,EACb,KAAK,EAAE,KAAK,GACZ,EAED,QAAQ,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,CAClC,eAAM,SAAS,EAAC,4CAA4C,YAC1D,KAAC,UAAU,IACT,UAAU,EAAC,OAAO,EAClB,KAAK,EAAE,UAAU,EACjB,OAAO,EAAE,GAAG,EAAE;wBACZ,OAAO,EAAE,CAAA;wBACT,QAAQ,CAAC,OAAO,EAAE,KAAK,EAAE,CAAA;oBAC3B,CAAC,EACD,aAAa,EAAE,CAAC,KAAK,EAAE,EAAE,CACvB,KAAK,CAAC,cAAc,EAAE,EAExB,IAAI,EAAE,IAAI,YAET,SAAS,GACC,GACR,CACR,CAAC,CAAC,CAAC,IAAI,IACH,CACR,CAAA;AACH,CAAC,CAAA"}
+{"version":3,"file":"SearchInput.js","sourceRoot":"","sources":["../../src/SearchInput/SearchInput.tsx"],"names":[],"mappings":";AACA,OAAO,EAGL,MAAM,GACP,MAAM,OAAO,CAAA;AAEd,OAAO,EAAE,UAAU,EAAE,MAAM,6BAA8B,CAAA;AACzD,OAAO,EACL,cAAc,EACd,gBAAgB,GACjB,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAI/C,MAAM,gBAAgB,GAAoC;IACxD,EAAE,EAAE,2FAA2F;IAC/F,EAAE,EAAE,2FAA2F;CAChG,CAAA;AAgBD;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,EAC1B,SAAS,EACT,SAAS,EACT,UAAU,GAAG,cAAc,EAC3B,YAAY,EACZ,cAAc,EACd,OAAO,EACP,GAAG,EACH,IAAI,GAAG,IAAI,EACX,KAAK,EACL,GAAG,UAAU,EACI,EAAa,EAAE;IAChC,MAAM,QAAQ,GAAG,MAAM,CAAmB,IAAI,CAAC,CAAA;IAC/C,MAAM,QAAQ,GACZ,cAAc;QACd,MAAM,CAAC,KAAK,IAAI,YAAY,IAAI,EAAE,CAAC,CAAC,MAAM,GAAG,CAAC,CAAA;IAEhD,MAAM,WAAW,GAAG,CAAC,IAA6B,EAAE,EAAE;QACpD,QAAQ,CAAC,OAAO,GAAG,IAAI,CAAA;QAEvB,IAAI,OAAO,GAAG,KAAK,UAAU;YAAE,GAAG,CAAC,IAAI,CAAC,CAAA;aACnC,IAAI,GAAG;YAAE,GAAG,CAAC,OAAO,GAAG,IAAI,CAAA;IAClC,CAAC,CAAA;IAED,OAAO,CACL,gBACE,SAAS,EAAE,WAAW,CAAC,gBAAgB,EAAE,SAAS,CAAC,aAEnD,mBACM,UAAU,EACd,SAAS,EAAE,WAAW,CACpB,+TAA+T,EAC/T,gBAAgB,CAAC,IAAI,CAAC,EACtB,gBAAgB,EAChB,cAAc,CACf,EACD,YAAY,EAAE,YAAY,EAC1B,GAAG,EAAE,WAAW,EAChB,IAAI,EAAC,QAAQ,EACb,KAAK,EAAE,KAAK,GACZ,EAED,QAAQ,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,CAClC,eAAM,SAAS,EAAC,4CAA4C,YAC1D,KAAC,UAAU,IACT,UAAU,EAAC,OAAO,EAClB,KAAK,EAAE,UAAU,EACjB,OAAO,EAAE,GAAG,EAAE;wBACZ,OAAO,EAAE,CAAA;wBACT,QAAQ,CAAC,OAAO,EAAE,KAAK,EAAE,CAAA;oBAC3B,CAAC,EACD,aAAa,EAAE,CAAC,KAAK,EAAE,EAAE,CACvB,KAAK,CAAC,cAAc,EAAE,EAExB,IAAI,EAAE,IAAI,YAET,SAAS,GACC,GACR,CACR,CAAC,CAAC,CAAC,IAAI,IACH,CACR,CAAA;AACH,CAAC,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@charcuterie/ui",
-  "version": "3.29.0",
+  "version": "3.30.0",
   "description": "The Charcuterie components. Tokens for look, @charcuterie/logic for state, ARIA that agents can actually drive.",
   "license": "MIT",
   "type": "module",

package/src/Main/Main.mdx

@@ -147,3 +147,56 @@ region, so the table is announced as a thing rather than as loose content.
 `<main>` accepts focus so `Shell`'s skip link moves **focus** and not merely the scroll
 position. Without it, Safari and Firefox scroll to `<main>` and leave the next Tab back up
 in the header — which looks exactly like a skip link that works.
+
+## `scrollKey` — the reader's place, kept
+
+<Canvas of={MainStories.ScrollMemory} />
+
+`Shell` gives this element 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, and this is what it
+costs.
+
+**The browser will not put the offset back.** A browser remembers the **document scroller's**
+position per history entry, and `<main>` is not the document scroller. It also restores
+nothing at all across a same-document `pushState` navigation, which is every link press in a
+single-page app. So Back lands at the top of a list the reader had scrolled half-way down,
+`history.scrollRestoration` has no bearing on it, and there is no browser setting that
+changes it. The owner, on Docket:
+
+> "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?"
+
+Pass the history entry's key and it is:
+
+```tsx
+const location = useLocation()
+
+<Main scrollKey={location.key}>
+  <Outlet />
+</Main>
+```
+
+Omit it and nothing is remembered, which is right for a page with no history to remember.
+
+### It has to wait for the content
+
+<Canvas of={MainStories.ScrollMemoryWithLateContent} />
+
+A one-shot `scrollTop = offset` does **nothing** on a real page. The commit that changes the
+route draws a skeleton, the rows land a fetch later, and an offset written against an empty
+scrollport is clamped to `0` by the browser. Every check 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.
+
+So the restore re-applies through a `ResizeObserver` on the scrollport and on its content
+column, and stops at the first of three things:
+
+1. **The offset lands.** Anything past that would only fight the reader.
+2. **The reader scrolls.** Any `wheel`, `touchstart`, `keydown` or `pointerdown` on the
+   scrollport ends it, because a page that jumps out from under somebody who has already
+   started reading is a worse bug than the one being fixed.
+3. **Three seconds pass.** A page that slow has been read from the top already.
+
+The offsets live in memory, not in `sessionStorage`. A history key survives a reload; the DOM
+it described does not, and 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.