@webtides/element-js 0.7.4 → 1.0.0-alpha.10

package/src/util/DOMHelper.js

@@ -1,3 +1,35 @@
+/* An Element node like <p> or <div> */
+export const ELEMENT_NODE = 1;
+/* An Attribute of an Element */
+export const ATTRIBUTE_NODE = 2;
+/* The actual Text inside an Element or Attr */
+export const TEXT_NODE = 3;
+/* A Comment node, such as <!-- … --> */
+export const COMMENT_NODE = 8;
+/* A Document Fragment, a document without a parent */
+export const DOCUMENT_FRAGMENT_NODE = 11;
+
+/**
+ * Gets a list of (childNode) indexes for the given node
+ * @param {Node} node
+ * @return {number[]}
+ */
+export const getNodePath = (node) => {
+	const path = [];
+	let parentNode = node.parentNode;
+	while (parentNode) {
+		path.push([...parentNode.childNodes].indexOf(node));
+		node = parentNode;
+		parentNode = node.parentNode;
+	}
+	return path;
+};
+
+/**
+ * Get a list of all parent nodes up the DOM tree
+ * @param {Node} domNode
+ * @returns {Node[]}
+ */
 export function getAllParentNodes(domNode) {
 	let node = domNode.parentElement;
 	let parents = [];
@@ -9,7 +41,12 @@ export function getAllParentNodes(domNode) {
 	return parents;
 }
 
-// https://stackoverflow.com/questions/27453617/how-can-i-tell-if-an-element-is-in-a-shadow-dom
+/**
+ * Gets the parent/root element of a shadow root or the global document body if not in shadow root.
+ * https://stackoverflow.com/questions/27453617/how-can-i-tell-if-an-element-is-in-a-shadow-dom
+ * @param {Node} element
+ * @returns {ShadowRoot | HTMLElement}
+ */
 export function getShadowParentOrBody(element) {
 	if (element instanceof ShadowRoot) {
 		return element;
@@ -25,6 +62,11 @@ export function getShadowParentOrBody(element) {
 
 // TODO: add function for getClosestParentOfNodeType('custom-element')
 
+/**
+ * Get the closest/first parent node that is a custom element
+ * @param {Node} domNode
+ * @returns {Node}
+ */
 export function getClosestParentCustomElementNode(domNode) {
 	const customElementParents = getAllParentNodes(domNode).filter((node) => {
 		return node.localName && node.localName.indexOf('-') !== -1;
@@ -33,6 +75,12 @@ export function getClosestParentCustomElementNode(domNode) {
 	return customElementParents.pop();
 }
 
+/**
+ * Get all
+ * @param {Node} domNode
+ * @param {{prototype: HTMLElement, new()}} instanceOfFilter
+ * @return {Node[]}
+ */
 export function getAllElementChildren(domNode, instanceOfFilter = HTMLElement) {
 	const nodeIterator = document.createNodeIterator(domNode, NodeFilter.SHOW_ELEMENT, (node) =>
 		node.nodeName.includes('-') && node instanceof instanceOfFilter
@@ -47,14 +95,214 @@ export function getAllElementChildren(domNode, instanceOfFilter = HTMLElement) {
 	return customElements;
 }
 
+/**
+ * Checks whether two nodes are of the same node type
+ * @param {Node} nodeA
+ * @param {Node} nodeB
+ * @returns {boolean}
+ */
 export function isOfSameNodeType(nodeA, nodeB) {
 	if (!nodeA && !nodeA.localName) return false;
 	if (!nodeB && !nodeB.localName) return false;
 	return nodeA.localName === nodeB.localName;
 }
 
-export const supportsAdoptingStyleSheets = () =>
-	'adoptedStyleSheets' in Document.prototype && 'replace' in CSSStyleSheet.prototype;
+/**
+ * Checks if adopting style sheets is supported in browser
+ * @returns {boolean}
+ */
+export const supportsAdoptingStyleSheets = () => {
+	return 'adoptedStyleSheets' in Document.prototype && 'replace' in CSSStyleSheet.prototype;
+};
+
+/**
+ * Better implementation of hasChildNodes check because the native check will also count for empty whitespace as child nodes... :(
+ * @param {Node} node
+ * @returns {boolean}
+ */
+export const hasChildNodes = (node) => {
+	const childNodesLength = node.childNodes.length;
+
+	if (childNodesLength === 0) return false;
+
+	if (childNodesLength === 1 && node.firstChild.nodeType === 3 && node.firstChild.textContent.trim() === '')
+		return false;
+
+	// children will not contain text nodes...
+	if (childNodesLength > 0) return true;
+
+	// TODO: check if more than 1 child nodes, but all childnodes are whitespace text ndoes?!
+};
+
+/**
+ * Parses the given string as HTML template and returns a real DOM element
+ * @param {string} template
+ * @returns {HTMLElement}
+ */
+export const convertStringToHTML = (template) => {
+	const parser = new DOMParser();
+	const document = parser.parseFromString(template.toString(), 'text/html');
+	return document.body;
+};
+
+/**
+ * Parses the given string and returns a DocumentFragment which contains the DOM subtree
+ * representing the <template> element's template contents.
+ * @param {string} string
+ * @return {DocumentFragment}
+ */
+export const convertStringToTemplate = (string) => {
+	const template = globalThis.document?.createElement('template');
+	// TODO: ensure that SSRed and CSRed templates have the same amount of whitespace text nodes
+	template.innerHTML = string.trimStart().trimEnd();
+	return template.content;
+};
+
+/**
+ * Diff the attributes for a live DOM element against a template DOM element
+ * @param {Element} templateElement - The new template
+ * @param {Element} domElement - The existing DOM node
+ */
+export const diffAttributes = function (templateElement, domElement) {
+	// remove or update previous attributes
+	for (/** @type {Attr} */ const attribute of Array.from(domElement.attributes)) {
+		if (templateElement.hasAttribute(attribute.name)) {
+			const oldValue = attribute.value;
+			const newValue = templateElement.getAttribute(attribute.name) || '';
+			if (oldValue !== newValue) {
+				domElement.setAttribute(attribute.name, newValue);
+			}
+		} else {
+			domElement.removeAttribute(attribute.name);
+		}
+	}
+
+	// set newly added attributes
+	for (/** @type {Attr} */ const attribute of Array.from(templateElement.attributes)) {
+		if (!domElement.hasAttribute(attribute.name)) {
+			domElement.setAttribute(attribute.name, attribute.value);
+		}
+	}
+};
+
+/**
+ * Diff a live DOM node against a template DOM node
+ * @param {Node} templateNode
+ * @param {Node} domNode
+ * @param {(Node) => Boolean} shouldDiffChildNodes
+ */
+export const diffNodes = function (templateNode, domNode, shouldDiffChildNodes = (templateChildNode) => true) {
+	// If the DOM node should be empty, remove all child nodes
+	if (hasChildNodes(domNode) && !hasChildNodes(templateNode)) {
+		domNode.replaceChildren();
+		return;
+	}
+
+	// If the DOM node is empty, but should have children, add child nodes from the template node
+	if (!hasChildNodes(domNode) && hasChildNodes(templateNode)) {
+		domNode.replaceChildren(...templateNode.childNodes);
+		return;
+	}
+
+	const templateChildNodes = [...templateNode.childNodes];
+	const domChildNodes = [...domNode.childNodes];
+
+	// Diff each node in the child node lists
+	let length = Math.max(templateChildNodes.length, domChildNodes.length);
+	for (let index = 0; index < length; index++) {
+		const templateChildNode = templateChildNodes[index];
+		const domChildNode = domChildNodes[index];
+
+		// If the DOM node doesn't exist, append/copy the template node
+		if (!domChildNode) {
+			domNode.appendChild(templateChildNode);
+			continue;
+		}
+
+		// If the template node doesn't exist, remove the node in the DOM
+		if (!templateChildNode) {
+			domNode.removeChild(domChildNode);
+			continue;
+		}
+
+		// If DOM node is equal to the template node, don't do anything
+		if (domChildNode.isEqualNode(templateChildNode)) {
+			continue;
+		}
+
+		// the following two checks don't have to be correct, but it could bring as back to the fast path
+		// in the worst case we still have to compare and swap all the elements
+		// but in the best case we find the one element that should actually be inserted or removed
+		// and from there on, every node that comes after should be equal again
+
+		// fast path for removing DOM nodes - we delete the node now instead of at the end
+		if (domNode.childNodes.length > templateNode.childNodes.length) {
+			domChildNodes.splice(index, 1);
+			domNode.removeChild(domChildNode);
+			// because domChildNodes will get shorter by splicing it, everything moves up by one
+			// so the (actual) next element will have the same index now as we currently have
+			// therefore we have to adjust our counters
+			length--;
+			index--;
+
+			// we might have corrected everything and the parent nodes could be equal again
+			// if so, we can skip the rest of the child node checks
+			if (domNode.childNodes.length === templateNode.childNodes.length && domNode.isEqualNode(templateNode)) {
+				return;
+			}
+
+			continue;
+		}
+
+		// fast path for adding DOM nodes - we insert the node now instead of at the end
+		// but NOT if we already are at the end of the list of child nodes
+		if (index !== domNode.childNodes.length - 1 && domNode.childNodes.length < templateNode.childNodes.length) {
+			domChildNodes.splice(index, 0, templateChildNode);
+			domNode.insertBefore(templateChildNode, domChildNode);
+
+			// we might have corrected everything and the parent nodes could be equal again
+			// if so, we can skip the rest of the child node checks
+			if (domNode.childNodes.length === templateNode.childNodes.length && domNode.isEqualNode(templateNode)) {
+				return;
+			}
+
+			continue;
+		}
 
-// for IE11 we are using the ShadyDOM Polyfill. With the polyfill we cannot append stylesheets to the shadowRoot
-export const supportsAppendingStyleSheets = !window.ShadyDOM;
+		// If node types are not the same, replace the DOM node with the template node
+		if (templateChildNode.nodeType !== domChildNode.nodeType) {
+			domNode.replaceChild(templateChildNode, domChildNode);
+			continue;
+		}
+
+		// If the node is a Text node or a Comment node, update it
+		if (domChildNode.nodeType === TEXT_NODE || domChildNode.nodeType === COMMENT_NODE) {
+			domChildNode.textContent = templateChildNode.textContent;
+			continue;
+		}
+
+		// If the element tag names are not the same, replace the DOM node with the template node
+		if (templateChildNode.nodeType === ELEMENT_NODE && templateChildNode.tagName !== domChildNode.tagName) {
+			domNode.replaceChild(templateChildNode, domChildNode);
+			continue;
+		}
+
+		// If the node is an SVG element, don't even think about diffing it, just replace it
+		if (templateChildNode.nodeType === ELEMENT_NODE && templateChildNode.tagName === 'SVG') {
+			domNode.replaceChild(templateChildNode, domChildNode);
+			continue;
+		}
+
+		// If the node is an Element node, diff the attributes
+		if (templateChildNode.nodeType === ELEMENT_NODE) {
+			diffAttributes(templateChildNode, domChildNode);
+		}
+
+		// If there are child nodes, diff them recursively
+		if (templateChildNode.hasChildNodes()) {
+			if (shouldDiffChildNodes(templateChildNode)) {
+				diffNodes(templateChildNode, domChildNode);
+			}
+		}
+	}
+};

package/src/util/Directive.js

@@ -0,0 +1,42 @@
+export class Directive {
+	/** @type {Element} */
+	node = undefined;
+
+	/**
+	 * @param {Node} node
+	 */
+	constructor(node) {
+		this.node = node;
+	}
+
+	/**
+	 * @abstract
+	 */
+	update() {}
+
+	// TODO: this is somewhat custom... maybe we could set the initial values in the constructor and then simply override the default toString() method?!
+	/**
+	 * Implement the stringify method and return a string for rendering the directive in SSR mode
+	 * @param {...any} values
+	 * @returns {string}
+	 */
+	stringify(...values) {
+		return '';
+	}
+}
+
+/**
+ * @param {Class<Directive>} directiveClass
+ */
+export const defineDirective = (directiveClass) => {
+	return (...values) => {
+		return {
+			directiveClass,
+			values,
+			toString: () => {
+				const directive = new directiveClass();
+				return directive.stringify(...values);
+			},
+		};
+	};
+};

package/src/util/GlobalStylesStore.js

@@ -0,0 +1,66 @@
+import { Store } from './Store.js';
+
+/**
+ * @property {CSSStyleSheet[]} cssStyleSheets
+ */
+class GlobalStylesStore extends Store {
+	/** @type {Map<Node, CSSStyleSheet>} */
+	globalStyleSheetsCache = new WeakMap();
+
+	constructor() {
+		super();
+		if (globalThis.elementJsConfig?.observeGlobalStyles) {
+			const mutationObserver = new MutationObserver((mutationRecord) => {
+				if (!mutationRecord[0]) return;
+				const filteredNodes = Array.from(mutationRecord[0].addedNodes).filter(
+					(node) => node.tagName === 'STYLE' || node.tagName === 'LINK',
+				);
+				if (filteredNodes && filteredNodes[0] && filteredNodes[0].tagName === 'LINK') {
+					filteredNodes[0].onload = () => {
+						this.requestUpdate();
+					};
+				} else if (filteredNodes && filteredNodes[0] && filteredNodes[0].tagName === 'STYLE') {
+					this.requestUpdate();
+				}
+			});
+			mutationObserver.observe(globalThis.document, { subtree: true, childList: true });
+		}
+	}
+
+	getGlobalStyleSheets(selector) {
+		/** @type {CSSStyleSheet[]}*/
+		const cssStyleSheets = [];
+
+		if (selector === false) return cssStyleSheets;
+
+		if (typeof selector === 'string') {
+			selector = [selector];
+		}
+
+		if (selector === true || selector.includes('document')) {
+			cssStyleSheets.push(...globalThis.document?.adoptedStyleSheets);
+		}
+
+		Array.from(globalThis.document?.styleSheets).map((styleSheet) => {
+			if (Array.isArray(selector) && !selector.some((cssSelector) => styleSheet.ownerNode.matches(cssSelector))) {
+				return;
+			}
+
+			// TODO: this will always be null as we never set anything to the cache...
+			let cssStyleSheet = this.globalStyleSheetsCache.get(styleSheet.ownerNode);
+			if (!cssStyleSheet) {
+				cssStyleSheet = new CSSStyleSheet();
+				if (styleSheet.ownerNode.tagName === 'STYLE') {
+					cssStyleSheet.replaceSync(styleSheet.ownerNode.textContent);
+				} else if (styleSheet.ownerNode.tagName === 'LINK') {
+					Array.from(styleSheet.cssRules).map((rule) => cssStyleSheet.insertRule(rule.cssText));
+				}
+			}
+			cssStyleSheets.push(cssStyleSheet);
+		});
+
+		return cssStyleSheets;
+	}
+}
+
+export const globalStylesStore = new GlobalStylesStore();

package/src/util/SerializeStateHelper.js

@@ -0,0 +1,103 @@
+import { Store } from './Store.js';
+
+/**
+ * @typedef {Object} Serializable
+ * An interface that classes should implement to enable serialization and deserialization of their state.
+ * @property {string} _serializationKey - a unique key to be used for serialization.
+ * @property {function} serializeState - Function to retrieve the state for serialization.
+ * @property {function} restoreState - Function to set the state during deserialization.
+ */
+
+// TODO: is it ok to expose this like this? Or should we wrap the cache in helper methods also?
+/** @type {Map<string, Serializable>} */
+export const serializableObjectsCache = new Map();
+
+/** @type {HTMLScriptElement} */
+let globalElementJsState;
+
+/**
+ * Initializes the global script element that holds the state for all `Serializable` objects.
+ */
+function initGlobalStateObject() {
+	if (!globalElementJsState) {
+		globalElementJsState = Array.from(globalThis.document.scripts).find((script) => script.type === 'ejs/json');
+		if (!globalElementJsState) {
+			const script = document.createElement('script');
+			script.setAttribute('type', 'ejs/json');
+			script.textContent = '{}';
+			document.body.appendChild(script);
+			globalElementJsState = script;
+		}
+	}
+}
+
+/**
+ * Takes an object that implements the `Serializable` interface and serializes its state.
+ * @param {Serializable} serializableObject
+ */
+export function serializeState(serializableObject) {
+	if (!globalThis.elementJsConfig?.serializeState) return;
+
+	if (!serializableObject._serializationKey && !serializableObject.serializeState) {
+		throw new Error('serializableObject does not implement the Serializable interface');
+	}
+
+	initGlobalStateObject();
+
+	const currentState = JSON.parse(globalElementJsState.textContent);
+	currentState[serializableObject._serializationKey] = serializableObject.serializeState();
+	globalElementJsState.textContent = JSON.stringify(currentState, (key, value) => {
+		if (value instanceof Store) {
+			return 'Store/' + value._serializationKey;
+		} else {
+			return value;
+		}
+	});
+}
+
+/**
+ * Takes an object that implements the `Serializable` interface and deserializes its state and restores the object.
+ * @param {Serializable} serializableObject
+ * @param {{[string: any]: *}} [serializedState]
+ */
+export function deserializeState(serializableObject, serializedState) {
+	if (!globalThis.elementJsConfig?.serializeState) return;
+
+	if (!serializableObject._serializationKey && !serializableObject.restoreState) {
+		throw new Error('serializableObject does not implement the Serializable interface');
+	}
+
+	if (serializedState) {
+		serializableObject.restoreState(serializedState);
+		return;
+	}
+
+	initGlobalStateObject();
+
+	const unresolvedState = JSON.parse(globalElementJsState.textContent);
+	const currentState = JSON.parse(globalElementJsState.textContent, (key, value) => {
+		if (typeof value === 'string' && value.startsWith('Store/')) {
+			const [_, storeUuid] = value.split('/');
+			const serializedState = unresolvedState[storeUuid];
+			return new Store(serializedState, { key: storeUuid, serializedState });
+		} else {
+			return value;
+		}
+	});
+
+	serializableObject.restoreState(currentState[serializableObject._serializationKey]);
+}
+
+/**
+ * Checks if a serialized state is available for a given key.
+ * @param key
+ * @return {boolean}
+ */
+export function hasSerializedState(key) {
+	if (!globalThis.elementJsConfig?.serializeState) return false;
+
+	initGlobalStateObject();
+
+	const serializedState = JSON.parse(globalElementJsState.textContent);
+	return serializedState.hasOwnProperty(key);
+}

package/src/util/Store.js

@@ -1,18 +1,59 @@
-import { isObjectLike, deepEquals } from './AttributeParser.js';
-import { BaseElement } from '../BaseElement';
+import { deepEquals, isObjectLike } from './AttributeParser.js';
+import {
+	hasSerializedState,
+	serializeState,
+	deserializeState,
+	serializableObjectsCache,
+} from './SerializeStateHelper.js';
+import { BaseElement } from '../BaseElement.js';
 
+/**
+ * Options object for the Store
+ * @typedef {Object} StoreOptions
+ * @property {string} [key] - A unique key so that the store instance can be serialized and deserialized correctly across multiple shared parents/hosts.
+ */
+
+/**
+ * @implements {Serializable}
+ */
 export class Store {
-	_observer = new Set();
+	_serializationKey;
+	_observer = new Set([]);
 	_singlePropertyMode = false;
 	_state = {};
 
-	constructor(value) {
-		// wrap primitives with a generic "value" field to generate getter and setter
+	/**
+	 * @param {* | object} [value]
+	 * @param {StoreOptions} [options]
+	 */
+	constructor(value, options) {
+		if (options?.key && serializableObjectsCache.has(options?.key)) {
+			return serializableObjectsCache.get(options?.key);
+		}
+
 		this._singlePropertyMode = arguments.length > 0 && !isObjectLike(value);
+
+		if (options?.key) {
+			this._serializationKey = options?.key;
+		} else {
+			this._serializationKey = globalThis.crypto.randomUUID();
+		}
+
+		if (options?.serializedState) {
+			deserializeState(this, options.serializedState);
+		} else if (hasSerializedState(this._serializationKey)) {
+			deserializeState(this);
+		}
+
+		// wrap primitives with a generic "value" field to generate getter and setter
 		const specificValues = this._singlePropertyMode ? { value } : value;
-		this._state = { ...(!this._singlePropertyMode && this.properties()), ...specificValues };
+		const properties = { ...(!this._singlePropertyMode && this.properties()), ...specificValues };
+
+		const serializationKeys = Object.keys(this.serializeState());
+		Object.entries(properties).map(([key, value]) => {
+			this._state[key] =
+				hasSerializedState(this._serializationKey) && serializationKeys.includes(key) ? this[key] : value;
 
-		Object.entries(this._state).map(([key, value]) => {
 			if (value instanceof Store) {
 				value.subscribe(this);
 			}
@@ -28,6 +69,8 @@ export class Store {
 						value.subscribe(this);
 					}
 
+					serializeState(this);
+
 					if (!deepEquals(newValue, oldValue)) {
 						const watch = this.watch();
 						if (watch.hasOwnProperty(key) && typeof watch[key] === 'function') {
@@ -38,8 +81,15 @@ export class Store {
 				},
 			});
 		});
+
+		serializableObjectsCache.set(this._serializationKey, this);
 	}
 
+	/**
+	 * Properties to be defined and assigned on the store. Can be overridden in extended classes.
+	 * Properties defined here will also trigger an update cycle when changed.
+	 * @return {{}}
+	 */
 	properties() {
 		return {};
 	}
@@ -47,34 +97,47 @@ export class Store {
 	/**
 	 * When a property as the key was changed in the store, the callback function defined as value
 	 * will be called with `newValue` and `oldValue`
-	 * eg. { property: (oldValue, newValue) => { console.log('property changed!, oldValue, newValue); } }
 	 * @return {{}}
 	 */
 	watch() {
 		return {};
 	}
 
+	/**
+	 * Overrides `valueOf` to automatically return .value
+	 * @returns {* | {}}
+	 */
 	valueOf() {
 		return this._singlePropertyMode ? this._state.value : this._state;
 	}
 
+	/**
+	 * Overrides `toString` to automatically return .value
+	 * @returns {string}
+	 */
 	toString() {
 		return `${this._singlePropertyMode ? this._state.value : this._state}`;
 	}
 
 	/**
+	 * Add an observer
 	 * @param {BaseElement|Function|Store} observer
 	 */
 	subscribe(observer) {
 		this._observer.add(observer);
 	}
+
 	/**
-	 * @param {BaseElement|Function} observer
+	 * Remove an observer
+	 * @param {BaseElement | Function} observer
 	 */
 	unsubscribe(observer) {
 		this._observer.delete(observer);
 	}
 
+	/**
+	 * Request and batch an asynchronous update cycle
+	 */
 	requestUpdate() {
 		this._observer.forEach(async (observer) => {
 			if (observer instanceof BaseElement || observer instanceof Store) {
@@ -104,4 +167,24 @@ export class Store {
 			}
 		});
 	}
+
+	/**
+	 * This method will be used to serialize this stores state.
+	 * By default, it will generate an object with all properties from this.properties().
+	 * You can override this and return a different object with more/less/different properties.
+	 * @return {{[string: any]: *}}
+	 */
+	serializeState() {
+		const keys = Object.keys(this.properties());
+		return Object.fromEntries(keys.map((key) => [key, this[key]]));
+	}
+
+	/**
+	 * This method will be used to restore properties on the store from a previously serialized state.
+	 * You can override this and handle the deserialization differently if the default is not enough.
+	 * @param {{[string: any]: *}} serializedState
+	 */
+	restoreState(serializedState) {
+		Object.assign(this, serializedState);
+	}
 }

package/src/util/defineElement.js

@@ -1,7 +1,7 @@
 /**
  * Wrapper for defining custom elements so that registering an element multiple times won't crash
- * @param name for the tag
- * @param constructor for the custom element
+ * @param {string} name - name for the element tag
+ * @param {CustomElementConstructor} constructor for the custom element
  */
 export function defineElement(name, constructor) {
 	try {

package/src/util/toString.js

@@ -1,8 +1,8 @@
 /**
  * Little wrapper function for JSON.stringify() to easily convert objects and arrays to strings
  * to be able to set them as attributes on custom elements
- * @param value to be stringified
- * @return String of the stringified value
+ * @param {object | array} value - to be stringified
+ * @return {string}
  */
 export function toString(value) {
 	try {