xdbc 1.0.217 → 1.0.219

package/dist/DBC/ARRAY.js

@@ -0,0 +1,90 @@
+import { DBC } from "../DBC";
+/**
+ * A {@link DBC } defining that a value must be an array.
+ *
+ * @remarks
+ * Maintainer: Salvatore Callari (XDBC@WaXCode.net) */
+export class ARRAY extends DBC {
+    /**
+     * Checks if the value **toCheck** is an array.
+     *
+     * @param toCheck	The value to check.
+     *
+     * @returns TRUE if the value **toCheck** is an array, otherwise a string describing the infringement. */
+    static checkAlgorithm(toCheck) {
+        if (toCheck === undefined || toCheck === null)
+            return true;
+        if (!Array.isArray(toCheck)) {
+            return `Value has to be an ARRAY but is of type "${typeof toCheck}"`;
+        }
+        return true;
+    }
+    /**
+     * A parameter-decorator factory using the {@link ARRAY.checkAlgorithm } to determine whether this {@link DBC } is fulfilled
+     * by the tagged parameter.
+     *
+     * @param path	See {@link DBC.decPrecondition }.
+     * @param hint	See {@link DBC.decPrecondition }.
+     * @param dbc	See {@link DBC.decPrecondition }.
+     *
+     * @returns See {@link DBC.decPrecondition }. */
+    static PRE(path = undefined, hint = undefined, dbc = undefined) {
+        return DBC.createPRE(ARRAY.checkAlgorithm, [], dbc, path, hint);
+    }
+    /**
+     * A method-decorator factory using the {@link ARRAY.checkAlgorithm } to determine whether this {@link DBC } is fulfilled
+     * by the tagged method's returnvalue.
+     *
+     * @param path	See {@link DBC.decPostcondition }.
+     * @param hint	See {@link DBC.decPostcondition }.
+     * @param dbc	See {@link DBC.decPostcondition }.
+     *
+     * @returns See {@link DBC.decPostcondition }. */
+    static POST(path = undefined, hint = undefined, dbc = undefined) {
+        return DBC.createPOST(ARRAY.checkAlgorithm, [], dbc, path, hint);
+    }
+    /**
+     * A field-decorator factory using the {@link ARRAY.checkAlgorithm } to determine whether this {@link DBC } is fulfilled
+     * by the tagged field.
+     *
+     * @param path	See {@link DBC.decInvariant }.
+     * @param hint	See {@link DBC.decInvariant }.
+     * @param dbc	See {@link DBC.decInvariant }.
+     *
+     * @returns See {@link DBC.decInvariant }. */
+    static INVARIANT(path = undefined, hint = undefined, dbc = undefined) {
+        return DBC.createINVARIANT(ARRAY, [], dbc, path, hint);
+    }
+    // #endregion Condition checking.
+    // #region Referenced Condition checking.
+    //
+    // For usage in dynamic scenarios (like with AE-DBC).
+    //
+    /**
+     * Invokes the {@link ARRAY.checkAlgorithm } passing the value **toCheck**.
+     *
+     * @param toCheck See {@link ARRAY.checkAlgorithm }.
+     *
+     * @returns See {@link ARRAY.checkAlgorithm}. */
+    check(toCheck) {
+        return ARRAY.checkAlgorithm(toCheck);
+    }
+    /**
+     * Invokes the {@link ARRAY.checkAlgorithm } passing the value **toCheck**.
+     *
+     * @param toCheck	See {@link ARRAY.checkAlgorithm }.
+     * @param hint		An optional {@link string } providing extra information in case of an infringement.
+     * @param id		A {@link string } identifying this {@link ARRAY } via the {@link DBC.Infringement }-Message.
+     *
+     * @returns The **CANDIDATE** **toCheck** if this {@link ARRAY } is fulfilled.
+     *
+     * @throws A {@link DBC.Infringement } if the **CANDIDATE** **toCheck** does not fulfill this {@link ARRAY }. */
+    static tsCheck(toCheck, hint = undefined, id = undefined, dbc = undefined) {
+        const result = ARRAY.checkAlgorithm(toCheck);
+        if (result === true) {
+            return toCheck;
+        }
+        DBC.reportTsCheckInfringement(`${id ? `(${id}) ` : ""}${result}${hint ? ` ✨ ${hint} ✨` : ""}`, dbc);
+        return toCheck;
+    }
+}

package/dist/DBC/COMPARISON/GREATER.js

