@djangocfg/ui-core 2.1.381 → 2.1.382

package/README.md

@@ -43,33 +43,19 @@ Organized in `components/` by category — everything re-exported from the root
 
 ### Boundary
 
-Wrap untrusted subtrees so a single render error does not crash the whole page.
-
 ```tsx
-import { Boundary } from '@djangocfg/ui-core';
+import { Boundary, useBoundary } from '@djangocfg/ui-core';
 
-// non-critical widget — disappears on error, page stays alive
 <Boundary variant="silent"><ChatLauncher /></Boundary>
+<Boundary variant="card" resetKeys={[pathname]}><Panel /></Boundary>
+```
 
-// inline status — compact alert with Retry
-<Boundary variant="inline" name="catalog-row"><Row /></Boundary>
-
-// feature panel — card with Retry button (default)
-<Boundary><AnalyticsPanel /></Boundary>
+Variants: `silent` / `inline` / `card` / `fullscreen`. Plus `useBoundary()` hook for async errors, `resetKeys`, `onReset`, custom `fallback` / `FallbackComponent`, and safe re-render guarantees.
 
-// fullscreen — for top-level layouts
-<Boundary variant="fullscreen"><AppShell /></Boundary>
+Full docs and patterns: [`src/components/boundary/README.md`](./src/components/boundary/README.md).
 
