basalt-ui 1.26.0 → 1.28.0

package/src/commands/overlays-mount.tsx

@@ -2,9 +2,16 @@
  * overlays-mount — composable overlay mount for basalt-ui apps.
  *
  * `BasaltOverlays` bundles ModalsProvider, Spotlight, and Notifications into a single mount point.
- * Put it inside BasaltProvider, before the router. It replaces the standalone `<BasaltNotifications />`
- * from `basalt-ui/notifications` — do NOT mount both `<BasaltOverlays notifications />` and
- * `<BasaltNotifications />` in the same tree (double-mount of `<Notifications />`).
+ * Put it inside BasaltProvider, before the router. It replaces the standalone
+ * `<BasaltNotifications />` from `basalt-ui/notifications` — do NOT mount both
+ * `<BasaltOverlays notifications />` and `<BasaltNotifications />` in the same tree (double-mount
+ * of `<Notifications />`).
+ *
+ * Every layer — ModalsProvider included — mounts as a SIBLING of `children`, never as a wrapper:
+ * see the comment in the component body (R1). `@mantine/modals`' imperative API (`modals.open*`,
+ * and so basalt's own `overlays.open`) is a window CustomEvent bus that ModalsProvider subscribes
+ * to, so nothing needs to be inside it; the one thing a sibling cannot serve is Mantine's
+ * `useModals()` context hook.
  *
  * Each overlay system is opt-in via props (all default to true). Use flags to disable layers the
  * app does not need — e.g. a charts-only app that has no commands can set `spotlight={false}`.
@@ -55,8 +62,10 @@ import type { NotificationsProps } from '@mantine/notifications'
 import type { SpotlightActionData } from '@mantine/spotlight'
 import { runCommand } from './define-commands'
 import type { CommandId } from './define-commands'
+import { useModalsLayer } from './define-overlays'
 import { toSpotlightActions } from './projectors'
 import { useCommandHotkeys } from './useCommandHotkeys'
+import { useNotificationsMountGuard } from '../notifications/mount-guard'
 
 // ── Lazy @mantine/spotlight resolution (module-wide singleton) ────────────────
 
@@ -149,8 +158,9 @@ export type BasaltOverlaysProps = {
   children: ReactNode
 }
 
-// ── Lazy ModalsProvider (falls back to a passthrough fragment) ────────────────
+// ── Lazy ModalsProvider (falls back to rendering nothing) ─────────────────────
 
+/** Missing-peer fallback. Mounted childless (see BasaltOverlays), so it renders nothing. */
 function PassthroughFragment({ children }: ModalsProviderProps) {
   return <>{children}</>
 }
@@ -160,6 +170,7 @@ const LazyModalsProvider = lazy(() =>
     .then((m) => ({ default: m.ModalsProvider }))
     .catch(() => ({ default: PassthroughFragment })),
 )
+Object.assign(LazyModalsProvider, { displayName: 'LazyModalsProvider' })
 
 // ── Lazy SpotlightMount (falls back to rendering nothing) ─────────────────────
 
@@ -215,6 +226,7 @@ const LazySpotlightMount = lazy<
     })
     .catch(() => ({ default: NullFallback })),
 )
+Object.assign(LazySpotlightMount, { displayName: 'LazySpotlightMount' })
 
 // ── Lazy Notifications (falls back to rendering nothing) ──────────────────────
 
@@ -227,6 +239,29 @@ const LazyNotifications = lazy<ComponentType<NotificationsProps>>(() =>
     .then((m) => ({ default: m.Notifications as ComponentType<NotificationsProps> }))
     .catch(() => ({ default: NotificationsFallback })),
 )
