@dowel-ui/react 0.1.0

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

@@ -0,0 +1,17 @@
+import { defineMeta } from "@/registry/schema";
+
+export const meta = defineMeta({
+  name: "ai-tool",
+  title: "AI Tool Call",
+  description: "A collapsible record of a tool the model called, its arguments and its result.",
+  category: "ai",
+  status: "stable",
+  dependencies: ["class-variance-authority", "radix-ui"],
+  registryDependencies: [],
+  files: ["ai-tool.tsx"],
+  a11y:
+    "A disclosure: the trigger exposes aria-expanded and controls the panel. Status is stated in " +
+    "words, not by a coloured dot — colour alone is unavailable to a screen reader and to anyone " +
+    "who cannot distinguish it. Payload blocks are focusable named regions, since JSON scrolls " +
+    "and an unfocusable scroll box is unreachable by keyboard.",
+});

package/src/components/alert/alert.stories.tsx

@@ -0,0 +1,101 @@
+import type { Decorator, Meta, StoryObj } from "@storybook/react-vite";
+import { CircleAlert, CircleCheck, Info, TriangleAlert } from "lucide-react";
+
+import { Alert, AlertDescription, AlertTitle } from "./alert";
+
+/** Named so its type is nameable in declaration output (TS2883). */
+const withFixedWidth: Decorator = (Story) => (
+  <div className="w-96">
+    <Story />
+  </div>
+);
+
+const meta = {
+  title: "Feedback/Alert",
+  component: Alert,
+  args: { variant: "default", live: "off" },
+  argTypes: {
+    variant: {
+      control: "select",
+      options: ["default", "destructive", "success", "warning", "info"],
+    },
+    live: { control: "select", options: ["off", "polite", "assertive"] },
+  },
+  decorators: [withFixedWidth],
+} satisfies Meta<typeof Alert>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: (args) => (
+    <Alert {...args}>
+      <Info />
+      <AlertTitle>Heads up</AlertTitle>
+      <AlertDescription>Your trial ends in 3 days.</AlertDescription>
+    </Alert>
+  ),
+};
+
+export const Variants: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="space-y-3">
+      <Alert>
+        <Info />
+        <AlertTitle>Heads up</AlertTitle>
+        <AlertDescription>Your trial ends in 3 days.</AlertDescription>
+      </Alert>
+      <Alert variant="success">
+        <CircleCheck />
+        <AlertTitle>Deployment succeeded</AlertTitle>
+        <AlertDescription>Build 1420 is live in production.</AlertDescription>
+      </Alert>
+      <Alert variant="warning">
+        <TriangleAlert />
+        <AlertTitle>Approaching your quota</AlertTitle>
+        <AlertDescription>You have used 92% of your monthly builds.</AlertDescription>
+      </Alert>
+      <Alert variant="destructive">
+        <CircleAlert />
+        <AlertTitle>Payment failed</AlertTitle>
+        <AlertDescription>Update your card to keep your workspace active.</AlertDescription>
+      </Alert>
+    </div>
+  ),
+};
+
+export const WithoutIcon: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <Alert>
+      <AlertTitle>Scheduled maintenance</AlertTitle>
+      <AlertDescription>Deployments pause on Sunday from 02:00 to 04:00 UTC.</AlertDescription>
+    </Alert>
+  ),
+};
+
+export const TitleOnly: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <Alert variant="info">
+      <Info />
+      <AlertTitle>Two-factor authentication is now required.</AlertTitle>
+    </Alert>
+  ),
+};
+
+/**
+ * An alert that appears in response to a user action should announce itself.
+ * The default `live="off"` avoids announcing notices that were already on screen.
+ */
+export const LiveRegion: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <Alert live="assertive" variant="destructive">
+      <CircleAlert />
+      <AlertTitle>Could not save changes</AlertTitle>
+      <AlertDescription>Check your connection and try again.</AlertDescription>
+    </Alert>
+  ),
+};

package/src/components/alert/alert.test.tsx

