react-f0rm 0.2.2 → 0.3.0

package/dist/index.d.ts

@@ -1,21 +1,203 @@
-import { O as Options, F as Form$1, N as Name, P as Path, a as Name$1 } from './form-d06e6444.js';
-export { b as PathValue, o as clearErrors, c as createForm, D as ensureValidate, h as getError, i as getErrorByPath, j as getErrors, k as getFirstError, d as getValue, e as getValueByPath, g as getValues, B as hasErrors, r as hasTouched, t as hasTouchedByPath, H as incrementSubmitCount, v as isDirty, w as isTouched, x as removeField, y as removeFieldByPath, A as reset, m as setError, n as setErrorByPath, z as setInitialValues, G as setIsSubmitting, I as setSubmitSuccessful, p as setTouched, q as setTouchedByPath, l as setValidatingByPath, s as setValue, f as setValueByPath, C as trigger, u as unsetValidatingByPath, E as validate } from './form-d06e6444.js';
+import { F as FieldPath, N as Name, a as Form$1, P as PathValueOf, b as FieldError, O as Options, c as Path } from './form-61297bc0.js';
+export { f as FieldErrorEntry, u as FieldState, a3 as HandleSubmitOptions, e as PathValue, R as ReValidateMode, U as ResetFieldOptions, Q as ResetOptions, S as SetFieldOptions, a5 as SetFocusOptions, g as VALIDATION_OUTCOME, i as ValidateResult, V as ValidationMode, h as ValidationOutcome, A as clearErrors, d as createForm, Z as ensureValidate, H as getDirtyFields, n as getError, o as getErrorByPath, r as getErrors, p as getFieldErrors, q as getFieldErrorsByPath, v as getFieldState, t as getFirstError, I as getTouchedFields, k as getValue, l as getValueByPath, j as getValues, a4 as handleSubmit, X as hasErrors, D as hasTouched, E as hasTouchedByPath, a0 as incrementSubmitCount, G as isDirty, J as isTouched, K as removeField, L as removeFieldByPath, T as reset, W as resetField, a2 as setDisabled, y as setError, z as setErrorByPath, a6 as setFocus, M as setInitialValues, $ as setIsSubmitting, a1 as setSubmitSuccessful, B as setTouched, C as setTouchedByPath, x as setValidatingByPath, s as setValue, m as setValueByPath, Y as trigger, w as unsetValidatingByPath, _ as validate } from './form-61297bc0.js';
 import * as React from 'react';
+import { ReactNode } from 'react';
+import { V as Validator } from './validate-148fe167.js';
 import { EventEmitter } from '@for-fun/event-emitter';
 
