basalt-ui 1.27.0 → 1.29.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 27 violation kinds.
+ * GUARD_RULES: the closed registry of all 26 violation kinds.
  * checkSource:  pure (text, relPath, cfg) → Finding[]. No FS, no walk, no console.
  */
 import type { Finding, GuardConfig, GuardKind, GuardSeverity } from './types'
@@ -160,8 +160,9 @@ const INLINE_FONT_SIZE =
 // Two deliberate non-matches:
 //   • `<Card.Section withBorder>` — a section DIVIDER, not card depth. Excluded by the `(?![\w.])`
 //     lookahead, which also rejects `<CardHeader>`-style names.
-//   • `withBorder={false}` — an explicit opt-out (what the shell's AppShell parts do). Excluded by
-//     the lookahead on WITH_BORDER_PROP.
+//   • `withBorder={false}` — a consumer opt-out; the shell no longer uses it (region edges are
+//     painted by the theme's `AppShell.extend`, not by a prop). Excluded by the lookahead on
+//     WITH_BORDER_PROP.
 const CARD_SURFACE_TAG = /<(?:Card|Paper)(?![\w.])(?:=>|[^>])*?>/g
 const WITH_BORDER_PROP = /\bwithBorder\b(?!\s*=\s*\{\s*false\s*\})/
 
