@juantroconisf/lib 11.6.0 → 11.7.0

package/README.md

@@ -1,437 +1,180 @@
-# @juantroconisf/lib
-
-A type-safe form management library for **React** and **HeroUI**. It eliminates boilerplate through a declarative `on.*` API that bridges your [Yup](https://github.com/jquense/yup) schema directly to HeroUI component props — complete with validation, error messages, dirty tracking, and ID-based array management.
-
----
-
-## Table of Contents
-
-- [Installation](#installation)
-- [Quick Start](#quick-start)
-- [Core Concepts](#core-concepts)
-  - [Schema Definition](#schema-definition)
-  - [Scalar Fields](#scalar-fields)
-  - [Nested Objects](#nested-objects)
-  - [Array Fields](#array-fields)
-- [The `on` API — Component Bindings](#the-on-api--component-bindings)
-- [Manual Updates](#manual-updates)
-- [Array Helpers](#array-helpers)
-- [Form Submission](#form-submission)
-- [API Reference](#api-reference)
-- [Localization](#localization)
-
----
-
-## Installation
-
-```bash
-pnpm add @juantroconisf/lib yup
-```
-
----
-
-## Quick Start
-
-```tsx
-import { useForm } from "@juantroconisf/lib";
-import { string, boolean } from "yup";
-import { Input, Switch, Button } from "@heroui/react";
-
-const MyForm = () => {
-  const { on, ControlledForm } = useForm({
-    fullName: string().required().default(""),
-    darkMode: boolean().default(false),
-  });
-
-  return (
-    <ControlledForm onSubmit={(data) => console.log(data)}>
-      <Input {...on.input("fullName")} label='Full Name' />
-      <Switch {...on.switch("darkMode")}>Dark Mode</Switch>
-      <Button type='submit' color='primary'>
-        Submit
-      </Button>
-    </ControlledForm>
-  );
-};
-```
-
-> `on.input("fullName")` spreads `value`, `onValueChange`, `isInvalid`, `errorMessage`, `isRequired`, `onBlur`, and `id` directly onto the HeroUI component. Zero boilerplate.
-
----
-
-## Core Concepts
-
-### Schema Definition
-
-Pass a plain object of Yup schemas (or raw values for unvalidated state) to `useForm`. The hook infers your TypeScript types automatically.
-
-```ts
-const { on, state, helpers, ControlledForm } = useForm({
-  email: string().email().required().default(""),
-  age: number().min(18).default(18),
-  settings: {
-    theme: string().oneOf(["light", "dark"]).default("dark"),
-    notifications: boolean().default(true),
-  },
-  tags: array().of(string()).default([]),
-  users: array()
-    .of(object({ id: number().required(), role: string().required() }))
-    .default([]),
-});
-```
-
-### Scalar Fields
-
-Top-level primitive fields. Use dot notation to reach into nested objects.
-
-```tsx
-<Input {...on.input("email")} label="Email" />
-<Input {...on.numberInput("age")} label="Age" />
-<Select {...on.select("settings.theme")} label="Theme">
-  <SelectItem key="light">Light</SelectItem>
-  <SelectItem key="dark">Dark</SelectItem>
-</Select>
-```
-
-### Nested Objects
-
-Dot notation reaches arbitrarily deep. TypeScript validates that the path exists and has the correct type.
-
-```tsx
-<Switch {...on.switch("settings.notifications")}>
-  Enable Notifications
-</Switch>
-<Autocomplete {...on.autocomplete("settings.theme")} label="Theme" />
-```
-
-### Array Fields
-
-Arrays of objects are tracked by item `id` (configurable via `arrayIdentifiers`). This means inputs hold their state correctly even after re-ordering or deletions.
-
-```tsx
-{
-  state.users.map((user) => (
-    <div key={user.id}>
-      {/* Bind to a field inside the array item using: path + itemId */}
-      <Input {...on.input("users.name", user.id)} label='Name' />
-      <Select {...on.select("users.role", user.id)} label='Role'>
-        <SelectItem key='admin'>Admin</SelectItem>
-        <SelectItem key='guest'>Guest</SelectItem>
-      </Select>
-      <Button onPress={() => helpers.removeById("users", user.id)}>
-        Remove
-      </Button>
-    </div>
-  ));
-}
-<Button
-  onPress={() => helpers.addItem("users", { id: Date.now(), role: "guest" })}
->
-  Add User
-</Button>;
-```
-
-### Deeply Nested Arrays (N-Level Depth)
-
-If your schema contains arrays inside objects inside arrays (infinite depth), you can pass a variadic sequence of arguments alternating between structural paths and array IDs (or indexes).
-
-```tsx
-// Schema: items[].form_response.input_values[].value
-<Input
-  {...on.input("items", itemId, "form_response.input_values", inputId, "value")}
-  label='Deep Value'
-/>
-```
-
-The library dynamically traverses your state, mapping IDs securely to their array indices natively, regardless of depth.
-
----
-
-## The `on` API — Component Bindings
-
-Each `on.*` method returns a set of props that you spread directly onto a HeroUI component. Every method automatically handles:
-
-- **Controlled value** — synced with form state
-- **Validation** — runs on change and blur against your Yup schema
-- **Error display** — `isInvalid` and `errorMessage` from the schema
-- **Required indicator** — `isRequired` derived from `.required()` in your schema
-
-All methods support **scalar/nested** paths, standard **array item** paths (composite `"array.field"` + `itemId`), and **variadic sequences** for N-level deep structures.
-
-| Method                     | HeroUI Component    | Key props returned                              |
-| -------------------------- | ------------------- | ----------------------------------------------- |
-| `on.input(...args)`        | `Input`, `Textarea` | `value: string`, `onValueChange(string)`        |
-| `on.numberInput(...args)`  | `NumberInput`       | `value: number`, `onValueChange(number)`        |
-| `on.select(...args)`       | `Select`            | `selectedKeys`, `onSelectionChange`             |
-| `on.autocomplete(...args)` | `Autocomplete`      | `selectedKey`, `onSelectionChange`              |
-| `on.checkbox(...args)`     | `Checkbox`          | `isSelected: boolean`, `onValueChange(boolean)` |
-| `on.switch(...args)`       | `Switch`            | `isSelected: boolean`, `onValueChange(boolean)` |
-| `on.radio(...args)`        | `RadioGroup`        | `value: string`, `onValueChange(string)`        |
-
-> **Why separate methods?** Each HeroUI component has a different prop contract (e.g. `isSelected` vs `value`, `onSelectionChange` vs `onValueChange`). Separate methods give accurate intellisense for each component.
-
-### Examples
-
-```tsx
-{/* Text input */}
-<Input {...on.input("firstName")} label="First Name" />
-
-{/* Numeric input (NumberInput-specific) */}
-<NumberInput {...on.numberInput("age")} label="Age" />
-
-{/* Boolean toggle */}
-<Checkbox {...on.checkbox("agreed")}>I agree to the terms</Checkbox>
-<Switch {...on.switch("notifications")}>Notifications</Switch>
-
-{/* String radio selection */}
-<RadioGroup {...on.radio("gender")} label="Gender">
-  <Radio value="male">Male</Radio>
-  <Radio value="female">Female</Radio>
-</RadioGroup>
-
-{/* Dropdown selection */}
-<Select {...on.select("country")} label="Country">
-  <SelectItem key="us">United States</SelectItem>
-  <SelectItem key="ca">Canada</SelectItem>
-</Select>
-
-{/* Inside an array — pass item ID as 2nd arg */}
-<Input {...on.input("users.name", user.id)} label="Name" />
-<Switch {...on.switch("users.active", user.id)}>Active</Switch>
-```
-
----
-
-## Manual Updates
-
-For updating state outside of a component (e.g. in an event handler, after an API call), use the manual functions returned by `useForm`.
-
-| Function                 | Use for                         | Signature             |
-| ------------------------ | ------------------------------- | --------------------- |
-| `onFieldChange`          | Scalar / nested object field    | `(id, value)`         |
-| `onArrayItemChange`      | Object array item field         | `({ at, id, value })` |
-| `onSelectionChange`      | Scalar / nested selection field | `(id, value)`         |
-| `onArraySelectionChange` | Array item selection field      | `({ at, id, value })` |
-
-```ts
-const { onFieldChange, onArrayItemChange, onSelectionChange } = useForm(schema);
-
-// Update a scalar field
-onFieldChange("email", "user@example.com");
-
-// Update a field inside an array item
-onArrayItemChange({ at: "users.name", id: userId, value: "Alice" });
-
-// Update a selection field inside an array item
-onArraySelectionChange({ at: "users.role", id: userId, value: "admin" });
-```
-
-> **`at`** is the composite dot-notation path (`"array.field"`), **`id`** is the item's unique identifier, **`value`** is the new value to set. These are direct setters — call them imperatively, not as event listeners.
-
----
-
-## Array Helpers
-
-Extracted from `helpers` on the `useForm` return value. Items in object arrays are tracked by ID (default field: `id`).
-
-| Method                                      | Description                                        |
-| ------------------------------------------- | -------------------------------------------------- |
-| `addItem(path, item, index?)`               | Adds an item to the end (or at `index`)            |
-| `removeItemByIndex(path, index)`            | Removes by index                                   |
-| `removeById(path, id)`                      | Removes by item ID                                 |
-| `updateByIndex(path, index, partial)`       | Partially updates an item by index (shallow merge) |
-| `updateById(path, id, partial)`             | Partially updates an item by ID (shallow merge)    |
-| `moveItemByIndex(path, fromIndex, toIndex)` | Reorders by index                                  |
-| `moveById(path, fromId, toId)`              | Reorders by ID                                     |
-| `getItemById(path, id)`                     | O(1) lookup by ID                                  |
-
-```ts
-const { helpers } = useForm(schema);
-
-helpers.addItem("users", { id: Date.now(), name: "", role: "guest" });
-helpers.removeById("users", 123);
-helpers.updateById("users", 123, { name: "Alice" }); // partial update — other fields preserved
-helpers.moveById("users", 123, 456); // moves item 123 to where item 456 is
-```
-
-### Custom Array Identifier
-
-By default, the library tracks array items by their `id` field. If your items use a different field (e.g. `uuid`, `slug`, `code`), configure it via `arrayIdentifiers` in the options.
-
-```ts
-const { on, helpers, onArrayItemChange } = useForm(
-  {
-    employees: array()
-      .of(
-        object({
-          uuid: string().required(),
-          name: string().required(),
-          role: string().required(),
-        }),
-      )
-      .default([]),
-  },
-  {
-    arrayIdentifiers: {
-      employees: "uuid", // tells the library to use `uuid` instead of `id`
-    },
-  },
-);
-```
-
-**Every ID-based function picks this up automatically:**
-
-```ts
-// on.* bindings — the second arg is the item identifier
-<Input {...on.input("employees.name", employee.uuid)} label="Name" />
-<Select {...on.select("employees.role", employee.uuid)} label="Role">...</Select>
-
-// Manual setters — `id` is the item identifier
-onArrayItemChange({ at: "employees.name", id: employee.uuid, value: "Alice" });
-onArraySelectionChange({ at: "employees.role", id: employee.uuid, value: "admin" });
-
-// Helpers — all `*ById` methods use the configured identifier
-helpers.removeById("employees", employee.uuid);
-helpers.updateById("employees", employee.uuid, { name: "Alice" });   // partial update
-helpers.moveById("employees", fromUuid, toUuid);
-helpers.getItemById("employees", employee.uuid);
-```
-
-> The identifier field you configure must be a **scalar** (string or number) present in every item. The library uses it to build an internal O(1) index map, which is why array operations are fast regardless of list size.
-
-**Type inference:** `arrayIdentifiers` is typed so only valid scalar keys of each array element are accepted:
-
-```ts
-// ✅ uuid is a string field on each employee
-{
-  arrayIdentifiers: {
-    employees: "uuid";
-  }
-}
-
-// ❌ TypeScript error — name is not a valid identifier (may not be unique)
-{
-  arrayIdentifiers: {
-    employees: "name";
-  }
-} // error if "name" is not in type
-```
-
----
-
-## Form Submission
-
-### Option 1: `ControlledForm` (recommended)
-
-`ControlledForm` is a drop-in replacement for HeroUI's `<Form>`. It automatically validates on submit and only calls `onSubmit` if the schema passes.
-
-```tsx
-const { ControlledForm } = useForm(schema);
-
-return (
-  <ControlledForm onSubmit={(data, event) => api.post("/submit", data)}>
-    <Input {...on.input("email")} label='Email' />
-    <Button type='submit'>Submit</Button>
-  </ControlledForm>
-);
-```
-
-`data` is fully typed from your schema. No manual type annotations needed.
-
-### Option 2: `onFormSubmit`
-
-For use with plain HTML `<form>` elements:
-
-```tsx
-const { onFormSubmit } = useForm(schema);
-
-const handleSubmit = onFormSubmit((data, event) => {
-  api.post("/submit", data);
-});
-
-return (
-  <form onSubmit={handleSubmit}>
-    <Input {...on.input("email")} label='Email' />
-    <button type='submit'>Submit</button>
-  </form>
-);
-```
-
-### Option 3: External handler with `FormSubmit`
-
-When you need to define the submit handler outside the JSX, use the `FormSubmit` utility type:
-
-```tsx
-import { useForm, FormSubmit } from "@juantroconisf/lib";
-
-const { ControlledForm } = useForm({
-  email: string().required().default(""),
-});
-
-const handleSubmit: FormSubmit<typeof ControlledForm> = (data, event) => {
-  // data.email is correctly typed as string — no schema re-declaration needed
-  console.log(data.email);
-};
-```
-
-`FormSubmit<typeof ControlledForm>` is a shorthand for `React.ComponentProps<typeof ControlledForm>["onSubmit"]`.
-
----
-
-## API Reference
-
-### `useForm(schema, options?)`
-
-| Parameter | Type                         | Description                                              |
-| --------- | ---------------------------- | -------------------------------------------------------- |
-| `schema`  | `Record<string, ConfigType>` | Yup schemas or primitive values defining your form shape |
-| `options` | `FormOptions`                | Optional configuration                                   |
-
-#### `FormOptions`
-
-| Option             | Type                     | Description                                               |
-| ------------------ | ------------------------ | --------------------------------------------------------- |
-| `arrayIdentifiers` | `Record<string, string>` | Override the ID field for object arrays (default: `"id"`) |
-| `resetOnSubmit`    | `boolean`                | Reset form to defaults after successful submit            |
-| `onFormSubmit`     | `Function`               | Default submit handler passed via options                 |
-| `keepValues`       | `(keyof State)[]`        | Fields to preserve during reset                           |
-
-### `useForm` returns
-
-| Property                 | Type                          | Description                                        |
-| ------------------------ | ----------------------------- | -------------------------------------------------- |
-| `state`                  | `InferState<S>`               | Current form values                                |
-| `setState`               | `Dispatch<SetStateAction<S>>` | Direct state setter                                |
-| `metadata`               | `Map<string, FieldMetadata>`  | Per-field `isTouched`, `isInvalid`, `errorMessage` |
-| `on`                     | `OnMethods<S>`                | Component binding methods                          |
-| `helpers`                | `HelpersFunc<S>`              | Array manipulation methods                         |
-| `isDirty`                | `boolean`                     | `true` if any field has been touched               |
-| `onFieldChange`          | Function                      | Manual scalar field update                         |
-| `onArrayItemChange`      | Function                      | Manual array item field update                     |
-| `onSelectionChange`      | Function                      | Manual scalar selection update                     |
-| `onArraySelectionChange` | Function                      | Manual array item selection update                 |
-| `onFieldBlur`            | Function                      | Manual blur trigger                                |
-| `onFormReset`            | Function                      | Resets state and clears metadata                   |
-| `onFormSubmit`           | Function                      | Wraps a submit handler with validation             |
-| `ControlledForm`         | Component                     | Validated `<Form>` wrapper                         |
-
----
-
-## Localization
-
-Validation error messages are automatically localized. The library reads a `LOCALE` cookie on initialization.
-
-- **Supported**: `en` (English — default), `es` (Spanish)
-- **Setting the locale**:
-
-```ts
-document.cookie = "LOCALE=es; path=/; max-age=31536000";
-```
-
-If no cookie is found, or the value is unrecognized, English is used.
-
----
-
-## License
-
-ISC © Juan T
+# @juantroconisf/lib
+
+[![npm version](https://img.shields.io/npm/v/@juantroconisf/lib.svg)](https://www.npmjs.com/package/@juantroconisf/lib)
+[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
+
+A type-safe form management library for **React** and **HeroUI**. It eliminates boilerplate through a declarative `on.*` API that bridges your [Yup](https://github.com/jquense/yup) schema directly to HeroUI component props — complete with validation, error messages, dirty tracking, and ID-based array management.
+
+## Why this library?
+
+Managing forms in React often involves manual state syncing and verbose validation logic. This library acts as a **bridge**, automatically mapping your [Yup](https://github.com/jquense/yup) schema's constraints directly to your HeroUI components.
+
+### Key Benefits
+- **Zero Boilerplate:** No more manual `value`, `onChange`, and `onBlur` wiring.
+- **Type-Safe:** Automatic inference from your schema with full Intellisense.
+- **Auto-Validation:** Errors and `isRequired` states flow naturally from your schema.
+- **ID-Based Arrays:** Seamless handling of dynamic lists with $O(1)$ performance.
+
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [How-to Guides](#how-to-guides)
+  - [1. Working with Nested Objects](#1-working-with-nested-objects)
+  - [2. Dynamic Arrays](#2-managing-dynamic-arrays)
+  - [3. N-Level Structures](#3-n-level-deep-structures)
+  - [4. Manual Updates](#4-performing-manual-updates)
+- [Reference](#reference)
+  - [useForm API](#useformschema-options)
+  - [on.* API](#the-on-api)
+  - [Array Helpers](#array-helpers-helpers)
+- [Explanation](#explanation)
+
+---
+
+## Quick Start
+
+Get up and running in under a minute.
+
+### 1. Install
+```bash
+pnpm add @juantroconisf/lib yup
+```
+
+### 2. Implementation
+```tsx
+import { useForm } from "@juantroconisf/lib";
+import { string, boolean } from "yup";
+import { Input, Switch, Button } from "@heroui/react";
+
+const MyForm = () => {
+  const { on, ControlledForm } = useForm({
+    fullName: string().required().default(""),
+    darkMode: boolean().default(false),
+  });
+
+  return (
+    <ControlledForm onSubmit={(data) => console.log(data)}>
+      {/* on.input() automatically handles value, onValueChange, isInvalid, and errorMessage */}
+      <Input {...on.input("fullName")} label='Full Name' />
+      
+      <Switch {...on.switch("darkMode")}>Dark Mode</Switch>
+      
+      <Button type='submit' color='primary'>
+        Submit
+      </Button>
+    </ControlledForm>
+  );
+};
+```
+
+---
+
+## How-to Guides
+
+Practical recipes for common form scenarios.
+
+### 1. Working with Nested Objects
+Dot notation reaches arbitrarily deep. TypeScript validates that the path exists and has the correct type.
+
+```tsx
+<Input {...on.input("settings.profile.username")} label="Username" />
+<Switch {...on.switch("settings.notifications")}>
+  Enable Notifications
+</Switch>
+```
+
+### 2. Managing Dynamic Arrays
+Arrays of objects are tracked by item `id` (or a custom identifier). This ensures inputs hold their state correctly even after re-ordering or deletions.
+
+```tsx
+{state.users.map((user) => (
+  <div key={user.id}>
+    {/* Bind to a field inside the array item using: path + itemId */}
+    <Input {...on.input("users.name", user.id)} label='Name' />
+    
+    <Button onPress={() => helpers.removeById("users", user.id)}>
+      Remove
+    </Button>
+  </div>
+))}
+
+<Button onPress={() => helpers.addItem("users", { id: Date.now(), name: "" })}>
+  Add User
+</Button>
+```
+
+### 3. N-Level Deep Structures
+For arrays inside objects inside arrays, pass a variadic sequence alternating between structural paths and identifiers.
+
+```tsx
+// Schema: items[].form_response.input_values[].value
+<Input
+  {...on.input("items", itemId, "form_response.input_values", inputId, "value")}
+  label='Deep Value'
+/>
+```
+
+### 4. Performing Manual Updates
+To update state outside of a component (e.g., in an API response handler), use the manual setters.
+
+```ts
+const { onFieldChange, onArrayItemChange } = useForm(schema);
+
+// Update a top-level or nested field
+onFieldChange("settings.theme", "dark");
+
+// Update a field inside an array item
+onArrayItemChange({ at: "users.name", id: userId, value: "Alice" });
+```
+
+---
+
+## Reference
+
+### `useForm(schema, options?)`
+
+| Option | Type | Description |
+| :--- | :--- | :--- |
+| `arrayIdentifiers` | `Record<string, string>` | Override the ID field (default: `"id"`) |
+| `resetOnSubmit` | `boolean` | Reset form after success (default: `false`) |
+| `keepValues` | `(keyof State)[]` | Fields to exclude from reset |
+
+### The `on.*` API
+Methods that bridge schema logic to HeroUI components.
+
+| Method | HeroUI Component | Key Props Returned |
+| :--- | :--- | :--- |
+| `on.input()` | `Input`, `Textarea` | `value`, `onValueChange` |
+| `on.select()` | `Select` | `selectedKeys`, `onSelectionChange` |
+| `on.switch()` | `Switch` | `isSelected`, `onValueChange` |
+| `on.checkbox()` | `Checkbox` | `isSelected`, `onValueChange` |
+| `on.radio()` | `RadioGroup` | `value`, `onValueChange` |
+
+### Array Helpers (`helpers.*`)
+| Method | Description |
+| :--- | :--- |
+| `addItem(path, item)` | Append a new item |
+| `removeById(path, id)` | Fast $O(1)$ removal by ID |
+| `updateById(path, id, partial)` | Shallow merge by ID |
+| `moveById(path, fromId, toId)` | Reorder items |
+
+---
+
+## Explanation
+
+### The Bridge Architecture
+Traditional form libraries often require you to manually map state to component props (`value={state.foo} onChange={...}`). 
+
+This library uses a **Bridge Pattern**:
+1. Your **Schema** defines the "Source of Truth".
+2. The **`on.*` methods** act as the bridge, translating that truth into the specific prop contract needed by each HeroUI component.
+3. This ensures that validation errors, required indicators, and values are always perfectly in sync without manual wiring.
+
+### Localization
+Validation messages are automatically localized by reading the `LOCALE` cookie (`en` or `es`).
+```ts
+document.cookie = "LOCALE=es; path=/;";
+```
+
+## License
+ISC © Juan T