@djangocfg/ui-tools 2.1.381 → 2.1.383

package/src/tools/Chat/hooks/useChat.ts

@@ -65,6 +65,18 @@ export interface UseChatReturn extends ChatState {
   loadMore: () => Promise<void>;
   newSession: () => Promise<void>;
   lastError: Error | null;
+  /**
+   * Inject a complete message from outside (push notification, admin
+   * takeover, system notice). De-duped by id. Position defaults to
+   * `append` — pass `prepend` for retroactive inserts.
+   */
+  injectMessage: (message: ChatMessage, position?: 'append' | 'prepend') => void;
+  /**
+   * Patch fields of an existing message in place (e.g. live-edit the
+   * admin's last reply, mark a message as resolved). No-op if the id
+   * doesn't exist.
+   */
+  updateMessage: (id: string, patch: Partial<ChatMessage>) => void;
 }
 
 export function useChat(config: UseChatConfig): UseChatReturn {
@@ -519,6 +531,20 @@ export function useChat(config: UseChatConfig): UseChatReturn {
     dispatch({ type: 'MESSAGE_DELETE', id });
   }, []);
 
+  const injectMessage = useCallback(
+    (message: ChatMessage, position?: 'append' | 'prepend') => {
+      dispatch({ type: 'MESSAGE_INJECT', message, position });
+    },
+    [],
+  );
+
+  const updateMessage = useCallback(
+    (id: string, patch: Partial<ChatMessage>) => {
+      dispatch({ type: 'MESSAGE_PATCH', id, patch });
+    },
+    [],
+  );
+
   const clearMessages = useCallback(() => {
     abortRef.current?.abort();
     dispatch({ type: 'MESSAGES_CLEAR' });
@@ -591,6 +617,8 @@ export function useChat(config: UseChatConfig): UseChatReturn {
     loadMore,
     newSession,
     lastError: lastErrorRef.current,
+    injectMessage,
+    updateMessage,
   };
 }
 

package/src/tools/Chat/hooks/useChatAudio.ts

@@ -1,191 +1,70 @@
 'use client';
 
-import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from 'react';
+import { useNotificationSounds } from '@djangocfg/ui-core/hooks';
 
-import { createAudioBus, type ChatAudioBus } from '../core/audio/audioBus';
-import { useChatAudioPrefs } from '../core/audio/preferences';
+import { DEFAULT_CHAT_SOUNDS } from '../core/audio/defaults';
 import type {
   ChatAudioConfig,
   ChatAudioEvent,
   UseChatAudioReturn,
 } from '../core/audio/types';
 
-const ALL_EVENTS: ChatAudioEvent[] = [
-  'messageSent',
-  'messageReceived',
-  'streamStart',
-  'error',
-  'mention',
-  'notification',
-];
-
-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';
-}
-
+const STORAGE_KEY = 'djangocfg-chat-audio:prefs';
+
+/**
+ * Slack / Linear / Intercom-style per-event volume scale. Applied on top
+ * of the master volume so error / status sounds don't startle the user
+ * sitting next to a busy chat. Override per-event via
+ * `config.eventVolumes`, or pass `eventVolumes: {}` to disable defaults.
+ */
+const DEFAULT_EVENT_VOLUMES: Partial<Record<ChatAudioEvent, number>> = {
+  error: 0.25,
+  mention: 1,
+  messageSent: 0.5,
+  messageReceived: 0.7,
+  streamStart: 0.3,
+  notification: 0.9,
+};
+
+/**
+ * Chat-specific audio facade. Thin wrapper over `useNotificationSounds`
+ * from `@djangocfg/ui-core` — keeps the `ChatAudioEvent` typing while
+ * the underlying bus / prefs / Safari-unlock logic lives in ui-core.
+ */
 export function useChatAudio(config: ChatAudioConfig = {}): UseChatAudioReturn {
-  const {
-    sounds = {},
-    volume: volumeOverride,
-    muted: mutedOverride,
-    shouldPlay,
-    respectReducedMotion = true,
-    respectReducedData = true,
-    muteWhenHidden = true,
-  } = config;
-
-  const volume = useChatAudioPrefs((s) => (volumeOverride != null ? volumeOverride : s.volume));
-  const mutedPersisted = useChatAudioPrefs((s) => s.muted);
-  const muted = mutedOverride != null ? mutedOverride : mutedPersisted;
-  const enabledMap = useChatAudioPrefs((s) => s.enabled);
-  const setVolumePref = useChatAudioPrefs((s) => s.setVolume);
-  const setMutedPref = useChatAudioPrefs((s) => s.setMuted);
-  const setEventEnabledPref = useChatAudioPrefs((s) => s.setEventEnabled);
-
-  // Refs to keep `play()` referentially-stable while still reading current prefs.
-  const volumeRef = useRef(volume);
-  volumeRef.current = volume;
-  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;
-
-  // 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]);
-
-  // Bus instance — created once per provider, sounds map hot-swapped on change.
-  const busRef = useRef<ChatAudioBus | null>(null);
-  if (busRef.current === null) {
-    busRef.current = createAudioBus({
-      sounds,
-      getVolume: () => volumeRef.current,
-      getMuted: () => effectiveMuted(),
-      isEnabled: (event) => isEnabledImpl(event),
-    });
-  }
-
-  function effectiveMuted(): boolean {
-    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;
-  }
-
-  function isEnabledImpl(event: ChatAudioEvent): boolean {
-    if (shouldPlayRef.current && shouldPlayRef.current(event) === false) return false;
-    const flag = enabledRef.current[event];
-    if (flag === false) return false;
-    return true;
-  }
-
-  // Hot-swap sounds when caller-provided map changes.
-  useEffect(() => {
-    busRef.current?.setSounds(sounds);
-  }, [sounds]);
-
-  // Preload all configured events once.
-  useEffect(() => {
-    const bus = busRef.current;
-    if (!bus) return;
-    for (const event of ALL_EVENTS) {
-      bus.preload(event);
-    }
-  }, [sounds]);
-
-  // Dispose on unmount.
-  useEffect(() => {
-    const bus = busRef.current;
-    return () => {
-      bus?.dispose();
-    };
-  }, []);
-
-  // Reactive `isUnlocked`.
-  const isUnlocked = useSyncExternalStore(
-    useCallback((cb) => busRef.current?.subscribeUnlock(cb) ?? (() => undefined), []),
-    () => busRef.current?.isUnlocked() ?? false,
-    () => false,
-  );
-
-  const play = useCallback((event: ChatAudioEvent) => {
-    busRef.current?.play(event);
-  }, []);
-  const preload = useCallback((event: ChatAudioEvent) => {
-    busRef.current?.preload(event);
-  }, []);
-  const unlock = useCallback(() => {
-    busRef.current?.unlock();
-  }, []);
-
-  const isEventEnabled = useCallback(
-    (event: ChatAudioEvent) => isEnabledImpl(event),
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-    [],
-  );
-
-  const api = useMemo<UseChatAudioReturn>(
-    () => ({
-      play,
-      preload,
-      unlock,
-      isUnlocked,
-      muted,
-      setMuted: (m: boolean) => setMutedPref(m),
-      volume,
-      setVolume: (v: number) => setVolumePref(v),
-      isEventEnabled,
-      setEventEnabled: (event, enabled) => setEventEnabledPref(event, enabled),
-    }),
-    [play, preload, unlock, isUnlocked, muted, volume, isEventEnabled, setMutedPref, setVolumePref, setEventEnabledPref],
-  );
-
-  // We need a useState here just to register a re-render trigger when the
-  // bus reports unlock changes — but we already wired `useSyncExternalStore`
-  // above, so this is a no-op holder.
-  void useState;
-
-  return api;
+  // Auto-fallback to built-in sounds when:
+  //   - host hasn't passed a `sounds` map (most apps)
+  //   - host hasn't opted into `silenced` mode (native hosts skip this)
+  // Pass `sounds: {}` explicitly to disable both defaults and embedded.
+  const resolvedSounds =
+    config.sounds === undefined && !config.silenced ? DEFAULT_CHAT_SOUNDS : config.sounds;
+
+  const api = useNotificationSounds<ChatAudioEvent>({
+    storageKey: STORAGE_KEY,
+    sounds: resolvedSounds,
+    volume: config.volume,
+    eventVolumes: config.eventVolumes ?? DEFAULT_EVENT_VOLUMES,
+    muted: config.muted,
+    shouldPlay: config.shouldPlay,
+    respectReducedMotion: config.respectReducedMotion,
+    respectReducedData: config.respectReducedData,
+    muteWhenHidden: config.muteWhenHidden,
+    silenced: config.silenced,
+    onSoundEvent: config.onSoundEvent,
+  });
+
+  return {
+    play: api.play,
+    preload: api.preload,
+    unlock: api.unlock,
+    isUnlocked: api.isUnlocked,
+    muted: api.muted,
+    setMuted: api.setMuted,
+    toggleMute: api.toggleMute,
+    volume: api.volume,
+    setVolume: api.setVolume,
+    isEventEnabled: api.isEventEnabled,
+    setEventEnabled: api.setEventEnabled,
+    isSilent: api.isSilent,
+  };
 }

