@djangocfg/ui-tools 2.1.381 → 2.1.382

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

@@ -0,0 +1,87 @@
+'use client';
+
+import { forwardRef } from 'react';
+import type { ButtonHTMLAttributes, ReactNode } from 'react';
+
+import { cn } from '@djangocfg/ui-core/lib';
+
+export interface ChatHeaderActionButtonProps
+  extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'children'> {
+  /** Icon (required). */
+  icon: ReactNode;
+  /** Accessible label + native tooltip. */
+  ariaLabel: string;
+  /** Optional unread / status badge — small number on top-right. */
+  badge?: number;
+  /** Mark as destructive — uses destructive hover tokens. */
+  destructive?: boolean;
+  /** Optional visual loading state (e.g. while reset is in flight). */
+  loading?: boolean;
+}
+
+/**
+ * Compact icon button for the chat header actions slot.
+ *
+ * Standard chrome: 28×28 ghost button, hover bg-accent, focus ring, optional
+ * destructive variant, optional numeric badge for unread / pending.
+ *
+ * @example
+ * ```tsx
+ * <ChatHeader
+ *   title="Assistant"
+ *   onClose={close}
+ *   actions={
+ *     <>
+ *       <ChatHeaderActionButton
+ *         icon={<RotateCcw className="h-3.5 w-3.5" />}
+ *         ariaLabel="Clear context"
+ *         onClick={handleReset}
+ *         loading={isResetting}
+ *       />
+ *       <ChatHeaderActionButton
+ *         icon={<Settings className="h-3.5 w-3.5" />}
+ *         ariaLabel="Settings"
+ *         onClick={openSettings}
+ *       />
+ *     </>
+ *   }
+ * />
+ * ```
+ */
+export const ChatHeaderActionButton = forwardRef<HTMLButtonElement, ChatHeaderActionButtonProps>(
+  function ChatHeaderActionButton(
+    { icon, ariaLabel, badge, destructive, loading, disabled, className, ...rest },
+    ref,
+  ) {
+    return (
+      <button
+        ref={ref}
+        type="button"
+        aria-label={ariaLabel}
+        title={ariaLabel}
+        disabled={disabled || loading}
+        className={cn(
+          'relative inline-flex h-7 w-7 items-center justify-center rounded-md',
+          'text-muted-foreground transition-colors',
+          'hover:bg-accent hover:text-foreground',
+          'focus:outline-none focus-visible:ring-2 focus-visible:ring-ring',
+          'disabled:opacity-50 disabled:cursor-not-allowed',
+          destructive && 'hover:bg-destructive/15 hover:text-destructive',
+          loading && 'animate-pulse',
+          className,
+        )}
+        {...rest}
+      >
+        {icon}
+        {badge !== undefined && (
+          <span
+            aria-hidden="true"
+            className="absolute -right-0.5 -top-0.5 inline-flex min-w-[14px] h-[14px] items-center justify-center rounded-full bg-destructive px-1 text-[9px] font-semibold leading-none text-destructive-foreground ring-2 ring-background"
+          >
+            {badge > 9 ? '9+' : badge}
+          </span>
+        )}
+      </button>
+    );
+  },
+);

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

@@ -0,0 +1,47 @@
+'use client';
+
+import { Volume2, VolumeX } from 'lucide-react';
+
+import { ChatHeaderActionButton } from './ChatHeaderActionButton';
+
+export interface ChatHeaderAudioToggleProps {
+  /** Current muted state. */
+  muted: boolean;
+  /** Toggle handler. Wire to `useChatAudio().setMuted` or `toggleMute`. */
+  onToggle: () => void;
+  /** Override tooltip label for muted → unmuted. */
+  unmuteLabel?: string;
+  /** Override tooltip label for unmuted → muted. */
+  muteLabel?: string;
+}
+
+/**
+ * Mute / unmute notification sounds. Drop into a `<ChatHeader>` actions
+ * slot or into `<ChatDock headerActions>`.
+ *
+ * @example
+ * ```tsx
+ * const audio = useChatAudio({ sounds: {...} });
+ * <ChatHeaderAudioToggle muted={audio.muted} onToggle={() => audio.setMuted(!audio.muted)} />
+ * ```
+ */
+export function ChatHeaderAudioToggle({
+  muted,
+  onToggle,
+  unmuteLabel = 'Unmute notifications',
+  muteLabel = 'Mute notifications',
+}: ChatHeaderAudioToggleProps) {
+  return (
+    <ChatHeaderActionButton
+      icon={
+        muted ? (
+          <VolumeX className="h-3.5 w-3.5" />
+        ) : (
+          <Volume2 className="h-3.5 w-3.5" />
+        )
+      }
+      ariaLabel={muted ? unmuteLabel : muteLabel}
+      onClick={onToggle}
+    />
+  );
+}

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

