@webtides/element-js 1.0.0-alpha.1 → 1.0.0-alpha.3

package/src/dom-parts/directives.js

@@ -1,6 +1,7 @@
 import { camelToDash, decodeAttribute, encodeAttribute } from '../util/AttributeParser.js';
-import { TemplateResult } from './TemplateResult';
-import { convertStringToHTML } from '../util/DOMHelper';
+import { TemplateResult } from './TemplateResult.js';
+import { convertStringToHTML, convertStringToTemplate } from '../util/DOMHelper.js';
+import { defineDirective, Directive } from '../util/Directive.js';
 
 /**
  * Maps a list of classes to an element from an object.
@@ -55,30 +56,54 @@ const choose = (value, cases, defaultCase) => {
 /**
  * Renders a given string as HTML instead of text
  * @param {string} string
- * @returns {function(): Node}
+ * @returns {function(): Node | string}
  */
 const unsafeHTML = (string) => {
-	// TODO: write tests for this...
-	// I mean should the string always have a single root element? Or could it also handle multiple root elements?!
-	return () => convertStringToHTML(string).firstChild;
+	if (!globalThis.DOMParser) return () => string;
+	const node = convertStringToHTML(string).firstChild;
+	const importedNode = globalThis.document?.importNode(node, true);
+	return () => importedNode;
 };
 
 /**
  * Renders multiple attributes as key="value" pairs from a map of attributes
- * @param {Object.<string, any>} attributes
- * @returns {function(): string}
  */
-const spreadAttributes = (attributes) => {
-	return () => {
+export class SpreadAttributesDirective extends Directive {
+	/**
+	 * @param {Object.<string, any>} attributes
+	 */
+	update(attributes) {
+		// TODO: what if the attribute was already there..?!
+		// TODO: what if the attribute was there from a previous render/update, but not anymore?!
+		for (const name of Object.keys(attributes)) {
+			const value = attributes[name];
+			this.node.setAttribute(
+				camelToDash(name),
+				encodeAttribute(typeof value !== 'string' ? JSON.stringify(value) : value),
+			);
+		}
+	}
+
+	/**
+	 * @param {Object.<string, any>} attributes
+	 * @returns {string}
+	 */
+	stringify(attributes) {
 		return Object.keys(attributes)
-			.map((key) => {
-				let value = attributes[key];
-				return `${camelToDash(key)}='${encodeAttribute(
+			.map((name) => {
+				let value = attributes[name];
+				return `${camelToDash(name)}='${encodeAttribute(
 					typeof value !== 'string' ? JSON.stringify(value) : value,
 				)}'`;
 			})
 			.join(' ');
-	};
-};
+	}
+}
+
+/**
+ * Renders multiple attributes as key="value" pairs from a map of attributes
+ * @param {Object.<string, any>} attributes
+ */
+const spreadAttributes = defineDirective(SpreadAttributesDirective);
 
 export { classMap, styleMap, when, choose, unsafeHTML, spreadAttributes };

package/src/util/AttributeParser.js

@@ -1,23 +1,48 @@
+/**
+ * Tests if a value is of type `object`
+ * @param {any} value
+ * @returns {boolean}
+ */
 export function isObjectLike(value) {
 	return typeof value == 'object' && value !== null;
 }
 
