@schukai/monster 3.80.2 → 3.80.3

package/source/data/pipe.mjs

@@ -32,11 +32,12 @@ const DELIMITER = "|";
  * With the Pipe, processing steps can be combined. Here, the value of an object is accessed via the pathfinder (path command).
  * the word is then converted to uppercase letters and a prefix Hello is added. the two backslash safe the space char.
  *
- * @externalExample  ../../example/data/pipe.mjs
+ * @example /examples/libraries/pipe/example-1/
+ *
  * @license AGPLv3
  * @since 1.5.0
  * @copyright schukai GmbH
- * @memberOf Monster.Data
+ * @summary The pipe class makes it possible to combine several processing steps.
  */
 class Pipe extends Base {
 	/**
@@ -56,7 +57,7 @@ class Pipe extends Base {
 	 * @param {string} name
 	 * @param {function} callback
 	 * @param {object} context
-	 * @returns {Transformer}
+	 * @return {Transformer}
 	 * @throws {TypeError} value is not a string
 	 * @throws {TypeError} value is not a function
 	 */
@@ -72,7 +73,7 @@ class Pipe extends Base {
 	 * run a pipe
 	 *
 	 * @param {*} value
-	 * @returns {*}
+	 * @return {*}
 	 */
 	run(value) {
 		return this.pipe.reduce((accumulator, transformer, currentIndex, array) => {

package/source/data/transformer.mjs

@@ -35,21 +35,21 @@ import { Pathfinder } from "./pathfinder.mjs";
 export { Transformer };
 
 /**
- * The transformer class is a swiss army knife for manipulating values. especially in combination with the pipe, processing chains can be built up.
+ * The transformer class is a swiss army knife for manipulating values.
  *
  * A simple example is the conversion of all characters to lowercase. for this purpose the command `tolower` must be used.
  *
- * ```
+ * ```js
  * let t = new Transformer('tolower').run('ABC'); // ↦ abc
  * ```
  *
- * @see {@link https://monsterjs.org/en/doc/#transformer|Monster Docs}
+ * @fragments /fragments/libraries/transformer
+ *
+ * @example /examples/libraries/transformer/simple
  *
- * @externalExample ../../example/data/transformer.mjs
- * @license AGPLv3
  * @since 1.5.0
  * @copyright schukai GmbH
- * @memberOf Monster.Data
+ * @summary The transformer class is a swiss army knife for manipulating values. especially in combination with the pipe, processing chains can be built up.
  */
 class Transformer extends Base {
 	/**
@@ -68,7 +68,7 @@ class Transformer extends Base {
 	 * @param {string} name
 	 * @param {function} callback
 	 * @param {object} context
-	 * @returns {Transformer}
+	 * @return {Transformer}
 	 * @throws {TypeError} value is not a string
 	 * @throws {TypeError} value is not a function
 	 */
@@ -91,7 +91,7 @@ class Transformer extends Base {
 	/**
 	 *
 	 * @param {*} value
-	 * @returns {*}
+	 * @return {*}
 	 * @throws {Error} unknown command
 	 * @throws {TypeError} unsupported type
 	 * @throws {Error} type not supported
@@ -104,7 +104,7 @@ class Transformer extends Base {
 /**
  *
  * @param {string} command
- * @returns {array}
+ * @return {array}
  * @private
  */
 function disassemble(command) {
@@ -149,7 +149,7 @@ function disassemble(command) {
  * tries to make a string out of value and if this succeeds to return it back
  *
  * @param {*} value
- * @returns {string}
+ * @return {string}
  * @private
  */
 function convertToString(value) {
@@ -164,7 +164,7 @@ function convertToString(value) {
 /**
  *
  * @param {*} value
- * @returns {*}
+ * @return {*}
  * @private
  * @throws {Error} unknown command
  * @throws {TypeError} unsupported type
@@ -835,6 +835,13 @@ function transform(value) {
 	}
 }
 
+/**
+ * converts special strings to their values
+ * @private
+ * @param input
+ * @param value
+ * @return {undefined|*|null|string}
+ */
 function convertSpecialStrings(input, value) {
 	switch (input) {
 		case "value":
@@ -850,6 +857,11 @@ function convertSpecialStrings(input, value) {
 	}
 }
 
+/**
+ * checks if a value is true or not
+ * @param value
+ * @return {boolean}
+ */
 function evaluateCondition(value) {
 	const lowerValue = typeof value === "string" ? value.toLowerCase() : value;
 

package/source/dom/assembler.mjs

@@ -53,7 +53,7 @@ class Assembler extends Base {
 	/**
 	 *
 	 * @param {string} prefix
-	 * @returns {Assembler}
+	 * @return {Assembler}
 	 * @throws {TypeError} value is not a string
 	 */
 	setAttributePrefix(prefix) {
@@ -64,7 +64,7 @@ class Assembler extends Base {
 
 	/**
 	 *
-	 * @returns {string}
+	 * @return {string}
 	 */
 	getAttributePrefix() {
 		return this.attributePrefix;

package/source/dom/attributes.mjs

@@ -65,7 +65,7 @@ function findClosestObjectLink(element) {
  * @param element
  * @param symbol
  * @param object
- * @returns {*}
+ * @return {*}
  */
 function addToObjectLink(element, symbol, object) {
 	validateInstance(element, HTMLElement);
@@ -89,7 +89,7 @@ function addToObjectLink(element, symbol, object) {
  * @memberOf Monster.DOM
  * @param {HTMLElement} element
  * @param {Symbol} symbol
- * @returns {*}
+ * @return {*}
  */
 function removeObjectLink(element, symbol) {
 	validateInstance(element, HTMLElement);

package/source/dom/customcontrol.mjs

@@ -83,7 +83,7 @@ class CustomControl extends CustomElement {
 
 	/**
 	 * This method is called by the `instanceof` operator.
-	 * @returns {symbol}
+	 * @return {symbol}
 	 * @since 2.1.0
 	 */
 	static get [instanceSymbol]() {

package/source/dom/customelement.mjs

@@ -119,49 +119,6 @@ const updateCloneDataSymbol = Symbol("@schukai/monster/dom/@@updateCloneData");
  */
 const scriptHostElementSymbol = Symbol("scriptHostElement");
 
-/**
- * HTMLElement
- * @external HTMLElement
- * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement
- *
- * @startuml customelement-sequencediagram.png
- * skinparam monochrome true
- * skinparam shadowing false
- *
- * autonumber
- *
- * Script -> DOM: element = document.createElement('my-element')
- * DOM -> CustomElement: constructor()
- * CustomElement -> CustomElement: [initMethodSymbol]()
- *
- * CustomElement --> DOM: Element
- * DOM --> Script : element
- *
- *
- * Script -> DOM: document.querySelector('body').append(element)
- *
- * DOM -> CustomElement : connectedCallback()
- *
- * note right CustomElement: is only called at\nthe first connection
- * CustomElement -> CustomElement : [assembleMethodSymbol]()
- *
- * ... ...
- *
- * autonumber
- *
- * Script -> DOM: document.querySelector('monster-confirm-button').parentNode.removeChild(element)
- * DOM -> CustomElement: disconnectedCallback()
- *
- *
- * @enduml
- *
- * @startuml customelement-class.png
- * skinparam monochrome true
- * skinparam shadowing false
- * HTMLElement <|-- CustomElement
- * @enduml
- */
-
 /**
  * The `CustomElement` class provides a way to define a new HTML element using the power of Custom Elements.
  *
@@ -237,12 +194,12 @@ const scriptHostElementSymbol = Symbol("scriptHostElement");
  */
 class CustomElement extends HTMLElement {
 	/**
-	 * A new object is created. First the `initOptions` method is called. Here the
+	 * 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.
+	 * @throws {Error} the option attribute does not contain a valid JSON definition.
 	 */
 	constructor() {
 		super();
@@ -258,7 +215,8 @@ class CustomElement extends HTMLElement {
 
 	/**
 	 * This method is called by the `instanceof` operator.
-	 * @returns {symbol}
+	 *
+	 * @return {symbol}
 	 * @since 2.1.0
 	 */
 	static get [instanceSymbol]() {
@@ -281,7 +239,7 @@ class CustomElement extends HTMLElement {
 	 *
 	 * @param attribute
 	 * @param callback
-	 * @returns {Monster.DOM.CustomElement}
+	 * @return {Monster.DOM.CustomElement}
 	 */
 	addAttributeObserver(attribute, callback) {
 		validateFunction(callback);
@@ -292,7 +250,7 @@ class CustomElement extends HTMLElement {
 	/**
 	 *
 	 * @param attribute
-	 * @returns {Monster.DOM.CustomElement}
+	 * @return {Monster.DOM.CustomElement}
 	 */
 	removeAttributeObserver(attribute) {
 		delete this[attributeObserverSymbol][attribute];
@@ -354,7 +312,7 @@ class CustomElement extends HTMLElement {
 	 *
 	 * Before you can use this method, you must have loaded the translations.
 	 *
-	 * @returns {Monster.DOM.CustomElement}
+	 * @return {Monster.DOM.CustomElement}
 	 * @throws {Error}  Cannot find an element with translations. Add a translation object to the document.
 	 */
 	updateI18n() {
@@ -433,10 +391,12 @@ class CustomElement extends HTMLElement {
 	 * Example usage:
 	 *
 	 * ```js
-	 * static getCSSStyleSheet() {
-	 *     const sheet = new CSSStyleSheet();
-	 *     sheet.replaceSync("p { color: red; }");
-	 *     return sheet;
+	 * class MyElement extends CustomElement {
+	 *   static getCSSStyleSheet() {
+	 *       const sheet = new CSSStyleSheet();
+	 *       sheet.replaceSync("p { color: red; }");
+	 *       return sheet;
+	 *   }
 	 * }
 	 * ```
 	 *
@@ -462,7 +422,7 @@ class CustomElement extends HTMLElement {
 	 * attach a new observer
 	 *
 	 * @param {Observer} observer
-	 * @returns {CustomElement}
+	 * @return {CustomElement}
 	 */
 	attachObserver(observer) {
 		this[internalSymbol].attachObserver(observer);
@@ -473,7 +433,7 @@ class CustomElement extends HTMLElement {
 	 * detach a observer
 	 *
 	 * @param {Observer} observer
-	 * @returns {CustomElement}
+	 * @return {CustomElement}
 	 */
 	detachObserver(observer) {
 		this[internalSymbol].detachObserver(observer);
@@ -482,7 +442,7 @@ class CustomElement extends HTMLElement {
 
 	/**
 	 * @param {Observer} observer
-	 * @returns {ProxyObserver}
+	 * @return {ProxyObserver}
 	 */
 	containsObserver(observer) {
 		return this[internalSymbol].containsObserver(observer);
@@ -556,13 +516,18 @@ class CustomElement extends HTMLElement {
 	 * This method is called once when the object is equipped with update for the dynamic change of the dom.
 	 * The functions returned here can be used as pipe functions in the template.
 	 *
-	 * In the example, the function `my-transformer` is defined. In the template you can use it as follows:
+	 * In the example, the function `my-transformer` is defined. In the template, you can use it as follows:
 	 *
 	 * ```html
-	 * <my-element data-monster-option-transformer="path:my-value | call:my-transformer"></my-element>
+	 * <my-element
+	 *   data-monster-option-transformer="path:my-value | call:my-transformer">
+	 * </my-element>
 	 * ```
 	 *
-	 * @example
+	 * The function `my-transformer` is called with the value of `my-value` as a parameter.
+	 *
+	 * ```js
+	 * class MyElement extends CustomElement {
 	 * [updaterTransformerMethodsSymbol]() {
 	 *    return {
 	 *       "my-transformer": (value) => {
@@ -577,6 +542,8 @@ class CustomElement extends HTMLElement {
 	 *    }
 	 *    };
 	 *  };
+	 *  }
+	 * ```
 	 *
 	 * @return {object}
 	 * @since 2.43.0
@@ -587,11 +554,13 @@ class CustomElement extends HTMLElement {
 
 	/**
 	 * 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.
+	 *
+	 * <ol>
+	 * <li>Extracts the options from the attributes and the script tag of the element and sets them.</li>
+	 * <li>Initializes the shadow root and its CSS stylesheet (if specified).</li>
+	 * <li>Initializes the HTML content of the element.</li>
+	 * <li>Initializes the custom elements inside the shadow root and the slotted elements.</li>
+	 * <li>Attaches a mutation observer to observe changes to the attributes of the element.</li>
 	 *
 	 * @return {CustomElement} - The updated custom element.
 	 * @since 1.8.0
@@ -672,7 +641,7 @@ class CustomElement extends HTMLElement {
 	 * You know what you are doing? This function is only for advanced users.
 	 * The result is a clone of the internal data.
 	 *
-	 * @returns {*}
+	 * @return {*}
 	 */
 	getInternalUpdateCloneData() {
 		return clone(this[updateCloneDataSymbol]);
@@ -764,7 +733,7 @@ class CustomElement extends HTMLElement {
 	 *
 	 * @param {string} name
 	 * @param {*} args
-	 * @returns {*}
+	 * @return {*}
 	 */
 	callCallback(name, args) {
 		return callControlCallback.call(this, name, ...args);
@@ -1066,7 +1035,7 @@ function getOptionsFromAttributes() {
  *
  * @private
  * @param {string} data The JSON data to be parsed.
- * @returns {Object} The parsed object.
+ * @return {Object} The parsed object.
  * @throws {error} Throws an error if the JSON data is not valid.
  */
 function parseOptionsJSON(data) {

package/source/dom/dimension.mjs

@@ -21,7 +21,7 @@ export { convertToPixels, getDeviceDPI };
  * Stores the DPI of the device.
  *
  * @private
- * @returns {number}
+ * @return {number}
  * @since 3.34.0
  * @type {number|function}
  */
@@ -40,7 +40,7 @@ let CURRENT_DEVICE_DPI = function () {
  *
  * @since 3.34.0
  * @memberOf Monster.DOM
- * @returns {number}
+ * @return {number}
  */
 function getDeviceDPI() {
 	// only call the function once
@@ -72,7 +72,7 @@ function getDeviceDPI() {
  * @param {string} value
  * @param {HTMLElement} [parentElement=document.documentElement]
  * @param {HTMLElement} [fontSizeElement=document.documentElement]
- * @returns {number}
+ * @return {number}
  * @license AGPLv3
  * @since 3.34.0
  * @copyright schukai GmbH

package/source/dom/focusmanager.mjs

@@ -63,7 +63,7 @@ class FocusManager extends BaseWithOptions {
 
 	/**
 	 * This method is called by the `instanceof` operator.
-	 * @returns {symbol}
+	 * @return {symbol}
 	 * @since 2.1.0
 	 */
 	static get [instanceSymbol]() {

package/source/dom/locale.mjs

@@ -64,7 +64,7 @@ function getLocaleOfDocument() {
 
 /**
  * @private
- * @returns {string|undefined|*}
+ * @return {string|undefined|*}
  * @see https://developer.mozilla.org/en-US/docs/Web/API/Navigator/language
  * @see https://developer.mozilla.org/en-US/docs/Web/API/Navigator/languages
  */

package/source/dom/resource/data.mjs

@@ -85,7 +85,7 @@ class Data extends Resource {
 
 	/**
 	 * This method is called by the `instanceof` operator.
-	 * @returns {symbol}
+	 * @return {symbol}
 	 * @since 2.1.0
 	 */
 	static get [instanceSymbol]() {

package/source/dom/resource/link/stylesheet.mjs

@@ -39,7 +39,7 @@ class Stylesheet extends Link {
 
 	/**
 	 * This method is called by the `instanceof` operator.
-	 * @returns {symbol}
+	 * @return {symbol}
 	 * @since 2.1.0
 	 */
 	static get [instanceSymbol]() {

package/source/dom/resource/link.mjs

@@ -77,7 +77,7 @@ class Link extends Resource {
 
 	/**
 	 * This method is called by the `instanceof` operator.
-	 * @returns {symbol}
+	 * @return {symbol}
 	 * @since 2.1.0
 	 */
 	static get [instanceSymbol]() {

package/source/dom/resource/script.mjs

@@ -61,7 +61,7 @@ class Script extends Resource {
 
 	/**
 	 * This method is called by the `instanceof` operator.
-	 * @returns {symbol}
+	 * @return {symbol}
 	 * @since 2.1.0
 	 */
 	static get [instanceSymbol]() {

package/source/dom/template.mjs

@@ -48,7 +48,7 @@ class Template extends Base {
 
 	/**
 	 * This method is called by the `instanceof` operator.
-	 * @returns {symbol}
+	 * @return {symbol}
 	 * @since 2.1.0
 	 */
 	static get [instanceSymbol]() {
@@ -57,7 +57,7 @@ class Template extends Base {
 
 	/**
 	 *
-	 * @returns {HTMLTemplateElement}
+	 * @return {HTMLTemplateElement}
 	 */
 	getTemplateElement() {
 		return this.template;

package/source/dom/theme.mjs

@@ -43,7 +43,7 @@ class Theme extends Base {
 
 	/**
 	 * This method is called by the `instanceof` operator.
-	 * @returns {symbol}
+	 * @return {symbol}
 	 * @since 2.1.0
 	 */
 	static get [instanceSymbol]() {
@@ -52,7 +52,7 @@ class Theme extends Base {
 
 	/**
 	 *
-	 * @returns {string}
+	 * @return {string}
 	 */
 	getName() {
 		return this.name;

package/source/dom/updater.mjs

@@ -54,11 +54,11 @@ export { Updater, addObjectWithUpdaterToElement };
  * to other values as well, you have to insert the attribute `data-monster-select-this`. This should be
  * done with care, as it can reduce performance.
  *
- * @externalExample ../../example/dom/updater.mjs
+ * @example /examples/libraries/dom/updater/simple/ Simple example
+ *
  * @license AGPLv3
  * @since 1.8.0
  * @copyright schukai GmbH
- * @memberOf Monster.DOM
  * @throws {Error} the value is not iterable
  * @throws {Error} pipes are not allowed when cloning a node.
  * @throws {Error} no template was found with the specified key.
@@ -149,7 +149,7 @@ class Updater extends Base {
 	/**
 	 * With this method, the eventlisteners are hooked in and the magic begins.
 	 *
-	 * ```
+	 * ```js
 	 * updater.run().then(() => {
 	 *   updater.enableEventProcessing();
 	 * });
@@ -198,7 +198,7 @@ class Updater extends Base {
 	 * The run method must be called for the update to start working.
 	 * The method ensures that changes are detected.
 	 *
-	 * ```
+	 * ```js
 	 * updater.run().then(() => {
 	 *   updater.enableEventProcessing();
 	 * });
@@ -244,7 +244,7 @@ class Updater extends Base {
 	 *
 	 * @param {string} name
 	 * @param {function} callback
-	 * @returns {Transformer}
+	 * @return {Transformer}
 	 * @throws {TypeError} value is not a string
 	 * @throws {TypeError} value is not a function
 	 */
@@ -317,7 +317,6 @@ function getControlEventHandler() {
  * @throws {Error} the bind argument must start as a value with a path
  * @param {HTMLElement} element
  * @return void
- * @memberOf Monster.DOM
  * @private
  */
 function retrieveAndSetValue(element) {

package/source/dom/util/extract-keys.mjs

@@ -22,7 +22,7 @@ export { extractKeys };
  * @param {string} keyPrefix
  * @param {string} keySeparator
  * @param {string} valueSeparator
- * @returns {Map<any, any>}
+ * @return {Map<any, any>}
  */
 function extractKeys(
 	obj,

package/source/dom/util/init-options-from-attributes.mjs

@@ -54,7 +54,7 @@ export { initOptionsFromAttributes };
  * @param {Object} options - The options object to be initialized.
  * @param {Object} mapping - A mapping between the attribute value and the property value.
  * @param {string} prefix - The prefix of the attributes to be considered.
- * @returns {Object} - The initialized options object.
+ * @return {Object} - The initialized options object.
  * @this HTMLElement - The context of the DOM element.
  */
 function initOptionsFromAttributes(

package/source/dom/util/set-option-from-attribute.mjs

@@ -46,7 +46,7 @@ export { setOptionFromAttribute };
  * @param {Object} options - The options object to be initialized.
  * @param {Object} mapping - A mapping between the attribute value and the property value.
  * @param {string} prefix - The prefix of the attributes to be considered.
- * @returns {Object} - The initialized options object.
+ * @return {Object} - The initialized options object.
  * @this HTMLElement - The context of the DOM element.
  */
 function setOptionFromAttribute(

package/source/dom/util.mjs

@@ -55,7 +55,7 @@ export {
  * }
  * ```
  *
- * @returns {object}
+ * @return {object}
  * @license AGPLv3
  * @since 1.6.0
  * @copyright schukai GmbH
@@ -103,7 +103,7 @@ function getDocument() {
  * }
  * ```
  *
- * @returns {object}
+ * @return {object}
  * @license AGPLv3
  * @since 1.6.0
  * @copyright schukai GmbH
@@ -149,7 +149,7 @@ function getWindow() {
  * }
  * ```
  *
- * @returns {DocumentFragment}
+ * @return {DocumentFragment}
  * @license AGPLv3
  * @since 1.6.0
  * @copyright schukai GmbH
@@ -173,7 +173,7 @@ function getDocumentFragmentFromString(html) {
  *
  * @param {HTMLElement|ShadowRoot} element - The starting element or shadow root to search from.
  * @param {string} targetId - The ID of the target element to find.
- * @returns {HTMLElement|null} - The ancestor element with the specified ID, or null if not found.
+ * @return {HTMLElement|null} - The ancestor element with the specified ID, or null if not found.
  * @memberOf Monster.DOM
  * @since 3.29.0
  * @license AGPLv3
@@ -222,7 +222,7 @@ function findElementWithIdUpwards(element, targetId) {
  *
  * @param {HTMLElement|ShadowRoot} element - The starting element or shadow root to search from.
  * @param {string} selector - The selector of the target element to find.
- * @returns {HTMLElement|null} - The ancestor element with the specified selector, or null if not found.
+ * @return {HTMLElement|null} - The ancestor element with the specified selector, or null if not found.
  * @memberOf Monster.DOM
  * @since 3.55.0
  */
@@ -259,7 +259,7 @@ function findElementWithSelectorUpwards(element, selector) {
 /**
  * @private
  * @param {HTMLElement} element
- * @returns {HTMLElement|null}
+ * @return {HTMLElement|null}
  */
 function traverseShadowRoots(element) {
 	let currentRoot = element.shadowRoot;
@@ -296,7 +296,7 @@ function traverseShadowRoots(element) {
  * Recursively searches upwards from a given element to find an ancestor element
  *
  * @param {HTMLElement} element
- * @returns {*}
+ * @return {*}
  * @throws {Error} Invalid argument. Expected an HTMLElement.
  * @memberOf Monster.DOM
  * @since 3.36.0
@@ -318,10 +318,10 @@ function getContainingDocument(element) {
 /**
  * Returns a list of all registered custom elements in the current document.
  *
- * @returns {string[]}
+ * @return {string[]}
  * @since 4.0.0
  * @memberOf Monster.DOM
- * @returns {string[]}
+ * @return {string[]}
  */
 function getRegisteredCustomElements() {
 	const customElementTags = Array.from(document.querySelectorAll("*"))

package/source/i18n/formatter.mjs

@@ -51,7 +51,7 @@ class Formatter extends TextFormatter {
 
 	/**
 	 * This method is called by the `instanceof` operator.
-	 * @returns {symbol}
+	 * @return {symbol}
 	 * @since 3.27.0
 	 */
 	static get [instanceSymbol]() {