@@ -0,0 +1,94 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+
+import { expectNoA11yViolations } from "../../../test/a11y";
+import { Alert, AlertDescription, AlertTitle } from "./alert";
+
+describe("Alert", () => {
+  it("renders its title and description", () => {
+    render(
+      <Alert>
+        <AlertTitle>Heads up</AlertTitle>
+        <AlertDescription>Your trial ends in 3 days.</AlertDescription>
+      </Alert>,
+    );
+
+    expect(screen.getByText("Heads up")).toBeInTheDocument();
+    expect(screen.getByText("Your trial ends in 3 days.")).toBeInTheDocument();
+  });
+
+  it("is not a live region by default", () => {
+    render(
+      <Alert data-testid="alert">
+        <AlertTitle>Heads up</AlertTitle>
+      </Alert>,
+    );
+
+    const alert = screen.getByTestId("alert");
+    expect(alert).not.toHaveAttribute("role");
+    expect(alert).not.toHaveAttribute("aria-live");
+    expect(screen.queryByRole("alert")).not.toBeInTheDocument();
+  });
+
+  it("becomes a polite status region when live is polite", () => {
+    render(
+      <Alert live="polite">
+        <AlertTitle>Saved</AlertTitle>
+      </Alert>,
+    );
+
+    const alert = screen.getByRole("status");
+    expect(alert).toHaveAttribute("aria-live", "polite");
+  });
+
+  it("becomes an assertive alert region when live is assertive", () => {
+    render(
+      <Alert live="assertive" variant="destructive">
+        <AlertTitle>Payment failed</AlertTitle>
+      </Alert>,
+    );
+
+    const alert = screen.getByRole("alert");
+    expect(alert).toHaveAttribute("aria-live", "assertive");
+  });
+
+  it.each([
+    ["default", "bg-card"],
+    ["destructive", "bg-destructive/8"],
+    ["success", "bg-success/8"],
+    ["warning", "bg-warning/10"],
+    ["info", "bg-info/8"],
+  ] as const)("applies the %s variant", (variant, expectedClass) => {
+    render(
+      <Alert variant={variant} data-testid="alert">
+        <AlertTitle>Title</AlertTitle>
+      </Alert>,
+    );
+    expect(screen.getByTestId("alert")).toHaveClass(expectedClass);
+  });
+
+  it("merges a consumer className", () => {
+    render(
+      <Alert className="mt-8" data-testid="alert">
+        <AlertTitle>Title</AlertTitle>
+      </Alert>,
+    );
+    expect(screen.getByTestId("alert")).toHaveClass("mt-8");
+  });
+
+  it("has no accessibility violations", async () => {
+    const { container } = render(
+      <>
+        <Alert>
+          <AlertTitle>Heads up</AlertTitle>
+          <AlertDescription>Your trial ends in 3 days.</AlertDescription>
+        </Alert>
+        <Alert live="assertive" variant="destructive">
+          <AlertTitle>Payment failed</AlertTitle>
+          <AlertDescription>Update your card to continue.</AlertDescription>
+        </Alert>
+      </>,
+    );
+    await expectNoA11yViolations(container);
+  });
+});

package/src/components/alert/alert.tsx

