@elabs-ai/components-ui 4.0.0

package/src/components/field-row/field-row.test.tsx

@@ -0,0 +1,188 @@
+import { useEffect } from "react";
+import { describe, expect, it } from "vitest";
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { useForm } from "react-hook-form";
+import { Input } from "../input";
+import {
+  Form,
+  FormControl,
+  FormDescription,
+  FormField,
+  FormItem,
+  FormLabel,
+  FormMessage,
+} from "../form";
+import { FieldRow } from "./field-row";
+
+describe("FieldRow", () => {
+  it("renders outside any FormProvider / react-hook-form context", () => {
+    expect(() =>
+      render(
+        <FieldRow label="Standalone">
+          <Input />
+        </FieldRow>,
+      ),
+    ).not.toThrow();
+  });
+
+  it("clicking the label focuses the control (native htmlFor/id association)", async () => {
+    render(
+      <FieldRow label="Name">
+        <Input />
+      </FieldRow>,
+    );
+    await userEvent.click(screen.getByText("Name"));
+    expect(screen.getByRole("textbox")).toHaveFocus();
+  });
+
+  it("composes aria-describedby from description + error ids that resolve to the real rendered nodes", () => {
+    render(
+      <FieldRow label="Name" description="Your full name" error="Required">
+        <Input />
+      </FieldRow>,
+    );
+    const input = screen.getByRole("textbox");
+    const describedBy = input.getAttribute("aria-describedby");
+    expect(describedBy).toBeTruthy();
+    const ids = describedBy!.split(" ");
+    expect(ids).toHaveLength(2);
+    for (const id of ids) {
+      expect(document.getElementById(id)).not.toBeNull();
+    }
+    expect(screen.getByText("Your full name").id).toBe(ids[0]);
+    const error = screen.getByRole("alert");
+    expect(error).toHaveTextContent("Required");
+    expect(error.id).toBe(ids[1]);
+  });
+
+  it("sets aria-invalid only when an error is present", () => {
+    const { rerender } = render(
+      <FieldRow label="Name">
+        <Input />
+      </FieldRow>,
+    );
+    expect(screen.getByRole("textbox")).toHaveAttribute("aria-invalid", "false");
+
+    rerender(
+      <FieldRow label="Name" error="Required">
+        <Input />
+      </FieldRow>,
+    );
+    expect(screen.getByRole("textbox")).toHaveAttribute("aria-invalid", "true");
+  });
+
+  it("omits aria-describedby entirely when there is no description and no error", () => {
+    render(
+      <FieldRow label="Name">
+        <Input />
+      </FieldRow>,
+    );
+    expect(screen.getByRole("textbox")).not.toHaveAttribute("aria-describedby");
+  });
+
+  // Regression lock: Radix `Slot` merges CHILD props OVER slot props, so a
+  // control carrying its own `id` used to silently win — `<Label htmlFor>`
+  // then pointed at an element that did not exist and clicking the label
+  // focused nothing. FieldRow now composes with the child's own id.
+  it("keeps the label associated when the control supplies its own id", async () => {
+    render(
+      <FieldRow label="Email" description="Work address">
+        <Input id="consumer-owned-id" />
+      </FieldRow>,
+    );
+    const input = screen.getByRole("textbox");
+    expect(input.id).toBe("consumer-owned-id");
+    expect(screen.getByText("Email")).toHaveAttribute("for", "consumer-owned-id");
+    await userEvent.click(screen.getByText("Email"));
+    expect(input).toHaveFocus();
+  });
+
+  // Same root cause: a child's own `aria-describedby` used to REPLACE the
+  // composed one, so the help and error text were never announced.
+  it("composes with (does not discard) a control's own aria-describedby", () => {
+    render(
+      <>
+        <span id="consumer-hint">Extra hint</span>
+        <FieldRow label="Name" description="Your full name" error="Required">
+          <Input aria-describedby="consumer-hint" />
+        </FieldRow>
+      </>,
+    );
+    const [hintId, descriptionId, errorId, ...rest] = screen
+      .getByRole("textbox")
+      .getAttribute("aria-describedby")!
+      .split(" ");
+    expect(rest).toHaveLength(0);
+    expect(hintId).toBe("consumer-hint");
+    for (const id of [hintId, descriptionId, errorId]) {
+      expect(document.getElementById(id!)).not.toBeNull();
+    }
+    expect(document.getElementById(descriptionId!)).toHaveTextContent("Your full name");
+    expect(document.getElementById(errorId!)).toHaveTextContent("Required");
+  });
+
+  // #354 — a field rendered through FieldRow must produce ACCESSIBLE MARKUP
+  // EQUIVALENT to the same field rendered through the existing react-hook-form
+  // path (Form/FormField/FormItem/FormLabel/FormControl/FormDescription/
+  // FormMessage), proven by a real assertion — not just claimed.
+  it("produces markup equivalent to the RHF-bound Form family for the same field shape", async () => {
+    function RhfField() {
+      const form = useForm({ defaultValues: { name: "" }, mode: "onChange" });
+      // Force a real validation error into RHF field state (not merely a
+      // static string prop), so FormControl/FormMessage compute their
+      // aria-invalid/aria-describedby/error text from the SAME code path a
+      // real consumer hits.
+      useEffect(() => {
+        void form.trigger("name");
+      }, [form]);
+      return (
+        <Form {...form}>
+          <FormField
+            control={form.control}
+            name="name"
+            rules={{ required: "Required" }}
+            render={({ field }) => (
+              <FormItem>
+                <FormLabel>Name</FormLabel>
+                <FormControl>
+                  <Input {...field} />
+                </FormControl>
+                <FormDescription>Your full name</FormDescription>
+                <FormMessage />
+              </FormItem>
+            )}
+          />
+        </Form>
+      );
+    }
+
+    const { unmount } = render(<RhfField />);
+    const rhfInput = await screen.findByRole("textbox");
+    await waitFor(() => expect(rhfInput).toHaveAttribute("aria-invalid", "true"));
+    const rhfLabel = screen.getByText("Name");
+    const rhfDescribedBy = rhfInput.getAttribute("aria-describedby")!.split(" ");
+    expect(rhfLabel.tagName).toBe("LABEL");
+    expect(rhfLabel).toHaveAttribute("for", rhfInput.id);
+    expect(rhfDescribedBy).toHaveLength(2);
+    for (const id of rhfDescribedBy) expect(document.getElementById(id)).not.toBeNull();
+    unmount();
+
+    render(
+      <FieldRow label="Name" description="Your full name" error="Required">
+        <Input />
+      </FieldRow>,
+    );
+    const frInput = screen.getByRole("textbox");
+    const frLabel = screen.getByText("Name");
+    const frDescribedBy = frInput.getAttribute("aria-describedby")!.split(" ");
+
+    // Equivalent SHAPE of accessible markup (same relationship types) — not
+    // identical id strings, since each side mints its own useId().
+    expect(frLabel.tagName).toBe(rhfLabel.tagName);
+    expect(frLabel).toHaveAttribute("for", frInput.id);
+    expect(frDescribedBy).toHaveLength(rhfDescribedBy.length);
+    for (const id of frDescribedBy) expect(document.getElementById(id)).not.toBeNull();
+    expect(frInput).toHaveAttribute("aria-invalid", "true");
+  });
+});

