react-f0rm 0.4.0 → 0.5.0

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-rTlcIiWH.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, j as SetServerErrorsOptions, V as VALIDATION_OUTCOME, k as ValidateResult, l as ValidationMode, m as ValidationOutcome, n as clearErrors, o as createForm, p as ensureValidate, q as getDirtyFields, r as getError, s as getErrorByPath, t as getErrors, u as getFieldErrors, v as getFieldErrorsByPath, w as getFieldState, x as getFirstError, y as getTouchedFields, z as getValue, A as getValueByPath, B as getValues, C as handleSubmit, D as hasErrors, E as hasTouched, G as hasTouchedByPath, I as incrementSubmitCount, J as isDirty, K as isTouched, L as removeField, M as removeFieldByPath, Q as reset, T as resetField, U as setDisabled, W as setError, X as setErrorByPath, Y as setFocus, Z as setInitialValues, _ as setIsSubmitting, $ as setServerErrors, a0 as setSubmitSuccessful, a1 as setTouched, a2 as setTouchedByPath, a3 as setValidatingByPath, a4 as setValue, a5 as setValueByPath, a6 as trigger, a7 as unsetValidatingByPath, a8 as validate } from './form-rTlcIiWH.js';
+import { V as Validator } from './validate-CQX7BJOD.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. */
@@ -317,7 +317,7 @@ 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
@@ -327,7 +327,7 @@ interface FormProps<T extends Record<string, any> = any> extends Omit<React.Form
      * `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<any> | null>;
+    context?: React.Context<Form$1<any> | null>;
     initialValues?: T;
     /**
      * Controlled external values. When the `values` reference changes, the
@@ -338,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
@@ -428,12 +431,25 @@ interface FieldProps<TValues extends Record<string, any> = any, TPath extends Fi
     /**
      * 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.
+     * next to the input. The input's aria-describedby points at that span's
+     * id (the same `fieldErrorId(name)` derivation) whenever the field has
+     * an error — with or without renderError — so custom error components
+     * that render the element themselves (using `fieldErrorId`) get the
+     * wiring for free.
      */
     renderError?: (error: string, id: string) => React.ReactNode;
 }
+/**
+ * The error-message element id a field's `aria-describedby` points at —
+ * `fieldErrorId('a[0].b')` is `'a-0-b'`, the same id `Field`'s built-in
+ * `renderError` span carries. This is the library-level wiring convention:
+ * whenever a bound field (Field/Checkbox/Select) has an error it sets
+ * `aria-invalid` and describes the element with this id, so a custom error
+ * component only needs `<span id={fieldErrorId(name)} role="alert">` to
+ * complete the accessible-name chain for screen readers.
+ * @param name the same field name passed to the bound component
+ */
+declare function fieldErrorId(name: Name): string;
 /**
  * The callable shape of {@link Field}: `form` + `name` flow their generics
  * into `validate`'s value argument (`PathValueOf<TValues, TPath>`). A named
@@ -468,5 +484,5 @@ interface SelectComponent {
 }
 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, fieldErrorId, 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];
   }
@@ -144,6 +144,31 @@ function setOwned(root, path, value, owned) {
 function isPromise(value) {
   return value && typeof value.then === "function";
 }
+function isEqual(a, b) {
+  if (Object.is(a, b)) return true;
+  if (a instanceof Date && b instanceof Date)
+    return a.getTime() === b.getTime();
+  if (!a || !b || typeof a !== "object" || typeof b !== "object") return false;
+  const isArray = Array.isArray(a);
+  if (isArray !== Array.isArray(b)) return false;
+  if (isArray) {
+    if (a.length !== b.length) return false;
+    for (let i = 0; i < a.length; i++) {
+      if (!isEqual(a[i], b[i])) return false;
+    }
+    return true;
+  }
+  const proto = Object.getPrototypeOf(a);
+  if (proto !== Object.prototype && proto !== null) return false;
+  if (Object.getPrototypeOf(b) !== proto) return false;
+  const keysA = Object.keys(a);
+  const keysB = Object.keys(b);
+  if (keysA.length !== keysB.length) return false;
+  for (const key of keysA) {
+    if (!isEqual(a[key], b[key])) return false;
+  }
+  return true;
+}
 function waitUntil(emitter, event, isResolve, isReject) {
   return new Promise((resolve, reject) => {
     if (isReject()) return void reject();
@@ -166,7 +191,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();
@@ -302,6 +326,19 @@ function clearErrors(form, name) {
   for (const { key } of paths) errors.delete(key);
   for (const path of paths) emit(emitter, "errors", path);
 }
+function setServerErrors(form, errors, options) {
+  if (!options?.keepExisting) clearErrors(form);
+  for (const [name, error] of Object.entries(errors)) {
+    setError(
+      form,
+      name,
+      (Array.isArray(error) ? error : [error]).map((message) => ({
+        type: "server",
+        message
+      }))
+    );
+  }
+}
 function setTouched(form, name) {
   setTouchedByPath(form, create$1(name));
 }
@@ -402,7 +439,9 @@ function reviveBranch(deleted, { key }) {
   }
 }
 function setInitialValues(form, initialValues) {
-  if (form.initialValues === initialValues) return;
+  if (form.initialValues === initialValues || isEqual(form.initialValues, initialValues)) {
+    return;
+  }
   form.initialValues = initialValues;
   form.parsedValues = void 0;
   form.values.clear();
@@ -761,7 +800,7 @@ function requireUseSyncExternalStoreShim_production () {
 	    var nextValue = latestGetSnapshot();
 	    return !objectIs(inst, nextValue);
 	  } catch (error) {
-	    return !0;
+	    return true;
 	  }
 	}
 	function useSyncExternalStore$1(subscribe, getSnapshot) {
@@ -803,7 +842,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 +853,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 +887,7 @@ function requireUseSyncExternalStoreShim_development () {
 	        var nextValue = latestGetSnapshot();
 	        return !objectIs(inst, nextValue);
 	      } catch (error) {
-	        return !0;
+	        return true;
 	      }
 	    }
 	    function useSyncExternalStore$1(subscribe, getSnapshot) {
@@ -864,8 +903,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 +921,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)},`);
@@ -1064,31 +1111,6 @@ function useIsSubmitting(form) {
 function useSubmitCount(form) {
   return useWatch(form.emitter, "submitCount", () => form.submitCount);
 }
-function isEqual(a, b) {
-  if (Object.is(a, b)) return true;
-  if (a instanceof Date && b instanceof Date)
-    return a.getTime() === b.getTime();
-  if (!a || !b || typeof a !== "object" || typeof b !== "object") return false;
-  const isArray = Array.isArray(a);
-  if (isArray !== Array.isArray(b)) return false;
-  if (isArray) {
-    if (a.length !== b.length) return false;
-    for (let i = 0; i < a.length; i++) {
-      if (!isEqual(a[i], b[i])) return false;
-    }
-    return true;
-  }
-  const proto = Object.getPrototypeOf(a);
-  if (proto !== Object.prototype && proto !== null) return false;
-  if (Object.getPrototypeOf(b) !== proto) return false;
-  const keysA = Object.keys(a);
-  const keysB = Object.keys(b);
-  if (keysA.length !== keysB.length) return false;
-  for (const key of keysA) {
-    if (!isEqual(a[key], b[key])) return false;
-  }
-  return true;
-}
 
 function usePath(name) {
   const path = useMemo(() => create$1(normalizePath(name)), [name]);
@@ -1471,6 +1493,9 @@ function errorIdFromKey(key) {
   const id = key.replace(/["'[\],\s]+/g, "-").replace(/^-+|-+$/g, "");
   return id || "field";
 }
+function fieldErrorId(name) {
+  return errorIdFromKey(create$1(name).key);
+}
 const Field = React.forwardRef(
   ({
     validate,
@@ -1559,16 +1584,17 @@ const Field = React.forwardRef(
     );
     const toValue = eventToValue ?? ((e) => e.target.value);
     const errorId = errorIdFromKey(fieldKey);
+    const describedBy = error ? [props["aria-describedby"], errorId].filter(Boolean).join(" ") : props["aria-describedby"];
     return /* @__PURE__ */ React.createElement(React.Fragment, null, /* @__PURE__ */ React.createElement(
       Component,
       {
-        "aria-invalid": error ? true : void 0,
-        "aria-describedby": error && renderError ? errorId : void 0,
         ...props,
         name: fieldKey,
         onBlur,
         ...asProps,
         ...valueToProps ? valueToProps(value) : { value },
+        "aria-invalid": error ? true : props["aria-invalid"],
+        "aria-describedby": describedBy,
         disabled: isDisabled,
         onChange: (e) => onChange(toValue(e)),
         ref: mergedRef
@@ -1610,12 +1636,13 @@ const Checkbox = React.forwardRef(
     return /* @__PURE__ */ React.createElement(
       "input",
       {
-        "aria-invalid": error ? true : void 0,
         ...props,
         name: fieldKey,
         onBlur,
         type: "checkbox",
         checked: !!value,
+        "aria-invalid": error ? true : props["aria-invalid"],
+        "aria-describedby": error ? [props["aria-describedby"], errorIdFromKey(fieldKey)].filter(Boolean).join(" ") : props["aria-describedby"],
         disabled: isDisabled,
         onChange: (e) => onChange(e.target.checked),
         ref
@@ -1663,12 +1690,13 @@ const Select = React.forwardRef(
     return /* @__PURE__ */ React.createElement(
       "select",
       {
-        "aria-invalid": error ? true : void 0,
         ...props,
         name: fieldKey,
         onBlur,
         multiple,
         value: toSelectValue(multiple, value),
+        "aria-invalid": error ? true : props["aria-invalid"],
+        "aria-describedby": error ? [props["aria-describedby"], errorIdFromKey(fieldKey)].filter(Boolean).join(" ") : props["aria-describedby"],
         disabled: isDisabled,
         onChange: (e) => onChange(
           multiple ? Array.from(e.target.selectedOptions, (option) => option.value) : e.target.value
@@ -1680,5 +1708,5 @@ const Select = React.forwardRef(
   }
 );
 
-export { Checkbox, CheckboxGroupContext, CheckboxGroupProvider, Field, Form, FormContext, FormProvider, Select, VALIDATION_OUTCOME, clearErrors, create as createForm, createFormContext, ensureValidate, getDirtyFields, getError, getErrorByPath, getErrors, getFieldErrors, getFieldErrorsByPath, getFieldState, getFirstError, getTouchedFields, getValue, getValueByPath, getValues, handleSubmit, hasErrors, hasTouched, hasTouchedByPath, incrementSubmitCount, isDirty, isTouched, removeField, removeFieldByPath, reset, resetField, setDisabled, setError, setErrorByPath, setFocus, setInitialValues, setIsSubmitting, setSubmitSuccessful, setTouched, setTouchedByPath, setValidatingByPath, setValue, setValueByPath, subscribe, trigger, unsetValidatingByPath, useCheckboxGroupContext, useDirtyFields, useError, useErrorByPath, useField, useFieldArray, useFieldErrors, useFieldErrorsByPath, useForm, useFormContext, useHasErrors, useIsDirty, useIsSubmitting, useSubmitCount, useTouched, useTouchedByPath, useTouchedFields, useValue, useValueByPath, useWatch, validate };
+export { Checkbox, CheckboxGroupContext, CheckboxGroupProvider, Field, Form, FormContext, FormProvider, Select, VALIDATION_OUTCOME, clearErrors, create as createForm, createFormContext, ensureValidate, fieldErrorId, getDirtyFields, getError, getErrorByPath, getErrors, getFieldErrors, getFieldErrorsByPath, getFieldState, getFirstError, getTouchedFields, getValue, getValueByPath, getValues, handleSubmit, hasErrors, hasTouched, hasTouchedByPath, incrementSubmitCount, isDirty, isTouched, removeField, removeFieldByPath, reset, resetField, setDisabled, setError, setErrorByPath, setFocus, setInitialValues, setIsSubmitting, setServerErrors, setSubmitSuccessful, setTouched, setTouchedByPath, setValidatingByPath, setValue, setValueByPath, subscribe, trigger, unsetValidatingByPath, useCheckboxGroupContext, useDirtyFields, useError, useErrorByPath, useField, useFieldArray, useFieldErrors, useFieldErrorsByPath, useForm, useFormContext, useHasErrors, useIsDirty, useIsSubmitting, useSubmitCount, useTouched, useTouchedByPath, useTouchedFields, useValue, useValueByPath, useWatch, validate };
 //# sourceMappingURL=index.mjs.map