basalt-ui 1.29.2 → 1.30.1

package/src/cli/init.ts

@@ -4,7 +4,7 @@
  * oxlint-preset plugin reader from `./sync` (also called there).
  */
 import { existsSync } from 'node:fs'
-import { relative, resolve } from 'node:path'
+import { resolve } from 'node:path'
 
 import { deriveSpacing } from '../tokens'
 import type { MergeLintResult, ScaffoldFlags } from './index'
@@ -15,17 +15,16 @@ import {
   mergeOxlintExtends,
   normalizeForLedger,
   patchPackageJson,
+  placementNotices,
   pruneRetiredManagedFiles,
   readManifest,
   reconcileRoots,
-  relativePosix,
   renderContext,
   reportPrune,
   resolvePeerFlags,
   resolvePlacement,
   rootsNotices,
   sha256,
-  shippedAssetPath,
   unitState,
   writeFileEnsuringDir,
   writeUnit,
@@ -166,30 +165,10 @@ export function init(cwd: string = process.cwd(), scaffoldFlags: ScaffoldFlags =
   if (seededLintScript) {
     console.log(`basalt-ui init: added the "lint:basalt" script (${lintScript}) to package.json.`)
   }
-  // lefthook.yml / .github/workflows/check.yml are repo-root-shaped — neither lefthook nor GitHub
-  // Actions reads config from anywhere but the repo root, so a package living in a subdirectory
-  // skips both rather than relocating them into a spot nothing reads.
-  if (!placement.isPackageRepoRoot) {
-    console.log(
-      `basalt-ui init: skipped lefthook.yml (this package is not the repo root — repo root ` +
-        `detected at ${placement.repoRoot}) — lefthook only reads config at the repo root; extend ` +
-        `${ctx.vars.LEFTHOOK_PRESET_PATH} from your root lefthook.yml instead, and give its ` +
-        `check-theme command \`env: { BASALT_CWD: ${relativePosix(placement.repoRoot, cwd)} }\` ` +
-        'so the guard runs where your basalt config actually lives.',
-    )
-    console.log(
-      `basalt-ui init: skipped .github/workflows/check.yml (this package is not the repo root — ` +
-        `repo root detected at ${placement.repoRoot}) — GitHub Actions only reads .github/ at the ` +
-        `repo root; copy the steps from ${shippedAssetPath(install, placement.repoRoot, 'configs/check.yml')} ` +
-        'into your root CI workflow instead.',
-    )
-  }
-  if (placement.relocatedQueryClient !== null) {
-    console.log(
-      `basalt-ui init: skipped src/query-client.ts (found an existing query client at ` +
-        `${relative(cwd, placement.relocatedQueryClient)}) — import it from there instead of ` +
-        're-seeding at the original path.',
-    )
+  // The permanent placement skips (repo-root-shaped tooling, a relocated scaffold) — one text,
+  // shared with `sync`. See {@link placementNotices}.
+  for (const line of placementNotices(cwd, placement)) {
+    console.log(`basalt-ui init: ${line}`)
   }
   // query-client.ts / __root.tsx reference the optional TanStack peers directly — seeding them
   // without the peer installed would ship an unresolved import. Hint how to opt in instead.

package/src/cli/sync.ts

@@ -5,7 +5,7 @@
  * resolution back from `./index`, this package's shared CLI helpers.
  */
 import { existsSync } from 'node:fs'
-import { relative, resolve } from 'node:path'
+import { resolve } from 'node:path'
 
 import { deriveSpacing } from '../tokens'
 import {
@@ -21,6 +21,7 @@ import {
   managedFiles,
   normalizeForLedger,
   parseJsonc,
+  placementNotices,
   pruneRetiredManagedFiles,
   readBasaltConfig,
   readIfExists,
@@ -232,26 +233,12 @@ export function sync(opts: SyncOptions = {}, invocationCwd: string = process.cwd
   })
   staleForCheck += pruned.removed.length + pruned.drifted.length
 
-  // Placement notices — informational, never affect the exit code (a skipped tooling seed or a
-  // relocated scaffold is a legitimate consumer choice, not a sync failure).
-  if (!placement.isPackageRepoRoot) {
-    console.log(
-      `basalt-ui sync: skipped lefthook.yml (this package is not the repo root — repo root ` +
-        `detected at ${placement.repoRoot}) — lefthook only reads config at the repo root; extend ` +
-        'node_modules/basalt-ui/configs/lefthook.yml from your root lefthook.yml instead.',
-    )
-    console.log(
-      `basalt-ui sync: skipped .github/workflows/check.yml (this package is not the repo root — ` +
-        `repo root detected at ${placement.repoRoot}) — GitHub Actions only reads .github/ at the ` +
-        'repo root; extend node_modules/basalt-ui/configs/check.yml from your root CI workflow instead.',
-    )
-  }
-  if (placement.relocatedQueryClient !== null) {
-    console.log(
-      `basalt-ui sync: skipped src/query-client.ts (found an existing query client at ` +
-        `${relative(cwd, placement.relocatedQueryClient)}) — import it from there instead of ` +
-        're-seeding at the original path.',
-    )
+  // Placement notices — informational, never affecting the exit code, and PERMANENT: `--check`
+  // hides them behind `--verbose` (it sits in consumers' CI chains, where three unchanging
+  // "skipped" paragraphs per run are noise indistinguishable from drift) but still prints the COUNT.
+  const placementSkips = placementNotices(cwd, placement)
+  if (opts.check !== true || syncFlags.includes('--verbose')) {
+    for (const line of placementSkips) console.log(`basalt-ui sync: ${line}`)
   }
 
   const rootsMessages = rootsNotices(rootsState)
@@ -298,7 +285,9 @@ export function sync(opts: SyncOptions = {}, invocationCwd: string = process.cwd
       console.error(`basalt-ui sync --check: ${staleForCheck} managed file(s) out of date.`)
       return 1
     }
-    console.log('✓ basalt-ui sync --check: all managed files current.')
+    const n = placementSkips.length
+    const skips = n === 0 ? '' : ` (${n} permanent placement skip(s) — --verbose for detail)`
+    console.log(`✓ basalt-ui sync --check: all managed files current.${skips}`)
     return 0
   }
 

package/src/controls/actions.tsx

@@ -13,6 +13,7 @@
  * media query, so there is no first-paint flash and no hook that re-renders on resize.
  */
 import { ActionIcon, Button, Group, Menu } from '@mantine/core'
+import type { MantineBreakpoint } from '@mantine/core'
 import { createContext, isValidElement, useContext, useEffect } from 'react'
 import type { ReactNode } from 'react'
 import type { BasaltProps } from '../common/props'
@@ -187,6 +188,19 @@ const MOBILE_PRIMARY_PADDING_X = 10
  */
 const BAR_GAP = 6
 
+/**
+ * A declared WIDTH TIER for one rendered form of an action — Mantine's own `visibleFrom`/`hiddenFrom`
+ * style props, forwarded verbatim, which is the same CSS-only mechanism this file's `sm` swap uses
+ * (see the module header). Never a JS media query: no first-paint flash, no resize re-render.
+ *
+ * It exists because `sm` is not the only width at which this row runs out of room — see
+ * {@link BarEntry}'s `md` label fold for the arithmetic.
+ */
+type TierVisibility = {
+  visibleFrom?: MantineBreakpoint
+  hiddenFrom?: MantineBreakpoint
+}
+
 /**
  * One action as a button. No `size` prop anywhere: the enclosing `CtlSlot` (mounted by the home,
  * never by the action) resolves the `ctl` tier — law C5.
@@ -195,15 +209,19 @@ function BarButton({
   action,
   variant,
   px,
+  tier,
 }: {
   action: BarActionItem
   variant: 'filled' | 'default'
   /** Overrides the tier's horizontal inset — only the compact mobile primary passes it. */
   px?: number
+  /** The declared width tier this form paints at — see {@link TierVisibility}. */
+  tier?: TierVisibility
 }): ReactNode {
   const shared = {
     variant,
     ...(px !== undefined && { px }),
+    ...tier,
     disabled: action.disabled === true,
     loading: action.loading === true,
     // EVERY icon in this file goes through `IconSlot` — the box is the framework's, never the
@@ -234,13 +252,17 @@ function BarButton({
 function BarIconButton({
   action,
   variant,
+  tier,
 }: {
   action: BarActionItem
   /** `default` is the bordered desktop form — a joined `ControlGroup` member (see {@link BarEntry}). */
   variant: 'filled' | 'subtle' | 'default'
+  /** The declared width tier this form paints at — see {@link TierVisibility}. */
+  tier?: TierVisibility
 }): ReactNode {
   const shared = {
     variant,
+    ...tier,
     'aria-label': action.label,
     disabled: action.disabled === true,
     loading: action.loading === true,
@@ -698,6 +720,35 @@ function BarEntry({
   if (iconOnly === true && action.icon !== undefined) {
     return <BarIconButton action={action} variant="default" />
   }
+  // THE `md` LABEL FOLD — the second declared tier, and the only fold this row had between `sm`
+  // (48em, where the whole mobile swap happens) and the width at which a desktop header is
+  // genuinely wide. Above `sm` the only fold was `DESKTOP_SECONDARY_MAX`, which is a COUNT and
+  // never a width: three labelled secondaries are three labelled secondaries at 768px and at
+  // 2560px.
+  //
+  // The arithmetic, on /dashboard at exactly 768px — the width where the navbar appears and takes
+  // 256px: 512px of header left, against ~554px of row 1 + ~102px of globals + ~48px of gaps ≈
+  // 704px. ~192px over, and nothing above `sm` folded — the breadcrumb absorbed it by shrinking to
+  // zero (`shell/app-header.module.css`'s `.lead`, now floored at 96px, which this tier pays for).
+  // Dropping up to `DESKTOP_SECONDARY_MAX` labelled secondaries to their 30px icon form returns
+  // roughly 180-240px on that row: a labelled `ctl` button is its icon slot + label + insets
+  // (~90-110px depending on the word), an icon-only one is the tier's 30px square.
+  //
+  // The PRIMARY keeps its label at every width — it is the one action a reader must be able to
+  // name without hovering (law C6: exactly one per home), so `emphasis === 'primary'` never enters
+  // this branch. An icon-LESS secondary keeps its label too: there is nothing to fall back to, the
+  // same reason `MobileBarEntry` renders a compact labelled button below `sm`.
+  //
+  // Both forms are rendered and CSS picks one, the mechanism the `sm` swap already uses — that is
+  // law C9 being HONOURED, not breached: the swap belongs to the control, and this is the control.
+  if (emphasis === 'secondary' && action.icon !== undefined) {
+    return (
+      <>
+        <BarIconButton action={action} variant="default" tier={{ hiddenFrom: 'md' }} />
+        <BarButton action={action} variant="default" tier={{ visibleFrom: 'md' }} />
+      </>
+    )
+  }
   return <BarButton action={action} variant={emphasis === 'primary' ? 'filled' : 'default'} />
 }
 

package/src/dashboard/section.module.css

@@ -6,20 +6,27 @@
 
 /*
  * 12px from the header to the body, and the same between two body children — one rhythm, read from
- * the stack scale (`--vx-space-stack-md`) instead of the card-inset scale
- * (`--mantine-spacing-sm`, 13px). A Section is a page-level GROUPING, so its gaps belong to the
- * vertical rhythm, not to the inset ladder its cards use.
+ * the stack scale (`SPACE.stackMd`, via the `--vx-space-section-gap` role token) instead of the
+ * card-inset scale (13px). A Section is a page-level GROUPING, so its gaps belong to the vertical
+ * rhythm, not to the inset ladder its cards use.
+ *
+ * Below `sm` it steps to `stackSm` (8px), together with the cards' own horizontal inset. That step
+ * is NOT written here: it belongs to the mobile inset ladder, whose ONE home is `spaceMobileDecls`
+ * in `tokens/index.ts` — this rule only reads the role token and gets the responsive value for
+ * free. See that function's doc for why the law lives in the emitter rather than in the three
+ * stylesheets that consume it (two of the three are inline styles, which cannot hold a media
+ * query at all).
  */
 .root {
   display: flex;
   flex-direction: column;
-  gap: var(--vx-space-stack-md, 0.75rem);
+  gap: var(--vx-space-section-gap, 0.75rem);
 }
 
 .body {
   display: flex;
   flex-direction: column;
-  gap: var(--vx-space-stack-md, 0.75rem);
+  gap: var(--vx-space-section-gap, 0.75rem);
 }
 
 /*
@@ -48,8 +55,9 @@
  * The collapse chevron — a plain control, not a Mantine ActionIcon, so it sits directly in the header
  * row (its own CtlSlot fragment would nest a theme provider around one glyph). It is sized to the
  * `ctl` tier BY HAND for exactly that reason: a 12px glyph in a 20px box was a different height from
- * every other control in the same header, which is what made the section header read as ragged. 30px
- * square, glyph centred, no padding — the box IS the tier.
+ * every other control in the same header, which is what made the section header read as ragged. 32px
+ * square (the `ctl` tier, 30 before the desktop-shell pass), glyph centred, no padding — the box IS
+ * the tier.
  */
 .chevron {
   /* `relative` is the anchor for the C15 hit-area overlay in the `< sm` block at the bottom. */

package/src/dashboard/stat-card.tsx

@@ -378,7 +378,12 @@ export function StatCard({
     <Card
       className={cx(classNames?.root, className)}
       style={{
-        // Card inset = spacing xs / sm, matching every other basalt card. `overflow: hidden` clips
+        // Card inset = the `cardInsetY`/`cardInsetX` role tokens (11/13 at level 0 — the same
+        // `xs`/`sm` rungs this used to spell as `--mantine-spacing-*`), matching every other basalt
+        // card because `ChartCard` reads the SAME two vars. Below `sm` the horizontal one steps a
+        // rung down on its own: the responsive half of the ladder lives in `spaceMobileDecls`
+        // (`tokens/index.ts`), which is the only home that can reach an inline style like this one.
+        // `overflow: hidden` clips
         // the full-bleed sparkline to the card's rounded corners; an element's own `box-shadow`
         // renders outside its border box and is NOT clipped by its own `overflow`, so the
         // shadow-card ring is unaffected (verified — only an ANCESTOR's overflow clips a
@@ -390,7 +395,7 @@ export function StatCard({
         // body is `height: 100%` and the sparkline is `margin-top: auto`. The content is what states
         // the height now (~88-96px), and four cards in a `SimpleGrid` still match because a grid row
         // stretches its items.
-        padding: 'var(--mantine-spacing-xs) var(--mantine-spacing-sm)',
+        padding: 'var(--vx-space-card-inset-y, 0.6875rem) var(--vx-space-card-inset-x, 0.8125rem)',
         overflow: 'hidden',
         // Anchors the tone rail. Set unconditionally so a card's stacking context does not change
         // depending on whether it happens to have crossed a threshold this render.

package/src/dashboard/stat-group.module.css

@@ -1,10 +1,41 @@
 /*
- * StatGroup's column law and its optional rail, in CSS (law C9). The literals are Mantine's
- * `--mantine-breakpoint-sm` (48em) and `--mantine-breakpoint-lg` (75em) — a `@media` condition
- * cannot read a custom property, so the number has to be written; the COUNTS are custom properties
- * the component sets per instance.
+ * StatGroup's column law and its optional rail, in CSS (law C9).
+ *
+ * **The law keys on the CONTAINER, not the viewport.** A viewport breakpoint answers the wrong
+ * question — the same one `resolveChartTier` refuses to ask (`charts/primitives/chart-frame-layout.
+ * ts`): the shell has regions that change the AVAILABLE width with the viewport held still (a
+ * `PageAside` claiming its 300px, the sidebar collapsing 256px → its 48px rail, a consumer's own
+ * split layout), and `@media` cannot see any of them. Measured defect: a `PageAside` mounted on a
+ * 1512px desktop left the KPI row ~956px wide, `@media` still resolved `lg`, and four cells of
+ * 239px truncated their own values mid-word ("8,7…", "Organic se…").
+ *
+ * `.container` is what makes the queries answerable — `StatGroup` renders it around the grid, so
+ * the container context ALWAYS exists and is ALWAYS the box the grid actually fills, whatever the
+ * shell or the consumer wrapped it in. It deliberately does not depend on the shell establishing
+ * one: a query with no container resolves to false, so a shell-only context would have silently
+ * pinned every non-shell consumer to the base count.
+ *
+ * The `@supports not` block below it is the pre-2023 fallback and the ONLY place the old viewport
+ * law survives. It is written as an exclusive alternative rather than as a base the container
+ * queries override, because the rail's `:nth-child` suppressors are MORE specific than the rule
+ * that draws the border: two overlapping laws would each suppress a different set of leading cells
+ * and the rail would lose hairlines in the middle of a row. One law at a time, chosen by support.
+ *
+ * The literals: `@container` conditions are stated in px, `@media` ones in Mantine's own `em`
+ * (`--mantine-breakpoint-sm` 48em, `--mantine-breakpoint-lg` 75em). Both spellings name the same
+ * boundary at the 16px initial font size — 768px and 1200px — but `em` inside a `@container`
+ * condition resolves against the CONTAINER's font-size rather than the root's, so a consumer panel
+ * with smaller text would silently move the breakpoint. px is the only spelling that cannot drift.
+ * (`47.99375em` → `767.9px`, `74.99375em` → `1199.9px`; the same complements `stat-card.module.css`
+ * uses.) A condition still cannot read a custom property either way, so the numbers are written;
+ * the COUNTS are custom properties the component sets per instance.
  */
 
+.container {
+  container-type: inline-size;
+  container-name: basalt-stat-group;
+}
+
 .root {
   display: grid;
   /* Two KPIs abreast on a phone, never one: a KPI is a short pre-formatted number, and a single
@@ -13,13 +44,13 @@
   gap: var(--vx-space-stack-md);
 }
 
-@media (min-width: 48em) {
+@container basalt-stat-group (min-width: 768px) {
   .root {
     grid-template-columns: repeat(var(--basalt-stat-group-cols-sm), minmax(0, 1fr));
   }
 }
 
-@media (min-width: 75em) {
+@container basalt-stat-group (min-width: 1200px) {
   .root {
     grid-template-columns: repeat(var(--basalt-stat-group-cols-lg), minmax(0, 1fr));
   }
@@ -40,14 +71,14 @@
   padding-inline-start: var(--vx-space-stack-md);
 }
 
-@media (max-width: 47.99375em) {
+@container basalt-stat-group (max-width: 767.9px) {
   .root[data-divided] > *:nth-child(2n + 1) {
     border-inline-start: 0;
     padding-inline-start: 0;
   }
 }
 
-@media (min-width: 48em) and (max-width: 74.99375em) {
+@container basalt-stat-group (min-width: 768px) and (max-width: 1199.9px) {
   .root[data-divided][data-sm-cols='2'] > *:nth-child(2n + 1),
   .root[data-divided][data-sm-cols='3'] > *:nth-child(3n + 1) {
     border-inline-start: 0;
@@ -55,7 +86,7 @@
   }
 }
 
-@media (min-width: 75em) {
+@container basalt-stat-group (min-width: 1200px) {
   .root[data-divided][data-cols='2'] > *:nth-child(2n + 1),
   .root[data-divided][data-cols='3'] > *:nth-child(3n + 1),
   .root[data-divided][data-cols='4'] > *:nth-child(4n + 1),
@@ -64,3 +95,48 @@
     padding-inline-start: 0;
   }
 }
+
+/*
+ * The pre-container-query fallback — Safari < 16, Chrome < 106, Firefox < 110. Verbatim the law
+ * this file shipped before, keyed on the viewport, and reachable ONLY where `@container` is not.
+ * A browser that cannot parse `container-type` also cannot parse the `@container` blocks above, so
+ * the two sets are never live at once.
+ */
+@supports not (container-type: inline-size) {
+  @media (min-width: 48em) {
+    .root {
+      grid-template-columns: repeat(var(--basalt-stat-group-cols-sm), minmax(0, 1fr));
+    }
+  }
+
+  @media (min-width: 75em) {
+    .root {
+      grid-template-columns: repeat(var(--basalt-stat-group-cols-lg), minmax(0, 1fr));
+    }
+  }
+
+  @media (max-width: 47.99375em) {
+    .root[data-divided] > *:nth-child(2n + 1) {
+      border-inline-start: 0;
+      padding-inline-start: 0;
+    }
+  }
+
+  @media (min-width: 48em) and (max-width: 74.99375em) {
+    .root[data-divided][data-sm-cols='2'] > *:nth-child(2n + 1),
+    .root[data-divided][data-sm-cols='3'] > *:nth-child(3n + 1) {
+      border-inline-start: 0;
+      padding-inline-start: 0;
+    }
+  }
+
+  @media (min-width: 75em) {
+    .root[data-divided][data-cols='2'] > *:nth-child(2n + 1),
+    .root[data-divided][data-cols='3'] > *:nth-child(3n + 1),
+    .root[data-divided][data-cols='4'] > *:nth-child(4n + 1),
+    .root[data-divided][data-cols='5'] > *:nth-child(5n + 1) {
+      border-inline-start: 0;
+      padding-inline-start: 0;
+    }
+  }
+}

package/src/dashboard/stat-group.module.css.d.ts

@@ -3,6 +3,7 @@
  * signature — so dot access stays verbatim under the package's strict flags.
  */
 declare const classes: {
+  readonly container: string
   readonly root: string
 }
 export default classes

package/src/dashboard/stat-group.tsx

@@ -4,12 +4,18 @@
  * packs tighter than a chart card and the law starts at TWO on a phone.
  *
  * **`cols` is the DESKTOP count** and the only number a consumer states; the law is
- * `base 2 → sm min(cols, 3) → lg cols`. Five is the ceiling — past that the cells are narrower than
+ * `base 2 → sm min(cols, 3), except 4 → 2 → lg cols`. Five is the ceiling — past that the cells are narrower than
  * a formatted currency value and the row is a table.
  *
  * **`lg` enters the package here and in `WidgetGrid`, nowhere else.** `sm` stays the only
  * breakpoint a consumer writes (`docs/CONTROLS-SPEC.md` §2).
  *
+ * **The column law keys on the CONTAINER, not the viewport.** `StatGroup` renders its own
+ * `container-type: inline-size` box around the grid, so the counts follow the width the row
+ * ACTUALLY has — a `PageAside` claiming 300px, a collapsed sidebar giving 208px back, a consumer's
+ * split pane — rather than the viewport width, which changes for none of those. See
+ * `stat-group.module.css`'s header for the measured defect and the pre-2023 fallback.
+ *
  * `divided` swaps the column gap for a hairline rail between cells — the bare-metric-row look, for
  * KPIs that are one reading split several ways rather than several independent cards. It draws the
  * rule on the GROUP, so the cells stay whatever they are; on `StatCard`s (which carry their own
@@ -33,7 +39,7 @@ import classes from './stat-group.module.css'
 export type StatGroupCols = 2 | 3 | 4 | 5
 
 export type StatGroupProps = BasaltProps & {
-  /** The DESKTOP column count (`lg` and up). Default `4`. `sm` gets `min(cols, 3)`, a phone gets 2.
+  /** The DESKTOP column count (`lg` and up). Default `4`. `sm` gets `min(cols, 3)` — except `4`, which gets 2 rather than an orphan row. A phone gets 2.
    * Never a responsive object — the law is basalt's, see the module docblock. */
   cols?: StatGroupCols
   /** Swap the column gap for a hairline rail between cells. Default `false`. */
@@ -49,26 +55,40 @@ export function StatGroup({
   className,
   style,
 }: StatGroupProps) {
-  const smCols = Math.min(cols, 3)
+  // `4 -> 2`, not `4 -> 3`. `min(cols, 3)` is the general rule and it is right for 2, 3 and 5, but
+  // FOUR is the default and the overwhelmingly common count, and three columns leave a four-KPI row
+  // as 3 + 1 — one orphan cell against two thirds of empty track. MEASURED on the playground
+  // dashboard with a `PageAside` claimed (group 916px): three cells of ~273px plus an orphan, where
+  // two of ~450px read as one balanced block. A KPI row is a set of peers; a ragged last row says
+  // one of them is different, which is the one thing it must not say.
+  const smCols = cols === 4 ? 2 : Math.min(cols, 3)
 
   return (
-    <div
-      className={cx(classes.root, className)}
-      data-cols={cols}
-      data-sm-cols={smCols}
-      // An ATTRIBUTE, not a second class: the rail's rules key off the resolved column count
-      // (`[data-cols]`/`[data-sm-cols]`) already, so one selector shape carries the whole law —
-      // same idiom `stat-card.module.css` uses for `[data-placement]`.
-      {...(divided && { 'data-divided': 'true' })}
-      style={
-        {
-          '--basalt-stat-group-cols-sm': smCols,
-          '--basalt-stat-group-cols-lg': cols,
-          ...style,
-        } as CSSProperties
-      }
-    >
-      {children}
+    // Two boxes, and the outer one is not decoration: a size container is a container for its
+    // DESCENDANTS, never for itself, so the grid whose tracks the query decides has to sit inside
+    // the box being measured. `className`/`style` land on the OUTER box because that is the root
+    // element a consumer positions (`BasaltProps`) — and because measuring the box the consumer
+    // sized is the whole point. `container-type: inline-size` contains the inline axis only, so the
+    // wrapper's block size still comes from the grid: no percentage height resolves differently,
+    // and there is no paint containment, so nothing inside is clipped.
+    <div className={cx(classes.container, className)} style={style}>
+      <div
+        className={classes.root}
+        data-cols={cols}
+        data-sm-cols={smCols}
+        // An ATTRIBUTE, not a second class: the rail's rules key off the resolved column count
+        // (`[data-cols]`/`[data-sm-cols]`) already, so one selector shape carries the whole law —
+        // same idiom `stat-card.module.css` uses for `[data-placement]`.
+        {...(divided && { 'data-divided': 'true' })}
+        style={
+          {
+            '--basalt-stat-group-cols-sm': smCols,
+            '--basalt-stat-group-cols-lg': cols,
+          } as CSSProperties
+        }
+      >
+        {children}
+      </div>
     </div>
   )
 }

package/src/dashboard/widget-grid.module.css

@@ -1,15 +1,34 @@
 /*
  * WidgetGrid's column law, in CSS (law C9 — a responsive swap belongs to the control, never to a JS
- * media query). The two literals below are Mantine's own `--mantine-breakpoint-sm` (48em) and
- * `--mantine-breakpoint-lg` (75em); a `@media` condition is resolved before custom properties
- * exist, so the number has to be written — same standing constraint `content/article-layout.
- * module.css` documents.
+ * media query).
  *
- * The COUNTS are custom properties instead, set once per instance by the component: three
- * hand-written `repeat()` blocks would have to enumerate every `cols` value, and the whole point of
- * this primitive is that a consumer states one desktop number and basalt owns the rest.
+ * **The law keys on the CONTAINER, not the viewport**, for the reason `stat-group.module.css`'s
+ * header states in full: the shell moves the available width without moving the viewport (a
+ * `PageAside` claiming 300px, the sidebar collapsing to its 48px rail, a consumer's split layout),
+ * and `@media` is blind to all of it. `.container` — rendered by `WidgetGrid` around the grid —
+ * is what makes the queries answerable and is always the box the grid actually fills; a query with
+ * no container resolves to false, so leaning on the shell to establish one would have pinned every
+ * non-shell consumer to a single column.
+ *
+ * `.item`'s span law is in the same blocks for the same reason: `grid-column: span <n>` must be
+ * clamped against the count the ROOT is actually rendering, and the root's count now follows the
+ * container. A span resolved against the viewport while the tracks follow the container is exactly
+ * the phantom-track defect `WidgetGrid.Item`'s context clamp exists to prevent.
+ *
+ * The literals: px in `@container`, Mantine's own `em` in the `@supports not` fallback — same
+ * boundary (768px / 1200px at the 16px initial font size), but `em` inside a `@container`
+ * condition resolves against the CONTAINER's font-size, so px is the only spelling that cannot
+ * drift. A condition cannot read a custom property either way, so the numbers are written; the
+ * COUNTS are custom properties, set once per instance by the component — three hand-written
+ * `repeat()` blocks would have to enumerate every `cols` value, and the whole point of this
+ * primitive is that a consumer states one desktop number and basalt owns the rest.
  */
 
+.container {
+  container-type: inline-size;
+  container-name: basalt-widget-grid;
+}
+
 .root {
   display: grid;
   /* Below `sm` a widget column is always 1 — a dashboard card holds a chart, and two of them on a
@@ -18,18 +37,6 @@
   gap: var(--vx-space-stack-md);
 }
 
-@media (min-width: 48em) {
-  .root {
-    grid-template-columns: repeat(var(--basalt-widget-grid-cols-sm), minmax(0, 1fr));
-  }
-}
-
-@media (min-width: 75em) {
-  .root {
-    grid-template-columns: repeat(var(--basalt-widget-grid-cols-lg), minmax(0, 1fr));
-  }
-}
-
 /*
  * `min-width: 0` on every cell: a grid track's default `min-width: auto` is its content's intrinsic
  * width, so one wide `<table>` or one long unbroken value blows the whole row out instead of
@@ -40,14 +47,50 @@
   min-width: 0;
 }
 
-@media (min-width: 48em) {
+@container basalt-widget-grid (min-width: 768px) {
+  .root {
+    grid-template-columns: repeat(var(--basalt-widget-grid-cols-sm), minmax(0, 1fr));
+  }
+
   .item {
     grid-column: span var(--basalt-widget-grid-span-sm);
   }
 }
 
-@media (min-width: 75em) {
+@container basalt-widget-grid (min-width: 1200px) {
+  .root {
+    grid-template-columns: repeat(var(--basalt-widget-grid-cols-lg), minmax(0, 1fr));
+  }
+
   .item {
     grid-column: span var(--basalt-widget-grid-span-lg);
   }
 }
+
+/*
+ * The pre-container-query fallback — Safari < 16, Chrome < 106, Firefox < 110. Verbatim the law
+ * this file shipped before, keyed on the viewport, and reachable ONLY where `@container` is not: a
+ * browser that cannot parse `container-type` cannot parse the blocks above either, so the two sets
+ * are never live at once.
+ */
+@supports not (container-type: inline-size) {
+  @media (min-width: 48em) {
+    .root {
+      grid-template-columns: repeat(var(--basalt-widget-grid-cols-sm), minmax(0, 1fr));
+    }
+
+    .item {
+      grid-column: span var(--basalt-widget-grid-span-sm);
+    }
+  }
+
+  @media (min-width: 75em) {
+    .root {
+      grid-template-columns: repeat(var(--basalt-widget-grid-cols-lg), minmax(0, 1fr));
+    }
+
+    .item {
+      grid-column: span var(--basalt-widget-grid-span-lg);
+    }
+  }
+}

package/src/dashboard/widget-grid.module.css.d.ts

@@ -3,6 +3,7 @@
  * signature — so dot access stays verbatim under the package's strict flags.
  */
 declare const classes: {
+  readonly container: string
   readonly root: string
   readonly item: string
 }