package/src/components/field-row/field-row.tsx

@@ -0,0 +1,115 @@
+import {
+  cloneElement,
+  forwardRef,
+  useId,
+  type HTMLAttributes,
+  type ReactElement,
+  type ReactNode,
+} from "react";
+import { Slot } from "@radix-ui/react-slot";
+import { cn } from "../../lib/cn";
+import { Label } from "../label";
+
+export interface FieldRowProps extends Omit<HTMLAttributes<HTMLDivElement>, "children"> {
+  /** Field label — rendered as a real `<label>`, click-to-focus associated with the control. */
+  label: ReactNode;
+  /** Optional help/description text, always visible (not gated by an error). */
+  description?: ReactNode;
+  /**
+   * Validation error text. When present: sets `aria-invalid` on the control,
+   * is appended to `aria-describedby`, and is announced via `role="alert"`.
+   */
+  error?: ReactNode;
+  /**
+   * The single field control (`Input`, `Textarea`, `Select`, …). Receives
+   * `id`/`aria-describedby`/`aria-invalid` via a Radix `Slot` — must be a
+   * single element that forwards those props to a real form control.
+   */
+  children: ReactElement;
+}
+
+/**
+ * Label/description/error/`aria-describedby` wiring for a field OUTSIDE a
+ * `react-hook-form` tree — the same anatomy as `FormItem`/`FormLabel`/
+ * `FormControl`/`FormDescription`/`FormMessage` (`../form`), but driven by
+ * plain props (`label`/`description`/`error`) instead of RHF field state, so
+ * a single `useState`-controlled field doesn't need a full `<Form>` +
+ * `<FormField>` + `Controller` just to get correct label/error association.
+ *
+ * Reach for `Form`/`FormField`/… instead when the field already lives inside
+ * a `react-hook-form` `<FormProvider>` — this component does not replace that
+ * family, it covers the gap outside it (#354).
+ */
+export const FieldRow = forwardRef<HTMLDivElement, FieldRowProps>(function FieldRow(
+  { label, description, error, children, className, ...props },
+  ref,
+) {
+  const id = useId();
+  const descriptionId = `${id}-description`;
+  const errorId = `${id}-error`;
+
+  // Radix `Slot` merges CHILD props OVER slot props, so a control that carries
+  // its own `id` / `aria-describedby` (a perfectly ordinary `<Input id="email">`)
+  // silently wins — the `<Label htmlFor>` would then point at nothing and the
+  // description/error would never be announced, defeating the one thing this
+  // component exists to guarantee. So compose with the child's own values
+  // instead of assuming they are absent, and clone the child with the composed
+  // result so "child wins" resolves to the composed value either way.
+  const control = children as ReactElement<{
+    id?: string;
+    "aria-describedby"?: string;
+  }>;
+  const childProps = control.props;
+  const controlId = childProps.id ?? `${id}-control`;
+
+  const describedBy =
+    [
+      childProps["aria-describedby"] ?? null,
+      description ? descriptionId : null,
+      error ? errorId : null,
+    ]
+      .filter(Boolean)
+      .join(" ") || undefined;
+
+  return (
+    <div ref={ref} data-slot="field-row" className={cn("space-y-2", className)} {...props}>
+      <Label
+        htmlFor={controlId}
+        data-slot="field-row-label"
+        className={cn(
+          "transition-colors duration-fast ease-standard",
+          error && "text-destructive-text",
+        )}
+      >
+        {label}
+      </Label>
+      <Slot
+        id={controlId}
+        aria-describedby={describedBy}
+        aria-invalid={!!error}
+        data-slot="field-row-control"
+      >
+        {cloneElement(control, { id: controlId, "aria-describedby": describedBy })}
+      </Slot>
+      {description ? (
+        <p
+          id={descriptionId}
+          data-slot="field-row-description"
+          className="text-body text-muted-foreground"
+        >
+          {description}
+        </p>
+      ) : null}
+      {error ? (
+        <p
+          id={errorId}
+          role="alert"
+          data-slot="field-row-error"
+          className="text-body font-medium text-destructive-text"
+        >
+          {error}
+        </p>
+      ) : null}
+    </div>
+  );
+});