@@ -0,0 +1,179 @@
+'use client';
+
+import type * as React from 'react';
+import { useMemo } from 'react';
+import { Globe } from 'lucide-react';
+
+import {
+  Combobox,
+  type ComboboxOption,
+  Flag,
+} from '@djangocfg/ui-core/components';
+import { cn } from '@djangocfg/ui-core/lib';
+
+import { findSpeechLanguage } from '../../SpeechRecognition';
+
+import {
+  WEB_SPEECH_LANGUAGES,
+  countryFromTag,
+  useResolvedLanguage,
+  useSpeechPrefs,
+} from '../../SpeechRecognition';
+
+export interface ChatHeaderLanguageButtonProps {
+  /** Override aria-label. Default "Speech language". */
+  ariaLabel?: string;
+  /**
+   * Subset of BCP-47 tags to offer. Default: every entry from the
+   * Web Speech catalogue (~66 tags incl. regional variants). Pass a
+   * tighter list when your backend STT only supports a subset.
+   */
+  allowedTags?: string[];
+  /** Hide the globe-fallback icon when no flag resolves. */
+  hideFallbackIcon?: boolean;
+  className?: string;
+}
+
+/**
+ * Compact flag-button language picker for the chat header. Built on
+ * top of the ui-core `<Combobox>` — searchable autocomplete with
+ * flags, ~66 BCP-47 tags from the official Chrome Web Speech demo, and
+ * a custom 28×28 trigger via `renderTrigger`.
+ *
+ * The selection persists into `useSpeechPrefs` (zustand+localStorage)
+ * so `useSpeechRecognition` picks it up as the second-priority resolver
+ * value (above i18n locale, below an explicit `language` prop).
+ */
+export function ChatHeaderLanguageButton({
+  ariaLabel = 'Speech language',
+  allowedTags,
+  hideFallbackIcon,
+  className,
+}: ChatHeaderLanguageButtonProps): React.ReactElement {
+  const prefs = useSpeechPrefs();
+  const active = useResolvedLanguage();
+
+  // Flatten every dialect into one Combobox option. Display name keeps
+  // the native language label; we stash the English aliases + BCP-47
+  // tag + region in `description` purely as a hidden search index.
+  // (We intentionally hide the description from the rendered row in
+  // `renderOption` — it would just clutter the dropdown.)
+  const options = useMemo<ComboboxOption[]>(() => {
+    const allow = allowedTags ? new Set(allowedTags) : null;
+    const out: ComboboxOption[] = [];
+    for (const lang of WEB_SPEECH_LANGUAGES) {
+      for (const d of lang.dialects) {
+        if (allow && !allow.has(d.code)) continue;
+        out.push({
+          value: d.code,
+          // "Русский" / "Español — Argentina" / "English — United States"
+          label:
+            lang.dialects.length === 1
+              ? lang.name
+              : `${lang.name} — ${d.region}`,
+          // Search-only index: English name, BCP-47 tag, ISO, region.
+          // Lets users type "russian" / "ru-RU" / "ru" / "argentina"
+          // and still find the row regardless of native script.
+          description: `${lang.englishName} ${d.code} ${lang.iso} ${d.region}`.toLowerCase(),
+        });
+      }
+    }
+    return out;
+  }, [allowedTags]);
+
+  return (
+    <Combobox
+      options={options}
+      value={prefs.language ?? active}
+      onValueChange={(v) => prefs.setLanguage(v || null)}
+      placeholder={ariaLabel}
+      searchPlaceholder="Search language…"
+      filterFunction={(opt, search) => {
+        const s = search.toLowerCase();
+        // Match label (native script), value (BCP-47), and our packed
+        // search index in description (English name + tag + region).
+        return (
+          opt.label.toLowerCase().includes(s) ||
+          opt.value.toLowerCase().includes(s) ||
+          (opt.description?.includes(s) ?? false)
+        );
+      }}
+      // Popover width follows the trigger by default (28px → narrow).
+      // Force a usable width and bump z-index above ChatDock (z-10000).
+      contentClassName="w-[280px]"
+      contentStyle={{ zIndex: 10001 }}
+      // Custom row: country flag + native language label + BCP-47 tag.
+      // ui-core Combobox default rendering only shows label/description
+      // — feeding the flag here keeps every list row instantly
+      // identifiable. Fallback to a neutral globe glyph when the tag
+      // has no resolvable country (rare: bn-BD etc. all have flags).
+      renderOption={(option) => {
+        const country = countryFromTag(option.value);
+        return (
+          <div className="flex min-w-0 flex-1 items-center gap-2">
+            {country ? (
+              <Flag
+                countryCode={country}
+                className="h-4 w-5 shrink-0 overflow-hidden rounded-[2px] border border-border/60 ring-1 ring-black/5"
+              />
+            ) : (
+              <Globe className="h-4 w-4 shrink-0 text-muted-foreground" aria-hidden />
+            )}
+            {/* Native-script label only — BCP-47 subtitle removed to
+                keep the dropdown visually quiet. Tag + region still
+                live in `description` for search. */}
+            <span className="truncate text-sm">{option.label}</span>
+          </div>
+        );
+      }}
+      // Compact icon-only trigger — replaces the default wide outline
+      // button. Stays the same 28×28 footprint as ChatHeaderActionButton
+      // siblings (audio toggle, reset).
+      renderTrigger={(selected, open) => {
+        const tag = selected?.value ?? active;
+        const country = countryFromTag(tag);
+        const found = findSpeechLanguage(tag);
+        // Tooltip copy: native language name + dialect region + tag.
+        // Falls back to just the tag for unknown / custom-engine codes.
+        const tooltipLabel = found
+          ? `${found.language.name}${
+              found.language.dialects.length > 1 ? ` — ${found.dialect.region}` : ''
+            } · ${tag}`
+          : tag;
+        // Note on tooltip: we intentionally use the native `title`
+        // attribute instead of `<Tooltip>` here. The button is already
+        // wrapped by Combobox's `PopoverTrigger asChild`, and stacking
+        // a second `TooltipTrigger asChild` on the same node makes
+        // Radix Slot merge two competing refs/handlers — popover click
+        // stops working. Native `title` is "good enough" for a single
+        // status label and ships zero extra DOM.
+        return (
+          <button
+            type="button"
+            aria-label={`${ariaLabel}: ${tooltipLabel}`}
+            aria-expanded={open}
+            title={tooltipLabel}
+            className={cn(
+              'inline-flex h-7 w-7 items-center justify-center rounded-md',
+              'text-muted-foreground transition-colors',
+              'hover:bg-accent hover:text-foreground',
+              'focus:outline-none focus-visible:ring-2 focus-visible:ring-ring',
+              className,
+            )}
+          >
+            {country ? (
+              <Flag
+                countryCode={country}
+                // Subtle hairline so flags with light edges (Japan,
+                // Switzerland, …) don't blend into the header bg.
+                className="h-4 w-5 overflow-hidden rounded-[2px] border border-border/60 ring-1 ring-black/5"
+              />
+            ) : hideFallbackIcon ? null : (
+              <Globe className="h-3.5 w-3.5" aria-hidden />
+            )}
+          </button>
+        );
+      }}
+    />
+  );
+}

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

