@juantroconisf/lib 11.8.0 → 11.10.0

package/README.md

@@ -25,6 +25,7 @@ Managing forms in React often involves manual state syncing and verbose validati
   - [4. Manual Updates](#4-performing-manual-updates)
 - [Reference](#reference)
   - [useForm API](#useformschema-options)
+  - [Validation Results](#validation-results)
   - [on.* API](#the-on-api)
   - [Array Helpers](#array-helpers-helpers)
 - [Explanation](#explanation)
@@ -139,6 +140,36 @@ onArrayItemChange({ at: "users.name", id: userId, value: "Alice" });
 | `resetOnSubmit` | `boolean` | Reset form after success (default: `false`) |
 | `keepValues` | `(keyof State)[]` | Fields to exclude from reset |
 
+### Validation Results
+
+The `validateAll`, `validateItem`, and the `helpers` validation methods return a `ValidationResponse` object:
+
+```ts
+// Top level
+const { isValid, results } = await validateAll();
+const { isValid, results } = await validateFields(["firstName", "lastName"]);
+
+// Within helpers
+const { isValid, results } = await helpers.validateItem("users", userId);
+```
+  isValid: boolean;
+  errors: string[]; // List of composite IDs with errors
+  results: ErrorResult[]; // Detailed error objects
+}
+
+interface ErrorResult {
+  id: string;      // e.g. "users.0.name"
+  label: string;   // resolved from DOM (e.g. "User Name") or prettified ID
+  message: string; // validation error message
+}
+```
+
+#### Automatic Label Capture
+The library lazily resolves labels the first time a field is blurred or validated. It checks in priority:
+1. `aria-labelledby` element's text.
+2. Standard `<label for="...">` text.
+3. Fallback: Prettified last segment of the ID (capitalized).
+
 ### The `on.*` API
 Methods that bridge schema logic to HeroUI components.
 

package/dist/index.d.mts

@@ -58,8 +58,20 @@ type FieldMetadata = {
     isTouched: boolean;
     isInvalid: boolean;
     errorMessage: string;
+    /** Captured label or placeholder for the field. */
+    label?: string;
 };
 type MetadataType = Map<string, FieldMetadata>;
+type ErrorResult = {
+    id: string;
+    label: string;
+    message: string;
+};
+type ValidationResponse = {
+    isValid: boolean;
+    errors: string[];
+    results: ErrorResult[];
+};
 type FormSubmitHandler<O extends StateType> = (data: O, e: React.FormEvent) => void;
 /**
  * A utility type for inferring the submit handler's signature directly from a Yup schema object.
@@ -239,7 +251,11 @@ interface HelpersFunc<O extends StateType> {
     /** Gets an item from an array by its unique identifier (O(1) via indexMap). */
     getItemById: <K extends ArrayPaths<O>>(arrayKey: K, itemId: string | number) => (NestedFieldValue<O, K> extends (infer E)[] ? E : never) | undefined;
     /** Validates a single item in an array by its unique identifier. */
-    validateItem: <K extends ArrayPaths<O>>(arrayKey: K, itemId: string | number) => Promise<boolean>;
+    validateItem: <K extends ArrayPaths<O>>(arrayKey: K, itemId: string | number) => Promise<ValidationResponse>;
+    /** Validates all fields in the form. */
+    validateAll: () => Promise<ValidationResponse>;
+    /** Validates a specific set of fields by their paths. */
+    validateFields: (paths: (keyof O | string)[]) => Promise<ValidationResponse>;
 }
 /**
  * The response object from the useForm hook.
@@ -287,15 +303,19 @@ interface UseFormResponse<O extends StateType> {
      * If validation fails, identifying errors and touching fields.
      * If validation succeeds, calls the provided handler with the current state.
      */
-    onFormSubmit: (fn: FormSubmitHandler<O>) => (e: React.FormEvent) => void;
+    onFormSubmit: (fn: FormSubmitHandler<O>) => (e: React.FormEvent) => Promise<void>;
     /**
      * A controlled form component that handles submission and validation.
      */
     ControlledForm: React.ComponentType<Omit<FormProps, "onSubmit"> & {
         onSubmit?: (data: O, e: React.FormEvent<HTMLFormElement>) => void;
     }>;
+    /** Validates all fields in the form. */
+    validateAll: () => Promise<ValidationResponse>;
+    /** Validates a specific set of fields by their paths. */
+    validateFields: (paths: (keyof O | string)[]) => Promise<ValidationResponse>;
 }
 
 declare function useForm<S extends Record<string, ConfigType>>(schema: S, { arrayIdentifiers, onFormSubmit: onFormSubmitProp, resetOnSubmit, keepValues: keepValuesProp, }?: FormOptions<InferState<S>>): UseFormResponse<InferState<S>>;
 
-export { type BlurFunc, type ComponentInputProps, type ConfigType, type FieldMetadata, type FormOptions, type FormResetOptions, type FormSubmit, type FormSubmitHandler, type HelpersFunc, type InferState, type InferSubmitHandler, type ItemAutocompleteProps, type ItemInputProps, type ItemNumberInputProps, type ItemRadioGroupProps, type ItemSelectProps, type ItemToggleProps, type MetadataType, type NestedChangeProps, NextUIError, type OnMethods, type StateType, type UseFormResponse, type ValueChangeFunc, useForm };
+export { type BlurFunc, type ComponentInputProps, type ConfigType, type ErrorResult, type FieldMetadata, type FormOptions, type FormResetOptions, type FormSubmit, type FormSubmitHandler, type HelpersFunc, type InferState, type InferSubmitHandler, type ItemAutocompleteProps, type ItemInputProps, type ItemNumberInputProps, type ItemRadioGroupProps, type ItemSelectProps, type ItemToggleProps, type MetadataType, type NestedChangeProps, NextUIError, type OnMethods, type StateType, type UseFormResponse, type ValidationResponse, type ValueChangeFunc, useForm };

package/dist/index.d.ts

@@ -58,8 +58,20 @@ type FieldMetadata = {
     isTouched: boolean;
     isInvalid: boolean;
     errorMessage: string;
+    /** Captured label or placeholder for the field. */
+    label?: string;
 };
 type MetadataType = Map<string, FieldMetadata>;
+type ErrorResult = {
+    id: string;
+    label: string;
+    message: string;
+};
+type ValidationResponse = {
+    isValid: boolean;
+    errors: string[];
+    results: ErrorResult[];
+};
 type FormSubmitHandler<O extends StateType> = (data: O, e: React.FormEvent) => void;
 /**
  * A utility type for inferring the submit handler's signature directly from a Yup schema object.
@@ -239,7 +251,11 @@ interface HelpersFunc<O extends StateType> {
     /** Gets an item from an array by its unique identifier (O(1) via indexMap). */
     getItemById: <K extends ArrayPaths<O>>(arrayKey: K, itemId: string | number) => (NestedFieldValue<O, K> extends (infer E)[] ? E : never) | undefined;
     /** Validates a single item in an array by its unique identifier. */
-    validateItem: <K extends ArrayPaths<O>>(arrayKey: K, itemId: string | number) => Promise<boolean>;
+    validateItem: <K extends ArrayPaths<O>>(arrayKey: K, itemId: string | number) => Promise<ValidationResponse>;
+    /** Validates all fields in the form. */
+    validateAll: () => Promise<ValidationResponse>;
+    /** Validates a specific set of fields by their paths. */
+    validateFields: (paths: (keyof O | string)[]) => Promise<ValidationResponse>;
 }
 /**
  * The response object from the useForm hook.
@@ -287,15 +303,19 @@ interface UseFormResponse<O extends StateType> {
      * If validation fails, identifying errors and touching fields.
      * If validation succeeds, calls the provided handler with the current state.
      */
-    onFormSubmit: (fn: FormSubmitHandler<O>) => (e: React.FormEvent) => void;
+    onFormSubmit: (fn: FormSubmitHandler<O>) => (e: React.FormEvent) => Promise<void>;
     /**
      * A controlled form component that handles submission and validation.
      */
     ControlledForm: React.ComponentType<Omit<FormProps, "onSubmit"> & {
         onSubmit?: (data: O, e: React.FormEvent<HTMLFormElement>) => void;
     }>;
+    /** Validates all fields in the form. */
+    validateAll: () => Promise<ValidationResponse>;
+    /** Validates a specific set of fields by their paths. */
+    validateFields: (paths: (keyof O | string)[]) => Promise<ValidationResponse>;
 }
 
 declare function useForm<S extends Record<string, ConfigType>>(schema: S, { arrayIdentifiers, onFormSubmit: onFormSubmitProp, resetOnSubmit, keepValues: keepValuesProp, }?: FormOptions<InferState<S>>): UseFormResponse<InferState<S>>;
 
-export { type BlurFunc, type ComponentInputProps, type ConfigType, type FieldMetadata, type FormOptions, type FormResetOptions, type FormSubmit, type FormSubmitHandler, type HelpersFunc, type InferState, type InferSubmitHandler, type ItemAutocompleteProps, type ItemInputProps, type ItemNumberInputProps, type ItemRadioGroupProps, type ItemSelectProps, type ItemToggleProps, type MetadataType, type NestedChangeProps, NextUIError, type OnMethods, type StateType, type UseFormResponse, type ValueChangeFunc, useForm };
+export { type BlurFunc, type ComponentInputProps, type ConfigType, type ErrorResult, type FieldMetadata, type FormOptions, type FormResetOptions, type FormSubmit, type FormSubmitHandler, type HelpersFunc, type InferState, type InferSubmitHandler, type ItemAutocompleteProps, type ItemInputProps, type ItemNumberInputProps, type ItemRadioGroupProps, type ItemSelectProps, type ItemToggleProps, type MetadataType, type NestedChangeProps, NextUIError, type OnMethods, type StateType, type UseFormResponse, type ValidationResponse, type ValueChangeFunc, useForm };