@schukai/monster 3.102.5 → 3.103.0

package/source/dom/customcontrol.mjs

@@ -12,15 +12,15 @@
  * SPDX-License-Identifier: AGPL-3.0
  */
 
-import {extend} from "../data/extend.mjs";
-import {addAttributeToken} from "./attributes.mjs";
-import {ATTRIBUTE_ERRORMESSAGE} from "./constants.mjs";
-import {CustomElement, attributeObserverSymbol} from "./customelement.mjs";
-import {instanceSymbol} from "../constants.mjs";
-import {DeadMansSwitch} from "../util/deadmansswitch.mjs";
-import {addErrorAttribute} from "./error.mjs";
+import { extend } from "../data/extend.mjs";
+import { addAttributeToken } from "./attributes.mjs";
+import { ATTRIBUTE_ERRORMESSAGE } from "./constants.mjs";
+import { CustomElement, attributeObserverSymbol } from "./customelement.mjs";
+import { instanceSymbol } from "../constants.mjs";
+import { DeadMansSwitch } from "../util/deadmansswitch.mjs";
+import { addErrorAttribute } from "./error.mjs";
 
-export {CustomControl};
+export { CustomControl };
 
 /**
  * @private
@@ -53,286 +53,285 @@ const attachedInternalSymbol = Symbol("attachedInternal");
  * @since 1.14.0
  */
 class CustomControl extends CustomElement {
-    /**
-     * The constructor method of CustomControl, which is called when creating a new instance.
-     * It checks whether the element supports `attachInternals()` and initializes an internal form-associated element
-     * if supported. Additionally, it initializes a MutationObserver to watch for attribute changes.
-     *
-     * See the links below for more information:
-     * {@link https://html.spec.whatwg.org/multipage/custom-elements.html#dom-customelementregistry-define|CustomElementRegistry.define()}
-     * {@link https://html.spec.whatwg.org/multipage/custom-elements.html#dom-customelementregistry-get|CustomElementRegistry.get()}
-     * and {@link https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals|ElementInternals}
-     *
-     * @inheritdoc
-     * @throws {Error} the ElementInternals is not supported and a polyfill is necessary
-     */
-    constructor() {
-        super();
-
-        // check if element supports `attachInternals()`
-        if (typeof this["attachInternals"] === "function") {
-            this[attachedInternalSymbol] = this.attachInternals();
-        } else {
-            // `attachInternals()` is not supported, so a polyfill is necessary
-            throw Error(
-                "the ElementInternals is not supported and a polyfill is necessary",
-            );
-        }
-
-        // watch for attribute value changes
-        initValueAttributeObserver.call(this);
-    }
-
-    /**
-     * This method is called by the `instanceof` operator.
-     * @return {symbol}
-     * @since 2.1.0
-     */
-    static get [instanceSymbol]() {
-        return Symbol.for("@schukai/monster/dom/custom-control@@instance");
-    }
-
-    /**
-     * This method determines which attributes are to be monitored by `attributeChangedCallback()`.
-     *
-     * @return {string[]}
-     * @since 1.15.0
-     */
-    static get observedAttributes() {
-        return super.observedAttributes;
-    }
-
-    /**
-     * Adding a static `formAssociated` property, with a true value, makes an autonomous custom element a form-associated custom element.
-     *
-     * @see [attachInternals()]{@link https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/attachInternals}
-     * @see [Custom Elements Face Example]{@link https://html.spec.whatwg.org/multipage/custom-elements.html#custom-elements-face-example}
-     * @return {boolean}
-     */
-    static formAssociated = true;
-
-    /**
-     * @inheritdoc
-     **/
-    get defaults() {
-        return extend({}, super.defaults);
-    }
-
-    /**
-     * Must be overridden by a derived class and return the value of the control.
-     *
-     * This is a method of [internal API](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals), which is a part of the web standard for custom elements.
-     *
-     * @throws {Error} the value getter must be overwritten by the derived class
-     */
-    get value() {
-        throw Error("the value getter must be overwritten by the derived class");
-    }
-
-    /**
-     * Must be overridden by a derived class and set the value of the control.
-     *
-     * This is a method of [internal API](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals), which is a part of the web standard for custom elements.
-     *
-     * @param {*} value The value to set.
-     * @throws {Error} the value setter must be overwritten by the derived class
-     */
-    set value(value) {
-        throw Error("the value setter must be overwritten by the derived class");
-    }
-
-    /**
-     * This is a method of [internal api](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals)
-     *
-     * @return {NodeList}
-     * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/labels}
-     * @throws {Error} the ElementInternals is not supported and a polyfill is necessary
-     */
-    get labels() {
-        return getInternal.call(this)?.labels;
-    }
-
-    /**
-     * This is a method of [internal api](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals)
-     *
-     * @return {string|null}
-     */
-    get name() {
-        return this.getAttribute("name");
-    }
-
-    /**
-     * This is a method of [internal api](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals)
-     *
-     * @return {string}
-     */
-    get type() {
-        return this.constructor.getTag();
-    }
-
-    /**
-     * This is a method of [internal api](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals)
-     *
-     * @return {ValidityState}
-     * @throws {Error} the ElementInternals is not supported and a polyfill is necessary
-     * @see [ValidityState]{@link https://developer.mozilla.org/en-US/docs/Web/API/ValidityState}
-     * @see [validity]{@link https://developer.mozilla.org/en-US/docs/Web/API/validity}
-     */
-    get validity() {
-        return getInternal.call(this)?.validity;
-    }
-
-    /**
-     * This is a method of [internal api](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals)
-     *
-     * @return {string}
-     * @see https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/validationMessage
-     * @throws {Error} the ElementInternals is not supported and a polyfill is necessary
-     */
-    get validationMessage() {
-        return getInternal.call(this)?.validationMessage;
-    }
-
-    /**
-     * This is a method of [internal api](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals)
-     *
-     * @return {boolean}
-     * @see https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/willValidate
-     * @throws {Error} the ElementInternals is not supported and a polyfill is necessary
-     */
-    get willValidate() {
-        return getInternal.call(this)?.willValidate;
-    }
-
-    /**
-     * This is a method of [internal api](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals)
-     *
-     * @return {boolean}
-     * @see https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/states
-     * @throws {Error} the ElementInternals is not supported and a polyfill is necessary
-     */
-    get states() {
-        return getInternal.call(this)?.states;
-    }
-
-    /**
-     * This is a method of [internal api](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals)
-     *
-     * @return {HTMLFontElement|null}
-     * @see https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/form
-     * @throws {Error} the ElementInternals is not supported and a polyfill is necessary
-     */
-    get form() {
-        return getInternal.call(this)?.form;
-    }
-
-    /**
-     * This is a method of [internal api](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals)
-     *
-     * ```
-     * // Use the control's name as the base name for submitted data
-     * const n = this.getAttribute('name');
-     * const entries = new FormData();
-     * entries.append(n + '-first-name', this.firstName_);
-     * entries.append(n + '-last-name', this.lastName_);
-     * this.setFormValue(entries);
-     * ```
-     *
-     * @param {File|string|FormData} value
-     * @param {File|string|FormData} state
-     * @return {undefined}
-     * @throws {DOMException} NotSupportedError
-     * @throws {Error} the ElementInternals is not supported and a polyfill is necessary
-     * @see https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/setFormValue
-     */
-    setFormValue(value, state) {
-        getInternal.call(this).setFormValue(value, state);
-    }
-
-    /**
-     *
-     * @param {object} flags
-     * @param {string|undefined} message
-     * @param {HTMLElement} anchor
-     * @see https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/setValidity
-     * @return {undefined}
-     * @throws {DOMException} NotSupportedError
-     * @throws {Error} the ElementInternals is not supported and a polyfill is necessary
-     */
-    setValidity(flags, message, anchor) {
-        getInternal.call(this).setValidity(flags, message, anchor);
-    }
-
-    /**
-     * This is a method of [internal api](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals)
-     *
-     * @see https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/checkValidity
-     * @return {boolean}
-     * @throws {DOMException} NotSupportedError
-     * @throws {Error} the ElementInternals is not supported and a polyfill is necessary
-     */
-    checkValidity() {
-        return getInternal.call(this)?.checkValidity();
-    }
-
-    /**
-     * This is a method of [internal api](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals)
-     *
-     * @return {boolean}
-     * @see https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/reportValidity
-     * @throws {Error} the ElementInternals is not supported and a polyfill is necessary
-     * @throws {DOMException} NotSupportedError
-     */
-    reportValidity() {
-        return getInternal.call(this)?.reportValidity();
-    }
-
-    /**
-     * Sets the `form` attribute of the custom control to the `id` of the passed form element.
-     * If no form element is passed, removes the `form` attribute.
-     *
-     * @param {HTMLFormElement} form - The form element to associate with the control
-     */
-    formAssociatedCallback(form) {
-        if (form) {
-            if (form.id) {
-                this.setAttribute("form", form.id);
-            }
-        } else {
-            this.removeAttribute("form");
-        }
-    }
-
-    /**
-     * Sets or removes the `disabled` attribute of the custom control based on the passed value.
-     *
-     * @param {boolean} disabled - Whether or not the control should be disabled
-     */
-    formDisabledCallback(disabled) {
-        if (disabled) {
-            if (!this.hasAttribute("disabled")) {
-                this.setAttribute("disabled", "");
-            }
-        } else {
-            if (this.hasAttribute("disabled")) {
-                this.removeAttribute("disabled");
-            }
-        }
-    }
-
-    /**
-     * @param {string} state
-     * @param {string} mode
-     */
-    formStateRestoreCallback(state, mode) {
-    }
-
-    /**
-     *
-     */
-    formResetCallback() {
-        this.value = "";
-    }
+	/**
+	 * The constructor method of CustomControl, which is called when creating a new instance.
+	 * It checks whether the element supports `attachInternals()` and initializes an internal form-associated element
+	 * if supported. Additionally, it initializes a MutationObserver to watch for attribute changes.
+	 *
+	 * See the links below for more information:
+	 * {@link https://html.spec.whatwg.org/multipage/custom-elements.html#dom-customelementregistry-define|CustomElementRegistry.define()}
+	 * {@link https://html.spec.whatwg.org/multipage/custom-elements.html#dom-customelementregistry-get|CustomElementRegistry.get()}
+	 * and {@link https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals|ElementInternals}
+	 *
+	 * @inheritdoc
+	 * @throws {Error} the ElementInternals is not supported and a polyfill is necessary
+	 */
+	constructor() {
+		super();
+
+		// check if element supports `attachInternals()`
+		if (typeof this["attachInternals"] === "function") {
+			this[attachedInternalSymbol] = this.attachInternals();
+		} else {
+			// `attachInternals()` is not supported, so a polyfill is necessary
+			throw Error(
+				"the ElementInternals is not supported and a polyfill is necessary",
+			);
+		}
+
+		// watch for attribute value changes
+		initValueAttributeObserver.call(this);
+	}
+
+	/**
+	 * This method is called by the `instanceof` operator.
+	 * @return {symbol}
+	 * @since 2.1.0
+	 */
+	static get [instanceSymbol]() {
+		return Symbol.for("@schukai/monster/dom/custom-control@@instance");
+	}
+
+	/**
+	 * This method determines which attributes are to be monitored by `attributeChangedCallback()`.
+	 *
+	 * @return {string[]}
+	 * @since 1.15.0
+	 */
+	static get observedAttributes() {
+		return super.observedAttributes;
+	}
+
+	/**
+	 * Adding a static `formAssociated` property, with a true value, makes an autonomous custom element a form-associated custom element.
+	 *
+	 * @see [attachInternals()]{@link https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/attachInternals}
+	 * @see [Custom Elements Face Example]{@link https://html.spec.whatwg.org/multipage/custom-elements.html#custom-elements-face-example}
+	 * @return {boolean}
+	 */
+	static formAssociated = true;
+
+	/**
+	 * @inheritdoc
+	 **/
+	get defaults() {
+		return extend({}, super.defaults);
+	}
+
+	/**
+	 * Must be overridden by a derived class and return the value of the control.
+	 *
+	 * This is a method of [internal API](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals), which is a part of the web standard for custom elements.
+	 *
+	 * @throws {Error} the value getter must be overwritten by the derived class
+	 */
+	get value() {
+		throw Error("the value getter must be overwritten by the derived class");
+	}
+
+	/**
+	 * Must be overridden by a derived class and set the value of the control.
+	 *
+	 * This is a method of [internal API](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals), which is a part of the web standard for custom elements.
+	 *
+	 * @param {*} value The value to set.
+	 * @throws {Error} the value setter must be overwritten by the derived class
+	 */
+	set value(value) {
+		throw Error("the value setter must be overwritten by the derived class");
+	}
+
+	/**
+	 * This is a method of [internal api](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals)
+	 *
+	 * @return {NodeList}
+	 * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/labels}
+	 * @throws {Error} the ElementInternals is not supported and a polyfill is necessary
+	 */
+	get labels() {
+		return getInternal.call(this)?.labels;
+	}
+
+	/**
+	 * This is a method of [internal api](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals)
+	 *
+	 * @return {string|null}
+	 */
+	get name() {
+		return this.getAttribute("name");
+	}
+
+	/**
+	 * This is a method of [internal api](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals)
+	 *
+	 * @return {string}
+	 */
+	get type() {
+		return this.constructor.getTag();
+	}
+
+	/**
+	 * This is a method of [internal api](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals)
+	 *
+	 * @return {ValidityState}
+	 * @throws {Error} the ElementInternals is not supported and a polyfill is necessary
+	 * @see [ValidityState]{@link https://developer.mozilla.org/en-US/docs/Web/API/ValidityState}
+	 * @see [validity]{@link https://developer.mozilla.org/en-US/docs/Web/API/validity}
+	 */
+	get validity() {
+		return getInternal.call(this)?.validity;
+	}
+
+	/**
+	 * This is a method of [internal api](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals)
+	 *
+	 * @return {string}
+	 * @see https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/validationMessage
+	 * @throws {Error} the ElementInternals is not supported and a polyfill is necessary
+	 */
+	get validationMessage() {
+		return getInternal.call(this)?.validationMessage;
+	}
+
+	/**
+	 * This is a method of [internal api](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals)
+	 *
+	 * @return {boolean}
+	 * @see https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/willValidate
+	 * @throws {Error} the ElementInternals is not supported and a polyfill is necessary
+	 */
+	get willValidate() {
+		return getInternal.call(this)?.willValidate;
+	}
+
+	/**
+	 * This is a method of [internal api](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals)
+	 *
+	 * @return {boolean}
+	 * @see https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/states
+	 * @throws {Error} the ElementInternals is not supported and a polyfill is necessary
+	 */
+	get states() {
+		return getInternal.call(this)?.states;
+	}
+
+	/**
+	 * This is a method of [internal api](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals)
+	 *
+	 * @return {HTMLFontElement|null}
+	 * @see https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/form
+	 * @throws {Error} the ElementInternals is not supported and a polyfill is necessary
+	 */
+	get form() {
+		return getInternal.call(this)?.form;
+	}
+
+	/**
+	 * This is a method of [internal api](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals)
+	 *
+	 * ```
+	 * // Use the control's name as the base name for submitted data
+	 * const n = this.getAttribute('name');
+	 * const entries = new FormData();
+	 * entries.append(n + '-first-name', this.firstName_);
+	 * entries.append(n + '-last-name', this.lastName_);
+	 * this.setFormValue(entries);
+	 * ```
+	 *
+	 * @param {File|string|FormData} value
+	 * @param {File|string|FormData} state
+	 * @return {undefined}
+	 * @throws {DOMException} NotSupportedError
+	 * @throws {Error} the ElementInternals is not supported and a polyfill is necessary
+	 * @see https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/setFormValue
+	 */
+	setFormValue(value, state) {
+		getInternal.call(this).setFormValue(value, state);
+	}
+
+	/**
+	 *
+	 * @param {object} flags
+	 * @param {string|undefined} message
+	 * @param {HTMLElement} anchor
+	 * @see https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/setValidity
+	 * @return {undefined}
+	 * @throws {DOMException} NotSupportedError
+	 * @throws {Error} the ElementInternals is not supported and a polyfill is necessary
+	 */
+	setValidity(flags, message, anchor) {
+		getInternal.call(this).setValidity(flags, message, anchor);
+	}
+
+	/**
+	 * This is a method of [internal api](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals)
+	 *
+	 * @see https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/checkValidity
+	 * @return {boolean}
+	 * @throws {DOMException} NotSupportedError
+	 * @throws {Error} the ElementInternals is not supported and a polyfill is necessary
+	 */
+	checkValidity() {
+		return getInternal.call(this)?.checkValidity();
+	}
+
+	/**
+	 * This is a method of [internal api](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals)
+	 *
+	 * @return {boolean}
+	 * @see https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/reportValidity
+	 * @throws {Error} the ElementInternals is not supported and a polyfill is necessary
+	 * @throws {DOMException} NotSupportedError
+	 */
+	reportValidity() {
+		return getInternal.call(this)?.reportValidity();
+	}
+
+	/**
+	 * Sets the `form` attribute of the custom control to the `id` of the passed form element.
+	 * If no form element is passed, removes the `form` attribute.
+	 *
+	 * @param {HTMLFormElement} form - The form element to associate with the control
+	 */
+	formAssociatedCallback(form) {
+		if (form) {
+			if (form.id) {
+				this.setAttribute("form", form.id);
+			}
+		} else {
+			this.removeAttribute("form");
+		}
+	}
+
+	/**
+	 * Sets or removes the `disabled` attribute of the custom control based on the passed value.
+	 *
+	 * @param {boolean} disabled - Whether or not the control should be disabled
+	 */
+	formDisabledCallback(disabled) {
+		if (disabled) {
+			if (!this.hasAttribute("disabled")) {
+				this.setAttribute("disabled", "");
+			}
+		} else {
+			if (this.hasAttribute("disabled")) {
+				this.removeAttribute("disabled");
+			}
+		}
+	}
+
+	/**
+	 * @param {string} state
+	 * @param {string} mode
+	 */
+	formStateRestoreCallback(state, mode) {}
+
+	/**
+	 *
+	 */
+	formResetCallback() {
+		this.value = "";
+	}
 }
 
 /**
@@ -342,13 +341,13 @@ class CustomControl extends CustomElement {
  * @this CustomControl
  */
 function getInternal() {
-    if (!(attachedInternalSymbol in this)) {
-        throw new Error(
-            "ElementInternals is not supported and a polyfill is necessary",
-        );
-    }
+	if (!(attachedInternalSymbol in this)) {
+		throw new Error(
+			"ElementInternals is not supported and a polyfill is necessary",
+		);
+	}
 
-    return this[attachedInternalSymbol];
+	return this[attachedInternalSymbol];
 }
 
 const debounceValueSymbol = Symbol("debounceValue");
