basalt-ui 1.37.0 → 1.38.0

package/CHANGELOG.md

@@ -1,3 +1,23 @@
+# [1.38.0](https://github.com/jkrumm/basalt-ui/compare/v1.37.1...v1.38.0) (2026-10-04)
+
+
+### Bug Fixes
+
+* inset the sidebar footer and seat the rail first icon like the expanded row ([7d9e980](https://github.com/jkrumm/basalt-ui/commit/7d9e980b9c1d6cd062e0d8f43a4800f7002b174d))
+* re-date the forms layout deprecations to 1.39.0 ([fe9e785](https://github.com/jkrumm/basalt-ui/commit/fe9e785439c8404dfe09bdcecb774db758123026))
+
+
+### Features
+
+* add --basalt-shell-lead-inset for a native title bar over the header lead ([980c2ff](https://github.com/jkrumm/basalt-ui/commit/980c2ff707a39ec150b64d27780b3ceecb98b922))
+
+## [1.37.1](https://github.com/jkrumm/basalt-ui/compare/v1.37.0...v1.37.1) (2026-10-02)
+
+
+### Bug Fixes
+
+* stop the measured fold folding a row that fits to the sub-pixel ([67aebae](https://github.com/jkrumm/basalt-ui/commit/67aebae33ee966acca555fc98cb609df33a81a6c))
+
 # [1.37.0](https://github.com/jkrumm/basalt-ui/compare/v1.36.1...v1.37.0) (2026-10-02)
 
 

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                                                                                                | 1.32.0                                                                    | 1.32.1                                                                                                          | 1.33.0                                                                        | 1.34.0                             | 1.34.1 | 1.35.0 | 1.36.0                                                                                       | 1.36.1 | 1.37.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` (§ 1.31.0)                                         | —                                                                         | `SIZE_CLASSES`/`CONTAINER_CLASSES` actually exported (§ Fixes)                                                  | `CONTAINER_GRID_BREAKPOINTS`; `raw-breakpoint` trusts it (§ 1.33.0)           | `CONTAINER_KEYS` (§ 1.34.0)        | —      | —      | —                                                                                            | —      | —      | —          |
-| **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`) | —                                                                             | `useBreakpoint` removed (§ 1.34.0) | —      | —      | `useCoarsePointer()` (§ `useCoarsePointer()`)                                                | —      | —      | —          |
-| **controls** (`./controls`)   | `NumberFilter`, `field.number` (§ Controls)                  | sheet renders panel rows; `PanelRow`, `SliderControl` (§ `basalt-ui/controls`)         | —                                                                                              | —                                                                                  | —                                                                     | —      | —                                                                                                     | —                                                                         | —                                                                                                               | `NumberFilter clearable`; `createSearchStore` `resets` (§ State and controls) | —                                  | —      | —      | `FormSection`/`FormRow`/`FormGroup`/`FormActions` move here (§ The form layout moves)        | —      | —      | —          |
-| **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)                                                                   | —                                                                             | —                                  | —      | —      | the layout + `useForm`/`schemaResolver` deprecated, removed 1.37.0 (§ The form layout moves) | —      | —      | —          |
-| **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)                                      | C1 + breakpoint pairs → `error`; `unknown-vx-token` `warn` (§ Guards)         | —                                  | —      | —      | `unknown-vx-token` → `error`; the token factories throw (§ 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                                                                                                          | 1.33.0                                                                        | 1.34.0                             | 1.34.1 | 1.35.0 | 1.36.0                                                                                       | 1.36.1 | 1.37.0 | 1.37.1 | 1.38.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` (§ 1.31.0)                                         | —                                                                         | `SIZE_CLASSES`/`CONTAINER_CLASSES` actually exported (§ Fixes)                                                  | `CONTAINER_GRID_BREAKPOINTS`; `raw-breakpoint` trusts it (§ 1.33.0)           | `CONTAINER_KEYS` (§ 1.34.0)        | —      | —      | —                                                                                            | —      | —      | —      | —      | —          |
+| **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`) | —                                                                             | `useBreakpoint` removed (§ 1.34.0) | —      | —      | `useCoarsePointer()` (§ `useCoarsePointer()`)                                                | —      | —      | —      | —      | —          |
+| **controls** (`./controls`)   | `NumberFilter`, `field.number` (§ Controls)                  | sheet renders panel rows; `PanelRow`, `SliderControl` (§ `basalt-ui/controls`)         | —                                                                                              | —                                                                                  | —                                                                     | —      | —                                                                                                     | —                                                                         | —                                                                                                               | `NumberFilter clearable`; `createSearchStore` `resets` (§ State and controls) | —                                  | —      | —      | `FormSection`/`FormRow`/`FormGroup`/`FormActions` move here (§ The form layout moves)        | —      | —      | —      | —      | —          |
+| **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)                                                                   | —                                                                             | —                                  | —      | —      | the layout + `useForm`/`schemaResolver` deprecated, removed 1.37.0 (§ The form layout moves) | —      | —      | —      | —      | —          |
+| **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)                                      | C1 + breakpoint pairs → `error`; `unknown-vx-token` `warn` (§ Guards)         | —                                  | —      | —      | `unknown-vx-token` → `error`; the token factories throw (§ Guards)                           | —      | —      | —      | —      | —          |
 
 ---
 
@@ -86,6 +86,14 @@ 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.38.0
+
+_Nothing to migrate in this release._
+
+## 1.37.1
+
+_Nothing to migrate in this release._
+
 ## 1.37.0
 
 _Nothing to migrate in this release._
@@ -129,15 +137,15 @@ import. `FormRow`/`FormGroup` stay law C1's form-row home from either subpath.
 
 | Was (`basalt-ui/forms`)                                                               | Now                                                                 | Removed in |
 | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | ---------- |
-| `FormSection`, `FormRow`, `FormGroup`, `FormActions` (+ their `*Props`/`*Slot` types) | the same names from `basalt-ui/controls`                            | 1.38.0     |
-| `useForm`, `schemaResolver`, `UseFormReturnType`, `UseFormInput`                      | `@mantine/form` directly (zero consumers imported them from basalt) | 1.38.0     |
+| `FormSection`, `FormRow`, `FormGroup`, `FormActions` (+ their `*Props`/`*Slot` types) | the same names from `basalt-ui/controls`                            | 1.39.0     |
+| `useForm`, `schemaResolver`, `UseFormReturnType`, `UseFormInput`                      | `@mantine/form` directly (zero consumers imported them from basalt) | 1.39.0     |
 
-**Grace:** every old import still resolves in 1.36.x and 1.37.x (re-dated from 1.37.0: consumers still import them). `basalt/deprecated-export` warns on the six
+**Grace:** every old import still resolves in 1.36.x–1.38.x (re-dated twice, from 1.37.0 and again from 1.38.0: consumers still import them). `basalt/deprecated-export` warns on the six
 values, but the rows are `fix: false` — the autofix rewrites a specifier inside its own import
 statement and cannot change the module — so move the import by hand
 (`import { FormRow } from 'basalt-ui/controls'`). Both subpaths are homes for
 `control-outside-home`/`raw-selection-control` throughout. The `public symbols` budget runs at 401
-during the grace minor; 1.38.0 removes six.
+during the grace minor; 1.39.0 removes six.
 
 ### `useCoarsePointer()` — the pointer class in JS
 

package/configs/oxlint-plugin.js

@@ -2049,7 +2049,7 @@ const CONTROL_OWNER_NAMES = new Set([
  * `control-outside-home` treating it as a home is the whole of the enforcement a settings page
  * gets, and the two tier rules deliberately do not reach inside it (see {@link SLOT_ATTRS}).
  * `FormRow`/`FormGroup` (`basalt-ui/controls`, `src/controls/form-layout.tsx`; `basalt-ui/forms`
- * re-exports them until 1.38.0 — the set is NAME-matched, so both subpaths are homes) are the SAME
+ * re-exports them until 1.39.0 — the set is NAME-matched, so both subpaths are homes) are the SAME
  * home written for a `<form>` rather than a settings page — a `TextInput` bound to a field is read and typed
  * into at Mantine's own tier, not a 30px chrome affordance — so they are added here rather than
  * given a second walk.
@@ -3671,42 +3671,42 @@ export const DEPRECATED_EXPORTS = [
     subpath: 'basalt-ui/forms',
     name: 'FormSection',
     replacement: "FormSection from 'basalt-ui/controls'",
-    removeIn: '1.38.0',
+    removeIn: '1.39.0',
     fix: false,
   },
   {
     subpath: 'basalt-ui/forms',
     name: 'FormRow',
     replacement: "FormRow from 'basalt-ui/controls'",
-    removeIn: '1.38.0',
+    removeIn: '1.39.0',
     fix: false,
   },
   {
     subpath: 'basalt-ui/forms',
     name: 'FormGroup',
     replacement: "FormGroup from 'basalt-ui/controls'",
-    removeIn: '1.38.0',
+    removeIn: '1.39.0',
     fix: false,
   },
   {
     subpath: 'basalt-ui/forms',
     name: 'FormActions',
     replacement: "FormActions from 'basalt-ui/controls'",
-    removeIn: '1.38.0',
+    removeIn: '1.39.0',
     fix: false,
   },
   {
     subpath: 'basalt-ui/forms',
     name: 'useForm',
     replacement: "useForm from '@mantine/form'",
-    removeIn: '1.38.0',
+    removeIn: '1.39.0',
     fix: false,
   },
   {
     subpath: 'basalt-ui/forms',
     name: 'schemaResolver',
     replacement: "schemaResolver from '@mantine/form'",
-    removeIn: '1.38.0',
+    removeIn: '1.39.0',
     fix: false,
   },
   {

package/configs/oxlint-plugin.test.ts

@@ -1923,7 +1923,7 @@ describe('basalt/control-outside-home', () => {
     },
   )
 
-  // FormRow/FormGroup (`basalt-ui/controls`, still re-exported from `basalt-ui/forms` until 1.38.0)
+  // FormRow/FormGroup (`basalt-ui/controls`, still re-exported from `basalt-ui/forms` until 1.39.0)
   // are law C1's third home written for a `<form>` rather than a settings page — the same non-home
   // treatment SettingsRow gets, via the same CONTROL_HOST_TAGS ancestry walk, which matches by NAME
   // so either subpath is a home.
@@ -3393,7 +3393,7 @@ describe('basalt/deprecated-export — the form layout move', () => {
       )
       expect(rules).toContain('deprecated-export')
       expect(output).toContain(`'basalt-ui/controls'`)
-      expect(output).toContain('removed in 1.38.0')
+      expect(output).toContain('removed in 1.39.0')
     },
   )
 

package/dist/controls/actions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../../src/controls/actions.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../../src/controls/actions.tsx"],"names":[],"mappings":"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"}

package/dist/controls/actions.js

@@ -193,6 +193,7 @@ function joinRuns(actions, opts) {
   }
   return runs;
 }
+const SUBPIXEL_SLACK = 1;
 const MORE_WIDTH = 80;
 function planBarFold(input) {
   const { room, fixed, gap, hasMenus, items } = input;
@@ -274,7 +275,13 @@ function useMeasuredFold(input) {
       const rendered = elements.reduce((sum, el) => sum + el.offsetWidth + BAR_GAP, 0);
       const moreNow = hasMenus || Object.values(foldsRef.current).includes("overflow");
       const fixed = used - rendered - (moreNow ? MORE_WIDTH + BAR_GAP : 0);
-      const next = planBarFold({ room: row.clientWidth, fixed, gap: BAR_GAP, hasMenus, items });
+      const next = planBarFold({
+        room: row.clientWidth + SUBPIXEL_SLACK,
+        fixed,
+        gap: BAR_GAP,
+        hasMenus,
+        items
+      });
       const prev = foldsRef.current;
       const same = Object.keys(next).length === Object.keys(prev).length && Object.entries(next).every(([key, step]) => prev[key] === step);
       if (!same) setFolds(next);

package/dist/forms/index.d.ts

@@ -10,7 +10,7 @@
  * (`useFormSubmit` + `FormStateProvider`), the list field (`useFieldArray`) and the draft
  * (`useFormDraft`). The layout (`FormSection` / `FormRow` / `FormGroup` / `FormActions`) moved to
  * `basalt-ui/controls` in 1.36.0 — it needs no `@mantine/form` — and stays here as deprecated
- * aliases until 1.38.0, as do the `useForm`/`schemaResolver` re-exports (import from
+ * aliases until 1.39.0, as do the `useForm`/`schemaResolver` re-exports (import from
  * `@mantine/form`).
  *
  * Optional peer: @mantine/form ^9.3.0 — install with: bun add @mantine/form
@@ -19,26 +19,26 @@ export { useBasaltForm } from './create-form.js';
 export type { UseBasaltFormOptions } from './create-form.js';
 export { inputProps, fieldKey } from './field.js';
 export { 
-/** @deprecated Import from 'basalt-ui/controls' — removed in 1.38.0. */
+/** @deprecated Import from 'basalt-ui/controls' — removed in 1.39.0. */
 FormSection, 
-/** @deprecated Import from 'basalt-ui/controls' — removed in 1.38.0. */
+/** @deprecated Import from 'basalt-ui/controls' — removed in 1.39.0. */
 FormRow, 
-/** @deprecated Import from 'basalt-ui/controls' — removed in 1.38.0. */
+/** @deprecated Import from 'basalt-ui/controls' — removed in 1.39.0. */
 FormGroup, 
-/** @deprecated Import from 'basalt-ui/controls' — removed in 1.38.0. */
+/** @deprecated Import from 'basalt-ui/controls' — removed in 1.39.0. */
 FormActions, } from '../controls/form-layout.js';
 export type { 
-/** @deprecated Import from 'basalt-ui/controls' — removed in 1.38.0. */
+/** @deprecated Import from 'basalt-ui/controls' — removed in 1.39.0. */
 FormSectionProps, 
-/** @deprecated Import from 'basalt-ui/controls' — removed in 1.38.0. */
+/** @deprecated Import from 'basalt-ui/controls' — removed in 1.39.0. */
 FormSectionSlot, 
-/** @deprecated Import from 'basalt-ui/controls' — removed in 1.38.0. */
+/** @deprecated Import from 'basalt-ui/controls' — removed in 1.39.0. */
 FormRowProps, 
-/** @deprecated Import from 'basalt-ui/controls' — removed in 1.38.0. */
+/** @deprecated Import from 'basalt-ui/controls' — removed in 1.39.0. */
 FormRowSlot, 
-/** @deprecated Import from 'basalt-ui/controls' — removed in 1.38.0. */
+/** @deprecated Import from 'basalt-ui/controls' — removed in 1.39.0. */
 FormGroupProps, 
-/** @deprecated Import from 'basalt-ui/controls' — removed in 1.38.0. */
+/** @deprecated Import from 'basalt-ui/controls' — removed in 1.39.0. */
 FormActionsProps, } from '../controls/form-layout.js';
 export { useFormSubmit, isFieldErrorEnvelope } from './use-form-submit.js';
 export type { FormFieldErrors, UseFormSubmitOptions, UseFormSubmitReturn } from './use-form-submit.js';
@@ -51,13 +51,13 @@ export type { FormErrorSummaryProps } from './FormErrorSummary.js';
 export { useFormDraft, DEFAULT_AUTOSAVE_DEBOUNCE_MS } from './use-form-draft.js';
 export type { UseFormDraftOptions, UseFormDraftReturn } from './use-form-draft.js';
 export { 
-/** @deprecated Import from '@mantine/form' — removed in 1.38.0. */
+/** @deprecated Import from '@mantine/form' — removed in 1.39.0. */
 useForm, 
-/** @deprecated Import from '@mantine/form' — removed in 1.38.0. */
+/** @deprecated Import from '@mantine/form' — removed in 1.39.0. */
 schemaResolver, } from '@mantine/form';
 export type { 
-/** @deprecated Import from '@mantine/form' — removed in 1.38.0. */
+/** @deprecated Import from '@mantine/form' — removed in 1.39.0. */
 UseFormReturnType, 
-/** @deprecated Import from '@mantine/form' — removed in 1.38.0. */
+/** @deprecated Import from '@mantine/form' — removed in 1.39.0. */
 UseFormInput, } from '@mantine/form';
 //# sourceMappingURL=index.d.ts.map

package/dist/shell/app-brand.module.css

@@ -15,10 +15,27 @@
  * 10px of `.root` frame inset plus 10px of NavLink inset (`rowInsetX`) = 20. One vertical line
  * across the seam — a claim this comment used to make while the gutter was 13, and that the
  * 13 -> 20 move made true.
+ *
+ * `--basalt-shell-lead-inset` (default 0px, set by the consumer on `:root`) is the opt-in native
+ * title-bar contract: a macOS overlay title bar paints its traffic lights ON TOP of this zone, so a
+ * consumer publishes their span (~70px) and the zone (a) grows its inline-start padding by it and
+ * (b) is never narrower than inset + the collapse toggle, so the 48px rail does not clip the toggle
+ * under `overflow: hidden` (the toggle lands right of the lights; the breadcrumb after a widened
+ * rail zone shifts right by the same amount — accepted). Unset, every value below resolves to
+ * exactly what it was before the property existed: `max(offset, 0px + toggle)` is the offset
+ * (256 / 48 are both above the 28px toggle) and the added padding is 0px.
  */
 .zone {
-  flex: 0 0 var(--app-shell-navbar-offset, 0rem);
-  width: var(--app-shell-navbar-offset, 0rem);
+  /* The collapse toggle's box — `app-brand.tsx`'s `size={28}`, which is Mantine's rem-scaled
+   * `--ai-size-md` (1.75rem). Mantine defines that var on the ActionIcon, not on `:root`, so the
+   * zone restates the same arithmetic; `app-brand.module.css.test.ts` pins the two together. */
+  --basalt-shell-toggle-size: calc(1.75rem * var(--mantine-scale, 1));
+  --basalt-shell-zone-width: max(
+    var(--app-shell-navbar-offset, 0rem),
+    calc(var(--basalt-shell-lead-inset, 0px) + var(--basalt-shell-toggle-size))
+  );
+  flex: 0 0 var(--basalt-shell-zone-width);
+  width: var(--basalt-shell-zone-width);
   min-width: 0;
   display: flex;
   align-items: center;
@@ -27,6 +44,7 @@
   align-self: stretch;
   margin-inline-start: calc(-1 * var(--app-shell-padding, 0px));
   padding-inline: var(--app-shell-padding, 0px);
+  padding-inline-start: calc(var(--app-shell-padding, 0px) + var(--basalt-shell-lead-inset, 0px));
   overflow: hidden;
   /* Mantine's own AppShell timing, so the zone and the navbar under it move as one box. */
   transition-property: flex-basis, width;
@@ -101,11 +119,12 @@
 /*
  * The rail form, mirroring exactly what the sidebar's own brand row did when collapsed: the lead
  * (logo + name) hides and the toggle centres. The zone drops its inset so the toggle's centre lands
- * on the rail's icon column rather than 13px right of it.
+ * on the rail's icon column rather than 13px right of it. The lead inset is the one padding the
+ * rail keeps: the toggle sits right of the native title-bar controls, not centred under them.
  */
 @media (min-width: 52.5em) {
   .zone[data-collapsed] {
-    padding-inline: 0;
+    padding-inline: var(--basalt-shell-lead-inset, 0px) 0;
   }
 
   .zone[data-collapsed] .brand {

package/dist/shell/app-sidebar.module.css

@@ -212,6 +212,11 @@
 .footer {
   flex-shrink: 0;
   padding-top: var(--vx-space-sidebar-region-gap);
+  /* The bottom inset equals the column's side inset (`.root`'s `row-inset-x`), so the last row —
+   * the settings link, the account row or a bottom progress block — does not sit FLUSH on the
+   * navbar's bottom edge against a 10px side gap. Rail and expanded alike: this is the footer's own
+   * edge, not a rail rule, so a collapsed sidebar cannot double it. */
+  padding-bottom: var(--vx-space-row-inset-x);
 }
 
 .footer > * + * {
@@ -697,6 +702,17 @@
     display: none;
   }
 
+  /* The FIRST section's band keeps its label gap in the rail. Expanded, that band's
+   * `margin-bottom` is what seats the first nav row `section-label-gap` below the navbar top (an
+   * unlabelled band is zero-height); zeroing it above left the rail's first icon flush at 0, a few
+   * px higher than the same row expanded. Only the first band: every later band's zeroed margin is
+   * what keeps the gap BETWEEN sections at `section-gap` in the rail, where the label it separated
+   * from the rows is gone. (A labelled first section expands to label + gap, which the rail cannot
+   * match — its label is `display: none`; the equal-offset contract is the unlabelled case.) */
+  .root[data-collapsed] .nav > div:first-child > .sectionBand {
+    margin-bottom: var(--vx-space-sidebar-section-label-gap);
+  }
+
   /* Collapse every nav row to its icon. Targets `.navItem` — the wrapper Box present on EVERY render
    * path — so it covers the shell's fallback NavLink AND a consumer's `SidebarItem.Anchor` (e.g. a router
    * <Link>), both of which render a Mantine NavLink inside. Keying off `.link` alone missed consumer

package/dist/shell/index.d.ts

@@ -152,6 +152,13 @@ export type BasaltShellProps = BasaltProps & {
  * inside it: `PageBarProvider` owns the header portal and the single-kebab claim, `AsideProvider`
  * owns the aside portal, the region CLAIM and the claiming page's fold state — which `ShellFrame`
  * has to READ to size `AppShell.Aside`, so it cannot be the component that provides it.
+ *
+ * **Native title bar (opt-in CSS contract).** A desktop host with a macOS overlay title bar paints
+ * its traffic lights ON TOP of the header's leading zone. Set `--basalt-shell-lead-inset` on
+ * `:root` to their span (e.g. `html { --basalt-shell-lead-inset: 70px }`; default `0px`, which
+ * changes nothing): the zone's inline-start padding grows by it, and the zone is never narrower than
+ * the inset plus the collapse toggle, so the 48px rail pushes the toggle to the right of the lights
+ * instead of clipping it. The breadcrumb after a widened rail zone shifts right by the same amount.
  */
 export declare function BasaltShell(props: BasaltShellProps): import("react").JSX.Element;
 //# sourceMappingURL=index.d.ts.map

package/dist/shell/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/shell/index.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/shell/index.tsx"],"names":[],"mappings":"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"}

package/llms.txt

@@ -1,4 +1,4 @@
-# basalt-ui v1.37.0
+# basalt-ui v1.38.0
 # Opinionated framework for Mantine-based React apps — theme, app shell, visx charts, toolchain presets
 #
 # basalt-ui is an opinionated framework for Mantine-based React apps.
@@ -19,7 +19,7 @@
 # ./tokens.css subpath. Guide: docs/FRAMEWORK-FREE.md in the repo.
 
 Package: basalt-ui
-Version: 1.37.0
+Version: 1.38.0
 
 ## basalt-ui
 Import: import { ... } from 'basalt-ui'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "basalt-ui",
-  "version": "1.37.0",
+  "version": "1.38.0",
   "description": "Opinionated framework for Mantine-based React apps — theme, app shell, visx charts, toolchain presets",
   "keywords": [
     "charts",

package/src/controls/actions.tsx

@@ -477,6 +477,9 @@ function joinRuns<T extends BarAction>(
 
 type FoldStep = 'icon' | 'overflow'
 
+/** `clientWidth` rounds to a whole pixel; the measured boxes do not — see `useMeasuredFold`. */
+const SUBPIXEL_SLACK = 1
+
 /** The `More` trigger's estimated width — reserved only once something has folded (cf. `FOLD_PILL_WIDTH`). */
 const MORE_WIDTH = 80
 
@@ -612,7 +615,16 @@ function useMeasuredFold(input: {
       const rendered = elements.reduce((sum, el) => sum + el.offsetWidth + BAR_GAP, 0)
       const moreNow = hasMenus || Object.values(foldsRef.current).includes('overflow')
       const fixed = used - rendered - (moreNow ? MORE_WIDTH + BAR_GAP : 0)
-      const next = planBarFold({ room: row.clientWidth, fixed, gap: BAR_GAP, hasMenus, items })
+      // `clientWidth` is a rounded integer, the rects above are fractional: a row that is exactly as
+      // wide as its content (a `slot` host's shrink-wrapped `Group`, measured against itself) would
+      // read 123.4px of content in 123px of room and fold a button that fits.
+      const next = planBarFold({
+        room: row.clientWidth + SUBPIXEL_SLACK,
+        fixed,
+        gap: BAR_GAP,
+        hasMenus,
+        items,
+      })
       const prev = foldsRef.current
       const same =
         Object.keys(next).length === Object.keys(prev).length &&

package/src/controls/form-layout.tsx

@@ -2,7 +2,7 @@
  * ./controls — the form layout primitives: `FormSection`, `FormRow`, `FormGroup`, `FormActions`.
  * Mantine-coupled. They need no `@mantine/form` (layout only), which is why they live here and not
  * in `./forms`, whose barrel value-imports it: importing a row from there made a consumer install a
- * peer it never used. `./forms` re-exports them as deprecated aliases until 1.38.0.
+ * peer it never used. `./forms` re-exports them as deprecated aliases until 1.39.0.
  *
  * The gap they close (audit B #5 / §4): `./forms` shipped no layout at all, so the only row
  * primitive in the package was `SettingsRow` over in `./dashboard` — which is the SETTINGS-page

package/src/controls/index.ts

@@ -56,7 +56,7 @@ export { SliderControl, type SliderControlProps } from './slider-control'
 
 // ── The form layout (moved from ./forms in 1.36.0) ────────────────────────────────────────────
 // Layout needs no `@mantine/form`, and `./forms`' barrel value-imports it — so a consumer rendering
-// a `FormRow` had to install a peer it never used. `./forms` re-exports these until 1.38.0.
+// a `FormRow` had to install a peer it never used. `./forms` re-exports these until 1.39.0.
 export {
   FormSection,
   FormRow,

package/src/forms/index.ts

@@ -10,7 +10,7 @@
  * (`useFormSubmit` + `FormStateProvider`), the list field (`useFieldArray`) and the draft
  * (`useFormDraft`). The layout (`FormSection` / `FormRow` / `FormGroup` / `FormActions`) moved to
  * `basalt-ui/controls` in 1.36.0 — it needs no `@mantine/form` — and stays here as deprecated
- * aliases until 1.38.0, as do the `useForm`/`schemaResolver` re-exports (import from
+ * aliases until 1.39.0, as do the `useForm`/`schemaResolver` re-exports (import from
  * `@mantine/form`).
  *
  * Optional peer: @mantine/form ^9.3.0 — install with: bun add @mantine/form
@@ -24,29 +24,29 @@ export type { UseBasaltFormOptions } from './create-form'
 // Two calls, never one object: `key` inside a spread is a React 19 warning. See field.ts.
 export { inputProps, fieldKey } from './field'
 
-// ── layout — moved to ./controls (1.36.0), deprecated aliases until 1.38.0 ─────
+// ── layout — moved to ./controls (1.36.0), deprecated aliases until 1.39.0 ─────
 export {
-  /** @deprecated Import from 'basalt-ui/controls' — removed in 1.38.0. */
+  /** @deprecated Import from 'basalt-ui/controls' — removed in 1.39.0. */
   FormSection,
-  /** @deprecated Import from 'basalt-ui/controls' — removed in 1.38.0. */
+  /** @deprecated Import from 'basalt-ui/controls' — removed in 1.39.0. */
   FormRow,
-  /** @deprecated Import from 'basalt-ui/controls' — removed in 1.38.0. */
+  /** @deprecated Import from 'basalt-ui/controls' — removed in 1.39.0. */
   FormGroup,
-  /** @deprecated Import from 'basalt-ui/controls' — removed in 1.38.0. */
+  /** @deprecated Import from 'basalt-ui/controls' — removed in 1.39.0. */
   FormActions,
 } from '../controls/form-layout'
 export type {
-  /** @deprecated Import from 'basalt-ui/controls' — removed in 1.38.0. */
+  /** @deprecated Import from 'basalt-ui/controls' — removed in 1.39.0. */
   FormSectionProps,
-  /** @deprecated Import from 'basalt-ui/controls' — removed in 1.38.0. */
+  /** @deprecated Import from 'basalt-ui/controls' — removed in 1.39.0. */
   FormSectionSlot,
-  /** @deprecated Import from 'basalt-ui/controls' — removed in 1.38.0. */
+  /** @deprecated Import from 'basalt-ui/controls' — removed in 1.39.0. */
   FormRowProps,
-  /** @deprecated Import from 'basalt-ui/controls' — removed in 1.38.0. */
+  /** @deprecated Import from 'basalt-ui/controls' — removed in 1.39.0. */
   FormRowSlot,
-  /** @deprecated Import from 'basalt-ui/controls' — removed in 1.38.0. */
+  /** @deprecated Import from 'basalt-ui/controls' — removed in 1.39.0. */
   FormGroupProps,
-  /** @deprecated Import from 'basalt-ui/controls' — removed in 1.38.0. */
+  /** @deprecated Import from 'basalt-ui/controls' — removed in 1.39.0. */
   FormActionsProps,
 } from '../controls/form-layout'
 
@@ -70,14 +70,14 @@ export type { UseFormDraftOptions, UseFormDraftReturn } from './use-form-draft'
 
 // ── @mantine/form re-exports — deprecated, zero consumers import them from here ──
 export {
-  /** @deprecated Import from '@mantine/form' — removed in 1.38.0. */
+  /** @deprecated Import from '@mantine/form' — removed in 1.39.0. */
   useForm,
-  /** @deprecated Import from '@mantine/form' — removed in 1.38.0. */
+  /** @deprecated Import from '@mantine/form' — removed in 1.39.0. */
   schemaResolver,
 } from '@mantine/form'
 export type {
-  /** @deprecated Import from '@mantine/form' — removed in 1.38.0. */
+  /** @deprecated Import from '@mantine/form' — removed in 1.39.0. */
   UseFormReturnType,
-  /** @deprecated Import from '@mantine/form' — removed in 1.38.0. */
+  /** @deprecated Import from '@mantine/form' — removed in 1.39.0. */
   UseFormInput,
 } from '@mantine/form'

package/src/shell/app-brand.module.css

@@ -15,10 +15,27 @@
  * 10px of `.root` frame inset plus 10px of NavLink inset (`rowInsetX`) = 20. One vertical line
  * across the seam — a claim this comment used to make while the gutter was 13, and that the
  * 13 -> 20 move made true.
+ *
+ * `--basalt-shell-lead-inset` (default 0px, set by the consumer on `:root`) is the opt-in native
+ * title-bar contract: a macOS overlay title bar paints its traffic lights ON TOP of this zone, so a
+ * consumer publishes their span (~70px) and the zone (a) grows its inline-start padding by it and
+ * (b) is never narrower than inset + the collapse toggle, so the 48px rail does not clip the toggle
+ * under `overflow: hidden` (the toggle lands right of the lights; the breadcrumb after a widened
+ * rail zone shifts right by the same amount — accepted). Unset, every value below resolves to
+ * exactly what it was before the property existed: `max(offset, 0px + toggle)` is the offset
+ * (256 / 48 are both above the 28px toggle) and the added padding is 0px.
  */
 .zone {
-  flex: 0 0 var(--app-shell-navbar-offset, 0rem);
-  width: var(--app-shell-navbar-offset, 0rem);
+  /* The collapse toggle's box — `app-brand.tsx`'s `size={28}`, which is Mantine's rem-scaled
+   * `--ai-size-md` (1.75rem). Mantine defines that var on the ActionIcon, not on `:root`, so the
+   * zone restates the same arithmetic; `app-brand.module.css.test.ts` pins the two together. */
+  --basalt-shell-toggle-size: calc(1.75rem * var(--mantine-scale, 1));
+  --basalt-shell-zone-width: max(
+    var(--app-shell-navbar-offset, 0rem),
+    calc(var(--basalt-shell-lead-inset, 0px) + var(--basalt-shell-toggle-size))
+  );
+  flex: 0 0 var(--basalt-shell-zone-width);
+  width: var(--basalt-shell-zone-width);
   min-width: 0;
   display: flex;
   align-items: center;
@@ -27,6 +44,7 @@
   align-self: stretch;
   margin-inline-start: calc(-1 * var(--app-shell-padding, 0px));
   padding-inline: var(--app-shell-padding, 0px);
+  padding-inline-start: calc(var(--app-shell-padding, 0px) + var(--basalt-shell-lead-inset, 0px));
   overflow: hidden;
   /* Mantine's own AppShell timing, so the zone and the navbar under it move as one box. */
   transition-property: flex-basis, width;
@@ -101,11 +119,12 @@
 /*
  * The rail form, mirroring exactly what the sidebar's own brand row did when collapsed: the lead
  * (logo + name) hides and the toggle centres. The zone drops its inset so the toggle's centre lands
- * on the rail's icon column rather than 13px right of it.
+ * on the rail's icon column rather than 13px right of it. The lead inset is the one padding the
+ * rail keeps: the toggle sits right of the native title-bar controls, not centred under them.
  */
 @media (min-width: 52.5em) {
   .zone[data-collapsed] {
-    padding-inline: 0;
+    padding-inline: var(--basalt-shell-lead-inset, 0px) 0;
   }
 
   .zone[data-collapsed] .brand {

package/src/shell/app-sidebar.module.css

@@ -212,6 +212,11 @@
 .footer {
   flex-shrink: 0;
   padding-top: var(--vx-space-sidebar-region-gap);
+  /* The bottom inset equals the column's side inset (`.root`'s `row-inset-x`), so the last row —
+   * the settings link, the account row or a bottom progress block — does not sit FLUSH on the
+   * navbar's bottom edge against a 10px side gap. Rail and expanded alike: this is the footer's own
+   * edge, not a rail rule, so a collapsed sidebar cannot double it. */
+  padding-bottom: var(--vx-space-row-inset-x);
 }
 
 .footer > * + * {
@@ -697,6 +702,17 @@
     display: none;
   }
 
+  /* The FIRST section's band keeps its label gap in the rail. Expanded, that band's
+   * `margin-bottom` is what seats the first nav row `section-label-gap` below the navbar top (an
+   * unlabelled band is zero-height); zeroing it above left the rail's first icon flush at 0, a few
+   * px higher than the same row expanded. Only the first band: every later band's zeroed margin is
+   * what keeps the gap BETWEEN sections at `section-gap` in the rail, where the label it separated
+   * from the rows is gone. (A labelled first section expands to label + gap, which the rail cannot
+   * match — its label is `display: none`; the equal-offset contract is the unlabelled case.) */
+  .root[data-collapsed] .nav > div:first-child > .sectionBand {
+    margin-bottom: var(--vx-space-sidebar-section-label-gap);
+  }
+
   /* Collapse every nav row to its icon. Targets `.navItem` — the wrapper Box present on EVERY render
    * path — so it covers the shell's fallback NavLink AND a consumer's `SidebarItem.Anchor` (e.g. a router
    * <Link>), both of which render a Mantine NavLink inside. Keying off `.link` alone missed consumer

package/src/shell/index.tsx

@@ -319,6 +319,13 @@ function collapseStore(key: string): CollapseStore {
  * inside it: `PageBarProvider` owns the header portal and the single-kebab claim, `AsideProvider`
  * owns the aside portal, the region CLAIM and the claiming page's fold state — which `ShellFrame`
  * has to READ to size `AppShell.Aside`, so it cannot be the component that provides it.
+ *
+ * **Native title bar (opt-in CSS contract).** A desktop host with a macOS overlay title bar paints
+ * its traffic lights ON TOP of the header's leading zone. Set `--basalt-shell-lead-inset` on
+ * `:root` to their span (e.g. `html { --basalt-shell-lead-inset: 70px }`; default `0px`, which
+ * changes nothing): the zone's inline-start padding grows by it, and the zone is never narrower than
+ * the inset plus the collapse toggle, so the 48px rail pushes the toggle to the right of the lights
+ * instead of clipping it. The breadcrumb after a widened rail zone shifts right by the same amount.
  */
 export function BasaltShell(props: BasaltShellProps) {
   assertRequiredProps('BasaltShell', props, ['brand', 'sections'])