@juantroconisf/lib 9.1.0 → 9.2.0

package/README.md

@@ -1,8 +1,8 @@
 # @juantroconisf/lib
 
-A powerful, type-safe form management and validation library optimized for **HeroUI** (formerly NextUI) and **React**.
+A powerful, type-safe form management and validation library tailored for **HeroUI** and **React**.
 
-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.
+Designed for complex applications, it provides **O(1) value updates**, stable **ID-based array management**, and deep nesting support, all seamlessly integrated with **Yup** schemas.
 
 ---
 
@@ -10,30 +10,31 @@ Designed for complex applications, it provides **O(1) value updates**, stable **
 
 - [Features](#features)
 - [Installation](#installation)
+- [Localization](#localization)
 - [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)
+  - [Form Submission](#form-submission)
 - [API Reference](#api-reference)
   - [useForm](#useform)
-  - [The `on` Object](#the-on-object)
+  - [The `on` API](#the-on-api)
+  - [ControlledForm](#controlledform)
   - [Array Helpers](#array-helpers)
-  - [Metadata & Reset](#metadata--reset)
+  - [Form Controls](#form-controls)
 
 ---
 
 ## 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 (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`, `onFieldBlur`, etc.).
-- ✅ **Yup Integration**: Built-in support for Yup schemas for validation.
+- 🎯 **Polymorphic `on` API**: A unified interface (`on.input`, `on.select`, `on.autocomplete`) saving lines of boilerplate.
+- 🧱 **ControlledForm Component**: Zero-boilerplate validated submissions leveraging the `@heroui/react` Form component directly.
+- 🧩 **Deep Nesting**: Dot-notation support (e.g., `settings.theme`) out of the box.
+- 🔢 **ID-Based Arrays**: List items are tracked by unique identifiers (default: `id`), ensuring states survive mapping, reordering, and deletions.
+- ⚡ **O(1) Performance**: Internal mapping for array updates offers incredible speed regardless of data density.
+- 🛡️ **Complete Type Safety**: TypeScript infers all acceptable paths, data structures, and outputs natively.
+- 🌍 **Built-in Localization**: Ships with English and Spanish validation translations via runtime cookies.
 
 ---
 
@@ -45,69 +46,107 @@ pnpm add @juantroconisf/lib yup
 
 ---
 
+## Localization
+
+Validation strings (e.g., minimum length, required fields) are localized automatically. The library checks for a browser cookie named `LOCALE` on initialization.
+
+- **Supported Locales**: `en` (English - default) and `es` (Spanish).
+- **How to Set**:
+  Set the cookie in your client application:
+  ```ts
+  document.cookie = "LOCALE=es; path=/; max-age=31536000"; // Sets language to Spanish
+  ```
+  If no cookie is detected, or the value is unrecognized, the library gracefully falls back to English (`en`).
+
+---
+
 ## Quick Start
 
-Here is a complete example demonstrating scalar fields, object arrays, and validation.
+Throughout this documentation, we will refer to a common, diverse schema. It includes simple scalars, deep objects, and complex arrays.
 
 ```tsx
 import { useForm } from "@juantroconisf/lib";
-import { string, number, array, object } from "yup";
-import { Input, Button } from "@heroui/react";
+import { string, number, array, object, boolean } from "yup";
+import { Input, Switch, Select, SelectItem, Button } from "@heroui/react";
 
-const MyForm = () => {
-  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" }]),
-  });
+// 1. Define your diverse schema structure
+const mySchema = {
+  fullName: string().required("Name is required").default(""),
+  age: number().min(18).default(18),
+  settings: object({
+    theme: string().oneOf(["light", "dark"]).default("dark"),
+    notifications: boolean().default(true),
+  }),
+  users: array()
+    .of(
+      object().shape({
+        id: number().required(),
+        role: string().required(),
+      }),
+    )
+    .default([{ id: Date.now(), role: "admin" }]),
+};
 
-  const handleSubmit = (data) => {
-    console.log("Submitted:", data);
+const MyForm = () => {
+  // 2. Initialize the hook with fully inferred types
+  const { on, state, helpers, ControlledForm } = useForm(mySchema);
+
+  // 3. Types are perfectly inferred from your Yup schema
+  const handleSubmit = (data, event) => {
+    console.log("Submitted payload:", data);
+    // data.fullName -> string
+    // data.settings.theme -> "light" | "dark"
+    // data.users[0].role -> string
   };
 
   return (
-    <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>
-      ))}
-
-      <div className="flex gap-2">
+    <ControlledForm onSubmit={handleSubmit} className='flex flex-col gap-4'>
+      {/* Scalar Fields */}
+      <Input {...on.input("fullName")} label='Full Name' />
+      <Input {...on.input("age")} type='number' label='Age' />
+
+      {/* Nested Object Fields */}
+      <Switch {...on.input("settings.notifications")}>
+        Enable Notifications
+      </Switch>
+      <Select {...on.select("settings.theme")} label='Theme'>
+        <SelectItem key='light'>Light</SelectItem>
+        <SelectItem key='dark'>Dark</SelectItem>
+      </Select>
+
+      {/* Array Fields */}
+      <div className='flex flex-col gap-2'>
+        <h3>Users</h3>
+        {state.users.map((user) => (
+          <div key={user.id} className='flex gap-2 items-center'>
+            {/* Bind by Array Path + Item ID */}
+            <Select {...on.select("users.role", user.id)} label='Role'>
+              <SelectItem key='admin'>Admin</SelectItem>
+              <SelectItem key='guest'>Guest</SelectItem>
+            </Select>
+            <Button
+              color='danger'
+              onPress={() => helpers.removeById("users", user.id)}
+            >
+              Remove
+            </Button>
+          </div>
+        ))}
+      </div>
+
+      <div className='flex gap-2'>
         <Button
-          onClick={() => helpers.addItem("items", { id: Date.now(), label: "" })}
+          onPress={() =>
+            helpers.addItem("users", { id: Date.now(), role: "guest" })
+          }
         >
-          Add Item
+          Add User
+        </Button>
+        <Button type='submit' color='primary'>
+          Submit
         </Button>
-        <Button type='submit' color="primary">Submit</Button>
       </div>
-    </form>
+    </ControlledForm>
   );
 };
 ```
@@ -116,86 +155,122 @@ const MyForm = () => {
 
 ## Usage Guide
 
+All examples below continue referencing the `mySchema` definition from the Quick Start.
+
 ### Scalar Fields
 
-Scalar fields are the bread and butter of any form. Use `on.input`, `on.select`, or `on.autocomplete` to bind them.
+Scalar fields map directly to your schema definitions. Use `on.input`, `on.select`, or `on.autocomplete` to yield binding props instantly compatible with HeroUI.
 
 ```tsx
 <Input {...on.input("fullName")} label="Full Name" />
-<Input {...on.input("email")} type="email" label="Email" />
+<Input {...on.input("age")} type="number" label="Age" />
 ```
 
 ### Nested Objects
 
-No special configuration needed. Just use standard dot notation.
+Nested state is managed intuitively via dot-notation directly on your identifiers. Your TypeScript types will validate that the path points to real endpoints on your data shape.
 
 ```tsx
-const { on } = useForm({
-  settings: object({
-    theme: object({
-      mode: string().default("dark"),
-    }),
-  }),
-});
-
-<Input {...on.input("settings.theme.mode")} />
+// Binds seamlessly to state.settings.theme
+<Select {...on.select("settings.theme")} label="Theme">
+  <SelectItem key="light">Light</SelectItem>
+  <SelectItem key="dark">Dark</SelectItem>
+</Select>
+
+// Booleans map smoothly to Switches/Checkboxes
+<Switch {...on.input("settings.notifications")}>Enable Alerts</Switch>
 ```
 
 ### Managing Arrays
 
-The library shines with arrays. It tracks items by ID, so you can reorder or delete items without losing focus or state.
+Array management is uniquely built around tracking entries by ID (`'id'` field by default). This stops issues where UI inputs lose state references if the array gets shifted.
 
-**1. Binding Inputs:**
+**Binding UI to Items:**
+Combine the general array path and the item ID.
 
-Always bind using the composite syntax: `path.field` + `itemId`.
+```tsx
+// ✅ Correct: Binds perfectly regardless of list index changes
+on.select("users.role", userId);
+
+// ❌ Warning (Unless primitives array): Prevents index-shifting stability
+on.select("users", 0);
+```
+
+**Using the `helpers` Library:**
+Extract `helpers` out of `useForm(...)` to manipulate array state securely.
 
 ```tsx
-// ✅ Correct: Binds to the item with ID 123
-on.input("users.name", 123)
+const { helpers } = useForm(mySchema);
+
+// Add an item (Optionally provide index as a 3rd argument to insert)
+helpers.addItem("users", { id: Date.now(), role: "guest" });
+
+// Remove item by ID
+helpers.removeById("users", 12345);
 
-// ❌ Avoid (unless primitive array): Binds to index 0
-on.input("users", 0) 
+// Reorder items by ID
+helpers.moveById("users", fromId, toId);
 ```
 
-**2. Manipulating the Array:**
+### Form Submission
 
-Use the `helpers` object.
+There are two primary ways to submit, validate, and handle your logic, both fully type-safe.
 
-```tsx
-// Add
-helpers.addItem("users", { id: "new-id", name: "" });
+**1. The `ControlledForm` Wrapper (Recommended)**
 
-// Remove by ID (Safe)
-helpers.removeById("users", "user-id-123");
+`ControlledForm` behaves exactly like a HeroUI `Form` component. It automatically intercepts submit events, validates all bindings through your schema, and invokes `onSubmit` with the validated dataset.
 
-// Move (Reorder)
-helpers.moveById("users", "from-id", "to-id");
+```tsx
+const { ControlledForm } = useForm(mySchema);
+
+return (
+  <ControlledForm onSubmit={(data, event) => console.log(data.fullName)}>
+    <Input {...on.input("fullName")} />
+    <Button type='submit'>Submit</Button>
+  </ControlledForm>
+);
 ```
 
-### Validation
+**2. The `onFormSubmit` Handler Wrapper**
 
-Validation is "Schema-First" via Yup.
+If you prefer using native HTML `<form>` tags, you can pass your callback into `onFormSubmit`. The params exposed to your callback are tightly inferred from the schema.
+
+```tsx
+const { onFormSubmit, state } = useForm(mySchema);
 
-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.
+// Automatically infers your final structured data (data) and the React form event (e)
+const submitHandler = onFormSubmit((data, e) => {
+  // Validation passed successfully!
+  // 'data.settings.theme' is correctly typed as string.
+  api.post("/endpoint", data);
+});
+
+// Used manually on form tags or button invocations
+<form onSubmit={submitHandler}>{/* inputs */}</form>;
+```
 
-### Submitting Forms
+**3. External Handler Definitions**
 
-The `onSubmit` wrapper handles `preventDefault`, runs full validation, and only executes your callback if valid.
+If you define your schemas inline inside `useForm( { ... } )` but want to extract your `submit` handler natively without destructing variables you aren't using:
 
 ```tsx
-const { onSubmit } = useForm(...);
+export const MyForm = () => {
+  // 1. Schema is defined organically inline inside the component execution
+  const { ControlledForm } = useForm({
+    fullName: string().required(),
+  });
 
-const handleSubmit = (data) => {
-  // 1. Validation has already passed!
-  // 2. Proceed with submission
-  api.post("/users", data);
-};
+  // 2. Type your extract handler capturing React.ComponentProps directly on the wrapper
+  const handleSubmit: React.ComponentProps<
+    typeof ControlledForm
+  >["onSubmit"] = (data, event) => {
+    // Both data.fullName and React Events are perfectly inferred natively!
+    console.log(data.fullName);
+  };
 
-return <form onSubmit={onSubmit(handleSubmit)}>...</form>;
+  // 3. Destructure whatever you need right on your JSX render
+  return <ControlledForm onSubmit={handleSubmit}>...</ControlledForm>;
+};
 ```
 
 ---
@@ -204,76 +279,81 @@ return <form onSubmit={onSubmit(handleSubmit)}>...</form>;
 
 ### `useForm`
 
+Instantiates state and schema configurations.
+
 ```ts
-const { 
-  state, 
-  on, 
-  helpers, 
-  metadata, 
-  reset, 
-  onSubmit, 
-  reset, 
-  onSubmit, 
-  isDirty,
-  onFieldChange,
-  onFieldBlur
-} = useForm(schema, options?);
+const formApi = 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. |
+| Parameter     | Type                         | Description                                                                      |
+| :------------ | :--------------------------- | :------------------------------------------------------------------------------- |
+| **`schema`**  | `Record<string, ConfigType>` | Your form shape configuration containing `Yup` schemas or primitive constraints. |
+| **`options`** | `FormOptions`                | Configuration behaviors.                                                         |
 
 #### Options
 
-- **`arrayIdentifiers`**: Mapping of array paths to their unique ID property (default: `"id"`).
+| Option                 | Type       | Description                                                                     |
+| :--------------------- | :--------- | :------------------------------------------------------------------------------ |
+| **`arrayIdentifiers`** | `Object`   | Identifier maps for objects missing `id` (e.g. `{ users: "uuid" }`).            |
+| **`resetOnSubmit`**    | `boolean`  | Instantly resets all values tracking arrays to initialization configurations.   |
+| **`onFormSubmit`**     | `Function` | Fallback default submission pipeline.                                           |
+| **`keepValues`**       | `string[]` | Keys in the root state to preserve during a reset (e.g. `["settings", "age"]`). |
 
-### The `on` Object
+---
 
-The `on` object generates props for your components: `value`, `onValueChange`, `isInvalid`, `errorMessage`, `onBlur`.
+### The `on` API
 
-| 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`). |
+`on` hooks dynamically assign value tracks, validity checks, error text extractions, and update invocations back to the controller.
 
-### Array Helpers
+| Method                            | Description                                                                  |
+| :-------------------------------- | :--------------------------------------------------------------------------- |
+| **`on.input(path, [itemId])`**    | Exports `{ id, isInvalid, errorMessage, value, onValueChange, onBlur }`.     |
+| **`on.select(path, [itemId])`**   | Exports properties mapped for `<Select>` components matching `selectedKeys`. |
+| **`on.autocomplete(path, [id])`** | Exports properties mapped for `<Autocomplete>` matching `selectedKey`.       |
 
-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. |
+### ControlledForm
 
-### Metadata & Reset
+A Drop-in `<Form />` equivalent handling submit event delegation natively linked to validation triggers internally.
 
-| 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. |
+| Prop           | Type                | Description                                                                                                                                                        |
+| :------------- | :------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **`onSubmit`** | `(data, e) => void` | Invoked strictly post-validation of `schema` variables passing criteria. Both arguments `data` (your state payload) and `e` (the React event) are correctly typed. |
 
-**Reset Options:**
+_Notes: Spreads any traditional `<form>` properties to standard HeroUI mappings out of the box._
 
-```ts
-// Reset everything
-reset();
+---
 
-// Keep specific fields
-reset({ keys: ["organizationId"] });
+### Array Helpers
 
-// Only clear touched status (keep values)
-reset({ onlyTouched: true });
-```
+Array adjustments exported off the `helpers` map:
+
+| Utility                            | Description                                                                   |
+| :--------------------------------- | :---------------------------------------------------------------------------- |
+| **`addItem(path, item, index?)`**  | Submits entries safely.                                                       |
+| **`removeItem(path, index)`**      | Excludes entry mapped at index map offset.                                    |
+| **`removeById(path, id)`**         | Standard and secure ID withdrawal.                                            |
+| **`updateItem(path, index, val)`** | Hot swap content without re-render destruction.                               |
+| **`moveItem(path, current, to)`**  | Re-order index slots.                                                         |
+| **`moveById(path, fromId, toId)`** | Shift lists seamlessly referencing fixed ID targets.                          |
+| **`getItem(path, id)`**            | Read items immediately via O(1) indexed lookups without array mapping cycles. |
+
+---
+
+### Form Controls
+
+Additional utilities available directly out of `useForm`:
+
+| Method            | Signatures / Types                  | Info                                                                |
+| :---------------- | :---------------------------------- | :------------------------------------------------------------------ |
+| **`state`**       | `InferState<S>`                     | Evaluated state values matching object signatures defined.          |
+| **`setState`**    | `Dispatch<SetStateAction>`          | The fundamental state mutation.                                     |
+| **`onFormReset`** | `(opts?: { keepValues: string[] })` | Discards invalidity layers and remounts variables back to defaults. |
+| **`isDirty`**     | `boolean`                           | Truthy flag reflecting if state parameters altered.                 |
+| **`metadata`**    | `Map<string, FieldMetadata>`        | Touched and Error metadata instances tracked.                       |
 
 ---
 

package/dist/index.d.mts

@@ -61,6 +61,11 @@ type FieldMetadata = {
 };
 type MetadataType = Map<string, FieldMetadata>;
 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.
+ * This saves developers from manually mapping `InferType` back to `FormSubmitHandler` when extracting sumbits.
+ */
+type InferSubmitHandler<S extends Record<string, ConfigType>> = (data: InferState<S>, e: React.FormEvent) => void;
 interface FormResetOptions<O> {
     keepValues?: (keyof O)[];
 }
@@ -205,4 +210,4 @@ interface UseFormResponse<O extends StateType> {
 
 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 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 };
+export { type BlurFunc, type ConfigType, type FieldMetadata, type FormOptions, type FormSubmitHandler, type HelpersFunc, type InferState, type InferSubmitHandler, type MetadataType, type NestedChangeProps, NextUIError, type OnMethods, type StateType, type UseFormResponse, type ValueChangeFunc, useForm };

package/dist/index.d.ts

@@ -61,6 +61,11 @@ type FieldMetadata = {
 };
 type MetadataType = Map<string, FieldMetadata>;
 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.
+ * This saves developers from manually mapping `InferType` back to `FormSubmitHandler` when extracting sumbits.
+ */
+type InferSubmitHandler<S extends Record<string, ConfigType>> = (data: InferState<S>, e: React.FormEvent) => void;
 interface FormResetOptions<O> {
     keepValues?: (keyof O)[];
 }
@@ -205,4 +210,4 @@ interface UseFormResponse<O extends StateType> {
 
 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 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 };
+export { type BlurFunc, type ConfigType, type FieldMetadata, type FormOptions, type FormSubmitHandler, type HelpersFunc, type InferState, type InferSubmitHandler, type MetadataType, type NestedChangeProps, NextUIError, type OnMethods, type StateType, type UseFormResponse, type ValueChangeFunc, useForm };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juantroconisf/lib",
-  "version": "9.1.0",
+  "version": "9.2.0",
   "description": "A form validation library for HeroUI.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",