@@ -362,31 +361,29 @@ const debounceValueSymbol = Symbol("debounceValue");
  * @this CustomControl
  */
 function initValueAttributeObserver() {
-    const self = this;
-    this[attributeObserverSymbol]["value"] = () => {
-
-        if (self[debounceValueSymbol] instanceof DeadMansSwitch) {
-            try {
-                self[debounceValueSymbol].touch();
-                return;
-            } catch (e) {
-                if (e.message !== "has already run") {
-                    throw e;
-                }
-                delete self[debounceValueSymbol];
-            }
-        }
-
-        self[debounceValueSymbol] = new DeadMansSwitch(10, () => {
-            const oldValue = self.getAttribute("value");
-            const newValue = self.getOption("value");
-
-            if (oldValue !== newValue) {
-                setTimeout(() => {
-                    this.setOption("value", this.getAttribute("value"));
-                },0);
-
-            }
-        });
-    };
+	const self = this;
+	this[attributeObserverSymbol]["value"] = () => {
+		if (self[debounceValueSymbol] instanceof DeadMansSwitch) {
+			try {
+				self[debounceValueSymbol].touch();
+				return;
+			} catch (e) {
+				if (e.message !== "has already run") {
+					throw e;
+				}
+				delete self[debounceValueSymbol];
+			}
+		}
+
+		self[debounceValueSymbol] = new DeadMansSwitch(10, () => {
+			const oldValue = self.getAttribute("value");
+			const newValue = self.getOption("value");
+
+			if (oldValue !== newValue) {
+				setTimeout(() => {
+					this.setOption("value", this.getAttribute("value"));
+				}, 0);
+			}
+		});
+	};
 }