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

package/src/BaseElement.js

@@ -1,11 +1,54 @@
 import { parseAttribute, isNaN, dashToCamel, camelToDash, isObjectLike } from './util/AttributeParser.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';
 
+/**
+ * Options object for the BaseElement
+ * @typedef {Object} BaseElementOptions
+ * @property {boolean} [autoUpdate] - When set to true the element will call the requestUpdate() method on the instance every time a property or attribute was changed. This will re-evaluate everything on the element and trigger a re-render (if a template is provided) and trigger the watchers for the affected properties/attributes. Default is `true`
+ * @property {boolean} [deferUpdate] - When set to true the element will not call the requestUpdate() method upon connecting and therefore will not render (if template was provided) initially. Default is `true`
+ * @property {boolean} [deferConnected] - When set to true the element will skip the initialization in connectedCallback() before connecting and therefore will not render (if template was provided) or hydrate initially. Default is `false`
+ * @property {MutationObserverOptions} [mutationObserverOptions]
+ * @property {PropertyOptions} [propertyOptions]
+ */
+
+/**
+ * Options object for the BaseElement mutationObserverOptions option
+ * @typedef {Object} MutationObserverOptions
+ * @property {boolean} [childList] - When childList is set to true the element will also call the requestUpdate method for childList modifications (eg. Adding or removing child elements). Default is `true`
+ * @property {boolean} [subtree] - Please note that observing subtree mutations might have performance implications and use it only if necessary. Default is `false`
+ */
+
+/**
+ * Options object for the BaseElement propertyOptions option
+ * @typedef {Object} PropertyOptions
+ * @property {undefined | boolean | function} [reflect] - When set to true the element will reflect property changes back to attributes if the attribute was not present when connecting the element. By default, all attributes that are present when connecting the element will be reflected anyway. Default is `undefined`
+ * @property {undefined | boolean | function} [parse] - When set to false the element will not automatically try to parse the attributes string value to a complex type (number, array, object). Default is `undefined`
+ * @property {undefined | boolean | function} [notify] - When set to true the element will dispatch CustomEvents for every property/attribute change. The event name will be the property name all lowercase and camel to dashes with a postfix of -changed. Default is `undefined`
+ */
+
+/**
+ * Options object for updating properties
+ * @typedef {Object} PropertyUpdateOptions
+ * @property {boolean} [notify] - Whether the update should trigger the lifecycle methods. The default is `true`
+ * @property {string} property - The property name
+ * @property {any} newValue - The new value for the property
+ * @property {string} newValueString - The new value as `string` for the property (for comparison reasons)
+ * @property {any} oldValue - The old value for the property
+ */
+
+/**
+ * @implements {Serializable}
+ */
 class BaseElement extends HTMLElement {
+	_serializationKey;
+
+	/**
+	 * @param {BaseElementOptions} options
+	 */
 	constructor(options = {}) {
 		super();
 		this.$refs = {};
@@ -27,37 +70,40 @@ class BaseElement extends HTMLElement {
 			propertyOptions: {},
 			...options,
 		};
+	}
 
+	/**
+	 * Overrides the native `connectedCallback` of the HTMLElement to set up and initialize our element.
+	 * This will define the attributes and properties as reactive getters and setter,
+	 * register observers, refs and events.
+	 */
+	connectedCallback() {
 		if (this.hasAttribute('defer-update')) {
 			this._options.deferUpdate = true;
 		}
-		if (this.hasAttribute('defer-connected')) {
-			this._options.deferConnected = true;
-		}
 
-		if (options.childListUpdate !== undefined && options.childListUpdate !== null) {
-			this._options.mutationObserverOptions.childList = options.childListUpdate;
-			console.warn(
-				`[${this.localName}] Using the "childListUpdate" option is deprecated and will be removed before 1.0! Please use the "mutationObserverOptions" dictionary instead. See the docs for more info`,
-			);
-		}
-	}
-
-	connectedCallback() {
-		if (this._options.deferConnected) {
+		if (this.hasAttribute('defer-connected') || this._options.deferConnected) {
 			this._options.deferConnected = false;
+			this.removeAttribute('defer-connected');
 			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();
 
 		// define all properties to "this"
 		this.defineProperties();
 
-		// define all computed properties to "this"
-		this.defineComputedProperties();
-
 		// define context
 		this.definePropertyInjection();
 
@@ -65,17 +111,21 @@ class BaseElement extends HTMLElement {
 		this.defineObserver();
 
 		if (this._options.deferUpdate) {
-			// don't updates/render, but register refs and events
+			// don't update/render, but register refs and events
 			this.registerEventsAndRefs();
 
 			this.triggerHook('connected');
 		} else {
 			this.requestUpdate({ notify: false }).then(() => {
 				this.triggerHook('connected');
+				this.triggerHook('afterUpdate');
 			});
 		}
 	}
 
+	/**
+	 * Define a MutationObserver on the element to get notified on attribute changes and childList updates according to the options specified via the constructor options.
+	 */
 	defineObserver() {
 		// see: https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver#Example_usage
 		this._mutationObserver = new MutationObserver((mutations) => {
@@ -108,6 +158,9 @@ class BaseElement extends HTMLElement {
 		});
 	}
 
+	/**
+	 * Native `disconnectedCallback` of the HTMLElement
+	 */
 	disconnectedCallback() {
 		// remove events for elements in the component
 		this.removeEvents();
@@ -129,6 +182,11 @@ class BaseElement extends HTMLElement {
 		this.triggerHook('disconnected');
 	}
 
+	/**
+	 * Request and batch an asynchronous update cycle
+	 * @param {PropertyUpdateOptions} options
+	 * @returns {Promise<unknown>}
+	 */
 	requestUpdate(options = { notify: true }) {
 		if (options.notify === true) {
 			this.triggerHook('beforeUpdate');
@@ -158,6 +216,7 @@ class BaseElement extends HTMLElement {
 	 * This should be called by the template component AFTER adding the template to
 	 * the DOM.
 	 * Here we will register the events and the refs for the element.
+	 * @param {PropertyUpdateOptions} options
 	 */
 	update(options = { notify: true }) {
 		this.registerEventsAndRefs();
@@ -224,12 +283,11 @@ class BaseElement extends HTMLElement {
 	 * Define a property on the element
 	 * Will trigger watch() function when a property was changed
 	 * Will trigger update() when a property was changed
+	 * @param {string} property
+	 * @param {any} value
+	 * @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;
@@ -245,8 +303,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];
@@ -257,6 +323,8 @@ class BaseElement extends HTMLElement {
 				if (JSON.stringify(oldValue) !== newValueString) {
 					this._state[property] = newValue;
 
+					serializeState(this);
+
 					if (newValue instanceof Store) {
 						newValue.subscribe(this);
 					}
@@ -287,12 +355,10 @@ class BaseElement extends HTMLElement {
 	}
 
 	/**
-	 * call the watch callbacks on property changes
-	 *
-	 * @param context is the elements instance
-	 * @param property property that changes
-	 * @param newValue
-	 * @param oldValue
+	 * Call the watch callbacks on property changes
+	 * @param {string} property property that changes
+	 * @param {any} newValue
+	 * @param {any} oldValue
 	 */
 	callPropertyWatcher(property, newValue, oldValue) {
 		// notify watched properties (after update())
@@ -303,11 +369,9 @@ class BaseElement extends HTMLElement {
 	}
 
 	/**
-	 * notify property observer via change event
-	 *
-	 * @param context is the elements instance
-	 * @param property property that changes
-	 * @param newValue
+	 * Notify property observer via change event
+	 * @param {string} property property that changes
+	 * @param {any} newValue
 	 */
 	notifyPropertyChange(property, newValue) {
 		// dispatch change event
@@ -315,10 +379,14 @@ class BaseElement extends HTMLElement {
 			property in this._options['propertyOptions'] &&
 			this._options['propertyOptions'][property]['notify'] === true
 		) {
-			this.dispatch(`${camelToDash(property)}-changed`, newValue, true);
+			this.dispatch(`${camelToDash(property)}-changed`, newValue);
 		}
 	}
 
+	/**
+	 * Reflects a property as attribute on the element
+	 * @param {PropertyUpdateOptions} options
+	 */
 	reflectProperty(options) {
 		const { property, newValue } = options;
 		const newValueString = options.newValueString || JSON.stringify(newValue);
@@ -380,20 +448,18 @@ class BaseElement extends HTMLElement {
 
 	/**
 	 * Helper Function to initialize the context requests
-	 *
-	 * @param propertyName
-	 * @param valueOrCallback
+	 * @param {string} propertyName
+	 * @param {any | function} valueOrCallback
 	 */
 	requestContext(propertyName, valueOrCallback) {
-		this.dispatch('request-context', { [propertyName]: valueOrCallback }, true, true, true);
+		this.dispatch('request-context', { [propertyName]: valueOrCallback });
 	}
 
 	/**
 	 * Internal Context Request Handler
 	 * This will check if the current/receiving instance actually provides a value under the requested name.
 	 * If there is something to provide it will either assign the value to the requesting element or call the callback.
-	 *
-	 * @param event
+	 * @param {CustomEvent} event
 	 */
 	onRequestContext(event) {
 		const provideProperties = this.provideProperties();
@@ -416,33 +482,31 @@ class BaseElement extends HTMLElement {
 		});
 	}
 
-	// Deprecated
-	hooks() {
-		return {};
-	}
-
-	// Connected lifecycle hook
+	/**
+	 * Connected lifecycle hook
+	 */
 	connected() {}
 
-	// BeforeUpdate lifecycle hook
+	/**
+	 * BeforeUpdate lifecycle hook
+	 */
 	beforeUpdate() {}
 
-	// AfterUpdate lifecycle hook
+	/**
+	 * AfterUpdate lifecycle hook
+	 */
 	afterUpdate() {}
 
-	// Disconnected lifecycle hook
+	/**
+	 * Disconnected lifecycle hook
+	 */
 	disconnected() {}
 
-	// Triggers a lifecycle hook based on the name
+	/**
+	 * Triggers a lifecycle hook based on the name
+	 * @param {string} name
+	 */
 	triggerHook(name) {
-		if (this.hooks && name in this.hooks()) {
-			console.warn(
-				`[${this.localName}] Using the hooks() map for lifecycle hooks is deprecated! Please overwrite the existing lifecycle hook functions. See the docs for more info`,
-			);
-			this.hooks()[name]();
-			return;
-		}
-
 		if (name in this) {
 			this[name]();
 		}
@@ -459,25 +523,6 @@ class BaseElement extends HTMLElement {
 		return {};
 	}
 
-	// Deprecated
-	computed() {
-		return {};
-	}
-
-	// Deprecated
-	defineComputedProperties() {
-		Object.keys(this.computed()).forEach((prop) => {
-			if (!this.hasOwnProperty(prop)) {
-				console.warn(
-					`[${this.localName}] Using the computed() map for computed properties is deprecated! Please use regular JS getters and return the computed value. See the docs for more info`,
-				);
-				Object.defineProperty(this, prop, {
-					get: () => this.computed()[prop](),
-				});
-			}
-		});
-	}
-
 	/**
 	 * Return a map of events that should be registered on the element.
 	 * eg. { '.link': {
@@ -570,21 +615,66 @@ class BaseElement extends HTMLElement {
 		this.$refs = refsMap;
 	}
 
-	// Helper function for dispatching custom events
-	dispatch(name, data, bubble = false, cancelable = false, composed = false) {
-		const event = new CustomEvent(name, {
-			bubbles: bubble,
-			cancelable: cancelable,
-			composed: composed,
-			detail: data,
-		});
+	/**
+	 * Helper function for dispatching custom events
+	 * @param {string} name
+	 * @param {Object} [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);
 	}
 
-	// Get the root element
+	/**
+	 * Get the root element
+	 * @returns {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,21 +1,20 @@
 import { BaseElement } from './BaseElement.js';
 import { supportsAdoptingStyleSheets, getShadowParentOrBody } from './util/DOMHelper.js';
-export { i18n } from './util/i18n.js';
+import { globalStylesStore } from './util/GlobalStylesStore.js';
 
-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 = document.getElementById('globalStyles');
-
-		if (StyledElement.globalStyles && StyledElement['globalStyleSheet']) {
-			//updates already adopted global styles
-			StyledElement['globalStyleSheet'].replaceSync(StyledElement.globalStyles.textContent);
-		}
-	}
+/**
+ * Options object for the StyledElement
+ * @typedef {Object} StyledElementOptions
+ * @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 | 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 {
+	/**
+	 * @param {StyledElementOptions} options
+	 */
 	constructor(options) {
 		super({
 			deferUpdate: false,
@@ -27,84 +26,96 @@ class StyledElement extends BaseElement {
 		this._styles = [...this._options.styles, ...this.styles()];
 	}
 
+	/**
+	 * Overrides the `connectedCallback` to adopt optional styles when the element is connected
+	 */
 	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();
-		} else if (this._options.shadowRender && window.ShadyCSS !== undefined) {
-			// if shadowRoot is polyfilled we use ShadyCSS to copy scoped styles to <head>
-			window.ShadyCSS.ScopingShim.prepareAdoptedCssText(this._styles, this.localName);
-		}
 
-		// if shadowRoot is polyfilled - scope element template
-		if (window.ShadyCSS !== undefined) {
-			window.ShadyCSS.styleElement(this);
+			if (this._options.adoptGlobalStyles !== false) {
+				globalStylesStore.subscribe(() => {
+					this.adoptStyleSheets();
+				});
+			}
 		}
 	}
 
+	/**
+	 * The styles method is another way to return a list of styles to be adopted when the element is connected.
+	 * You can either provide a list in the constructor options or return it here.
+	 * @returns {string[]}
+	 */
 	styles() {
 		return [];
 	}
 
+	/**
+	 * Overrides the `update` method to adopt optional styles
+	 * @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 && !window.ShadyCSS) {
-				appendableStyles.unshift(StyledElement.globalStyles?.textContent ?? '');
-			}
-			this.appendStyleSheets(appendableStyles);
+			this.appendStyleSheets();
 		}
 		super.update(options);
 	}
 
+	/**
+	 * 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
-	appendStyleSheets(styles) {
+	/**
+	 * Custom polyfill for constructable stylesheets by appending styles to the end of an element
+	 */
+	appendStyleSheets() {
 		const parentDocument = getShadowParentOrBody(this.getRoot());
-		styles.forEach((style, index) => {
+
+		const adoptGlobalStyleSheets =
+			this._options.shadowRender &&
+			this._options.adoptGlobalStyles !== false &&
+			parentDocument !== globalThis.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
 			if (!parentDocument.querySelector(`#${identifier}`)) {
-				const styleElement = document.createElement('style');
+				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,9 +1,17 @@
 import { StyledElement } from './StyledElement.js';
-import { html } from 'lit-html';
-import { render } from 'lit-html/lib/shady-render.js';
-export { i18n } from './util/i18n.js';
+import { html } from './dom-parts/html.js';
+import { render } from './dom-parts/render.js';
+
+/**
+ * Options object for the TemplateElement
+ * @typedef {Object} TemplateElementOptions
+ * @extends StyledElementOptions
+ */
 
 class TemplateElement extends StyledElement {
+	/**
+	 * @param {TemplateElementOptions} options
+	 */
 	constructor(options) {
 		super({
 			deferUpdate: false,
@@ -16,33 +24,51 @@ class TemplateElement extends StyledElement {
 			...options,
 		});
 		this._template = this._options.template;
+	}
 
+	/**
+	 * Overrides the native `connectedCallback` of the HTMLElement to set up and initialize our element.
+	 * This will attach a shadow DOM if the element is supposed to render in shadow DOM.
+	 */
+	connectedCallback() {
 		if (this._options.shadowRender) this.attachShadow({ mode: 'open' });
+		super.connectedCallback();
 	}
 
+	/**
+	 * The template method should be overridden in extending elements and return the template to be rendered to the root
+	 * @returns {TemplateResult}
+	 */
 	template() {
 		return html``;
 	}
 
+	/**
+	 * Override update method to render the template to the root
+	 * @param {PropertyUpdateOptions} options
+	 */
 	update(options) {
 		this.renderTemplate();
 		super.update(options);
 	}
 
+	/**
+	 * Render the template to the root
+	 */
 	renderTemplate() {
 		const template = this._template || this.template();
 		if (typeof template === 'string') {
 			// just a plain string literal. no lit-html required
 			this.getRoot().innerHTML = `${template}`;
 		} else {
-			// render via lit-html
-			render(html` ${template} `, this.getRoot(), {
-				scopeName: this.localName,
-				eventContext: this,
-			});
+			render(template, this.getRoot());
 		}
 	}
 
+	/**
+	 * Get the root element - either the element or the shadow root
+	 * @returns {ShadowRoot | HTMLElement}
+	 */
 	getRoot() {
 		return this.shadowRoot !== null ? this.shadowRoot : this;
 	}