@charcuterie/ui 3.28.1 → 3.28.2

package/dist/VirtualizedGrid/ElementGrid.d.ts

@@ -0,0 +1,7 @@
+import type { GridWindowProps, ScrollOwner } from "./virtualizedGridTypes.ts";
+export declare const ElementGrid: <Item>(props: GridWindowProps<Item> & {
+    scrollOwner: Extract<ScrollOwner, {
+        kind: "element";
+    }>;
+}) => import("react").JSX.Element;
+//# sourceMappingURL=ElementGrid.d.ts.map

package/dist/VirtualizedGrid/ElementGrid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ElementGrid.d.ts","sourceRoot":"","sources":["../../src/VirtualizedGrid/ElementGrid.tsx"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,eAAe,EACf,WAAW,EACZ,MAAM,2BAA2B,CAAA;AAElC,eAAO,MAAM,WAAW,GAAI,IAAI,EAC9B,OAAO,eAAe,CAAC,IAAI,CAAC,GAAG;IAC7B,WAAW,EAAE,OAAO,CAAC,WAAW,EAAE;QAAE,IAAI,EAAE,SAAS,CAAA;KAAE,CAAC,CAAA;CACvD,gCA+BF,CAAA"}

package/dist/VirtualizedGrid/ElementGrid.js

@@ -0,0 +1,19 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useVirtualizer } from "@tanstack/react-virtual";
+import { useCallback } from "react";
+import { GridRows } from "./GridRows.js";
+import { useScrollMargin } from "./virtualizedGridScroll.js";
+export const ElementGrid = (props) => {
+    const { gridElement, scrollMargin } = useScrollMargin(props.scrollOwner);
+    const measureRow = useCallback((element) => element.getBoundingClientRect().height + props.gap, [props.gap]);
+    const rowVirtualizer = useVirtualizer({
+        count: props.rowCount,
+        estimateSize: () => props.itemBlockSize + props.gap,
+        getScrollElement: () => props.scrollOwner.element,
+        measureElement: measureRow,
+        overscan: props.overscanRows,
+        scrollMargin,
+    });
+    return (_jsx(GridRows, { ...props, gridElement: gridElement, measureElement: rowVirtualizer.measureElement, scrollMargin: scrollMargin, totalSize: rowVirtualizer.getTotalSize(), virtualRows: rowVirtualizer.getVirtualItems() }));
+};
+//# sourceMappingURL=ElementGrid.js.map

package/dist/VirtualizedGrid/ElementGrid.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ElementGrid.js","sourceRoot":"","sources":["../../src/VirtualizedGrid/ElementGrid.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAA;AACxD,OAAO,EAAE,WAAW,EAAE,MAAM,OAAO,CAAA;AAEnC,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAgB,CAAA;AACzC,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAA;AAM5D,MAAM,CAAC,MAAM,WAAW,GAAG,CACzB,KAEC,EACD,EAAE;IACF,MAAM,EAAE,WAAW,EAAE,YAAY,EAAE,GAAG,eAAe,CACnD,KAAK,CAAC,WAAW,CAClB,CAAA;IAED,MAAM,UAAU,GAAG,WAAW,CAC5B,CAAC,OAAgB,EAAE,EAAE,CACnB,OAAO,CAAC,qBAAqB,EAAE,CAAC,MAAM,GAAG,KAAK,CAAC,GAAG,EACpD,CAAC,KAAK,CAAC,GAAG,CAAC,CACZ,CAAA;IAED,MAAM,cAAc,GAAG,cAAc,CAAC;QACpC,KAAK,EAAE,KAAK,CAAC,QAAQ;QACrB,YAAY,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,aAAa,GAAG,KAAK,CAAC,GAAG;QACnD,gBAAgB,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,WAAW,CAAC,OAAO;QACjD,cAAc,EAAE,UAAU;QAC1B,QAAQ,EAAE,KAAK,CAAC,YAAY;QAC5B,YAAY;KACb,CAAC,CAAA;IAEF,OAAO,CACL,KAAC,QAAQ,OACH,KAAK,EACT,WAAW,EAAE,WAAW,EACxB,cAAc,EAAE,cAAc,CAAC,cAAc,EAC7C,YAAY,EAAE,YAAY,EAC1B,SAAS,EAAE,cAAc,CAAC,YAAY,EAAE,EACxC,WAAW,EAAE,cAAc,CAAC,eAAe,EAAE,GAC7C,CACH,CAAA;AACH,CAAC,CAAA"}

package/dist/VirtualizedGrid/GridRows.d.ts

@@ -0,0 +1,4 @@
+import type { GridRowsProps } from "./virtualizedGridTypes.ts";
+/** The shared markup. Only the scroll observer differs between the two owners. */
+export declare const GridRows: <Item>({ drawnColumns, gap, getItemKey, gridElement, items, label, measureElement, renderItem, scrollMargin, totalSize, virtualRows, }: GridRowsProps<Item>) => import("react").JSX.Element;
+//# sourceMappingURL=GridRows.d.ts.map

package/dist/VirtualizedGrid/GridRows.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GridRows.d.ts","sourceRoot":"","sources":["../../src/VirtualizedGrid/GridRows.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAA;AAE9D,kFAAkF;AAClF,eAAO,MAAM,QAAQ,GAAI,IAAI,EAAG,iIAY7B,aAAa,CAAC,IAAI,CAAC,gCAyErB,CAAA"}

package/dist/VirtualizedGrid/GridRows.js

@@ -0,0 +1,40 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { getContentMaxInlineSize } from "../AdaptiveGrid/chooseColumns.js";
+/** The shared markup. Only the scroll observer differs between the two owners. */
+export const GridRows = ({ drawnColumns, gap, getItemKey, gridElement, items, label, measureElement, renderItem, scrollMargin, totalSize, virtualRows, }) => {
+    const firstRow = virtualRows[0];
+    const lastRow = virtualRows[virtualRows.length - 1];
+    // Everything scrolled past, and everything still to come. The two
+    // numbers that stand in for the rows that do not exist.
+    const paddingBlockStart = firstRow?.start ?? 0;
+    const paddingBlockEnd = lastRow
+        ? Math.max(0, totalSize - lastRow.end)
+        : 0;
+    return (_jsx("ul", { "aria-label": label, className: "grid w-full list-none p-0 [&>*]:min-w-0", ref: gridElement, style: {
+            gap: `${gap}px`,
+            gridTemplateColumns: `repeat(${drawnColumns}, minmax(0, 1fr))`,
+            maxInlineSize: getContentMaxInlineSize({
+                columns: drawnColumns,
+            }),
+            // Offset by `scrollMargin` because `start` is measured
+            // from the top of the scroll owner, and this padding is
+            // measured from the top of the grid.
+            paddingBlockEnd: `${paddingBlockEnd}px`,
+            paddingBlockStart: `${Math.max(0, paddingBlockStart - scrollMargin)}px`,
+        }, children: virtualRows.flatMap((row) => {
+            const firstIndex = row.index * drawnColumns;
+            return items
+                .slice(firstIndex, firstIndex + drawnColumns)
+                .map((item, offset) => {
+                const index = firstIndex + offset;
+                return (_jsx("li", { "aria-posinset": index + 1, "aria-setsize": items.length, "data-index": row.index, 
+                    // Measured on the leading cell alone. A CSS grid
+                    // stretches every cell to its row's height, so
+                    // one is enough — and measuring all of them
+                    // would have the virtualizer record the same row
+                    // once per column.
+                    ref: offset === 0 ? measureElement : undefined, children: renderItem(item, index) }, getItemKey?.(item, index) ?? index));
+            });
+        }) }));
+};
+//# sourceMappingURL=GridRows.js.map

