@djangocfg/ui-tools 2.1.334 → 2.1.336

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

@@ -0,0 +1,72 @@
+'use client';
+
+import { Copy, Pencil, RefreshCw, Trash } from 'lucide-react';
+
+import { cn } from '@djangocfg/ui-core/lib';
+
+import type { ChatRole } from '../types';
+
+export interface MessageActionsProps {
+  role: ChatRole;
+  onCopy?: () => void;
+  onRegenerate?: () => void;
+  onEdit?: () => void;
+  onDelete?: () => void;
+  hideOn?: Array<ChatRole>;
+  className?: string;
+}
+
+export function MessageActions({
+  role,
+  onCopy,
+  onRegenerate,
+  onEdit,
+  onDelete,
+  hideOn,
+  className,
+}: MessageActionsProps) {
+  if (hideOn?.includes(role)) return null;
+  return (
+    <div
+      className={cn(
+        'mt-1 flex items-center gap-0.5 opacity-0 transition-opacity group-hover/msg:opacity-100 focus-within:opacity-100',
+        className,
+      )}
+    >
+      {onCopy ? <ActionButton onClick={onCopy} label="Copy" icon={Copy} /> : null}
+      {onRegenerate && role === 'assistant' ? (
+        <ActionButton onClick={onRegenerate} label="Regenerate" icon={RefreshCw} />
+      ) : null}
+      {onEdit && role === 'user' ? (
+        <ActionButton onClick={onEdit} label="Edit" icon={Pencil} />
+      ) : null}
+      {onDelete ? <ActionButton onClick={onDelete} label="Delete" icon={Trash} destructive /> : null}
+    </div>
+  );
+}
+
+function ActionButton({
+  onClick,
+  label,
+  icon: Icon,
+  destructive,
+}: {
+  onClick: () => void;
+  label: string;
+  icon: typeof Copy;
+  destructive?: boolean;
+}) {
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      aria-label={label}
+      className={cn(
+        'rounded p-1 text-muted-foreground hover:bg-accent hover:text-foreground',
+        destructive && 'hover:bg-destructive/15 hover:text-destructive',
+      )}
+    >
+      <Icon aria-hidden className="size-3" />
+    </button>
+  );
+}

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

