@dowel-ui/react 0.1.0

package/src/components/activity-feed/activity-feed.stories.tsx

@@ -0,0 +1,163 @@
+import type { Decorator, Meta, StoryObj } from "@storybook/react-vite";
+import { CircleCheck, GitBranch, GitPullRequest, Rocket, TriangleAlert } from "lucide-react";
+
+import { Avatar, AvatarFallback } from "@/components/avatar";
+import { Badge } from "@/components/badge";
+
+import {
+  ActivityContent,
+  ActivityDescription,
+  ActivityFeed,
+  ActivityIndicator,
+  ActivityItem,
+  ActivityTime,
+  ActivityTitle,
+} from "./activity-feed";
+
+/** Named so its type is nameable in declaration output (TS2883). */
+const withFixedWidth: Decorator = (Story) => (
+  <div className="w-96">
+    <Story />
+  </div>
+);
+
+const meta = {
+  title: "Data/Activity Feed",
+  component: ActivityFeed,
+  parameters: { controls: { disable: true } },
+  decorators: [withFixedWidth],
+} satisfies Meta<typeof ActivityFeed>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const EVENTS = [
+  {
+    id: "1",
+    icon: Rocket,
+    title: "Deployed to production",
+    detail: "Build 1420 · main",
+    at: "2026-09-01T09:12:00Z",
+    label: "12 minutes ago",
+  },
+  {
+    id: "2",
+    icon: CircleCheck,
+    title: "All checks passed",
+    detail: "24 tests, 0 failures",
+    at: "2026-09-01T09:04:00Z",
+    label: "20 minutes ago",
+  },
+  {
+    id: "3",
+    icon: GitPullRequest,
+    title: "Opened pull request #482",
+    detail: "Add keyboard shortcuts to the command palette",
+    at: "2026-08-31T17:20:00Z",
+    label: "Yesterday",
+  },
+  {
+    id: "4",
+    icon: GitBranch,
+    title: "Created branch feat/shortcuts",
+    detail: "From main",
+    at: "2026-08-31T16:02:00Z",
+    label: "Yesterday",
+  },
+];
+
+export const Default: Story = {
+  render: () => (
+    <ActivityFeed>
+      {EVENTS.map((event, index) => {
+        const Icon = event.icon;
+        return (
+          <ActivityItem key={event.id} last={index === EVENTS.length - 1}>
+            <ActivityIndicator>
+              <Icon />
+            </ActivityIndicator>
+            <ActivityContent>
+              <ActivityTitle>{event.title}</ActivityTitle>
+              <ActivityDescription>{event.detail}</ActivityDescription>
+              <ActivityTime dateTime={event.at}>{event.label}</ActivityTime>
+            </ActivityContent>
+          </ActivityItem>
+        );
+      })}
+    </ActivityFeed>
+  ),
+};
+
+/** Avatars as the rail markers, via asChild. */
+export const WithAvatars: Story = {
+  render: () => (
+    <ActivityFeed>
+      {[
+        {
+          id: "1",
+          who: "AL",
+          title: "Ada Lovelace approved the pull request",
+          at: "2026-09-01T09:12:00Z",
+          label: "12 minutes ago",
+        },
+        {
+          id: "2",
+          who: "GH",
+          title: "Grace Hopper left a comment",
+          at: "2026-09-01T08:40:00Z",
+          label: "44 minutes ago",
+        },
+        {
+          id: "3",
+          who: "KJ",
+          title: "Katherine Johnson requested changes",
+          at: "2026-08-31T18:05:00Z",
+          label: "Yesterday",
+        },
+      ].map((event, index, all) => (
+        <ActivityItem key={event.id} last={index === all.length - 1}>
+          <ActivityIndicator asChild>
+            <Avatar size="xs">
+              <AvatarFallback>{event.who}</AvatarFallback>
+            </Avatar>
+          </ActivityIndicator>
+          <ActivityContent>
+            <ActivityTitle>{event.title}</ActivityTitle>
+            <ActivityTime dateTime={event.at}>{event.label}</ActivityTime>
+          </ActivityContent>
+        </ActivityItem>
+      ))}
+    </ActivityFeed>
+  ),
+};
+
+export const WithStatus: Story = {
+  render: () => (
+    <ActivityFeed>
+      <ActivityItem>
+        <ActivityIndicator className="border-success/40 text-success">
+          <CircleCheck />
+        </ActivityIndicator>
+        <ActivityContent>
+          <ActivityTitle className="flex items-center gap-2">
+            Deployment succeeded
+            <Badge variant="success" size="sm">
+              Live
+            </Badge>
+          </ActivityTitle>
+          <ActivityTime dateTime="2026-09-01T09:12:00Z">12 minutes ago</ActivityTime>
+        </ActivityContent>
+      </ActivityItem>
+      <ActivityItem last>
+        <ActivityIndicator className="border-warning/40 text-warning">
+          <TriangleAlert />
+        </ActivityIndicator>
+        <ActivityContent>
+          <ActivityTitle>Build finished with warnings</ActivityTitle>
+          <ActivityDescription>3 unused exports detected.</ActivityDescription>
+          <ActivityTime dateTime="2026-09-01T09:05:00Z">19 minutes ago</ActivityTime>
+        </ActivityContent>
+      </ActivityItem>
+    </ActivityFeed>
+  ),
+};

