@djangocfg/ui-core 2.1.381 → 2.1.382

package/src/components/boundary/README.md

@@ -0,0 +1,249 @@
+# Boundary
+
+React error boundary primitive with four visual variants, a `useBoundary()` hook for async errors, and safe-by-default behaviour (no infinite loops, normalized errors, accessible fallbacks).
+
+Designed as a drop-in replacement for `react-error-boundary` with batteries included: built-in fallback variants, dev logging, optional context-based escape hatch.
+
+---
+
+## When to use
+
+| Situation | Component |
+|---|---|
+| Wrap a non-critical widget (chat launcher, embed, ad) | `<Boundary variant="silent">` |
+| Wrap a row / inline block (table cell, list item) | `<Boundary variant="inline">` |
+| Wrap a feature panel (analytics card, settings group) | `<Boundary>` (card, default) |
+| Wrap an entire screen / root layout | `<Boundary variant="fullscreen">` |
+| Page/layout level with backend reporting | `<MonitorBoundary>` from `@djangocfg/layouts` |
+
+**Granularity matters.** One global boundary at the app root hides bugs and ruins UX (whole page = error screen). Prefer many small per-feature boundaries.
+
+---
+
+## Basic usage
+
+```tsx
+import { Boundary } from '@djangocfg/ui-core';
+
+<Boundary variant="card" name="dashboard-stats">
+  <StatsPanel />
+</Boundary>
+```
+
+The `name` prop is used in dev console logs — set it to something findable.
+
+---
+
+## Variants
+
+```tsx
+<Boundary variant="silent">…</Boundary>      // renders null on error
+<Boundary variant="inline">…</Boundary>      // compact one-line alert + Retry
+<Boundary variant="card">…</Boundary>        // bordered card with Retry (default)
+<Boundary variant="fullscreen">…</Boundary>  // centered fullscreen + Refresh page
+```
+
+All visible variants get `role="alert"` and `aria-live="assertive"` so screen readers announce them.
+
+---
+
+## Custom fallback
+
+Two forms — pick by use case:
+
+```tsx
+// Render-prop: simple inline cases
+<Boundary fallback={({ error, reset }) => <MyError onRetry={reset} />}>…</Boundary>
+
+// Component: better for memoization / testing
+function MyFallback({ error, errorInfo, reset }: BoundaryRenderProps) {
+  return <ErrorCard message={error.message} onRetry={reset} />;
+}
+<Boundary FallbackComponent={MyFallback}>…</Boundary>
+```
+
+`fallback` (function form) takes precedence over `FallbackComponent`. Both receive `{ error, errorInfo, reset }`.
+
+---
+
+## Reset patterns
+
+### 1. Auto-reset on route change
+
+```tsx
+const pathname = usePathname();
+<Boundary resetKeys={[pathname]}>{children}</Boundary>
+```
+
+When any value in `resetKeys` changes (shallow `Object.is` per index), the boundary clears its error state.
+
+**⚠ Anti-pattern:** `resetKeys={[Math.random()]}` or `resetKeys={[{}, []]}` causes an infinite reset loop because the array contents change on every render.
+
+### 2. React Query / refetch on recovery
+
+```tsx
+<Boundary
+  onReset={({ reason }) => {
+    // reason === 'imperative' (Retry button) or 'keys' (resetKeys changed)
+    queryClient.invalidateQueries({ queryKey: ['dashboard'] });
+  }}
+>
+  <Dashboard />
+</Boundary>
+```
+
+`onReset` is called in a microtask **after** state is cleared — your refetch sees a fresh component.
+
+### 3. Full remount (rare)
+
+If you need to fully discard component state (not just the error), use React's `key` prop instead:
+
+```tsx
+<Boundary key={feature.id} resetKeys={[feature.id]}>…</Boundary>
+```
+
+---
+
+## Async / event-handler errors
+
+**React error boundaries do not catch async errors.** That's a React limitation, not a bug.
+
+Use `useBoundary()` to push them into the nearest boundary:
+
+```tsx
+import { useBoundary } from '@djangocfg/ui-core';
+
+function LoadButton() {
+  const { showBoundary, resetBoundary } = useBoundary();
+
+  return (
+    <Button onClick={async () => {
+      try {
+        await api.loadData();
+      } catch (err) {
+        showBoundary(err);  // bubbles up to the closest <Boundary>
+      }
+    }}>
+      Load
+    </Button>
+  );
+}
+```
+
+`useBoundary()` works inside any component rendered under a `<Boundary>`. Throws if used outside one.
+
+---
+
+## Logging
+
+By default, caught errors are logged with `console.error` in development and silenced in production. Wire to your telemetry by passing `logger` or `onError`:
+
+```tsx
+<Boundary
+  onError={(error, info) => {
+    Sentry.captureException(error, { extra: { componentStack: info.componentStack } });
+  }}
+>
+  …
+</Boundary>
+```
+
+Or use `MonitorBoundary` from `@djangocfg/layouts` for automatic reporting to `@djangocfg/monitor`.
+
+---
+
+## Safety guarantees
+
+- **Fallback can throw safely.** If the user's fallback render itself errors, the boundary degrades to a minimal static alert instead of looping forever.
+- **`onError` / `onReset` can throw safely.** Caught and logged via `logger`. Won't crash the boundary.
+- **Non-`Error` throws are normalized.** `throw 'oops'`, `throw { code: 500 }` and bare objects become real `Error` instances with stack traces (where possible).
+- **No duplicate `onError` calls.** Internal tracking prevents firing twice for the same error instance.
+- **Reset clears state before `onReset`.** Errors thrown inside `onReset` don't re-trigger the just-cleared boundary.
+
+---
+
+## Pairing with `<Suspense>`
+
+Put `<Boundary>` **outside** `<Suspense>` — otherwise errors thrown by a suspended component bubble past it.
+
+```tsx
+<Boundary variant="card">
+  <Suspense fallback={<Spinner />}>
+    <DataPanel />
+  </Suspense>
+</Boundary>
+```
+
+---
+
+## Edge cases & gotchas
+
+| Issue | Cause | Solution |
+|---|---|---|
+| Boundary doesn't catch error | Error thrown in async code / event handler | Use `useBoundary().showBoundary(err)` |
+| Boundary doesn't catch error (SSR) | `componentDidCatch` doesn't run on server | Errors are caught on client hydration. For SSR-only errors, use Next.js `error.tsx` |
+| Infinite reset loop | `resetKeys` contains unstable values | Don't put new objects/arrays/random in `resetKeys` |
+| Fallback renders briefly with stale data | React 18 concurrent rendering / `useDeferredValue` | Expected — the boundary unmounts children on error |
+| `error.stack` is missing | Code threw a non-`Error` value | Boundary normalizes, but stack is reconstructed from current line. Prefer `throw new Error(...)` |
+| Component stack only in dev | React strips it in prod by default | Use `onError`'s `info.componentStack` server-side via monitor |
+
+---
+
+## API
+
+```ts
+interface BoundaryProps {
+  children: ReactNode;
+  variant?: 'silent' | 'inline' | 'card' | 'fullscreen';  // default 'card'
+  fallback?: ReactNode | ((props: BoundaryRenderProps) => ReactNode);
+  FallbackComponent?: ComponentType<BoundaryRenderProps>;
+  resetKeys?: ReadonlyArray<unknown>;
+  onError?: (error: Error, info: ErrorInfo) => void;
+  onReset?: (details: BoundaryResetDetails) => void;
+  name?: string;           // dev log tag
+  className?: string;      // fallback wrapper className
+  logger?: BoundaryLogger; // override default console.error in dev
+}
+
+interface BoundaryRenderProps {
+  error: Error;
+  errorInfo: ErrorInfo | null;
+  reset: () => void;
+}
+
+interface BoundaryResetDetails {
+  reason: 'imperative' | 'keys';
+  prevResetKeys?: ReadonlyArray<unknown>;
+  nextResetKeys?: ReadonlyArray<unknown>;
+}
+
+function useBoundary(): {
+  showBoundary: (error: unknown) => void;
+  resetBoundary: () => void;
+};
+```
+
+---
+
+## Comparison with `react-error-boundary`
+
+| Feature | `react-error-boundary` | `@djangocfg/ui-core` `Boundary` |
+|---|---|---|
+| `fallback` / `fallbackRender` / `FallbackComponent` | ✅ separate props | ✅ unified: `fallback` (node or fn) + `FallbackComponent` |
+| `resetKeys` | ✅ | ✅ (shallow `Object.is` per index) |
+| `onError` | ✅ | ✅ |
+| `onReset` | ✅ | ✅ (with `reason` + prev/next keys) |
+| `useErrorBoundary()` / `useBoundary()` | ✅ | ✅ |
+| Built-in visual variants | ❌ | ✅ silent / inline / card / fullscreen |
+| Safe fallback rendering | ❌ (can loop) | ✅ |
+| `onError` / `onReset` thrown errors caught | ❌ | ✅ |
+| Non-Error normalization | ❌ | ✅ |
+| Accessible defaults (`role`, `aria-live`) | ❌ | ✅ |
+| Backend telemetry integration | manual | `MonitorBoundary` wrapper |
+
+---
+
+## Related
+
+- **`MonitorBoundary`** (`@djangocfg/layouts`) — wraps `Boundary` and reports to `@djangocfg/monitor` automatically.
+- **Next.js `error.tsx`** — handles route-level errors. Use `Boundary` *inside* pages for finer granularity.

