xdbc 1.0.217 → 1.0.218

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,87 @@
+/** 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 `input` events (covering
+ * keyboard, paste, IME / mobile on-screen keyboard, voice input, and autofill).
+ *
+ * ### Supported attributes
+ *
+ * | Attribute                  | Example value              | Contract        |
+ * |----------------------------|----------------------------|-----------------|
+ * | `data-xdbc`                | *(path or empty)*          | marker / DBC path |
+ * | `data-xdbc-regex`          | `^\d*$`                    | {@link REGEX}   |
+ * | `data-xdbc-type`           | `string\|number`           | {@link TYPE}    |
+ * | `data-xdbc-eq`             | `hello`                    | {@link EQ}      |
+ * | `data-xdbc-different`      | `forbidden`                | {@link EQ} (inverted) |
+ * | `data-xdbc-defined`        | *(no value needed)*        | {@link DEFINED} |
+ * | `data-xdbc-undefined`      | *(no value needed)*        | {@link UNDEFINED} |
+ * | `data-xdbc-greater`        | `5`                        | {@link COMPARISON} |
+ * | `data-xdbc-greater-or-equal` | `5`                      | {@link COMPARISON} |
+ * | `data-xdbc-less`           | `100`                      | {@link COMPARISON} |
+ * | `data-xdbc-less-or-equal`  | `100`                      | {@link COMPARISON} |
+ * | `data-xdbc-or`             | `regex:^\d+$;;type:string` | {@link OR} (fragment syntax) |
+ *
+ * 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.
+ *
+ * @example
+ * ```html
+ * <input type="text" data-xdbc data-xdbc-regex="^\d*$" />
+ * <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;

package/dist/DBC/DOM.js

@@ -0,0 +1,223 @@
+import { DBC } from "../DBC";
+import { COMPARISON } from "./COMPARISON";
+import { DEFINED } from "./DEFINED";
+import { EQ } from "./EQ";
+import { REGEX } from "./REGEX";
+import { TYPE } from "./TYPE";
+import { UNDEFINED } from "./UNDEFINED";
+// ─── Contract registry ────────────────────────────────────────────────────────
+/**
+ * Maps a `data-xdbc-<key>` attribute suffix to a check function.
+ * Populated by {@link registerDOMContract } and the built-in defaults below.
+ */
+const registry = new Map();
+/**
+ * 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 function registerDOMContract(key, checkFn) {
+    registry.set(key, checkFn);
+}
+// ─── Built-in registrations ───────────────────────────────────────────────────
+// data-xdbc-regex="^\d*$"
+registerDOMContract("regex", (value, attr) => {
+    let rx;
+    try {
+        rx = new RegExp(attr);
+    }
+    catch (_a) {
+        return `[XDBC] Invalid RegExp pattern: "${attr}"`;
+    }
+    return REGEX.checkAlgorithm(value, rx);
+});
+// data-xdbc-type="string|number"
+registerDOMContract("type", (value, attr) => TYPE.checkAlgorithm(value, attr));
+// data-xdbc-eq="hello"
+registerDOMContract("eq", (value, attr) => EQ.checkAlgorithm(value, attr, false));
+// data-xdbc-different="forbidden"
+registerDOMContract("different", (value, attr) => EQ.checkAlgorithm(value, attr, true));
+// data-xdbc-defined  (attribute presence is enough; value ignored)
+registerDOMContract("defined", (value) => DEFINED.checkAlgorithm(value));
+// data-xdbc-undefined
+registerDOMContract("undefined", (value) => UNDEFINED.checkAlgorithm(value));
+// data-xdbc-greater="5"
+registerDOMContract("greater", (value, attr) => COMPARISON.checkAlgorithm(Number(value), Number(attr), false, false));
+// data-xdbc-greater-or-equal="5"
+registerDOMContract("greater-or-equal", (value, attr) => COMPARISON.checkAlgorithm(Number(value), Number(attr), true, false));
+// data-xdbc-less="100"
+registerDOMContract("less", (value, attr) => COMPARISON.checkAlgorithm(Number(value), Number(attr), false, true));
+// data-xdbc-less-or-equal="100"
+registerDOMContract("less-or-equal", (value, attr) => COMPARISON.checkAlgorithm(Number(value), Number(attr), true, true));
+// data-xdbc-or="regex:^\d+$;;type:string;;eq:42"
+// Fragments are separated by ";;". Each fragment is "<contract-key>:<attr-value>",
+// where the split is on the FIRST ":" only, so colons in the value (e.g. regex) are safe.
+// The OR passes as long as at least one fragment passes.
+registerDOMContract("or", (value, attr) => {
+    const fragments = attr.split(";;");
+    const messages = [];
+    for (const fragment of fragments) {
+        const colonIdx = fragment.indexOf(":");
+        const key = colonIdx === -1 ? fragment.trim() : fragment.slice(0, colonIdx).trim();
+        const fragAttr = colonIdx === -1 ? "" : fragment.slice(colonIdx + 1);
+        const checkFn = registry.get(key);
+        if (!checkFn) {
+            console.warn(`[XDBC] data-xdbc-or: unknown contract key "${key}"`);
+            continue;
+        }
+        const result = checkFn(value, fragAttr);
+        if (result === true)
+            return true; // short-circuit on first pass
+        if (typeof result === "string")
+            messages.push(result);
+    }
+    return messages.length > 0
+        ? `Value did not satisfy any of: ${messages.join(" | ")}`
+        : true;
+});
+// ─── scanDOM ──────────────────────────────────────────────────────────────────
+/**
+ * Scans the given **root** for `<input>` and `<textarea>` elements marked with the
+ * `data-xdbc` attribute, and binds XDBC contracts to their `input` events (covering
+ * keyboard, paste, IME / mobile on-screen keyboard, voice input, and autofill).
+ *
+ * ### Supported attributes
+ *
+ * | Attribute                  | Example value              | Contract        |
+ * |----------------------------|----------------------------|-----------------|
+ * | `data-xdbc`                | *(path or empty)*          | marker / DBC path |
+ * | `data-xdbc-regex`          | `^\d*$`                    | {@link REGEX}   |
+ * | `data-xdbc-type`           | `string\|number`           | {@link TYPE}    |
+ * | `data-xdbc-eq`             | `hello`                    | {@link EQ}      |
+ * | `data-xdbc-different`      | `forbidden`                | {@link EQ} (inverted) |
+ * | `data-xdbc-defined`        | *(no value needed)*        | {@link DEFINED} |
+ * | `data-xdbc-undefined`      | *(no value needed)*        | {@link UNDEFINED} |
+ * | `data-xdbc-greater`        | `5`                        | {@link COMPARISON} |
+ * | `data-xdbc-greater-or-equal` | `5`                      | {@link COMPARISON} |
+ * | `data-xdbc-less`           | `100`                      | {@link COMPARISON} |
+ * | `data-xdbc-less-or-equal`  | `100`                      | {@link COMPARISON} |
+ * | `data-xdbc-or`             | `regex:^\d+$;;type:string` | {@link OR} (fragment syntax) |
+ *
+ * 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.
+ *
+ * @example
+ * ```html
+ * <input type="text" data-xdbc data-xdbc-regex="^\d*$" />
+ * <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 function scanDOM(root = document) {
+    var _a;
+    const bound = [];
+    const elements = Array.from(root.querySelectorAll("[data-xdbc]"));
+    for (const el of elements) {
+        const dbcPath = el.dataset.xdbc || "WaXCode.DBC";
+        // Collect every registered contract that has a corresponding attribute on this element.
+        const checks = [];
+        for (const [key, checkFn] of registry) {
+            // dataset converts "xdbc-greater-or-equal" → "xdbcGreaterOrEqual" via camelCase.
+            // Build the camelCase key from the registry key.
+            const datasetKey = `xdbc${key
+                .split("-")
+                .map((s) => s.charAt(0).toUpperCase() + s.slice(1))
+                .join("")}`;
+            if (datasetKey in el.dataset) {
+                checks.push({ checkFn, attrValue: (_a = el.dataset[datasetKey]) !== null && _a !== void 0 ? _a : "" });
+            }
+        }
+        if (checks.length === 0)
+            continue;
+        let lastValid = el.value;
+        let composing = false;
+        const inputListener = () => {
+            if (composing)
+                return;
+            const value = el.value;
+            for (const { checkFn, attrValue } of checks) {
+                const result = checkFn(value, attrValue);
+                if (typeof result === "string") {
+                    el.value = lastValid;
+                    try {
+                        DBC.getRegistered(dbcPath).reportParameterInfringement(result, el, undefined, el.name || el.id || "input", 0, value);
+                    }
+                    catch (_a) {
+                        // swallowed — throwException must not propagate out of a DOM event handler
+                    }
+                    return; // stop checking further contracts once one fails
+                }
+            }
+            lastValid = value;
+        };
+        const compositionStartListener = () => {
+            composing = true;
+        };
+        const compositionEndListener = () => {
+            composing = false;
+            inputListener();
+        };
+        el.addEventListener("input", inputListener);
+        el.addEventListener("compositionstart", compositionStartListener);
+        el.addEventListener("compositionend", compositionEndListener);
+        bound.push({
+            element: el,
+            inputListener,
+            compositionStartListener,
+            compositionEndListener,
+        });
+    }
+    return () => {
+        for (const { element, inputListener, compositionStartListener, compositionEndListener, } of bound) {
+            element.removeEventListener("input", inputListener);
+            element.removeEventListener("compositionstart", compositionStartListener);
+            element.removeEventListener("compositionend", compositionEndListener);
+        }
+    };
+}