@dowel-ui/react 0.1.0

package/src/components/ai-agent-status/meta.ts

@@ -0,0 +1,17 @@
+import { defineMeta } from "@/registry/schema";
+
+export const meta = defineMeta({
+  name: "ai-agent-status",
+  title: "AI Agent Status",
+  description: "A pill showing what an agent is doing, in words as well as colour.",
+  category: "ai",
+  status: "stable",
+  dependencies: ["class-variance-authority"],
+  registryDependencies: [],
+  files: ["ai-agent-status.tsx"],
+  a11y:
+    "The state is always text. Agent states matter most when something has failed, which is " +
+    "exactly when a colour-only signal fails the people who most need to see it. Live " +
+    "announcements are off by default — several agents each announcing their transitions turns a " +
+    "dashboard into noise; enable it for the one agent being watched.",
+});

package/src/components/ai-conversation/ai-conversation.stories.tsx

@@ -0,0 +1,126 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { useState } from "react";
+
+import { Message, MessageAvatar, MessageBody } from "@/components/ai-message";
+import { Response, ThinkingIndicator } from "@/components/ai-response";
+import { Button } from "@/components/button";
+
+import {
+  Conversation,
+  ConversationMessages,
+  ConversationScrollButton,
+  ConversationStatus,
+} from "./ai-conversation";
+
+const meta: Meta<typeof Conversation> = {
+  title: "AI/Conversation",
+  component: Conversation,
+  parameters: { controls: { disable: true } },
+};
+
+export default meta;
+type Story = StoryObj<typeof Conversation>;
+
+const TURNS = [
+  { role: "user" as const, text: "What's the difference between a Sheet and a Drawer?" },
+  {
+    role: "assistant" as const,
+    text: "A Sheet slides in from any edge and is dismissed with Escape, the overlay or a close button. A Drawer is bottom-anchored and adds a drag gesture — but the gesture is never the only way out.",
+  },
+  { role: "user" as const, text: "When would I use one over the other?" },
+  {
+    role: "assistant" as const,
+    text: "Use a Sheet for secondary content on any viewport: filters, details, navigation. Use a Drawer when the surface is primarily touch-driven and dragging it away is the natural gesture.",
+  },
+];
+
+export const Default: Story = {
+  render: () => (
+    <div className="flex h-96 w-[34rem] flex-col rounded-xl border border-border">
+      <Conversation>
+        <ConversationMessages>
+          {TURNS.map((turn, index) => (
+            <Message key={index} from={turn.role}>
+              {turn.role === "assistant" ? <MessageAvatar>AI</MessageAvatar> : null}
+              <MessageBody from={turn.role}>
+                {turn.role === "assistant" ? <Response>{turn.text}</Response> : turn.text}
+              </MessageBody>
+            </Message>
+          ))}
+        </ConversationMessages>
+        <ConversationScrollButton />
+      </Conversation>
+    </div>
+  ),
+};
+
+/**
+ * State goes in the status region; the response text never does. A live region
+ * that updates per token is unusable with a screen reader.
+ */
+export const Streaming: Story = {
+  render: function Streaming() {
+    const [streaming, setStreaming] = useState(false);
+
+    return (
+      <div className="flex h-96 w-[34rem] flex-col rounded-xl border border-border">
+        <Conversation>
+          <ConversationMessages>
+            <Message from="user">
+              <MessageBody from="user">Explain streaming responses.</MessageBody>
+            </Message>
+            <Message from="assistant">
+              <MessageAvatar>AI</MessageAvatar>
+              <MessageBody from="assistant">
+                {streaming ? (
+                  <Response streaming>Tokens arrive one at a time, and the caret</Response>
+                ) : (
+                  <ThinkingIndicator />
+                )}
+              </MessageBody>
+            </Message>
+          </ConversationMessages>
+          <ConversationStatus>
+            {streaming ? "Generating response" : "Waiting for the first token"}
+          </ConversationStatus>
+        </Conversation>
+        <div className="border-t border-border p-3">
+          <Button
+            size="sm"
+            variant="outline"
+            onClick={() => {
+              setStreaming((current) => !current);
+            }}
+          >
+            Toggle streaming
+          </Button>
+        </div>
+      </div>
+    );
+  },
+};
+
+/** Scroll up: following stops, and an explicit way back appears. */
+export const LongTranscript: Story = {
+  render: () => (
+    <div className="flex h-96 w-[34rem] flex-col rounded-xl border border-border">
+      <Conversation>
+        <ConversationMessages>
+          {Array.from({ length: 14 }, (_, index) => {
+            const role = index % 2 === 0 ? ("user" as const) : ("assistant" as const);
+            return (
+              <Message key={index} from={role}>
+                {role === "assistant" ? <MessageAvatar>AI</MessageAvatar> : null}
+                <MessageBody from={role}>
+                  Turn {index + 1}.{" "}
+                  {role === "assistant" ? "An answer of some length." : "A question."}
+                </MessageBody>
+              </Message>
+            );
+          })}
+        </ConversationMessages>
+        <ConversationScrollButton />
+      </Conversation>
+    </div>
+  ),
+};

