@juantroconisf/lib 7.0.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,78 +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<ArrayPaths<O>, string>>;
 }
-type TouchedType = Map<string, boolean>;
-type ErrorsType = Map<string, NextUIError>;
+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 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"];
 }
 /**
@@ -100,8 +86,9 @@ interface OnMethods<O extends StateType> {
     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). */
-    /** Registers an array element — adapts to primitive arrays (by index). */
     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;
@@ -176,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 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 };