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

package/src/dom-parts/ChildNodePart.js

@@ -12,13 +12,13 @@ const removeChildNodes = (node) => {
 	const firstChild = Array.isArray(node)
 		? node[0]
 		: node instanceof TemplatePart
-		? node.childNodes[0]
-		: node.firstChild;
+		  ? node.childNodes[0]
+		  : node.firstChild;
 	const lastChild = Array.isArray(node)
 		? node[node.length - 1]
 		: node instanceof TemplatePart
-		? node.childNodes[node.childNodes.length - 1]
-		: node.lastChild;
+		  ? node.childNodes[node.childNodes.length - 1]
+		  : node.lastChild;
 	range.setStartAfter(firstChild);
 	range.setEndAfter(lastChild);
 	range.deleteContents();
@@ -75,28 +75,12 @@ const diffChildNodes = function (parentNode, domChildNodes, templateChildNodes,
 		}
 
 		// If DOM node is equal to the template node, don't do anything
-		// if (domChildNode.isEqualNode(templateChildNode)) {
 		if (domChildNode === templateChildNode) {
 			continue;
 		}
 
-		// If node types are not the same, replace the DOM node with the template node
-		if (templateChildNode.nodeType !== domChildNode.nodeType) {
-			parentNode.replaceChild(templateChildNode, domChildNode);
-			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) {
-			parentNode.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') {
-			parentNode.replaceChild(templateChildNode, domChildNode);
-			continue;
-		}
+		// Everything else is somehow different and can be replaced
+		parentNode.replaceChild(templateChildNode, domChildNode);
 	}
 	return templateChildNodes;
 };
