basalt-ui 1.25.0 → 1.27.0

package/dist/widget-header/widget-header.module.css

@@ -0,0 +1,350 @@
+/*
+ * WidgetHeader — the one heading primitive behind every section/card/table title
+ * (docs/CONTROLS-SPEC.md §2.2). Plain elements only — no `@mantine/*` anywhere in this folder —
+ * so `ChartCard` (inside the `charts/` boundary) can compose it without tripping
+ * `basalt/token-layer-boundary` / `check-dist-layering.mjs`.
+ *
+ * `--vx-space-section-header-height` / `--vx-space-widget-header-height` / `--vx-space-control-gap`
+ * are density-tracking anchors landing alongside this wave (docs/CONTROLS-SPEC.md §5) — referenced
+ * by name with rem fallbacks at their level-0 px value (36/28/6), same idiom as ChartCard's
+ * `--mantine-spacing-*` fallbacks.
+ *
+ * Layout: the title row holds title/icon/info/count/actions only. `value` + `delta` render on
+ * their own hero-metric row directly beneath it — for BOTH tiers, never inline with the title.
+ */
+
+.root {
+  display: flex;
+  flex-direction: column;
+}
+
+.titleRow {
+  display: flex;
+  align-items: center;
+  gap: var(--vx-space-control-gap, 0.375rem);
+}
+
+/*
+ * Below `sm` the title row WRAPS, which is the safety net for an `actions` slot too wide to sit
+ * beside the title. `flex-wrap` is the right tool precisely because it is conditional: a 30px kebab
+ * fits and stays on the row, while a control whose hypothetical size does not fit takes its own line
+ * instead of squeezing the heading to an ellipsis. No breakpoint arithmetic, no max-width fraction,
+ * and no prop — the row measures the actual content.
+ *
+ * `row-gap` is the 8px rhythm step, so a wrapped slot reads as the line under the title rather than
+ * as a second header. `.actions` keeps its `margin-inline-start: auto`, which on a wrapped line makes
+ * it right-aligned — the same edge it holds when it is on the row.
+ */
+@media (max-width: 47.99375em) {
+  .titleRow {
+    flex-wrap: wrap;
+    row-gap: var(--vx-space-stack-sm);
+  }
+}
+
+.root[data-tier='section'] .titleRow {
+  min-height: var(--vx-space-section-header-height, 2.25rem);
+}
+
+.root[data-tier='widget'] .titleRow {
+  min-height: var(--vx-space-widget-header-height, 1.75rem);
+}
+
+/*
+ * Section → h2, widget → h3, and the two tiers now read DIFFERENTLY on purpose — they did not, and
+ * that is what flattened the page.
+ *
+ * A `section` heading names a region of the page: 15px, weight 600, INK. A `widget` heading labels a
+ * number that is itself the thing being read (a KPI card's hero value, a chart card's total), so it
+ * is the quieter of the pair — one step down and MUTED, which is what lets the 24px mono value under
+ * it carry the card. Both keep the shared head-font 88% stretch.
+ *
+ * Rendered identically (15px ink both) the hero value competed with its own label, four cards in a
+ * row read as four headings, and the section that grouped them read as one more of the same.
+ */
+.heading {
+  display: inline-flex;
+  align-items: center;
+  gap: 5px;
+  margin: 0;
+  min-width: 0;
+  font-family: var(--basalt-font-head);
+  font-stretch: 88%;
+  font-weight: 550;
+  font-size: var(--vx-text-md);
+  color: var(--vx-ink);
+}
+
+.root[data-tier='section'] .heading {
+  font-weight: 600;
+}
+
+.root[data-tier='widget'] .heading {
+  font-size: var(--vx-text-sm);
+  color: var(--vx-muted);
+}
+
+.titleText {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+/*
+ * The icon slot PINS its glyph's box. A consumer's icon arrives at whatever size its own component
+ * chose (the playground's is 18px), and an 18px mark beside a 13.5px title is a bullet, not a label
+ * icon — so the tier states the size here rather than asking every call site to pass one.
+ */
+/*
+ * The heading's icon box carries COLOUR ONLY — geometry belongs to `theme/icon-slot.module.css`,
+ * which this class is composed onto (`IconSlot className={classes.icon}`). The per-tier SIZE is set
+ * as the slot's own box var below rather than as a `> svg` rule, so it survives whatever the caller's
+ * glyph declares for itself: a `width`/`height` attribute is a presentation attribute and loses to
+ * the slot's CSS, while a `> svg` rule scoped to one component only ever fixed that component.
+ */
+.icon {
+  color: var(--vx-faint);
+}
+
+.root[data-tier='widget'] .icon {
+  --vx-space-icon-size: 0.875rem;
+}
+
+.root[data-tier='section'] .icon {
+  --vx-space-icon-size: 1rem;
+}
+
+/* Mono count tag after the title (C11 — every table/list states its count in its header). Its box is
+ * the `tag` tier (20px), so it never grows the header row it sits in. */
+.count {
+  display: inline-flex;
+  flex-shrink: 0;
+  align-items: center;
+  /* Exactly the `tag` tier (20px), not a floor: the mono `VX.text.xs` line box plus
+   * `badgeInset`-y is 23px on its own, so a `min-height` changed nothing and the tag rendered 3px
+   * taller than the tier it is named for — enough to grow a 36px section-header row. `line-height: 1`
+   * is what lets the box be the stated height instead of the text's. */
+  /* `--mantine-scale`-aware, same reconstruction every other ctl/tag-tier box uses (`theme/index.ts`'s
+   * `ctlSizeVars`) — read raw, this box stayed fixed while the Badge/Button beside it in the same
+   * header scaled with `theme.scale`. */
+  height: calc(var(--vx-space-control-height-tag, 1.25rem) * var(--mantine-scale, 1));
+  line-height: 1;
+  border-radius: var(--vx-radius-ctrl);
+  background: var(--vx-surface-subtle);
+  padding: var(--vx-space-badge-inset-y) var(--vx-space-badge-inset-x);
+  font-family: var(--basalt-font-mono);
+  font-size: var(--vx-text-xs);
+  font-weight: 500;
+  color: var(--vx-faint);
+}
+
+/*
+ * The hero-metric row — value + delta, directly under the title row, for both tiers. The delta rides
+ * 4px off the value, not 8: it is a suffix ON the number (`$168,920 +47%`), and at 8px it read as a
+ * second, unrelated chip in the row. `baseline` alignment is what keeps the mono numeral and the
+ * badge's own smaller mono text sitting on one line.
+ */
+/*
+ * The hero-metric row: the value, then its `DeltaBadge`.
+ *
+ * The gap is the 8px vertical-rhythm step (`--vx-space-stack-sm`), not the 4px it shipped as. 4px is
+ * the rhythm's SMALLEST step — the distance between a label and the thing it labels — and at that
+ * distance the badge read as a superscript hanging off the numeral rather than as a second fact
+ * beside it. It is a token and not a literal so it tracks the density knob with every other spacing
+ * in the header (`deriveSpacing`, `tokens/palette.ts`); `theme/layout-rhythm-css.test.ts`'s sibling
+ * assertion in `widget-header.test.tsx` pins it against exactly the literal it used to be.
+ *
+ * `align-items: center`, not `baseline`. The badge is a BOX with its own padding and a mono 11.5px
+ * label, so aligning its text baseline to a 24px KPI numeral's baseline put the box itself low —
+ * its top edge sat below the numeral's x-height and its bottom edge hung under the numeral's
+ * baseline. A chip beside a numeral is centred on the numeral, the same law the `count` tag in the
+ * title row above already follows.
+ */
+.metrics {
+  display: flex;
+  flex-wrap: nowrap;
+  align-items: center;
+  gap: var(--vx-space-stack-sm);
+  margin-top: 2px;
+  min-width: 0;
+}
+
+/*
+ * Below `sm` the metric row WRAPS, so the badge drops under the value instead of ellipsizing it.
+ * `nowrap` plus the `.value` clamp below is right on desktop — a `+18.9%` cannot ellipsize and read,
+ * a numeral can — but a KPI's numeral IS the content, and in a 2-up card grid at 390px
+ * `$1294.9k ▲18.9%` rendered as `$129… ▲18.9%`. Truncating the number to protect the delta about the
+ * number is the wrong way round. Conditional like the title row above it: a short value keeps the
+ * badge beside it, and only a value that would otherwise clip gives up the line.
+ */
+@media (max-width: 47.99375em) {
+  .metrics {
+    flex-wrap: wrap;
+    row-gap: 2px;
+  }
+}
+
+/* The value is the row's shrinkable half and the delta badge is not: a pre-formatted numeral can
+ * ellipsize and still read, a `+18.9%` cannot. Without the clamp the badge grew past the header box
+ * and painted over `StatCard`'s 72px sparkline slot beside it. */
+.value {
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  font-family: var(--basalt-font-mono);
+  font-size: var(--vx-text-kpi);
+  font-weight: 600;
+  letter-spacing: -0.02em;
+  color: var(--vx-ink);
+}
+
+/*
+ * The unit beside the hero value. Mono like the number it qualifies (so `412 TSS` sits on one
+ * baseline grid), `--vx-text-sm` and `--vx-muted` so it never competes with the numeral — the whole
+ * point is that a unit is the SMALL half of the pair. `flex-shrink: 0`: the value is the row's
+ * shrinkable half (see `.value`), and a unit that ellipsized to `TS…` would state nothing.
+ */
+.unit {
+  flex-shrink: 0;
+  align-self: baseline;
+  font-family: var(--basalt-font-mono);
+  font-size: var(--vx-text-sm);
+  font-weight: 500;
+  color: var(--vx-muted);
+}
+
+/* The C1/C5 home for header actions — always pinned right, regardless of what else is present. */
+.actions {
+  display: inline-flex;
+  flex-shrink: 0;
+  align-items: center;
+  gap: var(--vx-space-control-gap, 0.375rem);
+  margin-inline-start: auto;
+}
+
+/* Directly under the title row, 4px off it — 1px put it inside the title's own line box, so a
+ * section with both read as a two-line heading rather than a heading plus a note. */
+.subtitle {
+  margin-top: 4px;
+  font-size: var(--vx-text-sm);
+  font-weight: 400;
+  color: var(--vx-muted);
+}
+
+/* `data-placement` is read by wave-3 composers wanting a `bleed` layout (docs/CONTROLS-SPEC.md
+ * §2.2's `sparklinePlacement` composer mapping) — this primitive only ever sets `right`. */
+.sparkline {
+  margin-top: 4px;
+}
+
+/* ── info glyph ─────────────────────────────────────────────────────────────────────────────── */
+
+.info {
+  position: relative;
+  display: inline-flex;
+  flex-shrink: 0;
+  align-items: center;
+}
+
+.infoTrigger {
+  display: inline-flex;
+  align-items: center;
+  appearance: none;
+  margin: 0;
+  padding: 0;
+  border: none;
+  background: none;
+  color: var(--vx-faint);
+  cursor: help;
+}
+
+.infoTrigger:hover,
+.infoTrigger:focus-visible,
+.infoTrigger[data-open='true'] {
+  color: var(--vx-muted);
+}
+
+/*
+ * The tooltip bubble reads like every other floating surface — panel bg + `shadow-card` + card
+ * radius (docs/DESIGN-SPEC.md §5). It opens DOWNWARD by convention, into whatever sits below the
+ * header. `pointer-events: none` so it can never swallow the pointer on its way back to the
+ * trigger's `mouseleave`. Mantine-free by design (this whole folder is), so it is a plain
+ * state-driven bubble rather than a Mantine Tooltip — which is also what makes it composable from
+ * inside the `charts/` boundary.
+ */
+.infoBubble {
+  position: absolute;
+  top: calc(100% + 7px);
+  left: 0;
+  z-index: 10;
+  width: max-content;
+  max-width: 260px;
+  padding: 7px 10px;
+  border-radius: var(--vx-radius-card);
+  background-color: var(--vx-surface-panel);
+  box-shadow: var(--vx-shadow-card);
+  color: var(--vx-muted);
+  font-size: var(--vx-text-sm);
+  font-weight: 400;
+  line-height: 1.4;
+  white-space: normal;
+  pointer-events: none;
+}
+
+/* ── DeltaBadge ─────────────────────────────────────────────────────────────────────────────── */
+
+.deltaBadge {
+  display: inline-flex;
+  flex: none;
+  white-space: nowrap;
+  align-items: center;
+  gap: 3px;
+  border-radius: var(--vx-radius-ctrl);
+  padding: var(--vx-space-badge-inset-y) var(--vx-space-badge-inset-x);
+  font-family: var(--basalt-font-mono);
+  font-size: var(--vx-text-xs);
+  font-weight: 600;
+  line-height: 1;
+}
+
+.deltaGlyph {
+  font-size: 0.8em;
+}
+
+.deltaPeriod {
+  margin-inline-start: 4px;
+  font-weight: 500;
+  opacity: 0.6;
+}
+
+/*
+ * Law C15 — the `actions` slot is the tier-2/tier-3 home, and its controls are 30px (`ctl`) or 24px
+ * (`icon`). Below `sm` an `::after` overlay lifts the HIT area to
+ * `--vx-space-touch-control-height` (36px at level 0) without moving the visible box, the same
+ * overlay `shell/page-bar.module.css` draws for the bar. `overflow: visible` is load-bearing:
+ * Mantine's Button/ActionIcon roots are `overflow: hidden`, which clips an overlay that by
+ * definition extends past the box — the clipping only exists for their loading overlay, painted
+ * under `[data-loading]`, which is excluded here.
+ */
+@media (max-width: 47.99375em) {
+  .actions :is(button, a) {
+    position: relative;
+  }
+
+  .actions :is(button, a):not([data-loading]) {
+    overflow: visible;
+  }
+
+  .actions :is(button, a)::after {
+    content: '';
+    position: absolute;
+    top: 50%;
+    left: 50%;
+    translate: -50% -50%;
+    width: 100%;
+    height: 100%;
+    min-width: var(--vx-space-touch-control-height, 2.25rem);
+    min-height: var(--vx-space-touch-control-height, 2.25rem);
+  }
+}

package/dist/widget-header/widget-header.module.css.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Typed CSS-module declaration (the S4 CSS-modules path). Named string props — not an index
+ * signature — so dot access stays verbatim under the package's strict flags.
+ */
+declare const classes: {
+  readonly root: string
+  readonly titleRow: string
+  readonly heading: string
+  readonly titleText: string
+  readonly icon: string
+  readonly count: string
+  readonly metrics: string
+  readonly value: string
+  readonly unit: string
+  readonly actions: string
+  readonly subtitle: string
+  readonly sparkline: string
+  readonly info: string
+  readonly infoTrigger: string
+  readonly infoBubble: string
+  readonly deltaBadge: string
+  readonly deltaGlyph: string
+  readonly deltaPeriod: string
+}
+export default classes

package/dist/widget-header/widget-header.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=widget-header.test.d.ts.map

package/dist/widget-header/widget-header.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"widget-header.test.d.ts","sourceRoot":"","sources":["../../src/widget-header/widget-header.test.tsx"],"names":[],"mappings":""}

