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

package/src/BaseElement.js

@@ -5,7 +5,44 @@ import { Store } from './util/Store.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 {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
+ */
+
 class BaseElement extends HTMLElement {
+	/**
+	 * @param {BaseElementOptions} options
+	 */
 	constructor(options = {}) {
 		super();
 		this.$refs = {};
@@ -28,6 +65,11 @@ class BaseElement extends HTMLElement {
 		};
 	}
 
+	/**
+	 * 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() {
 		// define all attributes to "this" as properties
 		this.defineAttributesAsProperties();
@@ -54,6 +96,9 @@ class BaseElement extends HTMLElement {
 		}
 	}
 
+	/**
+	 * 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) => {
@@ -86,6 +131,9 @@ class BaseElement extends HTMLElement {
 		});
 	}
 
+	/**
+	 * Native `disconnectedCallback` of the HTMLElement
+	 */
 	disconnectedCallback() {
 		// remove events for elements in the component
 		this.removeEvents();
@@ -107,6 +155,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');
@@ -136,6 +189,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();
@@ -202,6 +256,9 @@ 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) {
@@ -265,12 +322,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())
@@ -279,12 +334,11 @@ class BaseElement extends HTMLElement {
 			watch[property](newValue, oldValue);
 		}
 	}
+
 	/**
-	 * 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
@@ -296,6 +350,10 @@ class BaseElement extends HTMLElement {
 		}
 	}
 
+	/**
+	 * Reflects a property as attribute on the element
+	 * @param {PropertyUpdateOptions} options
+	 */
 	reflectProperty(options) {
 		const { property, newValue } = options;
 		const newValueString = options.newValueString || JSON.stringify(newValue);
@@ -344,9 +402,8 @@ 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);
@@ -356,8 +413,7 @@ class BaseElement extends HTMLElement {
 	 * 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 properties = this.properties();
@@ -379,19 +435,30 @@ class BaseElement extends HTMLElement {
 		});
 	}
 
-	// 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 (name in this) {
 			this[name]();
@@ -501,7 +568,14 @@ class BaseElement extends HTMLElement {
 		this.$refs = refsMap;
 	}
 
-	// Helper function for dispatching custom events
+	/**
+	 * 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,
@@ -512,7 +586,10 @@ class BaseElement extends HTMLElement {
 		this.dispatchEvent(event);
 	}
 
-	// Get the root element
+	/**
+	 * Get the root element
+	 * @returns {HTMLElement}
+	 */
 	getRoot() {
 		return this;
 	}

package/src/StyledElement.js

@@ -2,13 +2,22 @@ import { BaseElement } from './BaseElement.js';
 import { supportsAdoptingStyleSheets, getShadowParentOrBody } from './util/DOMHelper.js';
 export { i18n } from './util/i18n.js';
 
+/**
+ * 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} [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`
+ */
+
 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');
+		StyledElement.globalStyles = globalThis.document?.getElementById('globalStyles');
 
 		if (StyledElement.globalStyles && StyledElement['globalStyleSheet']) {
 			//updates already adopted global styles
@@ -16,6 +25,9 @@ class StyledElement extends BaseElement {
 		}
 	}
 
+	/**
+	 * @param {StyledElementOptions} options
+	 */
 	constructor(options) {
 		super({
 			deferUpdate: false,
@@ -27,6 +39,9 @@ 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();
 
@@ -36,10 +51,19 @@ class StyledElement extends BaseElement {
 		}
 	}
 
+	/**
+	 * 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) {
 		if (!supportsAdoptingStyleSheets() || this._options.shadowRender === false) {
 			// append stylesheets to template if not already adopted
@@ -52,6 +76,9 @@ class StyledElement extends BaseElement {
 		super.update(options);
 	}
 
+	/**
+	 * Adopt stylesheets
+	 */
 	adoptStyleSheets() {
 		if (!this.constructor['cssStyleSheets']) {
 			this.constructor['cssStyleSheets'] = this._styles.map((style) => {
@@ -79,7 +106,10 @@ class StyledElement extends BaseElement {
 		];
 	}
 
-	// custom polyfill for constructable stylesheets by appending styles to the end of an element
+	/**
+	 * Custom polyfill for constructable stylesheets by appending styles to the end of an element
+	 * @param {string[]} styles
+	 */
 	appendStyleSheets(styles) {
 		const parentDocument = getShadowParentOrBody(this.getRoot());
 		styles.forEach((style, index) => {
@@ -87,7 +117,7 @@ class StyledElement extends BaseElement {
 
 			// 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;

package/src/TemplateElement.js

@@ -3,7 +3,16 @@ 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
+ * @typedef {Object} TemplateElementOptions
+ * @extends StyledElementOptions
+ */
+
 class TemplateElement extends StyledElement {
+	/**
+	 * @param {TemplateElementOptions} options
+	 */
 	constructor(options) {
 		super({
 			deferUpdate: false,
@@ -20,15 +29,26 @@ class TemplateElement extends StyledElement {
 		if (this._options.shadowRender) this.attachShadow({ mode: 'open' });
 	}
 
+	/**
+	 * 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') {
@@ -39,6 +59,10 @@ class TemplateElement extends StyledElement {
 		}
 	}
 
+	/**
+	 * Get the root element - either the element or the shadow root
+	 * @returns {ShadowRoot | HTMLElement}
+	 */
 	getRoot() {
 		return this.shadowRoot !== null ? this.shadowRoot : this;
 	}

package/src/dom-parts/TemplateResult.js

@@ -213,7 +213,8 @@ export class TemplateResult {
 					// TODO: we currently cannot distinguish between NodeParts and AttributeParts before
 					if (isObjectLike(value) && value.directiveClass) {
 						// NodePart
-						// result += encodeAttribute(isObjectLike(value) ? JSON.stringify(value) : value);
+						const directive = new value.directiveClass();
+						result += directive.stringify(...value.values);
 					} else if (value != null) {
 						result += encodeAttribute(isObjectLike(value) ? JSON.stringify(value) : value);
 					}

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) {