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

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

@@ -0,0 +1,732 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { useState } from "react";
+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";
+import { DateInput, DatePicker } from "../date-picker";
+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. `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`.
+ * `validationMode` lives on `FieldRoot`, not on Form — set it per-field.
+ *
+ * Reference: [Forms – Base UI](https://base-ui.com/react/handbook/forms)
+ */
+const meta: Meta<typeof Form> = {
+  title: "Components/Form",
+  component: Form,
+  parameters: { layout: "centered" },
+  argTypes: {
+    children: { control: false },
+    onFormSubmit: { control: false },
+    actionsRef: { control: false },
+    errors: { control: false },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Form>;
+
+const NOTIFICATION_CHANNELS = [
+  { label: "Email", value: "email" },
+  { label: "SMS", value: "sms" },
+  { label: "Push", value: "push" },
+  { label: "Slack", value: "slack" },
+];
+
+const ROLES = [
+  { label: "Developer", value: "developer" },
+  { label: "Designer", value: "designer" },
+  { label: "Manager", value: "manager" },
+  { label: "QA Engineer", value: "qa" },
+];
+/**
+ * Native HTML constraint validation. Each `FieldRoot` carries a `name` so Form
+ * can route server errors automatically. Errors only surface after the first
+ * submit attempt — no premature invalid state.
+ *
+ * Both date controls — typeable `DateInput` and popover `DatePicker` — submit an
+ * ISO date string (`yyyy-MM-dd`), or `""` when empty so `required` triggers
+ * `valueMissing`. The displayed text stays `dd/MM/yyyy`; value and display are
+ * separate layers.
+ */
+export const Default: Story = {
+  render: () => {
+    const [done, setDone] = useState(false);
+
+    return (
+      <Form
+        className="flex w-80 flex-col gap-4"
+        onFormSubmit={() => setDone(true)}
+      >
+        <Field
+          name="email"
+          label="Email"
+          tooltip="We will never share your email."
+          error={[
+            { message: "Email is required.", match: "valueMissing" },
+            { message: "Enter a valid email address.", match: "typeMismatch" },
+          ]}
+        >
+          <Input type="email" required placeholder="you@example.com" />
+        </Field>
+
+        <Field
+          name="username"
+          label="Username"
+          error={[
+            { message: "Username is required.", match: "valueMissing" },
+            { message: "Username must be 3–15 characters.", match: "tooShort" },
+            {
+              message: "Only letters, numbers, and underscores.",
+              match: "patternMismatch",
+            },
+          ]}
+        >
+          <Input
+            required
+            pattern="[a-zA-Z0-9_]+"
+            minLength={3}
+            maxLength={15}
+            placeholder="e.g. jane_doe"
+          />
+        </Field>
+
+        <Field
+          name="role"
+          label="Role"
+          error={[{ message: "Role is required.", match: "valueMissing" }]}
+        >
+          <Select items={ROLES} placeholder="Select a role…" required />
+        </Field>
+
+        <Field
+          name="experience"
+          label="Years of experience"
+          description="Must be between 0 and 50."
+          error={[
+            { message: "This field is required.", match: "valueMissing" },
+            { message: "Value must be 0 or more.", match: "rangeUnderflow" },
+            { message: "Value cannot exceed 50.", match: "rangeOverflow" },
+          ]}
+        >
+          <NumberInput required min={0} max={50} />
+        </Field>
+
+        <Field
+          name="startDate"
+          label="Start date"
+          description="Typeable input — submits yyyy-MM-dd."
+          error={{ message: "Start date is required.", match: "valueMissing" }}
+        >
+          <DateInput required />
+        </Field>
+
+        <Field
+          name="endDate"
+          label="End date"
+          description="Popover picker — submits yyyy-MM-dd."
+          error={{ message: "End date is required.", match: "valueMissing" }}
+        >
+          <DatePicker mode="single" required />
+        </Field>
+
+        <Field
+          name="notifications"
+          label="Notification channels"
+          required
+          error={[
+            { message: "Select at least one channel.", match: "valueMissing" },
+          ]}
+        >
+          <Combobox
+            items={NOTIFICATION_CHANNELS}
+            placeholder="Select channels…"
+            multiple
+            required
+          />
+        </Field>
+
+        <Field
+          name="password"
+          label="Password"
+          error={{ message: "Password is required.", match: "valueMissing" }}
+        >
+          <PasswordRoot required placeholder="Enter your password" />
+        </Field>
+
+        <Field
+          name="bio"
+          label="Bio"
+          tooltip="Between 20 and 300 characters."
+          error={[
+            { message: "Bio is required.", match: "valueMissing" },
+            {
+              message: "Bio must be at least 20 characters.",
+              match: "tooShort",
+            },
+            {
+              message: "Bio must be 300 characters or less.",
+              match: "tooLong",
+            },
+          ]}
+        >
+          <Textarea
+            required
+            minLength={10}
+            maxLength={300}
+            placeholder="Tell us a bit about yourself…"
+          />
+        </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
+          label="I accept the terms and conditions"
+          error={{
+            message: "You must accept the terms.",
+            match: "valueMissing",
+          }}
+        >
+          <Checkbox required />
+        </Field>
+
+        {done && <p className="text-sm text-green-600">Account created!</p>}
+
+        <Button type="submit">Create account</Button>
+      </Form>
+    );
+  },
+};
+
+/**
+ * `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 — `onFormSubmit`
+ * only fires after all native constraints pass.
+ */
+export const OnSubmitValidation: Story = {
+  render: () => {
+    const [errors, setErrors] = useState<Record<string, string>>({});
+
+    return (
+      <Form
+        className="flex w-80 flex-col gap-4"
+        errors={errors}
+        onFormSubmit={(data) => {
+          const next: Record<string, string> = {};
+          const pwd = data.password as string;
+
+          if (!/[A-Z]/.test(pwd))
+            next.password = "Must contain at least 1 uppercase letter.";
+          else if (!/[a-z]/.test(pwd))
+            next.password = "Must contain at least 1 lowercase letter.";
+          else if (!/\d/.test(pwd))
+            next.password = "Must contain at least 1 number.";
+
+          if (data.password !== data.confirmPassword)
+            next.confirmPassword = "Passwords must match.";
+
+          if (Object.keys(next).length > 0) {
+            setErrors(next);
+            return;
+          }
+
+          setErrors({});
+        }}
+      >
+        <Field
+          name="email"
+          label="Email"
+          error={[
+            { message: "Email is required.", match: "valueMissing" },
+            { message: "Enter a valid email address.", match: "typeMismatch" },
+          ]}
+        >
+          <Input type="email" required placeholder="you@example.com" />
+        </Field>
+
+        <Field
+          name="password"
+          label="Password"
+          error={{ message: "Password is required.", match: "valueMissing" }}
+        >
+          <PasswordRoot required placeholder="Enter your password" />
+        </Field>
+
+        <Field
+          name="confirmPassword"
+          label="Repeat password"
+          error={{
+            message: "Repeat password is required.",
+            match: "valueMissing",
+          }}
+        >
+          <PasswordRoot required placeholder="Repeat your password" />
+        </Field>
+
+        <Button type="submit">Create account</Button>
+      </Form>
+    );
+  },
+};
+
+/**
+ * `validationMode` is a `FieldRoot` prop, not a Form prop — set it per-field.
+ * `"onChange"` validates on every keystroke. `"onBlur"` validates when focus leaves.
+ * Default is `"onSubmit"`.
+ */
+export const ValidateOnChange: Story = {
+  render: () => (
+    <Form className="flex w-80 flex-col gap-4">
+      <Field
+        name="email"
+        label="Email"
+        required
+        validationMode="onChange"
+        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">Submit</Button>
+    </Form>
+  ),
+};
+
+/**
+ * `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: () => {
+    const [values, setValues] = useState<Record<string, unknown> | null>(null);
+
+    return (
+      <Form
+        className="flex w-80 flex-col gap-4"
+        onFormSubmit={(data) => setValues(data)}
+      >
+        <Field name="email" label="Email">
+          <Input type="email" required placeholder="you@example.com" />
+        </Field>
+        <Field name="username" label="Username">
+          <Input required placeholder="e.g. jane_doe" />
+        </Field>
+        <Button type="submit">Submit</Button>
+        {values && (
+          <pre className="rounded-md bg-muted p-3 text-xs">
+            {JSON.stringify(values, null, 2)}
+          </pre>
+        )}
+      </Form>
+    );
+  },
+};
+
+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.
+ *
+ * ```tsx
+ * <FormPrimitive>
+ *   <FieldRoot name="email">
+ *     <FieldLabel>Email</FieldLabel>
+ *     <Input type="email" required />
+ *     <FieldError match="valueMissing">Required.</FieldError>
+ *   </FieldRoot>
+ * </FormPrimitive>
+ * ```
+ */
+export const Primitive: Story = {
+  render: () => (
+    <FormPrimitive
+      className="flex w-80 flex-col gap-4"
+      onSubmit={(e) => e.preventDefault()}
+    >
+      <FieldRoot name="email">
+        <FieldLabel>Email</FieldLabel>
+        <Input type="email" required placeholder="you@example.com" />
+        <FieldError match="valueMissing">Email is required.</FieldError>
+        <FieldError match="typeMismatch">
+          Enter a valid email address.
+        </FieldError>
+      </FieldRoot>
+      <Button type="submit">Submit</Button>
+    </FormPrimitive>
+  ),
+};
+
+// ── With zod + react-hook-form ───────────────────────────────────────────────────────────
+
+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."),
+});
+
+/**
+ * `react-hook-form` + `zod` integration via `HookForm`, `HookField`, and
+ * `useHookForm` — exported directly from `@boxcustodia/library`.
+ *
+ * ```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>
+ * ```
+ *
+ * `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 = useHookForm(FormSchema, {
+      defaultValues: { email: "", password: "" },
+    });
+
+    return (
+      <HookForm
+        form={form}
+        onFormSubmit={() => {}}
+        className="flex w-80 flex-col gap-4"
+      >
+        <HookField
+          name="email"
+          label="Email"
+          description="We'll never share your email."
+          render={(field) => (
+            <Input {...field} type="email" placeholder="you@example.com" />
+          )}
+        />
+
+        <HookField
+          name="password"
+          label="Password"
+          render={(field) => (
+            <PasswordRoot {...field} placeholder="Enter your password" />
+          )}
+        />
+
+        {form.formState.isSubmitSuccessful && (
+          <p className="text-sm text-green-600">Account created!</p>
+        )}
+
+        <Button type="submit">Create account</Button>
+      </HookForm>
+    );
+  },
+};
+
+/**
+ * `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"];
+
+    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."),
+  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." }),
+});
+
+type MemberFormData = z.infer<typeof MemberSchema>;
+
+/**
+ * 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>
+    );
+  },
+};