@samline/forms 2.4.0 → 2.7.0

package/docs/typescript.md

@@ -0,0 +1,615 @@
+# TypeScript Reference
+
+This page lists every type exported from `@samline/forms`, what it represents, and where it shows up. Each type links to the method(s) that consume or produce it.
+
+All types are exported from the package root:
+
+```ts
+import type {
+  AppendContentOptions,
+  AutoSubmitOptions,
+  FieldFormatConfig,
+  FieldFormatConfigMap,
+  FieldValidationContext,
+  FieldValidationRules,
+  FieldValidator,
+  FormatType,
+  FormController,
+  FormControllerOptions,
+  FormCleanup,
+  FormDataPrimitive,
+  FormErrors,
+  FormFieldElement,
+  FormFieldValue,
+  FormFieldWatcher,
+  FormsApi,
+  FormsAvailable,
+  FormStateListener,
+  FormStateSnapshot,
+  FormSubmitHandler,
+  FormTarget,
+  FormValues,
+  NewFormInput,
+  RuleConfig,
+  SerializedFormResult,
+  SerializedFormValue,
+  ValidationResult,
+  ValidationSchema,
+  ValueValidationRules,
+  VisualAttributes
+} from '@samline/forms'
+```
+
+---
+
+## `FormController`
+
+The full controller surface returned by [`form()`](api/form.md). All public methods are defined here.
+
+```ts
+interface FormController {
+  readonly element: HTMLFormElement | null
+  readonly f: HTMLFormElement | null
+  readonly options: FormControllerOptions
+  onSubmit: (callback: FormSubmitHandler, preventDefault?: boolean) => FormController
+  addCleanup: (cleanup: FormCleanup) => () => void
+  watch: (field: string, callback: FormFieldWatcher) => FormController
+  observe: (field: string, callback: FormFieldWatcher) => () => void
+  unwatch: (field?: string, callback?: FormFieldWatcher) => FormController
+  subscribe: (listener: FormStateListener) => () => void
+  prefill: (fieldName?: string) => FormController
+  append: (options: AppendContentOptions) => HTMLElement | null
+  setErrors: (fields: string[] | FormErrors) => FormController
+  clearErrors: (fields?: string[]) => FormController
+  setValue: (name: string, value: unknown) => FormController
+  validate: (fields?: string[]) => ValidationResult
+  revalidate: (fields?: string[]) => ValidationResult
+  /**
+   * Apply the same `@samline/formatter` pipeline to a single field or
+   * to a list of fields sharing one configuration. Chainable.
+   *
+   * Requires the optional peer dependency `@samline/formatter`. When
+   * the peer is not installed the call logs a single `console.error`
+   * and returns the controller unchanged.
+   */
+  format: (config: FieldFormatConfig) => FormController
+  formatAll: (config: FieldFormatConfig) => FormController
+  reset: () => FormController
+  autoSubmit: (options?: boolean | AutoSubmitOptions) => FormController
+  disableAutoSubmit: () => FormController
+  getValue: (name: string) => FormFieldValue
+  getField: (name: string) => FormFieldElement | FormFieldElement[] | null
+  getData: () => SerializedFormResult
+  getState: () => FormStateSnapshot
+  destroy: () => void
+}
+```
+
+---
+
+## `FormControllerOptions`
+
+The second argument to [`form()`](api/form.md). See [docs/options.md](options.md) for the full reference.
+
+```ts
+interface FormControllerOptions {
+  attributes?: Partial<VisualAttributes>
+  autoValidate?: boolean
+  autoSubmit?: boolean | AutoSubmitOptions
+  clearManualErrorsOnChange?: boolean
+  clearErrorsOnSubmit?: boolean
+  validators?: ValidationSchema
+  /**
+   * Declarative format configuration. Each entry is applied during
+   * `form()` initialization using the same logic as `controller.format(...)`.
+    * The key is just an identifier — the canonical field name lives in
+   * `FieldFormatConfig.field`.
+   */
+  formats?: FieldFormatConfigMap
+}
+```
+
+---
+
+## `FormTarget`
+
+What [`form()`](api/form.md) accepts as its first argument.
+
+```ts
+type FormTarget =
+  | string                                  // element id
+  | HTMLFormElement                         // direct element
+  | { current: HTMLFormElement | null }     // ref-like
+  | null
+  | undefined
+```
+
+A string is treated as a `document.getElementById(id)` lookup; only `HTMLFormElement` matches count. A ref-like value lets you pass a Vue/React-style ref object.
+
+---
+
+## `FormFieldElement`
+
+The set of DOM field types the controller manages.
+
+```ts
+type FormFieldElement =
+  | HTMLInputElement
+  | HTMLSelectElement
+  | HTMLTextAreaElement
+```
+
+Returned by [`getField`](api/get-field.md).
+
+---
+
+## `FormFieldValue`
+
+The normalized value of a field.
+
+```ts
+type FormFieldValue = string | string[] | File[] | undefined
+```
+
+- `string` — for text inputs, textareas, single selects, and single checked checkboxes / radios.
+- `string[]` — for checkbox groups, multiple selects, and repeated `name="field[]"` controls. Radio groups remain scalar.
+- `File[]` — for `<input type="file">` (may be empty).
+- `undefined` — when no field with that name exists.
+
+Returned by [`getValue`](api/get-value.md).
+
+---
+
+## `FormValues`
+
+The aggregated values map produced by the controller and the helpers.
+
+```ts
+type FormValues = Record<string, FormFieldValue>
+```
+
+Useful when you build custom validators that need cross-field logic beyond exact equality (`sameAs` handles equality directly):
+
+```ts
+form('booking-form', {
+  validators: {
+    end_date: {
+      validate: ({ value, values }) =>
+        typeof value === 'string' &&
+        typeof values.start_date === 'string' &&
+        value >= values.start_date
+          ? null
+          : 'End date must not precede start date.'
+    }
+  }
+})
+```
+
+The controller infers reactive dependencies from `sameAs`, but not from arbitrary reads inside `validate`. Add `dependsOn: 'start_date'` to the `end_date` rules when changes to the source should automatically revalidate the custom rule.
+
+---
+
+## `FormErrors`
+
+A map from field name to an array of error messages. Each field can have multiple errors (one per failed rule or per failing custom validator).
+
+```ts
+type FormErrors = Record<string, string[]>
+```
+
+Drives the `css-error` attribute on fields and is returned inside [`FormStateSnapshot`](#formstatesnapshot) and [`ValidationResult`](#validationresult).
+
+---
+
+## `FormStateSnapshot`
+
+The shape returned by [`getState()`](api/get-state.md). Built fresh on every call — it does not retain references to controller internals.
+
+```ts
+interface FormStateSnapshot {
+  values: FormValues
+  errors: FormErrors
+  filledFields: string[]
+  isValid: boolean
+  isValidated: boolean
+  autoSubmit: boolean
+  isSubmitting: boolean
+  submitCount: number
+}
+```
+
+| Field | Meaning |
+| --- | --- |
+| `values` | Current values for every tracked field. |
+| `errors` | Merged validation and manual errors. |
+| `filledFields` | Names of fields that have a non-empty value. |
+| `isValid` | `true` when `errors` has no entries. |
+| `isValidated` | `true` after the initial auto-validation pass or once [`validate`](api/validate.md) has run. |
+| `autoSubmit` | `true` while auto-submit is enabled. |
+| `isSubmitting` | `true` while one or more valid submissions have asynchronous handlers that have not settled. |
+| `submitCount` | Number of submit attempts (valid or invalid). |
+
+---
+
+## `FormStateListener`
+
+The callback passed to [`subscribe`](api/subscribe.md).
+
+```ts
+type FormStateListener = (state: FormStateSnapshot) => void
+```
+
+Receives the current snapshot immediately, then at controller notification points such as handled input, manual-error changes, reset, submit attempts, async-submit state transitions, auto-submit toggles, and observed DOM mutations. A direct `validate()` call does not independently notify it.
+
+---
+
+## `FormSubmitHandler`
+
+The callback passed to [`onSubmit`](api/on-submit.md).
+
+```ts
+type FormSubmitHandler = (
+  form: HTMLFormElement,
+  data: Record<string, SerializedFormValue>,
+  formData: FormData,
+  state: FormStateSnapshot
+) => void | Promise<void>
+```
+
+Only invoked when the form is valid. `data` and `formData` are produced fresh on each invocation. Returned promises are tracked by `FormStateSnapshot.isSubmitting`; fulfillment or rejection settles the tracked work.
+
+---
+
+## `FormFieldWatcher`
+
+The callback passed to [`watch`](api/watch.md) and [`observe`](api/observe.md).
+
+```ts
+type FormFieldWatcher = (
+  value: FormFieldValue,
+  field: FormFieldElement | FormFieldElement[] | null,
+  form: HTMLFormElement,
+  state: FormStateSnapshot
+) => void
+```
+
+- `value` — the current value of the field that just changed.
+- `field` — the DOM element(s) backing the field (same shape as [`getField`](api/get-field.md) returns). For a single matching field it is `HTMLInputElement` / `HTMLSelectElement` / `HTMLTextAreaElement`; for repeated fields (e.g. checkbox / radio groups) it is an array of them; it is `null` when no element matches the name.
+- `form` — the bound `HTMLFormElement`.
+- `state` — a snapshot of the whole controller state (see [`FormStateSnapshot`](#formstatesnapshot)).
+
+`observe` and `watch` fire once immediately with the current value, then on every matching `input` event. `observe` returns an unsubscribe function; `watch` returns the controller.
+
+---
+
+## `SerializedFormResult`
+
+The shape returned by [`getData()`](api/get-data.md) and [`parseFormData()`](api/parse-form-data.md).
+
+```ts
+interface SerializedFormResult {
+  data: Record<string, SerializedFormValue>
+  formData: FormData
+}
+```
+
+`data` is a plain object mirror of the `FormData`. Repeated names become arrays (e.g. `interests: ['design', 'code']`). Empty file entries are filtered out.
+
+---
+
+## `SerializedFormValue`
+
+The value shape inside `SerializedFormResult.data`.
+
+```ts
+type SerializedFormValue = FormDataPrimitive | FormDataPrimitive[]
+
+type FormDataPrimitive = FormDataEntryValue
+```
+
+`FormDataEntryValue` is `string | File` in the DOM lib types.
+
+---
+
+## `ValidationResult`
+
+The shape returned by [`validate`](api/validate.md), [`revalidate`](api/revalidate.md), and [`validateValues`](api/validate-values.md).
+
+```ts
+interface ValidationResult {
+  isValid: boolean
+  errors: FormErrors
+}
+```
+
+`errors` is always a fresh object — safe to mutate.
+
+---
+
+## `ValidationSchema`
+
+The shape of `options.validators`.
+
+```ts
+type ValidationSchema = Record<string, FieldValidationRules>
+```
+
+```ts
+form('signup-form', {
+  validators: {
+    email: { required: true, pattern: /^[^\s@]+@[^\s@]+\.[^\s@]+$/ },
+    password: { required: true, minLength: 8 }
+  }
+})
+```
+
+---
+
+## `FieldValidationRules`
+
+The rule set for a single field.
+
+```ts
+interface FieldValidationRules extends ValueValidationRules {
+  sameAs?: RuleConfig<string>
+  dependsOn?: string | string[]
+  each?: ValueValidationRules
+}
+
+interface ValueValidationRules {
+  required?: RuleConfig<boolean>
+  minLength?: RuleConfig<number>
+  maxLength?: RuleConfig<number>
+  pattern?: RuleConfig<RegExp>
+  numeric?: RuleConfig<boolean>
+  min?: RuleConfig<number>
+  max?: RuleConfig<number>
+  validate?: FieldValidator | FieldValidator[]
+}
+```
+
+Value rules run in the order: `required` → `minLength` → `maxLength` → `pattern` → numeric bounds → `validate`. Field-level `sameAs` and member-level `each` are then evaluated. All are optional; an empty rules object contributes nothing.
+
+`sameAs` names another exact field key. It compares non-empty strings exactly and arrays by ordered contents; file entries compare by `File` object identity. In a controller, changing the referenced field automatically revalidates the field that declares `sameAs`. Reciprocal declarations are cycle-safe, but usually duplicate the same error on both controls; prefer declaring the rule only on the confirmation field.
+
+`dependsOn` declares one or more exact source field names for controller revalidation. It is intended for custom validators that read `values`; it does not add an error or affect the pure helpers by itself. Dependency chains and cycles are traversed once per input event.
+
+`each` applies a `ValueValidationRules` object to every collection member independently. Controller validation can therefore mark only the failing DOM controls, while [`FormErrors`](#formerrors) remains a flat `Record<string, string[]>` with item messages collected under the field name.
+
+## `ValueValidationRules`
+
+The exported subset of rules that can validate one value, including each member of a collection. It excludes field-level `sameAs`, `dependsOn`, and nested `each`.
+
+`numeric`, `min`, and `max` skip empty values. Non-empty input must be a finite ordinary signed decimal: decimal integers and fractions are accepted, while exponent notation, hexadecimal, `Infinity`, `NaN`, and formatted separators are rejected. `min` and `max` are inclusive and imply numeric parsing even when `numeric` is omitted.
+
+---
+
+## `RuleConfig<T>`
+
+Lets a rule be configured with a plain value or a `{ value, message }` object.
+
+```ts
+type RuleConfig<T> = T | { value: T; message?: string }
+```
+
+```ts
+form('signup-form', {
+  validators: {
+    password: {
+      minLength: { value: 8, message: 'Use at least 8 characters.' }
+    },
+    terms: {
+      required: { value: true, message: 'Please accept the terms.' }
+    }
+  }
+})
+```
+
+When the plain form is used, default messages are produced automatically.
+
+---
+
+## `FieldValidationContext`
+
+The argument passed to a custom validator.
+
+```ts
+interface FieldValidationContext {
+  field: string
+  value: FormFieldValue
+  values: FormValues
+  element?: FormFieldElement
+  index?: number
+}
+```
+
+`element` and `index` are populated while a bound controller evaluates an `each` member. `index` is zero-based. Pure helper validation has no DOM element, so `element` remains undefined; `index` is still provided for array members.
+
+Use it to write cross-field validators:
+
+```ts
+form('checkout-form', {
+  validators: {
+    card: {
+      validate: ({ value, field }) => {
+        if (typeof value !== 'string') return `${field} is required.`
+        return /^\d{16}$/.test(value.replace(/\s+/g, ''))
+          ? null
+          : 'Card number must be 16 digits.'
+      }
+    }
+  }
+})
+```
+
+---
+
+## `FieldValidator`
+
+The custom validator signature.
+
+```ts
+type FieldValidator = (
+  context: FieldValidationContext
+) => string | undefined | null | false | true
+```
+
+| Return | Meaning |
+| --- | --- |
+| `string` (non-empty) | Push as the error message. |
+| `undefined`, `null`, `true` | Pass. |
+| `false` | Push the generic error message `"Validation failed."`. |
+
+Multiple validators can be chained by passing an array as `validate`:
+
+```ts
+form('order-form', {
+  validators: {
+    quantity: {
+      validate: [
+        ({ value }) => (typeof value === 'string' && Number(value) > 0 ? null : 'Must be greater than zero.'),
+        ({ value }) => (typeof value === 'string' && Number.isInteger(Number(value)) ? null : 'Must be an integer.')
+      ]
+    }
+  }
+})
+```
+
+---
+
+## `FormCleanup`
+
+The callback accepted by [`addCleanup()`](api/add-cleanup.md).
+
+```ts
+type FormCleanup = () => void
+```
+
+Cleanups are synchronous and run once in reverse registration order during `destroy()`, unless their returned unregister function removes them first.
+
+---
+
+## `AutoSubmitOptions`
+
+The argument to [`autoSubmit()`](api/auto-submit.md) and the `autoSubmit` option.
+
+```ts
+interface AutoSubmitOptions {
+  debounce?: number
+}
+```
+
+`debounce` is in milliseconds.
+
+---
+
+## `AppendContentOptions`
+
+The argument to [`append()`](api/append.md).
+
+```ts
+interface AppendContentOptions {
+  tag: keyof HTMLElementTagNameMap
+  content: string
+  class?: string
+  atStart?: boolean
+}
+```
+
+| Field | Meaning |
+| --- | --- |
+| `tag` | The HTML tag to create. |
+| `content` | `innerHTML` content for the new node. |
+| `class` | Optional class name. If a node with the same first class already exists inside the form, it is removed before the new one is inserted. |
+| `atStart` | When `true`, inserts at the start of the form. Defaults to `false` (append at the end). |
+
+---
+
+## `VisualAttributes`
+
+The shape of `options.attributes`.
+
+```ts
+interface VisualAttributes {
+  filled: string
+  error: string
+}
+```
+
+`Partial<VisualAttributes>` is accepted, so you can override only one of them. See [docs/css-styling.md](css-styling.md).
+
+---
+
+## `FieldFormatConfig` and `FieldFormatConfigMap`
+
+The argument to [`format()`](api/format.md) and [`formatAll()`](api/format.md). The map is the shape of `options.formats`.
+
+```ts
+type FormatType =
+  | 'general'
+  | 'phone'
+  | 'numeral'
+  | 'date'
+  | 'time'
+  | 'creditCard'
+  | 'creditCardType'
+
+interface FieldFormatConfig {
+  type: FormatType
+  field: string | string[]
+  displayField?: string
+  options?: Record<string, unknown>
+}
+
+type FieldFormatConfigMap = Record<string, FieldFormatConfig>
+```
+
+The `field` name is the **canonical** name of the formatted pair. A custom `displayField` is valid only for one string field; passing it with a field array logs an error and leaves the form unchanged. Array configurations derive `${fieldName}_displayed` independently for every field. Every map value includes its own `field` because the map key is only an identifier. See [The mirror convention](api/format.md#the-mirror-convention).
+
+---
+
+## `FormsApi`
+
+The shape of the [`browser`](../getting-started.md#browser-registry-helpers) singleton exported from the vanilla entrypoint. The IIFE bundle exposes the same shape as `window.Forms`.
+
+```ts
+interface FormsApi {
+  form: (target: FormTarget, options?: FormControllerOptions) => FormController
+  newForm: (input: NewFormInput) => FormController | undefined
+  destroyForm: (id: string) => void
+  available: FormsAvailable
+}
+```
+
+`form` is the same reference exported from `@samline/forms`. `newForm` and `destroyForm` manage the module-level `available` registry keyed by the form id. Spread `browser` into a new object to derive an independent registry (with its own `available` map); see the getting-started guide for the pattern.
+
+---
+
+## `NewFormInput`
+
+The argument to `FormsApi.newForm`.
+
+```ts
+interface NewFormInput {
+  id: string
+  options?: FormControllerOptions
+}
+```
+
+A missing `id` logs `Form ID is required` to `console.error` and `newForm` returns `undefined` without touching the registry.
+
+---
+
+## `FormsAvailable`
+
+The shape of `FormsApi.available`.
+
+```ts
+interface FormsAvailable {
+  [id: string]: FormController
+}
+```
+
+Use it to inspect or iterate over every live controller in a registry. Each entry is the `FormController` returned by `newForm` for that id.
+
+`Partial<VisualAttributes>` is accepted, so you can override only one of them. See [docs/css-styling.md](css-styling.md).

package/docs/vanilla.md

@@ -0,0 +1,12 @@
+# Vanilla
+
+The vanilla documentation has been reorganised into a modular tree. Start here:
+
+- [Getting started](getting-started.md) — concepts, observable contract, lifecycle, and the side-effect overview.
+- [Options reference](options.md) — every `FormControllerOptions` field with defaults.
+- [CSS styling](css-styling.md) — `css-filled` / `css-error` recipes and accessibility notes.
+- [TypeScript reference](typescript.md) — every exported type, with examples.
+- [API reference](api/index.md) — one page per public method.
+- [Recipes](recipes.md) — end-to-end patterns.
+
+If you arrived here from an older link, the equivalent of the previous one-page vanilla guide is now [docs/getting-started.md](getting-started.md).