package/llms.txt

@@ -1,4 +1,4 @@
-# basalt-ui v1.25.0
+# basalt-ui v1.27.0
 # Opinionated framework for Mantine-based React apps — theme, app shell, visx charts, toolchain presets
 #
 # basalt-ui is an opinionated framework for Mantine-based React apps.
@@ -19,11 +19,11 @@
 # ./tokens.css subpath. Guide: docs/FRAMEWORK-FREE.md in the repo.
 
 Package: basalt-ui
-Version: 1.25.0
+Version: 1.27.0
 
 ## basalt-ui
 Import: import { ... } from 'basalt-ui'
-Description: BasaltProvider, createBasaltTheme, BasaltShell + sidebar/mobile-nav/breadcrumbs, NavCountBadge, ThemeToggle, ThreadWorkspace + thread-chat components, dashboard composites (DeltaBadge, StatCard with threshold tone, EmptyState, QueryState/LoadingState/ErrorState, SettingsSection/SettingsRow/DangerZone)
+Description: BasaltProvider, createBasaltTheme, BasaltShell + sidebar/mobile-nav/breadcrumbs, PageBar, NavCountBadge, ThemeToggle, ThreadWorkspace + thread-chat components, WidgetHeader, dashboard composites (DeltaBadge, StatCard with threshold tone, EmptyState, QueryState/LoadingState/ErrorState, SettingsSection/SettingsRow/DangerZone)
 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