@@ -0,0 +1,57 @@
+'use client';
+
+import { PanelRightOpen, PanelRightClose } from 'lucide-react';
+
+import { useIsTabletOrBelow } from '@djangocfg/ui-core/hooks';
+
+import { ChatHeaderActionButton } from './ChatHeaderActionButton';
+import type { ChatDockMode } from './ChatDock';
+
+export interface ChatHeaderModeToggleProps {
+  /** Current dock mode. */
+  mode: ChatDockMode;
+  /** Toggle handler. Wire to `useChatDockPrefs().toggleMode`. */
+  onToggle: () => void;
+  /** Override aria/tooltip label for popover→side. */
+  expandLabel?: string;
+  /** Override aria/tooltip label for side→popover. */
+  collapseLabel?: string;
+  /**
+   * Always render — useful for stories. By default the toggle hides itself on
+   * viewports below `lg` (1024px) since side mode falls back to popover there.
+   */
+  forceVisible?: boolean;
+}
+
+/**
+ * "Dock to side" / "back to popover" toggle.
+ *
+ * Side mode is desktop-only — on viewports below `lg` (1024px) `<ChatDock>`
+ * silently falls back to popover anyway, so the toggle has nothing to do
+ * and auto-hides. Pass `forceVisible` to override (e.g. in stories).
+ */
+export function ChatHeaderModeToggle({
+  mode,
+  onToggle,
+  expandLabel = 'Dock to side',
+  collapseLabel = 'Back to popover',
+  forceVisible = false,
+}: ChatHeaderModeToggleProps) {
+  const isBelowDesktop = useIsTabletOrBelow();
+  if (isBelowDesktop && !forceVisible) return null;
+
+  const isSide = mode === 'side';
+  return (
+    <ChatHeaderActionButton
+      icon={
+        isSide ? (
+          <PanelRightClose className="h-3.5 w-3.5" />
+        ) : (
+          <PanelRightOpen className="h-3.5 w-3.5" />
+        )
+      }
+      ariaLabel={isSide ? collapseLabel : expandLabel}
+      onClick={onToggle}
+    />
+  );
+}

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

