@djangocfg/ui-tools 2.1.381 → 2.1.383

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

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

@@ -0,0 +1,38 @@
+/**
+ * UI label strings — i18n is the host's job. Pass overrides via
+ * `ChatConfig.labels` and merge with `DEFAULT_LABELS`.
+ */
+
+export interface ChatLabels {
+  send: string;
+  cancel: string;
+  copy: string;
+  regenerate: string;
+  edit: string;
+  delete: string;
+  retry: string;
+  newChat: string;
+  loadMore: string;
+  jumpToLatest: string;
+  attach: string;
+  voice: string;
+  errorGeneric: string;
+  cancelledSuffix: string;
+}
+
+export const DEFAULT_LABELS: ChatLabels = {
+  send: 'Send',
+  cancel: 'Stop',
+  copy: 'Copy',
+  regenerate: 'Regenerate',
+  edit: 'Edit',
+  delete: 'Delete',
+  retry: 'Retry',
+  newChat: 'New chat',
+  loadMore: 'Load more',
+  jumpToLatest: 'Jump to latest',
+  attach: 'Attach files',
+  voice: 'Voice input',
+  errorGeneric: 'Something went wrong',
+  cancelledSuffix: '[cancelled]',
+};

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

@@ -0,0 +1,32 @@
+/**
+ * The atomic unit — a single message in a chat session.
+ *
+ * Composed of role + content + optional rich-data slots (attachments,
+ * sources, tool calls). Serializable: no Date, no Map.
+ */
+
+import type { ChatAttachment, ChatSource } from './attachment';
+import type { ChatPersona, ChatRole } from './persona';
+import type { ChatToolCall } from './tool-call';
+
+export interface ChatMessage {
+  id: string;
+  role: ChatRole;
+  content: string;
+  /** epoch ms — serializable. */
+  createdAt: number;
+  isStreaming?: boolean;
+  isError?: boolean;
+  /** Bumps on edit so memo keys invalidate. */
+  version?: number;
+  /** Per-message persona override (multi-user / multi-bot). Falls back to
+   *  `ChatConfig.user` / `ChatConfig.assistant` when absent. */
+  sender?: ChatPersona;
+  /** Simple status indicator above message ("Searching knowledge base..."). */
+  toolActivity?: string;
+  toolCalls?: ChatToolCall[];
+  attachments?: ChatAttachment[];
+  sources?: ChatSource[];
+  tokensIn?: number;
+  tokensOut?: number;
+}

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

@@ -0,0 +1,31 @@
+/**
+ * Persona — display identity attached to messages and config.
+ *
+ * Used by `ChatMessage.sender`, `ChatConfig.user`, `ChatConfig.assistant`.
+ */
+
+export type ChatRole = 'user' | 'assistant' | 'system';
+
+export interface ChatPersona {
+  /** Display name. */
+  name?: string;
+  /** Avatar image URL. */
+  avatarUrl?: string;
+  /** Initials fallback when no avatar. Auto-derived from `name` if absent. */
+  initials?: string;
+  /** Tooltip / aria description. */
+  description?: string;
+}
+
+export interface ChatUserContext extends ChatPersona {
+  email?: string;
+  language?: string;
+  role?: string;
+  /** Free-form custom data forwarded to transport metadata. */
+  custom?: Record<string, unknown>;
+}
+
+export interface ChatAssistantContext extends ChatPersona {
+  /** Model identifier (gpt-4o, claude-opus, …). */
+  model?: string;
+}

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

