@tangle-network/ui 1.0.0

package/src/chat/chat-message.tsx

@@ -0,0 +1,129 @@
+/**
+ * ChatMessage — single message bubble in the conversation.
+ *
+ * Supports user messages (plain text) and assistant messages
+ * (rich markdown with inline tool call activity).
+ */
+
+import { type ReactNode } from "react";
+import { User, Bot } from "lucide-react";
+import { cn } from "../lib/utils";
+import { Markdown } from "../markdown/markdown";
+
+export type MessageRole = "user" | "assistant" | "system";
+
+export interface ChatMessageProps {
+  role: MessageRole;
+  content: string;
+  /** Inline tool call activity rendered between text chunks */
+  toolCalls?: ReactNode;
+  /** Whether the message is still streaming */
+  isStreaming?: boolean;
+  /** Timestamp */
+  timestamp?: Date;
+  className?: string;
+  /** Custom user label. Default: "You" */
+  userLabel?: string;
+  /** Custom assistant label. Default: "Agent" */
+  assistantLabel?: string;
+  /** Hide the role label row entirely */
+  hideRoleLabel?: boolean;
+  /** Hide the avatar icon */
+  hideAvatar?: boolean;
+  /** Custom avatar element (replaces default User/Bot icon) */
+  avatar?: ReactNode;
+}
+
+export function ChatMessage({
+  role,
+  content,
+  toolCalls,
+  isStreaming,
+  timestamp,
+  className,
+  userLabel = "You",
+  assistantLabel = "Agent",
+  hideRoleLabel,
+  hideAvatar,
+  avatar,
+}: ChatMessageProps) {
+  const isUser = role === "user";
+
+  return (
+    <div
+      className={cn(
+        "flex gap-3",
+        isUser ? "flex-row-reverse" : "flex-row",
+        className,
+      )}
+    >
+      {/* Avatar */}
+      {!hideAvatar && (
+        avatar ? (
+          <div className="mt-0.5 shrink-0">{avatar}</div>
+        ) : (
+          <div
+            className={cn(
+              "mt-0.5 flex shrink-0 items-center justify-center rounded-[calc(var(--radius-md)+2px)] border",
+              "h-[var(--avatar-size)] w-[var(--avatar-size)]",
+              isUser
+                ? "border-border bg-[var(--accent-surface-soft)] text-[var(--accent-text)]"
+                : "border-border bg-muted text-[var(--brand-cool)]",
+            )}
+          >
+            {isUser ? <User className="h-3.5 w-3.5" /> : <Bot className="h-3.5 w-3.5" />}
+          </div>
+        )
+      )}
+
+      {/* Bubble */}
+      <div
+        className={cn(
+          "min-w-0 max-w-[85%] space-y-1 rounded-[var(--radius-lg)] border",
+          "px-[var(--chat-message-px)] py-[var(--chat-message-py)]",
+          isUser
+            ? "border-border bg-muted/50"
+            : "border-border bg-card",
+        )}
+      >
+        {/* Role label + timestamp */}
+        {!hideRoleLabel && (
+          <div className={cn("flex items-center gap-2", isUser && "flex-row-reverse")}>
+            <span className="text-[var(--font-size-xs)] font-[var(--chat-label-weight,600)] uppercase tracking-[var(--chat-label-tracking,0.14em)] text-foreground">
+              {isUser ? userLabel : assistantLabel}
+            </span>
+            {timestamp && (
+              <span className="text-[var(--font-size-xs)] text-muted-foreground">
+                {formatTime(timestamp)}
+              </span>
+            )}
+          </div>
+        )}
+
+        {/* Message body */}
+        {isUser ? (
+          <div className="whitespace-pre-wrap text-[var(--font-size-base)] leading-[var(--line-height-base)] text-foreground">
+            {content}
+          </div>
+        ) : (
+          <>
+            {content && <Markdown className="tangle-prose text-[var(--font-size-base)] leading-[var(--line-height-base)]">{content}</Markdown>}
+            {isStreaming && (
+              <span className="ml-0.5 inline-block h-4 w-2 animate-pulse rounded-sm bg-[var(--brand-cool)] align-text-bottom" />
+            )}
+          </>
+        )}
+
+        {/* Inline tool calls (left-aligned below agent text) */}
+        {toolCalls}
+      </div>
+    </div>
+  );
+}
+
+function formatTime(date: Date): string {
+  return date.toLocaleTimeString(undefined, {
+    hour: "numeric",
+    minute: "2-digit",
+  });
+}

