@charcuterie/ui 3.34.0 → 4.0.0

package/dist/Main/Main.d.ts

@@ -2,16 +2,6 @@ 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.
@@ -102,18 +92,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
@@ -143,5 +142,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, ref, scrollKey, ...mainProps }: MainProps) => ReactNode;
+export declare const Main: ({ children, className, contentWidth, id, ref, ...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":"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"}
+{"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;AAMjC,MAAM,MAAM,SAAS,GAAG,qBAAqB,CAAC,MAAM,CAAC,GAAG;IACtD,YAAY,CAAC,EAAE,YAAY,CAAA;CAC5B,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0IG;AACH,eAAO,MAAM,IAAI,GAAI,8DAOlB,SAAS,KAAG,SA0Dd,CAAA"}

package/dist/Main/Main.js

@@ -4,6 +4,7 @@ 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 { ScrollMemoryContext } from "./scrollMemoryContext.js";
 import { useScrollMemory } from "./useScrollMemory.js";
 /**
  * The `<main>` landmark and the content column.
@@ -94,18 +95,27 @@ import { useScrollMemory } from "./useScrollMemory.js";
  * 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
@@ -135,9 +145,10 @@ import { useScrollMemory } from "./useScrollMemory.js";
  * wrap, so a wide one goes in an `overflow-x-auto` wrapper, which
  * `Main.mdx` shows.
  */
-export const Main = ({ children, className, contentWidth, id, ref, scrollKey, ...mainProps }) => {
+export const Main = ({ children, className, contentWidth, id, ref, ...mainProps }) => {
     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.
     const fallbackId = useUniqueId();

package/dist/Main/Main.js.map

@@ -1 +1 @@
-{"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"}
+{"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,mBAAmB,EAAE,MAAM,0BAA0B,CAAA;AAC9D,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAMtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0IG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG,CAAC,EACnB,QAAQ,EACR,SAAS,EACT,YAAY,EACZ,EAAE,EACF,GAAG,EACH,GAAG,SAAS,EACF,EAAa,EAAE;IACzB,MAAM,KAAK,GAAG,UAAU,CAAC,YAAY,CAAC,CAAA;IACtC,MAAM,WAAW,GAAG,UAAU,CAAC,mBAAmB,CAAC,CAAA;IACnD,MAAM,aAAa,GAAG,eAAe,CAAC,WAAW,CAAC,CAAA;IAElD,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/ScrollMemoryProvider.d.ts

@@ -0,0 +1,38 @@
+import type { ReactNode } from "react";
+import type { ScrollEntry } from "./scrollMemory.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 declare const ScrollMemoryProvider: ({ children, entry, }: ScrollMemoryProviderProps) => ReactNode;
+//# sourceMappingURL=ScrollMemoryProvider.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ScrollMemoryProvider.d.ts","sourceRoot":"","sources":["../../src/Main/ScrollMemoryProvider.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAEtC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAGpD,MAAM,MAAM,yBAAyB,GAAG;IACtC,QAAQ,CAAC,EAAE,SAAS,CAAA;IACpB;;;OAGG;IACH,KAAK,EAAE,WAAW,CAAA;CACnB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,oBAAoB,GAAI,sBAGlC,yBAAyB,KAAG,SAI9B,CAAA"}

package/dist/Main/ScrollMemoryProvider.js

@@ -0,0 +1,30 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { ScrollMemoryContext } from "./scrollMemoryContext.js";
+/**
+ * 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, }) => (_jsx(ScrollMemoryContext.Provider, { value: entry, children: children }));
+//# sourceMappingURL=ScrollMemoryProvider.js.map

package/dist/Main/ScrollMemoryProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ScrollMemoryProvider.js","sourceRoot":"","sources":["../../src/Main/ScrollMemoryProvider.tsx"],"names":[],"mappings":";AAGA,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAA;AAW9D;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,EACnC,QAAQ,EACR,KAAK,GACqB,EAAa,EAAE,CAAC,CAC1C,KAAC,mBAAmB,CAAC,QAAQ,IAAC,KAAK,EAAE,KAAK,YACvC,QAAQ,GACoB,CAChC,CAAA"}

package/dist/Main/scrollMemory.d.ts

@@ -1,40 +1,66 @@
 /**
- * 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:
+ * 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
+ * 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.
  */
-export declare const rememberScrollOffset: (key: string, offset: number) => void;
+export type ScrollEntry = {
+    /** The history entry — react-router's `useLocation().key`. */
+    key: string;
+    /** The page it belongs to — `useLocation().pathname`. */
+    path: string;
+};
+export declare const rememberScrollOffset: (entry: ScrollEntry, 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.
+ * 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 declare const recallScrollOffset: (key: string) => number;
+export declare const resolveScrollOffset: (entry: ScrollEntry) => number | null;
+/** Called by the hook once it owns the scrollport for this entry. */
+export declare const enterScrollEntry: (entry: ScrollEntry) => void;
 /** 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

@@ -1 +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"}
+{"version":3,"file":"scrollMemory.d.ts","sourceRoot":"","sources":["../../src/Main/scrollMemory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAUH,MAAM,MAAM,WAAW,GAAG;IACxB,8DAA8D;IAC9D,GAAG,EAAE,MAAM,CAAA;IACX,yDAAyD;IACzD,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAkBD,eAAO,MAAM,oBAAoB,GAC/B,OAAO,WAAW,EAClB,QAAQ,MAAM,SAkBf,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,GAAI,OAAO,WAAW,kBAYrD,CAAA;AAED,qEAAqE;AACrE,eAAO,MAAM,gBAAgB,GAAI,OAAO,WAAW,SAElD,CAAA;AAED,iEAAiE;AACjE,eAAO,MAAM,mBAAmB,YAG/B,CAAA"}

package/dist/Main/scrollMemory.js

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

package/dist/Main/scrollMemory.js.map

@@ -1 +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"}
+{"version":3,"file":"scrollMemory.js","sourceRoot":"","sources":["../../src/Main/scrollMemory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAEH;;;;;GAKG;AACH,MAAM,sBAAsB,GAAG,EAAE,CAAA;AAcjC,MAAM,iBAAiB,GAAG,IAAI,GAAG,EAA2B,CAAA;AAE5D;;;;;;GAMG;AACH,IAAI,YAAY,GAAuB,IAAI,CAAA;AAE3C,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAClC,KAAkB,EAClB,MAAc,EACd,EAAE;IACF,kEAAkE;IAClE,8DAA8D;IAC9D,4CAA4C;IAC5C,iBAAiB,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;IACnC,iBAAiB,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,EAAE;QAC/B,MAAM;QACN,IAAI,EAAE,KAAK,CAAC,IAAI;KACjB,CAAC,CAAA;IAEF,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,mBAAmB,GAAG,CAAC,KAAkB,EAAE,EAAE;IACxD,MAAM,UAAU,GAAG,iBAAiB,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;IAEnD,IAAI,UAAU,EAAE,CAAC;QACf,OAAO,UAAU,CAAC,MAAM,CAAA;IAC1B,CAAC;IAED,MAAM,UAAU,GACd,YAAY,KAAK,IAAI;QACrB,YAAY,CAAC,IAAI,KAAK,KAAK,CAAC,IAAI,CAAA;IAElC,OAAO,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAA;AAC9B,CAAC,CAAA;AAED,qEAAqE;AACrE,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,KAAkB,EAAE,EAAE;IACrD,YAAY,GAAG,KAAK,CAAA;AACtB,CAAC,CAAA;AAED,iEAAiE;AACjE,MAAM,CAAC,MAAM,mBAAmB,GAAG,GAAG,EAAE;IACtC,iBAAiB,CAAC,KAAK,EAAE,CAAA;IACzB,YAAY,GAAG,IAAI,CAAA;AACrB,CAAC,CAAA"}

package/dist/Main/scrollMemoryContext.d.ts

@@ -0,0 +1,18 @@
+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 declare const ScrollMemoryContext: import("react").Context<ScrollEntry | null>;
+//# sourceMappingURL=scrollMemoryContext.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"scrollMemoryContext.d.ts","sourceRoot":"","sources":["../../src/Main/scrollMemoryContext.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAEpD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,mBAAmB,6CACS,CAAA"}

package/dist/Main/scrollMemoryContext.js

@@ -0,0 +1,18 @@
+import { createContext } from "react";
+/**
+ * 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(null);
+//# sourceMappingURL=scrollMemoryContext.js.map

package/dist/Main/scrollMemoryContext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scrollMemoryContext.js","sourceRoot":"","sources":["../../src/Main/scrollMemoryContext.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,OAAO,CAAA;AAIrC;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAC9B,aAAa,CAAqB,IAAI,CAAC,CAAA"}

package/dist/Main/useScrollMemory.d.ts

@@ -1,29 +1,31 @@
+import { type ScrollEntry } from "./scrollMemory.ts";
 /**
- * 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 declare const useScrollMemory: (scrollKey: string | undefined) => (node: unknown) => void;
+export declare const useScrollMemory: (entry: ScrollEntry | null | undefined) => (node: unknown) => void;
 //# sourceMappingURL=useScrollMemory.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"useScrollMemory.d.ts","sourceRoot":"","sources":["../../src/Main/useScrollMemory.ts"],"names":[],"mappings":"AAEA,OAAO,EAIL,KAAK,WAAW,EACjB,MAAM,mBAAmB,CAAA;AAwB1B;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,eAAe,GAC1B,OAAO,WAAW,GAAG,IAAI,GAAG,SAAS,YAaC,OAAO,SAkI9C,CAAA"}