@charcuterie/ui 3.7.0 → 3.8.0

package/src/VirtualizedGrid/VirtualizedGrid.stories.tsx

@@ -0,0 +1,258 @@
+import type { Meta, StoryObj } from "@storybook/react"
+import { useState } from "react"
+
+import { getColumnChoices } from "../AdaptiveGrid/chooseColumns.ts"
+import type { BlockSizeResolver } from "../AdaptiveGrid/useAdaptiveColumns.ts"
+import { StorySection } from "../board.storyHelpers.tsx"
+import { Card } from "../Card/Card.tsx"
+import { SegmentedControl } from "../SegmentedControl/SegmentedControl.tsx"
+import { VirtualizedGrid } from "./VirtualizedGrid.tsx"
+
+/**
+ * A fixed block size, so a story shows the rule rather than the
+ * height of whichever frame Storybook happened to render it in.
+ * The same seam `AdaptiveGrid`'s stories inject, and for the same
+ * reason: in a real chromium `innerHeight` is a read-only accessor
+ * and assigning to it is a silent no-op.
+ */
+const fixedBlockSize = (
+  blockSize: number,
+): BlockSizeResolver => ({
+  get: () => blockSize,
+  subscribe: () => () => {},
+})
+
+const COLUMN_ITEMS = getColumnChoices({
+  maxColumns: 4,
+}).map((choice) => ({
+  label: String(choice),
+  value: String(choice),
+}))
+
+type Bay = {
+  id: string
+  label: string
+}
+
+/**
+ * Two thousand of them, which is the point.
+ *
+ * The number is not decoration: it is roughly what QueuePilot's
+ * Pending page holds, and it is the size at which rendering every
+ * item stops being viable. A story with twelve items would mount
+ * the same component and prove nothing about it.
+ */
+const MANY_ITEMS: Bay[] = Array.from(
+  { length: 2000 },
+  (_, index) => ({
+    id: `bay-${index + 1}`,
+    label: `Bay ${index + 1}`,
+  }),
+)
+
+const Item = ({ label }: { label: string }) => (
+  <Card padding="md" surface="raised">
+    <p className="font-semibold text-content-primary">
+      {label}
+    </p>
+
+    {/*
+     * An unbroken string with no wrap opportunity — the thing a
+     * grid item's `min-content` minimum turns into a horizontal
+     * scrollbar. `truncate` clips it; `[&>*]:min-w-0` on the row
+     * is what lets the track get small enough for the clipping to
+     * matter.
+     */}
+    <p className="truncate text-content-muted text-sm">
+      /mnt/Bunnies/Family/Media/very/long/unbroken/path/that/would/push/a/track/wide
+    </p>
+  </Card>
+)
+
+const meta = {
+  title: "Components/Layout/VirtualizedGrid",
+  component: VirtualizedGrid<Bay>,
+  parameters: { layout: "padded" },
+  args: {
+    blockSizeResolver: fixedBlockSize(1080),
+    chromeBlockSize: 260,
+    getItemKey: (item: Bay) => item.id,
+    itemBlockSize: 150,
+    items: MANY_ITEMS,
+    label: "Bays",
+    renderItem: (item: Bay) => <Item label={item.label} />,
+  },
+  argTypes: {
+    blockSizeResolver: { control: false },
+    getItemKey: { control: false },
+    items: { control: false },
+    renderItem: { control: false },
+  },
+} satisfies Meta<typeof VirtualizedGrid<Bay>>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+/**
+ * Two thousand items, of which a few dozen exist.
+ *
+ * The scrollbar is sized for all 2,000 — `getTotalSize()` is the
+ * full list — so the page behaves as though every item were there.
+ * Inspect the DOM and count: the row elements are the ones on
+ * screen plus `overscanRows` above and below.
+ */
+export const Default: Story = {}
+
+/**
+ * The same 2,000 items at three window heights.
+ *
+ * Inherited from `AdaptiveGrid` rather than reimplemented, so the
+ * rule that reads backwards holds here too: a **taller** window
+ * takes **fewer** columns, because height is what a column is
+ * bought with. Windowing changes how many rows are mounted, never
+ * how many columns are drawn.
+ */
+export const AllVariants: Story = {
+  render: (gridProps) => (
+    <StorySection title="Same items, same width — only the height changes.">
+      {[
+        {
+          blockSize: 1440,
+          label: "1440px tall",
+        },
+        { blockSize: 900, label: "900px tall" },
+        { blockSize: 600, label: "600px tall" },
+      ].map((panel) => (
+        <div
+          className="flex w-full flex-col gap-2"
+          key={panel.label}
+        >
+          <span className="font-mono text-content-muted text-xs">
+            {panel.label}
+          </span>
+
+          <VirtualizedGrid
+            {...gridProps}
+            blockSizeResolver={fixedBlockSize(
+              panel.blockSize,
+            )}
+          />
+        </div>
+      ))}
+    </StorySection>
+  ),
+}
+
+/**
+ * Empty, one item, and two thousand.
+ *
+ * The empty case draws a zero-height box and no rows — a windowed
+ * grid must not reserve space for a list that is not there, and it
+ * is the state a filter lands on. One item is one column, the same
+ * answer `AdaptiveGrid` gives, and the case that would otherwise
+ * stretch a lone card across an ultrawide.
+ */
+export const AllStates: Story = {
+  render: (gridProps) => (
+    <div className="flex flex-col gap-6">
+      {[
+        { items: [], label: "no items" },
+        {
+          items: MANY_ITEMS.slice(0, 1),
+          label: "one item",
+        },
+        { items: MANY_ITEMS, label: "2,000 items" },
+      ].map((panel) => (
+        <div
+          className="flex w-full flex-col gap-2"
+          key={panel.label}
+        >
+          <span className="font-mono text-content-muted text-xs">
+            {panel.label}
+          </span>
+
+          <VirtualizedGrid
+            {...gridProps}
+            items={panel.items}
+          />
+        </div>
+      ))}
+    </div>
+  ),
+}
+
+/**
+ * Three container widths, with the column floor dropped to 160px.
+ *
+ * The browser never moves and the column count still falls, which
+ * is the honest demonstration that the inline size comes off a
+ * `ResizeObserver` on the container rather than off the window.
+ */
+export const Responsive: Story = {
+  args: {
+    blockSizeResolver: fixedBlockSize(600),
+    minColumnInlineSize: 160,
+  },
+  render: (gridProps) => (
+    <div className="flex flex-wrap items-start gap-6">
+      {[
+        { inlineSize: "15rem", label: "15rem container" },
+        { inlineSize: "24rem", label: "24rem container" },
+        { inlineSize: "34rem", label: "34rem container" },
+      ].map((panel) => (
+        <div
+          // `shrink-0`, or flex shrinks the widest panel back to
+          // the viewport and all three grids answer the same.
+          className="flex shrink-0 flex-col gap-2"
+          key={panel.label}
+          style={{ inlineSize: panel.inlineSize }}
+        >
+          <span className="font-mono text-content-muted text-xs">
+            {panel.label}
+          </span>
+
+          <VirtualizedGrid
+            {...gridProps}
+            items={MANY_ITEMS.slice(0, 60)}
+          />
+        </div>
+      ))}
+    </div>
+  ),
+}
+
+/**
+ * The manual override beside the automatic answer, on a windowed
+ * list.
+ *
+ * Changing the count re-rows 2,000 items — the row count is
+ * `ceil(items / columns)` — so this is also the case that proves
+ * the virtualizer is re-measured rather than left holding
+ * positions for a layout that no longer exists.
+ */
+export const Interactive: Story = {
+  render: (gridProps) => {
+    const [choice, setChoice] = useState<string>("auto")
+
+    return (
+      <StorySection title="Pick a count, or hand it back to auto.">
+        <SegmentedControl
+          items={COLUMN_ITEMS}
+          label="Columns"
+          onChange={(value) => {
+            setChoice(value ?? "auto")
+          }}
+          selectedValue={choice}
+        />
+
+        <VirtualizedGrid
+          {...gridProps}
+          columns={
+            choice === "auto" ? undefined : Number(choice)
+          }
+        />
+      </StorySection>
+    )
+  },
+}