@@ -0,0 +1,228 @@
+'use client';
+
+import { memo, type ReactNode } from 'react';
+
+import { Avatar, AvatarFallback, AvatarImage } from '@djangocfg/ui-core/components';
+import { cn } from '@djangocfg/ui-core/lib';
+
+import { MarkdownMessage } from '../../../components/markdown';
+import type {
+  ChatAssistantContext,
+  ChatAttachment,
+  ChatMessage,
+  ChatSource,
+  ChatToolCall,
+  ChatUserContext,
+} from '../types';
+import { resolvePersona, deriveInitials } from '../core/persona';
+import { useChatContextOptional } from '../context';
+import { StreamingIndicator } from './StreamingIndicator';
+import { Sources } from './Sources';
+import { ToolCalls } from './ToolCalls';
+import {
+  AttachmentsGrid,
+  AttachmentsList,
+  type AttachmentRendererMap,
+} from './Attachments';
+import { MessageActions } from './MessageActions';
+import type { ToolCallsProps } from './ToolCalls';
+
+export interface MessageBubbleProps {
+  message: ChatMessage;
+  isUser?: boolean;
+  showAvatar?: boolean;
+  /** Override avatar URL (skips persona resolution). */
+  avatarSrc?: string;
+  /** Override avatar fallback (skips persona resolution). */
+  avatarFallback?: ReactNode;
+  /** Personas — when provided, take precedence over context. */
+  user?: ChatUserContext;
+  assistant?: ChatAssistantContext;
+  showTimestamp?: boolean;
+  showActions?: boolean;
+  isCompact?: boolean;
+  className?: string;
+  beforeContent?: ReactNode;
+  afterContent?: ReactNode;
+  toolCallsRenderer?: (calls: ChatToolCall[]) => ReactNode;
+  /** Forwarded to the default `<ToolCalls>` when `toolCallsRenderer` is not set. */
+  toolCallsProps?: Omit<ToolCallsProps, 'calls'>;
+  sourcesRenderer?: (sources: ChatSource[]) => ReactNode;
+  attachmentsRenderer?: (atts: ChatAttachment[]) => ReactNode;
+  /** Per-type attachment renderers forwarded to default `<Attachments>`. */
+  attachmentRenderers?: AttachmentRendererMap;
+  /** Click handler for attachment tiles (e.g. open lightbox). */
+  onAttachmentOpen?: (a: ChatAttachment) => void;
+  onCopy?: () => void;
+  onRegenerate?: () => void;
+  onEdit?: () => void;
+  onDelete?: () => void;
+}
+
+const MessageBubbleInner = ({
+  message,
+  isUser: isUserProp,
+  showAvatar = true,
+  avatarSrc,
+  avatarFallback,
+  user,
+  assistant,
+  showTimestamp = false,
+  showActions = true,
+  isCompact = false,
+  className,
+  beforeContent,
+  afterContent,
+  toolCallsRenderer,
+  toolCallsProps,
+  sourcesRenderer,
+  attachmentsRenderer,
+  attachmentRenderers,
+  onAttachmentOpen,
+  onCopy,
+  onRegenerate,
+  onEdit,
+  onDelete,
+}: MessageBubbleProps) => {
+  const isUser = isUserProp ?? message.role === 'user';
+  const isStreaming = !!message.isStreaming;
+  const isErr = !!message.isError;
+
+  const ctx = useChatContextOptional();
+  const persona = resolvePersona(
+    message,
+    user ?? ctx?.config.user,
+    assistant ?? ctx?.config.assistant,
+  );
+  const initials = deriveInitials(persona, message.role);
+  const personaName = persona.name ?? (isUser ? 'You' : 'Assistant');
+
+  return (
+    <div
+      role="article"
+      aria-label={`${personaName} said: ${message.content.slice(0, 80)}`}
+      aria-busy={isStreaming || undefined}
+      data-role={message.role}
+      className={cn(
+        'group/msg flex gap-2.5 px-2.5 py-2',
+        isUser ? 'flex-row-reverse' : 'flex-row',
+        className,
+      )}
+    >
+      {showAvatar ? (
+        <Avatar
+          className="size-7 shrink-0"
+          title={persona.description ?? personaName}
+        >
+          {avatarSrc || persona.avatarUrl ? (
+            <AvatarImage src={avatarSrc ?? persona.avatarUrl} alt={personaName} />
+          ) : null}
+          <AvatarFallback className="text-[10px]">
+            {avatarFallback ?? initials}
+          </AvatarFallback>
+        </Avatar>
+      ) : null}
+
+      <div className={cn('min-w-0 flex-1', isUser && 'flex flex-col items-end')}>
+        {beforeContent}
+        {message.attachments?.length
+          ? attachmentsRenderer
+            ? attachmentsRenderer(message.attachments)
+            : (
+                <div className="mb-1.5 w-full">
+                  {attachmentRenderers ? (
+                    <AttachmentsList
+                      attachments={message.attachments}
+                      renderers={attachmentRenderers}
+                      onClick={onAttachmentOpen}
+                      className={isUser ? 'items-end' : undefined}
+                    />
+                  ) : (
+                    <AttachmentsGrid
+                      attachments={message.attachments}
+                      onClick={onAttachmentOpen}
+                      className={isUser ? 'justify-end' : undefined}
+                    />
+                  )}
+                </div>
+              )
+          : null}
+
+        <div
+          className={cn(
+            'inline-block max-w-full rounded-2xl px-3.5 py-2 text-sm',
+            isUser
+              ? 'bg-primary text-primary-foreground rounded-tr-md'
+              : isErr
+                ? 'bg-destructive/10 text-destructive rounded-tl-md border border-destructive/30'
+                : 'bg-muted text-foreground rounded-tl-md',
+          )}
+        >
+          {isStreaming && message.toolActivity ? (
+            <div className="mb-1.5">
+              <StreamingIndicator label={message.toolActivity} />
+            </div>
+          ) : null}
+
+          {message.content || !isStreaming ? (
+            <MarkdownMessage
+              content={message.content || (isErr ? '*Failed to generate a response.*' : '')}
+              isUser={isUser}
+              isCompact={isCompact}
+              plainText={isStreaming}
+            />
+          ) : (
+            <StreamingIndicator />
+          )}
+        </div>
+
+        {message.toolCalls?.length
+          ? toolCallsRenderer
+            ? toolCallsRenderer(message.toolCalls)
+            : <ToolCalls calls={message.toolCalls} {...toolCallsProps} />
+          : null}
+
+        {message.sources?.length && !isStreaming
+          ? sourcesRenderer
+            ? sourcesRenderer(message.sources)
+            : <Sources sources={message.sources} />
+          : null}
+
+        {showActions && !isStreaming ? (
+          <MessageActions
+            role={message.role}
+            onCopy={onCopy}
+            onRegenerate={onRegenerate}
+            onEdit={onEdit}
+            onDelete={onDelete}
+          />
+        ) : null}
+
+        {showTimestamp ? (
+          <div className="mt-1 text-[10px] text-muted-foreground">
+            {new Date(message.createdAt).toLocaleTimeString()}
+          </div>
+        ) : null}
+
+        {afterContent}
+      </div>
+    </div>
+  );
+};
+
+export const MessageBubble = memo(MessageBubbleInner, (prev, next) => {
+  const a = prev.message;
+  const b = next.message;
+  return (
+    a.id === b.id &&
+    a.content === b.content &&
+    a.isStreaming === b.isStreaming &&
+    a.isError === b.isError &&
+    (a.version ?? 0) === (b.version ?? 0) &&
+    a.toolActivity === b.toolActivity &&
+    a.toolCalls === b.toolCalls &&
+    a.sources === b.sources &&
+    a.attachments === b.attachments
+  );
+});
+MessageBubble.displayName = 'MessageBubble';

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

