basalt-ui 1.40.3 → 2.0.0

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.

package/src/commands/projectors.ts

@@ -1,183 +1,9 @@
 /**
- * projectors — project the active command registry into Mantine Spotlight actions, a shortcut list,
- * and a @tanstack/react-hotkeys bindings array.
- *
- * All functions read the runtime stash (populated by defineCommands) — they do NOT read the
- * type-erased BasaltRegister slot. They are safe to call before any commands are registered
- * (returns empty array).
- *
- * @example
- * // In BasaltOverlays, pass toSpotlightActions() to Spotlight:
- * <Spotlight store={basaltSpotlight[0]} actions={toSpotlightActions()} shortcut="mod + K" />
- *
- * // Render a shortcut reference list:
- * const shortcuts = toShortcutList()  // [{ id, label, shortcut, group? }, ...]
- *
- * // Opt-in: drive your own useHotkeys() call (useCommandHotkeys uses the imperative manager API instead):
- * const bindings = toHotkeyBindings()
- * useHotkeys(bindings)
- */
-import type { SpotlightActionData } from '@mantine/spotlight'
-import type { ReactNode } from 'react'
-import { getActiveCommands, runCommand } from './define-commands'
-import type { CommandId } from './define-commands'
-import { formatShortcutDisplay, detectMac } from './shortcut-format'
-
-// ── UseHotkeyDefinition (re-typed locally to avoid peer import at module level) ──
-
-/**
- * Shape of a single entry in the array passed to useHotkeys().
- * Mirrors UseHotkeyDefinition from @tanstack/react-hotkeys — typed locally so
- * projectors.ts has no hard import on the optional peer.
- */
-export type HotkeyBinding = {
-  hotkey: string
-  /**
-   * Callback invoked when the hotkey fires. Widened to match @tanstack/react-hotkeys'
-   * HotkeyCallback signature — `(event: KeyboardEvent, context?: unknown) => void` — so
-   * consumers can pass toHotkeyBindings() directly to useHotkeys() without a tsc error.
-   * The implementations produced by toHotkeyBindings() only use the zero-arg form internally.
-   */
-  callback: (event: KeyboardEvent, context?: unknown) => void
-}
-
-// ── toSpotlightActions ────────────────────────────────────────────────────────
-
-/**
- * Project the active command registry into a Mantine Spotlight `SpotlightActionData[]` array.
- * Commands where `when()` returns false are excluded from the list.
- *
- * Reads a one-time snapshot of the runtime command stash at call time — commands registered AFTER
- * this is called (lazy/code-split) won't appear. Register all commands at module load before
- * mounting <BasaltOverlays>.
- *
- * When onTrigger is provided it is called INSTEAD OF runCommand (put runCommand(id) inside your
- * onTrigger if you want it to fire); without onTrigger, runCommand(id) fires directly.
- *
- * @example
- * // Close the palette then run the command:
- * const actions = toSpotlightActions((id) => { spotlight.close(); runCommand(id) })
- *
- * // Default: just runs the command directly
- * const actions = toSpotlightActions()
- */
-export function toSpotlightActions(onTrigger?: (id: CommandId) => void): SpotlightActionData[] {
-  const cmds = getActiveCommands()
-  const actions: SpotlightActionData[] = []
-
-  for (const [id, cmd] of Object.entries(cmds)) {
-    // Skip commands gated behind a false when() predicate
-    if (cmd.when !== undefined && !cmd.when()) continue
-
-    const action: SpotlightActionData = {
-      id,
-      label: cmd.label,
-      leftSection: cmd.icon,
-      keywords: [cmd.group ?? '', id].join(' ').trim(),
-      onClick: () => {
-        // id is the actual stash key (string from Object.entries), narrowed to CommandId for the typed callback
-        if (onTrigger !== undefined) {
-          onTrigger(id as CommandId)
-        } else {
-          runCommand(id as CommandId)
-        }
-      },
-    }
-    if (cmd.shortcut !== undefined) {
-      // detectMac() is SSR-safe (returns false when navigator is unavailable)
-      action.description = formatShortcutDisplay(cmd.shortcut, detectMac())
-    }
-    if (cmd.group !== undefined) action.group = cmd.group
-    actions.push(action)
-  }
-
-  return actions
-}
-
-// ── toRouteActions ────────────────────────────────────────────────────────────
-
-export type RouteActionItem = {
-  label: string
-  href?: string
-  icon?: ReactNode
-  disabled?: boolean
-  children?: RouteActionItem[]
-}
-
-export type RouteActionSection = {
-  /** Section label — the root segment of each item's breadcrumb-trail label. */
-  label: string
-  /** Section icon — inherited as the leftSection by items/children that have no icon of their own. */
-  icon?: ReactNode
-  items: RouteActionItem[]
-}
-
-export type ToRouteActionsOptions = {
-  /** Navigate to a route href — e.g. `(href) => router.navigate({ to: href })`. */
-  onNavigate: (href: string) => void
-  /** Prefix for generated action ids so they never collide with command ids. Default 'route:'. */
-  idPrefix?: string
-  /**
-   * Spotlight group for every produced action (e.g. 'Pages'). Omit for an ungrouped, flat list.
-   * Unlike the nav section (which becomes part of the breadcrumb label), this is a single kind
-   * bucket across all routes.
-   */
-  group?: string
-  /** Separator between breadcrumb segments in the action label. Default ' › '. */
-  separator?: string
-  /**
-   * Node rendered on the right of every action — e.g. a kind badge (`<Badge>Page</Badge>`). Lets
-   * the palette distinguish pages from commands at a glance regardless of grouping.
-   */
-  rightSection?: ReactNode
-}
-
-/**
- * Project a nav model (sections → items → nested children) into Mantine Spotlight
- * page-navigation actions. Pass the result to <BasaltOverlays spotlightActions={…}> so the palette
- * lists Pages alongside Commands.
- *
- * Each action's label is the full breadcrumb trail from the section down to the item
- * (e.g. `Overview › Dashboard › Sessions`), so a result is self-describing. Disabled items and
- * items without an href are skipped. An item/child without its own icon inherits the nearest
- * ancestor's (section → parent item), so sub-routes carry the parent's icon in the palette while
- * staying icon-less in a sidebar that renders them against a rail. Optionally assign one `group`
- * (a kind bucket like 'Pages') and a `rightSection` (a kind badge) to every action. Reads a static
- * snapshot — routes are static, so build it once.
- *
- * Structurally compatible with the shell's SidebarSection[] — pass your existing nav model directly.
+ * projectors — project the active command registry into the shortcut reference list that
+ * `ShortcutsHelp` renders. Reads the runtime stash (populated by `defineCommands`), not the
+ * type-erased `BasaltRegister` slot; safe to call before any commands are registered.
  */
