@dowel-ui/react 0.1.0

package/src/components/empty-state/empty-state.test.tsx

@@ -0,0 +1,97 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+
+import { expectNoA11yViolations } from "../../../test/a11y";
+import { Button } from "../button";
+import {
+  EmptyState,
+  EmptyStateActions,
+  EmptyStateDescription,
+  EmptyStateIcon,
+  EmptyStateTitle,
+} from "./empty-state";
+
+describe("EmptyState", () => {
+  it("renders its parts", () => {
+    render(
+      <EmptyState>
+        <EmptyStateIcon>
+          <svg />
+        </EmptyStateIcon>
+        <EmptyStateTitle>No projects yet</EmptyStateTitle>
+        <EmptyStateDescription>Create one to get started.</EmptyStateDescription>
+        <EmptyStateActions>
+          <Button>New project</Button>
+        </EmptyStateActions>
+      </EmptyState>,
+    );
+
+    expect(screen.getByText("No projects yet")).toBeInTheDocument();
+    expect(screen.getByText("Create one to get started.")).toBeInTheDocument();
+    expect(screen.getByRole("button", { name: "New project" })).toBeInTheDocument();
+  });
+
+  it("hides the icon from assistive technology", () => {
+    const { container } = render(
+      <EmptyState>
+        <EmptyStateIcon>
+          <svg />
+        </EmptyStateIcon>
+        <EmptyStateTitle>Nothing here</EmptyStateTitle>
+      </EmptyState>,
+    );
+
+    expect(container.querySelector("[data-slot='empty-state-icon']")).toHaveAttribute(
+      "aria-hidden",
+      "true",
+    );
+  });
+
+  it.each([
+    ["sm", "py-8"],
+    ["md", "py-12"],
+    ["lg", "py-20"],
+  ] as const)("applies the %s size", (size, expectedClass) => {
+    const { container } = render(
+      <EmptyState size={size}>
+        <EmptyStateTitle>Nothing</EmptyStateTitle>
+      </EmptyState>,
+    );
+    expect(container.firstElementChild).toHaveClass(expectedClass);
+  });
+
+  it("can render a dashed border", () => {
+    const { container } = render(
+      <EmptyState bordered>
+        <EmptyStateTitle>Nothing</EmptyStateTitle>
+      </EmptyState>,
+    );
+    expect(container.firstElementChild).toHaveClass("border-dashed");
+  });
+
+  it("lets a consumer className override a conflicting utility", () => {
+    const { container } = render(
+      <EmptyState className="py-2">
+        <EmptyStateTitle>Nothing</EmptyStateTitle>
+      </EmptyState>,
+    );
+    expect(container.firstElementChild).toHaveClass("py-2");
+    expect(container.firstElementChild).not.toHaveClass("py-12");
+  });
+
+  it("has no accessibility violations", async () => {
+    const { container } = render(
+      <EmptyState bordered>
+        <EmptyStateIcon>
+          <svg />
+        </EmptyStateIcon>
+        <EmptyStateTitle>No results</EmptyStateTitle>
+        <EmptyStateDescription>Try a different search.</EmptyStateDescription>
+        <EmptyStateActions>
+          <Button variant="outline">Clear filters</Button>
+        </EmptyStateActions>
+      </EmptyState>,
+    );
+    await expectNoA11yViolations(container);
+  });
+});

package/src/components/empty-state/empty-state.tsx