package/dist/VirtualizedGrid/GridRows.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GridRows.js","sourceRoot":"","sources":["../../src/VirtualizedGrid/GridRows.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,uBAAuB,EAAE,MAAM,kCAAkC,CAAA;AAG1E,kFAAkF;AAClF,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAQ,EAC9B,YAAY,EACZ,GAAG,EACH,UAAU,EACV,WAAW,EACX,KAAK,EACL,KAAK,EACL,cAAc,EACd,UAAU,EACV,YAAY,EACZ,SAAS,EACT,WAAW,GACS,EAAE,EAAE;IACxB,MAAM,QAAQ,GAAG,WAAW,CAAC,CAAC,CAAC,CAAA;IAC/B,MAAM,OAAO,GAAG,WAAW,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;IAEnD,kEAAkE;IAClE,wDAAwD;IACxD,MAAM,iBAAiB,GAAG,QAAQ,EAAE,KAAK,IAAI,CAAC,CAAA;IAE9C,MAAM,eAAe,GAAG,OAAO;QAC7B,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC;QACtC,CAAC,CAAC,CAAC,CAAA;IAEL,OAAO,CACL,2BACc,KAAK,EACjB,SAAS,EAAC,yCAAyC,EACnD,GAAG,EAAE,WAAW,EAChB,KAAK,EAAE;YACL,GAAG,EAAE,GAAG,GAAG,IAAI;YACf,mBAAmB,EAAE,UAAU,YAAY,mBAAmB;YAC9D,aAAa,EAAE,uBAAuB,CAAC;gBACrC,OAAO,EAAE,YAAY;aACtB,CAAC;YACF,uDAAuD;YACvD,wDAAwD;YACxD,qCAAqC;YACrC,eAAe,EAAE,GAAG,eAAe,IAAI;YACvC,iBAAiB,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,iBAAiB,GAAG,YAAY,CAAC,IAAI;SACxE,YAEA,WAAW,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,EAAE;YAC3B,MAAM,UAAU,GAAG,GAAG,CAAC,KAAK,GAAG,YAAY,CAAA;YAE3C,OAAO,KAAK;iBACT,KAAK,CAAC,UAAU,EAAE,UAAU,GAAG,YAAY,CAAC;iBAC5C,GAAG,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE;gBACpB,MAAM,KAAK,GAAG,UAAU,GAAG,MAAM,CAAA;gBAEjC,OAAO,CACL,8BACiB,KAAK,GAAG,CAAC,kBACV,KAAK,CAAC,MAAM,gBAcd,GAAG,CAAC,KAAK;oBAErB,iDAAiD;oBACjD,+CAA+C;oBAC/C,4CAA4C;oBAC5C,iDAAiD;oBACjD,mBAAmB;oBACnB,GAAG,EACD,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,SAAS,YAG1C,UAAU,CAAC,IAAI,EAAE,KAAK,CAAC,IAVnB,UAAU,EAAE,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,KAAK,CAWpC,CACN,CAAA;YACH,CAAC,CAAC,CAAA;QACN,CAAC,CAAC,GACC,CACN,CAAA;AACH,CAAC,CAAA"}

package/dist/VirtualizedGrid/VirtualizedGrid.d.ts

