@charcuterie/ui 2.7.0 → 2.8.0

package/src/AdaptiveGrid/AdaptiveGrid.stories.tsx

@@ -0,0 +1,240 @@
+import type { Meta, StoryObj } from "@storybook/react"
+import { useState } from "react"
+
+import {
+  StoryCell,
+  StoryGrid,
+  StoryRow,
+  StorySection,
+} from "../board.storyHelpers.tsx"
+import { Card } from "../Card/Card.tsx"
+import { SegmentedControl } from "../SegmentedControl/SegmentedControl.tsx"
+import { AdaptiveGrid } from "./AdaptiveGrid.tsx"
+import { getColumnChoices } from "./chooseColumns.ts"
+import type { BlockSizeResolver } from "./useAdaptiveColumns.ts"
+
+/**
+ * A fixed block size, so a story shows the rule rather than the
+ * height of whichever frame Storybook happened to render it in.
+ *
+ * This is also the seam that makes the DOM tests deterministic: the
+ * source app forced the viewport with
+ * `Object.defineProperty(window, "innerHeight", …)`, because in a
+ * real chromium `innerHeight` is a read-only accessor and a plain
+ * assignment is a silent no-op. Injecting a resolver retires that
+ * trick entirely.
+ */
+const fixedBlockSize = (
+  blockSize: number,
+): BlockSizeResolver => ({
+  get: () => blockSize,
+  subscribe: () => () => {},
+})
+
+/**
+ * `getColumnChoices({ maxColumns: 4 })`, as the picker's items —
+ * `"auto"` first, because a picker that only offers numbers once a
+ * number has been chosen is a one-way door.
+ */
+const COLUMN_ITEMS = getColumnChoices({
+  maxColumns: 4,
+}).map((choice) => ({
+  label: String(choice),
+  value: String(choice),
+}))
+
+const NINE_ITEMS = Array.from(
+  { length: 9 },
+  (_, index) => `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` inside
+     * `AdaptiveGrid` 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/AdaptiveGrid",
+  component: AdaptiveGrid,
+  parameters: { layout: "padded" },
+  args: {
+    children: NINE_ITEMS.map((label) => (
+      <Item key={label} label={label} />
+    )),
+    chromeBlockSize: 260,
+    itemBlockSize: 150,
+  },
+} satisfies Meta<typeof AdaptiveGrid>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+/**
+ * Nine items in a 1080px-tall window. Five stack, so two columns
+ * carry nine — and the content cap widens from 56rem to 72rem to
+ * hold them.
+ */
+export const Default: Story = {
+  args: { blockSizeResolver: fixedBlockSize(1080) },
+}
+
+/**
+ * The same nine items, the same width, three window heights.
+ *
+ * This is the whole rule in one board, and the middle panel is the
+ * part that reads backwards: a **taller** window takes **fewer**
+ * columns, because height is what a column is bought with.
+ */
+export const AllVariants: Story = {
+  render: (gridProps) => (
+    <StorySection title="Same items, same width — only the height changes.">
+      {[
+        {
+          blockSize: 1440,
+          label: "1440px tall — 2 columns",
+        },
+        { blockSize: 900, label: "900px tall — 3 columns" },
+        { blockSize: 600, label: "600px tall — 3 columns" },
+      ].map((panel) => (
+        <StoryRow key={panel.label}>
+          <div className="flex w-full flex-col gap-2">
+            <span className="font-mono text-content-muted text-xs">
+              {panel.label}
+            </span>
+
+            <AdaptiveGrid
+              {...gridProps}
+              blockSizeResolver={fixedBlockSize(
+                panel.blockSize,
+              )}
+            >
+              {NINE_ITEMS.map((label) => (
+                <Item key={label} label={label} />
+              ))}
+            </AdaptiveGrid>
+          </div>
+        </StoryRow>
+      ))}
+    </StorySection>
+  ),
+}
+
+/**
+ * One item is one column at every size — the case that would
+ * otherwise stretch a lone card across an ultrawide.
+ */
+export const AllStates: Story = {
+  args: { blockSizeResolver: fixedBlockSize(900) },
+  render: (gridProps) => (
+    <StoryGrid columns={1}>
+      <StoryCell align="stretch" label="one item">
+        <AdaptiveGrid {...gridProps}>
+          <Item label="Bay 1" />
+        </AdaptiveGrid>
+      </StoryCell>
+
+      <StoryCell align="stretch" label="nine items">
+        <AdaptiveGrid {...gridProps}>
+          {NINE_ITEMS.map((label) => (
+            <Item key={label} label={label} />
+          ))}
+        </AdaptiveGrid>
+      </StoryCell>
+    </StoryGrid>
+  ),
+}
+
+/**
+ * Three container widths, with the column floor dropped to 160px so
+ * the panels differ inside a docs page.
+ *
+ * The honest demonstration that the inline size is read from the
+ * **container** and not the window: the browser never moves, and
+ * the cap still falls from three columns to one.
+ */
+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>
+
+          <AdaptiveGrid {...gridProps}>
+            {NINE_ITEMS.slice(0, 6).map((label) => (
+              <Item key={label} label={label} />
+            ))}
+          </AdaptiveGrid>
+        </div>
+      ))}
+    </div>
+  ),
+}
+
+/**
+ * The manual override beside the automatic answer.
+ *
+ * A picker that only offered numbers once a number had been chosen
+ * would strand a person on a layout they tried once, so `"auto"` is
+ * always in the list.
+ */
+export const Interactive: Story = {
+  args: { blockSizeResolver: fixedBlockSize(1080) },
+  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}
+        />
+
+        <AdaptiveGrid
+          {...gridProps}
+          columns={
+            choice === "auto" ? undefined : Number(choice)
+          }
+        >
+          {NINE_ITEMS.map((label) => (
+            <Item key={label} label={label} />
+          ))}
+        </AdaptiveGrid>
+      </StorySection>
+    )
+  },
+}

