@samline/forms 2.7.2 → 2.8.0

package/docs/api/clear-errors.md

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

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

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

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

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