@charcuterie/ui 3.29.1 → 3.31.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/Tabs/PanelTabs.d.ts

@@ -0,0 +1,56 @@
+import type { ReactNode } from "react";
+import type { TabsPanelProps } from "./Tabs.tsx";
+/**
+ * The panel bar — every tab a `<button>`, every section a
+ * `role="tabpanel"` this component renders and hides. See `Tabs`
+ * for which of the two bars a screen wants.
+ *
+ * The composition is two hooks and one decision:
+ *
+ * ```ts
+ * const selection = useSinglePicker({ selectedValue: initialKey })
+ * const focus = useRovingFocus({ activeValue: initialKey })
+ *
+ * // `automatic` is this line, and `manual` is its absence.
+ * if (activation === "automatic") selection.select(focus.activeValue)
+ * ```
+ *
+ * ### Selection, not visibility — and the difference is not cosmetic
+ *
+ * M4 built this on `VisibilityGroup`, and the panels do end up
+ * one-at-a-time either way, because the two cores are the same
+ * shape. But the thing that **registers** here is the tab, not the
+ * panel, and what a tab bar is asking is *which one did you pick*.
+ * `SinglePicker` is the kind that answers that; the panel's
+ * `hidden` is derived from the answer.
+ *
+ * Reading it the other way round cost something concrete: it made
+ * `aria-selected` a report about a *panel's* visibility, so a
+ * consumer wanting a tab bar with no panels at all — a segmented
+ * filter, a view switcher that swaps a route — had to model its
+ * choice as a group of visibilities it did not have. `Alert`'s
+ * sibling `SegmentedControl` is exactly that consumer, and it now
+ * shares this component's core rather than hand-rolling a fourth
+ * one.
+ * [Decision](../../../../docs/decisions/2026-07-30-tab-selection-is-a-single-picker.md).
+ *
+ * ### What it does not use, and why that is the right answer
+ *
+ * The plan expected `createLinkedIds` here as well. It does not
+ * fit, and forcing it would have been the wrong call: that kind
+ * exists for a **dynamic** trigger↔target pair — a `Popover` whose
+ * panel mounts and unmounts, where the multiset is what stops
+ * `aria-controls` pointing at a node React has already removed. A
+ * tab bar's pairing is static and known at render, so the ids come
+ * from one `useUniqueId` and cannot get out of step at all.
+ *
+ * ### Focus is moved deliberately, and only then
+ *
+ * `RovingFocus` is state; something still has to call `.focus()`.
+ * That happens only while the tablist already contains the focused
+ * element — otherwise mounting a tab bar, or any parent re-render
+ * that moved `activeValue`, yanks the caret out of whatever the
+ * user was actually doing.
+ */
+export declare const PanelTabs: ({ activation, activeKey, className, label, onChange, orientation, tabs, }: TabsPanelProps) => ReactNode;
+//# sourceMappingURL=PanelTabs.d.ts.map

package/dist/Tabs/PanelTabs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PanelTabs.d.ts","sourceRoot":"","sources":["../../src/Tabs/PanelTabs.tsx"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAItC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAgBhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,eAAO,MAAM,SAAS,GAAI,2EAQvB,cAAc,KAAG,SA6KnB,CAAA"}

package/dist/Tabs/PanelTabs.js

