@charcuterie/ui 3.28.0 → 3.28.2

package/src/Shell/Shell.test.tsx

@@ -16,6 +16,7 @@ const {
   Default,
   Interactive,
   Responsive,
+  Scrollable,
   WithBothRails,
   WithStartRail,
 } = composeStories(stories)
@@ -152,6 +153,34 @@ test("the shell fills the viewport at desktop width without overflowing it", asy
   await expectNoHorizontalScroll()
 })
 
+test("only main scrolls vertically, keeping the rail available", async () => {
+  await setViewport(DESKTOP)
+
+  const { canvas, canvasElement } =
+    await mountStory(Scrollable)
+
+  const shell =
+    canvasElement.firstElementChild as HTMLElement
+  const main = canvas.getByRole("main")
+  const rail = canvas.getByRole("navigation", {
+    name: "Sections",
+  })
+
+  await expect(shell.clientHeight).toBe(DESKTOP.height)
+  await expect(main.scrollHeight).toBeGreaterThan(
+    main.clientHeight,
+  )
+  await expect(
+    globalThis.getComputedStyle(main).overflowY,
+  ).toBe("auto")
+
+  main.scrollTo({ top: main.scrollHeight })
+
+  await expect(main.scrollTop).toBeGreaterThan(0)
+  await expect(rail.scrollTop).toBe(0)
+  await expectNoAxeViolations(canvasElement)
+})
+
 test("the shell is one banner, one main, and two uniquely-named rails", async () => {
   const { canvas, canvasElement } =
     await mountStory(WithBothRails)

package/src/Shell/Shell.tsx

@@ -140,7 +140,7 @@ export const Shell = ({
       <div
         {...divProps}
         className={toClassName(
-          "relative grid min-h-dvh grid-cols-1 grid-rows-[auto_auto_1fr_auto] overflow-x-clip bg-surface-base text-content-primary md:grid-cols-[auto_minmax(0,1fr)_auto] md:grid-rows-[auto_1fr]",
+          "relative grid h-dvh grid-cols-1 grid-rows-[auto_auto_minmax(0,1fr)_auto] overflow-x-clip bg-surface-base text-content-primary md:grid-cols-[auto_minmax(0,1fr)_auto] md:grid-rows-[auto_minmax(0,1fr)]",
           className,
         )}
       >

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 }
+}