@djangocfg/ui-tools 2.1.394 → 2.1.397

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

@@ -0,0 +1,132 @@
+import type { ReactNode } from 'react';
+
+import type { ChatContextValue } from '../context';
+import type { ChatDockPrefs } from '../hooks/useChatDockPrefs';
+
+/**
+ * Declarative reset slot. The launcher renders the standard
+ * `<ChatHeaderResetButton>` wired to `onReset`, defaulting `onSuccess`
+ * to `ctx.clearMessages()`. The button hides itself until a `sessionId`
+ * exists on the chat context.
+ */
+export interface ChatHeaderResetSlot {
+  /** Backend reset call. Resolves to `true` on success. */
+  onReset: () => Promise<boolean>;
+  /** Show a confirm dialog before calling `onReset`. @default true */
+  confirm?: boolean;
+  /** Confirm dialog title. */
+  confirmTitle?: string;
+  /** Confirm dialog message. */
+  confirmMessage?: string;
+  /** Override tooltip / aria label. */
+  ariaLabel?: string;
+  /**
+   * Called after a successful reset. Defaults to `ctx.clearMessages()`.
+   * Override to also re-fetch history, navigate, fire analytics, etc.
+   */
+  onSuccess?: (ctx: ChatContextValue) => void;
+  /** Called on failure (returned `false` or threw). */
+  onError?: (err?: unknown) => void;
+}
+
+/** Declarative language-picker slot. */
+export interface ChatHeaderLanguageSlot {
+  /** Subset of BCP-47 tags to offer. */
+  allowedTags?: string[];
+  /** Override aria-label. */
+  ariaLabel?: string;
+  /** Hide the globe fallback icon when no flag resolves. */
+  hideFallbackIcon?: boolean;
+}
+
+/**
+ * Declarative mode-toggle slot. The launcher owns `useChatDockPrefs`
+ * internally — set `persistAs` to a localStorage key for persistence
+ * (omit for ephemeral / session-only mode toggling).
+ */
+export interface ChatHeaderModeToggleSlot {
+  /**
+   * localStorage key for `useChatDockPrefs`. When provided the toggle
+   * persists across reloads; omit to use an ephemeral in-memory toggle.
+   */
+  persistAs?: string;
+  /** Override the default `{ mode: 'popover', side: 'right', sideWidth: 420 }`. */
+  defaults?: Partial<ChatDockPrefs>;
+  /** Show the toggle even on viewports below `lg` (1024px). @default true */
+  forceVisible?: boolean;
+  /** Tooltip / aria for popover → side. */
+  expandLabel?: string;
+  /** Tooltip / aria for side → popover. */
+  collapseLabel?: string;
+}
+
+/**
+ * Header buttons rendered INSIDE the `<ChatProvider>` mounted by
+ * `<ChatLauncher>`. Each entry is rendered in the fixed order:
+ *
+ *   custom · languagePicker · modeToggle · audio · reset
+ *
+ * (close icon is always last, owned by `<ChatHeader>`).
+ *
+ * Slots that accept `boolean | object`:
+ *  - `true`  → render with default config
+ *  - `false` → hide explicitly
+ *  - object  → render with the given options
+ *
+ * Defaults:
+ *  - `audio`: rendered automatically when `audio` prop is passed to
+ *    `<ChatLauncher>` AND the resolved instance is not silent.
+ *  - `modeToggle`, `languagePicker`: off unless opted in.
+ *  - `reset`: off unless `onReset` is provided.
+ */
+export interface ChatHeaderSlots {
+  /** Auto-mute toggle. Defaults to true when launcher `audio` is configured. */
+  audio?: boolean;
+  /** Popover ↔ side mode toggle. */
+  modeToggle?: boolean | ChatHeaderModeToggleSlot;
+  /** Speech-recognition language picker. */
+  languagePicker?: boolean | ChatHeaderLanguageSlot;
+  /** Reset-conversation button. */
+  reset?: ChatHeaderResetSlot;
+  /** Arbitrary extra buttons rendered first (left-most). */
+  custom?: (ctx: ChatContextValue) => ReactNode;
+}
+
+/**
+ * Resolved mode-toggle config used by the launcher to pick between
+ * the dock's mode/side props and the prefs slot.
+ */
+export interface ResolvedChatHeaderSlots {
+  audio: boolean;
+  modeToggle: ChatHeaderModeToggleSlot | null;
+  languagePicker: ChatHeaderLanguageSlot | null;
+  reset: ChatHeaderResetSlot | null;
+  custom: ((ctx: ChatContextValue) => ReactNode) | null;
+}
+
+export function resolveHeaderSlots(
+  slots: ChatHeaderSlots | undefined,
+  audioConfigured: boolean,
+): ResolvedChatHeaderSlots {
+  const s = slots ?? {};
+  const audio = s.audio ?? audioConfigured;
+  const modeToggle: ChatHeaderModeToggleSlot | null =
+    s.modeToggle === true
+      ? {}
+      : s.modeToggle && typeof s.modeToggle === 'object'
+        ? s.modeToggle
+        : null;
+  const languagePicker: ChatHeaderLanguageSlot | null =
+    s.languagePicker === true
+      ? {}
+      : s.languagePicker && typeof s.languagePicker === 'object'
+        ? s.languagePicker
+        : null;
+  return {
+    audio,
+    modeToggle,
+    languagePicker,
+    reset: s.reset ?? null,
+    custom: s.custom ?? null,
+  };
+}

