@samline/forms 2.6.0 → 2.7.1

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { F as FormTarget, a as FormControllerOptions, b as FormController, S as SerializedFormResult, c as FormFieldValue, d as FieldValidationRules, e as FormValues, V as ValidationSchema, f as ValidationResult } from './registry-BpqJetAt.cjs';
-export { A as AppendContentOptions, g as AutoSubmitOptions, h as FieldFormatConfig, i as FieldFormatConfigMap, j as FieldValidationContext, k as FieldValidator, l as FormDataPrimitive, m as FormErrors, n as FormFieldElement, o as FormFieldWatcher, p as FormStateListener, q as FormStateSnapshot, r as FormSubmitHandler, s as FormatType, t as FormsApi, u as FormsAvailable, N as NewFormInput, R as RuleConfig, v as SerializedFormValue, w as VisualAttributes, x as browser } from './registry-BpqJetAt.cjs';
+import { F as FormTarget, a as FormControllerOptions, b as FormController, S as SerializedFormResult, c as FormFieldValue, d as FieldValidationRules, e as FormValues, V as ValidationSchema, f as ValidationResult } from './registry-GzopYPCR.cjs';
+export { A as AppendContentOptions, g as AutoSubmitOptions, h as FieldFormatConfig, i as FieldFormatConfigMap, j as FieldValidationContext, k as FieldValidator, l as FormCleanup, m as FormDataPrimitive, n as FormErrors, o as FormFieldElement, p as FormFieldWatcher, q as FormStateListener, r as FormStateSnapshot, s as FormSubmitHandler, t as FormatType, u as FormsApi, v as FormsAvailable, N as NewFormInput, R as RuleConfig, w as SerializedFormValue, x as ValueValidationRules, y as VisualAttributes, z as browser } from './registry-GzopYPCR.cjs';
 
 declare const form: (target: FormTarget, options?: FormControllerOptions) => FormController;
 

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { F as FormTarget, a as FormControllerOptions, b as FormController, S as SerializedFormResult, c as FormFieldValue, d as FieldValidationRules, e as FormValues, V as ValidationSchema, f as ValidationResult } from './registry-BpqJetAt.js';
-export { A as AppendContentOptions, g as AutoSubmitOptions, h as FieldFormatConfig, i as FieldFormatConfigMap, j as FieldValidationContext, k as FieldValidator, l as FormDataPrimitive, m as FormErrors, n as FormFieldElement, o as FormFieldWatcher, p as FormStateListener, q as FormStateSnapshot, r as FormSubmitHandler, s as FormatType, t as FormsApi, u as FormsAvailable, N as NewFormInput, R as RuleConfig, v as SerializedFormValue, w as VisualAttributes, x as browser } from './registry-BpqJetAt.js';
+import { F as FormTarget, a as FormControllerOptions, b as FormController, S as SerializedFormResult, c as FormFieldValue, d as FieldValidationRules, e as FormValues, V as ValidationSchema, f as ValidationResult } from './registry-GzopYPCR.js';
+export { A as AppendContentOptions, g as AutoSubmitOptions, h as FieldFormatConfig, i as FieldFormatConfigMap, j as FieldValidationContext, k as FieldValidator, l as FormCleanup, m as FormDataPrimitive, n as FormErrors, o as FormFieldElement, p as FormFieldWatcher, q as FormStateListener, r as FormStateSnapshot, s as FormSubmitHandler, t as FormatType, u as FormsApi, v as FormsAvailable, N as NewFormInput, R as RuleConfig, w as SerializedFormValue, x as ValueValidationRules, y as VisualAttributes, z as browser } from './registry-GzopYPCR.js';
 
 declare const form: (target: FormTarget, options?: FormControllerOptions) => FormController;
 

package/dist/index.js