package/src/components/activity-feed/activity-feed.test.tsx

@@ -0,0 +1,125 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+
+import { expectNoA11yViolations } from "../../../test/a11y";
+import {
+  ActivityContent,
+  ActivityDescription,
+  ActivityFeed,
+  ActivityIndicator,
+  ActivityItem,
+  ActivityTime,
+  ActivityTitle,
+} from "./activity-feed";
+
+const EVENTS = [
+  { id: "1", title: "Deployed to production", at: "2026-09-01T09:00:00Z" },
+  { id: "2", title: "Opened a pull request", at: "2026-08-31T17:20:00Z" },
+  { id: "3", title: "Created the project", at: "2026-08-30T11:05:00Z" },
+];
+
+function Example() {
+  return (
+    <ActivityFeed>
+      {EVENTS.map((event, index) => (
+        <ActivityItem key={event.id} last={index === EVENTS.length - 1}>
+          <ActivityIndicator>
+            <svg />
+          </ActivityIndicator>
+          <ActivityContent>
+            <ActivityTitle>{event.title}</ActivityTitle>
+            <ActivityTime dateTime={event.at}>Recently</ActivityTime>
+          </ActivityContent>
+        </ActivityItem>
+      ))}
+    </ActivityFeed>
+  );
+}
+
+describe("ActivityFeed", () => {
+  it("renders an ordered list, so position and count are announced", () => {
+    render(<Example />);
+    expect(screen.getByRole("list").tagName).toBe("OL");
+    expect(screen.getAllByRole("listitem")).toHaveLength(3);
+  });
+
+  it("renders each event", () => {
+    render(<Example />);
+    for (const event of EVENTS) {
+      expect(screen.getByText(event.title)).toBeInTheDocument();
+    }
+  });
+
+  it("hides the indicator from assistive technology", () => {
+    const { container } = render(<Example />);
+    for (const indicator of container.querySelectorAll("[data-slot='activity-indicator']")) {
+      expect(indicator).toHaveAttribute("aria-hidden", "true");
+    }
+  });
+
+  it("carries a machine-readable timestamp", () => {
+    const { container } = render(<Example />);
+    const time = container.querySelector("time");
+    expect(time).toHaveAttribute("datetime", "2026-09-01T09:00:00Z");
+  });
+
+  it("marks the last item so no rail is drawn past it", () => {
+    const { container } = render(<Example />);
+    const items = container.querySelectorAll("[data-slot='activity-item']");
+    expect(items[items.length - 1]).toHaveAttribute("data-last", "true");
+    expect(items[0]).not.toHaveAttribute("data-last");
+  });
+
+  it("renders the indicator as another element with asChild", () => {
+    render(
+      <ActivityFeed>
+        <ActivityItem>
+          <ActivityIndicator asChild>
+            <span data-testid="custom">A</span>
+          </ActivityIndicator>
+          <ActivityContent>
+            <ActivityTitle>Event</ActivityTitle>
+          </ActivityContent>
+        </ActivityItem>
+      </ActivityFeed>,
+    );
+    expect(screen.getByTestId("custom")).toHaveAttribute("aria-hidden", "true");
+  });
+
+  it("renders a description when given one", () => {
+    render(
+      <ActivityFeed>
+        <ActivityItem last>
+          <ActivityIndicator />
+          <ActivityContent>
+            <ActivityTitle>Deployed</ActivityTitle>
+            <ActivityDescription>Build 1420 is live.</ActivityDescription>
+          </ActivityContent>
+        </ActivityItem>
+      </ActivityFeed>,
+    );
+    expect(screen.getByText("Build 1420 is live.")).toBeInTheDocument();
+  });
+
+  it("lets a consumer className override a conflicting utility", () => {
+    const { container } = render(
+      <ActivityFeed className="gap-4">
+        <ActivityItem last className="pb-0">
+          <ActivityIndicator />
+          <ActivityContent>
+            <ActivityTitle>Event</ActivityTitle>
+          </ActivityContent>
+        </ActivityItem>
+      </ActivityFeed>,
+    );
+
+    const item = container.querySelector("[data-slot='activity-item']");
+    expect(item).toHaveClass("pb-0");
+    expect(item).not.toHaveClass("pb-6");
+  });
+
+  it("has no accessibility violations", async () => {
+    const { container } = render(<Example />);
+    await expectNoA11yViolations(container);
+  });
+});