package/src/components/ai-conversation/ai-conversation.test.tsx

@@ -0,0 +1,144 @@
+import { fireEvent, 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 { Message, MessageBody } from "../ai-message";
+import {
+  Conversation,
+  ConversationMessages,
+  ConversationScrollButton,
+  ConversationStatus,
+} from "./ai-conversation";
+
+function Example({ status }: { status?: string } = {}) {
+  return (
+    <Conversation>
+      <ConversationMessages>
+        <Message from="user">
+          <MessageBody from="user">What is the capital of France?</MessageBody>
+        </Message>
+        <Message from="assistant">
+          <MessageBody from="assistant">Paris.</MessageBody>
+        </Message>
+      </ConversationMessages>
+      {status ? <ConversationStatus>{status}</ConversationStatus> : null}
+      <ConversationScrollButton />
+    </Conversation>
+  );
+}
+
+/** jsdom has no layout, so scroll geometry is stubbed to drive the logic. */
+function stubScroll(
+  viewport: HTMLElement,
+  { scrollTop = 0, scrollHeight = 1000, clientHeight = 400 } = {},
+) {
+  Object.defineProperty(viewport, "scrollHeight", { value: scrollHeight, configurable: true });
+  Object.defineProperty(viewport, "clientHeight", { value: clientHeight, configurable: true });
+  Object.defineProperty(viewport, "scrollTop", {
+    value: scrollTop,
+    writable: true,
+    configurable: true,
+  });
+}
+
+function viewportOf(container: HTMLElement): HTMLElement {
+  const viewport = container.querySelector<HTMLElement>("[data-slot='conversation-viewport']");
+  if (!viewport) throw new Error("no viewport");
+  return viewport;
+}
+
+describe("Conversation", () => {
+  it("renders the transcript as an ordered list", () => {
+    render(<Example />);
+    expect(screen.getByRole("list").tagName).toBe("OL");
+    expect(screen.getAllByRole("listitem")).toHaveLength(2);
+  });
+
+  it("does NOT make the transcript a live region", () => {
+    // The central accessibility decision of this component. A live region that
+    // updates per streamed token is unusable with a screen reader.
+    const list = render(<Example />).container.querySelector(
+      "[data-slot='conversation-messages']",
+    );
+    expect(list).not.toHaveAttribute("aria-live");
+    expect(list).not.toHaveAttribute("role", "log");
+  });
+
+  it("announces state, not content, through a separate status region", () => {
+    render(<Example status="Generating response" />);
+
+    const status = screen.getByRole("status");
+    expect(status).toHaveAttribute("aria-live", "polite");
+    expect(status).toHaveTextContent("Generating response");
+    // The transcript text must not be inside the live region.
+    expect(status).not.toHaveTextContent("Paris.");
+  });
+
+  describe("the jump-to-latest control", () => {
+    it("is absent while the reader is at the bottom", () => {
+      render(<Example />);
+      expect(screen.queryByRole("button", { name: "Jump to latest" })).not.toBeInTheDocument();
+    });
+
+    it("appears once the reader scrolls away", async () => {
+      const { container } = render(<Example />);
+      const viewport = viewportOf(container);
+
+      stubScroll(viewport, { scrollTop: 0 });
+      fireEvent.scroll(viewport);
+
+      expect(await screen.findByRole("button", { name: "Jump to latest" })).toBeInTheDocument();
+    });
+
+    it("scrolls back down and then disappears", async () => {
+      const user = userEvent.setup();
+      const { container } = render(<Example />);
+      const viewport = viewportOf(container);
+      const scrollTo = vi.fn();
+      viewport.scrollTo = scrollTo;
+
+      stubScroll(viewport, { scrollTop: 0 });
+      fireEvent.scroll(viewport);
+      await user.click(await screen.findByRole("button", { name: "Jump to latest" }));
+
+      expect(scrollTo).toHaveBeenCalledWith({ top: 1000, behavior: "smooth" });
+
+      stubScroll(viewport, { scrollTop: 600 });
+      fireEvent.scroll(viewport);
+      await waitFor(() => {
+        expect(
+          screen.queryByRole("button", { name: "Jump to latest" }),
+        ).not.toBeInTheDocument();
+      });
+    });
+
+    it("counts near-the-bottom as the bottom, so a pixel of drift is not a prompt", async () => {
+      const { container } = render(<Example />);
+      const viewport = viewportOf(container);
+
+      stubScroll(viewport, { scrollTop: 580 });
+      fireEvent.scroll(viewport);
+
+      await waitFor(() => {
+        expect(container.querySelector("[data-slot='conversation']")).toHaveAttribute(
+          "data-at-bottom",
+          "true",
+        );
+      });
+    });
+  });
+
+  it("throws a useful error if the scroll button is used outside the root", () => {
+    const consoleError = vi.spyOn(console, "error").mockImplementation(() => undefined);
+    expect(() => render(<ConversationScrollButton />)).toThrow(
+      /must be rendered inside <Conversation>/,
+    );
+    consoleError.mockRestore();
+  });
+
+  it("has no accessibility violations", async () => {
+    const { container } = render(<Example status="Response complete" />);
+    await expectNoA11yViolations(container);
+  });
+});

package/src/components/ai-conversation/ai-conversation.tsx

@@ -0,0 +1,229 @@
+"use client";
+
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ComponentPropsWithRef,
+  type ReactNode,
+} from "react";
+
+import { cn } from "@/lib/utils";
+
+/**
+ * The scrolling container for a conversation.
+ *
+ * Two problems here are easy to get wrong and unpleasant to live with.
+ *
+ * **Scrolling.** A chat should follow new content, but only while the reader is
+ * already at the bottom. The moment someone scrolls up to re-read something,
+ * yanking them back down is worse than not following at all — so this tracks
+ * whether they are pinned to the bottom and stops following as soon as they are
+ * not, offering an explicit way back instead.
+ *
+ * **Announcements.** The obvious thing is to make the transcript a live region.
+ * Do not: a live region that updates on every token produces a stream of
+ * interruptions that is unusable with a screen reader, and it is the single
+ * most common accessibility failure in chat interfaces. The transcript here is
+ * an ordinary list, navigable at the reader's pace, and a *separate* status
+ * region announces state — "generating", "response complete" — never content.
+ */
+
+interface ConversationContextValue {
+  viewportRef: React.RefObject<HTMLDivElement | null>;
+  atBottom: boolean;
+  scrollToBottom: (behavior?: ScrollBehavior) => void;
+}
+
+const ConversationContext = createContext<ConversationContextValue | null>(null);
+
+function useConversation(component: string): ConversationContextValue {
+  const context = useContext(ConversationContext);
+  if (!context) {
+    throw new Error(`${component} must be rendered inside <Conversation>.`);
+  }
+  return context;
+}
+
+/** How close to the bottom still counts as "at the bottom", in pixels. */
+const BOTTOM_THRESHOLD = 32;
+
+export interface ConversationProps extends ComponentPropsWithRef<"div"> {
+  /**
+   * Follow new content while the reader is at the bottom.
+   *
+   * Turning this off never scrolls automatically; it does not pin the view.
+   */
+  autoScroll?: boolean;
+}
+
+export function Conversation({
+  className,
+  autoScroll = true,
+  children,
+  ...props
+}: ConversationProps) {
+  const viewportRef = useRef<HTMLDivElement | null>(null);
+  const [atBottom, setAtBottom] = useState(true);
+
+  const scrollToBottom = useCallback((behavior: ScrollBehavior = "smooth") => {
+    const viewport = viewportRef.current;
+    if (!viewport) return;
+    viewport.scrollTo({ top: viewport.scrollHeight, behavior });
+  }, []);
+
+  useEffect(() => {
+    const viewport = viewportRef.current;
+    if (!viewport) return;
+
+    function handleScroll() {
+      if (!viewport) return;
+      const distance = viewport.scrollHeight - viewport.scrollTop - viewport.clientHeight;
+      setAtBottom(distance <= BOTTOM_THRESHOLD);
+    }
+
+    handleScroll();
+    viewport.addEventListener("scroll", handleScroll, { passive: true });
+    return () => {
+      viewport.removeEventListener("scroll", handleScroll);
+    };
+  }, []);
+
+  // Follows content as it grows, but only while the reader is pinned to the
+  // bottom. Layout effect so the jump happens before paint rather than as a
+  // visible lurch.
+  useLayoutEffect(() => {
+    const viewport = viewportRef.current;
+    if (!viewport || !autoScroll) return;
+
+    const observer = new ResizeObserver(() => {
+      if (atBottom) viewport.scrollTop = viewport.scrollHeight;
+    });
+
+    for (const child of viewport.children) observer.observe(child);
+    return () => {
+      observer.disconnect();
+    };
+  }, [autoScroll, atBottom]);
+
+  const context = useMemo<ConversationContextValue>(
+    () => ({ viewportRef, atBottom, scrollToBottom }),
+    [atBottom, scrollToBottom],
+  );
+
+  return (
+    <ConversationContext.Provider value={context}>
+      <div
+        data-slot="conversation"
+        data-at-bottom={atBottom || undefined}
+        className={cn("relative flex min-h-0 flex-1 flex-col", className)}
+        {...props}
+      >
+        <div
+          ref={viewportRef}
+          data-slot="conversation-viewport"
+          className="flex-1 overflow-y-auto overscroll-contain"
+        >
+          {children}
+        </div>
+      </div>
+    </ConversationContext.Provider>
+  );
+}
+
+/**
+ * The transcript.
+ *
+ * An ordered list, deliberately not a live region — see the note on
+ * `Conversation`. Order is meaning here, and list semantics give a screen
+ * reader user position and count ("3 of 12") as they move through it.
+ */
+export function ConversationMessages({ className, ...props }: ComponentPropsWithRef<"ol">) {
+  return (
+    <ol
+      data-slot="conversation-messages"
+      className={cn("flex flex-col gap-6 p-4", className)}
+      {...props}
+    />
+  );
+}
+
+export interface ConversationStatusProps extends ComponentPropsWithRef<"div"> {
+  /** Announced politely when it changes. Keep it short: state, never content. */
+  children?: ReactNode;
+}
+
+/**
+ * A polite live region for conversation state.
+ *
+ * This is where "generating response" and "response complete" belong. Putting
+ * the response *text* here instead is the mistake this component exists to
+ * prevent.
+ */
+export function ConversationStatus({ className, children, ...props }: ConversationStatusProps) {
+  return (
+    <div
+      data-slot="conversation-status"
+      role="status"
+      aria-live="polite"
+      className={cn("px-4 text-xs text-muted-foreground", className)}
+      {...props}
+    >
+      {children}
+    </div>
+  );
+}
+
+export interface ConversationScrollButtonProps extends ComponentPropsWithRef<"button"> {
+  label?: string;
+}
+
+/**
+ * Returns the reader to the newest message.
+ *
+ * Rendered only when they have scrolled away, and removed from the DOM
+ * otherwise so it is never a focus stop pointing at where the reader already
+ * is.
+ */
+export function ConversationScrollButton({
+  className,
+  label = "Jump to latest",
+  ...props
+}: ConversationScrollButtonProps) {
+  const { atBottom, scrollToBottom } = useConversation("ConversationScrollButton");
+  if (atBottom) return null;
+
+  return (
+    <button
+      type="button"
+      data-slot="conversation-scroll-button"
+      onClick={() => {
+        scrollToBottom();
+      }}
+      className={cn(
+        "absolute bottom-3 left-1/2 z-[var(--z-sticky)] flex -translate-x-1/2 items-center gap-1.5",
+        "rounded-full border border-border bg-popover px-3 py-1.5 text-xs font-medium shadow-md",
+        "transition-colors duration-[var(--duration-fast)] hover:bg-accent",
+        "outline-none focus-visible:ring-2 focus-visible:ring-ring/55",
+        className,
+      )}
+      {...props}
+    >
+      <svg viewBox="0 0 24 24" fill="none" aria-hidden="true" className="size-3.5">
+        <path
+          d="M12 5v14m0 0-6-6m6 6 6-6"
+          stroke="currentColor"
+          strokeWidth="2"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+        />
+      </svg>
+      {label}
+    </button>
+  );
+}

