@djangocfg/ui-tools 2.1.404 → 2.1.408

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

@@ -0,0 +1,143 @@
+'use client';
+
+import type { ComponentType, ReactNode } from 'react';
+
+import type { UseChatComposerReturn } from '../hooks/useChatComposer';
+
+/** Composer visual size — shared across the `<Composer>` API. */
+export type ComposerSize = 'sm' | 'md' | 'lg';
+
+/**
+ * Spaciousness of the input surface — orthogonal to `size`:
+ * - `compact` — default; embedded composer (FAB panel, dock).
+ * - `full`    — full-page chat; roomier surface, bigger textarea + padding.
+ */
+export type ComposerAppearance = 'compact' | 'full';
+
+/**
+ * Geometry of the input surface:
+ * - `stacked` — textarea on top, action bar pinned below, one bordered surface.
+ * - `inline`  — single horizontal row (compact; `size="sm"` defaults to this).
+ */
+export type ComposerLayout = 'stacked' | 'inline';
+
+/** Conditional visibility of an action, evaluated against composer state. */
+export type ComposerActionVisibility =
+  | 'streaming'
+  | 'empty'
+  | 'hasText'
+  | 'disabled';
+
+/**
+ * Declarative descriptor for one action-bar button (Tier A). The Composer
+ * renders these into consistent `<ComposerButton>`s — size, aria and tooltip
+ * are handled centrally so hosts cannot misalign anything.
+ */
+export interface ComposerAction {
+  /** Stable key. */
+  id: string;
+  /** Lucide icon element. */
+  icon: ReactNode;
+  /** Used as `aria-label` and tooltip — required for a11y. */
+  label: string;
+  onClick: () => void;
+  disabled?: boolean;
+  /** Toggle state → emits `aria-pressed`. */
+  pressed?: boolean;
+  /** `send` — theme-inverting filled circle (ChatGPT send button). */
+  variant?: 'ghost' | 'secondary' | 'primary' | 'send';
+  /** Hide the action when the composer is in this state. */
+  hideWhen?: ComposerActionVisibility;
+  /** Sort weight within its cluster (ascending). Built-ins reserve high values. */
+  order?: number;
+}
+
+/**
+ * Tier A — declarative slot arrays + raw-node escape hatches. Hosts supply
+ * action descriptors; the Composer owns the rendering.
+ */
+export interface ComposerSlots {
+  /** Bottom-left cluster. Built-in attach prepends here when enabled. */
+  actionsStart?: ComposerAction[];
+  /** Bottom-right cluster. Built-in mic/send append here. */
+  actionsEnd?: ComposerAction[];
+  /** Full-width row above the textarea (reply banner, custom tray). */
+  blockStart?: ReactNode;
+  /** Raw nodes placed left of the textarea in the `inline` layout. */
+  inlineStart?: ReactNode;
+  /** Raw nodes placed right of the textarea in the `inline` layout. */
+  inlineEnd?: ReactNode;
+}
+
+// ── Tier B — full slot replacement ─────────────────────────────────────────
+
+export interface SendButtonProps {
+  /** True while a reply is streaming — render the stop affordance. */
+  streaming: boolean;
+  disabled: boolean;
+  size: ComposerSize;
+  onSend: () => void;
+  onCancel?: () => void;
+}
+
+export interface AttachButtonProps {
+  disabled: boolean;
+  size: ComposerSize;
+  onClick: () => void;
+}
+
+export interface ComposerTextareaProps {
+  composer: UseChatComposerReturn;
+  placeholder: string;
+  disabled: boolean;
+  size: ComposerSize;
+  className?: string;
+}
+
+export interface ActionBarProps {
+  /** Already filtered + sorted by `useComposerActions`. */
+  actionsStart: ComposerAction[];
+  actionsEnd: ComposerAction[];
+  size: ComposerSize;
+  layout: ComposerLayout;
+  inlineStart?: ReactNode;
+  inlineEnd?: ReactNode;
+}
+
+/** Tier B — swap a primitive entirely. Each is optional. */
+export interface ComposerSlotComponents {
+  SendButton?: ComponentType<SendButtonProps>;
+  AttachButton?: ComponentType<AttachButtonProps>;
+  Textarea?: ComponentType<ComposerTextareaProps>;
+  /** Replace the whole `blockEnd` action-bar row. */
+  ActionBar?: ComponentType<ActionBarProps>;
+}
+
+/** Per-slot prop overrides forwarded to the built-in primitives. */
+export interface ComposerSlotProps {
+  send?: Partial<SendButtonProps>;
+  attach?: Partial<AttachButtonProps>;
+  textarea?: { className?: string };
+  actionBar?: { className?: string };
+}
+
+// ── Footer ─────────────────────────────────────────────────────────────────
+
+/** Props for the strip below the input surface. */
+export interface ComposerFooterProps {
+  start?: ReactNode;
+  center?: ReactNode;
+  end?: ReactNode;
+  /** Auto char counter — reads `composer.value` + `maxLength`. */
+  showCounter?: boolean;
+  /** Auto keyboard-shortcut hint — reads `submitOn`. @default false */
+  showHint?: boolean;
+  /** Live value, for the counter. */
+  value?: string;
+  /** Character cap, for the counter. */
+  maxLength?: number;
+  /** Submit binding, for the hint. */
+  submitOn?: 'enter' | 'cmd+enter';
+  size?: ComposerSize;
+  className?: string;
+}

