@dowel-ui/react 0.1.0

package/src/components/form/form.tsx

@@ -0,0 +1,221 @@
+"use client";
+
+import { Label as LabelPrimitive, Slot } from "radix-ui";
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useId,
+  useMemo,
+  useState,
+  type ComponentPropsWithRef,
+  type ReactNode,
+} from "react";
+
+import { cn } from "@/lib/utils";
+
+/**
+ * Accessible wiring for form fields.
+ *
+ * Deliberately **not** bound to a form library. What is actually hard about a
+ * form field is the ARIA plumbing — generating an id, pointing the label at the
+ * control, assembling `aria-describedby` from the description and the error,
+ * and flipping `aria-invalid` — and that plumbing is identical whether the
+ * state comes from `useState`, React Hook Form, Formik or a server action.
+ *
+ * Binding to one library would make everyone else install it to get the
+ * plumbing, and would make the source you own harder to change. Pass `error`
+ * from whatever holds your state:
+ *
+ *   <FormField name="email" error={errors.email?.message}>
+ *     <FormLabel>Email</FormLabel>
+ *     <FormControl>
+ *       <Input {...register("email")} />
+ *     </FormControl>
+ *     <FormDescription>We will never share it.</FormDescription>
+ *     <FormMessage />
+ *   </FormField>
+ */
+
+interface FormFieldContextValue {
+  id: string;
+  name: string | undefined;
+  descriptionId: string;
+  messageId: string;
+  error: ReactNode;
+  hasDescription: boolean;
+  registerDescription: (present: boolean) => void;
+}
+
+const FormFieldContext = createContext<FormFieldContextValue | null>(null);
+
+function useFormField(component: string): FormFieldContextValue {
+  const context = useContext(FormFieldContext);
+  if (!context) {
+    throw new Error(`${component} must be rendered inside <FormField>.`);
+  }
+  return context;
+}
+
+export type FormProps = ComponentPropsWithRef<"form">;
+
+/**
+ * A form element.
+ *
+ * `noValidate` is on by default: when the form renders its own messages, the
+ * browser's validation bubbles compete with them, appear in a different visual
+ * language, and cannot be styled. Pass `noValidate={false}` to opt back in.
+ */
+export function Form({ className, noValidate = true, ...props }: FormProps) {
+  return (
+    <form
+      data-slot="form"
+      noValidate={noValidate}
+      className={cn("grid gap-6", className)}
+      {...props}
+    />
+  );
+}
+
+export interface FormFieldProps extends ComponentPropsWithRef<"div"> {
+  /** Field name, mirrored onto the wrapper for form-library integration. */
+  name?: string;
+  /** Present when the field is invalid. Its content is rendered by FormMessage. */
+  error?: ReactNode;
+}
+
+export function FormField({ className, name, error, ...props }: FormFieldProps) {
+  const uid = useId();
+  // Description presence is tracked rather than assumed: aria-describedby must
+  // not name an element that was never rendered. axe flags a dangling reference,
+  // and a screen reader announces nothing for it.
+  const [hasDescription, setHasDescription] = useState(false);
+
+  const registerDescription = useCallback((present: boolean) => {
+    setHasDescription(present);
+  }, []);
+
+  const value = useMemo<FormFieldContextValue>(
+    () => ({
+      id: `${uid}-control`,
+      name,
+      descriptionId: `${uid}-description`,
+      messageId: `${uid}-message`,
+      error,
+      hasDescription,
+      registerDescription,
+    }),
+    [uid, name, error, hasDescription, registerDescription],
+  );
+
+  return (
+    <FormFieldContext.Provider value={value}>
+      <div
+        data-slot="form-field"
+        data-name={name}
+        data-invalid={error ? true : undefined}
+        className={cn("grid gap-2", className)}
+        {...props}
+      />
+    </FormFieldContext.Provider>
+  );
+}
+
+export type FormLabelProps = ComponentPropsWithRef<typeof LabelPrimitive.Root>;
+
+export function FormLabel({ className, ...props }: FormLabelProps) {
+  const { id, error } = useFormField("FormLabel");
+
+  return (
+    <LabelPrimitive.Root
+      data-slot="form-label"
+      data-invalid={error ? true : undefined}
+      htmlFor={id}
+      className={cn(
+        "flex items-center gap-2 text-sm leading-none font-medium select-none",
+        "peer-disabled:cursor-not-allowed peer-disabled:opacity-55",
+        error && "text-destructive",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+export type FormControlProps = ComponentPropsWithRef<typeof Slot.Root>;
+
+/**
+ * Injects the field's id and ARIA attributes into its single child.
+ *
+ * Takes the control as a child rather than rendering one, so it works with any
+ * input: our Input, a native select, a third-party editor.
+ */
+export function FormControl(props: FormControlProps) {
+  const { id, error, messageId, descriptionId, hasDescription } = useFormField("FormControl");
+
+  const describedBy =
+    [hasDescription ? descriptionId : null, error ? messageId : null]
+      .filter(Boolean)
+      .join(" ") || undefined;
+
+  return (
+    <Slot.Root
+      data-slot="form-control"
+      id={id}
+      aria-describedby={describedBy}
+      aria-invalid={error ? true : undefined}
+      {...props}
+    />
+  );
+}
+
+export function FormDescription({ className, ...props }: ComponentPropsWithRef<"p">) {
+  const { descriptionId, registerDescription } = useFormField("FormDescription");
+
+  useEffect(() => {
+    registerDescription(true);
+    return () => {
+      registerDescription(false);
+    };
+  }, [registerDescription]);
+
+  return (
+    <p
+      data-slot="form-description"
+      id={descriptionId}
+      className={cn("text-xs text-muted-foreground", className)}
+      {...props}
+    />
+  );
+}
+
+export type FormMessageProps = ComponentPropsWithRef<"p">;
+
+/**
+ * Renders the field's error.
+ *
+ * Renders nothing when there is no error and no children, so the layout does
+ * not reserve space for a message that may never appear. It is a polite live
+ * region: a validation message that arrives after the user has moved on should
+ * be announced, but should not interrupt what is being read.
+ */
+export function FormMessage({ className, children, ...props }: FormMessageProps) {
+  const { messageId, error } = useFormField("FormMessage");
+  const content = children ?? error;
+
+  if (!content) return null;
+
+  return (
+    <p
+      data-slot="form-message"
+      id={messageId}
+      role="status"
+      aria-live="polite"
+      className={cn("text-xs font-medium text-destructive", className)}
+      {...props}
+    >
+      {content}
+    </p>
+  );
+}

package/src/components/form/index.ts

@@ -0,0 +1,13 @@
+export {
+  Form,
+  FormControl,
+  FormDescription,
+  FormField,
+  FormLabel,
+  FormMessage,
+  type FormControlProps,
+  type FormFieldProps,
+  type FormLabelProps,
+  type FormMessageProps,
+  type FormProps,
+} from "./form";

package/src/components/form/meta.ts

@@ -0,0 +1,17 @@
+import { defineMeta } from "@/registry/schema";
+
+export const meta = defineMeta({
+  name: "form",
+  title: "Form",
+  description: "Accessible field wiring that works with any form library, or none.",
+  category: "form",
+  status: "stable",
+  dependencies: ["radix-ui"],
+  registryDependencies: [],
+  files: ["form.tsx"],
+  a11y:
+    "FormField generates the id, points the Label at the control, and assembles aria-describedby " +
+    "from whichever of the description and error are actually present — a dangling reference " +
+    "announces nothing and is flagged by axe. aria-invalid follows the error. FormMessage is a " +
+    "polite live region, so a late validation message is announced without interrupting.",
+});

package/src/components/input/index.ts

@@ -0,0 +1 @@
+export { Input, inputVariants, type InputProps } from "./input";

package/src/components/input/input.stories.tsx

@@ -0,0 +1,84 @@
+import type { Decorator, Meta, StoryObj } from "@storybook/react-vite";
+
+import { Label } from "@/components/label";
+
+import { Input } from "./input";
+
+/** Named so its type is nameable in declaration output (TS2883). */
+const withFixedWidth: Decorator = (Story) => (
+  <div className="w-72">
+    <Story />
+  </div>
+);
+
+const meta = {
+  title: "Forms/Input",
+  component: Input,
+  args: {
+    placeholder: "acme-inc",
+    inputSize: "md",
+  },
+  argTypes: {
+    inputSize: { control: "select", options: ["sm", "md", "lg"] },
+    disabled: { control: "boolean" },
+    type: { control: "select", options: ["text", "email", "password", "number", "search"] },
+  },
+  decorators: [withFixedWidth],
+} satisfies Meta<typeof Input>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: (args) => (
+    <div className="grid gap-2">
+      <Label htmlFor="project">Project name</Label>
+      <Input id="project" {...args} />
+    </div>
+  ),
+};
+
+export const Sizes: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="grid gap-3">
+      <Input inputSize="sm" placeholder="Small" aria-label="Small" />
+      <Input inputSize="md" placeholder="Medium" aria-label="Medium" />
+      <Input inputSize="lg" placeholder="Large" aria-label="Large" />
+    </div>
+  ),
+};
+
+export const Invalid: Story = {
+  render: () => (
+    <div className="grid gap-2">
+      <Label htmlFor="email">Email</Label>
+      <Input
+        id="email"
+        type="email"
+        defaultValue="not-an-email"
+        aria-invalid
+        aria-describedby="email-error"
+      />
+      <p id="email-error" className="text-xs text-destructive">
+        Enter a valid email address.
+      </p>
+    </div>
+  ),
+};
+
+export const Disabled: Story = {
+  args: { disabled: true, value: "Read only" },
+};
+
+export const Types: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="grid gap-3">
+      <Input type="email" placeholder="you@example.com" aria-label="Email" />
+      <Input type="password" placeholder="••••••••" aria-label="Password" />
+      <Input type="number" placeholder="42" aria-label="Quantity" />
+      <Input type="search" placeholder="Search…" aria-label="Search" />
+    </div>
+  ),
+};

