@fransek/form 0.2.0 → 0.2.1

package/dist/cjs/index.d.ts

@@ -1,4 +1,4 @@
-export * from "./lib/Field";
-export * from "./lib/fieldState";
-export * from "./lib/Form";
-export * from "./lib/types";
+export { Field } from "./lib/Field";
+export { createFieldState, validate, validateAsync, validateIfDirty, validateIfDirtyAsync, } from "./lib/fieldState";
+export { Form } from "./lib/Form";
+export type { AsyncValidator, FieldProps, FieldRenderProps, FieldState, SyncValidator, Validation, ValidationMode, Validator, } from "./lib/types";

package/dist/cjs/index.js

@@ -13,7 +13,4 @@ exports.validateAsync = fieldState.validateAsync;
 exports.validateIfDirty = fieldState.validateIfDirty;
 exports.validateIfDirtyAsync = fieldState.validateIfDirtyAsync;
 exports.Form = Form.Form;
-exports.FormContext = Form.FormContext;
-exports.focusFirstError = Form.focusFirstError;
-exports.useFormContext = Form.useFormContext;
 //# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;"}

package/dist/cjs/lib/Field.d.ts

@@ -1,2 +1,8 @@
 import { FieldProps } from "./types";
+/**
+ * A headless form field component that manages validation state using a render prop pattern.
+ *
+ * Connects to a parent {@link Form} for submit validation coordination.
+ * Passes current field state and event handlers to the `children` render function.
+ */
 export declare function Field<T>(props: FieldProps<T>): import("react").ReactNode;

package/dist/cjs/lib/Field.js

@@ -4,10 +4,17 @@ var React = require('react');
 var fieldState = require('./fieldState.js');
 var Form = require('./Form.js');
 
