@samline/forms 2.6.0 → 2.7.1

package/docs/css-styling.md

@@ -20,7 +20,9 @@ The attributes are added and removed on:
 - Every explicit call to [`validate`](api/validate.md), [`revalidate`](api/revalidate.md), [`setErrors`](api/set-errors.md), or [`clearErrors`](api/clear-errors.md).
 - DOM mutations detected by the controller’s `MutationObserver` (new fields, changed `name` / `type` attributes).
 
-The attributes are also removed everywhere when you call [`reset`](api/reset.md).
+[`reset`](api/reset.md) clears both attributes, then re-synchronizes visual state from native default values. As a result, reset controls with non-empty defaults regain `css-filled`, while `css-error` and `aria-invalid` remain cleared.
+
+Initial `css-filled` synchronization is independent of validation. With `autoValidate: false`, prefilled controls are styled on mount without running rules, setting `css-error`, or marking the form as validated.
 
 ---
 
@@ -177,6 +179,8 @@ emailErrorEl.hidden = !state.errors.email
 emailErrorEl.textContent = state.errors.email?.[0] ?? ''
 ```
 
+For fields validated with `each`, item-only failures add `css-error` and `aria-invalid="true"` only to the failing controls. Aggregate field rules and manual errors still mark every control with that name. The public error map remains field-based (`errors[field]: string[]`), so use the optional `element` / `index` in an `each` custom validator when an integration needs item identity.
+
 ---
 
 ## Common pitfalls

package/docs/getting-started.md

@@ -8,7 +8,7 @@ This page explains what `@samline/forms` is, how the controller is wired, and wh
 
 Use the main `@samline/forms` entrypoint for native HTML forms. The package also provides `@samline/forms/browser` as an ESM/CJS browser module and `@samline/forms/browser/global` as the global IIFE distribution.
 
-> Note: the latest version is `2.6.0` — see [Releases](https://github.com/samline/forms/releases) for the changelog.
+> Note: the latest version is `2.7.1` — see [Releases](https://github.com/samline/forms/releases) for the changelog.
 
 If you want a `<script>`-only setup without a bundler, see [docs/browser.md](browser.md).
 
@@ -34,7 +34,7 @@ const contact = form('contact-form')
   .setErrors({ email: ['Already in use'] })
 ```
 
-Methods that return data instead of the controller: [`getValue`](api/get-value.md), [`getField`](api/get-field.md), [`getData`](api/get-data.md), [`getState`](api/get-state.md), [`validate`](api/validate.md), [`revalidate`](api/revalidate.md). Methods that return an unsubscribe function: [`observe`](api/observe.md), [`subscribe`](api/subscribe.md).
+Methods that return data instead of the controller: [`getValue`](api/get-value.md), [`getField`](api/get-field.md), [`getData`](api/get-data.md), [`getState`](api/get-state.md), [`validate`](api/validate.md), [`revalidate`](api/revalidate.md). Methods that return an unsubscribe or unregister function: [`observe`](api/observe.md), [`subscribe`](api/subscribe.md), [`addCleanup`](api/add-cleanup.md).
 
 ---
 
