@boxcustodia/library 2.0.0-alpha.2 → 2.0.0-alpha.20

package/src/components/checkbox/checkbox.tsx

@@ -0,0 +1,336 @@
+"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";
+import { Fieldset } from "@base-ui/react/fieldset";
+import type * as React from "react";
+import { createContext, type ReactNode, useContext, useId } from "react";
+import { cn } from "../../lib";
+import { Label } from "../label";
+
+// ── Primitives ─────────────────────────────────────────────────────────────────
+
+export function CheckboxRoot({
+  className,
+  ...props
+}: CheckboxPrimitive.Root.Props): React.ReactElement {
+  return (
+    <CheckboxPrimitive.Root
+      className={cn(
+        "peer relative inline-flex size-4.5 shrink-0 items-center justify-center rounded-[.25rem] border border-input bg-background not-dark:bg-clip-padding shadow-xs/5 outline-none ring-ring transition-shadow",
+        "before:pointer-events-none before:absolute before:inset-0 before:rounded-[3px]",
+        "not-data-disabled:not-data-checked:not-aria-invalid:before:shadow-[0_1px_--theme(--color-black/4%)]",
+        "focus-visible:ring-2 focus-visible:ring-offset-1 focus-visible:ring-offset-background",
+        "aria-invalid:border-error focus-visible:aria-invalid:border-error focus-visible:aria-invalid:ring-error",
+        "data-disabled:cursor-not-allowed data-disabled:opacity-64",
+        "sm:size-4",
+        "dark:not-data-disabled:not-data-checked:not-aria-invalid:before:shadow-[0_-1px_--theme(--color-white/6%)]",
+        "[[data-disabled],[data-checked],[aria-invalid]]:shadow-none",
+        className,
+      )}
+      data-slot="checkbox"
+      {...props}
+    />
+  );
+}
+
+export function CheckboxIndicator({
+  className,
+  ...props
+}: CheckboxPrimitive.Indicator.Props): React.ReactElement {
+  return (
+    <CheckboxPrimitive.Indicator
+      className={cn(
+        "absolute -inset-px flex items-center justify-center rounded-[.25rem] text-primary-foreground",
+        "data-unchecked:hidden data-checked:bg-primary data-indeterminate:text-foreground",
+        className,
+      )}
+      data-slot="checkbox-indicator"
+      render={(
+        renderProps: React.ComponentProps<"span">,
+        state: CheckboxPrimitive.Indicator.State,
+      ) => (
+        <span {...renderProps}>
+          {state.indeterminate ? (
+            <svg
+              aria-hidden="true"
+              className="size-3.5 sm:size-3"
+              fill="none"
+              height="24"
+              stroke="currentColor"
+              strokeLinecap="round"
+              strokeLinejoin="round"
+              strokeWidth="3"
+              viewBox="0 0 24 24"
+              width="24"
+              xmlns="http://www.w3.org/2000/svg"
+            >
+              <path d="M5.252 12h13.496" />
+            </svg>
+          ) : (
+            <svg
+              aria-hidden="true"
+              className="size-3.5 sm:size-3"
+              fill="none"
+              height="24"
+              stroke="currentColor"
+              strokeLinecap="round"
+              strokeLinejoin="round"
+              strokeWidth="3"
+              viewBox="0 0 24 24"
+              width="24"
+              xmlns="http://www.w3.org/2000/svg"
+            >
+              <path d="M5.252 12.7 10.2 18.63 18.748 5.37" />
+            </svg>
+          )}
+        </span>
+      )}
+      {...props}
+    />
+  );
+}
+
+// ── Group context ──────────────────────────────────────────────────────────────
+
+export const CheckboxGroupContext = createContext<{
+  controlFirst: boolean;
+  invalid: boolean;
+}>({
+  controlFirst: true,
+  invalid: false,
+});
+
+// ── Composite: Checkbox (single) ───────────────────────────────────────────────
+
+interface CheckboxProps extends Omit<CheckboxPrimitive.Root.Props, "children"> {
+  children?: ReactNode;
+  label?: ReactNode;
+  tooltip?: ReactNode;
+  controlFirst?: boolean;
+  /** Styles applied to each internal slot. */
+  classNames?: {
+    /** Flex wrapper around checkbox and label (only rendered when a label is provided). */
+    wrapper?: string;
+    /** Checkmark indicator inside the checkbox. */
+    indicator?: string;
+    /** Label element next to the checkbox. */
+    label?: string;
+  };
+}
+
+function CheckboxSingle({
+  className,
+  classNames,
+  label,
+  children,
+  tooltip,
+  controlFirst = true,
+  required,
+  id,
+  ...props
+}: CheckboxProps): React.ReactElement {
+  const generatedId = useId();
+  const idToUse = id ?? generatedId;
+  const labelContent = label ?? children;
+
+  const checkbox = (
+    <CheckboxRoot
+      id={idToUse}
+      className={className}
+      required={required}
+      {...props}
+    >
+      <CheckboxIndicator className={classNames?.indicator} />
+    </CheckboxRoot>
+  );
+
+  if (labelContent !== undefined) {
+    return (
+      <div
+        className={cn(
+          "flex select-none items-center gap-x-2",
+          !controlFirst && "flex-row-reverse justify-end",
+          classNames?.wrapper,
+        )}
+      >
+        {checkbox}
+        <Label
+          htmlFor={idToUse}
+          required={required}
+          tooltip={tooltip}
+          className={classNames?.label}
+        >
+          {labelContent}
+        </Label>
+      </div>
+    );
+  }
+
+  return checkbox;
+}
+
+// ── Composite: Checkbox.Item (for use in Checkbox.Group) ──────────────────────
+
+export interface CheckboxItemProps
+  extends Omit<CheckboxPrimitive.Root.Props, "children"> {
+  label: ReactNode;
+  /** Styles applied to each internal slot. */
+  classNames?: {
+    /** Flex wrapper around checkbox and label. */
+    wrapper?: string;
+    /** Checkmark indicator inside the checkbox. */
+    indicator?: string;
+    /** Label element next to the checkbox. */
+    label?: string;
+  };
+}
+
+function CheckboxItem({
+  className,
+  classNames,
+  label,
+  id,
+  ...props
+}: CheckboxItemProps): React.ReactElement {
+  const { controlFirst, invalid } = useContext(CheckboxGroupContext);
+  const generatedId = useId();
+  const idToUse = id ?? generatedId;
+
+  return (
+    <FieldBase.Root invalid={invalid}>
+      <div
+        className={cn(
+          "flex select-none items-center gap-x-2",
+          !controlFirst && "flex-row-reverse justify-end",
+          classNames?.wrapper,
+        )}
+      >
+        <CheckboxRoot id={idToUse} className={className} {...props}>
+          <CheckboxIndicator className={classNames?.indicator} />
+        </CheckboxRoot>
+        <Label htmlFor={idToUse} className={classNames?.label}>
+          {label}
+        </Label>
+      </div>
+    </FieldBase.Root>
+  );
+}
+
+// ── Composite: Checkbox.Legend ─────────────────────────────────────────────────
+
+export interface CheckboxLegendProps {
+  children: ReactNode;
+  className?: string;
+}
+
+function CheckboxLegend({
+  children,
+  className,
+}: CheckboxLegendProps): React.ReactElement {
+  return (
+    <Fieldset.Legend
+      className={cn("text-sm font-medium leading-none", className)}
+    >
+      {children}
+    </Fieldset.Legend>
+  );
+}
+
+// ── Composite: Checkbox.Group ──────────────────────────────────────────────────
+
+interface CheckboxGroupProps {
+  legend?: ReactNode;
+  children: ReactNode;
+  error?: string;
+  description?: ReactNode;
+  defaultValue?: string[];
+  value?: string[];
+  onValueChange?: (value: string[]) => void;
+  allValues?: string[];
+  disabled?: boolean;
+  controlFirst?: boolean;
+  className?: string;
+  /** Styles applied to each internal slot. */
+  classNames?: {
+    /** Legend element above the items. */
+    legend?: string;
+    /** Wrapper around the rendered children (items). */
+    items?: string;
+    /** Description shown below the items when there is no error. */
+    description?: string;
+    /** Error message shown below the items. */
+    error?: string;
+  };
+}
+
+function CheckboxGroup({
+  legend,
+  children,
+  error,
+  description,
+  defaultValue,
+  value,
+  onValueChange,
+  allValues,
+  disabled,
+  controlFirst = true,
+  className,
+  classNames,
+}: CheckboxGroupProps): React.ReactElement {
+  return (
+    <CheckboxGroupContext.Provider value={{ controlFirst, invalid: !!error }}>
+      <CheckboxGroupPrimitive
+        defaultValue={defaultValue}
+        value={value}
+        onValueChange={onValueChange}
+        allValues={allValues}
+        disabled={disabled}
+      >
+        <Fieldset.Root className={cn("flex flex-col gap-3", className)}>
+          {legend && (
+            <CheckboxLegend className={classNames?.legend}>
+              {legend}
+            </CheckboxLegend>
+          )}
+          <div className={cn("flex flex-col gap-2", classNames?.items)}>
+            {children}
+          </div>
+          {error && (
+            <p
+              className={cn(
+                "text-sm font-medium text-error",
+                classNames?.error,
+              )}
+            >
+              {error}
+            </p>
+          )}
+          {!error && description && (
+            <p
+              className={cn(
+                "text-sm text-muted-foreground",
+                classNames?.description,
+              )}
+            >
+              {description}
+            </p>
+          )}
+        </Fieldset.Root>
+      </CheckboxGroupPrimitive>
+    </CheckboxGroupContext.Provider>
+  );
+}
+
+// ── Compound export ────────────────────────────────────────────────────────────
+
+export const Checkbox = Object.assign(CheckboxSingle, {
+  Item: CheckboxItem,
+  Group: CheckboxGroup,
+  Legend: CheckboxLegend,
+});
+
+// ── Primitive escape hatch ─────────────────────────────────────────────────────
+
+export { CheckboxPrimitive };