package/src/chat/index.ts

@@ -0,0 +1,18 @@
+export { ChatContainer, type ChatContainerProps } from "./chat-container";
+export { MessageList, type MessageListProps } from "./message-list";
+export { UserMessage, type UserMessageProps } from "./user-message";
+export { ChatMessage, type ChatMessageProps, type MessageRole } from "./chat-message";
+export { ChatInput, type ChatInputProps, type PendingFile } from "./chat-input";
+export { ThinkingIndicator, type ThinkingIndicatorProps } from "./thinking-indicator";
+export {
+  AgentTimeline,
+  type AgentTimelineProps,
+  type AgentTimelineItem,
+  type AgentTimelineMessageItem,
+  type AgentTimelineToolItem,
+  type AgentTimelineToolGroupItem,
+  type AgentTimelineStatusItem,
+  type AgentTimelineArtifactItem,
+  type AgentTimelineCustomItem,
+  type AgentTimelineTone,
+} from "./agent-timeline";

package/src/chat/message-list.stories.tsx

@@ -0,0 +1,336 @@
+import type { Meta, StoryObj } from '@storybook/react'
+import { useState } from 'react'
+import { MessageList } from './message-list'
+import type { GroupedMessage } from '../types/run'
+import type { SessionPart } from '../types/parts'
+
+const meta: Meta<typeof MessageList> = {
+  title: 'Chat/MessageList',
+  component: MessageList,
+  parameters: {
+    layout: 'fullscreen',
+    backgrounds: { default: 'dark' },
+  },
+  decorators: [
+    (Story) => (
+      <div className="min-h-screen bg-[var(--bg-root)] p-8">
+        <div className="mx-auto max-w-3xl">
+          <Story />
+        </div>
+      </div>
+    ),
+  ],
+}
+
+export default meta
+type Story = StoryObj<typeof MessageList>
+
+// ---------------------------------------------------------------------------
+// Mock data — a realistic agent coding session
+// ---------------------------------------------------------------------------
+
+const NOW = Date.now()
+const t = (offsetSeconds: number) => NOW - offsetSeconds * 1000
+
+// User messages
+const userMsg1 = {
+  id: 'user-1',
+  role: 'user' as const,
+  time: { created: t(120) },
+}
+const userMsg2 = {
+  id: 'user-2',
+  role: 'user' as const,
+  time: { created: t(60) },
+}
+
+// Assistant messages (each run has one or more)
+const assistantMsg1 = {
+  id: 'asst-1',
+  role: 'assistant' as const,
+  time: { created: t(115), completed: t(100) },
+}
+const assistantMsg2 = {
+  id: 'asst-2',
+  role: 'assistant' as const,
+  time: { created: t(55), completed: t(30) },
+}
+
+const groups: GroupedMessage[] = [
+  { type: 'user', message: userMsg1 },
+  {
+    type: 'run',
+    run: {
+      id: 'run-1',
+      messages: [assistantMsg1],
+      isComplete: true,
+      isStreaming: false,
+      summaryText: 'Read 3 files, identified the staleTime misconfiguration',
+      finalTextPart: {
+        messageId: 'asst-1',
+        partIndex: 3,
+        text: 'The issue is your default `staleTime` is 0.',
+      },
+      stats: {
+        toolCount: 3,
+        messageCount: 1,
+        thinkingDurationMs: 4200,
+        textPartCount: 1,
+        toolCategories: new Set(['read', 'search'] as const),
+      },
+    },
+  },
+  { type: 'user', message: userMsg2 },
+  {
+    type: 'run',
+    run: {
+      id: 'run-2',
+      messages: [assistantMsg2],
+      isComplete: true,
+      isStreaming: false,
+      summaryText: 'Patched QueryClient config and updated the staleTime',
+      finalTextPart: {
+        messageId: 'asst-2',
+        partIndex: 5,
+        text: 'Done — staleTime set to 60s, cache flicker resolved.',
+      },
+      stats: {
+        toolCount: 2,
+        messageCount: 1,
+        thinkingDurationMs: 2100,
+        textPartCount: 2,
+        toolCategories: new Set(['read', 'edit'] as const),
+      },
+    },
+  },
+]
+
+// Part map — parts keyed by message ID
+const partMap: Record<string, SessionPart[]> = {
+  'user-1': [
+    {
+      type: 'text',
+      text: 'Can you help me debug why my React Query cache is not working? Every component mount triggers a refetch even for data that was just fetched.',
+    },
+  ],
+  'user-2': [
+    {
+      type: 'text',
+      text: 'Perfect, please fix it — set staleTime to 60 seconds globally.',
+    },
+  ],
+  'asst-1': [
+    {
+      type: 'reasoning',
+      text: 'The user is experiencing stale data refetches on mount. Default staleTime in TanStack Query v5 is 0, which causes this. I should read their QueryClient setup to confirm.',
+      time: { start: t(115), end: t(112) },
+    },
+    {
+      type: 'tool',
+      id: 'tool-1',
+      tool: 'read',
+      callID: 'call-1',
+      state: {
+        status: 'completed',
+        input: { path: 'src/lib/query-client.ts' },
+        output: 'export const queryClient = new QueryClient()',
+        time: { start: t(112), end: t(111) },
+      },
+    },
+    {
+      type: 'tool',
+      id: 'tool-2',
+      tool: 'grep',
+      callID: 'call-2',
+      state: {
+        status: 'completed',
+        input: { pattern: 'staleTime', path: 'src' },
+        output: 'No matches found.',
+        time: { start: t(111), end: t(110) },
+      },
+    },
+    {
+      type: 'tool',
+      id: 'tool-3',
+      tool: 'glob',
+      callID: 'call-3',
+      state: {
+        status: 'completed',
+        input: { pattern: 'src/**/*.ts' },
+        output: 'src/lib/query-client.ts\nsrc/hooks/useData.ts\nsrc/app/layout.tsx',
+        time: { start: t(110), end: t(109) },
+      },
+    },
+    {
+      type: 'text',
+      text: `The issue is your default \`staleTime\` is \`0\`, which is the TanStack Query v5 default. This means React Query considers all cached data immediately stale, triggering a background refetch on every component mount.
+
+Your current setup:
+
+\`\`\`typescript
+export const queryClient = new QueryClient()
+// No defaultOptions — staleTime defaults to 0ms
+\`\`\`
+
+No \`staleTime\` configuration was found anywhere in the codebase. Set it globally to fix the flicker.`,
+    },
+  ],
+  'asst-2': [
+    {
+      type: 'tool',
+      id: 'tool-4',
+      tool: 'read',
+      callID: 'call-4',
+      state: {
+        status: 'completed',
+        input: { path: 'src/lib/query-client.ts' },
+        output: 'export const queryClient = new QueryClient()',
+        time: { start: t(55), end: t(54) },
+      },
+    },
+    {
+      type: 'tool',
+      id: 'tool-5',
+      tool: 'edit',
+      callID: 'call-5',
+      state: {
+        status: 'completed',
+        input: {
+          path: 'src/lib/query-client.ts',
+          old_string: 'new QueryClient()',
+          new_string: 'new QueryClient({ defaultOptions: { queries: { staleTime: 60_000 } } })',
+        },
+        output: 'File updated.',
+        time: { start: t(54), end: t(53) },
+      },
+    },
+    {
+      type: 'text',
+      text: `Done. Updated \`src/lib/query-client.ts\`:
+
+\`\`\`typescript
+export const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      staleTime: 60_000, // 60 seconds
+    },
+  },
+})
+\`\`\`
+
+Cached data is now considered fresh for 60 seconds. Components that mount within that window will read from cache without triggering a refetch.`,
+    },
+  ],
+}
+
+// ---------------------------------------------------------------------------
+// Interactive wrapper — handles collapse state
+// ---------------------------------------------------------------------------
+
+function InteractiveMessageList({
+  groups: g,
+  partMap: pm,
+}: {
+  groups: GroupedMessage[]
+  partMap: Record<string, SessionPart[]>
+}) {
+  const [collapsed, setCollapsed] = useState<Record<string, boolean>>({})
+  return (
+    <MessageList
+      groups={g}
+      partMap={pm}
+      isCollapsed={(runId) => collapsed[runId] ?? false}
+      onToggleCollapse={(runId) =>
+        setCollapsed((prev) => ({ ...prev, [runId]: !prev[runId] }))
+      }
+    />
+  )
+}
+
+export const FullConversation: Story = {
+  render: () => <InteractiveMessageList groups={groups} partMap={partMap} />,
+}
+
+export const WithCollapsedRuns: Story = {
+  render: () => {
+    // Render with runs collapsed by default
+    const [collapsed, setCollapsed] = useState<Record<string, boolean>>({
+      'run-1': true,
+      'run-2': true,
+    })
+    return (
+      <MessageList
+        groups={groups}
+        partMap={partMap}
+        isCollapsed={(runId) => collapsed[runId] ?? false}
+        onToggleCollapse={(runId) =>
+          setCollapsed((prev) => ({ ...prev, [runId]: !prev[runId] }))
+        }
+      />
+    )
+  },
+}
+
+export const StreamingRun: Story = {
+  render: () => {
+    const streamingGroups: GroupedMessage[] = [
+      { type: 'user', message: userMsg1 },
+      {
+        type: 'run',
+        run: {
+          id: 'run-streaming',
+          messages: [assistantMsg1],
+          isComplete: false,
+          isStreaming: true,
+          summaryText: null,
+          finalTextPart: null,
+          stats: {
+            toolCount: 1,
+            messageCount: 1,
+            thinkingDurationMs: 0,
+            textPartCount: 0,
+            toolCategories: new Set(['read'] as const),
+          },
+        },
+      },
+    ]
+    const streamingPartMap: Record<string, SessionPart[]> = {
+      'user-1': partMap['user-1'],
+      'asst-1': [
+        {
+          type: 'tool',
+          id: 'tool-1',
+          tool: 'read',
+          callID: 'call-1',
+          state: {
+            status: 'running',
+            input: { path: 'src/lib/query-client.ts' },
+            time: { start: t(2) },
+          },
+        },
+      ],
+    }
+    return (
+      <MessageList
+        groups={streamingGroups}
+        partMap={streamingPartMap}
+        isCollapsed={() => false}
+        onToggleCollapse={() => {}}
+      />
+    )
+  },
+}
+
+export const OnlyUserMessages: Story = {
+  render: () => (
+    <MessageList
+      groups={[
+        { type: 'user', message: userMsg1 },
+        { type: 'user', message: userMsg2 },
+      ]}
+      partMap={partMap}
+      isCollapsed={() => false}
+      onToggleCollapse={() => {}}
+    />
+  ),
+}

