@slipstream-ui/ai 0.0.0-stage → 0.3.0

package/src/components/conversation/Conversation.tsx

@@ -0,0 +1,301 @@
+'use client';
+
+import * as React from 'react';
+import { cn } from '@slipstream-ui/core';
+import { Message } from '../message';
+import type { Message as MessageType } from '../../types';
+
+export type ConversationProps = {
+  messages: MessageType[];
+  className?: string;
+  showAvatars?: boolean;
+  userAvatarSrc?: string;
+  userAvatarFallback?: string;
+  assistantAvatarSrc?: string;
+  assistantAvatarFallback?: string;
+  isLoading?: boolean;
+  loadingMessage?: string;
+  /** Custom content renderer applied to every message (e.g. markdown). */
+  renderContent?: (content: string) => React.ReactNode;
+  /** ID of the message still being generated; renders its streaming cursor. */
+  streamingMessageId?: string;
+  /**
+   * Show a floating "scroll to latest" pill when the user has scrolled up.
+   * Default true.
+   */
+  showScrollButton?: boolean;
+  /** Show a download button that exports the transcript as Markdown. Default false. */
+  showDownload?: boolean;
+  /** Per-message generation failures keyed by message id; renders retry cards. */
+  messageErrors?: Record<string, string>;
+  /** Retry handler for failed messages in `messageErrors`. */
+  onRetryMessage?: (message: MessageType) => void;
+
+  // --- Empty state -------------------------------------------------------
+  /** Heading for the empty-transcript welcome state. */
+  welcomeTitle?: string;
+  /** Supporting copy for the welcome state. */
+  welcomeDescription?: string;
+  /** Starter prompts rendered as buttons under the welcome copy. */
+  welcomeSuggestions?: string[];
+  /** Called with the chosen starter prompt text. */
+  onWelcomeSelect?: (prompt: string) => void;
+
+  // --- History pagination --------------------------------------------------
+  /** Older history exists; renders a "load earlier" control at the top. */
+  hasMoreHistory?: boolean;
+  /** Older history request is in flight; shows a loading row. */
+  isLoadingMore?: boolean;
+  /** Called when the user requests older history. */
+  onLoadMore?: () => void;
+};
+
+/** Distance (px) from the bottom within which the view counts as "pinned". */
+const PINNED_THRESHOLD = 80;
+
+const DEFAULT_WELCOME_TITLE = 'Start the conversation';
+const DEFAULT_WELCOME_DESCRIPTION = 'Ask anything — responses stream in real time.';
+const DEFAULT_WELCOME_SUGGESTIONS = [
+  'Explain what you can do',
+  'Summarize a topic for me',
+];
+
+function transcriptToMarkdown(messages: MessageType[]): string {
+  return messages
+    .map((message) => {
+      const speaker =
+        message.role === 'user' ? 'You' : message.role === 'assistant' ? 'Assistant' : message.role;
+      const time = message.timestamp ? ` (${new Date(message.timestamp).toISOString()})` : '';
+      return `**${speaker}${time}:**\n\n${message.content}`;
+    })
+    .join('\n\n---\n\n');
+}
+
+const Conversation = React.forwardRef<HTMLDivElement, ConversationProps>(
+  ({
+    messages,
+    className,
+    showAvatars = true,
+    userAvatarSrc,
+    userAvatarFallback,
+    assistantAvatarSrc,
+    assistantAvatarFallback,
+    isLoading = false,
+    loadingMessage = 'Thinking...',
+    renderContent,
+    streamingMessageId,
+    showScrollButton = true,
+    showDownload = false,
+    messageErrors,
+    onRetryMessage,
+    welcomeTitle = DEFAULT_WELCOME_TITLE,
+    welcomeDescription = DEFAULT_WELCOME_DESCRIPTION,
+    welcomeSuggestions = DEFAULT_WELCOME_SUGGESTIONS,
+    onWelcomeSelect,
+    hasMoreHistory = false,
+    isLoadingMore = false,
+    onLoadMore,
+    ...props
+  }, ref) => {
+    const scrollRef = React.useRef<HTMLDivElement>(null);
+    const messagesEndRef = React.useRef<HTMLDivElement>(null);
+    const [isUnpinned, setIsUnpinned] = React.useState(false);
+    const prevScrollMetrics = React.useRef<{ height: number; top: number } | null>(null);
+
+    // Announce stream completion to assistive tech: when the streaming id
+    // transitions from set to unset, a response just finished.
+    const [announcement, setAnnouncement] = React.useState('');
+    const prevStreamingRef = React.useRef<string | undefined>(undefined);
+    React.useEffect(() => {
+      if (prevStreamingRef.current && !streamingMessageId) {
+        setAnnouncement('Response complete.');
+      }
+      prevStreamingRef.current = streamingMessageId;
+    }, [streamingMessageId]);
+
+    // Track pinned state on scroll so the jump-to-latest pill can appear.
+    React.useEffect(() => {
+      const container = scrollRef.current;
+      if (!container) return;
+
+      const updatePinned = () => {
+        const distanceFromBottom =
+          container.scrollHeight - container.scrollTop - container.clientHeight;
+        setIsUnpinned(distanceFromBottom > PINNED_THRESHOLD);
+      };
+
+      updatePinned();
+      container.addEventListener('scroll', updatePinned, { passive: true });
+      return () => container.removeEventListener('scroll', updatePinned);
+    }, []);
+
+    // Scroll anchoring across history loads: capture metrics before new rows
+    // render, then restore the same visual position after they land.
+    React.useLayoutEffect(() => {
+      const container = scrollRef.current;
+      if (!container || prevScrollMetrics.current === null) return;
+
+      const { height, top } = prevScrollMetrics.current;
+      container.scrollTop = container.scrollHeight - height + top;
+      prevScrollMetrics.current = null;
+    }, [messages]);
+
+    const captureAnchor = () => {
+      const container = scrollRef.current;
+      if (!container) return;
+      prevScrollMetrics.current = { height: container.scrollHeight, top: container.scrollTop };
+    };
+
+    const handleLoadMore = () => {
+      captureAnchor();
+      onLoadMore?.();
+    };
+
+    // Auto-scroll only when the user is already near the bottom, so reading
+    // history is never yanked. During streaming use instant scrolls; smooth
+    // animations restarted per token cause jank.
+    //
+    // Scroll the container itself (never scrollIntoView): scrollIntoView
+    // bubbles through every scrollable ancestor, including the document,
+    // which yanked the whole page when the demo/preview frames were small.
+    React.useEffect(() => {
+      const container = scrollRef.current;
+      if (!container) return;
+
+      const distanceFromBottom =
+        container.scrollHeight - container.scrollTop - container.clientHeight;
+      if (distanceFromBottom > PINNED_THRESHOLD) return;
+
+      container.scrollTo?.({
+        top: container.scrollHeight,
+        behavior: streamingMessageId ? 'auto' : 'smooth',
+      });
+    }, [messages, streamingMessageId]);
+
+    const scrollToLatest = () => {
+      const container = scrollRef.current;
+      if (!container) return;
+      container.scrollTo?.({ top: container.scrollHeight, behavior: 'smooth' });
+    };
+
+    const handleDownload = () => {
+      const blob = new Blob([transcriptToMarkdown(messages)], { type: 'text/markdown' });
+      const url = URL.createObjectURL(blob);
+      const anchor = document.createElement('a');
+      anchor.href = url;
+      anchor.download = 'conversation.md';
+      anchor.click();
+      URL.revokeObjectURL(url);
+    };
+
+    const isEmpty = messages.length === 0 && !isLoading;
+
+    return (
+      <div ref={ref} className={cn('relative h-full w-full', className)} {...props}>
+        <div ref={scrollRef} className="flex flex-col gap-4 p-4 overflow-y-auto h-full">
+          {(hasMoreHistory || isLoadingMore) && (
+            <button
+              type="button"
+              onClick={handleLoadMore}
+              disabled={isLoadingMore}
+              className="mx-auto rounded-full border border-border bg-background px-3 py-1 text-xs text-muted-foreground hover:text-foreground transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:opacity-50"
+            >
+              {isLoadingMore ? 'Loading…' : 'Load earlier messages'}
+            </button>
+          )}
+
+          {isEmpty ? (
+            <div className="flex flex-1 flex-col items-center justify-center gap-3 text-center py-16">
+              <h3 className="text-lg font-semibold">{welcomeTitle}</h3>
+              <p className="text-sm text-muted-foreground max-w-sm">{welcomeDescription}</p>
+              {welcomeSuggestions.length > 0 && (
+                <div className="mt-2 flex flex-col gap-2 w-full max-w-sm">
+                  {welcomeSuggestions.map((suggestion) => (
+                    <button
+                      key={suggestion}
+                      type="button"
+                      onClick={() => onWelcomeSelect?.(suggestion)}
+                      className="rounded-md border border-border bg-background px-4 py-2.5 text-sm text-left text-muted-foreground hover:bg-accent hover:text-accent-foreground transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+                    >
+                      {suggestion}
+                    </button>
+                  ))}
+                </div>
+              )}
+            </div>
+          ) : (
+            messages.map((message) => (
+              <Message
+                key={message.id}
+                message={message}
+                showAvatar={showAvatars}
+                avatarSrc={
+                  message.role === 'user' ? userAvatarSrc : assistantAvatarSrc
+                }
+                avatarFallback={
+                  message.role === 'user' ? userAvatarFallback : assistantAvatarFallback
+                }
+                renderContent={renderContent}
+                isStreaming={message.id === streamingMessageId}
+                error={messageErrors?.[message.id]}
+                onRetry={
+                  onRetryMessage && messageErrors?.[message.id]
+                    ? () => onRetryMessage(message)
+                    : undefined
+                }
+              />
+            ))
+          )}
+
+          {isLoading && !isEmpty && (
+            <Message
+              message={{
+                id: '__loading__',
+                role: 'assistant',
+                content: loadingMessage,
+              }}
+              showAvatar={showAvatars}
+              avatarSrc={assistantAvatarSrc}
+              avatarFallback={assistantAvatarFallback}
+              className="bg-muted/50"
+              renderContent={(content) => (
+                <span className="text-muted-foreground animate-pulse motion-reduce:animate-none">{content}</span>
+              )}
+            />
+          )}
+
+          {/* Screen-reader announcement when a streamed response completes. */}
+          <div aria-live="polite" className="sr-only">{announcement}</div>
+
+          <div ref={messagesEndRef} />
+        </div>
+
+        {showDownload && messages.length > 0 && (
+          <button
+            type="button"
+            onClick={handleDownload}
+            aria-label="Download transcript"
+            className="absolute top-2 right-2 z-10 rounded-md border border-border bg-background/90 px-2 py-1 text-xs text-muted-foreground hover:text-foreground transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+          >
+            ↓ .md
+          </button>
+        )}
+
+        {showScrollButton && isUnpinned && (
+          <button
+            type="button"
+            onClick={scrollToLatest}
+            aria-label="Scroll to latest message"
+            className="absolute bottom-3 left-1/2 z-10 -translate-x-1/2 rounded-full border border-border bg-background/95 px-3 py-1.5 text-xs font-medium shadow-sm hover:bg-accent transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+          >
+            ↓ Latest
+          </button>
+        )}
+      </div>
+    );
+  }
+);
+
+Conversation.displayName = 'Conversation';
+
+export { Conversation };

