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

package/index.js

@@ -3,8 +3,14 @@ import { StyledElement } from './src/StyledElement.js';
 import { TemplateElement, html } from './src/TemplateElement.js';
 import { toString } from './src/util/toString.js';
 import { defineElement } from './src/util/defineElement.js';
-import { i18n } from './src/util/i18n.js';
 import { Store } from './src/util/Store.js';
 import { Directive } from './src/util/Directive.js';
 
-export { BaseElement, StyledElement, TemplateElement, Store, Directive, html, toString, defineElement, i18n };
+/**
+ * Options object for element-js
+ * @typedef {Object} ElementJsConfig
+ * @property {boolean} [serializeState] - When set to true all elements and stores will serialize their state on changes to a global JSON object in the document. This is needed when rendering server side, so that elements and stores can hydrate with the correct state.
+ * @property {boolean} [observeGlobalStyles] - By default element-js will look for all style elements in the global document and apply them before any custom/element styles inside the shadow DOM. When set to true element-js will also observe the document for any changes regarding styles. This is needed if styles will get added async or late.
+ */
+
+export { BaseElement, StyledElement, TemplateElement, Store, Directive, html, toString, defineElement };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@webtides/element-js",
-	"version": "1.0.0-alpha.2",
+	"version": "1.0.0-alpha.3",
 	"module": "index.js",
 	"main": "dist/index.js",
 	"type": "module",

package/src/BaseElement.js

@@ -1,7 +1,7 @@
 import { parseAttribute, isNaN, dashToCamel, camelToDash, isObjectLike } from './util/AttributeParser.js';
-import { getClosestParentCustomElementNode, isOfSameNodeType } from './util/DOMHelper.js';
+import { getAllElementChildren, getClosestParentCustomElementNode, isOfSameNodeType } from './util/DOMHelper.js';
 import { Store } from './util/Store.js';
-
+import { serializeState, deserializeState, hasSerializedState } from './util/SerializeStateHelper.js';
 export { defineElement } from './util/defineElement.js';
 export { toString } from './util/toString.js';
 
@@ -39,7 +39,12 @@ export { toString } from './util/toString.js';
  * @property {any} oldValue - The old value for the property
  */
 
