@dowel-ui/react 0.1.0

package/src/components/checkbox/checkbox.stories.tsx

@@ -0,0 +1,124 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { useState } from "react";
+
+import { Label } from "@/components/label";
+
+import { Checkbox } from "./checkbox";
+
+const meta = {
+  title: "Forms/Checkbox",
+  component: Checkbox,
+  args: { disabled: false },
+  argTypes: { disabled: { control: "boolean" } },
+} satisfies Meta<typeof Checkbox>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: (args) => (
+    <div className="flex items-center gap-2">
+      <Checkbox id="terms" {...args} />
+      <Label htmlFor="terms">Accept terms and conditions</Label>
+    </div>
+  ),
+};
+
+export const WithDescription: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex items-start gap-2">
+      <Checkbox id="marketing" className="mt-0.5" />
+      <div className="grid gap-1">
+        <Label htmlFor="marketing">Product updates</Label>
+        <p className="text-xs text-muted-foreground">
+          Occasional email about new features. No more than once a month.
+        </p>
+      </div>
+    </div>
+  ),
+};
+
+export const States: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="grid gap-3">
+      {[
+        { id: "s1", label: "Unchecked", checked: false as const },
+        { id: "s2", label: "Checked", checked: true as const },
+        { id: "s3", label: "Indeterminate", checked: "indeterminate" as const },
+      ].map((state) => (
+        <div key={state.id} className="flex items-center gap-2">
+          <Checkbox id={state.id} checked={state.checked} />
+          <Label htmlFor={state.id}>{state.label}</Label>
+        </div>
+      ))}
+      <div className="flex items-center gap-2">
+        <Checkbox id="s4" disabled />
+        <Label htmlFor="s4">Disabled</Label>
+      </div>
+      <div className="flex items-center gap-2">
+        <Checkbox id="s5" disabled checked />
+        <Label htmlFor="s5">Disabled and checked</Label>
+      </div>
+    </div>
+  ),
+};
+
+/** Indeterminate summarises a partial selection; the user never cycles into it. */
+export const SelectAll: Story = {
+  parameters: { controls: { disable: true } },
+  render: function SelectAll() {
+    const items = ["Analytics", "Deployments", "Logs"];
+    const [selected, setSelected] = useState<string[]>(["Analytics"]);
+
+    const all = selected.length === items.length;
+    const some = selected.length > 0 && !all;
+
+    return (
+      <div className="grid gap-3">
+        <div className="flex items-center gap-2">
+          <Checkbox
+            id="all"
+            checked={all ? true : some ? "indeterminate" : false}
+            onCheckedChange={(checked) => {
+              setSelected(checked === true ? items : []);
+            }}
+          />
+          <Label htmlFor="all">Select all</Label>
+        </div>
+        <div className="ml-6 grid gap-3">
+          {items.map((item) => (
+            <div key={item} className="flex items-center gap-2">
+              <Checkbox
+                id={item}
+                checked={selected.includes(item)}
+                onCheckedChange={(checked) => {
+                  setSelected((current) =>
+                    checked ? [...current, item] : current.filter((entry) => entry !== item),
+                  );
+                }}
+              />
+              <Label htmlFor={item}>{item}</Label>
+            </div>
+          ))}
+        </div>
+      </div>
+    );
+  },
+};
+
+export const Invalid: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="grid gap-2">
+      <div className="flex items-center gap-2">
+        <Checkbox id="invalid" aria-invalid aria-describedby="invalid-error" />
+        <Label htmlFor="invalid">Accept terms</Label>
+      </div>
+      <p id="invalid-error" className="text-xs text-destructive">
+        You must accept the terms to continue.
+      </p>
+    </div>
+  ),
+};

package/src/components/checkbox/checkbox.test.tsx

