@juantroconisf/lib 7.0.0 → 9.0.0

package/dist/index.d.ts

@@ -1,5 +1,6 @@
-import { SelectProps, AutocompleteProps } from '@heroui/react';
+import { SelectProps, AutocompleteProps, FormProps } from '@heroui/react';
 import { SingleSelection } from '@react-types/shared';
+import { Schema, InferType } from 'yup';
 
 type StateType = Record<string, any>;
 interface NestedChangeProps<O extends StateType> {
@@ -13,78 +14,77 @@ declare class NextUIError {
     errorMessage: string;
     constructor(bool?: boolean, msg?: string);
 }
-type ValidatorFunction<T, U> = (val: T, ...args: U[]) => boolean;
-interface Validator<T, U = any> {
-    validate: ValidatorFunction<T, U>;
-    msg: string;
-}
-interface ValidatorTypes {
-    required: Validator<string | number, boolean>;
-    min: Validator<number | string, number | string>;
-    max: Validator<number | string, number | string>;
-    minLength: Validator<string, number>;
-    maxLength: Validator<string, number>;
-    pattern: Validator<string, RegExp>;
-    equal: Validator<string, string>;
-    numberIsEqual: Validator<number, number>;
-    email: Validator<string, boolean>;
-    password: Validator<string, boolean>;
-    custom: Validator<any, boolean>;
-}
-type ValidatorParams = {
-    [K in keyof ValidatorTypes]?: ValidatorTypes[K] extends Validator<any, infer U> ? U : never;
-};
-type ValidatorErrorMessage = {
-    [K in keyof ValidatorTypes]?: string;
-};
 
 /**
- * Validation rules for individual fields in an array item.
- * @template O The state type.
- * @template K The key of the array in the state.
+ * Valid types for the initial state configuration.
+ * Can be a raw value or a Yup schema.
  */
-type ValidatorRule<item = any> = ValidatorParams | ((item: item, ...args: any[]) => ValidatorParams);
-type RulePath<T> = T extends object ? {
-    [K in keyof T & string]: NonNullable<T[K]> extends (infer E)[] ? K | (E extends object ? `${K}.${RulePath<E>}` : never) : NonNullable<T[K]> extends object ? NonNullable<T[K]> extends Date ? K : K | `${K}.${RulePath<NonNullable<T[K]>>}` : K;
-}[keyof T & string] : never;
+type ConfigType = any | Schema<any>;
+/**
+ * Helper to infer the state type from the configuration object.
+ * If a value is a Yup schema, infer its return type.
+ * Otherwise, use the value's type directly.
+ */
+type InferState<S extends Record<string, ConfigType>> = {
+    [K in keyof S]: S[K] extends Schema<any, any, any, any> ? InferType<S[K]> : S[K];
+};
 /**
  * Options for the useForm hook.
  * @template O The state type.
  */
 interface FormOptions<O extends StateType> {
-    /** Validation rules for top-level fields. */
-    rules?: Partial<Record<RulePath<O>, ValidatorRule>>;
-    /** Custom error messages for top-level fields. */
-    messages?: Partial<Record<RulePath<O>, ValidatorErrorMessage>>;
     /**
      * Custom property names used as unique identifiers for items in specific arrays.
      * Default is "id".
      */
-    arrayIdentifiers?: Partial<Record<ArrayPaths<O>, string>>;
+    arrayIdentifiers?: {
+        [K in ArrayPaths<O>]?: NestedFieldValue<O, K> extends (infer E)[] ? E extends object ? ScalarKeys<E> : never : never;
+    };
+    /**
+     * Optional submit handler that is called when the form is submitted and validation passes.
+     */
+    onFormSubmit?: FormSubmitHandler<O>;
+    /**
+     * Whether to automatically reset the form after a successful submission.
+     * @default false
+     */
+    resetOnSubmit?: boolean;
+    /**
+     * Keys to preserve when resetting the form.
+     */
+    keepValues?: (keyof O)[];
+}
+type FieldMetadata = {
+    isTouched: boolean;
+    isInvalid: boolean;
+    errorMessage: string;
+};
+type MetadataType = Map<string, FieldMetadata>;
+type FormSubmitHandler<O extends StateType> = (data: O, e: React.FormEvent) => void;
+interface FormResetOptions<O> {
+    keepValues?: (keyof O)[];
 }
-type TouchedType = Map<string, boolean>;
-type ErrorsType = Map<string, NextUIError>;
 type ValueChangeFunc<O extends StateType, K extends keyof O> = (id: K, value: O[K]) => void;
 type BlurFunc<O extends StateType> = (id: keyof O) => void;
-interface ComponentInputProps<O extends StateType> {
+interface ComponentInputProps {
     id: string;
     onBlur: () => void;
     isInvalid: boolean;
     errorMessage: string;
 }
 /** Props returned by on.input() */
-interface ItemInputProps<V = any> extends ComponentInputProps<any> {
+interface ItemInputProps<V = any> extends ComponentInputProps {
     onValueChange: (value: V) => void;
     value: V;
 }
 /** Props returned by on.select() */
-interface ItemSelectProps extends ComponentInputProps<any> {
-    onSelectionChange: SelectProps["onSelectionChange"];
+interface ItemSelectProps extends ComponentInputProps {
+    onSelectionChange: NonNullable<SelectProps["onSelectionChange"]>;
     selectedKeys: string[] | number[] | string | null;
 }
 /** Props returned by on.autocomplete() */
-interface ItemAutocompleteProps extends ComponentInputProps<any> {
-    onSelectionChange: AutocompleteProps["onSelectionChange"];
+interface ItemAutocompleteProps extends ComponentInputProps {
+    onSelectionChange: NonNullable<AutocompleteProps["onSelectionChange"]>;
     selectedKey: SingleSelection["selectedKey"];
 }
 /**
@@ -95,27 +95,25 @@ interface OnMethods<O extends StateType> {
     input<P extends AllPaths<O>>(id: P): ItemInputProps<NestedFieldValue<O, P & string>>;
     /** Registers an array element — adapts to primitive arrays (by index) or object arrays (by ID + field). */
     /** Registers an array element — adapts to primitive arrays (by index). */
-    input<K extends ArrayKeys<O>>(arrayKey: K, index: number): ItemInputProps<any>;
+    input<K extends ArrayPaths<O>>(arrayKey: K, index: number): ItemInputProps<any>;
     /** Registers an object array element's field using composite syntax "array.field". */
-    input<P extends ObjectArrayFieldPaths<O>>(compositePath: P, itemId: ItemIdType<O, GetArrayKeyFromPath<O, P>>): ItemInputProps<any>;
+    input<P extends ObjectArrayFieldPaths<O>>(compositePath: P, itemId: string | number): ItemInputProps<any>;
     /** Registers a scalar or nested object field. */
     select<P extends AllPaths<O>>(id: P): ItemSelectProps;
+    /** Registers a complete array field for multi-selection. */
+    select<K extends ArrayPaths<O>>(arrayKey: K): ItemSelectProps;
     /** Registers an array element — adapts to primitive arrays (by index) or object arrays (by ID + field). */
-    /** Registers an array element — adapts to primitive arrays (by index). */
-    select<K extends ArrayKeys<O>>(arrayKey: K, index: number): ItemSelectProps;
+    select<K extends ArrayPaths<O>>(arrayKey: K, index: number): ItemSelectProps;
     /** Registers an object array element's field using composite syntax "array.field". */
-    select<P extends ObjectArrayFieldPaths<O>>(compositePath: P, itemId: ItemIdType<O, GetArrayKeyFromPath<O, P>>): ItemSelectProps;
+    select<P extends ObjectArrayFieldPaths<O>>(compositePath: P, itemId: string | number): ItemSelectProps;
     /** Registers a scalar or nested object field. */
     autocomplete<P extends AllPaths<O>>(id: P): ItemAutocompleteProps;
     /** Registers an array element — adapts to primitive arrays (by index) or object arrays (by ID + field). */
     /** Registers an array element — adapts to primitive arrays (by index). */
-    autocomplete<K extends ArrayKeys<O>>(arrayKey: K, index: number): ItemAutocompleteProps;
+    autocomplete<K extends ArrayPaths<O>>(arrayKey: K, index: number): ItemAutocompleteProps;
     /** Registers an object array element's field using composite syntax "array.field". */
-    autocomplete<P extends ObjectArrayFieldPaths<O>>(compositePath: P, itemId: ItemIdType<O, GetArrayKeyFromPath<O, P>>): ItemAutocompleteProps;
+    autocomplete<P extends ObjectArrayFieldPaths<O>>(compositePath: P, itemId: string | number): ItemAutocompleteProps;
 }
-type ArrayKeys<O extends StateType> = {
-    [K in keyof O]: O[K] extends any[] ? K : never;
-}[keyof O];
 /**
  * Recursive type to find all paths to arrays in the state.
  */
@@ -133,14 +131,10 @@ type ObjectArrayKeys<O extends StateType> = {
 type ObjectArrayFieldPaths<O extends StateType> = {
     [K in keyof O]: O[K] extends Record<string, any>[] ? `${K & string}.${FieldPaths<ArrayElement<O[K]>>}` : never;
 }[keyof O];
-/**
- * Helper to extract the array key from a path string like "arrayKey.field".
- */
-type GetArrayKeyFromPath<O extends StateType, P extends string> = P extends `${infer K}.${string}` ? K extends keyof O ? O[K] extends any[] ? K : never : never : never;
 type ArrayElement<T> = T extends (infer E)[] ? E : never;
 /** Resolves the type of the identifier field for an array element (defaults to "id"). */
 type ItemIdType<O extends StateType, K extends keyof O> = "id" extends keyof ArrayElement<O[K]> ? ArrayElement<O[K]>["id"] : string | number;
-type NestedFieldValue<T, F extends string> = F extends `${infer First}.${infer Rest}` ? First extends keyof T ? NestedFieldValue<T[First], Rest> : any : F extends keyof T ? T[F] : any;
+type NestedFieldValue<T, F extends string> = F extends `${infer First}.${infer Rest}` ? First extends keyof T ? NestedFieldValue<NonNullable<T[First]>, Rest> : NonNullable<T> extends (infer U)[] ? NestedFieldValue<U, F> : any : F extends keyof T ? NonNullable<T[F]> : NonNullable<T> extends (infer U)[] ? F extends keyof U ? NonNullable<U[F]> : any : any;
 type FieldPaths<T> = T extends Record<string, any> ? {
     [K in keyof T & string]: T[K] extends any[] ? K : T[K] extends Record<string, any> ? `${K}.${FieldPaths<T[K]>}` : K;
 }[keyof T & string] : never;
@@ -157,48 +151,58 @@ type AllPaths<O extends StateType> = ScalarKeys<O> | NestedObjectPaths<O>;
  */
 interface HelpersFunc<O extends StateType> {
     /** Adds a new item to an array. */
-    addItem: <K extends ArrayKeys<O>>(arrayKey: K, item: ArrayElement<O[K]>, index?: number) => void;
+    addItem: <K extends ArrayPaths<O>>(arrayKey: K, item: NestedFieldValue<O, K> extends (infer E)[] ? E : never, index?: number) => void;
     /** Removes an item from an array by its index. */
-    removeItem: <K extends ArrayKeys<O>>(arrayKey: K, index: number) => void;
+    removeItem: <K extends ArrayPaths<O>>(arrayKey: K, index: number) => void;
     /** Removes an item from an array by its unique identifier. */
-    removeById: <K extends ArrayKeys<O>>(arrayKey: K, itemId: string | number) => void;
+    removeById: <K extends ArrayPaths<O>>(arrayKey: K, itemId: string | number) => void;
     /** Replaces an item in an array at the given index. */
-    updateItem: <K extends ArrayKeys<O>>(arrayKey: K, index: number, value: ArrayElement<O[K]>) => void;
+    updateItem: <K extends ArrayPaths<O>>(arrayKey: K, index: number, value: NestedFieldValue<O, K> extends (infer E)[] ? E : never) => void;
     /** Moves an item within an array using indices. */
-    moveItem: <K extends ArrayKeys<O>>(arrayKey: K, from: number, to: number) => void;
+    moveItem: <K extends ArrayPaths<O>>(arrayKey: K, from: number, to: number) => void;
     /** Moves an item within an array using unique identifiers. */
-    moveById: <K extends ArrayKeys<O>>(arrayKey: K, fromId: string | number, toId: string | number) => void;
+    moveById: <K extends ArrayPaths<O>>(arrayKey: K, fromId: string | number, toId: string | number) => void;
     /** Gets an item from an array by its unique identifier (O(1) via indexMap). */
-    getItem: <K extends ArrayKeys<O>>(arrayKey: K, itemId: ItemIdType<O, K>) => ArrayElement<O[K]> | undefined;
+    getItem: <K extends ArrayPaths<O>>(arrayKey: K, itemId: string | number) => (NestedFieldValue<O, K> extends (infer E)[] ? E : never) | undefined;
 }
 /**
  * The response object from the useForm hook.
  * @template O The state type.
  */
 interface UseFormResponse<O extends StateType> {
-    onBlur: BlurFunc<O>;
+    onFieldBlur: BlurFunc<O>;
     /** Updates an object array element's field by ID. */
-    onValueChange<K extends ObjectArrayKeys<O>, F extends keyof ArrayElement<O[K]> & string>(arrayKey: K, itemId: ItemIdType<O, K>, field: F, value: ArrayElement<O[K]>[F]): void;
+    onFieldChange<K extends ObjectArrayKeys<O>, F extends keyof ArrayElement<O[K]> & string>(arrayKey: K, itemId: ItemIdType<O, K>, field: F, value: ArrayElement<O[K]>[F]): void;
     /** Updates a scalar or nested object field. */
-    onValueChange<P extends AllPaths<O>>(id: P, value: NestedFieldValue<O, P & string>): void;
+    onFieldChange<P extends AllPaths<O>>(id: P, value: NestedFieldValue<O, P & string>): void;
     onSelectionChange: ValueChangeFunc<O, keyof O>;
     state: O;
     setState: React.Dispatch<React.SetStateAction<O>>;
-    touched: TouchedType;
-    errors: ErrorsType;
+    metadata: MetadataType;
     /** Main object to bind form elements to the state. */
     on: OnMethods<O>;
     /** Array manipulation helpers. */
     helpers: HelpersFunc<O>;
     isDirty: boolean;
-    /** Manually triggers all validations and marks all fields as touched. Returns true if any error is found. */
-    hasInvalidValues: () => boolean;
-    /** Resets the form state and metadata. */
-    resetForm: (preservedKeys?: (keyof O)[]) => void;
-    /** Resets the touched metadata. */
-    resetTouched: (preservedKeys?: (keyof O)[]) => void;
+    /**
+     * Resets the form state and metadata.
+     * @param options Configuration for the reset (e.g., keys to keep).
+     */
+    onFormReset: (options?: FormResetOptions<O>) => void;
+    /**
+     * Wraps a form submission handler to automatically validate the form.
+     * 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;
+    /**
+     * A controlled form component that handles submission and validation.
+     */
+    ControlledForm: React.ComponentType<Omit<FormProps, "onSubmit"> & {
+        onSubmit?: (data: O, e: React.FormEvent<HTMLFormElement>) => void;
+    }>;
 }
 
-declare function useForm<O extends StateType>(initialState: O, { rules, messages, arrayIdentifiers }?: FormOptions<O>): UseFormResponse<O>;
+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 ErrorsType, type FormOptions, type HelpersFunc, type NestedChangeProps, NextUIError, type OnMethods, type StateType, type TouchedType, type UseFormResponse, type Validator, type ValidatorErrorMessage, type ValidatorParams, type ValidatorRule, type ValidatorTypes, type ValueChangeFunc, useForm };
+export { type BlurFunc, type ConfigType, type FieldMetadata, type FormOptions, type FormSubmitHandler, type HelpersFunc, type InferState, type MetadataType, type NestedChangeProps, NextUIError, type OnMethods, type StateType, type UseFormResponse, type ValueChangeFunc, useForm };