@djangocfg/ui-tools 2.1.335 → 2.1.337

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

@@ -0,0 +1,134 @@
+/**
+ * In-memory chat transport for stories and tests. Replays scripted replies.
+ */
+
+import type {
+  ChatMessage,
+  ChatStreamEvent,
+  ChatTransport,
+  CreateSessionOptions,
+  HistoryPage,
+  SendOptions,
+  SessionInfo,
+  StreamOptions,
+} from '../../types';
+import { createId } from '../ids';
+
+export interface MockTransportOptions {
+  /** Each entry is the assistant's reply for one user turn. Strings are split
+   *  into chunks; arrays are taken as the exact event sequence (after a
+   *  prepended `message_start` and before a synthetic `message_end`). */
+  replies?: Array<string | ChatStreamEvent[]>;
+  latencyMs?: number;
+  /** Initial history returned by `createSession`. */
+  initialMessages?: ChatMessage[];
+  shouldFail?: (attempt: number) => boolean;
+}
+
+const DEFAULT_REPLY = 'Hi there!';
+
+function splitForStream(text: string, parts = 4): string[] {
+  if (!text) return [];
+  const chunkSize = Math.max(1, Math.ceil(text.length / parts));
+  const out: string[] = [];
+  for (let i = 0; i < text.length; i += chunkSize) {
+    out.push(text.slice(i, i + chunkSize));
+  }
+  return out;
+}
+
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+export function createMockTransport(opts: MockTransportOptions = {}): ChatTransport {
+  const replies = opts.replies?.length ? opts.replies : [DEFAULT_REPLY];
+  const latency = opts.latencyMs ?? 30;
+  const history: ChatMessage[] = [...(opts.initialMessages ?? [])];
+  let turn = 0;
+  let attempt = 0;
+
+  return {
+    async createSession(_opts?: CreateSessionOptions): Promise<SessionInfo> {
+      await sleep(latency);
+      return {
+        sessionId: createId('s'),
+        messages: history.length ? [...history] : undefined,
+        hasMore: false,
+        cursor: null,
+        resumed: history.length > 0,
+      };
+    },
+
+    async loadHistory(_sid, _cursor, _limit): Promise<HistoryPage> {
+      await sleep(latency);
+      return { messages: [], hasMore: false, nextCursor: null };
+    },
+
+    async *stream(
+      _sid: string,
+      content: string,
+      options: StreamOptions,
+    ): AsyncGenerator<ChatStreamEvent, void, void> {
+      attempt += 1;
+      if (opts.shouldFail?.(attempt)) {
+        throw new Error('mock transport scripted failure');
+      }
+
+      // Record the user message for any subsequent loadHistory.
+      history.push({
+        id: createId('u'),
+        role: 'user',
+        content,
+        createdAt: Date.now(),
+      });
+
+      const messageId = createId('a');
+      yield { type: 'message_start', messageId, sessionId: _sid };
+
+      const reply = replies[turn % replies.length];
+      turn += 1;
+
+      if (typeof reply === 'string') {
+        for (const piece of splitForStream(reply)) {
+          if (options.signal.aborted) return;
+          await sleep(latency);
+          yield { type: 'chunk', delta: piece };
+        }
+        yield { type: 'message_end', tokensIn: content.length, tokensOut: reply.length };
+      } else {
+        for (const ev of reply) {
+          if (options.signal.aborted) return;
+          await sleep(latency);
+          yield ev;
+        }
+        // If the script didn't end the message itself, do it for them.
+        const lastType = reply[reply.length - 1]?.type;
+        if (lastType !== 'message_end' && lastType !== 'error') {
+          yield { type: 'message_end' };
+        }
+      }
+    },
+
+    async send(_sid, content, _options?: SendOptions): Promise<ChatMessage> {
+      await sleep(latency);
+      const reply = replies[turn % replies.length];
+      turn += 1;
+      const text =
+        typeof reply === 'string'
+          ? reply
+          : reply
+              .filter((e) => e.type === 'chunk')
+              .map((e) => (e as { delta: string }).delta)
+              .join('');
+      return {
+        id: createId('a'),
+        role: 'assistant',
+        content: text || DEFAULT_REPLY,
+        createdAt: Date.now(),
+      };
+    },
+
+    async closeSession(_sid: string): Promise<void> {
+      // no-op
+    },
+  };
+}

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