package/src/tools/Chat/composer/useComposerActions.tsx

@@ -0,0 +1,164 @@
+'use client';
+
+import { useMemo } from 'react';
+import { ArrowUp, Paperclip, Square } from 'lucide-react';
+
+import type { UseChatComposerReturn } from '../hooks/useChatComposer';
+import type { ComposerAction } from './types';
+
+/** `order` values reserved for built-in actions so host extras land between. */
+const ORDER = {
+  attach: 100,
+  hostStart: 200,
+  hostEnd: 200,
+  mic: 800,
+  send: 900,
+} as const;
+
+export interface UseComposerActionsParams {
+  composer: UseChatComposerReturn;
+  isStreaming: boolean;
+  isDisabled: boolean;
+  /** Built-in attach action wiring. */
+  showAttachmentButton?: boolean;
+  onPickFiles?: () => void;
+  attachLabel?: string;
+  /** Host-supplied declarative clusters. */
+  actionsStart?: ComposerAction[];
+  actionsEnd?: ComposerAction[];
+  /** Send / stop wiring. */
+  onSend: () => void;
+  onCancel?: () => void;
+  sendLabel?: string;
+  stopLabel?: string;
+  /** Telegram-style mic↔send swap. When true (default), mic and send never
+   *  show together — mic when the draft is empty, send once there is text. */
+  micSendSwap?: boolean;
+}
+
+export interface ComposerActionClusters {
+  actionsStart: ComposerAction[];
+  actionsEnd: ComposerAction[];
+}
+
+/**
+ * Merges built-in send/stop/attach descriptors with host-provided arrays,
+ * applies `hideWhen` against live composer state, resolves the mic↔send
+ * swap, and sorts each cluster by `order`.
+ */
+export function useComposerActions(params: UseComposerActionsParams): ComposerActionClusters {
+  const {
+    composer,
+    isStreaming,
+    isDisabled,
+    showAttachmentButton,
+    onPickFiles,
+    attachLabel = 'Attach files',
+    actionsStart,
+    actionsEnd,
+    onSend,
+    onCancel,
+    sendLabel = 'Send',
+    stopLabel = 'Stop',
+    micSendSwap = true,
+  } = params;
+
+  const hasText = composer.canSubmit;
+  const canSubmit = composer.canSubmit;
+
+  return useMemo(() => {
+    const start: ComposerAction[] = [];
+    const end: ComposerAction[] = [];
+
+    if (showAttachmentButton) {
+      start.push({
+        id: 'attach',
+        icon: <Paperclip aria-hidden />,
+        label: attachLabel,
+        onClick: () => onPickFiles?.(),
+        disabled: isDisabled,
+        variant: 'ghost',
+        order: ORDER.attach,
+      });
+    }
+
+    for (const a of actionsStart ?? []) {
+      start.push({ order: ORDER.hostStart, ...a });
+    }
+    for (const a of actionsEnd ?? []) {
+      end.push({ order: ORDER.hostEnd, ...a });
+    }
+
+    // Send / stop. While streaming → stop; otherwise → send. Both are
+    // round, theme-inverting buttons (ChatGPT/Gemini style).
+    if (isStreaming) {
+      end.push({
+        id: 'stop',
+        icon: <Square aria-hidden />,
+        label: stopLabel,
+        onClick: () => onCancel?.(),
+        variant: 'send',
+        order: ORDER.send,
+      });
+    } else {
+      end.push({
+        id: 'send',
+        icon: <ArrowUp aria-hidden />,
+        label: sendLabel,
+        onClick: onSend,
+        disabled: !canSubmit,
+        variant: 'send',
+        order: ORDER.send,
+      });
+    }
+
+    // Apply `hideWhen` against the live composer state.
+    const visible = (a: ComposerAction): boolean => {
+      switch (a.hideWhen) {
+        case 'streaming':
+          return !isStreaming;
+        case 'empty':
+          return hasText;
+        case 'hasText':
+          return !hasText;
+        case 'disabled':
+          return !isDisabled;
+        default:
+          return true;
+      }
+    };
+
+    let filteredEnd = end.filter(visible);
+    const filteredStart = start.filter(visible);
+
+    // Mic↔send swap: when there is text and a mic action exists, drop the
+    // mic so only send shows. The host marks its mic with `id: 'mic'`
+    // (or `hideWhen: 'hasText'`); this is a safety net for the common id.
+    if (micSendSwap && hasText) {
+      filteredEnd = filteredEnd.filter((a) => a.id !== 'mic');
+    }
+
+    const byOrder = (a: ComposerAction, b: ComposerAction) =>
+      (a.order ?? 0) - (b.order ?? 0);
+
+    return {
+      actionsStart: filteredStart.sort(byOrder),
+      actionsEnd: filteredEnd.sort(byOrder),
+    };
+  }, [
+    showAttachmentButton,
+    attachLabel,
+    onPickFiles,
+    isDisabled,
+    actionsStart,
+    actionsEnd,
+    isStreaming,
+    stopLabel,
+    onCancel,
+    sendLabel,
+    onSend,
+    canSubmit,
+    hasText,
+    micSendSwap,
+  ]);
+}