package/src/components/input/input.test.tsx

@@ -0,0 +1,108 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { createRef, useState } from "react";
+import { describe, expect, it, vi } from "vitest";
+
+import { expectNoA11yViolations } from "../../../test/a11y";
+import { Input } from "./input";
+
+describe("Input", () => {
+  it("renders a text input by default", () => {
+    render(<Input aria-label="Name" />);
+    expect(screen.getByRole("textbox", { name: "Name" })).toHaveAttribute("type", "text");
+  });
+
+  it("honours an explicit type", () => {
+    render(<Input type="email" aria-label="Email" />);
+    expect(screen.getByRole("textbox")).toHaveAttribute("type", "email");
+  });
+
+  it.each([
+    ["sm", "h-8"],
+    ["md", "h-9"],
+    ["lg", "h-10"],
+  ] as const)("applies the %s size", (inputSize, expectedClass) => {
+    render(<Input inputSize={inputSize} aria-label="Name" />);
+    expect(screen.getByRole("textbox")).toHaveClass(expectedClass);
+  });
+
+  it("does not shadow the native size attribute", () => {
+    render(<Input size={5} aria-label="Name" />);
+    expect(screen.getByRole("textbox")).toHaveAttribute("size", "5");
+  });
+
+  it("lets a consumer className override a conflicting utility", () => {
+    render(<Input className="h-16" aria-label="Name" />);
+    const input = screen.getByRole("textbox");
+    expect(input).toHaveClass("h-16");
+    expect(input).not.toHaveClass("h-9");
+  });
+
+  it("forwards a ref", () => {
+    const ref = createRef<HTMLInputElement>();
+    render(<Input ref={ref} aria-label="Name" />);
+    expect(ref.current).toBeInstanceOf(HTMLInputElement);
+  });
+
+  it("works uncontrolled", async () => {
+    const user = userEvent.setup();
+    render(<Input defaultValue="ab" aria-label="Name" />);
+
+    const input = screen.getByRole<HTMLInputElement>("textbox");
+    await user.type(input, "cd");
+    expect(input.value).toBe("abcd");
+  });
+
+  it("works controlled", async () => {
+    const user = userEvent.setup();
+
+    function Controlled() {
+      const [value, setValue] = useState("");
+      return (
+        <Input
+          value={value}
+          onChange={(event) => setValue(event.target.value)}
+          aria-label="Name"
+        />
+      );
+    }
+
+    render(<Controlled />);
+    const input = screen.getByRole<HTMLInputElement>("textbox");
+    await user.type(input, "hello");
+    expect(input.value).toBe("hello");
+  });
+
+  it("does not accept input while disabled", async () => {
+    const onChange = vi.fn();
+    const user = userEvent.setup();
+    render(<Input disabled onChange={onChange} aria-label="Name" />);
+
+    const input = screen.getByRole("textbox");
+    expect(input).toBeDisabled();
+    await user.type(input, "x");
+    expect(onChange).not.toHaveBeenCalled();
+  });
+
+  it("exposes the invalid state through aria-invalid", () => {
+    render(<Input aria-invalid aria-label="Name" />);
+    expect(screen.getByRole("textbox")).toHaveAttribute("aria-invalid", "true");
+  });
+
+  it("is reachable by keyboard", async () => {
+    const user = userEvent.setup();
+    render(<Input aria-label="Name" />);
+    await user.tab();
+    expect(screen.getByRole("textbox")).toHaveFocus();
+  });
+
+  it("has no accessibility violations", async () => {
+    const { container } = render(
+      <>
+        <label htmlFor="field">Name</label>
+        <Input id="field" />
+      </>,
+    );
+    await expectNoA11yViolations(container);
+  });
+});