@@ -0,0 +1,21 @@
+import { COMPARISON } from "../COMPARISON";
+/** See {@link COMPARISON }. */
+export class GREATER extends COMPARISON {
+    /** See {@link COMPARISON.PRE }. */
+    static PRE(equivalent, equalityPermitted = false, invert = false, path = undefined, hint = undefined, dbc = undefined) {
+        return COMPARISON.PRE(equivalent, false, false, path, hint, dbc);
+    }
+    /** See {@link COMPARISON.POST }. */
+    static POST(equivalent, equalityPermitted = false, invert = false, path = undefined, hint = undefined, dbc = undefined) {
+        return COMPARISON.POST(equivalent, false, false, path, hint, dbc);
+    }
+    /** See {@link COMPARISON.INVARIANT }. */
+    static INVARIANT(equivalent, equalityPermitted = false, invert = false, path = undefined, hint = undefined, dbc = undefined) {
+        return COMPARISON.INVARIANT(equivalent, false, false, path, hint, dbc);
+    }
+    /** See {@link COMPARISON.constructor }. */
+    constructor(equivalent) {
+        super(equivalent, false, false);
+        this.equivalent = equivalent;
+    }
+}

package/dist/DBC/COMPARISON/GREATER_OR_EQUAL.js

@@ -0,0 +1,21 @@
+import { COMPARISON } from "../COMPARISON";
+/** See {@link COMPARISON }. */
+export class GREATER_OR_EQUAL extends COMPARISON {
+    /** See {@link COMPARISON.PRE }. */
+    static PRE(equivalent, equalityPermitted = false, invert = false, path = undefined, hint = undefined, dbc = undefined) {
+        return COMPARISON.PRE(equivalent, true, false, path, hint, dbc);
+    }
+    /** See {@link COMPARISON.POST }. */
+    static POST(equivalent, equalityPermitted = false, invert = false, path = undefined, hint = undefined, dbc = undefined) {
+        return COMPARISON.POST(equivalent, true, false, path, hint, dbc);
+    }
+    /** See {@link COMPARISON.INVARIANT }. */
+    static INVARIANT(equivalent, equalityPermitted = false, invert = false, path = undefined, hint = undefined, dbc = undefined) {
+        return COMPARISON.INVARIANT(equivalent, true, false, path, hint, dbc);
+    }
+    /** See {@link COMPARISON.constructor }. */
+    constructor(equivalent) {
+        super(equivalent, true, false);
+        this.equivalent = equivalent;
+    }
+}

package/dist/DBC/COMPARISON/LESS.js

@@ -0,0 +1,21 @@
+import { COMPARISON } from "../COMPARISON";
+/** See {@link COMPARISON }. */
+export class LESS extends COMPARISON {
+    /** See {@link COMPARISON.PRE }. */
+    static PRE(equivalent, equalityPermitted = false, invert = false, path = undefined, hint = undefined, dbc = undefined) {
+        return COMPARISON.PRE(equivalent, false, true, path, hint, dbc);
+    }
+    /** See {@link COMPARISON.POST }. */
+    static POST(equivalent, equalityPermitted = false, invert = false, path = undefined, hint = undefined, dbc = undefined) {
+        return COMPARISON.POST(equivalent, false, true, path, hint, dbc);
+    }
+    /** See {@link COMPARISON.INVARIANT }. */
+    static INVARIANT(equivalent, equalityPermitted = false, invert = false, path = undefined, hint = undefined, dbc = undefined) {
+        return COMPARISON.INVARIANT(equivalent, false, true, path, hint, dbc);
+    }
+    /** See {@link COMPARISON.constructor }. */
+    constructor(equivalent) {
+        super(equivalent, false, true);
+        this.equivalent = equivalent;
+    }
+}

package/dist/DBC/COMPARISON/LESS_OR_EQUAL.js

@@ -0,0 +1,21 @@
+import { COMPARISON } from "../COMPARISON";
+/** See {@link COMPARISON }. */
+export class LESS_OR_EQUAL extends COMPARISON {
+    /** See {@link COMPARISON.PRE }. */
+    static PRE(equivalent, equalityPermitted = false, invert = false, path = undefined, hint = undefined, dbc = undefined) {
+        return COMPARISON.PRE(equivalent, true, true, path, hint, dbc);
+    }
+    /** See {@link COMPARISON.POST }. */
+    static POST(equivalent, equalityPermitted = false, invert = false, path = undefined, hint = undefined, dbc = undefined) {
+        return COMPARISON.POST(equivalent, true, true, path, hint, dbc);
+    }
+    /** See {@link COMPARISON.INVARIANT }. */
+    static INVARIANT(equivalent, equalityPermitted = false, invert = false, path = undefined, hint = undefined, dbc = undefined) {
+        return COMPARISON.INVARIANT(equivalent, true, true, path, hint, dbc);
+    }
+    /** See {@link COMPARISON.constructor }. */
+    constructor(equivalent) {
+        super(equivalent, true, true);
+        this.equivalent = equivalent;
+    }
+}