package/src/tools/Chat/context/ChatProvider.tsx

@@ -13,10 +13,12 @@ import {
 
 import type { ChatConfig, ChatLabels, ChatTransport } from '../types';
 import { DEFAULT_LABELS } from '../types';
+import type { BlockRegistry } from '../messages/blocks';
 
 import { useChat, type UseChatReturn } from '../hooks/useChat';
 import { useChatLayout, type UseChatLayoutReturn } from '../hooks/useChatLayout';
 import { useChatAudio } from '../hooks/useChatAudio';
+import { useStreamEndFocus } from '../hooks/useStreamEndFocus';
 import type { ChatAudioConfig, UseChatAudioReturn } from '../core/audio/types';
 
 /** Imperative handle a composer (built-in or custom) registers so
@@ -60,6 +62,9 @@ export interface ChatContextValue extends UseChatReturn {
    *  null until any composer has mounted. Plan64 follow-up. */
   composer: ComposerHandle | null;
   registerComposer: (handle: ComposerHandle | null) => void;
+  /** Registry of `kind` → renderer for `message.blocks`. `null` when the
+   *  host wired none — `<MessageBubble>` then uses `BUILTIN_BLOCK_REGISTRY`. */
+  blockRegistry: BlockRegistry | null;
 }
 
 const Ctx = createContext<ChatContextValue | null>(null);
@@ -116,12 +121,31 @@ export interface ChatProviderProps {
   audio?: ChatAudioConfig;
   /** Enable verbose dev logging via consola. Defaults to `isDev`. */
   debug?: boolean;
+  /** Registry of `kind` → renderer for `message.blocks`. Stored in
+   *  context so nested `<ChatRoot>` / `<MessageBubble>` pick it up. */
+  blockRegistry?: BlockRegistry;
   /**
    * Rewrite outgoing message content before it hits the transport.
    * History bubble keeps the original; useful for stripping rich-
    * display chips so the LLM sees plain text. See `useChat`.
    */
   onBeforeSend?: (content: string) => string | Promise<string>;
+  /**
+   * Contribute extra transport metadata, computed fresh per send.
+   * Merged over the static metadata right before `transport.stream/send`.
+   * Keeps `Chat` decoupled from any specific metadata source — the host
+   * supplies the function (e.g. the page-context snapshot from
+   * `usePageSnapshot().getChatMetadata`).
+   */
+  getDynamicMetadata?: () => Record<string, unknown> | undefined;
+  /**
+   * Re-focus the registered composer on the streaming → idle edge —
+   * the standard chat UX (type → send → read → keep typing without
+   * reaching for the mouse). Default `true`. Works for every usage
+   * pattern (`ChatRoot`, hand-rolled `Composer` layout, headless) as
+   * long as a composer is registered. Set `false` to opt out.
+   */
+  autoFocusOnStreamEnd?: boolean;
   children?: ReactNode;
 }
 
