@djangocfg/ui-tools 2.1.407 → 2.1.409

package/src/tools/Chat/public.ts

@@ -0,0 +1,212 @@
+'use client';
+
+/**
+ * Chat — shared "light surface".
+ *
+ * The single source of truth for everything safe to load synchronously:
+ * types, runtime constants, pure `core` + transports, hooks (no UI),
+ * notifier, payload-dispatch, logger, utils, styles, context.
+ *
+ * Both root entry points re-export this module verbatim:
+ * - `index.ts`  (`@djangocfg/ui-tools`)        — `public` + heavy sync components
+ * - `lazy.tsx`  (`@djangocfg/ui-tools/chat`)   — `public` + Lazy* wrappers
+ *
+ * Heavy UI components must NOT be added here — they belong in `index.ts`
+ * (sync) and `lazy.tsx` (lazy) only.
+ *
+ * `./chat` is the only sanctioned Chat subpath — do not add new subpaths
+ * (avoids the dual-bundle / two-React-context trap).
+ */
+
+// Types
+export type {
+  ChatRole,
+  ChatMessage,
+  ChatPersona,
+  ChatToolCall,
+  ChatAttachment,
+  ChatSource,
+  ChatDisplayMode,
+  ChatUserContext,
+  ChatAssistantContext,
+  ChatPrefs,
+  ChatConfig,
+  ChatLabels,
+  ChatTransport,
+  ChatStreamEvent,
+  CreateSessionOptions,
+  SessionInfo,
+  HistoryPage,
+  StreamOptions,
+  SendOptions,
+  MessageBlock,
+  MessageBlockKind,
+  BlockAppearance,
+  TextBlock,
+  MarkdownBlock,
+  AudioBlock,
+  VideoBlock,
+  ImageBlock,
+  GalleryBlock,
+  MapBlock,
+  JsonBlock,
+  MermaidBlock,
+  CodeBlock,
+  LottieBlock,
+  CustomBlock,
+} from './types';
+export { DEFAULT_LABELS } from './types';
+
+// Constants — plain runtime constants, no UI imports
+export {
+  STORAGE_KEYS,
+  CSS_VARS,
+  DEFAULT_Z_INDEX,
+  LIMITS,
+  DEFAULT_SIDEBAR,
+  HOTKEYS,
+  CHAT_EVENT_NAME,
+  type ChatEventDetail,
+} from './constants';
+
+// Core (pure) — reducer / id / token buffer / persona / initials
+export {
+  reducer,
+  initialState,
+  createId,
+  createTokenBuffer,
+  resolvePersona,
+  deriveInitials,
+  type ChatState,
+  type ChatAction,
+  type TokenBuffer,
+} from './core';
+
+// Transport — pure functions, no UI
+export {
+  createHttpTransport,
+  createMockTransport,
+  parseSSE,
+  TransportError,
+  createPydanticAIChatTransport,
+  createToolIdQueue,
+  mapPydanticAIEvent,
+  createPydanticAISSEMap,
+  type HttpTransportConfig,
+  type MockTransportOptions,
+  type ParseSSEOptions,
+  type PydanticAIChatTransportOpts,
+  type PydanticAIEvent,
+  type ToolIdQueue,
+} from './core/transport';
+
+// Hooks — React state glue, no JSX / UI components
+export {
+  useChat,
+  useChatComposer,
+  useChatHistory,
+  useChatLayout,
+  useChatAudio,
+  useAutoFocusOnStreamEnd,
+  useRegisterComposer,
+  useChatReset,
+  useVisitorFingerprint,
+  useChatDockPrefs,
+  DEFAULT_DOCK_PREFS,
+  useFocusOnEmptyClick,
+  useChatUnread,
+  useChatUnreadNotifier,
+  useChatLightbox,
+  type UseChatUnreadOptions,
+  type UseChatUnreadReturn,
+  type UseChatUnreadNotifierOptions,
+  type UseChatConfig,
+  type UseChatReturn,
+  type UseChatComposerOptions,
+  type UseChatComposerReturn,
+  type UseChatHistoryOptions,
+  type UseChatLayoutConfig,
+  type UseChatLayoutReturn,
+  type UseAutoFocusOnStreamEndOptions,
+  type Focusable,
+  type UseChatResetOptions,
+  type UseChatResetReturn,
+  type UseVisitorFingerprintOptions,
+  type ChatDockPrefs,
+  type UseChatDockPrefsOptions,
+  type UseChatDockPrefsReturn,
+  type UseFocusOnEmptyClickOptions,
+  type UseChatLightboxReturn,
+  type ChatLightboxState,
+  type ChatLightboxScope,
+} from './hooks';
+
+// Audio
+export {
+  useChatAudioPrefs,
+  DEFAULT_CHAT_SOUNDS,
+  type ChatAudioEvent,
+  type ChatAudioSounds,
+  type ChatAudioConfig,
+  type UseChatAudioReturn,
+} from './core/audio';
+
+// Notifier — title rotation + favicon badge + page-visibility + cross-tab
+export {
+  createBrowserNotifier,
+  createNoopNotifier,
+  createTitleRotator,
+  createFaviconBadge,
+  createCrossTabNotifier,
+  isPageHidden,
+  onVisibilityChange,
+  type ChatNotifier,
+  type BrowserNotifierOptions,
+  type TitleRotatorOptions,
+  type TitleMode,
+  type FaviconBadgeOptions,
+  type CrossTabNotifierOptions,
+} from './notifier';
+
+// Tool-call payload dispatcher — pure
+export {
+  dispatchToolPayload,
+  isPlainObject,
+  isLatLng,
+  isGeoJSONFeatureCollection,
+  isStringValue,
+  type ToolPayloadMatcher,
+  type ToolPayloadFallback,
+} from './core/payload-dispatch';
+
+// Dev logger (consola-based, namespace "chat:*")
+export { getChatLogger, type ChatLogger, type ChatLogScope } from './core/logger';
+
+// Utils — pure helpers
+export { sanitizeDraft, isSubmittableDraft, collectImageAttachments } from './utils';
+
+// Styles — role-aware className tokens + hooks
+export {
+  BUBBLE_SURFACE,
+  ANCHOR,
+  TOGGLE,
+  DESTRUCTIVE_SURFACE,
+  TOOL_CALL,
+  useChatBubbleStyles,
+  useChatRoleStyles,
+  useChatDestructiveStyles,
+  type ChatBubbleSurface,
+  type ChatBubbleStyles,
+  type ChatRoleStyles,
+  type ChatDestructiveStyles,
+} from './styles';
+
+// Context — provider + hooks for callers wiring custom chat shells
+export {
+  ChatProvider,
+  useChatContext,
+  useChatContextOptional,
+  type ChatContextValue,
+  type ChatProviderProps,
+  type ComposerHandle,
+} from './context';