package/src/VirtualizedGrid/VirtualizedGrid.test.tsx

@@ -0,0 +1,182 @@
+import { composeStories } from "@storybook/react"
+import { expect, waitFor } from "storybook/test"
+import { test } from "vitest"
+
+import { mountStory } from "../mountStory.testHelpers.ts"
+import * as stories from "./VirtualizedGrid.stories.tsx"
+
+/**
+ * What windowing has to be true for.
+ *
+ * `chooseColumns.test.ts` already proves the column arithmetic and
+ * `AdaptiveGrid.test.tsx` already proves it is fed real measured
+ * numbers. Neither is re-proved here — this component calls the
+ * same hook, and a second copy of those assertions would only
+ * guarantee that a copy stays in step.
+ *
+ * What is new, and what these cover:
+ *
+ *  - **Far fewer elements exist than items.** The claim the
+ *    component is for. Asserted as a bound rather than an exact
+ *    count, because the exact count is viewport height divided by
+ *    row height and would pin the test to the runner's window.
+ *  - **The page is still as tall as the whole list.** A windowed
+ *    grid that shortens its own scrollbar has traded one bug for a
+ *    worse one. Here that height lives in `padding-block-end`.
+ *  - **Scrolling swaps which rows exist.** The distinguishing
+ *    test: a component that merely rendered the first N items
+ *    would pass the two above and fail this one.
+ *  - **The true length reaches assistive technology.**
+ *    `aria-setsize` is the only thing standing between a reader
+ *    and "list, 40 items" on a list of 2,000.
+ *  - **An empty list reserves no space.** The state a filter lands
+ *    on.
+ */
+
+const { AllStates, Default } = composeStories(stories)
+
+const getLists = (canvasElement: HTMLElement) => [
+  ...canvasElement.querySelectorAll<HTMLElement>("ul"),
+]
+
+const getList = (
+  canvasElement: HTMLElement,
+  index = 0,
+): HTMLElement => {
+  const list = getLists(canvasElement)[index]
+
+  if (!list) {
+    throw new Error(
+      `No VirtualizedGrid at index ${index}; found ${getLists(canvasElement).length}.`,
+    )
+  }
+
+  return list
+}
+
+const getCells = (canvasElement: HTMLElement) => [
+  ...canvasElement.querySelectorAll<HTMLElement>("li"),
+]
+
+/**
+ * Which rows are mounted.
+ *
+ * `data-index` names a row and sits on every cell in it, so this
+ * is a set rather than a list — several cells report the same row,
+ * and that is the attribute working rather than a duplicate.
+ */
+const getRowIndexes = (canvasElement: HTMLElement) => [
+  ...new Set(
+    [
+      ...canvasElement.querySelectorAll<HTMLElement>(
+        "[data-index]",
+      ),
+    ].map((cell) => Number(cell.dataset.index)),
+  ),
+]
+
+test("2,000 items mount as a few dozen cells", async () => {
+  const { canvasElement } = await mountStory(Default)
+
+  await waitFor(async () => {
+    await expect(
+      getCells(canvasElement).length,
+    ).toBeGreaterThan(0)
+  })
+
+  // The bound is deliberately loose — the runner's window is
+  // 414x896, and the honest claim is "two orders of magnitude
+  // fewer", not a number that changes when someone resizes the
+  // harness.
+  await expect(getCells(canvasElement).length).toBeLessThan(
+    200,
+  )
+})
+
+test("the page is still as tall as the whole list", async () => {
+  const { canvasElement } = await mountStory(Default)
+
+  await waitFor(async () => {
+    await expect(
+      getRowIndexes(canvasElement).length,
+    ).toBeGreaterThan(0)
+  })
+
+  // At the top of the list, everything still to come is
+  // `padding-block-end`. 2,000 items at 150px plus a 16px gap, in
+  // however many columns the runner chose, is tens of thousands of
+  // pixels — far more than the handful of mounted rows occupy,
+  // which is the whole assertion.
+  const list = getList(canvasElement)
+
+  await expect(
+    Number.parseFloat(list.style.paddingBlockEnd),
+  ).toBeGreaterThan(10_000)
+})
+
+test("scrolling changes which rows exist", async () => {
+  const { canvasElement } = await mountStory(Default)
+
+  await waitFor(async () => {
+    await expect(
+      getRowIndexes(canvasElement).length,
+    ).toBeGreaterThan(0)
+  })
+
+  const before = getRowIndexes(canvasElement)
+
+  window.scrollTo(0, 6000)
+
+  try {
+    await waitFor(async () => {
+      // Not "some overlap changed" — no row that was mounted
+      // before may still be mounted, which is what separates
+      // windowing from a list that merely grew.
+      await expect(
+        getRowIndexes(canvasElement).some((index) =>
+          before.includes(index),
+        ),
+      ).toBe(false)
+    })
+  } finally {
+    // The window is shared with every later test in the file, and
+    // a canvas left scrolled would mount a different set of rows
+    // in the next one.
+    window.scrollTo(0, 0)
+  }
+})
+
+test("a screen reader is told the real length", async () => {
+  const { canvasElement } = await mountStory(Default)
+
+  await waitFor(async () => {
+    await expect(
+      getCells(canvasElement).length,
+    ).toBeGreaterThan(0)
+  })
+
+  const [firstCell] = getCells(canvasElement)
+
+  await expect(
+    firstCell?.getAttribute("aria-setsize"),
+  ).toBe("2000")
+
+  await expect(
+    firstCell?.getAttribute("aria-posinset"),
+  ).toBe("1")
+})
+
+test("an empty list reserves no space and mounts no rows", async () => {
+  const { canvasElement } = await mountStory(AllStates)
+
+  // `AllStates` draws three grids in order: none, one, 2,000.
+  const empty = getList(canvasElement, 0)
+
+  await waitFor(async () => {
+    await expect(empty.style.paddingBlockEnd).toBe("0px")
+  })
+
+  await expect(empty.style.paddingBlockStart).toBe("0px")
+
+  await expect(empty.querySelectorAll("li").length).toBe(0)
+})