package/src/components/conversation/Conversation.welcome.test.tsx

@@ -0,0 +1,73 @@
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { describe, expect, it, vi } from 'vitest';
+import { Conversation } from './Conversation';
+
+describe('Conversation welcome state', () => {
+  it('renders welcome copy and starter prompts when empty', async () => {
+    const user = userEvent.setup();
+    const onWelcomeSelect = vi.fn();
+    render(
+      <Conversation
+        messages={[]}
+        welcomeTitle="Hello"
+        welcomeDescription="Pick a starter"
+        welcomeSuggestions={['Tell me a joke']}
+        onWelcomeSelect={onWelcomeSelect}
+      />
+    );
+
+    expect(screen.getByText('Hello')).toBeInTheDocument();
+    await user.click(screen.getByRole('button', { name: 'Tell me a joke' }));
+    expect(onWelcomeSelect).toHaveBeenCalledWith('Tell me a joke');
+  });
+
+  it('does not show the welcome state once messages exist', () => {
+    render(
+      <Conversation
+        messages={[{ id: '1', role: 'user', content: 'Hi' }]}
+        welcomeTitle="Hello"
+      />
+    );
+    expect(screen.queryByText('Hello')).not.toBeInTheDocument();
+  });
+
+  it('hides the welcome state while loading the first response', () => {
+    render(<Conversation messages={[]} isLoading welcomeTitle="Hello" />);
+    expect(screen.queryByText('Hello')).not.toBeInTheDocument();
+  });
+});
+
+describe('Conversation history pagination', () => {
+  it('shows the load-earlier control only when history exists', async () => {
+    const user = userEvent.setup();
+    const onLoadMore = vi.fn();
+    const { rerender } = render(
+      <Conversation messages={[{ id: '1', role: 'user', content: 'Hi' }]} onLoadMore={onLoadMore} />
+    );
+    // No control without hasMoreHistory.
+    expect(screen.queryByRole('button', { name: /Load earlier/ })).not.toBeInTheDocument();
+
+    rerender(
+      <Conversation
+        messages={[{ id: '1', role: 'user', content: 'Hi' }]}
+        hasMoreHistory
+        onLoadMore={onLoadMore}
+      />
+    );
+    await user.click(screen.getByRole('button', { name: /Load earlier/ }));
+    expect(onLoadMore).toHaveBeenCalledOnce();
+  });
+
+  it('disables the control while loading more', () => {
+    render(
+      <Conversation
+        messages={[{ id: '1', role: 'user', content: 'Hi' }]}
+        hasMoreHistory
+        isLoadingMore
+        onLoadMore={() => {}}
+      />
+    );
+    expect(screen.getByRole('button', { name: /Loading/ })).toBeDisabled();
+  });
+});