package/src/components/field-row/index.ts

@@ -0,0 +1 @@
+export { FieldRow, type FieldRowProps } from "./field-row";

package/src/components/file-upload/file-upload.stories.tsx

@@ -0,0 +1,183 @@
+import { useState } from "react";
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import {
+  FileUpload,
+  FileUploadDropzone,
+  FileUploadList,
+  FileUploadItem,
+  type UploadFile,
+} from "./file-upload";
+
+const meta = {
+  title: "Forms/FileUpload",
+  component: FileUpload,
+  tags: ["autodocs"],
+  argTypes: {
+    files: {
+      description: "Controlled file list (`UploadFile[]`).",
+      control: false,
+      table: { category: "State" },
+    },
+    onFilesChange: {
+      description: "Called when files are added or removed.",
+      control: false,
+      table: { category: "Behavior" },
+    },
+    accept: {
+      description: "Accepted MIME types / extensions forwarded to the hidden `<input>`.",
+      control: "text",
+      table: { category: "Behavior" },
+    },
+    multiple: {
+      description: "Allow selecting multiple files at once.",
+      control: "boolean",
+      table: { category: "Behavior" },
+    },
+    maxSize: {
+      description: "Maximum individual file size in bytes.",
+      control: "number",
+      table: { category: "Behavior" },
+    },
+    maxFiles: {
+      description: "Maximum number of files in the list at once.",
+      control: "number",
+      table: { category: "Behavior" },
+    },
+    disabled: {
+      description: "Disable all interactions.",
+      control: "boolean",
+      table: { category: "State" },
+    },
+    children: {
+      description: "Compose with `FileUploadDropzone`, `FileUploadList`, and `FileUploadItem`.",
+      control: false,
+      table: { category: "Content" },
+    },
+    className: {
+      description: "Additional CSS classes applied to the root element.",
+      control: "text",
+      table: { category: "Appearance" },
+    },
+  },
+} satisfies Meta<typeof FileUpload>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// Seed files for visual stories
+function makeFakeFile(name: string, size: number): File {
+  const file = new File(["x"], name, { type: "text/plain", lastModified: Date.now() });
+  // Override the byte size so the stories display realistic file sizes.
+  Object.defineProperty(file, "size", { value: size });
+  return file;
+}
+
+const seedFiles: UploadFile[] = [
+  { id: "1", file: Object.assign(makeFakeFile("report.pdf", 204800), {}), status: "success" },
+  {
+    id: "2",
+    file: Object.assign(makeFakeFile("data.csv", 51200), {}),
+    status: "uploading",
+    progress: 60,
+  },
+  {
+    id: "3",
+    file: Object.assign(makeFakeFile("broken.txt", 1024), {}),
+    status: "error",
+    errorMessage: "File exceeds size limit.",
+  },
+];
+
+export const Default: Story = {
+  render: () => (
+    <div className="max-w-md">
+      <FileUpload multiple accept="image/*,.pdf">
+        <FileUploadDropzone />
+        <FileUploadList>
+          {seedFiles.map((f) => (
+            <FileUploadItem
+              key={f.id}
+              uploadFile={f}
+              status={f.status}
+              progress={f.progress}
+              errorMessage={f.errorMessage}
+            />
+          ))}
+        </FileUploadList>
+      </FileUpload>
+    </div>
+  ),
+};
+
+export const Uncontrolled: Story = {
+  render: () => (
+    <div className="max-w-md">
+      <FileUpload multiple accept="image/*,.pdf,.docx" maxSize={5 * 1024 * 1024} maxFiles={5}>
+        <FileUploadDropzone />
+        <FileUploadList />
+      </FileUpload>
+    </div>
+  ),
+};
+
+export const Controlled: Story = {
+  render: () => {
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    const [files, setFiles] = useState<UploadFile[]>([]);
+    return (
+      <div className="flex flex-col gap-4 max-w-md">
+        <FileUpload files={files} onFilesChange={setFiles} multiple>
+          <FileUploadDropzone />
+          <FileUploadList>
+            {files.map((f) => (
+              <FileUploadItem key={f.id} uploadFile={f} />
+            ))}
+          </FileUploadList>
+        </FileUpload>
+        <p className="text-body text-muted-foreground">
+          {files.length} file{files.length !== 1 ? "s" : ""} selected
+        </p>
+      </div>
+    );
+  },
+};
+
+export const WithProgress: Story = {
+  render: () => (
+    <div className="max-w-md">
+      <FileUpload>
+        <FileUploadDropzone />
+        <FileUploadList>
+          <FileUploadItem uploadFile={seedFiles[1]} status="uploading" progress={60} />
+          <FileUploadItem uploadFile={seedFiles[0]} status="success" />
+        </FileUploadList>
+      </FileUpload>
+    </div>
+  ),
+};
+
+export const WithError: Story = {
+  render: () => (
+    <div className="max-w-md">
+      <FileUpload>
+        <FileUploadDropzone />
+        <FileUploadList>
+          <FileUploadItem
+            uploadFile={seedFiles[2]}
+            status="error"
+            errorMessage="Server rejected the file."
+          />
+        </FileUploadList>
+      </FileUpload>
+    </div>
+  ),
+};
+
+export const Disabled: Story = {
+  render: () => (
+    <div className="max-w-md">
+      <FileUpload disabled>
+        <FileUploadDropzone />
+      </FileUpload>
+    </div>
+  ),
+};

