@dowel-ui/react 0.1.0

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

@@ -0,0 +1,160 @@
+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 { Button } from "../button";
+import {
+  Message,
+  MessageActions,
+  MessageAvatar,
+  MessageBody,
+  MessageFooter,
+} from "./ai-message";
+
+describe("Message", () => {
+  it("renders as a list item, for a transcript", () => {
+    render(
+      <ol>
+        <Message from="user">
+          <MessageBody from="user">Hello</MessageBody>
+        </Message>
+      </ol>,
+    );
+    expect(screen.getByRole("listitem")).toBeInTheDocument();
+  });
+
+  it.each([
+    ["user", "You said"],
+    ["assistant", "Assistant said"],
+    ["system", "System"],
+  ] as const)("names the %s speaker in text, not only by layout", (role, label) => {
+    render(
+      <ol>
+        <Message from={role}>
+          <MessageBody from={role}>Content</MessageBody>
+        </Message>
+      </ol>,
+    );
+    // Colour and alignment convey the speaker to a sighted reader and nothing
+    // to anyone else, so the role has to be readable.
+    expect(screen.getByRole("listitem")).toHaveTextContent(label);
+  });
+
+  it("accepts a custom speaker label", () => {
+    render(
+      <ol>
+        <Message from="assistant" fromLabel="Claude said">
+          <MessageBody from="assistant">Hi</MessageBody>
+        </Message>
+      </ol>,
+    );
+    expect(screen.getByRole("listitem")).toHaveTextContent("Claude said");
+  });
+
+  it("marks the speaker for styling", () => {
+    render(
+      <ol>
+        <Message from="user">
+          <MessageBody from="user">Hello</MessageBody>
+        </Message>
+      </ol>,
+    );
+    expect(screen.getByRole("listitem")).toHaveAttribute("data-from", "user");
+  });
+
+  it("does not shadow the ARIA role attribute", () => {
+    // `from` names the speaker; `role` still reaches the element as the real
+    // ARIA attribute, so a consumer can override the list-item semantics.
+    render(
+      <ol>
+        <Message from="assistant" role="presentation">
+          <MessageBody from="assistant">Hi</MessageBody>
+        </Message>
+      </ol>,
+    );
+    expect(screen.queryByRole("listitem")).not.toBeInTheDocument();
+  });
+
+  it("hides the avatar from assistive technology", () => {
+    const { container } = render(
+      <ol>
+        <Message from="assistant">
+          <MessageAvatar>AI</MessageAvatar>
+          <MessageBody from="assistant">Hi</MessageBody>
+        </Message>
+      </ol>,
+    );
+    expect(container.querySelector("[data-slot='message-avatar']")).toHaveAttribute(
+      "aria-hidden",
+      "true",
+    );
+  });
+
+  it("keeps hover-revealed actions in the tab order", async () => {
+    const user = userEvent.setup();
+    render(
+      <ol>
+        <Message from="assistant">
+          <MessageBody from="assistant">
+            Hi
+            <MessageActions>
+              <Button size="icon-sm" variant="ghost" aria-label="Copy">
+                C
+              </Button>
+            </MessageActions>
+          </MessageBody>
+        </Message>
+      </ol>,
+    );
+
+    // Visually faded until hover, but reachable — a control that only exists on
+    // hover is unusable by keyboard and invisible on touch.
+    await user.tab();
+    expect(screen.getByRole("button", { name: "Copy" })).toHaveFocus();
+  });
+
+  it("renders a footer for attachments and citations", () => {
+    render(
+      <ol>
+        <Message from="assistant">
+          <MessageBody from="assistant">
+            Hi
+            <MessageFooter>
+              <span>2 sources</span>
+            </MessageFooter>
+          </MessageBody>
+        </Message>
+      </ol>,
+    );
+    expect(screen.getByText("2 sources")).toBeInTheDocument();
+  });
+
+  it("lets a consumer className override a conflicting utility", () => {
+    render(
+      <ol>
+        <Message from="user" className="gap-8">
+          <MessageBody from="user">Hi</MessageBody>
+        </Message>
+      </ol>,
+    );
+    const item = screen.getByRole("listitem");
+    expect(item).toHaveClass("gap-8");
+    expect(item).not.toHaveClass("gap-3");
+  });
+
+  it("has no accessibility violations", async () => {
+    const { container } = render(
+      <ol>
+        <Message from="user">
+          <MessageBody from="user">What is the capital of France?</MessageBody>
+        </Message>
+        <Message from="assistant">
+          <MessageAvatar>AI</MessageAvatar>
+          <MessageBody from="assistant">Paris.</MessageBody>
+        </Message>
+      </ol>,
+    );
+    await expectNoA11yViolations(container);
+  });
+});

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

