@djangocfg/ui-tools 2.1.381 → 2.1.382

package/src/tools/Chat/stories/07-audio-actions.story.tsx

@@ -0,0 +1,112 @@
+import { useMemo } from 'react';
+
+import { defineStory } from '@djangocfg/playground';
+import { DialogProvider } from '@djangocfg/ui-core/lib';
+
+import { ChatRoot } from '../components/ChatRoot';
+import { useChatAudio } from '../hooks/useChatAudio';
+import { ChatDock } from '../launcher/ChatDock';
+import { ChatHeaderAudioToggle } from '../launcher/ChatHeaderAudioToggle';
+import { ChatHeaderResetButton } from '../launcher/ChatHeaderResetButton';
+import { ChatLauncher } from '../launcher/ChatLauncher';
+import { SEED_BASIC, makeBasicTransport } from './shared';
+
+export default defineStory({
+  title: 'Tools/Chat/Audio & Actions',
+  component: ChatHeaderAudioToggle,
+  description:
+    'Header audio toggle (auto-injected when `audio` is passed) and header reset action with `window.dialog.confirm`. Wrap stories in `<DialogProvider>` so confirm prompts render.',
+});
+
+// ── Audio toggle ──────────────────────────────────────────────────────────
+
+function AudioLauncher() {
+  const transport = useMemo(() => makeBasicTransport(SEED_BASIC), []);
+  // A real notification sound — bundle your own assets in production.
+  // No `sounds` prop — uses bundled DEFAULT_CHAT_SOUNDS automatically.
+  const audio = useChatAudio();
+
+  return (
+    <ChatLauncher
+      audio={audio}
+      hotkey={{ key: '/', meta: true }}
+      fab={{ ariaLabel: 'Open chat', tooltip: 'Open chat' }}
+      dock={{ title: 'Assistant', height: 600 }}
+    >
+      <ChatRoot transport={transport} />
+    </ChatLauncher>
+  );
+}
+
+export const AudioToggleAutoInjected = () => <AudioLauncher />;
+
+// ── Reset with confirm ────────────────────────────────────────────────────
+
+function ResetLauncher() {
+  const transport = useMemo(() => makeBasicTransport(SEED_BASIC), []);
+
+  return (
+    <DialogProvider>
+      <ChatLauncher
+        hotkey={{ key: '/', meta: true }}
+        fab={{ ariaLabel: 'Open chat', tooltip: 'Open chat' }}
+        dock={{
+          title: 'CRM Assistant',
+          height: 600,
+          headerActions: (
+            <ChatHeaderResetButton
+              onReset={async () => {
+                await new Promise((r) => setTimeout(r, 600));
+                return true;
+              }}
+              onSuccess={() => alert('Context cleared.')}
+            />
+          ),
+        }}
+      >
+        <ChatRoot transport={transport} />
+      </ChatLauncher>
+    </DialogProvider>
+  );
+}
+
+/**
+ * `ChatHeaderResetButton` prompts `window.dialog.confirm` (destructive
+ * variant) before running the backend reset. `DialogProvider` from
+ * `@djangocfg/ui-core` installs that API.
+ */
+export const ResetWithConfirm = () => <ResetLauncher />;
+
+// ── Both together ────────────────────────────────────────────────────────
+
+function FullLauncher() {
+  const transport = useMemo(() => makeBasicTransport(SEED_BASIC), []);
+  // No `sounds` prop — uses bundled DEFAULT_CHAT_SOUNDS automatically.
+  const audio = useChatAudio();
+  return (
+    <DialogProvider>
+      <ChatLauncher
+        audio={audio}
+        hotkey={{ key: '/', meta: true }}
+        fab={{ ariaLabel: 'Open chat', tooltip: 'Open chat' }}
+        dock={{
+          title: 'CRM Assistant',
+          height: 600,
+          headerActions: (
+            <ChatHeaderResetButton
+              onReset={async () => {
+                await new Promise((r) => setTimeout(r, 600));
+                return true;
+              }}
+              onSuccess={() => alert('Context cleared.')}
+            />
+          ),
+        }}
+      >
+        <ChatRoot transport={transport} />
+      </ChatLauncher>
+    </DialogProvider>
+  );
+}
+
+export const AudioPlusReset = () => <FullLauncher />;

