react-f0rm 0.3.0 → 0.4.1

package/dist/index.d.ts

@@ -1,8 +1,8 @@
-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 { a as FieldPath, N as Name, F as Form$1, P as PathValueOf, b as FieldError, c as Path, O as Options } from './form-DeRFdFKE.js';
+export { d as FieldErrorEntry, e as FieldState, H as HandleSubmitOptions, f as PathValue, R as ReValidateMode, g as ResetFieldOptions, h as ResetOptions, S as SetFieldOptions, i as SetFocusOptions, V as VALIDATION_OUTCOME, j as ValidateResult, k as ValidationMode, l as ValidationOutcome, m as clearErrors, n as createForm, o as ensureValidate, p as getDirtyFields, q as getError, r as getErrorByPath, s as getErrors, t as getFieldErrors, u as getFieldErrorsByPath, v as getFieldState, w as getFirstError, x as getTouchedFields, y as getValue, z as getValueByPath, A as getValues, B as handleSubmit, C as hasErrors, D as hasTouched, E as hasTouchedByPath, G as incrementSubmitCount, I as isDirty, J as isTouched, K as removeField, L as removeFieldByPath, M as reset, Q as resetField, T as setDisabled, U as setError, W as setErrorByPath, X as setFocus, Y as setInitialValues, Z as setIsSubmitting, _ as setSubmitSuccessful, $ as setTouched, a0 as setTouchedByPath, a1 as setValidatingByPath, a2 as setValue, a3 as setValueByPath, a4 as trigger, a5 as unsetValidatingByPath, a6 as validate } from './form-DeRFdFKE.js';
+import { V as Validator } from './validate-B7S9EiRT.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. */
@@ -151,9 +151,11 @@ declare function useFormContext<T extends Record<string, any> = any>(): Form$1<T
  * (`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.
+ * separate form. The bundle also carries its raw React context
+ * (`Ctx.context`) so `<Form context={Ctx.context}>` can provide into it.
  */
 declare function createFormContext<TValues extends Record<string, any> = any>(): {
+    context: React.Context<Form$1<TValues> | null>;
     FormProvider: ({ form, children }: {
         form: Form$1<TValues>;
         children: ReactNode;
@@ -315,7 +317,17 @@ declare function subscribe(form: Form$1, options: SubscribeOptions): () => void;
  * 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>;
+    form?: Form$1<T>;
+    /**
+     * Provide into an isolated context from `createFormContext()` instead of
+     * the module-level one — `<Form context={ProfileForm.context}>` keeps the
+     * component's full submit machinery while the factory's bound hooks
+     * (`ProfileForm.useField`, `ProfileForm.useFormContext`, ...) resolve this
+     * form from their private context. The module-level `useFormContext()` /
+     * `useField` do not see it; that is the point of the isolation. Omitted,
+     * the form lands in the module-level FormContext as before.
+     */
+    context?: React.Context<Form$1<any> | null>;
     initialValues?: T;
     /**
      * Controlled external values. When the `values` reference changes, the
@@ -326,8 +338,11 @@ interface FormProps<T extends Record<string, any> = any> extends Omit<React.Form
      * `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;
+    /** May be async — the submit flow awaits it, so form.isSubmitting
+     * covers the entire flight. */
+    onSubmit?: (values: T, e: React.FormEvent) => void | Promise<void>;
+    /** May be async, same as onSubmit. */
+    onValidSubmit?: (values: T, e: React.FormEvent) => void | Promise<void>;
     /**
      * Called when validation fails.
      * @param errors array of {path, type, message} entries in insertion
@@ -349,14 +364,34 @@ interface FormProps<T extends Record<string, any> = any> extends Omit<React.Form
      */
     shouldFocusError?: boolean;
 }
-declare function Form<T extends Record<string, any> = any>({ form: f1, initialValues, values, onSubmit, onValidSubmit, onInvalidSubmit, shouldFocusError, ...props }: FormProps<T>): React.JSX.Element;
+declare function Form<T extends Record<string, any> = any>({ form: f1, context, initialValues, values, onSubmit, onValidSubmit, onInvalidSubmit, shouldFocusError, ...props }: FormProps<T>): React.JSX.Element;
 