@@ -123,15 +123,13 @@ export type VirtualizedGridProps<Item> = {
  * idea of the distance from one row to the next and the browser's
  * the same number.
  *
- * ### Why the window and not a scroll box of its own
+ * ### It follows the page's existing scroll owner
  *
- * `useWindowVirtualizer`, so the page scrolls the way every other
- * page in the fleet scrolls — the header leaves, the scrollbar is
- * the browser's, `Ctrl+End` works. A component that grew its own
- * `overflow: auto` well would trap the wheel and strand the page
- * header above it. The cost is `scrollMargin`: the virtualizer has
- * to be told how far down the document the grid starts, which is
- * measured below.
+ * A standalone grid follows the browser window. Inside `Shell`, it
+ * follows `Main`, which is the shell's one vertical scroll region.
+ * It never creates a scroll box of its own. The cost is
+ * `scrollMargin`: the virtualizer has to be told how far down its
+ * scroll owner the grid starts, which is measured below.
  *
  * ### What windowing costs, and what is done about it
  *

package/dist/VirtualizedGrid/VirtualizedGrid.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"VirtualizedGrid.d.ts","sourceRoot":"","sources":["../../src/VirtualizedGrid/VirtualizedGrid.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAStC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uCAAuC,CAAA;AAK9E,MAAM,MAAM,oBAAoB,CAAC,IAAI,IAAI;IACvC;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,iBAAiB,CAAA;IACrC;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,kDAAkD;IAClD,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ;;;;;OAKG;IACH,UAAU,CAAC,EAAE,CACX,IAAI,EAAE,IAAI,EACV,KAAK,EAAE,MAAM,KACV,MAAM,GAAG,MAAM,CAAA;IACpB;;;;;;;;OAQG;IACH,aAAa,EAAE,MAAM,CAAA;IACrB,kCAAkC;IAClC,KAAK,EAAE,SAAS,IAAI,EAAE,CAAA;IACtB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,uDAAuD;IACvD,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,gDAAgD;IAChD,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,qBAAqB;IACrB,UAAU,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,KAAK,SAAS,CAAA;IACpD;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyEG;AACH,eAAO,MAAM,eAAe,GAAI,IAAI,EAAG,kLAepC,oBAAoB,CAAC,IAAI,CAAC,KAAG,SAkK/B,CAAA"}
+{"version":3,"file":"VirtualizedGrid.d.ts","sourceRoot":"","sources":["../../src/VirtualizedGrid/VirtualizedGrid.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAGtC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uCAAuC,CAAA;AAY9E,MAAM,MAAM,oBAAoB,CAAC,IAAI,IAAI;IACvC;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,iBAAiB,CAAA;IACrC;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,kDAAkD;IAClD,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ;;;;;OAKG;IACH,UAAU,CAAC,EAAE,CACX,IAAI,EAAE,IAAI,EACV,KAAK,EAAE,MAAM,KACV,MAAM,GAAG,MAAM,CAAA;IACpB;;;;;;;;OAQG;IACH,aAAa,EAAE,MAAM,CAAA;IACrB,kCAAkC;IAClC,KAAK,EAAE,SAAS,IAAI,EAAE,CAAA;IACtB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,uDAAuD;IACvD,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,gDAAgD;IAChD,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,qBAAqB;IACrB,UAAU,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,KAAK,SAAS,CAAA;IACpD;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuEG;AACH,eAAO,MAAM,eAAe,GAAI,IAAI,EAAG,kLAepC,oBAAoB,CAAC,IAAI,CAAC,KAAG,SAgE/B,CAAA"}

package/dist/VirtualizedGrid/VirtualizedGrid.js

@@ -1,10 +1,11 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { useWindowVirtualizer } from "@tanstack/react-virtual";
-import { useCallback, useLayoutEffect, useRef, useState, } from "react";
-import { getContentMaxInlineSize } from "../AdaptiveGrid/chooseColumns.js";
+import { useLayoutEffect, useState } from "react";
 import { useAdaptiveColumns } from "../AdaptiveGrid/useAdaptiveColumns.js";
 import { toClassName } from "../toClassName.js";
+import { ElementGrid } from "./ElementGrid.js";
 import { DEFAULT_GRID_GAP_PX } from "./gridGap.js";
+import { findScrollOwner } from "./virtualizedGridScroll.js";
+import { WindowGrid } from "./WindowGrid.js";
 /**
  * `AdaptiveGrid`'s layout, with only the rows you can see mounted.
  *
@@ -59,15 +60,13 @@ import { DEFAULT_GRID_GAP_PX } from "./gridGap.js";
  * idea of the distance from one row to the next and the browser's
  * the same number.
  *
- * ### Why the window and not a scroll box of its own
+ * ### It follows the page's existing scroll owner
  *
- * `useWindowVirtualizer`, so the page scrolls the way every other
- * page in the fleet scrolls — the header leaves, the scrollbar is
- * the browser's, `Ctrl+End` works. A component that grew its own
- * `overflow: auto` well would trap the wheel and strand the page
- * header above it. The cost is `scrollMargin`: the virtualizer has
- * to be told how far down the document the grid starts, which is
- * measured below.
+ * A standalone grid follows the browser window. Inside `Shell`, it
+ * follows `Main`, which is the shell's one vertical scroll region.
+ * It never creates a scroll box of its own. The cost is
+ * `scrollMargin`: the virtualizer has to be told how far down its
+ * scroll owner the grid starts, which is measured below.
  *
  * ### What windowing costs, and what is done about it
  *
@@ -90,88 +89,32 @@ export const VirtualizedGrid = ({ blockSizeResolver, chromeBlockSize, className,
         storageKey,
     });
     const drawnColumns = columns ?? layout.columns;
-    // Folded from what is DRAWN rather than read off the hook, so an
-    // override widens the page cap with it — the same rule
-    // `AdaptiveGrid` follows, and wrong in the same way if it does
-    // not.
-    const contentMaxInlineSize = getContentMaxInlineSize({
-        columns: drawnColumns,
-    });
     const rowCount = Math.ceil(items.length / drawnColumns);
     /**
-     * How far down the document the grid starts.
-     *
-     * `useWindowVirtualizer` measures against the document, so
-     * without this every row is placed as though the grid began at
-     * the top of the page, and the whole list sits shifted by the
-     * height of the header above it.
-     *
-     * State and not a ref, because it feeds `scrollMargin` and a
-     * change has to re-render. Measured on every commit rather than
-     * on a dependency list: a filter row that grows a line moves the
-     * grid down the page, and nothing in this component's own props
-     * would report that.
+     * Main owns vertical scrolling inside an app Shell. Older pages
+     * and a standalone grid still use the window. Resolve the owner
+     * from the actual tree rather than making every app wire a ref
+     * between two Charcuterie components.
      */
-    const gridElement = useRef(null);
-    const [scrollMargin, setScrollMargin] = useState(0);
+    const [scrollOwner, setScrollOwner] = useState(null);
     useLayoutEffect(() => {
-        const element = gridElement.current;
+        const element = layout.containerRef.current;
         if (!element) {
             return;
         }
-        const next = element.getBoundingClientRect().top + window.scrollY;
-        setScrollMargin((current) => current === next ? current : next);
-    });
-    /**
-     * A row's height, plus the gap that follows it.
-     *
-     * The gap is added here rather than left to the estimate because
-     * it is real distance the next row starts after: leave it out
-     * and the virtualizer's offsets drift by one gap per row, which
-     * on a list of two thousand is a scrollbar off by half a page.
-     */
-    const measureRow = useCallback((element) => element.getBoundingClientRect().height + gap, [gap]);
-    const rowVirtualizer = useWindowVirtualizer({
-        count: rowCount,
-        estimateSize: () => itemBlockSize + gap,
-        measureElement: measureRow,
-        overscan: overscanRows,
-        scrollMargin,
-    });
-    const virtualRows = rowVirtualizer.getVirtualItems();
-    const firstRow = virtualRows[0];
-    const lastRow = virtualRows[virtualRows.length - 1];
-    // Everything scrolled past, and everything still to come. The two
-    // numbers that stand in for the rows that do not exist.
-    const paddingBlockStart = firstRow?.start ?? 0;
-    const paddingBlockEnd = lastRow
-        ? Math.max(0, rowVirtualizer.getTotalSize() - lastRow.end)
-        : 0;
-    return (_jsx("div", { className: toClassName("flex justify-center", className), ref: layout.containerRef, children: _jsx("ul", { "aria-label": label, className: "grid w-full list-none p-0 [&>*]:min-w-0", ref: gridElement, style: {
-                gap: `${gap}px`,
-                gridTemplateColumns: `repeat(${drawnColumns}, minmax(0, 1fr))`,
-                maxInlineSize: contentMaxInlineSize,
-                // Offset by `scrollMargin` because `start` is measured
-                // from the top of the document, and this padding is
-                // measured from the top of the grid.
-                paddingBlockEnd: `${paddingBlockEnd}px`,
-                paddingBlockStart: `${Math.max(0, paddingBlockStart - scrollMargin)}px`,
-            }, children: virtualRows.flatMap((row) => {
-                const firstIndex = row.index * drawnColumns;
-                return items
-                    .slice(firstIndex, firstIndex + drawnColumns)
-                    .map((item, offset) => {
-                    const index = firstIndex + offset;
-                    return (_jsx("li", { "aria-posinset": index + 1, "aria-setsize": items.length, "data-index": row.index, 
-                        // Measured on the leading cell alone. A CSS grid
-                        // stretches every cell to its row's height, so
-                        // one is enough — and measuring all of them
-                        // would have the virtualizer record the same row
-                        // once per column.
-                        ref: offset === 0
-                            ? rowVirtualizer.measureElement
-                            : undefined, children: renderItem(item, index) }, getItemKey?.(item, index) ?? index));
-                });
-            }) }) }));
+        setScrollOwner(findScrollOwner(element));
+    }, [layout.containerRef]);
+    const gridProps = {
+        drawnColumns,
+        gap,
+        getItemKey,
+        itemBlockSize,
+        items,
+        label,
+        overscanRows,
+        renderItem,
+        rowCount,
+    };
+    return (_jsx("div", { className: toClassName("flex justify-center", className), ref: layout.containerRef, children: scrollOwner?.kind === "element" ? (_jsx(ElementGrid, { ...gridProps, scrollOwner: scrollOwner })) : scrollOwner?.kind === "window" ? (_jsx(WindowGrid, { ...gridProps })) : null }));
 };
 //# sourceMappingURL=VirtualizedGrid.js.map

package/dist/VirtualizedGrid/VirtualizedGrid.js.map

