@samline/forms 2.4.0 → 2.7.0

package/docs/api/add-cleanup.md

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

package/docs/api/append.md

@@ -0,0 +1,96 @@
+# `append(options)`
+
+Inserts a DOM node into the bound form. Useful for rendering banners, hints, or summary blocks that should live inside the `<form>` element so they are reset together with the form.
+
+## Signature
+
+```ts
+append(options: AppendContentOptions): HTMLElement | null
+```
+
+```ts
+interface AppendContentOptions {
+  tag: keyof HTMLElementTagNameMap
+  content: string
+  class?: string
+  atStart?: boolean
+}
+```
+
+## Parameters
+
+| Name | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `options.tag` | `keyof HTMLElementTagNameMap` | yes | — | The HTML tag to create (e.g. `'div'`, `'p'`, `'output'`). |
+| `options.content` | `string` | yes | — | `innerHTML` content for the new node. |
+| `options.class` | `string` | no | — | Class name. If a node with the same first class already exists inside the form, it is removed first. |
+| `options.atStart` | `boolean` | no | `false` | When `true`, the node is inserted at the start of the form. When `false`, it is appended at the end. |
+
+## Returns
+
+The created `HTMLElement`, or `null` when the controller has no bound form.
+
+## Behaviour
+
+- Clears the field cache (because the form subtree changed).
+- If `class` is provided and a descendant of the form matches the first class in the string, that descendant is removed before the new node is inserted. This gives you a single “render or replace” pattern.
+- The created node receives `innerHTML = content`. The content is trusted HTML; escape it yourself if it comes from user input.
+
+## Examples
+
+### Render a static hint
+
+```ts
+import { form } from '@samline/forms'
+
+const signup = form('signup-form')
+
+signup.append({
+  tag: 'p',
+  content: 'We will never share your email.',
+  class: 'signup-hint'
+})
+```
+
+### Render a live region for validation messages
+
+```ts
+const profile = form('profile-form')
+
+profile.append({
+  tag: 'output',
+  content: '',
+  class: 'profile-status',
+  atStart: true
+})
+
+profile.subscribe(state => {
+  const status = profile.element?.querySelector('.profile-status')
+  if (status) status.textContent = state.isValid ? 'Looks good' : 'Please fix errors'
+})
+```
+
+### Replace a previous banner
+
+```ts
+import { form } from '@samline/forms'
+
+const contact = form('contact-form')
+
+contact.append({ tag: 'div', content: 'Draft saved.', class: 'banner banner-info' })
+
+// Some time later — replaces the previous banner instead of stacking.
+contact.append({ tag: 'div', content: 'Draft published.', class: 'banner banner-success' })
+```
+
+## Edge cases
+
+- **Only the first class token is used for deduplication.** If you pass `'a b'`, the controller searches for `.a` inside the form and removes it. The other classes are still applied to the new node.
+- **The returned element is a live reference.** It stays in the DOM until you remove it or until [`reset`](reset.md) is called (which strips `css-filled` / `css-error` attributes but does not remove nodes you added).
+- **Appending does not trigger validation, watchers, or autoSubmit.** It only mutates the DOM.
+- **Calling `append` from a non-form controller** returns `null` and does nothing.
+
+## Related
+
+- [`reset`](reset.md) — strips visual attributes but not custom nodes.
+- [`destroy`](destroy.md) — removes listeners and observer but does not remove custom nodes.

package/docs/api/auto-submit.md