-interface UseFieldOptions {
-    form?: any;
-    name?: Name;
+/**
+ * Props shared by Field/Checkbox/Select. Generic so a typed form flows into
+ * the `validate` callback: with `form` (a `Form<Values>`) and `name`
+ * (a `FieldPath<Values>`) provided, `validate` receives the value at that
+ * path — `PathValueOf<Values, P>` — instead of `any`. The defaults keep the
+ * bare `<Field name="x" />` (context-resolved, untyped) call sites exactly
+ * as permissive as before.
+ */
+interface UseFieldOptions<TValues extends Record<string, any> = any, TPath extends FieldPath<TValues> | Name = Name> {
+    form?: Form$1<TValues>;
+    name?: TPath;
     initialValue?: any;
     shouldUnregister?: boolean;
-    validate?: Validator;
+    /**
+     * Field-level validator. The value argument is typed when the field is
+     * tied to a typed form (via the `form` prop); the return shape mirrors
+     * {@link Validator} — an error (string / FieldError / mixed array) or
+     * undefined when valid, possibly a Promise for async validation. The
+     * second argument carries the validation context (`meta.signal` aborts
+     * when the round is superseded).
+     */
+    validate?: (value: PathValueOf<TValues, TPath>, meta: {
+        form: Form$1;
+        path: Path;
+        signal: AbortSignal;
+    }) => ReturnType<Validator>;
     /**
      * Declarative rules (required/min/max/minLength/maxLength/pattern),
      * compiled into a validator that runs before `validate`; failures land
@@ -388,7 +423,7 @@ interface UseFieldOptions {
     delayError?: number;
     [key: string]: any;
 }
-interface FieldProps extends UseFieldOptions {
+interface FieldProps<TValues extends Record<string, any> = any, TPath extends FieldPath<TValues> | Name = Name> extends UseFieldOptions<TValues, TPath> {
     as?: React.ComponentType<any>;
     asProps?: Record<string, any>;
     eventToValue?: (e: any) => any;
@@ -402,15 +437,39 @@ interface FieldProps extends UseFieldOptions {
      */
     renderError?: (error: string, id: string) => React.ReactNode;
 }
-declare const Field: React.ForwardRefExoticComponent<Omit<FieldProps, "ref"> & React.RefAttributes<HTMLInputElement>>;
-interface CheckboxProps extends UseFieldOptions {
+/**
+ * The callable shape of {@link Field}: `form` + `name` flow their generics
+ * into `validate`'s value argument (`PathValueOf<TValues, TPath>`). A named
+ * interface rather than an inline `as <TValues, ...>() => ...` signature —
+ * same types, and the inline form trips no-use-before-define on the type
+ * parameters.
+ */
+interface FieldComponent {
+    <TValues extends Record<string, any> = any, TPath extends FieldPath<TValues> | Name = Name>(props: FieldProps<TValues, TPath> & React.RefAttributes<HTMLInputElement>): React.ReactElement | null;
+}
+declare const Field: FieldComponent;
+interface CheckboxProps<TValues extends Record<string, any> = any, TPath extends FieldPath<TValues> | Name = Name> extends UseFieldOptions<TValues, TPath> {
+}
+/**
+ * Callable shape of {@link Checkbox}: the same form-typed `validate`
+ * inference contract as {@link FieldComponent}.
+ */
+interface CheckboxComponent {
+    <TValues extends Record<string, any> = any, TPath extends FieldPath<TValues> | Name = Name>(props: CheckboxProps<TValues, TPath> & React.RefAttributes<HTMLInputElement>): React.ReactElement | null;
 }
-declare const Checkbox: React.ForwardRefExoticComponent<Omit<CheckboxProps, "ref"> & React.RefAttributes<HTMLInputElement>>;
-interface SelectProps extends UseFieldOptions {
+declare const Checkbox: CheckboxComponent;
+interface SelectProps<TValues extends Record<string, any> = any, TPath extends FieldPath<TValues> | Name = Name> extends UseFieldOptions<TValues, TPath> {
     multiple?: boolean;
     children?: React.ReactNode;
 }
-declare const Select: React.ForwardRefExoticComponent<Omit<SelectProps, "ref"> & React.RefAttributes<HTMLSelectElement>>;
+/**
+ * Callable shape of {@link Select}: the same form-typed `validate`
+ * inference contract as {@link FieldComponent}.
+ */
+interface SelectComponent {
+    <TValues extends Record<string, any> = any, TPath extends FieldPath<TValues> | Name = Name>(props: SelectProps<TValues, TPath> & React.RefAttributes<HTMLSelectElement>): React.ReactElement | null;
+}
+declare const Select: SelectComponent;
 
-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 { Checkbox, CheckboxGroupContext, CheckboxGroupProvider, Field, FieldError, FieldPath, Form, FormContext, Form$1 as FormInstance, FormProvider, Name, Options, Path, PathValueOf, Select, Validator, 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 };

package/dist/index.mjs

@@ -1,5 +1,5 @@
 import * as React from 'react';
-import React__default, { useState, useRef, useEffect, useCallback, useMemo, useContext, useReducer, createContext, createElement } from 'react';
+import React__default, { useCallback, useRef, useState, useEffect, useMemo, useContext, useReducer, createContext, createElement } from 'react';
 
 function getSet(ee, key) {
   var set = ee.get(key);
@@ -11,7 +11,7 @@ function getSet(ee, key) {
 function create$2() {
   return new Map();
 }
-function emit$1(ee, key) {
+function emit(ee, key) {
   for (var _len = arguments.length, args = new Array(_len > 2 ? _len - 2 : 0), _key = 2; _key < _len; _key++) {
     args[_key - 2] = arguments[_key];
   }
@@ -166,7 +166,6 @@ function create$1(name) {
   return { value, key: JSON.stringify(value) };
 }
 
-const emit = emit$1;
 const VALIDATION_OUTCOME = /* @__PURE__ */ Symbol("validation-outcome");
 function create(options) {
   const emitter = create$2();
@@ -761,7 +760,7 @@ function requireUseSyncExternalStoreShim_production () {
 	    var nextValue = latestGetSnapshot();
 	    return !objectIs(inst, nextValue);
 	  } catch (error) {
-	    return !0;
+	    return true;
 	  }
 	}
 	function useSyncExternalStore$1(subscribe, getSnapshot) {
@@ -803,7 +802,7 @@ function requireUseSyncExternalStoreShim_development () {
 	    function useSyncExternalStore$2(subscribe, getSnapshot) {
 	      didWarnOld18Alpha ||
 	        void 0 === React.startTransition ||
-	        ((didWarnOld18Alpha = !0),
+	        ((didWarnOld18Alpha = true),
 	        console.error(
 	          "You are using an outdated, pre-release alpha of React 18 that does not support useSyncExternalStore. The use-sync-external-store shim will not work correctly. Upgrade to a newer pre-release."
 	        ));
@@ -814,7 +813,7 @@ function requireUseSyncExternalStoreShim_development () {
 	          (console.error(
 	            "The result of getSnapshot should be cached to avoid an infinite loop"
 	          ),
-	          (didWarnUncachedGetSnapshot = !0));
+	          (didWarnUncachedGetSnapshot = true));
 	      }
 	      cachedValue = useState({
 	        inst: { value: value, getSnapshot: getSnapshot }
@@ -848,7 +847,7 @@ function requireUseSyncExternalStoreShim_development () {
 	        var nextValue = latestGetSnapshot();
 	        return !objectIs(inst, nextValue);
 	      } catch (error) {
-	        return !0;
+	        return true;
 	      }
 	    }
 	    function useSyncExternalStore$1(subscribe, getSnapshot) {
@@ -864,8 +863,8 @@ function requireUseSyncExternalStoreShim_development () {
 	      useEffect = React.useEffect,
 	      useLayoutEffect = React.useLayoutEffect,
 	      useDebugValue = React.useDebugValue,
-	      didWarnOld18Alpha = !1,
-	      didWarnUncachedGetSnapshot = !1,
+	      didWarnOld18Alpha = false,
+	      didWarnUncachedGetSnapshot = false,
 	      shim =
 	        "undefined" === typeof window ||
 	        "undefined" === typeof window.document ||
@@ -882,13 +881,21 @@ function requireUseSyncExternalStoreShim_development () {
 	return useSyncExternalStoreShim_development;
 }
 
-if (process.env.NODE_ENV === 'production') {
-  shim.exports = requireUseSyncExternalStoreShim_production();
-} else {
-  shim.exports = requireUseSyncExternalStoreShim_development();
+var hasRequiredShim;
+
+function requireShim () {
+	if (hasRequiredShim) return shim.exports;
+	hasRequiredShim = 1;
+
+	if (process.env.NODE_ENV === 'production') {
+	  shim.exports = requireUseSyncExternalStoreShim_production();
+	} else {
+	  shim.exports = requireUseSyncExternalStoreShim_development();
+	}
+	return shim.exports;
 }
 
-var shimExports = shim.exports;
+var shimExports = requireShim();
 
 function isDescendant(key, ancestorKey) {
   return key.startsWith(`${ancestorKey.slice(0, -1)},`);
@@ -1421,7 +1428,13 @@ function createFormContext() {
   function useFieldArray(options) {
     return useFieldArrayCore(options, Context);
   }
-  return { FormProvider: FormProvider2, useFormContext: useFormContext2, useField, useFieldArray };
+  return {
+    context: Context,
+    FormProvider: FormProvider2,
+    useFormContext: useFormContext2,
+    useField,
+    useFieldArray
+  };
 }
 const CheckboxGroupContext = createContext(null);
 const CheckboxGroupProvider = CheckboxGroupContext.Provider;
@@ -1433,6 +1446,7 @@ function useCheckboxGroupContext() {
 
 function Form({
   form: f1,
+  context,
   initialValues,
   values,
   onSubmit,
@@ -1449,7 +1463,8 @@ function Form({
     onInvalidSubmit,
     shouldFocusError
   });
-  return /* @__PURE__ */ React.createElement(FormProvider, { value: form }, /* @__PURE__ */ React.createElement("form", { ...props, noValidate: true, onSubmit: submit }));
+  const { Provider } = context ?? FormContext;
+  return /* @__PURE__ */ React.createElement(Provider, { value: form }, /* @__PURE__ */ React.createElement("form", { ...props, noValidate: true, onSubmit: submit }));
 }
 
 function setRef(ref, value) {