@@ -0,0 +1,89 @@
+import { cva, type VariantProps } from "class-variance-authority";
+import type { ComponentPropsWithRef } from "react";
+
+import { cn } from "@/lib/utils";
+
+const alertVariants = cva(
+  cn(
+    "relative grid w-full grid-cols-[0_1fr] items-start gap-y-1 rounded-lg border px-4 py-3 text-sm",
+    "has-[>svg]:grid-cols-[calc(var(--size-icon-md))_1fr] has-[>svg]:gap-x-3",
+    "[&>svg]:size-4 [&>svg]:translate-y-0.5 [&>svg]:text-current",
+  ),
+  {
+    variants: {
+      variant: {
+        default: "border-border bg-card text-card-foreground",
+        destructive:
+          "border-destructive/30 bg-destructive/8 text-foreground [&>svg]:text-destructive",
+        success: "border-success/30 bg-success/8 text-foreground [&>svg]:text-success",
+        warning: "border-warning/35 bg-warning/10 text-foreground [&>svg]:text-warning",
+        info: "border-info/30 bg-info/8 text-foreground [&>svg]:text-info",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+    },
+  },
+);
+
+/**
+ * How urgently the alert should interrupt a screen reader.
+ *
+ * - `off` (default): a static notice already present when the page rendered.
+ * - `polite`: appeared in response to something the user did; announce at the
+ *   next pause.
+ * - `assertive`: an error that must interrupt whatever is being read.
+ */
+export type AlertLive = "off" | "polite" | "assertive";
+
+export interface AlertProps
+  extends ComponentPropsWithRef<"div">, VariantProps<typeof alertVariants> {
+  live?: AlertLive;
+}
+
+/**
+ * A callout that draws attention to a message.
+ *
+ * `live` defaults to `off` rather than always rendering role="alert". A live
+ * region that exists on first paint announces itself for no reason and trains
+ * users to ignore it; opt in when the alert actually appears in response to
+ * something.
+ */
+export function Alert({ className, variant, live = "off", ...props }: AlertProps) {
+  const role = live === "assertive" ? "alert" : live === "polite" ? "status" : undefined;
+
+  return (
+    <div
+      data-slot="alert"
+      role={role}
+      aria-live={live === "off" ? undefined : live}
+      className={cn(alertVariants({ variant }), className)}
+      {...props}
+    />
+  );
+}
+
+export function AlertTitle({ className, ...props }: ComponentPropsWithRef<"div">) {
+  return (
+    <div
+      data-slot="alert-title"
+      className={cn("col-start-2 font-medium tracking-tight", className)}
+      {...props}
+    />
+  );
+}
+
+export function AlertDescription({ className, ...props }: ComponentPropsWithRef<"div">) {
+  return (
+    <div
+      data-slot="alert-description"
+      className={cn(
+        "col-start-2 text-sm text-muted-foreground [&_p]:leading-relaxed",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+export { alertVariants };

package/src/components/alert/index.ts

@@ -0,0 +1,8 @@
+export {
+  Alert,
+  AlertDescription,
+  AlertTitle,
+  alertVariants,
+  type AlertLive,
+  type AlertProps,
+} from "./alert";

package/src/components/alert/meta.ts

@@ -0,0 +1,16 @@
+import { defineMeta } from "@/registry/schema";
+
+export const meta = defineMeta({
+  name: "alert",
+  title: "Alert",
+  description: "A callout that draws attention to an important message.",
+  category: "feedback",
+  status: "stable",
+  dependencies: ["class-variance-authority"],
+  registryDependencies: [],
+  files: ["alert.tsx"],
+  a11y:
+    'Not a live region by default. Pass live="polite" for alerts that appear in response to ' +
+    'a user action, or live="assertive" for errors that must interrupt. Variant colour is ' +
+    "never the only signal — the title carries the meaning.",
+});

package/src/components/avatar/avatar.stories.tsx

@@ -0,0 +1,58 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+
+import { Avatar, AvatarFallback, AvatarImage } from "./avatar";
+
+const meta = {
+  title: "Display/Avatar",
+  component: Avatar,
+  args: { size: "md" },
+  argTypes: { size: { control: "select", options: ["xs", "sm", "md", "lg", "xl"] } },
+} satisfies Meta<typeof Avatar>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: (args) => (
+    <Avatar {...args}>
+      <AvatarImage src="https://i.pravatar.cc/128?img=12" alt="Ada Lovelace" />
+      <AvatarFallback>AL</AvatarFallback>
+    </Avatar>
+  ),
+};
+
+/** The fallback is what renders when the image is missing, slow or broken. */
+export const Fallback: Story = {
+  render: (args) => (
+    <Avatar {...args}>
+      <AvatarImage src="/does-not-exist.png" alt="Grace Hopper" />
+      <AvatarFallback>GH</AvatarFallback>
+    </Avatar>
+  ),
+};
+
+export const Sizes: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex items-center gap-3">
+      {(["xs", "sm", "md", "lg", "xl"] as const).map((size) => (
+        <Avatar key={size} size={size}>
+          <AvatarFallback>AL</AvatarFallback>
+        </Avatar>
+      ))}
+    </div>
+  ),
+};
+
+export const Group: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex -space-x-2">
+      {["AL", "GH", "KJ", "RM"].map((initials) => (
+        <Avatar key={initials} size="sm" className="ring-2 ring-background">
+          <AvatarFallback>{initials}</AvatarFallback>
+        </Avatar>
+      ))}
+    </div>
+  ),
+};

package/src/components/avatar/avatar.test.tsx