@@ -0,0 +1,93 @@
+'use client';
+
+import { RotateCcw } from 'lucide-react';
+
+import { useChatReset } from '../hooks/useChatReset';
+import { ChatHeaderActionButton } from './ChatHeaderActionButton';
+
+export interface ChatHeaderResetButtonProps {
+  /**
+   * Backend reset call. Should resolve to `true` on success.
+   * Plugged into `useChatReset` for in-flight state.
+   */
+  onReset: () => Promise<boolean>;
+  /** Called after a successful reset (e.g. clear local messages, refetch). */
+  onSuccess?: () => void;
+  /** Called when reset fails (returned `false` or threw). */
+  onError?: (error?: unknown) => void;
+  /**
+   * Show a `window.dialog.confirm` before calling `onReset`. @default true
+   *
+   * Requires the host to mount `<DialogProvider>` from `@djangocfg/ui-core`
+   * — it installs the `window.dialog` API used here.
+   */
+  confirm?: boolean;
+  /** Confirm dialog title. */
+  confirmTitle?: string;
+  /** Confirm dialog message. */
+  confirmMessage?: string;
+  /** Override tooltip / aria label. */
+  ariaLabel?: string;
+}
+
+const DEFAULT_TITLE = 'Clear conversation?';
+const DEFAULT_MESSAGE =
+  'The assistant will forget this session and start a new one. This cannot be undone.';
+const DEFAULT_LABEL = 'Clear conversation';
+
+/**
+ * Standard chat-reset action: prompts the user via `window.dialog.confirm`,
+ * then runs the backend reset call through `useChatReset` so the button
+ * spins while it's in flight.
+ *
+ * @example
+ * ```tsx
+ * <ChatHeaderResetButton
+ *   onReset={api.clearChat}
+ *   onSuccess={() => chat.clearMessages()}
+ * />
+ * ```
+ */
+export function ChatHeaderResetButton({
+  onReset,
+  onSuccess,
+  onError,
+  confirm = true,
+  confirmTitle = DEFAULT_TITLE,
+  confirmMessage = DEFAULT_MESSAGE,
+  ariaLabel = DEFAULT_LABEL,
+}: ChatHeaderResetButtonProps) {
+  const { reset, isResetting } = useChatReset({ onReset, onSuccess, onError });
+
+  const handleClick = async () => {
+    if (confirm) {
+      const api = typeof window !== 'undefined' ? window.dialog : undefined;
+      if (api?.confirm) {
+        const ok = await api.confirm({
+          title: confirmTitle,
+          message: confirmMessage,
+          variant: 'destructive',
+          confirmText: 'Clear',
+          cancelText: 'Cancel',
+        });
+        if (!ok) return;
+      } else if (typeof window !== 'undefined' && typeof window.confirm === 'function') {
+        // Fallback to the native browser confirm when the dialog service
+        // isn't wired (e.g. host forgot to mount DialogProvider).
+        const ok = window.confirm(`${confirmTitle}\n\n${confirmMessage}`);
+        if (!ok) return;
+      }
+    }
+    await reset();
+  };
+
+  return (
+    <ChatHeaderActionButton
+      icon={<RotateCcw className="h-3.5 w-3.5" />}
+      ariaLabel={ariaLabel}
+      onClick={handleClick}
+      loading={isResetting}
+      destructive
+    />
+  );
+}