@djangocfg/ui-core 2.1.380 → 2.1.382

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);
+}

package/src/hooks/audio/useNotificationSounds.ts

@@ -0,0 +1,271 @@
+'use client';
+
+import { useCallback, useEffect, useMemo, useRef, useSyncExternalStore } from 'react';
+
+import { createSoundBus, type SoundBus } from './createSoundBus';
+import { useAudioPrefs } from './useAudioPrefs';
+
+export interface NotificationSoundsConfig<E extends string> {
+  /**
+   * Persistence key for the mute / volume / per-event toggles. Use one
+   * key per product surface (e.g. `'chat.audio'`, `'alerts.audio'`).
+   */
+  storageKey: string;
+  /** Event → URL map. `false`/missing silences the event. */
+  sounds?: Partial<Record<E, string | false>>;
+  /** Master volume override. When set, the persisted value is ignored. */
+  volume?: number;
+  /**
+   * Per-event volume multipliers (0..1). Final per-play volume is
+   * `master × eventVolumes[event] ?? 1`. Use this to dim error / status
+   * sounds so they don't feel jarring next to message dings. Slack /
+   * Linear / Intercom-style defaults: error ≈ 0.25, mention ≈ 1.0,
+   * received/sent ≈ 0.6.
+   */
+  eventVolumes?: Partial<Record<E, number>>;
+  /** Master mute override. When set, the persisted value is ignored. */
+  muted?: boolean;
+  /** Custom predicate — return `false` to suppress one event. */
+  shouldPlay?: (event: E) => boolean;
+  /**
+   * Skip all playback when the user prefers reduced motion. @default true
+   */
+  respectReducedMotion?: boolean;
+  /**
+   * Skip all playback when the user prefers reduced data. @default true
+   */
+  respectReducedData?: boolean;
+  /**
+   * Skip all playback when the tab is hidden. @default true
+   */
+  muteWhenHidden?: boolean;
+  /**
+   * Disable the hook entirely — bus is not created, prefs are not read,
+   * `play()` is a no-op. Useful when the surrounding host plays sounds
+   * itself (e.g. Electron / Wails backend) and the React layer should
+   * stay silent.
+   */
+  silenced?: boolean;
+  /**
+   * Side-channel fired whenever `play()` would have triggered an event.
+   * Stays active even when `silenced=true`. Use to bridge into a native
+   * audio backend (cmdop_go, Tauri, …).
+   */
+  onSoundEvent?: (event: E) => void;
+}
+
+export interface NotificationSoundsApi<E extends string> {
+  play: (event: E) => void;
+  preload: (event: E) => void;
+  unlock: () => void;
+  isUnlocked: boolean;
+  /** Resolved mute state — combines persisted prefs + reduced-motion + hidden. */
+  muted: boolean;
+  setMuted: (m: boolean) => void;
+  toggleMute: () => void;
+  volume: number;
+  setVolume: (v: number) => void;
+  isEventEnabled: (event: E) => boolean;
+  setEventEnabled: (event: E, enabled: boolean) => void;
+  /** True when no sounds map is configured (or `silenced`). */
+  isSilent: boolean;
+}
+
+function readReducedMotion(): boolean {
+  if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') return false;
+  return window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+}
+function readReducedData(): boolean {
+  if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') return false;
+  return window.matchMedia('(prefers-reduced-data: reduce)').matches;
+}
+function readVisibilityHidden(): boolean {
+  if (typeof document === 'undefined') return false;
+  return document.visibilityState === 'hidden';
+}
+
+/**
+ * Mid-level notification-sounds hook.
+ *
+ * Use when you need a small named map (`received`, `error`, `mention`)
+ * with persisted mute + Safari unlock + reduced-motion / hidden-tab
+ * guards. Pair with `useAudioPrefs(...)` if you need cross-component
+ * access to the same mute state.
+ *
+ * @example
+ * ```tsx
+ * type Event = 'received' | 'error';
+ * const sounds = useNotificationSounds<Event>({
+ *   storageKey: 'myapp.audio',
+ *   sounds: { received: '/r.mp3', error: '/e.mp3' },
+ * });
+ *
+ * onMessage = (m) => sounds.play('received');
+ * onMute = () => sounds.toggleMute();
+ * ```
+ */
+export function useNotificationSounds<E extends string>(
+  config: NotificationSoundsConfig<E>,
+): NotificationSoundsApi<E> {
+  const {
+    storageKey,
+    sounds = {},
+    volume: volumeOverride,
+    eventVolumes,
+    muted: mutedOverride,
+    shouldPlay,
+    respectReducedMotion = true,
+    respectReducedData = true,
+    muteWhenHidden = true,
+    silenced = false,
+    onSoundEvent,
+  } = config;
+
+  const usePrefs = useAudioPrefs<E>(storageKey);
+  const volumeP = usePrefs((s) => s.volume);
+  const mutedP = usePrefs((s) => s.muted);
+  const enabledMap = usePrefs((s) => s.enabled);
+  const setVolumeP = usePrefs((s) => s.setVolume);
+  const setMutedP = usePrefs((s) => s.setMuted);
+  const setEventEnabledP = usePrefs((s) => s.setEventEnabled);
+
+  const volume = volumeOverride != null ? volumeOverride : volumeP;
+  const muted = mutedOverride != null ? mutedOverride : mutedP;
+
+  // Refs for stable getters inside the bus.
+  const volumeRef = useRef(volume);
+  volumeRef.current = volume;
+  const eventVolumesRef = useRef(eventVolumes);
+  eventVolumesRef.current = eventVolumes;
+  const mutedRef = useRef(muted);
+  mutedRef.current = muted;
+  const enabledRef = useRef(enabledMap);
+  enabledRef.current = enabledMap;
+  const reducedMotionRef = useRef(readReducedMotion());
+  const reducedDataRef = useRef(readReducedData());
+  const hiddenRef = useRef(readVisibilityHidden());
+  const shouldPlayRef = useRef(shouldPlay);
+  shouldPlayRef.current = shouldPlay;
+  const silencedRef = useRef(silenced);
+  silencedRef.current = silenced;
+  const onSoundEventRef = useRef(onSoundEvent);
+  onSoundEventRef.current = onSoundEvent;
+
+  // Watch reduced-motion / reduced-data preference changes.
+  useEffect(() => {
+    if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') return;
+    const mqMotion = window.matchMedia('(prefers-reduced-motion: reduce)');
+    const mqData = window.matchMedia('(prefers-reduced-data: reduce)');
+    const onMotion = () => {
+      reducedMotionRef.current = mqMotion.matches;
+    };
+    const onData = () => {
+      reducedDataRef.current = mqData.matches;
+    };
+    mqMotion.addEventListener('change', onMotion);
+    mqData.addEventListener('change', onData);
+    return () => {
+      mqMotion.removeEventListener('change', onMotion);
+      mqData.removeEventListener('change', onData);
+    };
+  }, []);
+
+  // Visibility tracking — mute while tab is hidden.
+  useEffect(() => {
+    if (!muteWhenHidden || typeof document === 'undefined') return;
+    const onVis = () => {
+      hiddenRef.current = document.visibilityState === 'hidden';
+    };
+    document.addEventListener('visibilitychange', onVis);
+    return () => document.removeEventListener('visibilitychange', onVis);
+  }, [muteWhenHidden]);
+
+  const effectiveMuted = useCallback((): boolean => {
+    if (silencedRef.current) return true;
+    if (mutedRef.current) return true;
+    if (muteWhenHidden && hiddenRef.current) return true;
+    if (respectReducedMotion && reducedMotionRef.current) return true;
+    if (respectReducedData && reducedDataRef.current) return true;
+    return false;
+  }, [muteWhenHidden, respectReducedMotion, respectReducedData]);
+
+  const isEnabledImpl = useCallback((event: E): boolean => {
+    if (shouldPlayRef.current && shouldPlayRef.current(event) === false) return false;
+    const flag = enabledRef.current[event];
+    if (flag === false) return false;
+    return true;
+  }, []);
+
+  // Bus instance — created once per hook lifetime, sounds map hot-swapped.
+  const busRef = useRef<SoundBus<E> | null>(null);
+  if (busRef.current === null) {
+    busRef.current = createSoundBus<E>({
+      sounds,
+      getVolume: (event) => {
+        const master = volumeRef.current;
+        if (event === undefined) return master;
+        const scale = eventVolumesRef.current?.[event];
+        if (scale === undefined) return master;
+        return master * scale;
+      },
+      getMuted: () => effectiveMuted(),
+      isEnabled: (event) => isEnabledImpl(event),
+    });
+  }
+
+  useEffect(() => {
+    busRef.current?.setSounds(sounds);
+  }, [sounds]);
+
+  // Preload all listed sounds once.
+  useEffect(() => {
+    const bus = busRef.current;
+    if (!bus) return;
+    for (const ev of Object.keys(sounds) as E[]) bus.preload(ev);
+  }, [sounds]);
+
+  useEffect(() => {
+    const bus = busRef.current;
+    return () => bus?.dispose();
+  }, []);
+
+  const isUnlocked = useSyncExternalStore(
+    useCallback((cb) => busRef.current?.subscribeUnlock(cb) ?? (() => undefined), []),
+    () => busRef.current?.isUnlocked() ?? false,
+    () => false,
+  );
+
+  const play = useCallback(
+    (event: E) => {
+      onSoundEventRef.current?.(event);
+      busRef.current?.play(event);
+    },
+    [],
+  );
+  const preload = useCallback((event: E) => busRef.current?.preload(event), []);
+  const unlock = useCallback(() => busRef.current?.unlock(), []);
+
+  const toggleMute = useCallback(() => setMutedP(!mutedRef.current), [setMutedP]);
+
+  const isEventEnabled = useCallback((event: E) => isEnabledImpl(event), [isEnabledImpl]);
+
+  const isSilent = useMemo(() => {
+    if (silenced) return true;
+    return !sounds || Object.keys(sounds).length === 0;
+  }, [silenced, sounds]);
+
+  return {
+    play,
+    preload,
+    unlock,
+    isUnlocked,
+    muted,
+    setMuted: (m: boolean) => setMutedP(m),
+    toggleMute,
+    volume,
+    setVolume: (v: number) => setVolumeP(v),
+    isEventEnabled,
+    setEventEnabled: (event, enabled) => setEventEnabledP(event, enabled),
+    isSilent,
+  };
+}

