basalt-ui 2.6.0 → 2.7.0

package/llms.txt

@@ -1,4 +1,4 @@
-# basalt-ui v2.6.0
+# basalt-ui v2.7.0
 # Opinionated framework for Mantine-based React apps — theme, app shell, TanStack Charts, toolchain presets
 #
 # Entry points: use the exact import specifier below; do not guess.
@@ -13,13 +13,39 @@
 # A subpath's `Install:` line is its required peers; `OptionalPeers:` are import()-only, install on use.
 
 Package: basalt-ui
-Version: 2.6.0
+Version: 2.7.0
 
 ## basalt-ui
 Import: import { ... } from 'basalt-ui'
 Description: Wiring (`BasaltProvider`, `createBasaltTheme`, `createBasaltRouter`, `unwrap`), shell + nav (`BasaltShell`, `PageBar`, `PageAside`, `PageTitle`, `ThemeToggle`, `defineNav`/`navGroup`/`navTarget`/`flattenNav`, `useBasaltNav`, `useSizeClass`, `useCoarsePointer`), dashboard (`Section`, `WidgetHeader`, `StatCard`, `StatGroup`, `DeltaBadge`, `EmptyState`, `SettingsSection`/`SettingsRow`/`DangerZone`). Reaches no subpath-required peer.
 Layer: mantine-coupled
 Rule: basalt-mantine
