customcontrol.mjs

/**
 * Copyright © schukai GmbH and all contributing authors, {{copyRightYear}}. All rights reserved.
 * Node module: @schukai/monster
 *
 * This source code is licensed under the GNU Affero General Public License version 3 (AGPLv3).
 * The full text of the license can be found at: https://www.gnu.org/licenses/agpl-3.0.en.html
 *
 * For those who do not wish to adhere to the AGPLv3, a commercial license is available.
 * Acquiring a commercial license allows you to use this software without complying with the AGPLv3 terms.
 * For more information about purchasing a commercial license, please contact schukai GmbH.
 *
 * 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";

export { CustomControl };

/**
 * @private
 * @type {symbol}
 */
const attachedInternalSymbol = Symbol("attachedInternal");

/**
 * This is a base class for creating custom controls using the power of CustomElement.
 *
 * After defining a `CustomElement`, the `registerCustomElement` method must be called with the new class name. Only then
 * will the tag defined via the `getTag` method be made known to the DOM.
 *
 * This control uses `attachInternals()` to integrate the control into a form. If the target environment does not support
 * this method, the [polyfill](https://www.npmjs.com/package/element-internals-polyfill) can be used.
 *
 * You can create the object using the function `document.createElement()`.
 *
 * This control uses `attachInternals()` to integrate the control into a form. If the target environment does not support
 * this method, the Polyfill for attachInternals() can be used: {@link https://www.npmjs.com/package/element-internals-polyfill|element-internals-polyfill}.
 *
 * Learn more about WICG Web Components: {@link https://github.com/WICG/webcomponents|WICG Web Components}.
 *
 * Read the HTML specification for Custom Elements: {@link https://html.spec.whatwg.org/multipage/custom-elements.html#custom-elements|Custom Elements}.
 *
 * Read the HTML specification for Custom Element Reactions: {@link https://html.spec.whatwg.org/dev/custom-elements.html#custom-element-reactions|Custom Element Reactions}.
 *
 * @summary A base class for custom controls based on CustomElement.
 * @license AGPLv3
 * @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();