basalt-ui 1.35.0 → 1.36.1

package/llms.txt

@@ -1,4 +1,4 @@
-# basalt-ui v1.35.0
+# basalt-ui v1.36.1
 # 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,11 +19,11 @@
 # ./tokens.css subpath. Guide: docs/FRAMEWORK-FREE.md in the repo.
 
 Package: basalt-ui
-Version: 1.35.0
+Version: 1.36.1
 
 ## basalt-ui
 Import: import { ... } from 'basalt-ui'
-Description: BasaltProvider, createBasaltTheme, BasaltShell + sidebar/mobile-nav/breadcrumbs, PageBar, PageAside, useSizeClass, NavCountBadge, ThemeToggle, ThreadWorkspace + thread-chat components, WidgetHeader, dashboard composites (DeltaBadge, StatCard with threshold tone, EmptyState, QueryState/LoadingState/ErrorState, SettingsSection/SettingsRow/DangerZone), ConnectivityProvider/useConnectivity/ConnectivityIndicator (auto-mounted, C1: absorbed from the dropped ./connectivity), createBasaltQueryClient/unwrap/BasaltQueryDevtools (C1: absorbed from the dropped ./query), BasaltDevDock (C5: lazy Router/Query devtools + theme lab in one dock)
+Description: BasaltProvider, createBasaltTheme, BasaltShell + sidebar/mobile-nav/breadcrumbs, PageBar, PageAside, useSizeClass, useCoarsePointer, NavCountBadge, ThemeToggle, ThreadWorkspace + thread-chat components, WidgetHeader, dashboard composites (DeltaBadge, StatCard with threshold tone, EmptyState, QueryState/LoadingState/ErrorState, SettingsSection/SettingsRow/DangerZone), ConnectivityProvider/useConnectivity/ConnectivityIndicator (auto-mounted, C1: absorbed from the dropped ./connectivity), createBasaltQueryClient/unwrap/BasaltQueryDevtools (C1: absorbed from the dropped ./query), BasaltDevDock (C5: lazy Router/Query devtools + theme lab in one dock)
 Layer: mantine-coupled
 Rule: basalt-mantine
 OptionalPeers: react-markdown@^10.1.0, remark-gfm@^4.0.1, rehype-sanitize@^6.0.0, remend@1.3.0, shiki@^4.3.0, beautiful-mermaid@^1.1.0, @tanstack/react-router-devtools@^1.166.13
@@ -70,7 +70,7 @@ OptionalPeers: @tanstack/react-router@^1.170.0
 
 ## basalt-ui/forms
 Import: import { ... } from 'basalt-ui/forms'
-Description: Mantine form layer: useBasaltForm + inputProps/fieldKey (two calls — a spread `key` is a React 19 warning; the deprecated `field` alias for `inputProps` was removed in 1.29.0, C1 consolidation), the FormSection/FormRow/FormGroup/FormActions layout (FormRow is law C1’s form row), useFormSubmit (submit state, decoded errors, server fieldErrors, focus-first-error, validateAsync), FormStateProvider disable propagation, useFieldArray, FormErrorSummary, useFormDraft with autosave (Standard Schema)
+Description: Mantine form layer: useBasaltForm + inputProps/fieldKey (two calls — a spread `key` is a React 19 warning; the deprecated `field` alias for `inputProps` was removed in 1.29.0, C1 consolidation), useFormSubmit (submit state, decoded errors, server fieldErrors, focus-first-error, validateAsync), FormStateProvider disable propagation, useFieldArray, FormErrorSummary, useFormDraft with autosave (Standard Schema). The FormSection/FormRow/FormGroup/FormActions layout moved to ./controls in 1.36.0 and the useForm/schemaResolver re-exports are deprecated (import from @mantine/form); all six stay here until 1.37.0
 Layer: mantine-coupled
 Rule: basalt-batteries
 OptionalPeers: @mantine/form@^9.3.0
@@ -126,7 +126,7 @@ OptionalPeers: shiki@^4.3.0, @shikijs/langs@^4.3.1, @shikijs/themes@^4.3.1, beau
 
 ## basalt-ui/controls
 Import: import { ... } from 'basalt-ui/controls'