package/src/components/ai-conversation/index.ts

@@ -0,0 +1,9 @@
+export {
+  Conversation,
+  ConversationMessages,
+  ConversationScrollButton,
+  ConversationStatus,
+  type ConversationProps,
+  type ConversationScrollButtonProps,
+  type ConversationStatusProps,
+} from "./ai-conversation";

package/src/components/ai-conversation/meta.ts

@@ -0,0 +1,20 @@
+import { defineMeta } from "@/registry/schema";
+
+export const meta = defineMeta({
+  name: "ai-conversation",
+  title: "AI Conversation",
+  description:
+    "The scrolling transcript container, with follow-on-new-content and a status region.",
+  category: "ai",
+  status: "stable",
+  dependencies: [],
+  registryDependencies: [],
+  files: ["ai-conversation.tsx"],
+  a11y:
+    "The transcript is an ordered list, NOT a live region. A live region that updates on every " +
+    "streamed token is unusable with a screen reader, and is the most common accessibility " +
+    'failure in chat interfaces. Announce state — "generating", "response complete" — through ' +
+    "ConversationStatus instead, and let the reader navigate the transcript at their own pace. " +
+    "Auto-scroll stops the moment the reader scrolls up, and ConversationScrollButton is the " +
+    "explicit way back.",
+});

