@samline/forms 2.4.0 → 2.7.0

package/docs/api/index.md

@@ -0,0 +1,55 @@
+# 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

@@ -0,0 +1,126 @@
+# `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

@@ -0,0 +1,94 @@
+# `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

@@ -0,0 +1,94 @@
+# `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

@@ -0,0 +1,89 @@
+# `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

@@ -0,0 +1,155 @@
+# `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

@@ -0,0 +1,61 @@
+# `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.