package/src/components/boundary/boundary.story.tsx

@@ -2,17 +2,17 @@ import { defineStory, useSelect } from '@djangocfg/playground';
 import { useState } from 'react';
 
 import { Button } from '../forms/button';
-import { Boundary } from '.';
-import type { BoundaryVariant } from '.';
+import { Boundary, useBoundary } from '.';
+import type { BoundaryRenderProps, BoundaryVariant } from '.';
 
 export default defineStory({
   title: 'Core/Boundary',
   component: Boundary,
   description:
-    'React error boundary with multiple visual variants. Wrap untrusted subtrees (widgets, third-party iframes, dynamic renderers) so a single render error does not crash the whole page.',
+    'React error boundary with multiple visual variants. Wrap untrusted subtrees (widgets, third-party iframes, dynamic renderers) so a single render error does not crash the whole page. Includes `useBoundary()` hook for async / event-handler errors.',
 });
 
-function BoomButton({ label = 'Throw error' }: { label?: string }) {
+function BoomButton({ label = 'Throw render error' }: { label?: string }) {
   const [boom, setBoom] = useState(false);
   if (boom) throw new Error('Demo crash from BoomButton');
   return (
@@ -90,13 +90,36 @@ export const CustomFallback = () => (
   </div>
 );
 
+function MyFallback({ error, reset }: BoundaryRenderProps) {
+  return (
+    <div className="rounded-md border border-blue-500/40 bg-blue-500/5 p-4">
+      <p className="text-sm font-semibold text-blue-700">FallbackComponent prop</p>
+      <p className="mt-1 text-xs text-blue-700/80">{error.message}</p>
+      <Button size="sm" variant="outline" className="mt-2" onClick={reset}>
+        Reset
+      </Button>
+    </div>
+  );
+}
+
+export const FallbackComponentProp = () => (
+  <div className="max-w-lg space-y-2">
+    <p className="text-sm text-muted-foreground">
+      Pass a component type instead of a render function — better memoization, easier to test.
+    </p>
+    <Boundary FallbackComponent={MyFallback}>
+      <BoomButton />
+    </Boundary>
+  </div>
+);
+
 export const ResetKeys = () => {
   const [key, setKey] = useState(0);
   return (
     <div className="max-w-lg space-y-3">
       <p className="text-sm text-muted-foreground">
         Pass <code className="text-xs">resetKeys</code> — when any value in the array changes, the boundary auto-resets.
-        Good for clearing errors on route change.
+        Good for clearing errors on route change (e.g. <code className="text-xs">[pathname]</code>).
       </p>
       <Button size="sm" onClick={() => setKey((k) => k + 1)}>
         Bump resetKey ({key})
@@ -107,3 +130,62 @@ export const ResetKeys = () => {
     </div>
   );
 };
+
+export const OnResetCallback = () => {
+  const [resets, setResets] = useState<string[]>([]);
+  return (
+    <div className="max-w-lg space-y-3">
+      <p className="text-sm text-muted-foreground">
+        <code className="text-xs">onReset</code> fires when the boundary recovers — wire it to React Query invalidation, refetch, etc.
+      </p>
+      <Boundary
+        variant="card"
+        onReset={(details) =>
+          setResets((prev) => [...prev, `reset @ ${new Date().toISOString().slice(11, 19)} (${details.reason})`])
+        }
+      >
+        <BoomButton />
+      </Boundary>
+      <div className="text-xs text-muted-foreground">
+        Resets:
+        <ul className="mt-1 space-y-0.5">
+          {resets.map((r, i) => (
+            <li key={i}>· {r}</li>
+          ))}
+        </ul>
+      </div>
+    </div>
+  );
+};
+
+function AsyncCrasher() {
+  const { showBoundary } = useBoundary();
+  return (
+    <Button
+      variant="outline"
+      size="sm"
+      onClick={async () => {
+        // Regular React boundaries DON'T catch this. useBoundary() does.
+        await new Promise((r) => setTimeout(r, 200));
+        try {
+          throw new Error('Async fetch failed after 200ms');
+        } catch (err) {
+          showBoundary(err);
+        }
+      }}
+    >
+      Throw async error
+    </Button>
+  );
+}
+
+export const AsyncErrorsViaHook = () => (
+  <div className="max-w-lg space-y-2">
+    <p className="text-sm text-muted-foreground">
+      React error boundaries only catch <em>render</em> errors. Use <code className="text-xs">useBoundary().showBoundary(err)</code> to push async / event-handler errors into the nearest boundary.
+    </p>
+    <Boundary variant="card" name="async-demo">
+      <AsyncCrasher />
+    </Boundary>
+  </div>
+);

package/src/components/boundary/index.ts

@@ -1,2 +1,9 @@
-export { Boundary } from './Boundary';
-export type { BoundaryProps, BoundaryVariant, BoundaryRenderProps } from './Boundary';
+export { Boundary, useBoundary } from './Boundary';
+export type {
+  BoundaryProps,
+  BoundaryVariant,
+  BoundaryRenderProps,
+  BoundaryResetReason,
+  BoundaryResetDetails,
+  BoundaryLogger,
+} from './Boundary';

package/src/components/index.ts

@@ -165,8 +165,15 @@ export { Toaster } from './feedback/sonner';
 // ─────────────────────────────────────────────────────────────────────────────
 // Boundary
 // ─────────────────────────────────────────────────────────────────────────────
-export { Boundary } from './boundary';
-export type { BoundaryProps, BoundaryVariant, BoundaryRenderProps } from './boundary';
+export { Boundary, useBoundary } from './boundary';
+export type {
+  BoundaryProps,
+  BoundaryVariant,
+  BoundaryRenderProps,
+  BoundaryResetReason,
+  BoundaryResetDetails,
+  BoundaryLogger,
+} from './boundary';
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Specialized

package/src/components/select/combobox.tsx

@@ -38,6 +38,23 @@ export interface ComboboxProps {
   disabled?: boolean
   renderOption?: (option: ComboboxOption) => React.ReactNode
   renderValue?: (option: ComboboxOption | undefined) => React.ReactNode
+  /**
+   * Replace the default `<Button variant="outline" w-full>` trigger
+   * entirely. Use when the default trigger is too wide / too heavy for
+   * the host (e.g. a 28×28 flag icon in a chat header). The element
+   * receives Radix `PopoverTrigger asChild` props (refs + a11y) so
+   * pass any native element here — `button`, `div role="button"`, etc.
+   */
+  renderTrigger?: (
+    selected: ComboboxOption | undefined,
+    open: boolean,
+  ) => React.ReactElement
+  /** Forwarded to `PopoverContent.className` — width, padding, etc. */
+  contentClassName?: string
+  /** Forwarded to `PopoverContent.style` — host can bump z-index when
+   *  the combobox is rendered above another overlay (chat dock,
+   *  modal, …) whose stacking context outranks ui-core's default. */
+  contentStyle?: React.CSSProperties
   /** Custom filter function. If provided, replaces default filtering logic. */
   filterFunction?: (option: ComboboxOption, search: string) => boolean
   /**
@@ -80,6 +97,9 @@ export function Combobox({
   disabled = false,
   renderOption,
   renderValue,
+  renderTrigger,
+  contentClassName,
+  contentStyle,
   filterFunction,
   storageKey,
   storageType,
@@ -242,26 +262,34 @@ export function Combobox({
       }}
     >
       <PopoverTrigger asChild>
-        <Button
-          variant="outline"
-          role="combobox"
-          aria-expanded={open}
-          className={cn(
-            "w-full justify-between",
-            !value && "text-muted-foreground",
-            className
-          )}
-          disabled={disabled}
-        >
-          {renderValue && selectedOption
-            ? renderValue(selectedOption)
-            : selectedOption
-            ? renderSelectedBadge(selectedOption)
-            : resolvedPlaceholder}
-          <ChevronsUpDown className="ml-2 h-4 w-4 shrink-0 opacity-50" />
-        </Button>
+        {renderTrigger ? (
+          renderTrigger(selectedOption, open)
+        ) : (
+          <Button
+            variant="outline"
+            role="combobox"
+            aria-expanded={open}
+            className={cn(
+              "w-full justify-between",
+              !value && "text-muted-foreground",
+              className
+            )}
+            disabled={disabled}
+          >
+            {renderValue && selectedOption
+              ? renderValue(selectedOption)
+              : selectedOption
+              ? renderSelectedBadge(selectedOption)
+              : resolvedPlaceholder}
+            <ChevronsUpDown className="ml-2 h-4 w-4 shrink-0 opacity-50" />
+          </Button>
+        )}
       </PopoverTrigger>
-      <PopoverContent className="w-[var(--radix-popover-trigger-width)] p-0" align="start">
+      <PopoverContent
+        className={cn("w-[var(--radix-popover-trigger-width)] p-0", contentClassName)}
+        style={contentStyle}
+        align="start"
+      >
         <Command shouldFilter={false} className="flex flex-col">
           <CommandInput
             placeholder={resolvedSearchPlaceholder}

package/src/hooks/audio/createSoundBus.ts

@@ -0,0 +1,172 @@
+'use client';
+
+/**
+ * Generic notification-sound bus.
+ *
+ * Lifted from `ui-tools/Chat/core/audio/audioBus` and generalised over an
+ * arbitrary event-key type so any feature (chat, presence, alerts, …)
+ * can reuse the same Safari unlock + multi-fire-safe playback infra.
+ *
+ * Pitfalls this addresses:
+ *   - Safari needs a user-gesture transaction to unlock playback. We
+ *     pre-allocate an `<audio>` per cached URL and play() each (muted)
+ *     during the unlock event so the whole bus lifts at once.
+ *   - Rapid play() calls on the same element cancel each other — we
+ *     clone a fresh `HTMLAudioElement` per fire (HTTP cache reuses the
+ *     underlying bytes for free).
+ *   - SSR safety: all DOM access is gated; module imports never touch
+ *     `window`.
+ *   - `play()` returns a Promise — we attach `.catch()` everywhere so
+ *     blocked-autoplay warnings don't reach the console.
+ */
+
+export interface SoundBusOptions<E extends string> {
+  /** Map an event key to a sound URL. `false`/missing silences the event. */
+  sounds: Partial<Record<E, string | false>>;
+  /**
+   * Volume 0..1 used for the next `play()` call. Receives the event so
+   * callers can scale per-event (e.g. quieter error sounds).
+   */
+  getVolume: (event?: E) => number;
+  /** Master mute. Read on every play. */
+  getMuted: () => boolean;
+  /** Per-event predicate. Return `false` to suppress one event. */
+  isEnabled: (event: E) => boolean;
+}
+
+export interface SoundBus<E extends string> {
+  play: (event: E) => void;
+  preload: (event: E) => void;
+  unlock: () => void;
+  isUnlocked: () => boolean;
+  subscribeUnlock: (cb: (unlocked: boolean) => void) => () => void;
+  setSounds: (sounds: Partial<Record<E, string | false>>) => void;
+  dispose: () => void;
+}
+
+// One unlock state per tab — first gesture inside ANY bus unlocks every
+// bus. Matches AudioPlayer's ADR-004 "global per tab" rule.
+let unlocked = false;
+const unlockListeners = new Set<(v: boolean) => void>();
+
+function setUnlocked(value: boolean) {
+  if (unlocked === value) return;
+  unlocked = value;
+  for (const cb of unlockListeners) cb(value);
+}
+
+/** Test helper — resets unlock state between tests. */
+export function _resetUnlockForTesting(): void {
+  unlocked = false;
+  unlockListeners.clear();
+}
+
+export function createSoundBus<E extends string>(
+  options: SoundBusOptions<E>,
+): SoundBus<E> {
+  if (typeof window === 'undefined') return noopBus<E>();
+
+  let sounds = options.sounds;
+  const cache = new Map<string, HTMLAudioElement>();
+
+  const getOrCreate = (url: string): HTMLAudioElement => {
+    const hit = cache.get(url);
+    if (hit) return hit;
+    const el = new Audio(url);
+    el.preload = 'auto';
+    el.crossOrigin = 'anonymous';
+    cache.set(url, el);
+    return el;
+  };
+
+  const resolveUrl = (event: E): string | null => {
+    const v = sounds[event];
+    if (!v) return null;
+    return v;
+  };
+
+  const play = (event: E) => {
+    if (options.getMuted()) return;
+    if (!options.isEnabled(event)) return;
+    const url = resolveUrl(event);
+    if (!url) return;
+
+    getOrCreate(url);
+    const fresh = new Audio(url);
+    fresh.preload = 'auto';
+    fresh.volume = clamp01(options.getVolume(event));
+    const p = fresh.play();
+    if (p && typeof p.catch === 'function') {
+      p.catch(() => {
+        // Browser blocked playback (no gesture yet) — ignore.
+      });
+    }
+  };
+
+  const preload = (event: E) => {
+    const url = resolveUrl(event);
+    if (!url) return;
+    const el = getOrCreate(url);
+    try {
+      el.load();
+    } catch {
+      // ignore
+    }
+  };
+
+  const unlock = () => {
+    if (unlocked) return;
+    for (const el of cache.values()) {
+      const wasMuted = el.muted;
+      el.muted = true;
+      const p = el.play();
+      if (p && typeof p.then === 'function') {
+        p.then(() => {
+          el.pause();
+          el.currentTime = 0;
+          el.muted = wasMuted;
+        }).catch(() => {
+          el.muted = wasMuted;
+        });
+      } else {
+        el.pause();
+        el.muted = wasMuted;
+      }
+    }
+    setUnlocked(true);
+  };
+
+  return {
+    play,
+    preload,
+    unlock,
+    isUnlocked: () => unlocked,
+    subscribeUnlock(cb) {
+      unlockListeners.add(cb);
+      return () => unlockListeners.delete(cb);
+    },
+    setSounds(next) {
+      sounds = next;
+    },
+    dispose() {
+      cache.clear();
+    },
+  };
+}
+
+function clamp01(v: number): number {
+  if (!Number.isFinite(v)) return 1;
+  return v < 0 ? 0 : v > 1 ? 1 : v;
+}
+
+function noopBus<E extends string>(): SoundBus<E> {
+  return {
+    play: () => undefined,
+    preload: () => undefined,
+    unlock: () => undefined,
+    isUnlocked: () => false,
+    subscribeUnlock: () => () => undefined,
+    setSounds: () => undefined,
+    dispose: () => undefined,
+  };
+}

package/src/hooks/audio/index.ts

@@ -0,0 +1,21 @@
+export {
+  createSoundBus,
+  _resetUnlockForTesting,
+  type SoundBus,
+  type SoundBusOptions,
+} from './createSoundBus';
+export {
+  createAudioPrefsStore,
+  useAudioPrefs,
+  type AudioPrefsState,
+} from './useAudioPrefs';
+export {
+  useNotificationSounds,
+  type NotificationSoundsConfig,
+  type NotificationSoundsApi,
+} from './useNotificationSounds';
+export {
+  useSoundEffect,
+  type SoundEffectOptions,
+  type SoundEffectApi,
+} from './useSoundEffect';