@@ -60,82 +60,95 @@ Layer: headless
 Import: import { ... } from 'basalt-ui/query'
 Description: createBasaltQueryClient, transport-agnostic unwrap, lazy BasaltQueryDevtools
 Layer: headless
-Rule: basalt-query
+Rule: basalt-batteries
 OptionalPeers: @tanstack/react-query-devtools@^5.101.0
 
 ## basalt-ui/router-tanstack
 Import: import { ... } from 'basalt-ui/router-tanstack'
-Description: TanStack Router bridge: defineNav/navGroup/navTarget (one typed nav definition) + useNav (sections + mobileNav, spread onto BasaltShell) + useBasaltNav (active route) + useRouterBreadcrumbs + createSearchParamStore (single-select URL-state store) + createMultiSearchParamStore (multi-select URL-state store)
+Description: TanStack Router bridge: defineNav/navGroup/navTarget (one typed nav definition) + useNav (sections + mobileNav, spread onto BasaltShell) + useBasaltNav (active route) + useRouterBreadcrumbs + createSearchStore (typed URL > localStorage > fallback store over field.enum/multi/range/number/boolean/string; deprecated createSearchParamStore/createMultiSearchParamStore wrappers until 1.29.0)
 Layer: headless
-Rule: basalt-router
+Rule: basalt-state
 OptionalPeers: @tanstack/react-router@^1.170.0
 
 ## basalt-ui/forms
 Import: import { ... } from 'basalt-ui/forms'
 Description: Mantine form adapter: useBasaltForm, field, FormErrorSummary, useFormDraft (Standard Schema)
 Layer: mantine-coupled
