@schukai/monster 3.35.4 → 3.37.0

package/package.json

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

package/source/dom/util.mjs

@@ -8,7 +8,7 @@
 import { getGlobal } from "../types/global.mjs";
 import { validateString } from "../types/validate.mjs";
 
-export { getDocument, getWindow, getDocumentFragmentFromString, findElementWithIdUpwards };
+export { getDocument, getWindow, getDocumentFragmentFromString, findElementWithIdUpwards,getContainingDocument };
 
 /**
  * This method fetches the document object
@@ -199,3 +199,48 @@ function findElementWithIdUpwards(element, targetId) {
     // Otherwise, search the current element's parent
     return findElementWithIdUpwards(element.parentElement, targetId);
 }
+
+/**
+ * @private
+ * @param {HTMLElement} element
+ * @returns {HTMLElement|null}
+ */
+function traverseShadowRoots(element) {
+    let currentRoot = element.shadowRoot;
+    let currentParent = element.parentNode;
+
+    while (currentParent && currentParent.nodeType !== Node.DOCUMENT_NODE && currentParent.nodeType !== Node.DOCUMENT_FRAGMENT_NODE) {
+        if (currentRoot && currentRoot.parentNode) {
+            currentParent = currentRoot.parentNode;
+            currentRoot = currentParent.shadowRoot;
+        } else if (currentParent.parentNode) {
+            currentParent = currentParent.parentNode;
+            currentRoot = null;
+        } else if (currentRoot && currentRoot.host && currentRoot.host.nodeType === Node.DOCUMENT_NODE) {
+            currentParent = currentRoot.host;
+            currentRoot = null;
+        } else {
+            currentParent = null;
+            currentRoot = null;
+        }
+    }
+
+    return currentParent;
+}
+
+/**
+ * Recursively searches upwards from a given element to find an ancestor element
+ *
+ * @param {HTMLElement} element
+ * @returns {*}
+ * @throws {Error} Invalid argument. Expected an HTMLElement.
+ * @memberOf Monster.DOM
+ * @since 3.36.0
+ */
+function getContainingDocument(element) {
+    if (!element || !(element instanceof HTMLElement || element instanceof element.ownerDocument.defaultView.HTMLElement)) {
+        throw new Error('Invalid argument. Expected an HTMLElement.');
+    }
+
+    return traverseShadowRoots(element) || null;
+}

package/source/text/bracketed-key-value-hash.mjs