@@ -0,0 +1,121 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { useState } from "react";
+import { describe, expect, it, vi } from "vitest";
+
+import { expectNoA11yViolations } from "../../../test/a11y";
+import { Label } from "../label";
+import { Checkbox } from "./checkbox";
+
+describe("Checkbox", () => {
+  it("renders unchecked by default", () => {
+    render(<Checkbox aria-label="Accept terms" />);
+    expect(screen.getByRole("checkbox", { name: "Accept terms" })).not.toBeChecked();
+  });
+
+  it("takes its accessible name from an associated label", () => {
+    render(
+      <>
+        <Checkbox id="terms" />
+        <Label htmlFor="terms">Accept terms</Label>
+      </>,
+    );
+    expect(screen.getByRole("checkbox", { name: "Accept terms" })).toBeInTheDocument();
+  });
+
+  it("toggles on click", async () => {
+    const user = userEvent.setup();
+    render(<Checkbox aria-label="Accept" />);
+
+    const checkbox = screen.getByRole("checkbox");
+    await user.click(checkbox);
+    expect(checkbox).toBeChecked();
+
+    await user.click(checkbox);
+    expect(checkbox).not.toBeChecked();
+  });
+
+  it("toggles with the Space key", async () => {
+    const user = userEvent.setup();
+    render(<Checkbox aria-label="Accept" />);
+
+    await user.tab();
+    expect(screen.getByRole("checkbox")).toHaveFocus();
+
+    await user.keyboard(" ");
+    expect(screen.getByRole("checkbox")).toBeChecked();
+  });
+
+  it("reports changes", async () => {
+    const onCheckedChange = vi.fn();
+    const user = userEvent.setup();
+    render(<Checkbox aria-label="Accept" onCheckedChange={onCheckedChange} />);
+
+    await user.click(screen.getByRole("checkbox"));
+    expect(onCheckedChange).toHaveBeenCalledWith(true);
+  });
+
+  it("works controlled", async () => {
+    const user = userEvent.setup();
+
+    function Controlled() {
+      const [checked, setChecked] = useState(false);
+      // onCheckedChange yields CheckedState (boolean | "indeterminate"), not a
+      // boolean — indeterminate is a state the application sets, so a boolean
+      // store narrows it here rather than widening the state.
+      return (
+        <Checkbox
+          aria-label="Accept"
+          checked={checked}
+          onCheckedChange={(next) => {
+            setChecked(next === true);
+          }}
+        />
+      );
+    }
+
+    render(<Controlled />);
+    const checkbox = screen.getByRole("checkbox");
+    await user.click(checkbox);
+    expect(checkbox).toBeChecked();
+  });
+
+  it("announces the indeterminate state as mixed", () => {
+    render(<Checkbox aria-label="Select all" checked="indeterminate" />);
+    expect(screen.getByRole("checkbox")).toHaveAttribute("aria-checked", "mixed");
+    expect(screen.getByRole("checkbox")).toHaveAttribute("data-state", "indeterminate");
+  });
+
+  it("does not toggle while disabled", async () => {
+    const onCheckedChange = vi.fn();
+    const user = userEvent.setup();
+    render(<Checkbox aria-label="Accept" disabled onCheckedChange={onCheckedChange} />);
+
+    const checkbox = screen.getByRole("checkbox");
+    expect(checkbox).toBeDisabled();
+    await user.click(checkbox);
+    expect(onCheckedChange).not.toHaveBeenCalled();
+  });
+
+  it("exposes the invalid state", () => {
+    render(<Checkbox aria-label="Accept" aria-invalid />);
+    expect(screen.getByRole("checkbox")).toHaveAttribute("aria-invalid", "true");
+  });
+
+  it("lets a consumer className override a conflicting utility", () => {
+    render(<Checkbox aria-label="Accept" className="size-6" />);
+    const checkbox = screen.getByRole("checkbox");
+    expect(checkbox).toHaveClass("size-6");
+    expect(checkbox).not.toHaveClass("size-4");
+  });
+
+  it("has no accessibility violations", async () => {
+    const { container } = render(
+      <div className="flex items-center gap-2">
+        <Checkbox id="a11y-terms" />
+        <Label htmlFor="a11y-terms">Accept terms</Label>
+      </div>,
+    );
+    await expectNoA11yViolations(container);
+  });
+});

package/src/components/checkbox/checkbox.tsx