-// custom fallback + auto-reset on route change
-<Boundary
-  resetKeys={[pathname]}
-  fallback={({ error, reset }) => <MyErrorCard error={error} onRetry={reset} />}
->
-  <Page />
-</Boundary>
-```
+For automatic backend reporting use `MonitorBoundary` from `@djangocfg/layouts`.
 
-For automatic reporting to your backend, use `MonitorBoundary` from `@djangocfg/layouts` (it wraps `Boundary` and pushes events through `@djangocfg/monitor/client`).
 
 > Pagination, breadcrumb and sidebar live here (not in ui-nextjs). `SSRPagination` reads URL state through `useLocation` + `useQueryParams`, so it works under any router adapter.
 
@@ -88,7 +74,8 @@ import { useNavigate, useLocation, useQueryParams, useRouter, useIsActive } from
 | **State** | `useDebounce`, `useDebouncedCallback`, `useCountdown`, `useImageLoader`, `useMounted` |
 | **DOM** | `useEventListener` |
 | **Theme** | `useThemeColor`, `useThemePalette` (palette-aware hex colors for Canvas/SVG) |
-| **Hotkey** | `useHotkey`, `HotkeysProvider`, `useHotkeysContext` |
+| **Hotkey** | `useHotkey` (smart `inInput` + `preventDefault` policy), `useHotkeyChord` (sequences), `formatHotkey('mod+k') → ⌘K`, `useHotkeyHelp` (auto cheat-sheet) |
+| **Audio** | `createSoundBus`, `useNotificationSounds`, `useAudioPrefs`, `useSoundEffect` — Safari unlock, mute persist, per-event toggles + volume scale, native-host bridge |
 | **Feedback** | `useToast`, `toast` (Sonner) |
 | **Debug** | `useDebugTools` |
 
@@ -106,6 +93,83 @@ import NextLink from 'next/link';
 
 When no adapter is mounted, `<Link>` falls back to a plain `<a>` and routes clicks through the History API. `@djangocfg/layouts/BaseApp` mounts the Next adapters by default.
 
+## Hotkeys
+
+```tsx
+import { useHotkey, formatHotkey, useHotkeyChord } from '@djangocfg/ui-core/hooks';
+
+// Smart defaults — auto-detects modifiers vs bare keys:
+useHotkey('mod+k', openPalette);          // ⌘K everywhere, incl. inputs; preventDefault auto
+useHotkey('/', focusSearch);              // bare key — skipped inside inputs
+useHotkey('escape', closeModal);          // always fires in inputs (blur / close pattern)
+useHotkey('?', openHelp, { description: 'Show shortcuts' });  // registers in cheat-sheet
+
+// Linear-style chords:
+useHotkeyChord(['g', 't'], () => router.push('/tasks'));
+
+// OS-aware tooltips:
+formatHotkey('mod+/')   // → '⌘/' on Mac, 'Ctrl+/' elsewhere
+formatHotkey('g t')     // → 'G then T'
+```
+
+Built on `react-hotkeys-hook` with an opinionated policy: modifier-combos and `escape` fire inside `<input>` / `<textarea>` / `[contenteditable]` by default; bare keys don't, so they won't hijack typing. Override per-call with `inInput: true | false`.
+
+`useHotkeyHelp()` reads a module-level registry populated by every `useHotkey(..., { description })` call — drop it into a `?` cheat-sheet dialog with two lines.
+
+## Audio
+
+Notification sounds with Safari unlock, persisted mute, and a side-channel for native hosts.
+
+```tsx
+import { useNotificationSounds, useSoundEffect } from '@djangocfg/ui-core/hooks';
+
+// Map event → URL + persisted mute + per-event toggles
+type Event = 'received' | 'mention' | 'error';
+const sounds = useNotificationSounds<Event>({
+  storageKey: 'myapp.audio',
+  sounds: { received: '/sfx/r.mp3', mention: '/sfx/m.mp3', error: '/sfx/e.mp3' },
+});
+
+onMessage = (m) => sounds.play('received');
+toggle    = () => sounds.toggleMute();
+sounds.muted    // boolean, persisted
+sounds.isSilent // true if no sounds wired or silenced
+
+// One-shot single asset (no persistence, no toggles)
+const ding = useSoundEffect('/sfx/ding.mp3');
+<Button onClick={() => { ding.play(); submit(); }} />
+```
+
+**Native-host bridge.** When a wrapper (Electron / Wails / Tauri) plays sounds outside the browser, set `silenced: true` and pipe `onSoundEvent` to your bridge — web playback stays silent while the backend gets the trigger:
+
+```tsx
+useNotificationSounds({
+  storageKey: 'cmdop.audio',
+  silenced: true,
+  onSoundEvent: (event) => window.go.playSound(event),
+});
+```
+
+**Per-event volume scale.** Master volume is multiplied by an optional per-event factor so different sounds can be balanced without juggling source files:
+
+```tsx
+useNotificationSounds<Event>({
+  storageKey: 'myapp.audio',
+  sounds: { received: '/r.mp3', error: '/e.mp3', mention: '/m.mp3' },
+  eventVolumes: {
+    error: 0.25,    // soft ack — destructive UI is the loud signal
+    mention: 1,     // personal — louder than baseline
+    received: 0.7,
+  },
+});
+```
+
+The bus respects `prefers-reduced-motion`, `prefers-reduced-data`, and `visibilityState === 'hidden'` by default (each is an opt-out). Multi-component sync: same `storageKey` from different surfaces shares the same store.
+
+Lower level: `createSoundBus<E>({ sounds, getMuted, getVolume, isEnabled })` exposes the raw bus if you need to wire your own React state. `getVolume(event)` receives the event so you can scale per-fire.
+
+For an opinionated, fully-wired example with bundled audio assets see `useChatAudio` in [`@djangocfg/ui-tools`](../../ui-tools/src/tools/Chat/README.md#audio) — it inlines six notification mp3s into the lazy chat chunk as `data:`-URLs so consumers need no asset setup.
+
 ## Schema-driven configurators
 
 `@djangocfg/ui-core/lib` exports a portable JSON Schema 7 subset (`CustomJsonSchema7`, `CustomJsonUiSchema7`, `CustomJsonUiGroup`, `CustomJsonUiDisabledWhenRule`) for packages that ship configurator schemas without taking a runtime dependency on RJSF.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-core",
-  "version": "2.1.381",
+  "version": "2.1.382",
   "description": "Pure React UI component library without Next.js dependencies - for Electron, Vite, CRA apps",
   "keywords": [
     "ui-components",
@@ -96,7 +96,7 @@
     "playground": "playground dev"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.381",
+    "@djangocfg/i18n": "^2.1.382",
     "consola": "^3.4.2",
     "lucide-react": "^0.545.0",
     "moment": "^2.30.1",
@@ -166,9 +166,9 @@
     "vaul": "1.1.2"
   },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.381",
+    "@djangocfg/i18n": "^2.1.382",
     "@djangocfg/playground": "workspace:*",
-    "@djangocfg/typescript-config": "^2.1.381",
+    "@djangocfg/typescript-config": "^2.1.382",
     "@types/node": "^24.7.2",
     "@types/react": "^19.1.0",
     "@types/react-dom": "^19.1.0",

package/src/components/boundary/Boundary.tsx

@@ -1,7 +1,14 @@
 'use client';
 
 import { AlertTriangle, RotateCcw } from 'lucide-react';
-import { Component, type ErrorInfo, type ReactNode } from 'react';
+import {
+  Component,
+  createContext,
+  useContext,
+  type ComponentType,
+  type ErrorInfo,
+  type ReactNode,
+} from 'react';
 
 import { isDev } from '../../lib/env';
 import { cn } from '../../lib/utils';
@@ -11,16 +18,29 @@ export type BoundaryVariant = 'silent' | 'inline' | 'card' | 'fullscreen';
 
 export interface BoundaryRenderProps {
   error: Error;
+  errorInfo: ErrorInfo | null;
   reset: () => void;
 }
 
+export type BoundaryResetReason = 'imperative' | 'keys';
+
+export interface BoundaryResetDetails {
+  reason: BoundaryResetReason;
+  prevResetKeys?: ReadonlyArray<unknown>;
+  nextResetKeys?: ReadonlyArray<unknown>;
+}
+
+export interface BoundaryLogger {
+  (message: string, error: Error, info: ErrorInfo | null): void;
+}
+
 export interface BoundaryProps {
   children: ReactNode;
   /**
    * Visual style of the fallback.
    * - silent: render nothing (good for non-critical widgets like a chat launcher)
    * - inline: compact one-line warning (good for inline blocks inside a page)
-   * - card: bordered card with retry button (good for panels/features)
+   * - card: bordered card with retry button (default; good for panels/features)
    * - fullscreen: centered fullscreen fallback (good for top-level layout)
    * @default 'card'
    */
@@ -28,29 +48,76 @@ export interface BoundaryProps {
   /**
    * Custom fallback. Receives the caught error and a reset() function.
    * Overrides `variant` rendering when provided.
+   * Takes precedence over `FallbackComponent`.
    */
   fallback?: ReactNode | ((props: BoundaryRenderProps) => ReactNode);
   /**
-   * Auto-reset the boundary when any of these values change.
-   * Common use: pass the current pathname or a feature id.
+   * Custom fallback component. Use this form instead of `fallback` for
+   * better memoization (no inline closures).
+   */
+  FallbackComponent?: ComponentType<BoundaryRenderProps>;
+  /**
+   * Auto-reset the boundary when any of these values change (shallow Object.is per index).
+   * Common use: pass `[pathname]` to clear errors on route change.
+   * AVOID passing volatile values like `Math.random()` or new object/array literals — causes reset loops.
    */
   resetKeys?: ReadonlyArray<unknown>;
   /**
-   * Called when an error is caught. Hook up Sentry / logging here.
+   * Called when an error is caught.
+   * Hook up Sentry / logging / @djangocfg/monitor here.
+   * Use the wrapping `MonitorBoundary` from @djangocfg/layouts for automatic reporting.
    */
   onError?: (error: Error, info: ErrorInfo) => void;
+  /**
+   * Called when the boundary recovers (via Retry button or resetKeys change).
+   * Use it to refetch data / invalidate caches (e.g. React Query queryClient.invalidateQueries).
+   */
+  onReset?: (details: BoundaryResetDetails) => void;
   /**
    * Optional label shown in dev console logs to help locate the source.
    */
   name?: string;
   /**
-   * Extra className for the fallback wrapper (variant: inline / card).
+   * Extra className for the fallback wrapper (variant: inline / card / fullscreen).
    */
   className?: string;
+  /**
+   * Replace default dev console logger. Defaults to `console.error` in development, no-op in production.
+   */
+  logger?: BoundaryLogger;
 }
 
 interface BoundaryState {
   error: Error | null;
+  errorInfo: ErrorInfo | null;
+}
+
+interface BoundaryContextValue {
+  /** Programmatically push an error into the nearest boundary (use for async / event handler errors). */
+  showBoundary: (error: unknown) => void;
+  /** Programmatically clear the boundary (same as the Retry button). */
+  resetBoundary: () => void;
+}
+
+const BoundaryContext = createContext<BoundaryContextValue | null>(null);
+
+/**
+ * Access the nearest `<Boundary>` programmatically.
+ * Lets you funnel errors from async code / event handlers into the boundary
+ * (regular React error boundaries don't catch those automatically).
+ *
+ * @example
+ * const { showBoundary } = useBoundary();
+ * useEffect(() => {
+ *   fetchData().catch(showBoundary);
+ * }, [showBoundary]);
+ */
+export function useBoundary(): BoundaryContextValue {
+  const ctx = useContext(BoundaryContext);
+  if (!ctx) {
+    throw new Error('useBoundary must be used inside <Boundary>');
+  }
+  return ctx;
 }
 
 function arraysShallowEqual(a: ReadonlyArray<unknown>, b: ReadonlyArray<unknown>): boolean {
@@ -61,19 +128,57 @@ function arraysShallowEqual(a: ReadonlyArray<unknown>, b: ReadonlyArray<unknown>
   return true;
 }
 
+function toError(value: unknown): Error {
+  if (value instanceof Error) return value;
+  if (typeof value === 'string') return new Error(value);
+  try {
+    return new Error(JSON.stringify(value));
+  } catch {
+    return new Error('Unknown error');
+  }
+}
+
+const defaultLogger: BoundaryLogger = (message, error, info) => {
+  if (!isDev) return;
+  console.error(message, error, info ?? '');
+};
+
 export class Boundary extends Component<BoundaryProps, BoundaryState> {
-  state: BoundaryState = { error: null };
+  state: BoundaryState = { error: null, errorInfo: null };
+
+  /** Stable context value identity — recreated only when error/reset functions change (i.e. on mount). */
+  private contextValue: BoundaryContextValue = {
+    showBoundary: (error: unknown) => this.showBoundary(error),
+    resetBoundary: () => this.reset('imperative'),
+  };
+
+  /** Prevents `onError` from firing twice for the same error instance. */
+  private lastReportedError: Error | null = null;
 
-  static getDerivedStateFromError(error: Error): BoundaryState {
-    return { error };
+  static getDerivedStateFromError(error: unknown): BoundaryState {
+    return { error: toError(error), errorInfo: null };
   }
 
   componentDidCatch(error: Error, info: ErrorInfo) {
-    this.props.onError?.(error, info);
-    if (isDev) {
-      const tag = this.props.name ? `[Boundary:${this.props.name}]` : '[Boundary]';
-      console.error(tag, error, info);
+    const normalized = toError(error);
+    this.setState({ errorInfo: info });
+
+    if (this.lastReportedError === normalized) return;
+    this.lastReportedError = normalized;
+
+    try {
+      this.props.onError?.(normalized, info);
+    } catch (callbackErr) {
+      // Never let user's onError crash the boundary.
+      (this.props.logger ?? defaultLogger)(
+        `[Boundary${this.props.name ? `:${this.props.name}` : ''}] onError handler threw`,
+        toError(callbackErr),
+        null,
+      );
     }
+
+    const tag = this.props.name ? `[Boundary:${this.props.name}]` : '[Boundary]';
+    (this.props.logger ?? defaultLogger)(`${tag} caught error`, normalized, info);
   }
 
   componentDidUpdate(prevProps: BoundaryProps) {
@@ -81,28 +186,92 @@ export class Boundary extends Component<BoundaryProps, BoundaryState> {
     const prevKeys = prevProps.resetKeys;
     const nextKeys = this.props.resetKeys;
     if (prevKeys && nextKeys && !arraysShallowEqual(prevKeys, nextKeys)) {
-      this.reset();
+      this.reset('keys', prevKeys, nextKeys);
     }
   }
 
-  reset = () => {
-    this.setState({ error: null });
+  /** Imperatively raise an error from async code / event handlers via `useBoundary()`. */
+  showBoundary = (raw: unknown) => {
+    const error = toError(raw);
+    this.setState({ error, errorInfo: null });
   };
 
-  render() {
-    const { error } = this.state;
-    if (!error) return this.props.children;
+  reset = (
+    reason: BoundaryResetReason = 'imperative',
+    prevResetKeys?: ReadonlyArray<unknown>,
+    nextResetKeys?: ReadonlyArray<unknown>,
+  ) => {
+    // Clear state BEFORE calling onReset — otherwise an error thrown
+    // inside onReset would re-trigger the boundary before state is cleared.
+    this.lastReportedError = null;
+    this.setState({ error: null, errorInfo: null });
 
-    const { fallback, variant = 'card', className } = this.props;
+    // Defer onReset to a microtask so the state clear is flushed first.
+    queueMicrotask(() => {
+      try {
+        this.props.onReset?.({ reason, prevResetKeys, nextResetKeys });
+      } catch (err) {
+        (this.props.logger ?? defaultLogger)(
+          `[Boundary${this.props.name ? `:${this.props.name}` : ''}] onReset handler threw`,
+          toError(err),
+          null,
+        );
+      }
+    });
+  };
 
-    if (typeof fallback === 'function') {
-      return fallback({ error, reset: this.reset });
-    }
-    if (fallback !== undefined) {
-      return fallback;
+  /** Wraps fallback rendering so errors in the fallback itself can't crash the boundary. */
+  private safeRenderFallback(): ReactNode {
+    const { error, errorInfo } = this.state;
+    if (!error) return null;
+
+    const { fallback, FallbackComponent, variant = 'card', className } = this.props;
+
+    try {
+      if (typeof fallback === 'function') {
+        return fallback({ error, errorInfo, reset: () => this.reset('imperative') });
+      }
+      if (fallback !== undefined) {
+        return fallback;
+      }
+      if (FallbackComponent) {
+        return (
+          <FallbackComponent
+            error={error}
+            errorInfo={errorInfo}
+            reset={() => this.reset('imperative')}
+          />
+        );
+      }
+      return renderVariant(variant, error, () => this.reset('imperative'), className);
+    } catch (fallbackError) {
+      // Last-resort static fallback — prevents infinite loops if user fallback throws.
+      (this.props.logger ?? defaultLogger)(
+        `[Boundary${this.props.name ? `:${this.props.name}` : ''}] fallback render threw`,
+        toError(fallbackError),
+        null,
+      );
+      return (
+        <div
+          role="alert"
+          aria-live="assertive"
+          className="p-2 text-sm text-destructive border border-destructive/40 rounded"
+        >
+          Something went wrong, and the error fallback also failed to render.
+        </div>
+      );
     }
+  }
 
-    return renderVariant(variant, error, this.reset, className);
+  render() {
+    if (this.state.error) {
+      return this.safeRenderFallback();
+    }
+    return (
+      <BoundaryContext.Provider value={this.contextValue}>
+        {this.props.children}
+      </BoundaryContext.Provider>
+    );
   }
 }
 
@@ -120,15 +289,14 @@ function renderVariant(
     return (
       <div
         role="alert"
+        aria-live="assertive"
         className={cn(
           'flex items-center gap-2 rounded-md border border-destructive/30 bg-destructive/5 px-3 py-2 text-sm text-destructive',
           className,
         )}
       >
         <AlertTriangle className="h-4 w-4 shrink-0" />
-        <span className="flex-1 truncate">
-          {message ?? 'Something went wrong.'}
-        </span>
+        <span className="flex-1 truncate">{message ?? 'Something went wrong.'}</span>
         <button
           type="button"
           onClick={reset}
@@ -143,7 +311,11 @@ function renderVariant(
 
   if (variant === 'fullscreen') {
     return (
-      <div className={cn('flex min-h-screen items-center justify-center bg-background p-4', className)}>
+      <div
+        role="alert"
+        aria-live="assertive"
+        className={cn('flex min-h-screen items-center justify-center bg-background p-4', className)}
+      >
         <div className="max-w-md w-full space-y-4 text-center">
           <AlertTriangle className="mx-auto h-10 w-10 text-destructive" />
           <h1 className="text-2xl font-bold text-foreground">Something went wrong</h1>
@@ -171,6 +343,7 @@ function renderVariant(
   return (
     <div
       role="alert"
+      aria-live="assertive"
       className={cn(
         'rounded-[var(--radius)] border border-destructive/40 bg-destructive/5 p-4 text-sm',
         className,
@@ -180,9 +353,7 @@ function renderVariant(
         <AlertTriangle className="mt-0.5 h-4 w-4 shrink-0 text-destructive" />
         <div className="flex-1 space-y-2">
           <p className="font-medium text-destructive">Something went wrong</p>
-          {message && (
-            <p className="text-xs text-muted-foreground break-words">{message}</p>
-          )}
+          {message && <p className="text-xs text-muted-foreground break-words">{message}</p>}
           <Button size="sm" variant="outline" onClick={reset}>
             <RotateCcw className="mr-2 h-3 w-3" />
             Try again