package/src/components/conversation/index.ts

@@ -0,0 +1,2 @@
+export { Conversation } from './Conversation';
+export type { ConversationProps } from './Conversation';

package/src/components/inline-citation/InlineCitation.test.tsx

@@ -0,0 +1,42 @@
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { axe } from 'jest-axe';
+import { describe, expect, it } from 'vitest';
+import { InlineCitation } from './InlineCitation';
+
+const source = {
+  id: 'src-1',
+  title: 'React docs',
+  url: 'https://react.dev',
+  snippet: 'The library for web and native user interfaces.',
+};
+
+describe('InlineCitation', () => {
+  it('renders the citation chip with a tooltip target', () => {
+    render(<InlineCitation source={source} />);
+    const trigger = screen.getByRole('button');
+    expect(trigger).toHaveAttribute('aria-describedby', 'citation-src-1-card');
+    expect(screen.getByRole('tooltip')).toBeInTheDocument();
+  });
+
+  it('wraps custom children instead of the title', () => {
+    render(
+      <InlineCitation source={source}>
+        as stated in the docs
+      </InlineCitation>
+    );
+    expect(screen.getByRole('button')).toHaveTextContent('as stated in the docs');
+  });
+
+  it('is keyboard reachable', async () => {
+    const user = userEvent.setup();
+    render(<InlineCitation source={source} />);
+    await user.tab();
+    expect(screen.getByRole('button')).toHaveFocus();
+  });
+
+  it('has no accessibility violations', async () => {
+    const { container } = render(<InlineCitation source={source} />);
+    expect(await axe(container)).toHaveNoViolations();
+  });
+});