package/src/tools/Chat/hooks/useChatDockPrefs.ts

@@ -0,0 +1,74 @@
+'use client';
+
+import { useCallback } from 'react';
+
+import { useLocalStorage } from '@djangocfg/ui-core/hooks';
+
+import type { ChatDockMode, ChatDockSide } from '../launcher/ChatDock';
+
+export interface ChatDockPrefs {
+  /** Popover (FAB-style) or side-docked panel. */
+  mode: ChatDockMode;
+  /** Which edge the side dock attaches to. */
+  side: ChatDockSide;
+  /** Width in px when side-docked (resizable in the future). */
+  sideWidth: number;
+}
+
+export const DEFAULT_DOCK_PREFS: ChatDockPrefs = {
+  mode: 'popover',
+  side: 'right',
+  sideWidth: 420,
+};
+
+const DEFAULT_KEY = 'chat.dock.prefs';
+
+export interface UseChatDockPrefsOptions {
+  /** localStorage key. @default 'chat.dock.prefs' */
+  storageKey?: string;
+  /** Override the baseline defaults (per-product branding, etc.). */
+  defaults?: Partial<ChatDockPrefs>;
+}
+
+export interface UseChatDockPrefsReturn extends ChatDockPrefs {
+  /** Merge-update — pass only the fields that changed. */
+  setPrefs: (patch: Partial<ChatDockPrefs>) => void;
+  /** Convenience toggle: popover ⇆ side. */
+  toggleMode: () => void;
+  /** Convenience toggle: right ⇆ left (only affects side mode). */
+  toggleSide: () => void;
+  /** Reset to defaults. */
+  reset: () => void;
+}
+
+/**
+ * Persistent dock preferences (mode / side / width) via ui-core localStorage.
+ *
+ * SSR-safe: returns defaults on the server, hydrates on mount.
+ * Survives reloads — power users keep their preferred chat layout.
+ */
+export function useChatDockPrefs(opts: UseChatDockPrefsOptions = {}): UseChatDockPrefsReturn {
+  const key = opts.storageKey ?? DEFAULT_KEY;
+  const initial: ChatDockPrefs = { ...DEFAULT_DOCK_PREFS, ...opts.defaults };
+
+  const [prefs, setStored] = useLocalStorage<ChatDockPrefs>(key, initial);
+
+  const setPrefs = useCallback(
+    (patch: Partial<ChatDockPrefs>) => {
+      setStored((prev) => ({ ...prev, ...patch }));
+    },
+    [setStored],
+  );
+
+  const toggleMode = useCallback(() => {
+    setStored((prev) => ({ ...prev, mode: prev.mode === 'side' ? 'popover' : 'side' }));
+  }, [setStored]);
+
+  const toggleSide = useCallback(() => {
+    setStored((prev) => ({ ...prev, side: prev.side === 'right' ? 'left' : 'right' }));
+  }, [setStored]);
+
+  const reset = useCallback(() => setStored(initial), [setStored, initial]);
+
+  return { ...prefs, setPrefs, toggleMode, toggleSide, reset };
+}

