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

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

@@ -0,0 +1,323 @@
+import { render, renderHook, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import {
+  Field,
+  FieldControl,
+  FieldDescription,
+  FieldError,
+  FieldItem,
+  FieldLabel,
+  FieldLegend,
+  FieldPrimitive,
+  FieldRoot,
+  FieldSet,
+  FieldsetPrimitive,
+  FieldValidity,
+  normalizeError,
+  useFieldName,
+  useIsInsideFieldRoot,
+} from "../../components";
+
+// ── normalizeError ────────────────────────────────────────────────────────────
+
+describe("normalizeError", () => {
+  it("returns [] for undefined", () => {
+    expect(normalizeError(undefined)).toEqual([]);
+  });
+
+  it("wraps a string with match: true", () => {
+    expect(normalizeError("Required")).toEqual([
+      { message: "Required", match: true },
+    ]);
+  });
+
+  it("wraps a single FieldErrorItem in an array", () => {
+    const item = { message: "Too short", match: "tooShort" as const };
+    expect(normalizeError(item)).toEqual([item]);
+  });
+
+  it("returns an array as-is", () => {
+    const items = [
+      { message: "Required", match: "valueMissing" as const },
+      { message: "Bad email", match: "typeMismatch" as const },
+    ];
+    expect(normalizeError(items)).toBe(items);
+  });
+});
+
+// ── Context hooks ──────────────────────────────────────────────────────────
+
+describe("useIsInsideFieldRoot", () => {
+  it("returns false outside FieldRoot", () => {
+    const { result } = renderHook(() => useIsInsideFieldRoot());
+    expect(result.current).toBe(false);
+  });
+
+  it("returns true inside FieldRoot", () => {
+    const { result } = renderHook(() => useIsInsideFieldRoot(), {
+      wrapper: ({ children }) => <FieldRoot name="test">{children}</FieldRoot>,
+    });
+    expect(result.current).toBe(true);
+  });
+});
+
+describe("useFieldName", () => {
+  it("returns undefined outside FieldRoot", () => {
+    const { result } = renderHook(() => useFieldName());
+    expect(result.current).toBeUndefined();
+  });
+
+  it("returns the name provided to FieldRoot", () => {
+    const { result } = renderHook(() => useFieldName(), {
+      wrapper: ({ children }) => <FieldRoot name="email">{children}</FieldRoot>,
+    });
+    expect(result.current).toBe("email");
+  });
+});
+
+// ── Primitives ────────────────────────────────────────────────────────────────
+
+describe("FieldRoot", () => {
+  it("renders with data-slot='field'", () => {
+    render(<FieldRoot name="x" />);
+    expect(document.querySelector('[data-slot="field"]')).toBeInTheDocument();
+  });
+
+  it("sets data-required when required prop is true", () => {
+    render(<FieldRoot name="x" required />);
+    expect(document.querySelector('[data-slot="field"]')).toHaveAttribute(
+      "data-required",
+    );
+  });
+
+  it("does not set data-required when required is absent", () => {
+    render(<FieldRoot name="x" />);
+    expect(document.querySelector('[data-slot="field"]')).not.toHaveAttribute(
+      "data-required",
+    );
+  });
+
+  it("forwards className", () => {
+    render(<FieldRoot name="x" className="field-cls" />);
+    expect(document.querySelector('[data-slot="field"]')).toHaveClass(
+      "field-cls",
+    );
+  });
+});
+
+describe("FieldLabel", () => {
+  it("renders with data-slot='field-label'", () => {
+    render(
+      <FieldRoot name="x">
+        <FieldLabel>Label</FieldLabel>
+      </FieldRoot>,
+    );
+    expect(
+      document.querySelector('[data-slot="field-label"]'),
+    ).toBeInTheDocument();
+  });
+});
+
+describe("FieldItem", () => {
+  it("renders with data-slot='field-item'", () => {
+    render(
+      <FieldRoot name="x">
+        <FieldItem>Item</FieldItem>
+      </FieldRoot>,
+    );
+    expect(
+      document.querySelector('[data-slot="field-item"]'),
+    ).toBeInTheDocument();
+  });
+});
+
+describe("FieldDescription", () => {
+  it("renders with data-slot='field-description'", () => {
+    render(
+      <FieldRoot name="x">
+        <FieldDescription>Helper text</FieldDescription>
+      </FieldRoot>,
+    );
+    expect(
+      document.querySelector('[data-slot="field-description"]'),
+    ).toBeInTheDocument();
+  });
+});
+
+describe("FieldError", () => {
+  it("is exported and defined", () => {
+    expect(FieldError).toBeDefined();
+  });
+});
+
+describe("FieldSet", () => {
+  it("renders with data-slot='fieldset'", () => {
+    render(<FieldSet />);
+    expect(
+      document.querySelector('[data-slot="fieldset"]'),
+    ).toBeInTheDocument();
+  });
+});
+
+describe("FieldLegend", () => {
+  it("renders with data-slot='fieldset-legend'", () => {
+    render(
+      <FieldSet>
+        <FieldLegend>Legend</FieldLegend>
+      </FieldSet>,
+    );
+    expect(
+      document.querySelector('[data-slot="fieldset-legend"]'),
+    ).toBeInTheDocument();
+  });
+});
+
+describe("FieldControl / FieldValidity / FieldPrimitive / FieldsetPrimitive exports", () => {
+  it("FieldControl is exported and defined", () => {
+    expect(FieldControl).toBeDefined();
+  });
+
+  it("FieldValidity is exported and defined", () => {
+    expect(FieldValidity).toBeDefined();
+  });
+
+  it("FieldPrimitive is exported and defined", () => {
+    expect(FieldPrimitive).toBeDefined();
+  });
+
+  it("FieldsetPrimitive is exported and defined", () => {
+    expect(FieldsetPrimitive).toBeDefined();
+  });
+});
+
+// ── Field composite ───────────────────────────────────────────────────────────
+
+describe("Field composite", () => {
+  it("renders root with data-slot='field'", () => {
+    render(<Field />);
+    expect(document.querySelector('[data-slot="field"]')).toBeInTheDocument();
+  });
+
+  it("renders children", () => {
+    render(
+      <Field>
+        <input placeholder="ctrl" />
+      </Field>,
+    );
+    expect(screen.getByPlaceholderText("ctrl")).toBeInTheDocument();
+  });
+
+  it("renders label when label prop is provided", () => {
+    render(<Field label="Email" />);
+    expect(screen.getByText("Email")).toBeInTheDocument();
+    expect(
+      document.querySelector('[data-slot="field-label"]'),
+    ).toBeInTheDocument();
+  });
+
+  it("does not render label when label is absent", () => {
+    render(<Field />);
+    expect(
+      document.querySelector('[data-slot="field-label"]'),
+    ).not.toBeInTheDocument();
+  });
+
+  it("renders description when provided", () => {
+    render(<Field description="Helper text" />);
+    expect(screen.getByText("Helper text")).toBeInTheDocument();
+    expect(
+      document.querySelector('[data-slot="field-description"]'),
+    ).toBeInTheDocument();
+  });
+
+  it("does not render description when absent", () => {
+    render(<Field />);
+    expect(
+      document.querySelector('[data-slot="field-description"]'),
+    ).not.toBeInTheDocument();
+  });
+
+  it("sets data-required when required is true", () => {
+    render(<Field required />);
+    expect(document.querySelector('[data-slot="field"]')).toHaveAttribute(
+      "data-required",
+    );
+  });
+
+  it("renders inline layout when inline=true", () => {
+    render(
+      <Field inline label="Accept" data-testid="field">
+        <input type="checkbox" />
+      </Field>,
+    );
+    const checkbox = screen.getByRole("checkbox");
+    const label = document.querySelector('[data-slot="field-label"]');
+    expect(checkbox).toBeInTheDocument();
+    expect(label).toBeInTheDocument();
+    // In inline mode both are siblings inside a flex div
+    expect(checkbox.parentElement).toBe(label!.parentElement);
+  });
+
+  it("renders stacked layout when inline=false (default)", () => {
+    render(
+      <Field label="Name">
+        <input placeholder="name" />
+      </Field>,
+    );
+    const field = document.querySelector('[data-slot="field"]');
+    const label = document.querySelector('[data-slot="field-label"]');
+    // label is a direct child of the field root (not wrapped in inline div)
+    expect(label!.parentElement).toBe(field);
+  });
+
+  it("applies classNames.label to the label slot", () => {
+    render(<Field label="Email" classNames={{ label: "lbl-cls" }} />);
+    expect(document.querySelector('[data-slot="field-label"]')).toHaveClass(
+      "lbl-cls",
+    );
+  });
+
+  it("applies classNames.description to the description slot", () => {
+    render(
+      <Field description="Helper" classNames={{ description: "desc-cls" }} />,
+    );
+    expect(
+      document.querySelector('[data-slot="field-description"]'),
+    ).toHaveClass("desc-cls");
+  });
+
+  it("accepts error as an array of FieldErrorItem without crashing", () => {
+    render(
+      <Field
+        name="email"
+        invalid
+        error={[
+          { message: "Required", match: "valueMissing" },
+          { message: "Bad email", match: "typeMismatch" },
+        ]}
+      />,
+    );
+    expect(document.querySelector('[data-slot="field"]')).toBeInTheDocument();
+  });
+
+  it("marks field as invalid when error string is provided", () => {
+    render(<Field name="x" error="Enter a valid value." />);
+    expect(document.querySelector('[data-slot="field"]')).toHaveAttribute(
+      "data-invalid",
+    );
+  });
+
+  it("marks field as invalid when invalid prop is true", () => {
+    render(<Field name="x" invalid />);
+    expect(document.querySelector('[data-slot="field"]')).toHaveAttribute(
+      "data-invalid",
+    );
+  });
+
+  it("forwards className to root", () => {
+    render(<Field className="root-cls" />);
+    expect(document.querySelector('[data-slot="field"]')).toHaveClass(
+      "root-cls",
+    );
+  });
+});

package/src/components/field/field.tsx

@@ -0,0 +1,266 @@
+"use client";
+
+import { Field as FieldPrimitive } from "@base-ui/react/field";
+import { Fieldset as FieldsetPrimitive } from "@base-ui/react/fieldset";
+import { createContext, type ReactNode, useContext } from "react";
+import { cn } from "../../lib";
+import { Label } from "../label";
+
+// ── Types ─────────────────────────────────────────────────────────────────────
+
+export type FieldErrorMatch = FieldPrimitive.Error.Props["match"];
+
+export type FieldErrorItem = {
+  message: ReactNode;
+  match?: NonNullable<FieldErrorMatch>;
+};
+
+export type FieldErrorProp = string | FieldErrorItem | FieldErrorItem[];
+
+// ── Primitives ────────────────────────────────────────────────────────────────
+
+const FieldNameContext = createContext<string | undefined>(undefined);
+export function useFieldName(): string | undefined {
+  return useContext(FieldNameContext);
+}
+
+const FieldRootPresentContext = createContext(false);
+export function useIsInsideFieldRoot(): boolean {
+  return useContext(FieldRootPresentContext);
+}
+
+export function FieldRoot({
+  className,
+  required,
+  name,
+  ...props
+}: FieldPrimitive.Root.Props & { required?: boolean }) {
+  return (
+    <FieldRootPresentContext.Provider value={true}>
+      <FieldNameContext.Provider value={name}>
+        <FieldPrimitive.Root
+          name={name}
+          className={cn("group flex flex-col gap-1", className)}
+          data-slot="field"
+          data-required={required || undefined}
+          {...props}
+        />
+      </FieldNameContext.Provider>
+    </FieldRootPresentContext.Provider>
+  );
+}
+
+export function FieldLabel({
+  className,
+  ...props
+}: FieldPrimitive.Label.Props) {
+  return (
+    <FieldPrimitive.Label
+      className={cn(
+        "inline-flex items-center font-medium text-base/4.5 text-foreground data-disabled:opacity-64 sm:text-sm/4",
+        className,
+      )}
+      data-slot="field-label"
+      {...props}
+    />
+  );
+}
+
+export function FieldItem({ className, ...props }: FieldPrimitive.Item.Props) {
+  return (
+    <FieldPrimitive.Item
+      className={cn("flex items-center gap-2", className)}
+      data-slot="field-item"
+      {...props}
+    />
+  );
+}
+
+export function FieldDescription({
+  className,
+  ...props
+}: FieldPrimitive.Description.Props) {
+  return (
+    <FieldPrimitive.Description
+      className={cn(
+        "text-muted-foreground text-xs group-data-[invalid]:hidden",
+        className,
+      )}
+      data-slot="field-description"
+      {...props}
+    />
+  );
+}
+
+export function FieldError({
+  className,
+  ...props
+}: FieldPrimitive.Error.Props) {
+  return (
+    <FieldPrimitive.Error
+      className={cn("text-error text-xs", className)}
+      data-slot="field-error"
+      {...props}
+    />
+  );
+}
+
+export const FieldControl: typeof FieldPrimitive.Control =
+  FieldPrimitive.Control;
+export const FieldValidity: typeof FieldPrimitive.Validity =
+  FieldPrimitive.Validity;
+
+export function FieldSet({
+  className,
+  ...props
+}: FieldsetPrimitive.Root.Props) {
+  return (
+    <FieldsetPrimitive.Root
+      className={cn("flex flex-col gap-3", className)}
+      data-slot="fieldset"
+      {...props}
+    />
+  );
+}
+
+export function FieldLegend({
+  className,
+  ...props
+}: FieldsetPrimitive.Legend.Props) {
+  return (
+    <FieldsetPrimitive.Legend
+      className={cn("text-sm font-medium leading-none", className)}
+      data-slot="fieldset-legend"
+      {...props}
+    />
+  );
+}
+
+// ── Composite ─────────────────────────────────────────────────────────────────
+
+export function normalizeError(
+  error: FieldErrorProp | undefined,
+): FieldErrorItem[] {
+  if (error === undefined) return [];
+  if (typeof error === "string") return [{ message: error, match: true }];
+  if (Array.isArray(error)) return error;
+  return [error];
+}
+
+export interface FieldProps
+  extends Omit<FieldPrimitive.Root.Props, "children"> {
+  /** Text rendered inside `FieldLabel`. */
+  label?: ReactNode;
+  /** Helper text rendered below the control. */
+  description?: ReactNode;
+  /**
+   * Error message(s) rendered below the control:
+   * - `string` → always renders once the field is invalid.
+   * - `{ message, match }` → renders only when the `ValidityState` key matches.
+   * - `FieldErrorItem[]` → multiple errors with individual matches.
+   */
+  error?: FieldErrorProp;
+  /** Shows a red asterisk after the label text. */
+  required?: boolean;
+  /** Renders an info icon with a tooltip next to the label. */
+  tooltip?: ReactNode;
+  /**
+   * Renders the control before the label on the same row.
+   * Use for single checkboxes and switches.
+   */
+  inline?: boolean;
+  children?: ReactNode;
+  /** Styles applied to each internal slot. */
+  classNames?: {
+    /** Label rendered above (or beside, when `inline`) the control. */
+    label?: string;
+    /** Helper text below the control. */
+    description?: string;
+    /** Error message rendered when the field is invalid. */
+    error?: string;
+  };
+}
+
+export function Field({
+  label,
+  description,
+  error,
+  required,
+  tooltip,
+  inline = false,
+  children,
+  className,
+  classNames,
+  invalid,
+  ...rootProps
+}: FieldProps) {
+  const errors = normalizeError(error);
+
+  const derivedInvalid =
+    invalid || errors.some((e) => e.match === true) || undefined;
+
+  const labelNode = label && (
+    <FieldLabel
+      render={tooltip ? <Label tooltip={tooltip} /> : undefined}
+      className={classNames?.label}
+    >
+      <span className="after:text-error group-has-[*:required]:after:content-['*'] group-data-[required]:after:content-['*']">
+        {label}
+      </span>
+    </FieldLabel>
+  );
+
+  return (
+    <FieldRoot
+      className={className}
+      required={required}
+      invalid={derivedInvalid}
+      {...rootProps}
+    >
+      {inline ? (
+        <div className="flex items-center gap-1">
+          {children}
+          {labelNode}
+        </div>
+      ) : (
+        <>
+          {labelNode}
+          {children}
+        </>
+      )}
+      {description && (
+        <FieldDescription className={classNames?.description}>
+          {description}
+        </FieldDescription>
+      )}
+      {errors.map((item, i) => (
+        <FieldError key={i} match={item.match} className={classNames?.error}>
+          {item.message}
+        </FieldError>
+      ))}
+      {/* Catch-all for errors not covered by any specific `match`:
+          - Server errors via `Form.errors`: field marked invalid externally,
+            validityData.error stays "" → caught by `error === ""`
+          - `Field.validate` errors: setCustomValidity(msg) → customError = true,
+            error = msg → caught by `validity.customError`
+          Native constraint failures have customError = false and are handled by
+          their specific `match` items, so this won't double-render them. */}
+      {!errors.some((item) => item.match === undefined) &&
+        (errors.length === 0 ? (
+          <FieldError className={classNames?.error} />
+        ) : (
+          <FieldValidity>
+            {({ validity, error }) =>
+              !validity.valid && (error === "" || validity.customError) ? (
+                <FieldError className={classNames?.error} />
+              ) : null
+            }
+          </FieldValidity>
+        ))}
+    </FieldRoot>
+  );
+}
+
+// ── Primitive escape hatch ────────────────────────────────────────────────────
+
+export { FieldPrimitive, FieldsetPrimitive };

package/src/components/field/index.ts

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