package/src/tools/Chat/stories/shared/Frame.tsx

@@ -0,0 +1,21 @@
+import type { ReactNode } from 'react';
+
+/** Fixed-size container so chat stories have a viewport to live in. */
+export function Frame({
+  children,
+  h = 560,
+  w = 480,
+}: {
+  children: ReactNode;
+  h?: number | string;
+  w?: number | string;
+}) {
+  return (
+    <div
+      className="overflow-hidden rounded-lg border border-border bg-background shadow-sm"
+      style={{ height: h, width: w }}
+    >
+      {children}
+    </div>
+  );
+}

package/src/tools/Chat/stories/shared/index.ts

@@ -0,0 +1,5 @@
+export { Frame } from './Frame';
+export { makeBasicTransport, makeToolCallsTransport } from './transports';
+export { BUBBLE_GALLERY } from './messages';
+export { USER_ANNA, ASSISTANT_AURA } from './personas';
+export { SEED_BASIC, SEED_TOOL_CALLS, SEED_JSON_PAYLOAD } from './seeds';

package/src/tools/Chat/stories/shared/messages.ts

@@ -0,0 +1,39 @@
+import type { ChatMessage } from '../../types';
+
+/** Compact transcript that exercises every bubble state for visual review. */
+export const BUBBLE_GALLERY: ChatMessage[] = [
+  {
+    id: 'u-1',
+    role: 'user',
+    content: 'How do I add a new persona?',
+    createdAt: Date.now() - 5 * 60_000,
+  },
+  {
+    id: 'a-1',
+    role: 'assistant',
+    content:
+      'Set `config.assistant = { name, avatarUrl }`. You can also override per message via `message.sender`.\n\nMore info: [docs](https://example.com/docs/personas).',
+    createdAt: Date.now() - 4 * 60_000,
+  },
+  {
+    id: 'u-2',
+    role: 'user',
+    content: 'And errors? What if the turn fails?',
+    createdAt: Date.now() - 3 * 60_000,
+  },
+  {
+    id: 'a-err',
+    role: 'assistant',
+    content: 'Network blew up — try again in a moment.',
+    isError: true,
+    createdAt: Date.now() - 2 * 60_000,
+  },
+  {
+    id: 'a-streaming',
+    role: 'assistant',
+    content: 'Live reply tokens arrive here',
+    isStreaming: true,
+    createdAt: Date.now() - 60_000,
+    toolActivity: 'Searching knowledge base…',
+  },
+];

package/src/tools/Chat/stories/shared/personas.ts

@@ -0,0 +1,13 @@
+import type { ChatAssistantContext, ChatUserContext } from '../../types';
+
+export const USER_ANNA: ChatUserContext = {
+  name: 'Anna',
+  email: 'anna@example.com',
+  avatarUrl: 'https://i.pravatar.cc/64?img=5',
+};
+
+export const ASSISTANT_AURA: ChatAssistantContext = {
+  name: 'Aura',
+  avatarUrl: 'https://i.pravatar.cc/64?img=11',
+  model: 'gpt-4o',
+};

package/src/tools/Chat/stories/shared/seeds.ts