package/src/components/input/input.tsx

@@ -0,0 +1,51 @@
+import { cva, type VariantProps } from "class-variance-authority";
+import type { ComponentPropsWithRef } from "react";
+
+import { focusRingInset, invalidStyles } from "@/lib/styles";
+import { cn } from "@/lib/utils";
+
+const inputVariants = cva(
+  cn(
+    "flex w-full min-w-0 rounded-md border border-input bg-background text-foreground shadow-xs",
+    "transition-[border-color,box-shadow] duration-[var(--duration-fast)] ease-[var(--ease-out-quint)]",
+    "placeholder:text-muted-foreground",
+    "file:mr-3 file:border-0 file:bg-transparent file:text-sm file:font-medium file:text-foreground",
+    "focus-visible:border-ring",
+    "disabled:cursor-not-allowed disabled:opacity-55",
+    focusRingInset,
+    invalidStyles,
+  ),
+  {
+    variants: {
+      inputSize: {
+        sm: "h-8 px-2.5 text-sm",
+        md: "h-9 px-3 text-sm",
+        lg: "h-10 px-3.5 text-base",
+      },
+    },
+    defaultVariants: {
+      inputSize: "md",
+    },
+  },
+);
+
+export interface InputProps
+  extends ComponentPropsWithRef<"input">, VariantProps<typeof inputVariants> {}
+
+/**
+ * Single-line text field.
+ *
+ * The visual size prop is named `inputSize` rather than `size` because `size`
+ * is a native `<input>` attribute with unrelated semantics (a character-count
+ * width hint). Naming it apart keeps both available instead of shadowing one.
+ *
+ * Error styling is driven by the native `aria-invalid` attribute rather than a
+ * bespoke prop, so form libraries wire it up without an adapter.
+ */
+export function Input({ className, inputSize, type = "text", ...props }: InputProps) {
+  return (
+    <input type={type} className={cn(inputVariants({ inputSize }), className)} {...props} />
+  );
+}
+
+export { inputVariants };