package/src/hooks/audio/useSoundEffect.ts

@@ -0,0 +1,78 @@
+'use client';
+
+import { useCallback, useEffect, useRef } from 'react';
+
+export interface SoundEffectOptions {
+  /** 0..1 master volume. @default 1 */
+  volume?: number;
+  /** Set to true to skip play() entirely (e.g. user-prefs gating). @default false */
+  silenced?: boolean;
+}
+
+export interface SoundEffectApi {
+  /** Trigger playback. Fire-and-forget; cancel-safe. */
+  play: () => void;
+  /** Eagerly preload the asset. */
+  preload: () => void;
+}
+
+/**
+ * One-shot single-asset hook — the minimal "play a ding" helper.
+ *
+ * Lower level than `useNotificationSounds` (no persisted mute, no
+ * per-event toggles). Use when you have ONE asset, ONE trigger, and
+ * don't need cross-component sync.
+ *
+ * @example
+ * ```tsx
+ * const submitDing = useSoundEffect('/sfx/ding.mp3');
+ * <Button onClick={() => { submitDing.play(); doStuff(); }} />
+ * ```
+ */
+export function useSoundEffect(
+  url: string | null | undefined,
+  options: SoundEffectOptions = {},
+): SoundEffectApi {
+  const { volume = 1, silenced = false } = options;
+  const templateRef = useRef<HTMLAudioElement | null>(null);
+  const volumeRef = useRef(volume);
+  volumeRef.current = volume;
+  const silencedRef = useRef(silenced);
+  silencedRef.current = silenced;
+  const urlRef = useRef(url);
+  urlRef.current = url;
+
+  useEffect(() => {
+    if (typeof window === 'undefined' || !url) return;
+    const el = new Audio(url);
+    el.preload = 'auto';
+    el.crossOrigin = 'anonymous';
+    templateRef.current = el;
+    return () => {
+      templateRef.current = null;
+    };
+  }, [url]);
+
+  const play = useCallback(() => {
+    if (silencedRef.current) return;
+    const u = urlRef.current;
+    if (!u || typeof window === 'undefined') return;
+    const fresh = new Audio(u);
+    fresh.preload = 'auto';
+    fresh.volume = volumeRef.current;
+    const p = fresh.play();
+    if (p && typeof p.catch === 'function') p.catch(() => undefined);
+  }, []);
+
+  const preload = useCallback(() => {
+    const el = templateRef.current;
+    if (!el) return;
+    try {
+      el.load();
+    } catch {
+      // ignore
+    }
+  }, []);
+
+  return { play, preload };
+}