+/** Type tag of a failed rule, as stored on the resulting FieldError. */
+type RuleType = 'required' | 'min' | 'max' | 'minLength' | 'maxLength' | 'pattern';
+/**
+ * Declarative field rules — a subset of react-hook-form's `register` rules.
+ *
+ * Failed rules land in the form's error state as FieldErrors (`type` is the
+ * rule name) instead of only surfacing through the browser's validity
+ * bubble, so any design system can render the messages uniformly.
+ */
+interface FieldRules {
+    /**
+     * Fails on empty values: `''`, `undefined` or `null` (`0` and `false`
+     * count as filled). A string is the error message; `true` uses the
+     * default. When it fails, the remaining rules are skipped — an empty
+     * value reports only its required error.
+     */
+    required?: string | true;
+    /** Fails when `Number(value)` is below this bound; `NaN` values skip. */
+    min?: number;
+    /** Fails when `Number(value)` is above this bound; `NaN` values skip. */
+    max?: number;
+    /** Fails when a string value is shorter than this; non-strings skip. */
+    minLength?: number;
+    /** Fails when a string value is longer than this; non-strings skip. */
+    maxLength?: number;
+    /** Fails when the value does not match `pattern.value`. */
+    pattern?: {
+        value: RegExp;
+        message: string;
+    };
+    /**
+     * Overrides the message per rule type — `min`, `max`, `minLength`,
+     * `maxLength` defaults and pattern's inline `message` alike — e.g. for
+     * centralizing or localizing messages.
+     */
+    messages?: Partial<Record<Exclude<RuleType, 'required'>, string>>;
+}
+
+interface UseFieldOptions$1<TValues extends Record<string, any> = any, TPath extends FieldPath<TValues> | Name = Name> {
+    form?: Form$1<TValues>;
+    name: TPath;
+    initialValue?: any;
+    shouldUnregister?: boolean;
+    validate?: Validator;
+    /**
+     * Declarative rules (required/min/max/minLength/maxLength/pattern),
+     * compiled into a validator that runs before `validate` — both sources'
+     * errors merge into one FieldError[], rules errors ahead. Failures land
+     * in the form's error state with the given or default messages.
+     */
+    rules?: FieldRules;
+    /**
+     * Milliseconds to debounce this field's validation kicks. Defaults to 0
+     * (validate immediately); while the timer is pending the field counts as
+     * validating, so `trigger`/`ensureValidate` wait out the window. Only the
+     * last kick inside the window runs the validator.
+     */
+    validateDebounce?: number;
+    /**
+     * Milliseconds to delay showing a newly appearing error in the render
+     * layer (`error`/`errorObject`/`errors` stay undefined/empty until the
+     * window passes). The form's error state is never delayed — trigger,
+     * submit and `getError` read it immediately. An error that clears inside
+     * the window never shows; once an error is visible, later changes apply
+     * immediately. Only the none → some transition waits.
+     */
+    delayError?: number;
+    /**
+     * Disable this field: OR-ed with the form-level flag
+     * (`createForm({disabled})` / `setDisabled`) into the result's
+     * `disabled`. A field cannot opt out of a disabled form.
+     */
+    disabled?: boolean;
+}
+/**
+ * The result of {@link useField}. Deliberately a closed shape: no index
+ * signature, so a typo'd property access (`field.vlaue`) is a type error
+ * instead of silently reading `undefined`.
+ */
+interface UseFieldResult<TValues extends Record<string, any> = any, TPath extends FieldPath<TValues> | Name = Name> {
+    /** The form instance this field is bound to (explicit prop or context) —
+     * handy for consumers that need direct access to the headless API. */
+    form: Form$1<TValues>;
+    value: PathValueOf<TValues, TPath>;
+    /** Error message string (FieldError#message) for display, or undefined */
+    error: string | undefined;
+    /** Full FieldError object ({type, message}), or undefined */
+    errorObject: FieldError | undefined;
+    /** Every error registered for the field, in insertion order — `error`
+     * and `errorObject` are its first entry. Empty (and reference-stable)
+     * when the field has no errors. */
+    errors: FieldError[];
+    onChange: (v: any) => void;
+    onBlur: () => void;
+    name: string;
+    /** Merged disabled flag: the form-level flag (`createForm({disabled})`
+     * toggled by `setDisabled`) OR-ed with this field's own `disabled`
+     * option, updated live through the form's event core. */
+    disabled: boolean;
+}
+declare function useField<TValues extends Record<string, any> = any, TPath extends FieldPath<TValues> | Name = Name>(options: UseFieldOptions$1<TValues, TPath>): UseFieldResult<TValues, TPath>;
+
+interface FieldArrayItem {
+    id: string;
+    index: number;
+}
+interface UseFieldArrayResult {
+    fields: FieldArrayItem[];
+    append: (value: any) => void;
+    prepend: (value: any) => void;
+    insert: (index: number, value: any) => void;
+    remove: (index: number) => void;
+    swap: (from: number, to: number) => void;
+    move: (from: number, to: number) => void;
+    replace: (values: any[]) => void;
+    update: (index: number, value: any) => void;
+}
+declare function useFieldArray(options: {
+    name: Name;
+    form?: Form$1;
+}): UseFieldArrayResult;
+
 declare const FormContext: React.Context<any>;
 declare const FormProvider: React.Provider<any>;
