@schukai/monster 3.80.2 → 3.80.4

package/source/data/datasource/server/restapi/writeerror.mjs

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

package/source/data/datasource/server/restapi.mjs

@@ -56,7 +56,7 @@ class RestAPI extends Server {
 
 	/**
 	 * This method is called by the `instanceof` operator.
-	 * @returns {symbol}
+	 * @return {symbol}
 	 * @since 2.1.0
 	 */
 	static get [instanceSymbol]() {
@@ -189,7 +189,7 @@ class RestAPI extends Server {
  * @param init
  * @param key
  * @param callback
- * @returns {Promise<string>}
+ * @return {Promise<string>}
  */
 function fetchData(init, key, callback) {
 	let response;

package/source/data/datasource/server/webconnect.mjs

@@ -67,14 +67,14 @@ class WebConnect extends Server {
 
 	/**
 	 *
-	 * @returns {Promise}
+	 * @return {Promise}
 	 */
 	connect() {
 		return this[webConnectSymbol].connect();
 	}
 
 	/**
-	 * @returns {boolean}
+	 * @return {boolean}
 	 */
 	isConnected() {
 		return this[webConnectSymbol].isConnected();
@@ -82,7 +82,7 @@ class WebConnect extends Server {
 
 	/**
 	 * This method is called by the `instanceof` operator.
-	 * @returns {symbol}
+	 * @return {symbol}
 	 */
 	static get [instanceSymbol]() {
 		return Symbol.for("@schukai/monster/data/datasource/server/webconnect");
@@ -142,7 +142,7 @@ class WebConnect extends Server {
 	/**
 	 * This method closes the connection.
 	 *
-	 * @returns {Promise}
+	 * @return {Promise}
 	 */
 	close() {
 		return this[webConnectSymbol].close();

package/source/data/datasource/server.mjs

@@ -39,7 +39,7 @@ const serverVersionSymbol = Symbol("serverVersion");
 class Server extends Datasource {
 	/**
 	 * This method is called by the `instanceof` operator.
-	 * @returns {symbol}
+	 * @return {symbol}
 	 */
 	static get [instanceSymbol]() {
 		return Symbol.for("@schukai/monster/data/datasource/server");
@@ -51,7 +51,7 @@ class Server extends Datasource {
 	 *
 	 * @private
 	 * @param {Object} payload
-	 * @returns {Object}
+	 * @return {Object}
 	 */
 	transformServerPayload(payload) {
 		payload = doTransform.call(this, "read", payload);
@@ -70,7 +70,7 @@ class Server extends Datasource {
 	 *
 	 * @private
 	 * @param {Object} payload
-	 * @returns {Object}
+	 * @return {Object}
 	 */
 	prepareServerPayload(payload) {
 		payload = doTransform.call(this, "write", payload);
@@ -92,7 +92,7 @@ class Server extends Datasource {
 /**
  *
  * @param obj
- * @returns {*}
+ * @return {*}
  */
 function doDiff(obj) {
 	if (
@@ -122,7 +122,7 @@ function doDiff(obj) {
  * @private
  * @param {string} type
  * @param {Object} obj
- * @returns {Object}
+ * @return {Object}
  */
 function doTransform(type, obj) {
 	const transformation = this.getOption(`${type}.mapping.transformer`);

package/source/data/datasource/storage/localstorage.mjs

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

package/source/data/datasource/storage/sessionstorage.mjs

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

package/source/data/datasource/storage.mjs

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

package/source/data/datasource.mjs

@@ -52,7 +52,6 @@ const internalDataSymbol = Symbol.for(
  * @license AGPLv3
  * @since 1.22.0
  * @copyright schukai GmbH
- * @memberOf Monster.Data
  * @summary The datasource class encapsulates the access to data objects.
  */
 class Datasource extends Base {
@@ -74,7 +73,7 @@ class Datasource extends Base {
 	 * attach a new observer
 	 *
 	 * @param {Observer} observer
-	 * @returns {Datasource}
+	 * @return {Datasource}
 	 */
 	attachObserver(observer) {
 		this[internalDataSymbol].attachObserver(observer);
@@ -85,7 +84,7 @@ class Datasource extends Base {
 	 * detach a observer
 	 *
 	 * @param {Observer} observer
-	 * @returns {Datasource}
+	 * @return {Datasource}
 	 */
 	detachObserver(observer) {
 		this[internalDataSymbol].detachObserver(observer);
@@ -94,7 +93,7 @@ class Datasource extends Base {
 
 	/**
 	 * @param {Observer} observer
-	 * @returns {boolean}
+	 * @return {boolean}
 	 */
 	containsObserver(observer) {
 		return this[internalDataSymbol].containsObserver(observer);
@@ -204,7 +203,7 @@ class Datasource extends Base {
 
 	/**
 	 * This method is called by the `instanceof` operator.
-	 * @returns {symbol}
+	 * @return {symbol}
 	 * @since 2.1.0
 	 */
 	static get [instanceSymbol]() {

package/source/data/pathfinder.mjs

@@ -81,12 +81,13 @@ const WILDCARD = "*";
  * new Pathfinder(obj).setVia('a.b.0.c', true); // ↦ {a:{b:[{c:true}]}}
  * ```
  *
- * @externalExample ../../example/data/pathfinder-1.mjs
- * @externalExample ../../example/data/pathfinder-2.mjs
+ * @example /examples/libraries/pathfinder/example-1/ Example 1
+ * @example /examples/libraries/pathfinder/example-2/ Example 2
+ *
  * @license AGPLv3
  * @since 1.4.0
  * @copyright schukai GmbH
- * @memberOf Monster.Data
+ * @summary Pathfinder is a class to find a path to an object.
  */
 class Pathfinder extends Base {
 	/**
@@ -124,7 +125,7 @@ class Pathfinder extends Base {
 	 *
 	 * @param {string|array} path
 	 * @since 1.4.0
-	 * @returns {*}
+	 * @return {*}
 	 * @throws {TypeError} unsupported type
 	 * @throws {Error} the journey is not at its end
 	 * @throws {TypeError} value is not a string
@@ -139,7 +140,7 @@ class Pathfinder extends Base {
 	 *
 	 * @param {string|array} path
 	 * @param {*} value
-	 * @returns {Pathfinder}
+	 * @return {Pathfinder}
 	 * @since 1.4.0
 	 * @throws {TypeError} unsupported type
 	 * @throws {TypeError} value is not a string
@@ -155,7 +156,7 @@ class Pathfinder extends Base {
 	 * Delete Via Path
 	 *
 	 * @param {string|array} path
-	 * @returns {Pathfinder}
+	 * @return {Pathfinder}
 	 * @since 1.6.0
 	 * @throws {TypeError} unsupported type
 	 * @throws {TypeError} value is not a string
@@ -226,7 +227,7 @@ function iterate(subject, path, check) {
  * @param subject
  * @param path
  * @param check
- * @returns {V|*|Map}
+ * @return {V|*|Map}
  * @throws {TypeError} unsupported type
  * @throws {Error} the journey is not at its end
  * @throws {Error} unsupported action for this data type
@@ -306,7 +307,7 @@ function getValueViaPath(subject, path, check) {
  * @param {object} subject
  * @param {string|array} path
  * @param {*} value
- * @returns {void}
+ * @return {void}
  * @throws {TypeError} unsupported type
  * @throws {TypeError} unsupported type
  * @throws {Error} the journey is not at its end
@@ -405,7 +406,7 @@ function assignProperty(object, key, value) {
  *
  * @param {object} subject
  * @param {string} path
- * @returns {void}
+ * @return {void}
  * @throws {TypeError} unsupported type
  * @throws {TypeError} unsupported type
  * @throws {Error} the journey is not at its end

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]() {