@@ -0,0 +1,92 @@
+import type { ChatMessage, ChatToolCall } from '../../types';
+
+const now = Date.now();
+
+/** Two-turn transcript exercising markdown + plain reply. Used in Basic stories. */
+export const SEED_BASIC: ChatMessage[] = [
+  {
+    id: 'seed-u-1',
+    role: 'user',
+    content: 'Give me a markdown sample with a list and a code snippet.',
+    createdAt: now - 4 * 60_000,
+  },
+  {
+    id: 'seed-a-1',
+    role: 'assistant',
+    content:
+      '**Sure!** Here is a list:\n\n- alpha\n- beta\n- gamma\n\nAnd a snippet:\n\n```ts\nconst answer = 42;\n```',
+    createdAt: now - 3 * 60_000,
+  },
+  {
+    id: 'seed-u-2',
+    role: 'user',
+    content: 'How does streaming work?',
+    createdAt: now - 2 * 60_000,
+  },
+  {
+    id: 'seed-a-2',
+    role: 'assistant',
+    content:
+      'Each token arrives separately over SSE. The UI sticks to the bottom while the stream is in flight and shows a streaming indicator until `message_end` fires.',
+    createdAt: now - 60_000,
+  },
+];
+
+/** A completed tool-call so the panel is visible without sending anything. */
+const SEED_TOOL_CALL: ChatToolCall = {
+  id: 'tc-seed-1',
+  name: 'search_docs',
+  input: { query: 'streaming protocol' },
+  output: { hits: 3, top: 'streaming.md' },
+  status: 'success',
+  startedAt: now - 90_000,
+  endedAt: now - 89_000,
+};
+
+export const SEED_TOOL_CALLS: ChatMessage[] = [
+  {
+    id: 'seed-u-tool',
+    role: 'user',
+    content: 'Find docs about streaming.',
+    createdAt: now - 2 * 60_000,
+  },
+  {
+    id: 'seed-a-tool',
+    role: 'assistant',
+    content: 'Let me check the docs for you.\n\nFound 3 relevant chunks. Here is a summary…',
+    createdAt: now - 60_000,
+    toolCalls: [SEED_TOOL_CALL],
+  },
+];
+
+/** Tool-call with a richer JSON payload — drives the JsonTree dispatcher story. */
+const SEED_JSON_TOOL_CALL: ChatToolCall = {
+  id: 'tc-seed-json',
+  name: 'fetch_user',
+  input: { id: 'usr_42', fields: ['email', 'roles', 'metadata'] },
+  output: {
+    id: 'usr_42',
+    email: 'mark@example.com',
+    roles: ['admin', 'editor'],
+    metadata: { plan: 'pro', seats: 5, trial: false },
+  },
+  status: 'success',
+  startedAt: now - 90_000,
+  endedAt: now - 89_000,
+};
+
+export const SEED_JSON_PAYLOAD: ChatMessage[] = [
+  {
+    id: 'seed-u-json',
+    role: 'user',
+    content: 'Fetch user 42.',
+    createdAt: now - 2 * 60_000,
+  },
+  {
+    id: 'seed-a-json',
+    role: 'assistant',
+    content: 'Open the tool panel to inspect the payload.',
+    createdAt: now - 60_000,
+    toolCalls: [SEED_JSON_TOOL_CALL],
+  },
+];

package/src/tools/Chat/stories/shared/transports.ts

@@ -0,0 +1,36 @@
+import { createMockTransport } from '../../core/transport/mock';
+import type { ChatMessage, ChatStreamEvent } from '../../types';
+
+/** Scripted-replies transport. Pass `seed` to pre-populate the bubble area. */
+export function makeBasicTransport(seed: ChatMessage[] = []) {
+  return createMockTransport({
+    initialMessages: seed,
+    replies: [
+      'Hello! I am a mock assistant. Ask me anything — I will reply with scripted text.',
+      '**Sure!** Here is a list:\n\n- alpha\n- beta\n- gamma\n\nAnd a snippet:\n\n```ts\nconst answer = 42;\n```',
+      'Streaming chunked text works too. Each token arrives separately and the UI sticks to the bottom while the stream is in flight.',
+    ],
+    latencyMs: 35,
+  });
+}
+
+/** Transport with an inline tool_call + result on send. Seedable. */
+export function makeToolCallsTransport(seed: ChatMessage[] = []) {
+  const toolTurn: ChatStreamEvent[] = [
+    { type: 'chunk', delta: 'Let me check the docs for you.\n\n' },
+    {
+      type: 'tool_call_start',
+      toolId: 'search-live',
+      name: 'search_docs',
+      input: { query: 'streaming protocol' },
+    },
+    {
+      type: 'tool_call_end',
+      toolId: 'search-live',
+      status: 'success',
+      output: { hits: 3, top: 'streaming.md' },
+    },
+    { type: 'chunk', delta: 'Found 3 relevant chunks. Here is a summary…' },
+  ];
+  return createMockTransport({ initialMessages: seed, replies: [toolTurn], latencyMs: 25 });
+}

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';

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

