@samline/forms 2.7.2 → 2.9.0

package/CHANGELOG.md

@@ -0,0 +1,316 @@
+# Changelog
+
+All notable changes to `@samline/forms` are documented in this file. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [2.9.0] - 2026-11-12
+
+No breaking API changes.
+
+### Added
+
+- `setOptions(name, options, config?)` replaces the options of a `<select>` with strings, numbers, `{ value, label, disabled, selected }` objects or `{ label, options }` groups. Labels are written as text. The current value is kept when it is still listed (`keepValue: true` by default), and the change pipeline runs once, only when the selected value changes ([#13](https://github.com/samline/forms/issues/13)). New exported types: `SelectOption`, `SelectOptionGroup`, `SelectOptionInput` and `SetOptionsConfig`.
+- `watch()` and `observe()` accept an array of field names. The callback receives `(values, changed, form, state)`: one value per listed field and the name of the field that changed (`null` on registration and after `reset()`). It fires once per change of any listed field. `unwatch(fields, callback?)` removes these watchers. New exported type: `FormFieldsWatcher` ([#10](https://github.com/samline/forms/issues/10)).
+
+### Fixed
+
+- Adding or removing `<option>` elements outside the controller is no longer ignored. When it changes a select's value, the controller revalidates, updates `css-filled` / `css-error`, fires watchers and notifies subscribers.
+
+## [2.8.0] - 2026-11-06
+
+No breaking API changes. The behavior changes below fix incorrect or surprising results; review them if your code relied on the old behavior.
+
+### Fixed
+
+- `prefill()` writes a repeated query key (`?tags[]=a&tags[]=b`) once as an array instead of keeping only the last value, and auto-submit runs once after the whole prefill instead of once per field.
+- A native `<button type="reset">` or a direct `form.reset()` now clears errors, `css-filled`, `css-error` and `aria-invalid` and restores formatted mirrors, like `reset()`. A canceled `reset` event is respected.
+- The form's `MutationObserver` ignores markup that contains no form controls, so a subscriber that renders messages or a summary into the form no longer re-enters validation in an endless loop.
+- An invalid submit started by auto-submit no longer moves focus away from the field being edited.
+- After a failed submit, focus goes to the first invalid control in document order instead of the first field declared in `validators`.
+- Formatting no longer moves the selection of an input that does not have focus (initial values, `setValue()`, `reset()`), which could also focus it in Safari.
+- After `destroy()`, mutating methods (`setValue`, `setErrors`, `clearErrors`, `validate`, `revalidate`, `reset`, `prefill`, `append`, `autoSubmit`) and new registrations (`subscribe`, `observe`, `watch`, `onSubmit`) are no-ops, so an async handler that settles late cannot repaint a form now owned by another controller. `validate()` returns `{ isValid: true, errors: {} }`.
+- `window.Forms` from the standalone script has exactly `form`, `newForm`, `destroyForm` and `available`; it no longer includes a `default` key.
+
+### Changed
+
+- `reset()` and native resets call `watch()`/`observe()` callbacks with the restored values.
+- A rejected promise returned by an `onSubmit()` handler is reported with `console.error('[forms] submit handler failed', reason)` instead of being swallowed. `isSubmitting` still settles.
+- The standalone `dist/browser/global.global.js` is minified (about 188 KB instead of 343 KB before compression); module builds are unchanged.
+- State reads index the form's controls once per snapshot instead of once per field name.
+- Raised the optional `@samline/formatter` peer and development dependency to `^2.1.0` (released 2026-11-06). The standalone script now bundles it, including its fixes for `regex.numeral`, `regex.password`, case-insensitive phone countries and decorated `general` masks.
+- Documentation moved to the website at <https://samline.github.io/forms/docs/>. The npm tarball now ships `dist`, `README.md`, `LICENSE.md` and `CHANGELOG.md`; the Markdown `docs/` folder is no longer published. Old Starlight URLs redirect to their new pages.
+
+### Added
+
+- A landing page, twelve live examples with copyable HTML / CDN and Package / ESM files, framework guides and an AI agent skill at `skills/forms/SKILL.md`.
+
+## [2.7.2] - 2026-09-23
+
+### Changed
+
+- Raised the optional `@samline/formatter` peer and development dependency minimum to `^2.0.3`, ensuring consumers receive the latest formatter fixes for empty date/time delimiters, suffix stripping, and parametric password validation.
+- Updated the npm-bundled and Starlight documentation examples to reference `@samline/forms@2.7.2`.
+
+## [2.7.1] - 2026-09-23
+
+### Fixed
+
+- Interpreted user input and rebind values as display-order data while retaining automatic detection for canonical mirrors and initial server values.
+
+### Changed
+
+- Synchronized the internal and Starlight formatter-integration documentation.
+- Removed duplicated implementation narratives and obsolete comments without changing the public API.
+
+## [2.7.0] - 2026-09-22
+
+### Added
+
+- Added explicit `dependsOn` metadata for reactive custom cross-field validation with transitive, cycle-safe dependency traversal.
+- Added per-member `each` validation with element-specific `css-error` and `aria-invalid` state for repeated controls while preserving the public `FormErrors` string-array shape.
+- Added strict decimal `numeric`, inclusive `min`, and inclusive `max` validation rules.
+- Added promise-aware submit tracking through `FormStateSnapshot.isSubmitting`, including concurrent and rejected handler promises.
+- Added `addCleanup()` for controller-owned integration teardown.
+
+### Fixed
+
+- Synchronized initial and reset `css-filled` state independently from `autoValidate`, without activating validation.
+- Resolved per-input visual validation state for repeated `name="foo[]"` controls ([#1](https://github.com/samline/forms/issues/1)).
+
+### Changed
+
+- Updated GitHub Actions, Astro, Starlight, and documentation tooling to their reviewed supported releases, including the Node and Astro compatibility floors required by those updates.
+- Synchronized the npm-bundled and Starlight documentation with every new public type, rule, method, and state transition.
+
+## [2.6.0] - 2026-09-21
+
+### Added
+
+- Added the declarative `sameAs` validation rule for password confirmations and other fields that must contain equal non-empty values, with custom messages through `RuleConfig<string>`.
+- Added automatic dependent-field revalidation for `sameAs`, including transitive dependencies, cycle-safe deduplication, `setValue()` updates, and activation after manual validation.
+- Added regression coverage for matching strings, ordered arrays, empty values, source-field changes, reciprocal cycles, and transitive dependencies.
+
+### Changed
+
+- Expanded the npm-bundled and Starlight documentation with `sameAs` recipes, exact equality semantics, empty-value behavior, file identity rules, cycle guarantees, and guidance to place mismatch errors on confirmation fields only.
+
+## [2.5.1] - 2026-09-20
+
+### Fixed
+
+- Corrected documentation for exact validator names, radio and collection values, subscriber notification points, destroyed-controller behavior, shared browser registries, formatter mirrors, and optional-peer behavior.
+
+### Added
+
+- Added focused Starlight guides for accessible validation and input formatting, plus references for native control behavior and package entrypoints.
+
+### Changed
+
+- Reorganized the documentation sidebar, expanded the API lifecycle contracts, improved accessible examples, and synchronized the npm-bundled and hosted documentation surfaces.
+
+## [2.5.0] - 2026-09-19
+
+### Fixed
+
+- Corrected the browser IIFE so `Forms.form`, `Forms.newForm`, `Forms.destroyForm`, and `Forms.available` are exposed directly instead of under `Forms.default`.
+- Fixed duplicate field processing, formatted-field reset state, submitter serialization, duplicate browser controllers, stateful regular expressions, external associated controls, multiple selects, reserved field names, escaped class names, pending auto-submit cancellation, and async formatter teardown.
+- Added `aria-invalid` synchronization and focus management for invalid submissions.
+
+### Added
+
+- Added ESM/CJS browser entrypoints, package artifact smoke tests, CJS/ESM type-consumer tests, coverage thresholds, pull-request CI, dependency auditing, and Dependabot configuration.
+- Added regression coverage for the corrected DOM, validation, serialization, formatting, and registry behavior.
+
+### Changed
+
+- Added `docs/` to the npm package, corrected conditional type exports, exported `FormDataPrimitive` and `FormFieldWatcher`, and made multi-field formatter configuration reject a shared `displayField` without mutating the form.
+- Updated root and documentation-site dependencies to audited versions and synchronized both documentation surfaces.
+
+## [2.4.0] - 2026-07-19
+
+### Fixed
+
+- `applyFormat` phase 2 and the capture-phase input handler now override `interpretInputAs` to `'auto'` for the initial value pass and for input events whose source is the hidden raw mirror, so a server pre-fill of the canonical raw (e.g. a Blade re-render with `value="{{ old('birthday') }}"` carrying `"19901212"` for a `d/m/Y` display + `Ymd` raw combo) is correctly converted to the display form on mount. Without the override, `@samline/formatter` v1.2.0+ — which changed `interpretInputAs` to default to `'display'` — mis-segmented the raw digits and the visible ended up showing the scrambled value (e.g. `"19/09/1212"`) instead of `"12/12/1990"`. As of `@samline/formatter@2.0.0`, the default is `'auto'` (which handles the same case via the formatter's own heuristic), so the override is now a defensive explicit declaration of intent rather than strictly required. It still serves two purposes: (1) it documents the controller's context awareness in code, and (2) it protects against a future formatter change that flips the default again. Live keystrokes on the visible input keep the formatter's default because what the user types is in display order. An explicit `interpretInputAs` in `config.options` is always respected, never overridden — pass `'display'` if you pre-render the visible in display order from the server, or `'raw'` if you want the legacy pre-1.2.0 round-trip semantics for the initial pass.
+
+### Added
+
+- Five regression tests under `test/api/format.test.ts`: the easytrip / Blade `old()` case (raw initial value → display form on mount), the live keystroke path (no `interpretInputAs` override applied to user typing), `setValue('field', raw)` writes the canonical raw with the `'auto'` interpretation forced, the explicit `interpretInputAs: 'display'` opt-in is preserved, and the re-bind path forwards the caller's options verbatim.
+
+### Changed
+
+- `docs/api/format.md` adds an "Initial value interpretation (server pre-fill)" section that documents the override and the four contexts (initial pass, mirror-source events, live keystrokes, re-bind) with the explicit opt-in caveat. With the formatter v2.0.0 default flip, the prose now notes that the override is defensive rather than strictly required.
+- `example/src/content/docs/reference/api.md` (Starlight mirror) gains a "Server pre-fill" note in the `format()` summary so the npm-bundled docs and the live site stay in sync.
+- `example/src/content/docs/reference/typescript.md` notes the `interpretInputAs` override in the `FieldFormatConfig` prose so consumers reading the type signature know the initial pass is the special case.
+- The peer dependency `@samline/formatter` is now `^2.0.0` (was `^1.0.1`). The `^1.x` range no longer receives the v2.0.0 fix, so consumers on the previous major must pin explicitly or upgrade.
+
+## [2.3.4] - 2026-07-16
+
+### Fixed
+
+- `readFieldValue` and `writeFieldValue` now respect the `name="foo[]"` convention for multi-value inputs. Previously, `getValue` returned only the first matching input's value and `setValue` wrote the same string to every matching input, breaking custom validators that check `Array.isArray(value)` on fields like `docusign_email[]`. The `[]` suffix is the de facto HTML pattern for array inputs (PHP, Rails, Express, Spring); the controller now treats it as the explicit signal for "collect all values as an array".
+
+### Added
+
+- Eleven regression tests under `test/api/array-syntax.test.ts` covering `getValue` / `setValue` with `name="foo[]"` for text, email, checkbox, and file inputs (the last via a hand-built `FileList`), plus guards that `name="foo"` (no brackets) keeps the original first-value / broadcast semantics and that custom validators keyed on the bracketed name now receive the full array.
+
+### Changed
+
+- `docs/api/get-value.md` and `docs/api/set-value.md` document the `name="foo[]"` behaviour in the per-field-type tables, with a new example for each direction and a dedicated edge-case bullet describing the explicit opt-in. `example/src/content/docs/reference/api.md` mirrors the note in the Starlight reference so the npm-bundled docs and the live site stay in sync.
+
+## [2.3.3] - 2026-07-16
+
+### Fixed
+
+- `syncVisualState` was routing `css-filled` and `css-error` to the **visible** input only on the user-typing path (`handleDelegatedEvent`). Every other path — `validate()`, `revalidate()`, `setErrors()`, `clearErrors()` with a name list, the initial mount, and the `MutationObserver`-driven re-sync — still wrote the attribute to the hidden raw mirror. For formatted fields the project label never matched `:has([css-error])` and the error indicator was invisible. The fix centralises the canonical→display name resolution inside `syncVisualState` itself, so all five call sites are fixed at once and the visual attribute contract documented in `api/format.ts` is honoured by every public entrypoint.
+
+### Added
+
+- Seven regression tests under `test/api/format.test.ts`: `validate()` (no-arg and with an explicit name list), `revalidate()`, `setErrors()` (array and map form), `clearErrors()` with a name list, and the initial-mount path with a pre-populated hidden mirror.
+
+### Changed
+
+- `docs/css-styling.md` adds a callout after the `:has()` recipe explaining that the hidden mirror created by `format()` lives outside any label and that the controller always targets the visible.
+- `docs/recipes.md` adds a one-liner to the mirror-convention section cross-referencing the styling page.
+
+## [2.3.2] - 2026-07-16
+
+### Fixed
+
+- `css-filled` and `css-error` were being written to the hidden raw mirror for fields wired through `format()`, so the `:has([css-filled])` selector on the project label parent never matched and the label text stayed invisible. `handleDelegatedEvent` now resolves the event target to the display name and calls `syncVisualState([displayName])` so visual attributes land on the element the user sees. The data path (validation, errors, raw mirror) is unchanged.
+
+### Added
+
+- Three regression tests for the user-typing path: `css-filled` on the visible after a keystroke, `css-filled` on the visible when `setValue` writes the canonical, and a guard for non-formatted fields.
+
+## [2.3.1] - 2026-07-15
+
+### Fixed
+
+- When `format()` was called multiple times in the same tick (e.g. `format(phone)` + `format(date)` + `format(general)` at form init), the first `applyFormat` to resume from `await loadFormatter()` would bind every entry in the bucket with the first call's config; the subsequent calls short-circuited on the "already bound" check. The easytrip registration form hit this: phone formatter ran for all three fields, so date and tag_number output was phone-style instead of date / general. Phase 2 of `applyFormat` is now scoped to the entries the current call touched (via a local `phase1Entries` array) instead of iterating the whole bucket.
+
+### Added
+
+- Regression test covers the three-sequential-`format()` case end-to-end.
+
+## [2.3.0] - 2026-07-15
+
+### Changed
+
+- **`format()` mirror convention inverted.** The canonical name (`<field>`) now carries the raw value on a hidden input appended to the form; the visible input is renamed to `<field>_displayed` (or whatever `displayField` resolves to). 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, etc. `rawField` config renamed to `displayField`.
+- `format()` runs in two phases: phase 1 (sync) renames the visible and creates/reuses the hidden mirror; phase 2 (async) loads the formatter peer and binds the input listener. The sync phase rolls back on a missing peer so the DOM is left exactly as the developer authored it.
+- `state.listeners` tracks `capture?` to match `addEventListener` (`exactOptionalPropertyTypes: true`).
+- `destroy()` restores the visible's name to the canonical form and detaches every capture-phase listener added by `format()`.
+
+### Notes
+
+- No peer changes — options are still forwarded to `@samline/formatter` as before, so `datePattern`, `dateRawPattern`, `rawPrefix`, `rawSuffix`, `prefixMode`, `suffixMode`, etc. all keep working identically.
+
+## [2.2.3] - 2026-07-14
+
+### Fixed
+
+- Cursor jumped past digits when backspacing adjacent to a delimiter. `applyFormattedValue` ignored `InputEvent.inputType` and `computeCursorPosition` counted non-format characters to the left of the caret without ever pulling the cursor back past a re-inserted delimiter. After a `deleteContentBackward` / `deleteWordBackward` the caret could land with a format character immediately on its left, so the next backspace removed the delimiter instead of the digit the user expected to delete.
+- `applyFormattedValue` now threads `InputEvent.inputType` from `buildHandler` and applies cleave.js' `postDelimiterBackspace` scan in **both** branches of the function (early-return and full `computeCursorPosition`), so the contract holds whether or not the formatter rewrites the visible value.
+
+### Added
+
+- Four vitest cases under `test/api/format.test.ts` covering the `postDelimiterBackspace` contract for `deleteContentBackward` adjacent to a delimiter, deletion of a delimiter itself, `deleteWordBackward` in the middle of a formatted value, and a DD/MM/YYYY date field with the caret parked after the first slash.
+
+## [2.2.2] - 2026-07-10
+
+### Fixed
+
+- `@samline/formatter` peer was being silently left as a bare specifier in the IIFE bundle, so `format()` / `formatAll()` did not run in Vite / Rollup production builds. The dynamic import carried a `/* @vite-ignore */` hint, which told Rollup to leave the literal `'@samline/formatter'` in the bundle.
+- The IIFE build now bundles the peer; ESM and CJS still externalize it. Consumers that need to ship the formatter separately can do so via a bundler-level externals configuration.
+
+## [2.2.1] - 2026-06-30
+
+### Changed
+
+- Documentation references aligned to 2.2.1 (CDN URLs in `README.md` and `docs/browser.md`).
+
+## [2.2.0] - 2026-06-30
+
+### Added
+
+- `browser` singleton export for bundler usage — the same `{ form, newForm, destroyForm, available }` surface as the IIFE, but as a module-level singleton, so bundler consumers can use the registry helpers without opting into the IIFE `globalThis` side-effect.
+
+### Fixed
+
+- `format()` integration tests: raw mirror handling on `setValue` writing the display name (the visible's `.value` was being clobbered by the canonical write path).
+
+## [2.1.0] - 2026-06-30
+
+> Not tagged at the time. The version was bumped and published; this entry is reconstructed from the commit log between v1.0.3 and v2.2.0.
+
+### Added
+
+- `@samline/formatter` peer dependency. The controller reads the peer at runtime via a dynamic import; a missing peer is non-fatal — a single `console.error` is logged and `format()` becomes a no-op so the rest of the form keeps working.
+- `format()` / `formatAll()` / `format` options API: `type`, `field` (string or `string[]`), `options` forwarded to the peer, `displayField` for the visible's name.
+- `onSubmit`, `watch`, `observe`, `unwatch`, `subscribe`, `prefill`, `append`, `setErrors`, `clearErrors`, `setValue`, `getValue`, `getField`, `getData`, `getState`, `reset`, `autoSubmit`, `disableAutoSubmit`, `validate`, `revalidate`, `destroy` — the per-method api/ factories.
+
+### Changed
+
+- **Package focus narrowed to vanilla JS and direct browser usage.** Framework-specific variants and docs were removed (`refactor: remove framework-specific variants and docs, simplify package structure`). The README was rewritten to reflect the new focus.
+- Browser global renamed to `Forms` and a registry helper added: `Forms.newForm({ id, options })` stores the controller under `Forms.available[id]`, `Forms.destroyForm(id)` calls `destroy()` and removes the entry.
+- `watch()` and `observe()` callbacks now receive the field element(s) as an additional argument, so consumers can read attributes (`css-filled`, `css-error`, `aria-*`, …) without doing their own DOM lookup.
+- "API at a glance" section added to the README and browser usage clarified.
+- Installation instructions updated to use `bun`.
+- Deployment branch for the GitHub Pages docs site changed to `v2`.
+- Accessibility skill and patterns documented.
+
+## [1.0.3] - 2026-05-31
+
+### Fixed
+
+- Manual errors were not cleared when the affected field changed. The controller now deletes the entry from `state.manualErrors[canonical]` on the next `input` / `change` event of the affected field, unless `clearManualErrorsOnChange: false` is passed via `FormControllerOptions`.
+
+## [1.0.2] - 2026-03-24
+
+### Fixed
+
+- `npm publish` workflow was failing in CI; auth check fixed.
+
+## [1.0.1] - 2026-03-24
+
+### Fixed
+
+- First stable patch on the 1.x line (release plumbing).
+
+## [1.0.0] - 2026-03-24
+
+### Fixed
+
+- `npm publish` workflow: npm auth check on the publish job.
+
+## [0.1.0] - 2026-03-24
+
+### Added
+
+- Initial release of `@samline/forms`. Vanilla JS form controller with framework-specific variants (React, Vue, Svelte) initially included; bundled `.local/` agent docs at the repo root.
+
+[Unreleased]: https://github.com/samline/forms/compare/v2.9.0...HEAD
+[2.9.0]: https://github.com/samline/forms/compare/v2.8.0...v2.9.0
+[2.8.0]: https://github.com/samline/forms/compare/v2.7.2...v2.8.0
+[2.7.2]: https://github.com/samline/forms/compare/v2.7.1...v2.7.2
+[2.7.1]: https://github.com/samline/forms/compare/v2.7.0...v2.7.1
+[2.7.0]: https://github.com/samline/forms/compare/v2.6.0...v2.7.0
+[2.6.0]: https://github.com/samline/forms/compare/v2.5.1...v2.6.0
+[2.5.1]: https://github.com/samline/forms/compare/v2.5.0...v2.5.1
+[2.5.0]: https://github.com/samline/forms/compare/v2.4.0...v2.5.0
+[2.4.0]: https://github.com/samline/forms/compare/v2.3.4...v2.4.0
+[2.3.4]: https://github.com/samline/forms/compare/v2.3.3...v2.3.4
+[2.3.3]: https://github.com/samline/forms/compare/v2.3.2...v2.3.3
+[2.3.2]: https://github.com/samline/forms/compare/v2.3.1...v2.3.2
+[2.3.1]: https://github.com/samline/forms/compare/v2.3.0...v2.3.1
+[2.3.0]: https://github.com/samline/forms/compare/v2.2.3...v2.3.0
+[2.2.3]: https://github.com/samline/forms/compare/v2.2.2...v2.2.3
+[2.2.2]: https://github.com/samline/forms/compare/v2.2.1...v2.2.2
+[2.2.1]: https://github.com/samline/forms/compare/v2.2.0...v2.2.1
+[2.2.0]: https://github.com/samline/forms/compare/v1.0.3...v2.2.0
+[1.0.3]: https://github.com/samline/forms/compare/v1.0.2...v1.0.3
+[1.0.2]: https://github.com/samline/forms/compare/v1.0.1...v1.0.2
+[1.0.1]: https://github.com/samline/forms/compare/v1.0.0...v1.0.1
+[1.0.0]: https://github.com/samline/forms/compare/v0.1.0...v1.0.0
+[0.1.0]: https://github.com/samline/forms/releases/tag/v0.1.0

package/README.md

@@ -1,183 +1,183 @@
-# Forms
+# @samline/forms
 
-> A TypeScript-first, framework-free controller for native HTML forms.
+Validation, reactive state, serialization and auto-submit for native HTML forms, with a typed, framework-free API for JavaScript and TypeScript.
 
-> Add validation, reactive field state, accessible error handling, serialization, auto-submit, and optional input formatting without adopting a UI framework.
+[Demo](https://samline.github.io/forms/) · [Examples](https://samline.github.io/forms/examples/) · [Documentation](https://samline.github.io/forms/docs/) · [Changelog](CHANGELOG.md)
 
----
-
-## Table of Contents
+## Table of contents
 
 - [Installation](#installation)
-- [CDN / Browser](#cdn--browser)
-- [Entrypoints](#entrypoints)
-- [Quick Start](#quick-start)
-- [What You Can Build](#what-you-can-build)
-- [API at a Glance](#api-at-a-glance)
+- [Quick start](#quick-start)
+- [HTML / CDN](#html--cdn)
+- [Capabilities](#capabilities)
+- [API at a glance](#api-at-a-glance)
 - [Documentation](#documentation)
+- [Changelog](#changelog)
+- [AI agent skill](#ai-agent-skill)
 - [License](#license)
 
----
-
 ## Installation
 
-```bash
+```sh
 npm install @samline/forms
 ```
 
-```bash
+```sh
 pnpm add @samline/forms
 ```
 
-```bash
+```sh
 bun add @samline/forms
 ```
 
-Requires Node 20+ when bundling. Runtime target is ES2020.
-
----
+Requires Node 20+ when bundling; the runtime targets ES2020 browsers. Formatting needs the optional peer `@samline/formatter` (`npm install @samline/formatter`); validation, state and serialization do not. No runtime stylesheet is required; the application owns form styling.
 
-## CDN / Browser
+## Quick start
 
-Use the browser build when you do not have a bundler and need to run the package directly in HTML, Shopify, WordPress, or any traditional template.
+Keep a native form with named fields. `novalidate` lets the controller's rules replace the browser's bubbles.
 
 ```html
-<script src="https://unpkg.com/@samline/forms@2.7.2/dist/browser/global.global.js"></script>
+<form id="signup" novalidate>
+  <label for="email">Email</label>
+  <input id="email" name="email" type="email" autocomplete="email" aria-describedby="email-error" />
+  <p id="email-error" data-error-for="email" aria-live="polite"></p>
+  <button type="submit">Sign up</button>
+</form>
 ```
 
-> Pin the version in production. Replace `2.7.2` with the version you ship.
-
-The browser bundle exposes a single global: `window.Forms`.
+```js
+import { form } from '@samline/forms'
 
-```html
-<form id="contact-form">
-  <input name="email" type="email" />
-  <button type="submit">Send</button>
-</form>
+const signup = form('signup', {
+  autoValidate: false,
+  validators: {
+    email: {
+      required: { value: true, message: 'Enter your email.' },
+      pattern: { value: /^[^\s@]+@[^\s@]+\.[^\s@]+$/, message: 'Use a valid email.' },
+    },
+  },
+})
 
-<script src="https://unpkg.com/@samline/forms@2.7.2/dist/browser/global.global.js"></script>
-<script>
-  const contactForm = window.Forms.newForm({ id: 'contact-form' })
+signup.subscribe(state => {
+  document.querySelector('#email-error').textContent = state.errors.email?.[0] ?? ''
+})
 
-  contactForm.onSubmit(async (form, data, formData) => {
-    await fetch('/api/contact', { method: 'POST', body: formData })
-  })
+signup.onSubmit(async (_element, _data, formData) => {
+  await fetch('/api/signup', { method: 'POST', body: formData })
+  signup.reset()
+})
 
-  contactForm.validate()
-</script>
+// When the form goes away (route change, component unmount):
+// signup.destroy()
 ```
 
-The browser surface keeps a small registry under `Forms.available`, keyed by the `id` you pass to `Forms.newForm`. Each successful `newForm` call stores the returned controller there, and `Forms.destroyForm(id)` calls `destroy()` and removes the entry. Use `Forms.form` directly when you need the factory without the registry side-effect.
-
-See [docs/browser.md](docs/browser.md) for the full browser surface.
+Invalid submits are always prevented and focus moves to the first invalid field. Valid submits reach every `onSubmit()` handler with a plain object, a fresh `FormData` and a state snapshot.
 
----
+## HTML / CDN
 
-## Entrypoints
+The standalone build defines `window.Forms` and already includes `@samline/formatter`. Pin the version.
 
-| Entrypoint | When to use |
-| --- | --- |
-| `@samline/forms` | Main vanilla API for bundlers, ESM, or CJS consumers. |
-| `@samline/forms/browser` | ESM/CJS browser module with registry exports, bundled types, and `window.Forms` registration. |
-| `@samline/forms/browser/global` | Pre-bundled IIFE for direct `<script>` usage; the CDN URL resolves to `dist/browser/global.global.js`. |
+```html
+<script src="https://unpkg.com/@samline/forms@2.9.0/dist/browser/global.global.js"></script>
+<script>
+  const signup = window.Forms.form('signup', {
+    validators: { email: { required: true, pattern: /^[^\s@]+@[^\s@]+\.[^\s@]+$/ } },
+  })
+</script>
+```
 
-The vanilla entrypoint also exports `browser`, the same `{ form, newForm, destroyForm, available }` surface as the IIFE but as a module-level singleton (no `globalThis` side-effect). Use it from a bundler when you want the registry helpers without the IIFE — see [docs/browser.md → Using the same shape from a bundler](docs/browser.md#using-the-same-shape-from-a-bundler).
+`window.Forms` has `form`, `newForm({ id, options })`, `destroyForm(id)` and the `available` registry. See [Browser global and CDN](https://samline.github.io/forms/docs/reference/browser/).
 
----
+## Capabilities
 
-## Quick Start
+- **Validation rules:** `required`, `minLength`, `maxLength`, `pattern`, `numeric`, `min`, `max`, `sameAs`, `dependsOn`, per-row `each` and custom validators that read every value.
+- **Accessible state:** invalid controls get `aria-invalid` and `css-error`, filled ones `css-filled`; a failed submit focuses the first invalid control in document order.
+- **Reactive state:** `subscribe()` for the whole form, `observe()`/`watch()` for one field.
+- **Submission:** promise-aware `onSubmit()`, `autoSubmit()` with debounce, `setErrors()` for server responses, `prefill()` from the URL and `reset()`.
+- **Native controls:** checkbox groups, radios, multiple selects, files, repeated `name[]` inputs and controls linked with `form="id"`, including fields added later.
+- **Formatting:** `format()`, `formatAll()` and the `formats` option format phones, cards, dates, times and amounts while a hidden field submits the raw value.
+- **DOM-free helpers:** `validateValues()` and `validateFieldValue()` run the same rules on the server; `parseFormData()` serializes any form.
 
-```ts
-import { form } from '@samline/forms'
+### Lifecycle
 
-const contactForm = form('contact-form', {
-  validators: {
-    email: {
-      required: true,
-      pattern: /^[^\s@]+@[^\s@]+\.[^\s@]+$/
-    }
-  }
-})
+One controller owns one form's listeners, `MutationObserver` and auto-submit timer. Create it once the form exists and call `destroy()` when it goes away. `addCleanup()` ties your own teardown to the same lifetime. After `destroy()`, writes and new registrations are no-ops.
 
-contactForm.watch('email', value => {
-  console.log('email is now:', value)
-})
-
-contactForm.onSubmit(async (_element, _data, formData) => {
-  await fetch('/api/contact', { method: 'POST', body: formData })
-})
-```
+## API at a glance
 
-What this does:
+| API                                               | Purpose                                                            |
+| ------------------------------------------------- | ------------------------------------------------------------------ |
+| `form(target, options?)`                          | Create a controller for an id, `HTMLFormElement` or `{ current }`. |
+| `createFormController(target, options?)`          | The same factory under its descriptive name.                       |
+| `browser`                                         | `{ form, newForm, destroyForm, available }` registry singleton.    |
+| `parseFormData(form, submitter?)`                 | Serialize a form into `{ data, formData }`.                        |
+| `validateValues(values, schema)`                  | Validate a plain values object against a `ValidationSchema`.       |
+| `validateFieldValue(field, value, rules, values)` | Validate one value.                                                |
+| `@samline/forms/browser`                          | The registry as a module namespace; also sets `globalThis.Forms`.  |
+| `@samline/forms/browser/global`                   | The standalone IIFE that defines `window.Forms`.                   |
 
-- Binds to the form with id `contact-form`.
-- Adds `css-filled` / `css-error` attributes on fields so you can style them with CSS.
-- Validates `email` on every change and on submit.
-- Intercepts valid submits (the default for `onSubmit`) and hands a real `FormData` instance to your handler.
+### Entrypoints
 
----
+| Entrypoint                      | When to use                                                                              |
+| ------------------------------- | ---------------------------------------------------------------------------------------- |
+| `@samline/forms`                | Controller factory, pure validation/serialization helpers and types for ESM or CommonJS. |
+| `@samline/forms/browser`        | Module registry that also installs `globalThis.Forms`.                                   |
+| `@samline/forms/browser/global` | Standalone script with `window.Forms` and the bundled formatter.                         |
 
-## What You Can Build
+### Controller methods
 
-- Contact, newsletter, login, signup, checkout, and profile forms.
-- Forms that submit with `fetch` while keeping native `FormData` payloads.
-- Autosave / autosubmit flows with optional debounce.
-- Visual feedback driven by `css-filled` and `css-error` attributes.
-- Progressive enhancement on top of any existing HTML form.
-- Forms rendered server-side (Blade, Twig, ERB) that still want client-side validation.
+| Group      | Methods                                                                         |
+| ---------- | ------------------------------------------------------------------------------- |
+| Submission | `onSubmit`, `autoSubmit`, `disableAutoSubmit`                                   |
+| Validation | `validate`, `revalidate`, `setErrors`, `clearErrors`                            |
+| State      | `subscribe`, `observe`, `watch`, `unwatch`, `getState`                          |
+| Values     | `setValue`, `setOptions`, `getValue`, `getField`, `getData`, `prefill`, `reset` |
+| Formatting | `format`, `formatAll`                                                           |
+| Lifecycle  | `element`, `f`, `options`, `append`, `addCleanup`, `destroy`                    |
 
----
+### Options
 
-## API at a Glance
+`validators`, `autoValidate` (default `true`), `autoSubmit`, `clearErrorsOnSubmit` (default `true`), `clearManualErrorsOnChange` (default `true`), `attributes` (default `{ filled: 'css-filled', error: 'css-error' }`) and `formats`. Every option is described in [Configuration options](https://samline.github.io/forms/docs/reference/configuration/); every type is exported, see the [TypeScript reference](https://samline.github.io/forms/docs/reference/typescript/).
 
-The controller is built around one factory and a small set of focused methods. Most methods are chainable.
+## Documentation
 
-| Group | Methods |
-| --- | --- |
-| Lifecycle | [`form`](docs/api/form.md) · [`addCleanup`](docs/api/add-cleanup.md) · [`destroy`](docs/api/destroy.md) · [`reset`](docs/api/reset.md) |
-| Registry (vanilla) | [`browser`](docs/getting-started.md#browser-registry-helpers) — bundler-friendly `{ form, newForm, destroyForm, available }` singleton. |
-| Properties | [`element`](docs/api/element.md) · [`options`](docs/options.md) |
-| Submission | [`onSubmit`](docs/api/on-submit.md) · [`autoSubmit`](docs/api/auto-submit.md) · [`disableAutoSubmit`](docs/api/disable-auto-submit.md) |
-| Field observation | [`watch`](docs/api/watch.md) · [`observe`](docs/api/observe.md) · [`unwatch`](docs/api/unwatch.md) · [`subscribe`](docs/api/subscribe.md) |
-| Field values | [`setValue`](docs/api/set-value.md) · [`getValue`](docs/api/get-value.md) · [`getField`](docs/api/get-field.md) · [`prefill`](docs/api/prefill.md) · [`format`](docs/api/format.md) · [`formatAll`](docs/api/format.md) |
-| Validation | [`validate`](docs/api/validate.md) · [`revalidate`](docs/api/revalidate.md) · [`setErrors`](docs/api/set-errors.md) · [`clearErrors`](docs/api/clear-errors.md) |
-| State and data | [`getData`](docs/api/get-data.md) · [`getState`](docs/api/get-state.md) · [`append`](docs/api/append.md) |
-| Pure helpers | [`parseFormData`](docs/api/parse-form-data.md) · [`validateValues`](docs/api/validate-values.md) · [`validateFieldValue`](docs/api/validate-field-value.md) |
+Read the [documentation](https://samline.github.io/forms/docs/) for the full guides and API contracts, and explore [working examples](https://samline.github.io/forms/examples/) with complete and separate source files for both loading modes.
 
-Validation supports explicit cross-field dependencies with `dependsOn`, per-member collection rules with `each`, and strict decimal `numeric` / inclusive `min` / `max` rules. Async `onSubmit` handlers are reflected by `getState().isSubmitting`, while `addCleanup()` lets integrations register controller-owned teardown work.
+| Guide                                                                                     | What it covers                                              |
+| ----------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
+| [Get started](https://samline.github.io/forms/docs/getting-started/)                      | Installation, the first form, CDN use and cleanup.          |
+| [Examples](https://samline.github.io/forms/docs/guides/examples/)                         | Twelve live forms with their code.                          |
+| [Validation and errors](https://samline.github.io/forms/docs/guides/validation/)          | Every rule, cross-field checks and accessible messages.     |
+| [State and submission](https://samline.github.io/forms/docs/guides/state-and-submission/) | Subscribers, async submits, auto-submit, prefill and reset. |
+| [Formatting fields](https://samline.github.io/forms/docs/guides/formatting/)              | The optional formatter and the hidden raw mirror.           |
+| [Framework integrations](https://samline.github.io/forms/docs/guides/frameworks/)         | React, Vue, Svelte, Astro, Shopify and WordPress.           |
+| [API reference](https://samline.github.io/forms/docs/reference/api/)                      | Every method, grouped by task, with one page per method.    |
 
-See the full per-method reference in [`docs/api/`](docs/api/index.md).
+## Changelog
 
----
+Read [CHANGELOG.md](CHANGELOG.md) or the [published changelog](https://samline.github.io/forms/docs/changelog/) for release history and explicitly marked breaking and behavior changes. Review the notes before upgrading.
 
-## Optional peer: `@samline/formatter`
+### Upgrading to 2.8
 
-[`format`](docs/api/format.md) and [`formatAll`](docs/api/format.md) rely on the optional peer dependency [`@samline/formatter`](https://github.com/samline/formatter). Install it when you need input masks (phone, credit-card, date, time, numeral, general):
+2.8.0 removes no API. Review these behavior fixes before upgrading: `prefill()` writes repeated query keys as arrays and auto-submits once; native reset buttons now clear errors and attributes; `reset()` calls watchers; failed submits focus the first invalid control in document order and automatic submits never move focus; methods called after `destroy()` no longer change the form; rejected async submit handlers are logged. The Markdown `docs/` folder is no longer published to npm; the documentation lives on the website. The optional `@samline/formatter` peer now requires `^2.1.0`, which the standalone script bundles. Read the [2.8.0 notes](CHANGELOG.md).
 
-```bash
-npm install @samline/formatter
-```
+## AI agent skill
 
-If the peer is not installed, the methods log a single `console.error` explaining how to install it and return the controller unchanged — the rest of the form keeps working. See [docs/recipes.md → 13. Format inputs with `@samline/formatter`](docs/recipes.md#13-format-inputs-with-samlineformatter) for end-to-end examples.
+<a id="agent-integration"></a>
 
----
+The [Forms skill](https://samline.github.io/forms/skills/forms/SKILL.md) describes 2.8 integration: loading modes, validation rules and accessible messages, state and submission, formatting and host ownership. Pass it to an agent or install it using a skills-compatible tool. Verify the installed package version before applying its guidance.
 
-## Documentation
+The maintained [repository source](skills/forms/SKILL.md) and website download are the same file.
 
-Full API reference, guides, and examples are available at **[samline.github.io/forms](https://samline.github.io/forms)**.
+Download [SKILL.md](https://samline.github.io/forms/skills/forms/SKILL.md) into a `forms/` folder in your agent's supported skill directory. For agents that discover project skills from `.agents/skills/`:
 
-| Doc | Purpose |
-| --- | --- |
-| [docs/getting-started.md](docs/getting-started.md) | Concepts, observable contract, lifecycle, and side-effect overview. |
-| [docs/options.md](docs/options.md) | Full `FormControllerOptions` reference. |
-| [docs/css-styling.md](docs/css-styling.md) | `css-filled` and `css-error` styling recipes. |
-| [docs/typescript.md](docs/typescript.md) | Every exported TypeScript type, with examples. |
-| [docs/api/index.md](docs/api/index.md) | One page per public method. |
-| [docs/recipes.md](docs/recipes.md) | End-to-end patterns: fetch submit, server errors, autosave, multi-step, etc. |
-| [docs/browser.md](docs/browser.md) | Browser global (`window.Forms`) usage. |
+```sh
+mkdir -p .agents/skills/forms
+curl --fail --location https://samline.github.io/forms/skills/forms/SKILL.md \
+  --output .agents/skills/forms/SKILL.md
+```
 
----
+When working from this repository, copy `skills/forms/SKILL.md` instead. Keep the filename `SKILL.md`; discovery paths and invocation syntax depend on the agent.
 
 ## License
 
-MIT
+MIT — [LICENSE.md](LICENSE.md).