@samline/forms 2.7.2 → 2.9.0

package/docs/getting-started.md

@@ -1,222 +0,0 @@
-# Getting Started
-
-This page explains what `@samline/forms` is, how the controller is wired, and which side effects to expect from each method. Use it as a mental model before diving into the per-method reference under [`docs/api/`](api/index.md).
-
----
-
-## When to use this variant
-
-Use the main `@samline/forms` entrypoint for native HTML forms. The package also provides `@samline/forms/browser` as an ESM/CJS browser module and `@samline/forms/browser/global` as the global IIFE distribution.
-
-> Note: the latest version is `2.7.2` — see [Releases](https://github.com/samline/forms/releases) for the changelog.
-
-If you want a `<script>`-only setup without a bundler, see [docs/browser.md](browser.md).
-
----
-
-## Anatomy of a controller
-
-A controller is created with [`form()`](api/form.md) and is bound to exactly one `HTMLFormElement`. Once bound, it:
-
-- Listens to delegated `input` events, including controls associated through `form="id"`.
-- Listens to the native `submit` event.
-- Maintains a small internal state (values, errors, watched fields, subscribers, submit handlers).
-- Applies DOM attributes (`css-filled`, `css-error`) to fields when needed.
-- Watches the form subtree with a `MutationObserver` so dynamic fields work.
-
-The controller is returned with a small, focused method surface. Most methods are chainable and return the same controller instance so you can compose setup fluently.
-
-```ts
-import { form } from '@samline/forms'
-
-const contact = form('contact-form')
-  .watch('email', value => console.log(value))
-  .setErrors({ email: ['Already in use'] })
-```
-
-Methods that return data instead of the controller: [`getValue`](api/get-value.md), [`getField`](api/get-field.md), [`getData`](api/get-data.md), [`getState`](api/get-state.md), [`validate`](api/validate.md), [`revalidate`](api/revalidate.md). Methods that return an unsubscribe or unregister function: [`observe`](api/observe.md), [`subscribe`](api/subscribe.md), [`addCleanup`](api/add-cleanup.md).
-
----
-
-## Observable contract
-
-Once a controller is created, you can rely on the following behaviour:
-
-- **`css-filled` attribute** is added to a field when it has a non-empty value, and removed when it becomes empty. Override the attribute name with `options.attributes.filled`.
-- **Initial filled state is always synchronized.** Prefilled controls receive `css-filled` on mount even with `autoValidate: false`; this does not run validation or set `isValidated`.
-- **`css-error` attribute** is added to a field when it has at least one error (validation or manual), and removed when it has none. Override with `options.attributes.error`.
-- **Validation runs on every change** for any field that has rules configured under `options.validators` (gated by `autoValidate`, default `true`).
-- **Manual errors from [`setErrors`](api/set-errors.md) are cleared by default when the affected field changes.** Set `clearManualErrorsOnChange: false` to keep them.
-- **Submit handlers receive a real `FormData` instance** built from the live form, plus a plain-object mirror. Invalid submissions never reach your handler.
-- **Async submit handlers are tracked.** `getState().isSubmitting` stays true while any promise-returning `onSubmit` work is pending, including overlapping submissions, and returns to false after fulfillment or rejection.
-- **Dynamic fields are auto-discovered.** A `MutationObserver` watches the form subtree for `name` / `type` attribute changes or new fields, re-caches the field registry, and re-runs visual state and validation.
-
----
-
-## Lifecycle
-
-The recommended flow:
-
-1. **Mount** — call [`form()`](api/form.md) with a binding target and options. The controller wires events, applies initial visual state, and (when `autoValidate`) runs an initial validation pass.
-2. **React** — register [`watch`](api/watch.md) / [`observe`](api/observe.md) callbacks for field-level reactions, and [`subscribe`](api/subscribe.md) for whole-form reactions.
-3. **Validate** — built-in validation runs automatically. Use [`validate`](api/validate.md) (or the alias [`revalidate`](api/revalidate.md)) to run it on demand.
-4. **Submit** — register [`onSubmit`](api/on-submit.md) handlers. Valid submissions are intercepted (default) or allowed to continue natively (`preventDefault: false`).
-5. **Reset** — call [`reset`](api/reset.md) to restore native defaults, clear errors, and re-synchronize visual attributes.
-6. **Destroy** — register integration teardown with [`addCleanup`](api/add-cleanup.md), then call [`destroy`](api/destroy.md) to remove listeners, disconnect the `MutationObserver`, run cleanups in reverse registration order, clear caches, and drop all subscribers.
-
----
-
-## Side effects per method
-
-Use this as a quick lookup when you need to know what a method will touch.
-
-| Method | DOM mutation | Events fired | Subscribers notified | AutoSubmit trigger | Visual state |
-| --- | --- | --- | --- | --- | --- |
-| [`setValue`](api/set-value.md) | yes (writes value, then `input`) | `input` | yes | yes | re-synced for that field |
-| [`getValue`](api/get-value.md) | no | no | no | no | unchanged |
-| [`getField`](api/get-field.md) | no | no | no | no | unchanged |
-| [`prefill`](api/prefill.md) | yes (writes via [`setValue`](api/set-value.md)) | per-field | yes | yes | re-synced per touched field |
-| [`append`](api/append.md) | yes (inserts a node; removes prior node with same class) | no | no | no | unchanged |
-| [`validate`](api/validate.md) | re-syncs visual attributes for the targeted fields | no | no | no | re-synced |
-| [`revalidate`](api/revalidate.md) | same as [`validate`](api/validate.md) | no | no | no | re-synced |
-| [`setErrors`](api/set-errors.md) | re-syncs visual attributes for the targeted fields | no | yes | no | re-synced |
-| [`clearErrors`](api/clear-errors.md) | re-syncs visual attributes (all or for the listed fields) | no | yes | no | re-synced |
-| [`reset`](api/reset.md) | calls native `form.reset()`; clears errors and re-syncs attributes from default values | no | yes | no | re-synced |
-| [`onSubmit`](api/on-submit.md) | none directly; submit handler is invoked on submit | n/a | n/a | n/a | n/a |
-| [`autoSubmit`](api/auto-submit.md) | schedules `form.requestSubmit()` (with optional debounce) | native submit | yes (config change) | enables the behaviour | unchanged |
-| [`disableAutoSubmit`](api/disable-auto-submit.md) | cancels any pending debounce timer | no | yes | disables | unchanged |
-| [`watch`](api/watch.md) / [`observe`](api/observe.md) | none directly; callback fires on changes | n/a | n/a | n/a | unchanged |
-| [`unwatch`](api/unwatch.md) | none | no | no | no | unchanged |
-| [`subscribe`](api/subscribe.md) | none; fires immediately with the current snapshot | no | n/a | n/a | unchanged |
-| [`addCleanup`](api/add-cleanup.md) | none until its callback runs during destroy | no | no | no | unchanged |
-| [`getData`](api/get-data.md) | no | no | no | no | unchanged |
-| [`getState`](api/get-state.md) | no | no | no | no | unchanged |
-| [`destroy`](api/destroy.md) | removes listeners and runs registered cleanups; does not remove visual attributes itself | no | no longer fires | disabled | unchanged |
-
-> Native field `input` events are delegated. Controls outside the form that use `form="id"` are handled through a document-level delegated listener.
-
----
-
-## Recommended usage patterns
-
-- Use [`watch`](api/watch.md) when you want a chainable, fire-and-forget reaction to a field. Use [`observe`](api/observe.md) when you need to clean up later — it returns an unsubscribe function.
-- Use [`subscribe`](api/subscribe.md) when a higher-level component (router, store, view layer) needs to react to the whole form state.
-- Use [`addCleanup`](api/add-cleanup.md) when third-party listeners, observers, subscriptions, or abort controllers should be released with the form controller.
-- Use [`getData()`](api/get-data.md) when you need both a plain object and a `FormData` instance.
-- Use [`setErrors`](api/set-errors.md) and [`clearErrors`](api/clear-errors.md) to drive visual feedback from server responses.
-- Pass `clearManualErrorsOnChange: false` only when manual errors should persist after the user edits a field.
-- Use [`autoSubmit({ debounce })`](api/auto-submit.md) for autosave / autosubmit flows. Pair with [`disableAutoSubmit()`](api/disable-auto-submit.md) when you want to pause it.
-- Call [`destroy()`](api/destroy.md) whenever a form is mounted and unmounted dynamically (SPA route changes, conditional rendering, modals).
-
----
-
-## Direct utilities
-
-The package also exposes a few pure helpers. They do not instantiate a controller — they accept plain values or a raw `HTMLFormElement` and return results.
-
-```ts
-import {
-  parseFormData,
-  validateFieldValue,
-  validateValues
-} from '@samline/forms'
-```
-
-- [`parseFormData(formElement, submitter?)`](api/parse-form-data.md) — same serializer the controller uses internally. Returns `{ data, formData }`.
-- [`validateFieldValue(field, value, rules, values)`](api/validate-field-value.md) — runs the rule set against a single value.
-- [`validateValues(values, schema)`](api/validate-values.md) — runs the rule set against a full values map.
-
-These are safe to tree-shake into any bundle and do not require a live form.
-
----
-
-## Browser registry helpers
-
-The browser IIFE bundle ships a small registry (`window.Forms`) that wraps `form()` with a `newForm` / `destroyForm` pair keyed by the form id. The same shape is available from the vanilla entrypoint as a module-level singleton called `browser`:
-
-```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: /^[^\s@]+@[^\s@]+\.[^\s@]+$/ }
-    }
-  }
-})
-
-window.Form.destroyForm('contact-form')
-console.log(window.Form.available) // { 'contact-form': FormController }
-```
-
-`browser` is an object you can spread into your own globals or use directly. Because `newForm` and `destroyForm` close over the singleton's `available` map, every spread shares the same registry — `window.Form.available`, `browser.available`, and any other spread all point to the same object, and `destroyForm` on one updates the others.
-
-If you need multiple independent registries, call the `form()` factory directly and keep your own map of controllers — `browser` is designed for the common case of one registry per page.
-
-```ts
-import { form } from '@samline/forms'
-
-const checkout = form('cart-form')
-const auth = form('login-form')
-
-// Track them yourself when you have multiple registries.
-const registries = {
-  checkout,
-  auth
-}
-```
-
-Use `form()` directly when you do not need the registry. The main entrypoint never touches `globalThis`. For a module that also registers `window.Forms`, import `@samline/forms/browser`; for a direct `<script>` tag, load the `@samline/forms/browser/global` IIFE described in [the browser guide](browser.md).
-
----
-
-## Submission examples
-
-### Intercept and send with `fetch` (default)
-
-```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.ok) throw new Error('Profile update failed')
-})
-```
-
-When `preventDefault` is omitted, valid submissions are intercepted — the browser will not navigate. Invalid submissions are always intercepted, regardless of the flag. Promise-returning handlers run concurrently and are reflected by `isSubmitting`; rejection settles that state but is not converted into a form error.
-
-### Let the browser submit natively
-
-```ts
-import { form } from '@samline/forms'
-
-const bladeForm = form('blade-form', {
-  validators: { email: { required: true } }
-})
-
-bladeForm.onSubmit(() => {
-  // Runs only when validation passes.
-  console.log('client-side hooks ran')
-}, false)
-```
-
-Pass `false` as the second argument when you want the browser’s native submit behaviour to continue after validation (Blade, ERB, plain PHP, classic Rails forms).
-
----
-
-## Next steps
-
-- Need a full options reference? See [docs/options.md](options.md).
-- Looking up the exact signature of a method? See [docs/api/index.md](api/index.md).
-- Working with the type system? See [docs/typescript.md](typescript.md).
-- Want end-to-end patterns? See [docs/recipes.md](recipes.md).

package/docs/options.md

@@ -1,326 +0,0 @@
-# Options
-
-`form(target, options?)` accepts a `FormControllerOptions` object. Every option has a default, so you can pass only what you need.
-
-```ts
-import { form } from '@samline/forms'
-
-const contactForm = form('contact-form', {
-  attributes: { filled: 'is-filled', error: 'is-invalid' },
-  autoValidate: true,
-  autoSubmit: { debounce: 500 },
-  clearErrorsOnSubmit: true,
-  clearManualErrorsOnChange: true,
-  validators: {
-    email: { required: true, pattern: /^[^\s@]+@[^\s@]+\.[^\s@]+$/ }
-  },
-  formats: {
-    phone: { type: 'phone', field: 'phone', options: { country: 'MX' } }
-  }
-})
-```
-
----
-
-## Signature
-
-```ts
-interface FormControllerOptions {
-  attributes?: Partial<VisualAttributes>
-  autoValidate?: boolean
-  autoSubmit?: boolean | AutoSubmitOptions
-  clearManualErrorsOnChange?: boolean
-  clearErrorsOnSubmit?: boolean
-  validators?: ValidationSchema
-  formats?: FieldFormatConfigMap
-}
-```
-
----
-
-## Options reference
-
-| Option | Type | Default | Behaviour |
-| --- | --- | --- | --- |
-| `attributes` | `Partial<VisualAttributes>` | `{ filled: 'css-filled', error: 'css-error' }` | Override the names of the visual attributes applied to fields. |
-| `autoValidate` | `boolean` | `true` | Run validation on construction and on handled `input` events for fields that have rules. Initial `css-filled` synchronization still runs when this is `false`. |
-| `autoSubmit` | `boolean \| AutoSubmitOptions` | `false` | Submit automatically after handled `input` events. Pass `{ debounce: ms }` to delay. |
-| `clearErrorsOnSubmit` | `boolean` | `true` | Clear all manual errors before submit validation runs. |
-| `clearManualErrorsOnChange` | `boolean` | `true` | Clear the manual error of a field when it changes. Set `false` to keep manual errors until you call [`clearErrors`](api/clear-errors.md). |
-| `validators` | `ValidationSchema` | `{}` | Field → rules map. See [docs/typescript.md](typescript.md#validationschema) and the rule reference below. |
-| `formats` | [`FieldFormatConfigMap`](typescript.md#fieldformatconfig-and-fieldformatconfigmap) | `{}` | Declarative `@samline/formatter` configuration. Each entry is applied during `form()` initialization using the same logic as [`format()`](api/format.md). Requires the optional peer dependency. |
-
----
-
-## `attributes`
-
-By default the controller adds `css-filled` to a field when it has a value, and `css-error` when it has at least one error. Override the names with `attributes`:
-
-```ts
-form('profile-form', {
-  attributes: { filled: 'is-filled', error: 'is-invalid' }
-})
-```
-
-This affects which DOM attributes the controller toggles. You provide the CSS. See [docs/css-styling.md](css-styling.md) for recipes.
-
----
-
-## `autoValidate`
-
-When `true` (default), the controller:
-
-- Runs an initial validation pass on mount for every field that has rules.
-- Validates each field on every delegated `input` event when the field has rules.
-
-Set this to `false` if you want to validate manually (e.g. only on submit, or only when the user moves past a step):
-
-```ts
-form('wizard-form', { autoValidate: false }).validate(['step-1'])
-```
-
-The initial visual-state pass is independent of validation. Prefilled controls receive `css-filled` on mount even when `autoValidate` is `false`, but no rules run and `isValidated` remains `false` until validation is requested.
-
----
-
-## `autoSubmit`
-
-When `true`, the controller schedules a native submit (`form.requestSubmit()`) on every change. Pass an `AutoSubmitOptions` object to add a debounce:
-
-```ts
-form('search-form', {
-  autoSubmit: { debounce: 300 }
-})
-```
-
-- `autoSubmit: true` — submit immediately on every change.
-- `autoSubmit: { debounce: 300 }` — submit 300ms after the last change.
-- `autoSubmit: false` — disabled at mount; enable later with [`autoSubmit()`](api/auto-submit.md).
-
-Disable at any time with [`disableAutoSubmit()`](api/disable-auto-submit.md).
-
----
-
-## `clearErrorsOnSubmit`
-
-When `true` (default), all manual errors created with [`setErrors`](api/set-errors.md) are cleared before submit validation runs. Validation errors from the current rules are computed fresh. Set this to `false` if you want manual errors to survive submit attempts:
-
-```ts
-form('profile-form', { clearErrorsOnSubmit: false })
-```
-
-This only affects manual errors. Validation errors always recompute on submit.
-
----
-
-## `clearManualErrorsOnChange`
-
-When `true` (default), the manual error of a field is cleared the moment the field changes (including changes triggered through [`setValue`](api/set-value.md)). Validation then runs and decides the new error state.
-
-Set this to `false` to keep manual errors visible until you explicitly clear them with [`clearErrors`](api/clear-errors.md):
-
-```ts
-form('profile-form', { clearManualErrorsOnChange: false })
-
-profileForm.setErrors({ email: ['This email is already in use.'] })
-// The error stays visible even after the user edits the field.
-```
-
-Use this when manual errors come from server validation and you want them to persist across edits.
-
----
-
-## `validators`
-
-A map of field names to rule sets. Each rule set is a `FieldValidationRules` object.
-
-```ts
-form('signup-form', {
-  validators: {
-    email: {
-      required: true,
-      pattern: /^[^\s@]+@[^\s@]+\.[^\s@]+$/
-    },
-    password: {
-      required: true,
-      minLength: { value: 8, message: 'Use at least 8 characters.' },
-      maxLength: 64
-    },
-    password_confirmation: {
-      required: true,
-      sameAs: {
-        value: 'password',
-        message: 'Passwords do not match.'
-      }
-    },
-    amount: {
-      required: true,
-      numeric: true,
-      min: 0,
-      max: 10000
-    },
-    'attendees[].email': {
-      each: {
-        required: true,
-        pattern: /^[^\s@]+@[^\s@]+\.[^\s@]+$/
-      }
-    }
-  }
-})
-```
-
-### Supported rules
-
-| Rule | Type | Description |
-| --- | --- | --- |
-| `required` | `boolean \| { value: boolean; message?: string }` | Field must have a non-empty value. |
-| `minLength` | `number \| { value: number; message?: string }` | Minimum string length (for checkbox groups, the minimum number of selected items). |
-| `maxLength` | `number \| { value: number; message?: string }` | Maximum string length (for checkbox groups, the maximum number of selected items). |
-| `pattern` | `RegExp \| { value: RegExp; message?: string }` | String must match the regular expression. Skipped when the field is empty. |
-| `numeric` | `boolean \| { value: boolean; message?: string }` | Non-empty value must be an ordinary signed decimal. |
-| `min` | `number \| { value: number; message?: string }` | Non-empty numeric value must be greater than or equal to the inclusive bound. |
-| `max` | `number \| { value: number; message?: string }` | Non-empty numeric value must be less than or equal to the inclusive bound. |
-| `sameAs` | `string \| { value: string; message?: string }` | Non-empty value must equal the named field. Changing the named field automatically revalidates this field. |
-| `dependsOn` | `string \| string[]` | Names fields whose changes should revalidate this field. Useful for custom cross-field validators; it does not itself add a validation error. |
-| `each` | `ValueValidationRules` | Applies value-level rules independently to every member/control in a collection. |
-| `validate` | `FieldValidator \| FieldValidator[]` | Custom validators. Return a string to push an error, or `null` / `undefined` / `true` to pass. Return `false` to push a generic `"Validation failed."` message. |
-
-Built-in rules accept either a plain value or a `{ value, message }` object. Use the object form when you want a custom error message per rule.
-
-`numeric`, `min`, and `max` trim surrounding whitespace and accept only ordinary signed decimal syntax, such as `12`, `-3.5`, `+4`, `.75`, or `10.`. They reject exponent notation, hexadecimal, `Infinity`, `NaN`, and formatted values containing separators. Empty values skip all three rules; add `required` when emptiness should fail. `min` and `max` are inclusive and also reject a non-numeric value even when `numeric` is omitted.
-
-Their default messages are `"Value must be a number."`, `"Minimum value is N."`, and `"Maximum value is N."` respectively.
-
-### Matching fields with `sameAs`
-
-Declare `sameAs` on the field that owns the error, normally the confirmation field:
-
-```ts
-form('signup-form', {
-  validators: {
-    password: { required: true, minLength: 8 },
-    password_confirmation: {
-      required: true,
-      sameAs: {
-        value: 'password',
-        message: 'Passwords do not match.'
-      }
-    }
-  }
-})
-```
-
-The controller records that `password_confirmation` depends on `password`. Once validation is active, input in either field validates the confirmation, including updates made through `setValue()`. Validation is active immediately with the default `autoValidate: true`; with `autoValidate: false`, it begins after the first `validate()` or `revalidate()` call. You do not need `watch()` or a manual `revalidate()` call for this dependency.
-
-Important behavior:
-
-- `sameAs` is skipped until both fields have non-empty values. Use `required` separately when either field is mandatory.
-- Strings use exact, case-sensitive equality. Arrays use ordered item equality, so `['a', 'b']` does not equal `['b', 'a']`. File entries compare by `File` object identity.
-- The referenced name must be the exact HTML field name. Wildcards and inferred `_confirmation` names are not supported.
-- Put the rule on the confirmation field only in most forms. Putting reciprocal rules on both fields is cycle-safe, but both fields will own and display the same mismatch error.
-- Dependency cycles do not recurse. The controller resolves the affected fields with a visited set and validates each field at most once per input event.
-
-### Custom cross-field dependencies with `dependsOn`
-
-Custom validators can read any value, but the controller cannot infer those reads. Declare each source with `dependsOn` so changing it revalidates the field that owns the custom validator:
-
-```ts
-form('shipping-form', {
-  validators: {
-    method: { required: true },
-    country: {
-      dependsOn: 'method',
-      validate: ({ value, values }) =>
-        values.method === 'domestic' && value !== 'US'
-          ? 'Domestic shipping requires a US address.'
-          : null
-    }
-  }
-})
-```
-
-Names are exact HTML field names. A string array declares multiple sources. Like `sameAs`, dependencies become reactive once validation is active, and transitive chains and cycles are deduplicated so each affected field runs at most once per input event. `dependsOn` is controller metadata only: the pure validation helpers evaluate the supplied snapshot without tracking changes.
-
-### Validate every collection member with `each`
-
-Use `each` for repeated controls, checkbox groups, or other fields whose value is a collection:
-
-```ts
-form('attendees-form', {
-  validators: {
-    'attendees[].email': {
-      minLength: { value: 1, message: 'Add at least one attendee.' },
-      each: {
-        required: true,
-        pattern: {
-          value: /^[^\s@]+@[^\s@]+\.[^\s@]+$/,
-          message: 'Enter a valid attendee email.'
-        }
-      }
-    }
-  }
-})
-```
-
-Rules outside `each` validate the aggregate value. Rules inside `each` validate members independently. In a bound controller, `css-error` and `aria-invalid="true"` are applied only to the controls whose `each` rules fail; an aggregate or manual field error still marks every control in the field. Public errors remain `Record<string, string[]>`: item messages are flattened under the field name in member order rather than exposing a nested error shape.
-
-### Custom validators
-
-```ts
-form('checkout-form', {
-  validators: {
-    card: {
-      validate: ({ value, field }) => {
-        if (typeof value !== 'string') return `${field} is required.`
-        if (!/^\d{16}$/.test(value.replace(/\s+/g, ''))) {
-          return 'Card number must be 16 digits.'
-        }
-        return null
-      }
-    }
-  }
-})
-```
-
-The custom validator receives `{ field, value, values }` and runs after the built-in rules. During `each`, it also receives the optional concrete `element` and zero-based `index`. See [`FieldValidationContext`](typescript.md#fieldvalidationcontext).
-
----
-
-## Defaults at a glance
-
-```ts
-const DEFAULT_ATTRIBUTES = {
-  filled: 'css-filled',
-  error: 'css-error'
-}
-
-const DEFAULT_OPTIONS = {
-  autoValidate: true,
-  clearErrorsOnSubmit: true,
-  clearManualErrorsOnChange: true
-}
-```
-
-Everything else (`autoSubmit`, `validators`, `formats`, partial `attributes`) defaults to neutral / empty values.
-
----
-
-## `formats`
-
-Declarative way to bind one or more `@samline/formatter` pipelines at construction time. Each entry is applied during `form()` initialization using the same logic as [`format()`](api/format.md).
-
-```ts
-import { form } from '@samline/forms'
-
-const checkout = form('checkout', {
-  formats: {
-    phone:  { type: 'phone',      field: 'phone',  options: { country: 'MX' } },
-    card:   { type: 'creditCard', field: 'card' },
-    amount: { type: 'numeral',    field: 'amount', options: { prefix: '$' } }
-  }
-})
-```
-
-The map key is just an identifier — the **canonical** field name lives in `FieldFormatConfig.field`. `format()` renames the visible to `<field>_displayed` (or `config.displayField`) on first run and creates a hidden `<input type="hidden" name="<field>">` that carries the raw value. Both names are first-class in the controller's API. See [`FieldFormatConfigMap`](typescript.md#fieldformatconfig-and-fieldformatconfigmap) for the full type, and the [formatting recipe](recipes.md#13-format-inputs-with-samlineformatter) for an end-to-end example.
-
-Module builds require `@samline/formatter` for `formats`. When it is missing, the module instance logs one cached `console.error`, asynchronously rolls back affected visible/mirror pairs, and keeps the controller usable. The standalone global IIFE bundles the formatter.