@@ -0,0 +1,82 @@
+'use client';
+
+import { type RefObject, type ReactNode, forwardRef, useCallback } from 'react';
+
+import { cn } from '@djangocfg/ui-core/lib';
+import { Spinner } from '@djangocfg/ui-core/components';
+
+import type { ChatMessage } from '../types';
+import { useChatContextOptional } from '../context';
+import { MessageBubble } from './MessageBubble';
+
+export interface MessageListProps {
+  messages?: ChatMessage[];
+  renderItem?: (m: ChatMessage, i: number) => ReactNode;
+  renderEmpty?: () => ReactNode;
+  isLoadingMore?: boolean;
+  topSentinelRef?: RefObject<HTMLDivElement | null>;
+  bottomRef?: RefObject<HTMLDivElement | null>;
+  className?: string;
+  itemClassName?: string;
+}
+
+export const MessageList = forwardRef<HTMLDivElement, MessageListProps>(function MessageList(
+  {
+    messages: messagesProp,
+    renderItem,
+    renderEmpty,
+    isLoadingMore: isLoadingMoreProp,
+    topSentinelRef,
+    bottomRef,
+    className,
+    itemClassName,
+  },
+  ref,
+) {
+  const ctx = useChatContextOptional();
+  const messages = messagesProp ?? ctx?.messages ?? [];
+  const isLoadingMore = isLoadingMoreProp ?? ctx?.isLoadingMore ?? false;
+
+  const defaultRenderItem = useCallback(
+    (m: ChatMessage) => (
+      <div className={itemClassName} key={m.id}>
+        <MessageBubble
+          message={m}
+          onCopy={() => copy(m.content)}
+          onRegenerate={ctx ? () => void ctx.regenerate(m.id) : undefined}
+          onDelete={ctx ? () => ctx.deleteMessage(m.id) : undefined}
+        />
+      </div>
+    ),
+    [itemClassName, ctx],
+  );
+
+  const itemRenderer = renderItem ?? defaultRenderItem;
+
+  return (
+    <div
+      ref={ref}
+      role="log"
+      aria-live="polite"
+      aria-atomic="false"
+      className={cn('flex-1 overflow-y-auto', className)}
+    >
+      <div ref={topSentinelRef} aria-hidden />
+      {isLoadingMore ? (
+        <div className="flex justify-center py-2">
+          <Spinner className="size-4 text-muted-foreground" />
+        </div>
+      ) : null}
+      {messages.length === 0
+        ? renderEmpty?.() ?? null
+        : messages.map((m, i) => itemRenderer(m, i))}
+      <div ref={bottomRef} aria-hidden />
+    </div>
+  );
+});
+
+function copy(text: string) {
+  if (typeof navigator !== 'undefined' && navigator.clipboard) {
+    void navigator.clipboard.writeText(text);
+  }
+}

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

