@samline/forms 2.7.2 → 2.9.0

package/docs/recipes.md

@@ -1,531 +0,0 @@
-# Recipes
-
-End-to-end patterns that combine multiple methods. Each recipe is a self-contained example you can drop into a real project.
-
----
-
-## 1. Login form with `fetch`
-
-```html
-<form id="login-form">
-  <input name="email" type="email" autocomplete="email" required />
-  <input name="password" type="password" autocomplete="current-password" required />
-  <button type="submit">Sign in</button>
-</form>
-```
-
-```ts
-import { form } from '@samline/forms'
-
-const login = form('login-form', {
-  validators: {
-    email: {
-      required: { value: true, message: 'Email is required.' },
-      pattern: {
-        value: /^[^\s@]+@[^\s@]+\.[^\s@]+$/,
-        message: 'Enter a valid email.'
-      }
-    },
-    password: { required: true, minLength: 8 }
-  }
-})
-
-login.onSubmit(async (_element, _data, formData) => {
-  const response = await fetch('/api/login', {
-    method: 'POST',
-    body: formData
-  })
-
-  if (!response.ok) {
-    login.setErrors({ password: ['Wrong email or password.'] })
-    return
-  }
-
-  window.location.assign('/dashboard')
-})
-```
-
-What this does:
-
-- Validates with custom messages.
-- Intercepts the submit (default `preventDefault: true`) so the browser does not navigate.
-- Surfaces a single error on the password field when the API rejects the credentials.
-
----
-
-## 2. Surface server-side validation errors
-
-```ts
-import { form } from '@samline/forms'
-
-const profile = form('profile-form', {
-  autoValidate: false,
-  clearManualErrorsOnChange: false,
-  validators: {
-    email: { required: true, pattern: /^[^\s@]+@[^\s@]+\.[^\s@]+$/ }
-  }
-})
-
-profile.onSubmit(async (_element, _data, formData) => {
-  const response = await fetch('/api/profile', {
-    method: 'POST',
-    body: formData
-  })
-
-  if (response.status === 422) {
-    const { fieldErrors } = (await response.json()) as {
-      fieldErrors: Record<string, string[]>
-    }
-    profile.setErrors(fieldErrors)
-    return
-  }
-
-  if (response.ok) {
-    profile.clearErrors()
-    profile.reset()
-  }
-})
-```
-
-Why `clearManualErrorsOnChange: false`: the server’s errors should stay visible while the user fixes them.
-
----
-
-## 3. Multi-step / wizard
-
-```html
-<form id="wizard">
-  <fieldset data-step="1">
-    <input name="name" />
-    <input name="email" type="email" />
-  </fieldset>
-  <fieldset data-step="2" hidden>
-    <input name="address" />
-    <input name="city" />
-  </fieldset>
-  <button type="button" id="next">Next</button>
-  <button type="submit" id="submit" hidden>Submit</button>
-</form>
-```
-
-```ts
-import { form } from '@samline/forms'
-
-const wizard = form('wizard', {
-  validators: {
-    name: { required: true },
-    email: { required: true, pattern: /^[^\s@]+@[^\s@]+\.[^\s@]+$/ },
-    address: { required: true },
-    city: { required: true }
-  }
-})
-
-const stepFields: Record<1 | 2, string[]> = {
-  1: ['name', 'email'],
-  2: ['address', 'city']
-}
-
-let currentStep: 1 | 2 = 1
-
-document.querySelector('#next')?.addEventListener('click', () => {
-  const ok = wizard.validate(stepFields[currentStep]).isValid
-  if (!ok) return
-
-  currentStep = 2
-  wizard.element?.querySelector('[data-step="1"]')?.setAttribute('hidden', '')
-  wizard.element?.querySelector('[data-step="2"]')?.removeAttribute('hidden')
-  document.querySelector('#next')!.setAttribute('hidden', '')
-  document.querySelector('#submit')!.removeAttribute('hidden')
-})
-
-wizard.onSubmit(async (_element, _data, formData) => {
-  await fetch('/api/wizard', { method: 'POST', body: formData })
-})
-```
-
-Each step validates only its own fields, so the user can progress without being blocked by later fields.
-
----
-
-## 4. Autosave drafts
-
-```html
-<form id="draft">
-  <input name="title" />
-  <textarea name="body"></textarea>
-</form>
-```
-
-```ts
-import { form } from '@samline/forms'
-
-const draft = form('draft', {
-  autoSubmit: { debounce: 800 }
-})
-
-draft.onSubmit(async (_element, _data, formData) => {
-  await fetch('/api/draft', { method: 'POST', body: formData })
-})
-```
-
-For a JSON endpoint, switch the body to `JSON.stringify(data)` and set the right `Content-Type` header.
-
-To pause autosave while the user is typing into a “bulk edit” textarea, toggle it explicitly:
-
-```ts
-const bodyField = draft.getField('body') as HTMLTextAreaElement | null
-
-bodyField?.addEventListener('focus', () => draft.disableAutoSubmit())
-bodyField?.addEventListener('blur', () => draft.autoSubmit({ debounce: 800 }))
-```
-
----
-
-## 5. Dynamic fields added at runtime
-
-```html
-<form id="builder">
-  <div id="rows"></div>
-  <button type="button" id="add">Add row</button>
-  <button type="submit">Save</button>
-</form>
-```
-
-```ts
-import { form } from '@samline/forms'
-
-const builder = form('builder', {
-  validators: {
-    'rows[].name': {
-      each: {
-        required: { value: true, message: 'Every row needs a name.' }
-      }
-    }
-  }
-})
-
-document.querySelector('#add')?.addEventListener('click', () => {
-  const rows = document.querySelector('#rows')!
-  const row = document.createElement('div')
-  row.innerHTML = `
-    <label>Name <input name="rows[].name" /></label>
-    <label>Value <input name="rows[].value" /></label>
-  `
-  rows.appendChild(row)
-})
-```
-
-Validator keys match literal HTML names, not wildcard paths. Reusing `rows[].name` gives the validator an array once multiple rows exist. `each` validates every row independently, so only an empty row receives `css-error` and `aria-invalid="true"`; `getState().errors['rows[].name']` remains a flat `string[]`. The form-subtree `MutationObserver` clears field lookups and, because the default controller is already validated, re-runs validation when each row is appended.
-
----
-
-## 6. Bind to a ref-like target after async mount
-
-```ts
-import { form } from '@samline/forms'
-
-const target = { current: null as HTMLFormElement | null }
-
-const controller = form(target)
-
-async function mount() {
-  const formElement = document.createElement('form')
-  formElement.innerHTML = `<input name="email" type="email" />`
-  document.querySelector('#app')!.appendChild(formElement)
-
-  target.current = formElement
-  controller.destroy() // The controller captured `current` at construction time.
-  form(target)
-}
-
-mount()
-```
-
-`form()` reads `target.current` once. If the form is mounted later, recreate the controller (or call `destroy()` and re-bind).
-
----
-
-## 7. Manual-only validation
-
-When you want validation to run only when you ask (not on every change), disable `autoValidate` and call `validate()` yourself. Initial `css-filled` state still synchronizes for prefilled controls without running any rules.
-
-```ts
-import { form } from '@samline/forms'
-
-const checkout = form('checkout-form', {
-  autoValidate: false,
-  validators: {
-    card: { required: true, minLength: 12 },
-    expiry: { required: true }
-  }
-})
-
-document.querySelector('#pay')?.addEventListener('click', () => {
-  const result = checkout.validate()
-  if (!result.isValid) {
-    checkout.setErrors({ card: ['Please review your details.'] })
-    return
-  }
-
-  checkout.element?.requestSubmit()
-})
-```
-
-Useful when you want to defer validation until a specific event (e.g. a “Review order” button).
-
----
-
-## 8. Keep manual errors until the user explicitly clears them
-
-```ts
-import { form } from '@samline/forms'
-
-const profile = form('profile-form', {
-  clearManualErrorsOnChange: false,
-  validators: {
-    email: { required: true, pattern: /^[^\s@]+@[^\s@]+\.[^\s@]+$/ }
-  }
-})
-
-profile.setErrors({ email: ['This email is already in use.'] })
-
-// The error stays visible even after the user edits the field.
-profile.clearErrors(['email']) // Or clearErrors() to clear everything.
-```
-
----
-
-## 9. Native server-rendered submit (Blade, ERB, classic Rails)
-
-```html
-<form id="profile" action="/profile" method="post">
-  @csrf
-  <input name="email" type="email" />
-  <input name="name" />
-  <button type="submit">Save</button>
-</form>
-```
-
-```ts
-import { form } from '@samline/forms'
-
-const profile = form('profile', {
-  validators: {
-    email: { required: true, pattern: /^[^\s@]+@[^\s@]+\.[^\s@]+$/ }
-  }
-})
-
-profile.onSubmit(() => {
-  console.log('client-side hooks ran')
-}, false)
-```
-
-When validation passes, the browser performs the native form submit to the `action` URL. When validation fails, the submit is prevented and the user sees the inline errors.
-
----
-
-## 10. SPA cleanup on route change
-
-```ts
-import { form } from '@samline/forms'
-
-const controllers = new Map<string, ReturnType<typeof form>>()
-
-router.on('/profile', element => {
-  controllers.set('profile', form(element, { validators: { email: { required: true } } }))
-})
-
-router.off('/profile', () => {
-  controllers.get('profile')?.destroy()
-  controllers.delete('profile')
-})
-```
-
-`destroy()` is idempotent — calling it more than once is safe.
-
----
-
-## 11. Sync state into a view layer
-
-```ts
-import { form } from '@samline/forms'
-
-const signup = form('signup-form', {
-  validators: {
-    email: { required: true },
-    password: { required: true, minLength: 8 }
-  }
-})
-
-signup.subscribe(state => {
-  const submit = signup.element?.querySelector<HTMLButtonElement>('button[type="submit"]')
-  if (submit) submit.disabled = !state.isValid
-})
-```
-
-Use `subscribe` when a single source of truth should drive your UI (button enabled state, live previews, dependent field visibility, etc.).
-
----
-
-## 12. Confirm a password with `sameAs`
-
-```ts
-import { form } from '@samline/forms'
-
-const signup = form('signup-form', {
-  validators: {
-    password: { required: true, minLength: 8 },
-    password_confirmation: {
-      required: true,
-      sameAs: {
-        value: 'password',
-        message: 'Passwords do not match.'
-      }
-    }
-  }
-})
-```
-
-Declare the rule on the confirmation field so the mismatch has one owner. The controller automatically revalidates it when `password` changes; do not add reciprocal `sameAs` rules or `watch()` calls unless you intentionally want errors on both fields. Empty values are left to `required`.
-
----
-
-## 13. Combine `setValue` with custom validation
-
-```ts
-import { form } from '@samline/forms'
-
-const shipping = form('shipping-form', {
-  validators: {
-    method: { required: true },
-    country: {
-      dependsOn: 'method',
-      validate: ({ value, values }) => {
-        if (values.method === 'international' && value !== 'US') return null
-        if (values.method === 'domestic' && value === 'US') return null
-        return 'Country and shipping method must be consistent.'
-      }
-    }
-  }
-})
-
-// Programmatic update triggers the delegated pipeline and revalidates country.
-shipping.setValue('method', 'international')
-```
-
-Custom validators receive the full values map, so cross-field rules read like plain JavaScript. `dependsOn` tells the controller that `country` must be revalidated whenever `method` changes; exact-name dependency chains and cycles are deduplicated.
-
----
-
-## 14. Format inputs with `@samline/formatter`
-
-When you need phone masks, credit-card grouping, numeral delimiters, or any other input formatting, pair `@samline/forms` with `@samline/formatter`. The `format()` and `formatAll()` methods bind a formatter pipeline to one or many fields, manage the hidden raw mirror, and preserve the caret like cleave.js.
-
-```html
-<form id="checkout">
-  <input name="phone" autocomplete="tel" />
-  <input name="card" autocomplete="cc-number" />
-  <input name="amount" inputmode="decimal" />
-</form>
-```
-
-```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: '$' } }
-  }
-})
-
-checkout.onSubmit((_form, _data, formData) => {
-  // formData carries the raw value at the canonical name and the
-  // formatted value at the display name. The backend only needs
-  // the canonical (raw) keys:
-  //   phone           = '5512345678'
-  //   phone_displayed = '55 1234 5678'
-  //   card            = '4111111111111111'
-  //   card_displayed  = '4111 1111 1111 1111'
-  //   amount          = '1234'
-  //   amount_displayed= '$1,234'
-  fetch('/api/checkout', { method: 'POST', body: formData })
-})
-```
-
-Things to know:
-
-- You write the HTML with the **canonical** name only (e.g. `<input name="phone" />`). `format()` renames the visible to `phone_displayed` on first run and appends a hidden `<input type="hidden" name="phone">` that holds the raw value. The hidden carries `data-formatter-raw-for="phone"` so the controller can identify it as owned and remove it on `destroy()`. The hidden is appended to the form root — outside any label wrapper. The controller never writes the visual attributes (`css-filled` / `css-error`) to the hidden; it always targets the visible, so the `:has()` recipe in [CSS styling](css-styling.md) keeps working for formatted fields.
-- Both names are first-class in the controller's API. `getValue('phone')` returns the raw, `getValue('phone_displayed')` returns the formatted, `watch('phone', cb)` fires with the raw, and so on. See the [full mirror contract in `format.md`](api/format.md#the-mirror-convention).
-- If you authored your own `<input type="hidden" name="<field>">` (or `<input data-formatter-raw-for="<field>">`) before wiring the controller, `format()` reuses it instead of duplicating it. Pre-existing mirrors survive `destroy()`; mirrors created by `format()` are removed.
-- If you prefer to pre-author the visible with the display name (e.g. `<input name="phone_displayed" />`) instead of letting `format()` rename it, `format()` picks that up and skips the rename. Both authoring styles end up with the same DOM.
-- Use `formatAll({ type, field: ['a', 'b', 'c'], options })` to bind the same configuration to several fields in one call. Each field gets its own pair (`a` + `a_displayed`, `b` + `b_displayed`, `c` + `c_displayed`).
-- Date/time initial values and canonical mirror writes use the formatter's `auto` interpretation; live visible-input events and re-binds use `display`. This preserves server-prefilled raw values without misreading a full-length delimiter-less paste in the visible field. An explicit `options.interpretInputAs` always wins.
-- `@samline/formatter` is an **optional peer dependency** for module builds. When it is missing, the module instance logs one cached `console.error` and asynchronously restores affected fields so the rest of the form keeps working. The standalone global IIFE bundles formatter behavior.
-
----
-
-## 15. Validate numeric ranges
-
-```ts
-import { form } from '@samline/forms'
-
-const invoice = form('invoice-form', {
-  validators: {
-    amount: {
-      required: true,
-      numeric: { value: true, message: 'Enter an unformatted decimal amount.' },
-      min: { value: 0, message: 'Amount cannot be negative.' },
-      max: { value: 100000, message: 'Amount is above the limit.' }
-    }
-  }
-})
-```
-
-The bounds are inclusive. Ordinary signed decimals such as `-1`, `+2.5`, `.75`, and `10.` are accepted; exponent notation, hexadecimal, `Infinity`, `NaN`, and values containing formatting separators are rejected. Empty input skips numeric rules, so use `required` when it must fail.
-
----
-
-## 16. Track async submission state
-
-```ts
-const profile = form('profile-form')
-
-profile.subscribe(state => {
-  saveButton.disabled = state.isSubmitting
-  saveButton.textContent = state.isSubmitting ? 'Saving...' : 'Save'
-})
-
-profile.onSubmit(async (_form, _data, formData) => {
-  await fetch('/api/profile', { method: 'POST', body: formData })
-})
-```
-
-Multiple async handlers start in registration order without awaiting one another. Overlapping submissions keep `isSubmitting` true until all tracked work settles. Rejections settle the state and are not converted into validation errors.
-
----
-
-## 17. Tie third-party resources to controller cleanup
-
-```ts
-const checkout = form('checkout-form')
-const abortController = new AbortController()
-
-window.addEventListener('resize', updateCheckoutLayout, {
-  signal: abortController.signal
-})
-
-checkout.addCleanup(() => abortController.abort())
-```
-
-Active cleanups run once in reverse registration order on `destroy()`. The returned unregister function removes only its own registration, duplicate callback registrations remain independent, and a cleanup registered after destruction runs immediately.
-
----
-
-## Next steps
-
-- Need a full options reference? See [docs/options.md](options.md).
-- Looking up an exact method signature? See [docs/api/index.md](api/index.md).
-- Working with TypeScript types? See [docs/typescript.md](typescript.md).
-- Setting up styling for `css-filled` / `css-error`? See [docs/css-styling.md](css-styling.md).