package/dist/DBC/COMPARISON.js

@@ -0,0 +1,98 @@
+import { DBC } from "../DBC";
+/**
+ * A {@link DBC } defining a comparison between two {@link object }s.
+ *
+ * @remarks
+ * Maintainer: Callari, Salvatore (XDBC@WaXCode.net) */
+export class COMPARISON extends DBC {
+    // #region Condition checking.
+    /**
+     * Does a comparison between the {@link object } **toCheck** and the **equivalent**.
+     *
+     * @param toCheck		The value that has to be equal to it's possible **equivalent** for this {@link DBC } to be fulfilled.
+     * @param equivalent	The {@link object } the one **toCheck** has to be equal to in order for this {@link DBC } to be
+     * 						fulfilled.
+     *
+     * @returns TRUE if the value **toCheck** and the **equivalent** are equal to each other, otherwise FALSE. */
+    static checkAlgorithm(toCheck, equivalent, equalityPermitted, invert) {
+        if (equalityPermitted && !invert && toCheck < equivalent) {
+            return `Value has to be greater than or equal to "${equivalent}"`;
+        }
+        if (equalityPermitted && invert && toCheck > equivalent) {
+            return `Value has to be less than or equal to "${equivalent}"`;
+        }
+        if (!equalityPermitted && !invert && toCheck <= equivalent) {
+            return `Value has to be greater than "${equivalent}"`;
+        }
+        if (!equalityPermitted && invert && toCheck >= equivalent) {
+            return `Value has to be less than "${equivalent}"`;
+        }
+        return true;
+    }
+    /**
+     * A parameter-decorator factory using the {@link COMPARISON.checkAlgorithm } to determine whether this {@link DBC } is fulfilled
+     * by the tagged parameter.
+     *
+     * @param equivalent	    See {@link COMPARISON.checkAlgorithm }.
+     * @param equalityPermitted See {@link COMPARISON.checkAlgorithm }.
+     * @param path			    See {@link DBC.decPrecondition }.
+     * @param hint				See {@link DBC.decPrecondition }.
+     * @param dbc			    See {@link DBC.decPrecondition }.
+     *
+     * @returns See {@link DBC.decPrecondition }. */
+    static PRE(equivalent, equalityPermitted = false, invert = false, path = undefined, hint = undefined, dbc = undefined) {
+        return DBC.createPRE(COMPARISON.checkAlgorithm, [equivalent, equalityPermitted, invert], dbc, path, hint);
+    }
+    /**
+     * A method-decorator factory using the {@link COMPARISON.checkAlgorithm } to determine whether this {@link DBC } is fulfilled
+     * by the tagged method's returnvalue.
+     *
+     * @param equivalent	    See {@link COMPARISON.checkAlgorithm }.
+     * @param equalityPermitted See {@link COMPARISON.checkAlgorithm }.
+     * @param path			    See {@link DBC.Postcondition }.
+     * @param hint				See {@link DBC.decPostcondition }.
+     * @param dbc			    See {@link DBC.decPostcondition }.
+     *
+     * @returns See {@link DBC.decPostcondition }. */
+    static POST(equivalent, equalityPermitted = false, invert = false, path = undefined, hint = undefined, dbc = undefined) {
+        return DBC.createPOST(COMPARISON.checkAlgorithm, [equivalent, equalityPermitted, invert], dbc, path, hint);
+    }
+    /**
+     * A field-decorator factory using the {@link COMPARISON.checkAlgorithm } to determine whether this {@link DBC } is fulfilled
+     * by the tagged field.
+     *
+     * @param equivalent	    See {@link COMPARISON.checkAlgorithm }.
+     * @param equalityPermitted See {@link COMPARISON.checkAlgorithm }.
+     * @param path			    See {@link DBC.decInvariant }.
+     * @param hint				See {@link DBC.decInvariant }.
+     * @param dbc			    See {@link DBC.decInvariant }.
+     *
+     * @returns See {@link DBC.decInvariant }. */
+    static INVARIANT(equivalent, equalityPermitted = false, invert = false, path = undefined, hint = undefined, dbc = undefined) {
+        return DBC.createINVARIANT(COMPARISON, [equivalent, equalityPermitted, invert], dbc, path, hint);
+    }
+    // #endregion Condition checking.
+    // #region Referenced Condition checking.
+    // #region Dynamic usage.
+    /**
+     * Invokes the {@link COMPARISON.checkAlgorithm } passing the value **toCheck**, {@link COMPARISON.equivalent } and {@link COMPARISON.invert }.
+     *
+     * @param toCheck See {@link COMPARISON.checkAlgorithm }.
+     *
+     * @returns See {@link COMPARISON.checkAlgorithm}. */
+    check(toCheck) {
+        return COMPARISON.checkAlgorithm(toCheck, this.equivalent, this.equalityPermitted, this.invert);
+    }
+    /**
+     * Creates this {@link COMPARISON } by setting the protected property {@link COMPARISON.equivalent }, {@link COMPARISON.equalityPermitted } and {@link COMPARISON.invert } used by {@link COMPARISON.check }.
+     *
+     * @param equivalent        See {@link COMPARISON.check }.
+     * @param equalityPermitted See {@link COMPARISON.check }.
+     * @param invert            See {@link COMPARISON.check }. */
+    constructor(equivalent, equalityPermitted = false, invert = false) {
+        super();
+        this.equivalent = equivalent;
+        this.equalityPermitted = equalityPermitted;
+        this.invert = invert;
+    }
+}

