Toolmark

Appearance

toolmark-monorepo / @toolmark/core/dom / scanDom

Function: scanDom() ​

scanDom(opts?): (tm) => () => void

Defined in: packages/core/src/dom/scan.ts:225

Scans the DOM for declarative tools and keeps them registered (spec §10.2). Use it as a consumer: tm.use(scanDom()).

  • Trusted root: nothing under [data-tool-ignore], [contenteditable] (any value but "false"), <iframe> or <template> is scanned (nor anything at all when root itself is inside such a region). Tool and field descriptions come from the scanned markup, which must be app-authored (§14).
  • Forms: a form with native toolname + tooldescription registers <toolname>.fill / .submit (and .options) through domFormAdapter and the synthesized schema, with origin: 'native-form' and nativeName = toolname on .fill and .submit; toolautosubmit removes the submit's confirmation hint, otherwise it is consequential. A form with data-tool + data-tool-description registers the same with origin: 'dom' (data-tool-destructive makes its submit destructive; data-tool-confirm is its submit summary). data-tool-options-url on a field adds a same-origin options lookup (other URLs are ignored with an options_url_rejected event). Fill and submit results are marked untrustedContent.
  • Buttons (<button> / button <input> with data-tool and data-tool-description; without a description the button is skipped with an invalid_name event in development, never described from its text) → an action tool that clicks the button; a button that submits or resets its form is always at least consequential, uses the form's data-tool-confirm as its summary, and its approval is refused stale when the form's values changed after the confirmation was requested.
  • Tables with data-tool and th[data-tool-column] (at most 32 columns) → a read-only query tool whose rows are capped at 200 000 JSON characters (truncated: true).
  • data-tool-group on an ancestor puts the tools in a scope of that name. An invalid tool or group name is skipped with an invalid_name event (never thrown, also in development); registration errors are reported as error events too.
  • Observation (observe, default true): one MutationObserver watches root and every open shadow root found; only mutations touching forms, form controls, labels, tool elements or tool attributes outside ignored regions schedule a rescan; changes are batched per animation frame; a tool is re-registered only when its synthesized schema (load-time defaults aside) or tool attributes changed; removed elements' tools and form adapters are disposed.

Without document (SSR) it does nothing.

Parameters ​

opts? ​

ScanDomOptions = {}

root (default document) and observe (default true).

Returns ​

A consumer for tm.use; its disposer disconnects the observer and disposes every adapter, tool and group scope it created.

(tm) => () => void