package/src/tools/Chat/shell/ChatRoot.tsx

@@ -0,0 +1,345 @@
+'use client';
+
+import { type ReactNode, useMemo, useRef, useState } from 'react';
+
+import { cn } from '@djangocfg/ui-core/lib';
+
+import type { ChatAttachment, ChatConfig, ChatMessage, ChatTransport } from '../types';
+import type { ChatAudioConfig } from '../core/audio/types';
+import {
+  ChatProvider,
+  useChatContext,
+  useChatContextOptional,
+  type ChatContextValue,
+} from '../context';
+import { useChatComposer, type UseChatComposerReturn } from '../hooks/useChatComposer';
+import { useFocusOnEmptyClick } from '../hooks/useFocusOnEmptyClick';
+import { Composer } from '../composer/Composer';
+import type {
+  ComposerAppearance,
+  ComposerFooterProps,
+  ComposerLayout,
+  ComposerSize,
+  ComposerSlots,
+} from '../composer/types';
+import { EmptyState } from './EmptyState';
+import { ErrorBanner } from './ErrorBanner';
+import { JumpToLatest } from '../messages/JumpToLatest';
+import { MessageBubble } from '../messages/MessageBubble';
+import { MessageList, type MessageListHandle } from '../messages/MessageList';
+import type { AttachmentRendererMap } from '../messages/Attachments';
+import type { BlockRegistry } from '../messages/blocks';
+import type { ToolCallsProps } from '../messages/ToolCalls';
+
+/** Empty-state render API — seeds + focuses the composer from prompt chips. */
+export interface ChatEmptyApi {
+  setValue: (v: string) => void;
+  focus: () => void;
+}
+
+/** Full-replacement render API for the composer slot — the live composer
+ *  hook plus the resolved {@link ChatComposerConfig} that produced it.
+ *  One source of truth; no hand-mirrored field list. */
+export interface ChatComposerRenderApi {
+  composer: UseChatComposerReturn;
+  config: ChatComposerConfig;
+}
+
+/** Composer-region configuration for `<ChatRoot composer={…}>`. Groups
+ *  every knob that forwards into the built-in `<Composer>`. */
+export interface ChatComposerConfig {
+  /** Visual size variant. Default `md`. */
+  size?: ComposerSize;
+  /** Input-surface layout. Default `stacked` (`sm` → `inline`). */
+  layout?: ComposerLayout;
+  /** Extra className on the `<Composer>` wrapper. */
+  className?: string;
+  /** Hide the composer entirely (e.g. while waiting for human approval). */
+  hidden?: boolean;
+  /** Show the paperclip "attach" button. */
+  showAttachmentButton?: boolean;
+  /** Called when the user clicks the attach button. */
+  onPickFiles?: () => void;
+  /** Tier A declarative slots — action clusters + raw-node escape hatches. */
+  slots?: ComposerSlots;
+  /** Footer toolbar below the input surface. `false` hides it. */
+  footer?: ComposerFooterProps | false;
+  /** Full replacement — receives the live composer hook + this config. */
+  render?: (api: ChatComposerRenderApi) => ReactNode;
+}
+
+/** Named ReactNode slots for `<ChatRoot slots={…}>`. The `header` / `empty`
+ *  slots accept either a node or a render fn — no separate `renderX` prop. */
+export interface ChatSlots {
+  /** Sticky banner above the message list (e.g. quota warning). */
+  banner?: ReactNode;
+  /** Header row below the banner — node, or a fn given the chat context. */
+  header?: ReactNode | ((ctx: ChatContextValue) => ReactNode);
+  /** Replaces the default `<EmptyState>` — node, or a fn given a seed API. */
+  empty?: ReactNode | ((api: ChatEmptyApi) => ReactNode);
+  /** Replaces the default `<JumpToLatest>` floating pill. */
+  jumpToLatest?: ReactNode;
+}
+
+/** Message-rendering configuration for `<ChatRoot messages={…}>`. */
+export interface ChatMessagesConfig {
+  /** Replace `<MessageBubble>` per message. */
+  render?: (m: ChatMessage, i: number) => ReactNode;
+  /**
+   * Render arbitrary content beneath every default `<MessageBubble>`
+   * (not invoked when `render` is set — the host owns layout then).
+   */
+  renderAfter?: (m: ChatMessage) => ReactNode;
+  /** Forwarded into `<MessageBubble toolCallsProps>` to swap payload renderers. */
+  toolCallsProps?: Omit<ToolCallsProps, 'calls'>;
+  /** Per-type attachment renderers — `{ image, audio, video, file, default }`. */
+  attachmentRenderers?: AttachmentRendererMap;
+  /** Called when an attachment tile is clicked (e.g. open lightbox). */
+  onAttachmentOpen?: (attachment: ChatAttachment) => void;
+  /**
+   * Registry of `kind` → renderer for `message.blocks`. Merge host
+   * overrides over the defaults with `createBlockRegistry({ … })`.
+   * Omit to use `BUILTIN_BLOCK_REGISTRY`.
+   */
+  blockRegistry?: BlockRegistry;
+}
+
+export interface ChatRootProps {
+  // ---- core wiring -------------------------------------------------------
+  /**
+   * Transport. Required UNLESS `<ChatRoot>` is rendered inside an
+   * existing `<ChatProvider>` (e.g. mounted by `<ChatLauncher>`), in
+   * which case the ambient provider is reused and `transport` is
+   * ignored.
+   */
+  transport?: ChatTransport;
+  config?: ChatConfig;
+  /** Session wiring — pre-existing id to attach, auto-create toggle. */
+  session?: { initialId?: string; autoCreate?: boolean };
+  streaming?: boolean;
+  /** Audio-trigger configuration. Off by default (no `sounds` map). */
+  audio?: ChatAudioConfig;
+  /**
+   * Verbose dev-mode logging via `consola` (namespace `chat:*`).
+   * Defaults to `isDev` from `@djangocfg/ui-core/lib`.
+   */
+  debug?: boolean;
+
+  // ---- presentation ------------------------------------------------------
+  /** Spaciousness of the whole chat — scales bubbles + composer.
+   *  `compact` (default) for embedded chat, `full` for full-page. */
+  appearance?: ComposerAppearance;
+  /** Extra className on the `<ChatRoot>` wrapper. */
+  className?: string;
+  /** Extra className forwarded to the `<MessageList>` scroll container. */
+  listClassName?: string;
+
+  // ---- composition (grouped) --------------------------------------------
+  /** Named ReactNode slots — banner, header, empty, jumpToLatest. */
+  slots?: ChatSlots;
+  /** Composer-region configuration. */
+  composer?: ChatComposerConfig;
+  /** Message-rendering configuration. */
+  messages?: ChatMessagesConfig;
+
+  // ---- behavior ----------------------------------------------------------
+  /**
+   * Click in the message area → focus the composer (Slack / ChatGPT).
+   * @default true
+   */
+  focusOnEmptyClick?: boolean;
+  /**
+   * Contribute extra transport metadata, computed fresh per send.
+   * Forwarded to the `<ChatProvider>` this component creates — ignored
+   * when mounted under an ambient provider (set it on that provider
+   * instead). Used to attach the page-context snapshot.
+   */
+  getDynamicMetadata?: () => Record<string, unknown> | undefined;
+}
+
+export function ChatRoot(props: ChatRootProps) {
+  const {
+    transport,
+    config,
+    session,
+    streaming,
+    audio,
+    debug,
+    className,
+    listClassName,
+    getDynamicMetadata,
+    ...rest
+  } = props;
+  // When mounted under a launcher-owned `<ChatProvider>`, reuse that
+  // provider instead of wrapping in a second one. This lets host code
+  // freely nest `<ChatRoot>` inside `<ChatLauncher>` without losing
+  // `headerSlots` access to the same session / clearMessages / audio.
+  const ambient = useChatContextOptional();
+  if (ambient) {
+    return <ChatRootShell className={className} listClassName={listClassName} parts={rest} />;
+  }
+  if (!transport) {
+    throw new Error(
+      '<ChatRoot> requires `transport` when mounted outside a <ChatProvider>.',
+    );
+  }
+  return (
+    <ChatProvider
+      transport={transport}
+      config={config}
+      initialSessionId={session?.initialId}
+      autoCreateSession={session?.autoCreate}
+      streaming={streaming}
+      audio={audio}
+      debug={debug}
+      blockRegistry={rest.messages?.blockRegistry}
+      getDynamicMetadata={getDynamicMetadata}
+    >
+      <ChatRootShell className={className} listClassName={listClassName} parts={rest} />
+    </ChatProvider>
+  );
+}
+
+type ChatRootParts = Pick<
+  ChatRootProps,
+  'appearance' | 'slots' | 'composer' | 'messages' | 'focusOnEmptyClick'
+>;
+
+interface ChatRootShellProps {
+  className?: string;
+  listClassName?: string;
+  parts: ChatRootParts;
+}
+
+function ChatRootShell({ className, listClassName, parts }: ChatRootShellProps) {
+  const { slots = {}, composer: composerConfig = {}, messages = {} } = parts;
+  const chat = useChatContext();
+  const composer = useChatComposer({
+    onSubmit: (content, attachments) => chat.sendMessage(content, attachments),
+    disabled: chat.isStreaming,
+  });
+  const onMessagesMouseUp = useFocusOnEmptyClick({
+    enabled: parts.focusOnEmptyClick !== false,
+  });
+  // Stream-end composer re-focus is handled by `<ChatProvider>` — it
+  // covers every usage pattern, not just `ChatRoot`.
+  // MessageList (virtuoso) owns the scroll viewport. We talk to it via
+  // the imperative handle (scrollToBottom) and the `onAtBottomChange`
+  // callback (drives the pill).
+  const listRef = useRef<MessageListHandle | null>(null);
+  const [isAtBottom, setIsAtBottom] = useState(true);
+  // The id of the most-recent user-sent message — passed as
+  // `scrollAnchorId` so every send re-anchors the viewport.
+  const lastUserMessageId = useMemo(() => {
+    const msgs = chat.messages;
+    for (let i = msgs.length - 1; i >= 0; i -= 1) {
+      if (msgs[i].role === 'user') return msgs[i].id;
+    }
+    return null;
+  }, [chat.messages]);
+  const handleStartReached = chat.hasMore && !chat.isLoadingMore
+    ? () => void chat.loadMore()
+    : undefined;
+
+  const greeting = chat.config.greeting ?? 'How can I help?';
+  const description = chat.config.description;
+  const suggestions = chat.config.suggestions;
+
+  const headerNode = typeof slots.header === 'function'
+    ? slots.header(chat)
+    : slots.header;
+
+  const emptyNode = typeof slots.empty === 'function'
+    ? slots.empty({ setValue: composer.setValue, focus: composer.focus })
+    : (slots.empty ?? (
+        <EmptyState
+          greeting={greeting}
+          description={description}
+          suggestions={suggestions}
+          onPickSuggestion={(prompt) => {
+            composer.setValue(prompt);
+            composer.focus();
+          }}
+        />
+      ));
+
+  // `appearance` scales the whole chat (bubbles + composer). Default
+  // `compact` keeps every embedded chat pixel-identical.
+  const appearance: ComposerAppearance = parts.appearance ?? 'compact';
+
+  const renderItem = messages.render
+    ?? ((m: ChatMessage) => (
+      <MessageBubble
+        key={m.id}
+        message={m}
+        appearance={appearance}
+        toolCallsProps={messages.toolCallsProps}
+        attachmentRenderers={messages.attachmentRenderers}
+        blockRegistry={messages.blockRegistry}
+        onAttachmentOpen={messages.onAttachmentOpen}
+        renderAfterMessage={messages.renderAfter}
+        onCopy={() => copy(m.content)}
+        onRegenerate={() => void chat.regenerate(m.id)}
+        onDelete={() => chat.deleteMessage(m.id)}
+      />
+    ));
+
+  return (
+    <div className={cn('relative flex h-full min-h-0 flex-col overflow-hidden', className)}>
+      {slots.banner ?? null}
+      {headerNode ?? null}
+      <div className="relative flex min-h-0 flex-1 flex-col" onMouseUp={onMessagesMouseUp}>
+        <ErrorBanner
+          error={chat.error}
+          onDismiss={chat.error ? () => chat.clearMessages() : undefined}
+          onRetry={chat.error ? () => void chat.regenerate() : undefined}
+        />
+        <MessageList
+          ref={listRef}
+          renderItem={renderItem}
+          appearance={appearance}
+          renderEmpty={() => <>{emptyNode}</>}
+          className={listClassName}
+          onStartReached={handleStartReached}
+          onAtBottomChange={setIsAtBottom}
+          scrollAnchorId={lastUserMessageId}
+        />
+        <div className="pointer-events-none absolute inset-x-0 bottom-2 flex justify-center">
+          {slots.jumpToLatest ?? (
+            <JumpToLatest
+              visible={!isAtBottom}
+              onClick={() => listRef.current?.scrollToBottom(true)}
+            />
+          )}
+        </div>
+      </div>
+      {!composerConfig.hidden && (
+        composerConfig.render
+          ? composerConfig.render({ composer, config: composerConfig })
+          : (
+              <Composer
+                composer={composer}
+                placeholder={chat.config.placeholder}
+                showAttachmentButton={composerConfig.showAttachmentButton}
+                onPickFiles={composerConfig.onPickFiles}
+                size={composerConfig.size}
+                appearance={appearance}
+                layout={composerConfig.layout}
+                className={composerConfig.className}
+                composerSlots={composerConfig.slots}
+                footer={composerConfig.footer ?? {}}
+              />
+            )
+      )}
+    </div>
+  );
+}
+
+function copy(text: string) {
+  if (typeof navigator !== 'undefined' && navigator.clipboard) {
+    void navigator.clipboard.writeText(text);
+  }
+}
+
+// re-export for convenience: composer hook return is a common slot dependency
+export type { UseChatComposerReturn };