@@ -0,0 +1,91 @@
+# `autoSubmit(options?)`
+
+Enables native auto-submit. Every change to a tracked field triggers `form.requestSubmit()`. Optionally debounced.
+
+## Signature
+
+```ts
+autoSubmit(options?: boolean | AutoSubmitOptions): FormController
+```
+
+## Parameters
+
+| Name | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `options` | `boolean \| AutoSubmitOptions` | no | `true` | Pass `true` to enable, `false` to disable, or an `{ debounce }` object to delay. |
+
+```ts
+interface AutoSubmitOptions {
+  debounce?: number
+}
+```
+
+## Returns
+
+The same [`FormController`](../typescript.md#formcontroller) — chainable.
+
+## Behaviour
+
+- `autoSubmit()` or `autoSubmit(true)` — enables auto-submit immediately on every change.
+- `autoSubmit({ debounce: ms })` — schedules `form.requestSubmit()` `ms` milliseconds after the most recent change. Subsequent changes within the debounce window reset the timer.
+- `autoSubmit(false)` — disables auto-submit (equivalent to [`disableAutoSubmit()`](disable-auto-submit.md)).
+
+When auto-submit fires, the native submit is invoked. If the form is invalid, the controller’s `submit` listener prevents the browser from navigating. If the form is valid, the registered [`onSubmit`](on-submit.md) handlers run as usual.
+
+Subscribers are notified when autoSubmit is enabled, disabled, or its debounce changes (because the state’s `autoSubmit` field changes).
+
+## Examples
+
+### Autosave on every change
+
+```ts
+import { form } from '@samline/forms'
+
+const draft = form('draft-form', {
+  validators: { title: { required: true } }
+})
+
+draft.autoSubmit()
+```
+
+### Debounced search
+
+```ts
+import { form } from '@samline/forms'
+
+const search = form('search-form', {
+  autoSubmit: { debounce: 300 }
+})
+
+search.onSubmit(async (_form, data) => {
+  await fetch('/search', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(data)
+  })
+})
+```
+
+### Toggle at runtime
+
+```ts
+const formEl = form('search-form')
+
+document.querySelector('#realtime')?.addEventListener('change', event => {
+  const enabled = (event.target as HTMLInputElement).checked
+  formEl.autoSubmit(enabled ? { debounce: 250 } : false)
+})
+```
+
+## Edge cases
+
+- **The submit is invoked via `form.requestSubmit()`** when available, falling back to clicking a submit button or `form.submit()` otherwise.
+- **`autoSubmit` does not validate.** Validation runs as part of the submit pipeline, so an invalid form will not navigate and your [`onSubmit`](on-submit.md) handler will not run.
+- **The debounce timer is cancelled by [`disableAutoSubmit()`](disable-auto-submit.md) and [`destroy()`](destroy.md).**
+- **Setting `autoSubmit` from `options` and from the method can both run at mount time** — the method is called last, so it wins.
+
+## Related
+
+- [`disableAutoSubmit`](disable-auto-submit.md) — turn auto-submit off.
+- [`onSubmit`](on-submit.md) — submit handlers.
+- [`options.autoSubmit`](../options.md#autosubmit) — mount-time configuration.

package/docs/api/clear-errors.md

@@ -0,0 +1,69 @@
+# `clearErrors(fields?)`
+
+Removes manual errors. Validation errors from rules are not touched.
+
+## Signature
+
+```ts
+clearErrors(): FormController
+clearErrors(fields: string[]): FormController
+```
+
+## Parameters
+
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `fields` | `string[]` | no | When provided, only the listed fields are cleared. When omitted, every manual error is cleared. |
+
+## Returns
+
+The same [`FormController`](../typescript.md#formcontroller) — chainable.
+
+## Behaviour
+
+- Only manual errors (set via [`setErrors`](set-errors.md)) are removed. Validation errors from rules are recomputed the next time validation runs.
+- Visual attributes are re-synced for the affected fields — `css-error` is removed when no errors remain for a field.
+- Subscribers are notified.
+
+## Examples
+
+### Clear a single field
+
+```ts
+import { form } from '@samline/forms'
+
+const profile = form('profile-form')
+
+profile.setErrors({ email: ['Already in use.'] })
+
+profile.clearErrors(['email'])
+```
+
+### Clear everything
+
+```ts
+profile.setErrors({
+  email: ['Already in use.'],
+  password: ['Too weak.']
+})
+
+profile.clearErrors()
+```
+
+### Clear before re-running validation
+
+```ts
+profile.clearErrors()
+profile.validate()
+```
+
+## Edge cases
+
+- **Validation errors are not cleared by `clearErrors`.** They live in a separate map and are only cleared by [`reset`](reset.md) or by a successful re-validation of the field.
+- **`clearErrors` on a field with no manual error is a no-op** — the chain still returns the controller.
+- **Passing an empty array `clearErrors([])` does nothing.** Use `clearErrors()` to clear everything.
+
+## Related
+
+- [`setErrors`](set-errors.md) — push manual errors.
+- [`reset`](reset.md) — clear every error and reset field values.

package/docs/api/destroy.md

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

package/docs/api/disable-auto-submit.md

@@ -0,0 +1,65 @@
+# `disableAutoSubmit()`
+
+Turns auto-submit off and cancels any pending debounce timer.
+
+## Signature
+
+```ts
+disableAutoSubmit(): FormController
+```
+
+## Returns
+
+The same [`FormController`](../typescript.md#formcontroller) — chainable.
+
+## Behaviour
+
+- Sets `state.autoSubmitEnabled` to `false`.
+- Cancels `state.autoSubmitTimer` if one is pending.
+- Notifies subscribers (because the state’s `autoSubmit` field changes).
+
+Equivalent to calling [`autoSubmit(false)`](auto-submit.md).
+
+## Examples
+
+### Pause autosave while typing resumes
+
+```ts
+import { form } from '@samline/forms'
+
+const draft = form('draft-form', { autoSubmit: { debounce: 800 } })
+
+document.querySelector('#pause')?.addEventListener('click', () => {
+  draft.disableAutoSubmit()
+})
+
+document.querySelector('#resume')?.addEventListener('click', () => {
+  draft.autoSubmit({ debounce: 800 })
+})
+```
+
+### Disable on blur
+
+```ts
+import { form } from '@samline/forms'
+
+const search = form('search-form', { autoSubmit: { debounce: 250 } })
+
+search.element?.addEventListener('focusin', () => {
+  search.autoSubmit({ debounce: 250 })
+})
+
+search.element?.addEventListener('focusout', () => {
+  search.disableAutoSubmit()
+})
+```
+
+## Edge cases
+
+- **Re-enabling later requires calling [`autoSubmit()`](auto-submit.md) again.** The previous debounce configuration is not preserved.
+- **A pending debounce timer is removed**, but the timer was already scheduled; nothing fires for it.
+
+## Related
+
+- [`autoSubmit`](auto-submit.md) — enable / configure.
+- [`destroy`](destroy.md) — also cancels any pending debounce.

package/docs/api/element.md

@@ -0,0 +1,78 @@
+# `element` and `f`
+
+Read-only getters that return the bound `HTMLFormElement`, or `null` if the binding target was unresolved at construction time.
+
+## Signatures
+
+```ts
+interface FormController {
+  readonly element: HTMLFormElement | null
+  readonly f: HTMLFormElement | null
+  readonly options: FormControllerOptions
+}
+```
+
+- `element` — the bound form.
+- `f` — alias of `element`, kept short for fluent setup.
+- `options` — the resolved options object (defaults merged with user-provided values).
+
+## Returns
+
+`HTMLFormElement | null`. `null` when the target passed to [`form()`](form.md) did not resolve to a form.
+
+## Examples
+
+### Read the bound form
+
+```ts
+import { form } from '@samline/forms'
+
+const profile = form('profile-form')
+
+if (profile.element) {
+  profile.element.classList.add('mounted')
+}
+```
+
+### Use the short alias
+
+```ts
+import { form } from '@samline/forms'
+
+const profile = form('profile-form')
+
+profile.f?.querySelector('[data-status]')?.setAttribute('data-state', 'ready')
+```
+
+### Read the resolved options
+
+```ts
+import { form } from '@samline/forms'
+
+const profile = form('profile-form', {
+  autoValidate: false,
+  attributes: { error: 'is-invalid' },
+  formats: {
+    phone: { type: 'phone', field: 'phone', options: { country: 'MX' } }
+  }
+})
+
+profile.options.autoValidate            // false (overridden)
+profile.options.autoSubmit              // false (default)
+profile.options.clearErrorsOnSubmit     // true (default)
+profile.options.attributes.error        // 'is-invalid'
+profile.options.attributes.filled       // 'css-filled' (default)
+profile.options.formats.phone           // FieldFormatConfig (overridden)
+```
+
+The `formats` key is the declarative counterpart to [`format()`](format.md) — see [the option reference](../options.md#formats) for the full shape.
+
+## Edge cases
+
+- The getter returns `null` when the target was `null`, `undefined`, a non-existent id, or an element that is not an `HTMLFormElement`.
+- The reference is the same one the controller uses internally — do not replace the form node, or the controller will keep listening to the original.
+
+## Related
+
+- [`form(target, options?)`](form.md) — bind a controller.
+- [`destroy`](destroy.md) — tear the controller down.

package/docs/api/form.md

@@ -0,0 +1,156 @@
+# `form(target, options?)`
+
+Creates a new controller bound to a form. This is the main entry point of `@samline/forms`.
+
+## Signature
+
+```ts
+function form(
+  target: FormTarget,
+  options?: FormControllerOptions
+): FormController
+```
+
+## Parameters
+
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `target` | [`FormTarget`](../typescript.md#formtarget) | yes | What to bind to: a string id, an `HTMLFormElement`, a ref-like `{ current }` object, or `null` / `undefined`. |
+| `options` | [`FormControllerOptions`](../typescript.md#formcontrolleroptions) | no | Controller configuration. See [docs/options.md](../options.md). |
+
+## Returns
+
+A [`FormController`](../typescript.md#formcontroller) — chainable for every method that does not return data or an unsubscribe function.
+
+## Binding modes
+
+### By id string
+
+```ts
+import { form } from '@samline/forms'
+
+const profile = form('profile-form')
+```
+
+The string is passed to `document.getElementById`. If no element is found, or the found element is not an `HTMLFormElement`, the controller is created but `controller.element` is `null` and most methods become no-ops.
+
+### By `HTMLFormElement`
+
+```ts
+const element = document.querySelector<HTMLFormElement>('#profile-form')
+const profile = form(element)
+```
+
+Useful when you already have the element from a `querySelector` call.
+
+### By ref-like object
+
+```ts
+const ref = { current: document.querySelector<HTMLFormElement>('#profile-form') }
+const profile = form(ref)
+```
+
+The controller reads `target.current` only at construction time. If you mount the form later, recreate the controller or call `destroy()` and re-bind.
+
+### By `null` / `undefined`
+
+```ts
+const profile = form()
+```
+
+Allowed for type-system ergonomics. The resulting controller has `element === null` and is effectively inert.
+
+## Behaviour
+
+On creation the controller:
+
+1. Resolves the form element.
+2. Merges the provided options with defaults (`autoValidate: true`, `clearErrorsOnSubmit: true`, `clearManualErrorsOnChange: true`, `attributes: { filled: 'css-filled', error: 'css-error' }`).
+3. Wires delegated `input` and `submit` listeners, including controls associated through `form="id"`.
+4. Starts a `MutationObserver` on the form subtree to track dynamic fields.
+5. Optionally enables [`autoSubmit`](../api/auto-submit.md) when `options.autoSubmit` is truthy.
+6. Synchronizes initial `css-filled` state for every tracked control, including when `autoValidate` is disabled.
+7. Runs an initial validation pass only if `autoValidate` is enabled.
+
+## Examples
+
+### Minimal setup
+
+```ts
+import { form } from '@samline/forms'
+
+const contact = form('contact-form')
+
+contact.onSubmit(async (_element, _data, formData) => {
+  await fetch('/api/contact', { method: 'POST', body: formData })
+})
+```
+
+### With validators and options
+
+```ts
+import { form } from '@samline/forms'
+
+const signup = form('signup-form', {
+  attributes: { filled: 'is-filled', error: 'is-invalid' },
+  autoValidate: true,
+  autoSubmit: { debounce: 600 },
+  clearManualErrorsOnChange: false,
+  validators: {
+    email: {
+      required: { value: true, message: 'Email is required.' },
+      pattern: {
+        value: /^[^\s@]+@[^\s@]+\.[^\s@]+$/,
+        message: 'Enter a valid email address.'
+      }
+    },
+    password: { required: true, minLength: 8 }
+  },
+  formats: {
+    phone: { type: 'phone', field: 'phone', options: { country: 'MX' } }
+  }
+})
+```
+
+### Bind later via ref
+
+```ts
+import { form } from '@samline/forms'
+
+const profileRef = { current: null as HTMLFormElement | null }
+
+const profile = form(profileRef)
+
+document.querySelector('#mount')?.appendChild(document.createElement('form'))
+profileRef.current = document.querySelector<HTMLFormElement>('#mount form')
+
+// Re-bind because the controller captured `current` at construction time.
+profile.destroy()
+form(profileRef)
+```
+
+## Edge cases
+
+- **The id is resolved once.** If the DOM element with that id is replaced, the controller keeps listening to the original element. Recreate the controller if you re-render the form.
+- **`null` / `undefined` targets** are accepted and produce an inert controller. The chainable methods still return the controller, so they are safe to call as no-ops.
+- **Reusing a target across multiple controllers** is supported but they each install their own listeners — call [`destroy()`](destroy.md) on the previous one to avoid duplicate work.
+- **`autoValidate: false` disables the initial rule pass, not visual initialization.** Prefilled fields still receive `css-filled`; no validation errors are produced and `isValidated` remains `false`.
+- **`createFormController` is also exported** as the lower-level factory; prefer `form` for ergonomic imports.
+
+## `createFormController`
+
+```ts
+function createFormController(
+  target: FormTarget,
+  options?: FormControllerOptions
+): FormController
+```
+
+This is the factory used by `form()` and accepts the same arguments. It is exported for integrations that prefer an explicit constructor-style name.
+
+## Related
+
+- [`FormController`](../typescript.md#formcontroller) — the returned controller type.
+- [`destroy`](destroy.md) — tear the controller down.
+- [`addCleanup`](add-cleanup.md) — attach integration cleanup to the controller lifecycle.
+- [docs/options.md](../options.md) — every option in detail.