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

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 {

package/src/util/i18n.js

@@ -1,20 +0,0 @@
-/**
- * Retrieves a translated key from a dictionary on the window object
- * Example: ${i18n('CustomElement.buttonLabel', 'Label')}
- * @param key to be translated
- * @param fallback to be used if key is not defined
- * @return String of the translated key or fallback or original key
- */
-export function i18n(key, fallback) {
-	try {
-		const translations = window.elementjs.i18n();
-		if (translations[key] === undefined) {
-			throw 'Translation Missing';
-		}
-
-		return translations[key];
-	} catch (err) {
-		if (fallback) return fallback;
-		else return key;
-	}
-}