package/src/tools/Chat/{components → shell}/EmptyState.tsx

@@ -24,7 +24,9 @@ export function EmptyState({
       <div className="grid size-10 place-items-center rounded-full bg-muted">
         <Sparkles aria-hidden className="size-5 text-muted-foreground" />
       </div>
-      {greeting ? <h2 className="text-base font-semibold">{greeting}</h2> : null}
+      {greeting ? (
+        <h2 className="text-base font-semibold text-foreground">{greeting}</h2>
+      ) : null}
       {description ? (
         <p className="max-w-md text-sm text-muted-foreground">{description}</p>
       ) : null}
@@ -35,7 +37,7 @@ export function EmptyState({
               key={s.prompt}
               type="button"
               onClick={() => onPickSuggestion?.(s.prompt)}
-              className="rounded-lg border border-border bg-background/60 px-3 py-2 text-left text-xs hover:bg-accent"
+              className="rounded-lg border border-border bg-background/60 px-3 py-2 text-left text-xs text-foreground hover:bg-accent hover:text-accent-foreground"
             >
               {s.label}
             </button>

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

@@ -0,0 +1,15 @@
+'use client';
+
+/** Shell — composition-root pieces (ChatRoot preset, empty / error states). */
+
+export {
+  ChatRoot,
+  type ChatRootProps,
+  type ChatComposerConfig,
+  type ChatComposerRenderApi,
+  type ChatSlots,
+  type ChatMessagesConfig,
+  type ChatEmptyApi,
+} from './ChatRoot';
+export { EmptyState, type EmptyStateProps } from './EmptyState';
+export { ErrorBanner, type ErrorBannerProps } from './ErrorBanner';