-Rule: basalt-forms
+Rule: basalt-batteries
 OptionalPeers: @mantine/form@^9.3.0
 
 ## basalt-ui/notifications
 Import: import { ... } from 'basalt-ui/notifications'
 Description: Mantine notifications: notify helpers, typed registry, persisted history, NotificationBell, NotificationCenter
 Layer: mantine-coupled
-Rule: basalt-notifications
+Rule: basalt-batteries
 OptionalPeers: @mantine/notifications@^9.3.0
 
 ## basalt-ui/commands
 Import: import { ... } from 'basalt-ui/commands'
 Description: typed command bus + overlay controller, toSpotlightActions, ShortcutsHelp, BasaltOverlays
 Layer: mantine-coupled
-Rule: basalt-commands
+Rule: basalt-batteries
 OptionalPeers: @mantine/spotlight@^9.3.0, @mantine/modals@^9.3.0, @tanstack/react-hotkeys@0.10.0
 
 ## basalt-ui/data
 Import: import { ... } from 'basalt-ui/data'
 Description: Convenience barrel pulling both TanStack Table + Virtual peer groups: BasaltDataTable, BasaltVirtualList (Mantine-rendered) — prefer ./data/table or ./data/virtual for per-feature opt-in
 Layer: mantine-coupled
-Rule: basalt-data
+Rule: basalt-batteries
 OptionalPeers: @tanstack/react-table@>=8 <9, @tanstack/react-virtual@>=3.13.26 <4
 
 ## basalt-ui/data/table
 Import: import { ... } from 'basalt-ui/data/table'
 Description: BasaltDataTable: a sortable data table over TanStack Table, rendered with Mantine (Mantine-rendered)
 Layer: mantine-coupled
