@djangocfg/ui-tools 2.1.381 → 2.1.383

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

@@ -0,0 +1,321 @@
+'use client';
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+import type { ReactNode } from 'react';
+
+import { useHotkey } from '@djangocfg/ui-core/hooks';
+
+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';
+
+export interface ChatLauncherHotkey {
+  /** Key (case-sensitive single char or named like 'Escape'). */
+  key: string;
+  /** Require Cmd (mac) or Ctrl (other). */
+  meta?: boolean;
+  /** Require Shift. */
+  shift?: boolean;
+  /** Require Alt. */
+  alt?: boolean;
+}
+
+export interface ChatLauncherGreeting
+  extends Omit<ChatGreetingProps, 'open' | 'onClick' | 'onDismiss' | 'position' | 'fabOffset' | 'children'> {
+  /** Greeting body — string for the default style, or any ReactNode. */
+  content: ReactNode;
+  /** Persistence key for "user dismissed this greeting" in `localStorage`. Pass `null` to disable persistence. @default null */
+  dismissStorageKey?: string | null;
+  /** Hide the greeting once the user opens the chat. @default true */
+  hideOnOpen?: boolean;
+}
+
+export interface ChatLauncherProps {
+  /** Dock contents — typically a `<Chat>` instance. */
+  children: ReactNode;
+  /** FAB customization (icon, position, label, pulse, badge, tooltip, variant, size). */
+  fab?: Omit<ChatFABProps, 'onClick'>;
+  /** Dock customization (size, title, position, transition, mobileFullscreen). */
+  dock?: Omit<ChatDockProps, 'open' | 'onClose' | 'children'>;
+  /**
+   * 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.
+   */
+  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`). */
+  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
+   */
+  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
+   */
+  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>`.
+   */
+  unreadMessage?: ChatMessage | null;
+  /**
+   * Called when the user opens the chat via FAB/preview/hotkey or
+   * dismisses the preview with ×. Wire to `useChatUnread().markRead`.
+   */
+  onMarkRead?: () => void;
+  /**
+   * Customize the unread bubble (`truncate`, `dismissLabel`, …).
+   * `open`/`message`/`onClick`/`onDismiss`/`position`/`fabOffset` are
+   * wired automatically.
+   */
+  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 {
+  if (!storageKey) return false;
+  if (typeof window === 'undefined') return false;
+  try {
+    return window.localStorage.getItem(storageKey) === '1';
+  } catch {
+    return false;
+  }
+}
+
+function writeDismissed(storageKey: string | null | undefined): void {
+  if (!storageKey) return;
+  if (typeof window === 'undefined') return;
+  try {
+    window.localStorage.setItem(storageKey, '1');
+  } catch {
+    // private mode / storage full — silently ignore
+  }
+}
+
+/**
+ * Floating chat launcher = 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.
+ */
+export function ChatLauncher({
+  children,
+  fab,
+  dock,
+  greeting,
+  hotkey,
+  defaultOpen = false,
+  open: controlledOpen,
+  onOpenChange,
+  autoFocusComposerOnOpen = true,
+  closeOnEscape = true,
+  unreadMessage,
+  onMarkRead,
+  unreadPreview,
+  audio,
+  hideAudioToggle = false,
+}: ChatLauncherProps) {
+  const [uncontrolledOpen, setUncontrolledOpen] = useState(defaultOpen);
+  const isControlled = controlledOpen !== undefined;
+  const open = isControlled ? controlledOpen : uncontrolledOpen;
+  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(() => {
+      const root = dockContentRef.current;
+      if (!root) return;
+      const target = root.querySelector<HTMLElement>(
+        'textarea:not([disabled]):not([readonly]), input[type="text"]:not([disabled]):not([readonly])',
+      );
+      target?.focus();
+    }, 120);
+    return () => clearTimeout(t);
+  }, [open, autoFocusComposerOnOpen]);
+
+  const setOpen = useCallback(
+    (next: boolean) => {
+      if (!isControlled) setUncontrolledOpen(next);
+      onOpenChange?.(next);
+    },
+    [isControlled, onOpenChange],
+  );
+  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) => {
+      const target = (e?.target as HTMLElement | null) ?? null;
+      const inEditable =
+        !!target &&
+        (target.matches?.('input, textarea, [contenteditable="true"]') ?? false);
+      if (inEditable) {
+        target.blur();
+        return;
+      }
+      setOpen(false);
+    },
+    { enabled: closeOnEscape && open },
+  );
+
+  // Normalize greeting prop.
+  const greetingConfig: ChatLauncherGreeting | null =
+    greeting === undefined
+      ? null
+      : typeof greeting === 'string'
+        ? { content: greeting }
+        : greeting;
+
+  const [dismissed, setDismissed] = useState(() =>
+    readDismissed(greetingConfig?.dismissStorageKey),
+  );
+
+  // Hotkey.
+  useEffect(() => {
+    if (!hotkey) return;
+    const handler = (e: KeyboardEvent) => {
+      const metaOk = hotkey.meta ? e.metaKey || e.ctrlKey : !e.metaKey && !e.ctrlKey;
+      const shiftOk = hotkey.shift ? e.shiftKey : !e.shiftKey;
+      const altOk = hotkey.alt ? e.altKey : !e.altKey;
+      if (!metaOk || !shiftOk || !altOk) return;
+      if (e.key !== hotkey.key) return;
+      e.preventDefault();
+      setOpen(!open);
+    };
+    window.addEventListener('keydown', handler);
+    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);
+
+  const fabPosition: ChatFABPosition = fab?.position ?? 'bottom-right';
+  const fabOffset = fab?.offset ?? 24;
+
+  const handleGreetingDismiss = () => {
+    setDismissed(true);
+    writeDismissed(greetingConfig?.dismissStorageKey);
+  };
+
+  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);
+    onMarkRead?.();
+  };
+  const handleUnreadDismiss = () => {
+    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 (
+    <>
+      <ChatFAB {...resolvedFab} onClick={toggleOpen} />
+      {unreadMessage ? (
+        <ChatUnreadPreview
+          {...unreadPreview}
+          open={unreadOpen}
+          message={unreadMessage}
+          onClick={handleUnreadClick}
+          onDismiss={handleUnreadDismiss}
+          position={fabPosition}
+          fabOffset={fabOffset}
+        />
+      ) : greetingConfig ? (
+        <ChatGreeting
+          {...greetingConfig}
+          open={greetingOpen}
+          onClick={handleGreetingClick}
+          onDismiss={handleGreetingDismiss}
+          position={fabPosition}
+          fabOffset={fabOffset}
+        >
+          {greetingConfig.content}
+        </ChatGreeting>
+      ) : null}
+      <ChatDock
+        {...dock}
+        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
+        }
+      >
+        <div ref={dockContentRef} className="flex h-full min-h-0 min-w-0 flex-col">
+          {children}
+        </div>
+      </ChatDock>
+    </>
+  );
+}

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

