@slipstream-ui/ai 0.0.0-stage → 0.3.0

package/src/components/reasoning/Reasoning.tsx

@@ -0,0 +1,85 @@
+'use client';
+
+import * as React from 'react';
+import { cn } from '@slipstream-ui/core';
+import type { ReasoningStep } from '../../types';
+
+export type ReasoningProps = {
+  steps: ReasoningStep[];
+  className?: string;
+  collapsible?: boolean;
+  defaultExpanded?: boolean;
+  /** Elapsed thinking time, e.g. 4 (seconds) or "4s"; rendered in the header. */
+  duration?: number | string;
+  /** Marks reasoning as still arriving: animated header state. */
+  isStreaming?: boolean;
+};
+
+const Reasoning = React.forwardRef<HTMLDivElement, ReasoningProps>(
+  ({ steps, className, collapsible = true, defaultExpanded = false, duration, isStreaming = false, ...props }, ref) => {
+    const [isExpanded, setIsExpanded] = React.useState(defaultExpanded);
+    const contentId = React.useId();
+
+    if (steps.length === 0) {
+      return null;
+    }
+
+    const headerText = [
+      'Reasoning',
+      `(${steps.length} ${steps.length === 1 ? 'step' : 'steps'})`,
+      typeof duration === 'number' ? `· ${duration}s` : duration ? `· ${duration}` : '',
+      isStreaming ? '· thinking…' : '',
+    ]
+      .filter(Boolean)
+      .join(' ');
+
+    return (
+      <div ref={ref} className={cn('border-l-2 border-muted-foreground/30 pl-4', className)} {...props}>
+        {collapsible ? (
+          <button
+            onClick={() => setIsExpanded(!isExpanded)}
+            className="flex items-center gap-2 text-sm font-medium text-muted-foreground hover:text-foreground transition-colors"
+            aria-expanded={isExpanded}
+            aria-controls={contentId}
+          >
+            <span className={cn('transition-transform', isExpanded ? 'rotate-90' : '')}>▶</span>
+            <span>{headerText}</span>
+            {isStreaming && (
+              <span className="flex gap-0.5" aria-hidden="true">
+                {[0, 150, 300].map((delay) => (
+                  <span
+                    key={delay}
+                    className="h-1 w-1 rounded-full bg-muted-foreground animate-pulse motion-reduce:animate-none"
+                    style={{ animationDelay: `${delay}ms` }}
+                  />
+                ))}
+              </span>
+            )}
+          </button>
+        ) : null}
+
+        {(isExpanded || !collapsible) && (
+          <div id={contentId} className="mt-3 space-y-3">
+            {steps.map((step, index) => (
+              <div key={step.id} className="flex gap-3">
+                <div className="w-3 h-3 rounded-full bg-primary/20 border-2 border-primary flex-shrink-0 mt-1" />
+                <div className="text-sm flex-1">
+                  <div className="font-medium text-foreground mb-1">Step {index + 1}</div>
+                  <div className="text-muted-foreground">{step.content}</div>
+                  {step.timestamp && (
+                    <div className="text-xs text-muted-foreground mt-1">
+                      {new Date(step.timestamp).toLocaleTimeString()}
+                    </div>
+                  )}
+                </div>
+              </div>
+            ))}
+          </div>
+        )}
+      </div>
+    );
+  }
+);
+Reasoning.displayName = 'Reasoning';
+
+export { Reasoning };

package/src/components/reasoning/index.ts

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

package/src/components/response/Response.test.tsx

