basalt-ui 1.31.0 → 1.32.1

package/CHANGELOG.md

@@ -1,3 +1,37 @@
+## [1.32.1](https://github.com/jkrumm/basalt-ui/compare/v1.32.0...v1.32.1) (2026-09-30)
+
+
+### Bug Fixes
+
+* align guard lanes on FormRow/FormGroup, drop basalt-main ([17e673d](https://github.com/jkrumm/basalt-ui/commit/17e673d421c3e2f93be01c2b8d24e10e56d5b71c))
+* bottom-align FormGroup's row direction so a trailing button isn't stretched ([e5ca2ab](https://github.com/jkrumm/basalt-ui/commit/e5ca2ab5e433e4e3ef15f505913c672b4912f0e9))
+* export the size- and container-class tables from basalt-ui/tokens ([14fb784](https://github.com/jkrumm/basalt-ui/commit/14fb784586c3348a3647280e74ea905b2df0091b))
+* point every § Unreleased reference at the section the release names ([bc17710](https://github.com/jkrumm/basalt-ui/commit/bc1771001048f2883607d6917e6f94cc397865be))
+* resolve consts before unwrapping raw-breakpoint conditionals ([4f9cc79](https://github.com/jkrumm/basalt-ui/commit/4f9cc7912ae0805eb5e574f8ed8a8f9c068e0ddf))
+
+# [1.32.0](https://github.com/jkrumm/basalt-ui/compare/v1.31.0...v1.32.0) (2026-09-30)
+
+
+### Bug Fixes
+
+* build BasaltDataTable cards only in card mode, guard the routed-prop lookup ([4024e83](https://github.com/jkrumm/basalt-ui/commit/4024e8333c83cb4808507929f47246209e67a00a))
+* exempt a container Grid only when its breakpoints map resolves ([d6d9bda](https://github.com/jkrumm/basalt-ui/commit/d6d9bdaa7eb693a01166d121fdc5bb95002bb09d))
+* honour maxHeight in BasaltDataTable's card projection ([3b59a2f](https://github.com/jkrumm/basalt-ui/commit/3b59a2f5304969e0dcadfa77b1ff375fd0f1d048))
+* key StatGroup and WidgetGrid on the container-class law ([db6e130](https://github.com/jkrumm/basalt-ui/commit/db6e130d050d562926fce63e7f1a5e3d0aeb45f8))
+* move raw-media-query's promotion to 1.33.0 with its AST twin ([ac2641c](https://github.com/jkrumm/basalt-ui/commit/ac2641c4ac1fcb42b2381758ae9a2b20809ce630))
+* move useBreakpoint's removal to 1.33.0 and correct its replacement ([a2c356b](https://github.com/jkrumm/basalt-ui/commit/a2c356bd1979960b8b9fc26eb8341cc84d3e88ee))
+* narrow the container-grid exemption to the props Mantine routes ([d547022](https://github.com/jkrumm/basalt-ui/commit/d5470226008984fba39849062c0ee0abbac178cc))
+* prune ignored dirs during the doc-drift repo walk instead of after it ([a4647dc](https://github.com/jkrumm/basalt-ui/commit/a4647dcd380f74f7ac73989fa6857d2041d16a23))
+* read only width clauses when judging a shell/ media query ([3f14b7f](https://github.com/jkrumm/basalt-ui/commit/3f14b7f342c64c9f2b7b1b04887930f37f695f01))
+* say legend.maxRows changed unit in its deprecation warning ([29ad3a5](https://github.com/jkrumm/basalt-ui/commit/29ad3a5183648a0edc71250b22a996fa818edfb8))
+* stop warning legend-slot contention on a same-commit owner hand-off ([af18cfa](https://github.com/jkrumm/basalt-ui/commit/af18cfad7c3d9747a7cc6c0a117db34bbb8cd531))
+
+
+### Features
+
+* give basalt/raw-breakpoint a reachable container-grid answer ([2bf4a22](https://github.com/jkrumm/basalt-ui/commit/2bf4a2256fff9b08adcd6c3716b92993b4fdb40a))
+* project BasaltDataTable rows as cards on the table's own width ([f201b2a](https://github.com/jkrumm/basalt-ui/commit/f201b2ac81726fc47b2adb5660fd42ce2c881b3e))
+
 # [1.31.0](https://github.com/jkrumm/basalt-ui/compare/v1.30.2...v1.31.0) (2026-09-28)
 
 

package/MIGRATING.md

@@ -66,18 +66,18 @@ There is one row per SURFACE, not per export, and a surface earns a row once any
 shipped lefthook preset both changed in 1.30.0 with no row that owned them — which is how a
 consumer read this index, found nothing, and diffed a KPI row that had silently gone 4-up → 2-up.
 
-| Surface                       | 1.27.0                                                       | 1.28.0                                                                                 | 1.29.0                                                                                         | 1.30.0                                                                             | 1.30.1                                                                | 1.30.2 | 1.31.0                                                                                                    | Unreleased |
-| ----------------------------- | ------------------------------------------------------------ | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | --------------------------------------------------------------------- | ------ | --------------------------------------------------------------------------------------------------------- | ---------- |
-| **tokens** (`./tokens`)       | —                                                            | `--vx-divider` → `rgba()` on both schemes (§ Shell)                                    | `--vx-space-touch-target` added (§ Additions)                                                  | eight spacing numbers (§ Chrome)                                                   | —                                                                     | —      | `--vx-hit` replaces the touch vars; `SIZE_CLASSES` (§ Unreleased)                                         | —          |
-| **charts** (`./charts`)       | —                                                            | phone tier, `curve`, formatters, `state`, log axis (§ preamble)                        | `ChartState.empty: string`, `AxisBottomNumeric` (§ Additions)                                  | responsive `height`, `legend.maxRows` (§ Charts)                                   | `height` reaches the kinds; `maxRows` beats the `fill` fit (§ Charts) | —      | container-class tier + `height` keys (§ Unreleased)                                                       | —          |
-| **shell** (`.`)               | —                                                            | scrollport, region seams, **the brand left the sidebar** (§§ scrollport, brand, Shell) | `PageTitle`, `BasaltDevDock`, `useBreakpoint` (§ Additions)                                    | More popover, aside pill, the responsive gutter, `useBasaltSpacing` (§ Chrome)     | —                                                                     | —      | `theme.breakpoints` derived, `useSizeClass`, `data-basalt-host`, `useBreakpoint` on notice (§ Unreleased) | —          |
-| **controls** (`./controls`)   | `NumberFilter`, `field.number` (§ Controls)                  | sheet renders panel rows; `PanelRow`, `SliderControl` (§ `basalt-ui/controls`)         | —                                                                                              | —                                                                                  | —                                                                     | —      | —                                                                                                         | —          |
-| **forms** (`./forms`)         | —                                                            | `field` → `inputProps`, **`inputProps` drops `key`**, the layout tier (§ `inputProps`) | `field` DELETED — and the `--fix` recipe no longer works (§ Consolidation)                     | —                                                                                  | —                                                                     | —      | —                                                                                                         | —          |
-| **data** (`./data/table`)     | —                                                            | root is a `<div>`, row selection, `getItemKey` required (§ `basalt-ui/data`)           | `./data` + `./query` + `./connectivity` dropped (§ Consolidation)                              | —                                                                                  | —                                                                     | —      | —                                                                                                         | —          |
-| **dashboard** (`.`)           | `StatCard`: `unit`, `breakdown`, delta format (§ `StatCard`) | `StatGroup`, `WidgetGrid`, query-aware `StatCard` — additive                           | —                                                                                              | **the column law keys on the CONTAINER; `cols={4}` is 2-up at `sm`** (§ Dashboard) | —                                                                     | —      | —                                                                                                         | —          |
-| **toolchain** (`./configs/*`) | —                                                            | —                                                                                      | the shipped lefthook preset's `check-theme` BROKE — the CLI resolver stopped ascending (§ CLI) | the preset's default bin, and the `root:` recipe (§ Toolchain)                     | —                                                                     | —      | —                                                                                                         | —          |
-| **CLI** (`basalt-ui`)         | —                                                            | —                                                                                      | **resolver stops relocating; `doctor` loses 6 of 10 checks** (§ CLI)                           | —                                                                                  | —                                                                     | —      | —                                                                                                         | —          |
-| **guards**                    | five rules → `error` (§ Guards)                              | six new ids at `warn` (§ preamble)                                                     | `query-dual-import` retired in 1.29.1 (§ Guards)                                               | four rules → `error` (§ Guards)                                                    | —                                                                     | —      | —                                                                                                         | —          |
+| Surface                       | 1.27.0                                                       | 1.28.0                                                                                 | 1.29.0                                                                                         | 1.30.0                                                                             | 1.30.1                                                                | 1.30.2 | 1.31.0                                                                                                | 1.32.0                                                                    | 1.32.1                                                                                                          | Unreleased |
+| ----------------------------- | ------------------------------------------------------------ | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | --------------------------------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | ---------- |
+| **tokens** (`./tokens`)       | —                                                            | `--vx-divider` → `rgba()` on both schemes (§ Shell)                                    | `--vx-space-touch-target` added (§ Additions)                                                  | eight spacing numbers (§ Chrome)                                                   | —                                                                     | —      | `--vx-hit` replaces the touch vars; `SIZE_CLASSES` (§ 1.31.0)                                         | —                                                                         | `SIZE_CLASSES`/`CONTAINER_CLASSES` actually exported (§ Fixes)                                                  | —          |
+| **charts** (`./charts`)       | —                                                            | phone tier, `curve`, formatters, `state`, log axis (§ preamble)                        | `ChartState.empty: string`, `AxisBottomNumeric` (§ Additions)                                  | responsive `height`, `legend.maxRows` (§ Charts)                                   | `height` reaches the kinds; `maxRows` beats the `fill` fit (§ Charts) | —      | container-class tier + `height` keys (§ 1.31.0)                                                       | —                                                                         | `ResponsiveChartHeight` `sm` → key (§ Container recipes)                                                        | —          |
+| **shell** (`.`)               | —                                                            | scrollport, region seams, **the brand left the sidebar** (§§ scrollport, brand, Shell) | `PageTitle`, `BasaltDevDock`, `useBreakpoint` (§ Additions)                                    | More popover, aside pill, the responsive gutter, `useBasaltSpacing` (§ Chrome)     | —                                                                     | —      | `theme.breakpoints` derived, `useSizeClass`, `data-basalt-host`, `useBreakpoint` on notice (§ 1.31.0) | `useBreakpoint` removal → 1.33.0; `useSizeClass` is shell-only (§ 1.32.0) | shell-less `shell/` gutter, `AppShell` breakpoints, `useSizeClass` for overlays (§§ Shell-less, `useSizeClass`) | —          |
+| **controls** (`./controls`)   | `NumberFilter`, `field.number` (§ Controls)                  | sheet renders panel rows; `PanelRow`, `SliderControl` (§ `basalt-ui/controls`)         | —                                                                                              | —                                                                                  | —                                                                     | —      | —                                                                                                     | —                                                                         | —                                                                                                               | —          |
+| **forms** (`./forms`)         | —                                                            | `field` → `inputProps`, **`inputProps` drops `key`**, the layout tier (§ `inputProps`) | `field` DELETED — and the `--fix` recipe no longer works (§ Consolidation)                     | —                                                                                  | —                                                                     | —      | —                                                                                                     | —                                                                         | `FormGroup` row no longer stretches (§ Fixes)                                                                   | —          |
+| **data** (`./data/table`)     | —                                                            | root is a `<div>`, row selection, `getItemKey` required (§ `basalt-ui/data`)           | `./data` + `./query` + `./connectivity` dropped (§ Consolidation)                              | —                                                                                  | —                                                                     | —      | —                                                                                                     | —                                                                         | `renderCard` documented (§ `renderCard`)                                                                        | —          |
+| **dashboard** (`.`)           | `StatCard`: `unit`, `breakdown`, delta format (§ `StatCard`) | `StatGroup`, `WidgetGrid`, query-aware `StatCard` — additive                           | —                                                                                              | **the column law keys on the CONTAINER; `cols={4}` is 2-up at `sm`** (§ Dashboard) | —                                                                     | —      | —                                                                                                     | —                                                                         | —                                                                                                               | —          |
+| **toolchain** (`./configs/*`) | —                                                            | —                                                                                      | the shipped lefthook preset's `check-theme` BROKE — the CLI resolver stopped ascending (§ CLI) | the preset's default bin, and the `root:` recipe (§ Toolchain)                     | —                                                                     | —      | —                                                                                                     | —                                                                         | —                                                                                                               | —          |
+| **CLI** (`basalt-ui`)         | —                                                            | —                                                                                      | **resolver stops relocating; `doctor` loses 6 of 10 checks** (§ CLI)                           | —                                                                                  | —                                                                     | —      | —                                                                                                     | —                                                                         | —                                                                                                               | —          |
+| **guards**                    | five rules → `error` (§ Guards)                              | six new ids at `warn` (§ preamble)                                                     | `query-dual-import` retired in 1.29.1 (§ Guards)                                               | four rules → `error` (§ Guards)                                                    | —                                                                     | —      | —                                                                                                     | `raw-breakpoint`: the container-grid answer, `error` at 1.33.0 (§ 1.32.0) | `FormRow`/`FormGroup` homes in both lanes; `basalt-main` dropped (§ Fixes)                                      | —          |
 
 ---
 
@@ -86,6 +86,196 @@ consumer read this index, found nothing, and diffed a KPI row that had silently
 _Nothing yet. Author the next section under this heading as `## Unreleased — <title>`; the
 release renames it and opens a new one here._
 
+## 1.32.1 — the 1.32.0 recipe resolves, and the gaps consumers hit upgrading to it
+
+A patch: no new API beyond restoring what 1.31.0/1.32.0 already documented. Eight consumers
+upgraded to 1.32.0; this section is what they had to find out by reading source.
+
+### Fixes you can now delete a workaround for
+
+| What                                                                                                                                                                                                                                                                                                                                                                  | Delete                                                                                                           |
+| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| **`SIZE_CLASSES`, `CONTAINER_CLASSES`, `resolveContainerClass`, `ContainerClass` are exported from `basalt-ui/tokens`.** The 1.31.0/1.32.0 sections, the `raw-breakpoint` message and the `BasaltDataTable` JSDoc all named that import; it did not resolve. A test now fails the build when a fenced import in this file names a symbol its subpath does not export. | the local `container-classes.ts` mirror or the literal `'480px'`/`800` — import them                             |
+| **`FormRow` / `FormGroup` are control homes in `check-theme` too.** The oxlint plugin already treated them as homes; the text lane's `raw-selection-control` did not, so a correctly migrated form row warned (and would have errored at 1.33.0). A parity test now pins both lanes' home lists to one set.                                                           | every `theme-allow raw-selection-control — … FormRow/FormGroup …` waiver (grep `WORKAROUND: homed in a FormRow`) |
+| **`basalt-main` is no longer an accepted `@container` name.** Nothing ever declared it, so a query against it never matched. Declare your own container (`container: <name> / inline-size` on the element) or use `basalt-grid` on the parent.                                                                                                                        | `@container basalt-main …` — rewrite against a container you declare                                             |
+| **The `raw-media-query` message no longer over-claims.** Only `basalt-card` and unnamed `@container` queries are judged against the 0/240/480/800 table; any other declared name is accepted at any width. Same behaviour, honest text.                                                                                                                               | —                                                                                                                |
+| **`raw-breakpoint` exempts a `tests?/` directory** (e.g. a `tests/setup/dom.ts` `matchMedia` polyfill), not only `*.test.*`/`__tests__`. The message now says `cols={{ base: 3 }}` is just `cols={3}`, and a `(hover: none)` read gets a pointer-tier hint.                                                                                                           | the polyfill's `theme-allow raw-breakpoint`                                                                      |
+| **`FormGroup direction="row"` no longer stretches a trailing button** (`align-items: flex-end`).                                                                                                                                                                                                                                                                      | a `style={{ alignSelf: … }}` on the button                                                                       |
+
+**This patch also TIGHTENS two checks — expect NEW warnings after upgrading, still `warn` until
+1.33.0:** `raw-breakpoint` now sees a responsive object inside a conditional, logical or
+const-resolved prop value (`span={wide ? { base: 12, md: 4 } : 12}` used to slip through), and
+`raw-media-query` rejects `@container basalt-main`. (The `FormRow`/`FormGroup` change only removes
+warnings.)
+
+**After any guard narrows, audit your waivers:** `basalt-ui check-theme --audit-allows` lists every
+`theme-allow` and whether it still suppresses anything. Dead ones (rb carried five
+`in-body-page-title`, linewatch one `bound-control-outside-home`) go.
+
+**Scope — the breakpoint law is Mantine/CSS-scoped.** `raw-breakpoint` is an oxlint rule over JSX
+and `raw-media-query` a `check-theme` kind over `.css`. A tokens-only (Tailwind) consumer has only
+the `check-theme` lane; nothing here asks it to adopt `type="container"` grids.
+
+### Container recipes 1.32.0 left implicit
+
+**Swap two children at a container width in ONE query** — narrow default, flip both sides inside
+one `min-width` rule. A `max-width: 799.9px` / `min-width: 800px` pair leaves a sub-pixel band where
+both or neither render.
+
+```css
+.root {
+  container: basalt-grid / inline-size;
+}
+.wide {
+  display: none;
+}
+@container basalt-grid (min-width: 800px) {
+  .narrow {
+    display: none;
+  }
+  .wide {
+    display: block;
+  }
+}
+```
+
+**A plain Mantine `Table` (not `BasaltDataTable`)** has no column fold or card projection; the
+sanctioned remedy is the same CSS module — declare the container on the wrapper and hide columns or
+swap to a list inside a `min-width` query. `BasaltDataTable` needs the optional
+`@tanstack/react-table` peer; don't add it only to get the fold.
+
+**Layouts that need a step above `wide` (800px).** There is no fifth class; one ships when two named
+consumers need the same width. Until then, verified against the 1.32.0 plugin:
+
+| Where                                                                    | Off-class width (e.g. `1200px`)                                                                                         |
+| ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
+| `SimpleGrid type="container"` px key — `cols={{ base: 1, '1200px': 5 }}` | passes: `raw-breakpoint` does not judge px keys, only theme names (`sm`)                                                |
+| `Grid type="container"` `breakpoints` map value — `xl: '1200px'`         | passes: the map's values are not judged                                                                                 |
+| `@container basalt-card` or unnamed, in CSS                              | flagged — `theme-allow raw-media-query — <why this layout needs 1200px>`                                                |
+| `@container <your-own-name>` or `basalt-grid`, in CSS                    | passes today; a later minor may judge `basalt-grid` — prefer a reasoned `theme-allow` over relying on the unjudged name |
+
+Either way, write the reason next to the width: it is the evidence the fifth class is waiting on.
+
+**`ResponsiveChartHeight` `sm` (768px) → which key.** `wide` (800) is 32px later and keeps the old
+step's meaning ("tablet or wider"); `regular` (480) opens 288px earlier. Pick by which side of the old
+width the height was for.
+
+### `BasaltDataTable` `renderCard` (1.32.0, undocumented here until now)
+
+The law lives in the prop's JSDoc (`src/data/data-table.tsx`, shipped in `dist/data/table.d.ts`).
+The points consumers tripped on:
+
+- Swaps at the table's OWN width `< CONTAINER_CLASSES.regular` (480px), not the viewport.
+- Card order is the table's processed order — sort, filter, page. For a domain order, pass
+  `initialSorting` or sort `data`; there is no second sort.
+- `minWidth` disables the COLUMN fold (it declares a horizontal floor) and is ignored by the card
+  list. `stickyHeader` alone keeps the fold; pair it with `maxHeight` to stick at every width.
+- Activation is click or **Enter** — not Space (the browser's page scroll on a focused non-button).
+
+### Shell-less apps and the 1.31.0 breakpoint move
+
+1.31.0 moved `sm` from 48em to **52.5em** (840px). What its checklist missed:
+
+- **Re-key your own literals:** grep `.css` for `47.99375em` / `48em` → `52.49375em` / `52.5em`.
+- **A shell-less app's gutter / sticky-bar CSS belongs under your own `shell/` directory** at
+  52.5em: any `shell/`-pathed CSS may write a width `@media` at a `SIZE_CLASSES` boundary; anywhere
+  else it is `raw-media-query`.
+- **A consumer-owned Mantine `AppShell`** resolves `navbar.breakpoint` / `aside.breakpoint` through
+  `theme.breakpoints`, so `breakpoint: 'sm'` collapses at 840px now, not 768px.
+- **In the `medium` class the sidebar defaults to the rail**, and the rail hides a `kind: 'custom'`
+  block entirely (a list block keeps a dot only with both `icon` and `count`). Anything a
+  `medium`-width user needs must not live only in a custom block.
+- **`PageBar` without a shell:** see the shell-less example in its JSDoc — `title` leads the one
+  sticky bar, and `classNames.root` is where the gutter bleed goes.
+
+### `useSizeClass()` outside the shell — two sanctioned uses
+
+Layout stays a container decision; an overlay's form (`Drawer` side, sheet vs dialog) and content
+paired with a `ViewTabs` option `only: 'sm-down'` may read it. Law and wording:
+`agent/rules/basalt-mantine.md` (a shipped rule, placed by `basalt-ui sync`).
+
+## 1.32.0 — `basalt/raw-breakpoint` gets its answer
+
+### The C1 pair (`control-outside-home` / `raw-selection-control`) — `error` at 1.33.0, the last extension
+
+Re-measured 2026-09-30: basalt's own tree 0, the fleet ~33 (image-gen 11, rb 7, image-share 6,
+weatherorb 5, email-gateway 4, argo 2). Clear them on 1.32.0 while they still warn — the remedies
+are unchanged (§ 1.31.0 below: a `PageBar` home, `basalt-ui/forms` rows, bound `FieldHandle`s, or a
+reasoned `theme-allow`). 1.33.0 promotes all four ids — this pair plus `raw-breakpoint` and
+`raw-media-query` — together.
+
+### `basalt/raw-breakpoint`
+
+1.31.0 shipped this rule (`warn`) with a message that said "reach for a container query" and named
+no primitive, and this file never mentioned it. It flags four shapes; each has a concrete target
+now. **Severity: `warn`, promotes to `error` at 1.33.0** (moved from 1.32.0 — this is the first
+minor with a documented answer). A `theme-allow raw-breakpoint — <reason>` waives one occurrence.
+
+**Its CSS twin, the `raw-media-query` guard kind** (`basalt-ui check-theme`), enforces the same law
+in `.css`: a width `@media` outside `shell/**`, an `@container` name other than `basalt-card` /
+`basalt-form` / `basalt-grid` (`basalt-main` was listed here too; dropped in 1.32.1, nothing declared it) or at a width off a `CONTAINER_CLASSES` boundary, and
+a pointer query other than `coarse`/`fine`. Same `warn`, and it moved with the rule — **`error` at
+1.33.0** (was 1.32.0). `theme-allow raw-media-query — <reason>` waives one line.
+
+**The law.** `useSizeClass()` is for **shell chrome**. A page swapping its OWN layout — a column
+count, a table for a card list, a row for a stack — is a **container** decision, keyed on
+`CONTAINER_CLASSES` (`basalt-ui/tokens`: compact 240 · regular 480 · wide 800), not the viewport.
+The primitive is Mantine 9's own `type="container"` grid. Verified against `@mantine/core` 9.3
+source, which is what the rule's exemption is built on:
+
+- `SimpleGrid type="container"` wraps itself in a `container: simple-grid / inline-size` div (no
+  ancestor needed) and writes **each key verbatim** into `@container simple-grid (min-width: <key>)`.
+  Keys are CSS lengths — `'480px'`, not `480` (unitless is invalid) and not `sm` (never resolved
+  through `theme.breakpoints`; emits a dead query). The rule flags `sm`-style keys there.
+- `Grid type="container"` only goes container **when it also gets a `breakpoints` map**; without
+  one it silently renders viewport media queries (flagged). The map is typed
+  `Record<MantineSize, string>` — all five `xs`–`xl`, no custom names — and `Grid.Col` keys resolve
+  through it, so `sm` there means whatever width the map gives it (exempt).
+
+| Shape (what it flags)                                                                           | Replace with                                                                                                                                                                                                                              |
+| ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| responsive object on a Mantine prop — `SimpleGrid cols={{ base, sm }}`                          | `SimpleGrid type="container"` with px keys (below)                                                                                                                                                                                        |
+| `Grid.Col span={{ base, lg }}`                                                                  | `Grid type="container"` + a `breakpoints` map onto container widths; spans keyed through it                                                                                                                                               |
+| `Flex direction={{ base: 'column', sm: 'row' }}`                                                | the container `SimpleGrid` (equal columns); a plain `Group` (wraps by default) for intrinsic-width items; or a CSS module: `container: basalt-grid / inline-size` on the parent, `@container basalt-grid (min-width: 480px)` on the child |
+| `visibleFrom`/`hiddenFrom` outside a shell home or a control's C9 swap                          | the same container rule, `display` toggled in the CSS module — or drop the swap                                                                                                                                                           |
+| `useMediaQuery`/`useMatches`/`useViewportSize` (`@mantine/*`), `window.matchMedia`/`innerWidth` | shell chrome: `useSizeClass()`; a page's layout: one of the above                                                                                                                                                                         |
+
+```tsx
+// before — viewport breakpoints
+<SimpleGrid cols={{ base: 1, sm: 3 }}>…</SimpleGrid>
+<Grid><Grid.Col span={{ base: 12, lg: 4 }}>…</Grid.Col></Grid>
+
+// after — the grid's own width
+import { CONTAINER_CLASSES as C } from 'basalt-ui/tokens'
+<SimpleGrid type="container" cols={{ base: 1, [`${C.regular}px`]: 3 }}>…</SimpleGrid>
+const px = (n: number) => `${n}px`
+const containerBreakpoints = { xs: px(C.compact), sm: px(C.regular), md: px(C.wide), lg: px(C.wide), xl: px(C.wide) }
+<Grid type="container" breakpoints={containerBreakpoints}>
+  <Grid.Col span={{ base: 12, md: 4 }}>…</Grid.Col>
+</Grid>
+```
+
+Pick the container key by the grid's own width, not by the viewport key it replaces: a grid inside a
+page with an aside or a sidebar is narrower than the viewport, which is the point.
+
+### `StatGroup` / `WidgetGrid` — `sm` opens at 800px, container name `basalt-grid`
+
+Both grids now key on the container-class law basalt ships: the `sm` column count opens at the
+`wide` class (**800px** of the grid's own width, was 768); the full `cols` count still opens at
+1200px. A grid 768–799px wide now renders its base count (StatGroup 2, WidgetGrid 1). The
+container they declare is renamed `basalt-stat-group`/`basalt-widget-grid` → **`basalt-grid`** — only
+a consumer rule written against the old names needs editing. The `@supports not (container-type)`
+viewport fallbacks (these two and `FormRow`'s) are gone: every browser that parses basalt's
+`color-mix()` also parses `@container`.
+
+### `useBreakpoint` — removal moved to 1.33.0, and the 1.31.0 replacement line was half wrong
+
+`useBreakpoint('sm')` → `useSizeClass() !== 'compact'` holds for **shell chrome only**. A page
+swapping its own layout on it (argo's table ↔ card list) is a container decision — see above. Note
+that `useSizeClass()` answers `'compact'` on the first frame (the server snapshot,
+`<BasaltProvider sizeClassHint>`) where `useBreakpoint` returned `undefined`, so an
+`isLg === true` guard written for that `undefined` can go.
+
 ## 1.31.0 — size classes and the pointer tier
 
 `theme.breakpoints` is now derived from `SIZE_CLASSES` (compact < 840, medium 840–1199, expanded
@@ -93,7 +283,9 @@ release renames it and opens a new one here._
 it out. Mapping: `xs` = `sm` = 52.5em (medium opens), `md` = `lg` = `xl` = 75em (expanded opens) — the
 keys collapse. So `xs` moves 36em → 52.5em, `sm` 48em → 52.5em (an iPad portrait is now bottom-bar chrome), `md`
 62em → 75em, `lg` stays 75em and `xl` 88em → 75em. Check every `visibleFrom`/`hiddenFrom`/`useBreakpoint`
-on those keys: `xs` no longer differs from `sm`, and `md`/`lg`/`xl` now switch at the same width.
+on those keys: `xs` no longer differs from `sm`, and `md`/`lg`/`xl` now switch at the same width. Outside a
+shell home those props are `basalt/raw-breakpoint` findings — move them to a container grid rather
+than re-keying them (see that section above).
 
 | Removed                                                                                                                     | Replacement                                                                                                                                                                           |
 | --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -149,10 +341,10 @@ everywhere).
 `storageKey`. Opt out with a controlled `collapsed` prop; a persisted `false` (the user opened it
 once) pins it open.
 
-**On notice — `useBreakpoint` (removed next minor).** `@deprecated`, still works. Replace
-`useBreakpoint('sm')` with `useSizeClass() !== 'compact'`, and `useBreakpoint('lg')` with
-`useSizeClass() === 'expanded'`. A `max`-edge or non-shell width read is a container concern: use
-`@container` in CSS.
+**On notice — `useBreakpoint` (removal moved to 1.33.0).** `@deprecated`, still works. For shell
+chrome, replace `useBreakpoint('sm')` with `useSizeClass() !== 'compact'` and `useBreakpoint('lg')`
+with `useSizeClass() === 'expanded'`. A page's own layout swap is a container decision, not a
+`useSizeClass()` one — corrected after release; see the `basalt/raw-breakpoint` section above.
 
 **Card chrome keys on the card's own width, not the viewport.** `ChartCard`, `StatCard` and `Section`
 are now `container: basalt-card / inline-size` (`container-type: inline-size` — layout and inline-size
@@ -322,7 +514,7 @@ exactly the case it was restored for. Measured: a 7-entry legend in a 92–150px
 entries at `maxRows` 3, 6 **and** 99, with five series drawn in colours nothing named.
 
 The fit now resolves an ABSENT cap only. When a caller states a number on a `fill` band, the legend
-takes the ENTRIES it asked for (`maxRows` counts entries, not rows — see § Unreleased) and
+takes the ENTRIES it asked for (`maxRows` counts entries, not rows — see § 1.30.1) and
 **`VX.minPlotHeight` stops being a floor** — the plot yields the height instead. Both things that used to trim the number are framework DEFAULTS (the tier's cap,
 and a floor about the plot); the stated number is the only intent in the room.
 
@@ -487,7 +679,7 @@ children is invisible to every rule. Grep for `SimpleGrid` before concluding the
 ### Charts — a responsive `height`, and the legend escape 1.30.0 promised
 
 Both of these landed in 1.30.0 with no row here, and both were only partly reachable. **Read this
-section against 1.30.1, not 1.30.0** — the § Unreleased entries above are what makes them usable.
+section against 1.30.1, not 1.30.0** — the § 1.30.1 entries above are what makes them usable.
 
 - **`height` accepts `{ base, sm?, md?, lg? }`** as well as a plain number, resolved against the
   chart's MEASURED container width (the same width the tier reads), not the viewport. In 1.30.0 the
@@ -499,7 +691,7 @@ section against 1.30.1, not 1.30.0** — the § Unreleased entries above are wha
   measured box, so a 380px inspector panel on a 1440px desktop IS "a phone" and its two-row default
   rolled a six-series legend up to `+4 more` with no way to say no. `margin` and `xLabelRotate`
   always had that escape; the legend did not. Under `fill` a measured cap still applies on top — see
-  § Unreleased for what that actually costs, because "can still roll up FURTHER" understated it.
+  § 1.30.1 for what that actually costs, because "can still roll up FURTHER" understated it.
 
 ### Toolchain — the shipped lefthook preset's `check-theme`, and what it does NOT fix
 

package/agent/rules/basalt-mantine.md

@@ -48,8 +48,7 @@ single mount (`basalt/hand-rolled-shell` fires on `AppShell.*` parts or a `Burge
 does not render it). The sub-components are exported for a genuinely divergent layout; prefer the
 shell, which already wires collapse persistence, the mobile breakpoint and the breadcrumb.
 
-Every extension point is **declared data, not a `ReactNode` slot**, so basalt owns the mobile
-projection:
+Extension points are **declared data, not `ReactNode` slots**, so basalt owns the mobile projection:
 
 | Prop                | Shape                                | What basalt then owns                                                                  |
 | ------------------- | ------------------------------------ | -------------------------------------------------------------------------------------- |
@@ -98,6 +97,8 @@ Depth-tier law (which token for which surface, why static, why the ring is inset
   clears the iOS zoom threshold via an `!important` floor (`sub-16-input-font` flags a smaller one).
 - **Charts measure themselves** — pass `height`/`aspectRatio`/`fill` only; never `useElementSize`
   in a chart file (Mantine is banned there), never raw `@visx/responsive` outside `charts/**`.
+- **A page's layout keys on its container, not the viewport** (`type="container"` grids, `CONTAINER_CLASSES`).
+  `useSizeClass()`: shell chrome, overlay form, `ViewTabs only: 'sm-down'` partners. Recipes: `MIGRATING.md`.
 
 ## Scroll regions
 
@@ -105,8 +106,7 @@ Depth-tier law (which token for which surface, why static, why the ring is inset
 it draws its own bar inside its root, so the bar floats instead of reflowing the column
 (`AppSidebar`'s nav is the reference: `type="hover"`, `scrollbars="y"`). Raw `overflow: auto` stays
 correct only where a library owns the node (`BasaltStickToBottom`, `BasaltVirtualList`) and for a
-table body (`Table.ScrollContainer type="native"` — a `ScrollArea` viewport would break a sticky
-`<thead>`'s positioning context).
+table body (`Table.ScrollContainer type="native"` — a `ScrollArea` viewport breaks a sticky `<thead>`).
 
 ## Interaction feedback and motion