@djangocfg/ui-tools 2.1.409 → 2.1.411

package/src/tools/Chat/settings/__tests__/useChatSettings.test.tsx

@@ -0,0 +1,84 @@
+// @vitest-environment jsdom
+import { act, createElement } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { CHAT_SETTINGS_STORAGE_KEY } from '../types';
+import { useChatSettings, type UseChatSettingsReturn } from '../useChatSettings';
+
+(globalThis as Record<string, unknown>).IS_REACT_ACT_ENVIRONMENT = true;
+
+let container: HTMLDivElement;
+let root: Root;
+let api: UseChatSettingsReturn | null = null;
+
+function Probe() {
+  api = useChatSettings();
+  return null;
+}
+
+beforeEach(() => {
+  window.localStorage.clear();
+  container = document.createElement('div');
+  document.body.appendChild(container);
+  root = createRoot(container);
+});
+
+afterEach(() => {
+  act(() => root.unmount());
+  container.remove();
+  window.localStorage.clear();
+  api = null;
+});
+
+async function flush() {
+  await act(async () => {
+    await Promise.resolve();
+  });
+}
+
+describe('useChatSettings', () => {
+  it('exposes the default settings before anything is stored', async () => {
+    await act(async () => root.render(createElement(Probe)));
+    expect(api!.settings.pageContext.linked).toBe(false);
+    expect(api!.settings.audio.muted).toBe(false);
+    expect(api!.settings.dock.side).toBe('right');
+  });
+
+  it('updates only the targeted slice, leaving siblings untouched', async () => {
+    await act(async () => root.render(createElement(Probe)));
+    const audioBefore = api!.settings.audio;
+
+    await act(async () => api!.updateDock({ side: 'left' }));
+
+    expect(api!.settings.dock.side).toBe('left');
+    // Audio slice identity is unchanged — a feature never touches another's.
+    expect(api!.settings.audio).toBe(audioBefore);
+  });
+
+  it('setPageContextLinked persists the opt-in under the central key', async () => {
+    await act(async () => root.render(createElement(Probe)));
+    await act(async () => api!.setPageContextLinked(true));
+    await flush();
+
+    expect(api!.settings.pageContext.linked).toBe(true);
+    const stored = JSON.parse(
+      window.localStorage.getItem(CHAT_SETTINGS_STORAGE_KEY)!,
+    );
+    expect(stored.pageContext.linked).toBe(true);
+  });
+
+  it('reset restores every slice to defaults', async () => {
+    await act(async () => root.render(createElement(Probe)));
+    await act(async () => {
+      api!.setAudioMuted(true);
+      api!.updateDock({ side: 'left' });
+    });
+    await flush();
+    expect(api!.settings.audio.muted).toBe(true);
+
+    await act(async () => api!.reset());
+    expect(api!.settings.audio.muted).toBe(false);
+    expect(api!.settings.dock.side).toBe('right');
+  });
+});

package/src/tools/Chat/settings/__tests__/useLocalStorage.test.tsx

