@djangocfg/ui-tools 2.1.380 → 2.1.382

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

package/src/tools/MarkdownEditor/MarkdownEditor.tsx

@@ -6,7 +6,7 @@ import Placeholder from '@tiptap/extension-placeholder';
 import Mention from '@tiptap/extension-mention';
 import { Markdown } from '@tiptap/markdown';
 import type { AnyExtension } from '@tiptap/core';
-import { useEffect, useRef, useMemo } from 'react';
+import { forwardRef, useEffect, useImperativeHandle, useMemo, useRef } from 'react';
 import {
   Bold, Italic, Strikethrough, Heading1, Heading2, Heading3,
   List, ListOrdered, Quote, Minus, Code, type LucideIcon,
@@ -90,20 +90,39 @@ export interface MarkdownEditorProps {
   onSubmit?: () => boolean | void;
 }
 
+/**
+ * Imperative handle exposed via `ref`. Matches `ComposerHandle` from
+ * `@djangocfg/ui-tools/chat` so consumers can forward it straight into
+ * `useRegisterComposer({ focus, moveCursorToEnd })` — that's what makes
+ * voice dictation (`VoiceComposerSlot`) push live text into a TipTap
+ * composer.
+ */
+export interface MarkdownEditorHandle {
+  /** Move keyboard focus into the editor. */
+  focus: () => void;
+  /** Place the caret at the end of the document (and focus). */
+  moveCursorToEnd: () => void;
+  /** Escape hatch — the underlying TipTap `Editor` instance. */
+  getEditor: () => Editor | null;
+}
+
 // ── Component ──
 
-export function MarkdownEditor({
-  value,
-  onChange,
-  placeholder = 'Write markdown...',
-  minHeight = 120,
-  className = '',
-  disabled = false,
-  showToolbar = true,
-  mentions,
-  onMentionIdsChange,
-  onSubmit,
-}: MarkdownEditorProps) {
+export const MarkdownEditor = forwardRef<MarkdownEditorHandle, MarkdownEditorProps>(function MarkdownEditor(
+  {
+    value,
+    onChange,
+    placeholder = 'Write markdown...',
+    minHeight = 120,
+    className = '',
+    disabled = false,
+    showToolbar = true,
+    mentions,
+    onMentionIdsChange,
+    onSubmit,
+  },
+  ref,
+) {
   // Keep the latest onSubmit in a ref so the Tiptap extension's
   // keymap closure always calls the freshest handler — Tiptap's
   // useEditor initialises extensions ONCE on first render. Without
@@ -244,6 +263,23 @@ export function MarkdownEditor({
     }
   }, [value, editor]);
 
+  // Imperative API for hosts that drive the editor without owning a
+  // TipTap ref directly — chat composer registration, voice slot,
+  // focus-on-stream-end.
+  useImperativeHandle(
+    ref,
+    (): MarkdownEditorHandle => ({
+      focus: () => {
+        editor?.commands.focus();
+      },
+      moveCursorToEnd: () => {
+        editor?.commands.focus('end');
+      },
+      getEditor: () => editor ?? null,
+    }),
+    [editor],
+  );
+
   const wrapperClass = `markdown-editor rounded-md border border-input bg-background ${disabled ? 'opacity-60' : ''} ${className}`.trim();
 
   return (
@@ -254,7 +290,7 @@ export function MarkdownEditor({
       </div>
     </div>
   );
-}
+});
 
 // ── Toolbar ──
 

package/src/tools/MarkdownEditor/index.ts

@@ -1,5 +1,5 @@
 export { MarkdownEditor } from './MarkdownEditor';
-export type { MarkdownEditorProps } from './MarkdownEditor';
+export type { MarkdownEditorProps, MarkdownEditorHandle } from './MarkdownEditor';
 export type {
   MentionItem,
   MentionConfig,