package/src/tools/Chat/hooks/useChatReset.ts

@@ -0,0 +1,70 @@
+'use client';
+
+import { useCallback, useState } from 'react';
+
+export interface UseChatResetOptions {
+  /**
+   * Backend call that performs the actual reset (e.g. POST /chat/reset).
+   * Should resolve to `true` on success, `false` on failure.
+   * Throwing also counts as failure — caught and logged.
+   */
+  onReset: () => Promise<boolean>;
+  /**
+   * Called after a successful reset (status === true). Use to clear the
+   * local message list, navigate, or fire analytics.
+   */
+  onSuccess?: () => void;
+  /**
+   * Called when reset fails (returned `false` or threw). Defaults to no-op
+   * — wire to a toast/banner if you want to surface it.
+   */
+  onError?: (error?: unknown) => void;
+}
+
+export interface UseChatResetReturn {
+  /** Trigger the reset. Safe to call multiple times — re-entrant guard. */
+  reset: () => Promise<boolean>;
+  /** True while the reset is in flight. */
+  isResetting: boolean;
+}
+
+/**
+ * Generic "clear chat context" hook.
+ *
+ * Stays generic — the backend call lives in the host (it knows the URL,
+ * auth, project slug). Provides the in-flight state and success/error
+ * callbacks every consumer wires up the same way.
+ *
+ * @example
+ * ```tsx
+ * const { reset, isResetting } = useChatReset({
+ *   onReset: async () => {
+ *     const res = await fetch('/api/chat/reset', { method: 'POST', credentials: 'include' });
+ *     return res.ok;
+ *   },
+ *   onSuccess: () => chat.clearMessages(),
+ * });
+ * ```
+ */
+export function useChatReset(opts: UseChatResetOptions): UseChatResetReturn {
+  const { onReset, onSuccess, onError } = opts;
+  const [isResetting, setIsResetting] = useState(false);
+
+  const reset = useCallback(async (): Promise<boolean> => {
+    if (isResetting) return false;
+    setIsResetting(true);
+    try {
+      const ok = await onReset();
+      if (ok) onSuccess?.();
+      else onError?.();
+      return ok;
+    } catch (err) {
+      onError?.(err);
+      return false;
+    } finally {
+      setIsResetting(false);
+    }
+  }, [isResetting, onReset, onSuccess, onError]);
+
+  return { reset, isResetting };
+}

