@djangocfg/ui-tools 2.1.334 → 2.1.336

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

@@ -0,0 +1,132 @@
+'use client';
+
+import { type RefObject, useCallback, useEffect, useRef, useState } from 'react';
+
+export interface UseChatScrollOptions {
+  containerRef: RefObject<HTMLElement | null>;
+  bottomRef: RefObject<HTMLElement | null>;
+  isStreaming?: boolean;
+  /** Distance from bottom (px) considered "at bottom". */
+  bottomThresholdPx?: number;
+  /** Bump key — increment when a new message arrives so the hook re-evaluates auto-scroll. */
+  messagesCount?: number;
+}
+
+export interface UseChatScrollReturn {
+  isAtBottom: boolean;
+  unreadCount: number;
+  scrollToBottom: (smooth?: boolean) => void;
+  resetUnread: () => void;
+}
+
+export function useChatScroll(options: UseChatScrollOptions): UseChatScrollReturn {
+  const {
+    containerRef,
+    bottomRef,
+    isStreaming = false,
+    bottomThresholdPx = 80,
+    messagesCount = 0,
+  } = options;
+
+  const [isAtBottom, setIsAtBottom] = useState(true);
+  const [unreadCount, setUnreadCount] = useState(0);
+  const lastCountRef = useRef(messagesCount);
+  const stickyRef = useRef(true);
+  const wasStreamingRef = useRef(isStreaming);
+
+  const scrollToBottom = useCallback(
+    (smooth = false) => {
+      const el = containerRef.current;
+      if (!el) return;
+      el.scrollTo({
+        top: el.scrollHeight,
+        behavior: smooth ? 'smooth' : 'auto',
+      });
+      stickyRef.current = true;
+      setIsAtBottom(true);
+      setUnreadCount(0);
+    },
+    [containerRef],
+  );
+
+  const resetUnread = useCallback(() => setUnreadCount(0), []);
+
+  // Track scroll position relative to bottom.
+  useEffect(() => {
+    const el = containerRef.current;
+    if (!el) return;
+    const onScroll = () => {
+      const distance = el.scrollHeight - el.scrollTop - el.clientHeight;
+      const atBottom = distance <= bottomThresholdPx;
+      stickyRef.current = atBottom;
+      setIsAtBottom(atBottom);
+      if (atBottom) setUnreadCount(0);
+    };
+    onScroll();
+    el.addEventListener('scroll', onScroll, { passive: true });
+    return () => {
+      el.removeEventListener('scroll', onScroll);
+    };
+  }, [containerRef, bottomThresholdPx]);
+
+  // Stick to bottom while streaming, and one extra rAF after stream ends so
+  // the final layout (markdown re-render, sources/tool-call panels) doesn't
+  // push the latest content out of view.
+  useEffect(() => {
+    const el = containerRef.current;
+    if (!el) return;
+
+    if (isStreaming) {
+      wasStreamingRef.current = true;
+      if (!stickyRef.current) return;
+      let raf = 0;
+      const tick = () => {
+        if (!stickyRef.current) return;
+        el.scrollTop = el.scrollHeight;
+        raf = requestAnimationFrame(tick);
+      };
+      raf = requestAnimationFrame(tick);
+      return () => cancelAnimationFrame(raf);
+    }
+
+    // Stream just ended — flush one more scroll on the next two frames so
+    // both markdown swap and any post-stream panel insertions are reflected.
+    if (wasStreamingRef.current && stickyRef.current) {
+      wasStreamingRef.current = false;
+      let raf1 = 0;
+      let raf2 = 0;
+      raf1 = requestAnimationFrame(() => {
+        el.scrollTop = el.scrollHeight;
+        raf2 = requestAnimationFrame(() => {
+          el.scrollTop = el.scrollHeight;
+        });
+      });
+      return () => {
+        cancelAnimationFrame(raf1);
+        cancelAnimationFrame(raf2);
+      };
+    }
+    wasStreamingRef.current = false;
+    return;
+  }, [containerRef, isStreaming]);
+
+  // On message count increase, decide whether to scroll or bump unread.
+  useEffect(() => {
+    if (messagesCount > lastCountRef.current) {
+      if (stickyRef.current) {
+        const el = containerRef.current;
+        if (el) el.scrollTop = el.scrollHeight;
+      } else {
+        setUnreadCount((n) => n + (messagesCount - lastCountRef.current));
+      }
+    }
+    lastCountRef.current = messagesCount;
+  }, [containerRef, messagesCount]);
+
+  // Watch bottom sentinel just for symmetry/future hooks.
+  useEffect(() => {
+    void bottomRef;
+  }, [bottomRef]);
+
+  return { isAtBottom, unreadCount, scrollToBottom, resetUnread };
+}

