@djangocfg/ui-tools 2.1.335 → 2.1.337

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

@@ -0,0 +1,191 @@
+'use client';
+
+import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from 'react';
+
+import { createAudioBus, type ChatAudioBus } from '../core/audio/audioBus';
+import { useChatAudioPrefs } from '../core/audio/preferences';
+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';
+}
+
+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;
+}

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

@@ -0,0 +1,227 @@
+'use client';
+
+import {
+  type ChangeEvent,
+  type ClipboardEvent,
+  type KeyboardEvent,
+  type RefObject,
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+} from 'react';
+
+import type { ChatAttachment } from '../types';
+import { LIMITS } from '../config';
+
+export interface UseChatComposerOptions {
+  onSubmit: (content: string, attachments: ChatAttachment[]) => void | Promise<void>;
+  initialValue?: string;
+  maxLength?: number;
+  maxAttachments?: number;
+  disabled?: boolean;
+  /** 'enter' = Enter sends, Shift+Enter newline. 'cmd+enter' = Enter inserts newline, Cmd/Ctrl+Enter sends. */
+  submitOn?: 'enter' | 'cmd+enter';
+  history?: { enabled?: boolean; size?: number };
+  onPasteFiles?: (files: File[]) => void;
+}
+
+export interface UseChatComposerReturn {
+  value: string;
+  setValue: (next: string) => void;
+  attachments: ChatAttachment[];
+  addAttachment: (a: ChatAttachment) => void;
+  removeAttachment: (id: string) => void;
+  isSubmitting: boolean;
+  canSubmit: boolean;
+  submit: () => Promise<void>;
+  reset: () => void;
+  focus: () => void;
+  textareaRef: RefObject<HTMLTextAreaElement | null>;
+  textareaProps: {
+    ref: RefObject<HTMLTextAreaElement | null>;
+    value: string;
+    disabled: boolean;
+    onChange: (e: ChangeEvent<HTMLTextAreaElement>) => void;
+    onKeyDown: (e: KeyboardEvent<HTMLTextAreaElement>) => void;
+    onPaste: (e: ClipboardEvent<HTMLTextAreaElement>) => void;
+  };
+  recallPrevious: () => void;
+  recallNext: () => void;
+}
+
+const MAX_TEXTAREA_HEIGHT = 240;
+
+export function useChatComposer(options: UseChatComposerOptions): UseChatComposerReturn {
+  const {
+    onSubmit,
+    initialValue = '',
+    maxLength = LIMITS.messageMaxLength,
+    maxAttachments = LIMITS.attachmentsMax,
+    disabled = false,
+    submitOn = 'enter',
+    history = { enabled: true, size: LIMITS.composerHistorySize },
+    onPasteFiles,
+  } = options;
+
+  const [value, setValueState] = useState(initialValue);
+  const [attachments, setAttachments] = useState<ChatAttachment[]>([]);
+  const [isSubmitting, setIsSubmitting] = useState(false);
+  const textareaRef = useRef<HTMLTextAreaElement | null>(null);
+
+  const historyRef = useRef<{ items: string[]; index: number }>({ items: [], index: -1 });
+
+  const setValue = useCallback(
+    (next: string) => {
+      setValueState(next.length > maxLength ? next.slice(0, maxLength) : next);
+    },
+    [maxLength],
+  );
+
+  // Autosize textarea on value change.
+  useEffect(() => {
+    const el = textareaRef.current;
+    if (!el) return;
+    el.style.height = 'auto';
+    el.style.height = `${Math.min(el.scrollHeight, MAX_TEXTAREA_HEIGHT)}px`;
+  }, [value]);
+
+  const reset = useCallback(() => {
+    setValueState('');
+    setAttachments([]);
+    historyRef.current.index = -1;
+  }, []);
+
+  const focus = useCallback(() => {
+    requestAnimationFrame(() => textareaRef.current?.focus());
+  }, []);
+
+  const submit = useCallback(async () => {
+    const trimmed = value.trim();
+    if ((!trimmed && attachments.length === 0) || isSubmitting || disabled) return;
+    setIsSubmitting(true);
+    try {
+      if (history.enabled !== false && trimmed) {
+        const buf = historyRef.current.items;
+        if (buf[buf.length - 1] !== trimmed) {
+          buf.push(trimmed);
+          if (buf.length > (history.size ?? LIMITS.composerHistorySize)) buf.shift();
+        }
+        historyRef.current.index = -1;
+      }
+      const snapshot = [...attachments];
+      const text = value;
+      reset();
+      await onSubmit(text, snapshot);
+    } finally {
+      setIsSubmitting(false);
+    }
+  }, [value, attachments, isSubmitting, disabled, history, onSubmit, reset]);
+
+  const addAttachment = useCallback(
+    (a: ChatAttachment) => {
+      setAttachments((prev) => {
+        if (prev.some((p) => p.id === a.id)) {
+          return prev.map((p) => (p.id === a.id ? a : p));
+        }
+        if (prev.length >= maxAttachments) return prev;
+        return [...prev, a];
+      });
+    },
+    [maxAttachments],
+  );
+
+  const removeAttachment = useCallback((id: string) => {
+    setAttachments((prev) => prev.filter((a) => a.id !== id));
+  }, []);
+
+  const recallPrevious = useCallback(() => {
+    const { items } = historyRef.current;
+    if (!items.length) return;
+    const next = historyRef.current.index < 0 ? items.length - 1 : Math.max(0, historyRef.current.index - 1);
+    historyRef.current.index = next;
+    setValueState(items[next]);
+  }, []);
+
+  const recallNext = useCallback(() => {
+    const { items } = historyRef.current;
+    if (!items.length || historyRef.current.index < 0) return;
+    const next = historyRef.current.index + 1;
+    if (next >= items.length) {
+      historyRef.current.index = -1;
+      setValueState('');
+      return;
+    }
+    historyRef.current.index = next;
+    setValueState(items[next]);
+  }, []);
+
+  const onChange = useCallback(
+    (e: ChangeEvent<HTMLTextAreaElement>) => {
+      setValue(e.target.value);
+    },
+    [setValue],
+  );
+
+  const onKeyDown = useCallback(
+    (e: KeyboardEvent<HTMLTextAreaElement>) => {
+      if (e.key === 'Enter') {
+        const isCmd = e.metaKey || e.ctrlKey;
+        const shouldSend = submitOn === 'cmd+enter' ? isCmd : !e.shiftKey;
+        if (shouldSend) {
+          e.preventDefault();
+          void submit();
+        }
+        return;
+      }
+      if (history.enabled !== false && value === '' && attachments.length === 0) {
+        if (e.key === 'ArrowUp') {
+          e.preventDefault();
+          recallPrevious();
+        } else if (e.key === 'ArrowDown' && historyRef.current.index >= 0) {
+          e.preventDefault();
+          recallNext();
+        }
+      }
+    },
+    [submitOn, submit, history, value, attachments.length, recallPrevious, recallNext],
+  );
+
+  const onPaste = useCallback(
+    (e: ClipboardEvent<HTMLTextAreaElement>) => {
+      const files = Array.from(e.clipboardData?.files ?? []);
+      if (files.length && onPasteFiles) {
+        e.preventDefault();
+        onPasteFiles(files);
+      }
+    },
+    [onPasteFiles],
+  );
+
+  const canSubmit =
+    !disabled && !isSubmitting && (value.trim().length > 0 || attachments.length > 0);
+
+  return {
+    value,
+    setValue,
+    attachments,
+    addAttachment,
+    removeAttachment,
+    isSubmitting,
+    canSubmit,
+    submit,
+    reset,
+    focus,
+    textareaRef,
+    textareaProps: {
+      ref: textareaRef,
+      value,
+      disabled,
+      onChange,
+      onKeyDown,
+      onPaste,
+    },
+    recallPrevious,
+    recallNext,
+  };
+}

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