+/**
+ * @implements {Serializable}
+ */
 class BaseElement extends HTMLElement {
+	_serializationKey;
+
 	/**
 	 * @param {BaseElementOptions} options
 	 */
@@ -54,6 +59,7 @@ class BaseElement extends HTMLElement {
 		this._options = {
 			autoUpdate: true,
 			deferUpdate: true,
+			deferConnected: false,
 			mutationObserverOptions: {
 				attributes: true,
 				childList: true,
@@ -63,6 +69,13 @@ class BaseElement extends HTMLElement {
 			propertyOptions: {},
 			...options,
 		};
+
+		if (this.hasAttribute('defer-update')) {
+			this._options.deferUpdate = true;
+		}
+		if (this.hasAttribute('defer-connected')) {
+			this._options.deferConnected = true;
+		}
 	}
 
 	/**
@@ -71,6 +84,21 @@ class BaseElement extends HTMLElement {
 	 * register observers, refs and events.
 	 */
 	connectedCallback() {
+		if (this._options.deferConnected) {
+			this._options.deferConnected = false;
+			return;
+		}
+
+		if (this.hasAttribute('ejs:key')) {
+			this._serializationKey = this.getAttribute('ejs:key');
+			deserializeState(this);
+		} else {
+			this._serializationKey = globalThis.crypto.randomUUID();
+			if (globalThis.elementJsConfig?.serializeState) {
+				this.setAttribute('ejs:key', this._serializationKey);
+			}
+		}
+
 		// define all attributes to "this" as properties
 		this.defineAttributesAsProperties();
 
@@ -261,10 +289,6 @@ class BaseElement extends HTMLElement {
 	 * @param {boolean} reflectAttribute
 	 */
 	defineProperty(property, value, reflectAttribute = false) {
-		if (value instanceof Store) {
-			value.subscribe(this);
-		}
-
 		if (this._state.hasOwnProperty(property)) {
 			// property has already been defined as an attribute nothing to do here
 			return;
@@ -280,8 +304,16 @@ class BaseElement extends HTMLElement {
 			this.removeAttribute(camelToDash(property));
 		}
 
+		if (hasSerializedState(this._serializationKey) && Object.keys(this.serializeState())?.includes(property)) {
+			value = this[property];
+		}
+
 		this._state[property] = value;
 
+		if (this._state[property] instanceof Store) {
+			this._state[property].subscribe(this);
+		}
+
 		Object.defineProperty(this, property, {
 			get: () => {
 				return this._state[property];
@@ -292,6 +324,8 @@ class BaseElement extends HTMLElement {
 				if (JSON.stringify(oldValue) !== newValueString) {
 					this._state[property] = newValue;
 
+					serializeState(this);
+
 					if (newValue instanceof Store) {
 						newValue.subscribe(this);
 					}
@@ -395,8 +429,21 @@ class BaseElement extends HTMLElement {
 			this.requestContext(key, value);
 		});
 		// define context provider
-		if (Object.keys(this.provideProperties()).length > 0) {
+		const providedKeys = Object.keys(this.provideProperties());
+		if (providedKeys.length > 0) {
 			this.addEventListener('request-context', this.onRequestContext);
+			// check if there are already connected elements in child dom and restart requests
+			getAllElementChildren(this.getRoot(), BaseElement).forEach((customChild) => {
+				// if injectProperties?.() is defined it means that the child got connected BEFORE the parent (Runtime Issue)
+				const requestedProperties = customChild.injectProperties?.() ?? {};
+				Object.entries(requestedProperties).forEach(([key, value]) => {
+					// iterate over requested properties to find missed context requests
+					if (providedKeys.includes(key)) {
+						// owns the provided  key -> replay request
+						customChild.requestContext(key, value);
+					}
+				});
+			});
 		}
 	}
 
@@ -406,7 +453,7 @@ class BaseElement extends HTMLElement {
 	 * @param {any | function} valueOrCallback
 	 */
 	requestContext(propertyName, valueOrCallback) {
-		this.dispatch('request-context', { [propertyName]: valueOrCallback }, true);
+		this.dispatch('request-context', { [propertyName]: valueOrCallback }, true, true, true);
 	}
 
 	/**
@@ -416,7 +463,6 @@ class BaseElement extends HTMLElement {
 	 * @param {CustomEvent} event
 	 */
 	onRequestContext(event) {
-		const properties = this.properties();
 		const provideProperties = this.provideProperties();
 
 		Object.entries(event.detail ?? {}).forEach(([key, valueOrCallback]) => {
@@ -429,7 +475,9 @@ class BaseElement extends HTMLElement {
 					valueOrCallback(providedValue);
 				} else {
 					// assign to prop
-					event.target[key] = providedValue;
+					const eventPath = event.composedPath();
+					const target = eventPath[0] || event.target;
+					target[key] = providedValue;
 				}
 			}
 		});
@@ -572,17 +620,32 @@ class BaseElement extends HTMLElement {
 	 * Helper function for dispatching custom events
 	 * @param {string} name
 	 * @param {Object} data
-	 * @param {boolean} bubble
-	 * @param {boolean} cancelable
-	 * @param {boolean} composed
-	 */
-	dispatch(name, data, bubble = false, cancelable = false, composed = false) {
-		const event = new CustomEvent(name, {
-			bubbles: bubble,
-			cancelable: cancelable,
-			composed: composed,
-			detail: data,
-		});
+	 * @param {CustomEventInit} options
+	 * @param {boolean} cancelable - DEPRECATED
+	 * @param {boolean} composed - DEPRECATED
+	 */
+	dispatch(name, data, options, cancelable = false, composed = false) {
+		let eventInit = {};
+
+		if (options !== undefined && typeof options === 'boolean') {
+			eventInit['bubbles'] = options;
+			eventInit['cancelable'] = cancelable;
+			eventInit['composed'] = composed;
+			eventInit['detail'] = data;
+			console.warn(
+				`[${this.localName}] Using the old parameter options for the event is deprecated and will be removed in v2.0! Please use the new options object that is in line with the "CustomEventInit" options`,
+			);
+		} else {
+			eventInit = {
+				bubbles: true,
+				cancelable: true,
+				composed: true,
+				detail: data,
+				...options,
+			};
+		}
+
+		const event = new CustomEvent(name, eventInit);
 		this.dispatchEvent(event);
 	}
 
@@ -593,6 +656,26 @@ class BaseElement extends HTMLElement {
 	getRoot() {
 		return this;
 	}
+
+	/**
+	 * This method will be used to serialize this elements 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 element 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);
+	}
 }
 
 export { BaseElement, getClosestParentCustomElementNode, isOfSameNodeType };

package/src/StyledElement.js

@@ -1,6 +1,6 @@
 import { BaseElement } from './BaseElement.js';
 import { supportsAdoptingStyleSheets, getShadowParentOrBody } from './util/DOMHelper.js';
-export { i18n } from './util/i18n.js';
+import { globalStylesStore } from './util/GlobalStylesStore.js';
 
 /**
  * Options object for the StyledElement
@@ -8,23 +8,10 @@ export { i18n } from './util/i18n.js';
  * @extends BaseElementOptions
  * @property {boolean} [shadowRender] - When set to true the element will render the template (if provided) in the Shadow DOM and therefore encapsulate the element and styles from the rest of the document. Default is `false`
  * @property {[]} [styles] - Via the styles option you can add multiple styles/stylesheets to your element. Default is `[]`
- * @property {boolean} [adoptGlobalStyles] - When set to true element-js will look for a style element in the global document with an id of "globalStyles" and apply it before any custom/element styles inside the shadow DOM. Default is `true`
+ * @property {boolean | string | string[]} [adoptGlobalStyles] - When set to true element-js will look for all style elements in the global document with and apply them before any custom/element styles inside the shadow DOM. Default is `true`.
  */
 
 class StyledElement extends BaseElement {
-	static globalStyles = null;
-
-	static updateGlobalStyles() {
-		// this is a runtime dependency so that every shadow dom can make use of global css
-		// we assume these styles to be inlined into the document
-		StyledElement.globalStyles = globalThis.document?.getElementById('globalStyles');
-
-		if (StyledElement.globalStyles && StyledElement['globalStyleSheet']) {
-			//updates already adopted global styles
-			StyledElement['globalStyleSheet'].replaceSync(StyledElement.globalStyles.textContent);
-		}
-	}
-
 	/**
 	 * @param {StyledElementOptions} options
 	 */
@@ -45,9 +32,23 @@ class StyledElement extends BaseElement {
 	connectedCallback() {
 		super.connectedCallback();
 
+		if (!this.constructor['elementStyleSheets']) {
+			this.constructor['elementStyleSheets'] = this._styles.map((style) => {
+				const cssStyleSheet = new CSSStyleSheet();
+				cssStyleSheet.replaceSync(style);
+				return cssStyleSheet;
+			});
+		}
+
 		if (supportsAdoptingStyleSheets() && this._options.shadowRender) {
 			// adopting does only make sense in shadow dom. Fall back to append for light elements
 			this.adoptStyleSheets();
+
+			if (this._options.adoptGlobalStyles !== false) {
+				globalStylesStore.subscribe(() => {
+					this.adoptStyleSheets();
+				});
+			}
 		}
 	}
 
@@ -65,13 +66,9 @@ class StyledElement extends BaseElement {
 	 * @param {PropertyUpdateOptions} options
 	 */
 	update(options) {
+		// We cannot do this in connectedCallback() since the whole template will be overridden in update/render afterward
 		if (!supportsAdoptingStyleSheets() || this._options.shadowRender === false) {
-			// append stylesheets to template if not already adopted
-			const appendableStyles = [...this._styles];
-			if (this._options.shadowRender && this._options.adoptGlobalStyles) {
-				appendableStyles.unshift(StyledElement.globalStyles?.textContent ?? '');
-			}
-			this.appendStyleSheets(appendableStyles);
+			this.appendStyleSheets();
 		}
 		super.update(options);
 	}
@@ -80,39 +77,29 @@ class StyledElement extends BaseElement {
 	 * Adopt stylesheets
 	 */
 	adoptStyleSheets() {
-		if (!this.constructor['cssStyleSheets']) {
-			this.constructor['cssStyleSheets'] = this._styles.map((style) => {
-				const sheet = new CSSStyleSheet();
-				if (sheet && sheet.cssRules.length === 0) {
-					sheet.replaceSync(style);
-				}
-				return sheet;
-			});
-		}
-
-		if (StyledElement.globalStyles && !StyledElement['globalStyleSheet']) {
-			StyledElement['globalStyleSheet'] = new CSSStyleSheet();
-			StyledElement['globalStyleSheet'].replaceSync(StyledElement.globalStyles.textContent);
-		}
+		const adoptGlobalStyleSheets = this._options.shadowRender && this._options.adoptGlobalStyles !== false;
 
-		// adopt styles
-		// uses proposed solution for constructable stylesheets
-		// see: https://wicg.github.io/construct-stylesheets/#proposed-solution
 		this.getRoot().adoptedStyleSheets = [
-			...(this._options.shadowRender && this._options.adoptGlobalStyles && StyledElement['globalStyleSheet']
-				? [StyledElement['globalStyleSheet']]
-				: []),
-			...this.constructor['cssStyleSheets'],
+			...(adoptGlobalStyleSheets ? globalStylesStore.getGlobalStyleSheets(this._options.adoptGlobalStyles) : []),
+			...this.constructor['elementStyleSheets'],
 		];
 	}
 
 	/**
 	 * Custom polyfill for constructable stylesheets by appending styles to the end of an element
-	 * @param {string[]} styles
 	 */
-	appendStyleSheets(styles) {
+	appendStyleSheets() {
 		const parentDocument = getShadowParentOrBody(this.getRoot());
-		styles.forEach((style, index) => {
+
+		const adoptGlobalStyleSheets =
+			this._options.shadowRender && this._options.adoptGlobalStyles !== false && parentDocument !== document.body;
+
+		const appendableStyles = [
+			...(adoptGlobalStyleSheets ? globalStylesStore.getGlobalStyleSheets(this._options.adoptGlobalStyles) : []),
+			...this.constructor['elementStyleSheets'],
+		];
+
+		appendableStyles.forEach((styleSheet, index) => {
 			const identifier = this.tagName + index;
 
 			// only append stylesheet if not already appended to shadowRoot or document
@@ -120,13 +107,13 @@ class StyledElement extends BaseElement {
 				const styleElement = globalThis.document?.createElement('style');
 				styleElement.id = identifier;
 				styleElement.style.display = 'none';
-				styleElement.textContent = style;
+				styleElement.textContent = Array.from(styleSheet.cssRules)
+					.map((rule) => rule.cssText)
+					.join('');
 				parentDocument.appendChild(styleElement);
 			}
 		});
 	}
 }
 
-StyledElement.updateGlobalStyles();
-
 export { StyledElement };

package/src/TemplateElement.js

@@ -1,7 +1,6 @@
 import { StyledElement } from './StyledElement.js';
 import { html } from './dom-parts/html.js';
 import { render } from './dom-parts/render.js';
-export { i18n } from './util/i18n.js';
 
 /**
  * Options object for the TemplateElement

package/src/util/DOMHelper.js

@@ -75,6 +75,26 @@ 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

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);
+}