@dowel-ui/react 0.1.0

package/src/blocks/ai-chat/ai-chat.stories.tsx

@@ -0,0 +1,149 @@
+import type { Decorator, Meta, StoryObj } from "@storybook/react-vite";
+import { useState } from "react";
+
+import { AiChatBlock, type ChatMessage } from "./ai-chat";
+
+/** Named so its type is nameable in declaration output (TS2883). */
+const withChatFrame: Decorator = (Story) => (
+  <div className="h-[36rem] w-[42rem] max-w-full overflow-hidden rounded-xl border border-border">
+    <Story />
+  </div>
+);
+
+const MODELS = [
+  { id: "fast", name: "Fast", description: "Lowest latency." },
+  { id: "balanced", name: "Balanced", description: "The default." },
+  { id: "deep", name: "Deep Research", description: "Multi-step, with citations." },
+];
+
+const CONVERSATION: ChatMessage[] = [
+  { id: "1", from: "user", content: "How do I make an overflowing table keyboard-scrollable?" },
+  {
+    id: "2",
+    from: "assistant",
+    content:
+      'Give the scrolling wrapper tabindex="0", a role of "region" and an accessible name. Without a focus stop, the columns past the edge are unreachable without a pointer.',
+    reasoning:
+      "The question is about keyboard access to overflowing tables.\n\nA scroll container is not focusable by default, so its content past the edge cannot be reached without a pointer. Adding a focus stop with a role and a name fixes both the reachability and the unlabelled-stop problem.",
+    tools: [
+      {
+        id: "t1",
+        name: "search_docs",
+        status: "success",
+        arguments: JSON.stringify({ query: "scrollable region keyboard", limit: 5 }, null, 2),
+        result: JSON.stringify({ hits: 3, top: "ARIA Authoring Practices" }, null, 2),
+      },
+    ],
+    sources: [
+      {
+        index: 1,
+        title: "ARIA Authoring Practices — scrollable regions",
+        origin: "w3.org",
+        href: "#1",
+      },
+      { index: 2, title: "Accessible data tables", origin: "example.org", href: "#2" },
+    ],
+    tokens: 148,
+  },
+];
+
+const meta = {
+  title: "Blocks/AI Chat",
+  component: AiChatBlock,
+  args: { messages: CONVERSATION, models: MODELS, model: "balanced" },
+  parameters: { controls: { disable: true } },
+  decorators: [withChatFrame],
+} satisfies Meta<typeof AiChatBlock>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};
+
+export const Empty: Story = {
+  args: { messages: [] },
+};
+
+export const Waiting: Story = {
+  args: { messages: [CONVERSATION[0]!], waiting: true },
+};
+
+export const Streaming: Story = {
+  args: {
+    messages: [
+      CONVERSATION[0]!,
+      {
+        id: "2",
+        from: "assistant",
+        content: 'Give the scrolling wrapper tabindex="0", a role',
+        streaming: true,
+      },
+    ],
+    busy: true,
+  },
+};
+
+/** Send a message and watch it stream back. */
+export const Interactive: Story = {
+  render: function Interactive() {
+    const [messages, setMessages] = useState<ChatMessage[]>([]);
+    const [waiting, setWaiting] = useState(false);
+    const [busy, setBusy] = useState(false);
+
+    function reply(text: string) {
+      const answer = `You asked: “${text}”. In a real product this is where the response would stream in, one token at a time.`;
+      let shown = 0;
+
+      const id = String(Date.now());
+      setWaiting(false);
+      setBusy(true);
+      setMessages((current) => [
+        ...current,
+        { id, from: "assistant", content: "", streaming: true },
+      ]);
+
+      const timer = window.setInterval(() => {
+        shown += 2;
+        const done = shown >= answer.length;
+
+        setMessages((current) =>
+          current.map((message) =>
+            message.id === id
+              ? {
+                  ...message,
+                  content: answer.slice(0, shown),
+                  streaming: !done,
+                  tokens: done ? 42 : undefined,
+                }
+              : message,
+          ),
+        );
+
+        if (done) {
+          window.clearInterval(timer);
+          setBusy(false);
+        }
+      }, 30);
+    }
+
+    return (
+      <AiChatBlock
+        messages={messages}
+        models={MODELS}
+        model="balanced"
+        busy={busy}
+        waiting={waiting}
+        onSend={(text) => {
+          setMessages((current) => [
+            ...current,
+            { id: `u${String(current.length)}`, from: "user", content: text },
+          ]);
+          setWaiting(true);
+          window.setTimeout(() => {
+            reply(text);
+          }, 700);
+        }}
+      />
+    );
+  },
+};

