@boxcustodia/library 2.0.0-alpha.18 → 2.0.0-alpha.19

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

@@ -0,0 +1,388 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { act } from "react";
+import { describe, expect, it, vi } from "vitest";
+import {
+  Checkbox,
+  CheckboxGroupContext,
+  CheckboxIndicator,
+  CheckboxPrimitive,
+  CheckboxRoot,
+} from "../../components";
+
+describe("Checkbox primitives", () => {
+  it("CheckboxRoot renders with the checkbox slot and merges className", () => {
+    render(<CheckboxRoot className="extra" />);
+
+    const root = screen.getByRole("checkbox");
+    expect(root).toHaveAttribute("data-slot", "checkbox");
+    expect(root).toHaveClass("extra");
+  });
+
+  it("renders the checkmark indicator when checked", () => {
+    render(
+      <CheckboxRoot defaultChecked>
+        <CheckboxIndicator />
+      </CheckboxRoot>,
+    );
+
+    const indicator = document.querySelector(
+      '[data-slot="checkbox-indicator"]',
+    );
+    expect(indicator).not.toBeNull();
+    // Checkmark path (not the indeterminate dash).
+    expect(indicator?.querySelector('path[d^="M5.252 12.7"]')).not.toBeNull();
+  });
+
+  it("renders the dash indicator when indeterminate", () => {
+    render(
+      <CheckboxRoot indeterminate>
+        <CheckboxIndicator />
+      </CheckboxRoot>,
+    );
+
+    const indicator = document.querySelector(
+      '[data-slot="checkbox-indicator"]',
+    );
+    expect(indicator).not.toBeNull();
+    // Indeterminate dash path.
+    expect(
+      indicator?.querySelector('path[d="M5.252 12h13.496"]'),
+    ).not.toBeNull();
+  });
+
+  it("exposes the Base UI namespace via CheckboxPrimitive", () => {
+    expect(CheckboxPrimitive).toBeDefined();
+    expect(CheckboxPrimitive.Root).toBeDefined();
+    expect(CheckboxPrimitive.Indicator).toBeDefined();
+  });
+});
+
+describe("Checkbox (single composite)", () => {
+  it("renders a bare checkbox when no label or children are provided", () => {
+    render(<Checkbox data-testid="cb" />);
+
+    const cb = screen.getByTestId("cb");
+    expect(cb).toHaveAttribute("data-slot", "checkbox");
+    // No label wrapper.
+    expect(document.querySelector('[data-slot="label"]')).toBeNull();
+  });
+
+  it("renders a label wrapper with the label text", () => {
+    render(<Checkbox label="Accept terms" />);
+
+    expect(screen.getByText("Accept terms")).toBeInTheDocument();
+    const label = document.querySelector('[data-slot="label"]');
+    expect(label).toHaveTextContent("Accept terms");
+  });
+
+  it("falls back to children as the label content", () => {
+    render(<Checkbox>Via children</Checkbox>);
+
+    const label = document.querySelector('[data-slot="label"]');
+    expect(label).toHaveTextContent("Via children");
+  });
+
+  it("associates the label with the checkbox via a generated id", () => {
+    render(<Checkbox label="Linked" />);
+
+    // Base UI applies the id to the hidden native input; the label's htmlFor
+    // points there for native click-to-toggle association.
+    const input = document.querySelector('input[type="checkbox"]');
+    const label = document.querySelector('[data-slot="label"]');
+    expect(input?.getAttribute("id")).toBeTruthy();
+    expect(label).toHaveAttribute("for", input?.getAttribute("id"));
+  });
+
+  it("respects an explicit id over the generated one", () => {
+    render(<Checkbox id="my-id" label="Linked" />);
+
+    expect(document.querySelector('input[type="checkbox"]')).toHaveAttribute(
+      "id",
+      "my-id",
+    );
+    expect(document.querySelector('[data-slot="label"]')).toHaveAttribute(
+      "for",
+      "my-id",
+    );
+  });
+
+  it("reverses the layout when controlFirst is false", () => {
+    render(<Checkbox label="Reversed" controlFirst={false} />);
+
+    const wrapper = document.querySelector('[data-slot="checkbox"]')
+      ?.parentElement;
+    expect(wrapper).toHaveClass("flex-row-reverse");
+  });
+
+  it("does not reverse the layout by default", () => {
+    render(<Checkbox label="Default order" />);
+
+    const wrapper = document.querySelector('[data-slot="checkbox"]')
+      ?.parentElement;
+    expect(wrapper).not.toHaveClass("flex-row-reverse");
+  });
+
+  it("shows the required asterisk on the label", () => {
+    render(<Checkbox label="Required field" required />);
+
+    const label = document.querySelector('[data-slot="label"]');
+    expect(label).toHaveTextContent("*");
+    expect(screen.getByRole("checkbox")).toBeRequired();
+  });
+
+  it("renders a tooltip trigger when tooltip is provided", () => {
+    render(<Checkbox label="With tooltip" tooltip="Helpful hint" />);
+
+    expect(
+      screen.getByRole("button", { name: "Más información" }),
+    ).toBeInTheDocument();
+  });
+
+  it("toggles checked state on click", () => {
+    render(<Checkbox data-testid="cb" />);
+
+    const cb = screen.getByTestId("cb");
+    expect(cb).not.toBeChecked();
+
+    act(() => cb.click());
+    expect(cb).toBeChecked();
+
+    act(() => cb.click());
+    expect(cb).not.toBeChecked();
+  });
+
+  it("honors the disabled prop", () => {
+    render(<Checkbox data-testid="cb" disabled />);
+
+    // The visible role=checkbox element reflects disabled via aria-disabled.
+    expect(screen.getByTestId("cb")).toHaveAttribute("aria-disabled", "true");
+  });
+
+  it("applies className to root and classNames to wrapper/indicator/label", () => {
+    render(
+      <Checkbox
+        defaultChecked
+        label="Styled"
+        className="root-cls"
+        classNames={{
+          wrapper: "wrapper-cls",
+          indicator: "indicator-cls",
+          label: "label-cls",
+        }}
+      />,
+    );
+
+    expect(document.querySelector('[data-slot="checkbox"]')).toHaveClass(
+      "root-cls",
+    );
+    expect(
+      document.querySelector('[data-slot="checkbox"]')?.parentElement,
+    ).toHaveClass("wrapper-cls");
+    expect(
+      document.querySelector('[data-slot="checkbox-indicator"]'),
+    ).toHaveClass("indicator-cls");
+    expect(document.querySelector('[data-slot="label"]')).toHaveClass(
+      "label-cls",
+    );
+  });
+});
+
+describe("Checkbox.Legend", () => {
+  it("renders its children inside a legend", () => {
+    render(<Checkbox.Legend>My legend</Checkbox.Legend>);
+
+    expect(screen.getByText("My legend")).toBeInTheDocument();
+  });
+
+  it("merges a custom className", () => {
+    render(<Checkbox.Legend className="legend-cls">L</Checkbox.Legend>);
+
+    expect(screen.getByText("L")).toHaveClass("legend-cls", "font-medium");
+  });
+});
+
+describe("Checkbox.Item", () => {
+  it("reads controlFirst from group context (reversed)", () => {
+    render(
+      <CheckboxGroupContext.Provider
+        value={{ controlFirst: false, invalid: false }}
+      >
+        <Checkbox.Item value="a" label="Item A" />
+      </CheckboxGroupContext.Provider>,
+    );
+
+    const wrapper = document.querySelector('[data-slot="checkbox"]')
+      ?.parentElement;
+    expect(wrapper).toHaveClass("flex-row-reverse");
+  });
+
+  it("renders label and links it to the checkbox", () => {
+    render(<Checkbox.Item value="a" label="Item A" />);
+
+    const input = document.querySelector('input[type="checkbox"]');
+    const label = document.querySelector('[data-slot="label"]');
+    expect(label).toHaveTextContent("Item A");
+    expect(label).toHaveAttribute("for", input?.getAttribute("id"));
+  });
+
+  it("applies classNames to wrapper, indicator, and label", () => {
+    render(
+      <Checkbox.Item
+        value="a"
+        label="Item A"
+        defaultChecked
+        className="root-cls"
+        classNames={{
+          wrapper: "wrapper-cls",
+          indicator: "indicator-cls",
+          label: "label-cls",
+        }}
+      />,
+    );
+
+    expect(document.querySelector('[data-slot="checkbox"]')).toHaveClass(
+      "root-cls",
+    );
+    expect(
+      document.querySelector('[data-slot="checkbox"]')?.parentElement,
+    ).toHaveClass("wrapper-cls");
+    expect(
+      document.querySelector('[data-slot="checkbox-indicator"]'),
+    ).toHaveClass("indicator-cls");
+    expect(document.querySelector('[data-slot="label"]')).toHaveClass(
+      "label-cls",
+    );
+  });
+});
+
+describe("Checkbox.Group", () => {
+  it("renders the legend when provided", () => {
+    render(
+      <Checkbox.Group legend="Pick some">
+        <Checkbox.Item value="a" label="A" />
+      </Checkbox.Group>,
+    );
+
+    expect(screen.getByText("Pick some")).toBeInTheDocument();
+  });
+
+  it("renders the description when there is no error", () => {
+    render(
+      <Checkbox.Group description="Choose at least one">
+        <Checkbox.Item value="a" label="A" />
+      </Checkbox.Group>,
+    );
+
+    expect(screen.getByText("Choose at least one")).toBeInTheDocument();
+  });
+
+  it("renders the error and hides the description when error is set", () => {
+    render(
+      <Checkbox.Group error="Required" description="Helper text">
+        <Checkbox.Item value="a" label="A" />
+      </Checkbox.Group>,
+    );
+
+    expect(screen.getByText("Required")).toBeInTheDocument();
+    expect(screen.queryByText("Helper text")).not.toBeInTheDocument();
+  });
+
+  it("marks items invalid through context when error is present", () => {
+    render(
+      <Checkbox.Group error="Bad">
+        <Checkbox.Item value="a" label="A" />
+      </Checkbox.Group>,
+    );
+
+    // The invalid context flows through FieldBase.Root and surfaces as
+    // data-invalid on the control (Base UI's invalid-state hook).
+    expect(screen.getByRole("checkbox")).toHaveAttribute("data-invalid");
+  });
+
+  it("fires onValueChange when an item is toggled", async () => {
+    const onValueChange = vi.fn();
+    render(
+      <Checkbox.Group onValueChange={onValueChange}>
+        <Checkbox.Item value="a" label="A" />
+        <Checkbox.Item value="b" label="B" />
+      </Checkbox.Group>,
+    );
+
+    await userEvent.click(screen.getByRole("checkbox", { name: "A" }));
+
+    expect(onValueChange).toHaveBeenCalledTimes(1);
+    // Base UI passes event details as a second argument.
+    expect(onValueChange.mock.calls[0][0]).toEqual(["a"]);
+  });
+
+  it("reflects defaultValue as checked items", () => {
+    render(
+      <Checkbox.Group defaultValue={["b"]}>
+        <Checkbox.Item value="a" label="A" />
+        <Checkbox.Item value="b" label="B" />
+      </Checkbox.Group>,
+    );
+
+    expect(screen.getByRole("checkbox", { name: "A" })).not.toBeChecked();
+    expect(screen.getByRole("checkbox", { name: "B" })).toBeChecked();
+  });
+
+  it("disables all items when disabled", () => {
+    render(
+      <Checkbox.Group disabled>
+        <Checkbox.Item value="a" label="A" />
+      </Checkbox.Group>,
+    );
+
+    expect(screen.getByRole("checkbox")).toHaveAttribute(
+      "aria-disabled",
+      "true",
+    );
+  });
+
+  it("reverses item layout via controlFirst=false", () => {
+    render(
+      <Checkbox.Group controlFirst={false}>
+        <Checkbox.Item value="a" label="A" />
+      </Checkbox.Group>,
+    );
+
+    const wrapper = document.querySelector('[data-slot="checkbox"]')
+      ?.parentElement;
+    expect(wrapper).toHaveClass("flex-row-reverse");
+  });
+
+  it("applies className and classNames slots", () => {
+    render(
+      <Checkbox.Group
+        legend="Legend"
+        error="Err"
+        className="group-cls"
+        classNames={{
+          legend: "legend-cls",
+          items: "items-cls",
+          error: "error-cls",
+        }}
+      >
+        <Checkbox.Item value="a" label="A" />
+      </Checkbox.Group>,
+    );
+
+    expect(screen.getByText("Legend")).toHaveClass("legend-cls");
+    expect(screen.getByText("Err")).toHaveClass("error-cls");
+  });
+
+  it("applies the description classNames slot when no error", () => {
+    render(
+      <Checkbox.Group
+        description="Desc"
+        classNames={{ description: "desc-cls" }}
+      >
+        <Checkbox.Item value="a" label="A" />
+      </Checkbox.Group>,
+    );
+
+    expect(screen.getByText("Desc")).toHaveClass("desc-cls");
+  });
+});