package/src/tools/Chat/lazy.tsx

@@ -136,9 +136,11 @@ export {
   DEFAULT_DOCK_PREFS,
   useFocusOnEmptyClick,
   useChatUnread,
+  useChatUnreadNotifier,
   useChatLightbox,
   type UseChatUnreadOptions,
   type UseChatUnreadReturn,
+  type UseChatUnreadNotifierOptions,
   type UseChatConfig,
   type UseChatReturn,
   type UseChatComposerOptions,
@@ -171,6 +173,24 @@ export {
   type UseChatAudioReturn,
 } from './core/audio';
 
+// Notifier — title rotation + favicon badge + cross-tab decorator. Pure
+// browser-API code, no React, no UI components.
+export {
+  createBrowserNotifier,
+  createNoopNotifier,
+  createTitleRotator,
+  createFaviconBadge,
+  createCrossTabNotifier,
+  isPageHidden,
+  onVisibilityChange,
+  type ChatNotifier,
+  type BrowserNotifierOptions,
+  type TitleRotatorOptions,
+  type TitleMode,
+  type FaviconBadgeOptions,
+  type CrossTabNotifierOptions,
+} from './notifier';
+
 // Tool-call payload dispatcher — pure
 export {
   dispatchToolPayload,
@@ -269,6 +289,10 @@ export type {
   ChatLauncherProps,
   ChatLauncherHotkey,
   ChatLauncherGreeting,
+  ChatHeaderSlots,
+  ChatHeaderResetSlot,
+  ChatHeaderLanguageSlot,
+  ChatHeaderModeToggleSlot,
   ChatFABProps,
   ChatFABPosition,
   ChatFABVariant,

package/src/tools/Chat/notifier/createBrowserNotifier.ts

@@ -0,0 +1,64 @@
+import type { ChatMessage } from '../types';
+
+import { createFaviconBadge, type FaviconBadgeOptions } from './faviconBadge';
+import { createTitleRotator, type TitleRotatorOptions } from './titleRotator';
+import type { ChatNotifier } from './types';
+
+export interface BrowserNotifierOptions {
+  /** Title rotation config. Pass `false` to disable title mutation. */
+  title?: TitleRotatorOptions | false;
+  /** Favicon badge config. Pass `false` to disable favicon mutation. */
+  favicon?: FaviconBadgeOptions | false;
+}
+
+const NOOP: ChatNotifier = { setUnread() {}, clear() {} };
+
+/**
+ * Facebook-style unread notifier: alternates `document.title` between
+ * the base title and an alert, plus paints a small badge over the
+ * favicon. Both surfaces are optional and individually toggleable.
+ *
+ * Returns a no-op in SSR or non-DOM environments — safe to construct
+ * unconditionally.
+ *
+ * The notifier itself is **stateless w.r.t. visibility** by design;
+ * the hook layer (`useChatUnreadNotifier`) decides when to call
+ * `setUnread` vs `clear` based on page focus. Keeping the policy in
+ * the hook lets hosts swap in their own notifier (Wails dock badge,
+ * cross-tab Zustand broadcaster) without duplicating the gating logic.
+ */
+export function createBrowserNotifier(opts: BrowserNotifierOptions = {}): ChatNotifier {
+  if (typeof document === 'undefined') return NOOP;
+
+  const title = opts.title === false ? null : createTitleRotator(opts.title);
+  const favicon = opts.favicon === false ? null : createFaviconBadge(opts.favicon);
+
+  let active = false;
+
+  return {
+    setUnread(count: number, latest?: ChatMessage | null) {
+      if (count <= 0) {
+        this.clear();
+        return;
+      }
+      if (active) {
+        title?.update(count, latest);
+        favicon?.set(count);
+      } else {
+        active = true;
+        title?.start(count, latest);
+        favicon?.set(count);
+      }
+    },
+    clear() {
+      if (!active) return;
+      active = false;
+      title?.stop();
+      favicon?.clear();
+    },
+  };
+}
+
+export function createNoopNotifier(): ChatNotifier {
+  return NOOP;
+}

package/src/tools/Chat/notifier/createCrossTabNotifier.ts

@@ -0,0 +1,99 @@
+import type { ChatMessage } from '../types';
+
+import type { ChatNotifier } from './types';
+
+export interface CrossTabNotifierOptions {
+  /**
+   * The underlying notifier that performs the actual title/favicon
+   * mutation (usually `createBrowserNotifier()`). The decorator only
+   * forwards calls when this tab is the elected leader; followers stay
+   * silent so the title doesn't flicker in stereo across 4 open tabs.
+   */
+  inner: ChatNotifier;
+  /**
+   * Live "this tab is the leader" flag. Read from `useActiveTab` in
+   * the hook layer and passed in via the live-getter form so the
+   * notifier sees the latest value without React re-rendering it.
+   */
+  isLeader: () => boolean;
+  /**
+   * Optional broadcast channel name. Followers subscribe to count
+   * updates here so the in-tab badge UI (FAB counter) stays in sync
+   * even when they're not the one mutating the title.
+   *
+   * Default: `djangocfg-chat:unread`.
+   */
+  channel?: string;
+  /**
+   * Callback for follower tabs: fired when a peer (leader) reports an
+   * unread count update. Use it to drive a Zustand store that the FAB
+   * badge subscribes to.
+   */
+  onPeerUpdate?: (count: number) => void;
+}
+
+interface BroadcastPayload {
+  count: number;
+}
+
+const DEFAULT_CHANNEL = 'djangocfg-chat:unread';
+
+/**
+ * Decorator over an inner notifier that adds cross-tab coordination.
+ *
+ * Behaviour:
+ *   - Leader tab → forwards `setUnread/clear` to the inner notifier
+ *     AND broadcasts the count so follower tabs can update their FAB
+ *     badge UI.
+ *   - Follower tab → does NOT call inner (silent on title/favicon),
+ *     but still broadcasts via `onPeerUpdate` so the host store
+ *     reflects the truth.
+ *
+ * When leadership flips at runtime (e.g. the previous leader closed
+ * its tab), the next `setUnread` call from the new leader will start
+ * mutating the title — there's no special handoff needed because the
+ * inner notifier is idempotent.
+ */
+export function createCrossTabNotifier(opts: CrossTabNotifierOptions): ChatNotifier {
+  const { inner, isLeader, onPeerUpdate } = opts;
+  const channelName = opts.channel ?? DEFAULT_CHANNEL;
+
+  let channel: BroadcastChannel | null = null;
+  if (typeof BroadcastChannel !== 'undefined') {
+    channel = new BroadcastChannel(channelName);
+    if (onPeerUpdate) {
+      channel.addEventListener('message', (e) => {
+        const data = e.data as BroadcastPayload | undefined;
+        if (!data || typeof data.count !== 'number') return;
+        onPeerUpdate(data.count);
+      });
+    }
+  }
+
+  return {
+    setUnread(count: number, latest?: ChatMessage | null) {
+      // Broadcast first so followers learn the count even if our local
+      // inner notifier no-ops in this environment.
+      channel?.postMessage({ count } satisfies BroadcastPayload);
+      if (isLeader()) {
+        inner.setUnread(count, latest);
+      }
+    },
+    clear() {
+      channel?.postMessage({ count: 0 } satisfies BroadcastPayload);
+      if (isLeader()) {
+        inner.clear();
+      } else {
+        // Followers never armed the inner notifier, but call clear()
+        // anyway in case leadership flipped between an old setUnread
+        // and this clear — inner is idempotent.
+        inner.clear();
+      }
+    },
+    dispose() {
+      channel?.close();
+      channel = null;
+      inner.dispose?.();
+    },
+  };
+}

package/src/tools/Chat/notifier/faviconBadge.ts

@@ -0,0 +1,280 @@
+export interface FaviconBadgeOptions {
+  /**
+   * Badge fill color. Default Facebook-ish red.
+   */
+  badgeColor?: string;
+  /**
+   * Text/number color. Default white.
+   */
+  textColor?: string;
+  /**
+   * `true` → paint the count inside the badge (caps at 99+).
+   * `false` → flat dot. Default `false` — Facebook-style restraint.
+   */
+  showCount?: boolean;
+  /**
+   * Optional explicit base favicon URL. If omitted, we read the current
+   * `<link rel="icon">` href; if there is none, we paint onto a blank
+   * canvas so something useful still appears on the tab.
+   */
+  baseUrl?: string;
+  /**
+   * Canvas size in CSS px. 32 is the standard favicon hi-DPI size.
+   */
+  size?: number;
+  /**
+   * Pulse the badge by alternating between the badged frame and the
+   * bare base favicon. Default `true` — periphery-vision cue that
+   * makes the dot findable in a tab bar of dozens of icons. Set
+   * `false` for a static dot (quieter; matches enterprise tastes).
+   */
+  pulse?: boolean;
+  /**
+   * Milliseconds the badge stays visible per cycle. Default 600.
+   */
+  pulseOnMs?: number;
+  /**
+   * Milliseconds the badge is hidden per cycle. Default 400.
+   * Asymmetric on/off (default 600/400) gives a Slack/FB-style
+   * heartbeat — the badge is the dominant state, the gap is brief.
+   */
+  pulseOffMs?: number;
+}
+
+interface BadgeHandle {
+  set(count: number): void;
+  clear(): void;
+}
+
+const LINK_REL_VARIANTS = ['icon', 'shortcut icon'] as const;
+const MANAGED_ATTR = 'data-chat-favicon-badge';
+
+/**
+ * Paints a small badge over the page's favicon using a hidden canvas
+ * and swaps the resulting data URL into `<link rel="icon">`. SSR-safe.
+ *
+ * Notes / gotchas (encoded as invariants):
+ *   - SVG favicons can't be rastered via `<img>` reliably across
+ *     browsers without inlining. We attempt anyway; on failure we paint
+ *     a blank background + the badge so the tab still signals unread.
+ *   - We never mutate the host's original `<link>`. We add a managed
+ *     `<link rel="icon" data-chat-favicon-badge>` ahead of it; on clear
+ *     we remove that managed node. This is the cleanest way to handle
+ *     hosts that swap their own favicons (e.g. Next.js dynamic icons).
+ *   - Cross-origin favicons need CORS to draw; if drawing throws we
+ *     fall back to a CORS-less canvas (badge only, no base image).
+ */
+export function createFaviconBadge(opts: FaviconBadgeOptions = {}): BadgeHandle {
+  if (typeof document === 'undefined') {
+    return { set() {}, clear() {} };
+  }
+
+  const badgeColor = opts.badgeColor ?? '#ef4444';
+  const textColor = opts.textColor ?? '#ffffff';
+  const showCount = opts.showCount ?? false;
+  const size = opts.size ?? 32;
+  const pulse = opts.pulse ?? true;
+  const pulseOnMs = opts.pulseOnMs ?? 600;
+  const pulseOffMs = opts.pulseOffMs ?? 400;
+
+  let baseImg: HTMLImageElement | null = null;
+  let baseLoaded = false;
+  let lastCount = -1;
+
+  // Pulse animation state.
+  let frameOn: string | null = null;   // badged frame data URL
+  let frameOff: string | null = null;  // bare base frame data URL (or empty)
+  let pulseTimer: ReturnType<typeof setTimeout> | null = null;
+  let pulsePhase: 'on' | 'off' = 'on';
+
+  const detectBaseUrl = (): string | null => {
+    if (opts.baseUrl) return opts.baseUrl;
+    for (const rel of LINK_REL_VARIANTS) {
+      const link = document.querySelector<HTMLLinkElement>(
+        `link[rel="${rel}"]:not([${MANAGED_ATTR}])`,
+      );
+      if (link?.href) return link.href;
+    }
+    return null;
+  };
+
+  const loadBase = () => {
+    if (baseImg) return;
+    const url = detectBaseUrl();
+    if (!url) return;
+    const img = new Image();
+    img.crossOrigin = 'anonymous';
+    img.onload = () => {
+      baseLoaded = true;
+      // If a `set()` came in before load completed, re-render now.
+      if (lastCount >= 0) renderFrames(lastCount);
+    };
+    img.onerror = () => {
+      // Network/CORS failure: leave baseLoaded=false; we'll paint badge
+      // on a blank canvas.
+      baseLoaded = false;
+    };
+    img.src = url;
+    baseImg = img;
+  };
+
+  const removeManagedLinks = () => {
+    document
+      .querySelectorAll(`link[${MANAGED_ATTR}]`)
+      .forEach((node) => node.remove());
+  };
+
+  const applyDataUrl = (dataUrl: string) => {
+    removeManagedLinks();
+    const link = document.createElement('link');
+    link.rel = 'icon';
+    link.type = 'image/png';
+    link.href = dataUrl;
+    link.setAttribute(MANAGED_ATTR, 'true');
+    document.head.appendChild(link);
+  };
+
+  // Paint the off-phase frame. If we have a usable base favicon, this
+  // is the bare base; otherwise a transparent canvas. Returning a
+  // transparent frame (rather than `null` + removing the link) is
+  // load-bearing: Chrome only re-rasters the tab favicon when the
+  // managed `<link>`'s href *changes*, so off-phase MUST swap to a
+  // different data URL — not vanish — for the pulse to be visible.
+  const renderOffFrame = (): string | null => {
+    const canvas = document.createElement('canvas');
+    canvas.width = size;
+    canvas.height = size;
+    const ctx = canvas.getContext('2d');
+    if (!ctx) return null;
+
+    if (baseImg && baseLoaded) {
+      try {
+        ctx.drawImage(baseImg, 0, 0, size, size);
+      } catch {
+        // Tainted canvas → fall through to the empty frame.
+        ctx.clearRect(0, 0, size, size);
+      }
+    }
+    // If no base, the canvas stays fully transparent — Chrome falls
+    // back to its default tab glyph, which still gives a visible
+    // on/off contrast against the red badge.
+    try {
+      return canvas.toDataURL('image/png');
+    } catch {
+      return null;
+    }
+  };
+
+  // Paint the badged frame. Reused for both the static (no-pulse) case
+  // and the `on` phase of the pulse loop.
+  const renderBadged = (count: number): string | null => {
+    const canvas = document.createElement('canvas');
+    canvas.width = size;
+    canvas.height = size;
+    const ctx = canvas.getContext('2d');
+    if (!ctx) return null;
+
+    if (baseImg && baseLoaded) {
+      try {
+        ctx.drawImage(baseImg, 0, 0, size, size);
+      } catch {
+        ctx.clearRect(0, 0, size, size);
+      }
+    }
+
+    const r = size * 0.28;
+    const cx = size - r - size * 0.04;
+    const cy = size - r - size * 0.04;
+
+    ctx.fillStyle = badgeColor;
+    ctx.beginPath();
+    ctx.arc(cx, cy, r, 0, Math.PI * 2);
+    ctx.fill();
+
+    if (showCount) {
+      const label = count > 99 ? '99+' : String(count);
+      ctx.fillStyle = textColor;
+      const fontSize = label.length >= 3 ? r * 0.85 : r * 1.25;
+      ctx.font = `600 ${fontSize}px system-ui, -apple-system, sans-serif`;
+      ctx.textAlign = 'center';
+      ctx.textBaseline = 'middle';
+      ctx.fillText(label, cx, cy + fontSize * 0.06);
+    }
+
+    try {
+      return canvas.toDataURL('image/png');
+    } catch {
+      // Tainted-canvas fallback: badge only, no base.
+      const fb = document.createElement('canvas');
+      fb.width = size;
+      fb.height = size;
+      const fctx = fb.getContext('2d');
+      if (!fctx) return null;
+      fctx.fillStyle = badgeColor;
+      fctx.beginPath();
+      fctx.arc(cx, cy, r, 0, Math.PI * 2);
+      fctx.fill();
+      return fb.toDataURL('image/png');
+    }
+  };
+
+  const stopPulse = () => {
+    if (pulseTimer !== null) {
+      clearTimeout(pulseTimer);
+      pulseTimer = null;
+    }
+  };
+
+  const tickPulse = () => {
+    if (frameOn === null) return;
+    // Always swap the managed <link>'s href between two distinct data
+    // URLs — Chrome / Safari skip the redraw if the href is identical
+    // to what was just set, so removing-and-readding the node isn't
+    // enough on its own (`renderOffFrame` guarantees a non-null off
+    // frame whenever frameOn exists).
+    if (pulsePhase === 'on') {
+      applyDataUrl(frameOn);
+      pulsePhase = 'off';
+      pulseTimer = setTimeout(tickPulse, pulseOnMs);
+    } else {
+      applyDataUrl(frameOff ?? frameOn);
+      pulsePhase = 'on';
+      pulseTimer = setTimeout(tickPulse, pulseOffMs);
+    }
+  };
+
+  const renderFrames = (count: number) => {
+    frameOn = renderBadged(count);
+    frameOff = renderOffFrame();
+
+    if (frameOn === null) return;
+
+    if (!pulse) {
+      applyDataUrl(frameOn);
+      return;
+    }
+
+    // (Re-)start the pulse loop. If a previous loop was running we
+    // tear it down first so the cadence doesn't double up.
+    stopPulse();
+    pulsePhase = 'on';
+    tickPulse();
+  };
+
+  return {
+    set(count) {
+      lastCount = count;
+      loadBase();
+      // If base not loaded yet, the onload handler will call
+      // renderFrames(lastCount) once it resolves.
+      renderFrames(count);
+    },
+    clear() {
+      lastCount = -1;
+      stopPulse();
+      frameOn = null;
+      frameOff = null;
+      removeManagedLinks();
+    },
+  };
+}

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

@@ -0,0 +1,20 @@
+export type { ChatNotifier } from './types';
+export {
+  createBrowserNotifier,
+  createNoopNotifier,
+  type BrowserNotifierOptions,
+} from './createBrowserNotifier';
+export {
+  createTitleRotator,
+  type TitleRotatorOptions,
+  type TitleMode,
+} from './titleRotator';
+export {
+  createFaviconBadge,
+  type FaviconBadgeOptions,
+} from './faviconBadge';
+export { isPageHidden, onVisibilityChange } from './visibility';
+export {
+  createCrossTabNotifier,
+  type CrossTabNotifierOptions,
+} from './createCrossTabNotifier';