@dowel-ui/react 0.1.0

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

@@ -0,0 +1,83 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+
+import { expectNoA11yViolations } from "../../../test/a11y";
+import { TokenCount, TokenUsage } from "./ai-token-usage";
+
+describe("TokenUsage", () => {
+  it("shows the numbers, which are the actual content", () => {
+    render(<TokenUsage used={12000} limit={200000} />);
+    expect(screen.getByText("12,000 / 200,000")).toBeInTheDocument();
+  });
+
+  it("labels what is being measured", () => {
+    render(<TokenUsage used={100} limit={1000} />);
+    expect(screen.getByText("Context used")).toBeInTheDocument();
+  });
+
+  it("accepts a custom label and formatter", () => {
+    render(
+      <TokenUsage
+        used={1500}
+        limit={4000}
+        label="Budget"
+        format={(value) => `${String(Math.round(value / 1000))}k`}
+      />,
+    );
+    expect(screen.getByText("Budget")).toBeInTheDocument();
+    expect(screen.getByText("2k / 4k")).toBeInTheDocument();
+  });
+
+  it("hides the bar, since it only restates the numbers", () => {
+    const { container } = render(<TokenUsage used={100} limit={1000} />);
+    // Not a second progressbar to read past.
+    expect(container.querySelector("[aria-hidden='true']")).toBeInTheDocument();
+    expect(screen.queryByRole("progressbar")).not.toBeInTheDocument();
+  });
+
+  it("marks the warning state past the threshold", () => {
+    const { container } = render(<TokenUsage used={900} limit={1000} />);
+    expect(container.firstElementChild).toHaveAttribute("data-warning", "true");
+  });
+
+  it("does not warn below the threshold", () => {
+    const { container } = render(<TokenUsage used={100} limit={1000} />);
+    expect(container.firstElementChild).not.toHaveAttribute("data-warning");
+  });
+
+  it("marks going over the limit", () => {
+    const { container } = render(<TokenUsage used={1200} limit={1000} />);
+    expect(container.firstElementChild).toHaveAttribute("data-over", "true");
+    // The figures stay readable even when over.
+    expect(screen.getByText("1,200 / 1,000")).toBeInTheDocument();
+  });
+
+  it("clamps the bar rather than overflowing it", () => {
+    const { container } = render(<TokenUsage used={5000} limit={1000} />);
+    const fill = container.querySelector("[aria-hidden='true'] > div");
+    expect(fill).toHaveStyle({ width: "100%" });
+  });
+
+  it("survives a zero limit without dividing by it", () => {
+    const { container } = render(<TokenUsage used={10} limit={0} />);
+    const fill = container.querySelector("[aria-hidden='true'] > div");
+    expect(fill).toHaveStyle({ width: "0%" });
+  });
+
+  it("has no accessibility violations", async () => {
+    const { container } = render(<TokenUsage used={180000} limit={200000} />);
+    await expectNoA11yViolations(container);
+  });
+});
+
+describe("TokenCount", () => {
+  it("formats the count", () => {
+    render(<TokenCount value={12345} />);
+    expect(screen.getByText("12,345 tokens")).toBeInTheDocument();
+  });
+
+  it("accepts a custom unit", () => {
+    render(<TokenCount value={42} label="output tokens" />);
+    expect(screen.getByText("42 output tokens")).toBeInTheDocument();
+  });
+});

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

