@djangocfg/ui-tools 2.1.394 → 2.1.397

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

@@ -0,0 +1,134 @@
+'use client';
+
+import { useEffect, useMemo, useRef, useState } from 'react';
+
+import { useActiveTabStore } from '@djangocfg/ui-core/hooks';
+
+import {
+  createBrowserNotifier,
+  createCrossTabNotifier,
+  isPageHidden,
+  onVisibilityChange,
+  type BrowserNotifierOptions,
+  type ChatNotifier,
+} from '../notifier';
+
+import { useChatUnread, type UseChatUnreadOptions } from './useChatUnread';
+
+export interface UseChatUnreadNotifierOptions extends UseChatUnreadOptions {
+  /**
+   * Custom notifier. Pass a host-specific implementation (Wails dock
+   * badge etc.) to opt out of the built-in browser title/favicon
+   * mutation. If omitted, a `createBrowserNotifier` instance is used.
+   */
+  notifier?: ChatNotifier;
+  /**
+   * Options forwarded to the default browser notifier. Ignored when an
+   * explicit `notifier` is provided.
+   */
+  browser?: BrowserNotifierOptions;
+  /**
+   * Master switch. Default `true`. Set false to keep the unread
+   * tracking but skip all environment mutation.
+   */
+  enabled?: boolean;
+  /**
+   * Cross-tab coordination. When enabled (default), only the elected
+   * leader tab mutates `document.title` / favicon — other tabs stay
+   * silent. The unread count is broadcast so every tab's FAB badge UI
+   * still reflects reality.
+   *
+   * Pass `false` to disable; pass an options object to customise the
+   * BroadcastChannel name. Disable in single-tab hosts (Wails / Electron)
+   * where leadership is moot.
+   */
+  crossTab?: boolean | { channel?: string };
+}
+
+/**
+ * Glue between `useChatUnread` and a `ChatNotifier`.
+ *
+ * Inputs that drive the notifier:
+ *   1. `useChatUnread` — provider-state-derived `{ count, unread }`.
+ *   2. Page visibility — clear when visible; re-arm when hidden+count>0.
+ *   3. Tab leadership (when `crossTab` enabled) — only leader mutates
+ *      title/favicon; followers receive count broadcasts so their
+ *      in-tab badge UI stays in sync.
+ *
+ * Returns `useChatUnread`'s shape, with the `count` overridden by
+ * cross-tab broadcasts when this tab is a follower (so the FAB badge
+ * shows the same number across every tab).
+ */
+export function useChatUnreadNotifier(opts: UseChatUnreadNotifierOptions = {}) {
+  const {
+    notifier: notifierProp,
+    browser,
+    enabled = true,
+    crossTab = true,
+    ...unreadOpts
+  } = opts;
+  const unread = useChatUnread(unreadOpts);
+
+  // Cross-tab count from peers (followers see this; leader publishes).
+  const [peerCount, setPeerCount] = useState<number | null>(null);
+
+  const crossTabChannel =
+    typeof crossTab === 'object' ? crossTab.channel : undefined;
+  const crossTabEnabled = crossTab !== false;
+
+  // Build the notifier. Inner = host-supplied OR built-in browser.
+  // Wrap with cross-tab decorator when enabled.
+  const notifier = useMemo<ChatNotifier>(() => {
+    const inner = notifierProp ?? createBrowserNotifier(browser);
+    if (!crossTabEnabled) return inner;
+    return createCrossTabNotifier({
+      inner,
+      isLeader: () => useActiveTabStore.getState().isLeader,
+      channel: crossTabChannel,
+      onPeerUpdate: (count) => setPeerCount(count),
+    });
+  }, [notifierProp, browser, crossTabEnabled, crossTabChannel]);
+
+  const lastSyncedCount = useRef(0);
+
+  // Visibility-driven sync. Single effect owns both the listener and
+  // the imperative calls to keep ordering deterministic.
+  useEffect(() => {
+    if (!enabled) {
+      notifier.clear();
+      return;
+    }
+
+    const sync = () => {
+      const hidden = isPageHidden();
+      if (hidden && unread.count > 0) {
+        notifier.setUnread(unread.count, unread.unread);
+        lastSyncedCount.current = unread.count;
+      } else {
+        notifier.clear();
+        lastSyncedCount.current = 0;
+      }
+    };
+
+    sync();
+    const unsub = onVisibilityChange(sync);
+    return () => {
+      unsub();
+      notifier.clear();
+    };
+  }, [enabled, notifier, unread.count, unread.unread]);
+
+  // Final cleanup — release any host-side resources.
+  useEffect(() => () => notifier.dispose?.(), [notifier]);
+
+  // Effective count: max of local (this tab's own unread tracking) and
+  // peer broadcast. The max handles the case where a peer hasn't sent
+  // a broadcast yet (peerCount === null) — we trust local.
+  const effectiveCount =
+    peerCount !== null ? Math.max(unread.count, peerCount) : unread.count;
+
+  return {
+    ...unread,
+    count: effectiveCount,
+  };
+}