@@ -0,0 +1,59 @@
+'use client';
+
+import { type RefObject, useEffect, useRef } from 'react';
+
+export interface UseChatHistoryOptions {
+  enabled?: boolean;
+  containerRef: RefObject<HTMLElement | null>;
+  topSentinelRef: RefObject<HTMLElement | null>;
+  hasMore: boolean;
+  isLoadingMore: boolean;
+  loadMore: () => Promise<void>;
+}
+
+/** Triggers `loadMore` when the top sentinel enters the container's viewport.
+ *  Preserves scroll anchor: if the container's height grows after load, we
+ *  bump scrollTop by the delta so the previously-visible message stays put. */
+export function useChatHistory(options: UseChatHistoryOptions): void {
+  const { enabled = true, containerRef, topSentinelRef, hasMore, isLoadingMore, loadMore } = options;
+  const heightBeforeRef = useRef<number | null>(null);
+
+  // Restore anchor after content prepends.
+  useEffect(() => {
+    if (heightBeforeRef.current == null) return;
+    const el = containerRef.current;
+    if (!el) {
+      heightBeforeRef.current = null;
+      return;
+    }
+    if (!isLoadingMore) {
+      const delta = el.scrollHeight - heightBeforeRef.current;
+      if (delta > 0) {
+        el.scrollTop += delta;
+      }
+      heightBeforeRef.current = null;
+    }
+  }, [containerRef, isLoadingMore]);
+
+  useEffect(() => {
+    if (!enabled || !hasMore) return;
+    const sentinel = topSentinelRef.current;
+    const root = containerRef.current;
+    if (!sentinel || !root) return;
+
+    const observer = new IntersectionObserver(
+      (entries) => {
+        const entry = entries[0];
+        if (!entry?.isIntersecting) return;
+        if (isLoadingMore) return;
+        const el = containerRef.current;
+        if (el) heightBeforeRef.current = el.scrollHeight;
+        void loadMore();
+      },
+      { root, threshold: 0, rootMargin: '200px 0px 0px 0px' },
+    );
+
+    observer.observe(sentinel);
+    return () => observer.disconnect();
+  }, [enabled, hasMore, isLoadingMore, containerRef, topSentinelRef, loadMore]);
+}

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

