@boxcustodia/library 2.0.0-alpha.10 → 2.0.0-alpha.12

package/src/components/field/field.stories.tsx

@@ -0,0 +1,223 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { CheckboxIndicator, CheckboxRoot } from "../checkbox/checkbox";
+import { Input } from "../input/input";
+import { SwitchRoot, SwitchThumb } from "../switch/switch";
+import { Textarea } from "../textarea/textarea";
+import {
+  Field,
+  FieldControl,
+  FieldDescription,
+  FieldError,
+  FieldItem,
+  FieldLabel,
+  FieldRoot,
+  FieldValidity,
+} from "./field";
+
+/**
+ * Layout wrapper that connects a label, description, and errors to any form
+ * control via Base UI's field context. Auto-wires `htmlFor`/`aria-describedby`.
+ *
+ * The composite `Field` promotes `label`, `description`, `error`, `required`,
+ * `tooltip`, and `inline` as top-level props — covers ~90% of use cases.
+ * `error` accepts a string, a `{ message, match }` object (scoped to a
+ * `ValidityState` key), or an array for multiple errors.
+ *
+ * For full structural control (custom ordering, extra elements between parts,
+ * non-standard error rendering), use `FieldRoot` + primitives directly.
+ *
+ * Reference: [Field – Base UI](https://base-ui.com/react/components/field.md)
+ */
+const meta: Meta<typeof Field> = {
+  title: "Components/Field",
+  component: Field,
+  subcomponents: {
+    FieldRoot,
+    FieldLabel,
+    FieldItem,
+    FieldDescription,
+    FieldError,
+    FieldControl,
+    FieldValidity,
+  },
+  parameters: { layout: "centered" },
+  args: {
+    label: "Email",
+    description: "We'll never share your email.",
+    children: <Input type="email" placeholder="you@example.com" />,
+  },
+  argTypes: {
+    children: { control: false },
+    labelProps: { control: false },
+    descriptionProps: { control: false },
+    errorProps: { control: false },
+    error: { control: false },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Field>;
+
+export const Default: Story = {};
+
+export const Required: Story = {
+  args: {
+    children: <Input type="email" required placeholder="you@example.com" />,
+  },
+};
+
+export const Disabled: Story = {
+  args: { disabled: true },
+};
+
+/**
+ * `tooltip` renders an info icon next to the label with an accessible popup.
+ */
+export const WithTooltip: Story = {
+  args: {
+    tooltip: "Used to send you a confirmation link.",
+  },
+};
+
+/**
+ * `error` as a string auto-marks the field invalid — no `invalid` prop needed.
+ */
+export const WithError: Story = {
+  args: {
+    error: "Enter a valid email address.",
+  },
+};
+
+/**
+ * `error` as an array maps each message to a specific `ValidityState` key via
+ * `match`. Submit the form to trigger native HTML validation.
+ */
+export const WithMatchedErrors: Story = {
+  render: () => (
+    <form className="flex flex-col gap-3" onSubmit={(e) => e.preventDefault()}>
+      <Field
+        label="Email"
+        required
+        error={[
+          { message: "Email is required.", match: "valueMissing" },
+          { message: "Enter a valid email address.", match: "typeMismatch" },
+        ]}
+      >
+        <Input type="email" required placeholder="you@example.com" />
+      </Field>
+      <button
+        type="submit"
+        className="rounded-md bg-primary px-3 py-1.5 text-sm text-primary-foreground"
+      >
+        Submit
+      </button>
+    </form>
+  ),
+};
+
+/**
+ * `FieldValidity` render prop exposes the full `ValidityState` for custom
+ * error rendering without going through the `error` prop.
+ */
+export const WithValidity: Story = {
+  render: () => (
+    <form className="flex flex-col gap-3" onSubmit={(e) => e.preventDefault()}>
+      <Field label="Email" required className="w-72">
+        <Input type="email" required placeholder="you@example.com" />
+        <FieldValidity>
+          {({ validity }) =>
+            !validity.valid && (
+              <p className="text-destructive-foreground text-xs">
+                {validity.valueMissing
+                  ? "Email is required."
+                  : "Enter a valid email address."}
+              </p>
+            )
+          }
+        </FieldValidity>
+      </Field>
+      <button
+        type="submit"
+        className="rounded-md bg-primary px-3 py-1.5 text-sm text-primary-foreground"
+      >
+        Submit
+      </button>
+    </form>
+  ),
+};
+
+export const TextareaField: Story = {
+  args: {
+    label: "Bio",
+    description: "Max 160 characters.",
+    children: <Textarea placeholder="Tell us about yourself..." />,
+  },
+};
+
+/**
+ * `inline` renders control + label side-by-side. Use for single checkboxes and
+ * switches. Description and error still wrap to the row below.
+ */
+export const CheckboxField: Story = {
+  args: {
+    inline: true,
+    label: "I accept the terms and conditions",
+    description: undefined,
+    className: undefined,
+    error: { message: "You must accept the terms.", match: "valueMissing" },
+    children: (
+      <CheckboxRoot required>
+        <CheckboxIndicator />
+      </CheckboxRoot>
+    ),
+  },
+};
+
+export const SwitchField: Story = {
+  args: {
+    inline: true,
+    label: "Email notifications",
+    description: "Receive a weekly digest.",
+    className: undefined,
+    children: (
+      <SwitchRoot>
+        <SwitchThumb />
+      </SwitchRoot>
+    ),
+  },
+};
+
+/**
+ * `FieldRoot` + primitives for full structural control. `FieldControl` registers
+ * a non-Base-UI input with the field context so it participates in labelling,
+ * validation, and error state.
+ *
+ * ```tsx
+ * <FieldRoot>
+ *   <FieldLabel>Website</FieldLabel>
+ *   <FieldControl render={<MyCustomInput />} />
+ *   <FieldDescription>Helper text</FieldDescription>
+ *   <FieldError>Error message</FieldError>
+ * </FieldRoot>
+ * ```
+ */
+export const Primitive: Story = {
+  render: () => (
+    <FieldRoot className="w-72">
+      <FieldLabel>Website</FieldLabel>
+      <FieldControl
+        render={
+          <input
+            className="w-full rounded-md border border-input bg-background px-3 py-2 text-sm outline-none focus-visible:border-ring focus-visible:ring-2 focus-visible:ring-ring/50"
+            type="url"
+            required
+            placeholder="https://example.com"
+          />
+        }
+      />
+      <FieldDescription>Your public profile URL.</FieldDescription>
+      <FieldError match="valueMissing">Website is required.</FieldError>
+      <FieldError match="typeMismatch">Enter a valid URL.</FieldError>
+    </FieldRoot>
+  ),
+};

package/src/components/field/field.tsx

@@ -0,0 +1,229 @@
+import { Field as FieldPrimitive } from "@base-ui/react/field";
+import { type ReactNode } 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 ────────────────────────────────────────────────────────────────
+
+export function FieldRoot({
+  className,
+  required,
+  ...props
+}: FieldPrimitive.Root.Props & { required?: boolean }) {
+  return (
+    <FieldPrimitive.Root
+      className={cn("group flex flex-col gap-1", className)}
+      data-slot="field"
+      data-required={required || undefined}
+      {...props}
+    />
+  );
+}
+
+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;
+
+// ── Composite ─────────────────────────────────────────────────────────────────
+
+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;
+  // Escape hatches for each sub-component
+  labelProps?: FieldPrimitive.Label.Props;
+  labelClassName?: string;
+  descriptionProps?: FieldPrimitive.Description.Props;
+  descriptionClassName?: string;
+  errorProps?: Omit<FieldPrimitive.Error.Props, "match" | "children">;
+  errorClassName?: string;
+}
+
+export function Field({
+  label,
+  description,
+  error,
+  required,
+  tooltip,
+  inline = false,
+  children,
+  className,
+  labelProps,
+  labelClassName,
+  descriptionProps,
+  descriptionClassName,
+  errorProps,
+  errorClassName,
+  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={labelClassName}
+      {...labelProps}
+    >
+      <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={descriptionClassName}
+          {...descriptionProps}
+        >
+          {description}
+        </FieldDescription>
+      )}
+      {errors.map((item, i) => (
+        <FieldError
+          key={i}
+          match={item.match}
+          className={errorClassName}
+          {...errorProps}
+        >
+          {item.message}
+        </FieldError>
+      ))}
+      {/* Catch-all for server errors propagated via `Form.errors` (React context,
+          not `setCustomValidity`). When all user errors have a `match`, none of
+          them fire for server-side errors — render a plain `FieldError` guarded
+          by `FieldValidity` so it only shows when the field is invalid AND native
+          validation passed (validity.error === ""). */}
+      {!errors.some((item) => item.match === undefined) &&
+        (errors.length === 0 ? (
+          <FieldError {...errorProps} />
+        ) : (
+          <FieldValidity>
+            {({ validity, error }) =>
+              !validity.valid && error === "" ? (
+                <FieldError {...errorProps} />
+              ) : null
+            }
+          </FieldValidity>
+        ))}
+    </FieldRoot>
+  );
+}
+
+// ── Primitive escape hatch ────────────────────────────────────────────────────
+
+export { FieldPrimitive };

package/src/components/field/index.ts

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