@dowel-ui/react 0.1.0

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

@@ -0,0 +1,96 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+
+import { expectNoA11yViolations } from "../../../test/a11y";
+import { Response, ThinkingIndicator } from "./ai-response";
+
+describe("Response", () => {
+  it("renders its text", () => {
+    render(<Response>The capital of France is Paris.</Response>);
+    expect(screen.getByText("The capital of France is Paris.")).toBeInTheDocument();
+  });
+
+  it("is NOT a live region", () => {
+    // Announcing streamed text as it arrives interrupts a screen reader on
+    // every token; state goes through ConversationStatus instead.
+    const { container } = render(<Response streaming>Partial…</Response>);
+    const response = container.querySelector("[data-slot='response']");
+
+    expect(response).not.toHaveAttribute("aria-live");
+    expect(response).not.toHaveAttribute("role");
+  });
+
+  it("shows a decorative caret while streaming", () => {
+    const { container } = render(<Response streaming>Partial</Response>);
+    const caret = container.querySelector("[data-slot='response-caret']");
+
+    expect(caret).toBeInTheDocument();
+    expect(caret).toHaveAttribute("aria-hidden", "true");
+  });
+
+  it("has no caret when it is not streaming", () => {
+    const { container } = render(<Response>Done</Response>);
+    expect(container.querySelector("[data-slot='response-caret']")).not.toBeInTheDocument();
+  });
+
+  it("marks the streaming state for styling", () => {
+    const { container } = render(<Response streaming>Partial</Response>);
+    expect(container.querySelector("[data-slot='response']")).toHaveAttribute(
+      "data-streaming",
+      "true",
+    );
+  });
+
+  it("preserves paragraph whitespace", () => {
+    const { container } = render(<Response>{"line one\nline two"}</Response>);
+    expect(container.querySelector("[data-slot='response']")).toHaveClass(
+      "whitespace-pre-wrap",
+    );
+  });
+
+  it("renders markup a consumer has already rendered", () => {
+    render(
+      <Response>
+        <p>First</p>
+        <p>Second</p>
+      </Response>,
+    );
+    expect(screen.getByText("First")).toBeInTheDocument();
+    expect(screen.getByText("Second")).toBeInTheDocument();
+  });
+
+  it("lets a consumer className override a conflicting utility", () => {
+    const { container } = render(<Response className="text-base">Hi</Response>);
+    const response = container.querySelector("[data-slot='response']");
+    expect(response).toHaveClass("text-base");
+    expect(response).not.toHaveClass("text-sm");
+  });
+
+  it("has no accessibility violations", async () => {
+    const { container } = render(<Response streaming>Streaming text…</Response>);
+    await expectNoA11yViolations(container);
+  });
+});
+
+describe("ThinkingIndicator", () => {
+  it("is labelled, because it is the only thing on screen", () => {
+    render(<ThinkingIndicator />);
+    expect(screen.getByText("Thinking")).toBeInTheDocument();
+  });
+
+  it("accepts a custom label", () => {
+    render(<ThinkingIndicator label="Searching the web" />);
+    expect(screen.getByText("Searching the web")).toBeInTheDocument();
+  });
+
+  it("hides its dots from assistive technology", () => {
+    const { container } = render(<ThinkingIndicator />);
+    const dots = container.querySelectorAll("span[aria-hidden='true']");
+    expect(dots).toHaveLength(3);
+  });
+
+  it("has no accessibility violations", async () => {
+    const { container } = render(<ThinkingIndicator />);
+    await expectNoA11yViolations(container);
+  });
+});

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