-export function isJSON(str) {
+/**
+ * Tests if a value can be parsed as JSON
+ * @param {any} value
+ * @returns {boolean}
+ */
+export function isJSON(value) {
 	try {
-		return JSON.parse(str) && !!str;
+		return JSON.parse(value) && !!value;
 	} catch (e) {
 		return false;
 	}
 }
 
+/**
+ * Tests if a value is `boolean`
+ * @param {any} value
+ * @returns {boolean}
+ */
 export function isBoolean(value) {
 	return value === 'true' || value === 'false';
 }
 
+/**
+ * Parses a value to `boolean`
+ * @param {any} value
+ * @returns {boolean}
+ */
 export function parseBoolean(value) {
 	return value === 'true';
 }
 
+/**
+ * Tests if a value is of type `string`
+ * @param {any} value
+ * @returns {boolean}
+ */
 export function isString(value) {
 	return (
 		typeof value === 'string' ||
@@ -25,26 +50,40 @@ export function isString(value) {
 	);
 }
 
+/**
+ * Tests if a value is of type `number`
+ * @param {any} value
+ * @returns {boolean}
+ */
 export function isNumber(value) {
 	return new RegExp('^-?(0|0\\.\\d+|[1-9]\\d*(\\.\\d+)?)$').test(value);
 }
 
+/**
+ * Tests if a value is of type `NaN`
+ * @param {any} value
+ * @returns {boolean}
+ */
 export function isNaN(value) {
 	return Number.isNaN(value);
 }
 
 /**
- * deep compare two values primitive or complex
- *
- * @param valueA
- * @param valueB
+ * Compare two values (deep). It compares primitive or complex values with JSON stringify.
+ * @param {any} valueA
+ * @param {any} valueB
  * @returns {boolean}
  */
-
 export function deepEquals(valueA, valueB) {
 	return JSON.stringify(valueA) === JSON.stringify(valueB);
 }
 
+/**
+ * Parses an attribute value that comes in as a `string` to its corresponding type
+ * @param {string} value
+ * @param {PropertyOptions} options
+ * @returns {string | number | boolean | object | array}
+ */
 export function parseAttribute(value, options = {}) {
 	if (options.parse === false || !isString(value)) {
 		// no-op
@@ -67,7 +106,8 @@ export function parseAttribute(value, options = {}) {
 
 /**
  * Replaces dashed-expression (i.e. some-value) to a camel-cased expression (i.e. someValue)
- * @returns string
+ * @param {string} string
+ * @returns {string}
  */
 export function dashToCamel(string) {
 	if (string.indexOf('-') === -1) return string;
@@ -77,17 +117,16 @@ export function dashToCamel(string) {
 
 /**
  * Replaces camel-cased expression (i.e. someValue) to a dashed-expression (i.e. some-value)
- * @returns string
+ * @param {string} string
+ * @returns {string}
  */
 export function camelToDash(string) {
 	return string.replace(/([A-Z])/g, '-$1').toLowerCase();
 }
 
 /**
- * Decodes an attribute. Can only be encoded with the `encodeAttribute` method which
- * is exported from this file.
- *
- * @param attribute
+ * Decodes an attribute.
+ * @param {string} attribute
  * @returns {string}
  */
 export function decodeAttribute(attribute) {
@@ -99,14 +138,8 @@ export function decodeAttribute(attribute) {
 }
 
 /**
- * Encodes an attribute. Can only be decoded with the `decodeAttribute` method which
- * is exported from this file.
- *
- * This does not use the standard way to encode an attribute, as the dom parser
- * that renders the html would understand and automatically decode it. Which results
- * in non sanitized html output.
- *
- * @param attribute
+ * Encodes an attribute.
+ * @param {string} attribute
  * @returns {string}
  */
 export function encodeAttribute(attribute) {

package/src/util/DOMHelper.js

@@ -6,10 +6,12 @@ export const ATTRIBUTE_NODE = 2;
 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 list of (childNode) indexes for the given node
- * @param node
+ * Gets a list of (childNode) indexes for the given node
+ * @param {Node} node
  * @return {number[]}
  */
 export const getNodePath = (node) => {
@@ -23,6 +25,11 @@ export const getNodePath = (node) => {
 	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 = [];
@@ -34,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;
@@ -50,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;
@@ -58,19 +75,51 @@ 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
+			? NodeFilter.FILTER_ACCEPT
+			: NodeFilter.FILTER_REJECT,
+	);
+	const customElements = [];
+	let currentNode;
+	while ((currentNode = nodeIterator.nextNode())) {
+		customElements.push(currentNode);
+	}
+	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;
-
-// for IE11 we are using the ShadyDOM Polyfill. With the polyfill we cannot append stylesheets to the shadowRoot
-export const supportsAppendingStyleSheets = !window.ShadyDOM;
+/**
+ * Checks if adopting style sheets is supported in browser
+ * @returns {boolean}
+ */
+export const supportsAdoptingStyleSheets = () => {
+	return 'adoptedStyleSheets' in Document.prototype && 'replace' in CSSStyleSheet.prototype;
+};
 
-// better hasChildNodes check because the native check will also count for empty whitespace as child nodes... :(
+/**
+ * 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;
 
@@ -86,7 +135,7 @@ export const hasChildNodes = (node) => {
 };
 
 /**
- * Parses the given template string and returns a real DOM element.
+ * Parses the given string as HTML template and returns a real DOM element
  * @param {string} template
  * @returns {HTMLElement}
  */
@@ -97,8 +146,8 @@ export const convertStringToHTML = (template) => {
 };
 
 /**
- * Parses the given string and returns a DocumentFragment
- * which contains the DOM subtree representing the <template> element's template contents.
+ * 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}
  */
@@ -111,8 +160,8 @@ export const convertStringToTemplate = (string) => {
 
 /**
  * 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
+ * @param {Element} templateElement - The new template
+ * @param {Element} domElement - The existing DOM node
  */
 export const diffAttributes = function (templateElement, domElement) {
 	// remove or update previous attributes

package/src/util/Directive.js

@@ -2,6 +2,9 @@ export class Directive {
 	/** @type {Element} */
 	node = undefined;
 
+	/**
+	 * @param {Node} node
+	 */
 	constructor(node) {
 		this.node = node;
 	}
@@ -10,6 +13,16 @@ export class Directive {
 	 * @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 '';
+	}
 }
 
 /**

package/src/util/GlobalStylesStore.js

@@ -0,0 +1,70 @@
+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();
+				let cssText = '';
+				if (styleSheet.ownerNode.tagName === 'STYLE') {
+					cssText = styleSheet.ownerNode.textContent;
+				} else if (styleSheet.ownerNode.tagName === 'LINK') {
+					cssText = Array.from(styleSheet.cssRules)
+						.map((rule) => rule.cssText)
+						.join('');
+				}
+				cssStyleSheet.replaceSync(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);
+}