package/src/components/activity-feed/activity-feed.tsx

@@ -0,0 +1,115 @@
+import { Slot } from "radix-ui";
+import type { ComponentPropsWithRef } from "react";
+
+import { cn } from "@/lib/utils";
+
+/**
+ * A chronological list of events.
+ *
+ * An ordered list underneath, because the order is the meaning: a screen reader
+ * announces the position and count, and "3 of 12" is information a row of divs
+ * cannot convey. The connecting line is drawn with a pseudo-element rather than
+ * a real node so it never appears in the accessibility tree.
+ */
+export function ActivityFeed({ className, ...props }: ComponentPropsWithRef<"ol">) {
+  return <ol data-slot="activity-feed" className={cn("flex flex-col", className)} {...props} />;
+}
+
+export interface ActivityItemProps extends ComponentPropsWithRef<"li"> {
+  /** Draws no connecting line below. Set this on the last item. */
+  last?: boolean;
+}
+
+export function ActivityItem({ className, last, ...props }: ActivityItemProps) {
+  return (
+    <li
+      data-slot="activity-item"
+      data-last={last || undefined}
+      className={cn(
+        "relative flex gap-3 pb-6 last:pb-0",
+        // The rail is a pseudo-element on the item, so it is decorative by
+        // construction rather than by remembering an aria-hidden.
+        "before:absolute before:top-7 before:bottom-1 before:left-[0.6875rem] before:w-px before:bg-border",
+        "last:before:hidden data-[last]:before:hidden",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+export interface ActivityIndicatorProps extends ComponentPropsWithRef<"div"> {
+  asChild?: boolean;
+}
+
+/** The marker on the rail. Decorative: the item's text says what happened. */
+export function ActivityIndicator({ className, asChild, ...props }: ActivityIndicatorProps) {
+  const Comp = asChild ? Slot.Root : "div";
+
+  return (
+    <Comp
+      data-slot="activity-indicator"
+      aria-hidden="true"
+      className={cn(
+        "relative z-[var(--z-base)] grid size-6 shrink-0 place-items-center rounded-full",
+        "border border-border bg-background text-muted-foreground",
+        "[&_svg:not([class*='size-'])]:size-3",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+export function ActivityContent({ className, ...props }: ComponentPropsWithRef<"div">) {
+  return (
+    <div
+      data-slot="activity-content"
+      className={cn("flex min-w-0 flex-1 flex-col gap-1 pt-0.5", className)}
+      {...props}
+    />
+  );
+}
+
+export function ActivityTitle({ className, ...props }: ComponentPropsWithRef<"p">) {
+  return (
+    <p
+      data-slot="activity-title"
+      className={cn("text-sm leading-snug text-foreground", className)}
+      {...props}
+    />
+  );
+}
+
+export interface ActivityTimeProps extends ComponentPropsWithRef<"time"> {
+  /** Machine-readable timestamp. Required — a relative label alone is ambiguous. */
+  dateTime: string;
+}
+
+/**
+ * When the event happened.
+ *
+ * `dateTime` is required rather than optional: "2 hours ago" is meaningless in
+ * a page read a day later, or by anything parsing the feed, and a `<time>` with
+ * no datetime is just a span.
+ */
+export function ActivityTime({ className, dateTime, ...props }: ActivityTimeProps) {
+  return (
+    <time
+      data-slot="activity-time"
+      dateTime={dateTime}
+      className={cn("text-xs text-muted-foreground", className)}
+      {...props}
+    />
+  );
+}
+
+export function ActivityDescription({ className, ...props }: ComponentPropsWithRef<"div">) {
+  return (
+    <div
+      data-slot="activity-description"
+      className={cn("text-sm text-muted-foreground", className)}
+      {...props}
+    />
+  );
+}

package/src/components/activity-feed/index.ts

@@ -0,0 +1,12 @@
+export {
+  ActivityContent,
+  ActivityDescription,
+  ActivityFeed,
+  ActivityIndicator,
+  ActivityItem,
+  ActivityTime,
+  ActivityTitle,
+  type ActivityIndicatorProps,
+  type ActivityItemProps,
+  type ActivityTimeProps,
+} from "./activity-feed";

package/src/components/activity-feed/meta.ts

@@ -0,0 +1,17 @@
+import { defineMeta } from "@/registry/schema";
+
+export const meta = defineMeta({
+  name: "activity-feed",
+  title: "Activity Feed",
+  description: "A chronological list of events, with a connecting timeline rail.",
+  category: "data",
+  status: "stable",
+  dependencies: ["radix-ui"],
+  registryDependencies: [],
+  files: ["activity-feed.tsx"],
+  a11y:
+    "An ordered list, so position and count are announced — the order is the meaning here. The " +
+    "rail and the indicators are decorative; the item text has to say what happened. " +
+    'ActivityTime requires a machine-readable dateTime, because a relative label like "2 hours ' +
+    'ago" is ambiguous outside the moment it was rendered.',
+});

package/src/components/ai-agent-status/ai-agent-status.stories.tsx

@@ -0,0 +1,86 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+
+import {
+  ActivityContent,
+  ActivityFeed,
+  ActivityIndicator,
+  ActivityItem,
+  ActivityTime,
+  ActivityTitle,
+} from "@/components/activity-feed";
+
+import { AgentStatus } from "./ai-agent-status";
+
+const meta = {
+  title: "AI/Agent Status",
+  component: AgentStatus,
+  args: { state: "working", live: false },
+  argTypes: {
+    state: {
+      control: "select",
+      options: ["idle", "thinking", "working", "waiting", "done", "error"],
+    },
+    live: { control: "boolean" },
+  },
+} satisfies Meta<typeof AgentStatus>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};
+
+/** Every state is a word. Colour never carries it alone. */
+export const States: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex flex-wrap gap-2">
+      {(["idle", "thinking", "working", "waiting", "done", "error"] as const).map((state) => (
+        <AgentStatus key={state} state={state} />
+      ))}
+    </div>
+  ),
+};
+
+export const CustomWording: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex flex-wrap gap-2">
+      <AgentStatus state="working" label="Indexing 412 files" />
+      <AgentStatus state="waiting" label="Needs your approval" />
+      <AgentStatus state="error" label="Rate limited — retrying in 30s" />
+    </div>
+  ),
+};
+
+/** In a fleet view, announcements stay off: six agents narrating is noise. */
+export const AgentFleet: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="w-96">
+      <ActivityFeed>
+        {[
+          {
+            id: "1",
+            name: "Researcher",
+            state: "working" as const,
+            at: "2026-09-01T09:12:00Z",
+          },
+          { id: "2", name: "Writer", state: "waiting" as const, at: "2026-09-01T09:10:00Z" },
+          { id: "3", name: "Reviewer", state: "done" as const, at: "2026-09-01T09:02:00Z" },
+          { id: "4", name: "Publisher", state: "error" as const, at: "2026-09-01T08:58:00Z" },
+        ].map((agent, index, all) => (
+          <ActivityItem key={agent.id} last={index === all.length - 1}>
+            <ActivityIndicator />
+            <ActivityContent>
+              <ActivityTitle className="flex items-center gap-2">
+                {agent.name}
+                <AgentStatus state={agent.state} />
+              </ActivityTitle>
+              <ActivityTime dateTime={agent.at}>Updated recently</ActivityTime>
+            </ActivityContent>
+          </ActivityItem>
+        ))}
+      </ActivityFeed>
+    </div>
+  ),
+};

package/src/components/ai-agent-status/ai-agent-status.test.tsx

@@ -0,0 +1,66 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+
+import { expectNoA11yViolations } from "../../../test/a11y";
+import { AgentStatus, type AgentState } from "./ai-agent-status";
+
+describe("AgentStatus", () => {
+  it.each([
+    ["idle", "Idle"],
+    ["thinking", "Thinking"],
+    ["working", "Working"],
+    ["waiting", "Waiting for input"],
+    ["done", "Done"],
+    ["error", "Error"],
+  ] as [AgentState, string][])("states %s in words", (state, label) => {
+    render(<AgentStatus state={state} />);
+    // Agent states matter most when something has failed — exactly when a
+    // colour-only signal fails the people who most need to notice.
+    expect(screen.getByText(label)).toBeInTheDocument();
+  });
+
+  it("accepts custom wording", () => {
+    render(<AgentStatus state="working" label="Indexing 412 files" />);
+    expect(screen.getByText("Indexing 412 files")).toBeInTheDocument();
+  });
+
+  it("marks the state for styling", () => {
+    const { container } = render(<AgentStatus state="error" />);
+    expect(container.firstElementChild).toHaveAttribute("data-state", "error");
+  });
+
+  it("does not announce by default", () => {
+    // Several agents each announcing their transitions turns a dashboard into
+    // noise.
+    render(<AgentStatus state="working" />);
+    expect(screen.queryByRole("status")).not.toBeInTheDocument();
+  });
+
+  it("announces politely when asked", () => {
+    render(<AgentStatus state="working" live />);
+    const status = screen.getByRole("status");
+    expect(status).toHaveAttribute("aria-live", "polite");
+    expect(status).toHaveTextContent("Working");
+  });
+
+  it("hides its dot from assistive technology", () => {
+    const { container } = render(<AgentStatus state="done" />);
+    expect(container.querySelector("span[aria-hidden='true']")).toBeInTheDocument();
+  });
+
+  it("lets a consumer className override a conflicting utility", () => {
+    const { container } = render(<AgentStatus state="idle" className="text-base" />);
+    expect(container.firstElementChild).toHaveClass("text-base");
+    expect(container.firstElementChild).not.toHaveClass("text-xs");
+  });
+
+  it("has no accessibility violations", async () => {
+    const { container } = render(
+      <div>
+        <AgentStatus state="working" />
+        <AgentStatus state="error" />
+      </div>,
+    );
+    await expectNoA11yViolations(container);
+  });
+});

package/src/components/ai-agent-status/ai-agent-status.tsx

@@ -0,0 +1,88 @@
+"use client";
+
+import { cva, type VariantProps } from "class-variance-authority";
+import type { ComponentPropsWithRef } from "react";
+
+import { cn } from "@/lib/utils";
+
+/**
+ * What an agent is doing right now.
+ *
+ * Always a word, never only a colour. Agent states matter most when something
+ * has gone wrong, which is exactly when a colour-only signal fails the people
+ * who most need to notice.
+ */
+
+export type AgentState = "idle" | "thinking" | "working" | "waiting" | "done" | "error";
+
+const STATE_LABEL: Record<AgentState, string> = {
+  idle: "Idle",
+  thinking: "Thinking",
+  working: "Working",
+  waiting: "Waiting for input",
+  done: "Done",
+  error: "Error",
+};
+
+const agentStatusVariants = cva(
+  "inline-flex items-center gap-1.5 rounded-full border px-2 py-0.5 text-xs font-medium",
+  {
+    variants: {
+      state: {
+        idle: "border-border bg-muted text-muted-foreground",
+        thinking: "border-info/30 bg-info/10 text-info",
+        working: "border-primary/30 bg-primary/10 text-primary",
+        waiting: "border-warning/35 bg-warning/10 text-warning",
+        done: "border-success/30 bg-success/10 text-success",
+        error: "border-destructive/30 bg-destructive/10 text-destructive",
+      },
+    },
+    defaultVariants: {
+      state: "idle",
+    },
+  },
+);
+
+export interface AgentStatusProps
+  extends ComponentPropsWithRef<"span">, VariantProps<typeof agentStatusVariants> {
+  state?: AgentState;
+  /** Overrides the wording. The state must still be readable as text. */
+  label?: string;
+  /**
+   * Announce changes politely.
+   *
+   * Off by default: several agents each announcing their own transitions turns
+   * a dashboard into noise. Turn it on for the one agent the user is watching.
+   */
+  live?: boolean;
+}
+
+export function AgentStatus({
+  className,
+  state = "idle",
+  label,
+  live = false,
+  children,
+  ...props
+}: AgentStatusProps) {
+  const busy = state === "thinking" || state === "working";
+
+  return (
+    <span
+      data-slot="agent-status"
+      data-state={state}
+      role={live ? "status" : undefined}
+      aria-live={live ? "polite" : undefined}
+      className={cn(agentStatusVariants({ state }), className)}
+      {...props}
+    >
+      <span
+        aria-hidden="true"
+        className={cn("size-1.5 rounded-full bg-current", busy && "animate-pulse-soft")}
+      />
+      {children ?? label ?? STATE_LABEL[state]}
+    </span>
+  );
+}
+
+export { agentStatusVariants };

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

@@ -0,0 +1,6 @@
+export {
+  AgentStatus,
+  agentStatusVariants,
+  type AgentState,
+  type AgentStatusProps,
+} from "./ai-agent-status";