@djangocfg/ui-tools 2.1.335 → 2.1.337

package/src/tools/Chat/components/Attachments.tsx

@@ -0,0 +1,192 @@
+'use client';
+
+import { type ReactNode } from 'react';
+import { File as FileIcon, X } from 'lucide-react';
+
+import { cn } from '@djangocfg/ui-core/lib';
+
+import type { ChatAttachment } from '../types';
+
+export interface AttachmentRendererArgs {
+  attachment: ChatAttachment;
+  /** True when shown inside the composer's staging tray (denser layout). */
+  isInComposer: boolean;
+  onClick?: () => void;
+  onRemove?: () => void;
+}
+
+export type AttachmentRenderer = (args: AttachmentRendererArgs) => ReactNode;
+
+export interface AttachmentRendererMap {
+  image?: AttachmentRenderer;
+  audio?: AttachmentRenderer;
+  video?: AttachmentRenderer;
+  file?: AttachmentRenderer;
+  /** Fallback renderer when no per-type entry matched. */
+  default?: AttachmentRenderer;
+}
+
+interface CommonProps {
+  attachments: ChatAttachment[];
+  maxVisible?: number;
+  onClick?: (a: ChatAttachment) => void;
+  onRemove?: (a: ChatAttachment) => void;
+  isInComposer?: boolean;
+  className?: string;
+}
+
+// ---------------------------------------------------------------------------
+// AttachmentsGrid — flex-wrap, ideal for thumbnails / file chips.
+// ---------------------------------------------------------------------------
+
+export interface AttachmentsGridProps extends CommonProps {
+  layout?: 'wrap' | 'grid';
+}
+
+export function AttachmentsGrid({
+  attachments,
+  maxVisible,
+  onClick,
+  onRemove,
+  isInComposer = false,
+  layout = 'wrap',
+  className,
+}: AttachmentsGridProps) {
+  if (!attachments?.length) return null;
+  const visible = maxVisible ? attachments.slice(0, maxVisible) : attachments;
+  return (
+    <div
+      className={cn(
+        layout === 'grid' ? 'grid grid-cols-3 gap-2' : 'flex flex-wrap gap-2',
+        className,
+      )}
+    >
+      {visible.map((a) => (
+        <AttachmentTile
+          key={a.id}
+          attachment={a}
+          isInComposer={isInComposer}
+          onClick={onClick ? () => onClick(a) : undefined}
+          onRemove={onRemove ? () => onRemove(a) : undefined}
+        />
+      ))}
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// AttachmentsList — vertical stack, designed for rich custom renderers
+// (LazyAudioPlayer, video players, document previews).
+// ---------------------------------------------------------------------------
+
+export interface AttachmentsListProps extends CommonProps {
+  /** Per-type renderer overrides. Falls back to the default tile. */
+  renderers?: AttachmentRendererMap;
+}
+
+export function AttachmentsList({
+  attachments,
+  maxVisible,
+  onClick,
+  onRemove,
+  renderers,
+  isInComposer = false,
+  className,
+}: AttachmentsListProps) {
+  if (!attachments?.length) return null;
+  const visible = maxVisible ? attachments.slice(0, maxVisible) : attachments;
+  return (
+    <div className={cn('flex w-full flex-col gap-2', className)}>
+      {visible.map((a) => {
+        const renderer = renderers?.[a.type] ?? renderers?.default;
+        const args: AttachmentRendererArgs = {
+          attachment: a,
+          isInComposer,
+          onClick: onClick ? () => onClick(a) : undefined,
+          onRemove: onRemove ? () => onRemove(a) : undefined,
+        };
+        if (renderer) {
+          return (
+            <div key={a.id} className="relative w-full min-w-0">
+              {renderer(args)}
+              {args.onRemove ? <RemoveBtn onRemove={args.onRemove} /> : null}
+            </div>
+          );
+        }
+        return <AttachmentTile key={a.id} {...args} />;
+      })}
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Attachments — backwards-compatible facade. Picks the right component based
+// on whether `renderers` are supplied. Existing call-sites keep working.
+// ---------------------------------------------------------------------------
+
+export interface AttachmentsProps extends CommonProps {
+  layout?: 'grid' | 'row';
+  renderers?: AttachmentRendererMap;
+}
+
+export function Attachments(props: AttachmentsProps) {
+  const { renderers, layout, ...rest } = props;
+  if (renderers) {
+    return <AttachmentsList {...rest} renderers={renderers} />;
+  }
+  return <AttachmentsGrid {...rest} layout={layout === 'grid' ? 'grid' : 'wrap'} />;
+}
+
+// ---------------------------------------------------------------------------
+// Tile + remove btn (default renderers).
+// ---------------------------------------------------------------------------
+
+function AttachmentTile({ attachment, onClick, onRemove }: AttachmentRendererArgs) {
+  const isImage = attachment.type === 'image';
+  const isUploading = attachment.status === 'uploading';
+
+  const inner = isImage ? (
+    <img
+      src={attachment.thumbnailUrl ?? attachment.url}
+      alt={attachment.name ?? 'attachment'}
+      className="h-16 w-16 rounded-md object-cover"
+      loading="lazy"
+    />
+  ) : (
+    <div className="flex max-w-44 items-center gap-2 rounded-md border border-border bg-background/60 px-2 py-1.5 text-xs">
+      <FileIcon aria-hidden className="size-4 shrink-0 text-muted-foreground" />
+      <span className="truncate">{attachment.name ?? 'file'}</span>
+    </div>
+  );
+
+  return (
+    <div className="relative">
+      {onClick ? (
+        <button type="button" onClick={onClick} className="block">
+          {inner}
+        </button>
+      ) : (
+        inner
+      )}
+      {isUploading ? (
+        <div className="pointer-events-none absolute inset-0 flex items-center justify-center rounded-md bg-background/70 text-[10px] font-medium">
+          {attachment.progress != null ? `${Math.round(attachment.progress * 100)}%` : '…'}
+        </div>
+      ) : null}
+      {onRemove ? <RemoveBtn onRemove={onRemove} /> : null}
+    </div>
+  );
+}
+
+function RemoveBtn({ onRemove }: { onRemove: () => void }) {
+  return (
+    <button
+      type="button"
+      aria-label="Remove attachment"
+      onClick={onRemove}
+      className="absolute -right-1.5 -top-1.5 grid h-4 w-4 place-items-center rounded-full border border-border bg-background text-muted-foreground hover:bg-destructive hover:text-destructive-foreground"
+    >
+      <X aria-hidden className="size-2.5" />
+    </button>
+  );
+}

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

@@ -0,0 +1,208 @@
+'use client';
+
+import { type ReactNode, useRef } 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, type ChatContextValue } from '../context';
+import { useChatComposer, type UseChatComposerReturn } from '../hooks/useChatComposer';
+import { useChatScroll } from '../hooks/useChatScroll';
+import { useChatHistory } from '../hooks/useChatHistory';
+import { Composer } from './Composer';
+import { EmptyState } from './EmptyState';
+import { ErrorBanner } from './ErrorBanner';
+import { JumpToLatest } from './JumpToLatest';
+import { MessageBubble } from './MessageBubble';
+import { MessageList } from './MessageList';
+import type { AttachmentRendererMap } from './Attachments';
+import type { ToolCallsProps } from './ToolCalls';
+
+export interface ChatRootProps {
+  // ---- core wiring -------------------------------------------------------
+  transport: ChatTransport;
+  config?: ChatConfig;
+  initialSessionId?: string;
+  autoCreateSession?: 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`. Pass `false` to silence
+   * even in development, or `true` to force on in production for debugging.
+   */
+  debug?: boolean;
+  className?: string;
+
+  // ---- named ReactNode slots --------------------------------------------
+  /** Sticky banner above the message list (e.g. quota warning). */
+  banner?: ReactNode;
+  /** Header row below the banner — title / actions / session switcher. */
+  header?: ReactNode;
+  /** Footer slot below the composer (disclaimers, model picker). */
+  footer?: ReactNode;
+  /** Replaces the default `<EmptyState>` rendered when the conversation is empty. */
+  empty?: ReactNode;
+  /** Slot left of the textarea inside `<Composer>`. */
+  composerToolbarStart?: ReactNode;
+  /** Slot right of the textarea inside `<Composer>`. */
+  composerToolbarEnd?: ReactNode;
+  /** Replaces the default attachment tray inside `<Composer>`. */
+  composerAttachmentTray?: ReactNode;
+  /** Replaces the default `<JumpToLatest>` floating pill. */
+  jumpToLatest?: ReactNode;
+
+  // ---- render-prop slots (need access to data) --------------------------
+  /** Replace `<MessageBubble>` per message. */
+  renderMessage?: (m: ChatMessage, i: number) => ReactNode;
+  /** Render the header lazily — receives the chat context. */
+  renderHeader?: (ctx: ChatContextValue) => ReactNode;
+  /** Render the empty-state lazily — receives a `setValue` to seed the composer. */
+  renderEmpty?: (api: { setValue: (v: string) => void; focus: () => void }) => ReactNode;
+  /** Forwarded into `<MessageBubble toolCallsProps>` so hosts can 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;
+
+  // ---- composer customization -------------------------------------------
+  /** Show the paperclip "attach" button in the composer. */
+  showAttachmentButton?: boolean;
+  /** Called when the user clicks the attach button (host opens its file picker). */
+  onPickFiles?: () => void;
+}
+
+export function ChatRoot(props: ChatRootProps) {
+  const { transport, config, initialSessionId, autoCreateSession, streaming, audio, debug, className, ...slots } = props;
+  return (
+    <ChatProvider
+      transport={transport}
+      config={config}
+      initialSessionId={initialSessionId}
+      autoCreateSession={autoCreateSession}
+      streaming={streaming}
+      audio={audio}
+      debug={debug}
+    >
+      <ChatRootShell className={className} slots={slots} />
+    </ChatProvider>
+  );
+}
+
+interface ChatRootShellProps {
+  className?: string;
+  slots: Omit<ChatRootProps, 'transport' | 'config' | 'initialSessionId' | 'autoCreateSession' | 'streaming' | 'audio' | 'debug' | 'className'>;
+}
+
+function ChatRootShell({ className, slots }: ChatRootShellProps) {
+  const chat = useChatContext();
+  const composer = useChatComposer({
+    onSubmit: (content, attachments) => chat.sendMessage(content, attachments),
+    disabled: chat.isStreaming,
+  });
+  const containerRef = useRef<HTMLDivElement | null>(null);
+  const bottomRef = useRef<HTMLDivElement | null>(null);
+  const topRef = useRef<HTMLDivElement | null>(null);
+
+  const scroll = useChatScroll({
+    containerRef,
+    bottomRef,
+    isStreaming: chat.isStreaming,
+    messagesCount: chat.messages.length,
+  });
+
+  useChatHistory({
+    containerRef,
+    topSentinelRef: topRef,
+    hasMore: chat.hasMore,
+    isLoadingMore: chat.isLoadingMore,
+    loadMore: chat.loadMore,
+  });
+
+  const greeting = chat.config.greeting ?? 'How can I help?';
+  const description = chat.config.description;
+  const suggestions = chat.config.suggestions;
+
+  const headerNode = slots.renderHeader ? slots.renderHeader(chat) : slots.header;
+
+  const emptyNode = slots.empty
+    ?? (slots.renderEmpty
+      ? slots.renderEmpty({ setValue: composer.setValue, focus: composer.focus })
+      : (
+          <EmptyState
+            greeting={greeting}
+            description={description}
+            suggestions={suggestions}
+            onPickSuggestion={(prompt) => {
+              composer.setValue(prompt);
+              composer.focus();
+            }}
+          />
+        ));
+
+  const renderItem = slots.renderMessage
+    ?? ((m: ChatMessage) => (
+      <MessageBubble
+        key={m.id}
+        message={m}
+        toolCallsProps={slots.toolCallsProps}
+        attachmentRenderers={slots.attachmentRenderers}
+        onAttachmentOpen={slots.onAttachmentOpen}
+        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">
+        <ErrorBanner
+          error={chat.error}
+          onDismiss={chat.error ? () => chat.clearMessages() : undefined}
+          onRetry={chat.error ? () => void chat.regenerate() : undefined}
+        />
+        <MessageList
+          ref={containerRef}
+          topSentinelRef={topRef}
+          bottomRef={bottomRef}
+          renderItem={renderItem}
+          renderEmpty={() => <>{emptyNode}</>}
+        />
+        <div className="pointer-events-none absolute inset-x-0 bottom-2 flex justify-center">
+          {slots.jumpToLatest ?? (
+            <JumpToLatest
+              visible={!scroll.isAtBottom}
+              unreadCount={scroll.unreadCount}
+              onClick={() => scroll.scrollToBottom(true)}
+            />
+          )}
+        </div>
+      </div>
+      <Composer
+        composer={composer}
+        placeholder={chat.config.placeholder}
+        showAttachmentButton={slots.showAttachmentButton}
+        onPickFiles={slots.onPickFiles}
+        toolbarStart={slots.composerToolbarStart}
+        toolbarEnd={slots.composerToolbarEnd}
+        attachmentTray={slots.composerAttachmentTray}
+      />
+      {slots.footer ?? null}
+    </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/Composer.tsx

@@ -0,0 +1,134 @@
+'use client';
+
+import { type ReactNode, forwardRef } from 'react';
+import { Paperclip, Send, Square } from 'lucide-react';
+
+import { Button, Textarea } from '@djangocfg/ui-core/components';
+import { cn } from '@djangocfg/ui-core/lib';
+
+import { useChatContextOptional } from '../context';
+import type { UseChatComposerReturn } from '../hooks/useChatComposer';
+import { Attachments } from './Attachments';
+
+export interface ComposerProps {
+  composer: UseChatComposerReturn;
+  placeholder?: string;
+  disabled?: boolean;
+  showAttachmentButton?: boolean;
+  onPickFiles?: () => void;
+  toolbarStart?: ReactNode;
+  toolbarEnd?: ReactNode;
+  attachmentTray?: ReactNode;
+  className?: string;
+  textareaClassName?: string;
+  /** Show "Stop" button instead of "Send" while streaming. */
+  isStreaming?: boolean;
+  onCancel?: () => void;
+}
+
+export const Composer = forwardRef<HTMLDivElement, ComposerProps>(function Composer(
+  {
+    composer,
+    placeholder = 'Type a message...',
+    disabled,
+    showAttachmentButton = false,
+    onPickFiles,
+    toolbarStart,
+    toolbarEnd,
+    attachmentTray,
+    className,
+    textareaClassName,
+    isStreaming: isStreamingProp,
+    onCancel: onCancelProp,
+  },
+  ref,
+) {
+  const ctx = useChatContextOptional();
+  const isStreaming = isStreamingProp ?? ctx?.isStreaming ?? false;
+  const onCancel = onCancelProp ?? ctx?.cancelStream;
+  const isDisabled = disabled ?? isStreaming;
+
+  return (
+    <div
+      ref={ref}
+      className={cn(
+        'border-t border-border bg-background/95 px-2.5 pt-2 pb-[max(0.5rem,env(safe-area-inset-bottom))]',
+        className,
+      )}
+    >
+      {composer.attachments.length > 0 ? (
+        <div className="mb-1.5">
+          {attachmentTray ?? (
+            <Attachments
+              attachments={composer.attachments}
+              onRemove={(a) => composer.removeAttachment(a.id)}
+            />
+          )}
+        </div>
+      ) : null}
+
+      {/* `[&>*]:h-9` enforces a consistent 36px slot height so toolbar
+       *   buttons line up with the textarea baseline (`min-h-[36px]`).
+       *   Toolbar slots that want to opt out can pass an explicit class
+       *   like `!h-auto`. */}
+      <div className="flex items-end gap-1.5 [&>:not(textarea)]:shrink-0 [&>:not(textarea)]:h-9">
+        {showAttachmentButton ? (
+          <Button
+            type="button"
+            variant="ghost"
+            size="icon"
+            onClick={onPickFiles}
+            aria-label="Attach files"
+            disabled={isDisabled}
+            className="h-9 w-9"
+          >
+            <Paperclip aria-hidden className="size-4" />
+          </Button>
+        ) : null}
+
+        {toolbarStart}
+
+        <Textarea
+          {...composer.textareaProps}
+          rows={1}
+          placeholder={placeholder}
+          aria-label={placeholder}
+          aria-multiline="true"
+          disabled={isDisabled}
+          className={cn(
+            'min-h-9 max-h-60 flex-1 resize-none rounded-2xl px-3.5 py-2 text-base sm:text-sm',
+            textareaClassName,
+          )}
+        />
+
+        {toolbarEnd}
+
+        {isStreaming ? (
+          <Button
+            type="button"
+            variant="secondary"
+            size="icon"
+            onClick={onCancel}
+            aria-label="Stop"
+            aria-keyshortcuts="Escape"
+            className="h-9 w-9"
+          >
+            <Square aria-hidden className="size-3.5" />
+          </Button>
+        ) : (
+          <Button
+            type="button"
+            size="icon"
+            onClick={() => void composer.submit()}
+            disabled={!composer.canSubmit}
+            aria-label="Send"
+            aria-keyshortcuts="Enter"
+            className="h-9 w-9"
+          >
+            <Send aria-hidden className="size-4" />
+          </Button>
+        )}
+      </div>
+    </div>
+  );
+});

package/src/tools/Chat/components/EmptyState.tsx

@@ -0,0 +1,47 @@
+'use client';
+
+import { Sparkles } from 'lucide-react';
+
+import { cn } from '@djangocfg/ui-core/lib';
+
+export interface EmptyStateProps {
+  greeting?: string;
+  description?: string;
+  suggestions?: Array<{ label: string; prompt: string }>;
+  onPickSuggestion?: (prompt: string) => void;
+  className?: string;
+}
+
+export function EmptyState({
+  greeting,
+  description,
+  suggestions,
+  onPickSuggestion,
+  className,
+}: EmptyStateProps) {
+  return (
+    <div className={cn('flex flex-col items-center gap-3 px-4 py-12 text-center', className)}>
+      <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}
+      {description ? (
+        <p className="max-w-md text-sm text-muted-foreground">{description}</p>
+      ) : null}
+      {suggestions?.length ? (
+        <div className="mt-2 grid w-full max-w-md grid-cols-1 gap-2 sm:grid-cols-2">
+          {suggestions.map((s) => (
+            <button
+              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"
+            >
+              {s.label}
+            </button>
+          ))}
+        </div>
+      ) : null}
+    </div>
+  );
+}

package/src/tools/Chat/components/ErrorBanner.tsx

@@ -0,0 +1,47 @@
+'use client';
+
+import { AlertCircle, RefreshCw, X } from 'lucide-react';
+
+import { cn } from '@djangocfg/ui-core/lib';
+
+export interface ErrorBannerProps {
+  error: string | null;
+  onDismiss?: () => void;
+  onRetry?: () => void;
+  className?: string;
+}
+
+export function ErrorBanner({ error, onDismiss, onRetry, className }: ErrorBannerProps) {
+  if (!error) return null;
+  return (
+    <div
+      role="alert"
+      className={cn(
+        'mx-2.5 my-2 flex items-start gap-2 rounded-md border border-destructive/40 bg-destructive/10 px-3 py-2 text-xs text-destructive',
+        className,
+      )}
+    >
+      <AlertCircle aria-hidden className="mt-0.5 size-3.5 shrink-0" />
+      <p className="min-w-0 flex-1 break-words">{error}</p>
+      {onRetry ? (
+        <button
+          type="button"
+          onClick={onRetry}
+          className="inline-flex items-center gap-1 rounded px-1.5 py-0.5 hover:bg-destructive/15"
+        >
+          <RefreshCw aria-hidden className="size-3" /> Retry
+        </button>
+      ) : null}
+      {onDismiss ? (
+        <button
+          type="button"
+          aria-label="Dismiss"
+          onClick={onDismiss}
+          className="rounded p-0.5 hover:bg-destructive/15"
+        >
+          <X aria-hidden className="size-3" />
+        </button>
+      ) : null}
+    </div>
+  );
+}

package/src/tools/Chat/components/JumpToLatest.tsx

@@ -0,0 +1,30 @@
+'use client';
+
+import { ArrowDown } from 'lucide-react';
+
+import { cn } from '@djangocfg/ui-core/lib';
+
+export interface JumpToLatestProps {
+  visible?: boolean;
+  unreadCount?: number;
+  onClick?: () => void;
+  className?: string;
+}
+
+export function JumpToLatest({ visible, unreadCount = 0, onClick, className }: JumpToLatestProps) {
+  if (!visible) return null;
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      aria-live="polite"
+      className={cn(
+        'pointer-events-auto inline-flex items-center gap-1.5 rounded-full border border-border bg-background px-3 py-1 text-xs shadow-md hover:bg-accent',
+        className,
+      )}
+    >
+      <ArrowDown aria-hidden className="size-3.5" />
+      {unreadCount > 0 ? `${unreadCount} new` : 'Jump to latest'}
+    </button>
+  );
+}