@samline/forms 2.4.0 → 2.6.0

package/docs/typescript.md

@@ -0,0 +1,576 @@
+# 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,
+  FormDataPrimitive,
+  FormErrors,
+  FormFieldElement,
+  FormFieldValue,
+  FormFieldWatcher,
+  FormsApi,
+  FormsAvailable,
+  FormStateListener,
+  FormStateSnapshot,
+  FormSubmitHandler,
+  FormTarget,
+  FormValues,
+  NewFormInput,
+  RuleConfig,
+  SerializedFormResult,
+  SerializedFormValue,
+  ValidationResult,
+  ValidationSchema,
+  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
+  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 can infer reactive dependencies from `sameAs`, but not from arbitrary reads inside `validate`. If `start_date` changes after `end_date` has been validated, explicitly revalidate `end_date` or watch the source field.
+
+---
+
+## `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
+  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` once [`validate`](api/validate.md) has run at least once. |
+| `autoSubmit` | `true` while auto-submit is enabled. |
+| `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, 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
+```
+
+Only invoked when the form is valid. `data` and `formData` are produced fresh on each invocation.
+
+---
+
+## `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 {
+  required?: RuleConfig<boolean>
+  minLength?: RuleConfig<number>
+  maxLength?: RuleConfig<number>
+  pattern?: RuleConfig<RegExp>
+  sameAs?: RuleConfig<string>
+  validate?: FieldValidator | FieldValidator[]
+}
+```
+
+Rules run in the order: `required` → `minLength` → `maxLength` → `pattern` → `sameAs` → `validate`. 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.
+
+---
+
+## `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
+}
+```
+
+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.')
+      ]
+    }
+  }
+})
+```
+
+---
+
+## `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).

package/package.json

@@ -1,10 +1,25 @@
 {
   "name": "@samline/forms",
-  "version": "2.4.0",
-  "description": "Form controller for vanilla JS and direct browser usage.",
+  "version": "2.6.0",
+  "description": "TypeScript-first, framework-free form controller with validation, reactive state, serialization, auto-submit, and input formatting.",
+  "keywords": [
+    "forms",
+    "form-validation",
+    "form-state",
+    "typescript",
+    "vanilla-javascript",
+    "browser"
+  ],
   "type": "module",
   "license": "MIT",
   "homepage": "https://samline.github.io/forms",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/samline/forms.git"
+  },
+  "bugs": {
+    "url": "https://github.com/samline/forms/issues"
+  },
   "publishConfig": {
     "access": "public",
     "tag": "latest"
@@ -12,21 +27,40 @@
   "engines": {
     "node": ">=20"
   },
-  "sideEffects": false,
+  "sideEffects": [
+    "./dist/browser/index.js",
+    "./dist/browser/index.cjs",
+    "./dist/browser/global.global.js"
+  ],
   "files": [
-    "dist"
+    "dist",
+    "docs"
   ],
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.cjs"
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
     },
     "./browser": {
-      "types": "./dist/browser/global.d.ts",
+      "import": {
+        "types": "./dist/browser/index.d.ts",
+        "default": "./dist/browser/index.js"
+      },
+      "require": {
+        "types": "./dist/browser/index.d.cts",
+        "default": "./dist/browser/index.cjs"
+      }
+    },
+    "./browser/global": {
       "default": "./dist/browser/global.global.js"
     }
   },
@@ -37,8 +71,10 @@
     "pack:check": "npm pack --dry-run",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:package": "node scripts/test-package.mjs && tsc -p tsconfig.package.json",
     "test:watch": "vitest",
-    "prepublishOnly": "npm run clean && npm run build && npm run typecheck && npm test"
+    "prepublishOnly": "npm run clean && npm run build && npm run typecheck && npm test && npm run test:package && npm run pack:check"
   },
   "peerDependencies": {
     "@samline/formatter": "^2.0.0"
@@ -48,12 +84,20 @@
       "optional": true
     }
   },
+  "overrides": {
+    "esbuild": "^0.28.1",
+    "nanoid": "^3.3.18",
+    "postcss": "^8.5.23",
+    "vite": "^8.0.0"
+  },
   "devDependencies": {
     "@samline/formatter": "^2.0.0",
-    "@types/node": "^24.0.0",
-    "jsdom": "^26.1.0",
-    "tsup": "^8.5.0",
-    "typescript": "^5.8.3",
-    "vitest": "^3.1.1"
+    "@types/node": "^26.6.2",
+    "@vitest/coverage-v8": "^5.0.1",
+    "jsdom": "^30.1.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vite": "^8.0.0",
+    "vitest": "^5.0.1"
   }
 }