package/src/components/file-upload/file-upload.test.tsx

@@ -0,0 +1,169 @@
+import { describe, expect, it, vi } from "vitest";
+import { render, screen, fireEvent } from "@testing-library/react";
+import {
+  FileUpload,
+  FileUploadDropzone,
+  FileUploadList,
+  FileUploadItem,
+  type UploadFile,
+} from "./file-upload";
+
+function makeUploadFile(name = "test.txt", size = 1024): UploadFile {
+  const file = new File(["x"], name, { type: "text/plain" });
+  Object.defineProperty(file, "size", { value: size });
+  return { id: `id-${name}`, file };
+}
+
+describe("FileUpload", () => {
+  it("renders the dropzone with a label pointing to the hidden input", () => {
+    render(
+      <FileUpload>
+        <FileUploadDropzone />
+      </FileUpload>,
+    );
+    // The label wraps the input — label's htmlFor matches input's id
+    const label = document.querySelector("label[data-slot='file-upload-dropzone']");
+    expect(label).not.toBeNull();
+    const inputId = label!.getAttribute("for");
+    expect(inputId).toBeTruthy();
+    const input = document.getElementById(inputId!);
+    expect(input).not.toBeNull();
+    expect(input!.tagName.toLowerCase()).toBe("input");
+    expect(input).toHaveAttribute("type", "file");
+  });
+
+  it("hidden file input has sr-only class (visually hidden but real)", () => {
+    render(
+      <FileUpload>
+        <FileUploadDropzone />
+      </FileUpload>,
+    );
+    const input = document.querySelector("input[type='file']");
+    expect(input).not.toBeNull();
+    expect(input).toHaveClass("sr-only");
+  });
+
+  it("calls onFilesChange when a file is added (controlled)", () => {
+    const onFilesChange = vi.fn();
+    render(
+      <FileUpload files={[]} onFilesChange={onFilesChange}>
+        <FileUploadDropzone />
+      </FileUpload>,
+    );
+    const input = document.querySelector("input[type='file']") as HTMLInputElement;
+    const file = new File(["hello"], "hello.txt", { type: "text/plain" });
+    fireEvent.change(input, { target: { files: [file] } });
+    expect(onFilesChange).toHaveBeenCalledOnce();
+    expect(onFilesChange.mock.calls[0]![0]).toHaveLength(1);
+    expect(onFilesChange.mock.calls[0]![0][0].file.name).toBe("hello.txt");
+  });
+
+  it("respects maxFiles — does not exceed the limit", () => {
+    const onFilesChange = vi.fn();
+    render(
+      <FileUpload files={[]} onFilesChange={onFilesChange} maxFiles={1}>
+        <FileUploadDropzone />
+      </FileUpload>,
+    );
+    const input = document.querySelector("input[type='file']") as HTMLInputElement;
+    const files = [
+      new File(["a"], "a.txt", { type: "text/plain" }),
+      new File(["b"], "b.txt", { type: "text/plain" }),
+    ];
+    fireEvent.change(input, { target: { files } });
+    expect(onFilesChange.mock.calls[0]![0]).toHaveLength(1);
+  });
+
+  it("respects maxSize — skips files over the limit", () => {
+    const onFilesChange = vi.fn();
+    render(
+      <FileUpload files={[]} onFilesChange={onFilesChange} maxSize={10}>
+        <FileUploadDropzone />
+      </FileUpload>,
+    );
+    const input = document.querySelector("input[type='file']") as HTMLInputElement;
+    // File content "x".repeat(100) is 100 bytes > 10
+    const big = new File(["x".repeat(100)], "big.txt", { type: "text/plain" });
+    fireEvent.change(input, { target: { files: [big] } });
+    expect(onFilesChange.mock.calls[0]![0]).toHaveLength(0);
+  });
+
+  it("FileUploadList renders role=status and aria-live=polite", () => {
+    const f = makeUploadFile();
+    render(
+      <FileUpload files={[f]} onFilesChange={() => {}}>
+        <FileUploadList>
+          <FileUploadItem uploadFile={f} />
+        </FileUploadList>
+      </FileUpload>,
+    );
+    const list = screen.getByRole("status");
+    expect(list).toHaveAttribute("aria-live", "polite");
+  });
+
+  it("FileUploadList returns null when no files and no children", () => {
+    const { container } = render(
+      <FileUpload files={[]} onFilesChange={() => {}}>
+        <FileUploadList />
+      </FileUpload>,
+    );
+    expect(container.querySelector("[data-slot='file-upload-list']")).toBeNull();
+  });
+
+  it("FileUploadItem shows progress bar when status=uploading", () => {
+    const f = makeUploadFile();
+    render(
+      <FileUpload files={[f]} onFilesChange={() => {}}>
+        <FileUploadList>
+          <FileUploadItem uploadFile={f} status="uploading" progress={42} />
+        </FileUploadList>
+      </FileUpload>,
+    );
+    // Progress bar is present (Radix renders a progressbar role)
+    expect(screen.getByRole("progressbar")).toBeInTheDocument();
+  });
+
+  it("FileUploadItem shows role=alert for error messages", () => {
+    const f = makeUploadFile();
+    render(
+      <FileUpload files={[f]} onFilesChange={() => {}}>
+        <FileUploadList>
+          <FileUploadItem uploadFile={f} status="error" errorMessage="Upload failed." />
+        </FileUploadList>
+      </FileUpload>,
+    );
+    const alert = screen.getByRole("alert");
+    expect(alert).toHaveTextContent("Upload failed.");
+  });
+
+  it("remove button calls removeFile via context", () => {
+    const onFilesChange = vi.fn();
+    const f = makeUploadFile("removeme.txt");
+    render(
+      <FileUpload files={[f]} onFilesChange={onFilesChange}>
+        <FileUploadList>
+          <FileUploadItem uploadFile={f} />
+        </FileUploadList>
+      </FileUpload>,
+    );
+    const removeBtn = screen.getByRole("button", { name: /remove removeme/i });
+    fireEvent.click(removeBtn);
+    expect(onFilesChange).toHaveBeenCalledWith([]);
+  });
+
+  it("disabled prop disables the file input and remove buttons", () => {
+    const f = makeUploadFile();
+    render(
+      <FileUpload files={[f]} onFilesChange={() => {}} disabled>
+        <FileUploadDropzone />
+        <FileUploadList>
+          <FileUploadItem uploadFile={f} />
+        </FileUploadList>
+      </FileUpload>,
+    );
+    const input = document.querySelector("input[type='file']") as HTMLInputElement;
+    expect(input).toBeDisabled();
+    const removeBtn = screen.getByRole("button", { name: /remove/i });
+    expect(removeBtn).toBeDisabled();
+  });
+});