@@ -43,10 +43,12 @@ Methods that return data instead of the controller: [`getValue`](api/get-value.m
 Once a controller is created, you can rely on the following behaviour:
 
 - **`css-filled` attribute** is added to a field when it has a non-empty value, and removed when it becomes empty. Override the attribute name with `options.attributes.filled`.
+- **Initial filled state is always synchronized.** Prefilled controls receive `css-filled` on mount even with `autoValidate: false`; this does not run validation or set `isValidated`.
 - **`css-error` attribute** is added to a field when it has at least one error (validation or manual), and removed when it has none. Override with `options.attributes.error`.
 - **Validation runs on every change** for any field that has rules configured under `options.validators` (gated by `autoValidate`, default `true`).
 - **Manual errors from [`setErrors`](api/set-errors.md) are cleared by default when the affected field changes.** Set `clearManualErrorsOnChange: false` to keep them.
 - **Submit handlers receive a real `FormData` instance** built from the live form, plus a plain-object mirror. Invalid submissions never reach your handler.
+- **Async submit handlers are tracked.** `getState().isSubmitting` stays true while any promise-returning `onSubmit` work is pending, including overlapping submissions, and returns to false after fulfillment or rejection.
 - **Dynamic fields are auto-discovered.** A `MutationObserver` watches the form subtree for `name` / `type` attribute changes or new fields, re-caches the field registry, and re-runs visual state and validation.
 
 ---
@@ -59,8 +61,8 @@ The recommended flow:
 2. **React** — register [`watch`](api/watch.md) / [`observe`](api/observe.md) callbacks for field-level reactions, and [`subscribe`](api/subscribe.md) for whole-form reactions.
 3. **Validate** — built-in validation runs automatically. Use [`validate`](api/validate.md) (or the alias [`revalidate`](api/revalidate.md)) to run it on demand.
 4. **Submit** — register [`onSubmit`](api/on-submit.md) handlers. Valid submissions are intercepted (default) or allowed to continue natively (`preventDefault: false`).
-5. **Reset** — call [`reset`](api/reset.md) to restore the native form, clear errors, and strip visual attributes.
-6. **Destroy** — call [`destroy`](api/destroy.md) to remove listeners, disconnect the `MutationObserver`, clear caches, and drop all subscribers.
+5. **Reset** — call [`reset`](api/reset.md) to restore native defaults, clear errors, and re-synchronize visual attributes.
+6. **Destroy** — register integration teardown with [`addCleanup`](api/add-cleanup.md), then call [`destroy`](api/destroy.md) to remove listeners, disconnect the `MutationObserver`, run cleanups in reverse registration order, clear caches, and drop all subscribers.
 
 ---
 
@@ -79,16 +81,17 @@ Use this as a quick lookup when you need to know what a method will touch.
 | [`revalidate`](api/revalidate.md) | same as [`validate`](api/validate.md) | no | no | no | re-synced |
 | [`setErrors`](api/set-errors.md) | re-syncs visual attributes for the targeted fields | no | yes | no | re-synced |
 | [`clearErrors`](api/clear-errors.md) | re-syncs visual attributes (all or for the listed fields) | no | yes | no | re-synced |
-| [`reset`](api/reset.md) | calls native `form.reset()`; strips attributes | no | yes | no | cleared |
+| [`reset`](api/reset.md) | calls native `form.reset()`; clears errors and re-syncs attributes from default values | no | yes | no | re-synced |
 | [`onSubmit`](api/on-submit.md) | none directly; submit handler is invoked on submit | n/a | n/a | n/a | n/a |
 | [`autoSubmit`](api/auto-submit.md) | schedules `form.requestSubmit()` (with optional debounce) | native submit | yes (config change) | enables the behaviour | unchanged |
 | [`disableAutoSubmit`](api/disable-auto-submit.md) | cancels any pending debounce timer | no | yes | disables | unchanged |
 | [`watch`](api/watch.md) / [`observe`](api/observe.md) | none directly; callback fires on changes | n/a | n/a | n/a | unchanged |
 | [`unwatch`](api/unwatch.md) | none | no | no | no | unchanged |
 | [`subscribe`](api/subscribe.md) | none; fires immediately with the current snapshot | no | n/a | n/a | unchanged |
+| [`addCleanup`](api/add-cleanup.md) | none until its callback runs during destroy | no | no | no | unchanged |
 | [`getData`](api/get-data.md) | no | no | no | no | unchanged |
 | [`getState`](api/get-state.md) | no | no | no | no | unchanged |
-| [`destroy`](api/destroy.md) | removes `css-filled` / `css-error` indirectly via listener teardown | no | no longer fires | disabled | unchanged |
+| [`destroy`](api/destroy.md) | removes listeners and runs registered cleanups; does not remove visual attributes itself | no | no longer fires | disabled | unchanged |
 
 > Native field `input` events are delegated. Controls outside the form that use `form="id"` are handled through a document-level delegated listener.
 
@@ -98,6 +101,7 @@ Use this as a quick lookup when you need to know what a method will touch.
 
 - Use [`watch`](api/watch.md) when you want a chainable, fire-and-forget reaction to a field. Use [`observe`](api/observe.md) when you need to clean up later — it returns an unsubscribe function.
 - Use [`subscribe`](api/subscribe.md) when a higher-level component (router, store, view layer) needs to react to the whole form state.
+- Use [`addCleanup`](api/add-cleanup.md) when third-party listeners, observers, subscriptions, or abort controllers should be released with the form controller.
 - Use [`getData()`](api/get-data.md) when you need both a plain object and a `FormData` instance.
 - Use [`setErrors`](api/set-errors.md) and [`clearErrors`](api/clear-errors.md) to drive visual feedback from server responses.
 - Pass `clearManualErrorsOnChange: false` only when manual errors should persist after the user edits a field.
@@ -184,11 +188,12 @@ profile.onSubmit(async (_element, _data, formData) => {
     method: 'POST',
     body: formData
   })
-  return response
+
+  if (!response.ok) throw new Error('Profile update failed')
 })
 ```
 
-When `preventDefault` is omitted, valid submissions are intercepted — the browser will not navigate. Invalid submissions are always intercepted, regardless of the flag.
+When `preventDefault` is omitted, valid submissions are intercepted — the browser will not navigate. Invalid submissions are always intercepted, regardless of the flag. Promise-returning handlers run concurrently and are reflected by `isSubmitting`; rejection settles that state but is not converted into a form error.
 
 ### Let the browser submit natively
 

package/docs/options.md

@@ -43,7 +43,7 @@ interface FormControllerOptions {
 | Option | Type | Default | Behaviour |
 | --- | --- | --- | --- |
 | `attributes` | `Partial<VisualAttributes>` | `{ filled: 'css-filled', error: 'css-error' }` | Override the names of the visual attributes applied to fields. |
-| `autoValidate` | `boolean` | `true` | Run validation on construction and on handled `input` events for fields that have rules. |
+| `autoValidate` | `boolean` | `true` | Run validation on construction and on handled `input` events for fields that have rules. Initial `css-filled` synchronization still runs when this is `false`. |
 | `autoSubmit` | `boolean \| AutoSubmitOptions` | `false` | Submit automatically after handled `input` events. Pass `{ debounce: ms }` to delay. |
 | `clearErrorsOnSubmit` | `boolean` | `true` | Clear all manual errors before submit validation runs. |
 | `clearManualErrorsOnChange` | `boolean` | `true` | Clear the manual error of a field when it changes. Set `false` to keep manual errors until you call [`clearErrors`](api/clear-errors.md). |
@@ -79,6 +79,8 @@ Set this to `false` if you want to validate manually (e.g. only on submit, or on
 form('wizard-form', { autoValidate: false }).validate(['step-1'])
 ```
 