@@ -0,0 +1,64 @@
+import { render, screen, waitFor } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+
+import { expectNoA11yViolations } from "../../../test/a11y";
+import { Avatar, AvatarFallback, AvatarImage } from "./avatar";
+
+describe("Avatar", () => {
+  it("shows the fallback while the image has not loaded", async () => {
+    render(
+      <Avatar>
+        <AvatarImage src="/nope.png" alt="Ada Lovelace" />
+        <AvatarFallback>AL</AvatarFallback>
+      </Avatar>,
+    );
+
+    await waitFor(() => {
+      expect(screen.getByText("AL")).toBeInTheDocument();
+    });
+  });
+
+  it("renders the fallback alone when there is no image", () => {
+    render(
+      <Avatar>
+        <AvatarFallback>AL</AvatarFallback>
+      </Avatar>,
+    );
+    expect(screen.getByText("AL")).toBeInTheDocument();
+  });
+
+  it.each([
+    ["xs", "size-6"],
+    ["sm", "size-8"],
+    ["md", "size-10"],
+    ["lg", "size-12"],
+    ["xl", "size-16"],
+  ] as const)("applies the %s size", (size, expectedClass) => {
+    render(
+      <Avatar size={size} data-testid="avatar">
+        <AvatarFallback>AL</AvatarFallback>
+      </Avatar>,
+    );
+    expect(screen.getByTestId("avatar")).toHaveClass(expectedClass);
+  });
+
+  it("lets a consumer className override the size", () => {
+    render(
+      <Avatar className="size-24" data-testid="avatar">
+        <AvatarFallback>AL</AvatarFallback>
+      </Avatar>,
+    );
+    const avatar = screen.getByTestId("avatar");
+    expect(avatar).toHaveClass("size-24");
+    expect(avatar).not.toHaveClass("size-10");
+  });
+
+  it("has no accessibility violations", async () => {
+    const { container } = render(
+      <Avatar>
+        <AvatarFallback>AL</AvatarFallback>
+      </Avatar>,
+    );
+    await expectNoA11yViolations(container);
+  });
+});

package/src/components/avatar/avatar.tsx

@@ -0,0 +1,68 @@
+import { cva, type VariantProps } from "class-variance-authority";
+import { Avatar as AvatarPrimitive } from "radix-ui";
+import type { ComponentPropsWithRef } from "react";
+
+import { cn } from "@/lib/utils";
+
+const avatarVariants = cva(
+  "relative flex shrink-0 overflow-hidden rounded-full bg-muted select-none",
+  {
+    variants: {
+      size: {
+        xs: "size-6 text-2xs",
+        sm: "size-8 text-xs",
+        md: "size-10 text-sm",
+        lg: "size-12 text-base",
+        xl: "size-16 text-lg",
+      },
+    },
+    defaultVariants: {
+      size: "md",
+    },
+  },
+);
+
+export interface AvatarProps
+  extends
+    ComponentPropsWithRef<typeof AvatarPrimitive.Root>,
+    VariantProps<typeof avatarVariants> {}
+
+/** Image representation of a user or entity, with a text fallback. */
+export function Avatar({ className, size, ...props }: AvatarProps) {
+  return (
+    <AvatarPrimitive.Root className={cn(avatarVariants({ size }), className)} {...props} />
+  );
+}
+
+export type AvatarImageProps = ComponentPropsWithRef<typeof AvatarPrimitive.Image>;
+
+export function AvatarImage({ className, ...props }: AvatarImageProps) {
+  return (
+    <AvatarPrimitive.Image
+      className={cn("aspect-square size-full object-cover", className)}
+      {...props}
+    />
+  );
+}
+
+export type AvatarFallbackProps = ComponentPropsWithRef<typeof AvatarPrimitive.Fallback>;
+
+/**
+ * Shown while the image loads and if it fails.
+ *
+ * Radix only renders this once the image has actually errored or is still
+ * pending, so there is never a flash of initials over a cached image.
+ */
+export function AvatarFallback({ className, ...props }: AvatarFallbackProps) {
+  return (
+    <AvatarPrimitive.Fallback
+      className={cn(
+        "flex size-full items-center justify-center bg-muted font-medium text-muted-foreground",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+export { avatarVariants };

package/src/components/avatar/index.ts

@@ -0,0 +1,9 @@
+export {
+  Avatar,
+  AvatarFallback,
+  AvatarImage,
+  avatarVariants,
+  type AvatarFallbackProps,
+  type AvatarImageProps,
+  type AvatarProps,
+} from "./avatar";

package/src/components/avatar/meta.ts

@@ -0,0 +1,15 @@
+import { defineMeta } from "@/registry/schema";
+
+export const meta = defineMeta({
+  name: "avatar",
+  title: "Avatar",
+  description: "An image representation of a user or entity with a graceful text fallback.",
+  category: "display",
+  status: "stable",
+  dependencies: ["class-variance-authority", "radix-ui"],
+  registryDependencies: [],
+  files: ["avatar.tsx"],
+  a11y:
+    'Give AvatarImage a meaningful alt, or alt="" when the adjacent text already names the ' +
+    "person. Fallback initials are decorative and are not announced separately.",
+});

package/src/components/badge/badge.stories.tsx

@@ -0,0 +1,68 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { Check } from "lucide-react";
+
+import { Badge } from "./badge";
+
+const meta = {
+  title: "Display/Badge",
+  component: Badge,
+  args: { children: "Active", variant: "default", size: "md" },
+  argTypes: {
+    variant: {
+      control: "select",
+      options: ["default", "secondary", "outline", "destructive", "success", "warning", "info"],
+    },
+    size: { control: "select", options: ["sm", "md"] },
+    asChild: { table: { disable: true } },
+  },
+} satisfies Meta<typeof Badge>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};
+
+export const Variants: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex flex-wrap items-center gap-2">
+      <Badge>Default</Badge>
+      <Badge variant="secondary">Secondary</Badge>
+      <Badge variant="outline">Outline</Badge>
+      <Badge variant="destructive">Failed</Badge>
+      <Badge variant="success">Deployed</Badge>
+      <Badge variant="warning">Degraded</Badge>
+      <Badge variant="info">Queued</Badge>
+    </div>
+  ),
+};
+
+export const Sizes: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex items-center gap-2">
+      <Badge size="sm">Small</Badge>
+      <Badge size="md">Medium</Badge>
+    </div>
+  ),
+};
+
+export const WithIcon: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <Badge variant="success">
+      <Check />
+      Verified
+    </Badge>
+  ),
+};
+
+export const AsLink: Story = {
+  name: "asChild (renders a link)",
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <Badge asChild variant="outline">
+      <a href="#status">View status</a>
+    </Badge>
+  ),
+};

