- Docs
- Changelog
Changelog
Every @samline/forms release, from 0.1.0 to today, with fixes, behavior changes and upgrade notes for each version.
All notable changes to @samline/forms are documented in this file. The format follows Keep a Changelog and the project adheres to Semantic Versioning.
3.0.0 - 2026-11-15
Breaking changes
@samline/forms/browserno longer has adefaultexport. Use the named exports (form,newForm,destroyForm,available) orimport * as Forms from '@samline/forms/browser'.window.Formsis unchanged.- The standalone script is now
dist/browser/forms.global.js, following the family naming, and@samline/forms/browser/globalpoints to it.dist/browser/global.global.jsis still shipped as an identical alias, so existing CDN URLs keep working.
Changed
- The standalone script bundles
@samline/formatter3.3.0:slugformats takecharMap(Cyrillic, Greek and German presets or your own map) andpreserve, and casing keeps decomposed accents inside their word. - Installs with pnpm and runs every script with Bun, with the @samline family CI, Prettier settings and gzip budgets for each public entry.
- CDN examples use pinned jsDelivr URLs.
Tests
- Coverage thresholds raised to 90 % branches and 95 % statements, functions and lines.
- Playwright tests of the standalone script in Chromium, Firefox and WebKit.
2.11.1 - 2026-11-13
No API changes.
Changed
- The standalone script bundles
@samline/formatter3.2.0. The optional peer range stays^2.1.0 || ^3.0.0.
Documentation
- The regex presets page covers formatter 3.2.0: the Mexican, US and European entries, the builders that follow a
format()mask (regex.date(),regex.numeral()), and the check-digit validators (isValidCurp,isValidIban,isValidCard…) used invalidate. It explains which value a formatted field validates (the hidden raw value under the canonical name) and how to loadwindow.Formatter.regexandwindow.Formatter.checksnext to the standalone script. - The validation and formatting guides, the API reference and the agent skill link to it. Links to formatter’s retired
docs/options.mdnow point to its website.
Tests
- End-to-end tests run formatter 3.2.0 patterns and check-digit validators through the controller, including formatted IBAN, date and numeral fields.
2.11.0 - 2026-11-13
No breaking API changes.
Added
FormatTypeaccepts'text'and'slug', the format types added in@samline/formatter3.1.0.textapplies a casing mode (options.case:'upper','lower','title','sentence'or'capitalize');slugkeeps a trailing separator in the visible input while the user types and submits the trimmed slug in the hidden input. Both need formatter 3.1.0 or newer; the optional peer range stays^2.1.0 || ^3.0.0.- The standalone script bundles formatter 3.1.0.
2.10.0 - 2026-11-12
No breaking API changes.
Added
- Support for
@samline/formatter3.0.0. The optional peer now accepts^2.1.0 || ^3.0.0. Formatter 3 makes phones opt-in, so forms loads@samline/formatter/phoneand callsregisterPhone()the first time a field is formatted withtype: '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 oneconsole.errorand 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: trueby default), and the change pipeline runs once, only when the selected value changes (#13). New exported types:SelectOption,SelectOptionGroup,SelectOptionInputandSetOptionsConfig.watch()andobserve()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 (nullon registration and afterreset()). It fires once per change of any listed field.unwatch(fields, callback?)removes these watchers. New exported type:FormFieldsWatcher(#10).
Fixed
- Adding or removing
<option>elements outside the controller is no longer ignored. When it changes a select’s value, the controller revalidates, updatescss-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 directform.reset()now clears errors,css-filled,css-errorandaria-invalidand restores formatted mirrors, likereset(). A canceledresetevent is respected. - The form’s
MutationObserverignores 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.Formsfrom the standalone script has exactlyform,newForm,destroyFormandavailable; it no longer includes adefaultkey.
Changed
reset()and native resets callwatch()/observe()callbacks with the restored values.- A rejected promise returned by an
onSubmit()handler is reported withconsole.error('[forms] submit handler failed', reason)instead of being swallowed.isSubmittingstill settles. - The standalone
dist/browser/global.global.jsis 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/formatterpeer and development dependency to^2.1.0(released 2026-11-06). The standalone script now bundles it, including its fixes forregex.numeral,regex.password, case-insensitive phone countries and decoratedgeneralmasks. - Documentation moved to the website at https://samline.github.io/forms/docs/. The npm tarball now ships
dist,README.md,LICENSE.mdandCHANGELOG.md; the Markdowndocs/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/formatterpeer 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
dependsOnmetadata for reactive custom cross-field validation with transitive, cycle-safe dependency traversal. - Added per-member
eachvalidation with element-specificcss-errorandaria-invalidstate for repeated controls while preserving the publicFormErrorsstring-array shape. - Added strict decimal
numeric, inclusivemin, and inclusivemaxvalidation 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-filledstate independently fromautoValidate, without activating validation. - Resolved per-input visual validation state for repeated
name="foo[]"controls (#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
sameAsvalidation rule for password confirmations and other fields that must contain equal non-empty values, with custom messages throughRuleConfig<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
sameAsrecipes, 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, andForms.availableare exposed directly instead of underForms.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-invalidsynchronization 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, exportedFormDataPrimitiveandFormFieldWatcher, and made multi-field formatter configuration reject a shareddisplayFieldwithout mutating the form. - Updated root and documentation-site dependencies to audited versions and synchronized both documentation surfaces.
2.4.0 - 2026-07-19
Fixed
applyFormatphase 2 and the capture-phase input handler now overrideinterpretInputAsto'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 withvalue="{{ old('birthday') }}"carrying"19901212"for ad/m/Ydisplay +Ymdraw combo) is correctly converted to the display form on mount. Without the override,@samline/formatterv1.2.0+ — which changedinterpretInputAsto 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 explicitinterpretInputAsinconfig.optionsis 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 / Bladeold()case (raw initial value → display form on mount), the live keystroke path (nointerpretInputAsoverride applied to user typing),setValue('field', raw)writes the canonical raw with the'auto'interpretation forced, the explicitinterpretInputAs: 'display'opt-in is preserved, and the re-bind path forwards the caller’s options verbatim.
Changed
docs/api/format.mdadds 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 theformat()summary so the npm-bundled docs and the live site stay in sync.example/src/content/docs/reference/typescript.mdnotes theinterpretInputAsoverride in theFieldFormatConfigprose so consumers reading the type signature know the initial pass is the special case.- The peer dependency
@samline/formatteris now^2.0.0(was^1.0.1). The^1.xrange 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
readFieldValueandwriteFieldValuenow respect thename="foo[]"convention for multi-value inputs. Previously,getValuereturned only the first matching input’s value andsetValuewrote the same string to every matching input, breaking custom validators that checkArray.isArray(value)on fields likedocusign_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.tscoveringgetValue/setValuewithname="foo[]"for text, email, checkbox, and file inputs (the last via a hand-builtFileList), plus guards thatname="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.mdanddocs/api/set-value.mddocument thename="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.mdmirrors 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
syncVisualStatewas routingcss-filledandcss-errorto 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 theMutationObserver-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 insidesyncVisualStateitself, so all five call sites are fixed at once and the visual attribute contract documented inapi/format.tsis 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.mdadds a callout after the:has()recipe explaining that the hidden mirror created byformat()lives outside any label and that the controller always targets the visible.docs/recipes.mdadds a one-liner to the mirror-convention section cross-referencing the styling page.
2.3.2 - 2026-07-16
Fixed
css-filledandcss-errorwere being written to the hidden raw mirror for fields wired throughformat(), so the:has([css-filled])selector on the project label parent never matched and the label text stayed invisible.handleDelegatedEventnow resolves the event target to the display name and callssyncVisualState([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-filledon the visible after a keystroke,css-filledon the visible whensetValuewrites 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 firstapplyFormatto resume fromawait 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 ofapplyFormatis now scoped to the entries the current call touched (via a localphase1Entriesarray) 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 whateverdisplayFieldresolves 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.rawFieldconfig renamed todisplayField.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.listenerstrackscapture?to matchaddEventListener(exactOptionalPropertyTypes: true).destroy()restores the visible’s name to the canonical form and detaches every capture-phase listener added byformat().
Notes
- No peer changes — options are still forwarded to
@samline/formatteras before, sodatePattern,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.
applyFormattedValueignoredInputEvent.inputTypeandcomputeCursorPositioncounted non-format characters to the left of the caret without ever pulling the cursor back past a re-inserted delimiter. After adeleteContentBackward/deleteWordBackwardthe 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. applyFormattedValuenow threadsInputEvent.inputTypefrombuildHandlerand applies cleave.js’postDelimiterBackspacescan in both branches of the function (early-return and fullcomputeCursorPosition), so the contract holds whether or not the formatter rewrites the visible value.
Added
- Four vitest cases under
test/api/format.test.tscovering thepostDelimiterBackspacecontract fordeleteContentBackwardadjacent to a delimiter, deletion of a delimiter itself,deleteWordBackwardin 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/formatterpeer was being silently left as a bare specifier in the IIFE bundle, soformat()/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.mdanddocs/browser.md).
2.2.0 - 2026-06-30
Added
browsersingleton 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 IIFEglobalThisside-effect.
Fixed
format()integration tests: raw mirror handling onsetValuewriting the display name (the visible’s.valuewas 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/formatterpeer dependency. The controller reads the peer at runtime via a dynamic import; a missing peer is non-fatal — a singleconsole.erroris logged andformat()becomes a no-op so the rest of the form keeps working.format()/formatAll()/formatoptions API:type,field(string orstring[]),optionsforwarded to the peer,displayFieldfor 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
Formsand a registry helper added:Forms.newForm({ id, options })stores the controller underForms.available[id],Forms.destroyForm(id)callsdestroy()and removes the entry. watch()andobserve()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 nextinput/changeevent of the affected field, unlessclearManualErrorsOnChange: falseis passed viaFormControllerOptions.
1.0.2 - 2026-03-24
Fixed
npm publishworkflow 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 publishworkflow: 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.