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

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,63 @@
-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;
+
+			if (value instanceof Store) {
+				value.subscribe(this);
+			}
 
-		Object.entries(this._state).map(([key, value]) => {
 			Object.defineProperty(this, key, {
 				get: () => {
 					return this._state[key];
@@ -20,6 +65,11 @@ export class Store {
 				set: (newValue) => {
 					const oldValue = this._state[key];
 					this._state[key] = newValue;
+					if (value instanceof Store) {
+						value.subscribe(this);
+					}
+
+					serializeState(this);
 
 					if (!deepEquals(newValue, oldValue)) {
 						const watch = this.watch();
@@ -31,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 {};
 	}
@@ -40,47 +97,66 @@ 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}`;
 	}
 
 	/**
-	 * @param {BaseElement|Function} observer
+	 * 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) {
-				await observer.requestUpdate();
+			if (observer instanceof BaseElement || observer instanceof Store) {
+				if (observer?._options?.autoUpdate !== false) {
+					await observer.requestUpdate();
+				}
 				// check if store is watched by an observer
 				if (Object.keys(observer.watch() ?? {}).length > 0) {
 					// observer actually has watched properties
-					const properties = observer.properties();
 					Object.keys(observer.watch() ?? {}).forEach((key) => {
 						if (observer._state[key] === this) {
 							// observer is actually watching store changes provide new and old values
-							observer.callPropertyWatcher(key, this, this);
-							observer.notifyPropertyChange(key, this);
+							if (observer instanceof Store) {
+								// observer is a foreign store / call watcher
+								observer.watch?.()[key](this, this);
+							} else {
+								observer.callPropertyWatcher(key, this, this);
+								observer.notifyPropertyChange(key, this);
+							}
 						}
 					});
 				}
@@ -91,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 {