package/src/components/checkbox/index.ts

@@ -0,0 +1 @@
+export * from "./checkbox";

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

@@ -0,0 +1,192 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { useState } from "react";
+import { Button } from "../button/button";
+import { Checkbox } from "../checkbox";
+import { Field } from "../field/field";
+import { Form } from "../form/form";
+import { CheckboxGroup, CheckboxGroupRoot } from "./checkbox-group";
+
+/**
+ * CheckboxGroup manages a set of checkboxes as a single `string[]` value.
+ * Built on `@base-ui/react/checkbox-group`.
+ *
+ * Designed to be used inside `Field` — `Field` provides the label, description,
+ * and error handling.
+ *
+ * **90% case** — pass `items` and let the composite render all checkboxes:
+ * ```tsx
+ * <CheckboxGroup
+ *   items={[{ value: "email", label: "Email" }, { value: "sms", label: "SMS" }]}
+ *   onValueChange={(values) => console.log(values)}
+ * />
+ * ```
+ *
+ * **Compound API** for custom layouts (parent checkbox, custom ordering):
+ * ```tsx
+ * <CheckboxGroup allValues={allValues} value={value} onValueChange={setValue}>
+ *   <Checkbox parent />
+ *   <Checkbox.Item value="email" label="Email" />
+ * </CheckboxGroup>
+ * ```
+ *
+ * Use `onValueChange` to react to selection changes.
+ *
+ * Pass `allValues` to enable the parent checkbox pattern: a `Checkbox` with
+ * `parent` computes checked/unchecked/indeterminate automatically.
+ *
+ * Reference: [CheckboxGroup – Base UI](https://base-ui.com/react/components/checkbox-group)
+ */
+const meta: Meta<typeof CheckboxGroup> = {
+  title: "Components/CheckboxGroup",
+  component: CheckboxGroup,
+  parameters: { layout: "centered" },
+  argTypes: {
+    children: { control: false },
+    items: { control: false },
+    onValueChange: { control: false },
+  },
+  tags: ["new"],
+};
+
+export default meta;
+type Story = StoryObj<typeof CheckboxGroup>;
+
+const NOTIFICATIONS = [
+  { label: "Comments on my posts", value: "comments" },
+  { label: "Mentions", value: "mentions" },
+  { label: "Direct messages", value: "messages" },
+  { label: "System updates", value: "system" },
+];
+
+export const Default: Story = {
+  render: (args) => (
+    <CheckboxGroup
+      {...args}
+      items={NOTIFICATIONS}
+      defaultValue={["comments"]}
+    />
+  ),
+};
+
+/**
+ * `value` + `onValueChange` for controlled mode.
+ */
+export const Controlled: Story = {
+  render: (args) => {
+    const [value, setValue] = useState<string[]>(["comments", "mentions"]);
+    return (
+      <div className="space-y-4">
+        <CheckboxGroup
+          {...args}
+          items={NOTIFICATIONS}
+          value={value}
+          onValueChange={setValue}
+        />
+        <p className="text-sm text-muted-foreground">
+          Active: {value.length > 0 ? value.join(", ") : "none"}
+        </p>
+      </div>
+    );
+  },
+};
+
+/**
+ * `allValues` enables the parent checkbox pattern. The `Checkbox` with `parent`
+ * computes its state automatically: checked when all items are selected,
+ * unchecked when none, indeterminate on partial selection — no manual state
+ * needed.
+ */
+export const WithParent: Story = {
+  render: (args) => {
+    const allValues = NOTIFICATIONS.map((n) => n.value);
+    const [value, setValue] = useState<string[]>(["comments"]);
+
+    return (
+      <CheckboxGroup
+        {...args}
+        value={value}
+        onValueChange={setValue}
+        allValues={allValues}
+      >
+        <div className="flex items-center gap-2">
+          <Checkbox parent />
+          <span className="select-none text-sm">Enable all notifications</span>
+        </div>
+        <div className="ml-6 flex flex-col gap-3 border-l-2 pl-4">
+          {NOTIFICATIONS.map(({ label, value: v }) => (
+            <Checkbox.Item key={v} value={v} label={label} />
+          ))}
+        </div>
+      </CheckboxGroup>
+    );
+  },
+};
+
+export const Disabled: Story = {
+  render: (args) => (
+    <CheckboxGroup
+      {...args}
+      items={NOTIFICATIONS}
+      defaultValue={["comments"]}
+      disabled
+    />
+  ),
+};
+
+/**
+ * Wrap `CheckboxGroup` with `Field` to add a label, description, and error
+ * handling. Since `CheckboxGroup` has no native `required`, use `Field`'s
+ * `validate` prop — it receives the current `string[]` and runs on submit.
+ * Return a string to show an error, `null` to pass.
+ */
+export const WithForm: Story = {
+  render: () => {
+    const [submitted, setSubmitted] = useState<string[] | null>(null);
+
+    return (
+      <Form
+        className="flex w-80 flex-col gap-4"
+        onFormSubmit={(data) => setSubmitted(data.notifications as string[])}
+      >
+        <Field
+          name="notifications"
+          label="Notifications"
+          required
+          description="Select the notifications you want to receive."
+          validate={(value) =>
+            Array.isArray(value) && value.length === 0
+              ? "Select at least one notification."
+              : null
+          }
+        >
+          <CheckboxGroup items={NOTIFICATIONS} />
+        </Field>
+        <Button type="submit">Submit</Button>
+        {submitted && (
+          <pre className="rounded-md bg-muted p-3 text-xs">
+            {JSON.stringify(submitted, null, 2)}
+          </pre>
+        )}
+      </Form>
+    );
+  },
+};
+
+/**
+ * Direct composition with the primitive for full structural control.
+ *
+ * ```tsx
+ * <CheckboxGroupRoot allValues={allValues}>
+ *   <Checkbox.Item value="email" label="Email" />
+ * </CheckboxGroupRoot>
+ * ```
+ */
+export const Primitive: Story = {
+  render: () => (
+    <CheckboxGroupRoot defaultValue={["comments"]}>
+      {NOTIFICATIONS.map(({ label, value }) => (
+        <Checkbox.Item key={value} value={value} label={label} />
+      ))}
+    </CheckboxGroupRoot>
+  ),
+};

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

@@ -0,0 +1,155 @@
+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",
+    );
+  });
+});