@djangocfg/ui-tools 2.1.335 → 2.1.337

package/src/tools/Chat/core/payload-dispatch.ts

@@ -0,0 +1,54 @@
+// Tiny dispatcher for tool-call payload renderers.
+//
+// Hosts compose matchers (predicate + render) and a fallback. The result is a
+// `renderPayload` function compatible with `<ToolCalls renderPayload>`.
+//
+// Pure — no React, no DOM. The matchers themselves return ReactNode.
+
+import type { ReactNode } from 'react';
+
+import type { ChatToolCall } from '../types';
+import type { ToolPayloadKind } from '../components/ToolCalls';
+
+export interface ToolPayloadMatcher {
+  /** Cheap predicate. First match wins. */
+  match: (value: unknown, kind: ToolPayloadKind, call: ChatToolCall) => boolean;
+  render: (value: unknown, kind: ToolPayloadKind, call: ChatToolCall) => ReactNode;
+}
+
+export type ToolPayloadFallback = (
+  value: unknown,
+  kind: ToolPayloadKind,
+  call: ChatToolCall,
+) => ReactNode;
+
+export function dispatchToolPayload(
+  matchers: ToolPayloadMatcher[],
+  fallback: ToolPayloadFallback,
+): ToolPayloadFallback {
+  return (value, kind, call) => {
+    for (const m of matchers) {
+      if (m.match(value, kind, call)) return m.render(value, kind, call);
+    }
+    return fallback(value, kind, call);
+  };
+}
+
+// ---- Common matcher predicates -------------------------------------------
+// Re-export as building blocks. Hosts can use directly or compose.
+
+export function isPlainObject(v: unknown): v is Record<string, unknown> {
+  return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+
+export function isLatLng(v: unknown): v is { lat: number; lng: number } {
+  return isPlainObject(v) && typeof v.lat === 'number' && typeof v.lng === 'number';
+}
+
+export function isGeoJSONFeatureCollection(v: unknown): v is { type: 'FeatureCollection'; features: unknown[] } {
+  return isPlainObject(v) && v.type === 'FeatureCollection' && Array.isArray(v.features);
+}
+
+export function isStringValue(v: unknown): v is string {
+  return typeof v === 'string';
+}

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

@@ -0,0 +1,35 @@
+// Persona resolution helpers — pure, no React.
+//
+// Resolution cascade for a bubble's persona:
+//   1. message.sender              (per-message override; multi-user chats)
+//   2. config.user / config.assistant (provider-level default)
+//   3. role-based fallback         ('You' / 'AI')
+
+import type { ChatAssistantContext, ChatMessage, ChatPersona, ChatUserContext } from '../types';
+
+const FALLBACK_USER: ChatPersona = { name: 'You', initials: 'You' };
+const FALLBACK_ASSISTANT: ChatPersona = { name: 'AI', initials: 'AI' };
+
+export function resolvePersona(
+  message: Pick<ChatMessage, 'role' | 'sender'>,
+  user?: ChatUserContext,
+  assistant?: ChatAssistantContext,
+): ChatPersona {
+  if (message.sender) return message.sender;
+  if (message.role === 'user') return user ?? FALLBACK_USER;
+  if (message.role === 'assistant') return assistant ?? FALLBACK_ASSISTANT;
+  return { name: message.role };
+}
+
+/** Compute initials for an avatar fallback. */
+export function deriveInitials(persona: ChatPersona, role?: string): string {
+  if (persona.initials) return persona.initials;
+  if (persona.name) {
+    const parts = persona.name.trim().split(/\s+/);
+    if (parts.length === 1) return parts[0].slice(0, 2).toUpperCase();
+    return (parts[0][0] + parts[parts.length - 1][0]).toUpperCase();
+  }
+  if (role === 'user') return 'You';
+  if (role === 'assistant') return 'AI';
+  return '?';
+}

package/src/tools/Chat/core/reducer.ts

@@ -0,0 +1,335 @@
+/**
+ * Pure chat state machine. Zero React. Zero I/O.
+ *
+ * Invariants:
+ *  - At most one message has `isStreaming === true` at any time. It is always
+ *    the last message in the array.
+ *  - Messages are immutable; updates produce new objects.
+ *  - `version` bumps on edit so memo keys invalidate.
+ */
+
+import type { ChatAttachment, ChatMessage, ChatSource, ChatToolCall } from '../types';
+
+export interface ChatState {
+  sessionId: string | null;
+  messages: ChatMessage[];
+  /** Initial history load in flight. */
+  isLoading: boolean;
+  /** Assistant is generating a reply. */
+  isStreaming: boolean;
+  /** Older history page in flight. */
+  isLoadingMore: boolean;
+  hasMore: boolean;
+  oldestCursor: string | null;
+  error: string | null;
+}
+
+export const initialState: ChatState = {
+  sessionId: null,
+  messages: [],
+  isLoading: false,
+  isStreaming: false,
+  isLoadingMore: false,
+  hasMore: true,
+  oldestCursor: null,
+  error: null,
+};
+
+export type ChatAction =
+  | {
+      type: 'SESSION_SET';
+      sessionId: string;
+      messages?: ChatMessage[];
+      hasMore?: boolean;
+      cursor?: string | null;
+    }
+  | { type: 'HISTORY_LOAD_START' }
+  | {
+      type: 'HISTORY_LOAD_DONE';
+      messages: ChatMessage[];
+      hasMore: boolean;
+      cursor: string | null;
+    }
+  | { type: 'HISTORY_MORE_START' }
+  | {
+      type: 'HISTORY_MORE_DONE';
+      messages: ChatMessage[];
+      hasMore: boolean;
+      cursor: string | null;
+    }
+  | { type: 'MESSAGE_USER_ADD'; message: ChatMessage }
+  | { type: 'STREAM_START'; id: string; createdAt?: number }
+  | { type: 'STREAM_CHUNK'; delta: string }
+  | { type: 'STREAM_TOOL_ACTIVITY'; tool: string }
+  | { type: 'TOOL_CALL_START'; messageId: string; toolCall: ChatToolCall }
+  | { type: 'TOOL_CALL_DELTA'; messageId: string; toolId: string; delta: string }
+  | {
+      type: 'TOOL_CALL_END';
+      messageId: string;
+      toolId: string;
+      output: unknown;
+      status: 'success' | 'error';
+    }
+  | {
+      type: 'STREAM_DONE';
+      id: string;
+      tokensIn?: number;
+      tokensOut?: number;
+      sources?: ChatSource[];
+    }
+  | { type: 'STREAM_CANCELLED'; id: string; partialText: string; label?: string }
+  | { type: 'STREAM_ERROR'; id?: string; message: string }
+  | { type: 'MESSAGE_EDIT'; id: string; content: string }
+  | { type: 'MESSAGE_DELETE'; id: string }
+  | { type: 'MESSAGES_CLEAR' }
+  | { type: 'ERROR_SET'; error: string | null }
+  | {
+      type: 'ATTACHMENT_PROGRESS';
+      messageId: string;
+      attachmentId: string;
+      progress?: number;
+      status?: ChatAttachment['status'];
+    };
+
+function updateLastStreaming(
+  messages: ChatMessage[],
+  patch: (m: ChatMessage) => ChatMessage,
+): ChatMessage[] {
+  const idx = findLastStreamingIndex(messages);
+  if (idx === -1) return messages;
+  const next = messages.slice();
+  next[idx] = patch(messages[idx]);
+  return next;
+}
+
+function findLastStreamingIndex(messages: ChatMessage[]): number {
+  for (let i = messages.length - 1; i >= 0; i -= 1) {
+    if (messages[i].isStreaming) return i;
+  }
+  return -1;
+}
+
+function patchMessageById(
+  messages: ChatMessage[],
+  id: string,
+  patch: (m: ChatMessage) => ChatMessage,
+): ChatMessage[] {
+  const idx = messages.findIndex((m) => m.id === id);
+  if (idx === -1) return messages;
+  const next = messages.slice();
+  next[idx] = patch(messages[idx]);
+  return next;
+}
+
+export function reducer(state: ChatState, action: ChatAction): ChatState {
+  switch (action.type) {
+    case 'SESSION_SET':
+      return {
+        ...state,
+        sessionId: action.sessionId,
+        messages: action.messages ?? state.messages,
+        hasMore: action.hasMore ?? state.hasMore,
+        oldestCursor: action.cursor ?? state.oldestCursor,
+        error: null,
+      };
+
+    case 'HISTORY_LOAD_START':
+      return { ...state, isLoading: true, error: null };
+
+    case 'HISTORY_LOAD_DONE':
+      return {
+        ...state,
+        isLoading: false,
+        messages: action.messages,
+        hasMore: action.hasMore,
+        oldestCursor: action.cursor,
+      };
+
+    case 'HISTORY_MORE_START':
+      return { ...state, isLoadingMore: true };
+
+    case 'HISTORY_MORE_DONE':
+      return {
+        ...state,
+        isLoadingMore: false,
+        // Older messages prepend to the top.
+        messages: [...action.messages, ...state.messages],
+        hasMore: action.hasMore,
+        oldestCursor: action.cursor,
+      };
+
+    case 'MESSAGE_USER_ADD':
+      return {
+        ...state,
+        messages: [...state.messages, action.message],
+        error: null,
+      };
+
+    case 'STREAM_START': {
+      if (state.isStreaming) {
+        if (typeof console !== 'undefined') {
+          // Soft guard — UI should disable the composer; this catches bugs.
+          // eslint-disable-next-line no-console
+          console.warn('[chat] STREAM_START while already streaming, ignoring');
+        }
+        return state;
+      }
+      const placeholder: ChatMessage = {
+        id: action.id,
+        role: 'assistant',
+        content: '',
+        createdAt: action.createdAt ?? Date.now(),
+        isStreaming: true,
+      };
+      return {
+        ...state,
+        isStreaming: true,
+        messages: [...state.messages, placeholder],
+      };
+    }
+
+    case 'STREAM_CHUNK': {
+      const messages = updateLastStreaming(state.messages, (m) => ({
+        ...m,
+        content: m.content + action.delta,
+      }));
+      return { ...state, messages };
+    }
+
+    case 'STREAM_TOOL_ACTIVITY': {
+      const messages = updateLastStreaming(state.messages, (m) => ({
+        ...m,
+        toolActivity: action.tool,
+      }));
+      return { ...state, messages };
+    }
+
+    case 'TOOL_CALL_START': {
+      const messages = patchMessageById(state.messages, action.messageId, (m) => ({
+        ...m,
+        toolCalls: [...(m.toolCalls ?? []), action.toolCall],
+      }));
+      return { ...state, messages };
+    }
+
+    case 'TOOL_CALL_DELTA': {
+      const messages = patchMessageById(state.messages, action.messageId, (m) => {
+        if (!m.toolCalls) return m;
+        return {
+          ...m,
+          toolCalls: m.toolCalls.map((tc) =>
+            tc.id === action.toolId
+              ? { ...tc, streamingText: (tc.streamingText ?? '') + action.delta }
+              : tc,
+          ),
+        };
+      });
+      return { ...state, messages };
+    }
+
+    case 'TOOL_CALL_END': {
+      const messages = patchMessageById(state.messages, action.messageId, (m) => {
+        if (!m.toolCalls) return m;
+        return {
+          ...m,
+          toolCalls: m.toolCalls.map((tc) =>
+            tc.id === action.toolId
+              ? {
+                  ...tc,
+                  output: action.output,
+                  status: action.status,
+                  streamingText: undefined,
+                  endedAt: Date.now(),
+                }
+              : tc,
+          ),
+        };
+      });
+      return { ...state, messages };
+    }
+
+    case 'STREAM_DONE': {
+      const messages = patchMessageById(state.messages, action.id, (m) => ({
+        ...m,
+        isStreaming: false,
+        tokensIn: action.tokensIn ?? m.tokensIn,
+        tokensOut: action.tokensOut ?? m.tokensOut,
+        sources: action.sources ?? m.sources,
+      }));
+      return { ...state, isStreaming: false, messages };
+    }
+
+    case 'STREAM_CANCELLED': {
+      const suffix = action.label ?? '[cancelled]';
+      const messages = patchMessageById(state.messages, action.id, (m) => ({
+        ...m,
+        isStreaming: false,
+        content: action.partialText + (action.partialText ? `\n\n_${suffix}_` : `_${suffix}_`),
+      }));
+      return { ...state, isStreaming: false, messages };
+    }
+
+    case 'STREAM_ERROR': {
+      const messages = action.id
+        ? patchMessageById(state.messages, action.id, (m) => ({
+            ...m,
+            isStreaming: false,
+            isError: true,
+          }))
+        : state.messages;
+      return { ...state, isStreaming: false, error: action.message, messages };
+    }
+
+    case 'MESSAGE_EDIT': {
+      const messages = patchMessageById(state.messages, action.id, (m) => ({
+        ...m,
+        content: action.content,
+        version: (m.version ?? 0) + 1,
+      }));
+      return { ...state, messages };
+    }
+
+    case 'MESSAGE_DELETE':
+      return {
+        ...state,
+        messages: state.messages.filter((m) => m.id !== action.id),
+      };
+
+    case 'MESSAGES_CLEAR':
+      return {
+        ...state,
+        messages: [],
+        isStreaming: false,
+        error: null,
+      };
+
+    case 'ERROR_SET':
+      return { ...state, error: action.error };
+
+    case 'ATTACHMENT_PROGRESS': {
+      const messages = patchMessageById(state.messages, action.messageId, (m) => {
+        if (!m.attachments) return m;
+        return {
+          ...m,
+          attachments: m.attachments.map((a) =>
+            a.id === action.attachmentId
+              ? {
+                  ...a,
+                  progress: action.progress ?? a.progress,
+                  status: action.status ?? a.status,
+                }
+              : a,
+          ),
+        };
+      });
+      return { ...state, messages };
+    }
+
+    default: {
+      // Exhaustiveness check.
+      const _exhaustive: never = action;
+      void _exhaustive;
+      return state;
+    }
+  }
+}

package/src/tools/Chat/core/transport/http.ts

@@ -0,0 +1,167 @@
+/**
+ * HTTP + SSE transport. Default implementation for web hosts.
+ *
+ * Backend contract (see @dev/@refactoring7-chat/06-integration.md):
+ *   POST   /sessions                     → SessionInfo (JSON)
+ *   GET    /sessions/:id/history?cursor= → HistoryPage (JSON)
+ *   POST   /sessions/:id/messages        → SSE stream of ChatStreamEvent
+ *   POST   /sessions/:id/messages/buffered → ChatMessage (JSON, fallback)
+ *   DELETE /sessions/:id                 → 204
+ */
+
+import type {
+  ChatMessage,
+  ChatStreamEvent,
+  ChatTransport,
+  CreateSessionOptions,
+  HistoryPage,
+  SendOptions,
+  SessionInfo,
+  StreamOptions,
+} from '../../types';
+import { TransportError } from './types';
+import { parseSSE } from './sse';
+
+export interface HttpTransportConfig {
+  /** Base URL without trailing slash, e.g. '/api/chat' or 'https://api.example.com/v1/chat'. */
+  baseUrl: string;
+  /** Optional slug appended/forwarded as project identifier. */
+  slug?: string;
+  /** Returns headers applied to every request — e.g. Authorization. */
+  getAuthHeader?: () => Record<string, string> | Promise<Record<string, string>>;
+  /** Default fetch timeout (per non-streaming request). */
+  timeoutMs?: number;
+  /** Override fetch implementation (useful for tests or custom retry layers). */
+  fetchImpl?: typeof fetch;
+}
+
+const DEFAULT_TIMEOUT = 20_000;
+
+async function jsonOrThrow<T>(res: Response, label: string): Promise<T> {
+  if (!res.ok) {
+    const text = await res.text().catch(() => '');
+    throw new TransportError(
+      `${label} failed (${res.status}): ${text || res.statusText}`,
+      mapStatusToCode(res.status),
+    );
+  }
+  try {
+    return (await res.json()) as T;
+  } catch {
+    throw new TransportError(`${label} returned invalid JSON`, 'invalid_response');
+  }
+}
+
+function mapStatusToCode(status: number): string {
+  if (status === 401) return 'unauthorized';
+  if (status === 403) return 'forbidden';
+  if (status === 404) return 'not_found';
+  if (status === 429) return 'rate_limited';
+  if (status >= 500) return 'server_error';
+  return 'http_error';
+}
+
+function withTimeout(signal: AbortSignal | undefined, timeoutMs: number): AbortSignal {
+  const ctrl = new AbortController();
+  const onAbort = () => ctrl.abort();
+  signal?.addEventListener('abort', onAbort, { once: true });
+  setTimeout(() => ctrl.abort(), timeoutMs);
+  return ctrl.signal;
+}
+
+export function createHttpTransport(config: HttpTransportConfig): ChatTransport {
+  const fetchImpl = config.fetchImpl ?? fetch;
+  const timeout = config.timeoutMs ?? DEFAULT_TIMEOUT;
+  const base = config.baseUrl.replace(/\/$/, '');
+
+  async function buildHeaders(extra?: Record<string, string>): Promise<Record<string, string>> {
+    const auth = (await config.getAuthHeader?.()) ?? {};
+    return {
+      'Content-Type': 'application/json',
+      ...auth,
+      ...(extra ?? {}),
+    };
+  }
+
+  return {
+    async createSession(opts?: CreateSessionOptions): Promise<SessionInfo> {
+      const res = await fetchImpl(`${base}/sessions`, {
+        method: 'POST',
+        headers: await buildHeaders(),
+        body: JSON.stringify({ slug: config.slug, metadata: opts?.metadata ?? {} }),
+        signal: withTimeout(undefined, timeout),
+      });
+      return jsonOrThrow<SessionInfo>(res, 'createSession');
+    },
+
+    async loadHistory(sessionId, cursor, limit): Promise<HistoryPage> {
+      const params = new URLSearchParams();
+      if (cursor) params.set('cursor', cursor);
+      if (limit) params.set('limit', String(limit));
+      const url = `${base}/sessions/${encodeURIComponent(sessionId)}/history${
+        params.toString() ? `?${params.toString()}` : ''
+      }`;
+      const res = await fetchImpl(url, {
+        method: 'GET',
+        headers: await buildHeaders(),
+        signal: withTimeout(undefined, timeout),
+      });
+      return jsonOrThrow<HistoryPage>(res, 'loadHistory');
+    },
+
+    async *stream(
+      sessionId: string,
+      content: string,
+      options: StreamOptions,
+    ): AsyncGenerator<ChatStreamEvent, void, void> {
+      const url = `${base}/sessions/${encodeURIComponent(sessionId)}/messages`;
+      const res = await fetchImpl(url, {
+        method: 'POST',
+        headers: await buildHeaders({ Accept: 'text/event-stream' }),
+        body: JSON.stringify({
+          content,
+          attachments: options.attachments ?? [],
+          metadata: options.metadata ?? {},
+        }),
+        signal: options.signal,
+      });
+
+      if (!res.ok) {
+        const text = await res.text().catch(() => '');
+        throw new TransportError(
+          `stream failed (${res.status}): ${text || res.statusText}`,
+          mapStatusToCode(res.status),
+        );
+      }
+
+      yield* parseSSE(res, { signal: options.signal });
+    },
+
+    async send(sessionId, content, options?: SendOptions): Promise<ChatMessage> {
+      const url = `${base}/sessions/${encodeURIComponent(sessionId)}/messages/buffered`;
+      const res = await fetchImpl(url, {
+        method: 'POST',
+        headers: await buildHeaders(),
+        body: JSON.stringify({
+          content,
+          attachments: options?.attachments ?? [],
+          metadata: options?.metadata ?? {},
+        }),
+        signal: options?.signal ?? withTimeout(undefined, timeout),
+      });
+      return jsonOrThrow<ChatMessage>(res, 'send');
+    },
+
+    async closeSession(sessionId: string): Promise<void> {
+      const url = `${base}/sessions/${encodeURIComponent(sessionId)}`;
+      const res = await fetchImpl(url, {
+        method: 'DELETE',
+        headers: await buildHeaders(),
+        signal: withTimeout(undefined, timeout),
+      });
+      if (!res.ok && res.status !== 404) {
+        throw new TransportError(`closeSession failed (${res.status})`, mapStatusToCode(res.status));
+      }
+    },
+  };
+}

package/src/tools/Chat/core/transport/index.ts

@@ -0,0 +1,13 @@
+export { createHttpTransport, type HttpTransportConfig } from './http';
+export { createMockTransport, type MockTransportOptions } from './mock';
+export { parseSSE, type ParseSSEOptions } from './sse';
+export { TransportError } from './types';
+export type {
+  ChatTransport,
+  ChatStreamEvent,
+  CreateSessionOptions,
+  SessionInfo,
+  HistoryPage,
+  StreamOptions,
+  SendOptions,
+} from './types';