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

package/src/dom-parts/TemplateResult.js

@@ -0,0 +1,332 @@
+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
+						const directive = new value.directiveClass();
+						result += directive.stringify(...value.values);
+					} 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/dom-parts/directives.js

@@ -0,0 +1,109 @@
+import { camelToDash, decodeAttribute, encodeAttribute } from '../util/AttributeParser.js';
+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.
+ * The keys will become the classes when the value is truthy.
+ * @param {Object.<string, string | boolean | number>} map
+ * @returns {string} string of classes joined together
+ */
+const classMap = (map) => {
+	const classes = [];
+	for (const [key, value] of Object.entries(map)) {
+		if (value) classes.push(key);
+	}
+	return classes.join(' ');
+};
+
+/**
+ * Maps a list of styles to an element from an object.
+ * The keys will become the properties and the values will become the values.
+ * @param {Object.<string, string | undefined | null>} map
+ * @returns {string} string of styles joined together
+ */
+const styleMap = (map) => {
+	const styles = [];
+	for (const [key, value] of Object.entries(map)) {
+		if (value) styles.push(`${key}:${value};`);
+	}
+	return styles.join(' ');
+};
+
+/**
+ * Renders one of two template parts based on a condition.
+ * @param {boolean} condition
+ * @param {TemplateResult | string} trueCase
+ * @param {TemplateResult | string} [falseCase]
+ * @returns {TemplateResult | string}
+ */
+const when = (condition, trueCase, falseCase) => {
+	return 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, TemplateResult | string>} cases
+ * @param {TemplateResult | string} [defaultCase]
+ * @returns {TemplateResult | string}
+ */
+const choose = (value, cases, defaultCase) => {
+	return cases[value] || defaultCase;
+};
+
+/**
+ * Renders a given string as HTML instead of text
+ * @param {string} string
+ * @returns {function(): Node | string}
+ */
+const unsafeHTML = (string) => {
+	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
+ */
+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((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

@@ -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

@@ -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,44 +117,37 @@ 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) {
 	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, "'");
 }
 
 /**
- * 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) {
 	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');
 }