+/**
+ * A headless form field component that manages validation state using a render prop pattern.
+ *
+ * Connects to a parent {@link Form} for submit validation coordination.
+ * Passes current field state and event handlers to the `children` render function.
+ */
 function Field(props) {
     const { registerField, unregisterField, validationMode: formValidationMode, debounceMs: formDebounceMs, } = Form.useFormContext();
     const { children, state, onChange, onInput, onBlur, validation, debounceMs = formDebounceMs || 500, validationMode = formValidationMode || "touchedAndDirty", } = props;
     const stateRef = React.useRef(state);
+    stateRef.current = state;
     const validationTimeoutRef = React.useRef(null);
     const validationIdRef = React.useRef(0);
     const isValidatingOnBlurRef = React.useRef(false);
@@ -15,14 +22,8 @@ function Field(props) {
     const pendingValidationRef = React.useRef(null);
     const fieldRef = React.useRef(null);
     const id = React.useId();
-    stateRef.current = state;
     React.useEffect(() => {
         async function performValidation() {
-            if (!stateRef.current.isValidating &&
-                stateRef.current.isDirty &&
-                stateRef.current.isTouched) {
-                return stateRef.current.isValid;
-            }
             validationIdRef.current++;
             pendingValidationRef.current = fieldState.validate(stateRef.current, validation?.onChange, validation?.onBlur, validation?.onSubmit);
             if (pendingValidationRef.current.isValid) {
@@ -57,7 +58,7 @@ function Field(props) {
         const shouldValidate = validationMode === "dirty" ||
             validationMode === "touchedOrDirty" ||
             stateRef.current.isTouched;
-        if (shouldValidate && (validation?.onChange || validation?.onChangeAsync)) {
+        if (shouldValidate) {
             const errorMessage = validation?.onChange?.(value);
             const willValidateAsync = Boolean(validation?.onChangeAsync && !errorMessage);
             onChange({
@@ -98,9 +99,10 @@ function Field(props) {
         const currentValidation = validationIdRef.current;
         let errorMessage = stateRef.current.errorMessage ||
             validation?.onBlur?.(stateRef.current.value);
-        const shouldValidateOnChange = validationMode === "touched" ||
-            validationMode === "touchedOrDirty" ||
-            (validationMode === "touchedAndDirty" && stateRef.current.isDirty);
+        const shouldValidateOnChange = !stateRef.current.isTouched &&
+            (validationMode === "touched" ||
+                (validationMode === "touchedOrDirty" && !stateRef.current.isDirty) ||
+                (validationMode === "touchedAndDirty" && stateRef.current.isDirty));
         if (!errorMessage && shouldValidateOnChange && validation?.onChange) {
             errorMessage = validation.onChange(stateRef.current.value);
         }

package/dist/cjs/lib/Field.js.map

@@ -1 +1 @@
-{"version":3,"file":"Field.js","sources":["../../../src/lib/Field.tsx"],"sourcesContent":["import { useEffect, useId, useRef } from \"react\";\nimport { validate, validateAsync } from \"./fieldState\";\nimport { useFormContext } from \"./Form\";\nimport { FieldProps, FieldState } from \"./types\";\n\nexport function Field<T>(props: FieldProps<T>) {\n  const {\n    registerField,\n    unregisterField,\n    validationMode: formValidationMode,\n    debounceMs: formDebounceMs,\n  } = useFormContext();\n\n  const {\n    children,\n    state,\n    onChange,\n    onInput,\n    onBlur,\n    validation,\n    debounceMs = formDebounceMs || 500,\n    validationMode = formValidationMode || \"touchedAndDirty\",\n  } = props;\n\n  const stateRef = useRef(state);\n  const validationTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(\n    null,\n  );\n  const validationIdRef = useRef(0);\n  const isValidatingOnBlurRef = useRef(false);\n  const isValidatingOnChangeRef = useRef(false);\n  const pendingValidationRef = useRef<FieldState<T> | null>(null);\n  const fieldRef = useRef<HTMLElement | null>(null);\n  const id = useId();\n\n  stateRef.current = state;\n\n  useEffect(() => {\n    async function performValidation() {\n      if (\n        !stateRef.current.isValidating &&\n        stateRef.current.isDirty &&\n        stateRef.current.isTouched\n      ) {\n        return stateRef.current.isValid;\n      }\n      validationIdRef.current++;\n      pendingValidationRef.current = validate(\n        stateRef.current,\n        validation?.onChange,\n        validation?.onBlur,\n        validation?.onSubmit,\n      );\n      if (pendingValidationRef.current.isValid) {\n        pendingValidationRef.current = await validateAsync(\n          stateRef.current,\n          validation?.onChangeAsync,\n          validation?.onBlurAsync,\n          validation?.onSubmitAsync,\n        );\n      }\n      return pendingValidationRef.current.isValid;\n    }\n\n    function commitPendingValidation() {\n      if (pendingValidationRef.current) {\n        onChange(pendingValidationRef.current);\n        pendingValidationRef.current = null;\n      }\n    }\n\n    registerField(\n      id,\n      fieldRef.current,\n      performValidation,\n      commitPendingValidation,\n    );\n\n    return () => {\n      unregisterField(id);\n    };\n  }, [id, registerField, validation, onChange, unregisterField]);\n\n  useEffect(() => {\n    return () => {\n      if (validationTimeoutRef.current) {\n        clearTimeout(validationTimeoutRef.current);\n      }\n    };\n  }, []);\n\n  function handleChange(value: T) {\n    onInput?.(value);\n\n    if (validationTimeoutRef.current) {\n      clearTimeout(validationTimeoutRef.current);\n    }\n\n    const currentValidation = ++validationIdRef.current;\n\n    const shouldValidate =\n      validationMode === \"dirty\" ||\n      validationMode === \"touchedOrDirty\" ||\n      stateRef.current.isTouched;\n\n    if (shouldValidate && (validation?.onChange || validation?.onChangeAsync)) {\n      const errorMessage = validation?.onChange?.(value);\n      const willValidateAsync = Boolean(\n        validation?.onChangeAsync && !errorMessage,\n      );\n\n      onChange({\n        ...stateRef.current,\n        value,\n        errorMessage,\n        isDirty: true,\n        isValid: !errorMessage,\n        isValidating: willValidateAsync,\n      });\n\n      if (willValidateAsync) {\n        isValidatingOnChangeRef.current = true;\n        validationTimeoutRef.current = setTimeout(async () => {\n          const asyncErrorMessage = await validation?.onChangeAsync?.(value);\n\n          isValidatingOnChangeRef.current = false;\n          if (currentValidation === validationIdRef.current) {\n            onChange({\n              ...stateRef.current,\n              errorMessage: asyncErrorMessage,\n              isValid: !asyncErrorMessage,\n              isValidating: isValidatingOnBlurRef.current,\n            });\n          }\n        }, debounceMs);\n      }\n    } else {\n      onChange({\n        ...stateRef.current,\n        value,\n        isDirty: true,\n        isValidating: false,\n      });\n    }\n  }\n\n  async function handleBlur() {\n    onBlur?.();\n\n    const currentValidation = validationIdRef.current;\n\n    let errorMessage =\n      stateRef.current.errorMessage ||\n      validation?.onBlur?.(stateRef.current.value);\n\n    const shouldValidateOnChange =\n      validationMode === \"touched\" ||\n      validationMode === \"touchedOrDirty\" ||\n      (validationMode === \"touchedAndDirty\" && stateRef.current.isDirty);\n\n    if (!errorMessage && shouldValidateOnChange && validation?.onChange) {\n      errorMessage = validation.onChange(stateRef.current.value);\n    }\n\n    if (\n      !errorMessage &&\n      (validation?.onBlurAsync || validation?.onChangeAsync)\n    ) {\n      isValidatingOnBlurRef.current = true;\n      onChange({\n        ...stateRef.current,\n        isValidating: true,\n        isTouched: true,\n      });\n\n      const asyncValidations: Promise<React.ReactNode>[] = [];\n\n      if (validation?.onBlurAsync) {\n        asyncValidations.push(validation.onBlurAsync(stateRef.current.value));\n      }\n\n      if (shouldValidateOnChange && validation?.onChangeAsync) {\n        asyncValidations.push(validation.onChangeAsync(stateRef.current.value));\n      }\n\n      const [blurError, changeError] = await Promise.all(asyncValidations);\n      errorMessage = blurError || changeError;\n    }\n\n    isValidatingOnBlurRef.current = false;\n\n    if (errorMessage && validationTimeoutRef.current) {\n      clearTimeout(validationTimeoutRef.current);\n    }\n\n    if (currentValidation !== validationIdRef.current) {\n      onChange({\n        ...stateRef.current,\n        isTouched: true,\n      });\n      return;\n    }\n\n    onChange({\n      ...stateRef.current,\n      errorMessage,\n      isTouched: true,\n      isValid: !errorMessage,\n      isValidating: isValidatingOnChangeRef.current,\n    });\n  }\n\n  const ref = (el: HTMLElement | null) => {\n    fieldRef.current = el;\n  };\n\n  return children({\n    ...stateRef.current,\n    handleChange,\n    handleBlur,\n    ref,\n  });\n}\n"],"names":["useFormContext","useRef","useId","useEffect","validate","validateAsync"],"mappings":"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"}
+{"version":3,"file":"Field.js","sources":["../../../src/lib/Field.tsx"],"sourcesContent":["import { useEffect, useId, useRef } from \"react\";\nimport { validate, validateAsync } from \"./fieldState\";\nimport { useFormContext } from \"./Form\";\nimport { FieldProps, FieldState } from \"./types\";\n\n/**\n * A headless form field component that manages validation state using a render prop pattern.\n *\n * Connects to a parent {@link Form} for submit validation coordination.\n * Passes current field state and event handlers to the `children` render function.\n */\nexport function Field<T>(props: FieldProps<T>) {\n  const {\n    registerField,\n    unregisterField,\n    validationMode: formValidationMode,\n    debounceMs: formDebounceMs,\n  } = useFormContext();\n\n  const {\n    children,\n    state,\n    onChange,\n    onInput,\n    onBlur,\n    validation,\n    debounceMs = formDebounceMs || 500,\n    validationMode = formValidationMode || \"touchedAndDirty\",\n  } = props;\n\n  const stateRef = useRef(state);\n  stateRef.current = state;\n  const validationTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(\n    null,\n  );\n  const validationIdRef = useRef(0);\n  const isValidatingOnBlurRef = useRef(false);\n  const isValidatingOnChangeRef = useRef(false);\n  const pendingValidationRef = useRef<FieldState<T> | null>(null);\n  const fieldRef = useRef<HTMLElement | null>(null);\n  const id = useId();\n\n  useEffect(() => {\n    async function performValidation() {\n      validationIdRef.current++;\n      pendingValidationRef.current = validate(\n        stateRef.current,\n        validation?.onChange,\n        validation?.onBlur,\n        validation?.onSubmit,\n      );\n      if (pendingValidationRef.current.isValid) {\n        pendingValidationRef.current = await validateAsync(\n          stateRef.current,\n          validation?.onChangeAsync,\n          validation?.onBlurAsync,\n          validation?.onSubmitAsync,\n        );\n      }\n      return pendingValidationRef.current.isValid;\n    }\n\n    function commitPendingValidation() {\n      if (pendingValidationRef.current) {\n        onChange(pendingValidationRef.current);\n        pendingValidationRef.current = null;\n      }\n    }\n\n    registerField(\n      id,\n      fieldRef.current,\n      performValidation,\n      commitPendingValidation,\n    );\n\n    return () => {\n      unregisterField(id);\n    };\n  }, [id, registerField, validation, onChange, unregisterField]);\n\n  useEffect(() => {\n    return () => {\n      if (validationTimeoutRef.current) {\n        clearTimeout(validationTimeoutRef.current);\n      }\n    };\n  }, []);\n\n  function handleChange(value: T) {\n    onInput?.(value);\n\n    if (validationTimeoutRef.current) {\n      clearTimeout(validationTimeoutRef.current);\n    }\n\n    const currentValidation = ++validationIdRef.current;\n\n    const shouldValidate =\n      validationMode === \"dirty\" ||\n      validationMode === \"touchedOrDirty\" ||\n      stateRef.current.isTouched;\n\n    if (shouldValidate) {\n      const errorMessage = validation?.onChange?.(value);\n      const willValidateAsync = Boolean(\n        validation?.onChangeAsync && !errorMessage,\n      );\n\n      onChange({\n        ...stateRef.current,\n        value,\n        errorMessage,\n        isDirty: true,\n        isValid: !errorMessage,\n        isValidating: willValidateAsync,\n      });\n\n      if (willValidateAsync) {\n        isValidatingOnChangeRef.current = true;\n        validationTimeoutRef.current = setTimeout(async () => {\n          const asyncErrorMessage = await validation?.onChangeAsync?.(value);\n\n          isValidatingOnChangeRef.current = false;\n          if (currentValidation === validationIdRef.current) {\n            onChange({\n              ...stateRef.current,\n              errorMessage: asyncErrorMessage,\n              isValid: !asyncErrorMessage,\n              isValidating: isValidatingOnBlurRef.current,\n            });\n          }\n        }, debounceMs);\n      }\n    } else {\n      onChange({\n        ...stateRef.current,\n        value,\n        isDirty: true,\n        isValidating: false,\n      });\n    }\n  }\n\n  async function handleBlur() {\n    onBlur?.();\n\n    const currentValidation = validationIdRef.current;\n\n    let errorMessage =\n      stateRef.current.errorMessage ||\n      validation?.onBlur?.(stateRef.current.value);\n\n    const shouldValidateOnChange =\n      !stateRef.current.isTouched &&\n      (validationMode === \"touched\" ||\n        (validationMode === \"touchedOrDirty\" && !stateRef.current.isDirty) ||\n        (validationMode === \"touchedAndDirty\" && stateRef.current.isDirty));\n\n    if (!errorMessage && shouldValidateOnChange && validation?.onChange) {\n      errorMessage = validation.onChange(stateRef.current.value);\n    }\n\n    if (\n      !errorMessage &&\n      (validation?.onBlurAsync || validation?.onChangeAsync)\n    ) {\n      isValidatingOnBlurRef.current = true;\n      onChange({\n        ...stateRef.current,\n        isValidating: true,\n        isTouched: true,\n      });\n\n      const asyncValidations: Promise<React.ReactNode>[] = [];\n\n      if (validation?.onBlurAsync) {\n        asyncValidations.push(validation.onBlurAsync(stateRef.current.value));\n      }\n\n      if (shouldValidateOnChange && validation?.onChangeAsync) {\n        asyncValidations.push(validation.onChangeAsync(stateRef.current.value));\n      }\n\n      const [blurError, changeError] = await Promise.all(asyncValidations);\n      errorMessage = blurError || changeError;\n    }\n\n    isValidatingOnBlurRef.current = false;\n\n    if (errorMessage && validationTimeoutRef.current) {\n      clearTimeout(validationTimeoutRef.current);\n    }\n\n    if (currentValidation !== validationIdRef.current) {\n      onChange({\n        ...stateRef.current,\n        isTouched: true,\n      });\n      return;\n    }\n\n    onChange({\n      ...stateRef.current,\n      errorMessage,\n      isTouched: true,\n      isValid: !errorMessage,\n      isValidating: isValidatingOnChangeRef.current,\n    });\n  }\n\n  const ref = (el: HTMLElement | null) => {\n    fieldRef.current = el;\n  };\n\n  return children({\n    ...stateRef.current,\n    handleChange,\n    handleBlur,\n    ref,\n  });\n}\n"],"names":["useFormContext","useRef","useId","useEffect","validate","validateAsync"],"mappings":"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"}

package/dist/cjs/lib/Form.d.ts

@@ -1,10 +1,26 @@
 import React from "react";
 import { FormContextValue, ValidationMode } from "./types";
+/** Props for the {@link Form} component. */
 interface FormProps extends Omit<React.ComponentProps<"form">, "onSubmit"> {
+    /** Default validation mode applied to all fields in the form. Defaults to `"touchedAndDirty"`. */
     validationMode?: ValidationMode;
+    /** Default debounce delay in milliseconds for async validators. Defaults to `500`. */
     debounceMs?: number;
-    onSubmit?: (e: React.SubmitEvent<HTMLFormElement>, validateAllFields: () => Promise<boolean>) => void;
+    /**
+     * Submit handler called when the form is submitted.
+     * Receives the submit event and a `validateAllFields` function that triggers
+     * validation on all registered fields and returns whether the form is valid.
+     */
+    onSubmit?: (e: React.SubmitEvent<HTMLFormElement>, validateForm: () => Promise<boolean>) => void;
 }
+/**
+ * A form component that provides context for coordinating field validation.
+ *
+ * Wraps a native `<form>` element and prevents the default submit behavior.
+ * On submit, the `onSubmit` callback is called with the submit event and a
+ * `validateAllFields` function that can be used to trigger validation on all
+ * registered {@link Field} components and focus the first invalid field.
+ */
 export declare function Form({ onSubmit, validationMode, debounceMs, ...props }: FormProps): React.JSX.Element;
 export declare const FormContext: React.Context<FormContextValue>;
 export declare function useFormContext(): FormContextValue;

package/dist/cjs/lib/Form.js

@@ -2,6 +2,14 @@
 
 var React = require('react');
 
+/**
+ * A form component that provides context for coordinating field validation.
+ *
+ * Wraps a native `<form>` element and prevents the default submit behavior.
+ * On submit, the `onSubmit` callback is called with the submit event and a
+ * `validateAllFields` function that can be used to trigger validation on all
+ * registered {@link Field} components and focus the first invalid field.
+ */
 function Form({ onSubmit, validationMode, debounceMs, ...props }) {
     const fieldsRef = React.useRef(new Map());
     const registerField = React.useCallback((id, ref, validate, commitPendingValidation) => {
@@ -14,7 +22,7 @@ function Form({ onSubmit, validationMode, debounceMs, ...props }) {
     const unregisterField = React.useCallback((id) => {
         fieldsRef.current.delete(id);
     }, []);
-    const validateAllFields = React.useCallback(async () => {
+    const validateForm = React.useCallback(async () => {
         const fields = Array.from(fieldsRef.current.values());
         const validationPromises = fields.map(async (field) => ({
             isValid: await field.validate(),
@@ -34,7 +42,7 @@ function Form({ onSubmit, validationMode, debounceMs, ...props }) {
             validationMode,
             debounceMs,
         } },
-        React.createElement("form", { onSubmit: (e) => onSubmit?.(e, validateAllFields), ...props })));
+        React.createElement("form", { onSubmit: (e) => onSubmit?.(e, validateForm), ...props })));
 }
 const FormContext = React.createContext({
     registerField: () => { },
@@ -52,26 +60,11 @@ function focusFirstError(results) {
     if (!firstInvalidField) {
         return;
     }
-    let firstInvalid = firstInvalidField;
-    if (firstInvalid.role === "radiogroup") {
-        const radio = firstInvalid.querySelector('[role="radio"]');
-        if (radio) {
-            firstInvalid = radio;
-        }
-    }
-    if (firstInvalid.role === "group") {
-        const checkbox = firstInvalid.querySelector('[role="checkbox"]');
-        if (checkbox) {
-            firstInvalid = checkbox;
-        }
-    }
-    firstInvalid.focus();
-    const rect = firstInvalid.getBoundingClientRect();
-    if (rect) {
-        window.scrollTo({
-            top: rect.top + window.scrollY - 100,
-        });
-    }
+    firstInvalidField.focus();
+    const rect = firstInvalidField.getBoundingClientRect();
+    window.scrollTo({
+        top: rect.top + window.scrollY - 100,
+    });
 }
 
 exports.Form = Form;

package/dist/cjs/lib/Form.js.map

@@ -1 +1 @@
-{"version":3,"file":"Form.js","sources":["../../../src/lib/Form.tsx"],"sourcesContent":["import React, { useCallback, useRef } from \"react\";\nimport { FieldMap, FormContextValue, ValidationMode } from \"./types\";\n\ninterface FormProps extends Omit<React.ComponentProps<\"form\">, \"onSubmit\"> {\n  validationMode?: ValidationMode;\n  debounceMs?: number;\n  onSubmit?: (\n    e: React.SubmitEvent<HTMLFormElement>,\n    validateAllFields: () => Promise<boolean>,\n  ) => void;\n}\n\nexport function Form({\n  onSubmit,\n  validationMode,\n  debounceMs,\n  ...props\n}: FormProps) {\n  const fieldsRef = useRef<FieldMap>(new Map());\n\n  const registerField = useCallback(\n    (\n      id: string,\n      ref: HTMLElement | null,\n      validate: () => Promise<boolean>,\n      commitPendingValidation: () => void,\n    ) => {\n      fieldsRef.current.set(id, {\n        ref,\n        validate,\n        commitPendingValidation,\n      });\n    },\n    [],\n  );\n\n  const unregisterField = useCallback((id: string) => {\n    fieldsRef.current.delete(id);\n  }, []);\n\n  const validateAllFields = useCallback(async () => {\n    const fields = Array.from(fieldsRef.current.values());\n    const validationPromises = fields.map(async (field) => ({\n      isValid: await field.validate(),\n      ref: field.ref,\n    }));\n    const results = await Promise.all(validationPromises);\n    fields.forEach((field) => field.commitPendingValidation());\n    const hasErrors = results.some((result) => !result.isValid);\n    if (hasErrors) {\n      focusFirstError(results);\n    }\n    return !hasErrors;\n  }, []);\n\n  return (\n    <FormContext.Provider\n      value={{\n        registerField,\n        unregisterField,\n        validationMode,\n        debounceMs,\n      }}\n    >\n      <form onSubmit={(e) => onSubmit?.(e, validateAllFields)} {...props} />\n    </FormContext.Provider>\n  );\n}\n\nexport const FormContext = React.createContext<FormContextValue>({\n  registerField: () => {},\n  unregisterField: () => {},\n});\n\nexport function useFormContext() {\n  return React.useContext(FormContext);\n}\n\nexport function focusFirstError(\n  results: {\n    isValid: boolean;\n    ref: HTMLElement | null;\n  }[],\n) {\n  const firstInvalidField = results\n    .filter((field) => !field.isValid && field.ref)\n    .map((field) => field.ref!)\n    .sort((a, b) =>\n      a.compareDocumentPosition(b) & Node.DOCUMENT_POSITION_PRECEDING ? 1 : -1,\n    )\n    .at(0);\n\n  if (!firstInvalidField) {\n    return;\n  }\n\n  let firstInvalid = firstInvalidField;\n\n  if (firstInvalid.role === \"radiogroup\") {\n    const radio = firstInvalid.querySelector<HTMLElement>('[role=\"radio\"]');\n    if (radio) {\n      firstInvalid = radio;\n    }\n  }\n\n  if (firstInvalid.role === \"group\") {\n    const checkbox =\n      firstInvalid.querySelector<HTMLElement>('[role=\"checkbox\"]');\n    if (checkbox) {\n      firstInvalid = checkbox;\n    }\n  }\n\n  firstInvalid.focus();\n  const rect = firstInvalid.getBoundingClientRect();\n  if (rect) {\n    window.scrollTo({\n      top: rect.top + window.scrollY - 100,\n    });\n  }\n}\n"],"names":["useRef","useCallback"],"mappings":";;;;AAYM,SAAU,IAAI,CAAC,EACnB,QAAQ,EACR,cAAc,EACd,UAAU,EACV,GAAG,KAAK,EACE,EAAA;IACV,MAAM,SAAS,GAAGA,YAAM,CAAW,IAAI,GAAG,EAAE,CAAC;AAE7C,IAAA,MAAM,aAAa,GAAGC,iBAAW,CAC/B,CACE,EAAU,EACV,GAAuB,EACvB,QAAgC,EAChC,uBAAmC,KACjC;AACF,QAAA,SAAS,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,EAAE;YACxB,GAAG;YACH,QAAQ;YACR,uBAAuB;AACxB,SAAA,CAAC;IACJ,CAAC,EACD,EAAE,CACH;AAED,IAAA,MAAM,eAAe,GAAGA,iBAAW,CAAC,CAAC,EAAU,KAAI;AACjD,QAAA,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;IAC9B,CAAC,EAAE,EAAE,CAAC;AAEN,IAAA,MAAM,iBAAiB,GAAGA,iBAAW,CAAC,YAAW;AAC/C,QAAA,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC;AACrD,QAAA,MAAM,kBAAkB,GAAG,MAAM,CAAC,GAAG,CAAC,OAAO,KAAK,MAAM;AACtD,YAAA,OAAO,EAAE,MAAM,KAAK,CAAC,QAAQ,EAAE;YAC/B,GAAG,EAAE,KAAK,CAAC,GAAG;AACf,SAAA,CAAC,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC;AACrD,QAAA,MAAM,CAAC,OAAO,CAAC,CAAC,KAAK,KAAK,KAAK,CAAC,uBAAuB,EAAE,CAAC;AAC1D,QAAA,MAAM,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC;QAC3D,IAAI,SAAS,EAAE;YACb,eAAe,CAAC,OAAO,CAAC;QAC1B;QACA,OAAO,CAAC,SAAS;IACnB,CAAC,EAAE,EAAE,CAAC;AAEN,IAAA,QACE,KAAA,CAAA,aAAA,CAAC,WAAW,CAAC,QAAQ,EAAA,EACnB,KAAK,EAAE;YACL,aAAa;YACb,eAAe;YACf,cAAc;YACd,UAAU;AACX,SAAA,EAAA;AAED,QAAA,KAAA,CAAA,aAAA,CAAA,MAAA,EAAA,EAAM,QAAQ,EAAE,CAAC,CAAC,KAAK,QAAQ,GAAG,CAAC,EAAE,iBAAiB,CAAC,EAAA,GAAM,KAAK,EAAA,CAAI,CACjD;AAE3B;AAEO,MAAM,WAAW,GAAG,KAAK,CAAC,aAAa,CAAmB;AAC/D,IAAA,aAAa,EAAE,MAAK,EAAE,CAAC;AACvB,IAAA,eAAe,EAAE,MAAK,EAAE,CAAC;AAC1B,CAAA;SAEe,cAAc,GAAA;AAC5B,IAAA,OAAO,KAAK,CAAC,UAAU,CAAC,WAAW,CAAC;AACtC;AAEM,SAAU,eAAe,CAC7B,OAGG,EAAA;IAEH,MAAM,iBAAiB,GAAG;AACvB,SAAA,MAAM,CAAC,CAAC,KAAK,KAAK,CAAC,KAAK,CAAC,OAAO,IAAI,KAAK,CAAC,GAAG;SAC7C,GAAG,CAAC,CAAC,KAAK,KAAK,KAAK,CAAC,GAAI;SACzB,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,KACT,CAAC,CAAC,uBAAuB,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,2BAA2B,GAAG,CAAC,GAAG,EAAE;SAEzE,EAAE,CAAC,CAAC,CAAC;IAER,IAAI,CAAC,iBAAiB,EAAE;QACtB;IACF;IAEA,IAAI,YAAY,GAAG,iBAAiB;AAEpC,IAAA,IAAI,YAAY,CAAC,IAAI,KAAK,YAAY,EAAE;QACtC,MAAM,KAAK,GAAG,YAAY,CAAC,aAAa,CAAc,gBAAgB,CAAC;QACvE,IAAI,KAAK,EAAE;YACT,YAAY,GAAG,KAAK;QACtB;IACF;AAEA,IAAA,IAAI,YAAY,CAAC,IAAI,KAAK,OAAO,EAAE;QACjC,MAAM,QAAQ,GACZ,YAAY,CAAC,aAAa,CAAc,mBAAmB,CAAC;QAC9D,IAAI,QAAQ,EAAE;YACZ,YAAY,GAAG,QAAQ;QACzB;IACF;IAEA,YAAY,CAAC,KAAK,EAAE;AACpB,IAAA,MAAM,IAAI,GAAG,YAAY,CAAC,qBAAqB,EAAE;IACjD,IAAI,IAAI,EAAE;QACR,MAAM,CAAC,QAAQ,CAAC;YACd,GAAG,EAAE,IAAI,CAAC,GAAG,GAAG,MAAM,CAAC,OAAO,GAAG,GAAG;AACrC,SAAA,CAAC;IACJ;AACF;;;;;;;"}
+{"version":3,"file":"Form.js","sources":["../../../src/lib/Form.tsx"],"sourcesContent":["import React, { useCallback, useRef } from \"react\";\nimport { FieldMap, FormContextValue, ValidationMode } from \"./types\";\n\n/** Props for the {@link Form} component. */\ninterface FormProps extends Omit<React.ComponentProps<\"form\">, \"onSubmit\"> {\n  /** Default validation mode applied to all fields in the form. Defaults to `\"touchedAndDirty\"`. */\n  validationMode?: ValidationMode;\n  /** Default debounce delay in milliseconds for async validators. Defaults to `500`. */\n  debounceMs?: number;\n  /**\n   * Submit handler called when the form is submitted.\n   * Receives the submit event and a `validateAllFields` function that triggers\n   * validation on all registered fields and returns whether the form is valid.\n   */\n  onSubmit?: (\n    e: React.SubmitEvent<HTMLFormElement>,\n    validateForm: () => Promise<boolean>,\n  ) => void;\n}\n\n/**\n * A form component that provides context for coordinating field validation.\n *\n * Wraps a native `<form>` element and prevents the default submit behavior.\n * On submit, the `onSubmit` callback is called with the submit event and a\n * `validateAllFields` function that can be used to trigger validation on all\n * registered {@link Field} components and focus the first invalid field.\n */\nexport function Form({\n  onSubmit,\n  validationMode,\n  debounceMs,\n  ...props\n}: FormProps) {\n  const fieldsRef = useRef<FieldMap>(new Map());\n\n  const registerField = useCallback(\n    (\n      id: string,\n      ref: HTMLElement | null,\n      validate: () => Promise<boolean>,\n      commitPendingValidation: () => void,\n    ) => {\n      fieldsRef.current.set(id, {\n        ref,\n        validate,\n        commitPendingValidation,\n      });\n    },\n    [],\n  );\n\n  const unregisterField = useCallback((id: string) => {\n    fieldsRef.current.delete(id);\n  }, []);\n\n  const validateForm = useCallback(async () => {\n    const fields = Array.from(fieldsRef.current.values());\n    const validationPromises = fields.map(async (field) => ({\n      isValid: await field.validate(),\n      ref: field.ref,\n    }));\n    const results = await Promise.all(validationPromises);\n    fields.forEach((field) => field.commitPendingValidation());\n    const hasErrors = results.some((result) => !result.isValid);\n    if (hasErrors) {\n      focusFirstError(results);\n    }\n    return !hasErrors;\n  }, []);\n\n  return (\n    <FormContext.Provider\n      value={{\n        registerField,\n        unregisterField,\n        validationMode,\n        debounceMs,\n      }}\n    >\n      <form onSubmit={(e) => onSubmit?.(e, validateForm)} {...props} />\n    </FormContext.Provider>\n  );\n}\n\nexport const FormContext = React.createContext<FormContextValue>({\n  registerField: () => {},\n  unregisterField: () => {},\n});\n\nexport function useFormContext() {\n  return React.useContext(FormContext);\n}\n\nexport function focusFirstError(\n  results: {\n    isValid: boolean;\n    ref: HTMLElement | null;\n  }[],\n) {\n  const firstInvalidField = results\n    .filter((field) => !field.isValid && field.ref)\n    .map((field) => field.ref!)\n    .sort((a, b) =>\n      a.compareDocumentPosition(b) & Node.DOCUMENT_POSITION_PRECEDING ? 1 : -1,\n    )\n    .at(0);\n\n  if (!firstInvalidField) {\n    return;\n  }\n\n  firstInvalidField.focus();\n  const rect = firstInvalidField.getBoundingClientRect();\n  window.scrollTo({\n    top: rect.top + window.scrollY - 100,\n  });\n}\n"],"names":["useRef","useCallback"],"mappings":"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"}

package/dist/cjs/lib/fieldState.d.ts

@@ -1,6 +1,23 @@
 import { FieldState, SyncValidator, Validator } from "./types";
+/** Creates the initial state for a field with the given initial value. */
 export declare function createFieldState<T>(initialValue: T): FieldState<T>;
+/**
+ * Runs the provided synchronous validators against the current field value and returns an updated {@link FieldState}.
+ * Sets `isDirty` and `isTouched` to `true`. Stops at the first failing validator.
+ */
 export declare function validate<T>(state: FieldState<T>, ...validators: Array<SyncValidator<T> | undefined>): FieldState<T>;
+/**
+ * Runs the provided synchronous and/or asynchronous validators against the current field value and returns an updated {@link FieldState}.
+ * Sets `isDirty` and `isTouched` to `true`. All validators run in parallel; the first truthy error message is used.
+ */
 export declare function validateAsync<T>(state: FieldState<T>, ...validators: Array<Validator<T> | undefined>): Promise<FieldState<T>>;
+/**
+ * Runs the provided synchronous validators only if the field is dirty (i.e. the value has been changed).
+ * Returns the state unchanged if the field is not dirty.
+ */
 export declare function validateIfDirty<T>(state: FieldState<T>, ...validators: Array<SyncValidator<T> | undefined>): FieldState<T>;
+/**
+ * Runs the provided synchronous and/or asynchronous validators only if the field is dirty (i.e. the value has been changed).
+ * Returns the state unchanged if the field is not dirty.
+ */
 export declare function validateIfDirtyAsync<T>(state: FieldState<T>, ...validators: Array<Validator<T> | undefined>): Promise<FieldState<T>>;

package/dist/cjs/lib/fieldState.js

@@ -1,5 +1,6 @@
 'use strict';
 
+/** Creates the initial state for a field with the given initial value. */
 function createFieldState(initialValue) {
     return {
         value: initialValue,
@@ -10,6 +11,10 @@ function createFieldState(initialValue) {
         isValidating: false,
     };
 }
+/**
+ * Runs the provided synchronous validators against the current field value and returns an updated {@link FieldState}.
+ * Sets `isDirty` and `isTouched` to `true`. Stops at the first failing validator.
+ */
 function validate(state, ...validators) {
     for (const validator of validators) {
         const errorMessage = validator?.(state.value);
@@ -33,6 +38,10 @@ function validate(state, ...validators) {
         isValidating: false,
     };
 }
+/**
+ * Runs the provided synchronous and/or asynchronous validators against the current field value and returns an updated {@link FieldState}.
+ * Sets `isDirty` and `isTouched` to `true`. All validators run in parallel; the first truthy error message is used.
+ */
 async function validateAsync(state, ...validators) {
     const errorMessages = await Promise.all(validators.map((validator) => validator?.(state.value)));
     const errorMessage = errorMessages.find(Boolean);
@@ -55,12 +64,20 @@ async function validateAsync(state, ...validators) {
         isValidating: false,
     };
 }
+/**
+ * Runs the provided synchronous validators only if the field is dirty (i.e. the value has been changed).
+ * Returns the state unchanged if the field is not dirty.
+ */
 function validateIfDirty(state, ...validators) {
     if (!state.isDirty) {
         return state;
     }
     return validate(state, ...validators);
 }
+/**
+ * Runs the provided synchronous and/or asynchronous validators only if the field is dirty (i.e. the value has been changed).
+ * Returns the state unchanged if the field is not dirty.
+ */
 async function validateIfDirtyAsync(state, ...validators) {
     if (!state.isDirty) {
         return state;

package/dist/cjs/lib/fieldState.js.map

@@ -1 +1 @@
-{"version":3,"file":"fieldState.js","sources":["../../../src/lib/fieldState.ts"],"sourcesContent":["import { FieldState, SyncValidator, Validator } from \"./types\";\n\nexport function createFieldState<T>(initialValue: T): FieldState<T> {\n  return {\n    value: initialValue,\n    errorMessage: undefined,\n    isTouched: false,\n    isDirty: false,\n    isValid: true,\n    isValidating: false,\n  };\n}\n\nexport function validate<T>(\n  state: FieldState<T>,\n  ...validators: Array<SyncValidator<T> | undefined>\n): FieldState<T> {\n  for (const validator of validators) {\n    const errorMessage = validator?.(state.value);\n    if (errorMessage) {\n      return {\n        ...state,\n        errorMessage,\n        isDirty: true,\n        isTouched: true,\n        isValid: false,\n        isValidating: false,\n      };\n    }\n  }\n\n  return {\n    ...state,\n    errorMessage: undefined,\n    isDirty: true,\n    isTouched: true,\n    isValid: true,\n    isValidating: false,\n  };\n}\n\nexport async function validateAsync<T>(\n  state: FieldState<T>,\n  ...validators: Array<Validator<T> | undefined>\n): Promise<FieldState<T>> {\n  const errorMessages = await Promise.all(\n    validators.map((validator) => validator?.(state.value)),\n  );\n  const errorMessage = errorMessages.find(Boolean);\n\n  if (errorMessage) {\n    return {\n      ...state,\n      errorMessage,\n      isDirty: true,\n      isTouched: true,\n      isValid: false,\n      isValidating: false,\n    };\n  }\n\n  return {\n    ...state,\n    errorMessage: undefined,\n    isDirty: true,\n    isTouched: true,\n    isValid: true,\n    isValidating: false,\n  };\n}\n\nexport function validateIfDirty<T>(\n  state: FieldState<T>,\n  ...validators: Array<SyncValidator<T> | undefined>\n): FieldState<T> {\n  if (!state.isDirty) {\n    return state;\n  }\n\n  return validate(state, ...validators);\n}\n\nexport async function validateIfDirtyAsync<T>(\n  state: FieldState<T>,\n  ...validators: Array<Validator<T> | undefined>\n): Promise<FieldState<T>> {\n  if (!state.isDirty) {\n    return state;\n  }\n\n  return validateAsync(state, ...validators);\n}\n"],"names":[],"mappings":";;AAEM,SAAU,gBAAgB,CAAI,YAAe,EAAA;IACjD,OAAO;AACL,QAAA,KAAK,EAAE,YAAY;AACnB,QAAA,YAAY,EAAE,SAAS;AACvB,QAAA,SAAS,EAAE,KAAK;AAChB,QAAA,OAAO,EAAE,KAAK;AACd,QAAA,OAAO,EAAE,IAAI;AACb,QAAA,YAAY,EAAE,KAAK;KACpB;AACH;SAEgB,QAAQ,CACtB,KAAoB,EACpB,GAAG,UAA+C,EAAA;AAElD,IAAA,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE;QAClC,MAAM,YAAY,GAAG,SAAS,GAAG,KAAK,CAAC,KAAK,CAAC;QAC7C,IAAI,YAAY,EAAE;YAChB,OAAO;AACL,gBAAA,GAAG,KAAK;gBACR,YAAY;AACZ,gBAAA,OAAO,EAAE,IAAI;AACb,gBAAA,SAAS,EAAE,IAAI;AACf,gBAAA,OAAO,EAAE,KAAK;AACd,gBAAA,YAAY,EAAE,KAAK;aACpB;QACH;IACF;IAEA,OAAO;AACL,QAAA,GAAG,KAAK;AACR,QAAA,YAAY,EAAE,SAAS;AACvB,QAAA,OAAO,EAAE,IAAI;AACb,QAAA,SAAS,EAAE,IAAI;AACf,QAAA,OAAO,EAAE,IAAI;AACb,QAAA,YAAY,EAAE,KAAK;KACpB;AACH;AAEO,eAAe,aAAa,CACjC,KAAoB,EACpB,GAAG,UAA2C,EAAA;IAE9C,MAAM,aAAa,GAAG,MAAM,OAAO,CAAC,GAAG,CACrC,UAAU,CAAC,GAAG,CAAC,CAAC,SAAS,KAAK,SAAS,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CACxD;IACD,MAAM,YAAY,GAAG,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC;IAEhD,IAAI,YAAY,EAAE;QAChB,OAAO;AACL,YAAA,GAAG,KAAK;YACR,YAAY;AACZ,YAAA,OAAO,EAAE,IAAI;AACb,YAAA,SAAS,EAAE,IAAI;AACf,YAAA,OAAO,EAAE,KAAK;AACd,YAAA,YAAY,EAAE,KAAK;SACpB;IACH;IAEA,OAAO;AACL,QAAA,GAAG,KAAK;AACR,QAAA,YAAY,EAAE,SAAS;AACvB,QAAA,OAAO,EAAE,IAAI;AACb,QAAA,SAAS,EAAE,IAAI;AACf,QAAA,OAAO,EAAE,IAAI;AACb,QAAA,YAAY,EAAE,KAAK;KACpB;AACH;SAEgB,eAAe,CAC7B,KAAoB,EACpB,GAAG,UAA+C,EAAA;AAElD,IAAA,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE;AAClB,QAAA,OAAO,KAAK;IACd;AAEA,IAAA,OAAO,QAAQ,CAAC,KAAK,EAAE,GAAG,UAAU,CAAC;AACvC;AAEO,eAAe,oBAAoB,CACxC,KAAoB,EACpB,GAAG,UAA2C,EAAA;AAE9C,IAAA,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE;AAClB,QAAA,OAAO,KAAK;IACd;AAEA,IAAA,OAAO,aAAa,CAAC,KAAK,EAAE,GAAG,UAAU,CAAC;AAC5C;;;;;;;;"}
+{"version":3,"file":"fieldState.js","sources":["../../../src/lib/fieldState.ts"],"sourcesContent":["import { FieldState, SyncValidator, Validator } from \"./types\";\n\n/** Creates the initial state for a field with the given initial value. */\nexport function createFieldState<T>(initialValue: T): FieldState<T> {\n  return {\n    value: initialValue,\n    errorMessage: undefined,\n    isTouched: false,\n    isDirty: false,\n    isValid: true,\n    isValidating: false,\n  };\n}\n\n/**\n * Runs the provided synchronous validators against the current field value and returns an updated {@link FieldState}.\n * Sets `isDirty` and `isTouched` to `true`. Stops at the first failing validator.\n */\nexport function validate<T>(\n  state: FieldState<T>,\n  ...validators: Array<SyncValidator<T> | undefined>\n): FieldState<T> {\n  for (const validator of validators) {\n    const errorMessage = validator?.(state.value);\n    if (errorMessage) {\n      return {\n        ...state,\n        errorMessage,\n        isDirty: true,\n        isTouched: true,\n        isValid: false,\n        isValidating: false,\n      };\n    }\n  }\n\n  return {\n    ...state,\n    errorMessage: undefined,\n    isDirty: true,\n    isTouched: true,\n    isValid: true,\n    isValidating: false,\n  };\n}\n\n/**\n * Runs the provided synchronous and/or asynchronous validators against the current field value and returns an updated {@link FieldState}.\n * Sets `isDirty` and `isTouched` to `true`. All validators run in parallel; the first truthy error message is used.\n */\nexport async function validateAsync<T>(\n  state: FieldState<T>,\n  ...validators: Array<Validator<T> | undefined>\n): Promise<FieldState<T>> {\n  const errorMessages = await Promise.all(\n    validators.map((validator) => validator?.(state.value)),\n  );\n  const errorMessage = errorMessages.find(Boolean);\n\n  if (errorMessage) {\n    return {\n      ...state,\n      errorMessage,\n      isDirty: true,\n      isTouched: true,\n      isValid: false,\n      isValidating: false,\n    };\n  }\n\n  return {\n    ...state,\n    errorMessage: undefined,\n    isDirty: true,\n    isTouched: true,\n    isValid: true,\n    isValidating: false,\n  };\n}\n\n/**\n * Runs the provided synchronous validators only if the field is dirty (i.e. the value has been changed).\n * Returns the state unchanged if the field is not dirty.\n */\nexport function validateIfDirty<T>(\n  state: FieldState<T>,\n  ...validators: Array<SyncValidator<T> | undefined>\n): FieldState<T> {\n  if (!state.isDirty) {\n    return state;\n  }\n\n  return validate(state, ...validators);\n}\n\n/**\n * Runs the provided synchronous and/or asynchronous validators only if the field is dirty (i.e. the value has been changed).\n * Returns the state unchanged if the field is not dirty.\n */\nexport async function validateIfDirtyAsync<T>(\n  state: FieldState<T>,\n  ...validators: Array<Validator<T> | undefined>\n): Promise<FieldState<T>> {\n  if (!state.isDirty) {\n    return state;\n  }\n\n  return validateAsync(state, ...validators);\n}\n"],"names":[],"mappings":";;AAEA;AACM,SAAU,gBAAgB,CAAI,YAAe,EAAA;IACjD,OAAO;AACL,QAAA,KAAK,EAAE,YAAY;AACnB,QAAA,YAAY,EAAE,SAAS;AACvB,QAAA,SAAS,EAAE,KAAK;AAChB,QAAA,OAAO,EAAE,KAAK;AACd,QAAA,OAAO,EAAE,IAAI;AACb,QAAA,YAAY,EAAE,KAAK;KACpB;AACH;AAEA;;;AAGG;SACa,QAAQ,CACtB,KAAoB,EACpB,GAAG,UAA+C,EAAA;AAElD,IAAA,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE;QAClC,MAAM,YAAY,GAAG,SAAS,GAAG,KAAK,CAAC,KAAK,CAAC;QAC7C,IAAI,YAAY,EAAE;YAChB,OAAO;AACL,gBAAA,GAAG,KAAK;gBACR,YAAY;AACZ,gBAAA,OAAO,EAAE,IAAI;AACb,gBAAA,SAAS,EAAE,IAAI;AACf,gBAAA,OAAO,EAAE,KAAK;AACd,gBAAA,YAAY,EAAE,KAAK;aACpB;QACH;IACF;IAEA,OAAO;AACL,QAAA,GAAG,KAAK;AACR,QAAA,YAAY,EAAE,SAAS;AACvB,QAAA,OAAO,EAAE,IAAI;AACb,QAAA,SAAS,EAAE,IAAI;AACf,QAAA,OAAO,EAAE,IAAI;AACb,QAAA,YAAY,EAAE,KAAK;KACpB;AACH;AAEA;;;AAGG;AACI,eAAe,aAAa,CACjC,KAAoB,EACpB,GAAG,UAA2C,EAAA;IAE9C,MAAM,aAAa,GAAG,MAAM,OAAO,CAAC,GAAG,CACrC,UAAU,CAAC,GAAG,CAAC,CAAC,SAAS,KAAK,SAAS,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CACxD;IACD,MAAM,YAAY,GAAG,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC;IAEhD,IAAI,YAAY,EAAE;QAChB,OAAO;AACL,YAAA,GAAG,KAAK;YACR,YAAY;AACZ,YAAA,OAAO,EAAE,IAAI;AACb,YAAA,SAAS,EAAE,IAAI;AACf,YAAA,OAAO,EAAE,KAAK;AACd,YAAA,YAAY,EAAE,KAAK;SACpB;IACH;IAEA,OAAO;AACL,QAAA,GAAG,KAAK;AACR,QAAA,YAAY,EAAE,SAAS;AACvB,QAAA,OAAO,EAAE,IAAI;AACb,QAAA,SAAS,EAAE,IAAI;AACf,QAAA,OAAO,EAAE,IAAI;AACb,QAAA,YAAY,EAAE,KAAK;KACpB;AACH;AAEA;;;AAGG;SACa,eAAe,CAC7B,KAAoB,EACpB,GAAG,UAA+C,EAAA;AAElD,IAAA,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE;AAClB,QAAA,OAAO,KAAK;IACd;AAEA,IAAA,OAAO,QAAQ,CAAC,KAAK,EAAE,GAAG,UAAU,CAAC;AACvC;AAEA;;;AAGG;AACI,eAAe,oBAAoB,CACxC,KAAoB,EACpB,GAAG,UAA2C,EAAA;AAE9C,IAAA,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE;AAClB,QAAA,OAAO,KAAK;IACd;AAEA,IAAA,OAAO,aAAa,CAAC,KAAK,EAAE,GAAG,UAAU,CAAC;AAC5C;;;;;;;;"}

package/dist/cjs/lib/types.d.ts

@@ -1,3 +1,4 @@
+/** Represents the state of a single form field. */
 export interface FieldState<T> {
     /** The current value of the field. */
     value: T;
@@ -7,42 +8,77 @@ export interface FieldState<T> {
     isTouched: boolean;
     /** Whether the value of the field has been changed by the user. */
     isDirty: boolean;
-    /** Whether the field is valid */
+    /** Whether the field is valid. */
     isValid: boolean;
-    /** Whether the field is currently being validated */
+    /** Whether the field is currently being validated. */
     isValidating: boolean;
 }
+/** Props passed to the render function of a {@link Field} component. */
 export interface FieldRenderProps<T> extends FieldState<T> {
+    /** Callback to update the field value. Should be called when the input value changes. */
     handleChange: (value: T) => void;
+    /** Callback to mark the field as touched. Should be called when the input loses focus. */
     handleBlur: () => void;
+    /** Ref callback to attach to the root element of the input. Used to focus the field on validation errors. */
     ref: (el: HTMLElement | null) => void;
 }
+/** Validator functions to run on different field events. */
 export interface Validation<T> {
+    /** Synchronous validator to run when the field value changes. */
     onChange?: SyncValidator<T>;
+    /** Asynchronous validator to run when the field value changes (debounced). */
     onChangeAsync?: AsyncValidator<T>;
+    /** Synchronous validator to run when the field loses focus. */
     onBlur?: SyncValidator<T>;
+    /** Asynchronous validator to run when the field loses focus. */
     onBlurAsync?: AsyncValidator<T>;
+    /** Synchronous validator to run when the form is submitted. */
     onSubmit?: SyncValidator<T>;
+    /** Asynchronous validator to run when the form is submitted. */
     onSubmitAsync?: AsyncValidator<T>;
 }
+/**
+ * Specifies when validation errors are displayed.
+ *
+ * - `"touched"` — Show errors after the field has been focused and blurred.
+ * - `"dirty"` — Show errors after the field value has been changed.
+ * - `"touchedAndDirty"` — Show errors only after the field has been both touched and changed.
+ * - `"touchedOrDirty"` — Show errors after the field has been either touched or changed.
+ */
 export type ValidationMode = "touched" | "dirty" | "touchedAndDirty" | "touchedOrDirty";
+/** Props for the {@link Field} component. */
 export interface FieldProps<T> {
+    /** The current state of the field, created with {@link createFieldState}. */
     state: FieldState<T>;
+    /** Render function that receives field state and event handlers. */
     children: (props: FieldRenderProps<T>) => React.ReactNode;
+    /** Callback invoked with the updated field state whenever the state changes. */
     onChange: (newState: FieldState<T>) => void;
+    /** Callback invoked with the raw input value on every change, before validation. */
     onInput?: (value: T) => void;
+    /** Callback invoked when the field loses focus. */
     onBlur?: () => void;
+    /** Validator functions to run on various field events. */
     validation?: Validation<T>;
+    /** Overrides the validation mode set on the parent {@link Form}. Defaults to `"touchedAndDirty"`. */
     validationMode?: ValidationMode;
+    /** Debounce delay in milliseconds for async validators. Overrides the value set on the parent {@link Form}. Defaults to `500`. */
     debounceMs?: number;
 }
+/** A synchronous validator function. Returns an error message if validation fails, or a falsy value if it passes. */
 export type SyncValidator<T> = (value: T) => React.ReactNode;
+/** An asynchronous validator function. Resolves with an error message if validation fails, or a falsy value if it passes. */
 export type AsyncValidator<T> = (value: T) => Promise<React.ReactNode>;
+/** A synchronous or asynchronous validator function. */
 export type Validator<T> = SyncValidator<T> | AsyncValidator<T>;
 export interface FormContextValue {
+    /** Default validation mode applied to all fields in the form. */
     validationMode?: ValidationMode;
+    /** Default debounce delay in milliseconds for async validators. */
     debounceMs?: number;
+    /** Registers a field with the form for submit validation. */
     registerField: (id: string, ref: HTMLElement | null, validate: () => Promise<boolean>, commitPendingValidation: () => void) => void;
+    /** Unregisters a field from the form. */
     unregisterField: (id: string) => void;
 }
 export type FieldMap = Map<string, {

package/dist/esm/index.d.ts

@@ -1,4 +1,4 @@
-export * from "./lib/Field";
-export * from "./lib/fieldState";
-export * from "./lib/Form";
-export * from "./lib/types";
+export { Field } from "./lib/Field";
+export { createFieldState, validate, validateAsync, validateIfDirty, validateIfDirtyAsync, } from "./lib/fieldState";
+export { Form } from "./lib/Form";
+export type { AsyncValidator, FieldProps, FieldRenderProps, FieldState, SyncValidator, Validation, ValidationMode, Validator, } from "./lib/types";

package/dist/esm/index.js

@@ -1,4 +1,4 @@
 export { Field } from './lib/Field.js';
 export { createFieldState, validate, validateAsync, validateIfDirty, validateIfDirtyAsync } from './lib/fieldState.js';
-export { Form, FormContext, focusFirstError, useFormContext } from './lib/Form.js';
+export { Form } from './lib/Form.js';
 //# sourceMappingURL=index.js.map

package/dist/esm/lib/Field.d.ts

@@ -1,2 +1,8 @@
 import { FieldProps } from "./types";
+/**
+ * A headless form field component that manages validation state using a render prop pattern.
+ *
+ * Connects to a parent {@link Form} for submit validation coordination.
+ * Passes current field state and event handlers to the `children` render function.
+ */
 export declare function Field<T>(props: FieldProps<T>): import("react").ReactNode;

package/dist/esm/lib/Field.js

@@ -2,10 +2,17 @@ import { useRef, useId, useEffect } from 'react';
 import { validate, validateAsync } from './fieldState.js';
 import { useFormContext } from './Form.js';
 
+/**
+ * A headless form field component that manages validation state using a render prop pattern.
+ *
+ * Connects to a parent {@link Form} for submit validation coordination.
+ * Passes current field state and event handlers to the `children` render function.
+ */
 function Field(props) {
     const { registerField, unregisterField, validationMode: formValidationMode, debounceMs: formDebounceMs, } = useFormContext();
     const { children, state, onChange, onInput, onBlur, validation, debounceMs = formDebounceMs || 500, validationMode = formValidationMode || "touchedAndDirty", } = props;
     const stateRef = useRef(state);
+    stateRef.current = state;
     const validationTimeoutRef = useRef(null);
     const validationIdRef = useRef(0);
     const isValidatingOnBlurRef = useRef(false);
@@ -13,14 +20,8 @@ function Field(props) {
     const pendingValidationRef = useRef(null);
     const fieldRef = useRef(null);
     const id = useId();
-    stateRef.current = state;
     useEffect(() => {
         async function performValidation() {
-            if (!stateRef.current.isValidating &&
-                stateRef.current.isDirty &&
-                stateRef.current.isTouched) {
-                return stateRef.current.isValid;
-            }
             validationIdRef.current++;
             pendingValidationRef.current = validate(stateRef.current, validation?.onChange, validation?.onBlur, validation?.onSubmit);
             if (pendingValidationRef.current.isValid) {
@@ -55,7 +56,7 @@ function Field(props) {
         const shouldValidate = validationMode === "dirty" ||
             validationMode === "touchedOrDirty" ||
             stateRef.current.isTouched;
-        if (shouldValidate && (validation?.onChange || validation?.onChangeAsync)) {
+        if (shouldValidate) {
             const errorMessage = validation?.onChange?.(value);
             const willValidateAsync = Boolean(validation?.onChangeAsync && !errorMessage);
             onChange({
@@ -96,9 +97,10 @@ function Field(props) {
         const currentValidation = validationIdRef.current;
         let errorMessage = stateRef.current.errorMessage ||
             validation?.onBlur?.(stateRef.current.value);
-        const shouldValidateOnChange = validationMode === "touched" ||
-            validationMode === "touchedOrDirty" ||
-            (validationMode === "touchedAndDirty" && stateRef.current.isDirty);
+        const shouldValidateOnChange = !stateRef.current.isTouched &&
+            (validationMode === "touched" ||
+                (validationMode === "touchedOrDirty" && !stateRef.current.isDirty) ||
+                (validationMode === "touchedAndDirty" && stateRef.current.isDirty));
         if (!errorMessage && shouldValidateOnChange && validation?.onChange) {
             errorMessage = validation.onChange(stateRef.current.value);
         }

package/dist/esm/lib/Field.js.map

@@ -1 +1 @@
-{"version":3,"file":"Field.js","sources":["../../../src/lib/Field.tsx"],"sourcesContent":["import { useEffect, useId, useRef } from \"react\";\nimport { validate, validateAsync } from \"./fieldState\";\nimport { useFormContext } from \"./Form\";\nimport { FieldProps, FieldState } from \"./types\";\n\nexport function Field<T>(props: FieldProps<T>) {\n  const {\n    registerField,\n    unregisterField,\n    validationMode: formValidationMode,\n    debounceMs: formDebounceMs,\n  } = useFormContext();\n\n  const {\n    children,\n    state,\n    onChange,\n    onInput,\n    onBlur,\n    validation,\n    debounceMs = formDebounceMs || 500,\n    validationMode = formValidationMode || \"touchedAndDirty\",\n  } = props;\n\n  const stateRef = useRef(state);\n  const validationTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(\n    null,\n  );\n  const validationIdRef = useRef(0);\n  const isValidatingOnBlurRef = useRef(false);\n  const isValidatingOnChangeRef = useRef(false);\n  const pendingValidationRef = useRef<FieldState<T> | null>(null);\n  const fieldRef = useRef<HTMLElement | null>(null);\n  const id = useId();\n\n  stateRef.current = state;\n\n  useEffect(() => {\n    async function performValidation() {\n      if (\n        !stateRef.current.isValidating &&\n        stateRef.current.isDirty &&\n        stateRef.current.isTouched\n      ) {\n        return stateRef.current.isValid;\n      }\n      validationIdRef.current++;\n      pendingValidationRef.current = validate(\n        stateRef.current,\n        validation?.onChange,\n        validation?.onBlur,\n        validation?.onSubmit,\n      );\n      if (pendingValidationRef.current.isValid) {\n        pendingValidationRef.current = await validateAsync(\n          stateRef.current,\n          validation?.onChangeAsync,\n          validation?.onBlurAsync,\n          validation?.onSubmitAsync,\n        );\n      }\n      return pendingValidationRef.current.isValid;\n    }\n\n    function commitPendingValidation() {\n      if (pendingValidationRef.current) {\n        onChange(pendingValidationRef.current);\n        pendingValidationRef.current = null;\n      }\n    }\n\n    registerField(\n      id,\n      fieldRef.current,\n      performValidation,\n      commitPendingValidation,\n    );\n\n    return () => {\n      unregisterField(id);\n    };\n  }, [id, registerField, validation, onChange, unregisterField]);\n\n  useEffect(() => {\n    return () => {\n      if (validationTimeoutRef.current) {\n        clearTimeout(validationTimeoutRef.current);\n      }\n    };\n  }, []);\n\n  function handleChange(value: T) {\n    onInput?.(value);\n\n    if (validationTimeoutRef.current) {\n      clearTimeout(validationTimeoutRef.current);\n    }\n\n    const currentValidation = ++validationIdRef.current;\n\n    const shouldValidate =\n      validationMode === \"dirty\" ||\n      validationMode === \"touchedOrDirty\" ||\n      stateRef.current.isTouched;\n\n    if (shouldValidate && (validation?.onChange || validation?.onChangeAsync)) {\n      const errorMessage = validation?.onChange?.(value);\n      const willValidateAsync = Boolean(\n        validation?.onChangeAsync && !errorMessage,\n      );\n\n      onChange({\n        ...stateRef.current,\n        value,\n        errorMessage,\n        isDirty: true,\n        isValid: !errorMessage,\n        isValidating: willValidateAsync,\n      });\n\n      if (willValidateAsync) {\n        isValidatingOnChangeRef.current = true;\n        validationTimeoutRef.current = setTimeout(async () => {\n          const asyncErrorMessage = await validation?.onChangeAsync?.(value);\n\n          isValidatingOnChangeRef.current = false;\n          if (currentValidation === validationIdRef.current) {\n            onChange({\n              ...stateRef.current,\n              errorMessage: asyncErrorMessage,\n              isValid: !asyncErrorMessage,\n              isValidating: isValidatingOnBlurRef.current,\n            });\n          }\n        }, debounceMs);\n      }\n    } else {\n      onChange({\n        ...stateRef.current,\n        value,\n        isDirty: true,\n        isValidating: false,\n      });\n    }\n  }\n\n  async function handleBlur() {\n    onBlur?.();\n\n    const currentValidation = validationIdRef.current;\n\n    let errorMessage =\n      stateRef.current.errorMessage ||\n      validation?.onBlur?.(stateRef.current.value);\n\n    const shouldValidateOnChange =\n      validationMode === \"touched\" ||\n      validationMode === \"touchedOrDirty\" ||\n      (validationMode === \"touchedAndDirty\" && stateRef.current.isDirty);\n\n    if (!errorMessage && shouldValidateOnChange && validation?.onChange) {\n      errorMessage = validation.onChange(stateRef.current.value);\n    }\n\n    if (\n      !errorMessage &&\n      (validation?.onBlurAsync || validation?.onChangeAsync)\n    ) {\n      isValidatingOnBlurRef.current = true;\n      onChange({\n        ...stateRef.current,\n        isValidating: true,\n        isTouched: true,\n      });\n\n      const asyncValidations: Promise<React.ReactNode>[] = [];\n\n      if (validation?.onBlurAsync) {\n        asyncValidations.push(validation.onBlurAsync(stateRef.current.value));\n      }\n\n      if (shouldValidateOnChange && validation?.onChangeAsync) {\n        asyncValidations.push(validation.onChangeAsync(stateRef.current.value));\n      }\n\n      const [blurError, changeError] = await Promise.all(asyncValidations);\n      errorMessage = blurError || changeError;\n    }\n\n    isValidatingOnBlurRef.current = false;\n\n    if (errorMessage && validationTimeoutRef.current) {\n      clearTimeout(validationTimeoutRef.current);\n    }\n\n    if (currentValidation !== validationIdRef.current) {\n      onChange({\n        ...stateRef.current,\n        isTouched: true,\n      });\n      return;\n    }\n\n    onChange({\n      ...stateRef.current,\n      errorMessage,\n      isTouched: true,\n      isValid: !errorMessage,\n      isValidating: isValidatingOnChangeRef.current,\n    });\n  }\n\n  const ref = (el: HTMLElement | null) => {\n    fieldRef.current = el;\n  };\n\n  return children({\n    ...stateRef.current,\n    handleChange,\n    handleBlur,\n    ref,\n  });\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"Field.js","sources":["../../../src/lib/Field.tsx"],"sourcesContent":["import { useEffect, useId, useRef } from \"react\";\nimport { validate, validateAsync } from \"./fieldState\";\nimport { useFormContext } from \"./Form\";\nimport { FieldProps, FieldState } from \"./types\";\n\n/**\n * A headless form field component that manages validation state using a render prop pattern.\n *\n * Connects to a parent {@link Form} for submit validation coordination.\n * Passes current field state and event handlers to the `children` render function.\n */\nexport function Field<T>(props: FieldProps<T>) {\n  const {\n    registerField,\n    unregisterField,\n    validationMode: formValidationMode,\n    debounceMs: formDebounceMs,\n  } = useFormContext();\n\n  const {\n    children,\n    state,\n    onChange,\n    onInput,\n    onBlur,\n    validation,\n    debounceMs = formDebounceMs || 500,\n    validationMode = formValidationMode || \"touchedAndDirty\",\n  } = props;\n\n  const stateRef = useRef(state);\n  stateRef.current = state;\n  const validationTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(\n    null,\n  );\n  const validationIdRef = useRef(0);\n  const isValidatingOnBlurRef = useRef(false);\n  const isValidatingOnChangeRef = useRef(false);\n  const pendingValidationRef = useRef<FieldState<T> | null>(null);\n  const fieldRef = useRef<HTMLElement | null>(null);\n  const id = useId();\n\n  useEffect(() => {\n    async function performValidation() {\n      validationIdRef.current++;\n      pendingValidationRef.current = validate(\n        stateRef.current,\n        validation?.onChange,\n        validation?.onBlur,\n        validation?.onSubmit,\n      );\n      if (pendingValidationRef.current.isValid) {\n        pendingValidationRef.current = await validateAsync(\n          stateRef.current,\n          validation?.onChangeAsync,\n          validation?.onBlurAsync,\n          validation?.onSubmitAsync,\n        );\n      }\n      return pendingValidationRef.current.isValid;\n    }\n\n    function commitPendingValidation() {\n      if (pendingValidationRef.current) {\n        onChange(pendingValidationRef.current);\n        pendingValidationRef.current = null;\n      }\n    }\n\n    registerField(\n      id,\n      fieldRef.current,\n      performValidation,\n      commitPendingValidation,\n    );\n\n    return () => {\n      unregisterField(id);\n    };\n  }, [id, registerField, validation, onChange, unregisterField]);\n\n  useEffect(() => {\n    return () => {\n      if (validationTimeoutRef.current) {\n        clearTimeout(validationTimeoutRef.current);\n      }\n    };\n  }, []);\n\n  function handleChange(value: T) {\n    onInput?.(value);\n\n    if (validationTimeoutRef.current) {\n      clearTimeout(validationTimeoutRef.current);\n    }\n\n    const currentValidation = ++validationIdRef.current;\n\n    const shouldValidate =\n      validationMode === \"dirty\" ||\n      validationMode === \"touchedOrDirty\" ||\n      stateRef.current.isTouched;\n\n    if (shouldValidate) {\n      const errorMessage = validation?.onChange?.(value);\n      const willValidateAsync = Boolean(\n        validation?.onChangeAsync && !errorMessage,\n      );\n\n      onChange({\n        ...stateRef.current,\n        value,\n        errorMessage,\n        isDirty: true,\n        isValid: !errorMessage,\n        isValidating: willValidateAsync,\n      });\n\n      if (willValidateAsync) {\n        isValidatingOnChangeRef.current = true;\n        validationTimeoutRef.current = setTimeout(async () => {\n          const asyncErrorMessage = await validation?.onChangeAsync?.(value);\n\n          isValidatingOnChangeRef.current = false;\n          if (currentValidation === validationIdRef.current) {\n            onChange({\n              ...stateRef.current,\n              errorMessage: asyncErrorMessage,\n              isValid: !asyncErrorMessage,\n              isValidating: isValidatingOnBlurRef.current,\n            });\n          }\n        }, debounceMs);\n      }\n    } else {\n      onChange({\n        ...stateRef.current,\n        value,\n        isDirty: true,\n        isValidating: false,\n      });\n    }\n  }\n\n  async function handleBlur() {\n    onBlur?.();\n\n    const currentValidation = validationIdRef.current;\n\n    let errorMessage =\n      stateRef.current.errorMessage ||\n      validation?.onBlur?.(stateRef.current.value);\n\n    const shouldValidateOnChange =\n      !stateRef.current.isTouched &&\n      (validationMode === \"touched\" ||\n        (validationMode === \"touchedOrDirty\" && !stateRef.current.isDirty) ||\n        (validationMode === \"touchedAndDirty\" && stateRef.current.isDirty));\n\n    if (!errorMessage && shouldValidateOnChange && validation?.onChange) {\n      errorMessage = validation.onChange(stateRef.current.value);\n    }\n\n    if (\n      !errorMessage &&\n      (validation?.onBlurAsync || validation?.onChangeAsync)\n    ) {\n      isValidatingOnBlurRef.current = true;\n      onChange({\n        ...stateRef.current,\n        isValidating: true,\n        isTouched: true,\n      });\n\n      const asyncValidations: Promise<React.ReactNode>[] = [];\n\n      if (validation?.onBlurAsync) {\n        asyncValidations.push(validation.onBlurAsync(stateRef.current.value));\n      }\n\n      if (shouldValidateOnChange && validation?.onChangeAsync) {\n        asyncValidations.push(validation.onChangeAsync(stateRef.current.value));\n      }\n\n      const [blurError, changeError] = await Promise.all(asyncValidations);\n      errorMessage = blurError || changeError;\n    }\n\n    isValidatingOnBlurRef.current = false;\n\n    if (errorMessage && validationTimeoutRef.current) {\n      clearTimeout(validationTimeoutRef.current);\n    }\n\n    if (currentValidation !== validationIdRef.current) {\n      onChange({\n        ...stateRef.current,\n        isTouched: true,\n      });\n      return;\n    }\n\n    onChange({\n      ...stateRef.current,\n      errorMessage,\n      isTouched: true,\n      isValid: !errorMessage,\n      isValidating: isValidatingOnChangeRef.current,\n    });\n  }\n\n  const ref = (el: HTMLElement | null) => {\n    fieldRef.current = el;\n  };\n\n  return children({\n    ...stateRef.current,\n    handleChange,\n    handleBlur,\n    ref,\n  });\n}\n"],"names":[],"mappings":"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"}

package/dist/esm/lib/Form.d.ts

@@ -1,10 +1,26 @@
 import React from "react";
 import { FormContextValue, ValidationMode } from "./types";
+/** Props for the {@link Form} component. */
 interface FormProps extends Omit<React.ComponentProps<"form">, "onSubmit"> {
+    /** Default validation mode applied to all fields in the form. Defaults to `"touchedAndDirty"`. */
     validationMode?: ValidationMode;
+    /** Default debounce delay in milliseconds for async validators. Defaults to `500`. */
     debounceMs?: number;
-    onSubmit?: (e: React.SubmitEvent<HTMLFormElement>, validateAllFields: () => Promise<boolean>) => void;
+    /**
+     * Submit handler called when the form is submitted.
+     * Receives the submit event and a `validateAllFields` function that triggers
+     * validation on all registered fields and returns whether the form is valid.
+     */
+    onSubmit?: (e: React.SubmitEvent<HTMLFormElement>, validateForm: () => Promise<boolean>) => void;
 }
+/**
+ * A form component that provides context for coordinating field validation.
+ *
+ * Wraps a native `<form>` element and prevents the default submit behavior.
+ * On submit, the `onSubmit` callback is called with the submit event and a
+ * `validateAllFields` function that can be used to trigger validation on all
+ * registered {@link Field} components and focus the first invalid field.
+ */
 export declare function Form({ onSubmit, validationMode, debounceMs, ...props }: FormProps): React.JSX.Element;
 export declare const FormContext: React.Context<FormContextValue>;
 export declare function useFormContext(): FormContextValue;

package/dist/esm/lib/Form.js

@@ -1,5 +1,13 @@
 import React, { useRef, useCallback } from 'react';
 
+/**
+ * A form component that provides context for coordinating field validation.
+ *
+ * Wraps a native `<form>` element and prevents the default submit behavior.
+ * On submit, the `onSubmit` callback is called with the submit event and a
+ * `validateAllFields` function that can be used to trigger validation on all
+ * registered {@link Field} components and focus the first invalid field.
+ */
 function Form({ onSubmit, validationMode, debounceMs, ...props }) {
     const fieldsRef = useRef(new Map());
     const registerField = useCallback((id, ref, validate, commitPendingValidation) => {
@@ -12,7 +20,7 @@ function Form({ onSubmit, validationMode, debounceMs, ...props }) {
     const unregisterField = useCallback((id) => {
         fieldsRef.current.delete(id);
     }, []);
-    const validateAllFields = useCallback(async () => {
+    const validateForm = useCallback(async () => {
         const fields = Array.from(fieldsRef.current.values());
         const validationPromises = fields.map(async (field) => ({
             isValid: await field.validate(),
@@ -32,7 +40,7 @@ function Form({ onSubmit, validationMode, debounceMs, ...props }) {
             validationMode,
             debounceMs,
         } },
-        React.createElement("form", { onSubmit: (e) => onSubmit?.(e, validateAllFields), ...props })));
+        React.createElement("form", { onSubmit: (e) => onSubmit?.(e, validateForm), ...props })));
 }
 const FormContext = React.createContext({
     registerField: () => { },
@@ -50,26 +58,11 @@ function focusFirstError(results) {
     if (!firstInvalidField) {
         return;
     }
-    let firstInvalid = firstInvalidField;
-    if (firstInvalid.role === "radiogroup") {
-        const radio = firstInvalid.querySelector('[role="radio"]');
-        if (radio) {
-            firstInvalid = radio;
-        }
-    }
-    if (firstInvalid.role === "group") {
-        const checkbox = firstInvalid.querySelector('[role="checkbox"]');
-        if (checkbox) {
-            firstInvalid = checkbox;
-        }
-    }
-    firstInvalid.focus();
-    const rect = firstInvalid.getBoundingClientRect();
-    if (rect) {
-        window.scrollTo({
-            top: rect.top + window.scrollY - 100,
-        });
-    }
+    firstInvalidField.focus();
+    const rect = firstInvalidField.getBoundingClientRect();
+    window.scrollTo({
+        top: rect.top + window.scrollY - 100,
+    });
 }
 
 export { Form, FormContext, focusFirstError, useFormContext };

package/dist/esm/lib/Form.js.map

@@ -1 +1 @@
-{"version":3,"file":"Form.js","sources":["../../../src/lib/Form.tsx"],"sourcesContent":["import React, { useCallback, useRef } from \"react\";\nimport { FieldMap, FormContextValue, ValidationMode } from \"./types\";\n\ninterface FormProps extends Omit<React.ComponentProps<\"form\">, \"onSubmit\"> {\n  validationMode?: ValidationMode;\n  debounceMs?: number;\n  onSubmit?: (\n    e: React.SubmitEvent<HTMLFormElement>,\n    validateAllFields: () => Promise<boolean>,\n  ) => void;\n}\n\nexport function Form({\n  onSubmit,\n  validationMode,\n  debounceMs,\n  ...props\n}: FormProps) {\n  const fieldsRef = useRef<FieldMap>(new Map());\n\n  const registerField = useCallback(\n    (\n      id: string,\n      ref: HTMLElement | null,\n      validate: () => Promise<boolean>,\n      commitPendingValidation: () => void,\n    ) => {\n      fieldsRef.current.set(id, {\n        ref,\n        validate,\n        commitPendingValidation,\n      });\n    },\n    [],\n  );\n\n  const unregisterField = useCallback((id: string) => {\n    fieldsRef.current.delete(id);\n  }, []);\n\n  const validateAllFields = useCallback(async () => {\n    const fields = Array.from(fieldsRef.current.values());\n    const validationPromises = fields.map(async (field) => ({\n      isValid: await field.validate(),\n      ref: field.ref,\n    }));\n    const results = await Promise.all(validationPromises);\n    fields.forEach((field) => field.commitPendingValidation());\n    const hasErrors = results.some((result) => !result.isValid);\n    if (hasErrors) {\n      focusFirstError(results);\n    }\n    return !hasErrors;\n  }, []);\n\n  return (\n    <FormContext.Provider\n      value={{\n        registerField,\n        unregisterField,\n        validationMode,\n        debounceMs,\n      }}\n    >\n      <form onSubmit={(e) => onSubmit?.(e, validateAllFields)} {...props} />\n    </FormContext.Provider>\n  );\n}\n\nexport const FormContext = React.createContext<FormContextValue>({\n  registerField: () => {},\n  unregisterField: () => {},\n});\n\nexport function useFormContext() {\n  return React.useContext(FormContext);\n}\n\nexport function focusFirstError(\n  results: {\n    isValid: boolean;\n    ref: HTMLElement | null;\n  }[],\n) {\n  const firstInvalidField = results\n    .filter((field) => !field.isValid && field.ref)\n    .map((field) => field.ref!)\n    .sort((a, b) =>\n      a.compareDocumentPosition(b) & Node.DOCUMENT_POSITION_PRECEDING ? 1 : -1,\n    )\n    .at(0);\n\n  if (!firstInvalidField) {\n    return;\n  }\n\n  let firstInvalid = firstInvalidField;\n\n  if (firstInvalid.role === \"radiogroup\") {\n    const radio = firstInvalid.querySelector<HTMLElement>('[role=\"radio\"]');\n    if (radio) {\n      firstInvalid = radio;\n    }\n  }\n\n  if (firstInvalid.role === \"group\") {\n    const checkbox =\n      firstInvalid.querySelector<HTMLElement>('[role=\"checkbox\"]');\n    if (checkbox) {\n      firstInvalid = checkbox;\n    }\n  }\n\n  firstInvalid.focus();\n  const rect = firstInvalid.getBoundingClientRect();\n  if (rect) {\n    window.scrollTo({\n      top: rect.top + window.scrollY - 100,\n    });\n  }\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"Form.js","sources":["../../../src/lib/Form.tsx"],"sourcesContent":["import React, { useCallback, useRef } from \"react\";\nimport { FieldMap, FormContextValue, ValidationMode } from \"./types\";\n\n/** Props for the {@link Form} component. */\ninterface FormProps extends Omit<React.ComponentProps<\"form\">, \"onSubmit\"> {\n  /** Default validation mode applied to all fields in the form. Defaults to `\"touchedAndDirty\"`. */\n  validationMode?: ValidationMode;\n  /** Default debounce delay in milliseconds for async validators. Defaults to `500`. */\n  debounceMs?: number;\n  /**\n   * Submit handler called when the form is submitted.\n   * Receives the submit event and a `validateAllFields` function that triggers\n   * validation on all registered fields and returns whether the form is valid.\n   */\n  onSubmit?: (\n    e: React.SubmitEvent<HTMLFormElement>,\n    validateForm: () => Promise<boolean>,\n  ) => void;\n}\n\n/**\n * A form component that provides context for coordinating field validation.\n *\n * Wraps a native `<form>` element and prevents the default submit behavior.\n * On submit, the `onSubmit` callback is called with the submit event and a\n * `validateAllFields` function that can be used to trigger validation on all\n * registered {@link Field} components and focus the first invalid field.\n */\nexport function Form({\n  onSubmit,\n  validationMode,\n  debounceMs,\n  ...props\n}: FormProps) {\n  const fieldsRef = useRef<FieldMap>(new Map());\n\n  const registerField = useCallback(\n    (\n      id: string,\n      ref: HTMLElement | null,\n      validate: () => Promise<boolean>,\n      commitPendingValidation: () => void,\n    ) => {\n      fieldsRef.current.set(id, {\n        ref,\n        validate,\n        commitPendingValidation,\n      });\n    },\n    [],\n  );\n\n  const unregisterField = useCallback((id: string) => {\n    fieldsRef.current.delete(id);\n  }, []);\n\n  const validateForm = useCallback(async () => {\n    const fields = Array.from(fieldsRef.current.values());\n    const validationPromises = fields.map(async (field) => ({\n      isValid: await field.validate(),\n      ref: field.ref,\n    }));\n    const results = await Promise.all(validationPromises);\n    fields.forEach((field) => field.commitPendingValidation());\n    const hasErrors = results.some((result) => !result.isValid);\n    if (hasErrors) {\n      focusFirstError(results);\n    }\n    return !hasErrors;\n  }, []);\n\n  return (\n    <FormContext.Provider\n      value={{\n        registerField,\n        unregisterField,\n        validationMode,\n        debounceMs,\n      }}\n    >\n      <form onSubmit={(e) => onSubmit?.(e, validateForm)} {...props} />\n    </FormContext.Provider>\n  );\n}\n\nexport const FormContext = React.createContext<FormContextValue>({\n  registerField: () => {},\n  unregisterField: () => {},\n});\n\nexport function useFormContext() {\n  return React.useContext(FormContext);\n}\n\nexport function focusFirstError(\n  results: {\n    isValid: boolean;\n    ref: HTMLElement | null;\n  }[],\n) {\n  const firstInvalidField = results\n    .filter((field) => !field.isValid && field.ref)\n    .map((field) => field.ref!)\n    .sort((a, b) =>\n      a.compareDocumentPosition(b) & Node.DOCUMENT_POSITION_PRECEDING ? 1 : -1,\n    )\n    .at(0);\n\n  if (!firstInvalidField) {\n    return;\n  }\n\n  firstInvalidField.focus();\n  const rect = firstInvalidField.getBoundingClientRect();\n  window.scrollTo({\n    top: rect.top + window.scrollY - 100,\n  });\n}\n"],"names":[],"mappings":"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"}

package/dist/esm/lib/fieldState.d.ts

@@ -1,6 +1,23 @@
 import { FieldState, SyncValidator, Validator } from "./types";
+/** Creates the initial state for a field with the given initial value. */
 export declare function createFieldState<T>(initialValue: T): FieldState<T>;
+/**
+ * Runs the provided synchronous validators against the current field value and returns an updated {@link FieldState}.
+ * Sets `isDirty` and `isTouched` to `true`. Stops at the first failing validator.
+ */
 export declare function validate<T>(state: FieldState<T>, ...validators: Array<SyncValidator<T> | undefined>): FieldState<T>;
+/**
+ * Runs the provided synchronous and/or asynchronous validators against the current field value and returns an updated {@link FieldState}.
+ * Sets `isDirty` and `isTouched` to `true`. All validators run in parallel; the first truthy error message is used.
+ */
 export declare function validateAsync<T>(state: FieldState<T>, ...validators: Array<Validator<T> | undefined>): Promise<FieldState<T>>;
+/**
+ * Runs the provided synchronous validators only if the field is dirty (i.e. the value has been changed).
+ * Returns the state unchanged if the field is not dirty.
+ */
 export declare function validateIfDirty<T>(state: FieldState<T>, ...validators: Array<SyncValidator<T> | undefined>): FieldState<T>;
+/**
+ * Runs the provided synchronous and/or asynchronous validators only if the field is dirty (i.e. the value has been changed).
+ * Returns the state unchanged if the field is not dirty.
+ */
 export declare function validateIfDirtyAsync<T>(state: FieldState<T>, ...validators: Array<Validator<T> | undefined>): Promise<FieldState<T>>;

package/dist/esm/lib/fieldState.js

@@ -1,3 +1,4 @@
+/** Creates the initial state for a field with the given initial value. */
 function createFieldState(initialValue) {
     return {
         value: initialValue,
@@ -8,6 +9,10 @@ function createFieldState(initialValue) {
         isValidating: false,
     };
 }
+/**
+ * Runs the provided synchronous validators against the current field value and returns an updated {@link FieldState}.
+ * Sets `isDirty` and `isTouched` to `true`. Stops at the first failing validator.
+ */
 function validate(state, ...validators) {
     for (const validator of validators) {
         const errorMessage = validator?.(state.value);
@@ -31,6 +36,10 @@ function validate(state, ...validators) {
         isValidating: false,
     };
 }
+/**
+ * Runs the provided synchronous and/or asynchronous validators against the current field value and returns an updated {@link FieldState}.
+ * Sets `isDirty` and `isTouched` to `true`. All validators run in parallel; the first truthy error message is used.
+ */
 async function validateAsync(state, ...validators) {
     const errorMessages = await Promise.all(validators.map((validator) => validator?.(state.value)));
     const errorMessage = errorMessages.find(Boolean);
@@ -53,12 +62,20 @@ async function validateAsync(state, ...validators) {
         isValidating: false,
     };
 }
+/**
+ * Runs the provided synchronous validators only if the field is dirty (i.e. the value has been changed).
+ * Returns the state unchanged if the field is not dirty.
+ */
 function validateIfDirty(state, ...validators) {
     if (!state.isDirty) {
         return state;
     }
     return validate(state, ...validators);
 }
+/**
+ * Runs the provided synchronous and/or asynchronous validators only if the field is dirty (i.e. the value has been changed).
+ * Returns the state unchanged if the field is not dirty.
+ */
 async function validateIfDirtyAsync(state, ...validators) {
     if (!state.isDirty) {
         return state;

package/dist/esm/lib/fieldState.js.map

@@ -1 +1 @@
-{"version":3,"file":"fieldState.js","sources":["../../../src/lib/fieldState.ts"],"sourcesContent":["import { FieldState, SyncValidator, Validator } from \"./types\";\n\nexport function createFieldState<T>(initialValue: T): FieldState<T> {\n  return {\n    value: initialValue,\n    errorMessage: undefined,\n    isTouched: false,\n    isDirty: false,\n    isValid: true,\n    isValidating: false,\n  };\n}\n\nexport function validate<T>(\n  state: FieldState<T>,\n  ...validators: Array<SyncValidator<T> | undefined>\n): FieldState<T> {\n  for (const validator of validators) {\n    const errorMessage = validator?.(state.value);\n    if (errorMessage) {\n      return {\n        ...state,\n        errorMessage,\n        isDirty: true,\n        isTouched: true,\n        isValid: false,\n        isValidating: false,\n      };\n    }\n  }\n\n  return {\n    ...state,\n    errorMessage: undefined,\n    isDirty: true,\n    isTouched: true,\n    isValid: true,\n    isValidating: false,\n  };\n}\n\nexport async function validateAsync<T>(\n  state: FieldState<T>,\n  ...validators: Array<Validator<T> | undefined>\n): Promise<FieldState<T>> {\n  const errorMessages = await Promise.all(\n    validators.map((validator) => validator?.(state.value)),\n  );\n  const errorMessage = errorMessages.find(Boolean);\n\n  if (errorMessage) {\n    return {\n      ...state,\n      errorMessage,\n      isDirty: true,\n      isTouched: true,\n      isValid: false,\n      isValidating: false,\n    };\n  }\n\n  return {\n    ...state,\n    errorMessage: undefined,\n    isDirty: true,\n    isTouched: true,\n    isValid: true,\n    isValidating: false,\n  };\n}\n\nexport function validateIfDirty<T>(\n  state: FieldState<T>,\n  ...validators: Array<SyncValidator<T> | undefined>\n): FieldState<T> {\n  if (!state.isDirty) {\n    return state;\n  }\n\n  return validate(state, ...validators);\n}\n\nexport async function validateIfDirtyAsync<T>(\n  state: FieldState<T>,\n  ...validators: Array<Validator<T> | undefined>\n): Promise<FieldState<T>> {\n  if (!state.isDirty) {\n    return state;\n  }\n\n  return validateAsync(state, ...validators);\n}\n"],"names":[],"mappings":"AAEM,SAAU,gBAAgB,CAAI,YAAe,EAAA;IACjD,OAAO;AACL,QAAA,KAAK,EAAE,YAAY;AACnB,QAAA,YAAY,EAAE,SAAS;AACvB,QAAA,SAAS,EAAE,KAAK;AAChB,QAAA,OAAO,EAAE,KAAK;AACd,QAAA,OAAO,EAAE,IAAI;AACb,QAAA,YAAY,EAAE,KAAK;KACpB;AACH;SAEgB,QAAQ,CACtB,KAAoB,EACpB,GAAG,UAA+C,EAAA;AAElD,IAAA,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE;QAClC,MAAM,YAAY,GAAG,SAAS,GAAG,KAAK,CAAC,KAAK,CAAC;QAC7C,IAAI,YAAY,EAAE;YAChB,OAAO;AACL,gBAAA,GAAG,KAAK;gBACR,YAAY;AACZ,gBAAA,OAAO,EAAE,IAAI;AACb,gBAAA,SAAS,EAAE,IAAI;AACf,gBAAA,OAAO,EAAE,KAAK;AACd,gBAAA,YAAY,EAAE,KAAK;aACpB;QACH;IACF;IAEA,OAAO;AACL,QAAA,GAAG,KAAK;AACR,QAAA,YAAY,EAAE,SAAS;AACvB,QAAA,OAAO,EAAE,IAAI;AACb,QAAA,SAAS,EAAE,IAAI;AACf,QAAA,OAAO,EAAE,IAAI;AACb,QAAA,YAAY,EAAE,KAAK;KACpB;AACH;AAEO,eAAe,aAAa,CACjC,KAAoB,EACpB,GAAG,UAA2C,EAAA;IAE9C,MAAM,aAAa,GAAG,MAAM,OAAO,CAAC,GAAG,CACrC,UAAU,CAAC,GAAG,CAAC,CAAC,SAAS,KAAK,SAAS,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CACxD;IACD,MAAM,YAAY,GAAG,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC;IAEhD,IAAI,YAAY,EAAE;QAChB,OAAO;AACL,YAAA,GAAG,KAAK;YACR,YAAY;AACZ,YAAA,OAAO,EAAE,IAAI;AACb,YAAA,SAAS,EAAE,IAAI;AACf,YAAA,OAAO,EAAE,KAAK;AACd,YAAA,YAAY,EAAE,KAAK;SACpB;IACH;IAEA,OAAO;AACL,QAAA,GAAG,KAAK;AACR,QAAA,YAAY,EAAE,SAAS;AACvB,QAAA,OAAO,EAAE,IAAI;AACb,QAAA,SAAS,EAAE,IAAI;AACf,QAAA,OAAO,EAAE,IAAI;AACb,QAAA,YAAY,EAAE,KAAK;KACpB;AACH;SAEgB,eAAe,CAC7B,KAAoB,EACpB,GAAG,UAA+C,EAAA;AAElD,IAAA,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE;AAClB,QAAA,OAAO,KAAK;IACd;AAEA,IAAA,OAAO,QAAQ,CAAC,KAAK,EAAE,GAAG,UAAU,CAAC;AACvC;AAEO,eAAe,oBAAoB,CACxC,KAAoB,EACpB,GAAG,UAA2C,EAAA;AAE9C,IAAA,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE;AAClB,QAAA,OAAO,KAAK;IACd;AAEA,IAAA,OAAO,aAAa,CAAC,KAAK,EAAE,GAAG,UAAU,CAAC;AAC5C;;;;"}
+{"version":3,"file":"fieldState.js","sources":["../../../src/lib/fieldState.ts"],"sourcesContent":["import { FieldState, SyncValidator, Validator } from \"./types\";\n\n/** Creates the initial state for a field with the given initial value. */\nexport function createFieldState<T>(initialValue: T): FieldState<T> {\n  return {\n    value: initialValue,\n    errorMessage: undefined,\n    isTouched: false,\n    isDirty: false,\n    isValid: true,\n    isValidating: false,\n  };\n}\n\n/**\n * Runs the provided synchronous validators against the current field value and returns an updated {@link FieldState}.\n * Sets `isDirty` and `isTouched` to `true`. Stops at the first failing validator.\n */\nexport function validate<T>(\n  state: FieldState<T>,\n  ...validators: Array<SyncValidator<T> | undefined>\n): FieldState<T> {\n  for (const validator of validators) {\n    const errorMessage = validator?.(state.value);\n    if (errorMessage) {\n      return {\n        ...state,\n        errorMessage,\n        isDirty: true,\n        isTouched: true,\n        isValid: false,\n        isValidating: false,\n      };\n    }\n  }\n\n  return {\n    ...state,\n    errorMessage: undefined,\n    isDirty: true,\n    isTouched: true,\n    isValid: true,\n    isValidating: false,\n  };\n}\n\n/**\n * Runs the provided synchronous and/or asynchronous validators against the current field value and returns an updated {@link FieldState}.\n * Sets `isDirty` and `isTouched` to `true`. All validators run in parallel; the first truthy error message is used.\n */\nexport async function validateAsync<T>(\n  state: FieldState<T>,\n  ...validators: Array<Validator<T> | undefined>\n): Promise<FieldState<T>> {\n  const errorMessages = await Promise.all(\n    validators.map((validator) => validator?.(state.value)),\n  );\n  const errorMessage = errorMessages.find(Boolean);\n\n  if (errorMessage) {\n    return {\n      ...state,\n      errorMessage,\n      isDirty: true,\n      isTouched: true,\n      isValid: false,\n      isValidating: false,\n    };\n  }\n\n  return {\n    ...state,\n    errorMessage: undefined,\n    isDirty: true,\n    isTouched: true,\n    isValid: true,\n    isValidating: false,\n  };\n}\n\n/**\n * Runs the provided synchronous validators only if the field is dirty (i.e. the value has been changed).\n * Returns the state unchanged if the field is not dirty.\n */\nexport function validateIfDirty<T>(\n  state: FieldState<T>,\n  ...validators: Array<SyncValidator<T> | undefined>\n): FieldState<T> {\n  if (!state.isDirty) {\n    return state;\n  }\n\n  return validate(state, ...validators);\n}\n\n/**\n * Runs the provided synchronous and/or asynchronous validators only if the field is dirty (i.e. the value has been changed).\n * Returns the state unchanged if the field is not dirty.\n */\nexport async function validateIfDirtyAsync<T>(\n  state: FieldState<T>,\n  ...validators: Array<Validator<T> | undefined>\n): Promise<FieldState<T>> {\n  if (!state.isDirty) {\n    return state;\n  }\n\n  return validateAsync(state, ...validators);\n}\n"],"names":[],"mappings":"AAEA;AACM,SAAU,gBAAgB,CAAI,YAAe,EAAA;IACjD,OAAO;AACL,QAAA,KAAK,EAAE,YAAY;AACnB,QAAA,YAAY,EAAE,SAAS;AACvB,QAAA,SAAS,EAAE,KAAK;AAChB,QAAA,OAAO,EAAE,KAAK;AACd,QAAA,OAAO,EAAE,IAAI;AACb,QAAA,YAAY,EAAE,KAAK;KACpB;AACH;AAEA;;;AAGG;SACa,QAAQ,CACtB,KAAoB,EACpB,GAAG,UAA+C,EAAA;AAElD,IAAA,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE;QAClC,MAAM,YAAY,GAAG,SAAS,GAAG,KAAK,CAAC,KAAK,CAAC;QAC7C,IAAI,YAAY,EAAE;YAChB,OAAO;AACL,gBAAA,GAAG,KAAK;gBACR,YAAY;AACZ,gBAAA,OAAO,EAAE,IAAI;AACb,gBAAA,SAAS,EAAE,IAAI;AACf,gBAAA,OAAO,EAAE,KAAK;AACd,gBAAA,YAAY,EAAE,KAAK;aACpB;QACH;IACF;IAEA,OAAO;AACL,QAAA,GAAG,KAAK;AACR,QAAA,YAAY,EAAE,SAAS;AACvB,QAAA,OAAO,EAAE,IAAI;AACb,QAAA,SAAS,EAAE,IAAI;AACf,QAAA,OAAO,EAAE,IAAI;AACb,QAAA,YAAY,EAAE,KAAK;KACpB;AACH;AAEA;;;AAGG;AACI,eAAe,aAAa,CACjC,KAAoB,EACpB,GAAG,UAA2C,EAAA;IAE9C,MAAM,aAAa,GAAG,MAAM,OAAO,CAAC,GAAG,CACrC,UAAU,CAAC,GAAG,CAAC,CAAC,SAAS,KAAK,SAAS,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CACxD;IACD,MAAM,YAAY,GAAG,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC;IAEhD,IAAI,YAAY,EAAE;QAChB,OAAO;AACL,YAAA,GAAG,KAAK;YACR,YAAY;AACZ,YAAA,OAAO,EAAE,IAAI;AACb,YAAA,SAAS,EAAE,IAAI;AACf,YAAA,OAAO,EAAE,KAAK;AACd,YAAA,YAAY,EAAE,KAAK;SACpB;IACH;IAEA,OAAO;AACL,QAAA,GAAG,KAAK;AACR,QAAA,YAAY,EAAE,SAAS;AACvB,QAAA,OAAO,EAAE,IAAI;AACb,QAAA,SAAS,EAAE,IAAI;AACf,QAAA,OAAO,EAAE,IAAI;AACb,QAAA,YAAY,EAAE,KAAK;KACpB;AACH;AAEA;;;AAGG;SACa,eAAe,CAC7B,KAAoB,EACpB,GAAG,UAA+C,EAAA;AAElD,IAAA,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE;AAClB,QAAA,OAAO,KAAK;IACd;AAEA,IAAA,OAAO,QAAQ,CAAC,KAAK,EAAE,GAAG,UAAU,CAAC;AACvC;AAEA;;;AAGG;AACI,eAAe,oBAAoB,CACxC,KAAoB,EACpB,GAAG,UAA2C,EAAA;AAE9C,IAAA,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE;AAClB,QAAA,OAAO,KAAK;IACd;AAEA,IAAA,OAAO,aAAa,CAAC,KAAK,EAAE,GAAG,UAAU,CAAC;AAC5C;;;;"}

package/dist/esm/lib/types.d.ts

@@ -1,3 +1,4 @@
+/** Represents the state of a single form field. */
 export interface FieldState<T> {
     /** The current value of the field. */
     value: T;
@@ -7,42 +8,77 @@ export interface FieldState<T> {
     isTouched: boolean;
     /** Whether the value of the field has been changed by the user. */
     isDirty: boolean;
-    /** Whether the field is valid */
+    /** Whether the field is valid. */
     isValid: boolean;
-    /** Whether the field is currently being validated */
+    /** Whether the field is currently being validated. */
     isValidating: boolean;
 }
+/** Props passed to the render function of a {@link Field} component. */
 export interface FieldRenderProps<T> extends FieldState<T> {
+    /** Callback to update the field value. Should be called when the input value changes. */
     handleChange: (value: T) => void;
+    /** Callback to mark the field as touched. Should be called when the input loses focus. */
     handleBlur: () => void;
+    /** Ref callback to attach to the root element of the input. Used to focus the field on validation errors. */
     ref: (el: HTMLElement | null) => void;
 }
+/** Validator functions to run on different field events. */
 export interface Validation<T> {
+    /** Synchronous validator to run when the field value changes. */
     onChange?: SyncValidator<T>;
+    /** Asynchronous validator to run when the field value changes (debounced). */
     onChangeAsync?: AsyncValidator<T>;
+    /** Synchronous validator to run when the field loses focus. */
     onBlur?: SyncValidator<T>;
+    /** Asynchronous validator to run when the field loses focus. */
     onBlurAsync?: AsyncValidator<T>;
+    /** Synchronous validator to run when the form is submitted. */
     onSubmit?: SyncValidator<T>;
+    /** Asynchronous validator to run when the form is submitted. */
     onSubmitAsync?: AsyncValidator<T>;
 }
+/**
+ * Specifies when validation errors are displayed.
+ *
+ * - `"touched"` — Show errors after the field has been focused and blurred.
+ * - `"dirty"` — Show errors after the field value has been changed.
+ * - `"touchedAndDirty"` — Show errors only after the field has been both touched and changed.
+ * - `"touchedOrDirty"` — Show errors after the field has been either touched or changed.
+ */
 export type ValidationMode = "touched" | "dirty" | "touchedAndDirty" | "touchedOrDirty";
+/** Props for the {@link Field} component. */
 export interface FieldProps<T> {
+    /** The current state of the field, created with {@link createFieldState}. */
     state: FieldState<T>;
+    /** Render function that receives field state and event handlers. */
     children: (props: FieldRenderProps<T>) => React.ReactNode;
+    /** Callback invoked with the updated field state whenever the state changes. */
     onChange: (newState: FieldState<T>) => void;
+    /** Callback invoked with the raw input value on every change, before validation. */
     onInput?: (value: T) => void;
+    /** Callback invoked when the field loses focus. */
     onBlur?: () => void;
+    /** Validator functions to run on various field events. */
     validation?: Validation<T>;
+    /** Overrides the validation mode set on the parent {@link Form}. Defaults to `"touchedAndDirty"`. */
     validationMode?: ValidationMode;
+    /** Debounce delay in milliseconds for async validators. Overrides the value set on the parent {@link Form}. Defaults to `500`. */
     debounceMs?: number;
 }
+/** A synchronous validator function. Returns an error message if validation fails, or a falsy value if it passes. */
 export type SyncValidator<T> = (value: T) => React.ReactNode;
+/** An asynchronous validator function. Resolves with an error message if validation fails, or a falsy value if it passes. */
 export type AsyncValidator<T> = (value: T) => Promise<React.ReactNode>;
+/** A synchronous or asynchronous validator function. */
 export type Validator<T> = SyncValidator<T> | AsyncValidator<T>;
 export interface FormContextValue {
+    /** Default validation mode applied to all fields in the form. */
     validationMode?: ValidationMode;
+    /** Default debounce delay in milliseconds for async validators. */
     debounceMs?: number;
+    /** Registers a field with the form for submit validation. */
     registerField: (id: string, ref: HTMLElement | null, validate: () => Promise<boolean>, commitPendingValidation: () => void) => void;
+    /** Unregisters a field from the form. */
     unregisterField: (id: string) => void;
 }
 export type FieldMap = Map<string, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fransek/form",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "type": "module",
   "private": false,
   "author": "Frans Ekman <fransedvinekman@gmail.com>",