@@ -0,0 +1,105 @@
+"use client";
+
+import type { ComponentPropsWithRef } from "react";
+
+import { cn } from "@/lib/utils";
+
+/**
+ * How much of the context window a conversation has used.
+ *
+ * Worth showing because running out of context is a cliff, not a slope: the
+ * conversation stops behaving the way it did, and without a gauge that looks
+ * like the model getting worse rather than a limit being reached.
+ *
+ * The numbers are the message; the bar is a summary of them. Both are present,
+ * and the numbers are what a screen reader gets.
+ */
+
+export interface TokenUsageProps extends ComponentPropsWithRef<"div"> {
+  /** Tokens used so far. */
+  used: number;
+  /** The context window. */
+  limit: number;
+  label?: string;
+  /** Fraction of the limit past which the gauge warns. */
+  warnAt?: number;
+  /** Formats the numbers. Defaults to the runtime locale's grouping. */
+  format?: (value: number) => string;
+}
+
+function defaultFormat(value: number): string {
+  return new Intl.NumberFormat().format(value);
+}
+
+export function TokenUsage({
+  className,
+  used,
+  limit,
+  label = "Context used",
+  warnAt = 0.85,
+  format = defaultFormat,
+  ...props
+}: TokenUsageProps) {
+  const fraction = limit > 0 ? Math.min(1, Math.max(0, used / limit)) : 0;
+  const percent = Math.round(fraction * 100);
+  const warning = fraction >= warnAt;
+  const over = used > limit;
+
+  return (
+    <div
+      data-slot="token-usage"
+      data-warning={warning || undefined}
+      data-over={over || undefined}
+      className={cn("flex w-full flex-col gap-1", className)}
+      {...props}
+    >
+      <div className="flex items-baseline justify-between gap-2 text-xs">
+        <span className="text-muted-foreground">{label}</span>
+        <span
+          className={cn(
+            "tabular-nums",
+            over ? "text-destructive" : warning ? "text-warning" : "text-muted-foreground",
+          )}
+        >
+          {format(used)} / {format(limit)}
+        </span>
+      </div>
+      {/* The bar summarises what the numbers above already say, so it is
+          decorative rather than a second progressbar to read through. */}
+      <div aria-hidden="true" className="h-1 w-full overflow-hidden rounded-full bg-muted">
+        <div
+          className={cn(
+            "h-full rounded-full transition-[width] duration-[var(--duration-slow)] ease-[var(--ease-out-quint)]",
+            over ? "bg-destructive" : warning ? "bg-warning" : "bg-primary",
+          )}
+          style={{ width: `${String(percent)}%` }}
+        />
+      </div>
+    </div>
+  );
+}
+
+export interface TokenCountProps extends ComponentPropsWithRef<"span"> {
+  value: number;
+  label?: string;
+  format?: (value: number) => string;
+}
+
+/** A bare token count, for a message footer or a toolbar. */
+export function TokenCount({
+  className,
+  value,
+  label = "tokens",
+  format = defaultFormat,
+  ...props
+}: TokenCountProps) {
+  return (
+    <span
+      data-slot="token-count"
+      className={cn("text-2xs text-muted-foreground tabular-nums", className)}
+      {...props}
+    >
+      {format(value)} {label}
+    </span>
+  );
+}

package/src/components/ai-token-usage/index.ts

@@ -0,0 +1,6 @@
+export {
+  TokenCount,
+  TokenUsage,
+  type TokenCountProps,
+  type TokenUsageProps,
+} from "./ai-token-usage";

package/src/components/ai-token-usage/meta.ts

@@ -0,0 +1,16 @@
+import { defineMeta } from "@/registry/schema";
+
+export const meta = defineMeta({
+  name: "ai-token-usage",
+  title: "AI Token Usage",
+  description: "A gauge showing how much of the context window a conversation has used.",
+  category: "ai",
+  status: "stable",
+  dependencies: [],
+  registryDependencies: [],
+  files: ["ai-token-usage.tsx"],
+  a11y:
+    "The numbers are the content and the bar only summarises them, so the bar is aria-hidden " +
+    "rather than a second progressbar to read past. Counts are formatted for the locale. Warning " +
+    "and over-limit states change the wording's colour but never remove the figures.",
+});

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

