Toolmark

Appearance

toolmark-monorepo / @toolmark/core/dom / domFormAdapter

Function: domFormAdapter() ​

domFormAdapter(form, opts?): DomFormAdapter

Defined in: packages/core/src/dom/form-adapter.ts:74

Adapts an uncontrolled (or framework-controlled) DOM form to form tools (spec §8.1, §10.2).

  • Fields are the named controls of form.elements (form=-associated controls and form-associated custom elements included). Hidden (e.g. CSRF _token), password (also after a "show password" toggle), autocomplete cc-* / current-password / new-password / one-time-code, disabled and [data-tool-ignore] controls are never read, reported or written. Read-only fields (readonly or aria-readonly="true" on any of their controls) are read (getValues, fields()) as context but never written. Names map to dot paths (a[b] → a.b, a[0][b] → a.0.b; a[] or a repeated name → an array; fieldset[name] prefixes its descendants).
  • setValues writes through the prototypes' native setters (text, select, option.selected, files via DataTransfer) and dispatches bubbling input and change; checkboxes and radios whose state must change are click()ed, so React-controlled inputs update their state.
  • dirtyPaths = fields whose value differs from the load snapshot and is not the value the agent last set, plus fields touched by trusted (isTrusted) input/change events; a form reset (not cancelled) re-snapshots and clears both. This protects the user's edits from being overwritten; it is not a security boundary — synthetic events are ignored, but page scripts can still change values (reported through the snapshot diff) or trigger trusted events.
  • submit (default): form.checkValidity() fails → invalid with each invalid field's validationMessage at its path (an excluded or read-only control is reported at "" without its name); else form.requestSubmit() → ok({ submitted: true }).
  • onUserInteraction (tour hooks, spec §13) reports trusted (isTrusted) input and focusin events on a field ({ path, kind: 'input' | 'focus' }) and a trusted submit of the form ({ path: '', kind: 'submit' }). Events caused by the adapter's own setValues and submit are never reported, nor are events on excluded controls (password, cc-*, hidden, disabled, [data-tool-ignore]): those fields do not exist for tools. Only paths are reported, never values. Note that element.focus() from page script also yields a trusted focusin. The trusted submit caused by a DOM button tool's click() (an agent activation) is not reported either. While subscribed, the control → path map is cached and invalidated by a MutationObserver on the form's root.

Parameters ​

form ​

HTMLFormElement

The form element.

opts? ​

DomFormAdapterOptions

Optional submit override.

Returns ​

DomFormAdapter

The adapter; call dispose() when the form goes away.