@@ -0,0 +1,95 @@
+"use client";
+
+import type { ComponentPropsWithRef } from "react";
+
+import { cn } from "@/lib/utils";
+
+/**
+ * The text of an assistant response.
+ *
+ * Renders plain text with paragraph whitespace preserved. Markdown is
+ * deliberately not parsed here: a Markdown renderer is a dependency, a security
+ * decision about raw HTML, and a styling surface all at once, and every product
+ * makes those differently. Pass already-rendered content as children when you
+ * need it — the prose styling below applies either way.
+ *
+ * Not a live region, and not by omission. See the note on `Conversation`:
+ * announcing streamed text token by token is unusable with a screen reader.
+ */
+export interface ResponseProps extends ComponentPropsWithRef<"div"> {
+  /** Shows the caret. Purely visual — it carries no announcement. */
+  streaming?: boolean;
+}
+
+export function Response({ className, streaming, children, ...props }: ResponseProps) {
+  return (
+    <div
+      data-slot="response"
+      data-streaming={streaming || undefined}
+      className={cn(
+        "text-sm leading-relaxed whitespace-pre-wrap text-foreground",
+        // Minimal prose styling for consumers who pass rendered Markdown.
+        "[&_a]:text-primary [&_a]:underline [&_a]:underline-offset-4",
+        "[&_code]:rounded [&_code]:bg-muted [&_code]:px-1 [&_code]:py-0.5 [&_code]:font-mono [&_code]:text-[0.9em]",
+        "[&_ol]:my-2 [&_ol]:list-decimal [&_ol]:pl-5 [&_ul]:my-2 [&_ul]:list-disc [&_ul]:pl-5",
+        "[&_p+p]:mt-3",
+        className,
+      )}
+      {...props}
+    >
+      {children}
+      {streaming ? <ResponseCaret /> : null}
+    </div>
+  );
+}
+
+/** The trailing cursor. Decorative — the streaming state is announced, if at
+ * all, through ConversationStatus. */
+export function ResponseCaret({ className, ...props }: ComponentPropsWithRef<"span">) {
+  return (
+    <span
+      data-slot="response-caret"
+      aria-hidden="true"
+      className={cn(
+        "ml-0.5 inline-block h-[1em] w-[2px] translate-y-[0.15em] animate-caret bg-current align-baseline",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+/**
+ * Shown while waiting for the first token.
+ *
+ * A distinct state from streaming: nothing has arrived yet, so there is no text
+ * to show a caret after. Labelled for assistive technology because, unlike the
+ * caret, this is the only thing on screen.
+ */
+export interface ThinkingIndicatorProps extends ComponentPropsWithRef<"div"> {
+  label?: string;
+}
+
+export function ThinkingIndicator({
+  className,
+  label = "Thinking",
+  ...props
+}: ThinkingIndicatorProps) {
+  return (
+    <div
+      data-slot="thinking-indicator"
+      className={cn("flex items-center gap-1.5 text-sm text-muted-foreground", className)}
+      {...props}
+    >
+      <span className="sr-only">{label}</span>
+      {[0, 1, 2].map((index) => (
+        <span
+          key={index}
+          aria-hidden="true"
+          className="size-1.5 animate-pulse-soft rounded-full bg-current"
+          style={{ animationDelay: `${String(index * 160)}ms` }}
+        />
+      ))}
+    </div>
+  );
+}

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

@@ -0,0 +1,7 @@
+export {
+  Response,
+  ResponseCaret,
+  ThinkingIndicator,
+  type ResponseProps,
+  type ThinkingIndicatorProps,
+} from "./ai-response";

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

@@ -0,0 +1,17 @@
+import { defineMeta } from "@/registry/schema";
+
+export const meta = defineMeta({
+  name: "ai-response",
+  title: "AI Response",
+  description: "Assistant response text, with a streaming caret and a thinking indicator.",
+  category: "ai",
+  status: "stable",
+  dependencies: [],
+  registryDependencies: [],
+  files: ["ai-response.tsx"],
+  a11y:
+    "Deliberately not a live region: announcing streamed text as it arrives interrupts a screen " +
+    "reader user on every token. Announce state through ConversationStatus and let them read the " +
+    "response when it settles. The caret is decorative; ThinkingIndicator carries a label because " +
+    "it is the only thing on screen while waiting for the first token.",
+});

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

@@ -0,0 +1,93 @@
+import type { Decorator, Meta, StoryObj } from "@storybook/react-vite";
+
+import { Response } from "@/components/ai-response";
+
+import { InlineCitation, Source, Sources, SourcesContent, SourcesTrigger } from "./ai-sources";
+
+/** Named so its type is nameable in declaration output (TS2883). */
+const withFixedWidth: Decorator = (Story) => (
+  <div className="w-[32rem]">
+    <Story />
+  </div>
+);
+
+const meta = {
+  title: "AI/Sources",
+  component: Sources,
+  parameters: { controls: { disable: true } },
+  decorators: [withFixedWidth],
+} satisfies Meta<typeof Sources>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const SOURCES = [
+  {
+    index: 1,
+    title: "ARIA Authoring Practices — Table pattern",
+    origin: "w3.org",
+    excerpt: "Scrollable regions should be focusable so keyboard users can scroll them.",
+  },
+  {
+    index: 2,
+    title: "Accessible data tables",
+    origin: "example.org",
+    excerpt: "Native table semantics convey row and column position without extra ARIA.",
+  },
+];
+
+/** Markers next to the claim, the list underneath saying what each one is. */
+export const Default: Story = {
+  render: () => (
+    <div className="grid gap-3">
+      <Response>
+        A scroll container needs an explicit focus stop to be reachable by keyboard
+        <InlineCitation index={1} title={SOURCES[0]!.title} href="#1" />, and native table
+        semantics carry position without extra ARIA
+        <InlineCitation index={2} title={SOURCES[1]!.title} href="#2" />.
+      </Response>
+      <Sources>
+        <SourcesTrigger count={SOURCES.length} />
+        <SourcesContent>
+          {SOURCES.map((source) => (
+            <Source key={source.index} {...source} href={`#${String(source.index)}`} />
+          ))}
+        </SourcesContent>
+      </Sources>
+    </div>
+  ),
+};
+
+export const Expanded: Story = {
+  render: () => (
+    <Sources defaultOpen>
+      <SourcesTrigger count={SOURCES.length} />
+      <SourcesContent>
+        {SOURCES.map((source) => (
+          <Source key={source.index} {...source} href={`#${String(source.index)}`} />
+        ))}
+      </SourcesContent>
+    </Sources>
+  ),
+};
+
+/** A marker with nowhere to go renders as text, not a link that does nothing. */
+export const WithoutLinks: Story = {
+  render: () => (
+    <Response>
+      Internal policy requires two approvals
+      <InlineCitation index={1} title="Engineering handbook, section 4" />.
+    </Response>
+  ),
+};
+
+export const SingleSource: Story = {
+  render: () => (
+    <Sources defaultOpen>
+      <SourcesTrigger count={1} />
+      <SourcesContent>
+        <Source index={1} title="Engineering handbook" origin="internal" href="#1" />
+      </SourcesContent>
+    </Sources>
+  ),
+};

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

@@ -0,0 +1,102 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it } from "vitest";
+
+import { expectNoA11yViolations } from "../../../test/a11y";
+import { InlineCitation, Source, Sources, SourcesContent, SourcesTrigger } from "./ai-sources";
+
+describe("InlineCitation", () => {
+  it("carries the source title in its accessible name", () => {
+    render(<InlineCitation index={1} title="Encyclopaedia entry on France" href="#1" />);
+    // The visible text is a bare number, which conveys nothing on its own.
+    expect(
+      screen.getByRole("link", { name: "Source 1: Encyclopaedia entry on France" }),
+    ).toBeInTheDocument();
+  });
+
+  it("renders as text, not a dead link, without an href", () => {
+    render(<InlineCitation index={2} title="Internal document" />);
+    expect(screen.queryByRole("link")).not.toBeInTheDocument();
+    expect(screen.getByText("Source 2: Internal document")).toBeInTheDocument();
+  });
+
+  it("shows the marker number visually", () => {
+    const { container } = render(<InlineCitation index={3} title="A source" />);
+    expect(container.querySelector("[aria-hidden='true']")).toHaveTextContent("3");
+  });
+});
+
+describe("Sources", () => {
+  function Example() {
+    return (
+      <Sources>
+        <SourcesTrigger count={2} />
+        <SourcesContent>
+          <Source index={1} title="Paris — overview" origin="example.org" href="#1" />
+          <Source
+            index={2}
+            title="France factbook"
+            origin="factbook.example"
+            excerpt="Paris is the capital and most populous city."
+            href="#2"
+          />
+        </SourcesContent>
+      </Sources>
+    );
+  }
+
+  it("is collapsed by default", () => {
+    render(<Example />);
+    expect(screen.getByRole("button", { name: "2 sources" })).toHaveAttribute(
+      "aria-expanded",
+      "false",
+    );
+  });
+
+  it("pluralises the count", () => {
+    render(
+      <Sources>
+        <SourcesTrigger count={1} />
+        <SourcesContent>
+          <Source index={1} title="Only one" href="#1" />
+        </SourcesContent>
+      </Sources>,
+    );
+    expect(screen.getByRole("button", { name: "1 source" })).toBeInTheDocument();
+  });
+
+  it("lists the sources in order, matching the marker numbers", async () => {
+    const user = userEvent.setup();
+    render(<Example />);
+
+    await user.click(screen.getByRole("button", { name: "2 sources" }));
+
+    const list = await screen.findByRole("list");
+    expect(list.tagName).toBe("OL");
+    expect(screen.getAllByRole("listitem")).toHaveLength(2);
+  });
+
+  it("shows origin and excerpt when given", async () => {
+    const user = userEvent.setup();
+    render(<Example />);
+
+    await user.click(screen.getByRole("button", { name: "2 sources" }));
+    expect(await screen.findByText("factbook.example")).toBeInTheDocument();
+    expect(
+      screen.getByText(/Paris is the capital and most populous city\./),
+    ).toBeInTheDocument();
+  });
+
+  it("has no accessibility violations", async () => {
+    const { container } = render(
+      <Sources defaultOpen>
+        <SourcesTrigger count={2} />
+        <SourcesContent>
+          <Source index={1} title="Paris — overview" origin="example.org" href="#1" />
+          <Source index={2} title="France factbook" href="#2" />
+        </SourcesContent>
+      </Sources>,
+    );
+    await expectNoA11yViolations(container);
+  });
+});

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

@@ -0,0 +1,186 @@
+"use client";
+
+import { Collapsible as CollapsiblePrimitive } from "radix-ui";
+import type { ComponentPropsWithRef } from "react";
+
+import { focusRing } from "@/lib/styles";
+import { cn } from "@/lib/utils";
+
+/**
+ * Where a response came from.
+ *
+ * Citations are the difference between an assertion and a claim someone can
+ * check, so they are first-class here rather than a footnote: an inline marker
+ * next to the sentence, and a list underneath that says what each marker is.
+ */
+
+/**
+ * An inline citation marker.
+ *
+ * The visible text is a bare number, which tells a screen reader user nothing,
+ * so the real title goes in the accessible name. Rendered as a link when given
+ * an href, and as plain text otherwise — a marker that looks clickable and is
+ * not is worse than one that does not.
+ */
+export interface InlineCitationProps extends ComponentPropsWithRef<"a"> {
+  /** Position in the source list, starting at 1. */
+  index: number;
+  /** What is being cited. Becomes the accessible name. */
+  title: string;
+}
+
+export function InlineCitation({
+  className,
+  index,
+  title,
+  href,
+  ...props
+}: InlineCitationProps) {
+  const shared = cn(
+    "mx-0.5 inline-flex h-4 min-w-4 items-center justify-center rounded px-1 align-[0.15em]",
+    "bg-muted text-2xs font-medium text-muted-foreground tabular-nums",
+    className,
+  );
+
+  if (!href) {
+    return (
+      <span data-slot="inline-citation" className={shared}>
+        <span aria-hidden="true">{index}</span>
+        <span className="sr-only">
+          Source {index}: {title}
+        </span>
+      </span>
+    );
+  }
+
+  return (
+    <a
+      data-slot="inline-citation"
+      href={href}
+      aria-label={`Source ${String(index)}: ${title}`}
+      className={cn(
+        shared,
+        "transition-colors duration-[var(--duration-fast)] hover:bg-accent hover:text-foreground",
+        focusRing,
+      )}
+      {...props}
+    >
+      <span aria-hidden="true">{index}</span>
+    </a>
+  );
+}
+
+export type SourcesProps = ComponentPropsWithRef<typeof CollapsiblePrimitive.Root>;
+
+export function Sources({ className, ...props }: SourcesProps) {
+  return (
+    <CollapsiblePrimitive.Root
+      data-slot="sources"
+      className={cn("w-full text-sm", className)}
+      {...props}
+    />
+  );
+}
+
+export interface SourcesTriggerProps extends ComponentPropsWithRef<
+  typeof CollapsiblePrimitive.Trigger
+> {
+  count: number;
+}
+
+export function SourcesTrigger({ className, count, children, ...props }: SourcesTriggerProps) {
+  return (
+    <CollapsiblePrimitive.Trigger
+      data-slot="sources-trigger"
+      className={cn(
+        "flex items-center gap-1.5 rounded-md text-xs text-muted-foreground",
+        "transition-colors duration-[var(--duration-fast)] hover:text-foreground",
+        "[&[data-state=open]>svg:last-child]:rotate-180",
+        focusRing,
+        className,
+      )}
+      {...props}
+    >
+      {children ?? `${String(count)} ${count === 1 ? "source" : "sources"}`}
+      <svg
+        viewBox="0 0 24 24"
+        fill="none"
+        aria-hidden="true"
+        className="size-3.5 shrink-0 transition-transform duration-[var(--duration-normal)]"
+      >
+        <path
+          d="m6 9 6 6 6-6"
+          stroke="currentColor"
+          strokeWidth="2"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+        />
+      </svg>
+    </CollapsiblePrimitive.Trigger>
+  );
+}
+
+export function SourcesContent({
+  className,
+  children,
+  ...props
+}: ComponentPropsWithRef<typeof CollapsiblePrimitive.Content>) {
+  return (
+    <CollapsiblePrimitive.Content
+      data-slot="sources-content"
+      className={cn(
+        "overflow-hidden",
+        "data-[state=closed]:animate-accordion-close data-[state=open]:animate-accordion-open",
+        className,
+      )}
+      {...props}
+    >
+      {/* Ordered, because the numbers in the inline markers refer to positions
+          in this list. */}
+      <ol className="mt-2 flex flex-col gap-1.5">{children}</ol>
+    </CollapsiblePrimitive.Content>
+  );
+}
+
+export interface SourceProps extends ComponentPropsWithRef<"a"> {
+  index: number;
+  title: string;
+  /** Where it came from — a domain, a filename, a document title. */
+  origin?: string;
+  /** The quoted passage, if there is one. */
+  excerpt?: string;
+}
+
+export function Source({ className, index, title, origin, excerpt, ...props }: SourceProps) {
+  return (
+    <li data-slot="source">
+      <a
+        className={cn(
+          "flex gap-2 rounded-md border border-border bg-card/50 px-2.5 py-2",
+          "transition-colors duration-[var(--duration-fast)] hover:bg-accent/50",
+          focusRing,
+          className,
+        )}
+        {...props}
+      >
+        <span
+          aria-hidden="true"
+          className="mt-0.5 grid size-4 shrink-0 place-items-center rounded bg-muted text-2xs font-medium text-muted-foreground tabular-nums"
+        >
+          {index}
+        </span>
+        <span className="min-w-0 flex-1">
+          <span className="block truncate text-xs font-medium text-foreground">{title}</span>
+          {origin ? (
+            <span className="block truncate text-2xs text-muted-foreground">{origin}</span>
+          ) : null}
+          {excerpt ? (
+            <span className="mt-1 line-clamp-2 block text-xs text-muted-foreground">
+              “{excerpt}”
+            </span>
+          ) : null}
+        </span>
+      </a>
+    </li>
+  );
+}

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

@@ -0,0 +1,11 @@
+export {
+  InlineCitation,
+  Source,
+  Sources,
+  SourcesContent,
+  SourcesTrigger,
+  type InlineCitationProps,
+  type SourceProps,
+  type SourcesProps,
+  type SourcesTriggerProps,
+} from "./ai-sources";

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

@@ -0,0 +1,17 @@
+import { defineMeta } from "@/registry/schema";
+
+export const meta = defineMeta({
+  name: "ai-sources",
+  title: "AI Sources",
+  description: "Inline citation markers and the source list they refer to.",
+  category: "ai",
+  status: "stable",
+  dependencies: ["radix-ui"],
+  registryDependencies: [],
+  files: ["ai-sources.tsx"],
+  a11y:
+    "An inline marker shows a bare number, which conveys nothing on its own, so the source title " +
+    "is carried in its accessible name. A marker with no href renders as text rather than as a " +
+    "link that goes nowhere. The source list is ordered, because the marker numbers refer to " +
+    "positions in it.",
+});

package/src/components/ai-token-usage/ai-token-usage.stories.tsx

@@ -0,0 +1,59 @@
+import type { Decorator, Meta, StoryObj } from "@storybook/react-vite";
+
+import { TokenCount, TokenUsage } from "./ai-token-usage";
+
+/** Named so its type is nameable in declaration output (TS2883). */
+const withFixedWidth: Decorator = (Story) => (
+  <div className="w-72">
+    <Story />
+  </div>
+);
+
+const meta = {
+  title: "AI/Token Usage",
+  component: TokenUsage,
+  args: { used: 42000, limit: 200000 },
+  argTypes: {
+    used: { control: { type: "range", min: 0, max: 240000, step: 1000 } },
+  },
+  decorators: [withFixedWidth],
+} satisfies Meta<typeof TokenUsage>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};
+
+/** Running out of context is a cliff, not a slope — so the gauge warns early. */
+export const Thresholds: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="grid gap-5">
+      <TokenUsage used={42000} limit={200000} />
+      <TokenUsage used={175000} limit={200000} />
+      <TokenUsage used={212000} limit={200000} />
+    </div>
+  ),
+};
+
+export const CustomFormat: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <TokenUsage
+      used={128000}
+      limit={200000}
+      label="Context"
+      format={(value) => `${String(Math.round(value / 1000))}k`}
+    />
+  ),
+};
+
+export const InlineCount: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex items-center gap-3">
+      <TokenCount value={1284} />
+      <TokenCount value={412} label="output tokens" />
+    </div>
+  ),
+};