-declare function useFormContext(): any;
+/**
+ * Read the form from the module-level {@link FormContext}. Pass the values
+ * shape — `useFormContext<Values>()` — to get a fully typed `Form<Values>`
+ * headless API; the `any` default keeps untyped call sites compiling.
+ *
+ * For multiple forms in one subtree use {@link createFormContext} instead.
+ *
+ * @throws when no `<FormProvider>` is mounted above the call site.
+ */
+declare function useFormContext<T extends Record<string, any> = any>(): Form$1<T>;
+/**
+ * Create an isolated bundle of form-context bindings: its own React context
+ * plus `useField` / `useFieldArray` / `useFormContext` hooks that resolve
+ * their form from it.
+ *
+ * Why: the module-level {@link FormContext} works fine for a single form per
+ * subtree, but nesting two forms (or reusing a component inside a different
+ * form) makes them fight over one context. Calling this factory once per app
+ * area — `const Ctx = createFormContext<Values>()` — fixes the value shape
+ * (`Ctx.useField({name: 'user.name'})` gets its `name` constrained by
+ * `FieldPath<Values>` and its `value` typed accordingly), so call sites stop
+ * hand-writing generics, and each instance's Provider scopes a strictly
+ * separate form.
+ */
+declare function createFormContext<TValues extends Record<string, any> = any>(): {
+    FormProvider: ({ form, children }: {
+        form: Form$1<TValues>;
+        children: ReactNode;
+    }) => ReactNode;
+    useFormContext: () => Form$1<TValues>;
+    useField: <TPath extends FieldPath<TValues> | Name = Name>(options: {
+        name: TPath;
+    } & Omit<UseFieldOptions$1<TValues, TPath>, "form">) => UseFieldResult<TValues, TPath>;
+    useFieldArray: (options: {
+        name: FieldPath<TValues> | Name;
+    }) => UseFieldArrayResult;
+};
 declare const CheckboxGroupContext: React.Context<any>;
 declare const CheckboxGroupProvider: React.Provider<any>;
 declare function useCheckboxGroupContext(): any;
 
-declare function useForm<T extends Record<string, any> = any>(options?: Options<T>): Form$1<T>;
+/**
+ * Create a form instance bound to this component.
+ *
+ * Beyond {@link Options}, the optional `values` object enables controlled
+ * usage: when it genuinely changes it is re-synced into the form with
+ * setInitialValues semantics -- uncommitted user edits are discarded
+ * (master-detail semantics: selecting another record replaces the draft),
+ * while touched flags and errors survive. Change detection is
+ * reference-first with a structural fallback, so re-renders that pass an
+ * inline literal with equal content never re-sync -- the user's
+ * in-progress typing is never clobbered.
+ */
+declare function useForm<T extends Record<string, any> = any>(options?: Options<T> & {
+    values?: T;
+}): Form$1<T>;
+/**
+ * Subscribe to a form event and keep the component's snapshot of `getter()`
+ * in sync with the form state.
+ *
+ * Built on useSyncExternalStore, so snapshots taken while React renders are
+ * guaranteed consistent (no tearing under concurrent rendering) and changes
+ * emitted before the subscription effect runs are still picked up.
+ */
 declare function useWatch<T>(emitter: EventEmitter, event: string, getter: () => T): T;
 /**
  * Get field value state
  */
-declare function useValue(form: Form$1, name: Name): any;
+declare function useValue<T extends Record<string, any> = any, P extends FieldPath<T> | Name = Name>(form: Form$1<T>, name: P): PathValueOf<T, P>;
 /**
  * Get field value state by path
  */
@@ -23,79 +205,187 @@ declare function useValueByPath(form: Form$1, path: Path): any;
 /**
  * Get field touched state
  */
-declare function useTouched(form: Form$1, name: Name): boolean;
+declare function useTouched<T extends Record<string, any> = any, P extends FieldPath<T> | Name = Name>(form: Form$1<T>, name: P): boolean;
 /**
  * Get field touched state by path
  */
 declare function useTouchedByPath(form: Form$1, path: Path): boolean;
 /**
- * Get field error state
+ * Get field error message state
+ * @return current error's message string (display text), or undefined
  */