package/src/blocks/ai-chat/ai-chat.test.tsx

@@ -0,0 +1,166 @@
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it, vi } from "vitest";
+
+import { expectNoA11yViolations } from "../../../test/a11y";
+import { AiChatBlock, type ChatMessage } from "./ai-chat";
+
+const MESSAGES: ChatMessage[] = [
+  { id: "1", from: "user", content: "How do I make an overflowing table keyboard-scrollable?" },
+  {
+    id: "2",
+    from: "assistant",
+    content: 'Give the scrolling wrapper tabindex="0", a role and an accessible name.',
+    reasoning: "The container is not focusable by default, so its overflow is unreachable.",
+    tools: [
+      {
+        id: "t1",
+        name: "search_docs",
+        status: "success",
+        arguments: '{ "query": "scrollable region" }',
+        result: '{ "hits": 3 }',
+      },
+    ],
+    sources: [{ index: 1, title: "ARIA Authoring Practices", origin: "w3.org", href: "#1" }],
+    tokens: 148,
+  },
+];
+
+describe("AiChatBlock", () => {
+  it("shows an empty state before anything is said", () => {
+    render(<AiChatBlock messages={[]} />);
+    expect(screen.getByText("Start a conversation")).toBeInTheDocument();
+  });
+
+  it("renders the transcript as a list, never a live region", () => {
+    const { container } = render(<AiChatBlock messages={MESSAGES} />);
+
+    const list = container.querySelector("[data-slot='conversation-messages']");
+    expect(list?.tagName).toBe("OL");
+    // The decision the whole AI layer rests on: announcing streamed text token
+    // by token is unusable with a screen reader.
+    expect(list).not.toHaveAttribute("aria-live");
+  });
+
+  it("names the speaker of every turn in text", () => {
+    render(<AiChatBlock messages={MESSAGES} />);
+    expect(screen.getByText("You said:")).toBeInTheDocument();
+    expect(screen.getByText("Assistant said:")).toBeInTheDocument();
+  });
+
+  it("announces state, not content", () => {
+    const { container } = render(<AiChatBlock messages={MESSAGES} busy />);
+
+    const status = container.querySelector("[data-slot='conversation-status']");
+    expect(status).toHaveAttribute("aria-live", "polite");
+    expect(status).toHaveTextContent("Generating response");
+    expect(status).not.toHaveTextContent("tabindex");
+  });
+
+  it("distinguishes waiting from generating", () => {
+    const { container } = render(<AiChatBlock messages={MESSAGES} waiting />);
+    expect(container.querySelector("[data-slot='conversation-status']")).toHaveTextContent(
+      "Waiting for a response",
+    );
+    expect(screen.getByText("Thinking")).toBeInTheDocument();
+  });
+
+  it("collapses reasoning and tool calls by default", () => {
+    render(<AiChatBlock messages={MESSAGES} />);
+
+    expect(screen.getByRole("button", { name: "Reasoning" })).toHaveAttribute(
+      "aria-expanded",
+      "false",
+    );
+    expect(screen.getByRole("button", { name: /search_docs/ })).toHaveAttribute(
+      "aria-expanded",
+      "false",
+    );
+  });
+
+  it("names tool payloads per tool, so two open tools do not collide", async () => {
+    const user = userEvent.setup();
+    render(<AiChatBlock messages={MESSAGES} />);
+
+    await user.click(screen.getByRole("button", { name: /search_docs/ }));
+    expect(
+      await screen.findByRole("region", { name: "search_docs arguments" }),
+    ).toBeInTheDocument();
+    expect(screen.getByRole("region", { name: "search_docs result" })).toBeInTheDocument();
+  });
+
+  it("lists sources behind a disclosure", async () => {
+    const user = userEvent.setup();
+    render(<AiChatBlock messages={MESSAGES} />);
+
+    await user.click(screen.getByRole("button", { name: "1 source" }));
+    expect(await screen.findByText("ARIA Authoring Practices")).toBeInTheDocument();
+  });
+
+  it("shows the token count for a finished response", () => {
+    render(<AiChatBlock messages={MESSAGES} />);
+    expect(screen.getByText("148 tokens")).toBeInTheDocument();
+  });
+
+  it("sends a message and clears the composer", async () => {
+    const onSend = vi.fn();
+    const user = userEvent.setup();
+    render(<AiChatBlock messages={MESSAGES} onSend={onSend} />);
+
+    const composer = screen.getByRole("textbox", { name: "Message" });
+    await user.type(composer, "Thanks{Enter}");
+
+    expect(onSend).toHaveBeenCalledWith("Thanks");
+    await waitFor(() => {
+      expect(composer).toHaveValue("");
+    });
+  });
+
+  it("does not send an empty message", async () => {
+    const onSend = vi.fn();
+    const user = userEvent.setup();
+    render(<AiChatBlock messages={MESSAGES} onSend={onSend} />);
+
+    await user.type(screen.getByRole("textbox", { name: "Message" }), "   {Enter}");
+    expect(onSend).not.toHaveBeenCalled();
+  });
+
+  it("offers Stop while a response is in flight", async () => {
+    const onStop = vi.fn();
+    const user = userEvent.setup();
+    render(<AiChatBlock messages={MESSAGES} busy onStop={onStop} />);
+
+    await user.click(screen.getByRole("button", { name: "Stop generating" }));
+    expect(onStop).toHaveBeenCalledTimes(1);
+  });
+
+  it("offers a model picker when models are given", async () => {
+    const onModelChange = vi.fn();
+    const user = userEvent.setup();
+    render(
+      <AiChatBlock
+        messages={MESSAGES}
+        model="fast"
+        onModelChange={onModelChange}
+        models={[
+          { id: "fast", name: "Fast" },
+          { id: "deep", name: "Deep" },
+        ]}
+      />,
+    );
+
+    await user.click(screen.getByRole("combobox", { name: "Model" }));
+    await user.click(await screen.findByRole("option", { name: "Deep" }));
+    expect(onModelChange).toHaveBeenCalledWith("deep");
+  });
+
+  it("hides the model picker when there are no models", () => {
+    render(<AiChatBlock messages={MESSAGES} />);
+    expect(screen.queryByRole("combobox", { name: "Model" })).not.toBeInTheDocument();
+  });
+
+  it("has no accessibility violations", async () => {
+    const { container } = render(<AiChatBlock messages={MESSAGES} />);
+    await expectNoA11yViolations(container);
+  });
+});

