@schukai/monster
Version:
Monster is a simple library for creating fast, robust and lightweight websites.
326 lines (298 loc) • 8.78 kB
JavaScript
/**
* Copyright © schukai GmbH and all contributing authors, {{copyRightYear}}. All rights reserved.
* Node module: @schukai/monster
*
* This source code is licensed under the GNU Affero General Public License version 3 (AGPLv3).
* The full text of the license can be found at: https://www.gnu.org/licenses/agpl-3.0.en.html
*
* For those who do not wish to adhere to the AGPLv3, a commercial license is available.
* Acquiring a commercial license allows you to use this software without complying with the AGPLv3 terms.
* For more information about purchasing a commercial license, please contact schukai GmbH.
*
* SPDX-License-Identifier: AGPL-3.0
*/
import { getGlobal } from "../types/global.mjs";
import { validateString } from "../types/validate.mjs";
export {
getDocument,
getWindow,
getDocumentFragmentFromString,
findElementWithIdUpwards,
getContainingDocument,
getRegisteredCustomElements,
findElementWithSelectorUpwards,
};
/**
* This method fetches the document object
*
* In nodejs this functionality can be performed with [jsdom](https://www.npmjs.com/package/jsdom).
*
* ```
* import {JSDOM} from "jsdom"
* if (typeof window !== "object") {
* const {window} = new JSDOM('', {
* url: 'http://example.com/',
* pretendToBeVisual: true
* });
*
* [
* 'self',
* 'document',
* 'Document',
* 'Node',
* 'Element',
* 'HTMLElement',
* 'DocumentFragment',
* 'DOMParser',
* 'XMLSerializer',
* 'NodeFilter',
* 'InputEvent',
* 'CustomEvent'
* ].forEach(key => (getGlobal()[key] = window[key]));
* }
* ```
*
* @return {object}
* @license AGPLv3
* @since 1.6.0
* @copyright schukai GmbH
* @throws {Error} not supported environment
*/
function getDocument() {
const document = getGlobal()?.["document"];
if (typeof document !== "object") {
throw new Error("not supported environment");
}
return document;
}
/**
* This method fetches the window object
*
* In nodejs this functionality can be performed with [jsdom](https://www.npmjs.com/package/jsdom).
*
* ```
* import {JSDOM} from "jsdom"
* if (typeof window !== "object") {
* const {window} = new JSDOM('', {
* url: 'http://example.com/',
* pretendToBeVisual: true
* });
*
* getGlobal()['window']=window;
*
* [
* 'self',
* 'document',
* 'Document',
* 'Node',
* 'Element',
* 'HTMLElement',
* 'DocumentFragment',
* 'DOMParser',
* 'XMLSerializer',
* 'NodeFilter',
* 'InputEvent',
* 'CustomEvent'
* ].forEach(key => (getGlobal()[key] = window[key]));
* }
* ```
*
* @return {object}
* @license AGPLv3
* @since 1.6.0
* @copyright schukai GmbH
* @throws {Error} not supported environment
*/
function getWindow() {
const window = getGlobal()?.["window"];
if (typeof window !== "object") {
throw new Error("not supported environment");
}
return window;
}
/**
* This method fetches the document object
*
* In nodejs this functionality can be performed with [jsdom](https://www.npmjs.com/package/jsdom).
*
* ```
* import {JSDOM} from "jsdom"
* if (typeof window !== "object") {
* const {window} = new JSDOM('', {
* url: 'http://example.com/',
* pretendToBeVisual: true
* });
*
* [
* 'self',
* 'document',
* 'Document',
* 'Node',
* 'Element',
* 'HTMLElement',
* 'DocumentFragment',
* 'DOMParser',
* 'XMLSerializer',
* 'NodeFilter',
* 'InputEvent',
* 'CustomEvent'
* ].forEach(key => (getGlobal()[key] = window[key]));
* }
* ```
*
* @return {DocumentFragment}
* @license AGPLv3
* @since 1.6.0
* @copyright schukai GmbH
* @throws {Error} not supported environment
* @throws {TypeError} value is not a string
*/
function getDocumentFragmentFromString(html) {
validateString(html);
const document = getDocument();
const template = document.createElement("template");
template.innerHTML = html;
return template.content;
}
/**
* Recursively searches upwards from a given element to find an ancestor element
* with a specified ID, considering both normal DOM and shadow DOM.
*
* @param {HTMLElement|ShadowRoot} element - The starting element or shadow root to search from.
* @param {string} targetId - The ID of the target element to find.
* @return {HTMLElement|null} - The ancestor element with the specified ID, or null if not found.
* @since 3.29.0
* @license AGPLv3
* @copyright schukai GmbH
*/
function findElementWithIdUpwards(element, targetId) {
if (!element) {
return null;
}
// Check if the current element has the target ID
if (element.id === targetId) {
return element;
}
// Search within the current element's shadow root, if it exists
if (element.shadowRoot) {
const target = element.shadowRoot.getElementById(targetId);
if (target) {
return target;
}
}
// If the current element is the document.documentElement, search within the main document
if (element === document.documentElement || element === document) {
const target = document.getElementById(targetId);
if (target) {
return target;
}
}
// If the current element is inside a shadow root, search its host's ancestors
const rootNode = element.getRootNode();
if (rootNode && rootNode instanceof ShadowRoot) {
return findElementWithIdUpwards(rootNode.host, targetId);
}
// Otherwise, search the current element's parent
return findElementWithIdUpwards(element.parentElement, targetId);
}
/**
* Recursively searches upwards from a given element to find an ancestor element
* with a specified selector, considering both normal DOM and shadow DOM.
* This method is useful for finding a parent element with a specific class.
*
* @param {HTMLElement|ShadowRoot} element - The starting element or shadow root to search from.
* @param {string} selector - The selector of the target element to find.
* @return {HTMLElement|null} - The ancestor element with the specified selector, or null if not found.
* @since 3.55.0
*/
function findElementWithSelectorUpwards(element, selector) {
if (!element || !selector) {
return null;
}
// Search within the current element's shadow root, if it exists
if (element.shadowRoot) {
const target = element.shadowRoot.querySelector(selector);
if (target) {
return target;
}
}
if (element === document.documentElement) {
const target = document.querySelector(selector);
if (target) {
return target;
}
}
// If the current element is inside a shadow root, search its host's ancestors
const rootNode = element.getRootNode();
if (rootNode && rootNode instanceof ShadowRoot) {
return findElementWithSelectorUpwards(rootNode.host, selector);
}
// Otherwise, search the current element's parent
return findElementWithSelectorUpwards(element.parentElement, selector);
}
/**
* @private
* @param {HTMLElement} element
* @return {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
* @return {*}
* @throws {Error} Invalid argument. Expected an HTMLElement.
* @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;
}
/**
* Returns a list of all registered custom elements in the current document.
*
* @return {string[]}
* @since 4.0.0
* @return {string[]}
*/
function getRegisteredCustomElements() {
const customElementTags = Array.from(document.querySelectorAll("*"))
.map((tag) => tag.tagName.toLowerCase())
.filter((tagName) => tagName.includes("-") && customElements.get(tagName));
return Array.from(new Set(customElementTags));
}