package/src/components/inline-citation/InlineCitation.tsx

@@ -0,0 +1,56 @@
+import * as React from 'react';
+import { cn } from '@slipstream-ui/core';
+import type { SourceItem } from '../../types';
+
+export type InlineCitationProps = {
+  /** The cited source; powers the hover/focus preview card. */
+  source: SourceItem;
+  /** Citation text to wrap (defaults to the source title). */
+  children?: React.ReactNode;
+  className?: string;
+};
+
+/**
+ * Perplexity-style inline citation: a superscript chip that reveals the
+ * source snippet on hover or keyboard focus.
+ */
+const InlineCitation = React.forwardRef<HTMLSpanElement, InlineCitationProps>(
+  ({ source, children, className, ...props }, ref) => {
+    return (
+      <span
+        ref={ref}
+        className={cn('group relative inline focus-within:outline-none', className)}
+        {...props}
+      >
+        <button
+          type="button"
+          aria-describedby={`citation-${source.id}-card`}
+          className="inline-flex items-baseline rounded-sm text-left focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+        >
+          {children ?? <span>{source.title}</span>}
+          <span
+            aria-hidden="true"
+            className="inline-flex items-center justify-center align-super ml-0.5 h-4 min-w-4 px-1 rounded-full border border-border bg-muted text-[10px] font-medium text-muted-foreground group-hover:text-foreground transition-colors"
+          >
+            {source.title.charAt(0).toUpperCase()}
+          </span>
+        </button>
+        <span
+          id={`citation-${source.id}-card`}
+          role="tooltip"
+          className="pointer-events-none absolute bottom-full left-1/2 z-10 mb-1 -translate-x-1/2 w-64 rounded-md border border-border bg-popover p-2.5 text-xs text-popover-foreground shadow-md opacity-0 group-hover:opacity-100 focus-within:opacity-100 transition-opacity"
+        >
+          <span className="block font-medium text-foreground truncate">{source.title}</span>
+          {source.snippet && (
+            <span className="mt-0.5 block text-muted-foreground line-clamp-3">
+              {source.snippet}
+            </span>
+          )}
+        </span>
+      </span>
+    );
+  }
+);
+InlineCitation.displayName = 'InlineCitation';
+
+export { InlineCitation };