@@ -0,0 +1,55 @@
+'use client';
+
+import { ExternalLink } from 'lucide-react';
+
+import { cn } from '@djangocfg/ui-core/lib';
+
+import type { ChatSource } from '../types';
+
+export interface SourcesProps {
+  sources: ChatSource[];
+  layout?: 'inline' | 'grid';
+  maxVisible?: number;
+  onClick?: (source: ChatSource) => void;
+  className?: string;
+}
+
+export function Sources({ sources, layout = 'inline', maxVisible, onClick, className }: SourcesProps) {
+  if (!sources?.length) return null;
+  const visible = maxVisible ? sources.slice(0, maxVisible) : sources;
+  const remaining = maxVisible ? Math.max(0, sources.length - maxVisible) : 0;
+
+  return (
+    <div
+      className={cn(
+        'mt-2 flex flex-wrap gap-1.5',
+        layout === 'grid' && 'grid grid-cols-2',
+        className,
+      )}
+    >
+      {visible.map((s, i) => {
+        const handle = onClick ? () => onClick(s) : undefined;
+        const Tag = handle ? 'button' : 'a';
+        const props = handle
+          ? ({ type: 'button', onClick: handle } as const)
+          : ({ href: s.url, target: '_blank', rel: 'noopener noreferrer' } as const);
+        return (
+          <Tag
+            key={`${s.url}-${i}`}
+            {...props}
+            className="inline-flex max-w-full items-center gap-1 rounded-md border border-border bg-background/60 px-2 py-1 text-xs text-foreground/80 hover:bg-accent hover:text-foreground"
+            title={s.snippet ?? s.title}
+          >
+            <span className="truncate">{s.title || s.url}</span>
+            <ExternalLink aria-hidden className="size-3 shrink-0 opacity-60" />
+          </Tag>
+        );
+      })}
+      {remaining > 0 ? (
+        <span className="inline-flex items-center rounded-md border border-dashed border-border px-2 py-1 text-xs text-muted-foreground">
+          +{remaining}
+        </span>
+      ) : null}
+    </div>
+  );
+}

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

@@ -0,0 +1,29 @@
+'use client';
+
+import { cn } from '@djangocfg/ui-core/lib';
+
+export interface StreamingIndicatorProps {
+  variant?: 'dots' | 'pulse';
+  label?: string;
+  className?: string;
+}
+
+export function StreamingIndicator({ variant = 'dots', label, className }: StreamingIndicatorProps) {
+  return (
+    <span
+      className={cn('inline-flex items-center gap-1.5 text-xs text-muted-foreground', className)}
+      aria-live="off"
+    >
+      {variant === 'dots' ? (
+        <span className="inline-flex gap-0.5" aria-hidden>
+          <span className="size-1 animate-bounce rounded-full bg-current [animation-delay:-0.2s]" />
+          <span className="size-1 animate-bounce rounded-full bg-current [animation-delay:-0.1s]" />
+          <span className="size-1 animate-bounce rounded-full bg-current" />
+        </span>
+      ) : (
+        <span className="inline-block size-1.5 animate-pulse rounded-full bg-current" aria-hidden />
+      )}
+      {label ? <span className="italic">{label}</span> : null}
+    </span>
+  );
+}

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