@@ -0,0 +1,245 @@
+/**
+ * Copyright schukai GmbH and contributors 2023. All Rights Reserved.
+ * Node module: @schukai/monster
+ * This file is licensed under the AGPLv3 License.
+ * License text available at https://www.gnu.org/licenses/agpl-3.0.en.html
+ */
+
+export {parseBracketedKeyValueHash, createBracketedKeyValueHash}
+
+/**
+ * Parses a string containing bracketed key-value pairs and returns an object representing the parsed result.
+ *
+ * - The string starts with a hash symbol #.
+ * - After the hash symbol, there are one or more selector strings, separated by a semicolon ;.
+ * - Each selector string has the format selectorName(key1=value1,key2=value2,...).
+ * - The selector name is a string of one or more alphanumeric characters.
+ * - The key-value pairs are separated by commas , and are of the form key=value.
+ * - The key is a string of one or more alphanumeric characters.
+ * - The value can be an empty string or a string of one or more characters.
+ * - If the value contains commas, it must be enclosed in double quotes ".
+ * - The entire key-value pair must be URL-encoded.
+ * - The closing parenthesis ) for each selector must be present, even if there are no key-value pairs.
+ *
+ * @example
+ *
+ * ```javascript
+ * // Example 1:
+ * const hashString = '#selector1(key1=value1,key2=value2);selector2(key3=value3)';
+ * const result = parseBracketedKeyValueHash(hashString);
+ * // result => { selector1: { key1: "value1", key2: "value2" }, selector2: { key3: "value3" } }
+ * ```
+ *
+ * @example
+ *
+ * ```javascript
+ * // Example 2:
+ * const hashString = '#selector1(key1=value1,key2=value2);selector2(';
+ * const result = parseBracketedKeyValueHash(hashString);
+ * // result => {}
+ * ```
+ *
+ * @since 3.37.0
+ * @param {string} hashString - The string to parse, containing bracketed key-value pairs.
+ * @returns {Object} - An object representing the parsed result, with keys representing the selectors and values representing the key-value pairs associated with each selector.
+ *                    - Returns an empty object if there was an error during parsing. */
+function parseBracketedKeyValueHash(hashString) {
+    const selectors = {};
+    //const selectorStack = [];
+    //const keyValueStack = [];
+
+    const trimmedHashString = hashString.trim();
+    const cleanedHashString = trimmedHashString.charAt(0) === '#' ? trimmedHashString.slice(1) : trimmedHashString;
+
+
+    //const selectors = (keyValueStack.length > 0) ? result[selectorStack[selectorStack.length - 1]] : result;
+    let currentSelector = "";
+
+    function addToResult(key, value) {
+        if (currentSelector && key) {
+            if (!selectors[currentSelector]) {
+                selectors[currentSelector] = {};
+            }
+
+            selectors[currentSelector][key] = value;
+        }
+    }
+
+    let currentKey = '';
+    let currentValue = '';
+    let inKey = true;
+    let inValue = false;
+    let inQuotedValue = false;
+    let inSelector = true;
+    let escaped = false;
+    let quotedValueStartChar = '';
+
+    for (let i = 0; i < cleanedHashString.length; i++) {
+        const c = cleanedHashString[i];
+        const nextChar = cleanedHashString?.[i + 1];
+
+        if (c === '\\' && !escaped) {
+            escaped = true;
+            continue;
+        }
+
+        if (escaped) {
+            if (inSelector) {
+                currentSelector += c;
+            } else if (inKey) {
+                currentKey += c;
+            } else if (inValue) {
+                currentValue += c;
+            }
+            escaped = false;
+            continue;
+        }
+
+        if (inQuotedValue && quotedValueStartChar !== c) {
+
+            if (inSelector) {
+                currentSelector += c;
+            } else if (inKey) {
+                currentKey += c;
+            } else if (inValue) {
+                currentValue += c;
+            }
+
+            continue;
+        }
+
+        if (c === ';' && inSelector) {
+            inSelector = true;
+            currentSelector = "";
+            continue;
+        }
+
+
+        if (inSelector === true && c !== '(') {
+            currentSelector += c;
+            continue;
+        }
+
+        if (c === '(' && inSelector) {
+            inSelector = false;
+            inKey = true;
+
+            currentKey = "";
+            continue;
+        }
+
+        if (inKey === true && c !== '=') {
+            currentKey += c;
+            continue;
+        }
+
+        if (c === '=' && inKey) {
+
+            inKey = false;
+            inValue = true;
+
+            if (nextChar === '"' || nextChar === "'") {
+                inQuotedValue = true;
+                quotedValueStartChar = nextChar;
+                i++;
+                continue;
+            }
+
+            currentValue = "";
+            continue;
+        }
+
+        if (inValue === true) {
+            if (inQuotedValue) {
+                if (c === quotedValueStartChar) {
+                    inQuotedValue = false;
+                    continue;
+                }
+
+                currentValue += c;
+                continue;
+            }
+
+            if (c === ',') {
+                inValue = false;
+                inKey = true;
+                const decodedCurrentValue = decodeURIComponent(currentValue);
+                addToResult(currentKey, decodedCurrentValue);
+                currentKey = "";
+                currentValue = "";
+                continue;
+            }
+
+            if (c === ')') {
+                inValue = false;
+                //inKey = true;
+                inSelector = true;
+
+                const decodedCurrentValue = decodeURIComponent(currentValue);
+                addToResult(currentKey, decodedCurrentValue);
+                currentKey = "";
+                currentValue = "";
+                currentSelector = "";
+                continue;
+            }
+
+            currentValue += c;
+
+            continue;
+        }
+    }
+
+
+    if (inSelector) {
+        return selectors;
+    }
+
+
+    return {};
+
+}
+
+/**
+ * Creates a hash selector string from an object.
+ *
+ * @param {Object} object - The object containing selectors and key-value pairs.
+ * @param {boolean} addHashPrefix - Whether to add the hash prefix # to the beginning of the string.
+ * @returns {string} The hash selector string.
+ * @since 3.37.0
+ */
+function createBracketedKeyValueHash(object, addHashPrefix = true) {
+    
+    if (!object) {
+        return addHashPrefix ? '#' : '';
+    }
+    
+    let hashString = '';
+
+    function encodeKeyValue(key, value) {
+        return encodeURIComponent(key) + '=' + encodeURIComponent(value);
+    }
+
+    for (const selector in object) {
+        if (object.hasOwnProperty(selector)) {
+            const keyValuePairs = object[selector];
+            let selectorString = selector;
+            let keyValueString = '';
+
+            for (const key in keyValuePairs) {
+                if (keyValuePairs.hasOwnProperty(key)) {
+                    const value = keyValuePairs[key];
+                    keyValueString += keyValueString.length === 0 ? '' : ',';
+                    keyValueString += encodeKeyValue(key, value);
+                }
+            }
+
+            if (keyValueString.length > 0) {
+                selectorString += '(' + keyValueString + ')';
+                hashString += hashString.length === 0 ? '' : ';';
+                hashString += selectorString;
+            }
+        }
+    }
+
+    return addHashPrefix ? '#' + hashString : hashString;
+}