@@ -0,0 +1,116 @@
+/**
+ * Server-Sent Events parser as an AsyncGenerator.
+ *
+ * Yields parsed events from a `Response` body. Handles the split-read case
+ * where `event:` and `data:` arrive in separate TCP packets. Skips malformed
+ * JSON gracefully. Honors AbortSignal (caller passes one to fetch).
+ */
+
+import type { ChatStreamEvent } from '../../types';
+import { LIMITS } from '../../config';
+
+interface RawEvent {
+  event?: string;
+  data?: string;
+}
+
+export interface ParseSSEOptions {
+  signal?: AbortSignal;
+  /** Map a raw SSE event to a ChatStreamEvent. Default: parse `data` as JSON
+   *  and assume the JSON shape already matches `ChatStreamEvent`. */
+  map?: (raw: RawEvent) => ChatStreamEvent | null;
+  idleTimeoutMs?: number;
+}
+
+const DEFAULT_MAP = (raw: RawEvent): ChatStreamEvent | null => {
+  if (!raw.data) return null;
+  try {
+    const parsed = JSON.parse(raw.data) as ChatStreamEvent;
+    if (raw.event && !('type' in parsed)) {
+      return { ...(parsed as object), type: raw.event } as ChatStreamEvent;
+    }
+    return parsed;
+  } catch {
+    return null;
+  }
+};
+
+export async function* parseSSE(
+  response: Response,
+  options: ParseSSEOptions = {},
+): AsyncGenerator<ChatStreamEvent, void, void> {
+  if (!response.body) {
+    throw new Error('SSE response has no body');
+  }
+
+  const map = options.map ?? DEFAULT_MAP;
+  const idleMs = options.idleTimeoutMs ?? LIMITS.sseIdleMs;
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = '';
+  let lastChunkAt = Date.now();
+
+  const idleCheck = () => {
+    if (Date.now() - lastChunkAt > idleMs) {
+      throw new Error(`SSE idle timeout (${idleMs}ms)`);
+    }
+  };
+
+  try {
+    while (true) {
+      if (options.signal?.aborted) {
+        return;
+      }
+      const { value, done } = await reader.read();
+      if (done) break;
+
+      lastChunkAt = Date.now();
+      buffer += decoder.decode(value, { stream: true });
+
+      // Split on blank line which delimits SSE events.
+      let separator = buffer.indexOf('\n\n');
+      while (separator !== -1) {
+        const rawBlock = buffer.slice(0, separator);
+        buffer = buffer.slice(separator + 2);
+
+        const raw = parseEventBlock(rawBlock);
+        const evt = map(raw);
+        if (evt) yield evt;
+
+        separator = buffer.indexOf('\n\n');
+      }
+
+      idleCheck();
+    }
+
+    // Flush any trailing partial event.
+    if (buffer.trim()) {
+      const raw = parseEventBlock(buffer);
+      const evt = map(raw);
+      if (evt) yield evt;
+    }
+  } finally {
+    try {
+      reader.releaseLock();
+    } catch {
+      /* ignore */
+    }
+  }
+}
+
+function parseEventBlock(block: string): RawEvent {
+  const out: RawEvent = {};
+  const lines = block.split(/\r?\n/);
+  const dataLines: string[] = [];
+  for (const line of lines) {
+    if (!line || line.startsWith(':')) continue;
+    const colon = line.indexOf(':');
+    if (colon === -1) continue;
+    const field = line.slice(0, colon).trim();
+    const value = line.slice(colon + 1).replace(/^ /, '');
+    if (field === 'event') out.event = value;
+    else if (field === 'data') dataLines.push(value);
+  }
+  if (dataLines.length) out.data = dataLines.join('\n');
+  return out;
+}

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

@@ -0,0 +1,24 @@
+/**
+ * Transport surface re-export. Lives in core so transport implementations
+ * never need to reach into the public types module.
+ */
+
+export type {
+  ChatTransport,
+  ChatStreamEvent,
+  CreateSessionOptions,
+  SessionInfo,
+  HistoryPage,
+  StreamOptions,
+  SendOptions,
+} from '../../types';
+
+export class TransportError extends Error {
+  code: string;
+
+  constructor(message: string, code = 'transport_error') {
+    super(message);
+    this.name = 'TransportError';
+    this.code = code;
+  }
+}

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

@@ -0,0 +1,26 @@
+'use client';
+
+export { useChat, type UseChatConfig, type UseChatReturn } from './useChat';
+export {
+  useChatComposer,
+  type UseChatComposerOptions,
+  type UseChatComposerReturn,
+} from './useChatComposer';
+export {
+  useChatScroll,
+  type UseChatScrollOptions,
+  type UseChatScrollReturn,
+} from './useChatScroll';
+export { useChatHistory, type UseChatHistoryOptions } from './useChatHistory';
+export {
+  useChatLayout,
+  type UseChatLayoutConfig,
+  type UseChatLayoutReturn,
+} from './useChatLayout';
+export { useChatAudio } from './useChatAudio';
+export {
+  useChatLightbox,
+  type UseChatLightboxReturn,
+  type ChatLightboxState,
+  type ChatLightboxScope,
+} from './useChatLightbox';