@@ -0,0 +1,111 @@
+'use client';
+
+import { useCallback, useEffect, useMemo, useState } from 'react';
+
+import { useLocalStorage, useMediaQuery } from '@djangocfg/ui-core/hooks';
+
+import { CSS_VARS, DEFAULT_SIDEBAR, STORAGE_KEYS } from '../config';
+import type { ChatDisplayMode } from '../types';
+
+export interface UseChatLayoutConfig {
+  defaultMode?: ChatDisplayMode;
+  storageKey?: string;
+  sidebarStorageKey?: string;
+  reserveCssVar?: string;
+  defaultSidebarWidth?: number;
+  minSidebarWidth?: number;
+  maxSidebarWidth?: number;
+  /** Mobile breakpoint, e.g. '(max-width: 640px)'. */
+  mobileQuery?: string;
+}
+
+export interface UseChatLayoutReturn {
+  mode: ChatDisplayMode;
+  setMode: (m: ChatDisplayMode) => void;
+  open: () => void;
+  close: () => void;
+  toggle: () => void;
+  sidebarWidth: number;
+  setSidebarWidth: (w: number) => void;
+  isMobile: boolean;
+  /** Mode after mobile collapse rules — sidebar/floating become fullscreen on mobile. */
+  effectiveMode: ChatDisplayMode;
+}
+
+const DEFAULT_MOBILE_QUERY = '(max-width: 640px)';
+
+export function useChatLayout(config: UseChatLayoutConfig = {}): UseChatLayoutReturn {
+  const {
+    defaultMode = 'closed',
+    storageKey = STORAGE_KEYS.mode,
+    sidebarStorageKey = STORAGE_KEYS.sidebarWidth,
+    reserveCssVar = CSS_VARS.reserve,
+    defaultSidebarWidth = DEFAULT_SIDEBAR.width,
+    minSidebarWidth = DEFAULT_SIDEBAR.min,
+    maxSidebarWidth = DEFAULT_SIDEBAR.max,
+    mobileQuery = DEFAULT_MOBILE_QUERY,
+  } = config;
+
+  const [mode, setMode] = useLocalStorage<ChatDisplayMode>(storageKey, defaultMode);
+  const [sidebarWidthRaw, setSidebarWidthRaw] = useLocalStorage<number>(
+    sidebarStorageKey,
+    defaultSidebarWidth,
+  );
+  const isMobile = useMediaQuery(mobileQuery);
+
+  const setSidebarWidth = useCallback(
+    (w: number) => {
+      const clamped = Math.max(minSidebarWidth, Math.min(maxSidebarWidth, w));
+      setSidebarWidthRaw(clamped);
+    },
+    [setSidebarWidthRaw, minSidebarWidth, maxSidebarWidth],
+  );
+
+  const [previousOpenMode, setPreviousOpenMode] = useState<ChatDisplayMode>(
+    mode === 'closed' ? 'embedded' : mode,
+  );
+  useEffect(() => {
+    if (mode !== 'closed') setPreviousOpenMode(mode);
+  }, [mode]);
+
+  const open = useCallback(() => {
+    setMode(previousOpenMode === 'closed' ? 'embedded' : previousOpenMode);
+  }, [setMode, previousOpenMode]);
+
+  const close = useCallback(() => setMode('closed'), [setMode]);
+  const toggle = useCallback(() => {
+    setMode((mode === 'closed' ? previousOpenMode : 'closed') as ChatDisplayMode);
+  }, [setMode, mode, previousOpenMode]);
+
+  const effectiveMode = useMemo<ChatDisplayMode>(() => {
+    if (mode === 'closed') return 'closed';
+    if (isMobile && (mode === 'sidebar' || mode === 'floating')) return 'fullscreen';
+    return mode;
+  }, [mode, isMobile]);
+
+  // Reserve right padding when in sidebar mode.
+  useEffect(() => {
+    if (typeof document === 'undefined') return;
+    const root = document.documentElement;
+    if (effectiveMode === 'sidebar') {
+      root.style.setProperty(reserveCssVar, `${sidebarWidthRaw}px`);
+    } else {
+      root.style.removeProperty(reserveCssVar);
+    }
+    return () => {
+      root.style.removeProperty(reserveCssVar);
+    };
+  }, [effectiveMode, sidebarWidthRaw, reserveCssVar]);
+
+  return {
+    mode,
+    setMode,
+    open,
+    close,
+    toggle,
+    sidebarWidth: sidebarWidthRaw,
+    setSidebarWidth,
+    isMobile,
+    effectiveMode,
+  };
+}

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

@@ -0,0 +1,34 @@
+'use client';
+
+import { useCallback, useState } from 'react';
+
+import type { ChatAttachment } from '../types';
+
+export type ChatLightboxScope = 'message' | 'conversation';
+
+export interface ChatLightboxState {
+  gallery: ChatAttachment[];
+  index: number;
+}
+
+export interface UseChatLightboxReturn {
+  state: ChatLightboxState | null;
+  open: (att: ChatAttachment, gallery?: ChatAttachment[]) => void;
+  close: () => void;
+}
+
+/** Tiny state container for an image lightbox. The host owns the modal +
+ *  `<LazyImageViewer>` mount; we just track which gallery to show. */
+export function useChatLightbox(): UseChatLightboxReturn {
+  const [state, setState] = useState<ChatLightboxState | null>(null);
+
+  const open = useCallback((att: ChatAttachment, gallery?: ChatAttachment[]) => {
+    const list = gallery && gallery.length ? gallery : [att];
+    const idx = list.findIndex((a) => a.id === att.id);
+    setState({ gallery: list, index: idx === -1 ? 0 : idx });
+  }, []);
+
+  const close = useCallback(() => setState(null), []);
+
+  return { state, open, close };
+}