@@ -1 +1 @@
-{"version":3,"file":"VirtualizedGrid.js","sourceRoot":"","sources":["../../src/VirtualizedGrid/VirtualizedGrid.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"VirtualizedGrid.js","sourceRoot":"","sources":["../../src/VirtualizedGrid/VirtualizedGrid.tsx"],"names":[],"mappings":";AACA,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAA;AAGjD,OAAO,EAAE,kBAAkB,EAAE,MAAM,uCAAuC,CAAA;AAC1E,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAmB,CAAA;AAC/C,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAA;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAA;AAK5D,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAkB,CAAA;AA2E7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuEG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAQ,EACrC,iBAAiB,EACjB,eAAe,EACf,SAAS,EACT,OAAO,EACP,GAAG,GAAG,mBAAmB,EACzB,UAAU,EACV,aAAa,EACb,KAAK,EACL,KAAK,EACL,UAAU,EACV,mBAAmB,EACnB,YAAY,GAAG,CAAC,EAChB,UAAU,EACV,UAAU,GACiB,EAAa,EAAE;IAC1C,MAAM,MAAM,GAAG,kBAAkB,CAAC;QAChC,iBAAiB;QACjB,eAAe;QACf,aAAa;QACb,SAAS,EAAE,KAAK,CAAC,MAAM;QACvB,cAAc,EAAE,UAAU;QAC1B,mBAAmB;QACnB,UAAU;KACX,CAAC,CAAA;IAEF,MAAM,YAAY,GAAG,OAAO,IAAI,MAAM,CAAC,OAAO,CAAA;IAE9C,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,YAAY,CAAC,CAAA;IAEvD;;;;;OAKG;IACH,MAAM,CAAC,WAAW,EAAE,cAAc,CAAC,GACjC,QAAQ,CAAqB,IAAI,CAAC,CAAA;IAEpC,eAAe,CAAC,GAAG,EAAE;QACnB,MAAM,OAAO,GAAG,MAAM,CAAC,YAAY,CAAC,OAAO,CAAA;QAE3C,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAM;QACR,CAAC;QAED,cAAc,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC,CAAA;IAC1C,CAAC,EAAE,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,CAAA;IAEzB,MAAM,SAAS,GAA0B;QACvC,YAAY;QACZ,GAAG;QACH,UAAU;QACV,aAAa;QACb,KAAK;QACL,KAAK;QACL,YAAY;QACZ,UAAU;QACV,QAAQ;KACT,CAAA;IAED,OAAO,CACL,cACE,SAAS,EAAE,WAAW,CACpB,qBAAqB,EACrB,SAAS,CACV,EACD,GAAG,EAAE,MAAM,CAAC,YAAY,YAEvB,WAAW,EAAE,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,CACjC,KAAC,WAAW,OACN,SAAS,EACb,WAAW,EAAE,WAAW,GACxB,CACH,CAAC,CAAC,CAAC,WAAW,EAAE,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,CACnC,KAAC,UAAU,OAAK,SAAS,GAAI,CAC9B,CAAC,CAAC,CAAC,IAAI,GACJ,CACP,CAAA;AACH,CAAC,CAAA"}

package/dist/VirtualizedGrid/WindowGrid.d.ts

@@ -0,0 +1,3 @@
+import type { GridWindowProps } from "./virtualizedGridTypes.ts";
+export declare const WindowGrid: <Item>(props: GridWindowProps<Item>) => import("react").JSX.Element;
+//# sourceMappingURL=WindowGrid.d.ts.map

package/dist/VirtualizedGrid/WindowGrid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WindowGrid.d.ts","sourceRoot":"","sources":["../../src/VirtualizedGrid/WindowGrid.tsx"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAA;AAEhE,eAAO,MAAM,UAAU,GAAI,IAAI,EAC7B,OAAO,eAAe,CAAC,IAAI,CAAC,gCA8B7B,CAAA"}

package/dist/VirtualizedGrid/WindowGrid.js

@@ -0,0 +1,20 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useWindowVirtualizer } from "@tanstack/react-virtual";
+import { useCallback } from "react";
+import { GridRows } from "./GridRows.js";
+import { useScrollMargin } from "./virtualizedGridScroll.js";
+export const WindowGrid = (props) => {
+    const { gridElement, scrollMargin } = useScrollMargin({
+        kind: "window",
+    });
+    const measureRow = useCallback((element) => element.getBoundingClientRect().height + props.gap, [props.gap]);
+    const rowVirtualizer = useWindowVirtualizer({
+        count: props.rowCount,
+        estimateSize: () => props.itemBlockSize + props.gap,
+        measureElement: measureRow,
+        overscan: props.overscanRows,
+        scrollMargin,
+    });
+    return (_jsx(GridRows, { ...props, gridElement: gridElement, measureElement: rowVirtualizer.measureElement, scrollMargin: scrollMargin, totalSize: rowVirtualizer.getTotalSize(), virtualRows: rowVirtualizer.getVirtualItems() }));
+};
+//# sourceMappingURL=WindowGrid.js.map

package/dist/VirtualizedGrid/WindowGrid.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"WindowGrid.js","sourceRoot":"","sources":["../../src/VirtualizedGrid/WindowGrid.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAA;AAC9D,OAAO,EAAE,WAAW,EAAE,MAAM,OAAO,CAAA;AAEnC,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAgB,CAAA;AACzC,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAA;AAG5D,MAAM,CAAC,MAAM,UAAU,GAAG,CACxB,KAA4B,EAC5B,EAAE;IACF,MAAM,EAAE,WAAW,EAAE,YAAY,EAAE,GAAG,eAAe,CAAC;QACpD,IAAI,EAAE,QAAQ;KACf,CAAC,CAAA;IAEF,MAAM,UAAU,GAAG,WAAW,CAC5B,CAAC,OAAgB,EAAE,EAAE,CACnB,OAAO,CAAC,qBAAqB,EAAE,CAAC,MAAM,GAAG,KAAK,CAAC,GAAG,EACpD,CAAC,KAAK,CAAC,GAAG,CAAC,CACZ,CAAA;IAED,MAAM,cAAc,GAAG,oBAAoB,CAAC;QAC1C,KAAK,EAAE,KAAK,CAAC,QAAQ;QACrB,YAAY,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,aAAa,GAAG,KAAK,CAAC,GAAG;QACnD,cAAc,EAAE,UAAU;QAC1B,QAAQ,EAAE,KAAK,CAAC,YAAY;QAC5B,YAAY;KACb,CAAC,CAAA;IAEF,OAAO,CACL,KAAC,QAAQ,OACH,KAAK,EACT,WAAW,EAAE,WAAW,EACxB,cAAc,EAAE,cAAc,CAAC,cAAc,EAC7C,YAAY,EAAE,YAAY,EAC1B,SAAS,EAAE,cAAc,CAAC,YAAY,EAAE,EACxC,WAAW,EAAE,cAAc,CAAC,eAAe,EAAE,GAC7C,CACH,CAAA;AACH,CAAC,CAAA"}

package/dist/VirtualizedGrid/virtualizedGridScroll.d.ts

@@ -0,0 +1,25 @@
+import type { ScrollOwner } from "./virtualizedGridTypes.ts";
+/**
+ * The closest ancestor that owns vertical scrolling.
+ *
+ * The computed value is enough. An `overflow-y:auto` ancestor can
+ * be shorter than its contents only AFTER this grid installs its
+ * virtual spacer, so requiring `scrollHeight > clientHeight` here
+ * would miss the owner on the first commit and create the exact
+ * document scrollbar this lookup prevents.
+ */
+export declare const findScrollOwner: (element: HTMLElement) => ScrollOwner;
+/**
+ * The offset from the scroll owner's content origin to the grid.
+ *
+ * Both formulas stay stable while their owner scrolls: the grid's
+ * viewport-relative top falls by the same amount that `scrollY` or
+ * `scrollTop` rises. The element path subtracts its border because
+ * a scroll offset starts at the padding edge, not at the outer
+ * border returned by `getBoundingClientRect()`.
+ */
+export declare const useScrollMargin: (scrollOwner: ScrollOwner) => {
+    gridElement: import("react").RefObject<HTMLUListElement | null>;
+    scrollMargin: number;
+};
+//# sourceMappingURL=virtualizedGridScroll.d.ts.map

package/dist/VirtualizedGrid/virtualizedGridScroll.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"virtualizedGridScroll.d.ts","sourceRoot":"","sources":["../../src/VirtualizedGrid/virtualizedGridScroll.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAA;AAE5D;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe,GAC1B,SAAS,WAAW,KACnB,WAcF,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe,GAC1B,aAAa,WAAW;;;CA2BzB,CAAA"}

package/dist/VirtualizedGrid/virtualizedGridScroll.js