@@ -408,31 +409,23 @@ const MOTION_TRANSITION_NUMERIC =
   /\btransition\s*=\s*\{\{[^}]*\b(?:duration|stiffness|damping|mass)\s*:\s*-?\d/g
 const MOTION_TRANSITION_EASE_ARRAY = /\btransition\s*=\s*\{\{[^}]*\bease\s*:\s*\[/g
 
-// A hand-rolled <ChartLegend items={[ …array literal… ]}> — legend entries authored inline
-// instead of derived (`items={deriveLegend(series)}`, a call expression, which must NOT match).
-// Scoped to the JSX tag itself ([^>]* is bounded by the tag's own closing `>`, which also makes
-// this a full-text scan rather than the per-line style every other kind uses — a multi-line-
-// formatted <ChartLegend ...\n  items={[...\n/> still resolves to one match). Bounded scans over
-// text this small are not a performance concern.
-const RAW_CHART_LEGEND_ARRAY = /<ChartLegend\b[^>]*?\bitems\s*=\s*\{\s*\[/g
-
 // A chart entry-point JSX tag (the 7 kinds + 2 sparklines) — full opening/self-closing tag,
 // scanned for a missing `ariaLabel` prop (an accessible text alternative for the SVG graphic).
-// Bounded, full-text scan (like RAW_CHART_LEGEND_ARRAY above) so a multi-line-formatted tag still
-// resolves to one match. The scan must survive two `>` decoys inside an opening tag: an explicit
-// JSX generic argument (`<MultiLine<Point>`) — consumed by the optional `<[^<>]*>` group — and
-// arrow functions in prop expressions (`getX={(d) => d.date}`) — consumed atomically by the `=>`
-// alternative so their `>` never terminates the tag early. A bare `>` comparison inside a prop
-// expression still ends the match (accepted limitation of the bounded scan).
+// Bounded, full-text scan so a multi-line-formatted tag still resolves to one match. The scan must
+// survive two `>` decoys inside an opening tag: an explicit JSX generic argument
+// (`<MultiLine<Point>`) — consumed by the optional `<[^<>]*>` group — and arrow functions in prop
+// expressions (`getX={(d) => d.date}`) — consumed atomically by the `=>` alternative so their `>`
+// never terminates the tag early. A bare `>` comparison inside a prop expression still ends the
+// match (accepted limitation of the bounded scan).
 const CHART_ENTRY_POINT_TAG =
   /<(MultiLine|Bars|BandStrip|Donut|DualPanel|Heatmap|MirroredBars|ZonedLine|StackedArea|LineSparkline|BarSparkline)\b(?:<[^<>]*>)?(?:=>|[^>])*?>/g
 const HAS_ARIA_LABEL_PROP = /\bariaLabel\s*=/
 
-// ── Tag provenance, shared by the two chart tag rules ────────────────────────────────────────────
+// ── Tag provenance, shared by chart-missing-aria-label ────────────────────────────────────────────
 //
-// Both `chart-missing-aria-label` and `unframed-chart` key on a JSX tag NAME, which is the whole of
-// their signal — so a consumer's OWN component that merely shares a shipped kind's name collected
-// the finding too. Reported by a consumer on 1.23.0: a hand-composed local `<MirroredBars>` was
+// `chart-missing-aria-label` keys on a JSX tag NAME, which is the whole of its signal — so a
+// consumer's OWN component that merely shares a shipped kind's name collected the finding too.
+// Reported by a consumer on 1.23.0: a hand-composed local `<MirroredBars>` was
 // told to pass an `ariaLabel` prop it does not accept, by a rule that presents as a correctness
 // finding rather than as a naming one. `shadow-basalt-export` / `ai-sdk-major` scope through
 // `isBasaltScopedFile` (package-level); the analogous file-level signal here is where the name in
@@ -506,9 +499,19 @@ const RAW_SELECTION_CONTROL_TAG =
  */
 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. */
+/**
+ * An opening tag for one of the declared non-homes — a settings row, an overlay, a composer — or
+ * for one of the basalt SUBTREE homes, where the children ARE the home (`FilterSet` / `PageAside` /
+ * `PanelRow`, `docs/ASIDE-SPEC.md` §3). The text lane cannot ask which of the two a tag is, and it
+ * does not need to: both mean "a raw control here is not homeless".
+ *
+ * The three subtree homes are the plugin's `BASALT_HOST_TAGS`, mirrored here so one law does not
+ * read differently in the two lanes. The plugin gates them on the tag's basalt IMPORT; a 12-line
+ * regex window has no import graph, so this lane matches by name and accepts the missed warn on a
+ * consumer's own `PanelRow` — the same direction every approximation in this scan already leans.
+ */
 const CONTROL_HOST_TAG =
-  /<(?:SettingsRow|Modal|Drawer|Popover\.Dropdown|Menu\.Dropdown|Composer)(?![\w])/
+  /<(?:SettingsRow|Modal|Drawer|Popover\.Dropdown|Menu\.Dropdown|Composer|FilterSet|PageAside|PanelRow)(?![\w])/
 
 /**
  * How far ABOVE a control the host-tag window reaches, in lines.
@@ -524,23 +527,50 @@ 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).
+ * {@link CONTROL_HOST_TAG}, and the same two dialects the plugin's `isOverlayConventionFile`
+ * applies to `basalt/control-outside-home` and `basalt/bound-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.
  *
+ * KEBAB and PascalCase both count, because a repo picks one file-naming law and the convention has
+ * to survive either: `edit-session-modal.tsx`, and `CbbiPanel.tsx` in a repo mandating
+ * `PascalCase.tsx` for component files (basalt's own root `CLAUDE.md` included). Each needs the
+ * leading SUBJECT — a bare `modal.tsx` / `Panel.tsx` is a page module, not the convention.
+ *
  * 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$/
+const OVERLAY_CONVENTION_KEBAB = /^[^/]*-(?:modal|drawer|popover|panel|form)\.[jt]sx$/
+const OVERLAY_CONVENTION_PASCAL = /^[A-Z]\w*(?:Modal|Drawer|Popover|Panel|Form)\.[jt]sx$/
+
+/** Does `relPath`'s BASENAME declare the overlay convention, in either dialect? */
+function isOverlayConventionFile(relPath: string): boolean {
+  const basename = relPath.slice(relPath.lastIndexOf('/') + 1)
+  return OVERLAY_CONVENTION_KEBAB.test(basename) || OVERLAY_CONVENTION_PASCAL.test(basename)
+}
 
-/** A name whose DECLARATION means this file DEFINES a basalt control rather than consuming one. */
+/**
+ * A name whose DECLARATION means this file DEFINES a basalt control rather than consuming one.
+ *
+ * Paired with {@link BASALT_ANY_IMPORT}, and the pair is the exemption — see the plugin's
+ * `CONTROL_OWNER_NAMES` for the whole reasoning: `PanelRow`, `EnumFilter` and `SliderControl` are
+ * names a consumer writes for their own helpers, so a bare-name match let one local
+ * `function PanelRow(…)` switch this kind off for the whole file.
+ */
 const CONTROL_OWNER_DEF =
-  /\b(?:function|const|class)\s+(?:RangeFilter|CompareFilter|SelectFilter|MultiSelectFilter|NumberFilter|SearchFilter|ToggleFilter|ViewTabs|FilterSet|FilterPill|SyncButton|ActionGroup|OverflowMenu|CtlSlot)(?![\w])/
+  /\b(?:function|const|class)\s+(?:RangeFilter|CompareFilter|SelectFilter|MultiSelectFilter|NumberFilter|SearchFilter|ToggleFilter|ViewTabs|FilterSet|FilterPill|EnumFilter|PanelRow|SliderControl|SyncButton|ActionGroup|OverflowMenu|CtlSlot)(?![\w])/
+
+/**
+ * ANY import from `basalt-ui` or one of its subpaths — named, default, namespace or side-effect.
+ * A file that CONSUMES basalt is not the module that DEFINES its controls, whatever it names its
+ * own helpers; basalt's own control sources import each other relatively and never by package name.
+ */
+const BASALT_ANY_IMPORT = /\b(?:from|import)\s+['"]basalt-ui(?:\/[^'"]*)?['"]/
 
 /** `@mantine/form` — a form is C1's third home, and its inputs are not filters. */
 const MANTINE_FORM_IMPORT = /from\s+['"]@mantine\/form['"]/
@@ -594,7 +624,6 @@ export const DEFAULT_GUARD_CONFIG: GuardConfig = {
   inlineDisplay: true,
   rawVisxAxis: true,
   rawMotionValue: true,
-  unframedChart: true,
   chartMissingAriaLabel: true,
   rawFormControl: true,
   sub16InputFont: true,
@@ -653,17 +682,19 @@ export type GraceEntry = { since: string; promote: string; why: string }
 export const GRACE_PERIOD_KINDS: Partial<Record<GuardKind, GraceEntry>> = {
   'raw-selection-control': {
     since: '1.26.0',
-    promote: '1.28.0',
+    promote: '1.30.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-' +
+      'law is settled. It moved from 1.27.0 to 1.30.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 ' +
+      'PARENT — law C1 cross-file, which neither lane can see. `isOverlayConventionFile` (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.',
+      'lanes. Re-dated 2026-08-28 — the argo wave-7 migration has not run; the PascalCase overlay ' +
+      'convention (this change) is expected to clear most of the 9. 1.30.0 is when the remainder ' +
+      'is re-measured. One law, two lanes, one promotion.',
   },
 }
 
@@ -834,22 +865,45 @@ export const PLUGIN_RULE_IDS: ReadonlySet<string> = new Set([
   'raw-scroll-container',
   'hand-rolled-filter',
   'control-outside-home',
+  // No text-lane twin, by design: a bound control's NAME says nothing without the import graph
+  // and the ancestry, which a 12-line regex window has neither of. See the rule's own JSDoc.
+  'bound-control-outside-home',
   'control-size-literal',
   'page-bar-budget',
   'responsive-twin',
   'search-literal-link',
   'use-search-from-literal',
+  // The three remaining F5 rules and the B4 deprecation rule — all AST-only, all outside
+  // `checkSource`'s reach: provenance here is an import graph and a JSX ancestry, neither of which
+  // a 12-line regex window has. Same reason `bound-control-outside-home` has no text-lane twin.
+  'provider-above-router',
+  'query-dual-import',
+  'query-fn-unwrap',
+  'deprecated-export',
+  // Same lane: `{...inputProps(…)}` without a sibling `key` is a JSX-ancestry claim (does this
+  // ELEMENT carry a `key` attribute?) over an import-resolved callee — neither is text.
+  'forms-field-key',
   // `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',
+  'no-import-meta-env',
   // These three honour `basalt-agent-allow`, never `theme-allow` — but they are still REAL ids, so
   // a `theme-allow ai-sdk-major` must parse as a (useless) scoped annotation rather than as prose.
   'agent-resume-guard',
   'agent-no-raw-usechat',
   'ai-sdk-major',
+  // Retired guard kinds — `unframed-chart`'s only case (`<ChartLegend items={[...]}>`) is fully
+  // subsumed by `basalt/chart-legend-literal`. Kept here (mirrored by the plugin's own
+  // `RETIRED_RULE_IDS`) so an existing `theme-allow unframed-chart` reads as a dead waiver via
+  // `--audit-allows`, never as an unknown-id typo.
+  'unframed-chart',
+  // Retired plugin rule — `<BasaltNotifications />` mounted beside `<BasaltOverlays
+  // notifications>` is unreachable now that `BasaltNotifications` no longer exists as a
+  // standalone export. Mirrored by the plugin's own `RETIRED_RULE_IDS`.
+  'duplicate-notifications-mount',
 ])
 
 /** The shortest string accepted as a written reason — enough to exclude a stray separator. */
@@ -1464,7 +1518,6 @@ export const TOKENS_ONLY_DISABLED_KINDS: ReadonlySet<GuardKind> = new Set([
   'inline-display',
   'raw-visx-axis',
   'raw-motion-value',
-  'unframed-chart',
   'chart-missing-aria-label',
   'raw-form-control',
   'sub-16-input-font',
@@ -1693,7 +1746,7 @@ type GuardRule = {
 }
 
 /**
- * The closed registry of all 27 guard kinds. The triad test asserts
+ * The closed registry of all 26 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
@@ -1846,15 +1899,6 @@ export const GUARD_RULES = {
     message:
       'Route animation timing through MOTION_DURATION / MOTION_SPRING / MOTION_EASE_STANDARD (basalt-ui motion tokens) instead of a hardcoded duration/spring/ease.',
   },
-  'unframed-chart': {
-    kind: 'unframed-chart',
-    pattern: RAW_CHART_LEGEND_ARRAY, // handled inline (full-text tag-scoped scan); entry keeps registry complete
-    enabled: (cfg: GuardConfig) => cfg.unframedChart,
-    // JSX-tag-shaped (`<ChartLegend items={[…]}>`) — never appears in CSS text.
-    appliesTo: (relPath) => !relPath.endsWith('.css'),
-    message:
-      'Hand-rolled ChartLegend built from an inline array literal — pass a derived legend (deriveLegend(series)), or compose ChartFrame, which derives it for you.',
-  },
   'chart-missing-aria-label': {
     kind: 'chart-missing-aria-label',
     pattern: CHART_ENTRY_POINT_TAG, // handled inline (full-text tag-scoped scan); entry keeps registry complete
@@ -2288,32 +2332,16 @@ export function checkSource(text: string, relPath: string, cfg: GuardConfig): Fi
     }
   }
 
-  // Both chart tag rules below gate on tag PROVENANCE (see the block above LOCAL_COMPONENT_DEF).
-  // Computed once, and only if one of the two actually runs.
-  const unframedChartRuns =
-    GUARD_RULES['unframed-chart'].enabled!(cfg) && ruleApplies('unframed-chart', relPath)
+  // The aria-label tag rule below gates on tag PROVENANCE (see the block above LOCAL_COMPONENT_DEF).
+  // Computed once, and only if the rule actually runs.
   const ariaLabelRuns =
     GUARD_RULES['chart-missing-aria-label'].enabled!(cfg) &&
     ruleApplies('chart-missing-aria-label', relPath)
-  const localNames =
-    unframedChartRuns || ariaLabelRuns ? localComponentNames(codeText) : new Set<string>()
-  const basaltNames =
-    unframedChartRuns || ariaLabelRuns ? basaltImportedNames(codeText) : new Set<string>()
+  const localNames = ariaLabelRuns ? localComponentNames(codeText) : new Set<string>()
+  const basaltNames = ariaLabelRuns ? basaltImportedNames(codeText) : new Set<string>()
   const isShippedTag = (tag: string): boolean => basaltNames.has(tag) || !localNames.has(tag)
 
-  // unframed-chart — full-text tag-scoped scan (not per-line, see RAW_CHART_LEGEND_ARRAY comment).
-  // Scans `codeText` (comment-stripped) so a legend example inside a comment can't match; reports
-  // at the line of the `items={[` token itself. Skipped wholesale when `ChartLegend` is this file's
-  // OWN component: a consumer's legend taking an `items` array is not the shipped one that derives
-  // its entries, and the remedy ("pass deriveLegend(series)") is unreachable there.
-  if (unframedChartRuns && isShippedTag('ChartLegend')) {
-    for (const m of codeText.matchAll(RAW_CHART_LEGEND_ARRAY)) {
-      const lineNo = codeText.slice(0, (m.index ?? 0) + m[0].length).split('\n').length
-      push('unframed-chart', lineNo, 'items={[')
-    }
-  }
-
-  // chart-missing-aria-label — full-text tag-scoped scan (same shape as unframed-chart above).
+  // chart-missing-aria-label — full-text tag-scoped scan.
   // A tag is a violation only when its own (possibly multi-line) prop list has no `ariaLabel=`.
   // Reports at the tag's OPENING line, like card-with-border below and unlike the end-of-match
   // arithmetic this used to do: on a multi-line-formatted chart the end lands on the closing `/>`,
@@ -2381,13 +2409,14 @@ export function checkSource(text: string, relPath: string, cfg: GuardConfig): Fi
 
   // 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.
+  // a file that DEFINES a basalt control (and imports none — see CONTROL_OWNER_DEF) 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) &&
+    !isOverlayConventionFile(relPath) &&
+    !(CONTROL_OWNER_DEF.test(codeText) && !BASALT_ANY_IMPORT.test(codeText)) &&
     !MANTINE_FORM_IMPORT.test(codeText)
   ) {
     for (const m of codeText.matchAll(RAW_SELECTION_CONTROL_TAG)) {

package/src/guard/types.ts

@@ -1,12 +1,17 @@
 /**
  * Guard types — Mantine-free, dependency-free (zero imports beyond TS types).
  *
- * GuardKind is the closed set of 27 violation kinds the theme guard can emit.
+ * GuardKind is the closed set of 26 violation kinds the theme guard can emit — `unframed-chart`
+ * retired at the C2 consolidation wave: its only case (a hand-authored `<ChartLegend items={[...]}>`
+ * array literal) is fully subsumed by the oxlint plugin's `basalt/chart-legend-literal`, which also
+ * catches the `.map()`-over-a-non-series form the regex never could. `'unframed-chart'` stays a
+ * recognized id in `PLUGIN_RULE_IDS`/`KNOWN_RULE_IDS` so an existing `theme-allow unframed-chart`
+ * reads as a dead waiver, not a typo.
  * Finding is the structured result per violation, replacing the old `Violation` shape.
  * GuardConfig is the per-run configuration that drives checkSource.
  */
 
-/** The 27 theme-guard violation kinds. */
+/** The 26 theme-guard violation kinds. */
 export type GuardKind =
   | 'raw-hex'
   | 'raw-color-fn'
@@ -23,7 +28,6 @@ export type GuardKind =
   | 'inline-display'
   | 'raw-visx-axis'
   | 'raw-motion-value'
-  | 'unframed-chart'
   | 'chart-missing-aria-label'
   | 'raw-form-control'
   | 'sub-16-input-font'
@@ -127,13 +131,6 @@ export type GuardConfig = {
   readonly rawVisxAxis: boolean
   /** Flag a hardcoded duration/spring/ease literal in a `transition={{...}}` prop. Default true. */
   readonly rawMotionValue: boolean
-  /**
-   * Flag a hand-rolled `<ChartLegend items={[...]}>` array literal — legend entries must be
-   * derived (e.g. `items={deriveLegend(series)}`), never authored inline, so a bespoke chart
-   * can't silently drift from the shared legend. Default `true` (ON). Set `false` to disable the
-   * `unframed-chart` check.
-   */
-  readonly unframedChart: boolean
   /**
    * Flag a chart-kind JSX usage (`<MultiLine>`, `<Bars>`, `<Donut>`, `<DualPanel>`, `<Heatmap>`,
    * `<ZonedLine>`, `<StackedArea>`, `<LineSparkline>`, `<BarSparkline>`) missing an `ariaLabel`

package/src/index.ts

@@ -10,25 +10,54 @@ export {
   BasaltProvider,
   type BasaltProviderProps,
   BasaltErrorBoundary,
+  type BasaltErrorBoundaryProps,
   type BasaltErrorContext,
 } from './provider'
+// -- Common primitives (src/common) ------------------------------------------------------------
+// Not a subpath of its own: `BasaltProps` is the base every component's props extend, so it belongs
+// on the entry a consumer already imports. The module is Mantine-free (`common/boundary.test.ts`),
+// which is what lets `./charts` reach `cx` without breaching the layer boundary.
+// The validate/errors internals (`useValidateProps`/`assertRequiredProps`/`requiredProp`/`oneOf`/
+// `deprecatedProp`/`duplicateMount`/`missingLayer`/`BASALT_PREFIX`) and the ref helpers
+// (`assignRef`/`mergeRefs`) are basalt's own diagnostic vocabulary, not a consumer's — no consumer
+// imports them, so they stay internal (C1 consolidation).
+export {
+  type BasaltProps,
+  type SlotClassNames,
+  type SlotStylesProps,
+  type Tone,
+  type ToneWithNeutral,
+  type Tier,
+  cx,
+  scrollParentOf,
+  SCROLLPORT_ATTRIBUTE,
+} from './common'
+
 export { createBasaltTheme, baseTheme, cssVariablesResolver } from './theme'
 export type { BasaltFontsConfig, CreateBasaltThemeOptions } from './theme'
 export { CTL_THEME, CtlSlot } from './theme'
 export type { CtlSlotProps } from './theme'
+export { ThemeToggle, type ThemeToggleProps } from './theme/theme-toggle'
 /**
  * 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.
+ * OTHER components that project it (`OverflowMenu`, `SyncButton`, and the filter family) live on
+ * `basalt-ui/controls`; `ActionGroup` is re-exported here alongside its own types so a typed
+ * `PageBar`/`BasaltShell` `actions` wrapper needs only this one subpath.
  */
-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 {
+  ActionGroup,
+  type BarAction,
+  type ActionGroupProps,
+  type GlobalAction,
+} from './controls/actions'
+export { MOTION_DURATION, MOTION_SPRING, MOTION_EASE_STANDARD } from './common/motion'
 export {
   BasaltShell,
   NavCountBadge,
+  type NavCountBadgeProps,
   AppSidebar,
   SidebarSearch,
+  type SidebarSearchProps,
   type SidebarSearchConfig,
   type SidebarSearchActions,
   SidebarAccount,
@@ -40,8 +69,18 @@ export {
   MOBILE_MENU_MAX_DEFAULT,
   MOBILE_MORE_KEY,
   AppBreadcrumbs,
+  type AppBreadcrumbsProps,
   PageBar,
   type PageBarProps,
+  type PageBarSlot,
+  PageAside,
+  type PageAsideProps,
+  type PageAsideSlot,
+  useBreakpoint,
+  type BreakpointName,
+  PageTitle,
+  type PageTitleProps,
+  type PageTitleSlot,
   type SidebarSection,
   type SidebarItem,
   type SidebarBlock,
@@ -87,9 +126,11 @@ export {
 } from './register'
 
 // ── 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`).
+// The `field.*` VALUE is deliberately not re-exported here. `basalt-ui/forms` used to own the
+// name `field` too and collide with this one; that forms helper is `inputProps` now (the
+// `@deprecated field` alias was removed in 1.29.0, C1 consolidation — see MIGRATING.md). Import
+// `field.*` from `basalt-ui/router-tanstack` (beside `createSearchStore`) or from `basalt-ui/state`
+// (beside `createLocalStore`).
 export {
   createPersistedState,
   type PersistedStateOptions,
@@ -114,37 +155,56 @@ export {
   type RangeWindow,
   type RangeWindows,
   type ResolvedLane,
+  type ResolveLane,
   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) ──────────────────────────────────
+// ── Dashboard composites (WidgetHeader/Section heading family + KPI atoms + settings building
+// blocks, docs/CONTROLS-SPEC.md §2.2) ──────────────────────────────────────────────────────────────
 export {
+  WidgetHeader,
+  type WidgetHeaderDeltaProps,
+  type WidgetHeaderMetricProps,
+  type WidgetHeaderProps,
+  type WidgetHeaderSlot,
+  type WidgetHeaderTier,
+  type WidgetHeaderTitleProps,
   DeltaBadge,
   type DeltaBadgeProps,
+  type DeltaPolarity,
+  Section,
+  type SectionProps,
+  type SectionSlot,
   StatCard,
   type StatCardBreakdownRow,
   type StatCardProps,
+  type StatCardSlot,
   type StatCardTone,
+  WidgetGrid,
+  type WidgetGridCols,
+  type WidgetGridItemProps,
+  type WidgetGridProps,
+  StatGroup,
+  type StatGroupCols,
+  type StatGroupProps,
   EmptyState,
   type EmptyStateProps,
+  type EmptyStateSlot,
   SettingsSection,
   type SettingsSectionProps,
+  type SettingsSectionSlot,
   SettingsRow,
   type SettingsRowProps,
+  type SettingsRowSlot,
   DangerZone,
   type DangerZoneProps,
   QueryState,
   type QueryStateProps,
   type QueryStateLike,
-  type QueryStateVariant,
+  type QueryStateSlot,
+  type QueryStateTier,
   type QueryEmptyCopy,
   LoadingState,
   type LoadingStateProps,
@@ -152,14 +212,26 @@ export {
   type ErrorStateProps,
 } from './dashboard'
 
-// ── Connectivity (auto-mounted by BasaltProvider) ────────────────────────────────────────────────
-export { ConnectivityProvider, ConnectivityIndicator, useConnectivity } from './connectivity'
+// ── Connectivity (auto-mounted by BasaltProvider, merged into ./provider — dropped ./connectivity
+// subpath) ──────────────────────────────────────────────────────────────────────────────────────
+export { ConnectivityProvider } from './provider/connectivity-provider'
+export { ConnectivityIndicator } from './provider/connectivity-indicator'
+export { useConnectivity } from './provider/use-connectivity'
 export type {
   ConnectivityStatus,
   ConnectivitySnapshot,
   ConnectivityProviderProps,
   ConnectivityOverride,
-} from './connectivity'
+} from './provider/connectivity-types'
+export type { ConnectivityIndicatorProps } from './provider/connectivity-indicator'
+
+// ── Query (createBasaltQueryClient, unwrap, lazy devtools — dropped ./query subpath) ──────────────
+export { createBasaltQueryClient, unwrap } from './query-client'
+export { BasaltQueryDevtools } from './query-devtools'
+export { toErrorMessage, errorStatus } from './common/errors'
+
+// ── BasaltDevDock (C5 consolidation) ────────────────────────────────────────────────────────────
+export { BasaltDevDock, type BasaltDevDockProps, type BasaltDevDockTool } from './dev-dock'
 
 // ── Type-only re-exports for compile fixtures (H.4) ──────────────────────────────────────────────
 // SurfaceSpec/RuleName/SkillName: the value SURFACES stays internal; types only for surfaces-broken
@@ -200,6 +272,7 @@ export type {
   MessageAffordances,
   VirtualizeOptions,
   VirtualizeProps,
+  RowHeightProps,
   ToolChipProps,
 } from './agent-chat'
 export {

package/src/notifications/bell.tsx

@@ -18,13 +18,14 @@
 import { ActionIcon, Indicator, Popover } from '@mantine/core'
 import { useDisclosure } from '@mantine/hooks'
 import { useRef } from 'react'
+import type { BasaltProps } from '../common/props'
 import { useNotificationHistory } from './store'
-import { NotificationCenter } from './center'
+import { NOTIFICATION_POPOVER_WIDTH, NotificationCenter } from './center'
 
 const HOVER_OPEN_DELAY = 150
 const HOVER_CLOSE_DELAY = 200
 
-export type NotificationBellProps = {
+export type NotificationBellProps = BasaltProps & {
   /** Tooltip label. Default: 'Notifications'. */
   label?: string
 }
@@ -38,7 +39,11 @@ export type NotificationBellProps = {
  *   {...rest}
  * />
  */
-export function NotificationBell({ label = 'Notifications' }: NotificationBellProps) {
+export function NotificationBell({
+  label = 'Notifications',
+  className,
+  style,
+}: NotificationBellProps) {
   const [opened, { open, toggle, close }] = useDisclosure(false)
   const { unreadCount } = useNotificationHistory()
   const timer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined)
@@ -53,7 +58,14 @@ export function NotificationBell({ label = 'Notifications' }: NotificationBellPr
   }
 
   return (
-    <Popover opened={opened} onClose={close} position="bottom-end" withArrow withinPortal>
+    <Popover
+      opened={opened}
+      onClose={close}
+      position="bottom-end"
+      width={NOTIFICATION_POPOVER_WIDTH}
+      withArrow
+      withinPortal
+    >
       <Popover.Target>
         <Indicator
           color="color-mix(in srgb, var(--vx-ink) 8%, transparent)"
@@ -78,6 +90,8 @@ export function NotificationBell({ label = 'Notifications' }: NotificationBellPr
             aria-label={label}
             aria-expanded={opened}
             aria-haspopup="dialog"
+            {...(className !== undefined && { className })}
+            {...(style !== undefined && { style })}
           >
             {/* Bell icon (simple SVG — no @tabler/icons dep per house rules) */}
             <svg