@djangocfg/ui-core 2.1.380 → 2.1.382

package/README.md

@@ -37,9 +37,26 @@ Organized in `components/` by category — everything re-exported from the root
 | **Layout** | `Card`, `Section`, `Sticky`, `ScrollArea`, `Resizable`, `Separator`, `Skeleton`, `AspectRatio` |
 | **Data** | `Table`, `Badge`, `Avatar`, `Progress`, `Carousel`, `Calendar`, `DatePicker`, `DateRangePicker`, `Toggle`, `ToggleGroup`, `Chart*` |
 | **Feedback** | `Alert`, `Spinner`, `Empty`, `Preloader`, `Toaster` (Sonner) |
+| **Boundary** | `Boundary` (React error boundary with `silent`/`inline`/`card`/`fullscreen` variants, `resetKeys`, custom `fallback`) |
 | **Specialized** | `Kbd`, `CopyButton`, `CopyField`, `TokenIcon`, `Item`, `Portal`, `ImageWithFallback`, `Flag`, `LanguageFlag` |
 | **Effects** | `GlowBackground` |
 
+### Boundary
+
+```tsx
+import { Boundary, useBoundary } from '@djangocfg/ui-core';
+
+<Boundary variant="silent"><ChatLauncher /></Boundary>
+<Boundary variant="card" resetKeys={[pathname]}><Panel /></Boundary>
+```
+
+Variants: `silent` / `inline` / `card` / `fullscreen`. Plus `useBoundary()` hook for async errors, `resetKeys`, `onReset`, custom `fallback` / `FallbackComponent`, and safe re-render guarantees.
+
+Full docs and patterns: [`src/components/boundary/README.md`](./src/components/boundary/README.md).
+
+For automatic backend reporting use `MonitorBoundary` from `@djangocfg/layouts`.
+
+
 > Pagination, breadcrumb and sidebar live here (not in ui-nextjs). `SSRPagination` reads URL state through `useLocation` + `useQueryParams`, so it works under any router adapter.
 
 ## Hooks
@@ -57,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` |
 
@@ -75,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.380",
+  "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.380",
+    "@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.380",
+    "@djangocfg/i18n": "^2.1.382",
     "@djangocfg/playground": "workspace:*",
-    "@djangocfg/typescript-config": "^2.1.380",
+    "@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

@@ -0,0 +1,365 @@
+'use client';
+
+import { AlertTriangle, RotateCcw } from 'lucide-react';
+import {
+  Component,
+  createContext,
+  useContext,
+  type ComponentType,
+  type ErrorInfo,
+  type ReactNode,
+} from 'react';
+
+import { isDev } from '../../lib/env';
+import { cn } from '../../lib/utils';
+import { Button } from '../forms/button';
+
+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 (default; good for panels/features)
+   * - fullscreen: centered fullscreen fallback (good for top-level layout)
+   * @default 'card'
+   */
+  variant?: BoundaryVariant;
+  /**
+   * Custom fallback. Receives the caught error and a reset() function.
+   * Overrides `variant` rendering when provided.
+   * Takes precedence over `FallbackComponent`.
+   */
+  fallback?: ReactNode | ((props: BoundaryRenderProps) => ReactNode);
+  /**
+   * 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 / @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 / 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 {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    if (!Object.is(a[i], b[i])) return false;
+  }
+  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, 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: unknown): BoundaryState {
+    return { error: toError(error), errorInfo: null };
+  }
+
+  componentDidCatch(error: Error, info: ErrorInfo) {
+    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) {
+    if (!this.state.error) return;
+    const prevKeys = prevProps.resetKeys;
+    const nextKeys = this.props.resetKeys;
+    if (prevKeys && nextKeys && !arraysShallowEqual(prevKeys, nextKeys)) {
+      this.reset('keys', prevKeys, nextKeys);
+    }
+  }
+
+  /** Imperatively raise an error from async code / event handlers via `useBoundary()`. */
+  showBoundary = (raw: unknown) => {
+    const error = toError(raw);
+    this.setState({ error, errorInfo: null });
+  };
+
+  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 });
+
+    // 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,
+        );
+      }
+    });
+  };
+
+  /** 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>
+      );
+    }
+  }
+
+  render() {
+    if (this.state.error) {
+      return this.safeRenderFallback();
+    }
+    return (
+      <BoundaryContext.Provider value={this.contextValue}>
+        {this.props.children}
+      </BoundaryContext.Provider>
+    );
+  }
+}
+
+function renderVariant(
+  variant: BoundaryVariant,
+  error: Error,
+  reset: () => void,
+  className?: string,
+): ReactNode {
+  if (variant === 'silent') return null;
+
+  const message = isDev ? error.message : null;
+
+  if (variant === 'inline') {
+    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>
+        <button
+          type="button"
+          onClick={reset}
+          className="inline-flex items-center gap-1 rounded px-1.5 py-0.5 text-xs font-medium underline-offset-2 hover:underline"
+        >
+          <RotateCcw className="h-3 w-3" />
+          Retry
+        </button>
+      </div>
+    );
+  }
+
+  if (variant === 'fullscreen') {
+    return (
+      <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>
+          <p className="text-muted-foreground">
+            We&apos;re sorry, but something unexpected happened. Please try refreshing the page.
+          </p>
+          {message && (
+            <pre className="text-left text-xs text-muted-foreground bg-muted rounded p-2 overflow-auto max-h-40">
+              {message}
+            </pre>
+          )}
+          <div className="flex justify-center gap-2">
+            <Button variant="outline" onClick={reset}>
+              <RotateCcw className="mr-2 h-4 w-4" />
+              Try again
+            </Button>
+            <Button onClick={() => window.location.reload()}>Refresh page</Button>
+          </div>
+        </div>
+      </div>
+    );
+  }
+
+  // card (default)
+  return (
+    <div
+      role="alert"
+      aria-live="assertive"
+      className={cn(
+        'rounded-[var(--radius)] border border-destructive/40 bg-destructive/5 p-4 text-sm',
+        className,
+      )}
+    >
+      <div className="flex items-start gap-3">
+        <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>}
+          <Button size="sm" variant="outline" onClick={reset}>
+            <RotateCcw className="mr-2 h-3 w-3" />
+            Try again
+          </Button>
+        </div>
+      </div>
+    </div>
+  );
+}