@@ -0,0 +1,172 @@
+'use client';
+
+import { type ReactNode, useEffect, useRef, useState } from 'react';
+import { ChevronDown, ChevronRight, Loader2 } from 'lucide-react';
+
+import { cn } from '@djangocfg/ui-core/lib';
+
+import type { ChatToolCall } from '../types';
+
+export type ToolPayloadKind = 'input' | 'output' | 'streaming';
+
+export interface ToolCallsProps {
+  calls: ChatToolCall[];
+  /** Open every panel up-front. Default: false (panels are closed). */
+  defaultExpanded?: boolean;
+  /** Auto-open while a tool is running, then auto-close on completion.
+   *  User toggles after that are remembered. Default: true. */
+  expandWhileStreaming?: boolean;
+  /** Override how the tool input payload is rendered. Receives the raw value. */
+  renderInput?: (input: unknown, call: ChatToolCall) => ReactNode;
+  /** Override how the tool output payload is rendered. */
+  renderOutput?: (output: unknown, call: ChatToolCall) => ReactNode;
+  /** Override how the live `streamingText` is rendered. */
+  renderStreaming?: (text: string, call: ChatToolCall) => ReactNode;
+  /** Single override for all three; specific renderers above take precedence. */
+  renderPayload?: (value: unknown, kind: ToolPayloadKind, call: ChatToolCall) => ReactNode;
+  className?: string;
+}
+
+export function ToolCalls({
+  calls,
+  defaultExpanded = false,
+  expandWhileStreaming = true,
+  renderInput,
+  renderOutput,
+  renderStreaming,
+  renderPayload,
+  className,
+}: ToolCallsProps) {
+  if (!calls?.length) return null;
+  return (
+    <div className={cn('mt-2 space-y-1.5', className)}>
+      {calls.map((call) => (
+        <ToolCallItem
+          key={call.id}
+          call={call}
+          defaultExpanded={defaultExpanded}
+          expandWhileStreaming={expandWhileStreaming}
+          renderInput={renderInput}
+          renderOutput={renderOutput}
+          renderStreaming={renderStreaming}
+          renderPayload={renderPayload}
+        />
+      ))}
+    </div>
+  );
+}
+
+interface ItemProps {
+  call: ChatToolCall;
+  defaultExpanded: boolean;
+  expandWhileStreaming: boolean;
+  renderInput?: ToolCallsProps['renderInput'];
+  renderOutput?: ToolCallsProps['renderOutput'];
+  renderStreaming?: ToolCallsProps['renderStreaming'];
+  renderPayload?: ToolCallsProps['renderPayload'];
+}
+
+function ToolCallItem({
+  call,
+  defaultExpanded,
+  expandWhileStreaming,
+  renderInput,
+  renderOutput,
+  renderStreaming,
+  renderPayload,
+}: ItemProps) {
+  const isRunning = call.status === 'running';
+  const initialOpen = defaultExpanded || (expandWhileStreaming && isRunning);
+  const [open, setOpen] = useState(initialOpen);
+  // Remember manual interaction so completion doesn't override it.
+  const userToggledRef = useRef(false);
+  const wasRunningRef = useRef(isRunning);
+
+  // Auto-collapse on running → completed transition, unless user has interacted.
+  useEffect(() => {
+    if (wasRunningRef.current && !isRunning) {
+      if (!userToggledRef.current && !defaultExpanded) {
+        setOpen(false);
+      }
+    }
+    wasRunningRef.current = isRunning;
+  }, [isRunning, defaultExpanded]);
+
+  const handleToggle = () => {
+    userToggledRef.current = true;
+    setOpen((v) => !v);
+  };
+
+  const Icon = open ? ChevronDown : ChevronRight;
+  const statusColor =
+    call.status === 'success'
+      ? 'text-emerald-500'
+      : call.status === 'error'
+        ? 'text-destructive'
+        : call.status === 'cancelled'
+          ? 'text-muted-foreground'
+          : 'text-amber-500';
+
+  const renderValue = (value: unknown, kind: ToolPayloadKind): ReactNode => {
+    if (kind === 'input' && renderInput) return renderInput(value, call);
+    if (kind === 'output' && renderOutput) return renderOutput(value, call);
+    if (kind === 'streaming' && renderStreaming)
+      return renderStreaming(typeof value === 'string' ? value : String(value), call);
+    if (renderPayload) return renderPayload(value, kind, call);
+    return <DefaultPayload value={value} kind={kind} />;
+  };
+
+  return (
+    <div className="overflow-hidden rounded-md border border-border bg-muted/30">
+      <button
+        type="button"
+        onClick={handleToggle}
+        aria-expanded={open}
+        className="flex w-full items-center gap-2 px-2 py-1.5 text-left text-xs hover:bg-muted/60"
+      >
+        <Icon aria-hidden className="size-3 shrink-0 text-muted-foreground" />
+        {isRunning ? (
+          <Loader2 aria-hidden className="size-3 shrink-0 animate-spin text-amber-500" />
+        ) : (
+          <span className={cn('size-2 shrink-0 rounded-full', statusColor.replace('text-', 'bg-'))} />
+        )}
+        <span className="font-mono text-foreground">{call.name}</span>
+        <span className={cn('ml-auto', statusColor)}>{call.status}</span>
+      </button>
+      {open ? (
+        <div className="space-y-1 border-t border-border px-2 py-1.5 text-[11px]">
+          {call.input != null ? renderValue(call.input, 'input') : null}
+          {call.streamingText != null
+            ? renderValue(call.streamingText, 'streaming')
+            : call.output !== undefined
+              ? renderValue(call.output, 'output')
+              : null}
+        </div>
+      ) : null}
+    </div>
+  );
+}
+
+function DefaultPayload({ value, kind }: { value: unknown; kind: ToolPayloadKind }) {
+  const isStreamingOrString = kind === 'streaming' || typeof value === 'string';
+  const muted = kind === 'input';
+  return (
+    <pre
+      className={cn(
+        'overflow-auto rounded bg-background/60 p-1.5 font-mono',
+        kind === 'input' ? 'max-h-32' : 'max-h-48',
+        muted ? 'text-muted-foreground' : 'text-foreground/90',
+      )}
+    >
+      {isStreamingOrString ? String(value) : safeStringify(value)}
+    </pre>
+  );
+}
+
+function safeStringify(value: unknown): string {
+  try {
+    return JSON.stringify(value, null, 2);
+  } catch {
+    return String(value);
+  }
+}

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

@@ -0,0 +1,24 @@
+'use client';
+
+export { ChatRoot, type ChatRootProps } from './ChatRoot';
+export { MessageList, type MessageListProps } from './MessageList';
+export { MessageBubble, type MessageBubbleProps } from './MessageBubble';
+export { MessageActions, type MessageActionsProps } from './MessageActions';
+export { Composer, type ComposerProps } from './Composer';
+export { Sources, type SourcesProps } from './Sources';
+export { ToolCalls, type ToolCallsProps, type ToolPayloadKind } from './ToolCalls';
+export {
+  Attachments,
+  AttachmentsGrid,
+  AttachmentsList,
+  type AttachmentsProps,
+  type AttachmentsGridProps,
+  type AttachmentsListProps,
+  type AttachmentRenderer,
+  type AttachmentRendererArgs,
+  type AttachmentRendererMap,
+} from './Attachments';
+export { EmptyState, type EmptyStateProps } from './EmptyState';
+export { ErrorBanner, type ErrorBannerProps } from './ErrorBanner';
+export { JumpToLatest, type JumpToLatestProps } from './JumpToLatest';
+export { StreamingIndicator, type StreamingIndicatorProps } from './StreamingIndicator';