@@ -0,0 +1,43 @@
+/**
+ * Session info + history page shapes returned by transports.
+ */
+
+import type { ChatAttachment } from './attachment';
+import type { ChatMessage } from './message';
+
+export interface CreateSessionOptions {
+  metadata?: Record<string, unknown>;
+}
+
+export interface SessionInfo {
+  sessionId: string;
+  /** If the server resumed an existing session, it may return prior messages. */
+  messages?: ChatMessage[];
+  hasMore?: boolean;
+  cursor?: string | null;
+  resumed?: boolean;
+  /**
+   * Optional human-readable title (typically derived from the first
+   * user message). Hosts that render a session-list sidebar can read
+   * this directly instead of crawling messages. Plan64.
+   */
+  title?: string;
+}
+
+export interface HistoryPage {
+  messages: ChatMessage[];
+  hasMore: boolean;
+  nextCursor: string | null;
+}
+
+export interface StreamOptions {
+  signal: AbortSignal;
+  attachments?: ChatAttachment[];
+  metadata?: Record<string, unknown>;
+}
+
+export interface SendOptions {
+  signal?: AbortSignal;
+  attachments?: ChatAttachment[];
+  metadata?: Record<string, unknown>;
+}

package/src/tools/Chat/types/tool-call.ts

@@ -0,0 +1,17 @@
+/**
+ * Tool calls — assistant-initiated function/tool invocations during a turn.
+ */
+
+export interface ChatToolCall {
+  id: string;
+  name: string;
+  input: unknown;
+  output?: unknown;
+  /** Live buffer accumulated during streaming. Replaced by `output` on completion. */
+  streamingText?: string;
+  status: 'running' | 'success' | 'error' | 'cancelled';
+  startedAt: number;
+  endedAt?: number;
+  /** Optional grouping label for parallel/fan-out execution. */
+  sourceHostname?: string;
+}

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

@@ -0,0 +1,28 @@
+/**
+ * Transport interface — what every chat backend adapter implements.
+ *
+ * Default web implementation lives in `core/transport/http.ts`.
+ * Pydantic-AI adapter lives in `core/transport/pydantic-ai-transport.ts`.
+ */
+
+import type { ChatMessage } from './message';
+import type { ChatStreamEvent } from './events';
+import type {
+  CreateSessionOptions,
+  HistoryPage,
+  SendOptions,
+  SessionInfo,
+  StreamOptions,
+} from './session';
+
+export interface ChatTransport {
+  createSession(opts?: CreateSessionOptions): Promise<SessionInfo>;
+  loadHistory(sessionId: string, cursor?: string | null, limit?: number): Promise<HistoryPage>;
+  stream(
+    sessionId: string,
+    content: string,
+    options: StreamOptions,
+  ): AsyncGenerator<ChatStreamEvent, void, void>;
+  send(sessionId: string, content: string, options?: SendOptions): Promise<ChatMessage>;
+  closeSession(sessionId: string): Promise<void>;
+}

package/src/tools/Chat/types.ts

@@ -1,244 +1,9 @@
 /**
- * Public types for the Chat tool.
+ * Backwards-compatibility re-export.
  *
- * Shapes here are the contract between transport adapters, the reducer,
- * the hooks layer and the components. Keep serializable (no Date, no Map).
+ * Types live in `./types/` (one file per domain). Import directly from
+ * `@djangocfg/ui-tools/Chat` in new code; this barrel exists so old
+ * `import … from '.../types'` paths keep working.
  */
 
