@charcuterie/ui 2.7.0 → 2.9.0

package/src/AdaptiveGrid/AdaptiveGrid.mdx

@@ -0,0 +1,169 @@
+import { Canvas, Controls, Meta } from "@storybook/addon-docs/blocks";
+
+import * as AdaptiveGridStories from "./AdaptiveGrid.stories";
+
+<Meta of={AdaptiveGridStories} />
+
+# AdaptiveGrid
+
+**Height is spent before width.** A column is something this grid is *forced* into when
+the items will not stack inside the window — never something it takes because a monitor
+is wide.
+
+That is the opposite of every wrapping grid in the fleet today. `auto-fill, minmax()`
+takes every column the width allows, which is how you end up with seven items strung
+across an ultrawide and nothing below the fold.
+
+<Canvas of={AdaptiveGridStories.Default} />
+
+## Props
+
+<Controls />
+
+## The rule in one sentence
+
+> If you're going to vertically scroll anyway, widen the items. If you're not, keep them
+> in a smaller grid so they all still fit on screen.
+
+Mechanically:
+
+1. Ask how many items stack in the space available — the viewport's block size, minus
+   whatever chrome sits above and below.
+2. Divide the item count by that. **That** is how many columns are needed.
+3. Only then ask how many columns actually fit across the container, and take the smaller
+   of the two.
+
+Step 3 can only ever *reduce* the answer. Width is a veto, not a reason.
+
+## The part that reads backwards
+
+<Canvas of={AdaptiveGridStories.AllVariants} />
+
+Same nine items, same width, three heights — and the **taller** window takes **fewer**
+columns. A 1440x900 laptop gets three columns while a larger 1920x1080 monitor gets two.
+
+That is not a bug and it is not a tuned breakpoint. The taller window stacks the same nine
+items in fewer stacks, so it needs fewer stacks. If you "fix" it, you have thrown the rule
+away and rebuilt `auto-fill`.
+
+## The content cap widens as columns are added
+
+The other half of the complaint this answers is pages that are "1 column, but waaaaaaay
+too wide". So the cap around the grid is not a constant:
+
+| Columns | Cap |
+| --- | --- |
+| 1 | 56rem |
+| 2 | 72rem |
+| 3 | 106rem |
+| 4 | 140rem |
+
+One column stays at a reading measure, because a 2000px-wide card is not a better card —
+it is one line of text the eye has to track from bezel to bezel. The page earns its width
+by having something to fill it with.
+
+The three numbers behind that table are `contentInlineSize` in `@charcuterie/tokens`,
+beside `screen` and `containerQuery`, and every part is overridable per call. The
+arithmetic lives in `getContentMaxInlineSize` and is not a token.
+
+## When to reach for it
+
+Reach for it when **all** of these are true:
+
+- The items wrap, and there could be few or many of them.
+- They are roughly the same height, and you can measure one.
+- Scrolling is a cost rather than the point — a rack of bays, a fleet of hosts, a set of
+  status cards. Ideally the user never scrolls at all.
+
+Do **not** reach for it for a feed, a search-results list, or anything else that is
+inherently long. The rule optimises for "it all fits", and content that will never all fit
+gets nothing from it.
+
+## The one number you must measure
+
+`itemBlockSize` is the only required option and the only genuinely app-specific one.
+Measure it off a running page rather than deriving it from padding, and **err high** — over-
+estimating makes the grid reach for a column slightly early, and a page that scrolls when
+it did not have to is the entire complaint. It only has to be right to within about one
+item; being one out shifts a borderline window by one column, which is taste.
+
+`chromeBlockSize` is everything down the page that is not the grid: header, rails, filter
+rows, labels. It defaults to `0`.
+
+## It measures its container, not the window
+
+<Canvas of={AdaptiveGridStories.Responsive} />
+
+Three grids, one browser window, three different answers. The inline size comes off a
+`ResizeObserver` on the grid's own container, so a grid sitting beside a rail is told the
+truth about the room it has — the container-query thesis this library is built on, applied
+to a layout decision instead of a card's internals.
+
+The block size is the exception, and it has to be: the question is "will this scroll", and
+an element in normal flow is exactly as tall as its contents, so measuring the grid always
+answers "it fits." That number comes from the viewport, behind an injectable
+`blockSizeResolver` for Electron windows, fixed-height kiosk panels, and tests.
+
+⚠️ **Never apply the returned cap to the element being measured.** If you wire
+`useAdaptiveColumns` by hand, the observed box and the capped box must be different
+elements. Collapse them and the fold reads back its own narrowed output: one column,
+forever, with no error anywhere. `AdaptiveGrid` enforces this structurally — an uncapped
+outer box it measures, an inner box it caps.
+
+## Composing with a shell
+
+`AdaptiveGrid` caps itself, so it is correct standing alone. If you want the **page chrome**
+to widen with the grid rather than the grid rattling around inside a fixed column, hoist
+the hook to the page and hand the pieces out:
+
+```tsx
+const layout = useAdaptiveColumns({
+  chromeBlockSize: 260,
+  itemBlockSize: 150,
+  itemCount: bays.length,
+  storageKey: "rip-deck.layout-columns",
+})
+
+<Main maxInlineSize={layout.contentMaxInlineSize} ref={layout.containerRef}>
+  <AdaptiveGrid columns={layout.columns} itemBlockSize={150}>
+    {bays.map(…)}
+  </AdaptiveGrid>
+</Main>
+```
+
+The `Main` region takes a caller-supplied max inline size; the ref goes on whatever box
+sits **outside** that cap.
+
+## Manual override
+
+<Canvas of={AdaptiveGridStories.Interactive} />
+
+`"auto"` is always in the list. A picker that only offers numbers once a number has been
+chosen is a one-way door — it strands someone on a layout they tried once with no route
+back to the mode that adapts.
+
+Pass `storageKey` to remember the choice across visits, namespaced to your app; the
+library will not invent that string for you. Omit it and the choice lasts the session and
+is written nowhere. Every unreadable stored value — a corrupt key, a browser that refuses
+storage, a count the picker cannot offer — falls back to `"auto"`, so a bad value costs a
+preference rather than a page.
+
+## Why the tracks are an inline style
+
+`repeat(N, minmax(0, 1fr))` is interpolated, and 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. `tailwindCandidates.test.ts` rejects the
+interpolated form outright.
+
+## `min-w-0` is not optional
+
+Every child gets `min-w-0`, applied by the component rather than asked for. A grid item's
+automatic minimum size is `min-content`, so one long unbroken string — a file path, a URL —
+widens its own track and shoves the whole grid past the viewport. The rule that stops it
+has to sit on children the caller owns, which is why it is not your job to remember.
+
+You still owe your own items a wrap or a `truncate`; `min-w-0` lets the track get small
+enough for that clipping to matter.
+
+<Canvas of={AdaptiveGridStories.AllStates} />

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