package/src/components/inline-citation/index.ts

@@ -0,0 +1,2 @@
+export { InlineCitation } from './InlineCitation';
+export type { InlineCitationProps } from './InlineCitation';

package/src/components/message/Message.error-edit.test.tsx

@@ -0,0 +1,60 @@
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { describe, expect, it, vi } from 'vitest';
+import { Message } from './Message';
+
+const base = { id: 'm1', role: 'assistant' as const, content: 'Hello' };
+
+describe('Message error/retry', () => {
+  it('renders an error alert with retry action', async () => {
+    const user = userEvent.setup();
+    const onRetry = vi.fn();
+    render(<Message message={base} error="Generation failed" onRetry={onRetry} />);
+
+    expect(screen.getByRole('alert')).toHaveTextContent('Generation failed');
+    await user.click(screen.getByRole('button', { name: /Retry/ }));
+    expect(onRetry).toHaveBeenCalledOnce();
+  });
+
+  it('hides retry without a handler', () => {
+    render(<Message message={base} error="Generation failed" />);
+    expect(screen.getByText('Generation failed')).toBeInTheDocument();
+    expect(screen.queryByRole('button')).not.toBeInTheDocument();
+  });
+});
+
+describe('Message edit flow', () => {
+  it('swaps content into an editable textarea and reports the commit', async () => {
+    const user = userEvent.setup();
+    const onEditContent = vi.fn();
+    render(
+      <Message message={{ id: 'u1', role: 'user', content: 'Original question' }} onEditContent={onEditContent} />
+    );
+
+    await user.click(screen.getByRole('button', { name: 'Edit' }));
+    const textarea = screen.getByLabelText('Edit message');
+    expect(textarea).toHaveValue('Original question');
+
+    await user.clear(textarea);
+    await user.type(textarea, 'Revised question');
+    await user.click(screen.getByRole('button', { name: 'Save & resend' }));
+
+    expect(onEditContent).toHaveBeenCalledWith('Revised question');
+    expect(screen.queryByLabelText('Edit message')).not.toBeInTheDocument();
+  });
+
+  it('cancels editing without reporting', async () => {
+    const user = userEvent.setup();
+    const onEditContent = vi.fn();
+    render(<Message message={base} onEditContent={onEditContent} />);
+
+    await user.click(screen.getByRole('button', { name: 'Edit' }));
+    await user.click(screen.getByRole('button', { name: 'Cancel' }));
+    expect(onEditContent).not.toHaveBeenCalled();
+  });
+
+  it('does not render Edit without onEditContent', () => {
+    render(<Message message={base} />);
+    expect(screen.queryByRole('button', { name: 'Edit' })).not.toBeInTheDocument();
+  });
+});

