@tribepad/themis 1.3.4 → 1.5.0

package/dist/styles/defaults.css

@@ -108,6 +108,9 @@
   --radius-lg: 0.5rem;
   --radius-full: 9999px;
 
+  /* ChatInterface */
+  --chat-input-max-lines: 6;
+
   /* Shadows */
   --shadow-sm: 0 1px 2px 0 rgb(0 0 0 / 0.05);
   --shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tribepad/themis",
-  "version": "1.3.4",
+  "version": "1.5.0",
   "description": "Accessible React component library built on React Aria primitives",
   "author": "Tribepad <mbasford@tribepad.com>",
   "license": "MIT",
@@ -149,55 +149,58 @@
     }
   },
   "dependencies": {
-    "@internationalized/date": "^3.12.0",
+    "@internationalized/date": "^3.12.1",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
-    "react-aria": "^3.47.0",
-    "react-aria-components": "^1.16.0",
-    "react-stately": "^3.45.0",
+    "react-aria": "^3.48.0",
+    "react-aria-components": "^1.17.0",
+    "react-stately": "^3.46.0",
     "tailwind-merge": "^3.5.0"
   },
   "devDependencies": {
-    "@eslint/js": "^9.39.4",
-    "@size-limit/preset-small-lib": "^11.2.0",
+    "@eslint/js": "^10.0.1",
+    "@size-limit/preset-small-lib": "^12.1.0",
     "@storybook/addon-a11y": "^10.3.5",
-    "@storybook/addon-mcp": "^0.4.2",
+    "@storybook/addon-mcp": "^0.6.0",
     "@storybook/react-vite": "^10.3.5",
-    "@tailwindcss/vite": "^4.2.2",
+    "@tailwindcss/vite": "^4.2.4",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.2",
     "@testing-library/user-event": "^14.6.1",
     "@types/node": "^25.6.0",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
-    "@typescript-eslint/eslint-plugin": "^8.58.2",
-    "@typescript-eslint/parser": "^8.58.2",
-    "@vitejs/plugin-react": "^5.2.0",
-    "@vitest/coverage-v8": "^4.1.4",
-    "eslint": "^9.39.4",
+    "@typescript-eslint/eslint-plugin": "^8.59.0",
+    "@typescript-eslint/parser": "^8.59.0",
+    "@vitejs/plugin-react": "^6.0.1",
+    "@vitest/coverage-v8": "^4.1.5",
+    "eslint": "^10.2.1",
     "eslint-plugin-jsx-a11y": "^6.10.2",
-    "eslint-plugin-storybook": "10.3.3",
+    "eslint-plugin-storybook": "10.3.5",
     "globals": "^17.5.0",
     "happy-dom": "^20.9.0",
     "jest-axe": "^10.0.0",
-    "jsdom": "^28.1.0",
-    "lucide-react": "^1.8.0",
+    "jsdom": "^29.1.0",
+    "lucide-react": "^1.11.0",
     "motion": "^12.38.0",
     "react": "^19.2.5",
     "react-dom": "^19.2.5",
-    "size-limit": "^11.2.0",
+    "size-limit": "^12.1.0",
     "storybook": "^10.3.5",
     "tsup": "^8.5.1",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
-    "vite": "^8.0.8",
-    "vitest": "^4.1.4",
+    "vite": "^8.0.10",
+    "vitest": "^4.1.5",
     "zod": "^4.3.6"
   },
   "pnpm": {
     "onlyBuiltDependencies": [
       "esbuild"
-    ]
+    ],
+    "overrides": {
+      "postcss@<8.5.10": "^8.5.12"
+    }
   },
   "engines": {
     "node": ">=18.0.0"
@@ -255,6 +258,11 @@
       "name": "PageTitle only",
       "path": "dist/elements/PageTitle/index.mjs",
       "limit": "60 KB"
+    },
+    {
+      "name": "ChatInterface only",
+      "path": "dist/elements/ChatInterface/index.mjs",
+      "limit": "28 KB"
     }
   ],
   "keywords": [

package/src/elements/ChatInterface/ChatInterface.stories.tsx

@@ -0,0 +1,495 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import {
+  forwardRef,
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  useMemo,
+  useRef,
+  useState,
+  type ReactElement,
+} from 'react';
+import { Bot, User } from 'lucide-react';
+import { ChatInterface } from './ChatInterface';
+import type {
+  ChatInputComponent,
+  ChatInputComponentHandle,
+  ChatInterfaceHandle,
+  ChatMessage,
+  ChatTopLevelStatus,
+} from './ChatInterface.types';
+
+const meta = {
+  title: 'Elements/ChatInterface',
+  component: ChatInterface,
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component:
+          'WCAG 2.2 AAA-compliant chatbot UI. Stateless from the library\'s perspective — the consumer owns messages, status, and websocket. Markdown is rendered by the consumer via render props (see "BYO markdown" story for `react-markdown` + `rehype-sanitize` setup). The `<div role="log">` is visual + navigable; a single sr-only `<div role="status">` is the only AT announcement channel (completion, stop, error, bounded "still working" pings).',
+      },
+    },
+  },
+  tags: ['autodocs'],
+} satisfies Meta<typeof ChatInterface>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const ASSISTANT_AVATAR = (
+  <span className="flex h-8 w-8 items-center justify-center rounded-full bg-[var(--primary-action)] text-[var(--primary-action-foreground)]">
+    <Bot className="h-4 w-4" aria-hidden="true" />
+  </span>
+);
+
+const USER_AVATAR = (
+  <span className="flex h-8 w-8 items-center justify-center rounded-full bg-[var(--muted)]">
+    <User className="h-4 w-4" aria-hidden="true" />
+  </span>
+);
+
+const DEFAULT_EMPTY_STATE = (
+  <div className="text-center text-[var(--muted-foreground)]">
+    <p className="text-lg font-medium">How can we help?</p>
+    <p className="mt-2 text-sm">Ask a question to get started.</p>
+  </div>
+);
+
+// ---------------------------------------------------------------------------
+// Empty state
+// ---------------------------------------------------------------------------
+export const Empty: Story = {
+  render: () => (
+    <div className="h-screen mx-auto max-w-2xl">
+      <ChatInterface
+        messages={[]}
+        status="idle"
+        onSendMessage={() => {}}
+        emptyState={DEFAULT_EMPTY_STATE}
+        assistantAvatar={ASSISTANT_AVATAR}
+        userAvatar={USER_AVATAR}
+      />
+    </div>
+  ),
+};
+
+// ---------------------------------------------------------------------------
+// Plain conversation
+// ---------------------------------------------------------------------------
+function PlainHarness(): ReactElement {
+  const [messages, setMessages] = useState<ChatMessage[]>([
+    { id: '1', role: 'user', status: 'complete', content: 'Hi, can you help me reset my password?' },
+    { id: '2', role: 'assistant', status: 'complete', content: 'Of course! Visit Settings → Security → Reset password. You\'ll get an email with a link.' },
+    { id: '3', role: 'user', status: 'complete', content: 'Thanks!' },
+  ]);
+  const handleSend = (text: string): void => {
+    setMessages((m) => [
+      ...m,
+      { id: `${m.length + 1}`, role: 'user', status: 'complete', content: text },
+      {
+        id: `${m.length + 2}`,
+        role: 'assistant',
+        status: 'complete',
+        content: 'Got it — I\'ll look into that for you.',
+      },
+    ]);
+  };
+  return (
+    <div className="h-screen mx-auto max-w-2xl">
+      <ChatInterface
+        messages={messages}
+        status="idle"
+        onSendMessage={handleSend}
+        assistantAvatar={ASSISTANT_AVATAR}
+        userAvatar={USER_AVATAR}
+      />
+    </div>
+  );
+}
+export const PlainConversation: Story = {
+  render: () => <PlainHarness />,
+};
+
+// ---------------------------------------------------------------------------
+// Streaming response (mock token-by-token mutation, new object per token)
+// ---------------------------------------------------------------------------
+function StreamingHarness(): ReactElement {
+  const [messages, setMessages] = useState<ChatMessage[]>([]);
+  const [status, setStatus] = useState<ChatTopLevelStatus>('idle');
+  const handleSend = useCallback((text: string): void => {
+    const userId = crypto.randomUUID();
+    const aid = crypto.randomUUID();
+    setMessages((m) => [
+      ...m,
+      { id: userId, role: 'user', status: 'complete', content: text },
+      { id: aid, role: 'assistant', status: 'streaming', content: '' },
+    ]);
+    setStatus('streaming');
+    const reply = 'Thanks for your question! Here is a streamed response that demonstrates the bubble updating token by token, while the screen reader stays silent. Once complete, the status region announces a preview.';
+    let idx = 0;
+    const tick = (): void => {
+      idx += Math.floor(Math.random() * 5) + 1;
+      if (idx >= reply.length) {
+        setMessages((m) =>
+          m.map((msg) =>
+            msg.id === aid && msg.role === 'assistant'
+              ? { ...msg, status: 'complete', content: reply }
+              : msg
+          )
+        );
+        setStatus('idle');
+        return;
+      }
+      setMessages((m) =>
+        m.map((msg) =>
+          msg.id === aid && msg.role === 'assistant'
+            ? { ...msg, content: reply.slice(0, idx) }
+            : msg
+        )
+      );
+      setTimeout(tick, 50);
+    };
+    setTimeout(tick, 200);
+  }, []);
+  const handleStop = useCallback((): void => {
+    setStatus('idle');
+    setMessages((m) =>
+      m.map((msg) =>
+        msg.role === 'assistant' && msg.status === 'streaming'
+          ? { ...msg, status: 'complete' }
+          : msg
+      )
+    );
+  }, []);
+  return (
+    <div className="h-screen mx-auto max-w-2xl">
+      <ChatInterface
+        messages={messages}
+        status={status}
+        onSendMessage={handleSend}
+        onStopGeneration={handleStop}
+        emptyState={DEFAULT_EMPTY_STATE}
+        assistantAvatar={ASSISTANT_AVATAR}
+        userAvatar={USER_AVATAR}
+      />
+    </div>
+  );
+}
+export const Streaming: Story = {
+  render: () => <StreamingHarness />,
+};
+
+// ---------------------------------------------------------------------------
+// Thinking with tool calls
+// ---------------------------------------------------------------------------
+function ThinkingHarness(): ReactElement {
+  const [messages, setMessages] = useState<ChatMessage[]>([
+    { id: 'u1', role: 'user', status: 'complete', content: 'Find me last quarter\'s sales numbers.' },
+    {
+      id: 'a1',
+      role: 'assistant',
+      status: 'thinking',
+      content: '',
+      parts: [
+        { kind: 'tool_call', name: 'search_kb', status: 'done', summary: '3 documents found' },
+        { kind: 'tool_call', name: 'fetch_report', status: 'running' },
+      ],
+    },
+  ]);
+  const [status, setStatus] = useState<ChatTopLevelStatus>('streaming');
+  // Promote to complete after a few seconds for demo purposes.
+  useEffect(() => {
+    const t = setTimeout(() => {
+      setMessages((m) =>
+        m.map((msg) =>
+          msg.id === 'a1' && msg.role === 'assistant'
+            ? {
+                ...msg,
+                status: 'complete',
+                content: 'Q3 revenue was £2.4m, up 14% YoY. Top markets: UK, US, DE.',
+                parts: [
+                  { kind: 'tool_call', name: 'search_kb', status: 'done', summary: '3 documents' },
+                  { kind: 'tool_call', name: 'fetch_report', status: 'done' },
+                ],
+              }
+            : msg
+        )
+      );
+      setStatus('idle');
+    }, 3000);
+    return () => clearTimeout(t);
+  }, []);
+  return (
+    <div className="h-screen mx-auto max-w-2xl">
+      <ChatInterface
+        messages={messages}
+        status={status}
+        onSendMessage={() => {}}
+        onStopGeneration={() => setStatus('idle')}
+        assistantAvatar={ASSISTANT_AVATAR}
+        userAvatar={USER_AVATAR}
+      />
+    </div>
+  );
+}
+export const Thinking: Story = {
+  render: () => <ThinkingHarness />,
+};
+
+// ---------------------------------------------------------------------------
+// Error + retry + escalate
+// ---------------------------------------------------------------------------
+export const ErrorState: Story = {
+  render: () => (
+    <div className="h-screen mx-auto max-w-2xl">
+      <ChatInterface
+        messages={[
+          { id: 'u1', role: 'user', status: 'complete', content: 'Tell me about Themis.' },
+          {
+            id: 'a1',
+            role: 'assistant',
+            status: 'error',
+            content: 'Themis is a',
+            errorMessage: 'Connection lost. Please try again or contact support.',
+          },
+        ]}
+        status="error"
+        onSendMessage={() => {}}
+        onRetry={() => {}}
+        onEscalate={() => {}}
+        assistantAvatar={ASSISTANT_AVATAR}
+        userAvatar={USER_AVATAR}
+      />
+    </div>
+  ),
+};
+
+// ---------------------------------------------------------------------------
+// BYO markdown — DEMO ONLY. Consumers integrating this pattern MUST configure
+// rehype-sanitize, urlTransform stripping `javascript:`/`data:` schemes,
+// `<a>` rel="noopener noreferrer nofollow", and disable images by default
+// unless the assistant content origin is fully trusted.
+// (react-markdown is a devDependency only — not bundled.)
+// ---------------------------------------------------------------------------
+//
+// SECURITY: this story uses a minimal "safe-as-text" renderer to keep the
+// Storybook demo dependency-free. Real consumers should adopt the snippet
+// in the README's "Markdown rendering: security" section.
+function safeMarkdownRender(content: string): ReactElement {
+  // Naive renderer: paragraphs by blank lines, **bold** and *italic*.
+  // Any <, >, & in source is JSX-escaped automatically.
+  const paragraphs = content.split(/\n{2,}/);
+  return (
+    <div className="text-sm leading-relaxed">
+      {paragraphs.map((p, i) => {
+        const parts = p.split(/(\*\*[^*]+\*\*|\*[^*]+\*)/g).filter(Boolean);
+        return (
+          <p key={i} className={i > 0 ? 'mt-2' : ''}>
+            {parts.map((part, j) => {
+              if (/^\*\*[^*]+\*\*$/.test(part)) {
+                return <strong key={j}>{part.slice(2, -2)}</strong>;
+              }
+              if (/^\*[^*]+\*$/.test(part)) {
+                return <em key={j}>{part.slice(1, -1)}</em>;
+              }
+              return <span key={j}>{part}</span>;
+            })}
+          </p>
+        );
+      })}
+    </div>
+  );
+}
+export const ByoMarkdown: Story = {
+  render: () => (
+    <div className="h-screen mx-auto max-w-2xl">
+      <ChatInterface
+        messages={[
+          { id: 'u1', role: 'user', status: 'complete', content: 'How do I get started?' },
+          {
+            id: 'a1',
+            role: 'assistant',
+            status: 'complete',
+            content:
+              'Welcome! Here are **three quick steps** to get you started:\n\n1. Sign in to your account.\n2. Visit *Settings* and configure your preferences.\n3. Start exploring!\n\nLet me know if you need anything else.',
+          },
+        ]}
+        status="idle"
+        onSendMessage={() => {}}
+        renderAssistantContent={(m) => safeMarkdownRender(m.content)}
+        renderUserContent={(m) => <span className="text-sm">{m.content}</span>}
+        assistantAvatar={ASSISTANT_AVATAR}
+        userAvatar={USER_AVATAR}
+      />
+    </div>
+  ),
+};
+
+// ---------------------------------------------------------------------------
+// Custom input — minimal contenteditable RTE that outputs markdown.
+// Demonstrates the ChatInputComponent contract.
+// ---------------------------------------------------------------------------
+const RichInput = forwardRef<
+  ChatInputComponentHandle,
+  {
+    isDisabled: boolean;
+    placeholder?: string;
+    'aria-label'?: string;
+    onSubmit: (markdown: string) => void;
+    onChange?: (markdown: string) => void;
+  }
+>(function RichInput({ isDisabled, placeholder, 'aria-label': ariaLabel, onSubmit, onChange }, ref) {
+  const editorRef = useRef<HTMLDivElement>(null);
+  const valueRef = useRef('');
+
+  const readMarkdown = (): string => {
+    const el = editorRef.current;
+    if (!el) return '';
+    // Naive: read innerText and treat <strong>/<em> as **/**. Real RTEs use proper serializers.
+    return el.innerText.trim();
+  };
+
+  useImperativeHandle(ref, () => ({
+    focus: () => editorRef.current?.focus(),
+    clear: () => {
+      if (editorRef.current) editorRef.current.innerHTML = '';
+      valueRef.current = '';
+      onChange?.('');
+    },
+    submit: () => {
+      const md = readMarkdown();
+      if (!md) return;
+      onSubmit(md);
+    },
+    setValue: (md: string) => {
+      if (editorRef.current) editorRef.current.innerText = md;
+      valueRef.current = md;
+      onChange?.(md);
+    },
+  }));
+
+  return (
+    <div
+      ref={editorRef}
+      role="textbox"
+      tabIndex={isDisabled ? -1 : 0}
+      contentEditable={!isDisabled}
+      aria-label={ariaLabel ?? 'Message'}
+      aria-multiline="true"
+      data-placeholder={placeholder}
+      onInput={(): void => {
+        valueRef.current = readMarkdown();
+        onChange?.(valueRef.current);
+      }}
+      onKeyDown={(e): void => {
+        if (
+          e.key === 'Enter' &&
+          !e.shiftKey &&
+          !(
+            (e.nativeEvent as KeyboardEvent & { isComposing?: boolean }).isComposing ||
+            e.keyCode === 229
+          )
+        ) {
+          e.preventDefault();
+          if (!isDisabled && readMarkdown()) onSubmit(readMarkdown());
+        }
+      }}
+      className="min-h-[44px] max-h-40 overflow-y-auto rounded-[var(--radius-lg)] border border-[var(--input-border)] bg-[var(--input-background)] p-3 text-sm focus:outline-none focus:ring-2 focus:ring-[var(--ring)]"
+      style={{ aspectRatio: 'auto' }}
+    />
+  );
+});
+RichInput.displayName = 'RichInput';
+
+function CustomInputHarness(): ReactElement {
+  const [messages, setMessages] = useState<ChatMessage[]>([]);
+  const handleSend = (md: string): void => {
+    setMessages((m) => [
+      ...m,
+      { id: crypto.randomUUID(), role: 'user', status: 'complete', content: md },
+      { id: crypto.randomUUID(), role: 'assistant', status: 'complete', content: 'Got it.' },
+    ]);
+  };
+  return (
+    <div className="h-screen mx-auto max-w-2xl">
+      <ChatInterface
+        messages={messages}
+        status="idle"
+        onSendMessage={handleSend}
+        inputComponent={RichInput as unknown as ChatInputComponent}
+        renderUserContent={(m) => <span className="text-sm whitespace-pre-wrap">{m.content}</span>}
+        emptyState={DEFAULT_EMPTY_STATE}
+        assistantAvatar={ASSISTANT_AVATAR}
+        userAvatar={USER_AVATAR}
+      />
+    </div>
+  );
+}
+export const CustomInput: Story = {
+  render: () => <CustomInputHarness />,
+};
+
+// ---------------------------------------------------------------------------
+// Long conversation — demonstrates content-visibility skipping offscreen bubbles
+// ---------------------------------------------------------------------------
+function LongHarness(): ReactElement {
+  const messages = useMemo<ChatMessage[]>(() => {
+    const out: ChatMessage[] = [];
+    for (let i = 0; i < 200; i++) {
+      out.push({
+        id: `u${i}`,
+        role: 'user',
+        status: 'complete',
+        content: `Question ${i + 1}: how does this work?`,
+      });
+      out.push({
+        id: `a${i}`,
+        role: 'assistant',
+        status: 'complete',
+        content: `Response ${i + 1}: it works because of the magic of memoised rendering and content-visibility.`,
+      });
+    }
+    return out;
+  }, []);
+  const ref = useRef<ChatInterfaceHandle>(null);
+  return (
+    <div className="h-screen mx-auto max-w-2xl">
+      <ChatInterface
+        ref={ref}
+        messages={messages}
+        status="idle"
+        onSendMessage={() => {}}
+        assistantAvatar={ASSISTANT_AVATAR}
+        userAvatar={USER_AVATAR}
+      />
+    </div>
+  );
+}
+export const LongConversation: Story = {
+  render: () => <LongHarness />,
+};
+
+// ---------------------------------------------------------------------------
+// Reduced motion (forced via Storybook a11y addon parameters)
+// ---------------------------------------------------------------------------
+export const ReducedMotion: Story = {
+  parameters: {
+    a11y: { config: { rules: [{ id: 'duplicate-id', enabled: false }] } },
+  },
+  render: () => (
+    <div className="h-screen mx-auto max-w-2xl">
+      <ChatInterface
+        messages={[
+          { id: 'u1', role: 'user', status: 'complete', content: 'Animation off?' },
+          { id: 'a1', role: 'assistant', status: 'streaming', content: 'partial response, no pulse' },
+        ]}
+        status="streaming"
+        onSendMessage={() => {}}
+        onStopGeneration={() => {}}
+        assistantAvatar={ASSISTANT_AVATAR}
+        userAvatar={USER_AVATAR}
+      />
+    </div>
+  ),
+};