@samline/forms 2.7.2 → 2.8.0

package/docs/api/index.md

@@ -1,55 +0,0 @@
-# API Reference
-
-Every public method and helper gets its own page. Use this index to navigate to the right one.
-
-## Lifecycle
-
-- [`form(target, options?)`](form.md) — bind a controller to an `HTMLFormElement`.
-- [`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.
-
-## Submission
-
-- [`onSubmit(callback, preventDefault?)`](on-submit.md) — register a submit handler.
-- [`autoSubmit(options?)`](auto-submit.md) — enable submit-on-change with optional debounce.
-- [`disableAutoSubmit()`](disable-auto-submit.md) — turn auto-submit off and cancel pending debounce.
-
-## Field observation
-
-- [`watch(field, callback)`](watch.md) — chainable fire-and-forget reaction to a field.
-- [`observe(field, callback)`](observe.md) — like `watch`, but returns an unsubscribe function and fires immediately.
-- [`unwatch(field?, callback?)`](unwatch.md) — remove watched callbacks.
-- [`subscribe(listener)`](subscribe.md) — react to the entire form state.
-
-## Field values
-
-- [`setValue(name, value)`](set-value.md) — write a value into a field.
-- [`getValue(name)`](get-value.md) — read the current value of a field.
-- [`getField(name)`](get-field.md) — read the underlying DOM element(s).
-- [`prefill(fieldName?)`](prefill.md) — populate the form from `window.location.search`.
-- [`format(config)`](format.md) — apply `@samline/formatter` to a field, with auto-managed raw mirror and cursor tracking. The visible is renamed to `<field>_displayed` and a hidden `<field>` raw mirror is created. Both names are first-class in the controller's API.
-- [`formatAll(config)`](format.md) — alias of `format()` for `field: string[]` use cases.
-
-## Validation
-
-- [`validate(fields?)`](validate.md) — run validation, return the result.
-- [`revalidate(fields?)`](revalidate.md) — alias of `validate` with explicit intent.
-- [`setErrors(fields)`](set-errors.md) — push manual errors.
-- [`clearErrors(fields?)`](clear-errors.md) — clear manual errors.
-
-## State and data
-
-- [`getData()`](get-data.md) — return plain object + `FormData` for the form.
-- [`getState()`](get-state.md) — return a snapshot of values, errors, and metadata.
-- [`append(options)`](append.md) — inject a DOM node into the form.
-
-## Pure helpers
-
-- [`parseFormData(formElement, submitter?)`](parse-form-data.md) — same serializer used internally, no controller needed.
-- [`validateValues(values, schema)`](validate-values.md) — run a schema against a values map.
-- [`validateFieldValue(field, value, rules, values)`](validate-field-value.md) — run a rule set against a single value.
-- [`regex`](regex.md) — named regular expressions and default error messages exported by the optional peer [`@samline/formatter`](https://github.com/samline/formatter), not by `@samline/forms`.

package/docs/api/observe.md

@@ -1,126 +0,0 @@
-# `observe(field, callback)`
-
-Registers a callback that fires immediately with the current value and on every subsequent change. Returns an unsubscribe function.
-
-## Signature
-
-```ts
-observe(
-  field: string,
-  callback: FormFieldWatcher
-): () => void
-```
-
-## Parameters
-
-| Name | Type | Required | Description |
-| --- | --- | --- | --- |
-| `field` | `string` | yes | The `name` attribute of the field to observe. |
-| `callback` | [`FormFieldWatcher`](../typescript.md#formfieldwatcher) | yes | Invoked with `(value, field, form, state)`. Fires immediately with the current value, then on every change. `field` is the observed DOM element(s) (same shape as [`getField`](../typescript.md#formfieldelement--formfieldelement--null) returns). |
-
-## Returns
-
-A function. Calling it removes the observer for this field.
-
-## Behaviour
-
-- On registration, the callback is invoked once synchronously with the current value, the bound form, and a state snapshot.
-- Subsequent user `input` events and programmatic [`setValue`](set-value.md) calls invoke the callback again. DOM mutations alone do not fire field watchers.
-- A field can have multiple observers.
-- The unsubscribe function is idempotent — calling it more than once is safe.
-
-## Examples
-
-### Observe and unsubscribe later
-
-```ts
-import { form } from '@samline/forms'
-
-const profile = form('profile-form')
-
-const stop = profile.observe('email', value => {
-  console.log('email is now:', value)
-})
-
-// Later, when the form is unmounted:
-stop()
-```
-
-### Sync a derived model
-
-```ts
-import { form } from '@samline/forms'
-
-const checkout = form('checkout-form')
-
-const unsubscribe = checkout.observe('shippingMethod', (value, field, _form, state) => {
-  const total = computeTotal(state.values)
-  document.querySelector('#total')!.textContent = String(total)
-  if (field && 'name' in field) {
-    console.log(`updated ${field.name} ->`, value)
-  }
-})
-
-window.addEventListener('beforeunload', unsubscribe)
-```
-
-### Share a handler across fields
-
-```ts
-import { form } from '@samline/forms'
-
-const signup = form('signup-form')
-
-const track = (value: unknown, field: HTMLInputElement | HTMLInputElement[] | null) => {
-  const name = field && 'name' in field ? field.name : null
-  analytics.track('signup_field_changed', { field: name, value })
-}
-
-const offEmail = signup.observe('email', track)
-const offPassword = signup.observe('password', track)
-
-// Later, on teardown:
-offEmail()
-offPassword()
-```
-
-### Manipulate the watched element directly
-
-```ts
-import { form } from '@samline/forms'
-
-const profile = form('profile-form')
-
-const stop = profile.observe('avatar', (_value, field) => {
-  if (field instanceof HTMLInputElement) {
-    field.setAttribute('data-touched', 'true')
-  }
-})
-```
-
-### Multiple observers on the same field
-
-```ts
-import { form } from '@samline/forms'
-
-const signup = form('signup-form')
-
-const offA = signup.observe('password', value => updateStrength(value))
-const offB = signup.observe('password', value => updateCapsLockWarning(value))
-
-// Remove only the strength meter.
-offA()
-```
-
-## Edge cases
-
-- **The initial fire happens synchronously inside `observe`**. If you do not want this, use [`watch`](watch.md) instead.
-- **Observers persist across calls to [`reset`](reset.md) and [`setValue`](set-value.md)** — they are not affected by state changes.
-- **The unsubscribe function only removes this specific callback.** Other observers on the same field continue to fire.
-
-## Related
-
-- [`watch`](watch.md) — chainable, no unsubscribe.
-- [`unwatch`](unwatch.md) — bulk removal of watchers.
-- [`subscribe`](subscribe.md) — global state observer.
-- [`format`](format.md) — when a field is formatted, `observe('<field>', cb)` fires with the raw value and `observe('<field>_displayed', cb)` fires with the formatted value. Both fire on the same keystroke. See [the mirror convention](format.md#the-mirror-convention).

package/docs/api/on-submit.md

@@ -1,94 +0,0 @@
-# `onSubmit(callback, preventDefault?)`
-
-Registers a handler that runs when the form is submitted and validation passes. Multiple handlers can be registered; each runs in registration order.
-
-## Signature
-
-```ts
-onSubmit(
-  callback: FormSubmitHandler,
-  preventDefault?: boolean
-): FormController
-```
-
-## Parameters
-
-| Name | Type | Required | Default | Description |
-| --- | --- | --- | --- | --- |
-| `callback` | [`FormSubmitHandler`](../typescript.md#formsubmithandler) | yes | — | Handler invoked when the form is valid. Receives `(form, data, formData, state)`. |
-| `preventDefault` | `boolean` | no | `true` | Whether to intercept valid submissions. Invalid submissions are always intercepted. |
-
-## Returns
-
-The same [`FormController`](../typescript.md#formcontroller) — chainable.
-
-## Behaviour
-
-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 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`.
-   - 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
-
-### Default: intercept and send with `fetch`
-
-```ts
-import { form } from '@samline/forms'
-
-const profile = form('profile-form')
-
-profile.onSubmit(async (_element, _data, formData) => {
-  await fetch('/profile', { method: 'POST', body: formData })
-})
-```
-
-### Pass `false` to allow native submit
-
-```ts
-import { form } from '@samline/forms'
-
-const bladeForm = form('blade-form', {
-  validators: { email: { required: true } }
-})
-
-bladeForm.onSubmit(() => {
-  console.log('client-side hooks ran')
-}, false)
-```
-
-Use this when you want the browser to perform the native submit (Blade, ERB, classic Rails, etc.) but still run a client-side hook first.
-
-### Multiple handlers
-
-```ts
-profile
-  .onSubmit((_form, data) => analytics.track('signup', data))
-  .onSubmit(async (_form, _data, formData) => {
-    await fetch('/signup', { method: 'POST', body: formData })
-  })
-```
-
-## Edge cases
-
-- **Handlers receive a fresh `FormData`** built from the live form on each invocation. Do not cache it.
-- **`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.
-- **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
-
-- [`autoSubmit`](auto-submit.md) — submit on every change.
-- [`validate`](validate.md) — run validation without submitting.
-- [`getData`](get-data.md) — what the handler receives.

package/docs/api/parse-form-data.md

@@ -1,94 +0,0 @@
-# `parseFormData(formElement, submitter?)`
-
-Pure serializer. Returns a plain object mirror of the form plus a fresh `FormData` instance. Does not require a controller — useful for one-off serialization (e.g. server-side hydration, scripts that read forms outside of a binding).
-
-## Signature
-
-```ts
-function parseFormData(
-  formElement: HTMLFormElement,
-  submitter?: HTMLElement | null
-): SerializedFormResult
-```
-
-```ts
-interface SerializedFormResult {
-  data: Record<string, SerializedFormValue>
-  formData: FormData
-}
-
-type SerializedFormValue = FormDataPrimitive | FormDataPrimitive[]
-type FormDataPrimitive = FormDataEntryValue // string | File
-```
-
-## Parameters
-
-| Name | Type | Required | Description |
-| --- | --- | --- | --- |
-| `formElement` | `HTMLFormElement` | yes | The form to serialize. |
-| `submitter` | `HTMLElement \| null` | no | Successful named submit button whose contribution should be included. |
-
-## Returns
-
-A [`SerializedFormResult`](../typescript.md#serializedformresult) with two fresh values:
-
-- `data` — plain object mirror. Repeated names become arrays.
-- `formData` — a fresh `FormData` instance.
-
-## Behaviour
-
-- Reads directly from the live DOM via `new FormData(formElement, submitter)` when a submitter is supplied.
-- Preserves fields named `constructor` or `__proto__` as ordinary own properties in `data`.
-- Drops entries where the value is an empty `File` (`size === 0` and `name === ''`).
-- Builds the `data` mirror while iterating, grouping repeated names into arrays.
-- Does not mutate the form or any global state.
-
-## Examples
-
-### One-off serialization
-
-```ts
-import { parseFormData } from '@samline/forms'
-
-const formElement = document.querySelector<HTMLFormElement>('#contact-form')
-if (formElement) {
-  const { data, formData } = parseFormData(formElement)
-  console.log(data, formData)
-}
-```
-
-### Hydrate from a snapshot
-
-```ts
-import { parseFormData } from '@samline/forms'
-
-const element = document.querySelector<HTMLFormElement>('#profile-form')
-
-// Snapshot on every input:
-element?.addEventListener('input', () => {
-  if (!element) return
-  const { data } = parseFormData(element)
-  localStorage.setItem('draft', JSON.stringify(data))
-})
-
-// Restore on load:
-const saved = localStorage.getItem('draft')
-if (saved && element) {
-  const data = JSON.parse(saved) as Record<string, string>
-  for (const [key, value] of Object.entries(data)) {
-    const field = element.querySelector<HTMLInputElement>(`[name="${key}"]`)
-    if (field) field.value = value
-  }
-}
-```
-
-## Edge cases
-
-- **Empty file inputs are filtered out.** This matches what [`getData()`](get-data.md) does inside a controller.
-- **`parseFormData` does not validate** — pass the result through [`validateValues`](validate-values.md) if you need validation.
-- **No type coercion.** All values come from `FormData` directly.
-
-## Related
-
-- [`getData`](get-data.md) — controller-bound equivalent.
-- [`validateValues`](validate-values.md) — run validation against a `FormValues` map.

package/docs/api/prefill.md

@@ -1,89 +0,0 @@
-# `prefill(fieldName?)`
-
-Populates the form (or a single field) from the current URL query string. Useful for sharing prefilled links, marketing tracking params, or restoring form state from `location.search`.
-
-## Signature
-
-```ts
-prefill(): FormController
-prefill(fieldName: string): FormController
-```
-
-## Parameters
-
-| Name | Type | Required | Description |
-| --- | --- | --- | --- |
-| `fieldName` | `string` | no | When provided, only this field is prefilled. When omitted, every query parameter is matched. |
-
-## Returns
-
-The same [`FormController`](../typescript.md#formcontroller) — chainable.
-
-## Behaviour
-
-- Reads `window.location.search` once with `URLSearchParams`.
-- For each entry, calls [`setValue`](set-value.md) with the key/value pair.
-- When `fieldName` is provided, only the matching key is written.
-- Values are always strings. If a field expects a different shape (e.g. `number`), the consumer must convert.
-
-Because the method delegates to [`setValue`](set-value.md), each prefilled field:
-
-- Receives a synthetic `input` event, so watchers and subscribers fire.
-- Triggers validation if it has rules and `autoValidate` is enabled.
-- Triggers autoSubmit if it is enabled.
-- Updates the `css-filled` / `css-error` attributes.
-
-## Examples
-
-### Prefill the whole form
-
-```ts
-import { form } from '@samline/forms'
-
-// URL: https://example.com/contact?utm_source=newsletter&email=hi@example.com
-const contact = form('contact-form')
-contact.prefill()
-
-contact.getValue('email')             // 'hi@example.com'
-contact.getValue('utm_source')        // 'newsletter'
-```
-
-### Prefill a single field
-
-```ts
-const contact = form('contact-form')
-contact.prefill('email')
-```
-
-### Round-trip a draft through the URL
-
-```ts
-import { form } from '@samline/forms'
-
-const draft = form('draft-form')
-
-// User types into fields, watchers debounce-serialize and push to the URL:
-draft.subscribe(state => {
-  const params = new URLSearchParams()
-  for (const [key, value] of Object.entries(state.values)) {
-    if (typeof value === 'string') params.set(key, value)
-  }
-  history.replaceState(null, '', `?${params.toString()}`)
-})
-
-// On next mount:
-draft.prefill()
-```
-
-## Edge cases
-
-- **`window` must exist.** The browser bundle uses `window.location`; in non-DOM environments `prefill` is a no-op.
-- **Values are always strings.** Prefilling a `<select>` requires the query value to match one of the option values exactly.
-- **Repeated query keys** (`?tag=a&tag=b`) are processed in iteration order. Only the last value wins because `URLSearchParams.forEach` visits both entries; the second `setValue` call overwrites the first.
-- **Prefill runs synchronously.** Call it after the form is in the DOM.
-
-## Related
-
-- [`setValue`](set-value.md) — underlying primitive.
-- [`getValue`](get-value.md) — read the prefilled values.
-- [`format`](format.md) — when a field is formatted, prefilling the canonical name writes the raw and reformats the visible; prefilling the display name writes the formatted and recomputes the raw. See [the mirror convention](format.md#the-mirror-convention).

package/docs/api/regex.md

@@ -1,155 +0,0 @@
-# `regex`
-
-> **Heads up — this is a peer dependency.** `regex` is exported by [`@samline/formatter`](https://github.com/samline/formatter), **not** by `@samline/forms`. It only exists when `@samline/formatter` is installed in your project. The forms package does not bundle it, ship it, or declare it as a hard dependency — it is an optional peer. Importing it without installing the peer will throw a module-not-found error at build / runtime, and the page below is only meaningful when the peer is on disk.
-
-A named dictionary of common regular expressions and their default error messages. Use it to feed the [`pattern`](../options.md#validators) rule of any field validator without hand-rolling a `RegExp` and a string for every form.
-
-## Import
-
-```ts
-import { regex } from '@samline/formatter'
-```
-
-`@samline/formatter` is listed as an optional peer in `package.json`. If you already have it installed for the `format()` / `formatAll()` masks, the import works out of the box. If you do not, install it with:
-
-```bash
-npm install @samline/formatter
-```
-
-```bash
-pnpm add @samline/formatter
-```
-
-```bash
-bun add @samline/formatter
-```
-
-## Signature
-
-```ts
-const regex: Record<string, { pattern: RegExp; errorMessage: string }>
-```
-
-Each entry is keyed by a short name (`'email'`, `'url'`, `'phone'`, …) and exposes:
-
-| Field | Type | Description |
-| --- | --- | --- |
-| `pattern` | `RegExp` | The expression to test the value against. |
-| `errorMessage` | `string` | A human-readable message describing the failure. Use it as the default `message` for the `pattern` rule. |
-
-The exact key set lives in the `@samline/formatter` package and can grow over time — refer to its [options reference](https://github.com/samline/formatter/blob/main/docs/options.md) for the full list. Common entries include `email`, `url`, `phone`, and `slug`.
-
-## Parameters
-
-None — `regex` is a plain object, not a function.
-
-## Returns
-
-A plain `Record<string, { pattern: RegExp; errorMessage: string }>` that you can index by name.
-
-## Behaviour
-
-`regex` is purely declarative data. The forms package does not call it for you — you opt in by passing `regex.<key>.pattern` (and optionally `regex.<key>.errorMessage`) into a field's `validators` config. The controller's built-in `pattern` rule then runs the expression and pushes the message when the value does not match.
-
-`regex` works the same whether you read it directly, destructure the entries you need, or merge it into a project-wide constant. The patterns are owned by `@samline/formatter`; treat the object as read-only.
-
-## Examples
-
-### Validate an email with the built-in pattern
-
-```ts
-import { form } from '@samline/forms'
-import { regex } from '@samline/formatter'
-
-const contact = form('contact-form', {
-  validators: {
-    email: {
-      required: true,
-      pattern: regex.email.pattern
-    }
-  }
-})
-```
-
-This is the same `pattern` you'd write by hand (`/^[^\s@]+@[^\s@]+\.[^\s@]+$/`); the only difference is that it ships with the formatter peer.
-
-### Pair the pattern with the default error message
-
-```ts
-import { form } from '@samline/forms'
-import { regex } from '@samline/formatter'
-
-const signup = form('signup-form', {
-  validators: {
-    email: {
-      required: true,
-      pattern: {
-        value: regex.email.pattern,
-        message: regex.email.errorMessage
-      }
-    }
-  }
-})
-```
-
-When the value fails the pattern, the controller pushes `regex.email.errorMessage` into `state.errors.email` and applies the `css-error` attribute to the field — see [Validation](../options.md#validators) and [CSS styling](../css-styling.md).
-
-### Use it without a controller
-
-The patterns and messages are plain values, so they work the same in any validation pipeline:
-
-```ts
-import { regex } from '@samline/formatter'
-import { validateFieldValue } from '@samline/forms'
-
-const errors = validateFieldValue(
-  'email',
-  'not-an-email',
-  { pattern: regex.email.pattern },
-  {}
-)
-
-// errors = ['<default pattern message, sourced from @samline/formatter>']
-```
-
-See [`validateFieldValue`](validate-field-value.md) for the pure helper signature.
-
-### Spread `regex` into a browser global alongside `browser`
-
-The vanilla entrypoint exposes a `browser` singleton with `form`, `newForm`, `destroyForm`, and `available`. The most common pattern is to spread it together with `regex` into a single project global — see [Browser registry helpers](../getting-started.md#browser-registry-helpers) in the getting-started guide:
-
-```ts
-import { browser } from '@samline/forms'
-import { regex } from '@samline/formatter' // optional, from your project
-
-window.Form = { ...browser, regex }
-
-window.Form.newForm({
-  id: 'contact-form',
-  options: {
-    validators: {
-      email: {
-        required: true,
-        pattern: regex.email.pattern
-      }
-    }
-  }
-})
-```
-
-The same shape is available from the IIFE bundle under `window.Forms`; the spread pattern works the same way when the project loads `@samline/forms/browser` instead.
-
-## Edge cases
-
-- **Missing peer.** `import { regex } from '@samline/formatter'` throws a module-not-found error when the peer is not installed. `@samline/forms` does not catch this — install the peer before you import the symbol.
-- **No types are shipped by `@samline/forms` for `regex`.** The shim in [`src/types/formatter.d.ts`](../../src/types/formatter.d.ts) declares the type as `Record<string, { pattern: RegExp; errorMessage: string }>` for projects that do not yet have the peer on disk, but the real types come from the installed peer at compile time.
-- **`regex` is not enumerated at runtime.** The key set lives in `@samline/formatter`; iterate with `Object.keys(regex)` if you need a dynamic listing.
-- **The controller never reads `regex` for you.** You opt in per field via the `pattern` rule. There is no global switch that turns on `regex.email` for every `email` field.
-- **Browser global key collision.** Spreading `{ ...browser, regex }` into `window.Form` is the documented pattern; assigning `window.Forms.regex` directly is fine too — the registry is shared across spreads.
-
-## Related
-
-- [`validators`](../options.md#validators) — the option that consumes `regex.<key>.pattern`.
-- [`validateFieldValue`](validate-field-value.md) — the pure helper that runs the `pattern` rule.
-- [`format`](format.md) — also depends on `@samline/formatter` being installed.
-- [`@samline/formatter` options reference](https://github.com/samline/formatter/blob/main/docs/options.md) — the canonical list of `regex` keys.

package/docs/api/reset.md

@@ -1,61 +0,0 @@
-# `reset()`
-
-Restores the form to its initial state: native field values reset, manual and validation errors cleared, visual attributes synchronized, subscribers notified.
-
-## Signature
-
-```ts
-reset(): FormController
-```
-
-## Returns
-
-The same [`FormController`](../typescript.md#formcontroller) — chainable.
-
-## Behaviour
-
-When invoked, the controller:
-
-1. Calls `state.element.reset()` (the native form reset).
-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. 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
-
-### Reset after a successful submit
-
-```ts
-import { form } from '@samline/forms'
-
-const profile = form('profile-form')
-
-profile.onSubmit(async (_element, _data, formData) => {
-  await fetch('/profile', { method: 'POST', body: formData })
-  profile.reset()
-})
-```
-
-### Reset on cancel
-
-```ts
-const signup = form('signup-form')
-
-document.querySelector('#cancel')?.addEventListener('click', () => {
-  signup.reset()
-})
-```
-
-## Edge cases
-
-- **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
-
-- [`destroy`](destroy.md) — full teardown.
-- [`clearErrors`](clear-errors.md) — clear errors without resetting field values.