-declare function useError(form: Form$1, name: Name): string | undefined;
+declare function useError<T extends Record<string, any> = any, P extends FieldPath<T> | Name = Name>(form: Form$1<T>, name: P): string | undefined;
 /**
  * Get field error state by path
+ * @return current FieldError object ({type, message}), or undefined
  */
-declare function useErrorByPath(form: Form$1, path: Path): string | undefined;
+declare function useErrorByPath(form: Form$1, path: Path): FieldError | undefined;
+/**
+ * Get all field errors
+ * @return every error registered for the field (insertion order); an empty
+ *         array when the field has none
+ */
+declare function useFieldErrors<T extends Record<string, any> = any, P extends FieldPath<T> | Name = Name>(form: Form$1<T>, name: P): FieldError[];
+/**
+ * Get all field errors by path
+ * @return every error registered for the field (insertion order); an empty
+ *         array when the field has none
+ */
+declare function useFieldErrorsByPath(form: Form$1, path: Path): FieldError[];
 declare function useIsDirty(form: Form$1): boolean;
+/**
+ * Get dirty fields state -- object mapping each dirty field's user-facing
+ * dotted path ('a.b', 'a.0.c') to true; recalculated after 'change' events
+ */
+declare function useDirtyFields(form: Form$1): Record<string, boolean>;
+/**
+ * Get touched fields state -- array of touched fields' user-facing dotted
+ * paths ('a.b', 'a.0.c'); recalculated after 'touched' events
+ */
+declare function useTouchedFields(form: Form$1): string[];
 declare function useHasErrors(form: Form$1): boolean;
 declare function useIsSubmitting(form: Form$1): boolean;
 declare function useSubmitCount(form: Form$1): number;
 