@@ -0,0 +1,50 @@
+import { useLayoutEffect, useRef, useState } from "react";
+/**
+ * The closest ancestor that owns vertical scrolling.
+ *
+ * The computed value is enough. An `overflow-y:auto` ancestor can
+ * be shorter than its contents only AFTER this grid installs its
+ * virtual spacer, so requiring `scrollHeight > clientHeight` here
+ * would miss the owner on the first commit and create the exact
+ * document scrollbar this lookup prevents.
+ */
+export const findScrollOwner = (element) => {
+    let ancestor = element.parentElement;
+    while (ancestor) {
+        const overflow = getComputedStyle(ancestor).overflowY;
+        if (overflow === "auto" || overflow === "scroll") {
+            return { element: ancestor, kind: "element" };
+        }
+        ancestor = ancestor.parentElement;
+    }
+    return { kind: "window" };
+};
+/**
+ * The offset from the scroll owner's content origin to the grid.
+ *
+ * Both formulas stay stable while their owner scrolls: the grid's
+ * viewport-relative top falls by the same amount that `scrollY` or
+ * `scrollTop` rises. The element path subtracts its border because
+ * a scroll offset starts at the padding edge, not at the outer
+ * border returned by `getBoundingClientRect()`.
+ */
+export const useScrollMargin = (scrollOwner) => {
+    const gridElement = useRef(null);
+    const [scrollMargin, setScrollMargin] = useState(0);
+    useLayoutEffect(() => {
+        const element = gridElement.current;
+        if (!element) {
+            return;
+        }
+        const gridTop = element.getBoundingClientRect().top;
+        const next = scrollOwner.kind === "window"
+            ? gridTop + window.scrollY
+            : gridTop -
+                scrollOwner.element.getBoundingClientRect().top -
+                scrollOwner.element.clientTop +
+                scrollOwner.element.scrollTop;
+        setScrollMargin((current) => current === next ? current : next);
+    });
+    return { gridElement, scrollMargin };
+};
+//# sourceMappingURL=virtualizedGridScroll.js.map

package/dist/VirtualizedGrid/virtualizedGridScroll.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"virtualizedGridScroll.js","sourceRoot":"","sources":["../../src/VirtualizedGrid/virtualizedGridScroll.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAA;AAIzD;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAC7B,OAAoB,EACP,EAAE;IACf,IAAI,QAAQ,GAAG,OAAO,CAAC,aAAa,CAAA;IAEpC,OAAO,QAAQ,EAAE,CAAC;QAChB,MAAM,QAAQ,GAAG,gBAAgB,CAAC,QAAQ,CAAC,CAAC,SAAS,CAAA;QAErD,IAAI,QAAQ,KAAK,MAAM,IAAI,QAAQ,KAAK,QAAQ,EAAE,CAAC;YACjD,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,SAAS,EAAE,CAAA;QAC/C,CAAC;QAED,QAAQ,GAAG,QAAQ,CAAC,aAAa,CAAA;IACnC,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAA;AAC3B,CAAC,CAAA;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAC7B,WAAwB,EACxB,EAAE;IACF,MAAM,WAAW,GAAG,MAAM,CAAmB,IAAI,CAAC,CAAA;IAClD,MAAM,CAAC,YAAY,EAAE,eAAe,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAA;IAEnD,eAAe,CAAC,GAAG,EAAE;QACnB,MAAM,OAAO,GAAG,WAAW,CAAC,OAAO,CAAA;QAEnC,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAM;QACR,CAAC;QAED,MAAM,OAAO,GAAG,OAAO,CAAC,qBAAqB,EAAE,CAAC,GAAG,CAAA;QACnD,MAAM,IAAI,GACR,WAAW,CAAC,IAAI,KAAK,QAAQ;YAC3B,CAAC,CAAC,OAAO,GAAG,MAAM,CAAC,OAAO;YAC1B,CAAC,CAAC,OAAO;gBACP,WAAW,CAAC,OAAO,CAAC,qBAAqB,EAAE,CAAC,GAAG;gBAC/C,WAAW,CAAC,OAAO,CAAC,SAAS;gBAC7B,WAAW,CAAC,OAAO,CAAC,SAAS,CAAA;QAEnC,eAAe,CAAC,CAAC,OAAO,EAAE,EAAE,CAC1B,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAClC,CAAA;IACH,CAAC,CAAC,CAAA;IAEF,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,CAAA;AACtC,CAAC,CAAA"}

package/dist/VirtualizedGrid/virtualizedGridTypes.d.ts

@@ -0,0 +1,27 @@
+import type { VirtualItem } from "@tanstack/react-virtual";
+import type { ReactNode, RefObject } from "react";
+export type ScrollOwner = {
+    kind: "element";
+    element: HTMLElement;
+} | {
+    kind: "window";
+};
+export type GridWindowProps<Item> = {
+    drawnColumns: number;
+    gap: number;
+    getItemKey?: (item: Item, index: number) => string | number;
+    itemBlockSize: number;
+    items: readonly Item[];
+    label?: string;
+    overscanRows: number;
+    renderItem: (item: Item, index: number) => ReactNode;
+    rowCount: number;
+};
+export type GridRowsProps<Item> = Omit<GridWindowProps<Item>, "itemBlockSize" | "overscanRows" | "rowCount"> & {
+    gridElement: RefObject<HTMLUListElement | null>;
+    measureElement: (element: Element | null) => void;
+    scrollMargin: number;
+    totalSize: number;
+    virtualRows: VirtualItem[];
+};
+//# sourceMappingURL=virtualizedGridTypes.d.ts.map

package/dist/VirtualizedGrid/virtualizedGridTypes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"virtualizedGridTypes.d.ts","sourceRoot":"","sources":["../../src/VirtualizedGrid/virtualizedGridTypes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA;AAC1D,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAEjD,MAAM,MAAM,WAAW,GACnB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,WAAW,CAAA;CAAE,GACzC;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAA;AAEtB,MAAM,MAAM,eAAe,CAAC,IAAI,IAAI;IAClC,YAAY,EAAE,MAAM,CAAA;IACpB,GAAG,EAAE,MAAM,CAAA;IACX,UAAU,CAAC,EAAE,CACX,IAAI,EAAE,IAAI,EACV,KAAK,EAAE,MAAM,KACV,MAAM,GAAG,MAAM,CAAA;IACpB,aAAa,EAAE,MAAM,CAAA;IACrB,KAAK,EAAE,SAAS,IAAI,EAAE,CAAA;IACtB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,YAAY,EAAE,MAAM,CAAA;IACpB,UAAU,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,KAAK,SAAS,CAAA;IACpD,QAAQ,EAAE,MAAM,CAAA;CACjB,CAAA;AAED,MAAM,MAAM,aAAa,CAAC,IAAI,IAAI,IAAI,CACpC,eAAe,CAAC,IAAI,CAAC,EACrB,eAAe,GAAG,cAAc,GAAG,UAAU,CAC9C,GAAG;IACF,WAAW,EAAE,SAAS,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAA;IAC/C,cAAc,EAAE,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,KAAK,IAAI,CAAA;IACjD,YAAY,EAAE,MAAM,CAAA;IACpB,SAAS,EAAE,MAAM,CAAA;IACjB,WAAW,EAAE,WAAW,EAAE,CAAA;CAC3B,CAAA"}

package/dist/VirtualizedGrid/virtualizedGridTypes.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=virtualizedGridTypes.js.map

package/dist/VirtualizedGrid/virtualizedGridTypes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"virtualizedGridTypes.js","sourceRoot":"","sources":["../../src/VirtualizedGrid/virtualizedGridTypes.ts"],"names":[],"mappings":""}

package/package.json

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

package/src/VirtualizedGrid/ElementGrid.tsx

