@juantroconisf/lib 6.1.0 → 8.0.0

package/README.md

@@ -1,65 +1,112 @@
 # @juantroconisf/lib
 
-A powerful, type-safe form management and validation library optimized for **HeroUI** (formerly NextUI).
+A powerful, type-safe form management and validation library optimized for **HeroUI** (formerly NextUI) and **React**.
 
-## Key Features
+Designed for complex applications, it provides **O(1) value updates**, stable **ID-based array management**, and deep nesting support, all while fully integrating with **Yup** for schema validation.
+
+---
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Usage Guide](#usage-guide)
+  - [Scalar Fields](#scalar-fields)
+  - [Nested Objects](#nested-objects)
+  - [Managing Arrays](#managing-arrays)
+  - [Validation](#validation)
+  - [Submitting Forms](#submitting-forms)
+- [API Reference](#api-reference)
+  - [useForm](#useform)
+  - [The `on` Object](#the-on-object)
+  - [Array Helpers](#array-helpers)
+  - [Metadata & Reset](#metadata--reset)
+
+---
+
+## Features
 
 - 🎯 **Polymorphic `on` API**: Single consistent interface for `input`, `select`, and `autocomplete`.
 - 🧩 **Deep Nesting**: Effortlessly manage complex objects with dot-notation support (e.g., `address.city`).
-- 🔢 **ID-Based Arrays**: Stable state management for dynamic lists. Items are tracked by unique identifiers, preventing state loss during reordering or deletions.
+- 🔢 **ID-Based Arrays**: Stable state management for dynamic lists. Items are tracked by unique identifiers (default: `id`), preventing state loss during reordering or deletions.
 - ⚡ **O(1) Performance**: Internal mapping for array items ensures lightning-fast updates regardless of list size.
 - 🛡️ **Total Type Safety**: Best-in-class Intellisense for paths, types, and array identifiers.
-- 🎨 **HeroUI Optimized**: Returns props ready to be spread directly onto HeroUI components (`isInvalid`, `errorMessage`, `onBlur`, etc.).
+- 🎨 **HeroUI Optimized**: Returns props ready to be spread directly onto HeroUI components (`isInvalid`, `errorMessage`, `onFieldBlur`, etc.).
+- ✅ **Yup Integration**: Built-in support for Yup schemas for validation.
 
 ---
 
 ## Installation
 
 ```bash
-pnpm add @juantroconisf/lib
+pnpm add @juantroconisf/lib yup
 ```
 
 ---
 
 ## Quick Start
 
+Here is a complete example demonstrating scalar fields, object arrays, and validation.
+
 ```tsx
 import { useForm } from "@juantroconisf/lib";
+import { string, number, array, object } from "yup";
+import { Input, Button } from "@heroui/react";
 
 const MyForm = () => {
-  const { on, state, helpers } = useForm({
-    name: "Juan",
-    lines: [
-      { id: 1, amount: 10 }
-    ]
-  }, {
-    rules: {
-      name: { required: true }
-    },
-    arrayRules: {
-      lines: {
-        amount: (item, index) => ({ min: 1 })
-      }
-    }
+  const { on, state, helpers, onSubmit } = useForm({
+    name: string().required("Name is required").default(""),
+    items: array()
+      .of(
+        object().shape({
+          id: number().required(),
+          label: string().required("Label is required"),
+        }),
+      )
+      .default([{ id: 1, label: "Initial Item" }]),
   });
 
+  const handleSubmit = (data) => {
+    console.log("Submitted:", data);
+  };
+
   return (
-    <form>
-      {/* Scalar/Nested Registration */}
-      <Input {...on.input("name")} label="Name" />
-
-      {/* Array Registration (By ID) */}
-      {state.lines.map((line) => (
-        <Input 
-          key={line.id} 
-          {...on.input("lines", line.id, "amount")} 
-          label="Amount" 
-        />
+    <form onSubmit={onSubmit(handleSubmit)} className='flex flex-col gap-4'>
+      {/* 1. Scalar Registration */}
+      <Input {...on.input("name")} label='Name' />
+
+      {/* 2. Array Registration */}
+      {state.items.map((item) => (
+        <div key={item.id} className='flex gap-2 items-center'>
+          
+          {/* 
+             Bind by Path + ID 
+             This ensures that even if the array order changes, 
+             the input remains bound to the correct item.
+          */}
+          <Input 
+            {...on.input("items.label", item.id)} 
+            label='Item Label' 
+          />
+          
+          <Button 
+            color="danger" 
+            onClick={() => helpers.removeById("items", item.id)}
+          >
+            Remove
+          </Button>
+        </div>
       ))}
-      
-      <Button onClick={() => helpers.removeById("lines", 1)}>
-        Remove First
-      </Button>
+
+      <div className="flex gap-2">
+        <Button
+          onClick={() => helpers.addItem("items", { id: Date.now(), label: "" })}
+        >
+          Add Item
+        </Button>
+        <Button type='submit' color="primary">Submit</Button>
+      </div>
     </form>
   );
 };
@@ -67,31 +114,166 @@ const MyForm = () => {
 
 ---
 
+## Usage Guide
+
+### Scalar Fields
+
+Scalar fields are the bread and butter of any form. Use `on.input`, `on.select`, or `on.autocomplete` to bind them.
+
+```tsx
+<Input {...on.input("fullName")} label="Full Name" />
+<Input {...on.input("email")} type="email" label="Email" />
+```
+
+### Nested Objects
+
+No special configuration needed. Just use standard dot notation.
+
+```tsx
+const { on } = useForm({
+  settings: object({
+    theme: object({
+      mode: string().default("dark"),
+    }),
+  }),
+});
+
+<Input {...on.input("settings.theme.mode")} />
+```
+
+### Managing Arrays
+
+The library shines with arrays. It tracks items by ID, so you can reorder or delete items without losing focus or state.
+
+**1. Binding Inputs:**
+
+Always bind using the composite syntax: `path.field` + `itemId`.
+
+```tsx
+// ✅ Correct: Binds to the item with ID 123
+on.input("users.name", 123)
+
+// ❌ Avoid (unless primitive array): Binds to index 0
+on.input("users", 0) 
+```
+
+**2. Manipulating the Array:**
+
+Use the `helpers` object.
+
+```tsx
+// Add
+helpers.addItem("users", { id: "new-id", name: "" });
+
+// Remove by ID (Safe)
+helpers.removeById("users", "user-id-123");
+
+// Move (Reorder)
+helpers.moveById("users", "from-id", "to-id");
+```
+
+### Validation
+
+Validation is "Schema-First" via Yup.
+
+1.  **Define Rules**: Pass a Yup schema to `useForm`.
+2.  **Auto-Validation**: 
+    - Fields validate on `blur`.
+    - If a field is `touched` and `invalid`, it re-validates on every keystroke (`onChange`).
+3.  **Submit Validation**: Use `onSubmit` wrapper to validate all fields before executing your handler.
+
+### Submitting Forms
+
+The `onSubmit` wrapper handles `preventDefault`, runs full validation, and only executes your callback if valid.
+
+```tsx
+const { onSubmit } = useForm(...);
+
+const handleSubmit = (data) => {
+  // 1. Validation has already passed!
+  // 2. Proceed with submission
+  api.post("/users", data);
+};
+
+return <form onSubmit={onSubmit(handleSubmit)}>...</form>;
+```
+
+---
+
 ## API Reference
 
-### `useForm(initialState, options)`
+### `useForm`
+
+```ts
+const { 
+  state, 
+  on, 
+  helpers, 
+  metadata, 
+  reset, 
+  onSubmit, 
+  reset, 
+  onSubmit, 
+  isDirty,
+  onFieldChange,
+  onFieldBlur
+} = useForm(schema, options?);
+```
+
+#### Arguments
+
+| Argument | Type | Description |
+| :--- | :--- | :--- |
+| **`schema`** | `Yup.Schema` | A Yup schema object defining structure, default values, and validation rules. |
+| **`options`** | `FormOptions` | Configuration object. |
 
 #### Options
-- **`rules`**: Validation rules for root/nested fields.
-- **`messages`**: Custom error messages for root/nested fields.
-- **`arrayRules`**: Validation rules for array items. Receives `(item, index)`.
-- **`arrayMessages`**: Custom error messages for array items.
-- **`arrayIdentifiers`**: Mapping of array keys to their unique ID property (defaults to `"id"`).
+
+- **`arrayIdentifiers`**: Mapping of array paths to their unique ID property (default: `"id"`).
 
 ### The `on` Object
-Provides methods to register components with the form state. Support both scalar/nested paths and array tracking.
-
-- **`on.input(path)`** / **`on.input(arrayKey, itemId, field)`**
-- **`on.select(path)`** / **`on.select(arrayKey, itemId, field)`**
-- **`on.autocomplete(path)`** / **`on.autocomplete(arrayKey, itemId, field)`**
-
-### Helpers
-Utilities for common state manipulations:
-- **`addItem(arrayKey, item, index?)`**
-- **`removeItem(arrayKey, index)`**
-- **`removeById(arrayKey, itemId)`**
-- **`moveItem(arrayKey, from, to)`**
-- **`moveById(arrayKey, fromId, toId)`**
+
+The `on` object generates props for your components: `value`, `onValueChange`, `isInvalid`, `errorMessage`, `onBlur`.
+
+| Method | Signature | Description |
+| :--- | :--- | :--- |
+| **`on.input`** | `(path, [id])` | Generic input handler. Returns standard input props. |
+| **`on.select`** | `(path, [id])` | Returns props compatible with `Select` (handles `selectedKeys`). |
+| **`on.autocomplete`** | `(path, [id])` | Returns props compatible with `Autocomplete` (handles `selectedKey`). |
+
+### Array Helpers
+
+Utilities for manipulating array state.
+
+| Method | Description |
+| :--- | :--- |
+| **`addItem(key, item, index?)`** | Adds an item to the array. |
+| **`removeItem(key, index)`** | Removes an item at a specific index. |
+| **`removeById(key, id)`** | **Recommended**. Removes an item by its unique ID. |
+| **`updateItem(key, index, val)`** | Replaces an item at a specific index. |
+| **`moveItem(key, from, to)`** | Moves an item from one index to another. |
+| **`moveById(key, fromId, toId)`** | Moves an item by ID. |
+| **`getItem(key, id)`** | Retrieval helper. |
+
+### Metadata & Reset
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| **`metadata`** | `Map<string, FieldMetadata>` | Contains validation state (`isInvalid`, `errorMessage`) and `isTouched`. |
+| **`reset`** | `(options?) => void` | Resets form state and metadata to initial values. |
+
+**Reset Options:**
+
+```ts
+// Reset everything
+reset();
+
+// Keep specific fields
+reset({ keys: ["organizationId"] });
+
+// Only clear touched status (keep values)
+reset({ onlyTouched: true });
+```
 
 ---
 

package/dist/index.d.mts

@@ -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 };