@schukai/monster 3.47.0 → 3.49.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@schukai/monster",
-  "version": "3.47.0",
+  "version": "3.49.0",
   "description": "Monster is a simple library for creating fast, robust and lightweight websites.",
   "keywords": [
     "framework",

package/source/dom/constants.mjs

@@ -59,9 +59,9 @@ export {
     ATTRIBUTE_HIDDEN,
     objectUpdaterLinkSymbol,
     customElementUpdaterLinkSymbol,
-    optionCallbackName,
+    initControlCallbackName,
     ATTRIBUTE_SCRIPT_HOST,
-    ATTRIBUTE_OPTION_CALLBACK
+    ATTRIBUTE_INIT_CALLBACK
 };
 
 /**
@@ -117,7 +117,7 @@ const ATTRIBUTE_OPTIONS_SELECTOR = `${ATTRIBUTE_PREFIX}options-selector`;
  * @since 3.48.0
  * @type {string}
  */
-const ATTRIBUTE_OPTION_CALLBACK = `${ATTRIBUTE_PREFIX}option-callback`;
+const ATTRIBUTE_INIT_CALLBACK = `${ATTRIBUTE_PREFIX}init-callback`;
 
 /**
  * This is the name of the callback to pass the callback to a control
@@ -127,7 +127,7 @@ const ATTRIBUTE_OPTION_CALLBACK = `${ATTRIBUTE_PREFIX}option-callback`;
  * @since 3.48.0
  * @type {string}
  */
-const optionCallbackName = `initCustomControlOptionsCallback`;
+const initControlCallbackName = `initCustomControlCallback`;
 
 /**
  * @memberOf Monster.DOM

package/source/dom/customcontrol.mjs

@@ -6,7 +6,8 @@
  */
 
 import {extend} from "../data/extend.mjs";
-import {ATTRIBUTE_VALUE} from "./constants.mjs";
+import {addAttributeToken} from "./attributes.mjs";
+import {ATTRIBUTE_ERRORMESSAGE} from "./constants.mjs";
 import {CustomElement, attributeObserverSymbol} from "./customelement.mjs";
 import {instanceSymbol} from "../constants.mjs";
 
@@ -19,57 +20,66 @@ export {CustomControl};
 const attachedInternalSymbol = Symbol("attachedInternal");
 
 /**
- * To define a new HTML control we need the power of CustomElement
+ * This is a base class for creating custom controls using the power of CustomElement.
  *
- * IMPORTANT: 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.
+ * 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.
  *
  * <img src="./images/customcontrol-class.png">
  *
- * 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.
+ * 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 via the function `document.createElement()`.
+ * You can create the object using the function `document.createElement()`.
  *
- * @startuml customcontrol-class.png
- * skinparam monochrome true
- * skinparam shadowing false
- * HTMLElement <|-- CustomElement
- * CustomElement <|-- CustomControl
- * @enduml
+ * 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}.
  *
- * @summary A base class for customcontrols based on CustomElement
- * @see {@link https://www.npmjs.com/package/element-internals-polyfill}
- * @see {@link https://github.com/WICG/webcomponents}
- * @see {@link https://html.spec.whatwg.org/multipage/custom-elements.html#custom-elements}
- * @see {@link https://html.spec.whatwg.org/dev/custom-elements.html#custom-element-reactions}
+ * 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.
+ * @copyright schukai GmbH 
  * @license AGPLv3
  * @since 1.14.0
- * @copyright schukai GmbH
  * @memberOf Monster.DOM
+ * @extends Monster.DOM.CustomElement
  */
 class CustomControl extends CustomElement {
+
     /**
-     * IMPORTANT: CustomControls instances are not created via the constructor, but either via a tag in the HTML or via <code>document.createElement()</code>.
+     * 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
-     * @summary create new Instance
+     * @since 1.7.0
      */
     constructor() {
         super();
 
+        // check if element supports `attachInternals()`
         if (typeof this["attachInternals"] === "function") {
-            /**
-             * currently only supported by chrome
-             * @property {Object}
-             * @private
-             */
             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");
         }
 
+        // initialize a MutationObserver to watch for attribute changes
         initObserver.call(this);
     }
 
+
     /**
      * This method is called by the `instanceof` operator.
      * @returns {symbol}
@@ -90,40 +100,27 @@ class CustomControl extends CustomElement {
     }
 
     /**
-     * Adding a static formAssociated property, with a true value, makes an autonomous custom element a form-associated custom element.
+     * Adding a static `formAssociated` property, with a true value, makes an autonomous custom element a form-associated custom element.
      *
-     * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/attachInternals}
-     * @see {@link https://html.spec.whatwg.org/multipage/custom-elements.html#custom-elements-face-example}
+     * @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}
      * @since 1.14.0
      * @return {boolean}
      */
-    static formAssociated = true
+    static formAssociated = true;
 
     /**
-     * Derived classes can override and extend this method as follows.
-     *
-     * ```
-     * get defaults() {
-     *    return extends{}, super.defaults, {
-     *        myValue:true
-     *    });
-     * }
-     * ```
-     *
-     * @see {@link https://html.spec.whatwg.org/multipage/custom-elements.html#custom-elements-face-example}
-     * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/attachInternals}
-     * @return {object}
+     * @inheritdoc
      * @since 1.14.0
-     */
+     **/
     get defaults() {
-        return extend({
-        }, super.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)
+     * 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.
      *
      * @since 1.14.0
      * @throws {Error} the value getter must be overwritten by the derived class
@@ -133,11 +130,11 @@ class CustomControl extends CustomElement {
     }
 
     /**
-     * Must be overridden by a derived class and return the value of the control.
+     * 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)
+     * 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
+     * @param {*} value The value to set.
      * @since 1.14.0
      * @throws {Error} the value setter must be overwritten by the derived class
      */
@@ -145,6 +142,7 @@ class CustomControl extends CustomElement {
         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)
      *
@@ -180,8 +178,8 @@ class CustomControl extends CustomElement {
      *
      * @return {ValidityState}
      * @throws {Error} the ElementInternals is not supported and a polyfill is necessary
-     * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/ValidityState}
-     * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/validity}
+     * @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;
@@ -214,7 +212,7 @@ class CustomControl extends CustomElement {
     /**
      * This is a method of [internal api](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals)
      *
-     * @return {CustomStateSet}
+     * @return {boolean}
      * @since 1.14.0
      * @see https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/states
      * @throws {Error} the ElementInternals is not supported and a polyfill is necessary
@@ -301,12 +299,15 @@ class CustomControl extends CustomElement {
     }
 
     /**
-     * @param {string} form
+     * 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);    
+            if (form.id) {
+                this.setAttribute("form", form.id);
             }
         } else {
             this.removeAttribute("form");
@@ -314,7 +315,9 @@ class CustomControl extends CustomElement {
     }
 
     /**
-     * @param {string} disabled
+     * 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) {
@@ -324,19 +327,20 @@ class CustomControl extends CustomElement {
         }
     }
 
+
     /**
      * @param {string} state
      * @param {string} mode
      */
     formStateRestoreCallback(state, mode) {
-        
+
     }
 
     /**
      *
      */
     formResetCallback() {
-       this.value = "";
+        this.value = "";
     }
 
 }

package/source/dom/customelement.mjs

@@ -23,11 +23,11 @@ import {
     ATTRIBUTE_DISABLED,
     ATTRIBUTE_ERRORMESSAGE,
     ATTRIBUTE_OPTIONS,
-    ATTRIBUTE_OPTION_CALLBACK,
+    ATTRIBUTE_INIT_CALLBACK,
     ATTRIBUTE_OPTIONS_SELECTOR,
     ATTRIBUTE_SCRIPT_HOST,
     customElementUpdaterLinkSymbol,
-    optionCallbackName
+    initControlCallbackName
 } from "./constants.mjs";
 import {findDocumentTemplate, Template} from "./template.mjs";
 import {addObjectWithUpdaterToElement} from "./updater.mjs";
@@ -121,15 +121,12 @@ const scriptHostElementSymbol = Symbol("scriptHostElement");
  */
 
 /**
- * To define a new HTML element we need the power of CustomElement
+ * The `CustomElement` class provides a way to define a new HTML element using the power of Custom Elements.
  *
- * IMPORTANT: 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.
- *
- * <img src="./images/customelement-class.png">
- *
- * You can create the object via the function `document.createElement()`.
+ * **IMPORTANT:** After defining a `CustomElement`, the `registerCustomElement` method must be called with the new class name
+ * to make the tag defined via the `getTag` method known to the DOM.
  *
+ * You can create an instance of the object via the `document.createElement()` function.
  *
  * ## Interaction
  *
@@ -137,15 +134,13 @@ const scriptHostElementSymbol = Symbol("scriptHostElement");
  *
  * ## Styling
  *
- * For optimal display of custom-elements the pseudo-class :defined can be used.
+ * To display custom elements optimally, the `:defined` pseudo-class can be used. To prevent custom elements from being displayed and flickering until the control is registered,
+ * it is recommended to create a CSS directive.
  *
- * To prevent the custom elements from being displayed and flickering until the control is registered, it is recommended to create a css directive.
+ * In the simplest case, you can simply hide the control:
  *
- * In the simplest case, you can simply hide the control.
- *
- * ```
+ * ```html
  * <style>
- *
  * my-custom-element:not(:defined) {
  *     display: none;
  * }
@@ -153,62 +148,64 @@ const scriptHostElementSymbol = Symbol("scriptHostElement");
  * my-custom-element:defined {
  *     display: flex;
  * }
- *
  * </style>
  * ```
  *
- * Alternatively you can also display a loader
+ * Alternatively, you can display a loader:
  *
- * ```
+ * ```css
  * my-custom-element:not(:defined) {
- *            display: flex;
- *            box-shadow: 0 4px 10px 0 rgba(33, 33, 33, 0.15);
- *            border-radius: 4px;
- *            height: 200px;
- *            position: relative;
- *            overflow: hidden;
- *        }
+ *     display: flex;
+ *     box-shadow: 0 4px 10px 0 rgba(33, 33, 33, 0.15);
+ *     border-radius: 4px;
+ *     height: 200px;
+ *     position: relative;
+ *     overflow: hidden;
+ * }
  *
  * my-custom-element:not(:defined)::before {
- *            content: '';
- *            display: block;
- *            position: absolute;
- *            left: -150px;
- *            top: 0;
- *            height: 100%;
- *            width: 150px;
- *            background: linear-gradient(to right, transparent 0%, #E8E8E8 50%, transparent 100%);
- *            animation: load 1s cubic-bezier(0.4, 0.0, 0.2, 1) infinite;
- *        }
+ *     content: '';
+ *     display: block;
+ *     position: absolute;
+ *     left: -150px;
+ *     top: 0;
+ *     height: 100%;
+ *     width: 150px;
+ *     background: linear-gradient(to right, transparent 0%, #E8E8E8 50%, transparent 100%);
+ *     animation: load 1s cubic-bezier(0.4, 0.0, 0.2, 1) infinite;
+ * }
  *
  * @keyframes load {
- *            from {
- *                left: -150px;
- *            }
- *            to   {
- *                left: 100%;
- *            }
- *        }
+ *     from {
+ *         left: -150px;
+ *     }
+ *     to {
+ *         left: 100%;
+ *     }
+ * }
  *
  * my-custom-element:defined {
- *           display: flex;
- *       }
+ *     display: flex;
+ * }
  * ```
+ * 
+ * More information about Custom Elements can be found in the [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements).
+ * And in the [HTML Standard](https://html.spec.whatwg.org/multipage/custom-elements.html#custom-elements) or in the [WHATWG Wiki](https://wiki.whatwg.org/wiki/Custom_Elements).
  *
  * @externalExample ../../example/dom/theme.mjs
- * @see https://github.com/WICG/webcomponents
- * @see https://html.spec.whatwg.org/multipage/custom-elements.html#custom-elements
  * @license AGPLv3
  * @since 1.7.0
  * @copyright schukai GmbH
  * @memberOf Monster.DOM
  * @extends external:HTMLElement
- * @summary A base class for HTML5 customcontrols
+ * @summary A base class for HTML5 custom controls.
  */
 class CustomElement extends HTMLElement {
     /**
      * A new object is created. First the `initOptions` method is called. Here the
      * options can be defined in derived classes. Subsequently, the shadowRoot is initialized.
+     * 
+     * IMPORTANT: CustomControls instances are not created via the constructor, but either via a tag in the HTML or via <code>document.createElement()</code>.
      *
      * @throws {Error} the options attribute does not contain a valid json definition.
      * @since 1.7.0
@@ -270,53 +267,25 @@ class CustomElement extends HTMLElement {
     }
 
     /**
-     * Derived classes can override and extend this method as follows.
+     * The `defaults` property defines the default values for a control. If you want to override these,
+     * you can use various methods, which are described in the documentation available at
+     * {@link https://monsterjs.orgendocconfigurate-a-monster-control}.
      *
-     * ```
-     * get defaults() {
-     *    return Object.assign({}, super.defaults, {
-     *        myValue:true
-     *    });
-     * }
-     * ```
-     *
-     * To set the options via the html tag the attribute data-monster-options must be set.
-     * As value a JSON object with the desired values must be defined.
-     *
-     * Since 1.18.0 the JSON can be specified as a DataURI.
-     *
-     * ```
-     * new Monster.Types.DataUrl(btoa(JSON.stringify({
-     *        shadowMode: 'open',
-     *        delegatesFocus: true,
-     *        templates: {
-     *            main: undefined
-     *        }
-     *    })),'application/json',true).toString()
-     * ```
-     *
-     * The attribute data-monster-options-selector can be used to access a script tag that contains additional configuration.
-     *
-     * As value a selector must be specified, which belongs to a script tag and contains the configuration as json.
-     *
-     * ```
-     * <script id="id-for-this-config" type="application/json">
-     *    {
-     *        "config-key": "config-value"
-     *    }
-     * </script>
-     * ```
+     * The individual configuration values are listed below:
      *
-     * The individual configuration values can be found in the table.
+     * More information about the shadowRoot can be found in the [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/API/Element/attachShadow),
+     * in the [HTML Standard](https://html.spec.whatwg.org/multipage/custom-elements.html#custom-elements) or in the [WHATWG Wiki](https://wiki.whatwg.org/wiki/Custom_Elements).
      *
-     * @property {boolean} disabled=false Object The Boolean disabled attribute, when present, makes the element not mutable, focusable, or even submitted with the form.
-     * @property {string} shadowMode=open `open` Elements of the shadow root are accessible from JavaScript outside the root, for example using. `close` Denies access to the node(s) of a closed shadow root from JavaScript outside it
-     * @property {Boolean} delegatesFocus=true A boolean that, when set to true, specifies behavior that mitigates custom element issues around focusability. When a non-focusable part of the shadow DOM is clicked, the first focusable part is given focus, and the shadow host is given any available :focus styling.
-     * @property {Object} templates Templates
-     * @property {string} templates.main=undefined Main template
-     * @property {Object} templateMapping Template mapping
+     * More information about the template element can be found in the [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/template).
      *
-     * @see https://developer.mozilla.org/en-US/docs/Web/API/Element/attachShadow
+     * More information about the slot element can be found in the [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/slot).
+     *  
+     * @property {boolean} disabled=false Specifies whether the control is disabled. When present, it makes the element non-mutable, non-focusable, and non-submittable with the form.
+     * @property {string} shadowMode=open Specifies the mode of the shadow root. When set to `open`, elements in the shadow root are accessible from JavaScript outside the root, while setting it to `closed` denies access to the root's nodes from JavaScript outside it.
+     * @property {Boolean} delegatesFocus=true Specifies the behavior of the control with respect to focusability. When set to `true`, it mitigates custom element issues around focusability. When a non-focusable part of the shadow DOM is clicked, the first focusable part is given focus, and the shadow host is given any available :focus styling.
+     * @property {Object} templates Specifies the templates used by the control.
+     * @property {string} templates.main=undefined Specifies the main template used by the control.
+     * @property {Object} templateMapping Specifies the mapping of templates.
      * @since 1.8.0
      */
     get defaults() {
@@ -383,39 +352,51 @@ class CustomElement extends HTMLElement {
     }
 
     /**
-     * There is no check on the name by this class. the developer is responsible for assigning an appropriate tag.
-     * if the name is not valid, registerCustomElement() will issue an error
+     * The `getTag()` method returns the tag name associated with the custom element. This method should be overwritten 
+     * by the derived class.
      *
-     * @link https://html.spec.whatwg.org/multipage/custom-elements.html#valid-custom-element-name
-     * @return {string}
-     * @throws {Error} the method getTag must be overwritten by the derived class.
+     * Note that there is no check on the name of the tag in this class. It is the responsibility of 
+     * the developer to assign an appropriate tag name. If the name is not valid, the 
+     * `registerCustomElement()` method will issue an error.
+     *
+     * @see https://html.spec.whatwg.org/multipage/custom-elements.html#valid-custom-element-name
+     * @throws {Error} This method must be overridden by the derived class.
+     * @return {string} The tag name associated with the custom element.
      * @since 1.7.0
      */
     static getTag() {
-        throw new Error("the method getTag must be overwritten by the derived class.");
+        throw new Error("The method `getTag()` must be overridden by the derived class.");
     }
 
     /**
-     * At this point a `CSSStyleSheet` object can be returned. If the environment does not
-     * support a constructor, then an object can also be built using the following detour.
+     * The `getCSSStyleSheet()` method returns a `CSSStyleSheet` object that defines the styles for the custom element. 
+     * If the environment does not support the `CSSStyleSheet` constructor, then an object can be built using the provided detour.
+     *
+     * If `undefined` is returned, then the shadow root does not receive a stylesheet.
      *
-     * If `undefined` is returned then the shadowRoot does not get a stylesheet.
+     * Example usage:
      *
+     * ```js
+     * static getCSSStyleSheet() {
+     *     const sheet = new CSSStyleSheet();
+     *     sheet.replaceSync("p { color: red; }");
+     *     return sheet;
+     * }
      * ```
-     * const doc = document.implementation.createHTMLDocument('title');
      *
-     * let style = doc.createElement("style");
-     * style.innerHTML="p{color:red;}";
+     * If the environment does not support the `CSSStyleSheet` constructor, 
+     * you can use the following workaround to create the stylesheet:
      *
-     * // WebKit Hack
+     * ```js
+     * const doc = document.implementation.createHTMLDocument('title');
+     * let style = doc.createElement("style");
+     * style.innerHTML = "p { color: red; }";
      * style.appendChild(document.createTextNode(""));
-     * // Add the <style> element to the page
      * doc.head.appendChild(style);
      * return doc.styleSheets[0];
-     * ;
      * ```
      *
-     * @return {CSSStyleSheet|CSSStyleSheet[]|string|undefined}
+     * @return {CSSStyleSheet|CSSStyleSheet[]|string|undefined} A `CSSStyleSheet` object or an array of such objects that define the styles for the custom element, or `undefined` if no stylesheet should be applied.
      */
     static getCSSStyleSheet() {
         return undefined;
@@ -511,9 +492,14 @@ class CustomElement extends HTMLElement {
     }
 
     /**
-     * Is called once when the object is included in the DOM for the first time.
+     * This method is called once when the object is included in the DOM for the first time. It performs the following actions:
+     * 1. Extracts the options from the attributes and the script tag of the element and sets them.
+     * 2. Initializes the shadow root and its CSS stylesheet (if specified).
+     * 3. Initializes the HTML content of the element.
+     * 4. Initializes the custom elements inside the shadow root and the slotted elements.
+     * 5. Attaches a mutation observer to observe changes to the attributes of the element.
      *
-     * @return {CustomElement}
+     * @return {CustomElement} - The updated custom element.
      * @since 1.8.0
      */
     [assembleMethodSymbol]() {
@@ -521,22 +507,25 @@ class CustomElement extends HTMLElement {
         let elements;
         let nodeList;
 
+        // Extract options from attributes and set them
         const AttributeOptions = getOptionsFromAttributes.call(self);
         if (isObject(AttributeOptions) && Object.keys(AttributeOptions).length > 0) {
             self.setOptions(AttributeOptions);
         }
 
+        // Extract options from script tag and set them
         const ScriptOptions = getOptionsFromScriptTag.call(self);
         if (isObject(ScriptOptions) && Object.keys(ScriptOptions).length > 0) {
             self.setOptions(ScriptOptions);
         }
 
-
+        // Initialize the shadow root and its CSS stylesheet
         if (self.getOption("shadowMode", false) !== false) {
             try {
                 initShadowRoot.call(self);
                 elements = self.shadowRoot.childNodes;
             } catch (e) {
+                addAttributeToken(self, ATTRIBUTE_ERRORMESSAGE, e.toString());
             }
 
             try {
@@ -546,21 +535,19 @@ class CustomElement extends HTMLElement {
             }
         }
 
+        // If the elements are not found inside the shadow root, initialize the HTML content of the element
         if (!(elements instanceof NodeList)) {
-            if (!(elements instanceof NodeList)) {
-                initHtmlContent.call(this);
-                elements = this.childNodes;
-            }
+            initHtmlContent.call(this);
+            elements = this.childNodes;
         }
 
+        // Initialize the custom elements inside the shadow root and the slotted elements
         initFromCallbackHost.call(this);
-
         try {
             nodeList = new Set([...elements, ...getSlottedElements.call(self)]);
         } catch (e) {
             nodeList = elements;
         }
-
         addObjectWithUpdaterToElement.call(
             self,
             nodeList,
@@ -568,26 +555,33 @@ class CustomElement extends HTMLElement {
             clone(self[internalSymbol].getRealSubject()["options"]),
         );
 
+        // Attach a mutation observer to observe changes to the attributes of the element
         attachAttributeChangeMutationObserver.call(this);
 
         return self;
     }
 
     /**
-     * Called every time the element is inserted into the DOM. Useful for running setup code, such as
-     * fetching resources or rendering. Generally, you should try to delay work until this time.
+     * This method is called every time the element is inserted into the DOM. It checks if the custom element
+     * has already been initialized and if not, calls the assembleMethod to initialize it.
      *
      * @return {void}
      * @since 1.7.0
+     * @see https://developer.mozilla.org/en-US/docs/Web/API/Element/connectedCallback
      */
     connectedCallback() {
-        let self = this;
+        const self = this;
+
+        // Check if the object has already been initialized
         if (!hasObjectLink(self, customElementUpdaterLinkSymbol)) {
+
+            // If not, call the assembleMethod to initialize the object
             self[assembleMethodSymbol]();
         }
-
     }
 
+
+
     /**
      * Called every time the element is removed from the DOM. Useful for running clean up code.
      *
@@ -725,31 +719,34 @@ function callControlCallback(callBackFunctionName, ...args) {
 }
 
 /**
- * This Function is called when the element is attached to the DOM.
- *
- * It looks for the attribute `data-monster-option-callback`. Is this attribute is not set, the default callback
- * `initCustomControlOptionsCallback` is called.
+ * Initializes the custom element based on the provided callback function.
  *
- * The callback is searched in this element and in the host element. If the callback is found, it is called with the
- * element as parameter.
- *
- * The `monster
+ * This function is called when the element is attached to the DOM. It checks if the
+ * `data-monster-option-callback` attribute is set, and if not, the default callback
+ * `initCustomControlCallback` is called. The callback function is searched for in this
+ * element and in the host element. If the callback is found, it is called with the element
+ * as a parameter.
  *
  * @this CustomElement
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry/define#providing_a_construction_callback
+ * @since 1.8.0
  */
 function initFromCallbackHost() {
     const self = this;
 
-    let callBackFunctionName = optionCallbackName // default callback
-    if (self.hasAttribute(ATTRIBUTE_OPTION_CALLBACK)) {
-        callBackFunctionName = self.getAttribute(ATTRIBUTE_OPTION_CALLBACK);
+    // Set the default callback function name
+    let callBackFunctionName = initControlCallbackName;
+
+    // If the `data-monster-option-callback` attribute is set, use its value as the callback function name
+    if (self.hasAttribute(ATTRIBUTE_INIT_CALLBACK)) {
+        callBackFunctionName = self.getAttribute(ATTRIBUTE_INIT_CALLBACK);
     }
 
+    // Call the callback function with the element as a parameter if it exists
     callControlCallback.call(self, callBackFunctionName);
-
-
 }
 
+
 /**
  * This method is called when the element is first created.
  *

package/source/types/version.mjs

@@ -142,7 +142,7 @@ function getMonsterVersion() {
     }
 
     /** don't touch, replaced by make with package.json version */
-    monsterVersion = new Version("3.47.0");
+    monsterVersion = new Version("3.49.0");
 
     return monsterVersion;
 }

package/test/cases/dom/customcontrol.mjs

@@ -22,6 +22,10 @@ describe('DOM', function () {
     before(function (done) {
         initJSDOM().then(() => {
 
+            import("element-internals-polyfill").then((m) => {
+                m.polyfill();
+            });
+
             // jsdom does not support ElementInternals
             jsdomFlag = navigator.userAgent.includes("jsdom");
 
@@ -72,8 +76,13 @@ describe('DOM', function () {
 
         describe('create', function () {
             it('should return custom-element object', function () {
-                let d = new TestComponent();
-                expect(typeof d).is.equal('object');
+                try {
+                    let d = new TestComponent();
+                } catch (e) {
+                    expect(e).to.be.not.null;
+                }
+
+                expect(typeof d).is.equal('undefined');
             });
         });
 
@@ -84,7 +93,7 @@ describe('DOM', function () {
                 document.getElementById('test1').appendChild(d);
                 expect(document.getElementsByTagName('monster-customcontrol').length).is.equal(1);
                 // no data-monster-objectlink="Symbol(monsterUpdater)" because it has nothing to update 
-                expect(document.getElementById('test1')).contain.html('<monster-customcontrol></monster-customcontrol>');
+                expect(document.getElementById('test1')).contain.html('<monster-customcontrol data-monster-error="Error: html is not set."></monster-customcontrol>')
             });
         });
 
@@ -129,11 +138,13 @@ describe('DOM', function () {
                 let d = document.createElement('monster-customcontrol');
                 form.appendChild(d);
 
-                if (jsdomFlag) {
-                    expect(() => d.form).to.throw(Error);
-                } else {
-                    expect(d.form).to.be.instanceof(HTMLFormElement)
-                }
+                expect(d.form).to.be.instanceof(HTMLFormElement)
+
+                // if (jsdomFlag) {
+                //     expect(() => d.form).to.throw(Error);
+                // } else {
+                //     expect(d.form).to.be.instanceof(HTMLFormElement)
+                // }
 
 
             });
@@ -160,13 +171,7 @@ describe('DOM', function () {
 
                 let d = document.createElement('monster-customcontrol');
                 form.appendChild(d);
-
-                if (jsdomFlag) {
-                    expect(() => d.setFormValue()).to.throw(Error);
-                } else {
-
-                }
-
+                
             });
 
             it('name getter', function () {
@@ -191,11 +196,6 @@ describe('DOM', function () {
 
                 let d = document.createElement('monster-customcontrol');
                 form.appendChild(d);
-                if (jsdomFlag) {
-                    expect(() => d.validity).to.throw(Error);
-                } else {
-
-                }
 
             });
 
@@ -204,11 +204,6 @@ describe('DOM', function () {
                 let d = document.createElement('monster-customcontrol');
                 form.appendChild(d);
 
-                if (jsdomFlag) {
-                    expect(() => d.validity).to.throw(Error);
-                } else {
-
-                }
 
             });
 
@@ -217,11 +212,6 @@ describe('DOM', function () {
                 let d = document.createElement('monster-customcontrol');
                 form.appendChild(d);
 
-                if (jsdomFlag) {
-                    expect(() => d.willValidate).to.throw(Error);
-                } else {
-
-                }
 
             });
             it('checkValidity()', function () {
@@ -229,11 +219,6 @@ describe('DOM', function () {
                 let d = document.createElement('monster-customcontrol');
                 form.appendChild(d);
 
-                if (jsdomFlag) {
-                    expect(() => d.checkValidity()).to.throw(Error);
-                } else {
-
-                }
 
             });
 
@@ -242,11 +227,6 @@ describe('DOM', function () {
                 let d = document.createElement('monster-customcontrol');
                 form.appendChild(d);
 
-                if (jsdomFlag) {
-                    expect(() => d.reportValidity()).to.throw(Error);
-                } else {
-
-                }
 
             });
 
@@ -255,11 +235,7 @@ describe('DOM', function () {
 
                 let d = document.createElement('monster-customcontrol');
                 form.appendChild(d);
-                if (jsdomFlag) {
-                    expect(() => d.setValidity()).to.throw(Error);
-                } else {
-                    expect(d.setValidity({'valueMissing': true}, "my message")).to.be.undefined;
-                }
+                expect(d.setValidity({'valueMissing': true}, "my message")).to.be.undefined;
 
             });
 

package/test/cases/dom/customelement-initfromscripthost.mjs

@@ -102,13 +102,13 @@ describe('DOM', function () {
 
             });
             
-            it('should found callback initCustomControlOptionsCallback', function () {
+            it('should found callback initCustomControlCallback', function () {
 
                 let mocks = document.getElementById('mocks');
                 mocks.innerHTML = `<div id="call-back-host"></div><div id="container"></div>`;
                 
                 const container = document.getElementById('call-back-host');
-                container.initCustomControlOptionsCallback = function (control) {
+                container.initCustomControlCallback = function (control) {
                     control.setOption('test', 1);
                 }
                 
@@ -120,14 +120,14 @@ describe('DOM', function () {
 
             });
             
-            it('should found callback initCustomControlOptionsCallback from self', function () {
+            it('should found callback initCustomControlCallback from self', function () {
 
                 let mocks = document.getElementById('mocks');
                 mocks.innerHTML = `<div id="call-back-host"></div><div id="container"></div>`;
 
                 let control = document.createElement(randomTagNumber);
                 expect(control.getOption('test')).is.eql(0);
-                control.initCustomControlOptionsCallback = function (control) {
+                control.initCustomControlCallback = function (control) {
                     control.setOption('test', 2);
                 }
                 

package/test/cases/dom/customelement.mjs

@@ -239,7 +239,8 @@ describe('DOM', function () {
                 document.getElementById('test1').appendChild(d);
                 expect(document.getElementsByTagName('monster-testclass').length).is.equal(1);
                 // no data-monster-objectlink="Symbol(monsterUpdater)" because it has nothing to update
-                expect(document.getElementById('test1')).contain.html('<monster-testclass></monster-testclass>');
+                // but data-monster-error="Error: html is not set."
+                expect(document.getElementById('test1')).contain.html('<monster-testclass data-monster-error="Error: html is not set."></monster-testclass>');
             });
         });
 

package/test/cases/monster.mjs

@@ -7,7 +7,7 @@ describe('Monster', function () {
         let monsterVersion
 
         /** don´t touch, replaced by make with package.json version */
-        monsterVersion = new Version("3.47.0")
+        monsterVersion = new Version("3.49.0")
 
         let m = getMonsterVersion();