@@ -0,0 +1,45 @@
+import { useVirtualizer } from "@tanstack/react-virtual"
+import { useCallback } from "react"
+
+import { GridRows } from "./GridRows.tsx"
+import { useScrollMargin } from "./virtualizedGridScroll.ts"
+import type {
+  GridWindowProps,
+  ScrollOwner,
+} from "./virtualizedGridTypes.ts"
+
+export const ElementGrid = <Item,>(
+  props: GridWindowProps<Item> & {
+    scrollOwner: Extract<ScrollOwner, { kind: "element" }>
+  },
+) => {
+  const { gridElement, scrollMargin } = useScrollMargin(
+    props.scrollOwner,
+  )
+
+  const measureRow = useCallback(
+    (element: Element) =>
+      element.getBoundingClientRect().height + props.gap,
+    [props.gap],
+  )
+
+  const rowVirtualizer = useVirtualizer({
+    count: props.rowCount,
+    estimateSize: () => props.itemBlockSize + props.gap,
+    getScrollElement: () => props.scrollOwner.element,
+    measureElement: measureRow,
+    overscan: props.overscanRows,
+    scrollMargin,
+  })
+
+  return (
+    <GridRows
+      {...props}
+      gridElement={gridElement}
+      measureElement={rowVirtualizer.measureElement}
+      scrollMargin={scrollMargin}
+      totalSize={rowVirtualizer.getTotalSize()}
+      virtualRows={rowVirtualizer.getVirtualItems()}
+    />
+  )
+}

package/src/VirtualizedGrid/GridRows.tsx

@@ -0,0 +1,90 @@
+import { getContentMaxInlineSize } from "../AdaptiveGrid/chooseColumns.ts"
+import type { GridRowsProps } from "./virtualizedGridTypes.ts"
+
+/** The shared markup. Only the scroll observer differs between the two owners. */
+export const GridRows = <Item,>({
+  drawnColumns,
+  gap,
+  getItemKey,
+  gridElement,
+  items,
+  label,
+  measureElement,
+  renderItem,
+  scrollMargin,
+  totalSize,
+  virtualRows,
+}: GridRowsProps<Item>) => {
+  const firstRow = virtualRows[0]
+  const lastRow = virtualRows[virtualRows.length - 1]
+
+  // Everything scrolled past, and everything still to come. The two
+  // numbers that stand in for the rows that do not exist.
+  const paddingBlockStart = firstRow?.start ?? 0
+
+  const paddingBlockEnd = lastRow
+    ? Math.max(0, totalSize - lastRow.end)
+    : 0
+
+  return (
+    <ul
+      aria-label={label}
+      className="grid w-full list-none p-0 [&>*]:min-w-0"
+      ref={gridElement}
+      style={{
+        gap: `${gap}px`,
+        gridTemplateColumns: `repeat(${drawnColumns}, minmax(0, 1fr))`,
+        maxInlineSize: getContentMaxInlineSize({
+          columns: drawnColumns,
+        }),
+        // Offset by `scrollMargin` because `start` is measured
+        // from the top of the scroll owner, and this padding is
+        // measured from the top of the grid.
+        paddingBlockEnd: `${paddingBlockEnd}px`,
+        paddingBlockStart: `${Math.max(0, paddingBlockStart - scrollMargin)}px`,
+      }}
+    >
+      {virtualRows.flatMap((row) => {
+        const firstIndex = row.index * drawnColumns
+
+        return items
+          .slice(firstIndex, firstIndex + drawnColumns)
+          .map((item, offset) => {
+            const index = firstIndex + offset
+
+            return (
+              <li
+                aria-posinset={index + 1}
+                aria-setsize={items.length}
+                // `data-index` names the ROW, so it goes on
+                // every cell in it — they all sit in that row
+                // and the attribute is true of all of them.
+                //
+                // Putting it only on the measured cell is the
+                // version that looks tidier and warns on every
+                // resize: the virtualizer keeps a
+                // `ResizeObserver` on whatever it measured and
+                // re-reads the attribute whenever that node
+                // changes size. Let the node stop being the
+                // leading cell — a column count change is all it
+                // takes — and it is still observed, now with no
+                // attribute to resolve.
+                data-index={row.index}
+                key={getItemKey?.(item, index) ?? index}
+                // Measured on the leading cell alone. A CSS grid
+                // stretches every cell to its row's height, so
+                // one is enough — and measuring all of them
+                // would have the virtualizer record the same row
+                // once per column.
+                ref={
+                  offset === 0 ? measureElement : undefined
+                }
+              >
+                {renderItem(item, index)}
+              </li>
+            )
+          })
+      })}
+    </ul>
+  )
+}

package/src/VirtualizedGrid/VirtualizedGrid.mdx

@@ -47,16 +47,17 @@ commitment — every mounted row is measured and the estimate corrected. It stil
 be close, because it is what the scrollbar is sized from before anything has been
 measured. A bad guess makes the bar jump under the thumb on the first scroll.
 
-## It scrolls the page, not a box of its own
+## It follows the page's scroll region
 
-`useWindowVirtualizer`, so the page scrolls the way every other page in the fleet
-scrolls — the header leaves, the scrollbar is the browser's, `Ctrl+End` works. A
-component that grew its own `overflow: auto` well would trap the wheel and strand the
-page header above it.
+The grid never creates a scroll box. It follows the nearest ancestor whose vertical
+overflow is `auto` or `scroll`. Inside `Shell`, that is `Main`, so the header and rail stay
+available while the grid scrolls. A standalone grid falls back to the browser window.
 
-The cost is that the grid has to know how far down the document it starts, which it
-measures in a layout effect and feeds to the virtualizer as `scrollMargin`. Get that
-wrong and every row is offset by the height of the header above it.
+The cost is that the grid has to know how far down its scroll region it starts. It measures
+that offset in a layout effect and feeds it to the virtualizer as `scrollMargin`. Get that
+wrong and every row is offset by the chrome above it.
+
+<Canvas of={VirtualizedGridStories.InShellScrollRegion} />
 
 ## The column rule is inherited, not reimplemented
 

package/src/VirtualizedGrid/VirtualizedGrid.stories.tsx

@@ -3,9 +3,13 @@ import { useState } from "react"
 
 import { getColumnChoices } from "../AdaptiveGrid/chooseColumns.ts"
 import type { BlockSizeResolver } from "../AdaptiveGrid/useAdaptiveColumns.ts"
+import { Button } from "../Button/Button.tsx"
 import { StorySection } from "../board.storyHelpers.tsx"
 import { Card } from "../Card/Card.tsx"
+import { Header } from "../Header/Header.tsx"
+import { Main } from "../Main/Main.tsx"
 import { SegmentedControl } from "../SegmentedControl/SegmentedControl.tsx"
+import { Shell } from "../Shell/Shell.tsx"
 import { VirtualizedGrid } from "./VirtualizedGrid.tsx"
 
 /**
@@ -104,6 +108,28 @@ type Story = StoryObj<typeof meta>
  */
 export const Default: Story = {}
 
+/**
+ * The app-shell contract: `Main` is the one vertical scroll region,
+ * and the grid follows it rather than adding document height.
+ *
+ * This is QueuePilot's Pending shape. It is a separate story because
+ * a standalone grid still follows the browser window and both paths
+ * need a real consumer.
+ */
+export const InShellScrollRegion: Story = {
+  parameters: { layout: "fullscreen" },
+  render: (gridProps) => (
+    <Shell contentWidth="full">
+      <Header heading="Pending" />
+
+      <Main>
+        <Button onClick={() => {}}>Mark all seen</Button>
+        <VirtualizedGrid {...gridProps} />
+      </Main>
+    </Shell>
+  ),
+}
+
 /**
  * The same 2,000 items at three window heights.
  *

package/src/VirtualizedGrid/VirtualizedGrid.test.tsx

@@ -33,7 +33,8 @@ import * as stories from "./VirtualizedGrid.stories.tsx"
  *    on.
  */
 