@@ -0,0 +1,197 @@
+'use client';
+
+import { X } from 'lucide-react';
+import type { CSSProperties, ReactNode } from 'react';
+
+import { Avatar, AvatarFallback, AvatarImage } from '@djangocfg/ui-core/components';
+import { cn } from '@djangocfg/ui-core/lib';
+
+import type { ChatMessage, ChatPersona } from '../types';
+import type { ChatFABPosition } from './ChatFAB';
+import { useChatPresence } from './useChatPresence';
+
+export interface ChatUnreadPreviewProps {
+  /** Controlled — usually `!dockOpen && !!message`. */
+  open: boolean;
+  /** Inbound message to preview. `null` hides the bubble. */
+  message: ChatMessage | null;
+  /** Tap → open chat + mark read. */
+  onClick?: () => void;
+  /** × → mark read without opening. */
+  onDismiss?: () => void;
+  /** Anchor corner — match the FAB so the bubble sits above it. @default 'bottom-right' */
+  position?: ChatFABPosition;
+  /** Horizontal offset from screen edge, matches the FAB. @default 24 */
+  fabOffset?: number;
+  /** Vertical clearance above/below the FAB. @default 96 */
+  fabClearance?: number;
+  /** Lines of body text before ellipsis. @default 2 */
+  truncate?: number;
+  /** z-index. @default 9998 */
+  zIndex?: number;
+  /** Render in-place (stories / previews). @default false */
+  inline?: boolean;
+  /** Override classes on the bubble. */
+  className?: string;
+  /** Override styles on the bubble. */
+  style?: CSSProperties;
+  /** ARIA label for the dismiss button. @default 'Mark as read' */
+  dismissLabel?: string;
+  /** Override the avatar — defaults to derived from `message.sender`. */
+  avatar?: ReactNode;
+  /** Override the sender label — defaults to `message.sender?.name`. */
+  senderName?: string;
+}
+
+const TIME_FORMAT = new Intl.DateTimeFormat(undefined, {
+  hour: '2-digit',
+  minute: '2-digit',
+});
+
+function anchorStyle(
+  position: ChatFABPosition,
+  fabOffset: number,
+  fabClearance: number,
+): CSSProperties {
+  const [vert, horiz] = position.split('-') as ['bottom' | 'top', 'right' | 'left'];
+  return { [vert]: fabClearance, [horiz]: fabOffset } as CSSProperties;
+}
+
+function originClass(position: ChatFABPosition): string {
+  if (position === 'bottom-right') return 'origin-bottom-right';
+  if (position === 'bottom-left') return 'origin-bottom-left';
+  if (position === 'top-right') return 'origin-top-right';
+  return 'origin-top-left';
+}
+
+function deriveAvatar(persona?: ChatPersona, name?: string): ReactNode {
+  const initials =
+    persona?.initials ??
+    (name ?? persona?.name ?? '?')
+      .split(/\s+/)
+      .map((p) => p[0])
+      .filter(Boolean)
+      .slice(0, 2)
+      .join('')
+      .toUpperCase();
+  return (
+    <Avatar className="h-9 w-9">
+      {persona?.avatarUrl ? <AvatarImage src={persona.avatarUrl} /> : null}
+      <AvatarFallback>{initials || '?'}</AvatarFallback>
+    </Avatar>
+  );
+}
+
+/**
+ * Push-notification bubble next to the chat FAB.
+ *
+ * Shows the last inbound message while the chat is closed —
+ * Intercom / LiveChat-style. Tap → open chat (host wires `onClick`).
+ * Dismiss × → keep chat closed but stop nagging.
+ *
+ * Pair with `useChatUnread()` (inside `<ChatProvider>`) for state.
+ */
+export function ChatUnreadPreview({
+  open,
+  message,
+  onClick,
+  onDismiss,
+  position = 'bottom-right',
+  fabOffset = 24,
+  fabClearance = 96,
+  truncate = 2,
+  zIndex = 9998,
+  inline = false,
+  className,
+  style,
+  dismissLabel = 'Mark as read',
+  avatar,
+  senderName,
+}: ChatUnreadPreviewProps) {
+  const shouldShow = open && !!message;
+  const phase = useChatPresence(shouldShow, 200);
+  if (phase === 'hidden' || !message) return null;
+
+  const animating = phase === 'entering' || phase === 'leaving';
+  const clickable = !!onClick;
+  const displayName = senderName ?? message.sender?.name ?? 'New message';
+  const stamp = TIME_FORMAT.format(new Date(message.createdAt));
+
+  return (
+    <div
+      role={clickable ? 'button' : 'status'}
+      aria-live="polite"
+      tabIndex={clickable ? 0 : -1}
+      onClick={clickable ? onClick : undefined}
+      onKeyDown={
+        clickable
+          ? (e) => {
+              if (e.key === 'Enter' || e.key === ' ') {
+                e.preventDefault();
+                onClick?.();
+              }
+            }
+          : undefined
+      }
+      className={cn(
+        inline ? 'relative inline-flex' : 'fixed',
+        'flex items-start gap-2.5 max-w-[300px]',
+        'rounded-2xl border border-border bg-popover text-popover-foreground',
+        'px-3.5 py-2.5 shadow-2xl transition-all duration-200 ease-out',
+        clickable &&
+          'cursor-pointer hover:bg-accent/40 focus:outline-none focus-visible:ring-2 focus-visible:ring-ring',
+        originClass(position),
+        animating ? 'opacity-0 scale-95 translate-y-1' : 'opacity-100 scale-100 translate-y-0',
+        className,
+      )}
+      style={{
+        ...(inline ? {} : anchorStyle(position, fabOffset, fabClearance)),
+        ...(inline ? {} : { zIndex }),
+        pointerEvents: phase === 'visible' ? 'auto' : 'none',
+        ...style,
+      }}
+    >
+      <div className="mt-0.5 shrink-0">
+        {avatar ?? deriveAvatar(message.sender, displayName)}
+      </div>
+
+      <div className="min-w-0 flex-1 text-sm leading-snug">
+        <div className="flex items-baseline justify-between gap-2">
+          <div className="truncate text-[12px] font-semibold text-foreground">
+            {displayName}
+          </div>
+          <div className="shrink-0 text-[10px] text-muted-foreground">{stamp}</div>
+        </div>
+        <div
+          className="text-foreground/90 mt-0.5 break-words"
+          style={{
+            display: '-webkit-box',
+            WebkitLineClamp: truncate,
+            WebkitBoxOrient: 'vertical',
+            overflow: 'hidden',
+          }}
+        >
+          {message.content}
+        </div>
+      </div>
+
+      {onDismiss ? (
+        <button
+          type="button"
+          aria-label={dismissLabel}
+          onClick={(e) => {
+            e.stopPropagation();
+            onDismiss();
+          }}
+          className={cn(
+            '-mr-1 -mt-1 flex h-6 w-6 shrink-0 items-center justify-center rounded-full',
+            'text-muted-foreground transition-colors hover:bg-accent hover:text-foreground',
+            'focus:outline-none focus-visible:ring-2 focus-visible:ring-ring',
+          )}
+        >
+          <X className="h-3.5 w-3.5" />
+        </button>
+      ) : null}
+    </div>
+  );
+}

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