package/src/chat/message-list.tsx

@@ -0,0 +1,79 @@
+import { memo, type ReactNode } from "react";
+import type { GroupedMessage } from "../types/run";
+import type { SessionPart } from "../types/parts";
+import type { SessionMessage } from "../types/message";
+import type { AgentBranding } from "../types/branding";
+import type { CustomToolRenderer } from "../types/tool-display";
+import type { ToolPart } from "../types/parts";
+import { RunGroup } from "../run/run-group";
+import { UserMessage } from "./user-message";
+
+export interface MessageListProps {
+  groups: GroupedMessage[];
+  partMap: Record<string, SessionPart[]>;
+  isCollapsed: (runId: string) => boolean;
+  onToggleCollapse: (runId: string) => void;
+  branding?: AgentBranding;
+  renderToolDetail?: CustomToolRenderer;
+  renderRunActions?: (group: Extract<GroupedMessage, { type: "run" }>["run"]) => ReactNode;
+  renderUserMessageActions?: (message: SessionMessage, parts: SessionPart[]) => ReactNode;
+  renderToolActions?: (
+    part: ToolPart,
+    options: {
+      run: Extract<GroupedMessage, { type: "run" }>["run"];
+      messageId: string;
+      partIndex: number;
+    },
+  ) => ReactNode;
+}
+
+/**
+ * Maps GroupedMessage[] to UserMessage and RunGroup components.
+ * This is the main render list for the chat view.
+ */
+export const MessageList = memo(
+  ({
+    groups,
+    partMap,
+    isCollapsed,
+    onToggleCollapse,
+    branding,
+    renderToolDetail,
+    renderRunActions,
+    renderUserMessageActions,
+    renderToolActions,
+  }: MessageListProps) => {
+    return (
+      <div className="space-y-4">
+        {groups.map((group) => {
+          if (group.type === "user") {
+            const messageParts = partMap[group.message.id] ?? [];
+            return (
+              <UserMessage
+                key={group.message.id}
+                message={group.message}
+                parts={messageParts}
+                actions={renderUserMessageActions?.(group.message, messageParts)}
+              />
+            );
+          }
+
+          return (
+            <RunGroup
+              key={group.run.id}
+              run={group.run}
+              partMap={partMap}
+              collapsed={isCollapsed(group.run.id)}
+              onToggle={() => onToggleCollapse(group.run.id)}
+              branding={branding}
+              renderToolDetail={renderToolDetail}
+              headerActions={renderRunActions?.(group.run)}
+              renderToolActions={renderToolActions}
+            />
+          );
+        })}
+      </div>
+    );
+  },
+);
+MessageList.displayName = "MessageList";