+Object.assign(LazyNotifications, { displayName: 'LazyNotifications' })
+
+// ── NotificationsLayer (runs the shared duplicate-mount guard, F15) ───────────
+
+/** Wraps `LazyNotifications` so `useNotificationsMountGuard` only fires while this layer is
+ * actually enabled — a sibling of `BasaltNotifications` importing the SAME shared counter. */
+function NotificationsLayer({
+  notificationsProps,
+}: {
+  notificationsProps: Omit<NotificationsProps, 'children'> | undefined
+}) {
+  useNotificationsMountGuard()
+  return (
+    <Suspense fallback={null}>
+      <LazyNotifications
+        position="bottom-right"
+        autoClose={4000}
+        limit={5}
+        {...notificationsProps}
+      />
+    </Suspense>
+  )
+}
 
 // ── HotkeysMount (inner component — ensures hook is inside component tree) ────
 
@@ -239,9 +274,9 @@ function HotkeysMount() {
 // ── BasaltOverlays ────────────────────────────────────────────────────────────
 
 /**
- * Composable overlay mount — wraps children in ModalsProvider and renders Spotlight +
- * Notifications siblings. All three layers are enabled by default; pass `false` to disable.
- * A disabled layer's optional peer is never imported.
+ * Composable overlay mount — renders ModalsProvider, Spotlight and Notifications as siblings of
+ * `children`. All three layers are enabled by default; pass `false` to disable. A disabled layer's
+ * optional peer is never imported.
  *
  * Mount exactly ONE BasaltOverlays per app. Do NOT combine with a standalone
  * `<BasaltNotifications />` from `basalt-ui/notifications` — that would double-mount
@@ -264,7 +299,20 @@ export function BasaltOverlays({
   projectCommands = true,
   children,
 }: BasaltOverlaysProps) {
-  const content = (
+  // Register the modals layer this mount serves, so `overlays.confirm` can reject with a named
+  // error instead of returning a promise nothing will ever settle (nothing subscribes to the modals
+  // event bus when no provider is up). With `modals={false}` nothing is registered here — a
+  // consumer mounting `<ModalsProvider>` themselves calls `registerModalsProvider()` instead.
+  useModalsLayer(enableModals)
+
+  // `children` sits OUTSIDE every Suspense boundary, and that is load-bearing (R1): React.lazy
+  // suspends on its first render even when the module is already warm, so a boundary wrapping the
+  // app defers the app's FIRST COMMIT past a microtask tick. TanStack Router's async loadMatches
+  // then resolves into that window and setStates onto the not-yet-mounted Transitioner fiber —
+  // "Can't perform a React state update on a component that hasn't mounted yet". The old shape
+  // also rendered `children` twice (once as the fallback, once resolved), running every effect in
+  // the app in both trees. Never put `children` under a lazy boundary here.
+  return (
     <>
       {enableSpotlight && (
         <Suspense fallback={null}>
@@ -274,28 +322,14 @@ export function BasaltOverlays({
           />
         </Suspense>
       )}
-      {enableNotifications && (
+      {enableNotifications && <NotificationsLayer notificationsProps={notificationsProps} />}
+      {enableHotkeys && <HotkeysMount />}
+      {enableModals && (
         <Suspense fallback={null}>
-          <LazyNotifications
-            position="bottom-right"
-            autoClose={4000}
-            limit={5}
-            {...notificationsProps}
-          />
+          <LazyModalsProvider />
         </Suspense>
       )}
-      {enableHotkeys && <HotkeysMount />}
       {children}
     </>
   )
-
-  if (enableModals) {
-    return (
-      <Suspense fallback={<>{content}</>}>
-        <LazyModalsProvider>{content}</LazyModalsProvider>
-      </Suspense>
-    )
-  }
-
-  return <>{content}</>
 }

package/src/common/errors.ts

@@ -0,0 +1,73 @@
+/**
+ * The message table (Blueprint audit §3). Every basalt diagnostic — thrown or logged — is built
+ * here, so the prefix, the `Component: …` shape and the em-dash-then-remedy rhythm are one decision
+ * instead of 60. It is the generalisation of `assertQueryStateLike`, which was the ONLY component
+ * in the library naming itself in its own failure (isomorphic finding F-ERR-1: the other 54 fail as
+ * raw `TypeError`s that `BasaltErrorBoundary` swallows into a blank subtree).
+ *
+ * Every builder returns a string; nothing here throws or logs. The caller decides which it is —
+ * `assertRequiredProps` throws, `useValidateProps` logs, the mount guards log.
+ */
+
+/** The one namespace every basalt message opens with. */
+export const BASALT_PREFIX = '[basalt]'
+
+function message(component: string, body: string): string {
+  return `${BASALT_PREFIX} ${component}: ${body}`
+}
+
+/**
+ * A prop the component reads into and cannot render without. This is the F-ERR-1 message: the
+ * component names itself and the prop, instead of the read landing as
+ * `undefined is not an object (evaluating 'field.use')`.
+ */
+export function requiredProp(component: string, prop: string, hint?: string): string {
+  return message(component, `prop "${prop}" is required${hint === undefined ? '.' : ` — ${hint}`}`)
+}
+
+/** A prop with a closed value set that got something outside it. */
+export function oneOf(
+  component: string,
+  prop: string,
+  allowed: readonly string[],
+  got: unknown,
+): string {
+  return message(
+    component,
+    `prop "${prop}" must be one of ${allowed.map((value) => `'${value}'`).join(' | ')} — ` +
+      `got ${JSON.stringify(got)}.`,
+  )
+}
+
+/**
+ * A prop still shipped and still working, with a named successor and the version it goes away in.
+ * Majors are banned here, so the deprecation notice IS the migration channel.
+ */
+export function deprecatedProp(
+  component: string,
+  oldProp: string,
+  newProp: string,
+  removeIn: string,
+): string {
+  return message(
+    component,
+    `prop "${oldProp}" is deprecated — use "${newProp}" instead. "${oldProp}" is removed in ${removeIn}.`,
+  )
+}
+
+/**
+ * An imperative call needs a layer that is not there — the optional peer is not installed, or the
+ * mount that subscribes to its event bus is disabled. Both halves are named because the remedy
+ * differs: install it, or stop turning it off.
+ */
+export function missingLayer(component: string, layer: string, remedy: string): string {
+  return message(component, `needs ${layer}, which is not available — ${remedy}.`)
+}
+
+/** A single-mount component found a second instance alive (`BasaltProvider`, `Notifications`). */
+export function duplicateMount(component: string): string {
+  return message(
+    component,
+    'more than one instance is mounted at once — mount exactly one, at the app root.',
+  )
+}

package/src/common/index.ts

@@ -0,0 +1,21 @@
+/**
+ * `common` — the prop, ref, message and validation primitives every basalt component shares.
+ *
+ * Not a published subpath: the pieces are re-exported from the root barrel (`.`) so a consumer has
+ * one import, and `src/surfaces.ts` stays the SSOT for real subpaths. The module is Mantine-free by
+ * rule (`.oxlintrc.json`) and by test (`boundary.test.ts`), so the Mantine-free half of the library
+ * may reach it too.
+ */
+export { type BasaltProps, type SlotClassNames, type SlotStylesProps } from './props'
+export { type Tone, type ToneWithNeutral, type Tier, cx } from './props'
+export { assignRef, mergeRefs } from './refs'
+export {
+  BASALT_PREFIX,
+  requiredProp,
+  oneOf,
+  deprecatedProp,
+  duplicateMount,
+  missingLayer,
+} from './errors'
+export { useValidateProps, assertRequiredProps, resetValidatedProps } from './validate'
+export { scrollParentOf, SCROLLPORT_ATTRIBUTE } from './scroll-parent'

package/src/common/props.ts

@@ -0,0 +1,71 @@
+/**
+ * The prop vocabulary every basalt component shares (Blueprint audit §1, isomorphic finding C8).
+ *
+ * The finding this file answers: 98 of 123 exported components drop `className`, so a consumer who
+ * needs one margin has to fork the component. Fixing that per component is 79 edits; fixing it once
+ * here is one — every component's props type extends `BasaltProps`, and the root element takes
+ * `cx(classes.root, className)` plus `style`.
+ *
+ * **`className` + per-slot `classNames`, and nothing else.** No `styles` object, no `vars`: basalt
+ * does not spread `...rest` onto the DOM (which is why the harness saw zero unknown-attribute
+ * warnings), and a `styles`/`vars` surface would re-open the styling seam Mantine already owns for
+ * the primitives underneath. A composite that needs more than its root styled declares its SLOT
+ * NAMES in its own props type — `SlotStylesProps<'root' | 'header' | 'body'>` — so the slot set is
+ * a documented, compiler-checked union rather than an open record.
+ *
+ * This module is **Mantine-free and React-type-only** so `./charts` and `./tokens` may reach it
+ * without breaching the layer boundary (`common/boundary.test.ts` pins that, and `.oxlintrc.json`
+ * bans `@mantine/*` here the same way it does for `state`/`query`/`guard`).
+ */
+import type { CSSProperties } from 'react'
+
+/**
+ * The base every basalt component accepts. `| undefined` is explicit on both members because
+ * `exactOptionalPropertyTypes` is on: a component destructuring `className` and forwarding it to a
+ * child would otherwise fail to type-check at every call site.
+ */
+export interface BasaltProps {
+  /** Appended to the root element's own class — never replaces it. */
+  readonly className?: string | undefined
+  /** Merged onto the root element's own inline style, if it has one. */
+  readonly style?: CSSProperties | undefined
+}
+
+/** One class per named slot. The slot union is the component's documented contract. */
+export type SlotClassNames<S extends string> = Partial<Record<S, string>>
+
+/**
+ * The composite half of the contract: a container that paints more than one box publishes its slot
+ * names here. The set is small on purpose — `Section`, `StatCard`, `ChartCard`, `PageBar`,
+ * `PageAside`, `WidgetHeader`, `EmptyState`, `QueryState`, `BasaltDataTable`. A leaf takes
+ * `BasaltProps` alone.
+ */
+export interface SlotStylesProps<S extends string> {
+  readonly classNames?: SlotClassNames<S> | undefined
+}
+
+/**
+ * The ONE status vocabulary (audit A13). Five forks exist today — `StatCardTone` and
+ * `SidebarBlockTone` are byte-identical to this, `CalloutKind` / `AccountBadgeTone` /
+ * `NotificationIntent` each differ — and they stay put for now: an adopter aliases its fork to this
+ * type, it does not get renamed out from under a consumer.
+ */
+export type Tone = 'good' | 'warn' | 'bad'
+
+/** `Tone` plus the un-toned state — a badge or a block with nothing to say yet. */
+export type ToneWithNeutral = Tone | 'neutral'
+
+/**
+ * The heading tier (`docs/CONTROLS-SPEC.md` §2.2). Re-exported from its owner rather than declared
+ * twice — `WidgetHeaderTier` stays the name on the public barrel; `Tier` is what `common`-aware
+ * code spells. Type-only, so this file emits no runtime edge into the Mantine-coupled half.
+ */
+export type { WidgetHeaderTier as Tier } from '../widget-header/widget-header'
+
+/**
+ * The class joiner. Replaces the `[a, b].filter(Boolean).join(' ')` spelled out in seven files
+ * today; falsy parts drop, so `cx(classes.root, open && classes.open, className)` is the idiom.
+ */
+export function cx(...parts: Array<string | false | null | undefined>): string {
+  return parts.filter((part): part is string => typeof part === 'string' && part !== '').join(' ')
+}

package/src/common/query-state-like.ts

@@ -0,0 +1,64 @@
+/**
+ * The query envelope every basalt container reads, and the ONE runtime assertion that stands in for
+ * the compiler over it.
+ *
+ * It lives in `common/` because two independent readers grew their own copy and the copies
+ * DISAGREED: `QueryState` (`dashboard/query-state.tsx`) checked the `data` key and that `refetch` is
+ * a function; `dataQueryBranch` (`data/query-branch.ts`) checked neither, so the table accepted a
+ * result whose Retry button did nothing. A validator that exists twice is a validator with two
+ * strictnesses, which is exactly the class of defect the assertion exists to catch.
+ *
+ * Mantine-free by construction (`common/boundary.test.ts`): types, a set and a throw.
+ */
+
+/**
+ * The structural subset of a TanStack `UseQueryResult` these components read.
+ *
+ * Typed as a SUBSET rather than as `UseQueryResult<T>` on purpose: a composed, derived or
+ * hand-rolled result must be passable without a cast, and the components stay independent of which
+ * `@tanstack/react-query` major a consumer pins. This is NOT a claim that the root barrel is free of
+ * that package — `./connectivity` imports `onlineManager` as a value and is re-exported from
+ * `src/index.ts`. The cost of the subset is that the compiler stops policing the shape — which is
+ * why {@link assertQueryStateLike} checks it at runtime.
+ */
+export type QueryStateLike<TData> = {
+  data: TData | undefined
+  isError: boolean
+  error: unknown
+  fetchStatus: 'fetching' | 'paused' | 'idle'
+  refetch: () => unknown
+}
+
+/** The three `fetchStatus` values a `UseQueryResult` can carry. */
+export const FETCH_STATUSES: ReadonlySet<string> = new Set(['fetching', 'paused', 'idle'])
+
+/**
+ * `QueryStateLike` is a structural subset, so TypeScript cannot protect a hand-composed result the
+ * way it protects a real `UseQueryResult` — and every field it drops fails SILENTLY in the exact
+ * direction these components exist to prevent. A missing `isError` renders "no data" over a 500. A
+ * misspelled `fetchStatus` never leaves the spinner. A missing `refetch` renders a Retry button that
+ * does nothing. Each of those is a false claim about the data, so it throws.
+ *
+ * `component` opens the message so the throw names the container that got the bad envelope —
+ * `QueryState`, `BasaltDataTable`, `BasaltVirtualList` all read the same shape.
+ */
+export function assertQueryStateLike(
+  component: string,
+  query: unknown,
+): asserts query is QueryStateLike<unknown> {
+  const bad = (detail: string): never => {
+    throw new Error(
+      `${component}: \`query\` ${detail}. It must carry { data, isError, error, fetchStatus, refetch } — ` +
+        'a TanStack UseQueryResult does; a hand-composed one must spell every field, because a ' +
+        'missing branch flag renders a false claim about the data instead of an error.',
+    )
+  }
+  if (query === null || typeof query !== 'object')
+    bad(`is ${query === null ? 'null' : typeof query}`)
+  const q = query as Record<string, unknown>
+  if (!('data' in q)) bad('has no `data` key')
+  if (typeof q['isError'] !== 'boolean') bad('has no boolean `isError`')
+  if (typeof q['fetchStatus'] !== 'string' || !FETCH_STATUSES.has(q['fetchStatus']))
+    bad(`has fetchStatus=${JSON.stringify(q['fetchStatus'])}, not 'fetching' | 'paused' | 'idle'`)
+  if (typeof q['refetch'] !== 'function') bad('has no `refetch()`')
+}

package/src/common/refs.ts

@@ -0,0 +1,58 @@
+/**
+ * Ref plumbing for composites (Blueprint audit §2). React 19 made `ref` an ordinary prop, which
+ * removed `forwardRef` — it did NOT remove the need to merge: a component that both forwards its
+ * caller's ref and keeps its own (a measurement, a focus target) still has two refs and one node.
+ *
+ * The React 19 wrinkle these two functions exist to get right: a callback ref MAY return a cleanup
+ * function, and when it does React never calls it again with `null`. So merging cannot just fan out
+ * — it has to fan out the cleanups too, and null out the refs that returned none.
+ */
+import type { Ref, RefCallback } from 'react'
+
+/**
+ * Writes `value` into one ref of either shape.
+ *
+ * @returns the callback ref's own cleanup when it returned one, else `undefined`.
+ */
+export function assignRef<T>(ref: Ref<T> | undefined, value: T | null): (() => void) | undefined {
+  if (ref === undefined || ref === null) return undefined
+  if (typeof ref === 'function') {
+    const cleanup = ref(value)
+    return typeof cleanup === 'function' ? cleanup : undefined
+  }
+  // `@types/react` 19 types `RefObject.current` as MUTABLE — the readonly `current` that forced a
+  // cast here was the React 18 `RefObject`, and `Ref<T>` now narrows to `RefObject<T | null>`.
+  ref.current = value
+  return undefined
+}
+
+/**
+ * Fans one node out to several refs.
+ *
+ * Returns a NEW function on every call, so a component that passes it straight to JSX re-attaches
+ * on every render — wrap it in `useCallback`/`useMemo` over the refs it merges when the node is
+ * expensive to re-attach.
+ *
+ * @example
+ * const merged = useMemo(() => mergeRefs(ref, localRef), [ref])
+ * return <div ref={merged} />
+ */
+export function mergeRefs<T>(...refs: Array<Ref<T> | undefined>): RefCallback<T> {
+  return (value: T | null) => {
+    const cleanups = refs.map((ref) => assignRef(ref, value))
+    // No child returned a cleanup → stay on React's legacy path and let it call us with `null`.
+    if (cleanups.every((cleanup) => cleanup === undefined)) return undefined
+    // At least one did → React will call THIS instead of re-invoking with `null`, so the refs that
+    // returned no cleanup have to be cleared here or they keep pointing at a detached node.
+    return () => {
+      refs.forEach((ref, index) => {
+        const cleanup = cleanups[index]
+        if (cleanup !== undefined) {
+          cleanup()
+          return
+        }
+        assignRef(ref, null)
+      })
+    }
+  }
+}

package/src/common/scroll-parent.ts

@@ -0,0 +1,42 @@
+/**
+ * `scrollParentOf` — which box actually scrolls `el`.
+ *
+ * Since `BasaltShell` made `AppShell.Main` the scrollport (`shell/app-main.module.css`), the
+ * document no longer scrolls inside a shell: `window.scrollY` is pinned at 0 and a `scroll`
+ * listener on `window` never fires. Everything in the package that reacted to page scroll had to
+ * stop asking the window and start asking whichever ancestor is really scrolling — and it has to
+ * keep working in a SHELL-LESS app, where the answer genuinely is the window.
+ *
+ * `null` IS the answer for "the document scrolls this", not a failure — callers listen on `window`
+ * and read `window.scrollY` in that case.
+ */
+
+/** The attribute `BasaltShell` puts on `AppShell.Main`. Also the public handle for a consumer. */
+export const SCROLLPORT_ATTRIBUTE = 'data-basalt-scrollport'
+
+function isScrollport(element: HTMLElement): boolean {
+  // The declared handle wins outright: Main is a scrollport by construction even on the frame where
+  // its content is short enough that `scrollHeight === clientHeight`.
+  if (element.hasAttribute(SCROLLPORT_ATTRIBUTE)) return true
+  const overflowY = getComputedStyle(element).overflowY
+  if (overflowY !== 'auto' && overflowY !== 'scroll') return false
+  return element.scrollHeight > element.clientHeight
+}
+
+/**
+ * The nearest scrolling ANCESTOR of `el`, or `null` when the document is the scroller.
+ *
+ * `el` itself is never considered — the question is which box scrolls it, not whether it scrolls
+ * its own children. `<body>` and `<html>` are never returned either: an app that scrolls at the
+ * document level is exactly the `null` case.
+ */
+export function scrollParentOf(el: Element | null): HTMLElement | null {
+  if (el === null || typeof window === 'undefined') return null
+  const root = el.ownerDocument.documentElement
+  let node = el.parentElement
+  while (node !== null && node !== root && node !== el.ownerDocument.body) {
+    if (isScrollport(node)) return node
+    node = node.parentElement
+  }
+  return null
+}

package/src/common/validate.ts

@@ -0,0 +1,94 @@
+/**
+ * Prop validation, in the two shapes basalt actually needs (Blueprint audit §3, isomorphic finding
+ * F-ERR-1).
+ *
+ * The split is the design: a MISUSE that would crash anyway throws immediately with a written
+ * message (`assertRequiredProps`), while a misuse that merely renders something the caller did not
+ * mean warns once in dev and renders on (`useValidateProps`).
+ */
+import { useEffect } from 'react'
+import { isDev } from '../utils/is-dev'
+import { requiredProp } from './errors'
+
+/** A check returns the message(s) it has, or nothing. `null`/`undefined` entries are ignored. */
+type CheckResult = string | null | undefined | Array<string | null | undefined>
+
+/**
+ * Module-level so the once-per-message promise survives a re-render, a remount, and a second
+ * instance of the same component. A dev warning is about the CODE, and printing it per render is
+ * how a real warning gets scrolled out of the console. Keyed by `component` + message, so two
+ * different faults in one component both get said.
+ */
+const reported = new Set<string>()
+
+/**
+ * Dev-only prop validation. `console.error`s each message ONCE per `(component, message)` pair, and
+ * is a no-op in production: `isDev()` reads `process.env.NODE_ENV`, which every bundler
+ * constant-folds, so the whole body disappears from a production build.
+ *
+ * **The dedup key is `${component} ${message}`, and nothing else** — not the instance, not the
+ * props. Two instances of one component producing the SAME message say it once between them, which
+ * is the intent (a dev warning is about the code). A caller that wants it said per instance has to
+ * embed the identifying context IN the message — the title, the persist key, the field name — the
+ * way `Section` writes `Section "<title>": …`. A message built from nothing instance-specific is a
+ * message the second faulty call site never gets.
+ *
+ * @example
+ * useValidateProps(
+ *   'Section',
+ *   () => (persistKey !== undefined && !collapsible ? sectionPersistMessage : null),
+ *   [persistKey, collapsible],
+ * )
+ */
+export function useValidateProps(
+  component: string,
+  check: () => CheckResult,
+  deps: unknown[],
+): void {
+  useEffect(() => {
+    if (!isDev()) return
+    const result = check()
+    const messages = Array.isArray(result) ? result : [result]
+    for (const raw of messages) {
+      if (raw === null || raw === undefined) continue
+      const key = `${component} ${raw}`
+      if (reported.has(key)) continue
+      reported.add(key)
+      console.error(raw)
+    }
+    // The deps ARE the caller's contract: this hook cannot know what `check` closes over.
+    // oxlint-disable-next-line react-hooks/exhaustive-deps -- the caller owns the dep list
+  }, deps)
+}
+
+/** Test seam. The once-per-message Set is module state, so a suite has to be able to clear it. */
+export function resetValidatedProps(): void {
+  reported.clear()
+}
+
+/**
+ * THROWS on a missing required prop, in every build, before the component reads into it.
+ *
+ * This is the F-ERR-1 remedy, and the reason it is not dev-gated: the component was going to crash
+ * either way (`undefined is not an object (evaluating 'field.use')`), so the only thing in question
+ * is whether the stack reaching `BasaltErrorBoundary` names the component and the prop. It does
+ * now. A prop that is merely questionable belongs in `useValidateProps`, not here.
+ *
+ * @example
+ * assertRequiredProps('SelectFilter', props, ['field'])
+ */
+export function assertRequiredProps<P extends object>(
+  component: string,
+  props: P,
+  keys: ReadonlyArray<Extract<keyof P, string>>,
+  hints?: Partial<Record<Extract<keyof P, string>, string>>,
+): void {
+  for (const key of keys) {
+    const value = (props as Record<string, unknown>)[key]
+    if (value !== undefined && value !== null) continue
+    const hint = hints?.[key]
+    throw new Error(
+      hint === undefined ? requiredProp(component, key) : requiredProp(component, key, hint),
+    )
+  }
+}

package/src/connectivity/connectivity-indicator.tsx

@@ -16,10 +16,13 @@
 import { ActionIcon, Badge, Divider, Group, Popover, Stack, Text } from '@mantine/core'
 import { useDisclosure } from '@mantine/hooks'
 import { useRef } from 'react'
+import type { BasaltProps } from '../common/props'
 import { alpha, VX } from '../tokens'
 import { useConnectivity } from './use-connectivity'
 import type { ConnectivityStatus } from './types'
 
+export type ConnectivityIndicatorProps = BasaltProps
+
 const HOVER_OPEN_DELAY = 150
 const HOVER_CLOSE_DELAY = 200
 
@@ -180,7 +183,7 @@ const ICON_COLOR: Record<ConnectivityStatus, string> = {
  *   {...rest}
  * />
  */
-export function ConnectivityIndicator() {
+export function ConnectivityIndicator({ className, style }: ConnectivityIndicatorProps = {}) {
   const [opened, { open, toggle, close }] = useDisclosure(false)
   const { status, details } = useConnectivity()
   const statusCfg = STATUS_CONFIG[status]
@@ -215,6 +218,8 @@ export function ConnectivityIndicator() {
           aria-label={statusCfg.label}
           aria-expanded={opened}
           aria-haspopup="dialog"
+          {...(className !== undefined && { className })}
+          {...(style !== undefined && { style })}
         >
           <WifiIcon />
         </ActionIcon>

package/src/connectivity/connectivity-provider.tsx

@@ -16,7 +16,10 @@ const SSR_SNAPSHOT: ConnectivitySnapshot = {
   status: 'online',
   details: {
     browserOnline: true,
-    queryOnline: null,
+    // Optimistic `true`, matching `browserOnline` — `onlineManager` is a module singleton so it is
+    // always readable, this is the same pre-hydration default as every other signal, never the
+    // "not mounted" case (see `ConnectivitySnapshot['details']['queryOnline']`'s JSDoc).
+    queryOnline: true,
     sseOpen: null,
     healthPassing: null,
   },

package/src/connectivity/index.ts

@@ -9,6 +9,7 @@
 
 export { ConnectivityProvider } from './connectivity-provider'
 export { ConnectivityIndicator } from './connectivity-indicator'
+export type { ConnectivityIndicatorProps } from './connectivity-indicator'
 export { useConnectivity } from './use-connectivity'
 export type {
   ConnectivityStatus,

package/src/connectivity/types.ts

@@ -13,7 +13,10 @@ export type ConnectivitySnapshot = {
   /** Per-signal breakdown for debugging / detailed indicators */
   details: {
     browserOnline: boolean // navigator.onLine
-    queryOnline: boolean | null // React Query onlineManager — null when QueryClient not mounted
+    // React Query onlineManager — a module-level singleton, so it is always readable regardless of
+    // whether a QueryClient is mounted; never null on the client (the pre-hydration SSR snapshot
+    // reports an optimistic `true`, matching `browserOnline`, rather than an "unknown" null).
+    queryOnline: boolean
     sseOpen: boolean | null // EventSource readyState === OPEN — null when no sseUrl configured
     healthPassing: boolean | null // /health ping succeeded — null when no healthUrl configured
   }
@@ -21,7 +24,7 @@ export type ConnectivitySnapshot = {
 
 export type ConnectivityOverride = {
   browserOnline?: boolean
-  queryOnline?: boolean | null
+  queryOnline?: boolean
   sseOpen?: boolean | null
   healthPassing?: boolean | null
 }