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

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

@@ -0,0 +1,594 @@
+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 { Button } from "../button/button";
+import { Checkbox } from "../checkbox/checkbox";
+import { Combobox } from "../combobox";
+import { DateInput } 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 { Select } from "../select";
+import { Textarea } from "../textarea/textarea";
+import { toast } from "../toast";
+import { Form, FormPrimitive } from "./form";
+
+/**
+ * Thin wrapper around Base UI Form. `onSubmit` 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 },
+    onSubmit: { 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.
+ */
+export const Default: Story = {
+  render: () => {
+    const [done, setDone] = useState(false);
+
+    return (
+      <Form className="flex w-80 flex-col gap-4" onSubmit={() => 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"
+          error={{ message: "Start date is required.", match: "valueMissing" }}
+        >
+          <DateInput required />
+        </Field>
+
+        <Field
+          name="notifications"
+          label="Notification channels"
+          required
+          error={[
+            { message: "Select at least one channel.", match: "valueMissing" },
+          ]}
+        >
+          <Combobox
+            items={NOTIFICATION_CHANNELS}
+            defaultValue={[NOTIFICATION_CHANNELS[0]]}
+            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="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>
+    );
+  },
+};
+
+/**
+ * `onSubmit` 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`
+ * 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}
+        onSubmit={(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>
+  ),
+};
+
+/**
+ * `onSubmit(data, event)` — `data` is parsed from `FormData`, `event` is the
+ * native submit event. `preventDefault` is already called by the Form wrapper.
+ */
+export const OnFormSubmit: Story = {
+  render: () => {
+    const [values, setValues] = useState<Record<string, unknown> | null>(null);
+
+    return (
+      <Form
+        className="flex w-80 flex-col gap-4"
+        onSubmit={(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>
+    );
+  },
+};
+
+/**
+ * `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>
+  ),
+};
+
+const CATEGORIES = [
+  { label: "Frontend", value: "frontend" },
+  { label: "Backend", value: "backend" },
+  { label: "DevOps", value: "devops" },
+  { label: "Design", value: "design" },
+];
+
+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." }),
+});
+
+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.
+ *
+ * ```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>
+ *   );
+ * }
+ * ```
+ */
+export const WithReactHookForm: Story = {
+  render: () => {
+    const form = useRHFForm(FormSchema, {
+      defaultValues: { email: "", password: "" },
+    });
+
+    return (
+      <RHFForm
+        form={form}
+        onSubmit={() => {}}
+        className="flex w-80 flex-col gap-4"
+      >
+        <RHFField
+          name="email"
+          label="Email"
+          description="We'll never share your email."
+          render={(field) => (
+            <Input {...field} type="email" placeholder="you@example.com" />
+          )}
+        />
+
+        <RHFField
+          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>
+      </RHFForm>
+    );
+  },
+};
+
+// ── RHF helpers (not exported by the library — copy into your project) ────────
+
+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."),
+});
+
+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;
+};
+
+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>
+  );
+}

package/src/components/form/form.tsx

@@ -0,0 +1,30 @@
+import { Form as FormPrimitive } from "@base-ui/react/form";
+import type React from "react";
+
+type BaseProps = 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 { FormPrimitive };

package/src/components/form/index.ts

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

package/src/components/heading/heading.stories.tsx

@@ -0,0 +1,74 @@
+import { faker } from "@faker-js/faker";
+import { Meta, StoryObj } from "@storybook/react-vite";
+import { Heading } from "../../components";
+
+const meta: Meta<typeof Heading> = {
+  title: "typography/Heading",
+  component: Heading,
+  args: {
+    children: faker.lorem.sentence(),
+  },
+  argTypes: {
+    children: {
+      control: false,
+    },
+    size: {
+      options: ["sm", "md", "lg", "xl", "2xl", "3xl", "4xl", "5xl", "6xl"],
+      control: { type: "select" },
+      defaultValue: "xl",
+      description: "The font size of the heading. xl is the default.",
+    },
+    weight: {
+      options: ["normal", "medium", "semibold", "bold"],
+      control: { type: "select" },
+      defaultValue: "semibold",
+      description: "The font weight of the heading. semibold is the default.",
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof Heading>;
+
+export const Default: Story = {};
+
+export const Sizes: Story = {
+  render: () => (
+    <>
+      <Heading size="sm">Heading sm (14px)</Heading>
+      <Heading size="md">Heading md (16px)</Heading>
+      <Heading size="lg">Heading lg (18px)</Heading>
+      <Heading size="xl">Heading xl (20px)</Heading>
+      <Heading size="2xl">Heading 2xl (24px)</Heading>
+      <Heading size="3xl">Heading 3xl (28px)</Heading>
+      <Heading size="4xl">Heading 4xl (32px)</Heading>
+      <Heading size="5xl">Heading 5xl (36px)</Heading>
+      <Heading size="6xl">Heading 6xl (40px)</Heading>
+    </>
+  ),
+};
+
+export const Weights: Story = {
+  render: () => (
+    <>
+      <Heading weight="normal">Heading normal</Heading>
+      <Heading weight="medium">Heading medium</Heading>
+      <Heading weight="semibold">Heading semibold</Heading>
+      <Heading weight="bold">Heading bold</Heading>
+    </>
+  ),
+};
+
+export const As: Story = {
+  render: () => (
+    <>
+      <Heading as="h1">Heading as h1</Heading>
+      <Heading as="h2">Heading as h2</Heading>
+      <Heading as="h3">Heading as h3</Heading>
+      <Heading as="h4">Heading as h4</Heading>
+      <Heading as="h5">Heading as h5</Heading>
+      <Heading as="h6">Heading as h6</Heading>
+    </>
+  ),
+};