package/dist/DBC/DEFINED.js

@@ -0,0 +1,87 @@
+import { DBC } from "../DBC";
+/**
+ * A {@link DBC } defining that an {@link object }s must be defined thus it's value may not be **null** or **undefined**.
+ *
+ * @remarks
+ * Maintainer: Salvatore Callari (XDBC@WaXCode.net) */
+export class DEFINED extends DBC {
+    /**
+     * Checks if the value **toCheck** is null or undefined.
+     *
+     * @param toCheck	The {@link Object } to check.
+     *
+     * @returns TRUE if the value **toCheck** is of the specified **type**, otherwise FALSE. */
+    static checkAlgorithm(toCheck) {
+        if (toCheck === undefined || toCheck === null) {
+            return `Value may not be UNDEFINED or NULL but it is ${toCheck === undefined ? "UNDEFINED" : "NULL"}`;
+        }
+        return true;
+    }
+    /**
+     * A parameter-decorator factory using the {@link DEFINED.checkAlgorithm } to determine whether this {@link DBC } is fulfilled
+     * by the tagged parameter.
+     *
+     * @param type	See {@link DEFINED.checkAlgorithm }.
+     * @param path	See {@link DBC.decPrecondition }.
+     * @param dbc	See {@link DBC.decPrecondition }.
+     *
+     * @returns See {@link DBC.decPrecondition }. */
+    static PRE(path = undefined, hint = undefined, dbc = undefined) {
+        return DBC.createPRE(DEFINED.checkAlgorithm, [], dbc, path, hint);
+    }
+    /**
+     * A method-decorator factory using the {@link DEFINED.checkAlgorithm } to determine whether this {@link DBC } is fulfilled
+     * by the tagged method's returnvalue.
+     *
+     * @param type	See {@link DEFINED.checkAlgorithm }.
+     * @param path	See {@link DBC.Postcondition }.
+     * @param dbc	See {@link DBC.decPostcondition }.
+     *
+     * @returns See {@link DBC.decPostcondition }. */
+    static POST(type, path = undefined, hint = undefined, dbc = undefined) {
+        return DBC.createPOST(DEFINED.checkAlgorithm, [], dbc, path, hint);
+    }
+    /**
+     * A field-decorator factory using the {@link DEFINED.checkAlgorithm } to determine whether this {@link DBC } is fulfilled
+     * by the tagged field.
+     *
+     * @param type	See {@link DEFINED.checkAlgorithm }.
+     * @param path	See {@link DBC.decInvariant }.
+     * @param dbc	See {@link DBC.decInvariant }.
+     *
+     * @returns See {@link DBC.decInvariant }. */
+    static INVARIANT(type, path = undefined, hint = undefined, dbc = undefined) {
+        return DBC.createINVARIANT(DEFINED, [], dbc, path, hint);
+    }
+    // #endregion Condition checking.
+    // #region Referenced Condition checking.
+    //
+    // For usage in dynamic scenarios (like with AE-DBC).
+    //
+    /**
+     * Invokes the {@link DEFINED.checkAlgorithm } passing the value **toCheck** and the {@link DEFINED.type } .
+     *
+     * @param toCheck See {@link DEFINED.checkAlgorithm }.
+     *
+     * @returns See {@link DEFINED.checkAlgorithm}. */
+    check(toCheck) {
+        return DEFINED.checkAlgorithm(toCheck);
+    }
+    /**
+     * Invokes the {@link DEFINED.checkAlgorithm } passing the value **toCheck** and the {@link DEFINED.type } .
+     *
+     * @param toCheck	See {@link DEFINED.checkAlgorithm }.
+     * @param id		A {@link string } identifying this {@link INSTANCE } via the {@link DBC.Infringement }-Message.
+     *
+     * @returns The **CANDIDATE** **toCheck** doesn't fulfill this {@link DEFINED }.
+     *
+     * @throws A {@link DBC.Infringement } if the **CANDIDATE** **toCheck** does not fulfill this {@link DEFINED }.*/
+    static tsCheck(toCheck, hint = undefined, id = undefined, dbc = undefined) {
+        const result = DEFINED.checkAlgorithm(toCheck);
+        if (result === true) {
+            return toCheck;
+        }
+        DBC.reportTsCheckInfringement(`${id ? `(${id}) ` : ""}${result}${hint ? ` ✨ ${hint} ✨` : ""}`, dbc);
+        return toCheck;
+    }
+}

