@djangocfg/ui-core 2.1.381 → 2.1.383

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

package/src/hooks/hotkey/formatHotkey.ts

@@ -0,0 +1,96 @@
+'use client';
+
+/**
+ * Human-readable hotkey formatter.
+ *
+ * Translates a `react-hotkeys-hook` combo string into the glyphs users
+ * expect to see in tooltips and cheat-sheets. Honours macOS conventions
+ * (⌘ ⌃ ⌥ ⇧) on Apple devices and falls back to text labels elsewhere.
+ *
+ * @example
+ * formatHotkey('mod+k')     // → '⌘K' on Mac, 'Ctrl+K' elsewhere
+ * formatHotkey('shift+/')   // → '⇧/'
+ * formatHotkey('escape')    // → 'Esc'
+ * formatHotkey('g t')       // → 'G then T' (chord)
+ */
+export function formatHotkey(combo: string, opts: { mac?: boolean } = {}): string {
+  const mac = opts.mac ?? detectMac();
+
+  // Chord: tokens separated by spaces.
+  if (combo.includes(' ')) {
+    return combo
+      .split(/\s+/)
+      .map((part) => formatHotkey(part, { mac }))
+      .join(' then ');
+  }
+
+  // Multiple alternatives via comma — show the first.
+  if (combo.includes(',')) {
+    const first = combo.split(',')[0]?.trim();
+    return first ? formatHotkey(first, { mac }) : combo;
+  }
+
+  return combo
+    .split('+')
+    .map((token) => token.trim().toLowerCase())
+    .filter(Boolean)
+    .map((token) => formatToken(token, mac))
+    .join(mac ? '' : '+');
+}
+
+function detectMac(): boolean {
+  if (typeof navigator === 'undefined') return false;
+  // navigator.userAgentData is Chromium-only; fall back to platform sniff.
+  const ua = (navigator.userAgent || '').toLowerCase();
+  const platform = (navigator.platform || '').toLowerCase();
+  return /mac|iphone|ipad|ipod/.test(platform) || /mac os|macintosh/.test(ua);
+}
+
+function formatToken(token: string, mac: boolean): string {
+  switch (token) {
+    case 'mod':
+      return mac ? '⌘' : 'Ctrl';
+    case 'meta':
+    case 'cmd':
+    case 'command':
+      return mac ? '⌘' : 'Win';
+    case 'ctrl':
+    case 'control':
+      return mac ? '⌃' : 'Ctrl';
+    case 'alt':
+    case 'option':
+      return mac ? '⌥' : 'Alt';
+    case 'shift':
+      return mac ? '⇧' : 'Shift';
+    case 'escape':
+    case 'esc':
+      return 'Esc';
+    case 'enter':
+    case 'return':
+      return mac ? '⏎' : 'Enter';
+    case 'tab':
+      return mac ? '⇥' : 'Tab';
+    case 'space':
+      return mac ? 'Space' : 'Space';
+    case 'backspace':
+      return mac ? '⌫' : 'Backspace';
+    case 'delete':
+    case 'del':
+      return mac ? '⌦' : 'Del';
+    case 'arrowup':
+    case 'up':
+      return '↑';
+    case 'arrowdown':
+    case 'down':
+      return '↓';
+    case 'arrowleft':
+    case 'left':
+      return '←';
+    case 'arrowright':
+    case 'right':
+      return '→';
+    default:
+      if (token.length === 1) return token.toUpperCase();
+      return token.charAt(0).toUpperCase() + token.slice(1);
+  }
+}

package/src/hooks/hotkey/index.ts

@@ -2,3 +2,13 @@
 
 export { useHotkey, useHotkeysContext, HotkeysProvider, isHotkeyPressed } from './useHotkey';
 export type { UseHotkeyOptions, HotkeyCallback, Keys, HotkeyRefType } from './useHotkey';
+
+export { formatHotkey } from './formatHotkey';
+export { useHotkeyChord, type UseHotkeyChordOptions } from './useHotkeyChord';
+export {
+  useHotkeyHelp,
+  useRegisterHotkey,
+  getRegisteredHotkeys,
+  registerHotkey,
+  type RegisteredHotkey,
+} from './useHotkeyHelp';