@@ -133,7 +157,10 @@ export function ChatProvider({
   streaming,
   audio,
   debug,
+  blockRegistry,
   onBeforeSend,
+  getDynamicMetadata,
+  autoFocusOnStreamEnd = true,
   children,
 }: ChatProviderProps) {
   const audioApi = useChatAudio(audio ?? {});
@@ -155,7 +182,7 @@ export function ChatProvider({
     streaming,
     debug,
     metadata: {
-      locale: config.locale ?? config.prefs?.locale,
+      locale: config.prefs?.locale,
       slug: config.slug,
     },
     userPersona: config.user,
@@ -164,6 +191,7 @@ export function ChatProvider({
     onStreamStart,
     onError,
     onBeforeSend,
+    getDynamicMetadata,
   });
   const layout = useChatLayout({ defaultMode: 'embedded' });
 
@@ -206,9 +234,32 @@ export function ChatProvider({
     setComposer(handle);
   }, []);
 
+  // Re-focus the composer on the streaming → idle edge. Lives here (not
+  // in `ChatRoot`) so it works for *every* usage pattern — `ChatRoot`,
+  // a hand-rolled `ChatProvider` + `Composer` layout, or headless — as
+  // long as a composer registered its handle.
+  const composerRef = useRef<ComposerHandle | null>(composer);
+  composerRef.current = composer;
+  useStreamEndFocus({
+    isStreaming: chat.isStreaming,
+    enabled: autoFocusOnStreamEnd,
+    delayMs: 0,
+    resolveTarget: () => composerRef.current,
+  });
+
   const value = useMemo<ChatContextValue>(
-    () => ({ ...chat, layout, config, labels, audio: audioApi, hasAudio, composer, registerComposer }),
-    [chat, layout, config, labels, audioApi, hasAudio, composer, registerComposer],
+    () => ({
+      ...chat,
+      layout,
+      config,
+      labels,
+      audio: audioApi,
+      hasAudio,
+      composer,
+      registerComposer,
+      blockRegistry: blockRegistry ?? null,
+    }),
+    [chat, layout, config, labels, audioApi, hasAudio, composer, registerComposer, blockRegistry],
   );
 
   return (

package/src/tools/Chat/core/__tests__/metadata.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, it } from 'vitest';
+
+import { resolveSendMetadata, safeDynamicMetadata } from '../metadata';
+
+describe('resolveSendMetadata', () => {
+  it('passes static metadata through when there is no contributor', () => {
+    const result = resolveSendMetadata({ locale: 'en' }, undefined);
+    expect(result).toEqual({ locale: 'en' });
+  });
+
+  it('returns undefined when both static and dynamic are absent', () => {
+    expect(resolveSendMetadata(undefined, undefined)).toBeUndefined();
+  });
+
+  it('merges dynamic metadata over static metadata', () => {
+    const result = resolveSendMetadata(
+      { locale: 'en', slug: 'proj' },
+      () => ({ pageContext: { url: '/x' } }),
+    );
+    expect(result).toEqual({
+      locale: 'en',
+      slug: 'proj',
+      pageContext: { url: '/x' },
+    });
+  });
+
+  it('lets dynamic keys win on collision', () => {
+    const result = resolveSendMetadata(
+      { locale: 'en' },
+      () => ({ locale: 'fr' }),
+    );
+    expect(result).toEqual({ locale: 'fr' });
+  });
+
+  it('passes static through when the contributor returns undefined', () => {
+    const result = resolveSendMetadata({ locale: 'en' }, () => undefined);
+    expect(result).toEqual({ locale: 'en' });
+  });
+
+  it('does not break the send when the contributor throws', () => {
+    const result = resolveSendMetadata({ locale: 'en' }, () => {
+      throw new Error('capture failed');
+    });
+    // Falls back to static metadata — the send must still proceed.
+    expect(result).toEqual({ locale: 'en' });
+  });
+
+  it('produces a fresh object each call (no shared mutation)', () => {
+    const getDynamic = () => ({ n: 1 });
+    const a = resolveSendMetadata({ locale: 'en' }, getDynamic);
+    const b = resolveSendMetadata({ locale: 'en' }, getDynamic);
+    expect(a).not.toBe(b);
+    expect(a).toEqual(b);
+  });
+});
+
+describe('safeDynamicMetadata', () => {
+  it('returns the contributor result', () => {
+    expect(safeDynamicMetadata(() => ({ a: 1 }))).toEqual({ a: 1 });
+  });
+
+  it('swallows a throw and returns undefined', () => {
+    expect(
+      safeDynamicMetadata(() => {
+        throw new Error('boom');
+      }),
+    ).toBeUndefined();
+  });
+});

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

@@ -2,4 +2,26 @@ export { reducer, initialState, type ChatState, type ChatAction } from './reduce
 export { createId } from './ids';
 export { createTokenBuffer, type TokenBuffer } from './markdown';
 export { resolvePersona, deriveInitials } from './persona';
-export * from './transport';
+export {
+  createHttpTransport,
+  createMockTransport,
+  parseSSE,
+  TransportError,
+  createPydanticAIChatTransport,
+  createToolIdQueue,
+  mapPydanticAIEvent,
+  createPydanticAISSEMap,
+  type HttpTransportConfig,
+  type MockTransportOptions,
+  type ParseSSEOptions,
+  type ChatTransport,
+  type ChatStreamEvent,
+  type CreateSessionOptions,
+  type SessionInfo,
+  type HistoryPage,
+  type StreamOptions,
+  type SendOptions,
+  type PydanticAIChatTransportOpts,
+  type PydanticAIEvent,
+  type ToolIdQueue,
+} from './transport';

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

@@ -4,7 +4,7 @@
  * on fast streams.
  */
 
-import { LIMITS } from '../config';
+import { LIMITS } from '../constants';
 
 export interface TokenBuffer {
   /** Append a delta. Returns immediately. */

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

@@ -0,0 +1,47 @@
+/**
+ * Transport-metadata assembly.
+ *
+ * A chat send carries two kinds of metadata:
+ *   - static  — fixed per session (locale, slug), set once in config.
+ *   - dynamic — recomputed for every send by an optional contributor.
+ *
+ * The dynamic contributor is what enables "capture-on-submit" features
+ * (e.g. a fresh page-context snapshot per message): it runs synchronously
+ * at send time, and its result is merged over the static metadata.
+ */
+
+/** A function that produces extra metadata, freshly, at send time. */
+export type DynamicMetadataFn = () => Record<string, unknown> | undefined;
+
+/**
+ * Invoke a dynamic-metadata contributor, swallowing any throw.
+ *
+ * A contributor that fails (e.g. a snapshot capture errors) must never
+ * break a chat send — the send proceeds with the static metadata only.
+ */
+export function safeDynamicMetadata(
+  fn: DynamicMetadataFn,
+): Record<string, unknown> | undefined {
+  try {
+    return fn();
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Merge the static metadata with a per-send dynamic contributor.
+ *
+ * Called at each `transport.stream/send` so the contributor runs fresh.
+ * Dynamic keys win over static keys on collision. When there is no
+ * contributor (or it returns nothing) the static metadata passes
+ * through unchanged.
+ */
+export function resolveSendMetadata(
+  staticMetadata: Record<string, unknown> | undefined,
+  getDynamic: DynamicMetadataFn | undefined,
+): Record<string, unknown> | undefined {
+  const dynamic = getDynamic ? safeDynamicMetadata(getDynamic) : undefined;
+  if (!dynamic) return staticMetadata;
+  return { ...staticMetadata, ...dynamic };
+}

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

@@ -8,7 +8,7 @@
 import type { ReactNode } from 'react';
 
 import type { ChatToolCall } from '../types';
-import type { ToolPayloadKind } from '../components/ToolCalls';
+import type { ToolPayloadKind } from '../messages/ToolCalls';
 
 export interface ToolPayloadMatcher {
   /** Cheap predicate. First match wins. */