@@ -0,0 +1,138 @@
+// @vitest-environment jsdom
+//
+// Covers the Part-1 additions to `@djangocfg/ui-core`'s `useLocalStorage`:
+// partial-merge `patch`, no-op skip, write coalescing, and same-tab
+// cross-instance sync. ui-core ships no test runner, so the test lives
+// here (ui-tools has vitest + jsdom and resolves ui-core via workspace).
+import { act, createElement } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { useLocalStorage } from '@djangocfg/ui-core/hooks';
+
+(globalThis as Record<string, unknown>).IS_REACT_ACT_ENVIRONMENT = true;
+
+interface Prefs {
+  a: number;
+  b: number;
+  c: string;
+}
+
+let container: HTMLDivElement;
+let root: Root;
+
+beforeEach(() => {
+  window.localStorage.clear();
+  container = document.createElement('div');
+  document.body.appendChild(container);
+  root = createRoot(container);
+});
+
+afterEach(() => {
+  act(() => root.unmount());
+  container.remove();
+  window.localStorage.clear();
+});
+
+/** Flush pending microtask-coalesced writes. */
+async function flushMicrotasks() {
+  await act(async () => {
+    await Promise.resolve();
+  });
+}
+
+describe('useLocalStorage — patch / coalescing / sync', () => {
+  it('patch shallow-merges a subset of keys', async () => {
+    let api: ReturnType<typeof useLocalStorage<Prefs>> | null = null;
+    function Probe() {
+      api = useLocalStorage<Prefs>('t.patch', { a: 1, b: 2, c: 'x' });
+      return null;
+    }
+    await act(async () => root.render(createElement(Probe)));
+
+    await act(async () => {
+      api![3]({ b: 99 });
+    });
+    expect(api![0]).toEqual({ a: 1, b: 99, c: 'x' });
+
+    await flushMicrotasks();
+    expect(JSON.parse(window.localStorage.getItem('t.patch')!)).toEqual({
+      a: 1,
+      b: 99,
+      c: 'x',
+    });
+  });
+
+  it('patch is a no-op when nothing changes', async () => {
+    let renders = 0;
+    let api: ReturnType<typeof useLocalStorage<Prefs>> | null = null;
+    function Probe() {
+      renders += 1;
+      api = useLocalStorage<Prefs>('t.noop', { a: 1, b: 2, c: 'x' });
+      return null;
+    }
+    await act(async () => root.render(createElement(Probe)));
+    await flushMicrotasks();
+    const rendersAfterMount = renders;
+
+    // Patching with the same values must not trigger a write/re-render.
+    await act(async () => {
+      api![3]({ a: 1, b: 2 });
+    });
+    await flushMicrotasks();
+
+    expect(renders).toBe(rendersAfterMount);
+    // No write happened — key stays absent.
+    expect(window.localStorage.getItem('t.noop')).toBeNull();
+  });
+
+  it('coalesces several patches in one tick into a single write', async () => {
+    let api: ReturnType<typeof useLocalStorage<Prefs>> | null = null;
+    function Probe() {
+      api = useLocalStorage<Prefs>('t.coalesce', { a: 0, b: 0, c: '' });
+      return null;
+    }
+    await act(async () => root.render(createElement(Probe)));
+
+    // Spy on the prototype — jsdom's per-instance `setItem` is read-only.
+    let writes = 0;
+    const realSetItem = Storage.prototype.setItem;
+    Storage.prototype.setItem = function patched(this: Storage, k, v) {
+      if (k === 't.coalesce') writes += 1;
+      return realSetItem.call(this, k, v);
+    };
+
+    await act(async () => {
+      api![3]({ a: 1 });
+      api![3]({ b: 2 });
+      api![3]({ c: 'z' });
+    });
+    await flushMicrotasks();
+    Storage.prototype.setItem = realSetItem;
+
+    // State reflects all three patches...
+    expect(api![0]).toEqual({ a: 1, b: 2, c: 'z' });
+    // ...but they collapsed into exactly one localStorage write.
+    expect(writes).toBe(1);
+  });
+
+  it('two hook instances on the same key stay in sync (same tab)', async () => {
+    let a: ReturnType<typeof useLocalStorage<Prefs>> | null = null;
+    let b: ReturnType<typeof useLocalStorage<Prefs>> | null = null;
+    function Probe() {
+      a = useLocalStorage<Prefs>('t.sync', { a: 1, b: 1, c: 'x' });
+      b = useLocalStorage<Prefs>('t.sync', { a: 1, b: 1, c: 'x' });
+      return null;
+    }
+    await act(async () => root.render(createElement(Probe)));
+
+    await act(async () => {
+      a![3]({ b: 42 });
+    });
+    await flushMicrotasks();
+
+    // The sibling instance saw the write without its own setter being called.
+    expect(a![0]).toEqual({ a: 1, b: 42, c: 'x' });
+    expect(b![0]).toEqual({ a: 1, b: 42, c: 'x' });
+  });
+});

package/src/tools/Chat/settings/index.ts

@@ -0,0 +1,23 @@
+'use client';
+
+/**
+ * @djangocfg/ui-tools — Chat / settings
+ *
+ * The one place every chat-owned persisted setting lives. See README.md.
+ */
+
+export {
+  CHAT_SETTINGS_STORAGE_KEY,
+  DEFAULT_CHAT_SETTINGS,
+  type ChatSettings,
+  type ChatDockSettings,
+  type ChatAudioSettings,
+  type ChatSpeechSettings,
+  type ChatPageContextSettings,
+} from './types';
+
+export {
+  useChatSettings,
+  type UseChatSettingsOptions,
+  type UseChatSettingsReturn,
+} from './useChatSettings';

package/src/tools/Chat/settings/types.ts