package/src/components/input/meta.ts

@@ -0,0 +1,15 @@
+import { defineMeta } from "@/registry/schema";
+
+export const meta = defineMeta({
+  name: "input",
+  title: "Input",
+  description: "A single-line text field with size variants and native validation styling.",
+  category: "form",
+  status: "stable",
+  dependencies: ["class-variance-authority"],
+  registryDependencies: [],
+  files: ["input.tsx"],
+  a11y:
+    "Always pair with a Label via htmlFor/id. Error state is driven by aria-invalid so " +
+    "assistive technology and styling stay in sync; describe the error with aria-describedby.",
+});

package/src/components/label/index.ts

@@ -0,0 +1 @@
+export { Label, type LabelProps } from "./label";

package/src/components/label/label.stories.tsx

@@ -0,0 +1,51 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+
+import { Input } from "@/components/input";
+
+import { Label } from "./label";
+
+const meta = {
+  title: "Forms/Label",
+  component: Label,
+  args: { children: "Project name" },
+} satisfies Meta<typeof Label>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: (args) => (
+    <div className="grid w-72 gap-2">
+      <Label htmlFor="project" {...args} />
+      <Input id="project" placeholder="acme-inc" />
+    </div>
+  ),
+};
+
+export const Required: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="grid w-72 gap-2">
+      <Label htmlFor="email">
+        Email
+        <span aria-hidden="true" className="text-destructive">
+          *
+        </span>
+      </Label>
+      <Input id="email" type="email" required placeholder="you@example.com" />
+    </div>
+  ),
+};
+
+/** A label dims alongside the control it describes. */
+export const WithDisabledControl: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="grid w-72 gap-2">
+      <Input id="locked" disabled placeholder="Locked" className="peer order-2" />
+      <Label htmlFor="locked" className="order-1">
+        Workspace slug
+      </Label>
+    </div>
+  ),
+};