@@ -0,0 +1,163 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { selectTabIndex, useRovingFocus, useSinglePicker, useUniqueId, } from "@charcuterie/logic";
+import { useCallback, useEffect, useRef } from "react";
+import { toClassName } from "../toClassName.js";
+import { TabTrigger } from "./TabTrigger.js";
+import { toTabListClass } from "./tabStyles.js";
+const ORIENTATION_KEYS = {
+    horizontal: {
+        next: "ArrowRight",
+        previous: "ArrowLeft",
+    },
+    vertical: { next: "ArrowDown", previous: "ArrowUp" },
+};
+/**
+ * The panel bar — every tab a `<button>`, every section a
+ * `role="tabpanel"` this component renders and hides. See `Tabs`
+ * for which of the two bars a screen wants.
+ *
+ * The composition is two hooks and one decision:
+ *
+ * ```ts
+ * const selection = useSinglePicker({ selectedValue: initialKey })
+ * const focus = useRovingFocus({ activeValue: initialKey })
+ *
+ * // `automatic` is this line, and `manual` is its absence.
+ * if (activation === "automatic") selection.select(focus.activeValue)
+ * ```
+ *
+ * ### Selection, not visibility — and the difference is not cosmetic
+ *
+ * M4 built this on `VisibilityGroup`, and the panels do end up
+ * one-at-a-time either way, because the two cores are the same
+ * shape. But the thing that **registers** here is the tab, not the
+ * panel, and what a tab bar is asking is *which one did you pick*.
+ * `SinglePicker` is the kind that answers that; the panel's
+ * `hidden` is derived from the answer.
+ *
+ * Reading it the other way round cost something concrete: it made
+ * `aria-selected` a report about a *panel's* visibility, so a
+ * consumer wanting a tab bar with no panels at all — a segmented
+ * filter, a view switcher that swaps a route — had to model its
+ * choice as a group of visibilities it did not have. `Alert`'s
+ * sibling `SegmentedControl` is exactly that consumer, and it now
+ * shares this component's core rather than hand-rolling a fourth
+ * one.
+ * [Decision](../../../../docs/decisions/2026-07-30-tab-selection-is-a-single-picker.md).
+ *
+ * ### What it does not use, and why that is the right answer
+ *
+ * The plan expected `createLinkedIds` here as well. It does not
+ * fit, and forcing it would have been the wrong call: that kind
+ * exists for a **dynamic** trigger↔target pair — a `Popover` whose
+ * panel mounts and unmounts, where the multiset is what stops
+ * `aria-controls` pointing at a node React has already removed. A
+ * tab bar's pairing is static and known at render, so the ids come
+ * from one `useUniqueId` and cannot get out of step at all.
+ *
+ * ### Focus is moved deliberately, and only then
+ *
+ * `RovingFocus` is state; something still has to call `.focus()`.
+ * That happens only while the tablist already contains the focused
+ * element — otherwise mounting a tab bar, or any parent re-render
+ * that moved `activeValue`, yanks the caret out of whatever the
+ * user was actually doing.
+ */
+export const PanelTabs = ({ activation = "automatic", activeKey, className, label, onChange, orientation = "horizontal", tabs, }) => {
+    const baseId = useUniqueId();
+    const tablistRef = useRef(null);
+    const tabElements = useRef(new Map());
+    const initialKey = activeKey ??
+        tabs.find((one) => !one.isDisabled)?.key ??
+        null;
+    const selection = useSinglePicker({
+        onChange,
+        selectedValue: initialKey,
+    });
+    const focus = useRovingFocus({
+        activeValue: initialKey,
+    });
+    const { select } = selection;
+    const { activeValue, setActiveValue } = focus;
+    /**
+     * Selected **or** pending, and the fallback is load-bearing.
+     *
+     * Members register from an effect, so on the first paint
+     * `selectedValue` is still null and the intent lives in
+     * `pendingValue` — a tab bar reading only the former renders with
+     * no tab selected and no panel shown, then corrects itself a
+     * frame later. It is a flash on a fast machine and a visible
+     * blank on a kiosk Pi.
+     *
+     * The core distinguishes the two on purpose, which is why this
+     * belongs here rather than in the selector — unlike
+     * `RovingFocus`, where the equivalent first-paint hole was in
+     * `selectTabIndex` itself and got fixed there.
+     */
+    const shownKey = selection.selectedValue ?? selection.pendingValue;
+    const selectTab = useCallback((key) => {
+        // Both, because a pointer press moves focus *and* chooses.
+        // Only selecting would leave `automatic`'s effect below to
+        // put the old panel straight back.
+        setActiveValue(key);
+        select(key);
+    }, [select, setActiveValue]);
+    useEffect(() => {
+        // Automatic activation, and the only behaviour that differs
+        // between the two modes. `select` is idempotent, so this is a
+        // no-op on every render where focus did not actually move.
+        if (activation === "automatic" &&
+            activeValue !== null) {
+            select(activeValue);
+        }
+    }, [activation, activeValue, select]);
+    useEffect(() => {
+        const tablist = tablistRef.current;
+        if (!tablist ||
+            activeValue === null ||
+            !tablist.contains(document.activeElement)) {
+            return;
+        }
+        tabElements.current.get(activeValue)?.focus();
+    }, [activeValue]);
+    const keys = ORIENTATION_KEYS[orientation];
+    return (_jsxs("div", { className: toClassName("flex flex-col gap-3", className), children: [_jsx("div", { "aria-label": label, "aria-orientation": orientation, className: toTabListClass(orientation), onKeyDown: (keyEvent) => {
+                    const commands = {
+                        [keys.next]: focus.next,
+                        [keys.previous]: focus.previous,
+                        End: focus.last,
+                        Home: focus.first,
+                    };
+                    const command = commands[keyEvent.key];
+                    if (command) {
+                        // Arrow keys scroll the page by default, and a tab bar
+                        // that scrolls the window while it moves focus is the
+                        // hand-rolled version of this component.
+                        keyEvent.preventDefault();
+                        command();
+                        return;
+                    }
+                    // `manual`'s commit. In `automatic` the panel is showing
+                    // already, so this is the no-op that makes Enter behave
+                    // identically in both modes.
+                    if ((keyEvent.key === "Enter" ||
+                        keyEvent.key === " ") &&
+                        activeValue !== null) {
+                        keyEvent.preventDefault();
+                        select(activeValue);
+                    }
+                }, ref: tablistRef, role: "tablist", children: tabs.map((tab, index) => (_jsx(TabTrigger, { id: `${baseId}-tab-${index}`, isSelected: shownKey === tab.key, onSelect: selectTab, panelId: `${baseId}-panel-${index}`, registerFocus: focus.register, orientation: orientation, registerSelection: selection.register, tab: tab, 
+                    // The roving-tabindex rule read from the core rather
+                    // than restated here: exactly one member is in the tab
+                    // order, so Tab enters and leaves the bar once while
+                    // the arrow keys move inside it.
+                    tabIndex: selectTabIndex(focus, tab.key), trackElement: (key, element) => {
+                        if (element) {
+                            tabElements.current.set(key, element);
+                        }
+                        else {
+                            tabElements.current.delete(key);
+                        }
+                    } }, tab.key))) }), tabs.map((tab, index) => (_jsx("div", { "aria-labelledby": `${baseId}-tab-${index}`, hidden: shownKey !== tab.key, id: `${baseId}-panel-${index}`, role: "tabpanel", children: tab.content }, tab.key)))] }));
+};
+//# sourceMappingURL=PanelTabs.js.map