package/src/hooks/hotkey/useHotkey.ts

@@ -1,26 +1,54 @@
 'use client';
 
+import { useEffect } from 'react';
 import { Options as HotkeysOptions, useHotkeys } from 'react-hotkeys-hook';
 import type { HotkeyCallback, Keys } from 'react-hotkeys-hook';
 
+import { registerHotkey } from './useHotkeyHelp';
+
 /** Ref type for hotkey target element */
 export type HotkeyRefType<T> = T | null;
 
 /**
- * Options for the useHotkey hook
+ * Options for the useHotkey hook.
+ *
+ * Most of the time you only need `{ inInput }` or nothing — sensible
+ * defaults are derived from the key combo (see below).
  */
 export interface UseHotkeyOptions extends Omit<HotkeysOptions, 'enabled'> {
   /** Whether the hotkey is enabled (default: true) */
   enabled?: boolean;
-  /** Scope for the hotkey - useful for context-specific shortcuts */
+  /** Scope for the hotkey — useful for context-specific shortcuts */
   scope?: string;
   /** Only trigger when focus is within a specific element */
   scopes?: string[];
   /** Prevent default browser behavior */
   preventDefault?: boolean;
-  /** Enable in input fields and textareas */
+  /**
+   * Whether the shortcut should also fire when focus is inside an input,
+   * textarea, select, or contenteditable element.
+   *
+   * Default policy (when not specified):
+   *   - Modifier-bearing combos (`cmd+*`, `ctrl+*`, `alt+*`, `shift+*`)
+   *     → `true`. Global app shortcuts (⌘K, Ctrl+S, ⌘/) must work no
+   *     matter where the user is.
+   *   - `escape` → `true`. Escape semantics (blur / close) are universal.
+   *   - Bare single-character keys (`/`, `?`, `j`, …) → `false`. They
+   *     would otherwise eat keystrokes the user is typing into inputs.
+   *   - Function keys, arrows, etc. → `false`.
+   *
+   * Pass `true` or `false` explicitly to override.
+   */
+  inInput?: boolean;
+  /**
+   * @deprecated Use `inInput` instead. Forwarded to react-hotkeys-hook
+   * when explicitly set; otherwise derived from `inInput` / policy.
+   */
   enableOnFormTags?: boolean | readonly ('input' | 'textarea' | 'select')[];
-  /** Enable when contentEditable element is focused */
+  /**
+   * @deprecated Use `inInput` instead. Same forwarding rules as
+   * `enableOnFormTags`.
+   */
   enableOnContentEditable?: boolean;
   /** Split key for multiple hotkey combinations (default: ',') */
   splitKey?: string;
@@ -32,40 +60,24 @@ export interface UseHotkeyOptions extends Omit<HotkeysOptions, 'enabled'> {
 }
 
 /**
- * Simple wrapper hook for react-hotkeys-hook
- *
- * @example
- * // Single key
- * useHotkey('escape', () => closeModal());
+ * Wrapper around react-hotkeys-hook with an opinionated `inInput` policy.
  *
  * @example
- * // Key combination
- * useHotkey('ctrl+s', (e) => {
- *   e.preventDefault();
- *   saveDocument();
- * });
+ * // ⌘K palette — works everywhere, including inside text fields
+ * useHotkey('mod+k', openPalette);
  *
  * @example
- * // Multiple keys (any of them will trigger)
- * useHotkey(['ArrowLeft', '['], () => goToPrevious());
- * useHotkey(['ArrowRight', ']'], () => goToNext());
+ * // `/` focuses search — auto-disabled inside text fields so typing
+ * // a `/` into a textarea doesn't yank focus away
+ * useHotkey('/', focusSearch);
  *
  * @example
- * // With options
- * useHotkey('/', () => focusSearch(), {
- *   preventDefault: true,
- *   enableOnFormTags: false,
- *   description: 'Focus search input'
- * });
+ * // Escape — defaults to fire in text fields too (blur / close pattern)
+ * useHotkey('escape', closeModal);
  *
  * @example
- * // Scoped hotkeys
- * useHotkey('delete', () => deleteItem(), { scopes: ['list-view'] });
- *
- * @param keys - Hotkey or array of hotkeys (e.g., 'ctrl+s', 'ArrowLeft', ['[', 'ArrowLeft'])
- * @param callback - Function to call when hotkey is pressed
- * @param options - Configuration options
- * @returns Ref callback to attach to element for scoped hotkeys
+ * // Explicit opt-in for a bare key inside inputs
+ * useHotkey('?', openHelp, { inInput: true });
  */
 export function useHotkey<T extends HTMLElement = HTMLElement>(
   keys: Keys,
@@ -74,13 +86,35 @@ export function useHotkey<T extends HTMLElement = HTMLElement>(
 ): (instance: HotkeyRefType<T>) => void {
   const {
     enabled = true,
-    preventDefault = false,
-    enableOnFormTags = false,
-    enableOnContentEditable = false,
-    description: _description,
+    preventDefault: explicitPreventDefault,
+    inInput,
+    enableOnFormTags: explicitFormTags,
+    enableOnContentEditable: explicitContentEditable,
+    description,
+    scope,
     ...restOptions
   } = options;
 
+  const policyAllowsInInput = resolveInInput(keys, inInput);
+  // Smart default — modifier combos preventDefault by default
+  // (cmd+s, cmd+k, etc. would otherwise fall through to the browser).
+  const preventDefault = explicitPreventDefault ?? hasModifier(keys);
+
+  // Register in the cheat-sheet help registry when described.
+  useEffect(() => {
+    if (!description) return;
+    return registerHotkey({
+      combo: normalizeKeys(keys).join(','),
+      description,
+      scope,
+    });
+  }, [keys, description, scope]);
+
+  const enableOnFormTags =
+    explicitFormTags !== undefined ? explicitFormTags : policyAllowsInInput;
+  const enableOnContentEditable =
+    explicitContentEditable !== undefined ? explicitContentEditable : policyAllowsInInput;
+
   return useHotkeys<T>(
     keys,
     (event, handler) => {
@@ -98,6 +132,44 @@ export function useHotkey<T extends HTMLElement = HTMLElement>(
   );
 }
 
+/**
+ * Decide whether a given key combo should fire when focus is inside a
+ * text input. Honours the caller's explicit `inInput` first, otherwise
+ * applies the policy described on `UseHotkeyOptions.inInput`.
+ */
+function resolveInInput(keys: Keys, explicit?: boolean): boolean {
+  if (explicit !== undefined) return explicit;
+
+  const list = normalizeKeys(keys);
+  // If ANY of the listed combos qualifies as "input-safe", treat the
+  // whole binding as input-safe — the caller declared them as
+  // alternatives, so the more permissive policy wins.
+  return list.some(isInputSafeByPolicy);
+}
+
+function normalizeKeys(keys: Keys): string[] {
+  if (Array.isArray(keys)) return keys.map((k) => String(k).toLowerCase());
+  return [String(keys).toLowerCase()];
+}
+
+const ESCAPE_ALIASES = new Set(['escape', 'esc']);
+const MODIFIER_ALIASES = ['mod+', 'meta+', 'cmd+', 'ctrl+', 'control+', 'alt+', 'option+', 'shift+'];
+
+function isInputSafeByPolicy(combo: string): boolean {
+  if (ESCAPE_ALIASES.has(combo)) return true;
+  return MODIFIER_ALIASES.some((mod) => combo.startsWith(mod));
+}
+
+/**
+ * Does the combo include a modifier key? Used to default `preventDefault`
+ * so global app shortcuts (⌘S, ⌘K, …) never fall through to the browser.
+ */
+function hasModifier(keys: Keys): boolean {
+  return normalizeKeys(keys).some((combo) =>
+    MODIFIER_ALIASES.some((mod) => combo.startsWith(mod)),
+  );
+}
+
 // Re-export useful utilities from react-hotkeys-hook
 export { useHotkeysContext, HotkeysProvider, isHotkeyPressed } from 'react-hotkeys-hook';