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

package/src/util/DOMHelper.js

@@ -1,3 +1,35 @@
+/* An Element node like <p> or <div> */
+export const ELEMENT_NODE = 1;
+/* An Attribute of an Element */
+export const ATTRIBUTE_NODE = 2;
+/* The actual Text inside an Element or Attr */
+export const TEXT_NODE = 3;
+/* A Comment node, such as <!-- … --> */
+export const COMMENT_NODE = 8;
+/* A Document Fragment, a document without a parent */
+export const DOCUMENT_FRAGMENT_NODE = 11;
+
+/**
+ * Gets a list of (childNode) indexes for the given node
+ * @param {Node} node
+ * @return {number[]}
+ */
+export const getNodePath = (node) => {
+	const path = [];
+	let parentNode = node.parentNode;
+	while (parentNode) {
+		path.push([...parentNode.childNodes].indexOf(node));
+		node = parentNode;
+		parentNode = node.parentNode;
+	}
+	return path;
+};
+
+/**
+ * Get a list of all parent nodes up the DOM tree
+ * @param {Node} domNode
+ * @returns {Node[]}
+ */
 export function getAllParentNodes(domNode) {
 	let node = domNode.parentElement;
 	let parents = [];
@@ -9,7 +41,12 @@ export function getAllParentNodes(domNode) {
 	return parents;
 }
 
-// https://stackoverflow.com/questions/27453617/how-can-i-tell-if-an-element-is-in-a-shadow-dom
+/**
+ * Gets the parent/root element of a shadow root or the global document body if not in shadow root.
+ * https://stackoverflow.com/questions/27453617/how-can-i-tell-if-an-element-is-in-a-shadow-dom
+ * @param {Node} element
+ * @returns {ShadowRoot | HTMLElement}
+ */
 export function getShadowParentOrBody(element) {
 	if (element instanceof ShadowRoot) {
 		return element;
@@ -25,6 +62,11 @@ export function getShadowParentOrBody(element) {
 
 // TODO: add function for getClosestParentOfNodeType('custom-element')
 
+/**
+ * Get the closest/first parent node that is a custom element
+ * @param {Node} domNode
+ * @returns {Node}
+ */
 export function getClosestParentCustomElementNode(domNode) {
 	const customElementParents = getAllParentNodes(domNode).filter((node) => {
 		return node.localName && node.localName.indexOf('-') !== -1;
@@ -33,14 +75,214 @@ export function getClosestParentCustomElementNode(domNode) {
 	return customElementParents.pop();
 }
 
+/**
+ * Checks whether two nodes are of the same node type
+ * @param {Node} nodeA
+ * @param {Node} nodeB
+ * @returns {boolean}
+ */
 export function isOfSameNodeType(nodeA, nodeB) {
 	if (!nodeA && !nodeA.localName) return false;
 	if (!nodeB && !nodeB.localName) return false;
 	return nodeA.localName === nodeB.localName;
 }
 
-export const supportsAdoptingStyleSheets = () =>
-	'adoptedStyleSheets' in Document.prototype && 'replace' in CSSStyleSheet.prototype;
+/**
+ * Checks if adopting style sheets is supported in browser
+ * @returns {boolean}
+ */
+export const supportsAdoptingStyleSheets = () => {
+	return 'adoptedStyleSheets' in Document.prototype && 'replace' in CSSStyleSheet.prototype;
+};
+
+/**
+ * Better implementation of hasChildNodes check because the native check will also count for empty whitespace as child nodes... :(
+ * @param {Node} node
+ * @returns {boolean}
+ */
+export const hasChildNodes = (node) => {
+	const childNodesLength = node.childNodes.length;
+
+	if (childNodesLength === 0) return false;
+
+	if (childNodesLength === 1 && node.firstChild.nodeType === 3 && node.firstChild.textContent.trim() === '')
+		return false;
+
+	// children will not contain text nodes...
+	if (childNodesLength > 0) return true;
+
+	// TODO: check if more than 1 child nodes, but all childnodes are whitespace text ndoes?!
+};
+
+/**
+ * Parses the given string as HTML template and returns a real DOM element
+ * @param {string} template
+ * @returns {HTMLElement}
+ */
+export const convertStringToHTML = (template) => {
+	const parser = new DOMParser();
+	const document = parser.parseFromString(template.toString(), 'text/html');
+	return document.body;
+};
+
+/**
+ * Parses the given string and returns a DocumentFragment which contains the DOM subtree
+ * representing the <template> element's template contents.
+ * @param {string} string
+ * @return {DocumentFragment}
+ */
+export const convertStringToTemplate = (string) => {
+	const template = globalThis.document?.createElement('template');
+	// TODO: ensure that SSRed and CSRed templates have the same amount of whitespace text nodes
+	template.innerHTML = string.trimStart().trimEnd();
+	return template.content;
+};
+
+/**
+ * Diff the attributes for a live DOM element against a template DOM element
+ * @param {Element} templateElement - The new template
+ * @param {Element} domElement - The existing DOM node
+ */
+export const diffAttributes = function (templateElement, domElement) {
+	// remove or update previous attributes
+	for (/** @type {Attr} */ const attribute of Array.from(domElement.attributes)) {
+		if (templateElement.hasAttribute(attribute.name)) {
+			const oldValue = attribute.value;
+			const newValue = templateElement.getAttribute(attribute.name) || '';
+			if (oldValue !== newValue) {
+				domElement.setAttribute(attribute.name, newValue);
+			}
+		} else {
+			domElement.removeAttribute(attribute.name);
+		}
+	}
+
+	// set newly added attributes
+	for (/** @type {Attr} */ const attribute of Array.from(templateElement.attributes)) {
+		if (!domElement.hasAttribute(attribute.name)) {
+			domElement.setAttribute(attribute.name, attribute.value);
+		}
+	}
+};
+
+/**
+ * Diff a live DOM node against a template DOM node
+ * @param {Node} templateNode
+ * @param {Node} domNode
+ * @param {(Node) => Boolean} shouldDiffChildNodes
+ */
+export const diffNodes = function (templateNode, domNode, shouldDiffChildNodes = (templateChildNode) => true) {
+	// If the DOM node should be empty, remove all child nodes
+	if (hasChildNodes(domNode) && !hasChildNodes(templateNode)) {
+		domNode.replaceChildren();
+		return;
+	}
+
+	// If the DOM node is empty, but should have children, add child nodes from the template node
+	if (!hasChildNodes(domNode) && hasChildNodes(templateNode)) {
+		domNode.replaceChildren(...templateNode.childNodes);
+		return;
+	}
+
+	const templateChildNodes = [...templateNode.childNodes];
+	const domChildNodes = [...domNode.childNodes];
+
+	// Diff each node in the child node lists
+	let length = Math.max(templateChildNodes.length, domChildNodes.length);
+	for (let index = 0; index < length; index++) {
+		const templateChildNode = templateChildNodes[index];
+		const domChildNode = domChildNodes[index];
+
+		// If the DOM node doesn't exist, append/copy the template node
+		if (!domChildNode) {
+			domNode.appendChild(templateChildNode);
+			continue;
+		}
+
+		// If the template node doesn't exist, remove the node in the DOM
+		if (!templateChildNode) {
+			domNode.removeChild(domChildNode);
+			continue;
+		}
+
+		// If DOM node is equal to the template node, don't do anything
+		if (domChildNode.isEqualNode(templateChildNode)) {
+			continue;
+		}
+
+		// the following two checks don't have to be correct, but it could bring as back to the fast path
+		// in the worst case we still have to compare and swap all the elements
+		// but in the best case we find the one element that should actually be inserted or removed
+		// and from there on, every node that comes after should be equal again
+
+		// fast path for removing DOM nodes - we delete the node now instead of at the end
+		if (domNode.childNodes.length > templateNode.childNodes.length) {
+			domChildNodes.splice(index, 1);
+			domNode.removeChild(domChildNode);
+			// because domChildNodes will get shorter by splicing it, everything moves up by one
+			// so the (actual) next element will have the same index now as we currently have
+			// therefore we have to adjust our counters
+			length--;
+			index--;
+
+			// we might have corrected everything and the parent nodes could be equal again
+			// if so, we can skip the rest of the child node checks
+			if (domNode.childNodes.length === templateNode.childNodes.length && domNode.isEqualNode(templateNode)) {
+				return;
+			}
+
+			continue;
+		}
+
+		// fast path for adding DOM nodes - we insert the node now instead of at the end
+		// but NOT if we already are at the end of the list of child nodes
+		if (index !== domNode.childNodes.length - 1 && domNode.childNodes.length < templateNode.childNodes.length) {
+			domChildNodes.splice(index, 0, templateChildNode);
+			domNode.insertBefore(templateChildNode, domChildNode);
+
+			// we might have corrected everything and the parent nodes could be equal again
+			// if so, we can skip the rest of the child node checks
+			if (domNode.childNodes.length === templateNode.childNodes.length && domNode.isEqualNode(templateNode)) {
+				return;
+			}
+
+			continue;
+		}
 
-// for IE11 we are using the ShadyDOM Polyfill. With the polyfill we cannot append stylesheets to the shadowRoot
-export const supportsAppendingStyleSheets = !window.ShadyDOM;
+		// If node types are not the same, replace the DOM node with the template node
+		if (templateChildNode.nodeType !== domChildNode.nodeType) {
+			domNode.replaceChild(templateChildNode, domChildNode);
+			continue;
+		}
+
+		// If the node is a Text node or a Comment node, update it
+		if (domChildNode.nodeType === TEXT_NODE || domChildNode.nodeType === COMMENT_NODE) {
+			domChildNode.textContent = templateChildNode.textContent;
+			continue;
+		}
+
+		// If the element tag names are not the same, replace the DOM node with the template node
+		if (templateChildNode.nodeType === ELEMENT_NODE && templateChildNode.tagName !== domChildNode.tagName) {
+			domNode.replaceChild(templateChildNode, domChildNode);
+			continue;
+		}
+
+		// If the node is an SVG element, don't even think about diffing it, just replace it
+		if (templateChildNode.nodeType === ELEMENT_NODE && templateChildNode.tagName === 'SVG') {
+			domNode.replaceChild(templateChildNode, domChildNode);
+			continue;
+		}
+
+		// If the node is an Element node, diff the attributes
+		if (templateChildNode.nodeType === ELEMENT_NODE) {
+			diffAttributes(templateChildNode, domChildNode);
+		}
+
+		// If there are child nodes, diff them recursively
+		if (templateChildNode.hasChildNodes()) {
+			if (shouldDiffChildNodes(templateChildNode)) {
+				diffNodes(templateChildNode, domChildNode);
+			}
+		}
+	}
+};

package/src/util/Directive.js

@@ -0,0 +1,35 @@
+export class Directive {
+	/** @type {Element} */
+	node = undefined;
+
+	/**
+	 * @param {Node} node
+	 */
+	constructor(node) {
+		this.node = node;
+	}
+
+	/**
+	 * @abstract
+	 */
+	update() {}
+
+	// TODO: this is somewhat custom... maybe we could set the initial values in the constructor and then simply override the default toString() method?!
+	/**
+	 * Implement the stringify method and return a string for rendering the directive in SSR mode
+	 * @param {...any} values
+	 * @returns {string}
+	 */
+	stringify(...values) {
+		return '';
+	}
+}
+
+/**
+ * @param {Class<Directive>} directiveClass
+ */
+export const defineDirective = (directiveClass) => {
+	return (...values) => {
+		return { directiveClass, values };
+	};
+};

package/src/util/Store.js

@@ -1,11 +1,14 @@
 import { isObjectLike, deepEquals } from './AttributeParser.js';
-import { BaseElement } from '../BaseElement';
+import { BaseElement } from '../BaseElement.js';
 
 export class Store {
 	_observer = new Set();
 	_singlePropertyMode = false;
 	_state = {};
 
+	/**
+	 * @param {* | object} value
+	 */
 	constructor(value) {
 		// wrap primitives with a generic "value" field to generate getter and setter
 		this._singlePropertyMode = arguments.length > 0 && !isObjectLike(value);
@@ -33,6 +36,11 @@ export class Store {
 		});
 	}
 
+	/**
+	 * 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,34 +48,47 @@ 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} 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) {

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/i18n.js

@@ -1,9 +1,9 @@
 /**
  * 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
+ * @param {string} key - to be translated
+ * @param {string} fallback - to be used if key is not defined
+ * @return {string} - String of the translated key or fallback or original key
  */
 export function i18n(key, fallback) {
 	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/CHANGELOG.md

@@ -1,142 +0,0 @@
-# Change Log
-
-All notable changes to this project will be documented in this file.
-
-The format is based on [Keep a Changelog](http://keepachangelog.com/) and this project adheres to [Semantic Versioning](http://semver.org/).
-
-<!--
-   PRs should document their user-visible changes (if any) in the
-   Unreleased section, uncommenting the header as necessary.
--->
-
-<!-- ## Unreleased -->
-<!-- ### Added -->
-<!-- ### Changed -->
-<!-- ### Removed -->
-<!-- ### Fixed -->
-
-## [0.7.3] - 2023-03-07
-
-### Fixed
-* last release was tagged wrong
-
-## [0.7.2] - 2023-03-03
-
-### Fixed
-* watcher callbacks for injected stores
-
-## [0.7.1] - 2023-03-03
-
-### Added
-* Elements are now able to watch Stores 
-
-### Fixed
-* Injection of falsy values
-
-## [0.7.0] - 2023-02-13
-
-### Added
-* Dependency Injection via Context Protocol 💉
-* Provide reactive Properties or entire Stores via: provideProperties() { return { name : value}} 
-* Inject / Request them via injectProperties() { return { name : 'defaultValue'}}
-
-### Changed
-* docs structure
-
-### Fixed
-* Cannot re-render slotted light dom when using the vanilla renderer https://github.com/webtides/element-js/issues/76
-* adds Vanilla Renderer Tests
-
-
-## [0.6.2] - 2022-11-18
-
-### FIXED
-* Store always switching to singleProperty Mode if constructed without any arguments.
-
-## [0.6.1] - 2022-11-18
-
-### ADDED
-* Store watch() map to control internal store state scope
-
-## [0.6.0] - 2022-11-17
-
-### ADDED
-* StoreProperty for shared application state  
-* Directives for Vanilla Renderer
-
-## [0.5.0] - 2022-09-13
-
-### Changed
-* improved the performance of the vanilla-renderer
-
-### Removed
-* setting attributes as properties during dom diffing for the vanilla renderer. This is potentially a **breaking** change if you used attributes with the "." (dot) notation
-
-## [0.4.3] - 2022-07-06
-
-### ADDED
-* parse option to propertyOptions that can be either a boolean OR a function for custom parsing
-* enhance reflect option in propertyOptions that it can also be a function for custom reflection
-
-## [0.4.2] - 2022-02-03
-
-### Fixed
-* vanilla-renderer: fixes attribute comparsion
-
-## [0.4.1] - 2022-02-01
-
-### Fixed
-* refs="id[]" indexing keys not nodes *rolleyes* 
-
-### Added
-* refs="id[]" aka possibbility to refrence a list of nodes to the $refs map. 
-
-## [0.4.0] - 2022-01-28
-
-### Added
-* a "vanilla" renderer with support for hydration and no dependencies
-
-### Changed
-* uses new @web/test-runner isntead of karma (#27)
-
-## [0.3.3] - 2021-09-22
-
-### Added
-* optional complex event callback notation to support addEventListener options (i.E. for passive Event Listeners )
-* Example:  {listener: () => {}, options: { passive: true } }
-* docs
-* tests
-
-
-## [0.3.2] - 2021-03-09
-
-### Added
-* bundled version of `element-js` to use from a CDN and be able to prototype in tools like CodePen etc.
-
-## [0.3.1] - 2020-12-08
-
-### Fixed 
-* i18n fallback values
-
-### Added
-* i18n tests
-
-## [0.3.0] - 2020-07-27
-
-### Added
-* first batch/draft of the documentation
-* property/attribute reflection via constructor options (see the [Documentation](/docs/README.md#propertyoptions) for more info)
-* mutationObserverOptions to enable observing subtree mutations (see the [Documentation](/docs/README.md#mutationobserveroptions) for more info)
-
-### Removed
-* `childListUpdate` constructor option has been deprecated and will be removed before `1.0`
-
-## [0.2.0] - 2020-07-01
-
-### Changed
-* uses shady-render instead of render from `lit-html` for rendering templates to be compatible with the shady-css polyfill
-* refactored and simplified `StyledElement`s handling/loading of style sheets
-
-## [0.1.0] - 2020-06-26
-
-* initial release

package/src/renderer/vanilla/TemplateElement.js

@@ -1,50 +0,0 @@
-import { StyledElement } from '../../StyledElement.js';
-import { html, spreadAttributes, unsafeHTML } from './util/html.js';
-import { render } from './util/render.js';
-export { i18n } from '../../util/i18n.js';
-
-class TemplateElement extends StyledElement {
-	constructor(options) {
-		super({
-			deferUpdate: false,
-			shadowRender: false,
-			styles: [],
-			adoptGlobalStyles: true,
-			mutationObserverOptions: {
-				childList: false,
-			},
-			...options,
-		});
-		this._template = this._options.template;
-
-		if (this._options.shadowRender && !this.shadowRoot) {
-			this.attachShadow({ mode: 'open' });
-		}
-	}
-
-	template() {
-		return html``;
-	}
-
-	update(options) {
-		this.renderTemplate();
-		super.update(options);
-	}
-
-	renderTemplate() {
-		const template = this._template || this.template();
-
-		if (typeof template === 'string') {
-			// just a plain string literal. no fancy rendering required
-			this.getRoot().innerHTML = `${template}`;
-		} else {
-			render(template, this.getRoot());
-		}
-	}
-
-	getRoot() {
-		return this.shadowRoot !== null ? this.shadowRoot : this;
-	}
-}
-
-export { TemplateElement, html, unsafeHTML, render, spreadAttributes };

package/src/renderer/vanilla/index.js

@@ -1,18 +0,0 @@
-import { BaseElement } from '../../BaseElement.js';
-import { StyledElement } from '../../StyledElement.js';
-import { TemplateElement, html, unsafeHTML, spreadAttributes } from './TemplateElement.js';
-import { toString } from '../../util/toString.js';
-import { defineElement } from '../../util/defineElement.js';
-import { i18n } from '../../util/i18n.js';
-
-export {
-	BaseElement,
-	StyledElement,
-	TemplateElement,
-	html,
-	unsafeHTML,
-	spreadAttributes,
-	toString,
-	defineElement,
-	i18n,
-};