@@ -0,0 +1,69 @@
+import { render, screen } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+import { Response } from './Response';
+import { closeIncompleteMarkdown } from './close-incomplete-markdown';
+
+describe('closeIncompleteMarkdown', () => {
+  it('leaves complete markdown untouched', () => {
+    const text = 'Hello **world** and `code`';
+    expect(closeIncompleteMarkdown(text)).toBe(text);
+  });
+
+  it('closes an unclosed bold marker', () => {
+    expect(closeIncompleteMarkdown('Hello **wor')).toBe('Hello **wor**');
+  });
+
+  it('closes unclosed inline code', () => {
+    expect(closeIncompleteMarkdown('Run `npm dev')).toBe('Run `npm dev`');
+  });
+
+  it('closes an unterminated code fence', () => {
+    const result = closeIncompleteMarkdown('Example:\n```js\nconst x = 1;');
+    expect(result.endsWith('```')).toBe(true);
+  });
+
+  it('does not touch content inside an open fence', () => {
+    // The unclosed `**` after the fence is code content and must stay as-is.
+    const result = closeIncompleteMarkdown('```js\n// ** not emphasis');
+    expect(result.endsWith('```')).toBe(true);
+    expect(result).toContain('// ** not emphasis\n```');
+  });
+});
+
+describe('Response', () => {
+  it('renders markdown paragraphs', () => {
+    render(<Response>{'# Heading\n\nParagraph with **bold**.'}</Response>);
+    expect(screen.getByRole('heading', { level: 1 })).toHaveTextContent('Heading');
+    expect(screen.getByText(/bold/)).toBeInTheDocument();
+  });
+
+  it('renders GFM tables and task lists', () => {
+    render(
+      <Response>{'| a | b |\n|---|---|\n| 1 | 2 |'}</Response>
+    );
+    expect(screen.getByRole('table')).toBeInTheDocument();
+  });
+
+  it('renders fenced code through CodeBlock with language label', () => {
+    render(<Response>{'```python\nprint("hi")\n```'}</Response>);
+    expect(screen.getByText('python')).toBeInTheDocument();
+  });
+
+  it('repairs incomplete bold while streaming', () => {
+    render(<Response>{'Partial **mess'}</Response>);
+    // The repaired marker means no stray asterisks appear as literal text nodes
+    // beyond the closed pair; assert the strong element rendered.
+    expect(screen.getByText('mess').closest('strong') ?? screen.queryByText('**')).toBeTruthy();
+  });
+
+  it('passes raw content through when parseIncompleteMarkdown is false', () => {
+    render(<Response parseIncompleteMarkdown={false}>{'Partial **mess'}</Response>);
+    expect(screen.getByText(/\*\*/)).toBeInTheDocument();
+  });
+
+  it('renders inline code distinctly', () => {
+    render(<Response>{'Use `npm install` first.'}</Response>);
+    const inline = screen.getByText('npm install');
+    expect(inline).toHaveClass('font-mono');
+  });
+});

package/src/components/response/Response.tsx

@@ -0,0 +1,75 @@
+'use client';
+
+import * as React from 'react';
+import ReactMarkdown from 'react-markdown';
+import remarkGfm from 'remark-gfm';
+import { cn } from '@slipstream-ui/core';
+import { CodeBlock } from '../code-block';
+import { closeIncompleteMarkdown } from './close-incomplete-markdown';
+
+export type ResponseProps = {
+  /** Markdown content to render. */
+  children: string;
+  /**
+   * Repair unclosed emphasis/inline-code/fences while streaming so partial
+   * chunks render cleanly (default true).
+   */
+  parseIncompleteMarkdown?: boolean;
+  className?: string;
+};
+
+/**
+ * Streaming-optimized markdown renderer for AI responses.
+ *
+ * Wraps react-markdown with GFM support and routes fenced code blocks to
+ * the CodeBlock component for highlighting + copy.
+ */
+const Response = React.forwardRef<HTMLDivElement, ResponseProps>(
+  ({ children, parseIncompleteMarkdown = true, className, ...props }, ref) => {
+    const content = React.useMemo(
+      () => (parseIncompleteMarkdown ? closeIncompleteMarkdown(children) : children),
+      [children, parseIncompleteMarkdown]
+    );
+
+    return (
+      <div
+        ref={ref}
+        className={cn(
+          'text-sm space-y-3 [&_a]:text-primary [&_a]:underline underline-offset-2',
+          '[&_ul]:list-disc [&_ul]:pl-5 [&_ol]:list-decimal [&_ol]:pl-5',
+          '[&_h1]:text-lg [&_h1]:font-semibold [&_h2]:text-base [&_h2]:font-semibold',
+          '[&_h3]:text-sm [&_h3]:font-semibold',
+          '[&_blockquote]:border-l-2 [&_blockquote]:border-border [&_blockquote]:pl-3 [&_blockquote]:text-muted-foreground',
+          '[&_table]:w-full [&_table]:text-xs [&_th]:border [&_th]:border-border [&_th]:p-1.5 [&_td]:border [&_td]:border-border [&_td]:p-1.5',
+          className
+        )}
+        {...props}
+      >
+        <ReactMarkdown
+          remarkPlugins={[remarkGfm]}
+          components={{
+            pre: ({ children }) => <>{children}</>,
+            code: ({ className: codeClassName, children: codeChildren }) => {
+              const raw = String(codeChildren).replace(/\n$/, '');
+              const match = /language-(\w+)/.exec(codeClassName ?? '');
+              const isInline = !match && !raw.includes('\n');
+              if (isInline) {
+                return (
+                  <code className="bg-muted px-1 py-0.5 rounded text-xs font-mono before:content-none after:content-none">
+                    {raw}
+                  </code>
+                );
+              }
+              return <CodeBlock code={raw} language={match?.[1] ?? 'text'} />;
+            },
+          }}
+        >
+          {content}
+        </ReactMarkdown>
+      </div>
+    );
+  }
+);
+Response.displayName = 'Response';
+
+export { Response };

