@samline/forms 2.8.0 → 2.10.0

package/CHANGELOG.md

@@ -4,6 +4,32 @@ All notable changes to `@samline/forms` are documented in this file. The format
 
 ## [Unreleased]
 
+## [2.10.0] - 2026-11-12
+
+No breaking API changes.
+
+### Added
+
+- Support for `@samline/formatter` 3.0.0. The optional peer now accepts `^2.1.0 || ^3.0.0`. Formatter 3 makes phones opt-in, so forms loads `@samline/formatter/phone` and calls `registerPhone()` the first time a field is formatted with `type: 'phone'`. Forms without phone fields never load libphonenumber-js, and bundlers put the phone subpath in its own lazy chunk. If the subpath cannot be loaded, forms logs one `console.error` and leaves the field unformatted.
+- The standalone script bundles formatter 3.0.0, with phone support included.
+
+### Fixed
+
+- A submit the user starts while a debounced auto-submit is pending cancels the pending one. Before, the form was submitted twice.
+
+## [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.
@@ -277,7 +303,9 @@ No breaking API changes. The behavior changes below fix incorrect or surprising
 
 - 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.8.0...HEAD
+[Unreleased]: https://github.com/samline/forms/compare/v2.10.0...HEAD
+[2.10.0]: https://github.com/samline/forms/compare/v2.9.0...v2.10.0
+[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

package/README.md

@@ -30,7 +30,7 @@ pnpm add @samline/forms
 bun add @samline/forms
 ```
 
-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.
+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.
 
 ## Quick start
 
@@ -78,7 +78,7 @@ Invalid submits are always prevented and focus moves to the first invalid field.
 The standalone build defines `window.Forms` and already includes `@samline/formatter`. Pin the version.
 
 ```html
-<script src="https://unpkg.com/@samline/forms@2.8.0/dist/browser/global.global.js"></script>
+<script src="https://unpkg.com/@samline/forms@2.10.0/dist/browser/global.global.js"></script>
 <script>
   const signup = window.Forms.form('signup', {
     validators: { email: { required: true, pattern: /^[^\s@]+@[^\s@]+\.[^\s@]+$/ } },
@@ -104,27 +104,35 @@ One controller owns one form's listeners, `MutationObserver` and auto-submit tim
 
 ## API at a glance
 
-| Export                                     | 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`.                    |
+| 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`.                   |
+
+### 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.                         |
 
 ### Controller methods
 
-| Group         | Methods                                                                            |
-| ------------- | ---------------------------------------------------------------------------------- |
-| Submission    | `onSubmit`, `autoSubmit`, `disableAutoSubmit`                                      |
-| Validation    | `validate`, `revalidate`, `setErrors`, `clearErrors`                               |
-| State         | `subscribe`, `observe`, `watch`, `unwatch`, `getState`                             |
-| Values        | `setValue`, `getValue`, `getField`, `getData`, `prefill`, `reset`                  |
-| Formatting    | `format`, `formatAll`                                                              |
-| Lifecycle     | `element`, `f`, `options`, `append`, `addCleanup`, `destroy`                       |
+| 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
 
@@ -132,19 +140,21 @@ One controller owns one form's listeners, `MutationObserver` and auto-submit tim
 
 ## Documentation
 
-| 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.             |
+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.
+
+| 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.    |
 
 ## Changelog
 
-Read [CHANGELOG.md](CHANGELOG.md) or the [published changelog](https://samline.github.io/forms/docs/changelog/) for release history and explicitly marked behavior changes.
+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.
 
 ### Upgrading to 2.8
 
@@ -156,6 +166,8 @@ Read [CHANGELOG.md](CHANGELOG.md) or the [published changelog](https://samline.g
 
 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.
 
+The maintained [repository source](skills/forms/SKILL.md) and website download are the same file.
+
 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/`:
 
 ```sh
@@ -168,4 +180,4 @@ When working from this repository, copy `skills/forms/SKILL.md` instead. Keep th
 
 ## License
 
-MIT — [LICENSE.md](LICENSE.md)
+MIT — [LICENSE.md](LICENSE.md).

package/dist/browser/global.d.ts

@@ -106,7 +106,38 @@ interface AppendContentOptions {
     class?: string;
     atStart?: boolean;
 }
+/** One `<option>` written by `setOptions()`. */
+interface SelectOption {
+    value: string | number;
+    /** Visible text. Defaults to `String(value)`. Written as text, never HTML. */
+    label?: string;
+    disabled?: boolean;
+    /** Selects the option and makes it the default restored by `reset()`. */
+    selected?: boolean;
+}
+/** One `<optgroup>` written by `setOptions()`. */
+interface SelectOptionGroup {
+    label: string;
+    options: Array<string | number | SelectOption>;
+    disabled?: boolean;
+}
+/** A plain string or number is shorthand for `{ value, label: String(value) }`. */
+type SelectOptionInput = string | number | SelectOption | SelectOptionGroup;
+interface SetOptionsConfig {
+    /**
+     * Keep the current selection when its value is still in the new list.
+     * Ignored for a select when any new option has `selected: true`.
+     * Defaults to `true`.
+     */
+    keepValue?: boolean;
+}
 type FormFieldWatcher = (value: FormFieldValue, field: FormFieldElement | FormFieldElement[] | null, form: HTMLFormElement, state: FormStateSnapshot) => void;
+/**
+ * Callback for `watch()` / `observe()` with a list of fields. `values` has
+ * one entry per watched field. `changed` is the field that triggered the
+ * call, or `null` on registration and after `reset()`.
+ */
+type FormFieldsWatcher = (values: FormValues, changed: string | null, form: HTMLFormElement, state: FormStateSnapshot) => void;
 type FormSubmitHandler = (form: HTMLFormElement, data: Record<string, SerializedFormValue>, formData: FormData, state: FormStateSnapshot) => void | Promise<void>;
 type FormCleanup = () => void;
 interface FormController {
@@ -115,15 +146,30 @@ interface FormController {
     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;
+    watch: {
+        (field: string, callback: FormFieldWatcher): FormController;
+        (fields: string[], callback: FormFieldsWatcher): FormController;
+    };
+    observe: {
+        (field: string, callback: FormFieldWatcher): () => void;
+        (fields: string[], callback: FormFieldsWatcher): () => void;
+    };
+    unwatch: {
+        (field?: string, callback?: FormFieldWatcher): FormController;
+        (fields: string[], callback?: FormFieldsWatcher): 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;
+    /**
+     * Replace the `<option>` / `<optgroup>` children of every `<select>`
+     * named `name`. Fires the normal change pipeline only when the
+     * selected value changes. Chainable.
+     */
+    setOptions: (name: string, options: SelectOptionInput[], config?: SetOptionsConfig) => FormController;
     validate: (fields?: string[]) => ValidationResult;
     revalidate: (fields?: string[]) => ValidationResult;
     /**