-Description: The control tier (docs/CONTROLS-SPEC.md §3): FilterSet (nowrap row + measured +N fold + the mobile Filters (n) sheet), RangeFilter/CompareFilter/SelectFilter/MultiSelectFilter/NumberFilter/SearchFilter/ToggleFilter (each bound to a FieldHandle — no value/onChange/size, law C2/C5; NumberFilter is the field.number lane, a radio list over `options` or a stepper without), ViewTabs, and the action/sync family (ActionGroup, OverflowMenu, SyncButton, BarAction/GlobalAction). THREE surfaces, picked by the home and never by a prop (useFilterSurface): pill in a PageBar row, sheet in the mobile Filters (n) drawer, panel in a PageAside body — where every control renders an inspector/facet ROW instead of a chip (docs/ASIDE-SPEC.md §3). PanelRow is that row primitive (label above, hint, mono readout, an `end` control on the label line) and SliderControl is the one bound control with no pill form at all; the counts/max props on MultiSelectFilter render the Foundry facet list there. Every control owns its own desktop/mobile swap in CSS (C9) and renders size="ctl" internally. Resolves and renders with NO @mantine/dates installed — the custom date picker is injected through RangeFilter.customPicker from ./controls-dates.
+Description: The control tier (docs/CONTROLS-SPEC.md §3): FilterSet (nowrap row + measured +N fold + the mobile Filters (n) sheet), RangeFilter/CompareFilter/SelectFilter/MultiSelectFilter/NumberFilter/SearchFilter/ToggleFilter (each bound to a FieldHandle — no value/onChange/size, law C2/C5; NumberFilter is the field.number lane, a radio list over `options` or a stepper without), ViewTabs, the action/sync family (ActionGroup, OverflowMenu, SyncButton, BarAction/GlobalAction), and the form layout FormSection/FormRow/FormGroup/FormActions (moved here from ./forms in 1.36.0 — FormRow is law C1’s form row and needs no @mantine/form). THREE surfaces, picked by the home and never by a prop (useFilterSurface): pill in a PageBar row, sheet in the mobile Filters (n) drawer, panel in a PageAside body — where every control renders an inspector/facet ROW instead of a chip (docs/ASIDE-SPEC.md §3). PanelRow is that row primitive (label above, hint, mono readout, an `end` control on the label line) and SliderControl is the one bound control with no pill form at all; the counts/max props on MultiSelectFilter render the Foundry facet list there. Every control owns its own desktop/mobile swap in CSS (C9) and renders size="ctl" internally. Resolves and renders with NO @mantine/dates installed — the custom date picker is injected through RangeFilter.customPicker from ./controls-dates.
 Layer: mantine-coupled
 Rule: basalt-controls
 

package/package.json

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

package/src/charts/primitives/ChartFrame.tsx

@@ -8,6 +8,7 @@ import {
   legendSlotContention,
   plotBelowFloor,
 } from '../../common/errors'
+import { useCoarsePointer } from '../../common/use-media-query'
 import { reportOnce, useValidateProps } from '../../common/validate'
 import { SizeClassHintContext, useSizeClass } from '../../shell/use-size-class'
 import { VX } from '../../tokens'
@@ -18,7 +19,7 @@ import { ChartCardContext } from './chart-card-context'
 import { resolveChartLayout, resolveFrameClass } from './chart-layout'
 import { resolveFrameHeight, resolveLegendRollup, resolvePlotRect } from './chart-frame-layout'
 import type { ResponsiveChartHeight } from './chart-frame-layout'
-import { ChartTierProvider, useCoarsePointer, useViewportHeight } from './chart-tier'
+import { ChartTierProvider, useViewportHeight } from './chart-tier'
 import { ChartLegend } from './ChartLegend'
 import { ChartEmpty, ChartError, ChartPending, resolveChartState } from './ChartPending'
 import type { ChartState } from './ChartPending'

package/src/charts/primitives/ChartLegend.tsx

@@ -1,9 +1,10 @@
 import type { CSSProperties, MouseEvent, ReactNode } from 'react'
 import type { BasaltProps } from '../../common/props'
+import { useCoarsePointer } from '../../common/use-media-query'
 import { alpha, VX } from '../../tokens'
 import type { SeriesRole, LegendPlacement } from '../series'
 import { DOTS_HIT_GAP, LEGEND_DOT_SIZE, LEGEND_ROW_GAP, orderEntries } from './chart-frame-layout'