@@ -0,0 +1,66 @@
+"use client";
+
+import { Checkbox as CheckboxPrimitive } from "radix-ui";
+import type { ComponentPropsWithRef } from "react";
+
+import { focusRing } from "@/lib/styles";
+import { cn } from "@/lib/utils";
+
+/**
+ * A control for a single on/off choice, or one of several independent choices.
+ *
+ * Supports the indeterminate state (`checked="indeterminate"`) for a parent box
+ * summarising a partially-selected group. Indeterminate is a state the
+ * *application* sets, never a third value the user cycles into.
+ */
+export type CheckboxProps = ComponentPropsWithRef<typeof CheckboxPrimitive.Root>;
+
+export function Checkbox({ className, ...props }: CheckboxProps) {
+  return (
+    <CheckboxPrimitive.Root
+      data-slot="checkbox"
+      className={cn(
+        "peer size-4 shrink-0 rounded-xs border border-input bg-background shadow-xs",
+        "transition-[background-color,border-color,box-shadow] duration-[var(--duration-fast)]",
+        "data-[state=checked]:border-primary data-[state=checked]:bg-primary data-[state=checked]:text-primary-foreground",
+        "data-[state=indeterminate]:border-primary data-[state=indeterminate]:bg-primary data-[state=indeterminate]:text-primary-foreground",
+        "disabled:cursor-not-allowed disabled:opacity-55",
+        "aria-invalid:border-destructive",
+        focusRing,
+        className,
+      )}
+      {...props}
+    >
+      {/* The indicator carries data-state, so both marks live here and CSS picks
+          one. Rendering conditionally in JS would need the checked value, which
+          an uncontrolled checkbox does not expose. */}
+      <CheckboxPrimitive.Indicator
+        data-slot="checkbox-indicator"
+        className="group grid place-items-center text-current"
+      >
+        <svg
+          viewBox="0 0 24 24"
+          fill="none"
+          aria-hidden="true"
+          className="size-3.5 group-data-[state=indeterminate]:hidden"
+        >
+          <path
+            d="m5 13 4 4L19 7"
+            stroke="currentColor"
+            strokeWidth="3"
+            strokeLinecap="round"
+            strokeLinejoin="round"
+          />
+        </svg>
+        <svg
+          viewBox="0 0 24 24"
+          fill="none"
+          aria-hidden="true"
+          className="hidden size-3.5 group-data-[state=indeterminate]:block"
+        >
+          <path d="M6 12h12" stroke="currentColor" strokeWidth="3" strokeLinecap="round" />
+        </svg>
+      </CheckboxPrimitive.Indicator>
+    </CheckboxPrimitive.Root>
+  );
+}

package/src/components/checkbox/index.ts

@@ -0,0 +1 @@
+export { Checkbox, type CheckboxProps } from "./checkbox";

package/src/components/checkbox/meta.ts

@@ -0,0 +1,16 @@
+import { defineMeta } from "@/registry/schema";
+
+export const meta = defineMeta({
+  name: "checkbox",
+  title: "Checkbox",
+  description: "A control for an on/off choice, with support for an indeterminate state.",
+  category: "form",
+  status: "stable",
+  dependencies: ["radix-ui"],
+  registryDependencies: [],
+  files: ["checkbox.tsx"],
+  a11y:
+    "Toggles with Space, matching the native control. Always pair with a Label via htmlFor/id — " +
+    'the box alone has no accessible name. Indeterminate is announced as "mixed" and is a ' +
+    "state the application sets, not one the user can reach by clicking.",
+});

package/src/components/code-block/code-block.stories.tsx

@@ -0,0 +1,62 @@
+import type { Decorator, Meta, StoryObj } from "@storybook/react-vite";
+
+import { CodeBlock } from "./code-block";
+
+/** Named so its type is nameable in declaration output (TS2883). */
+const withFixedWidth: Decorator = (Story) => (
+  <div className="w-[34rem]">
+    <Story />
+  </div>
+);
+
+const SAMPLE = `export function cn(...inputs: ClassValue[]): string {
+  return twMerge(clsx(inputs));
+}`;
+
+const meta = {
+  title: "Data/Code Block",
+  component: CodeBlock,
+  args: { language: "ts", children: SAMPLE },
+  decorators: [withFixedWidth],
+} satisfies Meta<typeof CodeBlock>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};
+
+export const WithFilename: Story = {
+  args: { title: "lib/utils.ts" },
+};
+
+export const WithoutCopy: Story = {
+  args: { hideCopy: true },
+};
+
+/** Overflowing code: the pre is focusable, so it can be scrolled by keyboard. */
+export const Overflowing: Story = {
+  args: {
+    title: "one-liner.ts",
+    children:
+      'const message = "a single very long line that runs well past the edge of the container and keeps going for a while yet";',
+  },
+};
+
+/**
+ * Highlighting is left to the application. Pass rendered markup as children and
+ * the real text as `code`, since reading text back out of highlighted DOM loses
+ * whitespace in ways that break pasted code.
+ */
+export const PreHighlighted: Story = {
+  args: {
+    title: "highlighted.ts",
+    code: 'const answer = "Paris";',
+    children: (
+      <>
+        <span className="text-info">const</span> answer{" "}
+        <span className="text-muted-foreground">=</span>{" "}
+        <span className="text-success">&quot;Paris&quot;</span>;
+      </>
+    ),
+  },
+};

package/src/components/code-block/code-block.test.tsx