@@ -212,6 +196,8 @@ export class ChildNodePart extends Part {
 
 		let serverSideRendered = false;
 		if (startNode) {
+			startNode.__part = this; // add Part to comment node for debugging in the browser
+
 			const placeholder = startNode.data;
 			const childNodes = [startNode];
 			let childNode = startNode.nextSibling;

package/src/dom-parts/NodePart.js

@@ -22,6 +22,7 @@ export class NodePart extends Part {
 			);
 		}
 		super();
+		node.__part = this; // add Part to comment node for debugging in the browser
 		this.node = node.nextElementSibling;
 		const { directiveClass, values } = initialValue;
 		this.directive = new directiveClass(node.nextElementSibling);

package/src/dom-parts/TemplatePart.js

@@ -34,6 +34,8 @@ export class TemplatePart extends Part {
 
 		let serverSideRendered = false;
 		if (startNode) {
+			startNode.__part = this; // add Part to comment node for debugging in the browser
+
 			const placeholder = startNode.data;
 			const childNodes = [startNode];
 			let childNode = startNode.nextSibling;
@@ -99,32 +101,24 @@ export class TemplatePart extends Part {
 				partsCache.set(templateResult.strings, parts);
 			}
 
-			/** @type AttributePart */
-			let previousAttributePart = undefined;
-			this.parts = parts.map((part, index) => {
-				// We currently need the path because the fragment will be cloned via importNode and therefore the node will be a different one
-				const node = part.path.reduceRight(({ childNodes }, i) => childNodes[i], this);
-
-				if (part.type === 'node') {
-					return new ChildNodePart(node, templateResult.values[index]);
-					// TODO: the nodes in the parts array also have nested parts information... could we start creating the nested parts here as well?
-				}
-				if (part.type === 'attribute') {
-					// If we have multiple attribute parts with the same name, it means we have multiple
-					// interpolations inside that attribute. Instead of creating a new part, we will return the same
-					// as before and let it defer the update until the last interpolation gets updated
-					if (previousAttributePart && previousAttributePart.name === part.name) {
-						previousAttributePart.addNode(node);
-						return previousAttributePart;
+			this.parts = parts
+				.map((part) => {
+					// We currently need the path because the fragment will be cloned via importNode and therefore the node will be a different one
+					part.node = part.path.reduceRight(({ childNodes }, i) => childNodes[i], this);
+					return part;
+				})
+				.map((part, index) => {
+					if (part.type === 'node') {
+						return new ChildNodePart(part.node, templateResult.values[index]);
 					}
-					return (previousAttributePart = new AttributePart(node, part.name, part.initialValue));
-				}
-				if (part.type === 'directive') {
-					return new NodePart(node, templateResult.values[index]);
-				}
-
-				throw `cannot map part: ${part}`;
-			});
+					if (part.type === 'attribute') {
+						return new AttributePart(part.node, part.name, part.initialValue);
+					}
+					if (part.type === 'directive') {
+						return new NodePart(part.node, templateResult.values[index]);
+					}
+					throw `cannot map part: ${part}`;
+				});
 			this.strings = templateResult.strings;
 		}
 	}

package/src/dom-parts/TemplateResult.js

@@ -1,4 +1,4 @@
-import { COMMENT_NODE, getNodePath } from '../util/DOMHelper';
+import { COMMENT_NODE, getNodePath } from '../util/DOMHelper.js';
 import { encodeAttribute, isObjectLike } from '../util/AttributeParser.js';
 import { TemplatePart } from './TemplatePart.js';
 
@@ -12,7 +12,7 @@ const partPositions = /[\x01\x02]/g;
 // \x03 COMMENT.ATTRIBUTE_TOKEN
 // \x04 Node.ATTRIBUTE_TOKEN
 
-const interpolation = new RegExp(`(<!--dom-part-(\\d+)--><!--/dom-part-(\\d+)-->|(\\S\\w+)="\x04(")?|\x04)`, 'g');
+const interpolation = new RegExp(`(<!--dom-part-(\\d+)--><!--/dom-part-(\\d+)-->|(\\S[-\\w]+)="\x04(")?|\x04)`, 'g');
 
 /**
  * Given a template, find part positions as both nodes and attributes and
@@ -32,7 +32,7 @@ export const createTemplateString = (templateStrings, attributePlaceholders = ''
 		if (trailingSlash.length) elementTagWithAttributes += voidElements.test(name) ? ' /' : '></' + name;
 		// collect all attribute parts so that we can place matching comment nodes
 		const attributeParts = attributesString.replace(attributes, (attribute, name, valueWithQuotes, directive) => {
-			if (directive) {
+			if (directive && directive === '\x01') {
 				return `<!--\x02$-->`;
 			}
 
@@ -95,10 +95,16 @@ const getValue = (value) => {
 			return String(value);
 		case 'object':
 			switch (true) {
+				case value === null:
+					return '';
 				case Array.isArray(value):
 					return value.map(getValue).join('');
 				case value instanceof TemplateResult:
 					return value.toString();
+				case value.__unsafeHTML:
+					return value.string;
+				default:
+					console.log('Cannot getValue for', value);
 			}
 			break;
 		case 'function':
@@ -213,7 +219,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);
 					}
@@ -255,40 +262,44 @@ export class TemplateResult {
 		const template = range.cloneContents();
 
 		const treeWalker = globalThis.document?.createTreeWalker(template, 128);
-		let node = treeWalker.currentNode;
+		let node = treeWalker.nextNode(); //to skip the root template-part
+		const parts = [];
 
-		// this is kinda freaky because the tree walker is shared throughout the recursion - but YOLO
-		const getParts = () => {
-			const parts = [];
-			let currentPart = undefined;
-			// search for parts through numbered comment nodes with placeholders
-			while ((node = treeWalker.nextNode())) {
-				if (/^template-part$/.test(node.data) && currentPart) {
-					// start recursion -> add nested parts to previous part
-					currentPart.parts = getParts();
-				}
-				if (/^\/template-part$/.test(node.data)) {
-					// end recursion
-					return parts;
-				}
-				if (/^dom-part-\d+$/.test(node.data)) {
-					parts.push((currentPart = { type: 'node', path: getNodePath(node), parts: [] }));
-				}
-				if (/^dom-part-\d+:/.test(node.data)) {
-					const [_, attribute] = node.data.split(':');
-					const [name, initialValue] = attribute.split('=');
-					currentPart = undefined;
-					parts.push({ type: 'attribute', path: getNodePath(node), name: name, initialValue });
-				}
-				if (/^dom-part-\d+\$/.test(node.data)) {
-					currentPart = undefined;
-					parts.push({ type: 'directive', path: getNodePath(node) });
+		let nestedLevel = 0;
+		// search for parts through numbered comment nodes with placeholders
+		while ((node = treeWalker.nextNode())) {
+			if (/^template-part$/.test(node.data)) {
+				nestedLevel++;
+				continue;
+			}
+			if (/^\/template-part$/.test(node.data)) {
+				if (nestedLevel > 0) {
+					nestedLevel--;
 				}
+				continue;
 			}
-			return parts;
-		};
-
-		const parts = getParts();
+			if (nestedLevel > 0) {
+				continue;
+			}
+			if (/^dom-part-\d+$/.test(node.data)) {
+				parts.push({ type: 'node', path: getNodePath(node) });
+				continue;
+			}
+			if (/^dom-part-\d+:/.test(node.data)) {
+				const [_, ...attribute] = node.data.split(':');
+				const [name, ...initialValue] = attribute.join(':').split('=');
+				parts.push({
+					type: 'attribute',
+					path: getNodePath(node),
+					name: name,
+					initialValue: initialValue.join('='),
+				});
+				continue;
+			}
+			if (/^dom-part-\d+\$/.test(node.data)) {
+				parts.push({ type: 'directive', path: getNodePath(node) });
+			}
+		}
 
 		// We couldn't correctly parse parts from the template
 		if (parts.length !== this.strings.length - 1) {

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.
@@ -53,32 +54,58 @@ const choose = (value, cases, defaultCase) => {
 };
 
 /**
- * Renders a given string as HTML instead of text
+ * Renders a given string as HTML instead of text or as unescaped string in SSR mode
  * @param {string} string
- * @returns {function(): Node}
+ * @returns {(function(): Node) | { __unsafeHTML: true, string: 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 { __unsafeHTML: true, 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/dom-parts/html.js

@@ -1,4 +1,4 @@
-import { TemplateResult } from './TemplateResult';
+import { TemplateResult } from './TemplateResult.js';
 
 /**
  * @param {TemplateStringsArray} strings

package/src/dom-parts/render.js

@@ -4,7 +4,12 @@
  * @param {Element} domNode
  */
 const render = (template, domNode) => {
-	template.renderInto(domNode);
+	if (typeof template === 'string') {
+		// just a plain string (or literal)
+		domNode.innerHTML = template;
+	} else {
+		template.renderInto(domNode);
+	}
 };
 
 export { render };

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

package/src/util/DOMHelper.js

@@ -6,10 +6,12 @@ export const ATTRIBUTE_NODE = 2;
 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 list of (childNode) indexes for the given node
- * @param node
+ * Gets a list of (childNode) indexes for the given node
+ * @param {Node} node
  * @return {number[]}
  */
 export const getNodePath = (node) => {
@@ -23,6 +25,11 @@ export const getNodePath = (node) => {
 	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 = [];
@@ -34,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;
@@ -50,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;
@@ -58,19 +75,51 @@ export function getClosestParentCustomElementNode(domNode) {
 	return customElementParents.pop();
 }
 
+/**
+ * Get all
+ * @param {Node} domNode
+ * @param {{prototype: HTMLElement, new()}} instanceOfFilter
+ * @return {Node[]}
+ */
+export function getAllElementChildren(domNode, instanceOfFilter = HTMLElement) {
+	const nodeIterator = document.createNodeIterator(domNode, NodeFilter.SHOW_ELEMENT, (node) =>
+		node.nodeName.includes('-') && node instanceof instanceOfFilter
+			? NodeFilter.FILTER_ACCEPT
+			: NodeFilter.FILTER_REJECT,
+	);
+	const customElements = [];
+	let currentNode;
+	while ((currentNode = nodeIterator.nextNode())) {
+		customElements.push(currentNode);
+	}
+	return customElements;
+}
+
+/**
+ * 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;
-
-// for IE11 we are using the ShadyDOM Polyfill. With the polyfill we cannot append stylesheets to the shadowRoot
-export const supportsAppendingStyleSheets = !window.ShadyDOM;
+/**
+ * Checks if adopting style sheets is supported in browser
+ * @returns {boolean}
+ */
+export const supportsAdoptingStyleSheets = () => {
+	return 'adoptedStyleSheets' in Document.prototype && 'replace' in CSSStyleSheet.prototype;
+};
 
-// better hasChildNodes check because the native check will also count for empty whitespace as child nodes... :(
+/**
+ * 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;
 
@@ -86,7 +135,7 @@ export const hasChildNodes = (node) => {
 };
 
 /**
- * Parses the given template string and returns a real DOM element.
+ * Parses the given string as HTML template and returns a real DOM element
  * @param {string} template
  * @returns {HTMLElement}
  */
@@ -97,8 +146,8 @@ export const convertStringToHTML = (template) => {
 };
 
 /**
- * Parses the given string and returns a DocumentFragment
- * which contains the DOM subtree representing the <template> element's template contents.
+ * 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}
  */
@@ -111,8 +160,8 @@ export const convertStringToTemplate = (string) => {
 
 /**
  * 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
+ * @param {Element} templateElement - The new template
+ * @param {Element} domElement - The existing DOM node
  */
 export const diffAttributes = function (templateElement, domElement) {
 	// remove or update previous attributes

package/src/util/Directive.js

@@ -2,6 +2,9 @@ export class Directive {
 	/** @type {Element} */
 	node = undefined;
 
+	/**
+	 * @param {Node} node
+	 */
 	constructor(node) {
 		this.node = node;
 	}
@@ -10,6 +13,16 @@ export class Directive {
 	 * @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 '';
+	}
 }
 
 /**
@@ -17,6 +30,13 @@ export class Directive {
  */
 export const defineDirective = (directiveClass) => {
 	return (...values) => {
-		return { directiveClass, values };
+		return {
+			directiveClass,
+			values,
+			toString: () => {
+				const directive = new directiveClass();
+				return directive.stringify(...values);
+			},
+		};
 	};
 };