@charcuterie/ui 2.7.0 → 2.9.0

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

package/src/AdaptiveGrid/chooseColumns.test.ts

@@ -0,0 +1,253 @@
+import { expect, test } from "vitest"
+
+import { containerQuery } from "../tokens.ts"
+import {
+  chooseColumns,
+  DEFAULT_MIN_COLUMN_INLINE_SIZE_PX,
+  getColumnChoices,
+  getContentMaxInlineSize,
+} from "./chooseColumns.ts"
+
+/**
+ * The heuristic, written down at eleven sizes.
+ *
+ * **This table is the spec**, ported from the app the rule came out
+ * of. The one instruction attached to this feature is "do not
+ * hand-tune breakpoints against one screenshot", and a table of
+ * sizes with the answers beside them is the only form in which that
+ * instruction can be checked — a browser sweep proves what happens
+ * at the four sizes somebody thought to open, and this proves the
+ * shape of the rule between them.
+ *
+ * Node, not the browser: there is nothing to render. The DOM half —
+ * measuring a container, resizing it, remembering a choice — is
+ * `AdaptiveGrid.test.tsx`.
+ */
+
+/** The rack the rule was tuned against. */
+const NINE_ITEMS = 9
+
+/** rip-deck's header, host row, drive rail, and bucket labels. */
+const CHROME_BLOCK_SIZE = 260
+
+/** A bay card, measured off a running page. */
+const ITEM_BLOCK_SIZE = 150
+
+const columnsAt = ({
+  blockSize,
+  inlineSize,
+  itemCount = NINE_ITEMS,
+  minColumnInlineSize,
+}: {
+  blockSize: number
+  inlineSize: number
+  itemCount?: number
+  minColumnInlineSize?: number
+}): number =>
+  chooseColumns({
+    availableBlockSize: blockSize,
+    availableInlineSize: inlineSize,
+    chromeBlockSize: CHROME_BLOCK_SIZE,
+    itemBlockSize: ITEM_BLOCK_SIZE,
+    itemCount,
+    minColumnInlineSize,
+  })
+
+test("the column floor is Charcuterie's own cq-sm step", () => {
+  // The threshold reconciliation, asserted rather than described.
+  // A bare `380` in this file would drift the moment somebody
+  // touched the scale; deriving it from `containerQuery.sm` means
+  // the grid's floor and the library's container-query steps move
+  // together or not at all.
+  expect(DEFAULT_MIN_COLUMN_INLINE_SIZE_PX).toBe(
+    Number.parseFloat(containerQuery.sm) * 16,
+  )
+
+  // And it stays a step BELOW the size at which this library's
+  // container-query components change shape. The denser card that
+  // appears under `cq-md` is a real density, not a failure, so a
+  // column narrower than it is still a column worth having.
+  expect(DEFAULT_MIN_COLUMN_INLINE_SIZE_PX).toBeLessThan(
+    Number.parseFloat(containerQuery.md) * 16,
+  )
+})
+
+test("moving the floor from the measured 380 to cq-sm changes no answer", () => {
+  // The empirical half of that decision. The source app's floor was
+  // hand-measured at 380px; `cq-sm` is 384. Every row of the table
+  // below gives the same answer at either number, which is what
+  // makes swapping a magic number for a token a rename rather than
+  // a behaviour change.
+  for (const size of [
+    { blockSize: 1440, inlineSize: 3440 },
+    { blockSize: 700, inlineSize: 3440 },
+    { blockSize: 400, inlineSize: 5120 },
+    { blockSize: 844, inlineSize: 390 },
+    { blockSize: 390, inlineSize: 844 },
+    { blockSize: 1180, inlineSize: 820 },
+    { blockSize: 800, inlineSize: 1280 },
+    { blockSize: 900, inlineSize: 1440 },
+    { blockSize: 1080, inlineSize: 1920 },
+    { blockSize: 600, inlineSize: 1920 },
+    { blockSize: 1440, inlineSize: 2560 },
+  ]) {
+    expect(
+      columnsAt({ ...size, minColumnInlineSize: 380 }),
+    ).toBe(columnsAt(size))
+  }
+})
+
+test("it stays narrow on an ultrawide that is also tall", () => {
+  // The sentence the whole feature exists for:
+  //
+  // > "That way, you don't get 9-wide just because you're on an
+  // > ultrawide even if you have more height available."
+  expect(
+    columnsAt({ blockSize: 1440, inlineSize: 3440 }),
+  ).toBe(2)
+})
+
+test("it goes as wide as it may when the height runs out", () => {
+  // The same monitor, a short window. Nine items cannot stack in
+  // 700px, so inline size is all that is left.
+  expect(
+    columnsAt({ blockSize: 700, inlineSize: 3440 }),
+  ).toBe(3)
+})
+
+test("it never reaches the 9-wide the owner called weird", () => {
+  // Every item, no height at all, and a monitor wide enough to hold
+  // nine of them side by side.
+  expect(
+    columnsAt({ blockSize: 400, inlineSize: 5120 }),
+  ).toBeLessThanOrEqual(3)
+})
+
+test("one item gets one column however big the window", () => {
+  expect(
+    columnsAt({
+      blockSize: 400,
+      inlineSize: 3440,
+      itemCount: 1,
+    }),
+  ).toBe(1)
+})
+
+test("a phone stays at one column", () => {
+  // One column is the owner's own answer, and it falls out of the
+  // inline-size cap rather than out of a device check.
+  expect(
+    columnsAt({ blockSize: 844, inlineSize: 390 }),
+  ).toBe(1)
+})
+
+test("a phone held sideways takes two", () => {
+  // Short AND narrow: the height rule wants more columns and cannot
+  // have them.
+  expect(
+    columnsAt({ blockSize: 390, inlineSize: 844 }),
+  ).toBe(2)
+})
+
+test("a tablet takes two", () => {
+  expect(
+    columnsAt({ blockSize: 1180, inlineSize: 820 }),
+  ).toBe(2)
+})
+
+/**
+ * Note 1440x900 taking THREE columns while the larger 1920x1080
+ * takes two. That reads backwards and it is the rule working: the
+ * taller window stacks nine items in fewer stacks, so it needs
+ * fewer. Inline size is only ever the cap.
+ */
+test.each([
+  { blockSize: 800, expected: 3, inlineSize: 1280 },
+  { blockSize: 900, expected: 3, inlineSize: 1440 },
+  { blockSize: 1080, expected: 2, inlineSize: 1920 },
+  { blockSize: 600, expected: 3, inlineSize: 1920 },
+  { blockSize: 1440, expected: 2, inlineSize: 2560 },
+])(
+  "$inlineSize x $blockSize renders $expected columns",
+  ({ blockSize, expected, inlineSize }) => {
+    expect(columnsAt({ blockSize, inlineSize })).toBe(
+      expected,
+    )
+  },
+)
+
+test("the cap is a default, not a constant", () => {
+  // The taste half. An app of squarer items raises it and gets the
+  // fourth column the source app deliberately refused.
+  expect(
+    chooseColumns({
+      availableBlockSize: 400,
+      availableInlineSize: 5120,
+      chromeBlockSize: CHROME_BLOCK_SIZE,
+      itemBlockSize: ITEM_BLOCK_SIZE,
+      itemCount: NINE_ITEMS,
+      maxColumns: 6,
+    }),
+  ).toBe(6)
+})
+
+test("chrome is a parameter, and it costs columns", () => {
+  // rip-deck's 260px of header and rails was a module-private
+  // constant. An app with no chrome stacks more items in the same
+  // window, so it needs fewer stacks.
+  const withChrome = chooseColumns({
+    availableBlockSize: 900,
+    availableInlineSize: 1440,
+    chromeBlockSize: 260,
+    itemBlockSize: ITEM_BLOCK_SIZE,
+    itemCount: NINE_ITEMS,
+  })
+
+  const withoutChrome = chooseColumns({
+    availableBlockSize: 900,
+    availableInlineSize: 1440,
+    itemBlockSize: ITEM_BLOCK_SIZE,
+    itemCount: NINE_ITEMS,
+  })
+
+  expect(withChrome).toBe(3)
+
+  expect(withoutChrome).toBe(2)
+})
+
+test("the content cap does not stretch one column across a monitor", () => {
+  expect(getContentMaxInlineSize({ columns: 1 })).toBe(
+    "56rem",
+  )
+})
+
+test("the content cap widens as columns are added", () => {
+  // "…the wrapping grids are all full-width only when you have too
+  // many items."
+  expect(
+    [1, 2, 3, 4].map((columns) =>
+      Number.parseFloat(
+        getContentMaxInlineSize({ columns }),
+      ),
+    ),
+  ).toEqual([56, 72, 106, 140])
+})
+
+test("the content cap's parts are overridable", () => {
+  expect(
+    getContentMaxInlineSize({
+      columnInlineSize: "20rem",
+      columns: 2,
+      gutterInlineSize: "2rem",
+    }),
+  ).toBe("42rem")
+})
+
+test("a picker never offers a count the cap will refuse", () => {
+  expect(getColumnChoices({ maxColumns: 3 })).toEqual([
+    "auto",
+    1,
+    2,
+    3,
+  ])
+})