@@ -5,7 +5,7 @@ import {
   parseFormData,
   validateFieldValue,
   validateValues
-} from "./chunk-L4GRKSQ5.js";
+} from "./chunk-MMHX34WB.js";
 export {
   browser,
   createFormController,

package/dist/{registry-BpqJetAt.d.cts → registry-GzopYPCR.d.cts}

@@ -30,16 +30,29 @@ interface FieldValidationContext {
     field: string;
     value: FormFieldValue;
     values: FormValues;
+    /** Concrete control while validating one member through `each`. */
+    element?: FormFieldElement;
+    /** Zero-based member position while validating through `each`. */
+    index?: number;
 }
 type FieldValidator = (context: FieldValidationContext) => string | undefined | null | false | true;
-interface FieldValidationRules {
+interface ValueValidationRules {
     required?: RuleConfig<boolean>;
     minLength?: RuleConfig<number>;
     maxLength?: RuleConfig<number>;
     pattern?: RuleConfig<RegExp>;
+    numeric?: RuleConfig<boolean>;
+    min?: RuleConfig<number>;
+    max?: RuleConfig<number>;
+    validate?: FieldValidator | FieldValidator[];
+}
+interface FieldValidationRules extends ValueValidationRules {
     /** Field name whose non-empty value must equal this field's value. */
     sameAs?: RuleConfig<string>;
-    validate?: FieldValidator | FieldValidator[];
+    /** Fields whose changes should revalidate this field. */
+    dependsOn?: string | string[];
+    /** Rules applied independently to each collection member. */
+    each?: ValueValidationRules;
 }
 type ValidationSchema = Record<string, FieldValidationRules>;
 interface VisualAttributes {
@@ -79,6 +92,7 @@ interface FormStateSnapshot {
     isValid: boolean;
     isValidated: boolean;
     autoSubmit: boolean;
+    isSubmitting: boolean;
     submitCount: number;
 }
 type FormStateListener = (state: FormStateSnapshot) => void;
@@ -93,12 +107,14 @@ interface AppendContentOptions {
     atStart?: boolean;
 }
 type FormFieldWatcher = (value: FormFieldValue, field: FormFieldElement | FormFieldElement[] | null, form: HTMLFormElement, state: FormStateSnapshot) => void;
-type FormSubmitHandler = (form: HTMLFormElement, data: Record<string, SerializedFormValue>, formData: FormData, state: FormStateSnapshot) => void;
+type FormSubmitHandler = (form: HTMLFormElement, data: Record<string, SerializedFormValue>, formData: FormData, state: FormStateSnapshot) => void | Promise<void>;
+type FormCleanup = () => void;
 interface FormController {
     readonly element: HTMLFormElement | null;
     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;
@@ -145,4 +161,4 @@ interface FormsApi {
 }
 declare const browser: FormsApi;
 
-export { type AppendContentOptions as A, type FormTarget as F, type NewFormInput as N, type RuleConfig as R, type SerializedFormResult as S, type ValidationSchema as V, type FormControllerOptions as a, type FormController as b, type FormFieldValue as c, type FieldValidationRules as d, type FormValues as e, type ValidationResult as f, type AutoSubmitOptions as g, type FieldFormatConfig as h, type FieldFormatConfigMap as i, type FieldValidationContext as j, type FieldValidator as k, type FormDataPrimitive as l, type FormErrors as m, type FormFieldElement as n, type FormFieldWatcher as o, type FormStateListener as p, type FormStateSnapshot as q, type FormSubmitHandler as r, type FormatType as s, type FormsApi as t, type FormsAvailable as u, type SerializedFormValue as v, type VisualAttributes as w, browser as x };
+export { type AppendContentOptions as A, type FormTarget as F, type NewFormInput as N, type RuleConfig as R, type SerializedFormResult as S, type ValidationSchema as V, type FormControllerOptions as a, type FormController as b, type FormFieldValue as c, type FieldValidationRules as d, type FormValues as e, type ValidationResult as f, type AutoSubmitOptions as g, type FieldFormatConfig as h, type FieldFormatConfigMap as i, type FieldValidationContext as j, type FieldValidator as k, type FormCleanup as l, type FormDataPrimitive as m, type FormErrors as n, type FormFieldElement as o, type FormFieldWatcher as p, type FormStateListener as q, type FormStateSnapshot as r, type FormSubmitHandler as s, type FormatType as t, type FormsApi as u, type FormsAvailable as v, type SerializedFormValue as w, type ValueValidationRules as x, type VisualAttributes as y, browser as z };

package/dist/{registry-BpqJetAt.d.ts → registry-GzopYPCR.d.ts}

@@ -30,16 +30,29 @@ interface FieldValidationContext {
     field: string;
     value: FormFieldValue;
     values: FormValues;
+    /** Concrete control while validating one member through `each`. */
+    element?: FormFieldElement;
+    /** Zero-based member position while validating through `each`. */
+    index?: number;
 }
 type FieldValidator = (context: FieldValidationContext) => string | undefined | null | false | true;
-interface FieldValidationRules {
+interface ValueValidationRules {
     required?: RuleConfig<boolean>;
     minLength?: RuleConfig<number>;
     maxLength?: RuleConfig<number>;
     pattern?: RuleConfig<RegExp>;
+    numeric?: RuleConfig<boolean>;
+    min?: RuleConfig<number>;
+    max?: RuleConfig<number>;
+    validate?: FieldValidator | FieldValidator[];
+}
+interface FieldValidationRules extends ValueValidationRules {
     /** Field name whose non-empty value must equal this field's value. */
     sameAs?: RuleConfig<string>;
-    validate?: FieldValidator | FieldValidator[];
+    /** Fields whose changes should revalidate this field. */
+    dependsOn?: string | string[];
+    /** Rules applied independently to each collection member. */
+    each?: ValueValidationRules;
 }
 type ValidationSchema = Record<string, FieldValidationRules>;
 interface VisualAttributes {
@@ -79,6 +92,7 @@ interface FormStateSnapshot {
     isValid: boolean;
     isValidated: boolean;
     autoSubmit: boolean;
+    isSubmitting: boolean;
     submitCount: number;
 }
 type FormStateListener = (state: FormStateSnapshot) => void;
@@ -93,12 +107,14 @@ interface AppendContentOptions {
     atStart?: boolean;
 }
 type FormFieldWatcher = (value: FormFieldValue, field: FormFieldElement | FormFieldElement[] | null, form: HTMLFormElement, state: FormStateSnapshot) => void;
-type FormSubmitHandler = (form: HTMLFormElement, data: Record<string, SerializedFormValue>, formData: FormData, state: FormStateSnapshot) => void;
+type FormSubmitHandler = (form: HTMLFormElement, data: Record<string, SerializedFormValue>, formData: FormData, state: FormStateSnapshot) => void | Promise<void>;
+type FormCleanup = () => void;
 interface FormController {
     readonly element: HTMLFormElement | null;
     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;
@@ -145,4 +161,4 @@ interface FormsApi {
 }
 declare const browser: FormsApi;
 
-export { type AppendContentOptions as A, type FormTarget as F, type NewFormInput as N, type RuleConfig as R, type SerializedFormResult as S, type ValidationSchema as V, type FormControllerOptions as a, type FormController as b, type FormFieldValue as c, type FieldValidationRules as d, type FormValues as e, type ValidationResult as f, type AutoSubmitOptions as g, type FieldFormatConfig as h, type FieldFormatConfigMap as i, type FieldValidationContext as j, type FieldValidator as k, type FormDataPrimitive as l, type FormErrors as m, type FormFieldElement as n, type FormFieldWatcher as o, type FormStateListener as p, type FormStateSnapshot as q, type FormSubmitHandler as r, type FormatType as s, type FormsApi as t, type FormsAvailable as u, type SerializedFormValue as v, type VisualAttributes as w, browser as x };
+export { type AppendContentOptions as A, type FormTarget as F, type NewFormInput as N, type RuleConfig as R, type SerializedFormResult as S, type ValidationSchema as V, type FormControllerOptions as a, type FormController as b, type FormFieldValue as c, type FieldValidationRules as d, type FormValues as e, type ValidationResult as f, type AutoSubmitOptions as g, type FieldFormatConfig as h, type FieldFormatConfigMap as i, type FieldValidationContext as j, type FieldValidator as k, type FormCleanup as l, type FormDataPrimitive as m, type FormErrors as n, type FormFieldElement as o, type FormFieldWatcher as p, type FormStateListener as q, type FormStateSnapshot as r, type FormSubmitHandler as s, type FormatType as t, type FormsApi as u, type FormsAvailable as v, type SerializedFormValue as w, type ValueValidationRules as x, type VisualAttributes as y, browser as z };

package/docs/api/add-cleanup.md

@@ -0,0 +1,52 @@
+# `addCleanup(cleanup)`
+
+Registers teardown work owned by the controller. The callback runs when [`destroy()`](destroy.md) tears the controller down, unless that registration is removed first.
+
+## Signature
+
+```ts
+addCleanup(cleanup: FormCleanup): () => void
+
+type FormCleanup = () => void
+```
+
+## Parameters
+
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `cleanup` | [`FormCleanup`](../typescript.md#formcleanup) | yes | Synchronous callback to run during controller destruction. |
+
+## Returns
+
+An unregister function. Calling it removes only that registration without running the cleanup. It is idempotent.
+
+## Behaviour
+
+- Active cleanups run once, in reverse registration order, when `destroy()` is first called.
+- Registering the same callback more than once creates independent registrations. Each active registration runs once.
+- A cleanup added after the controller is already destroyed runs immediately. Its returned unregister function is a no-op.
+- If a cleanup throws, `destroy()` logs `[forms] cleanup failed`, continues with the remaining callbacks, and completes teardown.
+- Calling `destroy()` again does not rerun cleanups.
+
+## Example
+
+```ts
+import { form } from '@samline/forms'
+
+const profile = form('profile-form')
+const abortController = new AbortController()
+
+const unregister = profile.addCleanup(() => abortController.abort())
+
+// Optional: keep the resource alive beyond this controller.
+unregister()
+
+profile.destroy()
+```
+
+This hook is useful for integration-owned event listeners, observers, subscriptions, abort controllers, and other resources that should share the form controller's lifetime.
+
+## Related
+
+- [`destroy`](destroy.md) — runs all active cleanup registrations.
+- [`observe`](observe.md) and [`subscribe`](subscribe.md) — return their own unsubscribe functions.

package/docs/api/destroy.md

@@ -1,6 +1,6 @@
 # `destroy()`
 
-Tears the controller down. Removes all DOM listeners, disconnects the `MutationObserver`, clears caches, drops subscribers and submit handlers, and resets internal state.
+Tears the controller down. Removes all DOM listeners, disconnects the `MutationObserver`, runs registered cleanups, clears caches, drops subscribers and submit handlers, and resets internal state.
 
 ## Signature
 
@@ -19,8 +19,10 @@ When invoked, the controller:
 - Removes every listener it added (`input`, `submit`, formatter listeners, and document delegation for external controls).
 - Cancels any pending auto-submit debounce timer.
 - Disconnects the form `MutationObserver`.
+- Runs active callbacks registered with [`addCleanup()`](add-cleanup.md) once in reverse registration order. A thrown cleanup is logged and does not stop the others.
 - Clears `watchedFields`, `subscribers`, `submitHandlers`, and `fieldCache`.
 - Resets manual and validation error maps.
+- Clears tracked async-submit state. Pending handler promises continue independently, but no completion notification is emitted after destruction.
 
 After `destroy()` the controller object still exists and its methods remain callable. Direct reads and writes can still inspect or mutate the bound DOM, but the removed controller listeners no longer react to resulting events.
 
@@ -53,13 +55,26 @@ window.addEventListener('beforeunload', () => {
 })
 ```
 
+### Own integration resources
+
+```ts
+const profile = form('profile-form')
+const observer = new ResizeObserver(() => updateLayout())
+
+if (profile.element) observer.observe(profile.element)
+profile.addCleanup(() => observer.disconnect())
+```
+
 ## Edge cases
 
 - **`destroy()` does not remove `css-filled` / `css-error` attributes** from fields. If you need that, call [`reset()`](reset.md) before destroy, or strip the attributes yourself.
 - **Subscribers and watchers stop receiving notifications immediately**, but their closures remain until you release them.
+- **Cleanup registrations are independent.** Registering the same callback twice runs it twice unless one registration's unregister function is called.
+- **Late cleanup registration runs immediately.** Calling `addCleanup()` after destruction executes the callback at once and returns a no-op unregister function.
 - **Reusing the controller reference after destroy is possible but usually misleading.** Reads still inspect the bound form and methods such as `setValue()` can still write fields, but watchers, subscribers, validation-on-input, and auto-submit no longer run.
 
 ## Related
 
 - [`reset`](reset.md) — restore form values without removing listeners.
 - [`form`](form.md) — bind a new controller.
+- [`addCleanup`](add-cleanup.md) — register controller-owned teardown work.

package/docs/api/form.md

@@ -69,8 +69,8 @@ On creation the controller:
 3. Wires delegated `input` and `submit` listeners, including controls associated through `form="id"`.
 4. Starts a `MutationObserver` on the form subtree to track dynamic fields.
 5. Optionally enables [`autoSubmit`](../api/auto-submit.md) when `options.autoSubmit` is truthy.
-6. Runs an initial validation pass if `autoValidate` is enabled.
-7. Notifies subscribers with the initial state.
+6. Synchronizes initial `css-filled` state for every tracked control, including when `autoValidate` is disabled.
+7. Runs an initial validation pass only if `autoValidate` is enabled.
 
 ## Examples
 
@@ -134,6 +134,7 @@ form(profileRef)
 - **The id is resolved once.** If the DOM element with that id is replaced, the controller keeps listening to the original element. Recreate the controller if you re-render the form.
 - **`null` / `undefined` targets** are accepted and produce an inert controller. The chainable methods still return the controller, so they are safe to call as no-ops.
 - **Reusing a target across multiple controllers** is supported but they each install their own listeners — call [`destroy()`](destroy.md) on the previous one to avoid duplicate work.
+- **`autoValidate: false` disables the initial rule pass, not visual initialization.** Prefilled fields still receive `css-filled`; no validation errors are produced and `isValidated` remains `false`.
 - **`createFormController` is also exported** as the lower-level factory; prefer `form` for ergonomic imports.
 
 ## `createFormController`
@@ -151,4 +152,5 @@ This is the factory used by `form()` and accepts the same arguments. It is expor
 
 - [`FormController`](../typescript.md#formcontroller) — the returned controller type.
 - [`destroy`](destroy.md) — tear the controller down.
+- [`addCleanup`](add-cleanup.md) — attach integration cleanup to the controller lifecycle.
 - [docs/options.md](../options.md) — every option in detail.

package/docs/api/format.md

@@ -81,11 +81,11 @@ When the visible field already carries a value at the moment `format()` first ru
 To bridge the two layers, the controller:
 
 - For the **initial pass** (and for input events whose source is the hidden mirror, e.g. a `setValue('field', raw)` that wrote the canonical raw), overrides the formatter call to use `interpretInputAs: 'auto'`. This handles the realistic `old()` re-render case where the server hands the visible the canonical raw.
-- For **live keystrokes** on the visible input, the formatter is invoked with the caller's `options` as-is — what the user typed is in display order, and the formatter's default (`'auto'` since v2.0.0) does the right thing.
-- For the **re-bind** path (a second `format()` call with new options for the same field), the formatter is also invoked with the caller's `options` as-is — the visible at that point is whatever the formatter previously produced, in display order.
+- For **live input events** on the visible field, the controller injects `interpretInputAs: 'display'` when the caller did not choose a mode. This keeps typing and full-length delimiter-less pastes in display order instead of leaving them ambiguous under the formatter's automatic heuristic.
+- For the **re-bind** path (a second `format()` call with new options for the same field), the controller also injects `'display'` by default because the current visible value is already in display order.
 - An **explicit `interpretInputAs`** in `options` is always respected, never overridden. Use `'display'` if you pre-render the visible in display order from the server, or `'raw'` if you want the legacy pre-1.2.0 round-trip semantics for the initial pass.
 
-This is transparent for the common case: a Blade re-render with `value="{{ old('birthday') }}"` carrying `"19901212"` repopulates the visible as `"12/12/1990"` without any extra wiring on the consumer side. The option is opt-in only when the consumer needs the inverse convention.
+This is transparent for the common case: a Blade re-render with `value="{{ old('birthday') }}"` carrying `"19901212"` repopulates the visible as `"12/12/1990"`, while pasting `"12121990"` into the visible field remains 12 December 1990. Set `interpretInputAs` explicitly only when your application needs a different convention.
 
 ## Pre-authoring the visible
 

package/docs/api/get-state.md

@@ -16,6 +16,7 @@ interface FormStateSnapshot {
   isValid: boolean
   isValidated: boolean
   autoSubmit: boolean
+  isSubmitting: boolean
   submitCount: number
 }
 ```
@@ -36,8 +37,9 @@ A [`FormStateSnapshot`](../typescript.md#formstatesnapshot). Every call returns
 | `errors` | Merged validation errors (from rules) and manual errors (from [`setErrors`](set-errors.md)). |
 | `filledFields` | Names of fields that have a non-empty value. |
 | `isValid` | `true` when `errors` has no entries. |
-| `isValidated` | `true` after [`validate`](validate.md) has run at least once. |
+| `isValidated` | `true` after the initial auto-validation pass or once [`validate`](validate.md) has run. |
 | `autoSubmit` | `true` while auto-submit is enabled. |
+| `isSubmitting` | `true` while at least one valid submission has asynchronous `onSubmit` work that has not settled. |
 | `submitCount` | Number of submit attempts (valid or invalid). |
 
 ## Examples
@@ -54,6 +56,7 @@ const state = profile.getState()
 console.log(state.values.email)
 console.log(state.errors)
 console.log(state.isValid)
+console.log(state.isSubmitting)
 ```
 
 ### Drive an accessible error message
@@ -82,12 +85,25 @@ profile.onSubmit((_form, _data, _formData, state) => {
 })
 ```
 
+### Disable a button during async submissions
+
+```ts
+profile.subscribe(state => {
+  submitButton.disabled = state.isSubmitting
+})
+
+profile.onSubmit(async (_form, _data, formData) => {
+  await fetch('/profile', { method: 'POST', body: formData })
+})
+```
+
 ## Edge cases
 
 - **`getState()` does not notify subscribers.** If you need a notification-driven view, use [`subscribe`](subscribe.md).
 - **`errors` is the merged map** (validation + manual). Use [`validate`](validate.md) if you need just the validation errors.
 - **`filledFields` reflects the value snapshot at the time of the call** — it is not stored between calls.
 - **`submitCount` increments on every submit**, valid or invalid. It does not reset on [`reset`](reset.md); it tracks the lifetime of the controller.
+- **`isSubmitting` tracks overlapping work.** It remains `true` until every currently pending async submission batch settles, including rejected promises. Synchronous handlers do not toggle it.
 
 ## Related
 

package/docs/api/index.md

@@ -8,6 +8,7 @@ Every public method and helper gets its own page. Use this index to navigate to
 - [`createFormController(target, options?)`](form.md#createformcontroller) — underlying controller factory.
 - [`browser`](../browser.md) — registry-oriented browser API and global build.
 - [`element`](element.md) — the bound form (`f` is an alias).
+- [`addCleanup(cleanup)`](add-cleanup.md) — register controller-owned teardown work.
 - [`destroy()`](destroy.md) — tear down listeners, observer, and caches.
 - [`reset()`](reset.md) — restore native form values and clear errors.
 

package/docs/api/on-submit.md

@@ -28,12 +28,13 @@ The submit pipeline runs in this order:
 
 1. If `clearErrorsOnSubmit` is `true` (default), manual errors are cleared.
 2. Validation runs for every field with rules. `isValidated` becomes `true`.
-3. If validation fails, the browser’s native submit is prevented, submit handlers are **not** invoked, `aria-invalid="true"` is synchronized, the first connected, enabled, non-hidden invalid field receives focus, `submitCount` is incremented, and subscribers are notified.
+3. If validation fails, the browser’s native submit is prevented, submit handlers are **not** invoked, `aria-invalid="true"` is synchronized, the first connected, enabled, non-hidden invalid control receives focus (including the first failing `each` member), `submitCount` is incremented, and subscribers are notified.
 4. If validation passes:
    - `submitCount` is incremented.
    - Subscribers are notified.
    - If at least one handler was registered with `preventDefault: true`, the native submit is prevented. Otherwise (all handlers `preventDefault: false`), the native submit proceeds.
-    - Every registered handler is invoked in registration order. When the event supplies a successful named submit button, its name/value is included in `data` and `formData`.
+   - Every registered handler is invoked in registration order. When the event supplies a successful named submit button, its name/value is included in `data` and `formData`.
+   - Promise-returning handlers are tracked concurrently. Subscribers receive `isSubmitting: true` while the batch is pending and another update when all promises in it have fulfilled or rejected.
 
 ## Examples
 
@@ -81,7 +82,10 @@ profile
 - **`data` is a plain object mirror of `FormData`.** Repeated names become arrays (e.g. `interests: ['design', 'code']`).
 - **Handlers do not receive errors as an argument.** If you need to inspect the validation result, read [`getState()`](get-state.md) or call [`validate()`](validate.md) from inside the handler.
 - **`onSubmit` cannot be removed** — there is no `offSubmit` API. If you need conditional submission, guard inside the handler or recreate the controller.
-- **The handler is invoked synchronously after the submit event.** If your handler returns a promise, the native submit is already prevented (when applicable) — the promise’s resolution does not gate the browser.
+- **Handlers may return `void` or `Promise<void>`.** Invocation still starts synchronously and native submit prevention is decided before promises settle; async resolution does not gate the browser.
+- **Handlers in one submission run concurrently.** The controller invokes them in registration order without awaiting between calls, then tracks all returned promises together.
+- **Rejected promises settle submission state.** They do not become form errors and are consumed by the controller's all-settled tracking, so `isSubmitting` returns to `false` when no other submission work remains.
+- **Overlapping submissions are tracked independently.** `isSubmitting` remains `true` until every pending submission batch has settled.
 
 ## Related
 

package/docs/api/reset.md

@@ -1,6 +1,6 @@
 # `reset()`
 
-Restores the form to its initial state: native field values reset, manual and validation errors cleared, visual attributes stripped, subscribers notified.
+Restores the form to its initial state: native field values reset, manual and validation errors cleared, visual attributes synchronized, subscribers notified.
 
 ## Signature
 
@@ -20,7 +20,7 @@ When invoked, the controller:
 2. Clears `state.manualErrors` and `state.validationErrors`.
 3. Restores matching visible/raw defaults for formatted fields.
 4. Removes every `css-filled`, `css-error`, and `aria-invalid` attribute from associated fields.
-5. Re-syncs visual state if the form has been validated (`isValidated` is `true`).
+5. Re-syncs visual state. Controls whose native default value is non-empty regain `css-filled`, even when `autoValidate` is `false`; errors and `aria-invalid` stay cleared.
 6. Notifies subscribers.
 
 ## Examples
@@ -53,6 +53,7 @@ document.querySelector('#cancel')?.addEventListener('click', () => {
 - **Native `reset()` does not dispatch `input` events** for fields whose value changes because of the reset. The controller restores formatted mirrors and visual/ARIA state explicitly.
 - **Submit handlers are not invoked.** `reset()` is purely a UI / state operation.
 - **The `submitCount` from [`getState()`](get-state.md) is not reset.** It tracks the lifetime of the controller, not the lifetime of a single form session.
+- **Pending async submit work is not cancelled.** `isSubmitting` remains true until the outstanding `onSubmit` promises settle.
 
 ## Related
 

package/docs/api/revalidate.md

@@ -21,6 +21,8 @@ Same as [`validate`](validate.md) — a [`ValidationResult`](../typescript.md#va
 
 Identical to [`validate`](validate.md). The two methods share the same internal implementation.
 
+This includes strict decimal `numeric` / inclusive `min` / `max` rules, per-member `each` validation and element-level error styling. Explicit field lists are not expanded through `sameAs` or `dependsOn`; those relationships drive revalidation after input events.
+
 ## When to use which
 
 Use `validate` when you are running validation as part of an initial check. Use `revalidate` when you are explicitly asking the controller to recompute validation after a state change (e.g. after `setErrors`, after async data loads, after resetting partial form state).
@@ -47,4 +49,4 @@ profile.revalidate(['email'])
 
 ## Related
 
-- [`validate`](validate.md) — same implementation, different name.
+- [`validate`](validate.md) — same implementation, different name.

package/docs/api/subscribe.md

@@ -32,6 +32,7 @@ State mutations that fire subscribers include:
 - [`autoSubmit`](auto-submit.md) and [`disableAutoSubmit`](disable-auto-submit.md).
 - [`reset`](reset.md).
 - Submit attempts, after their validation pass and `submitCount` update.
+- Async submit state transitions: once when promise-returning handlers make `isSubmitting` true, and again after their submission batch settles. Overlapping batches keep it true until all settle.
 - `MutationObserver`-detected DOM changes.
 
 Direct [`validate`](validate.md) and [`revalidate`](revalidate.md) calls update validation state and visual attributes but do not independently notify subscribers. Use their returned result when synchronous rendering is required.
@@ -78,6 +79,21 @@ profile.subscribe(state => {
 })
 ```
 
+### Track asynchronous submission
+
+```ts
+const profile = form('profile-form')
+
+profile.subscribe(state => {
+  submitButton.disabled = state.isSubmitting
+  submitButton.textContent = state.isSubmitting ? 'Saving...' : 'Save'
+})
+
+profile.onSubmit(async (_form, _data, formData) => {
+  await fetch('/profile', { method: 'POST', body: formData })
+})
+```
+
 ## Edge cases
 
 - **The listener is invoked with a fresh snapshot** on every fire — it is safe to store the reference for the duration of one call.

package/docs/api/validate-field-value.md

@@ -34,8 +34,10 @@ Runs each rule in order:
 2. `minLength` — string length (or array length) must be ≥ the threshold.
 3. `maxLength` — string length (or array length) must be ≤ the threshold.
 4. `pattern` — the string form of the value must match the regex (skipped when the value is empty).
-5. `sameAs` — the value must equal the named value (skipped until both values are non-empty).
-6. `validate` — each custom validator runs in registration order. Returning a string pushes an error; returning `false` pushes `"Validation failed."`; returning `null`, `undefined`, or `true` is treated as a pass.
+5. `numeric`, `min`, and `max` — non-empty values must be strict decimals and satisfy the inclusive bounds.
+6. `validate` — each field-level custom validator runs in registration order. Returning a string pushes an error; returning `false` pushes `"Validation failed."`; returning `null`, `undefined`, or `true` is treated as a pass.
+7. `sameAs` — the aggregate value must equal the named value (skipped until both values are non-empty).
+8. `each` — the value-level rules run independently for every collection member, including any member-level custom validators.
 
 Default error messages are produced when the rule was configured without an explicit `message`. Custom messages come from the `{ value, message }` form of `RuleConfig`.
 
@@ -93,14 +95,48 @@ const errors = validateFieldValue(
 console.log(errors) // ['Use at least 8 characters.']
 ```
 
+### Validate strict decimal values and bounds
+
+```ts
+const errors = validateFieldValue(
+  'amount',
+  '100.25',
+  { numeric: true, min: 0, max: 500 },
+  { amount: '100.25' }
+)
+
+console.log(errors) // []
+```
+
+### Validate every collection member
+
+```ts
+const errors = validateFieldValue(
+  'emails',
+  ['valid@example.com', 'invalid'],
+  {
+    each: {
+      required: true,
+      pattern: /^[^\s@]+@[^\s@]+\.[^\s@]+$/
+    }
+  },
+  { emails: ['valid@example.com', 'invalid'] }
+)
+
+console.log(errors) // ['Value does not match the required pattern.']
+```
+
 ## Edge cases
 
 - **The pattern rule is skipped for empty values.** This is the standard “required + pattern” pattern: required runs first, then pattern runs only when there is a value.
+- **Numeric rules are skipped for empty values.** Use `required` as well when the field is mandatory.
+- **Numeric parsing is strict.** Surrounding whitespace is trimmed, and ordinary signed decimals such as `-2`, `+3.5`, `.5`, and `10.` are accepted. Exponents, hexadecimal, `Infinity`, `NaN`, and formatted separators are rejected. `min` and `max` are inclusive and also enforce numeric input when `numeric` is omitted.
 - **The `sameAs` rule is skipped until both values are non-empty.** Add `required` to each mandatory field; `sameAs` does not imply requiredness.
-- **Pure validation does not track dependencies.** `validateFieldValue` compares the supplied values once. Automatic dependent revalidation is controller behavior.
+- **Pure validation does not track dependencies.** `dependsOn` is controller metadata and has no effect here; `validateFieldValue` evaluates the supplied values once.
 - **`validateFieldValue` does not read from any DOM.** Pass everything in as arguments.
 - **`validate` runs after the built-in rules.** It receives the full context, including the current value and the other field values.
 - **Multiple custom validators** can be passed as an array — they all run, and any error from any of them is collected.
+- **`each` keeps the public return type flat.** Member errors are appended to the returned `string[]` in member order. Member custom validators receive a zero-based `index`; `element` is unavailable in this DOM-free helper.
 
 ## Related
 

package/docs/api/validate-values.md

@@ -38,7 +38,7 @@ A [`ValidationResult`](../typescript.md#validationresult):
 
 ## Behaviour
 
-For each `[field, rules]` entry in the schema, runs [`validateFieldValue`](validate-field-value.md) against `values[field]`. The other values are available to `sameAs` and custom validators.
+For each `[field, rules]` entry in the schema, runs [`validateFieldValue`](validate-field-value.md) against `values[field]`. The other values are available to `sameAs` and custom validators. Aggregate rules and `each` member rules are collected into the same `string[]` for that field.
 
 ## Examples
 
@@ -92,6 +92,9 @@ if (!result.isValid) {
 - **`validateValues` does not know which fields are “tracked”.** It validates every entry in the schema, even fields that are not present in `values`. An undefined value fails `required` but passes the rest.
 - **Errors are always a fresh object.** Safe to mutate.
 - **`sameAs` compares the provided snapshot only.** Dependency tracking and automatic revalidation belong to a form controller, not this pure helper.
+- **`dependsOn` has no effect in this helper.** It describes controller revalidation triggers, not a validation rule.
+- **`each` errors stay flat.** Member messages are appended under the field's existing `FormErrors` key in member order; no nested error shape is introduced.
+- **Numeric rules use strict decimal syntax and inclusive bounds.** Empty values skip `numeric`, `min`, and `max`; use `required` to reject emptiness.
 - **Custom validators receive the full values map**, so cross-field rules work the same as inside a controller.
 
 ## Related

package/docs/api/validate.md

@@ -33,7 +33,8 @@ A [`ValidationResult`](../typescript.md#validationresult):
 
 - Marks the form as validated (`state.isValidated = true`). This means future field changes will run validation again, even when the controller was created with `autoValidate: false`.
 - Re-syncs visual attributes (`css-filled` / `css-error`) for the affected fields.
-- After the form is validated, an input event also revalidates fields whose `sameAs` rule references the changed field. Cycles are deduplicated and each affected field runs once.
+- After the form is validated, an input event also revalidates fields whose `sameAs` or `dependsOn` metadata references the changed field. Transitive chains and cycles are deduplicated and each affected field runs once.
+- `each` validates every collection member independently. Item-only failures apply `css-error` and `aria-invalid="true"` only to the failing DOM controls, while the public `errors[field]` remains a flat `string[]`.
 - Subscribers are not notified — this method is a pure read of the rule engine. To run validation and notify subscribers, use [`subscribe`](subscribe.md) and read [`getState()`](get-state.md).
 
 ## Examples
@@ -88,8 +89,9 @@ function nextStep(step: 1 | 2) {
 
 - **`validate` ignores manual errors** during computation, but the returned `errors` includes them (merged with validation errors). The `isValid` flag reflects the merged map.
 - **Validation rules must be configured** via `options.validators`. Fields without rules are always considered valid.
-- **An explicit partial call validates exactly the requested fields.** `validate(['password'])` does not expand `sameAs` dependencies; dependency expansion happens for input events, including those dispatched by `setValue()`.
-- **Custom validators receive `{ field, value, values }`** — see [`FieldValidationContext`](../typescript.md#fieldvalidationcontext).
+- **An explicit partial call validates exactly the requested fields.** `validate(['password'])` does not expand `sameAs` / `dependsOn` relationships; dependency expansion happens for input events, including those dispatched by `setValue()`.
+- **Custom validators receive `{ field, value, values }`.** During `each`, the context also includes the concrete `element` and zero-based `index` — see [`FieldValidationContext`](../typescript.md#fieldvalidationcontext).
+- **Numeric rules are strict and bounds are inclusive.** Empty values skip `numeric`, `min`, and `max`; add `required` when needed.
 - **A custom validator that returns `false` pushes the generic message `"Validation failed."`.**
 - **`validate()` is the same as calling [`revalidate()`](revalidate.md)`** — they are aliases for readability.
 

package/docs/browser.md

@@ -11,10 +11,10 @@ For every other case (modern apps, bundlers, TypeScript projects), use the main
 ## Script tag
 
 ```html
-<script src="https://unpkg.com/@samline/forms@2.6.0/dist/browser/global.global.js"></script>
+<script src="https://unpkg.com/@samline/forms@2.7.1/dist/browser/global.global.js"></script>
 ```
 
-> Pin the version in production. Replace `2.6.0` with the version you ship.
+> Pin the version in production. Replace `2.7.1` with the version you ship.
 
 The bundle is a single IIFE that registers a global object.
 
@@ -49,7 +49,7 @@ The factory returns a `FormController` with the same signatures, semantics, and
   <button type="submit">Send</button>
 </form>
 
-<script src="https://unpkg.com/@samline/forms@2.6.0/dist/browser/global.global.js"></script>
+<script src="https://unpkg.com/@samline/forms@2.7.1/dist/browser/global.global.js"></script>
 <script>
   const contactForm = window.Forms.newForm({
     id: 'contact-form',
@@ -102,7 +102,7 @@ The browser bundle ships only the registry helpers plus the `form` factory. Ever
 
 The controller returned by `form` / `newForm` exposes the methods documented under [docs/api/](api/index.md):
 
-- Lifecycle: [`element`](api/element.md), [`reset`](api/reset.md), [`destroy`](api/destroy.md).
+- Lifecycle: [`element`](api/element.md), [`addCleanup`](api/add-cleanup.md), [`reset`](api/reset.md), [`destroy`](api/destroy.md).
 - Submission: [`onSubmit`](api/on-submit.md), [`autoSubmit`](api/auto-submit.md), [`disableAutoSubmit`](api/disable-auto-submit.md).
 - Field observation: [`watch`](api/watch.md), [`observe`](api/observe.md), [`unwatch`](api/unwatch.md), [`subscribe`](api/subscribe.md).
 - Field values: [`setValue`](api/set-value.md), [`getValue`](api/get-value.md), [`getField`](api/get-field.md), [`prefill`](api/prefill.md).
@@ -126,7 +126,7 @@ window.Forms.destroyForm('contact-form')
 
 ## Common pitfalls
 
-- **Pin the version.** The CDN URL above is `2.6.0`. Replace it whenever you upgrade.
+- **Pin the version.** The CDN URL above is `2.7.1`. Replace it whenever you upgrade.
 - **The script must be loaded before any code that uses `window.Forms`.** Place the `<script>` tag in `<head>` with `defer`, or before the user script in `<body>`.
 - **No bundler means no tree-shaking.** The global browser bundle includes the controller and formatter peer. Inspect the published artifact when bundle size is a constraint.
 - **CSP:** if your site uses a strict Content Security Policy, allow `unpkg.com` in `script-src` (or self-host the file).