package/src/AdaptiveGrid/AdaptiveGrid.test.tsx

@@ -0,0 +1,243 @@
+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 "./AdaptiveGrid.stories.tsx"
+
+/**
+ * The half of the rule that needs a browser.
+ *
+ * `chooseColumns.test.ts` proves the arithmetic at eleven sizes in
+ * Node. What only a real chromium can prove is that the arithmetic
+ * is fed the right numbers: that the inline size comes off a
+ * `ResizeObserver` on a container rather than off the window, that
+ * the measured box is not the capped box, and that `min-w-0`
+ * actually reaches children the caller owns.
+ *
+ * ### Neither viewport dimension is trusted here
+ *
+ * The runner's window is 414x896, so a test that let the grid read
+ * it would assert "one column" forever and prove nothing.
+ *
+ * The block size is pinned by the stories, which inject a
+ * `blockSizeResolver`. That seam is also what retires the source
+ * app's worst test gotcha: it had to write
+ * `Object.defineProperty(window, "innerHeight", { configurable:
+ * true, value })`, because under vitest browser mode `innerWidth`
+ * and `innerHeight` are read-only accessors backed by the real
+ * window and a plain assignment is a silent no-op that leaves the
+ * hook quietly reading the live viewport.
+ *
+ * The inline size is driven the honest way instead — by resizing
+ * the canvas the grid is measuring and waiting for the
+ * `ResizeObserver` to deliver. That is not a workaround; it is the
+ * only assertion in the file that proves the observer is wired at
+ * all.
+ */
+
+const { AllStates, AllVariants, Default, Responsive } =
+  composeStories(stories)
+
+/**
+ * The grids this component drew.
+ *
+ * Matched on `max-inline-size` rather than on
+ * `grid-template-columns`, which looks like the more obvious
+ * choice and is wrong: `StoryGrid` sets an inline
+ * `gridTemplateColumns` too, so the obvious selector returns the
+ * story furniture first and every assertion measures the board
+ * instead of the component.
+ */
+const getGrids = (canvasElement: HTMLElement) => [
+  ...canvasElement.querySelectorAll<HTMLElement>(
+    "[style*='max-inline-size']",
+  ),
+]
+
+/**
+ * The nth grid, or a thrown error naming what was missing.
+ *
+ * A helper rather than a `!`, because a non-null assertion in a test
+ * turns "the component rendered nothing" into a `TypeError` about
+ * `undefined`, several frames from the thing that actually went
+ * wrong.
+ */
+const getGrid = (
+  canvasElement: HTMLElement,
+  index = 0,
+): HTMLElement => {
+  const grid = getGrids(canvasElement)[index]
+
+  if (!grid) {
+    throw new Error(
+      `No AdaptiveGrid at index ${index}; found ${getGrids(canvasElement).length}.`,
+    )
+  }
+
+  return grid
+}
+
+const getFirstChild = (grid: HTMLElement): Element => {
+  const child = grid.firstElementChild
+
+  if (!child) {
+    throw new Error("The grid rendered no children.")
+  }
+
+  return child
+}
+
+const getTrackCount = (grid: HTMLElement) =>
+  getComputedStyle(grid)
+    .gridTemplateColumns.split(" ")
+    .filter(Boolean).length
+
+const mountAtInlineSize = async (
+  story: Parameters<typeof mountStory>[0],
+  inlineSize: number,
+) => {
+  const mounted = await mountStory(story)
+
+  mounted.canvasElement.style.inlineSize = `${inlineSize}px`
+
+  return mounted
+}
+
+test("the grid re-columns when its container resizes", async () => {
+  // The observer, end to end. Nine items in a 1080px-tall window
+  // need two stacks; at 700px wide only one column fits, and at
+  // 1280px the second one it wanted is finally allowed.
+  const { canvasElement } = await mountAtInlineSize(
+    Default,
+    700,
+  )
+
+  await waitFor(async () => {
+    await expect(
+      getTrackCount(getGrid(canvasElement)),
+    ).toBe(1)
+  })
+
+  canvasElement.style.inlineSize = "1280px"
+
+  await waitFor(async () => {
+    await expect(
+      getTrackCount(getGrid(canvasElement)),
+    ).toBe(2)
+  })
+})
+
+test("height buys the column, and width only caps it", async () => {
+  // 3440px of width and 1440px of height: nine items stack seven
+  // deep, so two columns carry them and the third the width would
+  // have allowed is refused. This is the "don't go 9-wide just
+  // because you're on an ultrawide" row of the spec, drawn.
+  const { canvasElement } = await mountAtInlineSize(
+    AllVariants,
+    3440,
+  )
+
+  await waitFor(async () => {
+    await expect(
+      getGrids(canvasElement).map(getTrackCount),
+    ).toEqual([2, 3, 3])
+  })
+})
+
+test("the content cap widens with the columns", async () => {
+  const { canvasElement } = await mountAtInlineSize(
+    Default,
+    1280,
+  )
+
+  // 34rem x 2 + 4rem. One column would have been 56rem — narrower
+  // than two columns, which is the entire point: the page is only
+  // allowed to get wide once there is something to fill it with.
+  await waitFor(async () => {
+    await expect(
+      getGrids(canvasElement)[0]?.style.maxInlineSize,
+    ).toBe("72rem")
+  })
+})
+
+test("the measured box is never the capped box", async () => {
+  const { canvasElement } = await mountAtInlineSize(
+    Default,
+    1280,
+  )
+
+  const grid = getGrid(canvasElement)
+
+  const measured = grid.parentElement
+
+  // The bug this shape exists to prevent has no error message: if
+  // the cap were applied to the element the `ResizeObserver`
+  // watches, the fold would read back its own narrowed output and
+  // could never widen again — one column, forever. So the observed
+  // ancestor must carry no inline-size cap of its own.
+  await expect(measured?.style.maxInlineSize).toBeFalsy()
+
+  await waitFor(async () => {
+    await expect(
+      measured?.getBoundingClientRect().width,
+    ).toBeGreaterThan(grid.getBoundingClientRect().width)
+  })
+})
+
+test("one item is one column at a reading measure", async () => {
+  const { canvasElement } = await mountAtInlineSize(
+    AllStates,
+    1280,
+  )
+
+  await waitFor(async () => {
+    const single = getGrid(canvasElement)
+
+    await expect(getTrackCount(single)).toBe(1)
+
+    // Not stretched across the monitor it was given.
+    await expect(single.style.maxInlineSize).toBe("56rem")
+  })
+})
+
+test("a long unbroken string does not push a track wide", async () => {
+  const { canvasElement } = await mountAtInlineSize(
+    Default,
+    1280,
+  )
+
+  // A grid item's automatic minimum size is `min-content`, so the
+  // long path in each card would otherwise widen its own track and
+  // shove the grid past its container. `[&>*]:min-w-0` is what
+  // stops it, and this asserts it reached children the story — not
+  // the component — owns.
+  await waitFor(async () => {
+    const grid = getGrid(canvasElement)
+
+    await expect(
+      getComputedStyle(getFirstChild(grid)).minWidth,
+    ).toBe("0px")
+
+    await expect(grid.scrollWidth).toBeLessThanOrEqual(
+      grid.clientWidth,
+    )
+  })
+})
+
+test("the inline size is read from the container, not the window", async () => {
+  const { canvasElement } = await mountAtInlineSize(
+    Responsive,
+    1280,
+  )
+
+  // Three grids, one browser window, three different answers. A
+  // hook reading `window.innerWidth` would have returned the same
+  // number three times — which is what the source app's did, and
+  // the one part of this port that is not a lift.
+  await waitFor(async () => {
+    await expect(
+      getGrids(canvasElement).map(getTrackCount),
+    ).toEqual([1, 2, 3])
+  })
+})