+The initial visual-state pass is independent of validation. Prefilled controls receive `css-filled` on mount even when `autoValidate` is `false`, but no rules run and `isValidated` remains `false` until validation is requested.
+
 ---
 
 ## `autoSubmit`
@@ -150,6 +152,18 @@ form('signup-form', {
         value: 'password',
         message: 'Passwords do not match.'
       }
+    },
+    amount: {
+      required: true,
+      numeric: true,
+      min: 0,
+      max: 10000
+    },
+    'attendees[].email': {
+      each: {
+        required: true,
+        pattern: /^[^\s@]+@[^\s@]+\.[^\s@]+$/
+      }
     }
   }
 })
@@ -163,11 +177,20 @@ form('signup-form', {
 | `minLength` | `number \| { value: number; message?: string }` | Minimum string length (for checkbox groups, the minimum number of selected items). |
 | `maxLength` | `number \| { value: number; message?: string }` | Maximum string length (for checkbox groups, the maximum number of selected items). |
 | `pattern` | `RegExp \| { value: RegExp; message?: string }` | String must match the regular expression. Skipped when the field is empty. |
+| `numeric` | `boolean \| { value: boolean; message?: string }` | Non-empty value must be an ordinary signed decimal. |
+| `min` | `number \| { value: number; message?: string }` | Non-empty numeric value must be greater than or equal to the inclusive bound. |
+| `max` | `number \| { value: number; message?: string }` | Non-empty numeric value must be less than or equal to the inclusive bound. |
 | `sameAs` | `string \| { value: string; message?: string }` | Non-empty value must equal the named field. Changing the named field automatically revalidates this field. |
+| `dependsOn` | `string \| string[]` | Names fields whose changes should revalidate this field. Useful for custom cross-field validators; it does not itself add a validation error. |
+| `each` | `ValueValidationRules` | Applies value-level rules independently to every member/control in a collection. |
 | `validate` | `FieldValidator \| FieldValidator[]` | Custom validators. Return a string to push an error, or `null` / `undefined` / `true` to pass. Return `false` to push a generic `"Validation failed."` message. |
 
 Built-in rules accept either a plain value or a `{ value, message }` object. Use the object form when you want a custom error message per rule.
 
+`numeric`, `min`, and `max` trim surrounding whitespace and accept only ordinary signed decimal syntax, such as `12`, `-3.5`, `+4`, `.75`, or `10.`. They reject exponent notation, hexadecimal, `Infinity`, `NaN`, and formatted values containing separators. Empty values skip all three rules; add `required` when emptiness should fail. `min` and `max` are inclusive and also reject a non-numeric value even when `numeric` is omitted.
+
+Their default messages are `"Value must be a number."`, `"Minimum value is N."`, and `"Maximum value is N."` respectively.
+
 ### Matching fields with `sameAs`
 
 Declare `sameAs` on the field that owns the error, normally the confirmation field:
@@ -197,6 +220,50 @@ Important behavior:
 - Put the rule on the confirmation field only in most forms. Putting reciprocal rules on both fields is cycle-safe, but both fields will own and display the same mismatch error.
 - Dependency cycles do not recurse. The controller resolves the affected fields with a visited set and validates each field at most once per input event.
 
+### Custom cross-field dependencies with `dependsOn`
+
+Custom validators can read any value, but the controller cannot infer those reads. Declare each source with `dependsOn` so changing it revalidates the field that owns the custom validator:
+
+```ts
+form('shipping-form', {
+  validators: {
+    method: { required: true },
+    country: {
+      dependsOn: 'method',
+      validate: ({ value, values }) =>
+        values.method === 'domestic' && value !== 'US'
+          ? 'Domestic shipping requires a US address.'
+          : null
+    }
+  }
+})
+```
+
+Names are exact HTML field names. A string array declares multiple sources. Like `sameAs`, dependencies become reactive once validation is active, and transitive chains and cycles are deduplicated so each affected field runs at most once per input event. `dependsOn` is controller metadata only: the pure validation helpers evaluate the supplied snapshot without tracking changes.
+
+### Validate every collection member with `each`
+
+Use `each` for repeated controls, checkbox groups, or other fields whose value is a collection:
+
+```ts
+form('attendees-form', {
+  validators: {
+    'attendees[].email': {
+      minLength: { value: 1, message: 'Add at least one attendee.' },
+      each: {
+        required: true,
+        pattern: {
+          value: /^[^\s@]+@[^\s@]+\.[^\s@]+$/,
+          message: 'Enter a valid attendee email.'
+        }
+      }
+    }
+  }
+})
+```
+
+Rules outside `each` validate the aggregate value. Rules inside `each` validate members independently. In a bound controller, `css-error` and `aria-invalid="true"` are applied only to the controls whose `each` rules fail; an aggregate or manual field error still marks every control in the field. Public errors remain `Record<string, string[]>`: item messages are flattened under the field name in member order rather than exposing a nested error shape.
+
 ### Custom validators
 
 ```ts
@@ -215,7 +282,7 @@ form('checkout-form', {
 })
 ```
 
-The custom validator receives `{ field, value, values }` and runs after the built-in rules. See [`FieldValidationContext`](typescript.md#fieldvalidationcontext).
+The custom validator receives `{ field, value, values }` and runs after the built-in rules. During `each`, it also receives the optional concrete `element` and zero-based `index`. See [`FieldValidationContext`](typescript.md#fieldvalidationcontext).
 
 ---
 

package/docs/recipes.md

@@ -197,12 +197,8 @@ import { form } from '@samline/forms'
 const builder = form('builder', {
   validators: {
     'rows[].name': {
-      required: true,
-      validate: ({ value }) => {
-        const names = Array.isArray(value) ? value : [value]
-        return names.every(name => typeof name === 'string' && name.trim() !== '')
-          ? null
-          : 'Every row needs a name.'
+      each: {
+        required: { value: true, message: 'Every row needs a name.' }
       }
     }
   }
@@ -219,7 +215,7 @@ document.querySelector('#add')?.addEventListener('click', () => {
 })
 ```
 
-Validator keys match literal HTML names, not wildcard paths. Reusing `rows[].name` gives the validator an array once multiple rows exist. The form-subtree `MutationObserver` clears field lookups and, because the default controller is already validated, re-runs validation when each row is appended.
+Validator keys match literal HTML names, not wildcard paths. Reusing `rows[].name` gives the validator an array once multiple rows exist. `each` validates every row independently, so only an empty row receives `css-error` and `aria-invalid="true"`; `getState().errors['rows[].name']` remains a flat `string[]`. The form-subtree `MutationObserver` clears field lookups and, because the default controller is already validated, re-runs validation when each row is appended.
 
 ---
 
@@ -251,7 +247,7 @@ mount()
 
 ## 7. Manual-only validation
 
-When you want validation to run only when you ask (not on every change), disable `autoValidate` and call `validate()` yourself.
+When you want validation to run only when you ask (not on every change), disable `autoValidate` and call `validate()` yourself. Initial `css-filled` state still synchronizes for prefilled controls without running any rules.
 
 ```ts
 import { form } from '@samline/forms'
@@ -403,6 +399,7 @@ const shipping = form('shipping-form', {
   validators: {
     method: { required: true },
     country: {
+      dependsOn: 'method',
       validate: ({ value, values }) => {
         if (values.method === 'international' && value !== 'US') return null
         if (values.method === 'domestic' && value === 'US') return null
@@ -412,12 +409,11 @@ const shipping = form('shipping-form', {
   }
 })
 
-// Programmatic update still triggers the delegated event pipeline.
+// Programmatic update triggers the delegated pipeline and revalidates country.
 shipping.setValue('method', 'international')
-shipping.validate(['method', 'country'])
 ```
 
-Custom validators receive the full values map, so cross-field rules read like plain JavaScript.
+Custom validators receive the full values map, so cross-field rules read like plain JavaScript. `dependsOn` tells the controller that `country` must be revalidated whenever `method` changes; exact-name dependency chains and cycles are deduplicated.
 
 ---
 
@@ -465,10 +461,68 @@ Things to know:
 - If you authored your own `<input type="hidden" name="<field>">` (or `<input data-formatter-raw-for="<field>">`) before wiring the controller, `format()` reuses it instead of duplicating it. Pre-existing mirrors survive `destroy()`; mirrors created by `format()` are removed.
 - If you prefer to pre-author the visible with the display name (e.g. `<input name="phone_displayed" />`) instead of letting `format()` rename it, `format()` picks that up and skips the rename. Both authoring styles end up with the same DOM.
 - Use `formatAll({ type, field: ['a', 'b', 'c'], options })` to bind the same configuration to several fields in one call. Each field gets its own pair (`a` + `a_displayed`, `b` + `b_displayed`, `c` + `c_displayed`).
+- Date/time initial values and canonical mirror writes use the formatter's `auto` interpretation; live visible-input events and re-binds use `display`. This preserves server-prefilled raw values without misreading a full-length delimiter-less paste in the visible field. An explicit `options.interpretInputAs` always wins.
 - `@samline/formatter` is an **optional peer dependency** for module builds. When it is missing, the module instance logs one cached `console.error` and asynchronously restores affected fields so the rest of the form keeps working. The standalone global IIFE bundles formatter behavior.
 
 ---
 
+## 15. Validate numeric ranges
+
+```ts
+import { form } from '@samline/forms'
+
+const invoice = form('invoice-form', {
+  validators: {
+    amount: {
+      required: true,
+      numeric: { value: true, message: 'Enter an unformatted decimal amount.' },
+      min: { value: 0, message: 'Amount cannot be negative.' },
+      max: { value: 100000, message: 'Amount is above the limit.' }
+    }
+  }
+})
+```
+
+The bounds are inclusive. Ordinary signed decimals such as `-1`, `+2.5`, `.75`, and `10.` are accepted; exponent notation, hexadecimal, `Infinity`, `NaN`, and values containing formatting separators are rejected. Empty input skips numeric rules, so use `required` when it must fail.
+
+---
+
+## 16. Track async submission state
+
+```ts
+const profile = form('profile-form')
+
+profile.subscribe(state => {
+  saveButton.disabled = state.isSubmitting
+  saveButton.textContent = state.isSubmitting ? 'Saving...' : 'Save'
+})
+
+profile.onSubmit(async (_form, _data, formData) => {
+  await fetch('/api/profile', { method: 'POST', body: formData })
+})
+```
+
+Multiple async handlers start in registration order without awaiting one another. Overlapping submissions keep `isSubmitting` true until all tracked work settles. Rejections settle the state and are not converted into validation errors.
+
+---
+
+## 17. Tie third-party resources to controller cleanup
+
+```ts
+const checkout = form('checkout-form')
+const abortController = new AbortController()
+
+window.addEventListener('resize', updateCheckoutLayout, {
+  signal: abortController.signal
+})
+
+checkout.addCleanup(() => abortController.abort())
+```
+
+Active cleanups run once in reverse registration order on `destroy()`. The returned unregister function removes only its own registration, duplicate callback registrations remain independent, and a cleanup registered after destruction runs immediately.
+
+---
+
 ## Next steps
 
 - Need a full options reference? See [docs/options.md](options.md).

package/docs/typescript.md

@@ -16,6 +16,7 @@ import type {
   FormatType,
   FormController,
   FormControllerOptions,
+  FormCleanup,
   FormDataPrimitive,
   FormErrors,
   FormFieldElement,
@@ -34,6 +35,7 @@ import type {
   SerializedFormValue,
   ValidationResult,
   ValidationSchema,
+  ValueValidationRules,
   VisualAttributes
 } from '@samline/forms'
 ```
@@ -50,6 +52,7 @@ interface FormController {
   readonly f: HTMLFormElement | null
   readonly options: FormControllerOptions
   onSubmit: (callback: FormSubmitHandler, preventDefault?: boolean) => FormController
+  addCleanup: (cleanup: FormCleanup) => () => void
   watch: (field: string, callback: FormFieldWatcher) => FormController
   observe: (field: string, callback: FormFieldWatcher) => () => void
   unwatch: (field?: string, callback?: FormFieldWatcher) => FormController
@@ -182,7 +185,7 @@ form('booking-form', {
 })
 ```
 
-The controller can infer reactive dependencies from `sameAs`, but not from arbitrary reads inside `validate`. If `start_date` changes after `end_date` has been validated, explicitly revalidate `end_date` or watch the source field.
+The controller infers reactive dependencies from `sameAs`, but not from arbitrary reads inside `validate`. Add `dependsOn: 'start_date'` to the `end_date` rules when changes to the source should automatically revalidate the custom rule.
 
 ---
 
@@ -210,6 +213,7 @@ interface FormStateSnapshot {
   isValid: boolean
   isValidated: boolean
   autoSubmit: boolean
+  isSubmitting: boolean
   submitCount: number
 }
 ```
@@ -220,8 +224,9 @@ interface FormStateSnapshot {
 | `errors` | Merged validation and manual errors. |
 | `filledFields` | Names of fields that have a non-empty value. |
 | `isValid` | `true` when `errors` has no entries. |
-| `isValidated` | `true` once [`validate`](api/validate.md) has run at least once. |
+| `isValidated` | `true` after the initial auto-validation pass or once [`validate`](api/validate.md) has run. |
 | `autoSubmit` | `true` while auto-submit is enabled. |
+| `isSubmitting` | `true` while one or more valid submissions have asynchronous handlers that have not settled. |
 | `submitCount` | Number of submit attempts (valid or invalid). |
 
 ---
@@ -234,7 +239,7 @@ The callback passed to [`subscribe`](api/subscribe.md).
 type FormStateListener = (state: FormStateSnapshot) => void
 ```
 
-Receives the current snapshot immediately, then at controller notification points such as handled input, manual-error changes, reset, submit attempts, auto-submit toggles, and observed DOM mutations. A direct `validate()` call does not independently notify it.
+Receives the current snapshot immediately, then at controller notification points such as handled input, manual-error changes, reset, submit attempts, async-submit state transitions, auto-submit toggles, and observed DOM mutations. A direct `validate()` call does not independently notify it.
 
 ---
 
@@ -248,10 +253,10 @@ type FormSubmitHandler = (
   data: Record<string, SerializedFormValue>,
   formData: FormData,
   state: FormStateSnapshot
-) => void
+) => void | Promise<void>
 ```
 
-Only invoked when the form is valid. `data` and `formData` are produced fresh on each invocation.
+Only invoked when the form is valid. `data` and `formData` are produced fresh on each invocation. Returned promises are tracked by `FormStateSnapshot.isSubmitting`; fulfillment or rejection settles the tracked work.
 
 ---
 
@@ -345,20 +350,38 @@ form('signup-form', {
 The rule set for a single field.
 
 ```ts
-interface FieldValidationRules {
+interface FieldValidationRules extends ValueValidationRules {
+  sameAs?: RuleConfig<string>
+  dependsOn?: string | string[]
+  each?: ValueValidationRules
+}
+
+interface ValueValidationRules {
   required?: RuleConfig<boolean>
   minLength?: RuleConfig<number>
   maxLength?: RuleConfig<number>
   pattern?: RuleConfig<RegExp>
-  sameAs?: RuleConfig<string>
+  numeric?: RuleConfig<boolean>
+  min?: RuleConfig<number>
+  max?: RuleConfig<number>
   validate?: FieldValidator | FieldValidator[]
 }
 ```
 
-Rules run in the order: `required` → `minLength` → `maxLength` → `pattern` → `sameAs` → `validate`. All are optional; an empty rules object contributes nothing.
+Value rules run in the order: `required` → `minLength` → `maxLength` → `pattern` → numeric bounds → `validate`. Field-level `sameAs` and member-level `each` are then evaluated. All are optional; an empty rules object contributes nothing.
 
 `sameAs` names another exact field key. It compares non-empty strings exactly and arrays by ordered contents; file entries compare by `File` object identity. In a controller, changing the referenced field automatically revalidates the field that declares `sameAs`. Reciprocal declarations are cycle-safe, but usually duplicate the same error on both controls; prefer declaring the rule only on the confirmation field.
 
+`dependsOn` declares one or more exact source field names for controller revalidation. It is intended for custom validators that read `values`; it does not add an error or affect the pure helpers by itself. Dependency chains and cycles are traversed once per input event.
+
+`each` applies a `ValueValidationRules` object to every collection member independently. Controller validation can therefore mark only the failing DOM controls, while [`FormErrors`](#formerrors) remains a flat `Record<string, string[]>` with item messages collected under the field name.
+
+## `ValueValidationRules`
+
+The exported subset of rules that can validate one value, including each member of a collection. It excludes field-level `sameAs`, `dependsOn`, and nested `each`.
+
+`numeric`, `min`, and `max` skip empty values. Non-empty input must be a finite ordinary signed decimal: decimal integers and fractions are accepted, while exponent notation, hexadecimal, `Infinity`, `NaN`, and formatted separators are rejected. `min` and `max` are inclusive and imply numeric parsing even when `numeric` is omitted.
+
 ---
 
 ## `RuleConfig<T>`
@@ -395,9 +418,13 @@ interface FieldValidationContext {
   field: string
   value: FormFieldValue
   values: FormValues
+  element?: FormFieldElement
+  index?: number
 }
 ```
 
+`element` and `index` are populated while a bound controller evaluates an `each` member. `index` is zero-based. Pure helper validation has no DOM element, so `element` remains undefined; `index` is still provided for array members.
+
 Use it to write cross-field validators:
 
 ```ts
@@ -450,6 +477,18 @@ form('order-form', {
 
 ---
 
+## `FormCleanup`
+
+The callback accepted by [`addCleanup()`](api/add-cleanup.md).
+
+```ts
+type FormCleanup = () => void
+```
+
+Cleanups are synchronous and run once in reverse registration order during `destroy()`, unless their returned unregister function removes them first.
+
+---
+
 ## `AutoSubmitOptions`
 
 The argument to [`autoSubmit()`](api/auto-submit.md) and the `autoSubmit` option.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@samline/forms",
-  "version": "2.6.0",
+  "version": "2.7.1",
   "description": "TypeScript-first, framework-free form controller with validation, reactive state, serialization, auto-submit, and input formatting.",
   "keywords": [
     "forms",