package/src/chat/thinking-indicator.stories.tsx

@@ -0,0 +1,56 @@
+import type { Meta, StoryObj } from '@storybook/react'
+import { ThinkingIndicator } from './thinking-indicator'
+
+const meta: Meta<typeof ThinkingIndicator> = {
+  title: 'Chat/ThinkingIndicator',
+  component: ThinkingIndicator,
+  parameters: {
+    layout: 'fullscreen',
+    backgrounds: { default: 'dark' },
+  },
+  decorators: [
+    (Story) => (
+      <div className="min-h-screen bg-[var(--bg-root)] p-8">
+        <div className="mx-auto max-w-2xl">
+          <Story />
+        </div>
+      </div>
+    ),
+  ],
+}
+
+export default meta
+type Story = StoryObj<typeof ThinkingIndicator>
+
+/**
+ * Animated state — the component starts at elapsed=0 and ticks up.
+ * In Storybook you'll see the bouncing dots and text update live.
+ */
+export const Default: Story = {}
+
+/**
+ * Show it inline below a chat message to simulate the agent responding.
+ */
+export const InContext: Story = {
+  render: () => (
+    <div className="space-y-1">
+      <div className="rounded-[calc(var(--radius-xl)+2px)] border border-border bg-card px-4 py-4 text-sm text-foreground">
+        Let me analyze the rate limiter implementation and check the Redis pipeline for atomicity issues.
+      </div>
+      <ThinkingIndicator />
+    </div>
+  ),
+}
+
+/**
+ * Multiple indicators to show staggered animation timing.
+ */
+export const Stacked: Story = {
+  render: () => (
+    <div className="space-y-2">
+      <ThinkingIndicator />
+      <ThinkingIndicator className="opacity-60" />
+      <ThinkingIndicator className="opacity-30" />
+    </div>
+  ),
+}