@@ -0,0 +1,108 @@
+'use client';
+
+import type { ChatDisplayMode } from '../types';
+
+/**
+ * Dock / layout preferences.
+ *
+ * Mirrors the fields the existing `useChatDockPrefs` / `useChatLayout`
+ * persist today. Kept as a nested slice so a feature can `updateDock({...})`
+ * without touching audio / speech / page-context state.
+ */
+export interface ChatDockSettings {
+  /** Floating popover vs. side-docked panel vs. embedded, etc. */
+  mode: ChatDisplayMode;
+  /** Which edge a side dock attaches to. */
+  side: 'left' | 'right';
+  /** Width in px when side-docked. */
+  width: number;
+}
+
+/**
+ * Audio / notification-sound preferences.
+ *
+ * `eventsMuted` is a sparse map: only events the user explicitly toggled
+ * off appear here. An absent key means "use the default for that event".
+ */
+export interface ChatAudioSettings {
+  /** Master mute — silences every chat sound. */
+  muted: boolean;
+  /** Master volume, 0..1. */
+  volume: number;
+  /** Per-event opt-outs, keyed by chat audio event name. */
+  eventsMuted: Record<string, boolean>;
+}
+
+/**
+ * Speech-recognition / language-picker preferences.
+ *
+ * `language` is a BCP-47 tag the user explicitly picked, or `null` for
+ * "no override" — callers then fall back to the app locale.
+ */
+export interface ChatSpeechSettings {
+  /** Explicit language override, or `null` to follow the app locale. */
+  language: string | null;
+  /** Preferred capture device id, or `null` for the system default. */
+  deviceId: string | null;
+  /** Preferred STT engine id, or `null` for auto-select. */
+  engineId: string | null;
+  /** Earcon (audio cue) feedback on dictation start/stop. */
+  earcons: boolean;
+}
+
+/** Page-context (screen-sharing) opt-in. */
+export interface ChatPageContextSettings {
+  /**
+   * Whether the user has opted in to sharing a snapshot of the page they
+   * are viewing with the assistant. Persisted so the choice survives
+   * reloads — the user enables it once.
+   */
+  linked: boolean;
+}
+
+/**
+ * The single, typed shape for every chat-owned persisted setting.
+ *
+ * Centralization rationale: chat features used to each call
+ * `useLocalStorage` with their own ad-hoc key. That made it impossible to
+ * reason about (or export/import) "the chat's settings" as one thing, and
+ * scattered the SSR/migration concerns. One object, one storage key, one
+ * hook — every feature reads/writes its own slice through it.
+ */
+export interface ChatSettings {
+  dock: ChatDockSettings;
+  audio: ChatAudioSettings;
+  speech: ChatSpeechSettings;
+  pageContext: ChatPageContextSettings;
+}
+
+/** Baseline defaults — used for SSR and first-run (nothing stored yet). */
+export const DEFAULT_CHAT_SETTINGS: ChatSettings = {
+  dock: {
+    mode: 'closed',
+    side: 'right',
+    width: 420,
+  },
+  audio: {
+    muted: false,
+    volume: 1,
+    eventsMuted: {},
+  },
+  speech: {
+    language: null,
+    deviceId: null,
+    engineId: null,
+    earcons: false,
+  },
+  pageContext: {
+    linked: false,
+  },
+};
+
+/**
+ * Single localStorage key for the whole chat-settings object.
+ *
+ * One key (vs. one-per-feature) so the entire chat configuration is a
+ * single read/write/coalesce unit — see {@link useChatSettings}.
+ */
+export const CHAT_SETTINGS_STORAGE_KEY = 'djc.chat.settings';

package/src/tools/Chat/settings/useChatSettings.ts

