basalt-ui 1.25.0 → 1.27.0

package/src/guard/index.ts

@@ -1,7 +1,7 @@
 /**
  * ./guard — headless policy core. Mantine-free, dependency-free.
  *
- * GUARD_RULES: the closed registry of all 25 violation kinds.
+ * GUARD_RULES: the closed registry of all 27 violation kinds.
  * checkSource:  pure (text, relPath, cfg) → Finding[]. No FS, no walk, no console.
  */
 import type { Finding, GuardConfig, GuardKind, GuardSeverity } from './types'
@@ -483,6 +483,68 @@ const RAW_FORM_CONTROL = /<(?:input|select|textarea)\b/g
 // for a sub-floor fontSize.
 const RAW_FORM_CONTROL_TAG = /<(?:input|select|textarea)\b(?:=>|[^>])*?>/g
 
+// ── Control-home patterns (docs/CONTROLS-SPEC.md §6 — the text lane of laws C1/C8) ──────────────
+//
+// Bounded full-text tag scans, the CARD_SURFACE_TAG / CHART_ENTRY_POINT_TAG shape: a `<Title>` and a
+// `<Select>` are both routinely formatted across lines, so a per-line regex would see neither.
+
+/** A `<Title …>` opening tag, however it is wrapped. `order` is judged separately, on the tag text. */
+const PAGE_TITLE_TAG = /<Title(?![\w.])(?:=>|[^>])*?>/g
+/** `order={1}` / `order={2}` — the two orders that name a PAGE rather than a section. */
+const PAGE_TITLE_ORDER_PROP = /\border\s*=\s*\{\s*([12])\s*\}/
+
+/**
+ * A raw Mantine selection control's opening tag — the text-lane twin of the oxlint plugin's
+ * RAW_FILTER_TAGS. `Chip.Group` carries a dot, so the name class allows one.
+ */
+const RAW_SELECTION_CONTROL_TAG =
+  /<(SegmentedControl|Select|MultiSelect|NativeSelect|DatePickerInput|DateInput|TagsInput|Chip\.Group)(?![\w])(?:=>|[^>])*?>/g
+
+/**
+ * A tag whose presence makes an `order={1|2}` Title a DOCUMENT heading rather than a page title.
+ * File-scoped on purpose — see the scan's own comment for why the coarser test is the honest one.
+ */
+const PROSE_CONTEXT_TAG = /<(?:Prose|ArticleLayout|Modal|Drawer)(?![\w])/
+
+/** An opening tag for one of the declared non-homes — a settings row, an overlay, a composer. */
+const CONTROL_HOST_TAG =
+  /<(?:SettingsRow|Modal|Drawer|Popover\.Dropdown|Menu\.Dropdown|Composer)(?![\w])/
+
+/**
+ * How far ABOVE a control the host-tag window reaches, in lines.
+ *
+ * The text lane has no ancestry, so "inside a SettingsRow" is approximated by "a SettingsRow opens
+ * within the last N lines". 12 covers every row shape in the five consumer repos (label +
+ * description + the `control={` line); past that the window would start swallowing the next row's
+ * control, which is the direction that makes the kind silent rather than noisy. The plugin rule
+ * (`basalt/control-outside-home`) is the one that answers this exactly — this kind exists for the
+ * PreToolUse hook lane, which sees one file's TEXT and no AST at all.
+ */
+const CONTROL_HOST_WINDOW_LINES = 12
+
+/**
+ * A file whose BASENAME declares it is an overlay's or a form's own body — the cross-file half of
+ * {@link CONTROL_HOST_TAG}, and the same regex the plugin's `OVERLAY_CONVENTION_FILE` applies to
+ * `basalt/control-outside-home` (one law, two lanes, one exemption).
+ *
+ * Law C1's cross-file case is advisory by declaration (`docs/CONTROLS-SPEC.md` §6, "Honest
+ * coverage"), and this kind was paying for it: a `<Select>` inside `edit-session-modal.tsx` whose
+ * `<Modal>` is rendered by the parent route is outside BOTH the 12-line host window and any
+ * ancestry walk, because the host tag is not in the file at all. argo carried 9 of them.
+ *
+ * The trade is that a whole file goes unscanned on a naming convention — the same bargain
+ * {@link MANTINE_FORM_IMPORT} already buys, and a smaller one than promoting the kind with 9 known
+ * false positives. Basename only: a `modal/` DIRECTORY holds the page pieces around the modals too.
+ */
+const OVERLAY_CONVENTION_FILE = /(?:^|\/)[^/]*-(?:modal|drawer|popover|panel|form)\.[jt]sx$/
+
+/** A name whose DECLARATION means this file DEFINES a basalt control rather than consuming one. */
+const CONTROL_OWNER_DEF =
+  /\b(?:function|const|class)\s+(?:RangeFilter|CompareFilter|SelectFilter|MultiSelectFilter|NumberFilter|SearchFilter|ToggleFilter|ViewTabs|FilterSet|FilterPill|SyncButton|ActionGroup|OverflowMenu|CtlSlot)(?![\w])/
+
+/** `@mantine/form` — a form is C1's third home, and its inputs are not filters. */
+const MANTINE_FORM_IMPORT = /from\s+['"]@mantine\/form['"]/
+
 // A Mantine `styles={{ input: {...} }}` per-part style — the `input` key specifically targets the
 // rendered <input>/<textarea> part of TextInput/Select/Textarea/etc. Requires `input` be the FIRST
 // key in the styles object (see the sub-16-input-font doc comment for the scoping trade-off this
@@ -541,20 +603,32 @@ export const DEFAULT_GUARD_CONFIG: GuardConfig = {
   severity: {},
 }
 
+/**
+ * A grace-ledger entry: `since` and `promote` are plain `x.y.z` semver strings (C16,
+ * `docs/CONTROLS-SPEC.md` §1). `grace.test.ts` fails the build once `package.json`'s version
+ * reaches `promote` while the entry is still here — the version-gate that replaces the honor
+ * system a bare promotion-note string used to run on. `since` must be strictly before `promote`,
+ * also asserted there.
+ */
+export type GraceEntry = { since: string; promote: string; why: string }
+
 /**
  * Kinds still inside their grace minor — reported, not fatal, until the next minor promotes them.
  * See {@link GuardSeverity} for the doctrine and why basalt-ui in particular needs it.
  *
- * The value is the promotion note, so the entry carries its own expiry rather than relying on
- * someone remembering. Adding a kind here is part of shipping it; removing the entry IS the
- * promotion, and belongs in its own commit so the changelog says enforcement got stricter.
+ * Adding a kind here is part of shipping it; removing the entry IS the promotion, and belongs in
+ * its own commit so the changelog says enforcement got stricter. `grace.test.ts` is the other half
+ * of "belongs in its own commit": it fails once `package.json`'s version reaches an entry's
+ * `promote` while the entry is still here, so a kind can no longer sit at `warn` with nothing
+ * tracking it — which is exactly what happened to the five entries this ledger shipped in the
+ * round-4 guard minor (D4, `docs/CONTROLS-SPEC.md` §6): all five stayed `warn` for five minors
+ * because deleting the entry was the only enforcement, and nothing checked that anyone had.
  *
  * The runway is measured in consumer UPGRADES, not in version numbers: `mantine-shade-index`
  * (the table's first tenant, promoted and gone) sat here across two minors because 1.8.0 shipped
  * the same day as 1.7.0 and 1.9.0 carried the chart batch the same consumer was upgrading for —
  * bundling a build-breaking promotion into the minor they take for the fixes turns a routine bump
- * into an unplanned refactor, which is exactly what the grace minor exists to prevent. The five
- * entries below all landed together in the round-4 guard minor and all promote one minor later.
+ * into an unplanned refactor, which is exactly what the grace minor exists to prevent.
  *
  * **A `SCANNABLE_EXT` widening cannot be expressed here, and 1.23.2's was deliberately not.**
  * Adding `.astro`/`.jsx`/`.vue` widens the FILE SET for all 25 kinds at once — there is no kind to
@@ -572,29 +646,25 @@ export const DEFAULT_GUARD_CONFIG: GuardConfig = {
  * with `theme-allow`, `basalt.severity` and `exemptRules` all still available.
  *
  * @example
- * const GRACE: Partial<Record<GuardKind, string>> = {
- *   'raw-font-family': 'introduced 1.4.0 — promote to error in 1.5.0',
+ * const GRACE: Partial<Record<GuardKind, GraceEntry>> = {
+ *   'raw-font-family': { since: '1.4.0', promote: '1.5.0', why: 'introduced 1.4.0 — …' },
  * }
  */
-const GRACE_PERIOD_KINDS: Partial<Record<GuardKind, string>> = {
-  'theme-allow-unscoped':
-    'introduced in the round-4 guard minor — promote to error one minor later. Every consumer has ' +
-    'bare `theme-allow` comments today (basalt itself has ~20), and landing this as an error would ' +
-    'fail every one of their builds on an upgrade they took for the fixes.',
-  'surface-shadow-override':
-    'introduced in the round-4 guard minor — promote to error one minor later. Catches the shape a ' +
-    'TOKEN-FLUENT consumer writes, so the code it rejects is code that looks correct and passed ' +
-    'every previous release.',
-  'css-raw-surface':
-    'introduced in the round-4 guard minor — promote to error one minor later. The surface kinds ' +
-    'reaching CSS at all is the "existing kind, new file type" case the doctrine names explicitly.',
-  'inline-font-size':
-    'introduced in the round-4 guard minor — promote to error one minor later. The oxlint plugin ' +
-    'has enforced the same thing as `basalt/no-raw-font-size` for a while, so a consumer running ' +
-    'both sees nothing new; one running check-theme alone gets a minor of runway.',
-  'hidden-inline-style':
-    'introduced in the round-4 guard minor — promote by DELETING the kind and folding its two ' +
-    'scans into `raw-html-layout`, which is where they belong once the widening has had its minor.',
+export const GRACE_PERIOD_KINDS: Partial<Record<GuardKind, GraceEntry>> = {
+  'raw-selection-control': {
+    since: '1.26.0',
+    promote: '1.28.0',
+    why:
+      'new in the wave-6 control guards (docs/CONTROLS-SPEC.md §6, law C1). The text lane cannot ' +
+      'see ancestry, so "no home" is approximated by a 12-line host-tag window — the loosest ' +
+      'reading in the guard, and the reason this one lands warn rather than error even though its ' +
+      'law is settled. It moved from 1.27.0 to 1.28.0 with its AST twin, `basalt/control-outside-' +
+      'home`, whose PLUGIN_RULE_GRACE entry carries the measurement: the wave-7 run left 9 warns ' +
+      'in argo, all of them a control in a modal/form module whose `<Modal>` is rendered by the ' +
+      'PARENT — law C1 cross-file, which neither lane can see. `OVERLAY_CONVENTION_FILE` (this ' +
+      'file, and the same regex in the plugin) exempts that declared naming convention in both ' +
+      'lanes; 1.28.0 is when the remainder is re-measured. One law, two lanes, one promotion.',
+  },
 }
 
 /** A kind's effective severity: consumer override first, then the grace table, then `error`. */
@@ -762,6 +832,16 @@ export const PLUGIN_RULE_IDS: ReadonlySet<string> = new Set([
   'hand-rolled-shell',
   'shadow-basalt-export',
   'raw-scroll-container',
+  'hand-rolled-filter',
+  'control-outside-home',
+  'control-size-literal',
+  'page-bar-budget',
+  'responsive-twin',
+  'search-literal-link',
+  'use-search-from-literal',
+  // `in-body-page-title` is deliberately ABSENT: it is a plugin rule AND a guard kind under one id
+  // (one law, two lanes, one annotation), and this set is the ids OUTSIDE `checkSource`'s reach.
+  // `check-source.test.ts` asserts the two registries stay disjoint.
   'visx-boundary',
   'visx-tooltip',
   'token-layer-boundary',
@@ -1388,6 +1468,11 @@ export const TOKENS_ONLY_DISABLED_KINDS: ReadonlySet<GuardKind> = new Set([
   'chart-missing-aria-label',
   'raw-form-control',
   'sub-16-input-font',
+  // Both wave-6 control kinds: `<Title>` is a Mantine component and the remedy for either one is a
+  // Mantine-rendered home (PageBar / WidgetHeader) or a basalt control over @mantine/core. Neither
+  // sentence is followable in a consumer that installs the token layer and nothing else.
+  'in-body-page-title',
+  'raw-selection-control',
 ])
 
 // A `/` opens a regex literal (not division) when the previous significant token is one of these
@@ -1608,7 +1693,7 @@ type GuardRule = {
 }
 
 /**
- * The closed registry of all 25 guard kinds. The triad test asserts
+ * The closed registry of all 27 guard kinds. The triad test asserts
  * `surface.guardKinds ⊆ keyof GUARD_RULES` at runtime.
  *
  * raw-surface, raw-html-layout, and sub-16-input-font are handled inline in checkSource
@@ -1827,7 +1912,23 @@ export const GUARD_RULES = {
     enabled: (cfg: GuardConfig) => cfg.rawHtmlLayout,
     appliesTo: (relPath) => !isChartFile(relPath) && !relPath.endsWith('.css'),
     message:
-      'Raw HTML element with inline layout/surface styling that the line scan cannot see — the tag is formatted across lines, or the style object is hoisted to a const. Same violation as raw-html-layout: use a Mantine layout primitive (Box/Flex/Grid/Stack/Group). Its own kind for one minor so the widening lands as a warning; it merges into raw-html-layout at the promotion.',
+      'Raw HTML element with inline layout/surface styling that the line scan cannot see — the tag is formatted across lines, or the style object is hoisted to a const. Same violation as raw-html-layout: use a Mantine layout primitive (Box/Flex/Grid/Stack/Group). Promoted to error at 1.26.0 (C16) with severity only — the kind stayed standalone rather than folding into raw-html-layout as originally planned; the merge is still open, tracked as a follow-up, not done here.',
+  },
+  'in-body-page-title': {
+    kind: 'in-body-page-title',
+    pattern: PAGE_TITLE_TAG, // handled inline (full-text tag-scoped scan); entry keeps the registry complete
+    // JSX-tag-shaped (`<Title order={1}>`) — never appears in CSS text.
+    appliesTo: (relPath) => !relPath.endsWith('.css'),
+    message:
+      'In-body page title — a page is named ONCE, by the breadcrumb (staticData.title) or by PageBar.title in a shell-less app, and every section/card/table title is a WidgetHeader (docs/CONTROLS-SPEC.md law C8). An <Title order={1|2}> in the body is a second name for the same page, and it drifts. Prose / ArticleLayout / an overlay and anything under a content/ path are document headings and never report. Same law the oxlint plugin enforces as basalt/in-body-page-title — one id, two lanes, so one theme-allow covers both.',
+  },
+  'raw-selection-control': {
+    kind: 'raw-selection-control',
+    pattern: RAW_SELECTION_CONTROL_TAG, // handled inline (full-text tag-scoped scan + host window)
+    // JSX-tag-shaped (`<Select …>`) — never appears in CSS text.
+    appliesTo: (relPath) => !relPath.endsWith('.css'),
+    message:
+      'Raw selection control with no home — a filter or tab belongs in a PageBar / Section / WidgetHeader slot and takes a `field` (a FieldHandle), so it owns the URL write and the localStorage mirror instead of carrying value/onChange (docs/CONTROLS-SPEC.md laws C1–C3). Use the bound control from basalt-ui/controls. A settings row, an overlay and an @mantine/form file are the declared non-homes and never report. This is the TEXT lane of basalt/control-outside-home, which answers the same question against the real AST — where the two disagree, the plugin is right.',
   },
   'inline-font-size': {
     kind: 'inline-font-size',
@@ -2249,6 +2350,61 @@ export function checkSource(text: string, relPath: string, cfg: GuardConfig): Fi
     }
   }
 
+  // in-body-page-title — full-text tag scan (the card-with-border shape), because a `<Title>` with
+  // its props on separate lines is the formatted default. `order` is judged on the tag's own text.
+  //
+  // Two file-level exemptions, both deliberately coarser than the plugin's node-level ones and both
+  // false-NEGATIVE-only: anything under a `content/` path segment, and any file that renders
+  // `<Prose>` / `<ArticleLayout>` / an overlay anywhere in it. A text scan has no ancestry, so
+  // "under Prose" is not answerable per node — and a document heading told to become a breadcrumb is
+  // the wrong advice, not merely noise. `basalt/in-body-page-title` (the AST lane, same id) is the
+  // half that scopes this exactly.
+  if (
+    ruleApplies('in-body-page-title', relPath) &&
+    !relPath.split('/').includes('content') &&
+    !PROSE_CONTEXT_TAG.test(codeText)
+  ) {
+    for (const m of codeText.matchAll(PAGE_TITLE_TAG)) {
+      const order = PAGE_TITLE_ORDER_PROP.exec(m[0])
+      if (order === null) continue
+      const startLine = codeText.slice(0, m.index ?? 0).split('\n').length
+      const endLine = startLine + (m[0].split('\n').length - 1)
+      if (isAllowedInRange(startLine, endLine, 'in-body-page-title')) continue
+      findings.push({
+        relPath,
+        line: startLine,
+        token: `<Title order={${order[1]}}`,
+        kind: 'in-body-page-title',
+      })
+    }
+  }
+
+  // raw-selection-control — full-text tag scan plus the host WINDOW (see CONTROL_HOST_WINDOW_LINES).
+  // Three file-level exemptions mirror the plugin rule's, so the two lanes agree on the same file:
+  // a file that DEFINES a basalt control cannot be told to use one, a file importing
+  // `@mantine/form` is a form — C1's third home, whose inputs are not filters — and a file NAMED as
+  // an overlay body carries its `<Modal>` in the parent, where no scan of this file can reach it.
+  if (
+    ruleApplies('raw-selection-control', relPath) &&
+    !OVERLAY_CONVENTION_FILE.test(relPath) &&
+    !CONTROL_OWNER_DEF.test(codeText) &&
+    !MANTINE_FORM_IMPORT.test(codeText)
+  ) {
+    for (const m of codeText.matchAll(RAW_SELECTION_CONTROL_TAG)) {
+      const startLine = codeText.slice(0, m.index ?? 0).split('\n').length
+      const windowStart = Math.max(0, startLine - 1 - CONTROL_HOST_WINDOW_LINES)
+      if (CONTROL_HOST_TAG.test(codeLines.slice(windowStart, startLine).join('\n'))) continue
+      const endLine = startLine + (m[0].split('\n').length - 1)
+      if (isAllowedInRange(startLine, endLine, 'raw-selection-control')) continue
+      findings.push({
+        relPath,
+        line: startLine,
+        token: `<${m[1] ?? 'Select'}`,
+        kind: 'raw-selection-control',
+      })
+    }
+  }
+
   // sub-16-input-font — two full-text scans (same shape as the tag-scoped scans above): (a) a raw
   // form-control's own inline `style={{ fontSize: N }}`, (b) a Mantine `styles={{ input: { fontSize:
   // N } }}` per-part style. Either shape is now DEAD CODE against the `!important` floor in

package/src/guard/types.ts

@@ -1,12 +1,12 @@
 /**
  * Guard types — Mantine-free, dependency-free (zero imports beyond TS types).
  *
- * GuardKind is the closed set of 25 violation kinds the theme guard can emit.
+ * GuardKind is the closed set of 27 violation kinds the theme guard can emit.
  * Finding is the structured result per violation, replacing the old `Violation` shape.
  * GuardConfig is the per-run configuration that drives checkSource.
  */
 
-/** The 25 theme-guard violation kinds. */
+/** The 27 theme-guard violation kinds. */
 export type GuardKind =
   | 'raw-hex'
   | 'raw-color-fn'
@@ -33,6 +33,8 @@ export type GuardKind =
   | 'css-raw-surface'
   | 'inline-font-size'
   | 'hidden-inline-style'
+  | 'in-body-page-title'
+  | 'raw-selection-control'
 
 /**
  * How hard a finding lands. `error` fails the build; `warn` reports and passes.

package/src/index.ts

@@ -14,6 +14,14 @@ export {
 } from './provider'
 export { createBasaltTheme, baseTheme, cssVariablesResolver } from './theme'
 export type { BasaltFontsConfig, CreateBasaltThemeOptions } from './theme'
+export { CTL_THEME, CtlSlot } from './theme'
+export type { CtlSlotProps } from './theme'
+/**
+ * The action vocabulary every home's `actions` slot takes (`docs/CONTROLS-SPEC.md` §2.1). The
+ * COMPONENTS that project it (`ActionGroup`, `OverflowMenu`, `SyncButton`, and the filter family)
+ * live on `basalt-ui/controls` — only the types a `PageBar`/`BasaltShell` prop mentions are here.
+ */
+export type { BarAction, ActionGroupProps, GlobalAction } from './controls/actions'
 export { ThemeToggle, type ThemeToggleProps } from './theme-toggle'
 export { MOTION_DURATION, MOTION_SPRING, MOTION_EASE_STANDARD } from './motion'
 export {
@@ -22,6 +30,7 @@ export {
   AppSidebar,
   SidebarSearch,
   type SidebarSearchConfig,
+  type SidebarSearchActions,
   SidebarAccount,
   MobileNav,
   type MobileNavProps,
@@ -31,11 +40,16 @@ export {
   MOBILE_MENU_MAX_DEFAULT,
   MOBILE_MORE_KEY,
   AppBreadcrumbs,
-  PageHeaderProvider,
-  PageActions,
-  PageActionsOutlet,
+  PageBar,
+  type PageBarProps,
   type SidebarSection,
   type SidebarItem,
+  type SidebarBlock,
+  type SidebarBlockItem,
+  type SidebarBlockTone,
+  type SidebarListBlock,
+  type SidebarProgressBlock,
+  type SidebarCustomBlock,
   type NavAnchor,
   type NavAnchorProps,
   type NavMobilePlacement,
@@ -72,19 +86,51 @@ export {
   type StandardSchemaV1,
 } from './register'
 
-// ── Persisted state + online hook (state.ts) ─────────────────────────────────────────────────────
+// ── Persisted state + the headless store kernel (state.ts) ───────────────────────────────────────
+// The `field.*` VALUE is deliberately not re-exported here — `basalt-ui/forms` already owns the
+// name `field` on its own barrel. Import it from `basalt-ui/router-tanstack` (beside
+// `createSearchStore`) or from `basalt-ui/state` (beside `createLocalStore`).
 export {
   createPersistedState,
   type PersistedStateOptions,
-  useOnlineStatus,
   readPersistedValue,
+  createLocalStore,
+  type LocalStore,
+  type AnyField,
+  type BooleanField,
+  type EnumField,
+  type FieldFallback,
+  type FieldHandle,
+  type FieldLane,
+  type FieldOption,
+  type FieldSetOptions,
+  type FieldValue,
+  type MultiField,
+  type NumberField,
+  type RangeField,
+  type RangeParams,
+  type RangePresets,
+  type RangeValue,
+  type RangeWindow,
+  type RangeWindows,
+  type ResolvedLane,
+  type SearchValues,
+  type StoredValues,
+  type StringField,
 } from './state'
 
+// ── WidgetHeader (unified section/widget/card heading primitive, docs/CONTROLS-SPEC.md §2.2) ─────
+export { WidgetHeader, type WidgetHeaderProps } from './widget-header'
+
+// ── Section (tier-2 heading composer over WidgetHeader, docs/CONTROLS-SPEC.md §2.2) ───────────────
+export { Section, type SectionProps } from './section'
+
 // ── Dashboard composites (KPI atoms + settings building blocks) ──────────────────────────────────
 export {
   DeltaBadge,
   type DeltaBadgeProps,
   StatCard,
+  type StatCardBreakdownRow,
   type StatCardProps,
   type StatCardTone,
   EmptyState,

package/src/nav/types.ts

@@ -40,6 +40,8 @@ export type SidebarItem = {
   /** Plain href — the no-router fallback, and the breadcrumb parent target. */
   href?: string
   active?: boolean
+  /** A parent on the path to the active row. NOT active itself — never carries `aria-current`. */
+  ancestor?: boolean
   disabled?: boolean
   onClick?: (e: MouseEvent) => void
   /** Rich desktop badge (e.g. `NavCountBadge`). Desktop only. */
@@ -70,6 +72,88 @@ export type SidebarSection = {
   mobile?: false | NavSectionMobile
 }
 
+/**
+ * Status tone on a sidebar-block item — the same three-member vocabulary as `StatCardTone`, whose
+ * members are `VX.status` keys by construction. Declared here rather than imported from
+ * `../dashboard/stat-card`: this module is the one `./router-tanstack` reads, and even a
+ * type-only edge into the Mantine layer would make `nav/types.d.ts` unresolvable without
+ * `@mantine/core` installed.
+ */
+export type SidebarBlockTone = 'good' | 'warn' | 'bad'
+
+/** One row inside a `kind: 'list'` block. Same router seam as `SidebarItem` — `Anchor`, then href. */
+export type SidebarBlockItem = {
+  key: string
+  label: string
+  /** Trailing muted text (a timestamp, a count, an owner). */
+  meta?: string
+  icon?: ReactNode
+  /** Renders a status dot in place of a missing `icon`; reads `--vx-status-*`, never a hex. */
+  tone?: SidebarBlockTone
+  Anchor?: NavAnchor
+  href?: string
+  onClick?: () => void
+}
+
+/**
+ * A list of non-destination rows under a micro-label — "Awaiting action", "Recents", a project
+ * list. `count` is the header badge (and what earns a rail dot); `max` shows the first N with a
+ * "Show more" toggle past it.
+ */
+export type SidebarListBlock = {
+  kind: 'list'
+  key: string
+  label: string
+  icon?: ReactNode
+  count?: number
+  /** Rows shown before the "Show more" toggle. Omit to show every row. */
+  max?: number
+  items: SidebarBlockItem[]
+  /** @default 'nav' */
+  placement?: 'nav' | 'bottom'
+  collapsible?: boolean
+  /** Collapsed-rail projection. @default 'dot' when `count` is set, `'hidden'` otherwise */
+  rail?: 'dot' | 'hidden'
+  /** @default 'more' */
+  mobile?: 'more' | 'hidden'
+}
+
+/** A "Getting started 1 of 5" progress row. Pinned above the settings footer; never in the nav. */
+export type SidebarProgressBlock = {
+  kind: 'progress'
+  key: string
+  label: string
+  value: number
+  total: number
+  onClick?: () => void
+  /** @default 'bottom' — the only placement a progress row has. */
+  placement?: 'bottom'
+  /** Collapsed-rail projection: a ring on the settings row. @default 'ring' */
+  rail?: 'ring' | 'hidden'
+  /** @default 'hidden' */
+  mobile?: 'more' | 'hidden'
+}
+
+/**
+ * DESKTOP ONLY — arbitrary consumer content (a tree, a filter panel) that no set of rows can
+ * express. Replaced `BasaltShellProps.sidebarNavExtra`; hidden on the collapsed rail and absent
+ * from mobile for the same reason that prop was.
+ */
+export type SidebarCustomBlock = {
+  kind: 'custom'
+  key: string
+  node: ReactNode
+  /** @default 'nav' */
+  placement?: 'nav' | 'bottom'
+}
+
+/**
+ * A sidebar block — DECLARED DATA, never a `ReactNode` slot (law C13, `docs/CONTROLS-SPEC.md`
+ * §2.3), which is what lets basalt own the collapsed-rail badge and the mobile More-sheet
+ * projection instead of each consumer hand-rolling both.
+ */
+export type SidebarBlock = SidebarListBlock | SidebarProgressBlock | SidebarCustomBlock
+
 export type MobileNavSurface = 'link' | 'menu' | 'sheet'
 
 /** One row inside a `menu`/`sheet` slot, grouped under its source section. */
@@ -108,8 +192,6 @@ export type MobileNavConfig = {
   menuMax?: number
   /** @default 'More' */
   moreLabel?: string
-  /** Extra content pinned to the bottom of the More surface. */
-  moreExtra?: ReactNode
   /** Scroll container for active-slot re-tap. @default document.scrollingElement */
   getScrollElement?: () => HTMLElement | null
 }

package/src/notifications/bell.tsx

@@ -1,6 +1,6 @@
 /**
  * NotificationBell — ActionIcon + Indicator showing the unread Inbox count, opens a
- * NotificationCenter in a Popover. Designed for the shell `globalActions` slot (ReactNode).
+ * NotificationCenter in a Popover. Designed for the shell `globalActions` slot (`GlobalAction[]`).
  *
  * The badge counts unread Inbox items (errors / warnings / actionable notifications you haven't
  * seen) — not every toast that fired. Opening the bell does NOT mark anything read; items are
@@ -11,7 +11,7 @@
  *
  * // In the shell's globalActions prop:
  * <BasaltShell
- *   globalActions={<NotificationBell />}
+ *   globalActions={[{ key: 'notifications', node: <NotificationBell />, mobile: 'bar' }]}
  *   {...rest}
  * />
  */
@@ -33,7 +33,10 @@ export type NotificationBellProps = {
  * Bell icon button with an unread-Inbox indicator. Opens a NotificationCenter popover.
  *
  * @example
- * <BasaltShell globalActions={<NotificationBell />} {...rest} />
+ * <BasaltShell
+ *   globalActions={[{ key: 'notifications', node: <NotificationBell />, mobile: 'bar' }]}
+ *   {...rest}
+ * />
  */
 export function NotificationBell({ label = 'Notifications' }: NotificationBellProps) {
   const [opened, { open, toggle, close }] = useDisclosure(false)

package/src/notifications/index.ts

@@ -20,7 +20,7 @@
  * notifyPromise(save(), { loading: 'Saving…', success: 'Saved', error: 'Failed' })
  *
  * // Shell bell (globalActions slot):
- * <BasaltShell globalActions={<NotificationBell />} ... />
+ * <BasaltShell globalActions={[{ key: 'notifications', node: <NotificationBell />, mobile: 'bar' }]} ... />
  */
 
 // ── notify core ───────────────────────────────────────────────────────────────

package/src/router-tanstack/field.ts

@@ -0,0 +1,35 @@
+/**
+ * `field.*` — the field vocabulary `createSearchStore` takes, re-exported at the surface a consumer
+ * imports it from (`basalt-ui/router-tanstack`, beside the store factory).
+ *
+ * The builders and their codecs LIVE in `../state` on purpose: a field is declarative data with no
+ * router in it, and `createLocalStore` — the router-free lane, published on `basalt-ui/state` —
+ * has to build the same fields without pulling in `@tanstack/react-router`. One definition, two
+ * surfaces, no second description of the same param.
+ *
+ * Full field reference: the JSDoc on `field` itself, and `docs/CONTROLS-SPEC.md` §4.
+ */
+export { field } from '../state'
+export type {
+  AnyField,
+  BooleanField,
+  EnumField,
+  FieldFallback,
+  FieldHandle,
+  FieldLane,
+  FieldOption,
+  FieldSetOptions,
+  FieldValue,
+  MultiField,
+  NumberField,
+  RangeField,
+  RangeParams,
+  RangePresets,
+  RangeWindow,
+  RangeWindows,
+  RangeValue,
+  ResolvedLane,
+  SearchValues,
+  StoredValues,
+  StringField,
+} from '../state'

package/src/router-tanstack/index.ts

@@ -3,10 +3,36 @@
  * Optional peer: @tanstack/react-router.
  * Carries the typed navigation definition (`defineNav`/`navGroup`/`navTarget`/`flattenNav`) and
  * `useNav`, which resolves it into `BasaltShell`'s `sections` + `mobileNav` props; plus the
- * StaticDataRouteOption augmentation (title/icon/navSection) for router-derived breadcrumbs and
- * the search-param stores — no Mantine, no JSX.
+ * StaticDataRouteOption augmentation (title/icon/navSection) for router-derived breadcrumbs, plus
+ * `createSearchStore` + the `field.*` vocabulary (and the two deprecated enum-only wrappers it
+ * replaced) — no Mantine, no JSX.
  */
 
+export { createSearchStore, type CreateSearchStoreOptions, type SearchStore } from './search-store'
+export { field } from './field'
+export type {
+  AnyField,
+  BooleanField,
+  EnumField,
+  FieldFallback,
+  FieldHandle,
+  FieldLane,
+  FieldOption,
+  FieldSetOptions,
+  FieldValue,
+  MultiField,
+  NumberField,
+  RangeField,
+  RangeParams,
+  RangePresets,
+  RangeValue,
+  RangeWindow,
+  RangeWindows,
+  ResolvedLane,
+  SearchValues,
+  StoredValues,
+  StringField,
+} from './field'
 export {
   createSearchParamStore,
   type SearchParamStore,