-interface UseFieldOptions$1 {
-    form?: Form$1;
-    name: Name$1;
-    initialValue?: any;
-    shouldUnregister?: boolean;
-    validate?: (value: any, meta: {
-        form: Form$1;
-        path: Path;
-    }) => string | undefined | Promise<string | undefined>;
-    [key: string]: any;
-}
-interface UseFieldResult {
-    value: any;
-    error: string | undefined;
-    onChange: (v: any) => void;
-    onBlur: () => void;
-    name: string;
-    [key: string]: any;
-}
-declare function useField({ form: f1, name, initialValue, shouldUnregister, validate, ...rest }: UseFieldOptions$1): UseFieldResult;
-
-interface FieldArrayItem {
-    id: string;
-    index: number;
-}
-declare function useFieldArray(options: {
-    name: Name;
-    form?: Form$1;
-}): {
-    fields: FieldArrayItem[];
-    append: (value: any) => void;
-    prepend: (value: any) => void;
-    insert: (index: number, value: any) => void;
-    remove: (index: number) => void;
-    swap: (from: number, to: number) => void;
-    move: (from: number, to: number) => void;
+/** Subscription granularity for {@link onPathEvent}.
+ * - `'leaf'`: the subscriber reads exactly one key ({@link
+ *   useValueByPath}); only writes at that key or above it can change what
+ *   it reads.
+ * - `'branch'`: the subscriber aggregates a whole subtree below a key
+ *   ({@link useFieldArray}); descendant writes matter too. */
+type WatchScope = 'leaf' | 'branch';
+/** Events {@link subscribe} can watch. `'errors'` and `'touched'` are
+ * stored per exact key, so they match exact keys ({@link onKeyEvent});
+ * `'change'`, `'submitting'` and `'submitCount'` carry paths and go
+ * through {@link onPathEvent}. */
+type SubscribeEvent = 'change' | 'errors' | 'touched' | 'submitting' | 'submitCount';
+/** Options accepted by {@link subscribe}. */
+type SubscribeOptions = {
+    /** Path (or list of paths) to watch. Omit to receive every emission of
+     * `event`, payload-less broadcasts included. A single segments path
+     * (`['tags', 0]`) and a list of names (`['tags', 'user.name']`) are told
+     * apart by the same rule `trigger` uses: only a segments path can hold
+     * a number. */
+    name?: Name | Name[];
+    /** Event to watch. Defaults to `'change'`. */
+    event?: SubscribeEvent;
+    /** Which writes around `name` are relevant — `'leaf'` or `'branch'`.
+     * Only meaningful for `'change'`: `'errors'`/`'touched'` match exact
+     * keys and `'submitting'`/`'submitCount'` are payload-less. Defaults to
+     * `'branch'` — the intuitive linkage semantics, where subscribing to
+     * `'tags'` means the whole branch. */
+    scope?: WatchScope;
+    /** Invoked with no arguments after each matching emission. Read fresh
+     * state through the `get*` readers inside it. */
+    callback: () => void;
 };
+/**
+ * Subscribe to form events imperatively — the non-render counterpart of
+ * the `use*` hooks: linkages and side effects (province changed → clear
+ * city, autosave, analytics) run without mounting a watching component.
+ *
+ * Without `name`, `callback` fires on every `event` emission, payload-less
+ * broadcasts (reset, setInitialValues) included. With `name`, matching
+ * follows the event's shape: `'errors'`/`'touched'` match the exact key
+ * ({@link onKeyEvent}) — another field's error never wakes this
+ * subscriber — while `'change'`/`'submitting'`/`'submitCount'` go through
+ * {@link onPathEvent}, so the default `'branch'` scope wakes a `'tags'`
+ * subscriber when any `tags.*` descendant is written. A `name` array
+ * builds one subscription per path and the returned function unsubscribes
+ * them all.
+ *
+ * @param form the form to watch
+ * @param options event, name(s), scope and callback
+ * @return unsubscribe function
+ */
+declare function subscribe(form: Form$1, options: SubscribeOptions): () => void;
 
+/**
+ * Props for <Form>.
+ *
+ * Native validation behavior: the rendered <form> always sets noValidate,
+ * which suppresses the browser's built-in blocked-submit UI. However, native
+ * constraint validation still gates submission — the form element's
+ * checkValidity() runs before custom validators, and when it fails,
+ * reportValidity() surfaces the offending constraints as native bubbles and
+ * submission stops (onInvalidSubmit fires). onSubmit/onValidSubmit only run
+ * once every native constraint (required, type=email, minLength, ...) passes.
+ *
+ * The submit flow itself lives in the headless `handleSubmit` (see form.ts);
+ * this component is a thin wrapper that binds it to the rendered <form>.
+ */
 interface FormProps<T extends Record<string, any> = any> extends Omit<React.FormHTMLAttributes<HTMLFormElement>, 'onSubmit'> {
     form?: Form<T>;
     initialValues?: T;
+    /**
+     * Controlled external values. When the `values` reference changes, the
+     * new object is synced into the form (via setInitialValues semantics):
+     * uncommitted user edits are discarded -- master-detail semantics, where
+     * selecting another record replaces the draft -- while touched flags and
+     * errors are kept. Sync is reference-based: re-renders that pass the same
+     * `values` reference never clobber what the user is typing.
+     */
+    values?: T;
     onSubmit?: (values: T, e: React.FormEvent) => void;
     onValidSubmit?: (values: T, e: React.FormEvent) => void;
-    onInvalidSubmit?: (errors: string[], values: T) => void;
+    /**
+     * Called when validation fails.
+     * @param errors array of {path, type, message} entries in insertion
+     *        order; path is the dotted field path ('a.b', 'list.0'), type is
+     *        the error kind ('custom' for plain string errors, 'native' for
+     *        failed DOM constraint validation), message is the display text
+     * @param values current form values
+     */
+    onInvalidSubmit?: (errors: {
+        path: string;
+        type: string;
+        message: string;
+    }[], values: T) => void;
+    /**
+     * Focus the first field with an error after a failed submit: custom
+     * validation failures focus the first errored field, native constraint
+     * failures focus the first ':invalid' control. Defaults to true; pass
+     * false to disable.
+     */
+    shouldFocusError?: boolean;
 }
-declare function Form<T extends Record<string, any> = any>({ form: f1, initialValues, onSubmit, onValidSubmit, onInvalidSubmit, ...props }: FormProps<T>): React.JSX.Element;
+declare function Form<T extends Record<string, any> = any>({ form: f1, initialValues, values, onSubmit, onValidSubmit, onInvalidSubmit, shouldFocusError, ...props }: FormProps<T>): React.JSX.Element;
 
 interface UseFieldOptions {
     form?: any;
-    name?: Name$1;
+    name?: Name;
     initialValue?: any;
-    validate?: (value: any, meta: {
-        form: any;
-        path: any;
-    }) => string | undefined | Promise<string | undefined>;
+    shouldUnregister?: boolean;
+    validate?: Validator;
+    /**
+     * Declarative rules (required/min/max/minLength/maxLength/pattern),
+     * compiled into a validator that runs before `validate`; failures land
+     * in the form's error state. Passed through to useField — like
+     * validateDebounce it is never spread onto the DOM element.
+     */
+    rules?: FieldRules;
+    /**
+     * Milliseconds to debounce this field's validation kicks. Defaults to 0
+     * (validate immediately); only the last kick inside the window runs the
+     * validator, and `trigger` waits the window out. Passed through to
+     * useField/useValidate.
+     */
+    validateDebounce?: number;
+    /**
+     * Disable this field's control: OR-ed with the form-level flag
+     * (`createForm({disabled})` / `setDisabled`) — a field cannot opt out
+     * of a disabled form. Passed through to useField, like every option,
+     * never spread onto the DOM element from props.
+     */
+    disabled?: boolean;
+    /**
+     * Milliseconds to delay showing a newly appearing error (render layer
+     * only — `aria-invalid`/`renderError` wait out the window while the
+     * form's error state stays immediate for trigger/submit). An error
+     * that clears inside the window never shows; once visible, error
+     * changes apply immediately. Passed through to useField.
+     */
+    delayError?: number;
     [key: string]: any;
 }
 interface FieldProps extends UseFieldOptions {
@@ -103,10 +393,24 @@ interface FieldProps extends UseFieldOptions {
     asProps?: Record<string, any>;
     eventToValue?: (e: any) => any;
     valueToProps?: (value: any) => Record<string, any>;
+    /**
+     * Optional error renderer. When provided and the field has an error,
+     * Field renders `<span id={id} role="alert">{renderError(error, id)}</span>`
+     * next to the input and points the input's aria-describedby at that span.
+     * When omitted, no extra element is rendered (headless) and no
+     * aria-describedby is attached, avoiding dangling id references.
+     */
+    renderError?: (error: string, id: string) => React.ReactNode;
 }
 declare const Field: React.ForwardRefExoticComponent<Omit<FieldProps, "ref"> & React.RefAttributes<HTMLInputElement>>;
 interface CheckboxProps extends UseFieldOptions {
 }
 declare const Checkbox: React.ForwardRefExoticComponent<Omit<CheckboxProps, "ref"> & React.RefAttributes<HTMLInputElement>>;
+interface SelectProps extends UseFieldOptions {
+    multiple?: boolean;
+    children?: React.ReactNode;
+}
+declare const Select: React.ForwardRefExoticComponent<Omit<SelectProps, "ref"> & React.RefAttributes<HTMLSelectElement>>;
 
-export { Checkbox, CheckboxGroupContext, CheckboxGroupProvider, Field, Form, FormContext, FormProvider, Name, Options, useCheckboxGroupContext, useError, useErrorByPath, useField, useFieldArray, useForm, useFormContext, useHasErrors, useIsDirty, useIsSubmitting, useSubmitCount, useTouched, useTouchedByPath, useValue, useValueByPath, useWatch };
+export { Checkbox, CheckboxGroupContext, CheckboxGroupProvider, Field, FieldError, FieldPath, Form, FormContext, Form$1 as FormInstance, FormProvider, Name, Options, PathValueOf, Select, createFormContext, subscribe, useCheckboxGroupContext, useDirtyFields, useError, useErrorByPath, useField, useFieldArray, useFieldErrors, useFieldErrorsByPath, useForm, useFormContext, useHasErrors, useIsDirty, useIsSubmitting, useSubmitCount, useTouched, useTouchedByPath, useTouchedFields, useValue, useValueByPath, useWatch };
+export type { FieldRules, SubscribeEvent, SubscribeOptions, WatchScope };