package/src/components/ai-message/ai-message.stories.tsx

@@ -0,0 +1,106 @@
+import type { Decorator, Meta, StoryObj } from "@storybook/react-vite";
+import { Copy, RefreshCw, ThumbsDown, ThumbsUp } from "lucide-react";
+
+import { Response } from "@/components/ai-response";
+import { Button } from "@/components/button";
+
+import {
+  Message,
+  MessageActions,
+  MessageAvatar,
+  MessageBody,
+  MessageFooter,
+} from "./ai-message";
+
+/** Named so its type is nameable in declaration output (TS2883). */
+const withFixedWidth: Decorator = (Story) => (
+  <ol className="flex w-[32rem] flex-col gap-6">
+    <Story />
+  </ol>
+);
+
+const meta = {
+  title: "AI/Message",
+  component: Message,
+  args: { from: "assistant" },
+  argTypes: { from: { control: "inline-radio", options: ["user", "assistant", "system"] } },
+  decorators: [withFixedWidth],
+} satisfies Meta<typeof Message>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: (args) => (
+    <Message {...args}>
+      {args.from === "assistant" ? <MessageAvatar>AI</MessageAvatar> : null}
+      <MessageBody from={args.from}>
+        {args.from === "user"
+          ? "How do I make a table keyboard-scrollable?"
+          : 'Give the scrolling wrapper tabindex="0" and an accessible name. Without it, columns past the edge are unreachable by keyboard.'}
+      </MessageBody>
+    </Message>
+  ),
+};
+
+export const Roles: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <>
+      <Message from="system">
+        <MessageBody from="system">Conversation started with the Balanced model.</MessageBody>
+      </Message>
+      <Message from="user">
+        <MessageBody from="user">What is the capital of France?</MessageBody>
+      </Message>
+      <Message from="assistant">
+        <MessageAvatar>AI</MessageAvatar>
+        <MessageBody from="assistant">
+          <Response>Paris.</Response>
+        </MessageBody>
+      </Message>
+    </>
+  ),
+};
+
+/** Actions fade in on hover but stay in the tab order the whole time. */
+export const WithActions: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <Message from="assistant">
+      <MessageAvatar>AI</MessageAvatar>
+      <MessageBody from="assistant">
+        <Response>
+          A Sheet slides in from an edge; a Drawer is bottom-anchored and can be dragged away.
+        </Response>
+        <MessageActions>
+          {[
+            { icon: Copy, label: "Copy" },
+            { icon: RefreshCw, label: "Regenerate" },
+            { icon: ThumbsUp, label: "Good response" },
+            { icon: ThumbsDown, label: "Bad response" },
+          ].map(({ icon: Icon, label }) => (
+            <Button key={label} variant="ghost" size="icon-sm" aria-label={label}>
+              <Icon />
+            </Button>
+          ))}
+        </MessageActions>
+      </MessageBody>
+    </Message>
+  ),
+};
+
+export const WithFooter: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <Message from="assistant">
+      <MessageAvatar>AI</MessageAvatar>
+      <MessageBody from="assistant">
+        <Response>Paris has been the capital since 987.</Response>
+        <MessageFooter>
+          <span className="text-2xs text-muted-foreground">2 sources · 148 tokens</span>
+        </MessageFooter>
+      </MessageBody>
+    </Message>
+  ),
+};