package/src/components/checkbox/checkbox.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import { Checkbox as CheckboxPrimitive } from "@base-ui/react/checkbox";
 import { CheckboxGroup as CheckboxGroupPrimitive } from "@base-ui/react/checkbox-group";
 import { Field as FieldBase } from "@base-ui/react/field";

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

@@ -0,0 +1,156 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it, vi } from "vitest";
+import { Checkbox, CheckboxGroup, CheckboxGroupRoot } from "../../components";
+import { Field } from "../field/field";
+
+const options = [
+  { value: "a", label: "Option A" },
+  { value: "b", label: "Option B" },
+  { value: "c", label: "Option C", disabled: true },
+];
+
+describe("CheckboxGroupRoot primitive", () => {
+  it("renders with the checkbox-group slot and merges className", () => {
+    render(<CheckboxGroupRoot className="extra" data-testid="root" />);
+
+    const root = screen.getByTestId("root");
+    expect(root).toHaveAttribute("data-slot", "checkbox-group");
+    expect(root).toHaveClass("extra", "flex-col");
+  });
+});
+
+describe("CheckboxGroup composite", () => {
+  it("renders one checkbox per item from the items prop", () => {
+    render(<CheckboxGroup items={options} />);
+
+    expect(screen.getAllByRole("checkbox")).toHaveLength(3);
+    expect(screen.getByText("Option A")).toBeInTheDocument();
+    expect(screen.getByText("Option B")).toBeInTheDocument();
+    expect(screen.getByText("Option C")).toBeInTheDocument();
+  });
+
+  it("disables an item flagged as disabled", () => {
+    render(<CheckboxGroup items={options} />);
+
+    expect(screen.getByRole("checkbox", { name: "Option C" })).toHaveAttribute(
+      "aria-disabled",
+      "true",
+    );
+  });
+
+  it("renders children when no items prop is given", () => {
+    render(
+      <CheckboxGroup>
+        <Checkbox.Item value="x" label="Child X" />
+        <Checkbox.Item value="y" label="Child Y" />
+      </CheckboxGroup>,
+    );
+
+    expect(screen.getAllByRole("checkbox")).toHaveLength(2);
+    expect(screen.getByText("Child X")).toBeInTheDocument();
+  });
+
+  it("renders the legend when provided", () => {
+    render(<CheckboxGroup legend="Pick options" items={options} />);
+
+    expect(screen.getByText("Pick options")).toBeInTheDocument();
+  });
+
+  it("does not render a legend when omitted", () => {
+    render(<CheckboxGroup items={options} />);
+
+    expect(
+      document.querySelector('[data-slot="fieldset-legend"]'),
+    ).toBeNull();
+  });
+
+  it("fires onValueChange when an item is toggled", async () => {
+    const onValueChange = vi.fn();
+    render(<CheckboxGroup items={options} onValueChange={onValueChange} />);
+
+    await userEvent.click(screen.getByRole("checkbox", { name: "Option A" }));
+
+    expect(onValueChange).toHaveBeenCalledTimes(1);
+    expect(onValueChange.mock.calls[0][0]).toEqual(["a"]);
+  });
+
+  it("reflects defaultValue as checked items", () => {
+    render(<CheckboxGroup items={options} defaultValue={["b"]} />);
+
+    expect(
+      screen.getByRole("checkbox", { name: "Option A" }),
+    ).not.toBeChecked();
+    expect(screen.getByRole("checkbox", { name: "Option B" })).toBeChecked();
+  });
+
+  it("supports a controlled value", () => {
+    render(<CheckboxGroup items={options} value={["a", "c"]} />);
+
+    expect(screen.getByRole("checkbox", { name: "Option A" })).toBeChecked();
+    expect(screen.getByRole("checkbox", { name: "Option C" })).toBeChecked();
+    expect(
+      screen.getByRole("checkbox", { name: "Option B" }),
+    ).not.toBeChecked();
+  });
+
+  it("disables every item when the group is disabled", () => {
+    render(<CheckboxGroup items={options} disabled />);
+
+    for (const cb of screen.getAllByRole("checkbox")) {
+      expect(cb).toHaveAttribute("aria-disabled", "true");
+    }
+  });
+
+  it("reverses item layout when controlFirst is false", () => {
+    render(
+      <CheckboxGroup controlFirst={false}>
+        <Checkbox.Item value="x" label="X" />
+      </CheckboxGroup>,
+    );
+
+    const wrapper = document.querySelector('[data-slot="checkbox"]')
+      ?.parentElement;
+    expect(wrapper).toHaveClass("flex-row-reverse");
+  });
+
+  it("merges a custom className onto the fieldset", () => {
+    render(<CheckboxGroup className="group-cls" items={options} />);
+
+    expect(document.querySelector('[data-slot="fieldset"]')).toHaveClass(
+      "group-cls",
+    );
+  });
+
+  it("renders standalone (not inside a Field) by default", () => {
+    render(<CheckboxGroup items={options} />);
+
+    // Both the fieldset and the Base UI CheckboxGroup wrapper expose role=group.
+    expect(screen.getAllByRole("group").length).toBeGreaterThanOrEqual(1);
+    expect(screen.getAllByRole("checkbox")).toHaveLength(3);
+  });
+
+  it("integrates with a surrounding Field (valid state)", () => {
+    render(
+      <Field label="Preferences">
+        <CheckboxGroup items={options} />
+      </Field>,
+    );
+
+    expect(screen.getByText("Preferences")).toBeInTheDocument();
+    expect(screen.getAllByRole("checkbox")).toHaveLength(3);
+  });
+
+  it("integrates with a surrounding Field flagged invalid", () => {
+    render(
+      <Field label="Preferences" invalid>
+        <CheckboxGroup items={options} />
+      </Field>,
+    );
+
+    // The invalid field state flows into the items as data-invalid.
+    expect(
+      screen.getByRole("checkbox", { name: "Option A" }),
+    ).toHaveAttribute("data-invalid");
+  });
+});

package/src/components/checkbox-group/checkbox-group.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import { CheckboxGroup as CheckboxGroupPrimitive } from "@base-ui/react/checkbox-group";
 import { type ReactNode } from "react";
 import { cn } from "../../lib";