package/source/text/generate-range-comparison-expression.mjs

@@ -0,0 +1,93 @@
+/**
+ * Copyright schukai GmbH and contributors 2023. All Rights Reserved.
+ * Node module: @schukai/monster
+ * This file is licensed under the AGPLv3 License.
+ * License text available at https://www.gnu.org/licenses/agpl-3.0.en.html
+ */
+
+export { generateRangeComparisonExpression };
+
+/**
+ * The `generateRangeComparisonExpression()` function is function that generates a string representation
+ * of a comparison expression based on a range of values. It takes three arguments:
+ *
+ * - expression (required): a string representation of a range of values in the format of start1-end1,start2-end2,value3....
+ * - valueName (required): a string representing the name of the value that is being compared to the range of values.
+ * - options (optional): an object containing additional options to customize the comparison expression.
+ *
+ * The generateRangeComparisonExpression() function returns a string representation of the comparison expression.
+ *
+ * ## Options
+ * The options parameter is an object that can have the following properties:
+ *
+ * urlEncode (boolean, default: false): if set to true, URL encodes the comparison operators.
+ * andOp (string, default: '&&'): the logical AND operator to use in the expression.
+ * orOp (string, default: '||'): the logical OR operator to use in the expression.
+ * eqOp (string, default: '=='): the equality operator to use in the expression.
+ * geOp (string, default: '>='): the greater than or equal to operator to use in the expression.
+ * leOp (string, default: '<='): the less than or equal to operator to use in the expression.
+ *
+ * Examples
+ *
+ * ```javascript
+ * const expression = '0-10,20-30';
+ * const valueName = 'age';
+ * const options = { urlEncode: true, andOp: 'and', orOp: 'or', eqOp: '=', geOp: '>=', leOp: '<=' };
+ * const comparisonExpression = generateRangeComparisonExpression(expression, valueName, options);
+ *
+ * console.log(comparisonExpression); // age%3E%3D0%20and%20age%3C%3D10%20or%20age%3E%3D20%20and%20age%3C%3D30
+ * ```
+ *
+ * In this example, the generateRangeComparisonExpression() function generates a string representation of the comparison
+ * expression for the expression and valueName parameters with the specified options. The resulting comparison
+ * expression is 'age>=0 and age<=10 or age>=20 and age<=30', URL encoded according to the urlEncode option.
+ *
+ * @param {string} expression - The string expression to generate the comparison for.
+ * @param {string} valueName - The name of the value to compare against.
+ * @param {Object} [options] - The optional parameters.
+ * @param {boolean} [options.urlEncode=false] - Whether to encode comparison operators for use in a URL.
+ * @param {string} [options.andOp='&&'] - The logical AND operator to use.
+ * @param {string} [options.orOp='||'] - The logical OR operator to use.
+ * @param {string} [options.eqOp='=='] - The comparison operator for equality to use.
+ * @param {string} [options.geOp='>='] - The comparison operator for greater than or equal to to use.
+ * @param {string} [options.leOp='<='] - The comparison operator for less than or equal to to use.
+ * @returns {string} The generated comparison expression.
+ * @throws {Error} If the input is invalid.
+ * @memberOf Monster.Text
+ * @summary Generates a comparison expression based on a range of values.
+ */
+function generateRangeComparisonExpression(expression, valueName, options = {}) {
+    const { urlEncode = false, andOp = "&&", orOp = "||", eqOp = "==", geOp = ">=", leOp = "<=" } = options;
+    const ranges = expression.split(",");
+    let comparison = "";
+    for (let i = 0; i < ranges.length; i++) {
+        const range = ranges[i].trim();
+        if (range === "") {
+            throw new Error(`Invalid range '${range}'`);
+        } else if (range.includes("-")) {
+            const [start, end] = range.split("-").map((s) => (s === "" ? null : parseFloat(s)));
+            if ((start !== null && isNaN(start)) || (end !== null && isNaN(end))) {
+                throw new Error(`Invalid value in range '${range}'`);
+            }
+            if (start !== null && end !== null && start > end) {
+                throw new Error(`Invalid range '${range}'`);
+            }
+            const compStart =
+                start !== null ? `${valueName}${urlEncode ? encodeURIComponent(geOp) : geOp}${start}` : "";
+            const compEnd = end !== null ? `${valueName}${urlEncode ? encodeURIComponent(leOp) : leOp}${end}` : "";
+            const compRange = `${compStart}${compStart && compEnd ? ` ${andOp} ` : ""}${compEnd}`;
+            comparison += ranges.length > 1 ? `(${compRange})` : compRange;
+        } else {
+            const value = parseFloat(range);
+            if (isNaN(value)) {
+                throw new Error(`Invalid value '${range}'`);
+            }
+            const compValue = `${valueName}${urlEncode ? encodeURIComponent(eqOp) : eqOp}${value}`;
+            comparison += ranges.length > 1 ? `(${compValue})` : compValue;
+        }
+        if (i < ranges.length - 1) {
+            comparison += ` ${orOp} `;
+        }
+    }
+    return comparison;
+}