@@ -0,0 +1,101 @@
+/**
+ * Role-aware style hooks for chat surfaces.
+ *
+ * Pure utility hooks — no React state, no side effects, just memoized
+ * className strings derived from `bubbleTokens`. They exist so:
+ *   - components don't import token constants directly (single facade)
+ *   - "the user-bubble link color" can be changed in one file
+ *   - tests can mock the hook to assert intent without parsing classNames
+ */
+
+import { useMemo } from 'react';
+
+import {
+  ANCHOR,
+  BUBBLE_SURFACE,
+  DESTRUCTIVE_SURFACE,
+  TOGGLE,
+  TOOL_CALL,
+  type ChatBubbleSurface,
+} from './bubbleTokens';
+
+export interface ChatBubbleStyles {
+  /** className for the bubble container (background + text + border). */
+  surface: string;
+  /** className for an inline anchor inside markdown. */
+  anchor: string;
+  /** className for a secondary inline action (e.g. show more). */
+  toggle: string;
+}
+
+/**
+ * Resolve bubble + content styles for a single message.
+ *
+ * @param role        'user' | 'assistant' | 'system' (system defaults to assistant styling)
+ * @param isError     marks the bubble as a failed turn (overrides surface)
+ *
+ * @example
+ * ```tsx
+ * const { surface, anchor } = useChatBubbleStyles(message.role, !!message.isError);
+ * <div className={cn('rounded-2xl px-3.5 py-2', surface)}>…</div>
+ * ```
+ */
+export function useChatBubbleStyles(
+  role: 'user' | 'assistant' | 'system',
+  isError: boolean,
+): ChatBubbleStyles {
+  return useMemo(() => {
+    const isUser = role === 'user';
+    const variant: ChatBubbleSurface = isUser ? 'user' : isError ? 'error' : 'assistant';
+    return {
+      surface: BUBBLE_SURFACE[variant],
+      anchor: isUser ? ANCHOR.user : ANCHOR.assistant,
+      toggle: isUser ? TOGGLE.user : TOGGLE.assistant,
+    };
+  }, [role, isError]);
+}
+
+export interface ChatRoleStyles {
+  anchor: string;
+  toggle: string;
+}
+
+/**
+ * Lightweight variant when only role matters (no error state, no surface).
+ * Use in shared markdown renderers that don't know about bubble background.
+ */
+export function useChatRoleStyles(isUser: boolean): ChatRoleStyles {
+  return useMemo(
+    () => ({
+      anchor: isUser ? ANCHOR.user : ANCHOR.assistant,
+      toggle: isUser ? TOGGLE.user : TOGGLE.assistant,
+    }),
+    [isUser],
+  );
+}
+
+export interface ChatDestructiveStyles {
+  banner: string;
+  hover: string;
+  hoverStrong: string;
+  text: string;
+  menuItem: string;
+  toolErrorText: string;
+}
+
+/**
+ * Destructive (delete / error) class facade. Hook form keeps the API
+ * symmetric with the others; under the hood it returns a frozen object.
+ */
+export function useChatDestructiveStyles(): ChatDestructiveStyles {
+  return DESTRUCTIVE_STYLES;
+}
+
+const DESTRUCTIVE_STYLES: ChatDestructiveStyles = {
+  banner: DESTRUCTIVE_SURFACE.banner,
+  hover: DESTRUCTIVE_SURFACE.hover,
+  hoverStrong: DESTRUCTIVE_SURFACE.hoverStrong,
+  text: DESTRUCTIVE_SURFACE.text,
+  menuItem: DESTRUCTIVE_SURFACE.menuItem,
+  toolErrorText: TOOL_CALL.errorText,
+};

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

@@ -0,0 +1,25 @@
+/**
+ * Attachments + sources attached to a chat message.
+ */
+
+export interface ChatAttachment {
+  id: string;
+  type: 'image' | 'file' | 'audio' | 'video';
+  url: string;
+  thumbnailUrl?: string;
+  name?: string;
+  mimeType?: string;
+  sizeBytes?: number;
+  status?: 'uploading' | 'ready' | 'error';
+  /** 0..1 while uploading. */
+  progress?: number;
+  /** Extracted text from images (OCR). */
+  ocrText?: string;
+}
+
+export interface ChatSource {
+  title: string;
+  url: string;
+  snippet?: string;
+  chunkIndex?: number;
+}

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