package/src/components/response/close-incomplete-markdown.ts

@@ -0,0 +1,47 @@
+/**
+ * Repairs markdown that is mid-stream: closes unclosed bold/italic/strikethrough
+ * markers and unterminated inline code / code fences so partial chunks render
+ * without flickering or broken syntax.
+ *
+ * Deliberately conservative — only appends closing characters, never rewrites content.
+ */
+export function closeIncompleteMarkdown(markdown: string): string {
+  let text = markdown;
+
+  // Close an unterminated fenced code block (odd number of ``` lines).
+  const fenceMatches = text.match(/^`{3,}/gm);
+  if (fenceMatches && fenceMatches.length % 2 === 1) {
+    text = `${text}\n\`\`\``;
+  }
+
+  // Inline constructs are only repaired outside of code fences for simplicity:
+  // if we just opened a fence, the remainder is code and should not be touched.
+  const firstFence = text.indexOf('```');
+  const hasUnclosedFence = fenceMatches !== null && fenceMatches.length % 2 === 1;
+  const prose = hasUnclosedFence && firstFence !== -1 ? text.slice(0, firstFence) : text;
+  const rest = hasUnclosedFence && firstFence !== -1 ? text.slice(firstFence) : '';
+
+  let repaired = prose;
+  // Count unescaped emphasis markers; close whichever are odd.
+  for (const marker of ['**', '__', '~~']) {
+    const occurrences = prose.split(marker).length - 1;
+    if (occurrences % 2 === 1) {
+      repaired += marker;
+    }
+  }
+  // Single asterisk/underscore italics.
+  for (const marker of ['*', '_']) {
+    // Only count markers not part of **/__ pairs by stripping doubles first.
+    const singles = repaired.replace(/\*\*/g, '').replace(/__/g, '').split(marker).length - 1;
+    if (singles % 2 === 1) {
+      repaired += marker;
+    }
+  }
+  // Inline code.
+  const backtickCount = repaired.replace(/```/g, '').split('`').length - 1;
+  if (backtickCount % 2 === 1) {
+    repaired += '`';
+  }
+
+  return repaired + rest;
+}

package/src/components/response/index.ts

@@ -0,0 +1,3 @@
+export { Response } from './Response';
+export type { ResponseProps } from './Response';
+export { closeIncompleteMarkdown } from './close-incomplete-markdown';

package/src/components/source/Source.tsx

@@ -0,0 +1,51 @@
+import * as React from 'react';
+import { cn } from '@slipstream-ui/core';
+import type { SourceItem } from '../../types';
+
+export type SourceProps = {
+  source: SourceItem;
+  /**
+   * 1-based citation marker rendered as a `[n]` prefix.
+   * Omit to render the citation without numbering.
+   */
+  index?: number;
+  className?: string;
+};
+
+const Source = React.forwardRef<HTMLDivElement, SourceProps>(
+  ({ source, index, className, ...props }, ref) => {
+    return (
+      <div ref={ref} className={cn('flex gap-2 items-start text-sm', className)} {...props}>
+        {index !== undefined && (
+          <span className="text-muted-foreground select-none" aria-hidden="true">
+            [{index}]
+          </span>
+        )}
+        <div className="flex-1 min-w-0">
+          <div className="font-medium text-foreground">
+            {source.url ? (
+              <a
+                href={source.url}
+                target="_blank"
+                rel="noopener noreferrer"
+                className="hover:text-primary transition-colors"
+              >
+                {source.title}
+              </a>
+            ) : (
+              <span>{source.title}</span>
+            )}
+          </div>
+          {source.snippet && (
+            <div className="text-xs text-muted-foreground mt-1 line-clamp-2">
+              {source.snippet}
+            </div>
+          )}
+        </div>
+      </div>
+    );
+  }
+);
+Source.displayName = 'Source';
+
+export { Source };

package/src/components/source/Sources.tsx

@@ -0,0 +1,42 @@
+import * as React from 'react';
+import { cn } from '@slipstream-ui/core';
+import type { SourceItem } from '../../types';
+import { Source } from './Source';
+
+export type SourcesProps = {
+  sources: SourceItem[];
+  className?: string;
+  maxDisplay?: number;
+  /** Heading label; override for localization. */
+  label?: string;
+};
+
+const Sources = React.forwardRef<HTMLDivElement, SourcesProps>(
+  ({ sources, className, maxDisplay = 3, label = 'Sources', ...props }, ref) => {
+    const displaySources = maxDisplay ? sources.slice(0, maxDisplay) : sources;
+    const hasMore = maxDisplay && sources.length > maxDisplay;
+
+    if (sources.length === 0) {
+      return null;
+    }
+
+    return (
+      <div ref={ref} className={cn('mt-4 pt-4 border-t border-border', className)} {...props}>
+        <div className="text-xs font-medium text-muted-foreground mb-2">{label}</div>
+        <div className="space-y-2">
+          {displaySources.map((source, index) => (
+            <Source key={source.id} source={source} index={index + 1} />
+          ))}
+          {hasMore && (
+            <div className="text-xs text-muted-foreground">
+              +{sources.length - (maxDisplay ?? 0)} more sources
+            </div>
+          )}
+        </div>
+      </div>
+    );
+  }
+);
+Sources.displayName = 'Sources';
+
+export { Sources };

package/src/components/source/index.ts

@@ -0,0 +1,5 @@
+export { Source } from './Source';
+export type { SourceProps } from './Source';
+export { Sources } from './Sources';
+export type { SourcesProps } from './Sources';
+

package/src/components/source/source.test.tsx

@@ -0,0 +1,72 @@
+import { render, screen } from '@testing-library/react';
+import { axe } from 'jest-axe';
+import { describe, expect, it } from 'vitest';
+import { Source } from './Source';
+import { Sources } from './Sources';
+
+describe('Source', () => {
+  it('renders the title as a link when a URL is provided', () => {
+    render(<Source source={{ id: '1', title: 'React docs', url: 'https://react.dev' }} index={1} />);
+    const link = screen.getByRole('link', { name: 'React docs' });
+    expect(link).toHaveAttribute('href', 'https://react.dev');
+    expect(link).toHaveAttribute('rel', 'noopener noreferrer');
+  });
+
+  it('renders plain text without a URL', () => {
+    render(<Source source={{ id: '1', title: 'Internal note' }} />);
+    expect(screen.getByText('Internal note')).toBeInTheDocument();
+    expect(screen.queryByRole('link')).not.toBeInTheDocument();
+  });
+
+  it('shows a citation marker that is hidden from assistive tech', () => {
+    render(<Source source={{ id: '1', title: 'Docs' }} index={3} />);
+    expect(screen.getByText('[3]')).toHaveAttribute('aria-hidden', 'true');
+  });
+
+  it('omits the marker when no index is given', () => {
+    const { container } = render(<Source source={{ id: '1', title: 'Docs' }} />);
+    expect(container.querySelector('[aria-hidden="true"]')).toBeNull();
+  });
+
+  it('shows the snippet when provided', () => {
+    render(<Source source={{ id: '1', title: 'Docs', snippet: 'Useful excerpt' }} />);
+    expect(screen.getByText('Useful excerpt')).toBeInTheDocument();
+  });
+});
+
+describe('Sources', () => {
+  const sources = [
+    { id: '1', title: 'First', url: 'https://example.com/1' },
+    { id: '2', title: 'Second', url: 'https://example.com/2' },
+    { id: '3', title: 'Third', url: 'https://example.com/3' },
+    { id: '4', title: 'Fourth', url: 'https://example.com/4' },
+  ];
+
+  it('renders numbered citations in order', () => {
+    render(<Sources sources={sources.slice(0, 2)} />);
+    expect(screen.getByText('[1]')).toBeInTheDocument();
+    expect(screen.getByText('[2]')).toBeInTheDocument();
+    expect(screen.getByRole('link', { name: 'First' })).toBeInTheDocument();
+  });
+
+  it('caps display at maxDisplay and shows an overflow count', () => {
+    render(<Sources sources={sources} maxDisplay={3} />);
+    expect(screen.queryByRole('link', { name: 'Fourth' })).not.toBeInTheDocument();
+    expect(screen.getByText('+1 more sources')).toBeInTheDocument();
+  });
+
+  it('supports a custom label', () => {
+    render(<Sources sources={sources.slice(0, 1)} label="Referencias" />);
+    expect(screen.getByText('Referencias')).toBeInTheDocument();
+  });
+
+  it('renders nothing for an empty list', () => {
+    const { container } = render(<Sources sources={[]} />);
+    expect(container).toBeEmptyDOMElement();
+  });
+
+  it('has no accessibility violations', async () => {
+    const { container } = render(<Sources sources={sources.slice(0, 2)} />);
+    expect(await axe(container)).toHaveNoViolations();
+  });
+});

package/src/components/streaming/StreamingIndicator.test.tsx

@@ -0,0 +1,26 @@
+import { render, screen } from '@testing-library/react';
+import { axe } from 'jest-axe';
+import { describe, expect, it } from 'vitest';
+import { StreamingIndicator } from './StreamingIndicator';
+
+describe('StreamingIndicator', () => {
+  it('shows the default text while streaming', () => {
+    render(<StreamingIndicator isStreaming />);
+    expect(screen.getByText('Generating...')).toBeInTheDocument();
+  });
+
+  it('supports custom text', () => {
+    render(<StreamingIndicator isStreaming text="Denkt nach..." />);
+    expect(screen.getByText('Denkt nach...')).toBeInTheDocument();
+  });
+
+  it('renders nothing when not streaming', () => {
+    const { container } = render(<StreamingIndicator isStreaming={false} />);
+    expect(container).toBeEmptyDOMElement();
+  });
+
+  it('has no accessibility violations', async () => {
+    const { container } = render(<StreamingIndicator isStreaming />);
+    expect(await axe(container)).toHaveNoViolations();
+  });
+});

package/src/components/streaming/StreamingIndicator.tsx

@@ -0,0 +1,46 @@
+import * as React from 'react';
+import { cn } from '@slipstream-ui/core';
+
+export type StreamingIndicatorProps = {
+  isStreaming: boolean;
+  className?: string;
+  text?: string;
+};
+
+/**
+ * Animated three-dot streaming indicator. Announces the streaming state
+ * to screen readers via role="status" / aria-live so assistive tech
+ * users know generation is in progress.
+ */
+const StreamingIndicator = React.forwardRef<HTMLDivElement, StreamingIndicatorProps>(
+  ({ isStreaming, className, text = 'Generating...', ...props }, ref) => {
+    if (!isStreaming) {
+      return null;
+    }
+
+    return (
+      <div
+        ref={ref}
+        role="status"
+        aria-live="polite"
+        aria-label={text}
+        className={cn('flex items-center gap-2 text-sm text-muted-foreground', className)}
+        {...props}
+      >
+        <div className="flex gap-1" aria-hidden="true">
+          {[0, 150, 300].map((delay) => (
+            <span
+              key={delay}
+              className="w-2 h-2 bg-primary rounded-full animate-pulse motion-reduce:animate-none"
+              style={{ animationDelay: `${delay}ms` }}
+            />
+          ))}
+        </div>
+        <span>{text}</span>
+      </div>
+    );
+  }
+);
+StreamingIndicator.displayName = 'StreamingIndicator';
+
+export { StreamingIndicator };

package/src/components/streaming/index.ts

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

package/src/components/suggestion/Suggestion.test.tsx

@@ -0,0 +1,43 @@
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { axe } from 'jest-axe';
+import { describe, expect, it, vi } from 'vitest';
+import { Suggestions } from './Suggestion';
+
+const suggestions = [
+  { id: '1', text: 'Explain recursion' },
+  { id: '2', text: 'Write a haiku', type: 'action' as const },
+  { id: '3', text: 'Summarize this page' },
+];
+
+describe('Suggestions', () => {
+  it('renders every suggestion as a button', () => {
+    render(<Suggestions suggestions={suggestions} />);
+    expect(screen.getByRole('button', { name: 'Explain recursion' })).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: 'Write a haiku' })).toBeInTheDocument();
+  });
+
+  it('calls onSelect with the clicked suggestion', async () => {
+    const user = userEvent.setup();
+    const handleSelect = vi.fn();
+    render(<Suggestions suggestions={suggestions} onSelect={handleSelect} />);
+    await user.click(screen.getByRole('button', { name: 'Write a haiku' }));
+    expect(handleSelect).toHaveBeenCalledWith(suggestions[1]);
+  });
+
+  it('limits visible suggestions to maxDisplay', () => {
+    render(<Suggestions suggestions={suggestions} maxDisplay={2} />);
+    expect(screen.getByRole('button', { name: 'Explain recursion' })).toBeInTheDocument();
+    expect(screen.queryByRole('button', { name: 'Summarize this page' })).not.toBeInTheDocument();
+  });
+
+  it('renders nothing for an empty list', () => {
+    const { container } = render(<Suggestions suggestions={[]} />);
+    expect(container).toBeEmptyDOMElement();
+  });
+
+  it('has no accessibility violations', async () => {
+    const { container } = render(<Suggestions suggestions={suggestions} />);
+    expect(await axe(container)).toHaveNoViolations();
+  });
+});