package/src/tools/Chat/hooks/useChatUnread.ts

@@ -0,0 +1,87 @@
+'use client';
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+import { useChatContext } from '../context';
+import type { ChatMessage } from '../types';
+
+export interface UseChatUnreadOptions {
+  /**
+   * When true, unread state is auto-cleared (treated as "user is reading
+   * the chat right now"). Pass your dock-open boolean here so the badge
+   * resets the moment the user opens the chat.
+   */
+  open?: boolean;
+  /**
+   * Which message roles count as "unread". Defaults to `['assistant']` —
+   * we only count inbound replies, not the user's own messages.
+   */
+  countRoles?: Array<ChatMessage['role']>;
+}
+
+export interface UseChatUnreadReturn {
+  /** Most-recent inbound message since the last mark-as-read. */
+  unread: ChatMessage | null;
+  /** Total inbound messages since the last mark-as-read. */
+  count: number;
+  /** Manually clear the unread state. */
+  markRead: () => void;
+}
+
+/**
+ * Track inbound chat messages while the user isn't watching.
+ *
+ * Must be called **inside** the chat's `<ChatProvider>` (i.e. inside the
+ * `children` of `ChatLauncher`, alongside `ChatRoot`).
+ *
+ * @example
+ * ```tsx
+ * function ChatRootWithUnreadBadge({ open, onUnread }: { open: boolean; onUnread: (m: ChatMessage | null) => void }) {
+ *   const { unread, count, markRead } = useChatUnread({ open });
+ *   useEffect(() => onUnread(unread), [unread, onUnread]);
+ *   // pass `count` to your FAB badge via the host's state
+ *   return <ChatRoot transport={transport} />;
+ * }
+ * ```
+ *
+ * For end-to-end wiring with `<ChatLauncher unreadMessage onMarkRead>`,
+ * see the `Launcher / WithLivePush` story.
+ */
+export function useChatUnread(opts: UseChatUnreadOptions = {}): UseChatUnreadReturn {
+  const { open = false, countRoles = ['assistant'] } = opts;
+  const ctx = useChatContext();
+
+  const [lastSeenId, setLastSeenId] = useState<string | null>(null);
+  // On first mount, treat the current tail as already seen so old history
+  // doesn't immediately register as unread.
+  const initialized = useRef(false);
+  useEffect(() => {
+    if (initialized.current) return;
+    initialized.current = true;
+    const tail = ctx.messages[ctx.messages.length - 1];
+    setLastSeenId(tail?.id ?? null);
+  }, [ctx.messages]);
+
+  // While the dock is open, auto-advance the seen pointer to the tail so
+  // count stays at 0.
+  useEffect(() => {
+    if (!open) return;
+    const tail = ctx.messages[ctx.messages.length - 1];
+    setLastSeenId(tail?.id ?? null);
+  }, [open, ctx.messages]);
+
+  // Compute unread tail since `lastSeenId`.
+  const seenIdx = lastSeenId
+    ? ctx.messages.findIndex((m) => m.id === lastSeenId)
+    : -1;
+  const after = seenIdx === -1 ? ctx.messages : ctx.messages.slice(seenIdx + 1);
+  const inbound = after.filter((m) => countRoles.includes(m.role));
+  const unread = inbound.length > 0 ? inbound[inbound.length - 1]! : null;
+
+  const markRead = useCallback(() => {
+    const tail = ctx.messages[ctx.messages.length - 1];
+    setLastSeenId(tail?.id ?? null);
+  }, [ctx.messages]);
+
+  return { unread, count: inbound.length, markRead };
+}