package/src/AdaptiveGrid/AdaptiveGrid.tsx

@@ -0,0 +1,150 @@
+import type { ReactNode } from "react"
+import { Children } from "react"
+
+import { toClassName } from "../toClassName.ts"
+import { getContentMaxInlineSize } from "./chooseColumns.ts"
+import type { BlockSizeResolver } from "./useAdaptiveColumns.ts"
+import { useAdaptiveColumns } from "./useAdaptiveColumns.ts"
+
+export type AdaptiveGridProps = {
+  /**
+   * Where the available block size is read from. Defaults to the
+   * viewport, which is the only thing that can answer "will this
+   * scroll".
+   */
+  blockSizeResolver?: BlockSizeResolver
+  children: ReactNode
+  /**
+   * Everything down the page that is not this grid, in CSS px —
+   * header, rails, filter rows. Subtracted before asking how many
+   * items stack.
+   */
+  chromeBlockSize?: number
+  className?: string
+  /**
+   * Draw this many columns instead of the automatic answer — the
+   * manual override, for a picker or a page that hoisted
+   * `useAdaptiveColumns` itself.
+   */
+  columns?: number
+  /**
+   * One item's block size in CSS px. **The one genuinely
+   * app-specific number.** Measure it off a running page and err
+   * high: a page that scrolls when it did not have to is the
+   * complaint this component exists to answer.
+   */
+  itemBlockSize: number
+  /**
+   * How many items to lay out. Defaults to the number of children,
+   * and is worth passing explicitly when the rendered count churns
+   * — a grid that reflowed every time one item finished loading
+   * would be worse than one that is an item out.
+   */
+  itemCount?: number
+  /** The most columns the automatic answer will take. */
+  maxColumns?: number
+  /** The narrowest a column may be, in CSS px. */
+  minColumnInlineSize?: number
+  /**
+   * The `localStorage` key a manual choice is remembered under.
+   * Namespace it to the app; omit it and nothing is written.
+   */
+  storageKey?: string
+}
+
+/**
+ * A wrapping grid that spends height before it spends width.
+ *
+ * The fleet's grids are `auto-fill, minmax()`: they take every
+ * column the window allows and land on seven items strung across an
+ * ultrawide. This one adds a column only when the items will not
+ * stack inside the viewport, and caps the content at a reading
+ * measure the rest of the time —
+ *
+ * > "The idea is that, if you're going to vertically scroll, it's
+ * > best to widen the displayed items. If not, then keep them in a
+ * > smaller grid, so they all still fit on screen."
+ *
+ * The rule itself is `chooseColumns`; the measuring is
+ * `useAdaptiveColumns`. This is the markup, and it exists because
+ * three separate things about that markup are easy to get wrong and
+ * silent when you do.
+ *
+ * ### Two boxes, and why it is not one
+ *
+ * The outer box is measured and **never capped**; the inner box
+ * carries the cap and the tracks. Collapsing them is a real bug
+ * with no error message: the cap narrows the content when the item
+ * count is low, so an element that is both measured and capped
+ * feeds the fold its own output and can never widen again. One
+ * column, forever.
+ *
+ * ### `min-w-0` on every child
+ *
+ * `[&>*]:min-w-0`, because a grid item's automatic minimum size is
+ * `min-content` — so one long unbroken string (a file path, a URL)
+ * pushes its track wider than its share and shoves the whole grid
+ * out of the viewport. The rule that stops it has to be on the
+ * children, and they belong to the caller, so it is applied from
+ * here rather than asked for.
+ *
+ * ### The tracks are an inline style
+ *
+ * `repeat(N, minmax(0, 1fr))` is interpolated, which a className
+ * may not be: Tailwind v4 scans source *text* for complete class
+ * strings, so `grid-cols-${columns}` generates nothing at all — no
+ * error, no warning, an unstyled element. A class-per-count would
+ * need every count to survive the scan; an inline style needs
+ * none.
+ */
+export const AdaptiveGrid = ({
+  blockSizeResolver,
+  children,
+  chromeBlockSize,
+  className,
+  columns,
+  itemBlockSize,
+  itemCount,
+  maxColumns,
+  minColumnInlineSize,
+  storageKey,
+}: AdaptiveGridProps): ReactNode => {
+  const layout = useAdaptiveColumns({
+    blockSizeResolver,
+    chromeBlockSize,
+    itemBlockSize,
+    itemCount: itemCount ?? Children.count(children),
+    maxAutoColumns: maxColumns,
+    minColumnInlineSize,
+    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. A four-column grid inside
+  // a one-column cap is the same bug as no cap at all, upside down.
+  const contentMaxInlineSize = getContentMaxInlineSize({
+    columns: drawnColumns,
+  })
+
+  return (
+    <div
+      className={toClassName(
+        "flex justify-center",
+        className,
+      )}
+      ref={layout.containerRef}
+    >
+      <div
+        className="grid w-full gap-4 [&>*]:min-w-0"
+        style={{
+          gridTemplateColumns: `repeat(${drawnColumns}, minmax(0, 1fr))`,
+          maxInlineSize: contentMaxInlineSize,
+        }}
+      >
+        {children}
+      </div>
+    </div>
+  )
+}