@@ -0,0 +1,46 @@
+export {
+  ChatFAB,
+  type ChatFABProps,
+  type ChatFABPosition,
+  type ChatFABVariant,
+  type ChatFABSize,
+} from './ChatFAB';
+export {
+  ChatDock,
+  type ChatDockProps,
+  type ChatDockMode,
+  type ChatDockSide,
+} from './ChatDock';
+export { ChatHeader, type ChatHeaderProps } from './ChatHeader';
+export {
+  ChatHeaderActionButton,
+  type ChatHeaderActionButtonProps,
+} from './ChatHeaderActionButton';
+export {
+  ChatHeaderModeToggle,
+  type ChatHeaderModeToggleProps,
+} from './ChatHeaderModeToggle';
+export {
+  ChatHeaderAudioToggle,
+  type ChatHeaderAudioToggleProps,
+} from './ChatHeaderAudioToggle';
+export {
+  ChatHeaderResetButton,
+  type ChatHeaderResetButtonProps,
+} from './ChatHeaderResetButton';
+export {
+  ChatHeaderLanguageButton,
+  type ChatHeaderLanguageButtonProps,
+} from './ChatHeaderLanguageButton';
+export {
+  ChatLauncher,
+  type ChatLauncherProps,
+  type ChatLauncherHotkey,
+  type ChatLauncherGreeting,
+} from './ChatLauncher';
+export { ChatGreeting, type ChatGreetingProps } from './ChatGreeting';
+export {
+  ChatUnreadPreview,
+  type ChatUnreadPreviewProps,
+} from './ChatUnreadPreview';
+export { useChatPresence, type ChatPresencePhase } from './useChatPresence';

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