package/src/tools/Chat/hooks/useFocusOnEmptyClick.ts

@@ -0,0 +1,111 @@
+'use client';
+
+import { useCallback, useRef } from 'react';
+import type { MouseEvent as ReactMouseEvent, RefObject } from 'react';
+
+import { useChatContextOptional, type ComposerHandle } from '../context';
+import type { Focusable } from './useAutoFocusOnStreamEnd';
+
+export interface UseFocusOnEmptyClickOptions {
+  /**
+   * Custom focus target. Defaults to the composer registered in the chat
+   * context.
+   */
+  targetRef?: RefObject<Focusable | HTMLElement | null>;
+  /** Opt-out without unmounting the hook. @default true */
+  enabled?: boolean;
+  /**
+   * Don't focus if currently streaming (user is reading the reply).
+   * @default true
+   */
+  skipWhileStreaming?: boolean;
+}
+
+/**
+ * "Click anywhere in the chat → focus the composer" — Slack / Linear /
+ * ChatGPT behaviour.
+ *
+ * Returns a single `onMouseUp` handler to attach to the scrollable
+ * messages container. Heuristics that mirror the popular chat apps:
+ *
+ *   1. Ignore clicks on interactive elements (`button`, `a`, `input`,
+ *      `textarea`, `[role="button"]`, `[contenteditable]`, …) — they
+ *      have their own behaviour.
+ *   2. Ignore clicks that produced a text selection (drag-to-select).
+ *      Stealing focus would break copy-paste flow.
+ *   3. Ignore touch input — on mobile the system focuses the textarea
+ *      via tap on the composer itself; touching messages should never
+ *      open the keyboard.
+ *   4. Optionally skip while the assistant is streaming so the user
+ *      can keep reading without the keyboard popping up.
+ *
+ * @example
+ * ```tsx
+ * const onMouseUp = useFocusOnEmptyClick();
+ * <div ref={scrollRef} onMouseUp={onMouseUp}>{messages}</div>
+ * ```
+ */
+export function useFocusOnEmptyClick(
+  options: UseFocusOnEmptyClickOptions = {},
+): (event: ReactMouseEvent<HTMLElement>) => void {
+  const { targetRef, enabled = true, skipWhileStreaming = true } = options;
+  const ctx = useChatContextOptional();
+
+  const composerHandleRef = useRef<ComposerHandle | null>(null);
+  composerHandleRef.current = ctx?.composer ?? null;
+
+  const isStreamingRef = useRef(false);
+  isStreamingRef.current = ctx?.isStreaming ?? false;
+
+  return useCallback(
+    (event: ReactMouseEvent<HTMLElement>) => {
+      if (!enabled) return;
+      if (skipWhileStreaming && isStreamingRef.current) return;
+
+      // Touch / pen → never steal focus (mobile keyboard pop is hostile).
+      const pointerType = (event.nativeEvent as PointerEvent).pointerType;
+      if (pointerType && pointerType !== 'mouse') return;
+
+      // Drag-selected text → don't steal focus.
+      const selection = typeof window !== 'undefined' ? window.getSelection?.() : null;
+      if (selection && !selection.isCollapsed && selection.toString().length > 0) {
+        return;
+      }
+
+      // Click landed on something interactive → it handles itself.
+      const target = event.target as HTMLElement | null;
+      if (!target) return;
+      if (isInteractive(target)) return;
+
+      // Refocus.
+      const explicit = targetRef?.current as Focusable | HTMLElement | null | undefined;
+      if (explicit) {
+        explicit.focus?.();
+        return;
+      }
+      composerHandleRef.current?.focus?.();
+    },
+    [enabled, skipWhileStreaming, targetRef],
+  );
+}
+
+const INTERACTIVE_SELECTORS = [
+  'a[href]',
+  'button',
+  'input',
+  'textarea',
+  'select',
+  'label',
+  'summary',
+  '[role="button"]',
+  '[role="link"]',
+  '[role="menuitem"]',
+  '[role="tab"]',
+  '[contenteditable]:not([contenteditable="false"])',
+  '[data-no-autofocus]',
+].join(',');
+
+function isInteractive(el: HTMLElement | null): boolean {
+  if (!el) return false;
+  return !!el.closest(INTERACTIVE_SELECTORS);
+}