@juantroconisf/lib 9.4.0 → 11.0.0

package/README.md

@@ -1,40 +1,24 @@
 # @juantroconisf/lib
 
-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 seamlessly integrated with **Yup** schemas.
+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
 
-- [Features](#features)
 - [Installation](#installation)
-- [Localization](#localization)
 - [Quick Start](#quick-start)
-- [Usage Guide](#usage-guide)
+- [Core Concepts](#core-concepts)
+  - [Schema Definition](#schema-definition)
   - [Scalar Fields](#scalar-fields)
   - [Nested Objects](#nested-objects)
-  - [Managing Arrays](#managing-arrays)
-  - [Form Submission](#form-submission)
+  - [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)
-  - [useForm](#useform)
-  - [The `on` API](#the-on-api)
-  - [ControlledForm](#controlledform)
-  - [Array Helpers](#array-helpers)
-  - [Form Controls](#form-controls)
-
----
-
-## Features
-
-- 🎯 **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.
+- [Localization](#localization)
 
 ---
 
@@ -46,314 +30,390 @@ 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
 
-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, boolean } from "yup";
-import { Input, Switch, Select, SelectItem, Button } from "@heroui/react";
-
-// 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" }]),
-};
+import { string, boolean } from "yup";
+import { Input, Switch, Button } from "@heroui/react";
 
 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
-  };
+  const { on, ControlledForm } = useForm({
+    fullName: string().required().default(""),
+    darkMode: boolean().default(false),
+  });
 
   return (
-    <ControlledForm onSubmit={handleSubmit} className='flex flex-col gap-4'>
-      {/* Scalar Fields */}
+    <ControlledForm onSubmit={(data) => console.log(data)}>
       <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
-          onPress={() =>
-            helpers.addItem("users", { id: Date.now(), role: "guest" })
-          }
-        >
-          Add User
-        </Button>
-        <Button type='submit' color='primary'>
-          Submit
-        </Button>
-      </div>
+      <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.
 
-## Usage Guide
+---
 
-All examples below continue referencing the `mySchema` definition from the Quick Start.
+## Core Concepts
 
-### Scalar Fields
+### Schema Definition
 
-Scalar fields map directly to your schema definitions. Use `on.input`, `on.select`, or `on.autocomplete` to yield binding props instantly compatible with HeroUI.
+Pass a plain object of Yup schemas (or raw values for unvalidated state) to `useForm`. The hook infers your TypeScript types automatically.
 
-```tsx
-<Input {...on.input("fullName")} label="Full Name" />
-<Input {...on.input("age")} type="number" label="Age" />
+```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([]),
+});
 ```
 
-### Nested Objects
+### Scalar Fields
 
-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.
+Top-level primitive fields. Use dot notation to reach into nested objects.
 
 ```tsx
-// Binds seamlessly to state.settings.theme
+<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>
-
-// Booleans map smoothly to Switches/Checkboxes
-<Switch {...on.input("settings.notifications")}>Enable Alerts</Switch>
 ```
 
-### Managing Arrays
-
-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.
+### Nested Objects
 
-**Binding UI to Items:**
-Combine the general array path and the item ID.
+Dot notation reaches arbitrarily deep. TypeScript validates that the path exists and has the correct type.
 
 ```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);
+<Switch {...on.switch("settings.notifications")}>
+  Enable Notifications
+</Switch>
+<Autocomplete {...on.autocomplete("settings.theme")} label="Theme" />
 ```
 
-**Using the `helpers` Library:**
-Extract `helpers` out of `useForm(...)` to manipulate array state securely.
+### 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
-const { helpers } = useForm(mySchema);
+{
+  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>;
+```
 
-// 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);
+## The `on` API — Component Bindings
 
-// Reorder items by ID
-helpers.moveById("users", fromId, toId);
-```
+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
 
-### Form Submission
+All methods support both **scalar/nested** paths and **array item** paths (composite `"array.field"` + `itemId`).
 
-There are two primary ways to submit, validate, and handle your logic, both fully type-safe.
+| Method                            | HeroUI Component    | Key props returned                              |
+| --------------------------------- | ------------------- | ----------------------------------------------- |
+| `on.input(path, [itemId])`        | `Input`, `Textarea` | `value: string`, `onValueChange(string)`        |
+| `on.numberInput(path, [itemId])`  | `NumberInput`       | `value: number`, `onValueChange(number)`        |
+| `on.select(path, [itemId])`       | `Select`            | `selectedKeys`, `onSelectionChange`             |
+| `on.autocomplete(path, [itemId])` | `Autocomplete`      | `selectedKey`, `onSelectionChange`              |
+| `on.checkbox(path, [itemId])`     | `Checkbox`          | `isSelected: boolean`, `onValueChange(boolean)` |
+| `on.switch(path, [itemId])`       | `Switch`            | `isSelected: boolean`, `onValueChange(boolean)` |
+| `on.radio(path, [itemId])`        | `RadioGroup`        | `value: string`, `onValueChange(string)`        |
 
-**1. The `ControlledForm` Wrapper (Recommended)**
+> **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.
 
-`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.
+### Examples
 
 ```tsx
-const { ControlledForm } = useForm(mySchema);
+{/* 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>
 
-return (
-  <ControlledForm onSubmit={(data, event) => console.log(data.fullName)}>
-    <Input {...on.input("fullName")} />
-    <Button type='submit'>Submit</Button>
-  </ControlledForm>
-);
+{/* 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>
 ```
 
-**2. The `onFormSubmit` Handler Wrapper**
+---
 
-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.
+## Manual Updates
 
-```tsx
-const { onFormSubmit, state } = useForm(mySchema);
+For updating state outside of a component (e.g. in an event handler, after an API call), use the manual functions returned by `useForm`.
 
-// 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);
-});
+| 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);
 
-// Used manually on form tags or button invocations
-<form onSubmit={submitHandler}>{/* inputs */}</form>;
+// 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" });
 ```
 
-**3. External Handler Definitions**
+> **`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.
 
-If you define your schemas inline inside `useForm( { ... } )` but want to extract your `submit` handler natively without destructing variables you aren't using:
+---
 
-```tsx
-export const MyForm = () => {
-  // 1. Schema is defined organically inline inside the component execution
-  const { ControlledForm } = useForm({
-    fullName: string().required(),
-  });
+## Array Helpers
 
-  // 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);
-  };
+Extracted from `helpers` on the `useForm` return value. Items in object arrays are tracked by ID (default field: `id`).
 
-  // 3. Destructure whatever you need right on your JSX render
-  return <ControlledForm onSubmit={handleSubmit}>...</ControlledForm>;
-};
-```
+| Method                                      | Description                                        |
+| ------------------------------------------- | -------------------------------------------------- |
+| `addItem(path, item, index?)`               | Adds an item to the end (or at `index`)            |
+| `removeItemByIndexByIndex(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);
 
-## API Reference
+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
+```
 
-### `useForm`
+### Custom Array Identifier
 
-Instantiates state and schema configurations.
+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 formApi = useForm(schema, options?);
+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`
+    },
+  },
+);
 ```
 
-#### Arguments
+**Every ID-based function picks this up automatically:**
 
-| Parameter     | Type                         | Description                                                                      |
-| :------------ | :--------------------------- | :------------------------------------------------------------------------------- |
-| **`schema`**  | `Record<string, ConfigType>` | Your form shape configuration containing `Yup` schemas or primitive constraints. |
-| **`options`** | `FormOptions`                | Configuration behaviors.                                                         |
+```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);
+```
 
-#### Options
+> 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.
 
-| 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"]`). |
+**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
+```
 
 ---
 
-### The `on` API
+## Form Submission
 
-`on` hooks dynamically assign value tracks, validity checks, error text extractions, and update invocations back to the controller.
+### Option 1: `ControlledForm` (recommended)
 
-| 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`.       |
+`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);
 
-### ControlledForm
+return (
+  <ControlledForm onSubmit={(data, event) => api.post("/submit", data)}>
+    <Input {...on.input("email")} label='Email' />
+    <Button type='submit'>Submit</Button>
+  </ControlledForm>
+);
+```
 
-A Drop-in `<Form />` equivalent handling submit event delegation natively linked to validation triggers internally.
+`data` is fully typed from your schema. No manual type annotations needed.
 
-| 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. |
+### Option 2: `onFormSubmit`
 
-_Notes: Spreads any traditional `<form>` properties to standard HeroUI mappings out of the box._
+For use with plain HTML `<form>` elements:
 
----
+```tsx
+const { onFormSubmit } = useForm(schema);
 
-### Array Helpers
+const handleSubmit = onFormSubmit((data, event) => {
+  api.post("/submit", data);
+});
 
-Array adjustments exported off the `helpers` map:
+return (
+  <form onSubmit={handleSubmit}>
+    <Input {...on.input("email")} label='Email' />
+    <button type='submit'>Submit</button>
+  </form>
+);
+```
+
+### Option 3: Inline handler with full type inference
+
+When the schema is defined inline inside `useForm`, extract the handler type from `ControlledForm`:
 
-| 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. |
+```tsx
+const { ControlledForm } = useForm({
+  email: string().required().default(""),
+});
+
+const handleSubmit: React.ComponentProps<typeof ControlledForm>["onSubmit"] = (
+  data,
+  event,
+) => {
+  // data.email is correctly typed as string — no schema re-declaration needed
+  console.log(data.email);
+};
+```
+
+---
+
+## 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                         |
 
 ---
 
-### Form Controls
+## Localization
+
+Validation error messages are automatically localized. The library reads a `LOCALE` cookie on initialization.
 
-Additional utilities available directly out of `useForm`:
+- **Supported**: `en` (English — default), `es` (Spanish)
+- **Setting the locale**:
+
+```ts
+document.cookie = "LOCALE=es; path=/; max-age=31536000";
+```
 
-| 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.                       |
+If no cookie is found, or the value is unrecognized, English is used.
 
 ---