basalt-ui 1.41.0 → 2.0.0

package/src/commands/define-overlays.ts

@@ -5,7 +5,7 @@
  * `overlays` imperative controller — unknown keys are tsc errors. The type slot gives the
  * compile-time key union; the module-level stash gives the runtime values.
  *
- * Uses @mantine/modals under the hood. ModalsProvider must be mounted (BasaltOverlays does this).
+ * Uses @mantine/modals under the hood. ModalsProvider must be mounted (BasaltProvider does this).
  *
  * @example
  * // overlays.ts (app-side)
@@ -26,7 +26,6 @@
  * overlays.open('nonexistent', {})                         // ✗ tsc error
  */
 import type { ReactNode } from 'react'
-import { useEffect } from 'react'
 import { missingLayer } from '../common/errors'
 import type { Slot } from '../register'
 
@@ -48,32 +47,22 @@ function loadModals(): Promise<ModalsSingleton | undefined> {
 // ── Modals-layer availability ─────────────────────────────────────────────────
 
 /**
- * How many `ModalsProvider`s are live right now — a COUNTER, not a flag, for the same reason
- * `notifications/mount-guard.ts` counts: two overlapping mounts are normal (a route swap mounts the
- * next `BasaltOverlays` before unmounting the previous one), and a last-write-wins boolean reports
- * the teardown of the OLD one as "no layer" while the new one is serving.
+ * How many `ModalsProvider`s are live right now — a COUNTER, not a flag: two overlapping mounts
+ * are normal (a route swap mounts the next provider before unmounting the previous one), and a
+ * last-write-wins boolean reports the teardown of the OLD one as "no layer" while the new one is
+ * serving.
  *
  * It is the availability test `overlays.confirm` runs, because `@mantine/modals`' imperative API is
  * a window event bus: with nothing subscribed the dialog never appears and the promise never
- * settles. The previous version read `BasaltOverlays`' own `modals` flag instead, which refused the
- * call whenever a mounted shell passed `modals={false}` — even though the consumer had mounted their
- * own `<ModalsProvider>`, which is the very remedy the error message names.
+ * settles.
  */
 let mountedModalsProviders = 0
 
 /**
- * Declare that a `@mantine/modals` `<ModalsProvider>` is mounted and serving, and get back the
- * function that retracts it. `BasaltOverlays` calls this for its own provider; a consumer mounting
- * the provider THEMSELVES (with `<BasaltOverlays modals={false} />`, or with no `BasaltOverlays` at
- * all) calls it too, or `overlays.confirm` cannot tell their provider from no provider and rejects.
- *
- * There is no way to detect the provider from outside React — its context is only readable through
- * `useModals()`, and `confirm` is an imperative call with no component to read it from. So the
- * registration is explicit.
- *
- * @example
- * useEffect(() => registerModalsProvider(), [])
- * // …beside your own <ModalsProvider> mount.
+ * Internal — `BasaltProvider` declares its `ModalsProvider` as live for as long as it is mounted,
+ * and gets back the function that retracts it. There is no way to detect the provider from outside
+ * React (its context is only readable through `useModals()`, and `confirm` is an imperative call),
+ * so the registration is explicit. Not on the `./commands` barrel.
  */
 export function registerModalsProvider(): () => void {
   mountedModalsProviders++
@@ -87,18 +76,6 @@ export function registerModalsProvider(): () => void {
   }
 }
 
-/**
- * Internal — `BasaltOverlays` registers its OWN lazy `ModalsProvider` here, and only when it
- * actually renders one. Deliberately NOT on the `./commands` barrel (internal wiring only, same as
- * `notifications/mount-guard`); the consumer-facing half is {@link registerModalsProvider}.
- */
-export function useModalsLayer(enabled: boolean): void {
-  useEffect(() => {
-    if (!enabled) return
-    return registerModalsProvider()
-  }, [enabled])
-}
-
 // ── Overlay + OverlayMap ──────────────────────────────────────────────────────
 
 /**
@@ -267,7 +244,7 @@ async function confirm(options: ConfirmOptions): Promise<boolean> {
       missingLayer(
         'overlays.confirm',
         '@mantine/modals',
-        'install the @mantine/modals peer and mount <BasaltOverlays>',
+        'install the @mantine/modals peer and mount <BasaltProvider>',
       ),
     )
   }
@@ -276,8 +253,7 @@ async function confirm(options: ConfirmOptions): Promise<boolean> {
       missingLayer(
         'overlays.confirm',
         'a mounted <ModalsProvider>',
-        'drop `modals={false}` from <BasaltOverlays>, or mount <ModalsProvider> yourself and call ' +
-          'registerModalsProvider() from an effect for as long as it is up',
+        'mount <BasaltProvider> at the app root before calling it',
       ),
     )
   }

package/src/commands/index.ts

@@ -1,107 +1,24 @@
 /**
- * ./commands — command bus, overlay controller, Spotlight projection, shortcuts display,
- * live keybindings, and composable overlay mount for basalt-ui apps.
+ * ./commands — the command bus, overlay controller, shortcuts help and the notification registry.
  *
- * Optional peers: @mantine/modals ^9.3.0, @mantine/spotlight ^9.3.0,
- *   @mantine/notifications ^9.3.0, @tanstack/react-hotkeys 0.10.0.
- *
- * Install with: bun add @mantine/modals @mantine/spotlight @mantine/notifications @tanstack/react-hotkeys
- * Also import the Spotlight styles in main.tsx (the layered bundle — the unlayered one outranks
- * basalt's `@layer basalt` styles regardless of specificity): import '@mantine/spotlight/styles.layer.css'
+ * `BasaltProvider` mounts modals, Spotlight, hotkeys and notifications; this barrel is only what
+ * an app declares and calls.
  *
  * @example
- * // commands.ts (app-side) — define + augment:
- * import { defineCommands } from 'basalt-ui/commands'
+ * import { defineCommands, defineNotifications, emit } from 'basalt-ui/commands'
  * export const COMMANDS = defineCommands({
  *   'file:save': { label: 'Save', group: 'File', shortcut: 'Mod+S', run: () => save() },
  * })
  * declare module 'basalt-ui' {
  *   interface BasaltRegister { commands: typeof COMMANDS }
  * }
- *
- * // main.tsx — mount composable overlays:
- * import { BasaltOverlays } from 'basalt-ui/commands'
- * import '@mantine/spotlight/styles.layer.css'
- * <BasaltProvider><BasaltOverlays><App /></BasaltOverlays></BasaltProvider>
- *
- * // usage.ts — run a command:
- * import { runCommand } from 'basalt-ui/commands'
- * runCommand('file:save')
- *
- * // usage.ts — the registry-free confirm dialog:
- * import { overlays } from 'basalt-ui/commands'
- * const ok = await overlays.confirm({ title: 'Discard draft?', onConfirm: () => reset() })
- * overlays.confirmDelete({ subject: 'item', count: 3, onConfirm: () => removeSelected() })
- *
- * // Mounting ModalsProvider yourself instead of letting <BasaltOverlays> do it:
- * import { registerModalsProvider } from 'basalt-ui/commands'
- * useEffect(() => registerModalsProvider(), [])
- *
- * // Open/close Spotlight programmatically:
- * import { openSpotlight, closeSpotlight } from 'basalt-ui/commands'
- * openSpotlight()
  */
 
-// ── defineCommands + runCommand ───────────────────────────────────────────────
-export {
-  defineCommands,
-  defineCommand,
-  runCommand,
-  type Command,
-  type CommandMap,
-  type CommandId,
-  type CommandRunContext,
-} from './define-commands'
-
-// ── defineOverlays + defineOverlay + overlays controller ─────────────────────
-export {
-  defineOverlays,
-  defineOverlay,
-  overlays,
-  registerModalsProvider,
-  type Overlay,
-  type OverlayMap,
-  type OverlayKey,
-  type ConfirmOptions,
-  type ConfirmDeleteOptions,
-} from './define-overlays'
-
-// ── Projectors ────────────────────────────────────────────────────────────────
-export {
-  toSpotlightActions,
-  toRouteActions,
-  toShortcutList,
-  toHotkeyBindings,
-  type RouteActionItem,
-  type RouteActionSection,
-  type ToRouteActionsOptions,
-  type ShortcutEntry,
-  type HotkeyBinding,
-} from './projectors'
-
-// ── Imperative shell handles (setColorScheme/toggleSidebar) ──────────────────
-export {
-  setColorScheme,
-  toggleSidebar,
-  type ColorScheme,
-  type ColorSchemeSetter,
-  type SidebarToggle,
-} from './shell-bridge'
-
-// ── Shortcut format utils ─────────────────────────────────────────────────────
-export { parseShortcut, detectMac, formatShortcutDisplay } from './shortcut-format'
-
-// ── useCommandHotkeys hook ────────────────────────────────────────────────────
-export { useCommandHotkeys } from './useCommandHotkeys'
-
-// ── ShortcutsHelp ─────────────────────────────────────────────────────────────
-export { ShortcutsHelp, type ShortcutsHelpProps } from './ShortcutsHelp'
+export { defineCommands, type Command } from './define-commands'
+export { defineOverlays, overlays } from './define-overlays'
+export { setColorScheme, toggleSidebar } from './shell-bridge'
+export { ShortcutsHelp } from './ShortcutsHelp'
 
-// ── BasaltOverlays mount + Spotlight controls ─────────────────────────────────
-export {
-  BasaltOverlays,
-  type BasaltOverlaysProps,
-  basaltSpotlight,
-  openSpotlight,
-  closeSpotlight,
-} from './overlays-mount'
+// ── Notifications (folded in from `./notifications`) ──────────────────────────
+export { defineNotifications, emit } from './notifications/define-notifications'
+export { NotificationBell } from './notifications/bell'

package/src/{notifications → commands/notifications}/bell.tsx

@@ -7,7 +7,7 @@
  * marked read when interacted with inside the center.
  *
  * @example
- * import { NotificationBell } from 'basalt-ui/notifications'
+ * import { NotificationBell } from 'basalt-ui/commands'
  *
  * // In the shell's globalActions prop:
  * <BasaltShell
@@ -18,7 +18,7 @@
 import { ActionIcon, Indicator, Popover } from '@mantine/core'
 import { useDisclosure } from '@mantine/hooks'
 import { useRef } from 'react'
-import type { BasaltProps } from '../common/props'
+import type { BasaltProps } from '../../common/props'
 import { useNotificationHistory } from './store'
 import { NOTIFICATION_POPOVER_WIDTH, NotificationCenter } from './center'
 

package/src/{notifications → commands/notifications}/center.tsx

@@ -9,8 +9,10 @@
  * removed outright. Actionable items render a button resolved from the notifications registry, so a
  * notification can navigate or open a modal even after a reload. Consumes useNotificationHistory.
  *
+ * Internal: `NotificationBell` mounts it; `basalt-ui/commands` does not export it.
+ *
  * @example
- * import { NotificationCenter } from 'basalt-ui/notifications'
+ * import { NotificationCenter } from './center'
  * <NotificationCenter />
  */
 import { useState } from 'react'
@@ -25,9 +27,9 @@ import {
   Stack,
   Text,
 } from '@mantine/core'
-import type { BasaltProps } from '../common/props'
-import { cx } from '../common/props'
-import { VX } from '../tokens'
+import type { BasaltProps } from '../../common/props'
+import { cx } from '../../common/props'
+import { VX } from '../../tokens'
 import { resolveAction } from './define-notifications'
 import { useNotificationHistory } from './store'
 import type { NotificationHistoryItem, NotificationIntent } from './store'
@@ -174,7 +176,7 @@ export type NotificationCenterProps = BasaltProps & {
  * its own container.
  *
  * @example
- * import { NOTIFICATION_POPOVER_WIDTH, NotificationCenter } from 'basalt-ui/notifications'
+ * import { NOTIFICATION_POPOVER_WIDTH, NotificationCenter } from './center'
  *
  * <Popover width={NOTIFICATION_POPOVER_WIDTH}>
  *   <Popover.Dropdown>

package/src/{notifications → commands/notifications}/define-notifications.ts

@@ -12,7 +12,7 @@
  *
  * @example
  * // notifications.ts (app-side)
- * import { defineNotifications } from 'basalt-ui/notifications'
+ * import { defineNotifications } from 'basalt-ui/commands'
  * export const NOTIFICATIONS = defineNotifications({
  *   'upload:success': { intent: 'success', toMessage: (p: { name: string }) => `Uploaded ${p.name}` },
  *   'upload:error':   { intent: 'error',   toMessage: (_: unknown) => 'Upload failed' },
@@ -22,13 +22,13 @@
  * }
  *
  * // usage.ts
- * import { emit } from 'basalt-ui/notifications'
+ * import { emit } from 'basalt-ui/commands'
  * emit('upload:success', { name: 'photo.jpg' })  // ✓ typed, and the payload shape is checked
  * emit('upload:success', 'nope')                  // ✗ tsc error — wrong payload shape
  * emit('nonexistent', {})                         // ✗ tsc error — unregistered kind
  */
 import type { ReactNode } from 'react'
-import type { Slot } from '../register'
+import type { Slot } from '../../register'
 import { notify } from './notify'
 import type { NotifyOptions, NotificationIntent } from './notify'
 import type { NotificationActionRef } from './store'

package/src/commands/notifications/notify.tsx

@@ -0,0 +1,158 @@
+/**
+ * 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
+ *
+ * Internal: consumers reach it through `emit` (`defineNotifications`).
+ *
+ * @example
+ * notify({ intent: 'success', message: 'Saved' })
+ * notify({ intent: 'error', message: 'Failed', title: 'Upload error', autoClose: false })
+ */
+import type { ReactNode } from 'react'
+import { notifications } from '@mantine/notifications'
+import { add, has } 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
+/** dedupKey → when it was recorded, and the id that recording returned. */
+const dedupKeyTimestamps = new Map<string, { at: number; id: string }>()
+
+/** Drop entries past the window, so a long-lived page with many distinct keys never grows the map. */
+function pruneDedupKeys(now: number): void {
+  for (const [key, { at }] of dedupKeyTimestamps) {
+    if (now - at >= DEDUP_WINDOW_MS) dedupKeyTimestamps.delete(key)
+  }
+}
+
+/** The id recorded for `dedupKey` inside the window, or `undefined` when this call is a first. */
+function recentIdForKey(dedupKey: string): string | undefined {
+  const last = dedupKeyTimestamps.get(dedupKey)
+  if (last === undefined || Date.now() - last.at >= DEDUP_WINDOW_MS) return undefined
+  return last.id
+}
+
+// ── ID generation ─────────────────────────────────────────────────────────────
+
+let seq = 0
+function nextId(): string {
+  return `basalt-${Date.now()}-${++seq}`
+}
+
+/** History stores serializable text: a string or number survives, any other node is dropped. */
+function historyText(node: ReactNode): string | undefined {
+  if (typeof node === 'string') return node
+  if (typeof node === 'number') return String(node)
+  return undefined
+}
+
+// ── 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
+}
+
+// ── notify ────────────────────────────────────────────────────────────────────
+
+/**
+ * Show a toast and record it to the notification history. Only string / number `message` and
+ * `title` are recorded; any other node shows in the toast but the history keeps `''` (message) or
+ * no title.
+ * 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 } = opts
+
+  // Two-layer dedup: dedupKey window guard — a hit returns the id the first call recorded.
+  if (dedupKey !== undefined) {
+    const recorded = recentIdForKey(dedupKey)
+    if (recorded !== undefined) return recorded
+  }
+
+  const resolvedId = id ?? nextId()
+  if (dedupKey !== undefined) {
+    pruneDedupKeys(Date.now())
+    dedupKeyTimestamps.set(dedupKey, { at: Date.now(), id: resolvedId })
+  }
+  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,
+  })
+
+  // An explicit id already in the history is the same notification re-shown: Mantine updates it on
+  // screen, and the history keeps its one record.
+  if (id !== undefined && has(id)) return resolvedId
+
+  const titleText = historyText(title)
+  add({
+    id: resolvedId,
+    intent,
+    ...(titleText !== undefined && { title: titleText }),
+    message: historyText(message) ?? '',
+    createdAt: Date.now(),
+    ...(action !== undefined && { action }),
+  })
+
+  return resolvedId
+}

package/src/{notifications → commands/notifications}/store.ts

@@ -8,13 +8,16 @@
  * Module-level add/markRead/markAllRead/clear are callable from notify() (not hook-scoped), and
  * useNotificationHistory() exposes the reactive slice to components.
  *
+ * Internal: `basalt-ui/commands` publishes only `NotificationBell`, `defineNotifications` and `emit`;
+ * everything here is reached through them.
+ *
  * @example
  * // Module-level (non-React):
- * import { add, markRead, markAllRead, clear } from 'basalt-ui/notifications'
+ * import { add, markRead, markAllRead, clear } from './store'
  * add({ id: 'x', intent: 'success', message: 'Done', createdAt: Date.now() })
  *
  * // React:
- * import { useNotificationHistory } from 'basalt-ui/notifications'
+ * import { useNotificationHistory } from './store'
  * const { items, unreadCount, markRead, markAllRead, clear } = useNotificationHistory()
  */
 import { useSyncExternalStore } from 'react'
@@ -153,6 +156,11 @@ if (typeof window !== 'undefined') {
 
 // ── Module-level public API ───────────────────────────────────────────────────
 
+/** Whether the history already holds an item with this id. */
+export function has(id: string): boolean {
+  return state.some((item) => item.id === id)
+}
+
 /**
  * Add a notification to the history store (ring-buffer capped at 50).
  * Called by notify() — safe to call outside React.