package/src/chat/thinking-indicator.tsx

@@ -0,0 +1,30 @@
+import { useEffect, useState } from "react";
+import { cn } from "../lib/utils";
+
+export interface ThinkingIndicatorProps {
+  className?: string;
+}
+
+export function ThinkingIndicator({ className }: ThinkingIndicatorProps) {
+  const [elapsed, setElapsed] = useState(0);
+
+  useEffect(() => {
+    const interval = window.setInterval(() => setElapsed((current) => current + 1), 1000);
+    return () => window.clearInterval(interval);
+  }, []);
+
+  return (
+    <div className={cn("flex items-center gap-2 px-3 py-1.5", className)}>
+      <div className="flex gap-[3px]">
+        <span className="h-[var(--indicator-dot-size)] w-[var(--indicator-dot-size)] animate-bounce rounded-full bg-[var(--brand-glow)]" style={{ animationDelay: "0ms" }} />
+        <span className="h-[var(--indicator-dot-size)] w-[var(--indicator-dot-size)] animate-bounce rounded-full bg-[var(--brand-glow)]" style={{ animationDelay: "150ms" }} />
+        <span className="h-[var(--indicator-dot-size)] w-[var(--indicator-dot-size)] animate-bounce rounded-full bg-[var(--brand-glow)]" style={{ animationDelay: "300ms" }} />
+      </div>
+      {elapsed > 3 && (
+        <span className="text-[var(--font-size-xs)] tabular-nums text-[var(--text-dim)]">
+          {elapsed}s
+        </span>
+      )}
+    </div>
+  );
+}