package/src/tools/Chat/index.ts

@@ -0,0 +1,158 @@
+'use client';
+
+/**
+ * @djangocfg/ui-tools — Chat
+ *
+ * Decomposed, transport-agnostic chat. See @dev/@refactoring7-chat/ for design.
+ */
+
+// Types
+export type {
+  ChatRole,
+  ChatMessage,
+  ChatPersona,
+  ChatToolCall,
+  ChatAttachment,
+  ChatSource,
+  ChatDisplayMode,
+  ChatUserContext,
+  ChatAssistantContext,
+  ChatPrefs,
+  ChatConfig,
+  ChatLabels,
+  ChatTransport,
+  ChatStreamEvent,
+  CreateSessionOptions,
+  SessionInfo,
+  HistoryPage,
+  StreamOptions,
+  SendOptions,
+} from './types';
+export { DEFAULT_LABELS } from './types';
+
+// Config
+export {
+  STORAGE_KEYS,
+  CSS_VARS,
+  DEFAULT_Z_INDEX,
+  LIMITS,
+  DEFAULT_SIDEBAR,
+  HOTKEYS,
+  CHAT_EVENT_NAME,
+  type ChatEventDetail,
+} from './config';
+
+// Core (pure)
+export {
+  reducer,
+  initialState,
+  createId,
+  createTokenBuffer,
+  resolvePersona,
+  deriveInitials,
+  type ChatState,
+  type ChatAction,
+  type TokenBuffer,
+} from './core';
+
+// Transport
+export {
+  createHttpTransport,
+  createMockTransport,
+  parseSSE,
+  TransportError,
+  type HttpTransportConfig,
+  type MockTransportOptions,
+  type ParseSSEOptions,
+} from './core/transport';
+
+// Hooks
+export {
+  useChat,
+  useChatComposer,
+  useChatScroll,
+  useChatHistory,
+  useChatLayout,
+  useChatAudio,
+  type UseChatConfig,
+  type UseChatReturn,
+  type UseChatComposerOptions,
+  type UseChatComposerReturn,
+  type UseChatScrollOptions,
+  type UseChatScrollReturn,
+  type UseChatHistoryOptions,
+  type UseChatLayoutConfig,
+  type UseChatLayoutReturn,
+} from './hooks';
+
+// Audio
+export type {
+  ChatAudioEvent,
+  ChatAudioSounds,
+  ChatAudioConfig,
+  UseChatAudioReturn,
+} from './core/audio';
+export { useChatAudioPrefs } from './core/audio';
+
+// Tool-call payload dispatcher
+export {
+  dispatchToolPayload,
+  isPlainObject,
+  isLatLng,
+  isGeoJSONFeatureCollection,
+  isStringValue,
+  type ToolPayloadMatcher,
+  type ToolPayloadFallback,
+} from './core/payload-dispatch';
+
+// Lightbox helpers
+export { useChatLightbox, type UseChatLightboxReturn, type ChatLightboxState } from './hooks';
+export { collectImageAttachments } from './utils/collectImageAttachments';
+
+// Context
+export {
+  ChatProvider,
+  useChatContext,
+  useChatContextOptional,
+  type ChatContextValue,
+  type ChatProviderProps,
+} from './context';
+
+// Components
+export {
+  ChatRoot,
+  MessageList,
+  MessageBubble,
+  MessageActions,
+  Composer,
+  Sources,
+  ToolCalls,
+  Attachments,
+  AttachmentsGrid,
+  AttachmentsList,
+  EmptyState,
+  ErrorBanner,
+  JumpToLatest,
+  StreamingIndicator,
+  type ChatRootProps,
+  type MessageListProps,
+  type MessageBubbleProps,
+  type MessageActionsProps,
+  type ComposerProps,
+  type SourcesProps,
+  type ToolCallsProps,
+  type ToolPayloadKind,
+  type AttachmentsProps,
+  type AttachmentsGridProps,
+  type AttachmentsListProps,
+  type AttachmentRenderer,
+  type AttachmentRendererArgs,
+  type AttachmentRendererMap,
+  type EmptyStateProps,
+  type ErrorBannerProps,
+  type JumpToLatestProps,
+  type StreamingIndicatorProps,
+} from './components';
+
+// Lazy preset
+export { LazyChat } from './lazy';