package/src/tools/Chat/index.ts

@@ -103,6 +103,10 @@ export {
   type ChatLauncherProps,
   type ChatLauncherHotkey,
   type ChatLauncherGreeting,
+  type ChatHeaderSlots,
+  type ChatHeaderResetSlot,
+  type ChatHeaderLanguageSlot,
+  type ChatHeaderModeToggleSlot,
   type ChatGreetingProps,
   type ChatUnreadPreviewProps,
   type ChatPresencePhase,
@@ -124,8 +128,10 @@ export {
   DEFAULT_DOCK_PREFS,
   useFocusOnEmptyClick,
   useChatUnread,
+  useChatUnreadNotifier,
   type UseChatUnreadOptions,
   type UseChatUnreadReturn,
+  type UseChatUnreadNotifierOptions,
   type UseChatConfig,
   type UseChatReturn,
   type UseChatComposerOptions,
@@ -146,6 +152,23 @@ export {
   type UseFocusOnEmptyClickOptions,
 } from './hooks';
 
+// Notifier — title rotation + favicon badge + page-visibility + cross-tab
+export {
+  createBrowserNotifier,
+  createNoopNotifier,
+  createTitleRotator,
+  createFaviconBadge,
+  createCrossTabNotifier,
+  isPageHidden,
+  onVisibilityChange,
+  type ChatNotifier,
+  type BrowserNotifierOptions,
+  type TitleRotatorOptions,
+  type TitleMode,
+  type FaviconBadgeOptions,
+  type CrossTabNotifierOptions,
+} from './notifier';
+
 // Audio
 export type {
   ChatAudioEvent,

package/src/tools/Chat/launcher/ChatLauncher.tsx

@@ -1,16 +1,24 @@
 'use client';
 
-import { useCallback, useEffect, useRef, useState } from 'react';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import type { ReactNode } from 'react';
 
 import { useHotkey } from '@djangocfg/ui-core/hooks';
 
+import { ChatProvider, useChatContextOptional } from '../context';
+import type { ChatAudioConfig } from '../core/audio/types';
+import type {
+  ChatConfig,
+  ChatMessage,
+  ChatTransport,
+} from '../types';
+
 import { ChatFAB, type ChatFABPosition, type ChatFABProps } from './ChatFAB';
 import { ChatDock, type ChatDockProps } from './ChatDock';
 import { ChatGreeting, type ChatGreetingProps } from './ChatGreeting';
-import { ChatHeaderAudioToggle } from './ChatHeaderAudioToggle';
 import { ChatUnreadPreview, type ChatUnreadPreviewProps } from './ChatUnreadPreview';
-import type { ChatMessage } from '../types';
+import { HeaderSlotsRenderer } from './HeaderSlots';
+import { resolveHeaderSlots, type ChatHeaderSlots } from './types';
 
 export interface ChatLauncherHotkey {
   /** Key (case-sensitive single char or named like 'Escape'). */
@@ -34,73 +42,73 @@ export interface ChatLauncherGreeting
 }
 
 export interface ChatLauncherProps {
-  /** Dock contents — typically a `<Chat>` instance. */
+  // ---- chat-provider wiring (mounts <ChatProvider> internally) -----------
+  /**
+   * Transport. Required unless the launcher is mounted inside an
+   * existing `<ChatProvider>` (in which case the ambient provider is
+   * reused and `transport` is ignored).
+   */
+  transport?: ChatTransport;
+  /** Optional chat config (labels, prefs, persona, etc.). */
+  config?: ChatConfig;
+  /** Pre-existing session to attach to. */
+  initialSessionId?: string;
+  /** Create a new backend session automatically when none is provided. */
+  autoCreateSession?: boolean;
+  /** Enable streaming. Defaults to transport's preference. */
+  streaming?: boolean;
+  /**
+   * Audio-trigger configuration (sounds map). The launcher owns the
+   * `useChatAudio()` hook internally; consumers no longer construct it
+   * themselves.
+   */
+  audio?: ChatAudioConfig;
+  /** Verbose dev logging via consola. */
+  debug?: boolean;
+  /** Rewrite outgoing content before transport. */
+  onBeforeSend?: (content: string) => string | Promise<string>;
+
+  // ---- visual chrome ------------------------------------------------------
+  /** Dock contents — typically a `<ChatRoot>` or custom chat shell. */
   children: ReactNode;
-  /** FAB customization (icon, position, label, pulse, badge, tooltip, variant, size). */
+  /** FAB customization. */
   fab?: Omit<ChatFABProps, 'onClick'>;
-  /** Dock customization (size, title, position, transition, mobileFullscreen). */
-  dock?: Omit<ChatDockProps, 'open' | 'onClose' | 'children'>;
+  /** Dock customization. `headerActions` is computed from `headerSlots`. */
+  dock?: Omit<ChatDockProps, 'open' | 'onClose' | 'children' | 'headerActions'>;
+  /**
+   * Declarative header buttons rendered INSIDE the launcher's
+   * `<ChatProvider>`. See `ChatHeaderSlots` for the available knobs.
+   */
+  headerSlots?: ChatHeaderSlots;
   /**
-   * Proactive greeting bubble shown next to the FAB before the user opens the chat.
-   * Set to a string or full config object. Omit to disable.
+   * Proactive greeting bubble shown next to the FAB before the user
+   * opens the chat.
    */
   greeting?: string | ChatLauncherGreeting;
   /** Open/close via a keyboard shortcut. */
   hotkey?: ChatLauncherHotkey;
   /** Initial open state for uncontrolled mode. @default false */
   defaultOpen?: boolean;
-  /** Controlled open state (pair with `onOpenChange`). */
+  /** Controlled open state. */
   open?: boolean;
   /** Controlled open state setter. */
   onOpenChange?: (open: boolean) => void;
-  /**
-   * Focus the composer textarea when the dock opens. Saves a click for
-   * every "FAB → start typing" interaction. @default true
-   */
+  /** Focus the composer when the dock opens. @default true */
   autoFocusComposerOnOpen?: boolean;
-  /**
-   * Close the dock on `Escape`. Mirrors standard popover / drawer UX.
-   * Set to `false` to disable (e.g. if you want Escape to do something
-   * else inside the chat). @default true
-   */
+  /** Close the dock on Escape. @default true */
   closeOnEscape?: boolean;
   /**
-   * Last inbound message (admin reply / system notice / agent push) the
-   * user hasn't seen yet. Drives the `<ChatUnreadPreview>` bubble next
-   * to the FAB and (by default) the FAB badge.
-   *
-   * Source it from `useChatUnread()` inside your `<ChatProvider>`.
+   * Last unread inbound message — drives `<ChatUnreadPreview>` and the
+   * FAB badge.
    */
   unreadMessage?: ChatMessage | null;
-  /**
-   * Called when the user opens the chat via FAB/preview/hotkey or
-   * dismisses the preview with ×. Wire to `useChatUnread().markRead`.
-   */
+  /** Called when the chat is opened or the preview dismissed. */
   onMarkRead?: () => void;
-  /**
-   * Customize the unread bubble (`truncate`, `dismissLabel`, …).
-   * `open`/`message`/`onClick`/`onDismiss`/`position`/`fabOffset` are
-   * wired automatically.
-   */
+  /** Customize the unread bubble. */
   unreadPreview?: Omit<
     ChatUnreadPreviewProps,
     'open' | 'message' | 'onClick' | 'onDismiss' | 'position' | 'fabOffset'
   >;
-  /**
-   * Auto-inject a mute / unmute button into the header. Pass the
-   * `useChatAudio()` (or any compatible `{ muted, toggleMute }`)
-   * instance — the launcher renders `<ChatHeaderAudioToggle>` in the
-   * header's actions slot when audio is actually configured (not silent).
-   *
-   * Hosts that manage their own header can ignore this prop and render
-   * `<ChatHeaderAudioToggle>` directly.
-   */
-  audio?: { muted: boolean; toggleMute: () => void; isSilent?: boolean } | null;
-  /**
-   * Suppress the auto-injected audio toggle even when `audio` is passed.
-   * @default false
-   */
-  hideAudioToggle?: boolean;
 }
 
 function readDismissed(storageKey: string | null | undefined): boolean {
@@ -124,15 +132,31 @@ function writeDismissed(storageKey: string | null | undefined): void {
 }
 
 /**
- * Floating chat launcher = FAB + Dock + presence + optional greeting + hotkey.
+ * Floating chat launcher = `<ChatProvider>` + FAB + Dock + presence
+ * + optional greeting + hotkey.
  *
- * 99% of hosts use this directly. For non-FAB triggers (e.g. an inline
- * link in the page) compose `<ChatDock>` with your own button.
+ * The provider lives at this level so:
+ *   - declarative `headerSlots` (e.g. `reset`) can read `sessionId` /
+ *     call `clearMessages()` via `useChatContext()` while rendering in
+ *     the dock header, which is a sibling of `children` (not a child).
+ *   - descendant `<ChatRoot>` instances detect the ambient provider and
+ *     skip wrapping in a second one.
  */
 export function ChatLauncher({
+  // provider wiring
+  transport,
+  config,
+  initialSessionId,
+  autoCreateSession,
+  streaming,
+  audio,
+  debug,
+  onBeforeSend,
+  // visual chrome
   children,
   fab,
   dock,
+  headerSlots,
   greeting,
   hotkey,
   defaultOpen = false,
@@ -143,8 +167,6 @@ export function ChatLauncher({
   unreadMessage,
   onMarkRead,
   unreadPreview,
-  audio,
-  hideAudioToggle = false,
 }: ChatLauncherProps) {
   const [uncontrolledOpen, setUncontrolledOpen] = useState(defaultOpen);
   const isControlled = controlledOpen !== undefined;
@@ -152,9 +174,6 @@ export function ChatLauncher({
   const dockContentRef = useRef<HTMLDivElement>(null);
 
   // Auto-focus the composer when the dock opens.
-  // We probe the dock subtree for the first textarea/input after the
-  // enter-transition settles. Keeps the hook self-contained — no need to
-  // bridge into the ChatProvider context which lives inside `children`.
   useEffect(() => {
     if (!autoFocusComposerOnOpen || !open) return;
     const t = setTimeout(() => {
@@ -177,12 +196,6 @@ export function ChatLauncher({
   );
   const toggleOpen = useCallback(() => setOpen(!open), [open, setOpen]);
 
-  // Two-step Escape (ChatGPT / Slack behaviour):
-  //   - When focus is inside a textarea / input / contenteditable, first Esc
-  //     just blurs — drafts survive accidental presses.
-  //   - When focus is elsewhere (the user already left the composer or never
-  //     focused it), Esc closes the dock.
-  // Disabled when chat is shut so we don't intercept page-level Esc bindings.
   useHotkey(
     'escape',
     (e) => {
@@ -227,7 +240,6 @@ export function ChatLauncher({
     return () => window.removeEventListener('keydown', handler);
   }, [hotkey?.key, hotkey?.meta, hotkey?.shift, hotkey?.alt, open, setOpen, hotkey]);
 
-  // Greeting visibility: respect dismissal, hideOnOpen, and the actual open state.
   const greetingOpen = !!greetingConfig
     && !dismissed
     && (greetingConfig.hideOnOpen === false || !open);
@@ -242,22 +254,14 @@ export function ChatLauncher({
 
   const handleGreetingClick = () => {
     setOpen(true);
-    // Tap-to-open also clears the proactive bubble — pushing it again on
-    // the same visit would feel spammy. Persisted dismissal honours the
-    // storage key so it doesn't reappear after navigation either.
     setDismissed(true);
     writeDismissed(greetingConfig?.dismissStorageKey);
   };
 
-  // Mark-as-read also fires when the chat opens through any path (FAB,
-  // hotkey, controlled state) — symmetric with click-to-open via the
-  // preview itself.
   useEffect(() => {
     if (open && unreadMessage) onMarkRead?.();
   }, [open, unreadMessage, onMarkRead]);
 
-  // Unread preview replaces the greeting when there's a real inbound
-  // message to surface — same anchor, more relevant content.
   const unreadOpen = !open && !!unreadMessage;
   const handleUnreadClick = () => {
     setOpen(true);
@@ -267,12 +271,40 @@ export function ChatLauncher({
     onMarkRead?.();
   };
 
-  // Auto-derive a "1" badge from unread when the host didn't set one.
   const resolvedFab = unreadMessage && fab?.badge === undefined
     ? { ...fab, badge: 1 }
     : fab;
 
-  return (
+  // Whether the audio prop wires up any actual sound. Used as the
+  // default for `headerSlots.audio` — no point auto-injecting the
+  // toggle when there's nothing to mute.
+  const audioConfigured = useMemo<boolean>(() => {
+    if (!audio) return false;
+    if (audio.silenced) return false;
+    const sounds = audio.sounds;
+    // `useChatAudio` falls back to DEFAULT_CHAT_SOUNDS when `sounds` is
+    // undefined and `silenced` is false. Treat that as "configured" too.
+    if (sounds === undefined) return true;
+    return Object.values(sounds).some(
+      (v) => typeof v === 'string' && v.length > 0,
+    );
+  }, [audio]);
+
+  const resolvedSlots = useMemo(
+    () => resolveHeaderSlots(headerSlots, audioConfigured),
+    [headerSlots, audioConfigured],
+  );
+
+  const hasAnySlot =
+    resolvedSlots.audio ||
+    resolvedSlots.modeToggle !== null ||
+    resolvedSlots.languagePicker !== null ||
+    resolvedSlots.reset !== null ||
+    resolvedSlots.custom !== null;
+
+  const ambient = useChatContextOptional();
+
+  const body = (
     <>
       <ChatFAB {...resolvedFab} onClick={toggleOpen} />
       {unreadMessage ? (
@@ -302,14 +334,7 @@ export function ChatLauncher({
         open={open}
         onClose={() => setOpen(false)}
         headerActions={
-          (audio && !audio.isSilent && !hideAudioToggle) || dock?.headerActions ? (
-            <>
-              {dock?.headerActions}
-              {audio && !audio.isSilent && !hideAudioToggle ? (
-                <ChatHeaderAudioToggle muted={audio.muted} onToggle={audio.toggleMute} />
-              ) : null}
-            </>
-          ) : undefined
+          hasAnySlot ? <HeaderSlotsRenderer slots={resolvedSlots} /> : undefined
         }
       >
         <div ref={dockContentRef} className="flex h-full min-h-0 min-w-0 flex-col">
@@ -318,4 +343,33 @@ export function ChatLauncher({
       </ChatDock>
     </>
   );
+
+  if (ambient) {
+    // Already inside a ChatProvider — reuse it. Provider-level props
+    // (transport / config / audio / debug / onBeforeSend) are ignored
+    // because they belong to the upstream provider.
+    return body;
+  }
+
+  if (!transport) {
+    // No ambient provider and no transport — programmer error.
+    throw new Error(
+      '<ChatLauncher> requires `transport` when mounted outside a <ChatProvider>.',
+    );
+  }
+
+  return (
+    <ChatProvider
+      transport={transport}
+      config={config}
+      initialSessionId={initialSessionId}
+      autoCreateSession={autoCreateSession}
+      streaming={streaming}
+      audio={audio}
+      debug={debug}
+      onBeforeSend={onBeforeSend}
+    >
+      {body}
+    </ChatProvider>
+  );
 }

package/src/tools/Chat/launcher/HeaderSlots.tsx

@@ -0,0 +1,93 @@
+'use client';
+
+import { Fragment } from 'react';
+
+import { useChatContext } from '../context';
+import { useChatDockPrefs } from '../hooks/useChatDockPrefs';
+
+import { ChatHeaderAudioToggle } from './ChatHeaderAudioToggle';
+import { ChatHeaderLanguageButton } from './ChatHeaderLanguageButton';
+import { ChatHeaderModeToggle } from './ChatHeaderModeToggle';
+import { ChatHeaderResetButton } from './ChatHeaderResetButton';
+import type { ResolvedChatHeaderSlots } from './types';
+
+export interface HeaderSlotsRendererProps {
+  slots: ResolvedChatHeaderSlots;
+}
+
+/**
+ * Renders the declarative `headerSlots` config inside the
+ * `<ChatProvider>` mounted by `<ChatLauncher>`.
+ *
+ * Order (left → right, before the close icon):
+ *   custom · languagePicker · modeToggle · audio · reset
+ */
+export function HeaderSlotsRenderer({ slots }: HeaderSlotsRendererProps) {
+  const ctx = useChatContext();
+  return (
+    <>
+      {slots.custom ? <Fragment>{slots.custom(ctx)}</Fragment> : null}
+      {slots.languagePicker ? (
+        <ChatHeaderLanguageButton
+          allowedTags={slots.languagePicker.allowedTags}
+          ariaLabel={slots.languagePicker.ariaLabel}
+          hideFallbackIcon={slots.languagePicker.hideFallbackIcon}
+        />
+      ) : null}
+      {slots.modeToggle ? <ModeToggleSlot slot={slots.modeToggle} /> : null}
+      {slots.audio && !ctx.audio.isSilent ? (
+        <ChatHeaderAudioToggle
+          muted={ctx.audio.muted}
+          onToggle={ctx.audio.toggleMute}
+        />
+      ) : null}
+      {slots.reset && ctx.sessionId ? <ResetSlot slot={slots.reset} /> : null}
+    </>
+  );
+}
+
+function ModeToggleSlot({
+  slot,
+}: {
+  slot: NonNullable<ResolvedChatHeaderSlots['modeToggle']>;
+}) {
+  const prefs = useChatDockPrefs({
+    storageKey: slot.persistAs,
+    defaults: slot.defaults,
+  });
+  return (
+    <ChatHeaderModeToggle
+      mode={prefs.mode}
+      onToggle={prefs.toggleMode}
+      forceVisible={slot.forceVisible ?? true}
+      expandLabel={slot.expandLabel}
+      collapseLabel={slot.collapseLabel}
+    />
+  );
+}
+
+function ResetSlot({
+  slot,
+}: {
+  slot: NonNullable<ResolvedChatHeaderSlots['reset']>;
+}) {
+  const ctx = useChatContext();
+  const handleSuccess = () => {
+    if (slot.onSuccess) {
+      slot.onSuccess(ctx);
+      return;
+    }
+    ctx.clearMessages();
+  };
+  return (
+    <ChatHeaderResetButton
+      onReset={slot.onReset}
+      onSuccess={handleSuccess}
+      onError={slot.onError}
+      confirm={slot.confirm}
+      confirmTitle={slot.confirmTitle}
+      confirmMessage={slot.confirmMessage}
+      ariaLabel={slot.ariaLabel}
+    />
+  );
+}

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

@@ -38,6 +38,12 @@ export {
   type ChatLauncherHotkey,
   type ChatLauncherGreeting,
 } from './ChatLauncher';
+export type {
+  ChatHeaderSlots,
+  ChatHeaderResetSlot,
+  ChatHeaderLanguageSlot,
+  ChatHeaderModeToggleSlot,
+} from './types';
 export { ChatGreeting, type ChatGreetingProps } from './ChatGreeting';
 export {
   ChatUnreadPreview,