-export function toRouteActions(
-  sections: RouteActionSection[],
-  options: ToRouteActionsOptions,
-): SpotlightActionData[] {
-  const { onNavigate, idPrefix = 'route:', separator = ' › ', group, rightSection } = options
-  const actions: SpotlightActionData[] = []
-
-  const walk = (items: RouteActionItem[], trail: string[], inheritedIcon?: ReactNode): void => {
-    for (const item of items) {
-      const itemTrail = [...trail, item.label]
-      const icon = item.icon ?? inheritedIcon
-      if (!item.disabled && item.href !== undefined) {
-        const href = item.href
-        const action: SpotlightActionData = {
-          id: `${idPrefix}${href}`,
-          label: itemTrail.join(separator),
-          leftSection: icon,
-          keywords: [...itemTrail, href].join(' '),
-          onClick: () => onNavigate(href),
-        }
-        if (group !== undefined) action.group = group
-        if (rightSection !== undefined) action.rightSection = rightSection
-        actions.push(action)
-      }
-      if (item.children !== undefined) walk(item.children, itemTrail, icon)
-    }
-  }
-
-  for (const section of sections) walk(section.items, [section.label], section.icon)
-  return actions
-}
+import { getActiveCommands } from './define-commands'
 
 // ── ShortcutEntry ─────────────────────────────────────────────────────────────
 
