@samline/forms 2.7.2 → 2.9.0

package/docs/api/format.md

@@ -1,270 +0,0 @@
-# `format(config)` · `formatAll(config)`
-
-Apply an `@samline/formatter` pipeline to one or more fields inside the bound form. Chainable.
-
-`format()` and `formatAll()` behave identically — the alias exists so the call site reads naturally when the caller wants to apply the same configuration to several inputs.
-
-## The mirror convention
-
-A formatted field is exposed as a pair of inputs:
-
-| Role | `name` | `type` | Value |
-| --- | --- | --- | --- |
-| **Canonical** (the one the backend reads) | `<field>` | `hidden` | The raw value |
-| **Display** (what the user types) | `<field>_displayed` | `text` / `tel` / `…` | The formatted value |
-
-You write the HTML with the canonical name only — `<input name="phone" />`. The first time `format()` runs for that field it renames the visible from `phone` to `phone_displayed` and appends a hidden input with `name="phone"` that carries the raw value. The rename is idempotent and the hidden is reused (not duplicated) on re-binding.
-
-After the rename both names are first-class in the controller's API:
-
-| API call | Effect |
-| --- | --- |
-| `getValue('phone')` | Returns the **raw** value. |
-| `getValue('phone_displayed')` | Returns the **formatted** value. |
-| `getField('phone')` | Returns the **hidden** raw mirror element. |
-| `getField('phone_displayed')` | Returns the **visible** input element. |
-| `setValue('phone', x)` | Writes the raw; the visible is reformatted automatically. |
-| `setValue('phone_displayed', x)` | Writes the formatted; the raw is recomputed automatically. |
-| `watch('phone', cb)` | `cb` receives the raw value on every keystroke. |
-| `watch('phone_displayed', cb)` | `cb` receives the formatted value on every keystroke. |
-| `getData()` | The `FormData` carries both `phone` and `phone_displayed`. |
-| `validators.phone` | Validates the **raw** value (the one the backend gets). |
-
-This is the orthogonal model: every name is a real, queryable slot. You never need to know which is the "real" one — each method returns the value of the name you asked for.
-
-> **Optional peer dependency.** ESM, CJS, and browser-module builds require the optional `@samline/formatter` peer. If it is missing, the module instance logs one cached `console.error` and asynchronously rolls back affected field pairs; the controller remains usable. The standalone global IIFE bundles the formatter.
-
----
-
-## Signature
-
-```ts
-format(config: FieldFormatConfig): FormController
-formatAll(config: FieldFormatConfig): FormController
-```
-
-## Parameters
-
-`config` is a [`FieldFormatConfig`](../typescript.md#fieldformatconfig):
-
-| Name | Type | Required | Description |
-| --- | --- | --- | --- |
-| `type` | `'general' \| 'phone' \| 'numeral' \| 'date' \| 'time' \| 'creditCard' \| 'creditCardType'` | yes | One of the supported `FormatType` values exported by `@samline/formatter`. |
-| `field` | `string \| string[]` | yes | The **canonical** name of the field — the one the backend reads. The visible you authored in the HTML should already have this name (or the display name, see [Pre-authoring the visible](#pre-authoring-the-visible) below). |
-| `displayField` | `string` | no | Name of the visible input for a single `field`. Combining it with a field array logs an error and leaves the form unchanged; arrays derive `${fieldName}_displayed` per field. |
-| `options` | `Record<string, unknown>` | no | Format-specific options forwarded to `@samline/formatter`. See the [formatter options reference](https://github.com/samline/formatter/blob/main/docs/options.md). |
-
-## Returns
-
-The same [`FormController`](../typescript.md#formcontroller) — chainable. The method returns the controller unchanged when:
-
-- the form has already been destroyed,
-- there is no bound `HTMLFormElement`,
-- `@samline/formatter` is not installed (a single `console.error` is logged in this case, and the visible's name is restored to its canonical form so the form goes back to its original state),
-- no field matches `field` (or the display name) in the form.
-
-## Behaviour
-
-1. The sync part of `format()` renames the visible from the canonical name to the display name and creates / reuses the hidden raw mirror. The controller's API (`getValue`, `getField`, `setValue`, `watch`, `getData`) is fully functional for the field by the time `format()` returns.
-2. The async part loads the formatter peer through a lazy dynamic import. Subsequent calls reuse the cached module so the lookup cost is paid once. If the peer loads, the input listener is bound and the formatter is applied to the current value of the visible (pre-filled data, server-rendered values, etc.) so the hidden mirror is populated without waiting for a user keystroke. If the peer fails to load, the rename is rolled back.
-3. On every keystroke the capture-phase listener runs the formatter and rewrites the visible input **and** the hidden raw mirror. The capture-phase registration guarantees the mirror is up to date before the controller's delegated handler fires, so `watch('phone', cb)` callbacks receive the new raw value on the same tick.
-4. Cursor position is preserved using a cleave-style algorithm (see [Cursor tracking](#cursor-tracking)).
-5. If a hidden input already exists in the form for the same canonical name — either with the `data-formatter-raw-for="<field>"` attribute or as a plain `<input type="hidden" name="<field>">` — `format()` reuses it instead of duplicating it. The previously authored value is preserved across `destroy()` (see [Cleanup](#cleanup)).
-6. Calling `format()` twice for the same canonical name is idempotent: the listener is bound once and the configuration is refreshed in the internal registry.
-
-## Initial value interpretation (server pre-fill)
-
-When the visible field already carries a value at the moment `format()` first runs — typically a server-rendered `value="{{ old('field') }}"` in a Blade template, or a value set by a previous `setValue` call — the controller runs that value through the formatter once before any user interaction. The formatter's input is the visible's value, which on a server pre-fill is the **canonical raw** (e.g. `"19901212"` for a date with a `Ymd` raw), not the display form.
-
-`@samline/formatter` v2.0.0+ changed its default `interpretInputAs` to `'auto'`, which detects the raw shape by the absence of delimiters and the digit length matching the raw pattern. The controller still injects `interpretInputAs: 'auto'` explicitly for the initial pass and for mirror-source events so the intent is documented in code and the behaviour is robust against a future formatter change that flips the default again.
-
-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 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"`, 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
-
-The default flow is: write `<input name="phone" />` and let `format()` rename it to `phone_displayed`. If you'd rather keep the visible's name stable in your HTML, pre-author it with the display name:
-
-```html
-<input name="phone_displayed" />
-<form id="checkout">…</form>
-```
-
-```ts
-form('checkout', { formats: { phone: { type: 'phone', field: 'phone' } } })
-```
-
-`format()` will pick up `<input name="phone_displayed">` as the visible, leave its name alone, and create the hidden with `name="phone"`. Both authoring styles end up with the same DOM.
-
-## Hidden mirror semantics
-
-Every formatted field gets a sibling hidden input that:
-
-- has `type="hidden"`,
-- is named with the canonical `<field>` (the one the backend reads),
-- carries `data-formatter-raw-for="<field>"` so the controller can identify it as owned and clean it up on `destroy()`,
-- receives the latest `FormatterResult.raw` value on every input event.
-
-Because the mirror is a real `<input>` inside the form, it shows up automatically in `FormData`, `serialize()`, and `api.getData()`. You can also read or write it via the canonical name in every controller API method.
-
-## Cursor tracking
-
-The helper in [`src/core/format-helpers.ts`](../../src/core/format-helpers.ts) implements a cursor-restore algorithm modelled on cleave.js' `getNextCursorPosition` and `postDelimiterBackspace`:
-
-- The caret position is captured **before** the value is rewritten.
-- After `FormatterResult.formatted` is written, the helper counts the number of non-format characters (digits, ASCII letters) to the left of the original caret and re-positions the caret at the same logical index in the new value, skipping delimiters.
-- When the user deletes one character that sits right before a delimiter, the helper pulls the caret back one extra position to mirror cleave's `postDelimiterBackspace` behaviour so the cursor never ends up "jumping" past a delimiter that disappeared.
-- On Android, the caret restoration is deferred one animation frame via `requestAnimationFrame` to work around the IME quirk that causes the caret to land at the end on the first frame after a value rewrite.
-
-## Cleanup
-
-`destroy()` calls a dedicated cleanup routine that:
-
-- removes the `input` listener registered by `format()` (capture-phase, matched on registration),
-- restores the visible's name to the canonical form so the DOM goes back to the developer's authored state,
-- removes hidden raw mirrors that **this** controller created (mirrors authored before `format()` was called carry no `data-formatter-raw-for` attribute and survive `destroy()`),
-- clears the `formattedFields` registry so the controller can be garbage-collected.
-
-## Reading both values in one place
-
-If a watcher needs the raw and the formatted at the same time, the orthogonal model makes that cheap:
-
-```ts
-checkout.watch('phone', (raw, _field, _form, state) => {
-  const formatted = state.values.phone_displayed
-  // raw is the canonical value, formatted is what the user sees.
-  console.log({ raw, formatted })
-})
-```
-
-Both `state.values.phone` and `state.values.phone_displayed` are populated on every keystroke — pick whichever you need.
-
-## Examples
-
-### Format a phone field declaratively
-
-```ts
-import { form } from '@samline/forms'
-
-const checkout = form('checkout-form', {
-  formats: {
-    phone: { type: 'phone', field: 'phone', options: { country: 'MX' } }
-  }
-})
-
-// After `format()` runs (sync part):
-//   - the visible is now <input name="phone_displayed">
-//   - the hidden is <input type="hidden" name="phone">
-checkout.getValue('phone')           // '' (no user input yet)
-checkout.getValue('phone_displayed') // ''
-```
-
-### Apply a single configuration to multiple fields with `formatAll`
-
-```ts
-import { form } from '@samline/forms'
-
-const pricing = form('pricing-form', {
-  formats: {
-    money: {
-      type: 'numeral',
-      field: ['price', 'subtotal', 'total'],
-      options: { prefix: '$', delimiter: ',' }
-    }
-  }
-})
-
-// Three different fields, one configuration, one pair per field.
-pricing.getField('price_displayed')     // visible
-pricing.getField('price')               // hidden raw mirror
-pricing.getField('subtotal_displayed')  // visible
-pricing.getField('subtotal')            // hidden raw mirror
-pricing.getField('total_displayed')     // visible
-pricing.getField('total')               // hidden raw mirror
-```
-
-### Wire it imperatively after mount
-
-```ts
-import { form } from '@samline/forms'
-
-const profile = form('profile-form')
-profile.format({ type: 'date', field: 'birthday' })
-profile.format({ type: 'creditCard', field: 'card' })
-```
-
-### Custom display name
-
-```ts
-profile.format({ type: 'phone', field: 'phone', displayField: 'phoneVisible' })
-
-// After `format()` runs:
-//   - visible: <input name="phoneVisible">
-//   - hidden:  <input type="hidden" name="phone">
-```
-
-### React to keystrokes on either name
-
-```ts
-const checkout = form('checkout-form', {
-  formats: { phone: { type: 'phone', field: 'phone' } }
-})
-
-// Both watchers fire on the same keystroke. Each receives the
-// value of the name it was registered against.
-checkout.watch('phone', raw => console.log('backend value:', raw))
-checkout.watch('phone_displayed', formatted => console.log('user sees:', formatted))
-```
-
-### Read both values at submit time
-
-```ts
-checkout.onSubmit((_form, data, formData) => {
-  // data and formData carry both names:
-  //   phone           = '5512345678'           (raw)
-  //   phone_displayed = '55 1234 5678'         (formatted)
-  // The backend only needs `phone`.
-  fetch('/api/checkout', { method: 'POST', body: formData })
-})
-```
-
-### Fallback when the peer is missing
-
-```ts
-// @samline/formatter is NOT installed
-const profile = form('profile-form')
-profile.format({ type: 'phone', field: 'phone' })
-// console.error:
-//   [samline/forms] The `format()` and `formatAll()` methods require the
-//   @samline/formatter package. Install it with: npm i @samline/formatter ...
-// The visible is left with its original name (`phone`), no hidden
-// mirror is created, no listener is bound — the form is exactly
-// as the developer authored it. `profile.format(...)` still
-// returned the controller, so chaining works.
-profile.setValue('phone', '...').validate()
-```
-
-## Edge cases
-
-- **Non-text inputs are skipped.** `format()` ignores checkboxes, radios, files, submit buttons, and buttons. Calling it for one of those field names is a no-op (no listener, no mirror).
-- **Same field across multiple controllers.** Each `FormController` instance owns its own mirrors, so two controllers bound to different forms can format a `phone` field without the raw inputs colliding.
-- **Field pre-filled from the server.** If the visible field already carries a value when `format()` runs, the formatter is applied immediately (after the peer resolves) and the mirror is populated without waiting for a user keystroke.
-- **`setValue('phone', x)` and `setValue('phone_displayed', x)` both reformat the other side.** Each `setValue` writes its target, dispatches a synthetic `input` event, and the capture-phase listener reformats the partner.
-- **`validators.phone` runs against the raw value.** The raw is the value the backend ultimately receives, so the validator is the gatekeeper for backend acceptance.
-- **`destroy()` is idempotent.** Calling `destroy()` after `format()` was never wired leaves the form untouched; calling it after `format()` was wired removes only the mirrors owned by the current controller and restores the visible's name.
-
-## Related
-
-- [`getValue`](get-value.md) — read either the formatted or the raw value (orthogonal).
-- [`getField`](get-field.md) — grab the underlying DOM elements (visible or hidden).
-- [`setValue`](set-value.md) — write either the raw or the formatted value (the other side is reformatted automatically).
-- [`watch`](watch.md) / [`observe`](observe.md) — react to changes on either name; each callback receives the value of the name it was registered against.
-- [`getData`](get-data.md) — the serialized payload carries both names.
-- [`destroy`](destroy.md) — releases listeners, the mutation observer, owned raw mirrors, and restores the visible's name.
-- [Optional peer dependency `@samline/formatter`](https://github.com/samline/formatter)

package/docs/api/get-data.md

@@ -1,90 +0,0 @@
-# `getData()`
-
-Returns the form serialized as both a plain object and a fresh `FormData` instance. Empty file inputs are filtered out.
-
-## Signature
-
-```ts
-getData(): SerializedFormResult
-```
-
-```ts
-interface SerializedFormResult {
-  data: Record<string, SerializedFormValue>
-  formData: FormData
-}
-```
-
-## Parameters
-
-None.
-
-## Returns
-
-A [`SerializedFormResult`](../typescript.md#serializedformresult):
-
-- `data` — plain object mirror of the form. Repeated names become arrays. Strings and `File` instances are preserved as-is.
-- `formData` — a fresh `FormData` instance, safe to send directly to `fetch`.
-
-## Behaviour
-
-- Reads directly from the live DOM via `new FormData(formElement)`.
-- Drops entries where the value is an empty `File` (`size === 0` and `name === ''`) — these are produced by empty `<input type="file">` controls.
-- Builds the `data` mirror while iterating the raw `FormData`, grouping repeated names into arrays.
-
-## Examples
-
-### Send to a JSON endpoint
-
-```ts
-import { form } from '@samline/forms'
-
-const contact = form('contact-form')
-
-contact.onSubmit(async (_element, data) => {
-  await fetch('/api/contact', {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify(data)
-  })
-})
-```
-
-### Send a real `FormData` to a file-upload endpoint
-
-```ts
-import { form } from '@samline/forms'
-
-const upload = form('upload-form')
-
-upload.onSubmit(async (_element, _data, formData) => {
-  await fetch('/api/upload', { method: 'POST', body: formData })
-})
-```
-
-### Snapshot the form state without submitting
-
-```ts
-const profile = form('profile-form')
-
-profile.subscribe(state => {
-  if (state.submitCount > 0) {
-    const { data } = profile.getData()
-    console.log('last submit payload:', data)
-  }
-})
-```
-
-## Edge cases
-
-- **Empty file inputs are filtered out of both `data` and `formData`.** This is intentional — HTML produces placeholder `File` entries when a file input is rendered but no file is selected.
-- **The returned `data` mirror is fresh** on every call. Safe to mutate.
-- **`getData()` does not trigger validation, watchers, or autoSubmit** — it is a pure read.
-- **The plain object form is convenient for JSON endpoints; the `FormData` form is required for file uploads.** Browsers will not serialize `File` instances into JSON.
-
-## Related
-
-- [`parseFormData`](../api/parse-form-data.md) — same serializer, used directly without a controller.
-- [`getValue`](get-value.md) — read a single field’s value.
-- [`onSubmit`](../api/on-submit.md) — receives the same shape as arguments.
-- [`format`](format.md) — when a field is formatted, the `FormData` carries both the canonical name (with the raw value) and the `<field>_displayed` name (with the formatted value). See [the mirror convention](format.md#the-mirror-convention).

package/docs/api/get-field.md

@@ -1,87 +0,0 @@
-# `getField(name)`
-
-Returns the underlying DOM field(s) for a given name. Useful when you need direct DOM access — for example, to focus a field, attach a third-party widget, or read custom attributes.
-
-## Signature
-
-```ts
-getField(name: string): FormFieldElement | FormFieldElement[] | null
-```
-
-```ts
-type FormFieldElement =
-  | HTMLInputElement
-  | HTMLSelectElement
-  | HTMLTextAreaElement
-```
-
-## Parameters
-
-| Name | Type | Required | Description |
-| --- | --- | --- | --- |
-| `name` | `string` | yes | The `name` attribute of the target field. |
-
-## Returns
-
-- A single `FormFieldElement` when exactly one matching field exists.
-- An array of `FormFieldElement` when multiple fields share the same `name` (radios, checkbox groups).
-- `null` when no field with that `name` exists.
-
-## Behaviour
-
-- The lookup is performed against the live DOM, including dynamically added fields (the `MutationObserver` keeps the cache fresh).
-- The returned element(s) are live references — mutations you make to them are reflected in the form, but they bypass the controller’s normal pipeline. If you want watchers and validation to run, prefer [`setValue`](set-value.md).
-
-## Examples
-
-### Focus a field after submit
-
-```ts
-import { form } from '@samline/forms'
-
-const profile = form('profile-form')
-
-profile.onSubmit(async (_element, _data, formData) => {
-  const response = await fetch('/profile', { method: 'POST', body: formData })
-
-  if (response.status === 422) {
-    const field = profile.getField('email') as HTMLInputElement | null
-    field?.focus()
-  }
-})
-```
-
-### Iterate a radio group
-
-```ts
-const shipping = form('shipping-form')
-
-const radios = shipping.getField('method')
-
-if (Array.isArray(radios)) {
-  for (const radio of radios) {
-    radio.addEventListener('change', () => console.log(radio.value))
-  }
-}
-```
-
-### Read a custom data attribute
-
-```ts
-const profile = form('profile-form')
-
-const field = profile.getField('avatar') as HTMLInputElement | null
-const maxSize = Number(field?.dataset.maxSize ?? '0')
-```
-
-## Edge cases
-
-- **`null` means “no field with that name”** — distinct from `[]` which means “no matching fields but the lookup ran”.
-- **The array form is only used when more than one field matches.** A single checkbox that happens to be a group of one is still returned as a single element, not an array.
-- **`getField` does not throw** when the controller has no bound form — it returns `null`.
-
-## Related
-
-- [`getValue`](get-value.md) — read the value.
-- [`setValue`](set-value.md) — write a value through the controller.
-- [`format`](format.md) — when a field is formatted, `getField('<field>')` returns the hidden raw mirror and `getField('<field>_displayed')` returns the visible input. See [the mirror convention](format.md#the-mirror-convention).

package/docs/api/get-state.md

@@ -1,111 +0,0 @@
-# `getState()`
-
-Returns a fresh snapshot of the controller state. Pure read — does not mutate anything and does not notify subscribers.
-
-## Signature
-
-```ts
-getState(): FormStateSnapshot
-```
-
-```ts
-interface FormStateSnapshot {
-  values: FormValues
-  errors: FormErrors
-  filledFields: string[]
-  isValid: boolean
-  isValidated: boolean
-  autoSubmit: boolean
-  isSubmitting: boolean
-  submitCount: number
-}
-```
-
-## Parameters
-
-None.
-
-## Returns
-
-A [`FormStateSnapshot`](../typescript.md#formstatesnapshot). Every call returns a fresh object — safe to mutate.
-
-## Snapshot fields
-
-| Field | Meaning |
-| --- | --- |
-| `values` | Current values for every tracked field (validators + named fields in the form). |
-| `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 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
-
-### Read the current state
-
-```ts
-import { form } from '@samline/forms'
-
-const profile = form('profile-form')
-
-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
-
-```ts
-const profile = form('profile-form')
-
-profile.element?.addEventListener('input', () => {
-  const state = profile.getState()
-  emailError.hidden = !state.errors.email
-  emailError.textContent = state.errors.email?.[0] ?? ''
-})
-```
-
-The controller manages `aria-invalid`; use state to manage the message referenced by `aria-describedby`.
-
-### Snapshot on submit
-
-```ts
-const profile = form('profile-form')
-
-profile.onSubmit((_form, _data, _formData, state) => {
-  console.log('submit #', state.submitCount)
-  console.log('values at submit:', state.values)
-  console.log('errors at submit:', state.errors)
-})
-```
-
-### 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
-
-- [`subscribe`](subscribe.md) — receive state updates reactively.
-- [`getData`](get-data.md) — serialize the form payload.

package/docs/api/get-value.md

@@ -1,114 +0,0 @@
-# `getValue(name)`
-
-Reads the current value of a field, normalized for the field type.
-
-## Signature
-
-```ts
-getValue(name: string): FormFieldValue
-```
-
-```ts
-type FormFieldValue = string | string[] | File[] | undefined
-```
-
-## Parameters
-
-| Name | Type | Required | Description |
-| --- | --- | --- | --- |
-| `name` | `string` | yes | The `name` attribute of the target field. |
-
-## Returns
-
-The normalized value:
-
-- `string` for text inputs, textareas, single selects, the single checked radio, or a single checked checkbox.
-- `string[]` for checkbox groups with multiple selections.
-- `string[]` for any field whose `name` ends in `[]` and that matches more than one input — the values of every matching input, in DOM order.
-- `string[]` for the selected options of `<select multiple>`.
-- `File[]` for `<input type="file">` (may be empty), or the concatenation of every selected file across all inputs that share a `name` ending in `[]`.
-- `undefined` when no field with that `name` exists.
-
-## Behaviour by field type
-
-| Field type | Returned value |
-| --- | --- |
-| `<input>` (text-like) | `field.value`. |
-| `<input>` (text-like) with `name="foo[]"` and more than one input | `[input[0].value, input[1].value, ...]` — one entry per matching input, in DOM order. |
-| `<input type="radio">` (group) | The `value` of the checked radio, or `''` when none is checked. The `[]` suffix is ignored for radio — radio groups are always single-valued. |
-| `<input type="checkbox">` (single) | `field.value` when checked, `''` when unchecked. |
-| `<input type="checkbox">` (group) | `value` when exactly one is checked, `[value1, value2, ...]` when multiple are checked, `''` when none is checked. |
-| `<input type="checkbox">` (group with `name="foo[]"`) | `[value1, value2, ...]` of every checked input. Always an array — no single-value collapse — so `Array.isArray(value)` validators stay correct. |
-| `<input type="file">` | `Array.from(field.files)`. |
-| `<input type="file">` (group with `name="foo[]"`) | The concatenation of `Array.from(input.files)` across every matching input, in DOM order. |
-| `<select>` | `field.value`. |
-| `<select multiple>` | Values of every selected option. |
-| `<select>` (group with `name="foo[]"`) | `[select[0].value, select[1].value, ...]`. |
-| `<textarea>` | `field.value`. |
-| `<textarea>` (group with `name="foo[]"`) | `[textarea[0].value, textarea[1].value, ...]`. |
-
-## Examples
-
-### Read a text value
-
-```ts
-import { form } from '@samline/forms'
-
-const contact = form('contact-form')
-contact.setValue('email', 'hello@example.com')
-
-contact.getValue('email') // 'hello@example.com'
-```
-
-### Read a checkbox group
-
-```ts
-const signup = form('signup-form')
-
-signup.setValue('interests', ['design', 'code'])
-
-signup.getValue('interests') // ['design', 'code']
-
-signup.setValue('interests', ['design'])
-
-signup.getValue('interests') // 'design' (single string)
-```
-
-### Read a file input
-
-```ts
-const upload = form('upload-form')
-
-const files = upload.getValue('attachments')
-if (Array.isArray(files) && files.length > 0) {
-  console.log('first file:', files[0]!.name)
-}
-```
-
-### Read a `name="foo[]"` group
-
-```ts
-const signup = form('signup-form')
-
-signup.getValue('docusign_email[]') // ['a@example.com', 'b@example.com']
-
-// The `[]` suffix is the de facto multi-value input convention used by
-// PHP, Rails, Express, Spring, etc. on the server. It tells the
-// controller to collect every matching input as an array, so custom
-// validators can rely on `Array.isArray(value)`.
-```
-
-## Edge cases
-
-- **`getValue` is a pure read.** It does not mutate the DOM, does not notify subscribers, and does not trigger validation.
-- **`undefined` vs `''`** — `undefined` means “no field with that name”. `''` means “the field exists but is empty”.
-- **`getValue('radio-name')` returns `''` when no radio in the group is checked.** Treat empty string as “no selection”.
-- **The `name="foo[]"` suffix is the explicit opt-in for multi-value inputs.** A field with the suffix but a single matching input still returns a plain string (not a one-element array). Bare names — `name="foo"` with multiple inputs — keep the original first-value semantics and are not collapsed into an array.
-- **Whitespace is not trimmed.** If you need trimming, do it in your own code or in a custom validator.
-
-## Related
-
-- [`setValue`](set-value.md) — write a value.
-- [`getField`](get-field.md) — read the underlying DOM element(s).
-- [`getData`](get-data.md) — serialize the whole form.
-- [`format`](format.md) — when a field is formatted, `getValue('<field>')` returns the raw value and `getValue('<field>_displayed')` returns the formatted value. See [the mirror convention](format.md#the-mirror-convention).