@@ -0,0 +1,96 @@
+import type { Decorator, Meta, StoryObj } from "@storybook/react-vite";
+
+import { Tool, ToolContent, ToolHeader, ToolPayload, ToolSection } from "./ai-tool";
+
+/** Named so its type is nameable in declaration output (TS2883). */
+const withFixedWidth: Decorator = (Story) => (
+  <div className="w-[32rem]">
+    <Story />
+  </div>
+);
+
+const meta = {
+  title: "AI/Tool Call",
+  component: Tool,
+  args: { status: "success" },
+  argTypes: {
+    status: { control: "inline-radio", options: ["pending", "running", "success", "error"] },
+  },
+  decorators: [withFixedWidth],
+} satisfies Meta<typeof Tool>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: (args) => (
+    <Tool {...args}>
+      <ToolHeader name="search_web" status={args.status ?? "success"} />
+      <ToolContent>
+        <ToolSection label="Arguments">
+          <ToolPayload label="Arguments">
+            {JSON.stringify({ query: "accessible data tables", limit: 5 }, null, 2)}
+          </ToolPayload>
+        </ToolSection>
+        <ToolSection label="Result">
+          <ToolPayload label="Result">
+            {JSON.stringify(
+              { results: [{ title: "ARIA authoring practices", url: "https://example.org" }] },
+              null,
+              2,
+            )}
+          </ToolPayload>
+        </ToolSection>
+      </ToolContent>
+    </Tool>
+  ),
+};
+
+/** Status is always a word, never only a colour. */
+export const Statuses: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="grid gap-2">
+      {(["pending", "running", "success", "error"] as const).map((status) => (
+        <Tool key={status} status={status}>
+          <ToolHeader name={`tool_${status}`} status={status} />
+          <ToolContent>
+            <ToolSection label="Result">
+              <ToolPayload label="Result">{`Status: ${status}`}</ToolPayload>
+            </ToolSection>
+          </ToolContent>
+        </Tool>
+      ))}
+    </div>
+  ),
+};
+
+export const CustomStatusWording: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <Tool status="running">
+      <ToolHeader name="crawl_site" status="running" statusLabel="Fetching page 12 of 40" />
+      <ToolContent>
+        <ToolSection label="Progress">
+          <ToolPayload label="Progress">Crawling https://example.org…</ToolPayload>
+        </ToolSection>
+      </ToolContent>
+    </Tool>
+  ),
+};
+
+export const Failed: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <Tool status="error" defaultOpen>
+      <ToolHeader name="read_file" status="error" />
+      <ToolContent>
+        <ToolSection label="Error">
+          <ToolPayload label="Error">
+            {"ENOENT: no such file or directory, open '/app/missing.ts'"}
+          </ToolPayload>
+        </ToolSection>
+      </ToolContent>
+    </Tool>
+  ),
+};

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

@@ -0,0 +1,137 @@
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it } from "vitest";
+
+import { expectNoA11yViolations } from "../../../test/a11y";
+import {
+  Tool,
+  ToolContent,
+  ToolHeader,
+  ToolPayload,
+  ToolSection,
+  type ToolStatus,
+} from "./ai-tool";
+
+function Example({ status = "success" }: { status?: ToolStatus } = {}) {
+  return (
+    <Tool status={status}>
+      <ToolHeader name="search_web" status={status} />
+      <ToolContent>
+        <ToolSection label="Arguments">
+          <ToolPayload label="Arguments">{'{ "query": "capital of France" }'}</ToolPayload>
+        </ToolSection>
+        <ToolSection label="Result">
+          <ToolPayload label="Result">{'{ "answer": "Paris" }'}</ToolPayload>
+        </ToolSection>
+      </ToolContent>
+    </Tool>
+  );
+}
+
+describe("Tool", () => {
+  it("is collapsed by default, because provenance is not the answer", () => {
+    render(<Example />);
+    expect(screen.getByRole("button", { name: /search_web/ })).toHaveAttribute(
+      "aria-expanded",
+      "false",
+    );
+    expect(screen.queryByText(/capital of France/)).not.toBeInTheDocument();
+  });
+
+  it("opens on click", async () => {
+    const user = userEvent.setup();
+    render(<Example />);
+
+    await user.click(screen.getByRole("button", { name: /search_web/ }));
+    expect(await screen.findByText(/capital of France/)).toBeInTheDocument();
+  });
+
+  it("opens from the keyboard", async () => {
+    const user = userEvent.setup();
+    render(<Example />);
+
+    await user.tab();
+    await user.keyboard("{Enter}");
+    await waitFor(() => {
+      expect(screen.getByRole("button", { name: /search_web/ })).toHaveAttribute(
+        "aria-expanded",
+        "true",
+      );
+    });
+  });
+
+  it.each([
+    ["pending", "Queued"],
+    ["running", "Running"],
+    ["success", "Completed"],
+    ["error", "Failed"],
+  ] as const)("states the %s status in words, not only in colour", (status, label) => {
+    render(<Example status={status} />);
+    // A coloured dot says nothing to a screen reader, and nothing to anyone who
+    // cannot distinguish the colours.
+    expect(screen.getByRole("button", { name: new RegExp(label) })).toBeInTheDocument();
+  });
+
+  it("accepts custom status wording", () => {
+    render(
+      <Tool status="running">
+        <ToolHeader name="fetch" status="running" statusLabel="Fetching page 2 of 5" />
+        <ToolContent>Body</ToolContent>
+      </Tool>,
+    );
+    expect(screen.getByText("Fetching page 2 of 5")).toBeInTheDocument();
+  });
+
+  it("marks the status for styling", () => {
+    const { container } = render(<Example status="error" />);
+    expect(container.querySelector("[data-slot='tool']")).toHaveAttribute(
+      "data-status",
+      "error",
+    );
+  });
+
+  it("makes payloads focusable named regions", async () => {
+    const user = userEvent.setup();
+    render(<Example />);
+
+    await user.click(screen.getByRole("button", { name: /search_web/ }));
+
+    // JSON scrolls, and a scroll box that cannot take focus is unreachable by
+    // keyboard.
+    const payload = await screen.findByRole("region", { name: "Arguments" });
+    expect(payload).toHaveAttribute("tabindex", "0");
+  });
+
+  it("labels each section", async () => {
+    const user = userEvent.setup();
+    render(<Example />);
+
+    await user.click(screen.getByRole("button", { name: /search_web/ }));
+    expect(await screen.findByText("Arguments")).toBeInTheDocument();
+    expect(screen.getByText("Result")).toBeInTheDocument();
+  });
+
+  it("can be opened by default", () => {
+    render(
+      <Tool status="success" defaultOpen>
+        <ToolHeader name="read_file" status="success" />
+        <ToolContent>Contents</ToolContent>
+      </Tool>,
+    );
+    expect(screen.getByText("Contents")).toBeInTheDocument();
+  });
+
+  it("has no accessibility violations when open", async () => {
+    const { container } = render(
+      <Tool status="success" defaultOpen>
+        <ToolHeader name="search_web" status="success" />
+        <ToolContent>
+          <ToolSection label="Result">
+            <ToolPayload label="Result">{'{ "answer": "Paris" }'}</ToolPayload>
+          </ToolSection>
+        </ToolContent>
+      </Tool>,
+    );
+    await expectNoA11yViolations(container);
+  });
+});

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