@@ -198,7 +24,7 @@ export type ShortcutEntry = {
  *
  * Reads a one-time snapshot of the runtime command stash at call time — commands registered AFTER
  * this is called (lazy/code-split) won't appear. Register all commands at module load before
- * mounting <BasaltOverlays>.
+ * rendering `ShortcutsHelp`.
  *
  * @example
  * const shortcuts = toShortcutList()
@@ -219,49 +45,3 @@ export function toShortcutList(): ShortcutEntry[] {
 
   return result
 }
-
-// ── toHotkeyBindings ──────────────────────────────────────────────────────────
-
-/**
- * Project the active command registry into a `UseHotkeyDefinition[]` bindings array — the exact
- * shape accepted by `useHotkeys` from `@tanstack/react-hotkeys`.
- *
- * Commands without a `shortcut` field are skipped. Commands where `when()` returns false are
- * included in the bindings but their callback is a no-op (the command is gated at call time, not
- * at registration time — this avoids hook-count churn when `when()` toggles).
- *
- * Reads a one-time snapshot of the runtime command stash.
- *
- * NOTE: the built-in useCommandHotkeys() does NOT call this function. It uses the imperative
- * getHotkeyManager() API from @tanstack/react-hotkeys directly (register/unregister per
- * mount/unmount cycle). toHotkeyBindings() is an opt-in convenience projector for consumers
- * who want to drive their own useHotkeys([...]) call — it is not on the path that
- * useCommandHotkeys() takes.
- *
- * @example
- * import { useHotkeys } from '@tanstack/react-hotkeys'
- * import { toHotkeyBindings } from 'basalt-ui/commands'
- *
- * function MyHotkeys() {
- *   useHotkeys(toHotkeyBindings())
- * }
- */
-export function toHotkeyBindings(): HotkeyBinding[] {
-  const cmds = getActiveCommands()
-  const bindings: HotkeyBinding[] = []
-
-  for (const [id, cmd] of Object.entries(cmds)) {
-    if (cmd.shortcut === undefined) continue
-
-    bindings.push({
-      hotkey: cmd.shortcut,
-      callback: () => {
-        // Respect the when() gate at execution time (not registration time)
-        if (cmd.when !== undefined && !cmd.when()) return
-        void runCommand(id as CommandId)
-      },
-    })
-  }
-
-  return bindings
-}

package/src/commands/shell-bridge.ts

@@ -15,7 +15,7 @@
  *
  * basalt registers BOTH setters itself — `BasaltProvider` calls {@link registerColorSchemeSetter}
  * from inside `MantineProvider` (`provider/index.tsx`'s `BasaltBridge`), `BasaltShell` calls
- * {@link registerSidebarToggle} (`shell/index.tsx`'s `ShellFrame`) — so a consumer's own
+ * {@link registerSidebarToggle} (`shell/index.tsx`'s `ShellBody`) — so a consumer's own
  * `commands.tsx` needs no `__root.tsx` wiring at all, unlike argo's hand-rolled version: mount
  * `BasaltProvider`/`BasaltShell` once, and `setColorScheme`/`toggleSidebar` just work.
  *
@@ -50,8 +50,8 @@ export function registerSidebarToggle(toggle: SidebarToggle | null): void {
 
 /**
  * Set the color scheme from outside the React tree. A no-op (with a dev-only console warning)
- * when no `BasaltProvider` is mounted yet — the same "not wired" shape `runCommand`/
- * `overlays.open` already use for an unregistered id.
+ * when no `BasaltProvider` is mounted yet — the same "not wired" shape
+ * `overlays.open` already uses for an unregistered id.
  *
  * @example
  * setColorScheme('dark')
@@ -59,7 +59,7 @@ export function registerSidebarToggle(toggle: SidebarToggle | null): void {
 export function setColorScheme(scheme: ColorScheme): void {
   if (colorSchemeSetterRef === null) {
     if (process.env['NODE_ENV'] !== 'production') {
-      // eslint-disable-next-line no-console -- dev-only diagnostic, mirrors runCommand's own
+      // eslint-disable-next-line no-console -- dev-only diagnostic
       console.warn('[basalt] setColorScheme: no BasaltProvider is mounted yet')
     }
     return
@@ -77,7 +77,7 @@ export function setColorScheme(scheme: ColorScheme): void {
 export function toggleSidebar(): void {
   if (sidebarToggleRef === null) {
     if (process.env['NODE_ENV'] !== 'production') {
-      // eslint-disable-next-line no-console -- dev-only diagnostic, mirrors runCommand's own
+      // eslint-disable-next-line no-console -- dev-only diagnostic
       console.warn('[basalt] toggleSidebar: no BasaltShell is mounted yet')
     }
     return