package/src/components/label/label.test.tsx

@@ -0,0 +1,55 @@
+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 { Label } from "./label";
+
+describe("Label", () => {
+  it("renders its text", () => {
+    render(<Label htmlFor="name">Full name</Label>);
+    expect(screen.getByText("Full name")).toBeInTheDocument();
+  });
+
+  it("associates itself with a control via htmlFor", () => {
+    render(
+      <>
+        <Label htmlFor="name">Full name</Label>
+        <input id="name" />
+      </>,
+    );
+    expect(screen.getByLabelText("Full name")).toBeInTheDocument();
+  });
+
+  it("moves focus to its control when clicked", async () => {
+    const user = userEvent.setup();
+    render(
+      <>
+        <Label htmlFor="name">Full name</Label>
+        <input id="name" />
+      </>,
+    );
+
+    await user.click(screen.getByText("Full name"));
+    expect(screen.getByLabelText("Full name")).toHaveFocus();
+  });
+
+  it("merges a consumer className", () => {
+    render(
+      <Label htmlFor="name" className="text-destructive">
+        Full name
+      </Label>,
+    );
+    expect(screen.getByText("Full name")).toHaveClass("text-destructive", "font-medium");
+  });
+
+  it("has no accessibility violations", async () => {
+    const { container } = render(
+      <>
+        <Label htmlFor="name">Full name</Label>
+        <input id="name" />
+      </>,
+    );
+    await expectNoA11yViolations(container);
+  });
+});

package/src/components/label/label.tsx

@@ -0,0 +1,26 @@
+import { Label as LabelPrimitive } from "radix-ui";
+import type { ComponentPropsWithRef } from "react";
+
+import { cn } from "@/lib/utils";
+
+export type LabelProps = ComponentPropsWithRef<typeof LabelPrimitive.Root>;
+
+/**
+ * Caption for a form control.
+ *
+ * Built on the Radix primitive so clicking the label focuses its control even
+ * when the control is a composite widget rather than a native input.
+ */
+export function Label({ className, ...props }: LabelProps) {
+  return (
+    <LabelPrimitive.Root
+      className={cn(
+        "flex items-center gap-2 text-sm leading-none font-medium select-none",
+        "peer-disabled:cursor-not-allowed peer-disabled:opacity-55",
+        "group-data-[disabled=true]:pointer-events-none group-data-[disabled=true]:opacity-55",
+        className,
+      )}
+      {...props}
+    />
+  );
+}

package/src/components/label/meta.ts

@@ -0,0 +1,15 @@
+import { defineMeta } from "@/registry/schema";
+
+export const meta = defineMeta({
+  name: "label",
+  title: "Label",
+  description: "An accessible caption that associates text with a form control.",
+  category: "form",
+  status: "stable",
+  dependencies: ["radix-ui"],
+  registryDependencies: [],
+  files: ["label.tsx"],
+  a11y:
+    "Set htmlFor to the id of the control it labels. Clicking the label moves focus to that " +
+    "control, including composite widgets that are not native inputs.",
+});

package/src/components/pagination/index.ts

@@ -0,0 +1,10 @@
+export {
+  Pagination,
+  PaginationContent,
+  PaginationEllipsis,
+  PaginationItem,
+  PaginationLink,
+  PaginationNext,
+  PaginationPrevious,
+  type PaginationLinkProps,
+} from "./pagination";