package/source/text/util.mjs

@@ -1,86 +1,2 @@
-export { generateRangeComparisonExpression };
+export { generateRangeComparisonExpression } from "./generate-range-comparison-expression.mjs"
 
-/**
- * The `generateRangeComparisonExpression()` function is function that generates a string representation
- * of a comparison expression based on a range of values. It takes three arguments:
- *
- * - expression (required): a string representation of a range of values in the format of start1-end1,start2-end2,value3....
- * - valueName (required): a string representing the name of the value that is being compared to the range of values.
- * - options (optional): an object containing additional options to customize the comparison expression.
- *
- * The generateRangeComparisonExpression() function returns a string representation of the comparison expression.
- *
- * ## Options
- * The options parameter is an object that can have the following properties:
- *
- * urlEncode (boolean, default: false): if set to true, URL encodes the comparison operators.
- * andOp (string, default: '&&'): the logical AND operator to use in the expression.
- * orOp (string, default: '||'): the logical OR operator to use in the expression.
- * eqOp (string, default: '=='): the equality operator to use in the expression.
- * geOp (string, default: '>='): the greater than or equal to operator to use in the expression.
- * leOp (string, default: '<='): the less than or equal to operator to use in the expression.
- *
- * Examples
- *
- * ```javascript
- * const expression = '0-10,20-30';
- * const valueName = 'age';
- * const options = { urlEncode: true, andOp: 'and', orOp: 'or', eqOp: '=', geOp: '>=', leOp: '<=' };
- * const comparisonExpression = generateRangeComparisonExpression(expression, valueName, options);
- *
- * console.log(comparisonExpression); // age%3E%3D0%20and%20age%3C%3D10%20or%20age%3E%3D20%20and%20age%3C%3D30
- * ```
- *
- * In this example, the generateRangeComparisonExpression() function generates a string representation of the comparison
- * expression for the expression and valueName parameters with the specified options. The resulting comparison
- * expression is 'age>=0 and age<=10 or age>=20 and age<=30', URL encoded according to the urlEncode option.
- *
- * @param {string} expression - The string expression to generate the comparison for.
- * @param {string} valueName - The name of the value to compare against.
- * @param {Object} [options] - The optional parameters.
- * @param {boolean} [options.urlEncode=false] - Whether to encode comparison operators for use in a URL.
- * @param {string} [options.andOp='&&'] - The logical AND operator to use.
- * @param {string} [options.orOp='||'] - The logical OR operator to use.
- * @param {string} [options.eqOp='=='] - The comparison operator for equality to use.
- * @param {string} [options.geOp='>='] - The comparison operator for greater than or equal to to use.
- * @param {string} [options.leOp='<='] - The comparison operator for less than or equal to to use.
- * @returns {string} The generated comparison expression.
- * @throws {Error} If the input is invalid.
- * @memberOf Monster.Text
- * @summary Generates a comparison expression based on a range of values.
- */
-function generateRangeComparisonExpression(expression, valueName, options = {}) {
-    const { urlEncode = false, andOp = "&&", orOp = "||", eqOp = "==", geOp = ">=", leOp = "<=" } = options;
-    const ranges = expression.split(",");
-    let comparison = "";
-    for (let i = 0; i < ranges.length; i++) {
-        const range = ranges[i].trim();
-        if (range === "") {
-            throw new Error(`Invalid range '${range}'`);
-        } else if (range.includes("-")) {
-            const [start, end] = range.split("-").map((s) => (s === "" ? null : parseFloat(s)));
-            if ((start !== null && isNaN(start)) || (end !== null && isNaN(end))) {
-                throw new Error(`Invalid value in range '${range}'`);
-            }
-            if (start !== null && end !== null && start > end) {
-                throw new Error(`Invalid range '${range}'`);
-            }
-            const compStart =
-                start !== null ? `${valueName}${urlEncode ? encodeURIComponent(geOp) : geOp}${start}` : "";
-            const compEnd = end !== null ? `${valueName}${urlEncode ? encodeURIComponent(leOp) : leOp}${end}` : "";
-            const compRange = `${compStart}${compStart && compEnd ? ` ${andOp} ` : ""}${compEnd}`;
-            comparison += ranges.length > 1 ? `(${compRange})` : compRange;
-        } else {
-            const value = parseFloat(range);
-            if (isNaN(value)) {
-                throw new Error(`Invalid value '${range}'`);
-            }
-            const compValue = `${valueName}${urlEncode ? encodeURIComponent(eqOp) : eqOp}${value}`;
-            comparison += ranges.length > 1 ? `(${compValue})` : compValue;
-        }
-        if (i < ranges.length - 1) {
-            comparison += ` ${orOp} `;
-        }
-    }
-    return comparison;
-}

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.35.4");
+    monsterVersion = new Version("3.37.0");
 
     return monsterVersion;
 }