package/src/components/suggestion/Suggestion.tsx

@@ -0,0 +1,47 @@
+import * as React from 'react';
+import { cn } from '@slipstream-ui/core';
+
+export type Suggestion = {
+  id: string;
+  text: string;
+  type?: 'action' | 'query' | 'follow-up';
+};
+
+export type SuggestionsProps = {
+  suggestions: Suggestion[];
+  onSelect?: (suggestion: Suggestion) => void;
+  className?: string;
+  maxDisplay?: number;
+};
+
+const Suggestions = React.forwardRef<HTMLDivElement, SuggestionsProps>(
+  ({ suggestions, onSelect, className, maxDisplay = 4, ...props }, ref) => {
+  const displaySuggestions = maxDisplay ? suggestions.slice(0, maxDisplay) : suggestions;
+
+  if (suggestions.length === 0) {
+    return null;
+  }
+
+  return (
+    <div ref={ref} className={cn('mt-4 space-y-2', className)} {...props}>
+      {displaySuggestions.map((suggestion) => (
+        <button
+          key={suggestion.id}
+          className={cn(
+            'w-full text-left h-auto py-2 px-3 text-sm rounded-md',
+            'hover:bg-accent hover:text-accent-foreground',
+            'transition-colors',
+            'text-muted-foreground',
+            'focus:outline-none focus:ring-2 focus:ring-ring'
+          )}
+          onClick={() => onSelect?.(suggestion)}
+        >
+          {suggestion.text}
+        </button>
+      ))}
+    </div>
+  );
+});
+Suggestions.displayName = 'Suggestions';
+
+export { Suggestions };

package/src/components/suggestion/index.ts

@@ -0,0 +1,2 @@
+export { Suggestions } from './Suggestion';
+export type { SuggestionsProps, Suggestion } from './Suggestion';