package/src/components/message/Message.test.tsx

@@ -0,0 +1,80 @@
+import { render, screen } from '@testing-library/react';
+import { axe } from 'jest-axe';
+import { describe, expect, it } from 'vitest';
+import { Message } from './Message';
+import type { Message as MessageType } from '../../types';
+
+const userMessage: MessageType = {
+  id: 'm1',
+  role: 'user',
+  content: 'What is the capital of France?',
+};
+
+const assistantMessage: MessageType = {
+  id: 'm2',
+  role: 'assistant',
+  content: 'The capital of France is Paris.',
+};
+
+describe('Message', () => {
+  it('renders message content', () => {
+    render(<Message message={userMessage} />);
+    expect(screen.getByText('What is the capital of France?')).toBeInTheDocument();
+  });
+
+  it('defaults to English role labels', () => {
+    render(
+      <div>
+        <Message message={userMessage} />
+        <Message message={assistantMessage} />
+      </div>
+    );
+    expect(screen.getByText('You')).toBeInTheDocument();
+    expect(screen.getByText('Assistant')).toBeInTheDocument();
+  });
+
+  it('supports localized role labels', () => {
+    render(<Message message={userMessage} userLabel="Sie" />);
+    expect(screen.getByText('Sie')).toBeInTheDocument();
+    expect(screen.queryByText('You')).not.toBeInTheDocument();
+  });
+
+  it('shows a streaming cursor and aria-busy while isStreaming', () => {
+    render(<Message message={assistantMessage} isStreaming />);
+    expect(screen.getByTestId('streaming-cursor')).toBeInTheDocument();
+    const bubble = screen.getByText(assistantMessage.content).closest('[aria-busy]');
+    expect(bubble).not.toBeNull();
+  });
+
+  it('does not show a cursor when not streaming', () => {
+    render(<Message message={assistantMessage} />);
+    expect(screen.queryByTestId('streaming-cursor')).not.toBeInTheDocument();
+  });
+
+  it('delegates rendering to renderContent when provided', () => {
+    render(
+      <Message
+        message={{ ...assistantMessage, content: '**bold** text' }}
+        renderContent={(content) => <strong data-testid="custom">{content}</strong>}
+      />
+    );
+    const custom = screen.getByTestId('custom');
+    expect(custom).toHaveTextContent('**bold** text');
+    // Default plain-text node is replaced by the custom renderer output.
+    expect(custom.parentElement).not.toHaveTextContent('whitespace-pre-wrap');
+  });
+
+  it('shows a timestamp when provided', () => {
+    render(
+      <Message
+        message={{ ...assistantMessage, timestamp: new Date('2026-01-01T12:00:00') }}
+      />
+    );
+    expect(screen.getByText(/:\d{2}/)).toBeInTheDocument();
+  });
+
+  it('has no accessibility violations', async () => {
+    const { container } = render(<Message message={userMessage} />);
+    expect(await axe(container)).toHaveNoViolations();
+  });
+});