package/src/blocks/ai-chat/ai-chat.tsx

@@ -0,0 +1,280 @@
+"use client";
+
+import { useState, type FormEvent, type ReactNode } from "react";
+
+import {
+  Conversation,
+  ConversationMessages,
+  ConversationScrollButton,
+  ConversationStatus,
+} from "@/components/ai-conversation";
+import {
+  Message,
+  MessageActions,
+  MessageAvatar,
+  MessageBody,
+  MessageFooter,
+} from "@/components/ai-message";
+import { ModelSelector, type ModelOption } from "@/components/ai-model-selector";
+import {
+  PromptInput,
+  PromptInputSubmit,
+  PromptInputTextarea,
+  PromptInputToolbar,
+} from "@/components/ai-prompt-input";
+import { Reasoning, ReasoningContent, ReasoningTrigger } from "@/components/ai-reasoning";
+import { Response, ThinkingIndicator } from "@/components/ai-response";
+import { Source, Sources, SourcesContent, SourcesTrigger } from "@/components/ai-sources";
+import { TokenCount } from "@/components/ai-token-usage";
+import {
+  Tool,
+  ToolContent,
+  ToolHeader,
+  ToolPayload,
+  ToolSection,
+  type ToolStatus,
+} from "@/components/ai-tool";
+import { Button } from "@/components/button";
+import { EmptyState, EmptyStateDescription, EmptyStateTitle } from "@/components/empty-state";
+import { cn } from "@/lib/utils";
+
+/**
+ * A complete chat surface.
+ *
+ * Assembled from the AI components rather than reimplementing any of them, so
+ * every decision they encode still holds here: the transcript is a list and not
+ * a live region, state is announced separately, and the composer will not send
+ * mid-IME-composition.
+ */
+
+export interface ChatToolCall {
+  id: string;
+  name: string;
+  status: ToolStatus;
+  arguments?: string;
+  result?: string;
+}
+
+export interface ChatSource {
+  index: number;
+  title: string;
+  origin?: string;
+  href?: string;
+}
+
+export interface ChatMessage {
+  id: string;
+  from: "user" | "assistant";
+  content: string;
+  reasoning?: string;
+  tools?: ChatToolCall[];
+  sources?: ChatSource[];
+  tokens?: number;
+  /** Still arriving: shows the caret. */
+  streaming?: boolean;
+}
+
+export interface AiChatBlockProps {
+  messages: ChatMessage[];
+  onSend?: (message: string) => void;
+  onStop?: () => void;
+  /** A response is in flight. */
+  busy?: boolean;
+  /** Shown before the first token arrives. */
+  waiting?: boolean;
+  models?: ModelOption[];
+  model?: string;
+  onModelChange?: (model: string) => void;
+  /** Shown when the transcript is empty. */
+  empty?: ReactNode;
+  placeholder?: string;
+  className?: string;
+}
+
+export function AiChatBlock({
+  messages,
+  onSend,
+  onStop,
+  busy = false,
+  waiting = false,
+  models,
+  model,
+  onModelChange,
+  empty,
+  placeholder = "Ask anything…",
+  className,
+}: AiChatBlockProps) {
+  const [draft, setDraft] = useState("");
+
+  function handleSubmit(event: FormEvent<HTMLFormElement>) {
+    event.preventDefault();
+    const trimmed = draft.trim();
+    if (!trimmed) return;
+    onSend?.(trimmed);
+    setDraft("");
+  }
+
+  return (
+    <div className={cn("flex h-full min-h-0 flex-col", className)}>
+      <Conversation>
+        {messages.length === 0 ? (
+          <div className="grid h-full place-items-center p-8">
+            {empty ?? (
+              <EmptyState>
+                <EmptyStateTitle>Start a conversation</EmptyStateTitle>
+                <EmptyStateDescription>
+                  Ask a question, paste an error, or describe what you are trying to build.
+                </EmptyStateDescription>
+              </EmptyState>
+            )}
+          </div>
+        ) : (
+          <ConversationMessages>
+            {messages.map((message) => (
+              <Message key={message.id} from={message.from}>
+                {message.from === "assistant" ? <MessageAvatar>AI</MessageAvatar> : null}
+                <MessageBody from={message.from} className="min-w-0 flex-1">
+                  {message.reasoning ? (
+                    <Reasoning className="mb-2">
+                      <ReasoningTrigger streaming={message.streaming} />
+                      <ReasoningContent>{message.reasoning}</ReasoningContent>
+                    </Reasoning>
+                  ) : null}
+
+                  {message.tools?.map((tool) => (
+                    <Tool key={tool.id} status={tool.status} className="mb-2">
+                      <ToolHeader name={tool.name} status={tool.status} />
+                      <ToolContent>
+                        {tool.arguments ? (
+                          <ToolSection label="Arguments">
+                            <ToolPayload label={`${tool.name} arguments`}>
+                              {tool.arguments}
+                            </ToolPayload>
+                          </ToolSection>
+                        ) : null}
+                        {tool.result ? (
+                          <ToolSection label="Result">
+                            <ToolPayload label={`${tool.name} result`}>
+                              {tool.result}
+                            </ToolPayload>
+                          </ToolSection>
+                        ) : null}
+                      </ToolContent>
+                    </Tool>
+                  ))}
+
+                  {message.from === "assistant" ? (
+                    <Response streaming={message.streaming}>{message.content}</Response>
+                  ) : (
+                    message.content
+                  )}
+
+                  {message.sources && message.sources.length > 0 ? (
+                    <Sources className="mt-3">
+                      <SourcesTrigger count={message.sources.length} />
+                      <SourcesContent>
+                        {message.sources.map((source) => (
+                          <Source
+                            key={source.index}
+                            index={source.index}
+                            title={source.title}
+                            origin={source.origin}
+                            href={source.href ?? "#"}
+                          />
+                        ))}
+                      </SourcesContent>
+                    </Sources>
+                  ) : null}
+
+                  {message.from === "assistant" && !message.streaming ? (
+                    <>
+                      <MessageActions>
+                        <Button variant="ghost" size="icon-sm" aria-label="Copy response">
+                          <svg viewBox="0 0 24 24" fill="none" aria-hidden="true">
+                            <rect
+                              x="9"
+                              y="9"
+                              width="12"
+                              height="12"
+                              rx="2"
+                              stroke="currentColor"
+                              strokeWidth="2"
+                            />
+                            <path
+                              d="M5 15H4a1 1 0 0 1-1-1V4a1 1 0 0 1 1-1h10a1 1 0 0 1 1 1v1"
+                              stroke="currentColor"
+                              strokeWidth="2"
+                              strokeLinecap="round"
+                            />
+                          </svg>
+                        </Button>
+                        <Button variant="ghost" size="icon-sm" aria-label="Regenerate response">
+                          <svg viewBox="0 0 24 24" fill="none" aria-hidden="true">
+                            <path
+                              d="M20 12a8 8 0 1 1-2.3-5.6M20 4v5h-5"
+                              stroke="currentColor"
+                              strokeWidth="2"
+                              strokeLinecap="round"
+                              strokeLinejoin="round"
+                            />
+                          </svg>
+                        </Button>
+                      </MessageActions>
+                      {message.tokens === undefined ? null : (
+                        <MessageFooter>
+                          <TokenCount value={message.tokens} />
+                        </MessageFooter>
+                      )}
+                    </>
+                  ) : null}
+                </MessageBody>
+              </Message>
+            ))}
+
+            {waiting ? (
+              <Message from="assistant">
+                <MessageAvatar>AI</MessageAvatar>
+                <MessageBody from="assistant">
+                  <ThinkingIndicator />
+                </MessageBody>
+              </Message>
+            ) : null}
+          </ConversationMessages>
+        )}
+
+        <ConversationScrollButton />
+      </Conversation>
+
+      {/* State, never content — the transcript above stays navigable at the
+          reader's own pace. */}
+      <ConversationStatus className="px-4 pb-1">
+        {waiting ? "Waiting for a response" : busy ? "Generating response" : ""}
+      </ConversationStatus>
+
+      <div className="border-t border-border p-4">
+        <PromptInput busy={busy} onSubmit={handleSubmit}>
+          <PromptInputTextarea
+            aria-label="Message"
+            placeholder={placeholder}
+            value={draft}
+            onChange={(event) => {
+              setDraft(event.target.value);
+            }}
+          />
+          <PromptInputToolbar>
+            {models && models.length > 0 ? (
+              <ModelSelector
+                aria-label="Model"
+                models={models}
+                value={model}
+                onValueChange={onModelChange}
+                triggerSize="sm"
+              />
+            ) : null}
+            <PromptInputSubmit onStop={onStop} />
+          </PromptInputToolbar>
+        </PromptInput>
+      </div>
+    </div>
+  );
+}

