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

package/src/dom-parts/TemplateResult.js

@@ -0,0 +1,331 @@
+import { COMMENT_NODE, getNodePath } from '../util/DOMHelper';
+import { encodeAttribute, isObjectLike } from '../util/AttributeParser.js';
+import { TemplatePart } from './TemplatePart.js';
+
+const voidElements = /^(?:area|base|br|col|embed|hr|img|input|link|meta|source|track|wbr)$/i;
+const elements = /<([a-z]+[a-z0-9:._-]*)([^>]*?)(\/?)>/g;
+// TODO: v this will not match any values with escaped quotes like onClick='console.log("\'test")'
+const attributes = /([^\s]*)=((?:")[^"]*(?:")|(?:')[^']*(?:')|[^\s\/>]*)|([^\s\/>]*)/g;
+const partPositions = /[\x01\x02]/g;
+// \x01 Node.ELEMENT_NODE
+// \x02 Node.ATTRIBUTE_NODE
+// \x03 COMMENT.ATTRIBUTE_TOKEN
+// \x04 Node.ATTRIBUTE_TOKEN
+
+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
+ * return a string with placeholders as either comment nodes or named attributes.
+ * @param {TemplateStringsArray | string[]} templateStrings a template literal tag array
+ * @param {string} attributePlaceholders replace placeholders inside attribute values with this value
+ * @returns {string} X/HTML with prefixed comments or attributes
+ */
+export const createTemplateString = (templateStrings, attributePlaceholders = '') => {
+	// TODO: make it easier to identify attribute and node parts for SSR and leave the comments at those positions to be replaced in toString()
+	let partIndex = 0;
+	// join all interpolations (for values) with a special placeholder and remove any whitespace
+	let template = templateStrings.join('\x01').trim();
+	// find (match) all elements to identify their attributes
+	template = template.replace(elements, (_, name, attributesString, trailingSlash) => {
+		let elementTagWithAttributes = name + attributesString.replaceAll('\x01', attributePlaceholders).trimEnd();
+		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) {
+				return `<!--\x02$-->`;
+			}
+
+			// remove quotes from attribute value to normalize the value
+			const value =
+				valueWithQuotes?.startsWith('"') || valueWithQuotes?.startsWith("'")
+					? valueWithQuotes.slice(1, -1)
+					: valueWithQuotes;
+			const partsCount = (attribute.match(/\x01/g) || []).length;
+			const parts = [];
+			for (let index = 0; index < partsCount; index++) {
+				parts.push(`<!--\x02:${name}=${value.replaceAll('\x01', '\x03')}-->`);
+			}
+			return parts.join('');
+		});
+		return `
+				${attributesString.includes('\x01') ? attributeParts : ''}
+				<${elementTagWithAttributes}>
+			`;
+	});
+	// replace interpolation placeholders with our indexed markers
+	template = template.replace(partPositions, (partPosition) => {
+		if (partPosition === '\x01') {
+			return `<!--dom-part-${partIndex}--><!--/dom-part-${partIndex++}-->`;
+		}
+		if (partPosition === '\x02') {
+			return `dom-part-${partIndex++}`;
+		}
+	});
+	return `
+		<!--template-part-->
+		${template}
+		<!--/template-part-->
+	`;
+	// TODO: ^ this is actually important because of the whitespace
+};
+
+/**
+ * @param {String} name
+ * @param {any} value
+ * @param {Boolean} isSingleValue
+ * @return {String}
+ */
+const attribute = (name, value, isSingleValue = true) => {
+	return ` ${name}="${encodeAttribute(isObjectLike(value) ? JSON.stringify(value) : value)}${
+		isSingleValue ? '"' : ''
+	}`;
+};
+
+/**
+ * @param {any} value
+ * @return {String}
+ */
+const getValue = (value) => {
+	switch (typeof value) {
+		case 'string':
+			return encodeAttribute(value);
+		case 'boolean':
+		case 'number':
+			return String(value);
+		case 'object':
+			switch (true) {
+				case Array.isArray(value):
+					return value.map(getValue).join('');
+				case value instanceof TemplateResult:
+					return value.toString();
+			}
+			break;
+		case 'function':
+			return getValue(value());
+	}
+	return value == null ? '' : encodeAttribute(String(value));
+};
+
+/** @type {Map<TemplateStringsArray, *[]>} */
+const parsedUpdates = new WeakMap();
+
+/** @type {Map<Element, TemplatePart>} */
+const templateParts = new WeakMap();
+
+export class TemplateResult {
+	/**
+	 * @param {TemplateStringsArray} strings
+	 * @param {any[]} values
+	 */
+	constructor(strings, ...values) {
+		this.strings = strings;
+		this.values = values;
+	}
+
+	/**
+	 * @param {Element} domNode
+	 */
+	renderInto(domNode) {
+		let serverSideRendered = false;
+		let templatePart = templateParts.get(domNode);
+		if (!templatePart) {
+			const startNode = Array.from(domNode.childNodes)
+				.filter((node) => node.nodeType === COMMENT_NODE)
+				.find((node) => node.data === 'template-part');
+
+			serverSideRendered = startNode !== undefined;
+
+			templatePart = new TemplatePart(startNode, this);
+			templateParts.set(domNode, templatePart);
+
+			if (!serverSideRendered) {
+				domNode.replaceChildren(...templatePart.childNodes);
+			}
+		} else {
+			templatePart.update(this);
+		}
+	}
+
+	/**
+	 * @param {String[]} strings
+	 * @return {(() => String)[]}
+	 */
+	parse(strings) {
+		const html = createTemplateString(strings, '\x04');
+		const parts = [];
+		let i = 0;
+		let match = null;
+		while ((match = interpolation.exec(html))) {
+			const pre = html.slice(i, match.index);
+			i = match.index + match[0].length;
+			if (match[2]) {
+				// ChildNodePart
+				const index = match[2];
+				parts.push((value) => `${pre}<!--dom-part-${index}-->${getValue(value)}<!--/dom-part-${index}-->`);
+			} else if (match[4]) {
+				// AttributePart with single interpolation or the first interpolation right after the attribute=
+				const isSingleValue = match[5] !== undefined;
+				let name = match[4];
+				switch (true) {
+					case name[0] === '?':
+						const booleanName = name.slice(1).toLowerCase();
+						parts.push((value) => {
+							if (!value) return '';
+							return `${pre} ${booleanName}=""`;
+						});
+						break;
+					case name[0] === '.':
+						const lower = name.slice(1).toLowerCase();
+						parts.push((value) => {
+							let result = pre;
+							// null, undefined, and false are not shown at all
+							if (value === null || value === undefined || value === '') {
+								result += attribute(lower, '');
+							} else {
+								// in all other cases, just escape it in quotes
+								result += attribute(lower, value, isSingleValue);
+							}
+							return result;
+						});
+						break;
+					case name[0] === '@':
+						name = 'on' + name.slice(1);
+					case name[0] === 'o' && name[1] === 'n':
+						parts.push((value) => {
+							return pre;
+						});
+						break;
+					default:
+						parts.push((value) => {
+							let result = pre;
+							if (value != null) {
+								result += attribute(name, value, isSingleValue);
+							}
+							return result;
+						});
+						break;
+				}
+			} else {
+				// AttributePart in the middle of an attribute value or NodePart
+				parts.push((value) => {
+					let result = pre;
+					// TODO: we currently cannot distinguish between NodeParts and AttributeParts before
+					if (isObjectLike(value) && value.directiveClass) {
+						// NodePart
+						// result += encodeAttribute(isObjectLike(value) ? JSON.stringify(value) : value);
+					} else if (value != null) {
+						result += encodeAttribute(isObjectLike(value) ? JSON.stringify(value) : value);
+					}
+					return result;
+				});
+			}
+		}
+
+		// We couldn't correctly parse parts from the template
+		if (parts.length !== strings.length - 1) {
+			throw {
+				name: 'ParseTemplateError',
+				message: 'Could not parse parts from template correctly. Parts length has not the expected length.',
+				strings,
+				templateString: html,
+				parts,
+			};
+		}
+
+		if (parts.length) {
+			const last = parts[parts.length - 1];
+			const chunk = html.slice(i);
+			parts[parts.length - 1] = (value) => last(value) + chunk;
+		} else {
+			parts.push(() => html);
+		}
+		return parts;
+	}
+
+	/**
+	 * @param {Node[]} childNodes
+	 * @return {object[]}
+	 */
+	parseParts(childNodes) {
+		// we always create a template fragment so that we can start at the root for traversing the node path
+		const range = globalThis.document?.createRange();
+		range.setStartBefore(childNodes[0]);
+		range.setEndAfter(childNodes[childNodes.length - 1]);
+		const template = range.cloneContents();
+
+		const treeWalker = globalThis.document?.createTreeWalker(template, 128);
+		let node = treeWalker.currentNode;
+
+		// 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) });
+				}
+			}
+			return parts;
+		};
+
+		const parts = getParts();
+
+		// We couldn't correctly parse parts from the template
+		if (parts.length !== this.strings.length - 1) {
+			throw {
+				name: 'ParseTemplateError',
+				message:
+					'Could not parse parts from template correctly. Parts length has not the expected length. -> ' +
+					JSON.stringify({
+						strings: this.strings,
+						templateString: this.templateString,
+						childNodes,
+						template,
+						parts,
+					}),
+			};
+		}
+
+		return parts;
+	}
+
+	/**
+	 * find interpolations in the given template for nodes and attributes and
+	 * return a string with placeholders as either comment nodes or named attributes.
+	 * @returns {string} template with tagged placeholders for values
+	 */
+	get templateString() {
+		return createTemplateString(this.strings);
+	}
+
+	toString() {
+		let updates = parsedUpdates.get(this.strings);
+
+		if (!updates) {
+			updates = this.parse(this.strings);
+			parsedUpdates.set(this.strings, updates);
+		}
+
+		return this.values.length ? this.values.map((value, index) => updates[index](value)).join('') : updates[0]();
+	}
+}

