@charcuterie/ui 2.7.0 → 2.8.0

package/README.md

@@ -27,6 +27,17 @@ an accordion panel is [a `group` rather than a landmark](../../docs/decisions/20
 and [not every boolean is a state kind](../../docs/decisions/2026-07-31-not-every-boolean-is-a-state-kind.md).
 Full write-up: [M6a handoff](../../docs/2026-07-31-m6a-the-p1-components.md).
 
+**The link family** — `TextLink` and `ButtonLink` — closes the gap that had seven repos
+hand-rolling a `←` back-link, plex-channels navigating with
+`<button onClick={() => navigate(…)}>`, and mux-magic reloading the page through 14 raw
+`<a href>`. Buttons are for on-page actions; links are for navigation, and both of these
+render a real `<a href>` so middle-click, ctrl-click, open-in-new-tab and copy-link-address
+work. They differ in **paint, not semantics**
+([decision](../../docs/decisions/2026-08-10-buttons-are-actions-links-are-navigation.md)).
+The router is **injected** rather than depended on — `RouterLinkProvider` at the app root,
+with `@charcuterie/ui/react-router` as an optional subpath adapter and a plain `<a>` when
+nothing is provided. Recipe: **Guides/Routing** in Storybook.
+
 ## Install and wire
 
 ```ts

package/dist/AdaptiveGrid/AdaptiveGrid.d.ts

@@ -0,0 +1,94 @@
+import type { ReactNode } from "react";
+import type { BlockSizeResolver } 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 declare const AdaptiveGrid: ({ blockSizeResolver, children, chromeBlockSize, className, columns, itemBlockSize, itemCount, maxColumns, minColumnInlineSize, storageKey, }: AdaptiveGridProps) => ReactNode;
+//# sourceMappingURL=AdaptiveGrid.d.ts.map

package/dist/AdaptiveGrid/AdaptiveGrid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AdaptiveGrid.d.ts","sourceRoot":"","sources":["../../src/AdaptiveGrid/AdaptiveGrid.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAKtC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAA;AAGhE,MAAM,MAAM,iBAAiB,GAAG;IAC9B;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,iBAAiB,CAAA;IACrC,QAAQ,EAAE,SAAS,CAAA;IACnB;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;;;OAKG;IACH,aAAa,EAAE,MAAM,CAAA;IACrB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,uDAAuD;IACvD,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,gDAAgD;IAChD,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,eAAO,MAAM,YAAY,GAAI,8IAW1B,iBAAiB,KAAG,SAuCtB,CAAA"}

package/dist/AdaptiveGrid/AdaptiveGrid.js

@@ -0,0 +1,73 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Children } from "react";
+import { toClassName } from "../toClassName.js";
+import { getContentMaxInlineSize } from "./chooseColumns.js";
+import { useAdaptiveColumns } from "./useAdaptiveColumns.js";
+/**
+ * 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, }) => {
+    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 (_jsx("div", { className: toClassName("flex justify-center", className), ref: layout.containerRef, children: _jsx("div", { className: "grid w-full gap-4 [&>*]:min-w-0", style: {
+                gridTemplateColumns: `repeat(${drawnColumns}, minmax(0, 1fr))`,
+                maxInlineSize: contentMaxInlineSize,
+            }, children: children }) }));
+};
+//# sourceMappingURL=AdaptiveGrid.js.map

package/dist/AdaptiveGrid/AdaptiveGrid.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AdaptiveGrid.js","sourceRoot":"","sources":["../../src/AdaptiveGrid/AdaptiveGrid.tsx"],"names":[],"mappings":";AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAA;AAEhC,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAC/C,OAAO,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAA;AAE5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAA;AAgD5D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,EAC3B,iBAAiB,EACjB,QAAQ,EACR,eAAe,EACf,SAAS,EACT,OAAO,EACP,aAAa,EACb,SAAS,EACT,UAAU,EACV,mBAAmB,EACnB,UAAU,GACQ,EAAa,EAAE;IACjC,MAAM,MAAM,GAAG,kBAAkB,CAAC;QAChC,iBAAiB;QACjB,eAAe;QACf,aAAa;QACb,SAAS,EAAE,SAAS,IAAI,QAAQ,CAAC,KAAK,CAAC,QAAQ,CAAC;QAChD,cAAc,EAAE,UAAU;QAC1B,mBAAmB;QACnB,UAAU;KACX,CAAC,CAAA;IAEF,MAAM,YAAY,GAAG,OAAO,IAAI,MAAM,CAAC,OAAO,CAAA;IAE9C,iEAAiE;IACjE,kEAAkE;IAClE,kEAAkE;IAClE,MAAM,oBAAoB,GAAG,uBAAuB,CAAC;QACnD,OAAO,EAAE,YAAY;KACtB,CAAC,CAAA;IAEF,OAAO,CACL,cACE,SAAS,EAAE,WAAW,CACpB,qBAAqB,EACrB,SAAS,CACV,EACD,GAAG,EAAE,MAAM,CAAC,YAAY,YAExB,cACE,SAAS,EAAC,iCAAiC,EAC3C,KAAK,EAAE;gBACL,mBAAmB,EAAE,UAAU,YAAY,mBAAmB;gBAC9D,aAAa,EAAE,oBAAoB;aACpC,YAEA,QAAQ,GACL,GACF,CACP,CAAA;AACH,CAAC,CAAA"}

package/dist/AdaptiveGrid/chooseColumns.d.ts

@@ -0,0 +1,206 @@
+/**
+ * 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 declare 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 declare 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 declare const DEFAULT_MIN_COLUMN_INLINE_SIZE_PX: number;
+/**
+ * `"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 declare const chooseColumns: ({ availableBlockSize, availableInlineSize, chromeBlockSize, itemBlockSize, itemCount, maxColumns, minColumnInlineSize, }: {
+    /**
+     * 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;
+/**
+ * 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 declare const getContentMaxInlineSize: ({ columnInlineSize, columns, gutterInlineSize, singleInlineSize, }: {
+    /** 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;
+/**
+ * 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 declare const getColumnChoices: ({ maxColumns, }: {
+    maxColumns?: number;
+}) => ColumnChoice[];
+//# sourceMappingURL=chooseColumns.d.ts.map

package/dist/AdaptiveGrid/chooseColumns.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chooseColumns.d.ts","sourceRoot":"","sources":["../../src/AdaptiveGrid/chooseColumns.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAEH;;;;;;;;;GASG;AACH,eAAO,MAAM,wBAAwB,IAAI,CAAA;AAEzC;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,IAAI,CAAA;AAE3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,iCAAiC,QACH,CAAA;AAE3C;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,CAAA;AAE1C;;;GAGG;AACH,eAAO,MAAM,aAAa,GAAI,0HAQ3B;IACD;;;;;;;;OAQG;IACH,kBAAkB,EAAE,MAAM,CAAA;IAC1B;;;;;;;;;;;;OAYG;IACH,mBAAmB,EAAE,MAAM,CAAA;IAC3B;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB;;;;;;;;;;OAUG;IACH,aAAa,EAAE,MAAM,CAAA;IACrB;;;;;;OAMG;IACH,SAAS,EAAE,MAAM,CAAA;IACjB,oCAAoC;IACpC,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,6CAA6C;IAC7C,mBAAmB,CAAC,EAAE,MAAM,CAAA;CAC7B,KAAG,MA4BH,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,uBAAuB,GAAI,oEAKrC;IACD,wDAAwD;IACxD,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,OAAO,EAAE,MAAM,CAAA;IACf,8DAA8D;IAC9D,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,6CAA6C;IAC7C,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAC1B,KAAG,MAG6F,CAAA;AAEjG;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,GAAI,iBAE9B;IACD,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB,KAAG,YAAY,EAMf,CAAA"}

package/dist/AdaptiveGrid/chooseColumns.js

@@ -0,0 +1,156 @@
+import { containerQuery, contentInlineSize, } from "../tokens.js";
+/**
+ * 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;
+/**
+ * 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, }) => {
+    // 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, }) => 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, }) => [
+    "auto",
+    ...Array.from({ length: Math.max(1, maxColumns) }, (_, index) => index + 1),
+];
+//# sourceMappingURL=chooseColumns.js.map

package/dist/AdaptiveGrid/chooseColumns.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chooseColumns.js","sourceRoot":"","sources":["../../src/AdaptiveGrid/chooseColumns.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,iBAAiB,GAClB,MAAM,cAAc,CAAA;AAErB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAEH;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAA;AAEzC;;;;GAIG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,CAAA;AAE3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,CAAC,MAAM,iCAAiC,GAC5C,MAAM,CAAC,UAAU,CAAC,cAAc,CAAC,EAAE,CAAC,GAAG,EAAE,CAAA;AAO3C;;;GAGG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,EAC5B,kBAAkB,EAClB,mBAAmB,EACnB,eAAe,GAAG,CAAC,EACnB,aAAa,EACb,SAAS,EACT,UAAU,GAAG,wBAAwB,EACrC,mBAAmB,GAAG,iCAAiC,GAwDxD,EAAU,EAAE;IACX,8DAA8D;IAC9D,gEAAgE;IAChE,MAAM,aAAa,GAAG,IAAI,CAAC,GAAG,CAC5B,CAAC,EACD,IAAI,CAAC,GAAG,CACN,UAAU,EACV,IAAI,CAAC,KAAK,CAAC,mBAAmB,GAAG,mBAAmB,CAAC,CACtD,CACF,CAAA;IAED,IAAI,SAAS,IAAI,CAAC,EAAE,CAAC;QACnB,OAAO,CAAC,CAAA;IACV,CAAC;IAED,+DAA+D;IAC/D,6CAA6C;IAC7C,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAC1B,CAAC,EACD,IAAI,CAAC,KAAK,CACR,CAAC,kBAAkB,GAAG,eAAe,CAAC;QACpC,aAAa,CAChB,CACF,CAAA;IAED,MAAM,aAAa,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,GAAG,WAAW,CAAC,CAAA;IAExD,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,aAAa,EAAE,aAAa,CAAC,CAAC,CAAA;AAC5D,CAAC,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,EACtC,gBAAgB,GAAG,iBAAiB,CAAC,MAAM,EAC3C,OAAO,EACP,gBAAgB,GAAG,iBAAiB,CAAC,MAAM,EAC3C,gBAAgB,GAAG,iBAAiB,CAAC,MAAM,GAS5C,EAAU,EAAE,CACX,OAAO,IAAI,CAAC;IACV,CAAC,CAAC,gBAAgB;IAClB,CAAC,CAAC,GAAG,MAAM,CAAC,UAAU,CAAC,gBAAgB,CAAC,GAAG,OAAO,GAAG,MAAM,CAAC,UAAU,CAAC,gBAAgB,CAAC,KAAK,CAAA;AAEjG;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,EAC/B,UAAU,GAAG,0BAA0B,GAGxC,EAAkB,EAAE,CAAC;IACpB,MAAM;IACN,GAAG,KAAK,CAAC,IAAI,CACX,EAAE,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,UAAU,CAAC,EAAE,EACnC,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,GAAG,CAAC,CACxB;CACF,CAAA"}