package/src/blocks/ai-chat/index.ts

@@ -0,0 +1,7 @@
+export {
+  AiChatBlock,
+  type AiChatBlockProps,
+  type ChatMessage,
+  type ChatSource,
+  type ChatToolCall,
+} from "./ai-chat";

package/src/blocks/ai-chat/meta.ts

@@ -0,0 +1,32 @@
+import { defineMeta } from "@/registry/schema";
+
+export const meta = defineMeta({
+  name: "ai-chat",
+  kind: "block",
+  title: "AI Chat",
+  description:
+    "A complete chat surface: transcript, reasoning, tool calls, sources and composer.",
+  category: "ai",
+  status: "stable",
+  dependencies: [],
+  registryDependencies: [
+    "ai-conversation",
+    "ai-message",
+    "ai-model-selector",
+    "ai-prompt-input",
+    "ai-reasoning",
+    "ai-response",
+    "ai-sources",
+    "ai-token-usage",
+    "ai-tool",
+    "button",
+    "empty-state",
+  ],
+  files: ["ai-chat.tsx"],
+  a11y:
+    "Assembled from the AI components rather than reimplementing them, so their decisions still " +
+    "hold: the transcript is a list and not a live region, state is announced separately through " +
+    "ConversationStatus, and the composer will not send while an IME composition is active. Tool " +
+    "payloads are named per tool, so two open tool calls do not present two regions called " +
+    '"Result".',
+});