@@ -0,0 +1,162 @@
+"use client";
+
+import { cva, type VariantProps } from "class-variance-authority";
+import { Slot } from "radix-ui";
+import type { ComponentPropsWithRef } from "react";
+
+import { cn } from "@/lib/utils";
+
+/**
+ * One turn in a conversation.
+ *
+ * The role is stated in text, not only in layout. Alignment and colour are how
+ * a sighted reader tells a question from an answer; a screen reader user gets
+ * nothing from either, so every message carries a visually hidden label naming
+ * who is speaking.
+ */
+
+const messageVariants = cva("group/message flex w-full gap-3", {
+  variants: {
+    role: {
+      user: "flex-row-reverse",
+      assistant: "flex-row",
+      system: "flex-row",
+    },
+  },
+  defaultVariants: {
+    role: "assistant",
+  },
+});
+
+const messageBodyVariants = cva("min-w-0 rounded-xl px-4 py-3 text-sm", {
+  variants: {
+    role: {
+      user: "max-w-[85%] bg-primary text-primary-foreground",
+      assistant: "w-full bg-transparent px-0 py-0 text-foreground",
+      system:
+        "w-full border border-dashed border-border bg-muted/40 text-xs text-muted-foreground",
+    },
+  },
+  defaultVariants: {
+    role: "assistant",
+  },
+});
+
+export type MessageRole = "user" | "assistant" | "system";
+
+export interface MessageProps
+  extends ComponentPropsWithRef<"li">, Omit<VariantProps<typeof messageVariants>, "role"> {
+  /**
+   * Who is speaking.
+   *
+   * Named `from` rather than `role` on purpose. `role` is a global HTML
+   * attribute, and a component prop that shadows it cannot be told apart from
+   * the real thing by static analysis — every consumer's accessibility linter
+   * would flag ordinary usage of this component. The values are still the
+   * familiar conversation roles.
+   */
+  from?: MessageRole;
+  /** Overrides the visually hidden speaker label. */
+  fromLabel?: string;
+}
+
+const DEFAULT_ROLE_LABELS: Record<MessageRole, string> = {
+  user: "You said",
+  assistant: "Assistant said",
+  system: "System",
+};
+
+export function Message({
+  className,
+  from = "assistant",
+  fromLabel,
+  children,
+  ...props
+}: MessageProps) {
+  return (
+    <li
+      data-slot="message"
+      data-from={from}
+      className={cn(messageVariants({ role: from }), className)}
+      {...props}
+    >
+      {/* Names the speaker for anyone who cannot see the layout. */}
+      <span className="sr-only">{fromLabel ?? DEFAULT_ROLE_LABELS[from]}:</span>
+      {children}
+    </li>
+  );
+}
+
+export interface MessageBodyProps
+  extends ComponentPropsWithRef<"div">, Omit<VariantProps<typeof messageBodyVariants>, "role"> {
+  /** Who is speaking. See the note on MessageProps for why not `role`. */
+  from?: MessageRole;
+}
+
+export function MessageBody({ className, from = "assistant", ...props }: MessageBodyProps) {
+  return (
+    <div
+      data-slot="message-body"
+      className={cn(messageBodyVariants({ role: from }), className)}
+      {...props}
+    />
+  );
+}
+
+export interface MessageAvatarProps extends ComponentPropsWithRef<"div"> {
+  asChild?: boolean;
+}
+
+/** Decorative: the speaker is already named by the hidden label on Message. */
+export function MessageAvatar({ className, asChild, ...props }: MessageAvatarProps) {
+  const Comp = asChild ? Slot.Root : "div";
+
+  return (
+    <Comp
+      data-slot="message-avatar"
+      aria-hidden="true"
+      className={cn(
+        "grid size-7 shrink-0 place-items-center rounded-full border border-border bg-muted",
+        "text-xs font-medium text-muted-foreground",
+        "[&_svg:not([class*='size-'])]:size-3.5",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+/**
+ * Per-message controls: copy, regenerate, feedback.
+ *
+ * Revealed on hover for pointer users but always present in the DOM and in the
+ * tab order — hiding controls behind hover makes them unreachable by keyboard
+ * and invisible on touch.
+ */
+export function MessageActions({ className, ...props }: ComponentPropsWithRef<"div">) {
+  return (
+    <div
+      data-slot="message-actions"
+      className={cn(
+        "mt-1.5 flex items-center gap-1",
+        "opacity-0 transition-opacity duration-[var(--duration-fast)]",
+        "group-focus-within/message:opacity-100 group-hover/message:opacity-100",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+/** Attachments, citations and other content that hangs off a message. */
+export function MessageFooter({ className, ...props }: ComponentPropsWithRef<"div">) {
+  return (
+    <div
+      data-slot="message-footer"
+      className={cn("mt-2 flex flex-wrap items-center gap-2", className)}
+      {...props}
+    />
+  );
+}
+
+export { messageBodyVariants, messageVariants };

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

@@ -0,0 +1,13 @@
+export {
+  Message,
+  MessageActions,
+  MessageAvatar,
+  MessageBody,
+  MessageFooter,
+  messageBodyVariants,
+  messageVariants,
+  type MessageAvatarProps,
+  type MessageBodyProps,
+  type MessageProps,
+  type MessageRole,
+} from "./ai-message";

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

@@ -0,0 +1,17 @@
+import { defineMeta } from "@/registry/schema";
+
+export const meta = defineMeta({
+  name: "ai-message",
+  title: "AI Message",
+  description: "One turn in a conversation, with role, avatar, actions and footer slots.",
+  category: "ai",
+  status: "stable",
+  dependencies: ["class-variance-authority", "radix-ui"],
+  registryDependencies: [],
+  files: ["ai-message.tsx"],
+  a11y:
+    "Every message carries a visually hidden label naming the speaker. Alignment and colour tell " +
+    "a sighted reader who is talking and tell a screen reader user nothing, so the role is always " +
+    "in text. Message actions fade in on hover but stay in the DOM and in the tab order — a " +
+    "control that only exists on hover is unreachable by keyboard and invisible on touch.",
+});

package/src/components/ai-model-selector/ai-model-selector.stories.tsx

@@ -0,0 +1,66 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+
+import { Badge } from "@/components/badge";
+
+import { ModelSelector, type ModelOption } from "./ai-model-selector";
+
+const MODELS: ModelOption[] = [
+  {
+    id: "fast",
+    name: "Fast",
+    description: "Lowest latency. Good for short answers.",
+    group: "General",
+  },
+  {
+    id: "balanced",
+    name: "Balanced",
+    description: "The default for most work.",
+    group: "General",
+    badge: (
+      <Badge size="sm" variant="secondary">
+        Default
+      </Badge>
+    ),
+  },
+  {
+    id: "deep",
+    name: "Deep Research",
+    description: "Multi-step research with citations.",
+    group: "Advanced",
+  },
+  {
+    id: "vision",
+    name: "Vision Pro",
+    group: "Advanced",
+    disabled: true,
+    disabledReason: "Available on the Team plan",
+  },
+];
+
+const meta = {
+  title: "AI/Model Selector",
+  component: ModelSelector,
+  args: { models: MODELS, defaultValue: "balanced", "aria-label": "Model" },
+  parameters: { controls: { disable: true } },
+} satisfies Meta<typeof ModelSelector>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/** The trigger shows only the model name; descriptions stay in the list. */
+export const Default: Story = {};
+
+export const Ungrouped: Story = {
+  args: {
+    models: [
+      { id: "a", name: "Model A", description: "Fast and cheap." },
+      { id: "b", name: "Model B", description: "Slower and stronger." },
+    ],
+    defaultValue: "a",
+  },
+};
+
+/** A disabled model always says why. Otherwise it reads as a broken interface. */
+export const WithUnavailableModel: Story = {
+  args: { defaultValue: "fast" },
+};

package/src/components/ai-model-selector/ai-model-selector.test.tsx

@@ -0,0 +1,120 @@
+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 { ModelSelector, type ModelOption } from "./ai-model-selector";
+
+const MODELS: ModelOption[] = [
+  { id: "fast", name: "Fast", description: "Quick answers.", group: "General" },
+  { id: "balanced", name: "Balanced", description: "The default.", group: "General" },
+  {
+    id: "deep",
+    name: "Deep Research",
+    group: "Advanced",
+    disabled: true,
+    disabledReason: "Available on the Pro plan",
+  },
+];
+
+describe("ModelSelector", () => {
+  it("shows a placeholder until a model is chosen", () => {
+    render(<ModelSelector models={MODELS} aria-label="Model" />);
+    expect(screen.getByRole("combobox")).toHaveTextContent("Select a model");
+  });
+
+  it("lists the models, grouped", async () => {
+    const user = userEvent.setup();
+    render(<ModelSelector models={MODELS} aria-label="Model" />);
+
+    await user.click(screen.getByRole("combobox"));
+    expect(await screen.findByRole("option", { name: /Fast/ })).toBeInTheDocument();
+    expect(screen.getByText("General")).toBeInTheDocument();
+    expect(screen.getByText("Advanced")).toBeInTheDocument();
+  });
+
+  it("shows each model's description", async () => {
+    const user = userEvent.setup();
+    render(<ModelSelector models={MODELS} aria-label="Model" />);
+
+    await user.click(screen.getByRole("combobox"));
+    expect(await screen.findByText("Quick answers.")).toBeInTheDocument();
+  });
+
+  it("says why an unavailable model cannot be chosen", async () => {
+    const user = userEvent.setup();
+    render(<ModelSelector models={MODELS} aria-label="Model" />);
+
+    await user.click(screen.getByRole("combobox"));
+    // A disabled option with no reason reads as a broken interface.
+    expect(await screen.findByText("Available on the Pro plan")).toBeInTheDocument();
+  });
+
+  it("does not select a disabled model", async () => {
+    const onValueChange = vi.fn();
+    const user = userEvent.setup();
+    render(<ModelSelector models={MODELS} aria-label="Model" onValueChange={onValueChange} />);
+
+    await user.click(screen.getByRole("combobox"));
+    await user.click(await screen.findByRole("option", { name: /Deep Research/ }));
+    expect(onValueChange).not.toHaveBeenCalled();
+  });
+
+  it("reports the chosen model", async () => {
+    const onValueChange = vi.fn();
+    const user = userEvent.setup();
+    render(<ModelSelector models={MODELS} aria-label="Model" onValueChange={onValueChange} />);
+
+    await user.click(screen.getByRole("combobox"));
+    await user.click(await screen.findByRole("option", { name: /Balanced/ }));
+    expect(onValueChange).toHaveBeenCalledWith("balanced");
+  });
+
+  it("shows the chosen model's name, not its description", async () => {
+    render(<ModelSelector models={MODELS} aria-label="Model" defaultValue="fast" />);
+
+    await waitFor(() => {
+      expect(screen.getByRole("combobox")).toHaveTextContent("Fast");
+    });
+    expect(screen.getByRole("combobox")).not.toHaveTextContent("Quick answers.");
+  });
+
+  it("keeps the order it was given rather than sorting groups", async () => {
+    const user = userEvent.setup();
+    render(<ModelSelector models={MODELS} aria-label="Model" />);
+
+    await user.click(screen.getByRole("combobox"));
+    const options = await screen.findAllByRole("option");
+    expect(options.map((option) => option.textContent?.slice(0, 4))).toEqual([
+      "Fast",
+      "Bala",
+      "Deep",
+    ]);
+  });
+
+  it("works without groups", async () => {
+    const user = userEvent.setup();
+    render(
+      <ModelSelector
+        models={[
+          { id: "a", name: "Model A" },
+          { id: "b", name: "Model B" },
+        ]}
+        aria-label="Model"
+      />,
+    );
+
+    await user.click(screen.getByRole("combobox"));
+    expect(await screen.findByRole("option", { name: "Model A" })).toBeInTheDocument();
+  });
+
+  it("has no accessibility violations", async () => {
+    const { container } = render(
+      <>
+        <span id="model-label">Model</span>
+        <ModelSelector models={MODELS} aria-labelledby="model-label" />
+      </>,
+    );
+    await expectNoA11yViolations(container);
+  });
+});

package/src/components/ai-model-selector/ai-model-selector.tsx

@@ -0,0 +1,112 @@
+"use client";
+
+import type { ComponentPropsWithRef, ReactNode } from "react";
+
+import {
+  Select,
+  SelectContent,
+  SelectGroup,
+  SelectItem,
+  SelectLabel,
+  SelectTrigger,
+  SelectValue,
+} from "@/components/select";
+import { cn } from "@/lib/utils";
+
+/**
+ * Picks the model a conversation runs on.
+ *
+ * A thin, opinionated layer over Select rather than a new control: model
+ * pickers differ between products in what they show, not in how they behave.
+ * What this adds is the shape of the option — a name, a short description, and
+ * the fact that some models are unavailable on the current plan — which is the
+ * part every implementation gets wrong in the same way, by hiding the reason a
+ * model cannot be chosen.
+ */
+
+export interface ModelOption {
+  id: string;
+  name: string;
+  /** One line on what the model is for. */
+  description?: string;
+  /** Grouping, for example a provider name. */
+  group?: string;
+  disabled?: boolean;
+  /**
+   * Why it is unavailable.
+   *
+   * Shown and announced alongside the name. A disabled option with no reason
+   * makes the user think the interface is broken.
+   */
+  disabledReason?: string;
+  badge?: ReactNode;
+}
+
+export interface ModelSelectorProps extends Omit<
+  ComponentPropsWithRef<typeof SelectTrigger>,
+  "children"
+> {
+  models: ModelOption[];
+  value?: string;
+  defaultValue?: string;
+  onValueChange?: (value: string) => void;
+  placeholder?: string;
+}
+
+export function ModelSelector({
+  className,
+  models,
+  value,
+  defaultValue,
+  onValueChange,
+  placeholder = "Select a model",
+  ...props
+}: ModelSelectorProps) {
+  // Preserves the order the caller gave, rather than sorting group names.
+  const groups = new Map<string, ModelOption[]>();
+  for (const model of models) {
+    const key = model.group ?? "";
+    groups.set(key, [...(groups.get(key) ?? []), model]);
+  }
+
+  return (
+    <Select value={value} defaultValue={defaultValue} onValueChange={onValueChange}>
+      <SelectTrigger
+        data-slot="model-selector"
+        className={cn("w-auto min-w-44 gap-2", className)}
+        {...props}
+      >
+        <SelectValue placeholder={placeholder} />
+      </SelectTrigger>
+      <SelectContent className="min-w-64">
+        {[...groups].map(([group, groupModels]) => (
+          <SelectGroup key={group || "ungrouped"}>
+            {group ? <SelectLabel>{group}</SelectLabel> : null}
+            {groupModels.map((model) => (
+              <SelectItem
+                key={model.id}
+                value={model.id}
+                disabled={model.disabled}
+                textValue={model.name}
+                // Only the name reaches the trigger; the description stays in
+                // the list where there is room for it.
+                label={model.name}
+              >
+                <span className="flex min-w-0 flex-col gap-0.5">
+                  <span className="flex items-center gap-2">{model.badge}</span>
+                  {model.disabled && model.disabledReason ? (
+                    <span className="text-2xs text-muted-foreground">
+                      {model.disabledReason}
+                    </span>
+                  ) : model.description ? (
+                    <span className="text-2xs text-muted-foreground">{model.description}</span>
+                  ) : null}
+                </span>
+              </SelectItem>
+            ))}
+          </SelectGroup>
+        ))}
+      </SelectContent>
+    </Select>
+  );
+}

package/src/components/ai-model-selector/index.ts

@@ -0,0 +1 @@
+export { ModelSelector, type ModelOption, type ModelSelectorProps } from "./ai-model-selector";

package/src/components/ai-model-selector/meta.ts

@@ -0,0 +1,17 @@
+import { defineMeta } from "@/registry/schema";
+
+export const meta = defineMeta({
+  name: "ai-model-selector",
+  title: "AI Model Selector",
+  description: "Picks the model a conversation runs on, with descriptions and availability.",
+  category: "ai",
+  status: "stable",
+  dependencies: [],
+  registryDependencies: ["select"],
+  files: ["ai-model-selector.tsx"],
+  a11y:
+    "Inherits Select's listbox keyboard model. Each option sets textValue to the model name so " +
+    "typeahead matches the name rather than the description. A disabled model shows and " +
+    "announces why it is unavailable — a disabled option with no reason reads as a broken " +
+    "interface.",
+});