basalt-ui 1.26.0 → 1.28.0

package/src/notifications/index.ts

@@ -19,6 +19,10 @@
  * notifyError('Failed', { title: 'Upload error' })
  * notifyPromise(save(), { loading: 'Saving…', success: 'Saved', error: 'Failed' })
  *
+ * // Optimistic mutation with an undo window (the toast's autoClose IS the window):
+ * import { notifyUndo } from 'basalt-ui/notifications'
+ * notifyUndo({ message: 'Item deleted', onUndo: () => restore(), onExpire: () => api.delete(id) })
+ *
  * // Shell bell (globalActions slot):
  * <BasaltShell globalActions={[{ key: 'notifications', node: <NotificationBell />, mobile: 'bar' }]} ... />
  */
@@ -31,8 +35,15 @@ export {
   notifyWarning,
   notifyInfo,
   notifyPromise,
+  notifyUndo,
+  notifyUndoable,
+} from './notify'
+export type {
+  NotifyOptions,
+  NotifyPromiseMessages,
+  NotifyUndoOptions,
+  NotifyUndoHandle,
 } from './notify'
-export type { NotifyOptions, NotifyPromiseMessages } from './notify'
 
 // ── defineNotification + defineNotifications + typed emit ─────────────────────
 export {

package/src/notifications/mount-guard.ts

@@ -0,0 +1,41 @@
+/**
+ * Duplicate-Notifications-mount guard (F15) — a shared module-level counter, not a per-caller ref,
+ * because the whole point is detecting a SECOND, unrelated caller: `<BasaltOverlays notifications />`
+ * (`commands/overlays-mount.tsx`) and `<BasaltNotifications />` (`./overlay.tsx`) both render
+ * Mantine's `<Notifications />` and neither can see the other mount. `overlays-mount.tsx`'s own
+ * JSDoc has warned against combining them since it shipped ("do NOT mount both … (double-mount of
+ * `<Notifications />`)") with nothing enforcing it — this is that enforcement, finally.
+ *
+ * Lives here (`./notifications`), not `./commands`, so `commands` is the one importing a shared util
+ * rather than the reverse — `./notifications` never depends on `./commands`. Zero `@mantine/*`
+ * import, so pulling it into `commands` does not eagerly load `@mantine/notifications`.
+ *
+ * Not exported from the `./notifications` public barrel (`index.ts`) — internal wiring only, same
+ * as `provider/lab-theme.ts`.
+ */
+import { useEffect } from 'react'
+import { isDev } from '../utils/is-dev'
+
+let mountedNotificationsCount = 0
+
+/**
+ * Call from any component that renders a `<Notifications />` overlay. Warns in dev when a second
+ * caller is mounted at the same time. Not a false positive under React 18 StrictMode's double-invoke
+ * (that mounts/unmounts the SAME instance in sequence, so the count returns to 0 before a genuine
+ * second instance could exist).
+ */
+export function useNotificationsMountGuard(): void {
+  useEffect(() => {
+    mountedNotificationsCount++
+    if (mountedNotificationsCount > 1 && isDev()) {
+      console.warn(
+        '[basalt] more than one Notifications overlay is mounted at once — mount ONE of ' +
+          '<BasaltOverlays notifications /> or <BasaltNotifications />, never both (they both ' +
+          "render Mantine's <Notifications />, so toasts would double-fire).",
+      )
+    }
+    return () => {
+      mountedNotificationsCount--
+    }
+  }, [])
+}

package/src/notifications/notify.tsx

@@ -7,7 +7,8 @@
  *   2. dedupKey window — module-level Map prevents duplicate keys within 1500ms
  *
  * For loading→success/error transitions use notifyPromise — it calls notifications.update
- * (never show()) so the loading state is replaced correctly.
+ * (never show()) so the loading state is replaced correctly. For an optimistic mutation with a
+ * grace period use notifyUndo — one number is both the Undo affordance and the commit delay.
  *
  * @example
  * notify({ intent: 'success', message: 'Saved' })
@@ -15,6 +16,7 @@
  * notifyPromise(apiCall(), { loading: 'Saving…', success: 'Saved', error: 'Failed' })
  */
 import type { ReactNode } from 'react'
+import { Button, Group, Text } from '@mantine/core'
 import { notifications } from '@mantine/notifications'
 import { add } from './store'
 import type { NotificationIntent, NotificationActionRef } from './store'
@@ -85,6 +87,12 @@ export type NotifyOptions = {
    * only when calling `notify()` for an action registered in the notifications registry.
    */
   action?: NotificationActionRef
+  /**
+   * What the persisted history records instead of `String(message)`. Only needed when `message` is
+   * a composed ReactNode the store cannot stringify — `String(<Group/>)` is `[object Object]`.
+   * `notifyUndo` passes its plain text here because its toast body carries the Undo button.
+   */
+  historyMessage?: string
 }
 
 // ── notify ────────────────────────────────────────────────────────────────────
@@ -98,7 +106,17 @@ export type NotifyOptions = {
  * const id = notify({ intent: 'error', message: <b>Failed</b>, autoClose: false })
  */
 export function notify(opts: NotifyOptions): string {
-  const { intent = 'info', message, title, icon, autoClose, id, dedupKey, action } = opts
+  const {
+    intent = 'info',
+    message,
+    title,
+    icon,
+    autoClose,
+    id,
+    dedupKey,
+    action,
+    historyMessage,
+  } = opts
 
   // Two-layer dedup: dedupKey window guard
   if (dedupKey !== undefined && isDuplicateKey(dedupKey)) return id ?? nextId()
@@ -123,7 +141,7 @@ export function notify(opts: NotifyOptions): string {
     id: resolvedId,
     intent,
     ...(title !== undefined && { title: String(title) }),
-    message: String(message),
+    message: historyMessage ?? String(message),
     createdAt: Date.now(),
     ...(action !== undefined && { action }),
   })
@@ -186,6 +204,107 @@ export function notifyInfo(
   return notify({ ...opts, intent: 'info', message })
 }
 
+// ── notifyUndo ────────────────────────────────────────────────────────────────
+
+/** Default undo window (ms) — the toast's autoClose and the grace period are the same number. */
+const UNDO_WINDOW_MS = 6000
+
+export type NotifyUndoOptions = {
+  /** The toast text, left of the Undo button. Also what the history records. */
+  message: ReactNode
+  /** Revert the optimistic change. Runs once, on click; `onExpire` then never runs. */
+  onUndo: () => void
+  /** How long the Undo button stays offered, in ms. Also the toast's autoClose. Default: 6000. */
+  window?: number
+  /**
+   * The window elapsed with no undo — the place to COMMIT the optimistic mutation. Runs at most
+   * once, and never after `onUndo`.
+   */
+  onExpire?: () => void
+}
+
+export type NotifyUndoHandle = {
+  /** The toast id — the same id in Mantine and in the notification history. */
+  id: string
+  /**
+   * Close the toast early and settle the window NOW: `onExpire` runs (unless undo already did), so
+   * a dismissed toast can never strand an uncommitted mutation. Idempotent.
+   */
+  dismiss: () => void
+}
+
+/**
+ * Show a toast offering an Undo for `window` ms, then commit.
+ *
+ * The affordance and the grace period are ONE number: `autoClose === window`, so the button is on
+ * screen for exactly as long as undoing still does something. Exactly one of `onUndo` / `onExpire`
+ * runs, exactly once — clicking Undo cancels the timer, and letting it elapse (or calling
+ * `dismiss()`) commits.
+ *
+ * Built on `notify`, so the toast is recorded to the notification history like any other.
+ *
+ * @example
+ * // Optimistic delete: the row is already gone from the UI; commit when the window closes.
+ * setRows((rows) => rows.filter((r) => r.id !== id))
+ * notifyUndo({
+ *   message: 'Item deleted',
+ *   onUndo: () => setRows(before),
+ *   onExpire: () => api.delete(id),
+ * })
+ */
+export function notifyUndo(opts: NotifyUndoOptions): NotifyUndoHandle {
+  const { message, onUndo, window: undoWindow = UNDO_WINDOW_MS, onExpire } = opts
+  const id = nextId()
+
+  let settled = false
+  let timer: ReturnType<typeof setTimeout> | undefined
+
+  const settle = (undone: boolean): void => {
+    if (settled) return
+    settled = true
+    if (timer !== undefined) clearTimeout(timer)
+    notifications.hide(id)
+    if (undone) onUndo()
+    else onExpire?.()
+  }
+
+  timer = setTimeout(() => settle(false), undoWindow)
+
+  notify({
+    intent: 'info',
+    id,
+    autoClose: undoWindow,
+    historyMessage: String(message),
+    message: (
+      <Group justify="space-between" wrap="nowrap" gap="sm">
+        <Text span size="sm">
+          {message}
+        </Text>
+        <Button variant="subtle" size="compact-xs" onClick={() => settle(true)}>
+          Undo
+        </Button>
+      </Group>
+    ),
+  })
+
+  return { id, dismiss: () => settle(false) }
+}
+
+/**
+ * `notifyUndo` for the common optimistic shape: the UI already changed, `undo` puts it back, and
+ * `mutate` is what actually commits when the window closes.
+ *
+ * @example
+ * notifyUndoable(() => api.delete(id), () => setRows(before), { message: 'Item deleted' })
+ */
+export function notifyUndoable(
+  mutate: () => void,
+  undo: () => void,
+  opts: Omit<NotifyUndoOptions, 'onUndo' | 'onExpire'>,
+): NotifyUndoHandle {
+  return notifyUndo({ ...opts, onUndo: undo, onExpire: mutate })
+}
+
 // ── notifyPromise ─────────────────────────────────────────────────────────────
 
 export type NotifyPromiseMessages = {

package/src/notifications/overlay.tsx

@@ -29,6 +29,7 @@
  * )
  */
 import { Notifications } from '@mantine/notifications'
+import { useNotificationsMountGuard } from './mount-guard'
 
 export type BasaltNotificationsProps = {
   /** Toast position. Default: 'bottom-right'. */
@@ -60,5 +61,6 @@ export function BasaltNotifications({
   autoClose = 4000,
   limit = 5,
 }: BasaltNotificationsProps) {
+  useNotificationsMountGuard()
   return <Notifications position={position} autoClose={autoClose} limit={limit} />
 }

package/src/notifications/store.ts

@@ -21,6 +21,13 @@ import { useSyncExternalStore } from 'react'
 
 // ── Types ─────────────────────────────────────────────────────────────────────
 
+/**
+ * Mantine's own notification vocabulary — kept as its own type rather than aliased to
+ * `common/props.ts`'s `Tone` (`'good' | 'warn' | 'bad'`) because `@mantine/notifications` and
+ * `INTENT_COLOR`/`INTENT_ROLE` key off exactly these four strings. Roughly:
+ * `success` ~ `Tone.good`, `error`/`warning` ~ `Tone.bad`/`Tone.warn`, `info` has no `Tone`
+ * equivalent (`ToneWithNeutral`'s `'neutral'` is the nearest fit).
+ */
 export type NotificationIntent = 'success' | 'error' | 'warning' | 'info'
 
 /**

package/src/provider/index.tsx

@@ -21,12 +21,14 @@ import { Component, useEffect, useMemo } from 'react'
 import type { ErrorInfo, ReactNode } from 'react'
 import { VxThemeProvider } from '../charts/theme'
 import { ConnectivityProvider } from '../connectivity'
+import type { ConnectivityProviderProps } from '../connectivity'
 import { cssVariablesResolver } from '../theme'
 import { useLabTheme } from './lab-theme'
 import { buildDensityCss, buildFontsCss, buildPaletteCss, buildRadiusCss } from '../tokens'
 import type { BuildPaletteOpts } from '../tokens'
 import { isDefaultDeriveConfig } from '../tokens/derive'
 import { buildPaletteData } from '../tokens/palette'
+import { isDev } from '../utils/is-dev'
 
 /**
  * Where an error surfaced — drives consumer routing (a render error vs a global rejection differ).
@@ -91,18 +93,35 @@ export type BasaltProviderProps = {
    * prop; its nonce mechanism is `getStyleNonce: () => string`, which flows through `...rest`.
    */
   nonce?: string
-  /** Optional SSE endpoint for connectivity monitoring. When set, an EventSource is opened. */
+  /**
+   * Options threaded through to the auto-mounted `ConnectivityProvider` (everything except
+   * `children`) — `sseUrl`, `healthUrl`, `healthIntervalMs`, and `override` (previously
+   * unreachable through `BasaltProvider`: the only way to reach it was a second, shadowing
+   * `ConnectivityProvider`). Takes precedence over the deprecated flattened props below when both
+   * are set.
+   */
+  connectivity?: Omit<ConnectivityProviderProps, 'children'>
+  /**
+   * @deprecated Use `connectivity={{ sseUrl }}` instead. Still honoured when `connectivity` is
+   * unset or omits `sseUrl`; removed in 1.29.0.
+   */
   sseUrl?: string
-  /** Optional health-check endpoint for connectivity monitoring. When set, periodic GET pings run. */
+  /**
+   * @deprecated Use `connectivity={{ healthUrl }}` instead. Still honoured when `connectivity` is
+   * unset or omits `healthUrl`; removed in 1.29.0.
+   */
   healthUrl?: string
-  /** Interval in ms for health pings. Default: 30_000 (30s). */
+  /**
+   * @deprecated Use `connectivity={{ healthIntervalMs }}` instead. Still honoured when
+   * `connectivity` is unset or omits `healthIntervalMs`; removed in 1.29.0.
+   */
   healthIntervalMs?: number
-} & Omit<MantineProviderProps, 'children' | 'theme' | 'defaultColorScheme'>
+} & Omit<MantineProviderProps, 'children' | 'theme' | 'defaultColorScheme' | 'cssVariablesResolver'>
 
 // ── Default error handler ─────────────────────────────────────────────────────────────────────────
 
 function defaultOnError(error: unknown, ctx: BasaltErrorContext): void {
-  if (process.env['NODE_ENV'] !== 'production') {
+  if (isDev()) {
     // eslint-disable-next-line no-console -- intentional dev-only diagnostic when no onError is supplied
     console.error('[BasaltProvider] unhandled error', ctx.kind, error)
   }
@@ -255,6 +274,68 @@ function BasaltBridge({
   )
 }
 
+// ── Duplicate-mount guard (F14) ───────────────────────────────────────────────────────────────────
+
+/**
+ * Module-level (deliberately NOT a per-instance ref, unlike `fence-block.tsx`'s warn-once gate) —
+ * the whole point is detecting a SECOND, unrelated `BasaltProvider` mounted anywhere else in the
+ * tree, which a per-instance gate could never see. Nested/duplicate providers double-mount
+ * `MantineProvider`, the palette `<style>` and `ConnectivityProvider`'s signal listeners — real
+ * misuse, not a false positive from React 18 StrictMode's double-invoke (that mounts/unmounts the
+ * SAME instance in sequence, so the count returns to 0 before a second instance could ever exist).
+ */
+let mountedProviderCount = 0
+
+function useDuplicateProviderGuard(): void {
+  useEffect(() => {
+    mountedProviderCount++
+    if (mountedProviderCount > 1 && isDev()) {
+      console.warn(
+        '[basalt] BasaltProvider: more than one instance is mounted at once — nested/duplicate ' +
+          'BasaltProviders double-mount MantineProvider, the palette <style> and ' +
+          'ConnectivityProvider. Mount exactly one, at the app root.',
+      )
+    }
+    return () => {
+      mountedProviderCount--
+    }
+  }, [])
+}
+
+/**
+ * Resolves the `connectivity` object against the three deprecated flattened props: `connectivity`
+ * wins WHOLESALE when provided, not per-key — a partial `connectivity={{ sseUrl }}` no longer picks
+ * up a stray `healthUrl` left on the old prop, which was surprising for a mid-migration consumer who
+ * expected the new prop to fully replace the old ones once set. Warns once, dev builds only, when
+ * both are actually supplied. Exported as a pure function (same rationale as `composeInjectedCss`
+ * above) so `provider/index.test.ts` can assert the precedence without rendering a tree.
+ */
+export function resolveConnectivityProps(props: {
+  connectivity: Omit<ConnectivityProviderProps, 'children'> | undefined
+  sseUrl: string | undefined
+  healthUrl: string | undefined
+  healthIntervalMs: number | undefined
+}): Omit<ConnectivityProviderProps, 'children'> {
+  if (props.connectivity !== undefined) {
+    const hasDeprecated =
+      props.sseUrl !== undefined ||
+      props.healthUrl !== undefined ||
+      props.healthIntervalMs !== undefined
+    if (hasDeprecated && isDev()) {
+      console.warn(
+        '[basalt] BasaltProvider: `connectivity` and one of `sseUrl`/`healthUrl`/`healthIntervalMs` ' +
+          'were both supplied — `connectivity` wins wholesale and the deprecated props are ignored.',
+      )
+    }
+    return props.connectivity
+  }
+  return {
+    ...(props.sseUrl !== undefined ? { sseUrl: props.sseUrl } : {}),
+    ...(props.healthUrl !== undefined ? { healthUrl: props.healthUrl } : {}),
+    ...(props.healthIntervalMs !== undefined ? { healthIntervalMs: props.healthIntervalMs } : {}),
+  }
+}
+
 // ── Public provider ───────────────────────────────────────────────────────────────────────────────
 
 export function BasaltProvider({
@@ -265,11 +346,13 @@ export function BasaltProvider({
   defaultColorScheme = 'dark',
   onError,
   nonce,
+  connectivity,
   sseUrl,
   healthUrl,
   healthIntervalMs,
   ...rest
 }: BasaltProviderProps) {
+  useDuplicateProviderGuard()
   const errorHandler = onError ?? defaultOnError
 
   // `createBasaltTheme(theme)` — plus, when the theme lab's "Apply" switch is on, the delta of its
@@ -278,12 +361,23 @@ export function BasaltProvider({
   // Basalt base and nothing else. See `./lab-theme.ts`.
   const resolvedTheme = useLabTheme(theme)
 
+  const resolvedConnectivity = resolveConnectivityProps({
+    connectivity,
+    sseUrl,
+    healthUrl,
+    healthIntervalMs,
+  })
+
   return (
+    // `...rest` spreads FIRST so a consumer's `MantineProviderProps` can never shadow the three
+    // values that follow it — `cssVariablesResolver` in particular is the resolver the package
+    // exists to install (F24); `theme`/`defaultColorScheme` are excluded from `rest`'s type too,
+    // this is belt-and-braces against a widened rest at the call site.
     <MantineProvider
+      {...rest}
       theme={resolvedTheme}
       cssVariablesResolver={cssVariablesResolver}
       defaultColorScheme={defaultColorScheme}
-      {...rest}
     >
       <BasaltErrorBoundary onError={errorHandler}>
         <BasaltBridge
@@ -292,13 +386,7 @@ export function BasaltProvider({
           nonce={nonce}
           onError={errorHandler}
         >
-          <ConnectivityProvider
-            {...(sseUrl !== undefined ? { sseUrl } : {})}
-            {...(healthUrl !== undefined ? { healthUrl } : {})}
-            {...(healthIntervalMs !== undefined ? { healthIntervalMs } : {})}
-          >
-            {children}
-          </ConnectivityProvider>
+          <ConnectivityProvider {...resolvedConnectivity}>{children}</ConnectivityProvider>
         </BasaltBridge>
       </BasaltErrorBoundary>
     </MantineProvider>

package/src/provider/lab-theme.ts

@@ -44,6 +44,7 @@ import { useMemo } from 'react'
 import { useDeriveControlsState, toDeriveOverride } from '../theme-lab/derive-state'
 import type { DeriveOverride } from '../theme-lab/derive-state'
 import { baseTheme, createBasaltTheme } from '../theme'
+import { isDev } from '../utils/is-dev'
 
 type Plain = Record<string, unknown>
 
@@ -135,7 +136,7 @@ export function applyLabOverride(
  * through a dev server (`bun run dev`), so that is the right side of the trade — but if you ever
  * preview the playground via `vite build && vite preview`, the sliders will be inert there.
  */
-const LAB_ENABLED = process.env['NODE_ENV'] !== 'production'
+const LAB_ENABLED = isDev()
 
 /**
  * Dev build: subscribed to the lab store.

package/src/query/devtools.tsx

@@ -10,6 +10,7 @@ import type { ReactQueryDevtools } from '@tanstack/react-query-devtools'
 const LazyDevtools = lazy(() =>
   import('@tanstack/react-query-devtools').then((m) => ({ default: m.ReactQueryDevtools })),
 )
+Object.assign(LazyDevtools, { displayName: 'LazyDevtools' })
 
 /**
  * Lazy, production-excluded wrapper for ReactQueryDevtools. Safe to import unconditionally —

package/src/router-tanstack/field.ts

@@ -14,17 +14,22 @@ export type {
   AnyField,
   BooleanField,
   EnumField,
+  FieldFallback,
   FieldHandle,
   FieldLane,
   FieldOption,
+  FieldSetOptions,
   FieldValue,
   MultiField,
   NumberField,
   RangeField,
   RangeParams,
   RangePresets,
+  RangeWindow,
+  RangeWindows,
   RangeValue,
   ResolvedLane,
+  ResolveLane,
   SearchValues,
   StoredValues,
   StringField,

package/src/router-tanstack/index.ts

@@ -14,9 +14,11 @@ export type {
   AnyField,
   BooleanField,
   EnumField,
+  FieldFallback,
   FieldHandle,
   FieldLane,
   FieldOption,
+  FieldSetOptions,
   FieldValue,
   MultiField,
   NumberField,
@@ -24,6 +26,8 @@ export type {
   RangeParams,
   RangePresets,
   RangeValue,
+  RangeWindow,
+  RangeWindows,
   ResolvedLane,
   SearchValues,
   StoredValues,