package/dist/DBC/DOM.d.ts

@@ -0,0 +1,123 @@
+/** A check function that receives the current field value and the raw attribute string. */
+export type DOMContractCheck = (value: string, attrValue: string) => boolean | string;
+/**
+ * Registers a check function for a `data-xdbc-<key>` attribute.
+ * Call this before {@link scanDOM } to make a contract available declaratively.
+ *
+ * @param key       The attribute suffix (e.g. `"type"` → `data-xdbc-type`).
+ * @param checkFn   Receives the live field value and the raw attribute string.
+ *                  Return `true` when the value is valid, or a `string` message when it is not.
+ *
+ * @example
+ * ```ts
+ * import { registerDOMContract } from "xdbc/DBC/DOM";
+ * import { MY_CONTRACT } from "./MY_CONTRACT";
+ *
+ * registerDOMContract("my-contract", (value, attr) =>
+ *     MY_CONTRACT.checkAlgorithm(value, attr),
+ * );
+ * ```
+ */
+export declare function registerDOMContract(key: string, checkFn: DOMContractCheck): void;
+/**
+ * Scans the given **root** for `<input>` and `<textarea>` elements marked with the
+ * `data-xdbc` attribute, and binds XDBC contracts to their DOM events (blur by
+ * default; configurable per element via `data-xdbc-validate-on`).
+ *
+ * ### Supported attributes
+ *
+ * | Attribute                  | Example value              | Contract        |
+ * |----------------------------|----------------------------|-----------------|
+ * | `data-xdbc`                | *(path or empty)*          | marker / DBC path |
+ * | `data-xdbc-validate-on`         | `input` \| `blur`           | when to validate default contracts (default: `blur`) |
+ * | `data-xdbc-regex`               | `^[a-z]+\.[a-z]{2,}$`      | {@link REGEX} — validated per `data-xdbc-validate-on` |
+ * | `data-xdbc-regex-input`         | `^[a-zA-Z0-9.\-]*$`        | {@link REGEX} — always on every keystroke |
+ * | `data-xdbc-type`                | `string\|number`            | {@link TYPE}    |
+ * | `data-xdbc-type-input`          | `string\|number`            | {@link TYPE} — always on every keystroke |
+ * | `data-xdbc-eq`                  | `hello`                     | {@link EQ}      |
+ * | `data-xdbc-eq-input`            | `hello`                     | {@link EQ} — always on every keystroke |
+ * | `data-xdbc-different`           | `forbidden`                 | {@link EQ} (inverted) |
+ * | `data-xdbc-different-input`     | `forbidden`                 | {@link EQ} (inverted) — always on every keystroke |
+ * | `data-xdbc-defined`             | *(no value needed)*         | {@link DEFINED} |
+ * | `data-xdbc-defined-input`       | *(no value needed)*         | {@link DEFINED} — always on every keystroke |
+ * | `data-xdbc-undefined`           | *(no value needed)*         | {@link UNDEFINED} |
+ * | `data-xdbc-undefined-input`     | *(no value needed)*         | {@link UNDEFINED} — always on every keystroke |
+ * | `data-xdbc-greater`             | `5`                         | {@link COMPARISON} |
+ * | `data-xdbc-greater-input`       | `5`                         | {@link COMPARISON} — always on every keystroke |
+ * | `data-xdbc-greater-or-equal`    | `5`                         | {@link COMPARISON} |
+ * | `data-xdbc-greater-or-equal-input` | `5`                      | {@link COMPARISON} — always on every keystroke |
+ * | `data-xdbc-less`                | `100`                       | {@link COMPARISON} |
+ * | `data-xdbc-less-input`          | `100`                       | {@link COMPARISON} — always on every keystroke |
+ * | `data-xdbc-less-or-equal`       | `100`                       | {@link COMPARISON} |
+ * | `data-xdbc-less-or-equal-input` | `100`                       | {@link COMPARISON} — always on every keystroke |
+ * | `data-xdbc-or`                  | `regex:^\d+$;;type:string`  | {@link OR} (fragment syntax) |
+ * | `data-xdbc-or-input`            | `regex:^\d+$;;eq:N/A`       | {@link OR} — always on every keystroke |
+ *
+ * Use {@link registerDOMContract } to add further contracts at any time.
+ *
+ * ### OR fragment syntax
+ *
+ * Fragments are separated by `;;`. Each fragment is `<contract-key>:<value>`, where the
+ * split is on the **first** `:` only, so colons inside values (e.g. regex) are safe.
+ * The OR passes as long as **at least one** fragment passes.
+ *
+ * ```html
+ * <!-- digits OR exactly "N/A" -->
+ * <input data-xdbc data-xdbc-or="regex:^\d+$;;eq:N/A" />
+ * ```
+ *
+ * ### Behaviour on infringement
+ *
+ * 1. The element's value is **reverted** to the last accepted state (blocking the invalid input).
+ * 2. The configured DBC instance's infringement settings are honoured — `logToConsole`,
+ *    `onInfringement`, and `throwException` all fire in the usual order. Any throw is caught
+ *    internally so it cannot propagate out of the DOM event handler.
+ *
+ * ### IME / composition awareness
+ *
+ * Validation is suspended during IME composition (e.g. CJK input) and runs once after
+ * `compositionend`, so partially composed characters are never incorrectly rejected.
+ *
+ * @param root  Element or Document to scan (default: `document`).
+ * @returns     A cleanup function that removes all bound event listeners.
+ *
+ * ### Validate-on
+ *
+ * By default all contracts are validated when focus **leaves** the field (`blur`). This lets
+ * users type freely and only enforces the contract on completion. Set
+ * `data-xdbc-validate-on="input"` on an element to revert invalid input on every keystroke.
+ *
+ * ### Progressive + whole-value validation
+ *
+ * Use `data-xdbc-regex-input` alongside `data-xdbc-regex` to apply two different patterns:
+ * one that allows partial input during typing, and one that enforces the full format on blur.
+ * `data-xdbc-regex-input` always fires on every `input` event, regardless of
+ * `data-xdbc-validate-on`.
+ *
+ * ```html
+ * <!-- Only validate full domain format when leaving the field (default blur behaviour) -->
+ * <!-- While typing, only allow characters that could appear in a domain name -->
+ * <input type="text" data-xdbc
+ *        data-xdbc-regex="^[a-zA-Z0-9][a-zA-Z0-9.\-]*\.[a-zA-Z]{2,}$"
+ *        data-xdbc-regex-input="^[a-zA-Z0-9.\-]*$" />
+ *
+ * <!-- Block non-digit keystrokes in real time (explicit input-time validation) -->
+ * <input type="text" data-xdbc data-xdbc-validate-on="input" data-xdbc-regex="^\d*$" />
+ * ```
+ *
+ * @example
+ * ```html
+ * <input type="text" data-xdbc data-xdbc-regex="^[a-zA-Z0-9.\-]*\.[a-zA-Z]{2,}$" />
+ * <input type="text" data-xdbc="MyApp.DBC" data-xdbc-type="string" data-xdbc-greater="0" />
+ * <input type="text" data-xdbc data-xdbc-or="regex:^\d+$;;eq:N/A" />
+ * <textarea data-xdbc data-xdbc-regex="^[\w\s]*$"></textarea>
+ * ```
+ * ```ts
+ * import { scanDOM, registerDOMContract } from "xdbc/DBC/DOM";
+ *
+ * const cleanup = scanDOM();
+ * // later:
+ * cleanup();
+ * ```
+ */
+export declare function scanDOM(root?: Element | Document): () => void;