-Rule: basalt-data
+Rule: basalt-batteries
 OptionalPeers: @tanstack/react-table@>=8 <9
 
 ## basalt-ui/data/virtual
 Import: import { ... } from 'basalt-ui/data/virtual'
 Description: BasaltVirtualList: a windowed virtual list over TanStack Virtual, rendered with Mantine (Mantine-rendered)
 Layer: mantine-coupled
-Rule: basalt-data
+Rule: basalt-batteries
 OptionalPeers: @tanstack/react-virtual@>=3.13.26 <4
 
 ## basalt-ui/agent
 Import: import { ... } from 'basalt-ui/agent'
 Description: Headless streaming-chat layer: useAgentStream, aiSdkTransport (recommended default) + edenTransport, isResumable/ResumableAgentTransport (stream-resumption seam), PartList, coalesceParts, the ForeignPart/definePartRenderers/narrowAgentPart open part-registry seam, plus the multi-thread createThreadsStore + useAgentThreadRuns + outcome-resolver seam (Mantine-free)
 Layer: headless
-Rule: basalt-agent
+Rule: basalt-batteries
 OptionalPeers: ai@^7.0.15, use-stick-to-bottom@^1.1.6
 
 ## basalt-ui/agent-chat
 Import: import { ... } from 'basalt-ui/agent-chat'
 Description: Mantine-styled thread-chat components over basalt-ui/agent: ThreadWorkspace, ThreadFeed (variant/renderRow), ThreadFeedRow (inline-expanding Slack row, lazily mounted + kept mounted), ThreadOutcomeCard, ThreadDetailPanel, Composer, ThreadTranscript (open part-renderer registry via its renderers/fallbackRenderer props, per-message MessageAffordances, groupConsecutive, and an optional virtualize/height windowing mode whose VirtualizeOptions carry overscan/estimateSize/initialScroll — a virtualized transcript opens scrolled to the newest message unless initialScroll is "start"), threadPartRenderers, ToolChip (Mantine-coupled). motion is required, not optional — ThreadFeed/ThreadDetailPanel import motion/react eagerly, so this subpath fails to resolve without it installed even though peerDependenciesMeta marks it optional (npm has no per-subpath optionality). remend is genuinely optional here — ThreadTranscript reaches it only through the lazy dynamic import() inside content/markdown.tsx, and @tanstack/react-virtual the same way through the lazy import() behind ThreadTranscript virtualize (absent peer degrades to an unwindowed, height-bound pane).
 Layer: mantine-coupled