package/src/{renderer/vanilla/util → dom-parts}/directives.js

@@ -1,5 +1,6 @@
-import { camelToDash, decodeAttribute } from '../../../util/AttributeParser.js';
-import { Part } from './html.js';
+import { camelToDash, decodeAttribute, encodeAttribute } from '../util/AttributeParser.js';
+import { TemplateResult } from './TemplateResult';
+import { convertStringToHTML } from '../util/DOMHelper';
 
 /**
  * Maps a list of classes to an element from an object.
@@ -32,9 +33,9 @@ const styleMap = (map) => {
 /**
  * Renders one of two template parts based on a condition.
  * @param {boolean} condition
- * @param {TemplateLiteral | string} trueCase
- * @param {TemplateLiteral | string} [falseCase]
- * @returns {TemplateLiteral | string}
+ * @param {TemplateResult | string} trueCase
+ * @param {TemplateResult | string} [falseCase]
+ * @returns {TemplateResult | string}
  */
 const when = (condition, trueCase, falseCase) => {
 	return condition ? trueCase : falseCase;
@@ -43,9 +44,9 @@ const when = (condition, trueCase, falseCase) => {
 /**
  * Chooses and evaluates a template part from a map of cases based on matching the given value to a case.
  * @param {string} value
- * @param {Object.<string, TemplateLiteral | string>} cases
- * @param {TemplateLiteral | string} [defaultCase]
- * @returns {TemplateLiteral | string}
+ * @param {Object.<string, TemplateResult | string>} cases
+ * @param {TemplateResult | string} [defaultCase]
+ * @returns {TemplateResult | string}
  */
 const choose = (value, cases, defaultCase) => {
 	return cases[value] || defaultCase;
@@ -54,10 +55,12 @@ const choose = (value, cases, defaultCase) => {
 /**
  * Renders a given string as HTML instead of text
  * @param {string} string
- * @returns {function(): string}
+ * @returns {function(): Node}
  */
 const unsafeHTML = (string) => {
-	return () => `${decodeAttribute(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;
 };
 
 /**
@@ -69,7 +72,10 @@ const spreadAttributes = (attributes) => {
 	return () => {
 		return Object.keys(attributes)
 			.map((key) => {
-				return `${camelToDash(key)}='${new Part(attributes[key])}'`;
+				let value = attributes[key];
+				return `${camelToDash(key)}='${encodeAttribute(
+					typeof value !== 'string' ? JSON.stringify(value) : value,
+				)}'`;
 			})
 			.join(' ');
 	};

