@boxcustodia/library 2.0.0-alpha.13 → 2.0.0-alpha.15

package/src/components/form/form.stories.tsx

@@ -1,16 +1,12 @@
-import { zodResolver } from "@hookform/resolvers/zod";
 import type { Meta, StoryObj } from "@storybook/react-vite";
-import type { ReactNode } from "react";
 import { useState } from "react";
-import {
-  type FieldValues,
-  type SubmitHandler,
-  type UseFormProps,
-  type UseFormReturn,
-  useController,
-  useForm,
-} from "react-hook-form";
 import { z } from "zod";
+import {
+  HookField,
+  HookForm,
+  parseFormValues,
+  useHookForm,
+} from "../../utils/form";
 import { Button } from "../button/button";
 import { Checkbox } from "../checkbox/checkbox";
 import { Combobox } from "../combobox";
@@ -19,13 +15,15 @@ import { Field, FieldError, FieldLabel, FieldRoot } from "../field/field";
 import { Input } from "../input/input";
 import { NumberInput } from "../number-input";
 import { PasswordRoot } from "../password/password";
+import { RadioGroup } from "../radio-group";
 import { Select } from "../select";
+import { Stack } from "../stack";
 import { Textarea } from "../textarea/textarea";
 import { toast } from "../toast";
 import { Form, FormPrimitive } from "./form";
 
 /**
- * Thin wrapper around Base UI Form. `onSubmit` receives `(data, event)` —
+ * Thin wrapper around Base UI Form. `onFormSubmit` receives `(data, event)` —
  * `data` is a `Record<string, unknown>` parsed from `FormData`, `event` is
  * the native submit event. `preventDefault` is called automatically.
  * `errors` propagates server-side messages to fields by `name`.
@@ -39,7 +37,7 @@ const meta: Meta<typeof Form> = {
   parameters: { layout: "centered" },
   argTypes: {
     children: { control: false },
-    onSubmit: { control: false },
+    onFormSubmit: { control: false },
     actionsRef: { control: false },
     errors: { control: false },
   },
@@ -71,7 +69,10 @@ export const Default: Story = {
     const [done, setDone] = useState(false);
 
     return (
-      <Form className="flex w-80 flex-col gap-4" onSubmit={() => setDone(true)}>
+      <Form
+        className="flex w-80 flex-col gap-4"
+        onFormSubmit={() => setDone(true)}
+      >
         <Field
           name="email"
           label="Email"
@@ -144,7 +145,6 @@ export const Default: Story = {
         >
           <Combobox
             items={NOTIFICATION_CHANNELS}
-            defaultValue={[NOTIFICATION_CHANNELS[0]]}
             placeholder="Select channels…"
             multiple
             required
@@ -183,6 +183,23 @@ export const Default: Story = {
           />
         </Field>
 
+        <Field
+          name="plan"
+          label="Plan"
+          required
+          description="Choose the plan that fits your needs."
+          error={[{ message: "Please select a plan.", match: "valueMissing" }]}
+        >
+          <RadioGroup
+            required
+            items={[
+              { value: "free", label: "Free" },
+              { value: "pro", label: "Pro" },
+              { value: "enterprise", label: "Enterprise" },
+            ]}
+          />
+        </Field>
+
         <Field
           name="terms"
           inline
@@ -204,12 +221,12 @@ export const Default: Story = {
 };
 
 /**
- * `onSubmit` receives parsed `FormData` and is the right place for cross-field
+ * `onFormSubmit` receives parsed `FormData` and is the right place for cross-field
  * and custom-rule validation. Errors are stored in state and forwarded via
  * `Form.errors`, which routes each message to the matching field by `name` and
  * clears it automatically as soon as the user modifies that field.
  *
- * Native browser validation (email format, required) runs first — `onSubmit`
+ * Native browser validation (email format, required) runs first — `onFormSubmit`
  * only fires after all native constraints pass.
  */
 export const OnSubmitValidation: Story = {
@@ -220,7 +237,7 @@ export const OnSubmitValidation: Story = {
       <Form
         className="flex w-80 flex-col gap-4"
         errors={errors}
-        onSubmit={(data) => {
+        onFormSubmit={(data) => {
           const next: Record<string, string> = {};
           const pwd = data.password as string;
 
@@ -304,8 +321,8 @@ export const ValidateOnChange: Story = {
 };
 
 /**
- * `onSubmit(data, event)` — `data` is parsed from `FormData`, `event` is the
- * native submit event. `preventDefault` is already called by the Form wrapper.
+ * `onFormSubmit(data, event)` — `data` is parsed from `FormData`, `event` is
+ * the native submit event. `preventDefault` is already called by Base UI.
  */
 export const OnFormSubmit: Story = {
   render: () => {
@@ -314,7 +331,7 @@ export const OnFormSubmit: Story = {
     return (
       <Form
         className="flex w-80 flex-col gap-4"
-        onSubmit={(data) => setValues(data)}
+        onFormSubmit={(data) => setValues(data)}
       >
         <Field name="email" label="Email">
           <Input type="email" required placeholder="you@example.com" />
@@ -333,6 +350,77 @@ export const OnFormSubmit: Story = {
   },
 };
 
+const ZodSchema = z.object({
+  name: z.string().min(1, "Name is required."),
+  age: z.coerce
+    .number({ message: "Age must be a number." })
+    .positive("Age must be a positive number."),
+});
+
+/**
+ * Validación con `zod` sin `react-hook-form`. Útil cuando querés mantener un
+ * schema como source of truth (tipado del data, coerción, transformaciones)
+ * pero no necesitás watchers, dependent fields ni multi-step. El form sigue
+ * siendo un `<form>` nativo — sin context provider, sin re-renders por
+ * keystroke, sin `useForm` orquestando estado.
+ *
+ * **Flujo:**
+ *
+ * 1. Definí el schema con `zod`. Usá `z.coerce.*` para campos cuyo `FormData`
+ *    llega como string (`age`, fechas, números).
+ * 2. En `onFormSubmit`, pasá los `values` a `parseFormValues(schema, values)`.
+ *    Devuelve `{ data, errors }`:
+ *    - `data` es `z.infer<typeof schema>` cuando todas las validaciones pasan;
+ *      `null` si alguna falla.
+ *    - `errors` es `Record<string, string[]>` — keys son los `name` del Field,
+ *      values son los mensajes de zod. Vacío `{}` en éxito.
+ * 3. Pasá `errors` al prop `errors` del Form. Base UI rutea cada mensaje al
+ *    Field por `name` y lo limpia automáticamente cuando el usuario edita
+ *    ese campo.
+ *
+ * Para componentes con valor tipado (Select, Combobox), su valor llega al
+ * `formValues` como el shape que vos definas en el `value` — coerce o
+ * transformá en el schema si lo querés normalizar.
+ *
+ * Para reactividad real entre campos (watch, dependent fields, wizards),
+ * usá `HookForm` + `HookField` (más abajo).
+ */
+export const WithZod: Story = {
+  render: () => {
+    const [errors, setErrors] = useState<Record<string, string[]>>({});
+
+    return (
+      <Form
+        className="flex w-80 flex-col gap-4"
+        errors={errors}
+        onFormSubmit={(values) => {
+          const result = parseFormValues(ZodSchema, values);
+          setErrors(result.errors);
+
+          if (result.data) {
+            toast({
+              title: "Saved!",
+              description: (
+                <pre className="rounded-md bg-muted p-3 text-xs font-mono">
+                  {JSON.stringify(result.data, null, 2)}
+                </pre>
+              ),
+            });
+          }
+        }}
+      >
+        <Field name="name" label="Name">
+          <Input placeholder="Enter name" />
+        </Field>
+        <Field name="age" label="Age" description="Must be positive.">
+          <Input placeholder="Enter age" />
+        </Field>
+        <Button type="submit">Submit</Button>
+      </Form>
+    );
+  },
+};
+
 /**
  * `FormPrimitive` + `FieldRoot` primitives for full structural control.
  * Use when you need custom ordering or elements between parts.
@@ -366,139 +454,52 @@ export const Primitive: Story = {
   ),
 };
 
-const CATEGORIES = [
-  { label: "Frontend", value: "frontend" },
-  { label: "Backend", value: "backend" },
-  { label: "DevOps", value: "devops" },
-  { label: "Design", value: "design" },
-];
+// ── With zod + react-hook-form ───────────────────────────────────────────────────────────
 
-const schema = z.object({
-  age: z.coerce
-    .number({ message: "Please enter a number." })
-    .positive({ message: "Number must be positive." }),
-  name: z.string().min(1, { message: "Please enter a name." }),
-  emoji: z.emoji({ message: "Please enter an emoji." }),
-  category: z.string().min(1, { message: "Select a category." }),
-  terms: z.literal(true, { message: "You must accept the terms." }),
+const FormSchema = z.object({
+  email: z
+    .string()
+    .min(1, "Email is required.")
+    .email("Enter a valid email address."),
+  password: z.string().min(1, "Password is required."),
 });
 
-type FormDataType = z.infer<typeof schema>;
-type Errors = Partial<Record<keyof FormDataType, string[]>>;
-
-export const UsingZod: Story = {
-  render: () => {
-    const [loading, setLoading] = useState(false);
-    const [errors, setErrors] = useState<Errors>({});
-
-    const onSubmit = async (data: any) => {
-      setLoading(true);
-
-      try {
-        const result = schema.safeParse(data);
-
-        if (!result.success) {
-          const { fieldErrors } = z.flattenError(result.error);
-          setErrors(fieldErrors as Errors);
-          return;
-        }
-
-        setErrors({});
-        await new Promise((r) => setTimeout(r, 800));
-
-        toast({
-          title: "Success",
-          description: (
-            <pre className="rounded-md bg-muted p-3 text-sm font-mono">
-              {JSON.stringify(result.data, null, 2)}
-            </pre>
-          ),
-        });
-      } finally {
-        setLoading(false);
-      }
-    };
-
-    return (
-      <Form
-        className="flex w-full max-w-64 flex-col gap-4"
-        errors={errors}
-        onSubmit={onSubmit}
-      >
-        <Field name="name" label="Name" required>
-          <Input placeholder="Enter name" />
-        </Field>
-
-        <Field name="age" label="Age" description="Must be positive." required>
-          <Input placeholder="Enter age" />
-        </Field>
-
-        <Field
-          name="emoji"
-          label="Emoji"
-          required
-          tooltip="What's your favorite emoji?"
-        >
-          <Input />
-        </Field>
-
-        <Field name="category" label="Category" required>
-          <Combobox items={CATEGORIES} placeholder="Select a category…" />
-        </Field>
-
-        <Field
-          name="terms"
-          inline
-          label="I accept the terms and conditions"
-          required
-        >
-          <Checkbox />
-        </Field>
-
-        <Button loading={loading} type="submit">
-          Submit
-        </Button>
-      </Form>
-    );
-  },
-};
-
-// ── React Hook Form ───────────────────────────────────────────────────────────
-
 /**
- * Integration with React Hook Form + Zod. The `RHFField` helper wraps `Field`
- * and feeds `invalid`/`error` from `fieldState` — copy it into your project.
+ * `react-hook-form` + `zod` integration via `HookForm`, `HookField`, and
+ * `useHookForm` — exported directly from `@boxcustodia/library`.
  *
  * ```tsx
- * function RHFField({ name, label, description, rules, render }) {
- *   const { field, fieldState } = useController({ name, rules });
- *   return (
- *     <Field
- *       name={name}
- *       label={label}
- *       description={description}
- *       invalid={fieldState.invalid}
- *       error={fieldState.error?.message}
- *     >
- *       {render(field)}
- *     </Field>
- *   );
- * }
+ * import { HookForm, HookField, useHookForm } from "@boxcustodia/library";
+ *
+ * const form = useHookForm(MySchema, { defaultValues: { ... } });
+ *
+ * <HookForm form={form} onFormSubmit={(data) => console.log(data)}>
+ *   <HookField
+ *     name="email"
+ *     label="Email"
+ *     render={(field) => <Input {...field} type="email" />}
+ *   />
+ * </HookForm>
  * ```
+ *
+ * `useHookForm(schema, options)` wraps `react-hook-form`'s `useForm` with
+ * `zodResolver` pre-wired. `HookForm` provides the `FormProvider` context.
+ * `HookField` wraps `Controller` + `Field` — errors and invalid state are
+ * managed automatically.
  */
 export const WithReactHookForm: Story = {
   render: () => {
-    const form = useRHFForm(FormSchema, {
+    const form = useHookForm(FormSchema, {
       defaultValues: { email: "", password: "" },
     });
 
     return (
-      <RHFForm
+      <HookForm
         form={form}
-        onSubmit={() => {}}
+        onFormSubmit={() => {}}
         className="flex w-80 flex-col gap-4"
       >
-        <RHFField
+        <HookField
           name="email"
           label="Email"
           description="We'll never share your email."
@@ -507,7 +508,7 @@ export const WithReactHookForm: Story = {
           )}
         />
 
-        <RHFField
+        <HookField
           name="password"
           label="Password"
           render={(field) => (
@@ -520,75 +521,197 @@ export const WithReactHookForm: Story = {
         )}
 
         <Button type="submit">Create account</Button>
-      </RHFForm>
+      </HookForm>
     );
   },
 };
 
-// ── RHF helpers (not exported by the library — copy into your project) ────────
+/**
+ * `Field.validate` runs after native constraints pass. Return a string to fail,
+ * `null` to pass. Async functions are supported.
+ *
+ * **Important:** after the first submit attempt, Base UI switches to per-keystroke
+ * validation regardless of `validationMode` (`submitAttemptedRef` becomes `true`).
+ * For async validators that hit a backend, two guards are required:
+ *
+ * 1. `validationDebounceTime` — debounces the onChange trigger so the function
+ *    only fires after the user pauses typing.
+ * 2. A length/format check at the top of `validate` — skip the network call when
+ *    native constraints (required, minLength…) haven't passed yet. Base UI calls
+ *    `validate` even while those are failing when in onChange mode.
+ */
+export const FieldValidate: Story = {
+  render: () => {
+    const TAKEN = ["admin", "jane_doe", "johndoe"];
 
-const FormSchema = z.object({
+    return (
+      <Form className="flex w-80 flex-col gap-4" validationMode="onSubmit">
+        <Field
+          name="username"
+          label="Username"
+          description={`Already taken: ${TAKEN.join(", ")}`}
+          validationDebounceTime={400}
+          validationMode="onSubmit"
+          validate={async (value) => {
+            const str = String(value);
+            if (str.length < 3)
+              return "Username must be at least 3 characters.";
+            await new Promise((r) => setTimeout(r, 600));
+            return TAKEN.includes(str)
+              ? "This username is already taken."
+              : null;
+          }}
+        >
+          <Input placeholder="e.g. jane_doe" />
+        </Field>
+        <Button type="submit">Check availability</Button>
+      </Form>
+    );
+  },
+};
+
+// ── With react-hook-form (full example) ─────────────────────────────────────
+
+const MemberSchema = z.object({
+  firstName: z.string().min(1, "First name is required."),
+  lastName: z.string().min(1, "Last name is required."),
   email: z
     .string()
     .min(1, "Email is required.")
     .email("Enter a valid email address."),
-  password: z.string().min(1, "Password is required."),
+  role: z.string().min(1, "Role is required."),
+  bio: z.string().min(10, "Bio must be at least 10 characters."),
+  terms: z.literal(true, { message: "You must accept the terms." }),
 });
 
-function useRHFForm<T extends z.ZodType<FieldValues, FieldValues>>(
-  schema: T,
-  options?: Omit<UseFormProps<z.infer<T>>, "resolver">,
-) {
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  return useForm<z.infer<T>>({
-    resolver: zodResolver(schema as any),
-    ...options,
-  });
-}
-
-type RHFFormProps<T extends FieldValues> = {
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  form: UseFormReturn<T, any, any>;
-  onSubmit: SubmitHandler<T>;
-  children: ReactNode;
-  className?: string;
-};
+type MemberFormData = z.infer<typeof MemberSchema>;
 
-function RHFForm<T extends FieldValues>({
-  form,
-  onSubmit,
-  children,
-  ...props
-}: RHFFormProps<T>) {
-  return (
-    <Form
-      // onSubmit={(data, event) => form.handleSubmit(onSubmit)(data, event)}
-      {...props}
-    >
-      {children}
-    </Form>
-  );
-}
-
-interface RHFFieldProps {
-  name: string;
-  label?: ReactNode;
-  description?: ReactNode;
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  render: (field: any) => ReactNode;
-}
-
-function RHFField({ name, label, description, render }: RHFFieldProps) {
-  const { field, fieldState } = useController({ name });
-  return (
-    <Field
-      name={name}
-      label={label}
-      description={description}
-      invalid={fieldState.invalid}
-      error={fieldState.error?.message}
-    >
-      {render(field)}
-    </Field>
-  );
-}
+/**
+ * Full real-world example using `useForm`, `Form`, and `FormField` from
+ * `@boxcustodia/library`. These are thin wrappers over `react-hook-form` +
+ * `zod` — just import and use, no boilerplate needed.
+ *
+ * ```tsx
+ * import { HookForm, HookField, useHookForm } from "@boxcustodia/library";
+ *
+ * const form = useHookForm(MySchema, { defaultValues: { ... } });
+ *
+ * <HookForm form={form} onFormSubmit={(data) => console.log(data)}>
+ *   <HookField
+ *     name="email"
+ *     label="Email"
+ *     render={(field) => <Input {...field} type="email" />}
+ *   />
+ * </HookForm>
+ * ```
+ *
+ * `render` receives `ControllerRenderProps` plus `invalid: boolean`.
+ * Spread `{...field}` into inputs that accept `value` / `onChange` / `onBlur` / `ref`.
+ *
+ * Components with a typed item API require manual mapping:
+ * - `Select` — `onChange` returns `TItem | null`, extract `.value` for `z.string()` schemas.
+ * - `Checkbox` — uses `checked` / `onCheckedChange`, not `value` / `onChange`.
+ */
+export const WithReactHookFormFull: Story = {
+  render: () => {
+    const [loading, setLoading] = useState(false);
+
+    const form = useHookForm(MemberSchema, {
+      defaultValues: {
+        firstName: "",
+        lastName: "",
+        email: "",
+        role: "",
+        bio: "",
+        terms: false as unknown as true,
+      },
+    });
+
+    const onSubmit = async (data: MemberFormData) => {
+      setLoading(true);
+      await new Promise((r) => setTimeout(r, 800));
+      setLoading(false);
+      toast({
+        title: "Member created!",
+        description: (
+          <pre className="rounded-md bg-muted p-3 text-xs font-mono">
+            {JSON.stringify(data, null, 2)}
+          </pre>
+        ),
+      });
+    };
+
+    return (
+      <HookForm
+        form={form}
+        onFormSubmit={onSubmit}
+        className="flex w-80 flex-col gap-4"
+      >
+        <Stack>
+          <HookField
+            name="firstName"
+            label="First name"
+            required
+            render={(field) => <Input {...field} placeholder="Jane" />}
+          />
+          <HookField
+            name="lastName"
+            label="Last name"
+            required
+            render={(field) => <Input {...field} placeholder="Doe" />}
+          />
+        </Stack>
+
+        <HookField
+          name="email"
+          label="Email"
+          required
+          render={(field) => (
+            <Input {...field} type="email" placeholder="jane@example.com" />
+          )}
+        />
+
+        <HookField
+          name="role"
+          label="Role"
+          required
+          render={({ onChange, ...field }) => (
+            <Select
+              items={ROLES}
+              placeholder="Select a role…"
+              {...field}
+              value={field.value}
+              onValueChange={(item) => onChange(item?.value)}
+            />
+          )}
+        />
+
+        <HookField
+          name="bio"
+          label="Bio"
+          description="Min 10 characters."
+          render={(field) => (
+            <Textarea {...field} placeholder="Tell us about yourself…" />
+          )}
+        />
+
+        <HookField
+          name="terms"
+          inline
+          label="I accept the terms and conditions"
+          render={(field) => (
+            <Checkbox
+              {...field}
+              checked={field.value}
+              onCheckedChange={field.onChange}
+            />
+          )}
+        />
+
+        <Button loading={loading} type="submit">
+          Create member
+        </Button>
+      </HookForm>
+    );
+  },
+};

package/src/components/form/form.tsx

@@ -1,30 +1,10 @@
 import { Form as FormPrimitive } from "@base-ui/react/form";
 import type React from "react";
 
-type BaseProps = FormPrimitive.Props;
+export type FormProps = FormPrimitive.Props;
 
-export interface FormProps
-  extends Omit<BaseProps, "onSubmit" | "onFormSubmit"> {
-  onSubmit?: BaseProps["onFormSubmit"];
-  onFormSubmit?: BaseProps["onFormSubmit"];
-}
-
-export function Form({
-  onSubmit,
-  onFormSubmit,
-  className,
-  ...props
-}: FormProps): React.ReactElement {
-  const handleSubmit = onSubmit ?? onFormSubmit;
-
-  return (
-    <FormPrimitive
-      className={className}
-      onFormSubmit={handleSubmit}
-      data-slot="form"
-      {...props}
-    />
-  );
+export function Form(props: FormProps): React.ReactElement {
+  return <FormPrimitive data-slot="form" {...props} />;
 }
 
 export { FormPrimitive };