package/src/components/badge/badge.test.tsx

@@ -0,0 +1,61 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+
+import { expectNoA11yViolations } from "../../../test/a11y";
+import { Badge } from "./badge";
+
+describe("Badge", () => {
+  it("renders its label", () => {
+    render(<Badge>Active</Badge>);
+    expect(screen.getByText("Active")).toBeInTheDocument();
+  });
+
+  it.each([
+    ["default", "bg-primary"],
+    ["secondary", "bg-secondary"],
+    ["outline", "border-border-strong"],
+    ["destructive", "bg-destructive"],
+    ["success", "bg-success"],
+    ["warning", "bg-warning"],
+    ["info", "bg-info"],
+  ] as const)("applies the %s variant", (variant, expectedClass) => {
+    render(<Badge variant={variant}>Label</Badge>);
+    expect(screen.getByText("Label")).toHaveClass(expectedClass);
+  });
+
+  it.each([
+    ["sm", "h-5"],
+    ["md", "h-6"],
+  ] as const)("applies the %s size", (size, expectedClass) => {
+    render(<Badge size={size}>Label</Badge>);
+    expect(screen.getByText("Label")).toHaveClass(expectedClass);
+  });
+
+  it("lets a consumer className override a conflicting utility", () => {
+    render(<Badge className="bg-card">Label</Badge>);
+    const badge = screen.getByText("Label");
+    expect(badge).toHaveClass("bg-card");
+    expect(badge).not.toHaveClass("bg-primary");
+  });
+
+  it("renders as a link when asChild is set", () => {
+    render(
+      <Badge asChild>
+        <a href="/status">Active</a>
+      </Badge>,
+    );
+    const link = screen.getByRole("link", { name: "Active" });
+    expect(link).toHaveAttribute("href", "/status");
+    expect(link).toHaveClass("bg-primary");
+  });
+
+  it("has no accessibility violations", async () => {
+    const { container } = render(
+      <>
+        <Badge>Active</Badge>
+        <Badge variant="destructive">Failed</Badge>
+      </>,
+    );
+    await expectNoA11yViolations(container);
+  });
+});