@juantroconisf/lib 6.1.0 → 8.0.0

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { SelectProps, AutocompleteProps } 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,82 +14,63 @@ 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<ArrayKeys<O>, string>>;
+    arrayIdentifiers?: Partial<Record<ArrayPaths<O>, string>>;
+}
+type FieldMetadata = {
+    isTouched: boolean;
+    isInvalid: boolean;
+    errorMessage: string;
+};
+type MetadataType = Map<string, FieldMetadata>;
+type SubmitHandler<O extends StateType> = (data: O, e: React.FormEvent) => void;
+interface ResetOptions<O> {
+    preservedStateKeys?: (keyof O)[];
+    preserveTouched?: boolean;
 }
-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;
 }
-type UXProps<O extends StateType> = Record<keyof O, {
-    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"];
 }
 /**
@@ -98,23 +80,50 @@ interface OnMethods<O extends StateType> {
     /** Registers a scalar or nested object field. */
     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). */
-    input<K extends ArrayKeys<O>>(arrayKey: K, ...args: O[K] extends Record<string, any>[] ? [itemId: ItemIdType<O, K>, field: FieldPaths<ArrayElement<O[K]>>] | [itemId: ItemIdType<O, K>, field: string, index: number] : [index: number]): ItemInputProps<any>;
+    /** Registers an array element — adapts to primitive arrays (by index). */
+    input<K extends ArrayKeys<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>;
     /** 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 ArrayKeys<O>>(arrayKey: K): ItemSelectProps;
     /** Registers an array element — adapts to primitive arrays (by index) or object arrays (by ID + field). */
-    select<K extends ArrayKeys<O>>(arrayKey: K, ...args: O[K] extends Record<string, any>[] ? [itemId: ItemIdType<O, K>, field: FieldPaths<ArrayElement<O[K]>>] | [itemId: ItemIdType<O, K>, field: string, index: number] : [index: number]): ItemSelectProps;
+    select<K extends ArrayKeys<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;
     /** 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). */
-    autocomplete<K extends ArrayKeys<O>>(arrayKey: K, ...args: O[K] extends Record<string, any>[] ? [itemId: ItemIdType<O, K>, field: FieldPaths<ArrayElement<O[K]>>] | [itemId: ItemIdType<O, K>, field: string, index: number] : [index: number]): ItemAutocompleteProps;
+    /** Registers an array element — adapts to primitive arrays (by index). */
+    autocomplete<K extends ArrayKeys<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;
 }
 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.
+ */
+type ArrayPaths<T> = T extends object ? {
+    [K in keyof T & string]: NonNullable<T[K]> extends (infer E)[] ? K | (E extends object ? `${K}.${ArrayPaths<E>}` : never) : NonNullable<T[K]> extends object ? NonNullable<T[K]> extends Date ? never : `${K}.${ArrayPaths<NonNullable<T[K]>>}` : never;
+}[keyof T & string] : never;
 /** Keys whose values are arrays of objects (not primitives). */
 type ObjectArrayKeys<O extends StateType> = {
     [K in keyof O]: O[K] extends Record<string, any>[] ? K : never;
 }[keyof O];
+/**
+ * Helper to get paths for fields within object arrays.
+ * Returns paths like "arrayKey.fieldName".
+ */
+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;
@@ -154,29 +163,33 @@ interface HelpersFunc<O extends StateType> {
  * @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 (preserve keys, preserve touched).
+     */
+    reset: (options?: ResetOptions<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.
+     */
+    onSubmit: (fn: SubmitHandler<O>) => (e: React.FormEvent) => 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 }?: 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 UXProps, 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 HelpersFunc, type InferState, type MetadataType, type NestedChangeProps, NextUIError, type OnMethods, type StateType, type SubmitHandler, type UseFormResponse, type ValueChangeFunc, useForm };