basalt-ui 1.41.0 → 2.0.0

package/src/notifications/notify.tsx

@@ -1,379 +0,0 @@
-/**
- * notify — core toast helper wrapping @mantine/notifications.
- *
- * Maps intent → Mantine color name, sets per-intent aria role and autoClose defaults,
- * records every toast into the module-level history store, and applies two-layer dedup:
- *   1. Mantine id-dedup (passing the same id to notifications.show is a no-op on screen)
- *   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. 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' })
- * notify({ intent: 'error', message: 'Failed', title: 'Upload error', autoClose: false })
- * 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'
-
-export type { NotificationIntent }
-
-// ── Intent → Mantine color + defaults ────────────────────────────────────────
-
-const INTENT_COLOR: Record<NotificationIntent, string> = {
-  success: 'green',
-  error: 'red',
-  warning: 'yellow',
-  info: 'blue',
-}
-
-/**
- * Aria role per intent.
- * 'alert' = assertive (error/warning: must be announced immediately)
- * 'status' = polite (success/info: waits for a natural pause)
- */
-const INTENT_ROLE: Record<NotificationIntent, 'alert' | 'status'> = {
-  error: 'alert',
-  warning: 'alert',
-  success: 'status',
-  info: 'status',
-}
-
-/** Per-intent default autoClose (ms). false = until-dismissed. */
-const INTENT_AUTO_CLOSE: Record<NotificationIntent, number | false> = {
-  success: 2000,
-  info: 3000,
-  warning: 5000,
-  error: false,
-}
-
-// ── Two-layer dedup — dedupKey window ────────────────────────────────────────
-
-const DEDUP_WINDOW_MS = 1500
-const dedupKeyTimestamps = new Map<string, number>()
-
-function isDuplicateKey(dedupKey: string): boolean {
-  const last = dedupKeyTimestamps.get(dedupKey)
-  if (last !== undefined && Date.now() - last < DEDUP_WINDOW_MS) return true
-  dedupKeyTimestamps.set(dedupKey, Date.now())
-  return false
-}
-
-// ── ID generation ─────────────────────────────────────────────────────────────
-
-let seq = 0
-function nextId(): string {
-  return `basalt-${Date.now()}-${++seq}`
-}
-
-// ── NotifyOptions ─────────────────────────────────────────────────────────────
-
-export type NotifyOptions = {
-  intent?: NotificationIntent
-  message: ReactNode
-  title?: ReactNode
-  icon?: ReactNode
-  autoClose?: number | false
-  id?: string
-  dedupKey?: string
-  /**
-   * A serializable action ref — gives the recorded item an action button in the notification
-   * center. Usually attached automatically by `emit()` from the kind's spec; pass it directly
-   * 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 ────────────────────────────────────────────────────────────────────
-
-/**
- * Show a toast and record it to the notification history.
- * Returns the notification id (string).
- *
- * @example
- * const id = notify({ intent: 'success', message: 'Profile saved', title: 'Success' })
- * 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,
-    historyMessage,
-  } = opts
-
-  // Two-layer dedup: dedupKey window guard
-  if (dedupKey !== undefined && isDuplicateKey(dedupKey)) return id ?? nextId()
-
-  const resolvedId = id ?? nextId()
-  const color = INTENT_COLOR[intent]
-  const role = INTENT_ROLE[intent]
-  const resolvedAutoClose = autoClose !== undefined ? autoClose : INTENT_AUTO_CLOSE[intent]
-
-  notifications.show({
-    id: resolvedId,
-    message,
-    title: title ?? undefined,
-    color,
-    icon: icon ?? undefined,
-    autoClose: resolvedAutoClose,
-    role,
-  })
-
-  // Record to history store (stringify ReactNode — store only serializable text)
-  add({
-    id: resolvedId,
-    intent,
-    ...(title !== undefined && { title: String(title) }),
-    message: historyMessage ?? String(message),
-    createdAt: Date.now(),
-    ...(action !== undefined && { action }),
-  })
-
-  return resolvedId
-}
-
-// ── Convenience wrappers ──────────────────────────────────────────────────────
-
-/**
- * Show a success toast.
- *
- * @example
- * notifySuccess('Profile saved')
- * notifySuccess('Done', { title: 'Upload complete', icon: <IconCheck /> })
- */
-export function notifySuccess(
-  message: ReactNode,
-  opts?: Omit<NotifyOptions, 'intent' | 'message'>,
-): string {
-  return notify({ ...opts, intent: 'success', message })
-}
-
-/**
- * Show an error toast (auto-close off by default).
- *
- * @example
- * notifyError('Upload failed', { title: 'Error' })
- */
-export function notifyError(
-  message: ReactNode,
-  opts?: Omit<NotifyOptions, 'intent' | 'message'>,
-): string {
-  return notify({ ...opts, intent: 'error', message })
-}
-
-/**
- * Show a warning toast.
- *
- * @example
- * notifyWarning('Session expires in 5 minutes')
- */
-export function notifyWarning(
-  message: ReactNode,
-  opts?: Omit<NotifyOptions, 'intent' | 'message'>,
-): string {
-  return notify({ ...opts, intent: 'warning', message })
-}
-
-/**
- * Show an info toast.
- *
- * @example
- * notifyInfo('New version available')
- */
-export function notifyInfo(
-  message: ReactNode,
-  opts?: Omit<NotifyOptions, 'intent' | 'message'>,
-): string {
-  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 = {
-  loading: ReactNode
-  success: ReactNode
-  error: ReactNode
-}
-
-/**
- * Show a loading toast while a promise is pending, then update to success or error on settle.
- * Uses notifications.show for loading → notifications.update for the final state (Mantine dedup
- * requires update, not show, to replace an existing id).
- * Records the final state (success/error) to history.
- *
- * @example
- * await notifyPromise(uploadFile(file), {
- *   loading: 'Uploading…',
- *   success: 'Upload complete',
- *   error: 'Upload failed',
- * })
- */
-export function notifyPromise<T>(promise: Promise<T>, messages: NotifyPromiseMessages): Promise<T> {
-  const id = nextId()
-
-  notifications.show({
-    id,
-    message: messages.loading,
-    loading: true,
-    autoClose: false,
-    withCloseButton: false,
-    role: 'status',
-  })
-
-  return promise.then(
-    (result) => {
-      notifications.update({
-        id,
-        message: messages.success,
-        color: INTENT_COLOR['success'],
-        loading: false,
-        autoClose: INTENT_AUTO_CLOSE['success'],
-        withCloseButton: true,
-        role: 'status',
-      })
-      add({
-        id,
-        intent: 'success',
-        message: String(messages.success),
-        createdAt: Date.now(),
-      })
-      return result
-    },
-    (err: unknown) => {
-      notifications.update({
-        id,
-        message: messages.error,
-        color: INTENT_COLOR['error'],
-        loading: false,
-        autoClose: INTENT_AUTO_CLOSE['error'],
-        withCloseButton: true,
-        role: 'alert',
-      })
-      add({
-        id,
-        intent: 'error',
-        message: String(messages.error),
-        createdAt: Date.now(),
-      })
-      throw err
-    },
-  )
-}

package/src/provider/connectivity-indicator.tsx

@@ -1,267 +0,0 @@
-/**
- * ConnectivityIndicator — header ActionIcon + Popover showing per-signal connection detail.
- *
- * Designed for the shell's `globalActions` slot. Shows a wifi icon whose color reflects overall
- * status (faint=online, status-warn=degraded, status-danger=offline — `docs/DESIGN-SPEC.md` §5's
- * status tokens, not the Mantine teal/yellow/red ramps). Click opens a Popover with per-signal rows.
- *
- * @example
- * import { ConnectivityIndicator } from 'basalt-ui'
- *
- * <BasaltShell
- *   globalActions={[{ key: 'connectivity', node: <ConnectivityIndicator />, mobile: 'bar' }]}
- *   {...rest}
- * />
- */
-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 './connectivity-types'
-
-export type ConnectivityIndicatorProps = BasaltProps
-
-const HOVER_OPEN_DELAY = 150
-const HOVER_CLOSE_DELAY = 200
-
-// ── Inline icons (14px, same stroke pattern as NotificationBell) ──────────────────────────────────────
-
-function GlobeIcon() {
-  return (
-    <svg
-      width={14}
-      height={14}
-      viewBox="0 0 24 24"
-      fill="none"
-      stroke="currentColor"
-      strokeWidth={2}
-      strokeLinecap="round"
-      strokeLinejoin="round"
-      aria-hidden
-    >
-      <circle cx="12" cy="12" r="10" />
-      <path d="M2 12h20" />
-      <path d="M12 2a15.3 15.3 0 0 1 4 10 15.3 15.3 0 0 1-4 10 15.3 15.3 0 0 1-4-10 15.3 15.3 0 0 1 4-10z" />
-    </svg>
-  )
-}
-
-function LightningIcon() {
-  return (
-    <svg
-      width={14}
-      height={14}
-      viewBox="0 0 24 24"
-      fill="none"
-      stroke="currentColor"
-      strokeWidth={2}
-      strokeLinecap="round"
-      strokeLinejoin="round"
-      aria-hidden
-    >
-      <path d="M13 2L3 14h9l-1 8 10-12h-9l1-8z" />
-    </svg>
-  )
-}
-
-function AntennaIcon() {
-  return (
-    <svg
-      width={14}
-      height={14}
-      viewBox="0 0 24 24"
-      fill="none"
-      stroke="currentColor"
-      strokeWidth={2}
-      strokeLinecap="round"
-      strokeLinejoin="round"
-      aria-hidden
-    >
-      <path d="M5 17l3-5 3 5" />
-      <path d="M11 13l3-5 3 5" />
-      <path d="M17 9l3-5 3 5" />
-      <path d="M3 21h18" />
-    </svg>
-  )
-}
-
-function HeartIcon() {
-  return (
-    <svg
-      width={14}
-      height={14}
-      viewBox="0 0 24 24"
-      fill="none"
-      stroke="currentColor"
-      strokeWidth={2}
-      strokeLinecap="round"
-      strokeLinejoin="round"
-      aria-hidden
-    >
-      <path d="M20.84 4.61a5.5 5.5 0 0 0-7.78 0L12 5.67l-1.06-1.06a5.5 5.5 0 0 0-7.78 7.78l1.06 1.06L12 21.23l7.78-7.78 1.06-1.06a5.5 5.5 0 0 0 0-7.78z" />
-    </svg>
-  )
-}
-
-// ── Wifi icon for the ActionIcon button (18px) ────────────────────────────────────────────────────────
-
-function WifiIcon({ size = 18 }: { size?: number }) {
-  return (
-    <svg
-      width={size}
-      height={size}
-      viewBox="0 0 24 24"
-      fill="none"
-      stroke="currentColor"
-      strokeWidth={2}
-      strokeLinecap="round"
-      strokeLinejoin="round"
-      aria-hidden
-    >
-      <path d="M12 18h.01" />
-      <path d="M9.172 15.172a4 4 0 0 1 5.656 0" />
-      <path d="M6.343 12.343a8 8 0 0 1 11.314 0" />
-      <path d="M3.515 9.515c4.686 -4.687 12.284 -4.687 16.97 0" />
-    </svg>
-  )
-}
-
-// ── Per-signal row ────────────────────────────────────────────────────────────────────────────────────
-
-function SignalRow({
-  label,
-  value,
-  icon,
-}: {
-  label: string
-  value: boolean | null
-  icon: React.ReactNode
-}) {
-  const color = value === true ? VX.status.good : value === false ? VX.status.bad : 'dimmed'
-  const text = value === true ? 'Connected' : value === false ? 'Disconnected' : 'Not configured'
-  return (
-    <Group justify="space-between">
-      <Group gap="xs">
-        {icon}
-        <Text size="sm">{label}</Text>
-      </Group>
-      <Text size="sm" c={color}>
-        {text}
-      </Text>
-    </Group>
-  )
-}
-
-// ── Status badge ──────────────────────────────────────────────────────────────────────────────────────
-
-// Status dot/badge colors read the exact spec status tokens (docs/DESIGN-SPEC.md §5: "connectivity
-// indicator: status dot colors from status tokens"), not the Mantine teal/yellow/red theme ramps —
-// those are a different hue family than STATUS.good/warn/bad.
-const STATUS_CONFIG: Record<ConnectivityStatus, { token: string; label: string }> = {
-  online: { token: VX.status.good, label: 'Connected' },
-  degraded: { token: VX.status.warn, label: 'Degraded' },
-  offline: { token: VX.status.bad, label: 'Offline' },
-}
-
-/** Icon color is neutral when online — only degrades when something is wrong. */
-const ICON_COLOR: Record<ConnectivityStatus, string> = {
-  online: VX.faint,
-  degraded: VX.status.warn,
-  offline: VX.status.bad,
-}
-
-// ── Component ─────────────────────────────────────────────────────────────────────────────────────────
-
-/**
- * ConnectivityIndicator — clickable wifi icon that opens a per-signal detail popover.
- *
- * @example
- * <BasaltShell
- *   globalActions={[{ key: 'connectivity', node: <ConnectivityIndicator />, mobile: 'bar' }]}
- *   {...rest}
- * />
- */
-export function ConnectivityIndicator({ className, style }: ConnectivityIndicatorProps = {}) {
-  const [opened, { open, toggle, close }] = useDisclosure(false)
-  const { status, details } = useConnectivity()
-  const statusCfg = STATUS_CONFIG[status]
-  const timer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined)
-
-  const scheduleOpen = () => {
-    clearTimeout(timer.current)
-    timer.current = setTimeout(() => open(), HOVER_OPEN_DELAY)
-  }
-  const scheduleClose = () => {
-    clearTimeout(timer.current)
-    timer.current = setTimeout(() => close(), HOVER_CLOSE_DELAY)
-  }
-
-  return (
-    <Popover opened={opened} onClose={close} position="bottom-end" withArrow withinPortal>
-      <Popover.Target>
-        <ActionIcon
-          variant="transparent"
-          color={ICON_COLOR[status]}
-          // `ctl`, the control tier (`docs/CONTROLS-SPEC.md` §5) — this indicator's home is a header
-          // toolbar, and that is the tier a toolbar control is. It used to pin a literal `28` to opt
-          // OUT of the `size="md"` height (42px, sized for a form field), which was the right escape
-          // before the `ctl` tier existed; the cost was that the shell's globals rendered 2px short
-          // of every other control in the same 48px row. `--ai-size-ctl` is declared on `:root` by
-          // `cssVariablesResolver`, so this resolves with or without an enclosing `CtlSlot`, and it
-          // tracks the density knob like the rest of the tier.
-          size="ctl"
-          onClick={toggle}
-          onMouseEnter={scheduleOpen}
-          onMouseLeave={scheduleClose}
-          aria-label={statusCfg.label}
-          aria-expanded={opened}
-          aria-haspopup="dialog"
-          {...(className !== undefined && { className })}
-          {...(style !== undefined && { style })}
-        >
-          <WifiIcon />
-        </ActionIcon>
-      </Popover.Target>
-
-      <Popover.Dropdown
-        p="md"
-        aria-label="Connectivity details"
-        w={260}
-        onMouseEnter={scheduleOpen}
-        onMouseLeave={scheduleClose}
-      >
-        <Stack gap="xs">
-          <Group justify="space-between">
-            <Text size="sm" fw={600}>
-              Status
-            </Text>
-            <Badge
-              size="sm"
-              styles={{
-                root: {
-                  backgroundColor: alpha(statusCfg.token, 0.13),
-                  color: statusCfg.token,
-                  fontFamily: 'var(--basalt-font-mono)',
-                  fontWeight: 600,
-                  fontSize: VX.text.xs,
-                  borderRadius: 'var(--vx-radius-ctrl)',
-                },
-              }}
-            >
-              {statusCfg.label}
-            </Badge>
-          </Group>
-
-          <Divider />
-
-          <SignalRow label="Browser" value={details.browserOnline} icon={<GlobeIcon />} />
-          <SignalRow label="React Query" value={details.queryOnline} icon={<LightningIcon />} />
-          <SignalRow label="SSE" value={details.sseOpen} icon={<AntennaIcon />} />
-          <SignalRow label="Health Check" value={details.healthPassing} icon={<HeartIcon />} />
-        </Stack>
-      </Popover.Dropdown>
-    </Popover>
-  )
-}