@samline/forms 2.4.0 → 2.6.0

package/docs/api/validate.md

@@ -0,0 +1,100 @@
+# `validate(fields?)`
+
+Runs validation against the configured [`validators`](../options.md#validators). Returns the result and marks the form as validated.
+
+## Signature
+
+```ts
+validate(): ValidationResult
+validate(fields: string[]): ValidationResult
+```
+
+```ts
+interface ValidationResult {
+  isValid: boolean
+  errors: FormErrors
+}
+```
+
+## Parameters
+
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `fields` | `string[]` | no | When provided, only the listed fields are validated. When omitted, every field with rules is validated. |
+
+## Returns
+
+A [`ValidationResult`](../typescript.md#validationresult):
+
+- `isValid` — `true` when the merged error map (validation + manual) is empty.
+- `errors` — the merged error map (validation + manual). The map is a fresh object — safe to mutate.
+
+## Behaviour
+
+- Marks the form as validated (`state.isValidated = true`). This means future field changes will run validation again, even when the controller was created with `autoValidate: false`.
+- Re-syncs visual attributes (`css-filled` / `css-error`) for the affected fields.
+- After the form is validated, an input event also revalidates fields whose `sameAs` rule references the changed field. Cycles are deduplicated and each affected field runs once.
+- Subscribers are not notified — this method is a pure read of the rule engine. To run validation and notify subscribers, use [`subscribe`](subscribe.md) and read [`getState()`](get-state.md).
+
+## Examples
+
+### Validate the whole form
+
+```ts
+import { form } from '@samline/forms'
+
+const signup = form('signup-form', {
+  validators: {
+    email: { required: true, pattern: /^[^\s@]+@[^\s@]+\.[^\s@]+$/ },
+    password: { required: true, minLength: 8 }
+  }
+})
+
+const result = signup.validate()
+
+if (!result.isValid) {
+  console.warn('errors:', result.errors)
+}
+```
+
+### Validate a single field
+
+```ts
+signup.validate(['email'])
+```
+
+### Validate a sub-group of fields (e.g. a wizard step)
+
+```ts
+const wizard = form('wizard-form', {
+  validators: {
+    'step-1.name': { required: true },
+    'step-1.email': { required: true, pattern: /^[^\s@]+@[^\s@]+\.[^\s@]+$/ },
+    'step-2.address': { required: true },
+    'step-2.city': { required: true }
+  }
+})
+
+function nextStep(step: 1 | 2) {
+  const fields = step === 1
+    ? ['step-1.name', 'step-1.email']
+    : ['step-2.address', 'step-2.city']
+
+  return wizard.validate(fields).isValid
+}
+```
+
+## Edge cases
+
+- **`validate` ignores manual errors** during computation, but the returned `errors` includes them (merged with validation errors). The `isValid` flag reflects the merged map.
+- **Validation rules must be configured** via `options.validators`. Fields without rules are always considered valid.
+- **An explicit partial call validates exactly the requested fields.** `validate(['password'])` does not expand `sameAs` dependencies; dependency expansion happens for input events, including those dispatched by `setValue()`.
+- **Custom validators receive `{ field, value, values }`** — see [`FieldValidationContext`](../typescript.md#fieldvalidationcontext).
+- **A custom validator that returns `false` pushes the generic message `"Validation failed."`.**
+- **`validate()` is the same as calling [`revalidate()`](revalidate.md)`** — they are aliases for readability.
+
+## Related
+
+- [`revalidate`](revalidate.md) — alias of `validate`.
+- [`setErrors`](set-errors.md) and [`clearErrors`](clear-errors.md) — manual errors.
+- [`validateValues`](../api/validate-values.md) — pure helper for use without a controller.

package/docs/api/watch.md

@@ -0,0 +1,117 @@
+# `watch(field, callback)`
+
+Registers a callback that fires every time a field changes. Chainable alias of [`observe`](observe.md); use it when you want fluent setup without holding the unsubscribe function.
+
+## Signature
+
+```ts
+watch(
+  field: string,
+  callback: FormFieldWatcher
+): FormController
+```
+
+## Parameters
+
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `field` | `string` | yes | The `name` attribute of the field to watch. |
+| `callback` | [`FormFieldWatcher`](../typescript.md#formfieldwatcher) | yes | Invoked with `(value, field, form, state)` on every change. `field` is the observed DOM element(s) (same shape as [`getField`](../typescript.md#formfieldelement--formfieldelement--null) returns), handy for manipulating the actual `<input>` / `<select>` / `<textarea>` without re-querying it. |
+
+## Returns
+
+The same [`FormController`](../typescript.md#formcontroller) — chainable.
+
+## Behaviour
+
+- The callback fires immediately on registration and after every change, matching `observe()`; only the return type differs.
+- A field can have multiple watchers.
+- Watchers persist for the lifetime of the controller. Use [`unwatch`](unwatch.md) to remove them, or [`observe`](observe.md) if you need explicit unsubscribe semantics.
+- The callback fires after the controller has processed the change — manual errors are cleared (when applicable), validation has run for fields with rules, visual state has been re-synced, and subscribers have been notified.
+
+## Examples
+
+### Show a live preview
+
+```ts
+import { form } from '@samline/forms'
+
+const profile = form('profile-form')
+
+profile.watch('bio', value => {
+  const preview = document.querySelector('#bio-preview')
+  if (preview && typeof value === 'string') preview.textContent = value
+})
+```
+
+### Reactive password strength
+
+```ts
+import { form } from '@samline/forms'
+
+const signup = form('signup-form')
+
+signup.watch('password', value => {
+  const meter = document.querySelector('#password-strength')
+  if (meter && typeof value === 'string') {
+    meter.textContent = scorePassword(value)
+  }
+})
+```
+
+### Share a single handler across fields
+
+```ts
+import { form } from '@samline/forms'
+
+const search = form('search-form')
+
+const logField = (
+  value: unknown,
+  field: HTMLInputElement | HTMLInputElement[] | null
+) => {
+  if (field && 'name' in field) {
+    console.log(`${field.name} =`, value)
+  }
+}
+
+search.watch('q', logField).watch('category', logField)
+```
+
+### Interact with the field element directly
+
+```ts
+import { form } from '@samline/forms'
+
+const checkout = form('checkout-form')
+
+checkout.watch('country', (_value, field, _form, _state) => {
+  if (field instanceof HTMLSelectElement) {
+    // Toggle a CSS class on the actual <select> without re-querying it.
+    field.classList.toggle('has-zip', field.value !== 'US')
+  }
+})
+```
+
+### Chain with other setup
+
+```ts
+form('search-form')
+  .watch('q', value => console.log('q =', value))
+  .watch('category', value => console.log('category =', value))
+  .onSubmit((_form, data) => console.log('submit', data))
+```
+
+## Edge cases
+
+- **The callback receives the value, not the event object.** Use [`getField`](get-field.md) if you need the underlying DOM element.
+- **`watch` fires immediately**, just like [`observe`](observe.md); it differs only by returning the controller instead of an unsubscribe function.
+- **A field name that does not match any DOM field** receives one initial call with `undefined` and `null`. It runs again only if an `input` event later comes from a field with that name.
+- **Watchers are not invoked from [`setValue`](set-value.md) directly.** `setValue` writes the value and dispatches one `input` event, which goes through the same delegated listener path as user input.
+
+## Related
+
+- [`observe`](observe.md) — same immediate callback, but returns an unsubscribe function.
+- [`unwatch`](unwatch.md) — remove watched callbacks.
+- [`subscribe`](subscribe.md) — react to the whole form state.
+- [`format`](format.md) — when a field is formatted, `watch('<field>', cb)` fires with the raw value and `watch('<field>_displayed', cb)` fires with the formatted value. Both fire on the same keystroke. See [the mirror convention](format.md#the-mirror-convention).

package/docs/browser.md

@@ -0,0 +1,156 @@
+# Browser
+
+## When to use this variant
+
+Use the browser build when you do not have a bundler and need to integrate the package directly into HTML, Shopify, WordPress, or any traditional template that does not run through a build step.
+
+For every other case (modern apps, bundlers, TypeScript projects), use the main vanilla entrypoint — see [docs/getting-started.md](getting-started.md).
+
+---
+
+## Script tag
+
+```html
+<script src="https://unpkg.com/@samline/forms@2.6.0/dist/browser/global.global.js"></script>
+```
+
+> Pin the version in production. Replace `2.6.0` with the version you ship.
+
+The bundle is a single IIFE that registers a global object.
+
+---
+
+## Global object
+
+The browser build exposes `window.Forms` (also reachable via `globalThis.Forms`).
+
+```ts
+window.Forms = {
+  form,
+  newForm,
+  destroyForm,
+  available
+}
+```
+
+- `form` is the same factory exported by `@samline/forms` — see [`docs/api/form.md`](api/form.md) for the signature.
+- `newForm` and `destroyForm` are ergonomic wrappers that keep a registry under `Forms.available`, keyed by the form id.
+
+The factory returns a `FormController` with the same signatures, semantics, and behaviours as the main vanilla entrypoint — every per-method page under [docs/api/](api/index.md) applies.
+
+---
+
+## Minimal example
+
+```html
+<form id="contact-form">
+  <input name="email" type="email" />
+  <input name="message" />
+  <button type="submit">Send</button>
+</form>
+
+<script src="https://unpkg.com/@samline/forms@2.6.0/dist/browser/global.global.js"></script>
+<script>
+  const contactForm = window.Forms.newForm({
+    id: 'contact-form',
+    options: {
+      validators: {
+        email: {
+          required: true,
+          pattern: /^[^\s@]+@[^\s@]+\.[^\s@]+$/
+        },
+        message: { required: true, minLength: 10 }
+      }
+    }
+  })
+
+  contactForm.onSubmit(async (_element, _data, formData) => {
+    await fetch('/api/contact', { method: 'POST', body: formData })
+    contactForm.reset()
+  })
+</script>
+```
+
+The controller returned by `newForm` is the same instance stored under `Forms.available['contact-form']`. Use `window.Forms.destroyForm('contact-form')` later to call `destroy()` and remove it from the registry.
+
+---
+
+## Registry helpers
+
+| Helper | Purpose |
+| --- | --- |
+| `Forms.newForm({ id, options })` | Destroy any existing controller under the id, build a replacement via `Forms.form(id, options)`, and store it in `Forms.available[id]`. Logs `Form ID is required` and returns early if `id` is missing. |
+| `Forms.destroyForm(id)` | Look up `Forms.available[id]`, call `destroy()`, and delete the entry. Missing ids log an error; absent entries log a warning. |
+| `Forms.available` | Shared mutable registry: `{ [id: string]: FormController }`. Prefer `newForm()` and `destroyForm()` to manage it. |
+
+Use `Forms.form` directly when you do not want the registry side-effect (for example, transient controllers in tests).
+
+---
+
+## Surface reference
+
+The browser bundle ships only the registry helpers plus the `form` factory. Every controller method is documented under [docs/api/](api/index.md).
+
+| Global | Purpose |
+| --- | --- |
+| `Forms.form(target, options?)` | Bind a controller to a form (recommended). See [`docs/api/form.md`](api/form.md). |
+| `Forms.newForm({ id, options? })` | Build + register a controller in `Forms.available[id]`. |
+| `Forms.destroyForm(id)` | Destroy + unregister a controller by id. |
+| `Forms.available` | Registry of active controllers keyed by id. |
+
+### Controller methods
+
+The controller returned by `form` / `newForm` exposes the methods documented under [docs/api/](api/index.md):
+
+- Lifecycle: [`element`](api/element.md), [`reset`](api/reset.md), [`destroy`](api/destroy.md).
+- Submission: [`onSubmit`](api/on-submit.md), [`autoSubmit`](api/auto-submit.md), [`disableAutoSubmit`](api/disable-auto-submit.md).
+- Field observation: [`watch`](api/watch.md), [`observe`](api/observe.md), [`unwatch`](api/unwatch.md), [`subscribe`](api/subscribe.md).
+- Field values: [`setValue`](api/set-value.md), [`getValue`](api/get-value.md), [`getField`](api/get-field.md), [`prefill`](api/prefill.md).
+- Validation: [`validate`](api/validate.md), [`revalidate`](api/revalidate.md), [`setErrors`](api/set-errors.md), [`clearErrors`](api/clear-errors.md).
+- State and data: [`getData`](api/get-data.md), [`getState`](api/get-state.md), [`append`](api/append.md).
+
+---
+
+## TypeScript users
+
+The module entrypoint `@samline/forms/browser` ships types, registers the `Window.Forms` declaration, and exposes the same API as module exports. The direct IIFE subpath does not expose a typed module export.
+
+```ts
+import Forms from '@samline/forms/browser'
+
+Forms.newForm({ id: 'contact-form' })
+window.Forms.destroyForm('contact-form')
+```
+
+---
+
+## Common pitfalls
+
+- **Pin the version.** The CDN URL above is `2.6.0`. Replace it whenever you upgrade.
+- **The script must be loaded before any code that uses `window.Forms`.** Place the `<script>` tag in `<head>` with `defer`, or before the user script in `<body>`.
+- **No bundler means no tree-shaking.** The global browser bundle includes the controller and formatter peer. Inspect the published artifact when bundle size is a constraint.
+- **CSP:** if your site uses a strict Content Security Policy, allow `unpkg.com` in `script-src` (or self-host the file).
+
+---
+
+## Using the same shape from a bundler
+
+If you have a bundler but still want the `newForm` / `destroyForm` / `available` ergonomics (without the IIFE and without `window.Forms` auto-installed), use the vanilla `browser` singleton instead:
+
+```ts
+import { browser } from '@samline/forms'
+
+browser.newForm({ id: 'contact-form' })
+browser.destroyForm('contact-form')
+browser.available // { 'contact-form': FormController }
+```
+
+`browser` is a module-level singleton with a shared `available` registry. Spreading it copies references but does not create an independent registry because its methods close over the same `available` object. For isolated registries, call `form()` and keep controllers in your own `Map`. See [Browser registry helpers](getting-started.md#browser-registry-helpers) for the composition pattern, including how to attach `regex` from `@samline/formatter`.
+
+---
+
+## Next steps
+
+- Concepts and lifecycle: [docs/getting-started.md](getting-started.md).
+- Full options reference: [docs/options.md](options.md).
+- End-to-end patterns: [docs/recipes.md](recipes.md).

package/docs/css-styling.md

@@ -0,0 +1,187 @@
+# CSS Styling
+
+The controller does not ship styles. It only toggles boolean attributes on fields so your CSS can react. By default those attributes are `css-filled` and `css-error`. You can rename them with [`options.attributes`](options.md#attributes).
+
+This page shows how the attributes behave, which elements they apply to, and how to write CSS that pairs cleanly with them.
+
+---
+
+## How attributes are applied
+
+| Attribute | Added when | Removed when |
+| --- | --- | --- |
+| `css-filled` | The field has a non-empty value (for checkboxes/radios, when checked; for files, when one or more files are selected). | The field becomes empty. |
+| `css-error` | The field has at least one error — either from built-in validation rules or from [`setErrors`](api/set-errors.md). | All errors for that field are cleared (via [`clearErrors`](api/clear-errors.md), [`reset`](api/reset.md), or a successful re-validation). |
+
+The attributes are added and removed on:
+
+- Mount (initial sync).
+- Every delegated `input` event, including controls associated through `form="id"`.
+- Every explicit call to [`validate`](api/validate.md), [`revalidate`](api/revalidate.md), [`setErrors`](api/set-errors.md), or [`clearErrors`](api/clear-errors.md).
+- DOM mutations detected by the controller’s `MutationObserver` (new fields, changed `name` / `type` attributes).
+
+The attributes are also removed everywhere when you call [`reset`](api/reset.md).
+
+---
+
+## Default selectors
+
+```css
+/* any field that has a value */
+[css-filled] { /* ... */ }
+
+/* any field with at least one error */
+[css-error] { /* ... */ }
+```
+
+These attributes are boolean: present or absent. They never have a value. The selector `[css-filled]` matches both `[css-filled]` and `[css-filled=""]`.
+
+---
+
+## Recipes
+
+### Text inputs
+
+```css
+input[css-filled] {
+  border-color: var(--color-border-emphasis);
+}
+
+input[css-error] {
+  border-color: var(--color-danger);
+  background-color: var(--color-danger-soft);
+}
+
+input[css-error]:focus-visible {
+  outline-color: var(--color-danger);
+}
+```
+
+### Textarea
+
+```css
+textarea[css-filled] {
+  background-color: var(--color-surface-soft);
+}
+
+textarea[css-error] {
+  border-color: var(--color-danger);
+}
+```
+
+### Selects
+
+```css
+select[css-filled] {
+  background-color: var(--color-surface-soft);
+}
+
+select[css-error] {
+  border-color: var(--color-danger);
+}
+```
+
+### Checkboxes and radios
+
+The attribute is set on the input itself when it’s checked.
+
+```css
+input[type="checkbox"][css-filled],
+input[type="radio"][css-filled] {
+  outline: 2px solid var(--color-accent);
+  outline-offset: 2px;
+}
+
+input[type="checkbox"][css-error],
+input[type="radio"][css-error] {
+  outline: 2px solid var(--color-danger);
+  outline-offset: 2px;
+}
+```
+
+### File inputs
+
+```css
+input[type="file"][css-filled] {
+  border-color: var(--color-success);
+}
+
+input[type="file"][css-error] {
+  border-color: var(--color-danger);
+}
+```
+
+### Styling the wrapper
+
+A common pattern is to style a parent label that contains the input:
+
+```html
+<label class="field">
+  <span>Email</span>
+  <input name="email" type="email" />
+</label>
+```
+
+```css
+.field {
+  display: grid;
+  gap: 0.25rem;
+}
+
+.field:has([css-filled]) > span {
+  color: var(--color-text-emphasis);
+}
+
+.field:has([css-error]) > span {
+  color: var(--color-danger);
+}
+```
+
+> `:has()` is supported in evergreen browsers. If you need older browser support, attach the attributes to the wrapper from your own code or use class-based selectors instead.
+
+> **Formatted fields.** The hidden raw mirror created by [`format()`](api/format.md) lives at the end of the form, outside any label. The controller always applies `css-filled` and `css-error` to the **visible** input (the one inside the label) for fields wired through `format()` — the hidden is intentionally excluded from the `:has()` selector. This is what makes the recipe above work without changes for formatted fields.
+
+### Custom attribute names
+
+```ts
+form('signup-form', {
+  attributes: { filled: 'is-filled', error: 'is-invalid' }
+})
+```
+
+```css
+.is-filled { /* ... */ }
+.is-invalid { /* ... */ }
+```
+
+---
+
+## Accessibility
+
+The controller sets `aria-invalid="true"` while a field has validation or manual errors and removes it when the field becomes valid. Invalid submission focuses the first connected, enabled, non-hidden invalid field. Provide `aria-describedby` and an error message element in your template:
+
+```html
+<label class="field">
+  <span>Email</span>
+  <input name="email" type="email" aria-describedby="email-error" />
+  <small id="email-error" hidden></small>
+</label>
+```
+
+The controller’s [`getState()`](api/get-state.md) returns the current errors per field so you can reveal and populate the message from a single source of truth:
+
+```ts
+const state = profileForm.getState()
+
+emailErrorEl.hidden = !state.errors.email
+emailErrorEl.textContent = state.errors.email?.[0] ?? ''
+```
+
+---
+
+## Common pitfalls
+
+- **The attributes have no value.** A selector like `[css-filled="true"]` will not match. Use `[css-filled]` instead.
+- **`css-error` is set whenever there is any error**, including manual errors from [`setErrors`](api/set-errors.md). Combine your selector with the actual message you render.
+- **Field labels do not automatically receive the attributes.** Apply styles to the input itself, or use `:has()` / a wrapper class.
+- **CSS is not the only place the attributes appear.** Treat them as a styling hook, not as state. Read [`getState()`](api/get-state.md) if you need the authoritative state.