-import { useChartMetrics, useCoarsePointer } from './chart-tier'
+import { useChartMetrics } from './chart-tier'
 import { LegendDisclosure, useLegendDisclosure } from './legend-disclosure'
 
 export type LegendEntry = {

package/src/charts/primitives/chart-tier.tsx

@@ -1,6 +1,5 @@
 import { createContext, useContext, useSyncExternalStore } from 'react'
 import type { ReactNode } from 'react'
-import { useMediaQuery } from '../../common/use-media-query'
 import type { ContainerClass } from '../../tokens/size-classes'
 import { chartMetrics } from './chart-frame-layout'
 import type { ChartTierMetrics } from './chart-frame-layout'
@@ -42,11 +41,6 @@ export function useChartMetrics(): ChartTierMetrics {
 
 const subscribeNothing = (): (() => void) => () => {}
 
-/** Whether the primary pointer is coarse. Server snapshot `false`: hydration agrees, then updates. */
-export function useCoarsePointer(): boolean {
-  return useMediaQuery('(pointer: coarse)', false)
-}
-
 /** Viewport height is quantized so a mobile URL bar collapsing does not re-lay-out every chart. */
 const VIEWPORT_H_STEP = 50
 

package/src/common/index.ts

@@ -19,4 +19,5 @@ export {
 } from './errors'
 export { useValidateProps, assertRequiredProps, resetValidatedProps } from './validate'
 export { scrollParentOf, SCROLLPORT_ATTRIBUTE } from './scroll-parent'
+export { useCoarsePointer } from './use-media-query'
 export { MOTION_DURATION, MOTION_EASE_STANDARD, MOTION_SPRING } from './motion'

package/src/common/use-media-query.ts

@@ -54,3 +54,13 @@ export function useMediaQuery(query: string, serverFallback: boolean): boolean {
   const getServerSnapshot = useCallback(() => serverFallback, [serverFallback])
   return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot)
 }
+
+/**
+ * Whether the primary pointer is coarse — the JS twin of `--vx-hit`'s `(pointer: coarse)` query.
+ * For a branch CSS cannot express (mount one of two components, attach a keydown listener); styling
+ * stays `@media (pointer: coarse)` in a CSS module. Server and hydration snapshot is `false`; a
+ * `createRoot` app reads the real pointer on its first render.
+ */
+export function useCoarsePointer(): boolean {
+  return useMediaQuery('(pointer: coarse)', false)
+}

package/src/common/vx-families.ts

@@ -2,7 +2,7 @@
 
 /**
  * The families every emitted `--vx-*` name lives in (`basaltVxFamilies`) — basalt-owned:
- * `unknown-vx-token` judges every name inside one, and `groupTokens`/`seriesTokens` warn on a
+ * `unknown-vx-token` judges every name inside one, and `groupTokens`/`seriesTokens` throw on a
  * consumer ref there.
  */
 export const BASALT_VX_FAMILIES: readonly string[] = [

package/src/{forms → controls}/form-layout.tsx

@@ -1,6 +1,8 @@
 /**
- * ./forms — the form layout primitives: `FormSection`, `FormRow`, `FormGroup`, `FormActions`.
- * Mantine-coupled. Optional peer: @mantine/form (these four need none of it — they are layout).
+ * ./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.37.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
@@ -22,11 +24,11 @@ import type { ReactNode } from 'react'
 import { cx } from '../common/props'
 import type { BasaltProps, SlotStylesProps } from '../common/props'
 import { assertRequiredProps } from '../common/validate'
-import { BarActionSlot } from '../controls/actions'
-import type { SlotActions } from '../controls/actions'
+import { BarActionSlot } from './actions'
+import type { SlotActions } from './actions'
 import { WidgetHeader } from '../dashboard'
 import type { WidgetHeaderTitleProps } from '../dashboard'
-import { useFormState } from './form-state'
+import { useFormState } from '../forms/form-state'
 import classes from './form-layout.module.css'
 
 // ── the two fragments FormRow and FormGroup both paint ────────────────────────

package/src/controls/index.ts

@@ -53,3 +53,19 @@ export { ViewTabs, type ViewTabsOption, type ViewTabsProps } from './view-tabs'
 // docs. The filters above render their own panel forms; there is nothing extra to import for them.
 export { PanelRow, type PanelRowProps } from './panel-row'
 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.37.0.
+export {
+  FormSection,
+  FormRow,
+  FormGroup,
+  FormActions,
+  type FormSectionProps,
+  type FormSectionSlot,
+  type FormRowProps,
+  type FormRowSlot,
+  type FormGroupProps,
+  type FormActionsProps,
+} from './form-layout'

package/src/forms/index.ts

@@ -6,10 +6,12 @@
  * `basalt-ui`. Same reason `./charts` and `./tokens` stay off the root barrel, one optional peer
  * over. Import everything below from `basalt-ui/forms`.
  *
- * Five pieces: the form (`useBasaltForm` + `inputProps`/`fieldKey`), the layout
- * (`FormSection` / `FormRow` / `FormGroup` / `FormActions`), the submit lifecycle
+ * Four pieces: the form (`useBasaltForm` + `inputProps`/`fieldKey`), the submit lifecycle
  * (`useFormSubmit` + `FormStateProvider`), the list field (`useFieldArray`) and the draft
- * (`useFormDraft`).
+ * (`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.37.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
  */
@@ -22,16 +24,31 @@ 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 — law C1's third home, the form row ────────────────────────────────
-export { FormSection, FormRow, FormGroup, FormActions } from './form-layout'
+// ── layout — moved to ./controls (1.36.0), deprecated aliases until 1.37.0 ─────
+export {
+  /** @deprecated Import from 'basalt-ui/controls' — removed in 1.37.0. */
+  FormSection,
+  /** @deprecated Import from 'basalt-ui/controls' — removed in 1.37.0. */
+  FormRow,
+  /** @deprecated Import from 'basalt-ui/controls' — removed in 1.37.0. */
+  FormGroup,
+  /** @deprecated Import from 'basalt-ui/controls' — removed in 1.37.0. */
+  FormActions,
+} from '../controls/form-layout'
 export type {
+  /** @deprecated Import from 'basalt-ui/controls' — removed in 1.37.0. */
   FormSectionProps,
+  /** @deprecated Import from 'basalt-ui/controls' — removed in 1.37.0. */
   FormSectionSlot,
+  /** @deprecated Import from 'basalt-ui/controls' — removed in 1.37.0. */
   FormRowProps,
+  /** @deprecated Import from 'basalt-ui/controls' — removed in 1.37.0. */
   FormRowSlot,
+  /** @deprecated Import from 'basalt-ui/controls' — removed in 1.37.0. */
   FormGroupProps,
+  /** @deprecated Import from 'basalt-ui/controls' — removed in 1.37.0. */
   FormActionsProps,
-} from './form-layout'
+} from '../controls/form-layout'
 
 // ── submit lifecycle ──────────────────────────────────────────────────────────
 export { useFormSubmit, isFieldErrorEnvelope } from './use-form-submit'
@@ -51,6 +68,16 @@ export type { FormErrorSummaryProps } from './FormErrorSummary'
 export { useFormDraft, DEFAULT_AUTOSAVE_DEBOUNCE_MS } from './use-form-draft'
 export type { UseFormDraftOptions, UseFormDraftReturn } from './use-form-draft'
 
-// ── @mantine/form re-exports (convenience) ────────────────────────────────────
-export { useForm, schemaResolver } from '@mantine/form'
-export type { UseFormReturnType, UseFormInput } from '@mantine/form'
+// ── @mantine/form re-exports — deprecated, zero consumers import them from here ──
+export {
+  /** @deprecated Import from '@mantine/form' — removed in 1.37.0. */
+  useForm,
+  /** @deprecated Import from '@mantine/form' — removed in 1.37.0. */
+  schemaResolver,
+} from '@mantine/form'
+export type {
+  /** @deprecated Import from '@mantine/form' — removed in 1.37.0. */
+  UseFormReturnType,
+  /** @deprecated Import from '@mantine/form' — removed in 1.37.0. */
+  UseFormInput,
+} from '@mantine/form'

package/src/guard/index.ts

@@ -334,7 +334,7 @@ const KNOWN_VX_NAMES: ReadonlySet<string> = new Set(BASALT_VX_NAMES)
  * emitted set, so `--vx-surface-2` and a bare root like `--vx-space` are both findings.
  *
  * That judgement is honest only because no consumer ref may point into these families:
- * `groupTokens`/`seriesTokens` warn on a name inside one (and throw once this kind promotes). A name in any OTHER family (argo's
+ * `groupTokens`/`seriesTokens` throw on a name inside one. A name in any OTHER family (argo's
  * `--vx-activity-*`, rb's `--vx-confidence-*`) may be a consumer group declared in a file this scan
  * cannot see, and is never judged.
  */
@@ -893,6 +893,8 @@ export type GraceEntry = { since: string; promote: string; why: string }
 
 /**
  * Kinds still inside their grace minor — reported, not fatal, until the next minor promotes them.
+ * Empty since 1.36.0: `unknown-vx-token`, the last tenant, promoted (its grace ran one minor past
+ * 1.35.0 to keep the factory throw out of the a11y release).
  * See {@link GuardSeverity} for the doctrine and why basalt-ui in particular needs it.
  *
  * Adding a kind here is part of shipping it; removing the entry IS the promotion, and belongs in
@@ -929,19 +931,7 @@ export type GraceEntry = { since: string; promote: string; why: string }
  *   'raw-font-family': { since: '1.4.0', promote: '1.5.0', why: 'introduced 1.4.0 — …' },
  * }
  */
-export const GRACE_PERIOD_KINDS: Partial<Record<GuardKind, GraceEntry>> = {
-  'unknown-vx-token': {
-    since: '1.34.0',
-    promote: '1.36.0',
-    why:
-      'New kind at 1.33.0 (consumer-loop r2 B3): obsidian lost its 44px touch floor to a removed ' +
-      '`var(--vx-space-touch-target)` that nothing reported. WIDENED at 1.34.0 (image-gen r4: ' +
-      '`var(--vx-surface-2)` rendered transparent, unreported) to every unemitted name inside a ' +
-      'basalt-owned family, so the grace restarts: warn through 1.34.x, error at 1.35.0. EXTENDED one minor at 1.35.0: that ' +
-      'minor ships the shell a11y fixes consumers are upgrading for, and the promotion also turns the ' +
-      'seriesTokens warning into a throw — not a change to bundle into that bump. Error at 1.36.0.',
-  },
-}
+export const GRACE_PERIOD_KINDS: Partial<Record<GuardKind, GraceEntry>> = {}
 
 /** A kind's effective severity: consumer override first, then the grace table, then `error`. */
 function severityOf(kind: GuardKind, cfg: GuardConfig): GuardSeverity {
@@ -2272,7 +2262,7 @@ export const GUARD_RULES = {
   'unknown-vx-token': {
     kind: 'unknown-vx-token',
     pattern: VX_VAR_REF, // handled inline (basalt-owned families); entry keeps the registry complete
-    message: `var() names a --vx-* token basalt does not emit, so it resolves to its fallback (or to nothing) with no error anywhere. Judged: every name inside a basalt-owned family (${[...BASALT_VX_FAMILY_SET].join(', ')}) — pick the token from basalt-ui/tokens.css; your own series belong in a family of their own (groupTokens warns on one inside basalt's). Removed names and their replacements: ${Object.entries(
+    message: `var() names a --vx-* token basalt does not emit, so it resolves to its fallback (or to nothing) with no error anywhere. Judged: every name inside a basalt-owned family (${[...BASALT_VX_FAMILY_SET].join(', ')}) — pick the token from basalt-ui/tokens.css; your own series belong in a family of their own (groupTokens throws on one inside basalt's, in dev builds). Removed names and their replacements: ${Object.entries(
       REMOVED_VX_NAMES,
     )
       .map(([from, to]) => `${from} → ${to ?? '(deleted, no replacement)'}`)

package/src/index.ts

@@ -31,6 +31,7 @@ export {
   cx,
   scrollParentOf,
   SCROLLPORT_ATTRIBUTE,
+  useCoarsePointer,
 } from './common'
 
 export { createBasaltTheme, baseTheme, cssVariablesResolver } from './theme'

package/src/provider/index.tsx

@@ -113,10 +113,11 @@ export type BasaltProviderProps = {
   connectivity?: Omit<ConnectivityProviderProps, 'children'>
   /**
    * The size class `useSizeClass()` reports on the server and during hydration, before `matchMedia`
-   * can answer. Default `'compact'` (mobile-first). An SSR app that knows the device class (UA
-   * hint, cookie) passes it so the first frame already matches. An SSR desktop app SHOULD pass it:
-   * without it the first paint is `'compact'`, and `PageAside`/`ThreadWorkspace` remount after
-   * hydration when the real class lands.
+   * can answer. Default `'compact'` (mobile-first). SSR only: a client-rendered (`createRoot`) app
+   * reads `matchMedia` on its first render and never sees this value. An SSR app that knows the
+   * device class (UA hint, cookie) passes it so the first frame already matches. An SSR desktop app
+   * SHOULD pass it: without it the first paint is `'compact'`, and `PageAside`/`ThreadWorkspace`
+   * remount after hydration when the real class lands.
    */
   sizeClassHint?: SizeClass
 } & Omit<MantineProviderProps, 'children' | 'theme' | 'defaultColorScheme' | 'cssVariablesResolver'>

package/src/shell/use-size-class.ts

@@ -4,10 +4,12 @@
  * `'compact' | 'medium' | 'expanded'`, for the JS reads CSS cannot express (portal targets,
  * mount-one-of-two branches). Shell-only — components size by container, not by this.
  *
- * Built on `useMediaQuery` (`common/use-media-query`), one call per class boundary. The server
- * snapshot is `<BasaltProvider sizeClassHint>` (default `'compact'`), so SSR, the hydration pass
- * and the first client paint agree, and the real class lands one commit later — no first-frame
- * flash from a `matchMedia` read inside a `useState` initializer.
+ * Built on `useMediaQuery` (`common/use-media-query`), one call per class boundary. A
+ * client-rendered app (`createRoot`) reads `matchMedia` on its FIRST render — no hint, no flash, so
+ * a mount-one-of-two branch on this hook is flash-free in a CSR SPA (`use-size-class.test.tsx`
+ * pins it). Only SSR and the `hydrateRoot` pass read the server snapshot,
+ * `<BasaltProvider sizeClassHint>` (default `'compact'`), so server HTML and hydration agree and the
+ * real class lands one commit later.
  */
 import { createContext, useContext } from 'react'
 import { useMediaQuery } from '../common/use-media-query'

package/src/surfaces.ts

@@ -299,7 +299,7 @@ export const SURFACES = {
       "no second cssVariablesResolver — don't hand-build createTheme or re-add the resolver basalt already installs",
     ],
     description:
-      'BasaltProvider, createBasaltTheme, BasaltShell + sidebar/mobile-nav/breadcrumbs, PageBar, PageAside, useSizeClass, NavCountBadge, ThemeToggle, ThreadWorkspace + thread-chat components, WidgetHeader, dashboard composites (DeltaBadge, StatCard with threshold tone, EmptyState, QueryState/LoadingState/ErrorState, SettingsSection/SettingsRow/DangerZone), ConnectivityProvider/useConnectivity/ConnectivityIndicator (auto-mounted, C1: absorbed from the dropped ./connectivity), createBasaltQueryClient/unwrap/BasaltQueryDevtools (C1: absorbed from the dropped ./query), BasaltDevDock (C5: lazy Router/Query devtools + theme lab in one dock)',
+      'BasaltProvider, createBasaltTheme, BasaltShell + sidebar/mobile-nav/breadcrumbs, PageBar, PageAside, useSizeClass, useCoarsePointer, NavCountBadge, ThemeToggle, ThreadWorkspace + thread-chat components, WidgetHeader, dashboard composites (DeltaBadge, StatCard with threshold tone, EmptyState, QueryState/LoadingState/ErrorState, SettingsSection/SettingsRow/DangerZone), ConnectivityProvider/useConnectivity/ConnectivityIndicator (auto-mounted, C1: absorbed from the dropped ./connectivity), createBasaltQueryClient/unwrap/BasaltQueryDevtools (C1: absorbed from the dropped ./query), BasaltDevDock (C5: lazy Router/Query devtools + theme lab in one dock)',
     optionalPeers: [
       'react-markdown',
       'remark-gfm',
@@ -443,7 +443,7 @@ export const SURFACES = {
     // consumer ships today (`PLUGIN_RULE_GRACE`).
     pluginRules: ['forms-field-key'],
     description:
-      'Mantine form layer: useBasaltForm + inputProps/fieldKey (two calls — a spread `key` is a React 19 warning; the deprecated `field` alias for `inputProps` was removed in 1.29.0, C1 consolidation), the FormSection/FormRow/FormGroup/FormActions layout (FormRow is law C1’s form row), useFormSubmit (submit state, decoded errors, server fieldErrors, focus-first-error, validateAsync), FormStateProvider disable propagation, useFieldArray, FormErrorSummary, useFormDraft with autosave (Standard Schema)',
+      'Mantine form layer: useBasaltForm + inputProps/fieldKey (two calls — a spread `key` is a React 19 warning; the deprecated `field` alias for `inputProps` was removed in 1.29.0, C1 consolidation), useFormSubmit (submit state, decoded errors, server fieldErrors, focus-first-error, validateAsync), FormStateProvider disable propagation, useFieldArray, FormErrorSummary, useFormDraft with autosave (Standard Schema). The FormSection/FormRow/FormGroup/FormActions layout moved to ./controls in 1.36.0 and the useForm/schemaResolver re-exports are deprecated (import from @mantine/form); all six stay here until 1.37.0',
     optionalPeers: ['@mantine/form'],
     forbiddenImports: [],
   },
@@ -589,7 +589,7 @@ export const SURFACES = {
       'C12 — one shape for refresh/sync (SyncButton); only the alias table sees a renamed copy',
     ],
     description:
-      'The control tier (docs/CONTROLS-SPEC.md §3): FilterSet (nowrap row + measured +N fold + the mobile Filters (n) sheet), RangeFilter/CompareFilter/SelectFilter/MultiSelectFilter/NumberFilter/SearchFilter/ToggleFilter (each bound to a FieldHandle — no value/onChange/size, law C2/C5; NumberFilter is the field.number lane, a radio list over `options` or a stepper without), ViewTabs, and the action/sync family (ActionGroup, OverflowMenu, SyncButton, BarAction/GlobalAction). THREE surfaces, picked by the home and never by a prop (useFilterSurface): pill in a PageBar row, sheet in the mobile Filters (n) drawer, panel in a PageAside body — where every control renders an inspector/facet ROW instead of a chip (docs/ASIDE-SPEC.md §3). PanelRow is that row primitive (label above, hint, mono readout, an `end` control on the label line) and SliderControl is the one bound control with no pill form at all; the counts/max props on MultiSelectFilter render the Foundry facet list there. Every control owns its own desktop/mobile swap in CSS (C9) and renders size="ctl" internally. Resolves and renders with NO @mantine/dates installed — the custom date picker is injected through RangeFilter.customPicker from ./controls-dates.',
+      'The control tier (docs/CONTROLS-SPEC.md §3): FilterSet (nowrap row + measured +N fold + the mobile Filters (n) sheet), RangeFilter/CompareFilter/SelectFilter/MultiSelectFilter/NumberFilter/SearchFilter/ToggleFilter (each bound to a FieldHandle — no value/onChange/size, law C2/C5; NumberFilter is the field.number lane, a radio list over `options` or a stepper without), ViewTabs, the action/sync family (ActionGroup, OverflowMenu, SyncButton, BarAction/GlobalAction), and the form layout FormSection/FormRow/FormGroup/FormActions (moved here from ./forms in 1.36.0 — FormRow is law C1’s form row and needs no @mantine/form). THREE surfaces, picked by the home and never by a prop (useFilterSurface): pill in a PageBar row, sheet in the mobile Filters (n) drawer, panel in a PageAside body — where every control renders an inspector/facet ROW instead of a chip (docs/ASIDE-SPEC.md §3). PanelRow is that row primitive (label above, hint, mono readout, an `end` control on the label line) and SliderControl is the one bound control with no pill form at all; the counts/max props on MultiSelectFilter render the Foundry facet list there. Every control owns its own desktop/mobile swap in CSS (C9) and renders size="ctl" internally. Resolves and renders with NO @mantine/dates installed — the custom date picker is injected through RangeFilter.customPicker from ./controls-dates.',
     optionalPeers: [],
     // `@mantine/dates` is an optional peer basaltViteConfig pre-bundles the whole @mantine scope
     // for — a consumer without the peer (linewatch) must never resolve it through this surface.
@@ -608,6 +608,14 @@ export const SURFACES = {
         '@mantine/dates/*',
         '@mantine/dates is an OPTIONAL peer (docs/CONTROLS-SPEC.md §3) — ./controls must resolve with no @mantine/dates installed. The one reach lives in src/controls-dates/, injected into range-filter.tsx’s customPicker seam.',
       ),
+      v(
+        '@mantine/form',
+        '@mantine/form is an OPTIONAL peer — ./controls (which owns the form layout since 1.36.0) must resolve with no @mantine/form installed. Only ./forms needs it.',
+      ),
+      vg(
+        '@mantine/form/*',
+        '@mantine/form is an OPTIONAL peer — ./controls (which owns the form layout since 1.36.0) must resolve with no @mantine/form installed. Only ./forms needs it.',
+      ),
     ],
   },
   './controls-dates': {

package/src/tokens/index.ts

@@ -808,23 +808,20 @@ function frameworkDerived(data: PaletteData, only: 'core' | 'all', legacyAliases
   return legacyAliases ? `${canonical}\n${frameworkDerivedAliases(data)}` : canonical
 }
 
-const warnedVxNames = new Set<string>()
-
 /**
- * Warn, once per name, on a consumer series/group name inside a basalt-owned `--vx-*` family
- * (`surface`, `space`, `ink`, …): `check-theme`'s `unknown-vx-token` judges every name there against
- * what basalt emits, which is sound only while no consumer REF points there. A WARNING for the
- * minor that kind is graced in (1.34.x), dev builds only; `grace.test.ts` pins the message's
- * version to the ledger's `promote` and requires a throw once the kind promotes.
- * The families are the guard's own generated `BASALT_VX_FAMILIES`. Checked on the refs, not in
- * `buildPaletteCss`, which runs on every first paint.
+ * Throw on a consumer series/group name inside a basalt-owned `--vx-*` family (`surface`, `space`,
+ * `ink`, …): `check-theme`'s `unknown-vx-token` judges every name there against what basalt emits,
+ * which is sound only while no consumer REF points there. Dev builds only (the call sits behind a
+ * literal NODE_ENV read); `unknown-vx-token` left the grace ledger at 1.36.0, which is when this
+ * went from a once-per-name warning to a throw. The families are the guard's own generated
+ * `BASALT_VX_FAMILIES`. Checked on the refs, not in `buildPaletteCss`, which runs on every first
+ * paint.
  */
-function warnConsumerVxName(name: string): void {
+function assertConsumerVxName(name: string): void {
   const family = vxFamilyOf(name)
-  if (!BASALT_VX_FAMILIES.includes(family) || warnedVxNames.has(name)) return
-  warnedVxNames.add(name)
-  console.warn(
-    `[basalt] ${name} is inside basalt's own --vx-${family} family — name your series group something basalt does not own (groupTokens('app', …)). Throws from 1.36.0.`,
+  if (!BASALT_VX_FAMILIES.includes(family)) return
+  throw new Error(
+    `[basalt] ${name} is inside basalt's own --vx-${family} family — name your series group something basalt does not own (groupTokens('app', …)).`,
   )
 }
 
@@ -842,7 +839,7 @@ export function seriesTokens<const T extends SeriesMap>(
   const out = {} as { [K in keyof T]: string }
   for (const key of Object.keys(map) as (keyof T)[]) {
     // Literal read at the branch, so a production bundle drops the check (common/dev-gate.test.ts).
-    if (process.env.NODE_ENV !== 'production') warnConsumerVxName(`--vx-${prefix}${String(key)}`)
+    if (process.env.NODE_ENV !== 'production') assertConsumerVxName(`--vx-${prefix}${String(key)}`)
     out[key] = `var(--vx-${prefix}${String(key)})`
   }
   return out

package/dist/forms/form-layout.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"form-layout.d.ts","sourceRoot":"","sources":["../../src/forms/form-layout.tsx"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAEtC,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAGnE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AAEtD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAA;AAyC1D,gEAAgE;AAChE,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAA;AAExD;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,WAAW,GACxC,eAAe,CAAC,eAAe,CAAC,GAChC,sBAAsB,GAAG;IACvB,0DAA0D;IAC1D,QAAQ,EAAE,SAAS,CAAA;CACpB,CAAA;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,gBAAgB,+BAoBlD;AAID,4DAA4D;AAC5D,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAA;AAEtD,MAAM,MAAM,YAAY,GAAG,WAAW,GACpC,eAAe,CAAC,WAAW,CAAC,GAAG;IAC7B,4FAA4F;IAC5F,KAAK,EAAE,MAAM,CAAA;IACb,oFAAoF;IACpF,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;;;OAKG;IACH,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB,oGAAoG;IACpG,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,4FAA4F;IAC5F,QAAQ,EAAE,SAAS,CAAA;CACpB,CAAA;AAEH;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,YAAY,+BA0B1C;AAID,MAAM,MAAM,cAAc,GAAG,WAAW,GAAG;IACzC,qGAAqG;IACrG,KAAK,EAAE,MAAM,CAAA;IACb,mCAAmC;IACnC,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,0DAA0D;IAC1D,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,KAAK,GAAG,QAAQ,CAAA;IAC5B,+CAA+C;IAC/C,QAAQ,EAAE,SAAS,CAAA;CACpB,CAAA;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,cAAc,+BAsB9C;AAID,MAAM,MAAM,gBAAgB,GAAG,WAAW,GAAG;IAC3C;;;;;;;;OAQG;IACH,OAAO,EAAE,WAAW,CAAA;CACrB,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,gBAAgB,+BAgBlD"}