@djangocfg/ui-core 2.1.381 → 2.1.383

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/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';

package/src/hooks/audio/useAudioPrefs.ts

@@ -0,0 +1,91 @@
+'use client';
+
+/**
+ * Persistent audio preferences (volume / mute / per-event toggles).
+ *
+ * One zustand store per `storageKey` — instances with different keys
+ * persist independently (chat / alerts / per-product). Cross-tab sync
+ * via the `storage` event ships with zustand's persist middleware.
+ */
+
+import { create, type StoreApi, type UseBoundStore } from 'zustand';
+import { persist, createJSONStorage } from 'zustand/middleware';
+
+export interface AudioPrefsState<E extends string = string> {
+  /** 0..1 master volume. */
+  volume: number;
+  /** Master mute (overrides per-event toggles). */
+  muted: boolean;
+  /** Per-event opt-out — `false` silences a single trigger. */
+  enabled: Partial<Record<E, boolean>>;
+  setVolume: (v: number) => void;
+  setMuted: (m: boolean) => void;
+  setEventEnabled: (event: E, enabled: boolean) => void;
+}
+
+const clamp01 = (v: number): number => {
+  if (!Number.isFinite(v)) return 1;
+  return v < 0 ? 0 : v > 1 ? 1 : v;
+};
+
+/**
+ * Per-key registry so repeated calls with the same `storageKey` return
+ * the same store instance — necessary for cross-component state sharing
+ * (e.g. ChatHeader audio toggle + ChatLauncher bus reading the same key).
+ */
+const registry = new Map<string, UseBoundStore<StoreApi<AudioPrefsState<string>>>>();
+
+export function createAudioPrefsStore<E extends string = string>(
+  storageKey: string,
+): UseBoundStore<StoreApi<AudioPrefsState<E>>> {
+  const cached = registry.get(storageKey);
+  if (cached) return cached as unknown as UseBoundStore<StoreApi<AudioPrefsState<E>>>;
+
+  const store = create<AudioPrefsState<E>>()(
+    persist(
+      (set) => ({
+        volume: 1,
+        muted: false,
+        enabled: {},
+        setVolume: (v) => set({ volume: clamp01(v) }),
+        setMuted: (m) => set({ muted: !!m }),
+        setEventEnabled: (event, enabled) =>
+          set((s) => ({ enabled: { ...s.enabled, [event]: enabled } })),
+      }),
+      {
+        name: storageKey,
+        storage: createJSONStorage(() => {
+          if (typeof window === 'undefined') {
+            return {
+              getItem: () => null,
+              setItem: () => undefined,
+              removeItem: () => undefined,
+            };
+          }
+          return window.localStorage;
+        }),
+        partialize: (s) => ({ volume: s.volume, muted: s.muted, enabled: s.enabled }),
+        version: 1,
+      },
+    ),
+  );
+
+  registry.set(storageKey, store as unknown as UseBoundStore<StoreApi<AudioPrefsState<string>>>);
+  return store;
+}
+
+/**
+ * React hook helper — returns the persisted prefs store hook for a given
+ * `storageKey`. Callers can use it as a normal zustand hook with selectors.
+ *
+ * @example
+ * ```ts
+ * const usePrefs = useAudioPrefs<'sent' | 'received'>('myapp.audio');
+ * const muted = usePrefs((s) => s.muted);
+ * ```
+ */
+export function useAudioPrefs<E extends string = string>(
+  storageKey: string,
+): UseBoundStore<StoreApi<AudioPrefsState<E>>> {
+  return createAudioPrefsStore<E>(storageKey);
+}