@@ -0,0 +1,48 @@
+/**
+ * Top-level chat configuration — placeholder, suggestions, identities, prefs.
+ */
+
+import type { ChatAssistantContext, ChatUserContext } from './persona';
+import type { ChatLabels } from './labels';
+
+export type ChatDisplayMode = 'closed' | 'embedded' | 'floating' | 'sidebar' | 'fullscreen';
+
+export interface ChatPrefs {
+  /** Submit hotkey for the composer. */
+  submitOn?: 'enter' | 'cmd+enter';
+  /** UI density. */
+  density?: 'comfortable' | 'compact';
+  /** Locale forwarded to transport metadata. */
+  locale?: string;
+  /** Show timestamps on each bubble. */
+  showTimestamps?: boolean;
+}
+
+export interface ChatConfig {
+  /** Window title / aria-label. */
+  title?: string;
+  /** Composer placeholder. */
+  placeholder?: string;
+  /** Empty-state greeting. */
+  greeting?: string;
+  /** Empty-state description. */
+  description?: string;
+  /** Suggested prompts shown on empty conversation. */
+  suggestions?: Array<{ label: string; prompt: string }>;
+  /** Locale forwarded to the transport via stream metadata. */
+  locale?: string;
+  /** Project / chat slug forwarded to the transport. */
+  slug?: string;
+  /** UI density. Use `prefs.density` for the same effect; this stays for
+   *  backwards compatibility. */
+  density?: 'comfortable' | 'compact';
+  /** Identity of the human author. Renders avatar / name on user bubbles
+   *  and gets stamped on outgoing messages as `message.sender`. */
+  user?: ChatUserContext;
+  /** Identity of the assistant. Renders avatar / name on assistant bubbles. */
+  assistant?: ChatAssistantContext;
+  /** UI preferences. */
+  prefs?: ChatPrefs;
+  /** Visual labels (i18n is the host's job). */
+  labels?: Partial<ChatLabels>;
+}

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

@@ -0,0 +1,35 @@
+/**
+ * SSE stream events — the canonical wire shape consumed by the reducer.
+ *
+ * Backend-specific shapes (e.g. pydantic-AI's `text_delta`) get normalized
+ * into this union by `mapPydanticAIEvent` and friends.
+ */
+
+import type { ChatSource } from './attachment';
+
+export type ChatStreamEvent =
+  | { type: 'message_start'; messageId: string; sessionId: string }
+  | { type: 'resume_start' }
+  | { type: 'chunk'; delta: string }
+  | { type: 'tool_activity'; tool: string; status: string }
+  | {
+      type: 'tool_call_start';
+      toolId: string;
+      name: string;
+      input: unknown;
+      sourceHostname?: string;
+    }
+  | { type: 'tool_call_delta'; toolId: string; delta: string }
+  | {
+      type: 'tool_call_end';
+      toolId: string;
+      output: unknown;
+      status: 'success' | 'error';
+    }
+  | {
+      type: 'message_end';
+      tokensIn?: number;
+      tokensOut?: number;
+      sources?: ChatSource[];
+    }
+  | { type: 'error'; code: string; message: string };

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

@@ -0,0 +1,34 @@
+/**
+ * Public types for the Chat tool — single source of truth.
+ *
+ * Shapes here are the contract between transport adapters, the reducer,
+ * the hooks layer and the components. Keep serializable (no Date, no Map).
+ *
+ * Organized by domain:
+ *   persona     — identity (role, ChatPersona, user/assistant contexts)
+ *   tool-call   — ChatToolCall
+ *   attachment  — ChatAttachment, ChatSource
+ *   message     — ChatMessage (composes the above)
+ *   labels      — UI strings + DEFAULT_LABELS
+ *   config      — ChatConfig + ChatPrefs + display mode
+ *   events      — ChatStreamEvent SSE union
+ *   session     — Session/history/stream/send option shapes
+ *   transport   — ChatTransport interface
+ */
+
+export type { ChatRole, ChatPersona, ChatUserContext, ChatAssistantContext } from './persona';
+export type { ChatToolCall } from './tool-call';
+export type { ChatAttachment, ChatSource } from './attachment';
+export type { ChatMessage } from './message';
+export { DEFAULT_LABELS } from './labels';
+export type { ChatLabels } from './labels';
+export type { ChatConfig, ChatPrefs, ChatDisplayMode } from './config';
+export type { ChatStreamEvent } from './events';
+export type {
+  CreateSessionOptions,
+  SessionInfo,
+  HistoryPage,
+  StreamOptions,
+  SendOptions,
+} from './session';
+export type { ChatTransport } from './transport';