@@ -0,0 +1,92 @@
+import { cva, type VariantProps } from "class-variance-authority";
+import type { ComponentPropsWithRef } from "react";
+
+import { cn } from "@/lib/utils";
+
+const emptyStateVariants = cva("flex flex-col items-center justify-center gap-3 text-center", {
+  variants: {
+    size: {
+      sm: "px-4 py-8",
+      md: "px-6 py-12",
+      lg: "px-8 py-20",
+    },
+    bordered: {
+      true: "rounded-xl border border-dashed border-border",
+      false: "",
+    },
+  },
+  defaultVariants: {
+    size: "md",
+    bordered: false,
+  },
+});
+
+export interface EmptyStateProps
+  extends ComponentPropsWithRef<"div">, VariantProps<typeof emptyStateVariants> {}
+
+/**
+ * Shown where content would be, when there is none.
+ *
+ * An empty state should say why it is empty and what to do next. "No results"
+ * after a search and "nothing here yet" on a new account are different
+ * messages, and the second one is where a call to action belongs.
+ */
+export function EmptyState({ className, size, bordered, ...props }: EmptyStateProps) {
+  return (
+    <div
+      data-slot="empty-state"
+      className={cn(emptyStateVariants({ size, bordered }), className)}
+      {...props}
+    />
+  );
+}
+
+/** Decorative by default — the title carries the meaning. */
+export function EmptyStateIcon({ className, ...props }: ComponentPropsWithRef<"div">) {
+  return (
+    <div
+      data-slot="empty-state-icon"
+      aria-hidden="true"
+      className={cn(
+        "grid size-11 place-items-center rounded-full bg-muted text-muted-foreground",
+        "[&_svg:not([class*='size-'])]:size-5",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+export function EmptyStateTitle({ className, children, ...props }: ComponentPropsWithRef<"p">) {
+  return (
+    <p
+      data-slot="empty-state-title"
+      className={cn("text-base font-medium text-foreground", className)}
+      {...props}
+    >
+      {children}
+    </p>
+  );
+}
+
+export function EmptyStateDescription({ className, ...props }: ComponentPropsWithRef<"p">) {
+  return (
+    <p
+      data-slot="empty-state-description"
+      className={cn("max-w-sm text-sm text-balance text-muted-foreground", className)}
+      {...props}
+    />
+  );
+}
+
+export function EmptyStateActions({ className, ...props }: ComponentPropsWithRef<"div">) {
+  return (
+    <div
+      data-slot="empty-state-actions"
+      className={cn("mt-1 flex flex-wrap items-center justify-center gap-2", className)}
+      {...props}
+    />
+  );
+}
+
+export { emptyStateVariants };

package/src/components/empty-state/index.ts

@@ -0,0 +1,9 @@
+export {
+  EmptyState,
+  EmptyStateActions,
+  EmptyStateDescription,
+  EmptyStateIcon,
+  EmptyStateTitle,
+  emptyStateVariants,
+  type EmptyStateProps,
+} from "./empty-state";

package/src/components/empty-state/meta.ts

@@ -0,0 +1,16 @@
+import { defineMeta } from "@/registry/schema";
+
+export const meta = defineMeta({
+  name: "empty-state",
+  title: "Empty State",
+  description: "Shown where content would be, explaining why it is empty and what to do next.",
+  category: "feedback",
+  status: "stable",
+  dependencies: ["class-variance-authority"],
+  registryDependencies: [],
+  files: ["empty-state.tsx"],
+  a11y:
+    "A plain container with no implicit landmark or live region. When it replaces content after " +
+    "a search, put aria-live on the results region so the change is announced. The icon is " +
+    "decorative — the title has to carry the message on its own.",
+});

package/src/components/form/form.stories.tsx

@@ -0,0 +1,144 @@
+import type { Decorator, Meta, StoryObj } from "@storybook/react-vite";
+import { useState } from "react";
+
+import { Button } from "@/components/button";
+import { Checkbox } from "@/components/checkbox";
+import { Input } from "@/components/input";
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "@/components/select";
+
+import { Form, FormControl, FormDescription, FormField, FormLabel, FormMessage } from "./form";
+
+/** Named so its type is nameable in declaration output (TS2883). */
+const withFixedWidth: Decorator = (Story) => (
+  <div className="w-80">
+    <Story />
+  </div>
+);
+
+const meta = {
+  title: "Forms/Form",
+  component: Form,
+  parameters: { controls: { disable: true } },
+  decorators: [withFixedWidth],
+} satisfies Meta<typeof Form>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: () => (
+    <Form>
+      <FormField name="username">
+        <FormLabel>Username</FormLabel>
+        <FormControl>
+          <Input placeholder="ada" />
+        </FormControl>
+        <FormDescription>This is your public display name.</FormDescription>
+        <FormMessage />
+      </FormField>
+      <Button type="submit">Save</Button>
+    </Form>
+  ),
+};
+
+export const WithError: Story = {
+  render: () => (
+    <Form>
+      <FormField name="email" error="Enter a valid email address.">
+        <FormLabel>Email</FormLabel>
+        <FormControl>
+          <Input type="email" defaultValue="not-an-email" />
+        </FormControl>
+        <FormDescription>We will never share it.</FormDescription>
+        <FormMessage />
+      </FormField>
+      <Button type="submit">Save</Button>
+    </Form>
+  ),
+};
+
+/**
+ * The field wiring is state-agnostic — this uses plain `useState`, and the
+ * markup would be identical with React Hook Form or a server action. Only the
+ * source of `error` changes.
+ */
+export const LiveValidation: Story = {
+  render: function LiveValidation() {
+    const [email, setEmail] = useState("");
+    const [touched, setTouched] = useState(false);
+    const error = touched && !email.includes("@") ? "Enter a valid email address." : undefined;
+
+    return (
+      <Form
+        onSubmit={(event) => {
+          event.preventDefault();
+          setTouched(true);
+        }}
+      >
+        <FormField name="email" error={error}>
+          <FormLabel>Email</FormLabel>
+          <FormControl>
+            <Input
+              type="email"
+              value={email}
+              onChange={(event) => setEmail(event.target.value)}
+              onBlur={() => setTouched(true)}
+              placeholder="you@example.com"
+            />
+          </FormControl>
+          <FormDescription>Used for deploy notifications.</FormDescription>
+          <FormMessage />
+        </FormField>
+        <Button type="submit">Continue</Button>
+      </Form>
+    );
+  },
+};
+
+export const MixedControls: Story = {
+  render: () => (
+    <Form>
+      <FormField name="project">
+        <FormLabel>Project name</FormLabel>
+        <FormControl>
+          <Input placeholder="acme-inc" />
+        </FormControl>
+        <FormMessage />
+      </FormField>
+
+      <FormField name="region" error="Choose a region to continue.">
+        <FormLabel>Region</FormLabel>
+        <FormControl>
+          <Select>
+            <SelectTrigger>
+              <SelectValue placeholder="Select a region" />
+            </SelectTrigger>
+            <SelectContent>
+              <SelectItem value="us">United States</SelectItem>
+              <SelectItem value="eu">Europe</SelectItem>
+            </SelectContent>
+          </Select>
+        </FormControl>
+        <FormMessage />
+      </FormField>
+
+      <FormField name="terms">
+        <div className="flex items-center gap-2">
+          <FormControl>
+            <Checkbox />
+          </FormControl>
+          <FormLabel>Accept terms and conditions</FormLabel>
+        </div>
+        <FormMessage />
+      </FormField>
+
+      <Button type="submit">Create project</Button>
+    </Form>
+  ),
+};

package/src/components/form/form.test.tsx

@@ -0,0 +1,203 @@
+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 { Input } from "../input";
+import { Form, FormControl, FormDescription, FormField, FormLabel, FormMessage } from "./form";
+
+function Example({
+  error,
+  withDescription = true,
+}: {
+  error?: string;
+  withDescription?: boolean;
+} = {}) {
+  return (
+    <Form>
+      <FormField name="email" error={error}>
+        <FormLabel>Email</FormLabel>
+        <FormControl>
+          <Input type="email" />
+        </FormControl>
+        {withDescription ? <FormDescription>We will never share it.</FormDescription> : null}
+        <FormMessage />
+      </FormField>
+    </Form>
+  );
+}
+
+describe("Form", () => {
+  it("disables native validation so custom messages are the only ones shown", () => {
+    const { container } = render(<Example />);
+    expect(container.querySelector("form")).toHaveAttribute("novalidate");
+  });
+
+  it("allows native validation back in", () => {
+    const { container } = render(
+      <Form noValidate={false}>
+        <div />
+      </Form>,
+    );
+    expect(container.querySelector("form")).not.toHaveAttribute("novalidate");
+  });
+});
+
+describe("FormField", () => {
+  it("points the label at the control", () => {
+    render(<Example />);
+    expect(screen.getByLabelText("Email")).toBe(screen.getByRole("textbox"));
+  });
+
+  it("describes the control with its description", () => {
+    render(<Example />);
+    expect(screen.getByRole("textbox")).toHaveAccessibleDescription("We will never share it.");
+  });
+
+  it("does not reference a description that was never rendered", () => {
+    render(<Example withDescription={false} />);
+    expect(screen.getByRole("textbox")).not.toHaveAttribute("aria-describedby");
+  });
+
+  it("is not invalid without an error", () => {
+    render(<Example />);
+    expect(screen.getByRole("textbox")).not.toHaveAttribute("aria-invalid");
+    expect(screen.queryByText("Enter a valid email address.")).not.toBeInTheDocument();
+  });
+
+  describe("with an error", () => {
+    it("marks the control invalid", () => {
+      render(<Example error="Enter a valid email address." />);
+      expect(screen.getByRole("textbox")).toHaveAttribute("aria-invalid", "true");
+    });
+
+    it("renders the message", () => {
+      render(<Example error="Enter a valid email address." />);
+      expect(screen.getByText("Enter a valid email address.")).toBeInTheDocument();
+    });
+
+    it("describes the control with both the description and the message", () => {
+      render(<Example error="Enter a valid email address." />);
+      expect(screen.getByRole("textbox")).toHaveAccessibleDescription(
+        "We will never share it. Enter a valid email address.",
+      );
+    });
+
+    it("announces the message politely", () => {
+      render(<Example error="Enter a valid email address." />);
+      const message = screen.getByText("Enter a valid email address.");
+      expect(message).toHaveAttribute("role", "status");
+      expect(message).toHaveAttribute("aria-live", "polite");
+    });
+
+    it("marks the label and wrapper as invalid for styling", () => {
+      const { container } = render(<Example error="Bad" />);
+      expect(container.querySelector("[data-slot='form-field']")).toHaveAttribute(
+        "data-invalid",
+        "true",
+      );
+      expect(screen.getByText("Email")).toHaveClass("text-destructive");
+    });
+  });
+
+  it("mirrors the field name for form-library integration", () => {
+    const { container } = render(<Example />);
+    expect(container.querySelector("[data-slot='form-field']")).toHaveAttribute(
+      "data-name",
+      "email",
+    );
+  });
+
+  it("gives each field its own ids", () => {
+    render(
+      <Form>
+        <FormField name="first">
+          <FormLabel>First</FormLabel>
+          <FormControl>
+            <Input />
+          </FormControl>
+        </FormField>
+        <FormField name="last">
+          <FormLabel>Last</FormLabel>
+          <FormControl>
+            <Input />
+          </FormControl>
+        </FormField>
+      </Form>,
+    );
+
+    const first = screen.getByLabelText("First");
+    const last = screen.getByLabelText("Last");
+    expect(first.id).not.toBe(last.id);
+  });
+
+  it("works with any state source, updating as validation changes", async () => {
+    const user = userEvent.setup();
+
+    function Validated() {
+      const [value, setValue] = useState("");
+      const error = value.includes("@") ? undefined : "Enter a valid email address.";
+      return (
+        <Form>
+          <FormField name="email" error={value ? error : undefined}>
+            <FormLabel>Email</FormLabel>
+            <FormControl>
+              <Input value={value} onChange={(event) => setValue(event.target.value)} />
+            </FormControl>
+            <FormMessage />
+          </FormField>
+        </Form>
+      );
+    }
+
+    render(<Validated />);
+    const input = screen.getByRole("textbox");
+
+    await user.type(input, "nope");
+    expect(input).toHaveAttribute("aria-invalid", "true");
+    expect(screen.getByText("Enter a valid email address.")).toBeInTheDocument();
+
+    await user.type(input, "@example.com");
+    expect(input).not.toHaveAttribute("aria-invalid");
+    expect(screen.queryByText("Enter a valid email address.")).not.toBeInTheDocument();
+  });
+
+  it("lets FormMessage render its own children", () => {
+    render(
+      <Form>
+        <FormField name="email">
+          <FormLabel>Email</FormLabel>
+          <FormControl>
+            <Input />
+          </FormControl>
+          <FormMessage>Custom hint</FormMessage>
+        </FormField>
+      </Form>,
+    );
+    expect(screen.getByText("Custom hint")).toBeInTheDocument();
+  });
+
+  it.each([
+    ["FormLabel", <FormLabel key="l">Label</FormLabel>],
+    [
+      "FormControl",
+      <FormControl key="c">
+        <input />
+      </FormControl>,
+    ],
+    ["FormDescription", <FormDescription key="d">Text</FormDescription>],
+    ["FormMessage", <FormMessage key="m">Text</FormMessage>],
+  ])("throws a useful error if %s is used outside FormField", (name, element) => {
+    const consoleError = vi.spyOn(console, "error").mockImplementation(() => undefined);
+    expect(() => render(element)).toThrow(
+      new RegExp(`${name} must be rendered inside <FormField>`),
+    );
+    consoleError.mockRestore();
+  });
+
+  it("has no accessibility violations", async () => {
+    const { container } = render(<Example error="Enter a valid email address." />);
+    await expectNoA11yViolations(container);
+  });
+});