-Rule: basalt-agent
+Rule: basalt-batteries
 OptionalPeers: ai@^7.0.15, motion@12.42.0, remend@1.3.0, use-stick-to-bottom@^1.1.6, react-markdown@^10.1.0, remark-gfm@^4.0.1, shiki@^4.3.0, @shikijs/langs@^4.3.1, @shikijs/themes@^4.3.1, beautiful-mermaid@^1.1.0, @tanstack/react-virtual@>=3.13.26 <4
 
 ## basalt-ui/content
 Import: import { ... } from 'basalt-ui/content'
-Description: Prose (article/chat typography), CodeBlock (shiki, optional peer), Callout, TableOfContents, ReadingProgress, Markdown (react-markdown + remark-gfm, optional peers; `streaming` is a rendering mode ONLY — `contentTrust` is the independent security input, and any surface rendering agent/model output must pin `contentTrust="untrusted"`, the sole input to the image-origin allowlist; a `fenceRenderers` registry — settledOnly/FenceRenderer/FenceRenderers/FenceRenderContext; `sanitizeSchema`, an additions-only SanitizeSchemaExtension merged over BASALT_SANITIZE_SCHEMA via mergeSanitizeSchema; the remend streaming-repair pass is now a lazy optional peer), MermaidDiagram (beautiful-mermaid, optional peer), mdxComponents/createMdxComponents, ArticleLayout (docs-page frame), ArticleCard/ArticleGrid (overview cards), Article model (sortArticles/filterArticles/formatArticleDate), ArticleFilterBar (category/tags filter UI), toArticleActions (Spotlight projector, @mantine/spotlight type-only), GuideLink/GuideDrawer (contextual-help drawer) — the content/prose surface
+Description: Prose (article/chat typography), CodeBlock (shiki, optional peer), Callout, TableOfContents, ReadingProgress, Markdown (react-markdown + remark-gfm, optional peers; `streaming` is a rendering mode ONLY — `contentTrust` is the independent security input, and any surface rendering agent/model output must pin `contentTrust="untrusted"`, the sole input to the image-origin allowlist; a `fenceRenderers` registry — settledOnly/FenceRenderer/FenceRenderers/FenceRenderContext; `sanitizeSchema`, an additions-only SanitizeSchemaExtension merged over BASALT_SANITIZE_SCHEMA via mergeSanitizeSchema; the remend streaming-repair pass is now a lazy optional peer), MermaidDiagram (beautiful-mermaid, optional peer), mdxComponents/createMdxComponents, ArticleLayout (docs-page frame), ArticleCard/ArticleGrid (overview cards), Article model (sortArticles/filterArticles/formatArticleDate), FilterSet/ViewTabs/MultiSelectFilter re-exported from ./controls (they replaced the controlled ArticleFilterBar), toArticleActions (Spotlight projector, @mantine/spotlight type-only), GuideLink/GuideDrawer (contextual-help drawer) — the content/prose surface
 Layer: mantine-coupled