package/src/dom-parts/html.js

@@ -0,0 +1,12 @@
+import { TemplateResult } from './TemplateResult';
+
+/**
+ * @param {TemplateStringsArray} strings
+ * @param {any[]} values
+ * @return {TemplateResult}
+ */
+const html = function (strings, ...values) {
+	return new TemplateResult(strings, ...values);
+};
+
+export { html };

package/src/dom-parts/render.js

@@ -0,0 +1,10 @@
+/**
+ * Render a template string into the given DOM node
+ * @param {TemplateResult | string} template
+ * @param {Element} domNode
+ */
+const render = (template, domNode) => {
+	template.renderInto(domNode);
+};
+
+export { render };

package/src/util/AttributeParser.js

@@ -92,10 +92,10 @@ export function camelToDash(string) {
  */
 export function decodeAttribute(attribute) {
 	return `${attribute}`
-		.replace(/\$lt;/g, '<')
-		.replace(/\$gt;/g, '>')
-		.replace(/\$quot;/g, '"')
-		.replace(/\$apos;/g, "'");
+		.replace(/&lt;/g, '<')
+		.replace(/&gt;/g, '>')
+		.replace(/&quot;/g, '"')
+		.replace(/&apos;/g, "'");
 }
 
 /**
@@ -111,10 +111,10 @@ export function decodeAttribute(attribute) {
  */
 export function encodeAttribute(attribute) {
 	return `${attribute}`
-		.replace(/'/g, '$apos;')
-		.replace(/"/g, '$quot;')
-		.replace(/</g, '$lt;')
-		.replace(/>/g, '$gt;')
+		.replace(/'/g, '&apos;')
+		.replace(/"/g, '&quot;')
+		.replace(/</g, '&lt;')
+		.replace(/>/g, '&gt;')
 		.replace(/\r\n/g, '\n')
 		.replace(/[\r\n]/g, '\n');
 }

package/src/util/DOMHelper.js

@@ -1,3 +1,28 @@
+/* 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;
+
+/**
+ * Gets list of (childNode) indexes for the given node
+ * @param 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;
+};
+
 export function getAllParentNodes(domNode) {
 	let node = domNode.parentElement;
 	let parents = [];
@@ -44,3 +69,191 @@ export const supportsAdoptingStyleSheets = () =>
 
 // for IE11 we are using the ShadyDOM Polyfill. With the polyfill we cannot append stylesheets to the shadowRoot
 export const supportsAppendingStyleSheets = !window.ShadyDOM;
+
+// better hasChildNodes check because the native check will also count for empty whitespace as child nodes... :(
+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 template string 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;
+		}
+
+		// 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,22 @@
+export class Directive {
+	/** @type {Element} */
+	node = undefined;
+
+	constructor(node) {
+		this.node = node;
+	}
+
+	/**
+	 * @abstract
+	 */
+	update() {}
+}
+
+/**
+ * @param {Class<Directive>} directiveClass
+ */
+export const defineDirective = (directiveClass) => {
+	return (...values) => {
+		return { directiveClass, values };
+	};
+};