package/src/tools/Chat/lazy.tsx

@@ -0,0 +1,14 @@
+'use client';
+
+import { createLazyComponent, LoadingFallback } from '../../components/lazy-wrapper';
+import type { ChatRootProps } from './components/ChatRoot';
+
+export const LazyChat = createLazyComponent<ChatRootProps>(
+  () => import('./components/ChatRoot').then((m) => ({ default: m.ChatRoot })),
+  {
+    displayName: 'LazyChat',
+    fallback: <LoadingFallback minHeight={320} text="Loading chat…" />,
+  },
+);
+
+export type { ChatRootProps };

package/src/tools/Chat/types.ts

@@ -0,0 +1,237 @@
+/**
+ * Public types for the Chat tool.
+ *
+ * Shapes here are the contract between transport adapters, the reducer,
+ * the hooks layer and the components. Keep serializable (no Date, no Map).
+ */
+
+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;
+}
+
+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: '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>;
+}

package/src/tools/Chat/utils/collectImageAttachments.ts

@@ -0,0 +1,13 @@
+import type { ChatAttachment, ChatMessage } from '../types';
+
+/** Walk the conversation and collect image attachments in chronological order. */
+export function collectImageAttachments(messages: ChatMessage[]): ChatAttachment[] {
+  const out: ChatAttachment[] = [];
+  for (const m of messages) {
+    if (!m.attachments) continue;
+    for (const a of m.attachments) {
+      if (a.type === 'image') out.push(a);
+    }
+  }
+  return out;
+}

package/src/tools/JsonForm/JsonSchemaForm.tsx

@@ -121,6 +121,37 @@ export function JsonSchemaForm<T = any>(props: JsonSchemaFormProps<T>) {
     range: SliderWidget, // alias
   }), []);
 
+  // Validate uiSchema widget references and strip unknown ones so RJSF
+  // doesn't crash with "No widget 'xxx' for type 'yyy'".
+  const safeUiSchema = useMemo(() => {
+    if (!uiSchema) return uiSchema;
+    const known = new Set(Object.keys(widgets));
+    let dirty = false;
+
+    function walk(node: unknown): unknown {
+      if (!node || typeof node !== 'object') return node;
+      if (Array.isArray(node)) return node.map(walk);
+      const out: Record<string, unknown> = {};
+      for (const [k, v] of Object.entries(node as Record<string, unknown>)) {
+        if (k === 'ui:widget' && typeof v === 'string' && !known.has(v)) {
+          dirty = true;
+          if (isDev) {
+            consola.error(
+              `[JsonSchemaForm] Unknown widget "${v}" — falling back to default. ` +
+                `Available: ${[...known].filter((w) => w[0]?.toLowerCase() === w[0]).join(', ')}`,
+            );
+          }
+          continue; // drop unknown widget so RJSF picks the default
+        }
+        out[k] = walk(v);
+      }
+      return out;
+    }
+
+    const cleaned = walk(uiSchema) as UiSchema | undefined;
+    return dirty ? cleaned : uiSchema;
+  }, [uiSchema, widgets]);
+
   // Memoize templates to prevent recreation on every render
   const templates = useMemo(() => ({
     FieldTemplate,
@@ -181,7 +212,7 @@ export function JsonSchemaForm<T = any>(props: JsonSchemaFormProps<T>) {
     <div className={className} data-jsonform-density={density}>
       <Form
         schema={validatedSchema}
-        uiSchema={uiSchema as UiSchema | undefined}
+        uiSchema={safeUiSchema as UiSchema | undefined}
         formData={normalizedFormData}
         validator={validator}
         widgets={widgets}