-Rule: basalt-content
+Rule: basalt-batteries
 OptionalPeers: shiki@^4.3.0, @shikijs/langs@^4.3.1, @shikijs/themes@^4.3.1, beautiful-mermaid@^1.1.0, react-markdown@^10.1.0, remark-gfm@^4.0.1, rehype-sanitize@^6.0.0, remend@1.3.0, @mantine/spotlight@^9.3.0
 
+## 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). 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
+
+## basalt-ui/controls-dates
+Import: import { ... } from 'basalt-ui/controls-dates'
+Description: DateRangePicker — the @mantine/dates implementation of RangeFilter's customPicker seam. Its own subpath because @mantine/dates is an optional peer and basaltViteConfig pre-bundles the whole @mantine scope, so a consumer without the peer (linewatch) must never resolve it: nothing under src/controls may import it, statically or lazily (docs/CONTROLS-SPEC.md §3).
+Layer: mantine-coupled
+Rule: basalt-controls
+OptionalPeers: @mantine/dates@^9.3.0
+
 ## basalt-ui/state
 Import: import { ... } from 'basalt-ui/state'
-Description: createPersistedState (versioned localStorage) + useOnlineStatus — Mantine-free state primitives
+Description: createPersistedState (versioned localStorage) + the store field vocabulary (field.enum/multi/range/number/boolean/string, FieldHandle, lanes) + createLocalStore, the router-free store — Mantine-free state primitives
 Layer: headless
 Rule: basalt-state
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "basalt-ui",
-  "version": "1.25.0",
+  "version": "1.27.0",
   "description": "Opinionated framework for Mantine-based React apps — theme, app shell, visx charts, toolchain presets",
   "keywords": [
     "charts",
@@ -113,6 +113,14 @@
       "types": "./dist/content/index.d.ts",
       "import": "./dist/content/index.js"
     },
+    "./controls": {
+      "types": "./dist/controls/index.d.ts",
+      "import": "./dist/controls/index.js"
+    },
+    "./controls-dates": {
+      "types": "./dist/controls-dates/index.d.ts",
+      "import": "./dist/controls-dates/index.js"
+    },
     "./state": {
       "types": "./dist/state.d.ts",
       "import": "./dist/state.js"
@@ -143,6 +151,7 @@
     "@fontsource-variable/hubot-sans": "5.2.8",
     "@fontsource-variable/jetbrains-mono": "5.2.8",
     "@fontsource-variable/nunito-sans": "5.2.7",
+    "@mantine/dates": "9.3.0",
     "@shikijs/langs": "^4.3.1",
     "@shikijs/themes": "^4.3.1",
     "@tanstack/react-hotkeys": "0.10.0",
@@ -179,6 +188,7 @@
     "@fontsource-variable/jetbrains-mono": "5.2.8",
     "@fontsource-variable/nunito-sans": "5.2.7",
     "@mantine/core": "^9.3.0",
+    "@mantine/dates": "^9.3.0",
     "@mantine/form": "^9.3.0",
     "@mantine/hooks": "^9.3.0",
     "@mantine/modals": "^9.3.0",
@@ -228,6 +238,9 @@
     "@mantine/core": {
       "optional": true
     },
+    "@mantine/dates": {
+      "optional": true
+    },
     "@mantine/form": {
       "optional": true
     },

package/src/charts/cursor/resolve.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from 'bun:test'
-import { buildDomainIndex, parseKey, resolveCursorPoint } from './resolve'
+import { buildDomainIndex, classifyDomain, parseKey, resolveCursorPoint } from './resolve'
 
 type Point = { date: string }
 
@@ -121,3 +121,31 @@ describe("resolveCursorPoint — 'leading' resolution (bucket-keyed domains)", (
     expect(resolveCursorPoint(i, '2026-08-05', 'leading')?.date).toBe('2026-08-01')
   })
 })