@@ -0,0 +1,168 @@
+'use client';
+
+import { useCallback, useMemo } from 'react';
+
+import { useLocalStorage } from '@djangocfg/ui-core/hooks';
+
+import {
+  CHAT_SETTINGS_STORAGE_KEY,
+  DEFAULT_CHAT_SETTINGS,
+  type ChatAudioSettings,
+  type ChatDockSettings,
+  type ChatPageContextSettings,
+  type ChatSettings,
+  type ChatSpeechSettings,
+} from './types';
+
+/** Options for {@link useChatSettings}. */
+export interface UseChatSettingsOptions {
+  /**
+   * Override the storage key (per-product scoping). Defaults to the
+   * shared {@link CHAT_SETTINGS_STORAGE_KEY}.
+   */
+  storageKey?: string;
+  /**
+   * Override baseline defaults — merged over {@link DEFAULT_CHAT_SETTINGS}
+   * at the slice level (per-product branding, host opt-ins, etc.).
+   */
+  defaults?: Partial<ChatSettings>;
+}
+
+/** Everything {@link useChatSettings} exposes. */
+export interface UseChatSettingsReturn {
+  /** The full, typed settings object (each slice always present). */
+  settings: ChatSettings;
+
+  /**
+   * Top-level grouped patch — shallow-merges whole slices. Use this for
+   * cross-slice updates; for a single slice prefer the typed helpers.
+   */
+  patch: (partial: Partial<ChatSettings>) => void;
+
+  /** Merge a subset of dock fields. */
+  updateDock: (partial: Partial<ChatDockSettings>) => void;
+  /** Merge a subset of audio fields. */
+  updateAudio: (partial: Partial<ChatAudioSettings>) => void;
+  /** Merge a subset of speech fields. */
+  updateSpeech: (partial: Partial<ChatSpeechSettings>) => void;
+  /** Merge a subset of page-context fields. */
+  updatePageContext: (partial: Partial<ChatPageContextSettings>) => void;
+
+  /** Master audio mute shortcut. */
+  setAudioMuted: (muted: boolean) => void;
+  /** Page-context opt-in shortcut. */
+  setPageContextLinked: (linked: boolean) => void;
+
+  /** Reset every slice back to defaults. */
+  reset: () => void;
+}
+
+/** Shallow-merge `defaults` slices over the baseline. */
+function resolveDefaults(defaults?: Partial<ChatSettings>): ChatSettings {
+  if (!defaults) return DEFAULT_CHAT_SETTINGS;
+  return {
+    dock: { ...DEFAULT_CHAT_SETTINGS.dock, ...defaults.dock },
+    audio: { ...DEFAULT_CHAT_SETTINGS.audio, ...defaults.audio },
+    speech: { ...DEFAULT_CHAT_SETTINGS.speech, ...defaults.speech },
+    pageContext: {
+      ...DEFAULT_CHAT_SETTINGS.pageContext,
+      ...defaults.pageContext,
+    },
+  };
+}
+
+/**
+ * The single entry point for chat-owned persisted settings.
+ *
+ * Every chat feature that wants to remember a preference goes through
+ * here instead of calling `useLocalStorage` with its own key. Why:
+ *
+ * - One typed object, one storage key — "the chat's settings" is a single
+ *   thing that can be reasoned about, exported, or reset wholesale.
+ * - Coalesced writes: `useLocalStorage` (Part 1) updates React state
+ *   synchronously but batches the actual `localStorage` write to one per
+ *   tick — so several features patching different slices in the same
+ *   render commit collapse into a single write, no thrash.
+ * - Cross-instance sync: two `useChatSettings()` consumers (e.g. the
+ *   header audio toggle and the settings panel) stay in lockstep within
+ *   the same tab and across tabs.
+ *
+ * Each helper updates only its own slice, leaving sibling slices
+ * untouched — a feature never has to know about the others.
+ *
+ * SSR-safe: returns defaults on the server, hydrates on mount.
+ */
+export function useChatSettings(
+  opts: UseChatSettingsOptions = {},
+): UseChatSettingsReturn {
+  const key = opts.storageKey ?? CHAT_SETTINGS_STORAGE_KEY;
+  // Memoized so the resolved defaults keep a stable identity — passing a
+  // fresh object to `useLocalStorage` each render is harmless but wasteful.
+  const initial = useMemo(
+    () => resolveDefaults(opts.defaults),
+    [opts.defaults],
+  );
+
+  const [settings, setSettings, , patch] = useLocalStorage<ChatSettings>(
+    key,
+    initial,
+  );
+
+  // Slice updaters: read the current slice, shallow-merge the partial,
+  // write back via the coalescing top-level `patch`. The inner
+  // `useLocalStorage` `patch` already skips no-op writes.
+  const updateDock = useCallback(
+    (partial: Partial<ChatDockSettings>) => {
+      patch({ dock: { ...settings.dock, ...partial } });
+    },
+    [patch, settings.dock],
+  );
+
+  const updateAudio = useCallback(
+    (partial: Partial<ChatAudioSettings>) => {
+      patch({ audio: { ...settings.audio, ...partial } });
+    },
+    [patch, settings.audio],
+  );
+
+  const updateSpeech = useCallback(
+    (partial: Partial<ChatSpeechSettings>) => {
+      patch({ speech: { ...settings.speech, ...partial } });
+    },
+    [patch, settings.speech],
+  );
+
+  const updatePageContext = useCallback(
+    (partial: Partial<ChatPageContextSettings>) => {
+      patch({ pageContext: { ...settings.pageContext, ...partial } });
+    },
+    [patch, settings.pageContext],
+  );
+
+  const setAudioMuted = useCallback(
+    (muted: boolean) => updateAudio({ muted }),
+    [updateAudio],
+  );
+
+  const setPageContextLinked = useCallback(
+    (linked: boolean) => updatePageContext({ linked }),
+    [updatePageContext],
+  );
+
+  const reset = useCallback(
+    () => setSettings(initial),
+    [setSettings, initial],
+  );
+
+  return {
+    settings,
+    patch,
+    updateDock,
+    updateAudio,
+    updateSpeech,
+    updatePageContext,
+    setAudioMuted,
+    setPageContextLinked,
+    reset,
+  };
+}