@@ -0,0 +1,44 @@
+'use client';
+
+import { useEffect, useRef, useState } from 'react';
+
+export type ChatPresencePhase = 'hidden' | 'entering' | 'visible' | 'leaving';
+
+/**
+ * Presence state machine for floating popovers.
+ *
+ * Drives a four-phase lifecycle so enter/leave CSS transitions actually fire:
+ *
+ *   hidden → entering (mount, transition class starts) → visible
+ *   visible → leaving (transition runs) → hidden (unmount)
+ *
+ * Mounting in `entering` and ticking to `visible` on the next paint is what
+ * lets transition classes animate. Without it the element appears already
+ * at its final state and CSS transitions never observe a change.
+ *
+ * @param open - controlled open state
+ * @param exitDurationMs - how long the leave transition runs; should match CSS
+ */
+export function useChatPresence(open: boolean, exitDurationMs = 200): ChatPresencePhase {
+  const [phase, setPhase] = useState<ChatPresencePhase>('hidden');
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  useEffect(() => {
+    if (timerRef.current) clearTimeout(timerRef.current);
+
+    if (open) {
+      setPhase('entering');
+      // One paint later: switch to 'visible' so the CSS transition runs.
+      timerRef.current = setTimeout(() => setPhase('visible'), 16);
+    } else {
+      setPhase('leaving');
+      timerRef.current = setTimeout(() => setPhase('hidden'), exitDurationMs);
+    }
+
+    return () => {
+      if (timerRef.current) clearTimeout(timerRef.current);
+    };
+  }, [open, exitDurationMs]);
+
+  return phase;
+}