@@ -0,0 +1,235 @@
+"use client";
+
+import { cva, type VariantProps } from "class-variance-authority";
+import { Collapsible as CollapsiblePrimitive } from "radix-ui";
+import type { ComponentPropsWithRef, ReactNode } from "react";
+
+import { focusRing } from "@/lib/styles";
+import { cn } from "@/lib/utils";
+
+/**
+ * A tool the model called, and what came back.
+ *
+ * Collapsed by default: a tool call is provenance, not the answer. Someone
+ * checking why a response says what it does needs to open it; everybody else
+ * needs it to stay out of the way.
+ *
+ * The status is the whole point of the header, so it is text, never a coloured
+ * dot alone.
+ */
+
+export type ToolStatus = "pending" | "running" | "success" | "error";
+
+const STATUS_LABEL: Record<ToolStatus, string> = {
+  pending: "Queued",
+  running: "Running",
+  success: "Completed",
+  error: "Failed",
+};
+
+const toolVariants = cva("overflow-hidden rounded-lg border text-sm", {
+  variants: {
+    status: {
+      pending: "border-border bg-muted/30",
+      running: "border-info/30 bg-info/5",
+      success: "border-border bg-muted/30",
+      error: "border-destructive/30 bg-destructive/5",
+    },
+  },
+  defaultVariants: {
+    status: "pending",
+  },
+});
+
+export interface ToolProps
+  extends
+    ComponentPropsWithRef<typeof CollapsiblePrimitive.Root>,
+    VariantProps<typeof toolVariants> {
+  status?: ToolStatus;
+}
+
+export function Tool({ className, status = "pending", ...props }: ToolProps) {
+  return (
+    <CollapsiblePrimitive.Root
+      data-slot="tool"
+      data-status={status}
+      className={cn(toolVariants({ status }), className)}
+      {...props}
+    />
+  );
+}
+
+export interface ToolHeaderProps extends ComponentPropsWithRef<
+  typeof CollapsiblePrimitive.Trigger
+> {
+  /** The tool's name, as the model called it. */
+  name: string;
+  status?: ToolStatus;
+  /** Overrides the status wording. */
+  statusLabel?: string;
+  icon?: ReactNode;
+}
+
+export function ToolHeader({
+  className,
+  name,
+  status = "pending",
+  statusLabel,
+  icon,
+  ...props
+}: ToolHeaderProps) {
+  return (
+    <CollapsiblePrimitive.Trigger
+      data-slot="tool-header"
+      className={cn(
+        "flex w-full items-center gap-2 px-3 py-2 text-left",
+        "transition-colors duration-[var(--duration-fast)] hover:bg-accent/50",
+        "[&[data-state=open]>svg:last-child]:rotate-180",
+        focusRing,
+        className,
+      )}
+      {...props}
+    >
+      {icon ?? <ToolIcon status={status} />}
+      <span className="font-mono text-xs font-medium">{name}</span>
+      {/* Status in words. A coloured dot alone says nothing to a screen reader
+          and nothing to anyone who cannot distinguish the colours. */}
+      <span
+        data-slot="tool-status"
+        className={cn(
+          "ml-auto text-xs",
+          status === "error" ? "text-destructive" : "text-muted-foreground",
+        )}
+      >
+        {statusLabel ?? STATUS_LABEL[status]}
+      </span>
+      <svg
+        viewBox="0 0 24 24"
+        fill="none"
+        aria-hidden="true"
+        className="size-3.5 shrink-0 text-muted-foreground 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>
+  );
+}
+
+function ToolIcon({ status }: { status: ToolStatus }) {
+  if (status === "running") {
+    return (
+      <svg
+        viewBox="0 0 24 24"
+        fill="none"
+        aria-hidden="true"
+        className="size-3.5 shrink-0 animate-spin text-info"
+      >
+        <circle cx="12" cy="12" r="9" stroke="currentColor" strokeWidth="2.5" opacity="0.25" />
+        <path
+          d="M12 3a9 9 0 0 1 9 9"
+          stroke="currentColor"
+          strokeWidth="2.5"
+          strokeLinecap="round"
+        />
+      </svg>
+    );
+  }
+
+  return (
+    <svg
+      viewBox="0 0 24 24"
+      fill="none"
+      aria-hidden="true"
+      className={cn(
+        "size-3.5 shrink-0",
+        status === "error" ? "text-destructive" : "text-muted-foreground",
+      )}
+    >
+      <path
+        d={
+          status === "success"
+            ? "m5 13 4 4L19 7"
+            : status === "error"
+              ? "M12 8v5m0 3h.01M10.3 4.3 2.6 18a2 2 0 0 0 1.7 3h15.4a2 2 0 0 0 1.7-3L13.7 4.3a2 2 0 0 0-3.4 0Z"
+              : "M14.7 6.3a4 4 0 0 1-5 5L5 16v3h3l4.7-4.7a4 4 0 0 1 5-5l-2.3 2.3"
+        }
+        stroke="currentColor"
+        strokeWidth="2"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+    </svg>
+  );
+}
+
+export function ToolContent({
+  className,
+  ...props
+}: ComponentPropsWithRef<typeof CollapsiblePrimitive.Content>) {
+  return (
+    <CollapsiblePrimitive.Content
+      data-slot="tool-content"
+      className={cn(
+        "overflow-hidden border-t border-border",
+        "data-[state=closed]:animate-accordion-close data-[state=open]:animate-accordion-open",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+export interface ToolSectionProps extends ComponentPropsWithRef<"div"> {
+  label: string;
+}
+
+/** A labelled block inside the disclosure: the arguments, or the result. */
+export function ToolSection({ className, label, children, ...props }: ToolSectionProps) {
+  return (
+    <div
+      data-slot="tool-section"
+      className={cn("border-b border-border/60 px-3 py-2 last:border-b-0", className)}
+      {...props}
+    >
+      <p className="mb-1 text-2xs font-medium tracking-wide text-muted-foreground uppercase">
+        {label}
+      </p>
+      {children}
+    </div>
+  );
+}
+
+/**
+ * Serialised arguments or output.
+ *
+ * A `<pre>` with a tabindex, because JSON of any size scrolls and a scrollable
+ * box that cannot be focused is unreachable by keyboard.
+ */
+export interface ToolPayloadProps extends ComponentPropsWithRef<"pre"> {
+  label?: string;
+}
+
+export function ToolPayload({ className, label = "Payload", ...props }: ToolPayloadProps) {
+  return (
+    <pre
+      data-slot="tool-payload"
+      tabIndex={0}
+      role="region"
+      aria-label={label}
+      className={cn(
+        "max-h-56 overflow-auto rounded-md bg-muted/60 p-2 font-mono text-xs leading-relaxed",
+        focusRing,
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+export { toolVariants };

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

@@ -0,0 +1,13 @@
+export {
+  Tool,
+  ToolContent,
+  ToolHeader,
+  ToolPayload,
+  ToolSection,
+  toolVariants,
+  type ToolHeaderProps,
+  type ToolPayloadProps,
+  type ToolProps,
+  type ToolSectionProps,
+  type ToolStatus,
+} from "./ai-tool";