@maestro-js/form 1.0.0-alpha.0

package/README.md

@@ -0,0 +1,386 @@
+# @maestro-js/form
+
+Headless React form primitives with client and server validation, hidden inputs for custom components, controlled/uncontrolled state management, and Standard Schema (Zod) FormData parsing with automatic type coercion.
+
+## Quick Setup
+
+```tsx
+import { HeadlessForm } from '@maestro-js/form'
+
+// 1. Wrap your app with GlobalProvider to enable server error integration
+function App() {
+  return (
+    <HeadlessForm.GlobalProvider useServerErrors={useMyServerErrors}>
+      <MyPage />
+    </HeadlessForm.GlobalProvider>
+  )
+}
+
+// 2. Use HeadlessForm as your form element
+function LoginForm() {
+  return (
+    <HeadlessForm as="form" method="post" action="/login">
+      <input name="email" type="email" required />
+      <button type="submit">Log in</button>
+    </HeadlessForm>
+  )
+}
+```
+
+## Core Concepts
+
+### Validation Flow
+
+Custom validation via `validate` functions runs in realtime, setting `setCustomValidity()` on the referenced native element. Errors are committed (shown to the user) on input `change` or form `submit`. Server errors from `GlobalProvider` are shown immediately and cleared when the user edits the field. The first invalid input auto-focuses on submit.
+
+### Hidden Inputs for Custom Components
+
+Custom UI components (dropdowns, file pickers, date pickers) can't natively participate in HTML forms. `HiddenInput`, `HiddenFileInput`, and `HiddenSelect` bridge this gap with visually-hidden native elements that carry the value and participate in constraint validation.
+
+### FormData Parsing
+
+`parseFormData` and `parseFormDataClientSide` convert native FormData into typed objects using a Standard Schema (Zod). They handle type coercion (strings to numbers/booleans), nested objects via dot notation (`address.city`), arrays, and file uploads.
+
+## API Reference
+
+### HeadlessForm (Component)
+
+```tsx
+<HeadlessForm as="form" method="post" id="profile-form">
+  {children}
+</HeadlessForm>
+```
+
+Root form component. Wraps a native `<form>` with validation and server error support.
+
+- `as` -- Component to render (must resolve to `HTMLFormElement`)
+- `method` -- `'get'` | `'post'` | `'put'` | `'patch'` | `'delete'`
+- `id` -- Optional (auto-generated via `useId()` if omitted)
+- Plus all standard form element props
+
+GET forms validate on submit and prevent submission if invalid. Non-GET forms inject a hidden `__formId` input for server-side form identification.
+
+### GlobalProvider
+
+```tsx
+<HeadlessForm.GlobalProvider useServerErrors={useMyServerErrors}>
+  {children}
+</HeadlessForm.GlobalProvider>
+```
+
+Wraps your app to provide server error resolution to all forms. The `useServerErrors` prop is a hook with signature:
+
+```ts
+(formId: string) => { path: string; message: string }[] | null
+```
+
+### useValidation
+
+```ts
+HeadlessForm.useValidation<T>(
+  props: {
+    name: string | string[]
+    value: T
+    form: string
+    validate?: ValidationFunction<T>
+    isInvalid?: boolean
+    isRequired?: boolean
+    focus?: () => void
+  },
+  ref: RefObject<HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement>
+): {
+  isInvalid: boolean
+  validationErrors: string[]
+  validationDetails: ValidityState
+  validationMessage: string
+  commitValidation(): void
+}
+```
+
+Connects custom validation to the native Constraint Validation API. Use inside custom input components.
+
+- Runs `validate(value)` in realtime, sets `setCustomValidity()` on the referenced element
+- Commits errors on `change` event or form submit (`invalid` event)
+- Auto-focuses the first invalid input on submission
+- Integrates server errors from `GlobalProvider` -- clears when user edits
+- Resets on form `reset` event
+
+### useWarningState
+
+```ts
+HeadlessForm.useWarningState<T>(
+  props: { value: T; validate?: ValidationFunction<T>; isInvalid?: boolean }
+): {
+  realtimeValidation: ValidationResult
+  displayValidation: ValidationResult
+  warningMessage: string
+  commitValidation(): void
+  resetValidation(): void
+  updateValidation(result: ValidationResult): void
+}
+```
+
+Like `useValidation` but for non-blocking warnings. Does not integrate with native constraint validation or server errors. Use for soft validation hints that don't prevent submission.
+
+### useControlledState
+
+```ts
+HeadlessForm.useControlledState<T>(
+  value: T | undefined,
+  defaultValue: T,
+  onChange?: (v: T) => void
+): [T, (value: T) => void]
+```
+
+Manages controlled/uncontrolled state for custom form components. When `value` is defined, the component is controlled; when `undefined`, it uses `defaultValue` and manages its own state.
+
+### useReset
+
+```ts
+HeadlessForm.useReset(
+  ref: RefObject<HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement>,
+  initialValue: T,
+  onReset: (value: T) => void
+)
+```
+
+Calls `onReset` with the initial value when the parent form fires a `reset` event.
+
+### useServerErrors
+
+```ts
+HeadlessForm.useServerErrors(formId?: string): { path: string; message: string }[]
+```
+
+Returns server errors for the given form ID (or the current form's ID from context if omitted). Requires `GlobalProvider` in the tree.
+
+### useTopLevelFormValidation
+
+```ts
+HeadlessForm.useTopLevelFormValidation(
+  formElement: HTMLFormElement | string
+): { revalidate(field: string | null): void }
+```
+
+Programmatically re-triggers validation on form fields. Pass `null` to revalidate all fields, or a field name prefix to revalidate only matching fields.
+
+### composeValidators
+
+```ts
+HeadlessForm.composeValidators<T>(
+  ...fns: (ValidationFunction<T> | undefined | null)[]
+): ValidationFunction<T>
+```
+
+Combines multiple validation functions. Each is called with the value; all returned errors are collected into a single array.
+
+```ts
+const required = (v: string) => (!v ? 'Required' : null)
+const minLen = (min: number) => (v: string) => (v.length < min ? `At least ${min} chars` : null)
+
+const validate = HeadlessForm.composeValidators(required, minLen(5))
+validate('')  // ['Required', 'At least 5 chars']
+```
+
+### Hidden Input Components
+
+#### HiddenInput
+
+Visually hidden `<input>` that participates in form submission. Use inside custom components.
+
+```tsx
+<HeadlessForm.HiddenInput ref={inputRef} name="country" value={selectedCountry} form={formId} isRequired />
+```
+
+Props: `value`, `name`, `form`, `isRequired`, `type`, `min`, `max`
+
+#### HiddenFileInput
+
+Visually hidden `<input type="file">` with programmatic file assignment via `DataTransfer`.
+
+```tsx
+<HeadlessForm.HiddenFileInput ref={fileRef} name="avatar" value={selectedFile} form={formId} isRequired />
+```
+
+Props: `value` (`File | File[] | null`), `name`, `form`, `isRequired`
+
+#### HiddenSelect
+
+Visually hidden `<select>` for custom dropdown components.
+
+```tsx
+<HeadlessForm.HiddenSelect ref={selectRef} name="role" value={selectedRole} form={formId} isRequired>
+  <option value="admin">Admin</option>
+  <option value="viewer">Viewer</option>
+</HeadlessForm.HiddenSelect>
+```
+
+Props: `value`, `name`, `form`, `isRequired`, `children`, `autoComplete`, `onChange`, `label`
+
+### FormData Parsing
+
+#### parseFormData
+
+```ts
+HeadlessForm.parseFormData<T>(
+  schema: StandardSchema<T>,
+  formData: FormData | Promise<FormData>,
+  options?: {
+    handleFile?(file: File, path: string, data: T): Promise<string>
+    libraryOptions?: Record<string, unknown>
+  }
+): Promise<ParseFormDataResult<T>>
+```
+
+Server-side FormData parser. Converts raw FormData into a typed object validated against a Standard Schema (Zod).
+
+```ts
+const schema = z.object({ name: z.string(), age: z.number(), avatar: z.string() })
+
+const result = await HeadlessForm.parseFormData(schema, request.formData(), {
+  handleFile: async (file) => await uploadToS3(file)
+})
+
+if (result.success) {
+  result.data // { name: 'Alice', age: 30, avatar: 'https://cdn.example.com/avatar.png' }
+}
+```
+
+#### parseFormDataClientSide
+
+```ts
+HeadlessForm.parseFormDataClientSide<T>(
+  schema: StandardSchema<T>,
+  formData: FormData,
+  options?: ParseFormDataOptions<T>
+): ParseFormDataResult<T> & { fileEntries: FoundFile[] }
+```
+
+Synchronous client-side variant. Files are replaced with placeholder URLs for validation; actual file entries are returned separately in `fileEntries`.
+
+### Coercion Rules
+
+The parser uses the schema's JSON Schema representation to coerce FormData string values:
+
+| Schema Type | FormData Value | Result |
+| --- | --- | --- |
+| `string` | `'Alice'` | `'Alice'` |
+| `string` (nullable) | `''` | `null` |
+| `number` / `integer` | `'42'` | `42` |
+| `number` (empty) | `''` | `null` |
+| `boolean` | `'true'` / `'false'` | `true` / `false` |
+| `boolean` (absent) | *(missing)* | `false` |
+| `array` | multiple values | `['a', 'b']` |
+| `array` | JSON string `'[1,2]'` | `[1, 2]` |
+| `array` (empty) | `''` | `[]` |
+| nested object | `'addr.city'` key | `{ addr: { city: ... } }` |
+| array of objects | `'items.0.name'` key | `[{ name: ... }]` |
+
+### Types
+
+```ts
+type ValidationFunction<T> = (value: T) => string | string[] | null | undefined
+
+interface ValidationResult {
+  isInvalid: boolean
+  validationDetails: ValidityState
+  validationErrors: string[]
+}
+
+type ParseFormDataResult<T> =
+  | { success: true; data: T; formData: FormData; formId: string | null; issues: undefined }
+  | { success: false; data: any; formData: FormData; formId: string | null; issues: readonly StandardSchemaV1.Issue[] }
+```
+
+## Common Patterns
+
+### Custom Input with Validation
+
+```tsx
+function PhoneInput({ name, form }: { name: string; form: string }) {
+  const inputRef = useRef<HTMLInputElement>(null)
+  const [value, setValue] = HeadlessForm.useControlledState<string>(undefined, '')
+
+  const validation = HeadlessForm.useValidation(
+    {
+      name,
+      form,
+      value,
+      validate: (v) => (v && !/^\d{10}$/.test(v) ? 'Enter a 10-digit phone number' : null)
+    },
+    inputRef
+  )
+
+  HeadlessForm.useReset(inputRef, '', setValue)
+
+  return (
+    <div>
+      <input value={value} onChange={(e) => setValue(e.target.value)} />
+      <HeadlessForm.HiddenInput ref={inputRef} name={name} value={value} form={form} />
+      {validation.isInvalid && <span>{validation.validationMessage}</span>}
+    </div>
+  )
+}
+```
+
+### Server-Side Form Processing
+
+```ts
+async function handleProfileUpdate(formData: FormData) {
+  const schema = z.object({
+    name: z.string().min(1),
+    bio: z.string().nullable(),
+    age: z.number().min(13),
+    avatar: z.string(),
+    tags: z.array(z.string())
+  })
+
+  const result = await HeadlessForm.parseFormData(schema, formData, {
+    handleFile: async (file) => uploadToStorage(file)
+  })
+
+  if (!result.success) {
+    return { errors: result.issues.map((i) => ({ path: i.path?.join('.') ?? '', message: i.message })) }
+  }
+
+  await db.updateUser(result.data)
+}
+```
+
+### Custom Select with Hidden Native Element
+
+```tsx
+function RoleSelect({ name, form }: { name: string; form: string }) {
+  const selectRef = useRef<HTMLSelectElement>(null)
+  const [value, setValue] = HeadlessForm.useControlledState<string>(undefined, '')
+
+  const validation = HeadlessForm.useValidation({ name, form, value, isRequired: true }, selectRef)
+  HeadlessForm.useReset(selectRef, '', setValue)
+
+  return (
+    <div>
+      <CustomDropdown value={value} onChange={setValue} options={['admin', 'editor', 'viewer']} />
+      <HeadlessForm.HiddenSelect ref={selectRef} name={name} value={value} form={form} isRequired>
+        <option value="admin">Admin</option>
+        <option value="editor">Editor</option>
+        <option value="viewer">Viewer</option>
+      </HeadlessForm.HiddenSelect>
+      {validation.isInvalid && <span>{validation.validationMessage}</span>}
+    </div>
+  )
+}
+```
+
+## Warnings and Gotchas
+
+> **Warning:** `GlobalProvider` must wrap your app before any `HeadlessForm` is rendered. Without it, `useServerErrors` throws: `'GlobalContext not found. Please wrap your site with GlobalProvider'`.
+
+> **Warning:** Do not use async validation with `parseFormData` / `parseFormDataClientSide` -- they throw `'Async validation not supported'`. All schema validation must be synchronous.
+
+> **Note:** Non-GET forms inject a hidden `__formId` field. `parseFormData` strips this automatically. If you parse FormData manually, filter out `__formId`.
+
+> **Note:** `parseFormData` requires a `handleFile` option when the form contains file uploads. Without it, it throws. The client-side variant replaces files with placeholder URLs instead.
+
+> **Warning:** Unchecked boolean checkboxes are absent from FormData. The parser defaults these to `false` based on the schema. If the boolean field isn't declared in the schema, the absent value won't be coerced.
+
+> **Note:** `useControlledState` warns in the console if a component switches between controlled and uncontrolled mode. Always consistently pass either a value or `undefined`.

package/dist/index.d.ts

@@ -0,0 +1,183 @@
+import * as React$1 from 'react';
+import React__default from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { StandardJSONSchemaV1, StandardSchemaV1, StandardTypedV1 } from '@standard-schema/spec';
+
+type HeadlessFormProps<As extends React__default.ElementType> = {
+    id?: string;
+    children?: React__default.ReactNode;
+    as: RefType<As> extends HTMLFormElement ? As : never;
+    method?: 'get' | 'post' | 'put' | 'patch' | 'delete' | 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+} & React__default.ComponentProps<As>;
+type RefType<T extends React__default.ElementType<any>> = React__default.ComponentPropsWithRef<T>['ref'] extends React__default.Ref<infer I> | undefined ? I : never;
+declare function GlobalProvider({ useServerErrors, children, csrfToken }: GlobalContextValue): react_jsx_runtime.JSX.Element;
+interface GlobalContextValue {
+    useServerErrors(formId: string): {
+        path: string;
+        message: string;
+    }[] | null;
+    csrfToken?: string;
+    children?: React__default.ReactNode;
+}
+declare function useServerErrors(formId: string | undefined): {
+    path: string;
+    message: string;
+}[];
+
+declare function useControlledState<T, C = T>(value: Exclude<T, undefined>, defaultValue: Exclude<T, undefined> | undefined, onChange?: (v: C, ...args: any[]) => void): [T, (value: T) => void];
+declare function useControlledState<T, C = T>(value: Exclude<T, undefined> | undefined, defaultValue: Exclude<T, undefined>, onChange?: (v: C, ...args: any[]) => void): [T, (value: T) => void];
+
+declare function useTopLevelFormValidation(formElement: HTMLFormElement | string): {
+    revalidate: (field: string | null) => void;
+};
+
+type ValidatableElement$1 = HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement;
+declare function useReset<T>(ref: React__default.RefObject<ValidatableElement$1 | null>, initialValue: T, onReset: (value: T) => void): void;
+
+interface Validation<T> {
+    /** Whether user input is required on the input before form submission. */
+    isRequired?: boolean;
+    /** Whether the input value is invalid. */
+    isInvalid?: boolean;
+    /**
+     * A function that returns an error message if a given value is invalid.
+     * Validation errors are displayed to the user when the form is submitted
+     * if `validationBehavior="native"`. For realtime validation, use the `isInvalid`
+     * prop instead.
+     */
+    validate?: ValidationFunction<T>;
+}
+interface ValidationResult {
+    isInvalid: boolean;
+    validationDetails: ValidityState;
+    validationErrors: string[];
+}
+type ValidationFunction<T> = (value: T) => string | string[] | null | undefined;
+
+type ValidatableElement = HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement;
+interface FormValidationHookOptions<T> extends Validation<T> {
+    focus?: () => void;
+    name: string | string[] | undefined;
+    value: T;
+    form: string | undefined;
+}
+declare function useValidation<T>(props: FormValidationHookOptions<T>, ref: React__default.RefObject<ValidatableElement | null> | undefined): {
+    validationMessage: string;
+    isInvalid: boolean;
+    validationDetails: ValidityState;
+    validationErrors: string[];
+    commitValidation: () => void;
+};
+
+interface FormValidationProps<T> extends Validation<T> {
+    value: T;
+}
+interface FormWarningState {
+    /** Realtime validation results, updated as the user edits the value. */
+    realtimeValidation: ValidationResult;
+    /** Currently displayed validation results, updated when the user commits their changes. */
+    displayValidation: ValidationResult;
+    /** Updates the current validation result. Not displayed to the user until `commitValidation` is called. */
+    updateValidation(result: ValidationResult): void;
+    /** Resets the displayed validation state to valid when the user resets the form. */
+    resetValidation(): void;
+    /** Commits the realtime validation so it is displayed to the user. */
+    commitValidation(): void;
+    warningMessage: string;
+}
+declare function useWarningState<T>(props: FormValidationProps<T>): FormWarningState;
+
+type StandardSchema<Input = unknown, Output = Input> = StandardJSONSchemaV1<Input, Output> & StandardSchemaV1<Input, Output> & StandardTypedV1<Input, Output>;
+type ParseFormDataResult<T> = {
+    success: false;
+    issues: {
+        /** The error message of the issue. */
+        message: string;
+        /** The path of the issue, if any. */
+        path?: Array<PropertyKey | {
+            key: string | number | symbol;
+        }> | undefined;
+    }[];
+    data: any;
+    formData: FormData;
+    formId: string | null;
+} | {
+    success: true;
+    issues: undefined;
+    data: T;
+    formData: FormData;
+    formId: string | null;
+};
+interface ParseFormDataOptions<T> {
+    handleFile?(file: File, path: string, data: T): Promise<string>;
+    libraryOptions?: Record<string, unknown> | undefined;
+}
+declare function parseFormDataClientSide<T>(schema: StandardSchema<T>, formData: FormData, options?: ParseFormDataOptions<T>): ParseFormDataResult<T> & {
+    fileEntries: FoundFile[];
+};
+declare function parseFormData<T>(schema: StandardSchema<T>, formData: FormData | Promise<FormData>, options?: ParseFormDataOptions<T>): Promise<ParseFormDataResult<T>>;
+interface FoundFile {
+    path: (string | number)[];
+    value: File;
+}
+
+declare function composeValidators<T>(...fns: (ValidationFunction<T> | undefined | null)[]): ValidationFunction<T>;
+/**
+ * Headless React form primitives with validation, hidden inputs, and FormData parsing.
+ * Wrap your app with `HeadlessForm.GlobalProvider`, use `HeadlessForm` as the form root,
+ * and build custom inputs with `useValidation`, `useControlledState`, and hidden input components.
+ *
+ * @example
+ * ```tsx
+ * <HeadlessForm.GlobalProvider useServerErrors={useMyServerErrors}>
+ *   <HeadlessForm as="form" method="post">
+ *     <PhoneInput name="phone" form={formId} />
+ *     <button type="submit">Submit</button>
+ *   </HeadlessForm>
+ * </HeadlessForm.GlobalProvider>
+ * ```
+ */
+declare const HeadlessForm: (<As extends React.ElementType = "form">(props: {
+    id?: string;
+    children?: React.ReactNode;
+    as: (React$1.ComponentPropsWithRef<As>["ref"] extends React$1.Ref<infer I> | undefined ? I : never) extends HTMLFormElement ? As : never;
+    method?: "get" | "post" | "put" | "patch" | "delete" | "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+} & React$1.ComponentProps<As> & React$1.RefAttributes<HTMLFormElement>) => React.ReactElement | null) & {
+    GlobalProvider: typeof GlobalProvider;
+    useValidation: typeof useValidation;
+    useWarningState: typeof useWarningState;
+    useReset: typeof useReset;
+    useControlledState: typeof useControlledState;
+    HiddenInput: React$1.ForwardRefExoticComponent<{
+        value: string | number | readonly string[] | undefined;
+        name: string | undefined;
+        form: string | undefined;
+        isRequired?: boolean;
+        min?: number;
+        max?: number;
+        type?: React$1.HTMLInputTypeAttribute;
+    } & React$1.RefAttributes<HTMLInputElement>>;
+    HiddenFileInput: React$1.ForwardRefExoticComponent<{
+        value: File | File[] | null | undefined;
+        name: string | undefined;
+        form?: string | undefined;
+        isRequired?: boolean;
+    } & React$1.RefAttributes<HTMLInputElement>>;
+    HiddenSelect: React$1.ForwardRefExoticComponent<{
+        value: string | number | readonly string[] | undefined;
+        name: string | undefined;
+        form: string | undefined;
+        isRequired?: boolean;
+        children?: React.ReactNode;
+        autoComplete?: string;
+        onChange?: (e: React.ChangeEvent<HTMLSelectElement>) => unknown;
+        label?: React.ReactNode;
+    } & React$1.RefAttributes<HTMLSelectElement>>;
+    useServerErrors: typeof useServerErrors;
+    parseFormDataClientSide: typeof parseFormDataClientSide;
+    parseFormData: typeof parseFormData;
+    useTopLevelFormValidation: typeof useTopLevelFormValidation;
+    composeValidators: typeof composeValidators;
+};
+
+export { HeadlessForm, type HeadlessFormProps, type ValidationFunction, type ValidationResult };