package/src/tools/Chat/styles/bubbleTokens.ts

@@ -0,0 +1,71 @@
+/**
+ * Chat color tokens — single source of truth.
+ *
+ * Every role-conditional class for chat surfaces lives here.
+ * Components consume via `useChatBubbleStyles` / `useChatRoleStyles`,
+ * never via raw Tailwind literals.
+ *
+ * Why centralize:
+ *   1. One file to edit when the design system changes (e.g. light-theme
+ *      contrast tweaks, palette swap).
+ *   2. Eliminates the "first-token-on-bg-primary-was-text-white" class
+ *      of bugs where each call site picks its own foreground.
+ *   3. Lets us snapshot-test color decisions later.
+ */
+
+/** Bubble surface classes (background + text), keyed by message state. */
+export const BUBBLE_SURFACE = {
+  /** User-authored bubble — solid brand color. */
+  user: 'bg-primary text-primary-foreground rounded-tr-md',
+  /** Assistant bubble in normal state — neutral muted surface. */
+  assistant: 'bg-muted text-foreground rounded-tl-md',
+  /** Assistant bubble when the turn failed — destructive tint. */
+  error: 'bg-destructive/10 text-destructive rounded-tl-md border border-destructive/30',
+} as const;
+
+/**
+ * Anchor (link) classes for markdown content rendered inside a bubble.
+ *
+ * On `bg-primary` the link MUST stay legible against the cyan/brand fill —
+ * `text-primary-foreground` matches the bubble's foreground token, so
+ * contrast tracks the design system automatically.
+ *
+ * On the neutral assistant bubble we keep the brand-primary color so links
+ * still pop without competing with the body text.
+ */
+export const ANCHOR = {
+  user:
+    'text-primary-foreground underline decoration-primary-foreground/60 underline-offset-2 ' +
+    'hover:decoration-primary-foreground transition-colors break-all',
+  assistant: 'text-primary underline hover:text-primary/80 transition-colors break-all',
+} as const;
+
+/** Inline secondary action (e.g. "Show more / less"). Same logic as anchors. */
+export const TOGGLE = {
+  user: 'text-primary-foreground/80 hover:text-primary-foreground',
+  assistant: 'text-primary hover:text-primary/80',
+} as const;
+
+/** Destructive surface — used by ErrorBanner and the delete action. */
+export const DESTRUCTIVE_SURFACE = {
+  /** Banner / card variant: border + tint + text. */
+  banner:
+    'border border-destructive/40 bg-destructive/10 text-destructive',
+  /** Subtle hover for destructive buttons inside the banner / menu. */
+  hover: 'hover:bg-destructive/15',
+  /** Strong-hover variant (e.g. trash overlay on attachments). */
+  hoverStrong:
+    'hover:bg-destructive hover:text-destructive-foreground',
+  /** Inline destructive text utility. */
+  text: 'text-destructive',
+  /** Hover style for menu items that delete data. */
+  menuItem:
+    'text-destructive focus:text-destructive hover:bg-destructive/15 hover:text-destructive',
+} as const;
+
+/** Tool-call result text. */
+export const TOOL_CALL = {
+  errorText: 'text-destructive',
+} as const;
+
+export type ChatBubbleSurface = keyof typeof BUBBLE_SURFACE;

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

@@ -0,0 +1,16 @@
+export {
+  BUBBLE_SURFACE,
+  ANCHOR,
+  TOGGLE,
+  DESTRUCTIVE_SURFACE,
+  TOOL_CALL,
+  type ChatBubbleSurface,
+} from './bubbleTokens';
+export {
+  useChatBubbleStyles,
+  useChatRoleStyles,
+  useChatDestructiveStyles,
+  type ChatBubbleStyles,
+  type ChatRoleStyles,
+  type ChatDestructiveStyles,
+} from './useChatStyles';