basalt-ui 1.40.3 → 2.0.0

package/src/controls/glyphs.tsx

@@ -47,16 +47,6 @@ export function CalendarGlyph(): ReactNode {
   )
 }
 
-/** `CompareFilter`'s default leading icon — the arrows-swap glyph. */
-export function SwapGlyph(): ReactNode {
-  return (
-    <Stroke>
-      <path d="M4 8h13l-3.5 -3.5" />
-      <path d="M20 16h-13l3.5 3.5" />
-    </Stroke>
-  )
-}
-
 /** The mobile `Filters (n)` pill's leading icon. */
 export function FunnelGlyph(): ReactNode {
   return (

package/src/controls/index.ts

@@ -2,70 +2,19 @@
  * `basalt-ui/controls` — the Mantine-coupled control tier (`docs/CONTROLS-SPEC.md` §3).
  *
  * Every control here renders at the `ctl` tier from the home that hosts it and owns its own
- * desktop/mobile swap in CSS (law C9). Actions and sync land in wave 3; the filter/tab family
- * follows in wave 4.
+ * desktop/mobile swap in CSS (law C9).
  */
-export {
-  ActionGroup,
-  OverflowMenu,
-  MOBILE_GLOBAL_BAR_MAX,
-  barActionMobile,
-  globalActionMobile,
-  type BarAction,
-  type BarActionItem,
-  type BarActionMenu,
-  type BarActionCustom,
-  type ActionGroupProps,
-  type GlobalAction,
-  type OverflowMenuProps,
-} from './actions'
-export { SyncButton, formatAge, AGE_REFRESH_MS, type SyncButtonProps } from './sync-button'
-export { ControlGroup, type ControlGroupProps } from './control-group'
+export { type BarAction, type GlobalAction } from './actions'
+export { SyncButton } from './sync-button'
 
-// ── Filters + tabs (wave 4) ───────────────────────────────────────────────────────────────────
 // `FilterPill`, `FilterSheet` and the `EnumFilter` body are deliberately NOT here: reaching for
-// them is hand-rolling a filter (`basalt/hand-rolled-filter`), and `useFilterSurface` is only
-// meaningful to a control living inside a `FilterSet` — i.e. to this folder.
-export { FilterSet, type FilterSetProps } from './filter-set'
-export { RangeFilter, type RangeCustomPickerProps, type RangeFilterProps } from './range-filter'
-export {
-  CompareFilter,
-  COMPARE_VALUES,
-  type CompareFilterProps,
-  type CompareValue,
-} from './compare-filter'
-export {
-  SelectFilter,
-  type FilterOption,
-  type SelectFilterEnumProps,
-  type SelectFilterProps,
-  type SelectFilterStringProps,
-} from './select-filter'
-export { MultiSelectFilter, type MultiSelectFilterProps } from './multi-select-filter'
-export { NumberFilter, type NumberFilterOption, type NumberFilterProps } from './number-filter'
-export { SearchFilter, type SearchFilterProps } from './search-filter'
-export { ToggleFilter, type ToggleFilterProps } from './toggle-filter'
-export { ViewTabs, type ViewTabsOption, type ViewTabsProps } from './view-tabs'
-
-// ── The `panel` surface (docs/ASIDE-SPEC.md wave 2) ───────────────────────────────────────────
-// The two row-level primitives an aside body needs. `PanelRow` is the home (it wraps its slots in
-// `CtlSlot`), and `SliderControl` is the one bound control that has no pill form at all — see their
-// docs. The filters above render their own panel forms; there is nothing extra to import for them.
-export { PanelRow, type PanelRowProps } from './panel-row'
-export { SliderControl, type SliderControlProps } from './slider-control'
-
-// ── The form layout (moved from ./forms in 1.36.0) ────────────────────────────────────────────
-// Layout needs no `@mantine/form`, and `./forms`' barrel value-imports it — so a consumer rendering
-// a `FormRow` had to install a peer it never used. `./forms` re-exports these until 1.39.0.
-export {
-  FormSection,
-  FormRow,
-  FormGroup,
-  FormActions,
-  type FormSectionProps,
-  type FormSectionSlot,
-  type FormRowProps,
-  type FormRowSlot,
-  type FormGroupProps,
-  type FormActionsProps,
-} from './form-layout'
+// them is hand-rolling a filter (`basalt/hand-rolled-filter`).
+export { FilterSet } from './filter-set'
+export { RangeFilter } from './range-filter'
+export { SelectFilter } from './select-filter'
+export { MultiSelectFilter } from './multi-select-filter'
+export { NumberFilter } from './number-filter'
+export { SearchFilter } from './search-filter'
+export { ToggleFilter } from './toggle-filter'
+export { ViewTabs } from './view-tabs'
+export { FormRow, FormGroup } from './form-layout'

package/src/controls/multi-select-filter.tsx

@@ -25,21 +25,22 @@
 import { Checkbox, Stack } from '@mantine/core'
 import { useState } from 'react'
 import type { CSSProperties, ReactNode } from 'react'
-import type { BasaltProps } from '../common/props'
 import { assertRequiredProps } from '../common/validate'
-import type { FieldHandle, MultiField } from '../state'
+import type { FieldHandle } from '../state'
+import type { MultiField } from '../state/fields'
 import type { FilterOption } from './select-filter'
 import classes from './controls.module.css'
 import { POPOVER_ROW_HIT_GAP, useFilterRegistration, useFilterSurface } from './filter-context'
 import { FilterClearButton, FilterPill } from './filter-pill'
 import { CheckGlyph, useControlName } from './filter-sheet'
 import { PanelRow } from './panel-row'
+import type { UncontrolledProps } from './uncontrolled'
 
 /** How many facet rows a panel shows before the rest fold behind `Show N more`. Six is the point at
  *  which a facet column stops being a list you scan and starts being one you scroll. */
 const PANEL_FACET_MAX = 6
 
-export type MultiSelectFilterProps<T extends string> = BasaltProps & {
+export type MultiSelectFilterProps<T extends string> = UncontrolledProps & {
   readonly field: FieldHandle<MultiField<T>>
   readonly label: string
   readonly icon?: ReactNode
@@ -75,7 +76,7 @@ export type MultiSelectFilterProps<T extends string> = BasaltProps & {
 
 export function MultiSelectFilter<T extends string>(props: MultiSelectFilterProps<T>): ReactNode {
   // F-ERR-1 — without this a missing `field` surfaces as `undefined is not an object
-  // (evaluating 'field.use')`, caught by `BasaltErrorBoundary`.
+  // (evaluating 'field.use')`, caught by `RootBoundary`.
   assertRequiredProps('MultiSelectFilter', props, ['field'], {
     field: 'bind it to a store field (`store.field.<name>`), never a value/onChange pair.',
   })

package/src/controls/number-filter.tsx

@@ -63,7 +63,8 @@ import { useEffect, useRef, useState } from 'react'
 import type { ReactNode } from 'react'
 import type { BasaltProps } from '../common/props'
 import { assertRequiredProps } from '../common/validate'
-import type { FieldHandle, NumberField } from '../state'
+import type { FieldHandle } from '../state'
+import type { NumberField } from '../state/fields'
 import classes from './controls.module.css'
 import { EnumFilter } from './enum-filter'
 import type { ChoiceHandle } from './enum-filter'
@@ -71,6 +72,7 @@ import { useFilterRegistration, useFilterSurface } from './filter-context'
 import { FilterClearButton, FilterPill } from './filter-pill'
 import { useControlName } from './filter-sheet'
 import { PanelRow } from './panel-row'
+import type { UncontrolledProps } from './uncontrolled'
 
 /** One row of a numeric preset set. Narrower than `FilterOption` — a preset is never `disabled`:
  *  the set is declared at the call site, so a row that should not be offered is left out. */
@@ -79,7 +81,7 @@ export type NumberFilterOption = {
   readonly label: string
 }
 
-export type NumberFilterProps = BasaltProps & {
+export type NumberFilterProps = UncontrolledProps & {
   readonly field: FieldHandle<NumberField>
   /** The popover/sheet heading and the accessible name — never the pill text, which reads the
    *  VALUE (see `EnumFilter`'s doc for why a pill may only print what is selected). */
@@ -102,7 +104,7 @@ export type NumberFilterProps = BasaltProps & {
 
 export function NumberFilter(props: NumberFilterProps): ReactNode {
   // F-ERR-1 — without this a missing `field` surfaces as `undefined is not an object
-  // (evaluating 'field.use')`, caught by `BasaltErrorBoundary`.
+  // (evaluating 'field.use')`, caught by `RootBoundary`.
   assertRequiredProps('NumberFilter', props, ['field'], {
     field: 'bind it to a store field (`store.field.<name>`), never a value/onChange pair.',
   })
@@ -316,7 +318,9 @@ function useCommittedNumber(
   const [draft, setDraft] = useState<number | string>(value)
   const seen = useRef(value)
   const commitRef = useRef(setValue)
-  commitRef.current = setValue
+  useEffect(() => {
+    commitRef.current = setValue
+  })
 
   useEffect(() => {
     if (seen.current === value) return

package/src/controls/range-filter.tsx

@@ -30,15 +30,16 @@
 import { SegmentedControl, Select, Stack } from '@mantine/core'
 import { useEffect, useRef, useState } from 'react'
 import type { ComponentType, ReactNode } from 'react'
-import type { BasaltProps } from '../common/props'
 import { assertRequiredProps } from '../common/validate'
-import type { FieldHandle, RangeField, RangeValue } from '../state'
+import type { FieldHandle } from '../state'
+import type { RangeField, RangeValue } from '../state/fields'
 import classes from './controls.module.css'
 import { useFilterRegistration, useFilterSurface } from './filter-context'
 import { FilterPill } from './filter-pill'
 import { CalendarGlyph } from './glyphs'
 import { useControlName } from './filter-sheet'
 import { PanelRow } from './panel-row'
+import type { UncontrolledProps } from './uncontrolled'
 
 /** Past four presets the track goes vertical. */
 const VERTICAL_FROM = 5
@@ -81,7 +82,7 @@ export type RangeCustomPickerProps = {
 }
 
 /** Everything about the props that does not depend on the field's `custom` flag. */
-type RangeFilterBase<P extends string, C extends boolean> = BasaltProps & {
+type RangeFilterBase<P extends string, C extends boolean> = UncontrolledProps & {
   /**
    * A range handle from either store factory. Generic over the field's `custom` flag so a
    * `field.range({ ... })` WITHOUT `custom` (whose handle is `RangeField<P, false>`, and whose
@@ -112,7 +113,7 @@ export function RangeFilter<P extends string, C extends boolean = boolean>(
   props: RangeFilterProps<P, C>,
 ): ReactNode {
   // F-ERR-1 — without this a missing `field` surfaces as `undefined is not an object
-  // (evaluating 'field.use')`, caught by `BasaltErrorBoundary`.
+  // (evaluating 'field.use')`, caught by `RootBoundary`.
   assertRequiredProps('RangeFilter', props, ['field'], {
     field: 'bind it to a store field (`store.field.<name>`), never a value/onChange pair.',
   })

package/src/controls/search-filter.tsx

@@ -13,19 +13,21 @@
  * <SearchFilter field={table.field.q} placeholder="Search pages" />
  */
 import { TextInput } from '@mantine/core'
+import { useDebouncedCallback } from '@mantine/hooks'
 import { useEffect, useRef, useState } from 'react'
 import type { ReactNode } from 'react'
-import type { BasaltProps } from '../common/props'
 import { assertRequiredProps } from '../common/validate'
-import type { FieldHandle, StringField } from '../state'
+import type { FieldHandle } from '../state'
+import type { StringField } from '../state/fields'
 import { useFilterRegistration, useFilterSurface } from './filter-context'
 import { useControlName } from './filter-sheet'
 import { PanelRow } from './panel-row'
+import type { UncontrolledProps } from './uncontrolled'
 
 /** One navigation per typed phrase, not per keystroke. */
 const DEBOUNCE_MS = 200
 
-export type SearchFilterProps = BasaltProps & {
+export type SearchFilterProps = UncontrolledProps & {
   readonly field: FieldHandle<StringField>
   readonly placeholder?: string
   /** Sheet-form heading. @default 'Search' */
@@ -34,7 +36,7 @@ export type SearchFilterProps = BasaltProps & {
 
 export function SearchFilter(props: SearchFilterProps): ReactNode {
   // F-ERR-1 — without this a missing `field` surfaces as `undefined is not an object
-  // (evaluating 'field.use')`, caught by `BasaltErrorBoundary`.
+  // (evaluating 'field.use')`, caught by `RootBoundary`.
   assertRequiredProps('SearchFilter', props, ['field'], {
     field: 'bind it to a store field (`store.field.<name>`), never a value/onChange pair.',
   })
@@ -98,27 +100,31 @@ function useDebouncedField(
 ): { value: string; set: (next: string) => void } {
   const [draft, setDraft] = useState(value)
   const seen = useRef(value)
-  const commit = useRef(setValue)
-  commit.current = setValue
+  const held = useRef(value)
+  useEffect(() => {
+    held.current = value
+  })
+  const commit = useDebouncedCallback((next: string) => {
+    // A phrase typed and erased inside the window ends where it began: nothing to write.
+    if (next === held.current) return
+    seen.current = next
+    setValue(next)
+  }, DEBOUNCE_MS)
 
   useEffect(() => {
     if (seen.current === value) return
     seen.current = value
     setDraft(value)
-  }, [value])
+    commit.cancel()
+  }, [value, commit])
 
-  useEffect(() => {
-    if (draft === value) return
-    const timer = setTimeout(() => {
-      seen.current = draft
-      commit.current(draft)
-    }, DEBOUNCE_MS)
-    return () => {
-      clearTimeout(timer)
-    }
-  }, [draft, value])
-
-  return { value: draft, set: setDraft }
+  return {
+    value: draft,
+    set: (next) => {
+      setDraft(next)
+      commit(next)
+    },
+  }
 }
 
 function SearchIcon(): ReactNode {

package/src/controls/select-filter.tsx

@@ -30,10 +30,11 @@
  * />
  */
 import type { ReactNode } from 'react'
-import type { BasaltProps } from '../common/props'
 import { assertRequiredProps } from '../common/validate'
-import type { EnumField, FieldHandle, StringField } from '../state'
+import type { EnumField, FieldHandle } from '../state'
+import type { StringField } from '../state/fields'
 import { EnumFilter } from './enum-filter'
+import type { UncontrolledProps } from './uncontrolled'
 
 /**
  * One row of a runtime catalogue. Wider than the store's own `FieldOption` by exactly one member:
@@ -47,7 +48,7 @@ export type FilterOption = {
   readonly disabled?: boolean
 }
 
-type SelectFilterCommon = BasaltProps & {
+type SelectFilterCommon = UncontrolledProps & {
   readonly label: string
   readonly icon?: ReactNode
   /** Adds a `Clear` action that writes the field back to its fallback. */
@@ -82,7 +83,7 @@ export function SelectFilter(props: SelectFilterStringProps): ReactNode
 export function SelectFilter<T extends string>(props: SelectFilterProps<T>): ReactNode {
   // F-ERR-1: without this, a `field` that never arrived surfaces as
   // `undefined is not an object (evaluating 'field.use')` from inside `EnumFilter`, caught by
-  // `BasaltErrorBoundary` and rendered as a blank subtree. `field` is not optional in the type, so
+  // `RootBoundary` and rendered as a blank subtree. `field` is not optional in the type, so
   // this only ever fires on untyped JS, a `props` object built at runtime, or a store key that
   // resolved to nothing — all three of which the message now names.
   assertRequiredProps('SelectFilter', props, ['field'], {

package/src/controls/sync-button.tsx

@@ -21,7 +21,7 @@
  * button relying on its visible children would be an unnamed icon on a phone.
  */
 import { ActionIcon, Button, Tooltip } from '@mantine/core'
-import { useEffect, useState } from 'react'
+import { useSyncExternalStore } from 'react'
 import type { ReactNode } from 'react'
 import { cx } from '../common/props'
 import type { BasaltProps } from '../common/props'
@@ -73,30 +73,28 @@ function toMillis(at: number | Date | null | undefined): number | undefined {
  * The age string, refreshed on an interval that exists ONLY while the component is mounted and
  * only while there is an age to show — a sync control on a background route costs no timer.
  *
- * The clock is read in the EFFECT, never during render. A global `SyncButton` in `globalActions`
- * renders inline in the shell header (no portal), so under SSR the server would emit `just now` and
- * a client hydrating a minute later would emit `1m ago` — a React text mismatch that discards the
- * subtree. Server and first client paint both omit the age; the effect fills it in after mount.
- * That also makes the interval the only thing that re-renders, so the old `setTick` counter is gone.
+ * The clock is read through `useSyncExternalStore`, whose server snapshot omits the age. A global
+ * `SyncButton` in `globalActions` renders inline in the shell header (no portal), so under SSR the
+ * server would emit `just now` and a client hydrating a minute later would emit `1m ago` — a React
+ * text mismatch that discards the subtree. Server and hydrating paint both omit the age; React
+ * re-renders with the client snapshot right after. The snapshot is the formatted label, a bucketed
+ * string (`just now`, `1m ago`, …), so it is stable across calls within a bucket and a tick only
+ * re-renders when the label changes. With no timestamp there is no subscription and no timer.
  */
 function useRelativeAge(at: number | Date | null | undefined): string | undefined {
-  const [age, setAge] = useState<string | undefined>(undefined)
   const timestamp = toMillis(at)
+  return useSyncExternalStore(
+    timestamp === undefined ? subscribeNever : subscribeAgeTick,
+    () => (timestamp === undefined ? undefined : formatAge(Date.now() - timestamp)),
+    () => undefined,
+  )
+}
 
-  useEffect(() => {
-    if (timestamp === undefined) {
-      setAge(undefined)
-      return
-    }
-    const publish = (): void => {
-      setAge(formatAge(Date.now() - timestamp))
-    }
-    publish()
-    const id = setInterval(publish, AGE_REFRESH_MS)
-    return () => clearInterval(id)
-  }, [timestamp])
+const subscribeNever = (): (() => void) => () => {}
 
-  return age
+function subscribeAgeTick(onTick: () => void): () => void {
+  const id = setInterval(onTick, AGE_REFRESH_MS)
+  return () => clearInterval(id)
 }
 
 function RefreshGlyph({ spinning }: { spinning: boolean }) {

package/src/controls/toggle-filter.tsx

@@ -13,14 +13,15 @@
 import { Switch } from '@mantine/core'
 import { useId } from 'react'
 import type { ReactNode } from 'react'
-import type { BasaltProps } from '../common/props'
 import { assertRequiredProps } from '../common/validate'
-import type { BooleanField, FieldHandle } from '../state'
+import type { FieldHandle } from '../state'
+import type { BooleanField } from '../state/fields'
 import { useFilterRegistration, useFilterSurface } from './filter-context'
 import { FilterPill } from './filter-pill'
 import { PanelRow } from './panel-row'
+import type { UncontrolledProps } from './uncontrolled'
 
-export type ToggleFilterProps = BasaltProps & {
+export type ToggleFilterProps = UncontrolledProps & {
   readonly field: FieldHandle<BooleanField>
   readonly label: string
   readonly icon?: ReactNode
@@ -28,7 +29,7 @@ export type ToggleFilterProps = BasaltProps & {
 
 export function ToggleFilter(props: ToggleFilterProps): ReactNode {
   // F-ERR-1 — without this a missing `field` surfaces as `undefined is not an object
-  // (evaluating 'field.use')`, caught by `BasaltErrorBoundary`.
+  // (evaluating 'field.use')`, caught by `RootBoundary`.
   assertRequiredProps('ToggleFilter', props, ['field'], {
     field: 'bind it to a store field (`store.field.<name>`), never a value/onChange pair.',
   })

package/src/controls/uncontrolled.ts

@@ -0,0 +1,12 @@
+import type { BasaltProps } from '../common/props'
+
+/**
+ * Law C2 as named slots: a basalt filter or tab owns its value through `field`, so `value`,
+ * `onChange` and `size` are typed `never` — the compile error names the mistake instead of
+ * reporting an unknown prop (`docs/V2-SPEC.md` §3).
+ */
+export type UncontrolledProps = BasaltProps & {
+  value?: never
+  onChange?: never
+  size?: never
+}

package/src/controls/view-tabs.tsx

@@ -30,13 +30,13 @@
 import { SegmentedControl, Select } from '@mantine/core'
 import type { ReactNode } from 'react'
 import { cx } from '../common/props'
-import type { BasaltProps } from '../common/props'
 import { assertRequiredProps } from '../common/validate'
 import type { EnumField, FieldHandle } from '../state'
 import classes from './controls.module.css'
 import { useFilterSurface } from './filter-context'
 import { useControlName } from './filter-sheet'
 import { PanelChoice, PanelRow, useTrackFits } from './panel-row'
+import type { UncontrolledProps } from './uncontrolled'
 
 /** Past three options the phone form is a `Select`, not a track. */
 const PHONE_TRACK_MAX = 3
@@ -48,7 +48,7 @@ export type ViewTabsOption<T extends string> = {
   readonly only?: 'sm-up' | 'sm-down'
 }
 
-export type ViewTabsProps<T extends string> = BasaltProps & {
+export type ViewTabsProps<T extends string> = UncontrolledProps & {
   readonly field: FieldHandle<EnumField<T>>
   /** Defaults to `field.options` (every declared value, labelled by `store.labels()`). */
   readonly options?: readonly ViewTabsOption<T>[]
@@ -64,7 +64,7 @@ export type ViewTabsProps<T extends string> = BasaltProps & {
 
 export function ViewTabs<T extends string>(props: ViewTabsProps<T>): ReactNode {
   // F-ERR-1 — without this a missing `field` surfaces as `undefined is not an object
-  // (evaluating 'field.use')`, caught by `BasaltErrorBoundary`.
+  // (evaluating 'field.use')`, caught by `RootBoundary`.
   assertRequiredProps('ViewTabs', props, ['field'], {
     field: 'bind it to a store field (`store.field.<name>`), never a value/onChange pair.',
   })

package/src/controls-dates/date-range-picker.tsx

@@ -29,7 +29,7 @@ import type { RangeCustomPickerProps } from '../controls/range-filter'
 
 export function DateRangePicker(props: RangeCustomPickerProps): ReactNode {
   // F-ERR-1 — without this a missing `value` surfaces as `undefined is not an object
-  // (evaluating 'value.from')`, caught by `BasaltErrorBoundary`.
+  // (evaluating 'value.from')`, caught by `RootBoundary`.
   assertRequiredProps('DateRangePicker', props, ['value'], {
     value: "pass `{ from, to }` — usually injected by `RangeFilter`'s `customPicker`.",
   })

package/src/controls-dates/index.ts

@@ -5,4 +5,3 @@
  * Proven from outside the package by `scripts/pack-test.sh`.
  */
 export { DateRangePicker } from './date-range-picker'
-export type { RangeCustomPickerProps } from '../controls/range-filter'

package/src/dashboard/index.ts

@@ -1,48 +1,7 @@
-export {
-  WidgetHeader,
-  type WidgetHeaderDeltaProps,
-  type WidgetHeaderMetricProps,
-  type WidgetHeaderProps,
-  type WidgetHeaderSlot,
-  type WidgetHeaderTier,
-  type WidgetHeaderTitleProps,
-} from './widget-header'
-export { DeltaBadge, type DeltaBadgeProps, type DeltaPolarity } from './delta-badge'
-export { Section, type SectionProps, type SectionSlot } from './section'
-export {
-  StatCard,
-  type StatCardBreakdownRow,
-  type StatCardProps,
-  type StatCardSlot,
-  type StatCardTone,
-} from './stat-card'
-export {
-  WidgetGrid,
-  type WidgetGridCols,
-  type WidgetGridItemProps,
-  type WidgetGridProps,
-} from './widget-grid'
-export { StatGroup, type StatGroupCols, type StatGroupProps } from './stat-group'
-export { EmptyState, type EmptyStateProps, type EmptyStateSlot } from './empty-state'
-export {
-  SettingsSection,
-  type SettingsSectionProps,
-  type SettingsSectionSlot,
-  SettingsRow,
-  type SettingsRowProps,
-  type SettingsRowSlot,
-  DangerZone,
-  type DangerZoneProps,
-} from './settings-section'
-export {
-  QueryState,
-  type QueryStateProps,
-  type QueryStateLike,
-  type QueryStateSlot,
-  type QueryStateTier,
-  type QueryEmptyCopy,
-  LoadingState,
-  type LoadingStateProps,
-  ErrorState,
-  type ErrorStateProps,
-} from './query-state'
+export { WidgetHeader } from './widget-header'
+export { DeltaBadge } from './delta-badge'
+export { Section } from './section'
+export { StatCard, type StatCardBreakdownRow, type StatCardTone } from './stat-card'
+export { StatGroup } from './stat-group'
+export { EmptyState } from './empty-state'
+export { SettingsSection, SettingsRow, DangerZone } from './settings-section'

package/src/dashboard/section.tsx

@@ -12,8 +12,7 @@
  *
  * `actions` and `tabs` are two separate `CtlSlot`-wrapped fragments rendered in the header row
  * (C1/C5) via `WidgetHeader`'s single `actions` slot; `tabs` hides while the section is collapsed.
- * `Section` holds ≤3 actions (C6) — past that, a dev-only `useValidateProps` message fires once per
- * title (the AST guard lands in wave 6).
+ * `Section` holds ≤3 actions (C6) — a fourth is a tsc error (the `SectionActions` type).
  *
  * `collapsible` state persists via `createPersistedState('basalt:section:<persistKey>')` when
  * `persistKey` is given, else it is local `useState` — the header always stays drawn, only the body
@@ -46,15 +45,15 @@
  *   <UsageChart />
  * </Section>
  */
-import { Children, useId } from 'react'
+import { useId } from 'react'
 import type { ReactNode } from 'react'
 import { cx } from '../common/props'
 import type { BasaltProps, SlotStylesProps } from '../common/props'
 import { BASALT_PREFIX } from '../common/errors'
 import { useValidateProps } from '../common/validate'
 import { CtlSlot } from '../theme'
-import { BarActionSlot, isBarActionList } from '../controls/actions'
-import type { SlotActions } from '../controls/actions'
+import { BarActionSlot } from '../controls/actions'
+import type { SectionActions } from '../controls/actions'
 import { useFilterSurface } from '../controls/filter-context'
 import { QueryState } from './query-state'
 import type { QueryEmptyCopy, QueryStateLike } from './query-state'
@@ -79,12 +78,10 @@ export type SectionProps = Omit<WidgetHeaderProps, 'tier' | 'classNames' | 'acti
   BasaltProps &
   SlotStylesProps<SectionSlot> & {
     /**
-     * Header actions, in either form (law C15): a typed `BarAction[]`, which basalt projects through
-     * the SAME row `PageBar` and `ActionGroup` use — ≤3 inline, the rest folded into `More`, one
-     * kebab below `sm` — or an opaque `ReactNode` a caller drew itself, rendered verbatim. The ≤3
-     * budget (C6) is checked against whichever form is given.
+     * Header actions as typed data (law C15), projected through the SAME row `PageBar` uses — one
+     * kebab below `sm`. At most three: a fourth is a tsc error (law C6, `docs/V2-SPEC.md` §3).
      */
-    actions?: SlotActions
+    actions?: SectionActions
     /**
      * The section's async result. Given one, the BODY renders through `QueryState` at the section
      * tier — pending / error-with-retry / empty each REPLACE `children`, data renders them — while
@@ -122,27 +119,6 @@ export type SectionProps = Omit<WidgetHeaderProps, 'tier' | 'classNames' | 'acti
     children: ReactNode
   }
 
-/**
- * ≤3 actions is C6 (docs/CONTROLS-SPEC.md §1) — the AST guard (`basalt/page-bar-budget`) lands in
- * wave 6; this is the dev-only stopgap so the budget is visible before the lint rule exists.
- *
- * Returns the message rather than logging it, because it is a {@link useValidateProps} check now:
- * it used to `console.warn` straight from the render body, which said it again on every keystroke
- * that re-rendered the page. The title is IN the message on purpose — the dedup key is
- * `${component} ${message}`, so two over-budget sections only both get heard because they name
- * themselves.
- */
-function actionBudgetMessage(title: string, actions: SlotActions): string | null {
-  // Both arms of the union are counted, and the typed one is counted EXACTLY: `Children.count` over
-  // a `BarAction[]` would report the array's length as one child.
-  const count = isBarActionList(actions) ? actions.length : Children.count(actions)
-  if (count <= 3) return null
-  return (
-    `${BASALT_PREFIX} Section "${title}": ${count} actions exceeds the ≤3 budget ` +
-    '(docs/CONTROLS-SPEC.md C6) — move the rest behind a menu.'
-  )
-}
-
 function ChevronToggle({
   open,
   onToggle,
@@ -196,13 +172,9 @@ export function Section({
 }: SectionProps) {
   const { title } = headerProps
 
-  // Two dev-only checks, one hook — both are misuses that RENDER fine, which is what puts them in
-  // `useValidateProps` rather than in `assertRequiredProps`.
-  //
-  //  1. A `persistKey` with nothing to fold writes a localStorage key nobody ever reads back — the
-  //     shape a consumer lands on after deleting `collapsible` and leaving the key behind.
-  //  2. More than three header actions (C6). This used to `console.warn` from the render body, so a
-  //     page that re-rendered on every keystroke reprinted it every keystroke.
+  // A `persistKey` with nothing to fold writes a localStorage key nobody ever reads back — the
+  // shape a consumer lands on after deleting `collapsible` and leaving the key behind. It renders
+  // fine, which is what puts it in `useValidateProps` rather than in `assertRequiredProps`.
   useValidateProps(
     'Section',
     () => [
@@ -210,9 +182,8 @@ export function Section({
         ? `${BASALT_PREFIX} Section "${title}": \`persistKey\` is set but \`collapsible\` is ` +
           'false — there is no fold to persist. Add `collapsible`, or drop `persistKey`.'
         : null,
-      actions === undefined ? null : actionBudgetMessage(title, actions),
     ],
-    [persistKey, collapsible, title, actions],
+    [persistKey, collapsible, title],
   )
 
   const [open, setOpen] = usePersistedOrLocal({