-export type ChatRole = 'user' | 'assistant' | 'system';
-
-export interface ChatToolCall {
-  id: string;
-  name: string;
-  input: unknown;
-  output?: unknown;
-  /** Live buffer accumulated during streaming. Replaced by `output` on completion. */
-  streamingText?: string;
-  status: 'running' | 'success' | 'error' | 'cancelled';
-  startedAt: number;
-  endedAt?: number;
-  /** Optional grouping label for parallel/fan-out execution. */
-  sourceHostname?: string;
-}
-
-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;
-}
-
-export interface ChatPersona {
-  /** Display name. */
-  name?: string;
-  /** Avatar image URL. */
-  avatarUrl?: string;
-  /** Initials fallback when no avatar. Auto-derived from `name` if absent. */
-  initials?: string;
-  /** Tooltip / aria description. */
-  description?: string;
-}
-
-export interface ChatMessage {
-  id: string;
-  role: ChatRole;
-  content: string;
-  /** epoch ms — serializable. */
-  createdAt: number;
-  isStreaming?: boolean;
-  isError?: boolean;
-  /** Bumps on edit so memo keys invalidate. */
-  version?: number;
-  /** Per-message persona override (multi-user / multi-bot). Falls back to
-   *  `ChatConfig.user` / `ChatConfig.assistant` when absent. */
-  sender?: ChatPersona;
-  /** Simple status indicator above message ("Searching knowledge base..."). */
-  toolActivity?: string;
-  toolCalls?: ChatToolCall[];
-  attachments?: ChatAttachment[];
-  sources?: ChatSource[];
-  tokensIn?: number;
-  tokensOut?: number;
-}
-
-export type ChatDisplayMode = 'closed' | 'embedded' | 'floating' | 'sidebar' | 'fullscreen';
-
-export interface ChatUserContext extends ChatPersona {
-  email?: string;
-  language?: string;
-  role?: string;
-  /** Free-form custom data forwarded to transport metadata. */
-  custom?: Record<string, unknown>;
-}
-
-export interface ChatAssistantContext extends ChatPersona {
-  /** Model identifier (gpt-4o, claude-opus, …). */
-  model?: string;
-}
-
-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>;
-}
-
-export interface ChatLabels {
-  send: string;
-  cancel: string;
-  copy: string;
-  regenerate: string;
-  edit: string;
-  delete: string;
-  retry: string;
-  newChat: string;
-  loadMore: string;
-  jumpToLatest: string;
-  attach: string;
-  voice: string;
-  errorGeneric: string;
-  cancelledSuffix: string;
-}
-
-export const DEFAULT_LABELS: ChatLabels = {
-  send: 'Send',
-  cancel: 'Stop',
-  copy: 'Copy',
-  regenerate: 'Regenerate',
-  edit: 'Edit',
-  delete: 'Delete',
-  retry: 'Retry',
-  newChat: 'New chat',
-  loadMore: 'Load more',
-  jumpToLatest: 'Jump to latest',
-  attach: 'Attach files',
-  voice: 'Voice input',
-  errorGeneric: 'Something went wrong',
-  cancelledSuffix: '[cancelled]',
-};
-
-// ---- Transport ------------------------------------------------------------
-
-export interface CreateSessionOptions {
-  metadata?: Record<string, unknown>;
-}
-
-export interface SessionInfo {
-  sessionId: string;
-  /** If the server resumed an existing session, it may return prior messages. */
-  messages?: ChatMessage[];
-  hasMore?: boolean;
-  cursor?: string | null;
-  resumed?: boolean;
-  /**
-   * Optional human-readable title (typically derived from the first
-   * user message). Hosts that render a session-list sidebar can read
-   * this directly instead of crawling messages. Plan64.
-   */
-  title?: string;
-}
-
-export interface HistoryPage {
-  messages: ChatMessage[];
-  hasMore: boolean;
-  nextCursor: string | null;
-}
-
-export interface StreamOptions {
-  signal: AbortSignal;
-  attachments?: ChatAttachment[];
-  metadata?: Record<string, unknown>;
-}
-
-export interface SendOptions {
-  signal?: AbortSignal;
-  attachments?: ChatAttachment[];
-  metadata?: Record<string, unknown>;
-}
-
-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 };
-
-export interface ChatTransport {
-  createSession(opts?: CreateSessionOptions): Promise<SessionInfo>;
-  loadHistory(sessionId: string, cursor?: string | null, limit?: number): Promise<HistoryPage>;
-  stream(
-    sessionId: string,
-    content: string,
-    options: StreamOptions,
-  ): AsyncGenerator<ChatStreamEvent, void, void>;
-  send(sessionId: string, content: string, options?: SendOptions): Promise<ChatMessage>;
-  closeSession(sessionId: string): Promise<void>;
-}
+export * from './types/index';