+
+describe('classifyDomain', () => {
+  test('an ISO date domain classifies as time', () => {
+    expect(classifyDomain(['2026-08-01', '2026-08-02', '2026-08-03'])).toBe('time')
+  })
+
+  test("a bare-year domain classifies as linear, matching parseKey's numeric-first precedence", () => {
+    // "2026" passes the numeric test before it ever reaches the date fallback — same ordering
+    // `parseKey` applies to a single key, applied here across the whole domain.
+    expect(classifyDomain(['2024', '2025', '2026'])).toBe('linear')
+  })
+
+  test('a numeric bucket domain classifies as linear', () => {
+    expect(classifyDomain(['0', '1', '2', '3'])).toBe('linear')
+  })
+
+  test('a category domain classifies as band', () => {
+    expect(classifyDomain(['Visited', 'Added to cart', 'Purchased'])).toBe('band')
+  })
+
+  test('a mixed domain falls back to band', () => {
+    expect(classifyDomain(['2026-08-01', 'Direct'])).toBe('band')
+  })
+
+  test('an empty domain classifies as band', () => {
+    expect(classifyDomain([])).toBe('band')
+  })
+})

package/src/charts/cursor/resolve.ts

@@ -8,18 +8,50 @@
  * PARSED domain instead makes that automatic (`docs/CHARTS-SPEC.md` §3).
  */
 
+/** Numeric-string test — shared by `parseKey` and `classifyDomain` so a key can never be numeric
+ * to one and not the other. */
+function isNumericString(key: string): boolean {
+  return /^[-+]?\d*\.?\d+$/.test(key) && Number.isFinite(Number(key))
+}
+
+/** `Date.parse`-able test — shared by `parseKey` and `classifyDomain`, same reason. */
+function isDateParseableString(key: string): boolean {
+  return !Number.isNaN(Date.parse(key))
+}
+
 /**
  * A key as a comparable number: numeric-looking strings as numbers, everything else as a date.
  * Neither (a plain category like "Direct") → null, which degrades to exact-match only — correct,
  * since "nearest category" is meaningless.
  */
 export function parseKey(key: string): number | null {
-  if (/^[-+]?\d*\.?\d+$/.test(key)) {
-    const n = Number(key)
-    return Number.isFinite(n) ? n : null
-  }
-  const t = Date.parse(key)
-  return Number.isNaN(t) ? null : t
+  if (isNumericString(key)) return Number(key)
+  return isDateParseableString(key) ? Date.parse(key) : null
+}
+
+/** The x-domain families the shared cursor partitions on, derived from a chart's own keys — never
+ * a prop, never `ChartCursorScope`. A chart's kind is stamped on every broadcast it makes, and a
+ * receiving chart ignores any broadcast whose kind differs from its own — so a category chart can
+ * never be mistaken for a time chart just because both domains happen to parse. */
+export type DomainKind = 'time' | 'linear' | 'band'
+
+/**
+ * Classify a domain by the SAME parse precedence `parseKey` applies to each key, so a domain can
+ * never be classified one way and resolved another:
+ *
+ * - empty domain → `'band'` (nothing to share).
+ * - every key numeric (same test `parseKey` tries first) → `'linear'`.
+ * - otherwise every key `Date.parse`-able (same test `parseKey` falls back to) → `'time'`.
+ * - otherwise → `'band'` (categories, or a mixed domain).
+ *
+ * Ordering matters and mirrors `parseKey` exactly: a domain of bare years like `"2026"` is numeric
+ * FIRST, so it classifies `'linear'`, not `'time'`, even though every value is also a valid date.
+ */
+export function classifyDomain(keys: readonly string[]): DomainKind {
+  if (keys.length === 0) return 'band'
+  if (keys.every(isNumericString)) return 'linear'
+  if (keys.every(isDateParseableString)) return 'time'
+  return 'band'
 }
 
 /**