@@ -0,0 +1,139 @@
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { expectNoA11yViolations } from "../../../test/a11y";
+import { CodeBlock } from "./code-block";
+
+const SAMPLE = 'const answer = "Paris";';
+
+/**
+ * Replaces the clipboard.
+ *
+ * Must be called *after* `userEvent.setup()`, which installs a clipboard stub
+ * of its own — applying ours first means testing theirs.
+ */
+function mockClipboard(impl: () => Promise<void>) {
+  const writeText = vi.fn(impl);
+  Object.defineProperty(navigator, "clipboard", {
+    value: { writeText },
+    configurable: true,
+  });
+  return writeText;
+}
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe("CodeBlock", () => {
+  it("renders the code", () => {
+    render(<CodeBlock language="ts">{SAMPLE}</CodeBlock>);
+    expect(screen.getByText(SAMPLE)).toBeInTheDocument();
+  });
+
+  it("shows the language in the header", () => {
+    render(<CodeBlock language="typescript">{SAMPLE}</CodeBlock>);
+    expect(screen.getByText("typescript")).toBeInTheDocument();
+  });
+
+  it("prefers a title over the language", () => {
+    render(
+      <CodeBlock language="ts" title="button.tsx">
+        {SAMPLE}
+      </CodeBlock>,
+    );
+    expect(screen.getByText("button.tsx")).toBeInTheDocument();
+    expect(screen.queryByText("ts")).not.toBeInTheDocument();
+  });
+
+  it("is a focusable named region, since code scrolls sideways", () => {
+    render(<CodeBlock language="ts">{SAMPLE}</CodeBlock>);
+
+    const region = screen.getByRole("region", { name: "ts code" });
+    expect(region).toHaveAttribute("tabindex", "0");
+  });
+
+  it("names the region after the title when there is one", () => {
+    render(<CodeBlock title="button.tsx">{SAMPLE}</CodeBlock>);
+    expect(screen.getByRole("region", { name: "button.tsx" })).toBeInTheDocument();
+  });
+
+  it("renders markup a highlighter has already produced", () => {
+    render(
+      <CodeBlock language="ts" code={SAMPLE}>
+        <span className="token">const</span>
+        <span> answer</span>
+      </CodeBlock>,
+    );
+    expect(screen.getByText("const")).toBeInTheDocument();
+  });
+
+  describe("copying", () => {
+    it("copies the text content", async () => {
+      const user = userEvent.setup();
+      const writeText = mockClipboard(() => Promise.resolve());
+      render(<CodeBlock language="ts">{SAMPLE}</CodeBlock>);
+
+      await user.click(screen.getByRole("button", { name: "Copy code" }));
+      expect(writeText).toHaveBeenCalledWith(SAMPLE);
+    });
+
+    it("prefers the explicit code prop over reading the DOM", async () => {
+      const user = userEvent.setup();
+      const writeText = mockClipboard(() => Promise.resolve());
+      render(
+        <CodeBlock language="ts" code={SAMPLE}>
+          <span>const</span>
+          <span> answer</span>
+        </CodeBlock>,
+      );
+
+      // Reading highlighted DOM back loses whitespace in ways that break pasted
+      // code, which is why `code` exists.
+      await user.click(screen.getByRole("button", { name: "Copy code" }));
+      expect(writeText).toHaveBeenCalledWith(SAMPLE);
+    });
+
+    it("announces success, not just draws a tick", async () => {
+      const user = userEvent.setup();
+      mockClipboard(() => Promise.resolve());
+      render(<CodeBlock language="ts">{SAMPLE}</CodeBlock>);
+
+      await user.click(screen.getByRole("button", { name: "Copy code" }));
+      await waitFor(() => {
+        expect(screen.getByRole("status")).toHaveTextContent("Copied");
+      });
+    });
+
+    it("reports a refused clipboard rather than looking like success", async () => {
+      const user = userEvent.setup();
+      mockClipboard(() => Promise.reject(new Error("denied")));
+      render(<CodeBlock language="ts">{SAMPLE}</CodeBlock>);
+
+      await user.click(screen.getByRole("button", { name: "Copy code" }));
+      await waitFor(() => {
+        expect(screen.getByRole("status")).toHaveTextContent("Copy failed");
+      });
+    });
+
+    it("can be hidden", () => {
+      render(
+        <CodeBlock language="ts" hideCopy>
+          {SAMPLE}
+        </CodeBlock>,
+      );
+      expect(screen.queryByRole("button", { name: "Copy code" })).not.toBeInTheDocument();
+    });
+  });
+
+  it("has no accessibility violations", async () => {
+    mockClipboard(() => Promise.resolve());
+    const { container } = render(
+      <CodeBlock language="ts" title="answer.ts">
+        {SAMPLE}
+      </CodeBlock>,
+    );
+    await expectNoA11yViolations(container);
+  });
+});