package/src/AdaptiveGrid/chooseColumns.ts

@@ -0,0 +1,270 @@
+import {
+  containerQuery,
+  contentInlineSize,
+} from "../tokens.ts"
+
+/**
+ * How many columns a wrapping grid should draw, and how wide the
+ * page around it may get.
+ *
+ * The arithmetic, lifted out of rip-deck's `useLayoutColumns` and
+ * made generic. It stays a pure fold — no `window`, no ref, no
+ * React — because a heuristic nobody can unit-test at nine sizes is
+ * a heuristic hand-tuned against one screenshot, and the table in
+ * `chooseColumns.test.ts` is the only form in which the rule can be
+ * checked at all.
+ *
+ * ## Height is spent first
+ *
+ * The owner's ask, which is the whole design:
+ *
+ * > "All these apps seem to be really narrow with a very large
+ * > max-width — 1 column, but waaaaaaay too wide. What I really
+ * > want is something like Rip-Deck where the app has a narrower
+ * > main column but the wrapping grids are all full-width only when
+ * > you have too many items. […] 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. Ideally, we wouldn't require users to scroll."
+ *
+ * And the sentence it replaced, from the app this came out of:
+ *
+ * > "Like if you have enough height, try to fill it. If you don't,
+ * > then abuse as much width side-by-side as possible. That way,
+ * > you don't get 9-wide just because you're on an ultrawide even
+ * > if you have more height available."
+ *
+ * Stated plainly: **a column is something the layout is FORCED
+ * into** when the items will not stack inside the space available —
+ * never something it takes merely because a monitor is wide. That
+ * inversion is why `availableInlineSize` only ever *caps* the
+ * answer here rather than producing it, and it is the opposite of
+ * every `auto-fill, minmax()` grid in the fleet, which takes every
+ * column the width allows and lands on seven items across an
+ * ultrawide.
+ *
+ * The visible consequence is deliberately non-monotonic: 1440x900
+ * takes three columns while the *larger* 1920x1080 takes two. That
+ * reads backwards and is the rule working — the taller window
+ * stacks the same items in fewer stacks, so it needs fewer.
+ */
+
+/**
+ * The most columns the automatic answer will ever choose.
+ *
+ * > "It would look weird to do 9 side-by-side."
+ *
+ * Three is the number the owner said he could "easily fit". A
+ * caller with squarer content raises it; a caller with wide content
+ * lowers it. It is taste about one app's content, which is exactly
+ * why it is a default rather than a constant.
+ */
+export const DEFAULT_MAX_AUTO_COLUMNS = 3
+
+/**
+ * The widest a manual picker offers, one above the automatic cap —
+ * because a cap is a default and not a ceiling on what a person is
+ * allowed to ask for.
+ */
+export const DEFAULT_MAX_MANUAL_COLUMNS = 4
+
+/**
+ * The narrowest a column may be, in CSS px, before the grid stops
+ * adding them. `24rem` at a 16px root — `containerQuery.sm`.
+ *
+ * ## Which threshold system this is, and which it is not
+ *
+ * Two live in the fleet today and they answer different questions,
+ * so this reconciles them by *keeping them apart*:
+ *
+ *  - A `cq-*` step is read **by the item, inside the track**: "how
+ *    should this card lay itself out at the width it was handed."
+ *    Charcuterie's are `--cq-xs` … `--cq-xl`, deliberately not
+ *    Tailwind's `--container-*` (see
+ *    `docs/decisions/2026-07-29-container-query-scale-is-cq-not-container.md`).
+ *  - This number is read **by the grid, outside the item**: "is
+ *    another track worth having at all."
+ *
+ * Nothing forces them to agree, and the source app's did not: its
+ * cards restyle at Tailwind's own `28rem` container variant while
+ * its grid floor sat at a hand-measured `380px`. It set the floor
+ * *below* the restyle threshold on purpose, because the denser card
+ * that appears under it is a real density rather than a failure.
+ *
+ * That relationship is what survives here, expressed in
+ * Charcuterie's own scale instead of a magic number: the floor
+ * defaults to `cq-sm` (24rem = 384px), which is within 4px of the
+ * measured 380 — every row of the ported spec table gives the same
+ * answer at either value — and stays a step below `cq-md` (32rem),
+ * where the library's own container-query components change shape.
+ *
+ * The link is asserted in `chooseColumns.test.ts` so it cannot
+ * drift back into a bare number.
+ */
+export const DEFAULT_MIN_COLUMN_INLINE_SIZE_PX =
+  Number.parseFloat(containerQuery.sm) * 16
+
+/**
+ * `"auto"`, or the number of columns a person explicitly asked for.
+ */
+export type ColumnChoice = "auto" | number
+
+/**
+ * The column count the automatic rule wants, for one measured space
+ * and one set of items.
+ */
+export const chooseColumns = ({
+  availableBlockSize,
+  availableInlineSize,
+  chromeBlockSize = 0,
+  itemBlockSize,
+  itemCount,
+  maxColumns = DEFAULT_MAX_AUTO_COLUMNS,
+  minColumnInlineSize = DEFAULT_MIN_COLUMN_INLINE_SIZE_PX,
+}: {
+  /**
+   * The block size the layout has to spend, in CSS px — the
+   * viewport's, not the grid's.
+   *
+   * It has to come from the viewport, because the question being
+   * asked is "will this scroll", and an element's own block size
+   * cannot answer it: a grid in normal flow is exactly as tall as
+   * its contents, so measuring it always says "it fits."
+   */
+  availableBlockSize: number
+  /**
+   * The inline size the grid has to spend, in CSS px — the
+   * container's, not the viewport's.
+   *
+   * The container is the honest source here: a grid sitting beside
+   * a rail has less room than the window suggests, and this library
+   * is built around the case where "the component's container is
+   * what changed, not the window."
+   *
+   * It must be measured on an element that is **not itself capped
+   * by the answer**, or the fold feeds on its own output and can
+   * never widen. `AdaptiveGrid` guarantees that structurally.
+   */
+  availableInlineSize: number
+  /**
+   * Everything down the page that is not this grid, in CSS px —
+   * headers, rails, filter rows, labels. Subtracted from
+   * `availableBlockSize` before asking how many items stack.
+   */
+  chromeBlockSize?: number
+  /**
+   * One item's block size, in CSS px. **The one genuinely
+   * app-specific number**, and the only required one.
+   *
+   * Measure it off a running page rather than deriving it, and err
+   * high: over-estimating means the grid reaches for a column
+   * slightly early, and a page that scrolls when it did not have to
+   * is the complaint this exists to answer. It only has to be right
+   * to within about an item — being one out shifts a borderline
+   * size by one column, which is taste.
+   */
+  itemBlockSize: number
+  /**
+   * How many items the grid is being asked to fit.
+   *
+   * The stable count rather than the rendered one where those
+   * differ: a column count that reflowed every time one item
+   * finished loading would be worse than one that is an item out.
+   */
+  itemCount: number
+  /** @see DEFAULT_MAX_AUTO_COLUMNS */
+  maxColumns?: number
+  /** @see DEFAULT_MIN_COLUMN_INLINE_SIZE_PX */
+  minColumnInlineSize?: number
+}): number => {
+  // Inline size is a CAP, never a reason. This is the "don't go
+  // 9-wide just because you're on an ultrawide" half of the rule.
+  const inlineSizeCap = Math.max(
+    1,
+    Math.min(
+      maxColumns,
+      Math.floor(availableInlineSize / minColumnInlineSize),
+    ),
+  )
+
+  if (itemCount <= 1) {
+    return 1
+  }
+
+  // Block size is the reason. How many items stack in the space,
+  // then how many stacks that many items need.
+  const rowsThatFit = Math.max(
+    1,
+    Math.floor(
+      (availableBlockSize - chromeBlockSize) /
+        itemBlockSize,
+    ),
+  )
+
+  const columnsNeeded = Math.ceil(itemCount / rowsThatFit)
+
+  return Math.max(1, Math.min(inlineSizeCap, columnsNeeded))
+}
+
+/**
+ * How wide the content around the grid may grow, as a CSS length.
+ *
+ * The other half of the ask — "the app has a narrower main column
+ * but the wrapping grids are all full-width only when you have too
+ * many items." 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 across a monitor. Past that the cap **grows with
+ * the columns**, so three columns get room to be three readable
+ * things rather than three slivers.
+ *
+ * ### Why the numbers live in `@charcuterie/tokens`
+ *
+ * They are `contentInlineSize`, not constants in this file. A
+ * readable measure is a structural fact about the fleet in exactly
+ * the sense `screen` and `containerQuery` are — a variant may
+ * change how a card *looks*, not how far the eye tracks — so it
+ * belongs in the one package a Satori renderer or a plain-CSS
+ * consumer can read without a React tree. The *arithmetic* is not a
+ * token, and stays here.
+ *
+ * The three parts are still overridable per call, because an app of
+ * dense tables and an app of prose disagree about a measure and
+ * neither is wrong.
+ */
+export const getContentMaxInlineSize = ({
+  columnInlineSize = contentInlineSize.column,
+  columns,
+  gutterInlineSize = contentInlineSize.gutter,
+  singleInlineSize = contentInlineSize.single,
+}: {
+  /** What one column is worth, once there are several. */
+  columnInlineSize?: string
+  columns: number
+  /** Slack added on top of a multi-column cap, for the gaps. */
+  gutterInlineSize?: string
+  /** The cap when there is only one column. */
+  singleInlineSize?: string
+}): string =>
+  columns <= 1
+    ? singleInlineSize
+    : `${Number.parseFloat(columnInlineSize) * columns + Number.parseFloat(gutterInlineSize)}rem`
+
+/**
+ * The choices a manual picker offers: `"auto"`, then every count up
+ * to `maxColumns`.
+ *
+ * A function rather than a constant so the picker and the cap
+ * cannot disagree — an app that lowers its cap gets a shorter list
+ * for free, instead of offering a count it will then refuse.
+ */
+export const getColumnChoices = ({
+  maxColumns = DEFAULT_MAX_MANUAL_COLUMNS,
+}: {
+  maxColumns?: number
+}): ColumnChoice[] => [
+  "auto",
+  ...Array.from(
+    { length: Math.max(1, maxColumns) },
+    (_, index) => index + 1,
+  ),
+]