+Signature: BasaltProvider(props: BasaltProviderProps): JSX.Element
+Signature: BasaltShell(props: BasaltShellProps<G, T>): JSX.Element
+Signature: DangerZone(props: SettingsSectionProps): JSX.Element
+Signature: DeltaBadge(props: DeltaBadgeProps): JSX.Element
+Signature: EmptyState(props: EmptyStateProps): JSX.Element
+Signature: PageAside(props: PageAsideProps): ReactNode
+Signature: PageBar(props: PageBarProps): ReactNode
+Signature: PageTitle(props: PageTitleProps): ReactNode
+Signature: Section(props: SectionProps): JSX.Element
+Signature: SettingsRow(props: SettingsRowProps): JSX.Element
+Signature: SettingsSection(props: SettingsSectionProps): JSX.Element
+Signature: StatCard(props: StatCardProps): JSX.Element
+Signature: StatGroup(props: StatGroupProps): JSX.Element
+Signature: ThemeToggle(props: ThemeToggleProps): JSX.Element
+Signature: WidgetHeader(props: WidgetHeaderProps): JSX.Element
+Signature: createBasaltRouter(options: { routeTree: TRouteTree; context?: TContext; query?: QueryClientConfi…): BasaltRouter<TRouteTree>
+Signature: createBasaltTheme(overrides: Omit<PartialObjectDeep<MantineTheme, { recurseIntoArrays: false; allo…, options: CreateBasaltThemeOptions | undefined): PartialObjectDeep<Ma…
+Signature: defineNav(config: "basalt: declare Register { router }"): NavConfig<G, T>
+Signature: flattenNav(config: { groups: ReadonlyArray<AnyNavGroup>; }): FlatNavItem[]
+Signature: navGroup(meta: Exact<M, NavGroupMeta>, items: NavItemsInput<T>): M & { items: T; }
+Signature: navTarget(config: C, id: K): NavIndex<C["groups"]>[K]
+Signature: scrollParentOf(el: Element | null): HTMLElement | null
+Signature: unwrap(response: R): UnwrapResult<R>
+Signature: useBasaltNav(): { currentPath: string; isActive: (href: string, opts?: { exact?: bool…
+Signature: useCoarsePointer(): boolean
+Signature: useSizeClass(): "compact" | "medium" | "expanded"
 OptionalPeers: remark-gfm@^4.0.1, rehype-sanitize@^6.0.0, remend@1.4.0, shiki@^4.5.0, beautiful-mermaid@^1.1.0, @tanstack/react-router-devtools@^1.166.13
 
 ## basalt-ui/charts
@@ -27,6 +53,209 @@ Import: import { ... } from 'basalt-ui/charts'
 Description: CartesianChart (the TanStack Charts rung), the Lines and Bars kinds, ChartCard and the shared chartCursor (Mantine-free; @tanstack/charts + d3-scale peers)
 Layer: headless
 Rule: basalt-charts
+Signature: BandStrip(props: BandStripProps<T, X>): ReactElement<unknown, string | JSXElementConstructor<any>>
+  className?: string
+  style?: CSSProperties
+  ariaLabel: string
+  data: readonly T[]
+  x: (d: T) => X
+  xTicks?: number | readonly X[]
+  formatX?: ((x: X) => string)
+  legend?: false | ChartLegendConfig
+  height?: number | ResponsiveChartHeight
+  state?: ChartState
+  cursorGroup?: string
+  cursorResolution?: CursorResolution
+  tooltip?: false | ChartTooltipConfig<T, X>
+  states: readonly BandStripSeries<T>[]
+  getBand: (d: T) => BandSpan
+  fold?: BandFold<T>
+Signature: Bars(props: BarsProps<T, X>): ReactElement<unknown, string | JSXElementConstructor<any>>
+  className?: string
+  style?: CSSProperties
+  ariaLabel: string
+  data: readonly T[]
+  x: (d: T) => X
+  y?: AxisConfig<T>
+  y2?: AxisConfig<T>
+  xTicks?: number | readonly X[]
+  formatX?: ((x: X) => string)
+  zones?: readonly ZoneSpec[]
+  xZones?: readonly XZoneSpec<X>[]
+  refLines?: readonly RefLine[]
+  legend?: false | ChartLegendConfig
+  height?: number | ResponsiveChartHeight
+  state?: ChartState
+  cursorGroup?: string
+  cursorResolution?: CursorResolution
+  tooltip?: false | ChartTooltipConfig<T, X>
+  bars: readonly BarsBar<T>[]
+  lines?: readonly BarsLine<T>[]
+  layout?: "stacked" | "grouped" | "normalized"
+  barOpacity?: ((d: T, key: string) => number)
+Signature: CartesianChart(props: CartesianChartProps<T, X>): ReactElement<unknown, string | JSXElementConstructor<any>>
+  className?: string
+  style?: CSSProperties
+  ariaLabel: string
+  data: readonly T[]
+  x: (d: T) => X
+  series: readonly ChartSeries<T>[]
+  marks: (plot: PlotContext<T, X>) => ChartMarks
+  y?: AxisConfig<T>
+  y2?: AxisConfig<T>
+  xTicks?: number | readonly X[]
+  formatX?: ((x: X) => string)
+  zones?: readonly ZoneSpec[]
+  xZones?: readonly XZoneSpec<X>[]
+  refLines?: readonly RefLine[]
+  legend?: false | ChartLegendConfig
+  height?: number | ResponsiveChartHeight
+  state?: ChartState
+  cursorGroup?: string
+  cursorResolution?: CursorResolution
+  tooltip?: false | ChartTooltipConfig<T, X>
+Signature: ChartCard(props: ChartCardProps): ReactElement<unknown, string | JSXElementConstructor<any>>
+  className?: string
+  style?: CSSProperties
+  classNames?: Partial<Record<ChartCardSlot, string>>
+  title?: string
+  icon?: ReactNode
+  subtitle?: string
+  info?: string
+  value?: string
+  delta?: number
+  deltaPeriod?: string
+  deltaPolarity?: DeltaPolarity
+  count?: number
+  actions?: ReactNode
+  state?: ChartState
+  placeholderHeight?: number | ResponsiveChartHeight
+  stateAction?: ReactNode
+  children?: ReactNode
+Signature: Donut(props: DonutProps<K>): ReactElement<unknown, string | JSXElementConstructor<any>>
+  className?: string
+  style?: CSSProperties
+  ariaLabel: string
+  data: readonly DonutDatum<K>[]
+  colorForKey: (key: K) => string
+  formatValue: (v: number) => string
+  seriesLabel?: ((key: K) => string)
+  centerLabel?: string
+  centerSubLabel?: string
+  height?: number | ResponsiveChartHeight
+  state?: ChartState
+Signature: DualPanel(props: DualPanelProps<T, X>): ReactElement<unknown, string | JSXElementConstructor<any>>
+  className?: string
+  style?: CSSProperties
+  ariaLabel: string
+  data: readonly T[]
+  x: (d: T) => X
+  formatX?: ((x: X) => string)
+  legend?: false | ChartLegendConfig
+  height?: number | ResponsiveChartHeight
+  state?: ChartState
+  cursorGroup?: string
+  cursorResolution?: CursorResolution
+  tooltip?: false | ChartTooltipConfig<T, X>
+  series: readonly DualPanelLine<T>[]
+  top?: { domain?: readonly [number, number] | "auto" | undefined; …
+  fillBetween?: { from: string; to: string; fill: string; aboveFill?: strin…
+  bar: DualPanelBar<T>
+  topFraction?: number
+Signature: Heatmap(props: HeatmapProps<T>): ReactElement<unknown, string | JSXElementConstructor<any>>
+  className?: string
+  style?: CSSProperties
+  ariaLabel: string
+  data: readonly T[]
+  getRow: (d: T) => string
+  getCol: (d: T) => string
+  getValue: (d: T) => number | null
+  rows?: readonly string[]
+  cols?: readonly string[]
+  color?: string
+  domain?: readonly [number, number]
+  formatValue?: ((v: number) => string)
+  formatRow?: ((row: string) => string)
+  formatCol?: ((col: string) => string)
+  legend?: false | { label?: string | undefined; }
+  tooltip?: false | { rows?: ((d: T) => readonly ChartTooltipRow[]) | u…
+  height?: number | ResponsiveChartHeight
+  matchHeight?: boolean
+  state?: ChartState
+Signature: Lines(props: LinesProps<T, X>): ReactElement<unknown, string | JSXElementConstructor<any>>
+  className?: string
+  style?: CSSProperties
+  ariaLabel: string
+  data: readonly T[]
+  x: (d: T) => X
+  series: readonly ChartSeries<T>[]
+  y?: AxisConfig<T>
+  y2?: AxisConfig<T>
+  xTicks?: number | readonly X[]
+  formatX?: ((x: X) => string)
+  zones?: readonly ZoneSpec[]
+  xZones?: readonly XZoneSpec<X>[]
+  refLines?: readonly RefLine[]
+  legend?: false | ChartLegendConfig
+  height?: number | ResponsiveChartHeight
+  state?: ChartState
+  cursorGroup?: string
+  cursorResolution?: CursorResolution
+  tooltip?: false | ChartTooltipConfig<T, X>
+  thresholds?: [X] extends [string] ? never : readonly Threshold[]
+Signature: MirroredBars(props: MirroredBarsProps<T, X>): ReactElement<unknown, string | JSXElementConstructor<any>>
+  className?: string
+  style?: CSSProperties
+  ariaLabel: string
+  data: readonly T[]
+  x: (d: T) => X
+  formatX?: ((x: X) => string)
+  legend?: false | ChartLegendConfig
+  height?: number | ResponsiveChartHeight
+  state?: ChartState
+  cursorGroup?: string
+  tooltip?: false | ChartTooltipConfig<T, X>
+  series: readonly MirroredBarsSeries<T>[]
+  up: MirroredBarPane
+  down: MirroredBarPane
+  upFraction?: number
+  getAbsentFraction?: ((d: T) => number)
+  getBarOpacity?: ((d: T) => number)
+  fold?: { minBandPx?: number | undefined; merge: (group: T[]) => T;…
+  cursorResolution?: CursorResolution
+Signature: Sparkline(props: SparklineProps): ReactElement<unknown, string | JSXElementConstructor<any>>
+  className?: string
+  style?: CSSProperties
+  ariaLabel: string
+  data: readonly number[]
+  height: number
+  width?: number
+  mark?: "line" | "bar"
+  color?: string
+  emphasizeLast?: boolean
+  emphasisColor?: string
+  state?: ChartState
+Signature: StackedArea(props: StackedAreaProps<T, X>): ReactElement<unknown, string | JSXElementConstructor<any>>
+  className?: string
+  style?: CSSProperties
+  ariaLabel: string
+  data: readonly T[]
+  x: (d: T) => X
+  xTicks?: number | readonly X[]
+  formatX?: ((x: X) => string)
+  zones?: readonly ZoneSpec[]
+  xZones?: readonly XZoneSpec<X>[]
+  refLines?: readonly RefLine[]
+  legend?: false | ChartLegendConfig
+  height?: number | ResponsiveChartHeight
+  state?: ChartState
+  cursorGroup?: string
+  cursorResolution?: CursorResolution
+  tooltip?: false | ChartTooltipConfig<T, X>
+  series: readonly StackedAreaBand<T>[]
+  y?: Omit<AxisConfig<T>, "scale">
+Signature: chartCursor(group: string): ChartCursorController<ChartValue, ChartValue>
+Signature: chartCurve(name: CurveName): ChartCurve
 Install: bun add @tanstack/charts@1.1.0 d3-scale@4.0.2
 
 ## basalt-ui/tokens
@@ -34,11 +263,24 @@ Import: import { ... } from 'basalt-ui/tokens'
 Description: VX token refs, buildPaletteCss, defineSeries, seriesTokens, groupTokens, alpha (Mantine-free)
 Layer: headless
 Rule: basalt-tokens
+Signature: BP: { black, white, darkGray, gray, lightGray, blue, green, orange, red, vermilion, rose, violet, indigo, cerulean, turquoise, forest, lime, gold, sepia }
+Signature: CONTAINER_CLASSES: { micro, compact, regular, wide }
+Signature: CONTAINER_GRID_BREAKPOINTS: { xs, sm, md, lg, xl }
+Signature: CONTAINER_KEYS: { compact, regular, wide }
+Signature: VX: { lineWidth, line2Width, axisFont, dotR, dashArray, legendGap, legendFontSize, text, radiusCard, radiusCtrl, radiusPill, hit, space, line2Dark, good, goodSoft, bad, …
+Signature: alpha(token: string, a: number): string
+Signature: buildPaletteCss(opts: BuildPaletteOpts, data: { ACCENT: { readonly accent: ColorPair; readonly accentHover: ColorPa…): string
+Signature: defineSeries(map: T): T
+Signature: groupTokens(name: string, map: T): { readonly [K in keyof T]: GroupRef; }
+Signature: p(fam: readonly string[], light: number, dark: number): ColorPair
+Signature: seriesTokens(map: T, prefix: string): { [K in keyof T]: string; }
 
 ## basalt-ui/vite
 Import: import { ... } from 'basalt-ui/vite'
 Description: basaltViteConfig(opts) — Vite preset for basalt-ui consumer apps; basaltAppPlugin(opts) — PWA head, manifest, and icon metadata derived from the token palette
 Layer: build-tooling
+Signature: basaltAppPlugin(options: BasaltAppOptions): PluginOption[]
+Signature: basaltViteConfig(opts: BasaltViteOptions): UserConfig
 Install: bun add 'vite@^7 || ^8'
 OptionalPeers: vite-plugin-pwa@^1.3.0
 
@@ -46,20 +288,25 @@ OptionalPeers: vite-plugin-pwa@^1.3.0
 Import: import { ... } from 'basalt-ui/format'
 Description: integer/money/percent/durationClock/relativeTime/weekday/km/kcal — Intl-backed, Mantine-free, React-free formatting; the chart layer formats through the same implementation
 Layer: headless
-Signature: integer(value: number, { locale? }) => string
-Signature: money(value: number, { currency: string, compact?, digits?, locale? }) => string
-Signature: percent(value: number, { input?: 'ratio' | 'percent', digits?, locale? }) => string
-Signature: km(meters: number, { digits? }) => string
-Signature: kcal(value: number, { digits? }) => string
-Signature: durationClock(seconds: number) => string
-Signature: relativeTime(value: number | Date | string, { now?, locale? }) => string
-Signature: weekday(value: Date | number | string, { format?: 'short' | 'long' | 'narrow', locale? }) => string
+Signature: durationClock(seconds: number): string
+Signature: integer(value: number, options: LocaleOption): string
+Signature: kcal(value: number, options: KcalOptions): string
+Signature: km(meters: number, options: KmOptions): string
+Signature: money(value: number, options: FmtCurrencyOptions): string
+Signature: percent(value: number, options: FmtPercentOptions): string
+Signature: relativeTime(value: string | number | Date, options: RelativeTimeOptions): string
+Signature: weekday(value: string | number | Date, options: WeekdayOptions): string
 
 ## basalt-ui/forms
 Import: import { ... } from 'basalt-ui/forms'
 Description: Mantine form layer: useBasaltForm + inputProps/fieldKey (two calls — a spread `key` is a React 19 warning), on @mantine/form
 Layer: mantine-coupled
 Rule: basalt-batteries
+Signature: fieldKey(form: UseFormReturnType<Values>, path: Path): string
+Signature: inputProps(form: UseFormReturnType<Values>, path: Path): InputProps
+Signature: useBasaltForm(opts: UseBasaltFormOptions<Values>): UseFormReturnType<Values>
+  mode?: "controlled" | "uncontrolled"
+  schema?: StandardSchemaV1<unknown, Values>
 Install: bun add @mantine/form@^9.7.0
 
 ## basalt-ui/commands
@@ -67,6 +314,15 @@ Import: import { ... } from 'basalt-ui/commands'
 Description: defineCommands (typed command bus), defineOverlays/overlays, setColorScheme, toggleSidebar, ShortcutsHelp, defineNotifications/emit/NotificationBell (folded in from ./notifications); BasaltProvider mounts Spotlight, Modals and Notifications
 Layer: mantine-coupled
 Rule: basalt-batteries
+Signature: NotificationBell(props: NotificationBellProps): JSX.Element
+Signature: ShortcutsHelp(props: ShortcutsHelpProps): JSX.Element | null
+Signature: defineCommands(spec: T): T
+Signature: defineNotifications(spec: T): T
+Signature: defineOverlays(spec: T): T
+Signature: emit(kind: K, args: EmitArgs<K>): string
+Signature: overlays: { open, confirm, confirmDelete, close }
+Signature: setColorScheme(scheme: ColorScheme): void
+Signature: toggleSidebar(): void
 Install: bun add @tanstack/react-hotkeys@0.13.0
 
 ## basalt-ui/table
@@ -74,6 +330,49 @@ Import: import { ... } from 'basalt-ui/table'
 Description: BasaltDataTable and createColumnHelper: a data table over TanStack Table v9, rendered with Mantine (renamed from ./data/table)
 Layer: mantine-coupled
 Rule: basalt-batteries
+Signature: BasaltDataTable(props: BasaltDataTableProps<T>): JSX.Element
+  className?: string
+  style?: CSSProperties
+  classNames?: Partial<Record<BasaltDataTableSlot, string>>
+  title?: string
+  icon?: ReactNode
+  subtitle?: string
+  data: T[]
+  columns: BasaltColumnDef<T>[]
+  enableSorting?: boolean
+  manualSorting?: boolean
+  striped?: boolean | "odd" | "even"
+  highlightOnHover?: boolean
+  emptyState?: ReactNode
+  isLoading?: boolean
+  query?: QueryStateLike<unknown>
+  skeletonRows?: number
+  initialSorting?: SortingState
+  onSortingChange?: (sorting: SortingState) => void
+  enableGlobalFilter?: boolean
+  globalFilterPlaceholder?: string
+  searchIcon?: ReactNode
+  initialGlobalFilter?: string
+  onGlobalFilterChange?: (value: string) => void
+  facets?: DataTableFacet<T>[]
+  onColumnFiltersChange?: (filters: ColumnFiltersState) => void
+  manualFiltering?: boolean
+  actions?: SlotActions
+  onRowActivate?: (row: T) => void
+  renderCard?: (row: T) => ReactNode
+  enableRowSelection?: boolean
+  rowSelection?: RowSelectionState
+  onRowSelectionChange?: (selection: RowSelectionState) => void
+  getRowId?: (row: T, index: number) => string
+  bulkActions?: (rows: T[]) => BarAction[]
+  rowActions?: DataTableRowAction<T>[]
+  rowLabel?: (row: T) => string
+  enablePagination?: boolean
+  pageSizeOptions?: number[]
+  initialPagination?: PaginationState
+  onPaginationChange?: (pagination: PaginationState) => void
+  … +13 more
+Signature: createColumnHelper(): ColumnHelper<{ rowSortingFeature: TableFeature; columnFilteringFeatur…
 Install: bun add @tanstack/react-table@9.2.8
 
 ## basalt-ui/agent
@@ -81,6 +380,14 @@ Import: import { ... } from 'basalt-ui/agent'
 Description: Streaming-chat surface: aiSdkTransport, useAgentThreadRuns, parseAgentPart, the open part-registry types, the consumer-owned thread contracts (AgentThread/ThreadsStore/ChatMessage), and the Mantine chat UI folded in from ./agent-chat (ThreadFeed, ThreadFeedRow, Composer, ToolChip). motion is subpath-required: the chat UI imports it eagerly
 Layer: mantine-coupled
 Rule: basalt-batteries
+Signature: Composer(props: ComposerProps): JSX.Element
+Signature: ThreadFeed(props: ThreadFeedProps): JSX.Element
+Signature: ThreadFeedRow(props: ThreadFeedRowProps): JSX.Element
+Signature: ToolChip(props: ToolChipProps): JSX.Element
+Signature: aiSdkTransport(options: AiSdkTransportOptions): AiSdkTransport<TPart>
+Signature: parseAgentPart(raw: unknown): AgentPart | null
+Signature: toAgentError(error: unknown): AgentError
+Signature: useAgentThreadRuns(props: UseAgentThreadRunsArgs<TPart>): UseAgentThreadRunsReturn<TPart>
 Install: bun add ai@^7.0.137 @ai-sdk/provider@^4.0.26 motion@14.1.0
 OptionalPeers: use-stick-to-bottom@^1.1.6, @tanstack/react-virtual@>=3.14.0 <4
 
@@ -89,20 +396,40 @@ Import: import { ... } from 'basalt-ui/content'
 Description: Prose (article/chat typography), Callout, TableOfContents, 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; `fenceRenderers` extends fenced-block rendering — settledOnly/FenceRenderer/FenceRenderers; `sanitizeSchema` is an additions-only SanitizeSchemaExtension merged over the default via mergeSanitizeSchema; shiki code blocks, beautiful-mermaid diagrams and the remend streaming repair load lazily from optional peers), ArticleLayout (docs-page frame), GuideLink (contextual-help link) — the content/prose surface
 Layer: mantine-coupled
 Rule: basalt-batteries
+Signature: ArticleLayout(props: ArticleLayoutProps): JSX.Element
+Signature: Callout(props: CalloutProps): JSX.Element
+Signature: GuideLink(props: GuideLinkProps): JSX.Element
+Signature: Markdown(props: MarkdownProps): JSX.Element
+Signature: Prose(props: ProseProps): JSX.Element
+Signature: TableOfContents(props: TableOfContentsProps): JSX.Element | null
+Signature: mergeSanitizeSchema(base: SanitizeSchemaInput, extensions: readonly (SanitizeSchemaExtension | undefined)[]): SanitizeSchema
+Signature: settledOnly(render: FenceRenderer): FenceRenderer
 Install: bun add react-markdown@^10.1.0
 OptionalPeers: shiki@^4.5.0, @shikijs/langs@^4.5.0, @shikijs/themes@^4.5.0, beautiful-mermaid@^1.1.0, remark-gfm@^4.0.1, rehype-sanitize@^6.0.0, remend@1.4.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, the action/sync family (ActionGroup, OverflowMenu, SyncButton, BarAction/GlobalAction), and the form layout FormSection/FormRow/FormGroup/FormActions (moved here from ./forms in 1.36.0 — FormRow is law C1’s form row and needs no @mantine/form). THREE surfaces, picked by the home and never by a prop (useFilterSurface): pill in a PageBar row, sheet in the mobile Filters (n) drawer, panel in a PageAside body — where every control renders an inspector/facet ROW instead of a chip (docs/ASIDE-SPEC.md §3). PanelRow is that row primitive (label above, hint, mono readout, an `end` control on the label line) and SliderControl is the one bound control with no pill form at all; the counts/max props on MultiSelectFilter render the Foundry facet list there. Every control owns its own desktop/mobile swap in CSS (C9) and renders size="ctl" internally. Resolves and renders with NO @mantine/dates installed — the custom date picker is injected through RangeFilter.customPicker from ./controls-dates.
+Description: The control tier (docs/CONTROLS-SPEC.md §3). Exports: `FilterSet` (nowrap row + measured +N fold + the mobile Filters (n) sheet), `RangeFilter`/`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`, `SyncButton` with the `BarAction`/`GlobalAction` types, and the form layout `FormRow`/`FormGroup` (moved here from ./forms in 1.36.0 — `FormRow` is law C1’s form row and needs no @mantine/form). THREE surfaces, picked by the home and never by a prop: pill in a PageBar row, sheet in the mobile Filters (n) drawer, panel in a PageAside body — where every control renders an inspector/facet ROW instead of a chip (docs/ASIDE-SPEC.md §3); the counts/max props on `MultiSelectFilter` render the Foundry facet list there. Every control owns its own desktop/mobile swap in CSS (C9) and renders size="ctl" internally. Resolves and renders with NO @mantine/dates installed — the custom date picker is injected through RangeFilter.customPicker from ./controls-dates.
 Layer: mantine-coupled
 Rule: basalt-controls
+Signature: FilterSet(props: FilterSetProps): ReactNode
+Signature: FormGroup(props: FormGroupProps): JSX.Element
+Signature: FormRow(props: FormRowProps): JSX.Element
+Signature: MultiSelectFilter(props: MultiSelectFilterProps<T>): ReactNode
+Signature: NumberFilter(props: NumberFilterProps): ReactNode
+Signature: RangeFilter(props: RangeFilterProps<P, C>): ReactNode
+Signature: SearchFilter(props: SearchFilterProps): ReactNode
+Signature: SelectFilter(props: SelectFilterEnumProps<T>): ReactNode
+Signature: SyncButton(props: SyncButtonProps): ReactNode
+Signature: ToggleFilter(props: ToggleFilterProps): ReactNode
+Signature: ViewTabs(props: ViewTabsProps<T>): ReactNode
 
 ## 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
+Signature: DateRangePicker(props: RangeCustomPickerProps): ReactNode
 Install: bun add @mantine/dates@^9.7.0 dayjs@^1.11.0
 
 ## basalt-ui/state
@@ -110,6 +437,11 @@ Import: import { ... } from 'basalt-ui/state'
 Description: field.enum/multi/range/number/boolean/string (the store field vocabulary), createSearchStore (typed URL > localStorage > fallback store), createLocalStore (the router-free store), createPersistedState (versioned localStorage)
 Layer: headless
 Rule: basalt-state
+Signature: createLocalStore(o: { key: string; fields: S; version?: number; }): LocalStore<S>
+Signature: createPersistedState(opts: PersistedStateOptions<T>): () => readonly [T, (next: T) => void]
+Signature: createSearchStore(o: CreateSearchStoreOptions<S>): SearchStore<S>
+Signature: externalField(o: { values: readonly T[]; fallback: NoInfer<T>; labels?: Partial<Record…): FieldHandle<EnumField<T, ResolvedLane>>
+Signature: field: { enum, multi, range, number, boolean, string }
 
 ## basalt-ui/styles.css
 Asset: basalt-ui/styles.css

package/package.json

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

package/src/charts/Bars.tsx

@@ -57,7 +57,7 @@ export type BarsProps<T, X extends ChartX = ChartX> = Omit<
   lines?: readonly BarsLine<T>[] | undefined
   /** Default `'stacked'`. `'normalized'` stacks each x to its share of the total. */
   layout?: 'stacked' | 'grouped' | 'normalized' | undefined
-  /** Per-bar opacity (a partial week, an estimate). Overrides the series' `fillOpacity`. */
+  /** Per-bar opacity (a partial week, an estimate, a shade per series). Overrides the series' `fillOpacity`; the legend swatch samples it on the first row. */
   barOpacity?: ((d: T, key: string) => number) | undefined
 }
 
@@ -82,12 +82,22 @@ function guardLogStack(layout: string, onLog: boolean): void {
 export function Bars<T, X extends ChartX = ChartX>(props: BarsProps<T, X>): ReactElement {
   const { bars, lines, layout = 'stacked', barOpacity, ...rest } = props
   guardLogStack(layout, bars.length > 0 && rest.y?.scale === 'log')
+  const sample = rest.data[0]
   const series = useMemo<ChartSeries<T>[]>(
     () => [
-      ...bars.map((b) => ({ ...b, mark: 'bar' as const })),
+      // The legend has no datum: its swatch wears the shade the bars draw on the first row, so
+      // per-bar shades (`barOpacity`) read the same in the legend as on the plot.
+      ...bars.map((b) => ({
+        ...b,
+        mark: 'bar' as const,
+        fillOpacity:
+          (sample !== undefined ? barOpacity?.(sample, b.key) : undefined) ??
+          b.fillOpacity ??
+          DEFAULT_BAR_OPACITY,
+      })),
       ...(lines ?? []).map((l) => ({ ...l, mark: 'line' as const })),
     ],
-    [bars, lines],
+    [bars, lines, barOpacity, sample],
   )
 
   const marks = useCallback(

package/src/charts/legend.tsx

@@ -87,8 +87,15 @@ function Swatch({ s, mode }: { s: SwatchStyle; mode: LegendMode }): ReactElement
       <span
         aria-hidden
         className={classes.dot}
-        // theme-allow raw-surface — a legend dot is a circle, not a surface corner
-        style={{ width: 8, height: 8, borderRadius: '50%', background: s.color, flex: 'none' }}
+        style={{
+          width: 8,
+          height: 8,
+          // theme-allow raw-surface — a legend dot is a circle, not a surface corner
+          borderRadius: '50%',
+          background: s.color,
+          opacity: s.fillOpacity ?? 1,
+          flex: 'none',
+        }}
       />
     )
   if ((s.mark ?? 'line') === 'line')

package/src/controls/form-layout.tsx

@@ -137,9 +137,10 @@ export type FormRowProps = BasaltProps &
     hint?: string
     /**
      * The field's error, rendered under the control. Falsy renders nothing. For a Mantine input
-     * wired through `inputProps(form, path)`, Mantine's own `Input.Wrapper` already renders
-     * `form.errors[path]` — passing it here too would render it twice. Reserve this prop for
-     * children that render no error of their own: a raw input, a custom control.
+     * wired through `inputProps(form, path)`, Mantine's own `Input.Wrapper` already renders the
+     * field error — passing it here too would render it twice. Reserve this prop for children that
+     * render no error of their own (a raw input, a custom control) and read it typed:
+     * `error={inputProps(form, path).error}`.
      */
     error?: ReactNode
     /** Marks the field required: an accent `*` for sighted readers, `(required)` for assistive tech. */
@@ -172,7 +173,7 @@ export type FormRowProps = BasaltProps &
  *
  * @example
  * // A raw control renders no error of its own — pass it explicitly.
- * <FormRow label="Email" required error={form.errors['email']}>
+ * <FormRow label="Email" required error={inputProps(form, 'email').error}>
  *   <input value={form.values.email} onChange={(e) => form.setFieldValue('email', e.target.value)} />
  * </FormRow>
  */
@@ -239,8 +240,16 @@ export type FormGroupProps = BasaltProps & {
  *
  * @example
  * <FormGroup label="Notify me about" direction="row">
- *   <Checkbox key={fieldKey(form, 'onDeploy')} {...inputProps(form, 'onDeploy')} label="Deploys" />
- *   <Checkbox key={fieldKey(form, 'onError')} {...inputProps(form, 'onError')} label="Errors" />
+ *   <Checkbox
+ *     key={fieldKey(form, 'onDeploy')}
+ *     {...inputProps(form, 'onDeploy', { type: 'checkbox' })}
+ *     label="Deploys"
+ *   />
+ *   <Switch
+ *     key={fieldKey(form, 'onError')}
+ *     {...inputProps(form, 'onError', { type: 'checkbox' })}
+ *     label="Errors"
+ *   />
  * </FormGroup>
  */
 export function FormGroup(props: FormGroupProps) {

package/src/forms/field.ts

@@ -15,7 +15,56 @@
  * which was the whole reason for the rename in the first place. Write
  * `key={fieldKey(form, path)} {...inputProps(form, path)}`.
  */
-import type { LooseKeys, UseFormReturnType } from '@mantine/form'
+import type { GetInputPropsReturnType, LooseKeys, UseFormReturnType } from '@mantine/form'
+import type { ReactNode } from 'react'
+
+/**
+ * What `inputProps` returns: Mantine's shape with `error` typed (`any` upstream). `error` is always
+ * present — Mantine sets the key on every call, `undefined` on a clean field — so it is `ReactNode`,
+ * not optional. It is the one typed way to read a field error: `form.errors` is an index signature
+ * (dot access is TS4111), and a raw control inside `FormRow` takes
+ * `<FormRow error={inputProps(form, path).error}>`. A Mantine input spread with `inputProps` already
+ * renders it; passing it to `FormRow` as well renders it twice.
+ */
+export type InputProps = Omit<GetInputPropsReturnType, 'error'> & { error: ReactNode }
+
+type Digit = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9'
+
+type AllDigits<S extends string> = S extends `${Digit}${infer Rest}`
+  ? Rest extends ''
+    ? true
+    : AllDigits<Rest>
+  : false
+
+/** A canonical array index: digits only, no sign, no decimal point, no exponent, no leading zero. */
+type IsIndex<S extends string> = S extends '0'
+  ? true
+  : S extends `0${string}`
+    ? false
+    : AllDigits<S>
+
+/** One path segment applied to a value; `never` when the segment does not exist there. */
+type Child<T, K extends string> =
+  NonNullable<T> extends infer N
+    ? N extends readonly (infer V)[]
+      ? IsIndex<K> extends true
+        ? V
+        : never
+      : K extends keyof N
+        ? N[K]
+        : never
+    : never
+
+type ValueAt<T, P extends string> = P extends `${infer Head}.${infer Rest}`
+  ? ValueAt<Child<T, Head>, Rest>
+  : Child<T, P>
+
+/** `Path` if the value at that dot path is a (possibly optional/nullable) boolean, else `never`. */
+type BooleanAt<Values, Path extends string> = [ValueAt<Values, Path>] extends [never]
+  ? never
+  : [NonNullable<ValueAt<Values, Path>>] extends [boolean]
+    ? Path
+    : never
 
 // ── inputProps ────────────────────────────────────────────────────────────────
 
@@ -37,8 +86,34 @@ import type { LooseKeys, UseFormReturnType } from '@mantine/form'
 export function inputProps<Values extends Record<string, unknown>, Path extends LooseKeys<Values>>(
   form: UseFormReturnType<Values>,
   path: Path,
-): ReturnType<UseFormReturnType<Values>['getInputProps']> {
-  return form.getInputProps(path)
+): InputProps
+/**
+ * The boolean overload: `{ type: 'checkbox' }` binds a boolean field to Mantine `Checkbox` and
+ * `Switch`. It returns `onChange` plus `defaultChecked` in `useBasaltForm`'s default `uncontrolled`
+ * mode, or `checked` under `mode: 'controlled'` (Mantine decides; there is no `value`).
+ *
+ * Only a path whose value is a boolean (optional/nullable included) type-checks; a string path is a
+ * type error, not a silently wrong binding. Two limits of that check:
+ * - The path must be a literal. A `string`-typed path is rejected here (use a literal, or the
+ *   one-argument form), so the path argument does not autocomplete.
+ * - On a union parent, a key present on several members is accepted only when every member types it
+ *   as boolean; array segments must be canonical indices (`flags.0`, never `flags.1.5` or `flags.01`).
+ *
+ * @example
+ * <Switch key={fieldKey(form, 'active')} {...inputProps(form, 'active', { type: 'checkbox' })} />
+ */
+export function inputProps<Values extends Record<string, unknown>, Path extends string>(
+  form: UseFormReturnType<Values>,
+  path: BooleanAt<Values, Path>,
+  options: { type: 'checkbox' },
+): InputProps
+export function inputProps<Values extends Record<string, unknown>>(
+  form: UseFormReturnType<Values>,
+  path: string,
+  options?: { type: 'checkbox' },
+): InputProps {
+  // Mantine types `error` optional but sets the key on every call (`withError` defaults to true).
+  return form.getInputProps(path, options) as InputProps
 }
 
 /**