@samline/forms 2.3.4 → 2.6.0

package/docs/api/revalidate.md

@@ -0,0 +1,50 @@
+# `revalidate(fields?)`
+
+Alias of [`validate`](validate.md) kept separate for readability at call sites that want to express “re-run validation now”.
+
+## Signature
+
+```ts
+revalidate(): ValidationResult
+revalidate(fields: string[]): ValidationResult
+```
+
+## Parameters
+
+Same as [`validate`](validate.md).
+
+## Returns
+
+Same as [`validate`](validate.md) — a [`ValidationResult`](../typescript.md#validationresult).
+
+## Behaviour
+
+Identical to [`validate`](validate.md). The two methods share the same internal implementation.
+
+## When to use which
+
+Use `validate` when you are running validation as part of an initial check. Use `revalidate` when you are explicitly asking the controller to recompute validation after a state change (e.g. after `setErrors`, after async data loads, after resetting partial form state).
+
+```ts
+import { form } from '@samline/forms'
+
+const profile = form('profile-form', {
+  validators: { email: { required: true } }
+})
+
+// Initial check.
+profile.validate()
+
+// After a manual state change:
+profile.setValue('email', '')
+profile.revalidate(['email'])
+```
+
+## Edge cases
+
+- **`revalidate` is not a different operation from `validate`.** Pick whichever name reads better at the call site.
+- **Both methods mark the form as validated** the first time they are called.
+
+## Related
+
+- [`validate`](validate.md) — same implementation, different name.

package/docs/api/set-errors.md

@@ -0,0 +1,97 @@
+# `setErrors(fields)`
+
+Pushes manual errors into the form. The typical use case is surfacing server-side validation feedback after a failed `fetch`.
+
+## Signature
+
+```ts
+setErrors(fields: string[]): FormController
+setErrors(fields: FormErrors): FormController
+```
+
+## Parameters
+
+| Overload | Type | Description |
+| --- | --- | --- |
+| Array form | `string[]` | Each entry is treated as a field name. The error message defaults to `'Invalid value.'`. |
+| Map form | [`FormErrors`](../typescript.md#formerrors) | Map from field name to one or more error messages. |
+
+## Returns
+
+The same [`FormController`](../typescript.md#formcontroller) — chainable.
+
+## Behaviour
+
+- Manual errors are merged with existing manual errors — existing entries for other fields are preserved.
+- Validation errors from rules are not affected: validation errors and manual errors live in separate maps and are merged only when reading state.
+- Visual attributes are re-synced for the affected fields, so `css-error` is added to each.
+- Subscribers are notified.
+
+## Examples
+
+### Array form (generic message)
+
+```ts
+import { form } from '@samline/forms'
+
+const profile = form('profile-form')
+
+profile.setErrors(['email', 'password'])
+// state.errors.email    -> ['Invalid value.']
+// state.errors.password -> ['Invalid value.']
+```
+
+### Map form (per-field messages)
+
+```ts
+profile.setErrors({
+  email: ['This email is already in use.'],
+  password: ['Too weak. Use at least 8 characters.']
+})
+```
+
+### Map form with multiple errors per field
+
+```ts
+profile.setErrors({
+  password: [
+    'Too weak.',
+    'Must contain a number.',
+    'Must contain a symbol.'
+  ]
+})
+```
+
+### Surface server errors after a failed submit
+
+```ts
+import { form } from '@samline/forms'
+
+const signup = form('signup-form', {
+  clearManualErrorsOnChange: false
+})
+
+signup.onSubmit(async (_element, _data, formData) => {
+  const response = await fetch('/signup', { method: 'POST', body: formData })
+
+  if (!response.ok) {
+    const { fieldErrors } = await response.json()
+    signup.setErrors(fieldErrors)
+  } else {
+    signup.clearErrors()
+  }
+})
+```
+
+## Edge cases
+
+- **Manual errors are cleared by default on the next change** of the affected field. Pass `clearManualErrorsOnChange: false` to keep them until you call [`clearErrors`](clear-errors.md).
+- **The array form uses the literal string `'Invalid value.'`.** Use the map form when you need custom messages.
+- **`setErrors` does not run validation.** Validation errors are computed independently by [`validate`](validate.md).
+- **Setting an empty object `setErrors({})` clears nothing** — it just doesn’t add new errors. Use [`clearErrors`](clear-errors.md) to remove existing manual errors.
+
+## Related
+
+- [`clearErrors`](clear-errors.md) — remove manual errors.
+- [`validate`](validate.md) — run validation and read the result.
+- [`options.clearManualErrorsOnChange`](../options.md#clearmanualerrorsonchange).

package/docs/api/set-value.md

@@ -0,0 +1,120 @@
+# `setValue(name, value)`
+
+Writes a value into a field and dispatches the correct DOM event so watchers, validators, and visual state run as if a user typed.
+
+## Signature
+
+```ts
+setValue(name: string, value: unknown): FormController
+```
+
+## Parameters
+
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `name` | `string` | yes | The `name` attribute of the target field. |
+| `value` | `unknown` | yes | The value to write. Coerced per field type. |
+
+## Returns
+
+The same [`FormController`](../typescript.md#formcontroller) — chainable. Returns the controller unchanged when the field does not exist.
+
+## Behaviour by field type
+
+| Field type | How `value` is applied |
+| --- | --- |
+| `<input>` (text-like: `text`, `email`, `password`, …) | `String(value)` is assigned to `field.value`. |
+| `<input>` (text-like) with `name="foo[]"` receiving an array | One array element per input, in order: `input[i].value = String(value[i])`. Inputs beyond the array length are cleared to `''`; extra array elements (more elements than inputs) are dropped. |
+| `<input type="checkbox">` (single) | `field.checked = String(value) === field.value`. |
+| `<input type="checkbox">` (group with the same `name`) | Each checkbox is checked if `Array.isArray(value)` includes its `value`, otherwise all unchecked. |
+| `<input type="radio">` (group with the same `name`) | The radio whose `value` matches `String(value)` is checked. |
+| `<input type="file">` | File inputs are read-only — `setValue` cannot assign a file. Passing `[]` clears the input. |
+| `<select>` (single) | `String(value)` must match an option value. |
+| `<select multiple>` | Every option whose value occurs in the supplied array is selected. A scalar selects its matching option. |
+| `<select>` (group with `name="foo[]"`) receiving an array | One array element per select, in order: `select[i].value = String(value[i])`. Inputs beyond the array length are cleared to `''`; extra array elements are dropped. |
+| `<textarea>` | `String(value)` is assigned to `field.value`. |
+| `<textarea>` (group with `name="foo[]"`) receiving an array | One array element per textarea, in order: `textarea[i].value = String(value[i])`. Inputs beyond the array length are cleared to `''`; extra array elements are dropped. |
+
+After writing, the controller dispatches one synthetic `input` event on the **first** matching field.
+
+The synthetic event flows through the form-level delegated listener, so the rest of the pipeline runs as if the user had typed: manual errors are cleared (default), validation runs (if `autoValidate`), watchers fire, subscribers are notified, and `autoSubmit` is scheduled.
+
+## Examples
+
+### Set a text value
+
+```ts
+import { form } from '@samline/forms'
+
+const contact = form('contact-form')
+contact.setValue('email', 'hello@example.com')
+```
+
+### Toggle checkboxes
+
+```ts
+const signup = form('signup-form')
+
+// Multiple values — array form.
+signup.setValue('interests', ['design', 'code'])
+
+// Single value — string form.
+signup.setValue('terms', 'yes')
+```
+
+### Select a radio
+
+```ts
+const shipping = form('shipping-form')
+shipping.setValue('method', 'express')
+```
+
+### Reset a file input
+
+```ts
+const upload = form('upload-form')
+upload.setValue('attachments', [])
+```
+
+### Chain with other setup
+
+```ts
+form('contact-form')
+  .setValue('subject', 'Question about pricing')
+  .setValue('message', 'Hello,')
+```
+
+### Distribute values across a `name="foo[]"` group
+
+```ts
+const signup = form('signup-form')
+
+// Each input gets one array element, in order. With two inputs and
+// `name="docusign_email[]"`, this writes the first email to the first
+// input and the second email to the second input.
+signup.setValue('docusign_email[]', ['a@example.com', 'b@example.com'])
+
+// When the array is shorter than the input count, the surplus inputs
+// are cleared to ''.
+signup.setValue('docusign_email[]', ['a@example.com'])
+
+// When the array is longer than the input count, the extra array
+// elements are dropped — there's no input to write to.
+signup.setValue('docusign_email[]', ['a@example.com', 'b@example.com', 'c@example.com'])
+```
+
+## Edge cases
+
+- **The synthetic event is dispatched only on the first matching field.** For radio/checkbox groups, this is intentional — the event bubbles, and the controller only needs to react once.
+- **Passing `null` or `undefined` writes an empty string.** This is treated as a value, not as “skip”, so the field becomes empty and watchers fire.
+- **`setValue` is a no-op for unknown field names** — the chain still works, but no event fires and no watchers run.
+- **`setValue` cannot assign to `<input type="file">`.** Browsers do not allow programmatic file assignment for security reasons. Use a DataTransfer or a real file picker.
+- **The `name="foo[]"` suffix is the explicit opt-in for multi-value inputs.** A field with the suffix that receives an array distributes one element per input (surplus inputs are cleared, surplus array elements are dropped). Bare names — `name="foo"` with multiple inputs — keep the original broadcast semantics and receive the same value on every matching input.
+- **Manual errors for the field are cleared by default** (because the synthetic event triggers the delegated handler). Pass `clearManualErrorsOnChange: false` to keep them.
+
+## Related
+
+- [`getValue`](get-value.md) — read the current value.
+- [`getField`](get-field.md) — read the underlying DOM element.
+- [`reset`](reset.md) — restore the form’s initial values.
+- [`format`](format.md) — when a field is formatted, `setValue('<field>', x)` writes the raw to the hidden mirror and reformats the visible; `setValue('<field>_displayed', x)` writes the formatted to the visible and recomputes the raw. See [the mirror convention](format.md#the-mirror-convention).

package/docs/api/subscribe.md

@@ -0,0 +1,91 @@
+# `subscribe(listener)`
+
+Registers a listener that fires immediately with the current state and at controller notification points. Returns an unsubscribe function.
+
+## Signature
+
+```ts
+subscribe(listener: FormStateListener): () => void
+```
+
+## Parameters
+
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `listener` | [`FormStateListener`](../typescript.md#formstatelistener) | yes | Callback invoked with the full state snapshot. |
+
+## Returns
+
+A function. Calling it removes the listener.
+
+## Behaviour
+
+- The listener fires **once synchronously** on registration with the current [`FormStateSnapshot`](../typescript.md#formstatesnapshot).
+- It then fires at explicit controller notification points. This is not a proxy around every internal assignment.
+- Multiple subscribers are supported. They run in registration order.
+
+State mutations that fire subscribers include:
+
+- Any `input` event on a tracked field.
+- [`setValue`](set-value.md).
+- [`setErrors`](set-errors.md) and [`clearErrors`](clear-errors.md).
+- [`autoSubmit`](auto-submit.md) and [`disableAutoSubmit`](disable-auto-submit.md).
+- [`reset`](reset.md).
+- Submit attempts, after their validation pass and `submitCount` update.
+- `MutationObserver`-detected DOM changes.
+
+Direct [`validate`](validate.md) and [`revalidate`](revalidate.md) calls update validation state and visual attributes but do not independently notify subscribers. Use their returned result when synchronous rendering is required.
+
+## Examples
+
+### Mirror state into a view layer
+
+```ts
+import { form } from '@samline/forms'
+
+const profile = form('profile-form')
+
+const unsubscribe = profile.subscribe(state => {
+  document.querySelector('#status')!.textContent = state.isValid ? 'Ready' : 'Errors'
+  document.querySelector('#counter')!.textContent = String(state.submitCount)
+})
+
+window.addEventListener('beforeunload', unsubscribe)
+```
+
+### React to a specific field
+
+```ts
+const signup = form('signup-form')
+
+signup.subscribe(state => {
+  const password = state.values.password
+  const passwordError = state.errors.password?.[0]
+  document.querySelector('#password-hint')!.textContent =
+    passwordError ?? (typeof password === 'string' && password.length > 0 ? 'OK' : 'Empty')
+})
+```
+
+### Track submit attempts
+
+```ts
+const profile = form('profile-form')
+
+profile.subscribe(state => {
+  if (state.submitCount > 0 && !state.isValid) {
+    console.warn('submit attempt failed:', state.submitCount)
+  }
+})
+```
+
+## Edge cases
+
+- **The listener is invoked with a fresh snapshot** on every fire — it is safe to store the reference for the duration of one call.
+- **Subscribers do not receive partial / incremental updates.** Each fire carries the whole snapshot.
+- **Subscribers and watchers are independent.** A field-level change fires both the watchers for that field and every subscriber.
+- **Unsubscribing does not detach the listener immediately if it is currently iterating.** JavaScript’s `Set` semantics guarantee no skips — once the unsubscribe returns, future mutations will not invoke that listener.
+
+## Related
+
+- [`watch`](watch.md) and [`observe`](observe.md) — per-field reactions.
+- [`getState`](get-state.md) — read the current snapshot synchronously.

package/docs/api/unwatch.md

@@ -0,0 +1,74 @@
+# `unwatch(field?, callback?)`
+
+Removes watched callbacks. Three overloads, distinguished by the arguments you pass.
+
+## Signature
+
+```ts
+unwatch(): FormController
+unwatch(field: string): FormController
+unwatch(field: string, callback: FormFieldWatcher): FormController
+```
+
+## Parameters
+
+| Overload | Description |
+| --- | --- |
+| `unwatch()` | Removes every watcher from every field. |
+| `unwatch(field)` | Removes every watcher for the given field. |
+| `unwatch(field, callback)` | Removes only the matching callback for the given field. |
+
+## Returns
+
+The same [`FormController`](../typescript.md#formcontroller) — chainable.
+
+## Behaviour
+
+- Watchers added via [`watch`](watch.md) and [`observe`](observe.md) share the same internal registry.
+- For exact-match removal (`field` + `callback`), the same function reference must be passed.
+- For bulk removal (`field` only or no args), all matching watchers are removed.
+
+## Examples
+
+### Remove a specific watcher
+
+```ts
+import { form } from '@samline/forms'
+
+const profile = form('profile-form')
+
+const callback = (value: unknown) => console.log(value)
+profile.watch('email', callback)
+
+profile.unwatch('email', callback)
+```
+
+### Remove all watchers for a field
+
+```ts
+profile.unwatch('email')
+```
+
+### Remove every watcher
+
+```ts
+profile.unwatch()
+```
+
+### Use `observe`’s unsubscribe
+
+```ts
+const stop = profile.observe('email', value => console.log(value))
+stop() // Equivalent to profile.unwatch('email', theCallback)
+```
+
+## Edge cases
+
+- **`unwatch` does not affect subscribers** added via [`subscribe`](subscribe.md). Use the unsubscribe returned by `subscribe`.
+- **Watchers added with the same callback twice are deduplicated** — calling `unwatch` with that callback removes only one entry.
+- **Bulk removal is safe to call at any time** — it does not throw if there are no watchers.
+
+## Related
+
+- [`watch`](watch.md) — add a watcher.
+- [`observe`](observe.md) — add a watcher with an unsubscribe function.

package/docs/api/validate-field-value.md

@@ -0,0 +1,108 @@
+# `validateFieldValue(field, value, rules, values)`
+
+Pure validator. Runs the rule set against a single value. Does not require a controller — useful in tests, custom submission pipelines, or anywhere you need to evaluate validation rules outside of a bound form.
+
+## Signature
+
+```ts
+function validateFieldValue(
+  field: string,
+  value: FormFieldValue,
+  rules: FieldValidationRules,
+  values: FormValues
+): string[]
+```
+
+## Parameters
+
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `field` | `string` | yes | The field name (used for error messages and to seed `FieldValidationContext`). |
+| `value` | [`FormFieldValue`](../typescript.md#formfieldvalue) | yes | The value to validate. |
+| `rules` | [`FieldValidationRules`](../typescript.md#fieldvalidationrules) | yes | The rule set to apply. |
+| `values` | [`FormValues`](../typescript.md#formvalues) | yes | All current values, exposed to custom validators via `context.values`. |
+
+## Returns
+
+A `string[]` of error messages. Empty when the field is valid.
+
+## Behaviour
+
+Runs each rule in order:
+
+1. `required` — value must be non-empty (non-empty string, non-empty array, non-undefined).
+2. `minLength` — string length (or array length) must be ≥ the threshold.
+3. `maxLength` — string length (or array length) must be ≤ the threshold.
+4. `pattern` — the string form of the value must match the regex (skipped when the value is empty).
+5. `sameAs` — the value must equal the named value (skipped until both values are non-empty).
+6. `validate` — each custom validator runs in registration order. Returning a string pushes an error; returning `false` pushes `"Validation failed."`; returning `null`, `undefined`, or `true` is treated as a pass.
+
+Default error messages are produced when the rule was configured without an explicit `message`. Custom messages come from the `{ value, message }` form of `RuleConfig`.
+
+## Examples
+
+### Validate a single value
+
+```ts
+import { validateFieldValue } from '@samline/forms'
+
+const errors = validateFieldValue(
+  'email',
+  'invalid',
+  {
+    required: true,
+    pattern: /^[^\s@]+@[^\s@]+\.[^\s@]+$/
+  },
+  { email: 'invalid' }
+)
+
+console.log(errors) // ['Value does not match the required pattern.']
+```
+
+### Match two fields
+
+```ts
+import { validateFieldValue } from '@samline/forms'
+
+const errors = validateFieldValue(
+  'confirm',
+  'foo',
+  {
+    sameAs: { value: 'password', message: 'Passwords do not match.' }
+  },
+  { password: 'bar', confirm: 'foo' }
+)
+
+console.log(errors) // ['Passwords do not match.']
+```
+
+### Custom error messages
+
+```ts
+import { validateFieldValue } from '@samline/forms'
+
+const errors = validateFieldValue(
+  'password',
+  'short',
+  {
+    minLength: { value: 8, message: 'Use at least 8 characters.' }
+  },
+  { password: 'short' }
+)
+
+console.log(errors) // ['Use at least 8 characters.']
+```
+
+## Edge cases
+
+- **The pattern rule is skipped for empty values.** This is the standard “required + pattern” pattern: required runs first, then pattern runs only when there is a value.
+- **The `sameAs` rule is skipped until both values are non-empty.** Add `required` to each mandatory field; `sameAs` does not imply requiredness.
+- **Pure validation does not track dependencies.** `validateFieldValue` compares the supplied values once. Automatic dependent revalidation is controller behavior.
+- **`validateFieldValue` does not read from any DOM.** Pass everything in as arguments.
+- **`validate` runs after the built-in rules.** It receives the full context, including the current value and the other field values.
+- **Multiple custom validators** can be passed as an array — they all run, and any error from any of them is collected.
+
+## Related
+
+- [`validateValues`](validate-values.md) — run a schema against a whole values map.
+- [`validate`](validate.md) — controller-bound equivalent.

package/docs/api/validate-values.md

@@ -0,0 +1,100 @@
+# `validateValues(values, schema)`
+
+Pure schema validator. Runs every field in the schema against a values map and returns the aggregated result. Does not require a controller.
+
+## Signature
+
+```ts
+function validateValues(
+  values: FormValues,
+  schema: ValidationSchema
+): ValidationResult
+```
+
+```ts
+interface ValidationResult {
+  isValid: boolean
+  errors: FormErrors
+}
+
+type FormValues = Record<string, FormFieldValue>
+type FormErrors = Record<string, string[]>
+type ValidationSchema = Record<string, FieldValidationRules>
+```
+
+## Parameters
+
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `values` | [`FormValues`](../typescript.md#formvalues) | yes | The values to validate. |
+| `schema` | [`ValidationSchema`](../typescript.md#validationschema) | yes | Field → rules map. |
+
+## Returns
+
+A [`ValidationResult`](../typescript.md#validationresult):
+
+- `isValid` — `true` when `errors` is empty.
+- `errors` — a fresh error map.
+
+## Behaviour
+
+For each `[field, rules]` entry in the schema, runs [`validateFieldValue`](validate-field-value.md) against `values[field]`. The other values are available to `sameAs` and custom validators.
+
+## Examples
+
+### Validate a snapshot
+
+```ts
+import { validateValues } from '@samline/forms'
+
+const result = validateValues(
+  {
+    email: 'invalid',
+    terms: ''
+  },
+  {
+    email: {
+      required: true,
+      pattern: /^[^\s@]+@[^\s@]+\.[^\s@]+$/
+    },
+    terms: {
+      required: { value: true, message: 'Accept the terms.' }
+    }
+  }
+)
+
+console.log(result.isValid)    // false
+console.log(result.errors)     // { email: [...], terms: ['Accept the terms.'] }
+```
+
+### Use with `parseFormData`
+
+```ts
+import { parseFormData, validateValues } from '@samline/forms'
+
+const formElement = document.querySelector<HTMLFormElement>('#contact-form')
+if (!formElement) throw new Error('form not found')
+
+const { data } = parseFormData(formElement)
+
+const result = validateValues(data as Record<string, string | string[] | File[] | undefined>, {
+  email: { required: true, pattern: /^[^\s@]+@[^\s@]+\.[^\s@]+$/ },
+  message: { required: true, minLength: 10 }
+})
+
+if (!result.isValid) {
+  console.warn(result.errors)
+}
+```
+
+## Edge cases
+
+- **`validateValues` does not know which fields are “tracked”.** It validates every entry in the schema, even fields that are not present in `values`. An undefined value fails `required` but passes the rest.
+- **Errors are always a fresh object.** Safe to mutate.
+- **`sameAs` compares the provided snapshot only.** Dependency tracking and automatic revalidation belong to a form controller, not this pure helper.
+- **Custom validators receive the full values map**, so cross-field rules work the same as inside a controller.
+
+## Related
+
+- [`validateFieldValue`](validate-field-value.md) — single-field validator.
+- [`parseFormData`](parse-form-data.md) — produce a `FormValues` map from a form.