-const { AllStates, Default } = composeStories(stories)
+const { AllStates, Default, InShellScrollRegion } =
+  composeStories(stories)
 
 const getLists = (canvasElement: HTMLElement) => [
   ...canvasElement.querySelectorAll<HTMLElement>("ul"),
@@ -146,6 +147,64 @@ test("scrolling changes which rows exist", async () => {
   }
 })
 
+test("a grid inside Shell follows Main's one scroll region", async () => {
+  const { canvasElement } = await mountStory(
+    InShellScrollRegion,
+  )
+  const main =
+    canvasElement.querySelector<HTMLElement>("main")
+
+  if (!main) {
+    throw new Error("The shell story has no Main element.")
+  }
+
+  await waitFor(async () => {
+    await expect(
+      getRowIndexes(canvasElement).length,
+    ).toBeGreaterThan(0)
+  })
+
+  await expect(getComputedStyle(main).overflowY).toBe(
+    "auto",
+  )
+  await expect(main.scrollHeight).toBeGreaterThan(
+    main.clientHeight,
+  )
+
+  const before = getRowIndexes(canvasElement)
+
+  main.scrollTop = 6000
+  main.dispatchEvent(new Event("scroll"))
+
+  await waitFor(async () => {
+    await expect(
+      getRowIndexes(canvasElement).some((index) =>
+        before.includes(index),
+      ),
+    ).toBe(false)
+  })
+
+  // The last row must replace the virtual spacer. This is the
+  // reported failure's visible half: the old window observer left
+  // tens of thousands of blank pixels below the first mounted rows
+  // when Main scrolled.
+  main.scrollTop = main.scrollHeight
+  main.dispatchEvent(new Event("scroll"))
+
+  await waitFor(async () => {
+    await expect(
+      getCells(canvasElement).some(
+        (cell) =>
+          cell.getAttribute("aria-posinset") === "2000",
+      ),
+    ).toBe(true)
+  })
+
+  await expect(
+    getList(canvasElement).style.paddingBlockEnd,
+  ).toBe("0px")
+})
+
 test("a screen reader is told the real length", async () => {
   const { canvasElement } = await mountStory(Default)
 

package/src/VirtualizedGrid/VirtualizedGrid.tsx

@@ -1,17 +1,17 @@
-import { useWindowVirtualizer } from "@tanstack/react-virtual"
 import type { ReactNode } from "react"
-import {
-  useCallback,
-  useLayoutEffect,
-  useRef,
-  useState,
-} from "react"
+import { useLayoutEffect, useState } from "react"
 
-import { getContentMaxInlineSize } from "../AdaptiveGrid/chooseColumns.ts"
 import type { BlockSizeResolver } from "../AdaptiveGrid/useAdaptiveColumns.ts"
 import { useAdaptiveColumns } from "../AdaptiveGrid/useAdaptiveColumns.ts"
 import { toClassName } from "../toClassName.ts"
+import { ElementGrid } from "./ElementGrid.tsx"
 import { DEFAULT_GRID_GAP_PX } from "./gridGap.ts"
+import { findScrollOwner } from "./virtualizedGridScroll.ts"
+import type {
+  GridWindowProps,
+  ScrollOwner,
+} from "./virtualizedGridTypes.ts"
+import { WindowGrid } from "./WindowGrid.tsx"
 
 export type VirtualizedGridProps<Item> = {
   /**
@@ -140,15 +140,13 @@ export type VirtualizedGridProps<Item> = {
  * idea of the distance from one row to the next and the browser's
  * the same number.
  *
- * ### Why the window and not a scroll box of its own
+ * ### It follows the page's existing scroll owner
  *
- * `useWindowVirtualizer`, so the page scrolls the way every other
- * page in the fleet scrolls — the header leaves, the scrollbar is
- * the browser's, `Ctrl+End` works. A component that grew its own
- * `overflow: auto` well would trap the wheel and strand the page
- * header above it. The cost is `scrollMargin`: the virtualizer has
- * to be told how far down the document the grid starts, which is
- * measured below.
+ * A standalone grid follows the browser window. Inside `Shell`, it
+ * follows `Main`, which is the shell's one vertical scroll region.
+ * It never creates a scroll box of its own. The cost is
+ * `scrollMargin`: the virtualizer has to be told how far down its
+ * scroll owner the grid starts, which is measured below.
  *
  * ### What windowing costs, and what is done about it
  *
@@ -188,85 +186,38 @@ export const VirtualizedGrid = <Item,>({
 
   const drawnColumns = columns ?? layout.columns
 
-  // Folded from what is DRAWN rather than read off the hook, so an
-  // override widens the page cap with it — the same rule
-  // `AdaptiveGrid` follows, and wrong in the same way if it does
-  // not.
-  const contentMaxInlineSize = getContentMaxInlineSize({
-    columns: drawnColumns,
-  })
-
   const rowCount = Math.ceil(items.length / drawnColumns)
 
   /**
-   * How far down the document the grid starts.
-   *
-   * `useWindowVirtualizer` measures against the document, so
-   * without this every row is placed as though the grid began at
-   * the top of the page, and the whole list sits shifted by the
-   * height of the header above it.
-   *
-   * State and not a ref, because it feeds `scrollMargin` and a
-   * change has to re-render. Measured on every commit rather than
-   * on a dependency list: a filter row that grows a line moves the
-   * grid down the page, and nothing in this component's own props
-   * would report that.
+   * Main owns vertical scrolling inside an app Shell. Older pages
+   * and a standalone grid still use the window. Resolve the owner
+   * from the actual tree rather than making every app wire a ref
+   * between two Charcuterie components.
    */
-  const gridElement = useRef<HTMLUListElement>(null)
-  const [scrollMargin, setScrollMargin] = useState(0)
+  const [scrollOwner, setScrollOwner] =
+    useState<ScrollOwner | null>(null)
 
   useLayoutEffect(() => {
-    const element = gridElement.current
+    const element = layout.containerRef.current
 
     if (!element) {
       return
     }
 
-    const next =
-      element.getBoundingClientRect().top + window.scrollY
-
-    setScrollMargin((current) =>
-      current === next ? current : next,
-    )
-  })
+    setScrollOwner(findScrollOwner(element))
+  }, [layout.containerRef])
 
-  /**
-   * A row's height, plus the gap that follows it.
-   *
-   * The gap is added here rather than left to the estimate because
-   * it is real distance the next row starts after: leave it out
-   * and the virtualizer's offsets drift by one gap per row, which
-   * on a list of two thousand is a scrollbar off by half a page.
-   */
-  const measureRow = useCallback(
-    (element: Element) =>
-      element.getBoundingClientRect().height + gap,
-    [gap],
-  )
-
-  const rowVirtualizer = useWindowVirtualizer({
-    count: rowCount,
-    estimateSize: () => itemBlockSize + gap,
-    measureElement: measureRow,
-    overscan: overscanRows,
-    scrollMargin,
-  })
-
-  const virtualRows = rowVirtualizer.getVirtualItems()
-
-  const firstRow = virtualRows[0]
-  const lastRow = virtualRows[virtualRows.length - 1]
-
-  // Everything scrolled past, and everything still to come. The two
-  // numbers that stand in for the rows that do not exist.
-  const paddingBlockStart = firstRow?.start ?? 0
-
-  const paddingBlockEnd = lastRow
-    ? Math.max(
-        0,
-        rowVirtualizer.getTotalSize() - lastRow.end,
-      )
-    : 0
+  const gridProps: GridWindowProps<Item> = {
+    drawnColumns,
+    gap,
+    getItemKey,
+    itemBlockSize,
+    items,
+    label,
+    overscanRows,
+    renderItem,
+    rowCount,
+  }
 
   return (
     <div
@@ -276,65 +227,14 @@ export const VirtualizedGrid = <Item,>({
       )}
       ref={layout.containerRef}
     >
-      <ul
-        aria-label={label}
-        className="grid w-full list-none p-0 [&>*]:min-w-0"
-        ref={gridElement}
-        style={{
-          gap: `${gap}px`,
-          gridTemplateColumns: `repeat(${drawnColumns}, minmax(0, 1fr))`,
-          maxInlineSize: contentMaxInlineSize,
-          // Offset by `scrollMargin` because `start` is measured
-          // from the top of the document, and this padding is
-          // measured from the top of the grid.
-          paddingBlockEnd: `${paddingBlockEnd}px`,
-          paddingBlockStart: `${Math.max(0, paddingBlockStart - scrollMargin)}px`,
-        }}
-      >
-        {virtualRows.flatMap((row) => {
-          const firstIndex = row.index * drawnColumns
-
-          return items
-            .slice(firstIndex, firstIndex + drawnColumns)
-            .map((item, offset) => {
-              const index = firstIndex + offset
-
-              return (
-                <li
-                  aria-posinset={index + 1}
-                  aria-setsize={items.length}
-                  // `data-index` names the ROW, so it goes on
-                  // every cell in it — they all sit in that row
-                  // and the attribute is true of all of them.
-                  //
-                  // Putting it only on the measured cell is the
-                  // version that looks tidier and warns on every
-                  // resize: the virtualizer keeps a
-                  // `ResizeObserver` on whatever it measured and
-                  // re-reads the attribute whenever that node
-                  // changes size. Let the node stop being the
-                  // leading cell — a column count change is all it
-                  // takes — and it is still observed, now with no
-                  // attribute to resolve.
-                  data-index={row.index}
-                  key={getItemKey?.(item, index) ?? index}
-                  // Measured on the leading cell alone. A CSS grid
-                  // stretches every cell to its row's height, so
-                  // one is enough — and measuring all of them
-                  // would have the virtualizer record the same row
-                  // once per column.
-                  ref={
-                    offset === 0
-                      ? rowVirtualizer.measureElement
-                      : undefined
-                  }
-                >
-                  {renderItem(item, index)}
-                </li>
-              )
-            })
-        })}
-      </ul>
+      {scrollOwner?.kind === "element" ? (
+        <ElementGrid
+          {...gridProps}
+          scrollOwner={scrollOwner}
+        />
+      ) : scrollOwner?.kind === "window" ? (
+        <WindowGrid {...gridProps} />
+      ) : null}
     </div>
   )
 }