package/test/cases/dom/util.mjs

@@ -2,6 +2,7 @@ import {
     getDocument, getWindow, getDocumentFragmentFromString
 } from "../../../../application/source/dom/util.mjs";
 
+import {getContainingDocument} from "../../../../application/source/dom/util.mjs";
 
 import {initJSDOM} from "../../util/jsdom.mjs";
 
@@ -52,4 +53,63 @@ describe('DOM', function () {
         });
 
     });
+
+
+    describe('getContainingDocument', () => {
+        let  jsDomDocument;
+
+         beforeEach(() => {
+             jsDomDocument = getDocument();
+         });
+        //
+        // afterEach(() => {
+        //     dom.window.close();
+        // });
+
+        it('should throw an error when called with an invalid argument', () => {
+            expect(() => getContainingDocument(null)).to.throw('Invalid argument. Expected an HTMLElement.');
+        });
+
+        it('should return the correct containing document for an element in the main document', () => {
+            const element = jsDomDocument.createElement('div');
+            const containingDocument = getContainingDocument(element);
+
+            expect(containingDocument).to.null;
+        });
+
+        it('should return the correct containing document for an element inside a shadow root', () => {
+            const host = jsDomDocument.createElement('div');
+            const shadowRoot = host.attachShadow({ mode: 'open' });
+            const element = jsDomDocument.createElement('span');
+            shadowRoot.appendChild(element);
+
+            const containingDocument = getContainingDocument(element);
+            expect(containingDocument).to.not.null;
+        });
+
+        it('should return the correct containing document for an element inside a nested shadow root', () => {
+            const outerHost = jsDomDocument.createElement('div');
+            const outerShadowRoot = outerHost.attachShadow({ mode: 'open' });
+
+            const innerHost = jsDomDocument.createElement('div');
+            outerShadowRoot.appendChild(innerHost);
+
+            const innerShadowRoot = innerHost.attachShadow({ mode: 'open' });
+
+            const element = jsDomDocument.createElement('span');
+            innerShadowRoot.appendChild(element);
+
+            const containingDocument = getContainingDocument(element);
+            expect(containingDocument).to.not.null;
+        });
+
+        it('should return null when the element is not attached to any document', () => {
+            const detachedElement = jsDomDocument.createElement('div');
+            detachedElement.remove();
+
+            const containingDocument = getContainingDocument(detachedElement);
+            expect(containingDocument).to.be.null;
+        });
+    });    
+    
 });

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.35.4")
+        monsterVersion = new Version("3.37.0")
 
         let m = getMonsterVersion();