package/src/VirtualizedGrid/WindowGrid.tsx

@@ -0,0 +1,39 @@
+import { useWindowVirtualizer } from "@tanstack/react-virtual"
+import { useCallback } from "react"
+
+import { GridRows } from "./GridRows.tsx"
+import { useScrollMargin } from "./virtualizedGridScroll.ts"
+import type { GridWindowProps } from "./virtualizedGridTypes.ts"
+
+export const WindowGrid = <Item,>(
+  props: GridWindowProps<Item>,
+) => {
+  const { gridElement, scrollMargin } = useScrollMargin({
+    kind: "window",
+  })
+
+  const measureRow = useCallback(
+    (element: Element) =>
+      element.getBoundingClientRect().height + props.gap,
+    [props.gap],
+  )
+
+  const rowVirtualizer = useWindowVirtualizer({
+    count: props.rowCount,
+    estimateSize: () => props.itemBlockSize + props.gap,
+    measureElement: measureRow,
+    overscan: props.overscanRows,
+    scrollMargin,
+  })
+
+  return (
+    <GridRows
+      {...props}
+      gridElement={gridElement}
+      measureElement={rowVirtualizer.measureElement}
+      scrollMargin={scrollMargin}
+      totalSize={rowVirtualizer.getTotalSize()}
+      virtualRows={rowVirtualizer.getVirtualItems()}
+    />
+  )
+}

package/src/VirtualizedGrid/virtualizedGridScroll.ts

@@ -0,0 +1,69 @@
+import { useLayoutEffect, useRef, useState } from "react"
+
+import type { ScrollOwner } from "./virtualizedGridTypes.ts"
+
+/**
+ * The closest ancestor that owns vertical scrolling.
+ *
+ * The computed value is enough. An `overflow-y:auto` ancestor can
+ * be shorter than its contents only AFTER this grid installs its
+ * virtual spacer, so requiring `scrollHeight > clientHeight` here
+ * would miss the owner on the first commit and create the exact
+ * document scrollbar this lookup prevents.
+ */
+export const findScrollOwner = (
+  element: HTMLElement,
+): ScrollOwner => {
+  let ancestor = element.parentElement
+
+  while (ancestor) {
+    const overflow = getComputedStyle(ancestor).overflowY
+
+    if (overflow === "auto" || overflow === "scroll") {
+      return { element: ancestor, kind: "element" }
+    }
+
+    ancestor = ancestor.parentElement
+  }
+
+  return { kind: "window" }
+}
+
+/**
+ * The offset from the scroll owner's content origin to the grid.
+ *
+ * Both formulas stay stable while their owner scrolls: the grid's
+ * viewport-relative top falls by the same amount that `scrollY` or
+ * `scrollTop` rises. The element path subtracts its border because
+ * a scroll offset starts at the padding edge, not at the outer
+ * border returned by `getBoundingClientRect()`.
+ */
+export const useScrollMargin = (
+  scrollOwner: ScrollOwner,
+) => {
+  const gridElement = useRef<HTMLUListElement>(null)
+  const [scrollMargin, setScrollMargin] = useState(0)
+
+  useLayoutEffect(() => {
+    const element = gridElement.current
+
+    if (!element) {
+      return
+    }
+
+    const gridTop = element.getBoundingClientRect().top
+    const next =
+      scrollOwner.kind === "window"
+        ? gridTop + window.scrollY
+        : gridTop -
+          scrollOwner.element.getBoundingClientRect().top -
+          scrollOwner.element.clientTop +
+          scrollOwner.element.scrollTop
+
+    setScrollMargin((current) =>
+      current === next ? current : next,
+    )
+  })
+
+  return { gridElement, scrollMargin }
+}

package/src/VirtualizedGrid/virtualizedGridTypes.ts

@@ -0,0 +1,32 @@
+import type { VirtualItem } from "@tanstack/react-virtual"
+import type { ReactNode, RefObject } from "react"
+
+export type ScrollOwner =
+  | { kind: "element"; element: HTMLElement }
+  | { kind: "window" }
+
+export type GridWindowProps<Item> = {
+  drawnColumns: number
+  gap: number
+  getItemKey?: (
+    item: Item,
+    index: number,
+  ) => string | number
+  itemBlockSize: number
+  items: readonly Item[]
+  label?: string
+  overscanRows: number
+  renderItem: (item: Item, index: number) => ReactNode
+  rowCount: number
+}
+
+export type GridRowsProps<Item> = Omit<
+  GridWindowProps<Item>,
+  "itemBlockSize" | "overscanRows" | "rowCount"
+> & {
+  gridElement: RefObject<HTMLUListElement | null>
+  measureElement: (element: Element | null) => void
+  scrollMargin: number
+  totalSize: number
+  virtualRows: VirtualItem[]
+}