solarite 0.4.0 → 0.5.1

package/src/Solarite.js

@@ -8,31 +8,279 @@ JavasCript UI library
 https://vorticode.github.io/solarite/ */
 import h from './h.js';
 export default h;
-export {default as h, default as r} from './h.js'; //Named exports for h() are deprecated.
-export {getArg, ArgType} from './getArg.js';
+export {default as delve} from './delve.js';
 export {default as Template} from './Template.js';
 export {default as toEl} from './toEl.js';
-
+import Template from './Template.js';
 
 // Experimental:
 //--------------
+export {default as Globals} from './Globals.js';
+export {default as SolariteUtil} from './Util.js';
+
+// Deprecated:
+//--------------
+export {default as h} from './h.js'; // Named exports for h() are deprecated.
+export {getArg, ArgType} from './getArg.js';
 export {setArgs} from './getArg.js';
+export {default as r} from './h.js';
+export function t(html) {
+	return new Template([html], []);
+}
+//export {default as watch, renderWatched} from './watch.js'; // unfinished
+
+// Only used for tests:
+//--------------
+export {default as HtmlParser} from './HtmlParser.js';
+export {default as NodeGroup} from './NodeGroup.js';
+export {default as Shell} from './Shell.js';
+
+
+
 
-import createSolarite from "./createSolarite.js";
+
+// Solarite Class:
+//--------------
+import Util from "./Util.js";
+import Globals from "./Globals.js";
 
 /**
- * TODO: The Proxy and the multiple base classes mess up 'instanceof Solarite'
- * @type {Node|Class<HTMLElement>|function(tagName:string):Node|Class<HTMLElement>} */
-const Solarite = new Proxy(createSolarite(), {
-	apply(self, _, args) {
-		return createSolarite(...args)
+ * Intercept the construct call to auto-define the class before the constructor is called. */
+let HTMLElementAutoDefine = new Proxy(HTMLElement, {
+	construct(Parent, args, Class) {
+
+		// 1. Call customElements.define() automatically.
+		Util.defineClass(Class);
+
+		// 2. This line is equivalent the to super() call to HTMLElement:
+		return Reflect.construct(Parent, args, Class);
 	}
 });
 
+/**
+ * Solarite provides more features if your web component extends Solarite instead of HTMLElement.
+ *
+ * Reasons to inherit from Solarite instead of HTMLElement.
+ * 1.  customElements.define() is called automatically when you create the first instance.
+ * 2.  Calls render() when added to the DOM, if it hasn't been called already.
+ * 3.  Populates the attribs argument to the constructor when instantiated from regular html outside a template string.
+ *         It parses JSON from DOM attribute values surrouned with '${...}'
+ * 4.  Shows an error if render() isn't defined.
+ *
+ * Advantages to inheriting from HTMLElement
+ * 1.  We can inherit from things like HTMLTableRowElement directly.
+ * 2.  There's less magic, since everyone is familiar with defining custom elements.
+ * 3.  No confusion about how the class name becomes a tag name.
+ * @extends {HTMLElement} */
+export class Solarite extends HTMLElementAutoDefine {
 
-/** @type {HTMLElement|Class} */
-export {Solarite}
-export {default as Globals} from './Globals.js';
-export {default as SolariteUtil} from './Util.js';
+	/**
+	 * @param attribs {?Record<string, any>} */
+	constructor(attribs=null) {
+		super();
+
+		if (attribs) {
+			if (typeof attribs !== 'object')
+				throw new Error('First argument to custom element constructor must be an object.');
+
+			// 1. Populate attribs if it's an empty object.
+			if (attribs && !Object.keys(attribs).length) {
+				let attribs2 =  Solarite.getAttribs(this);
+				for (let name in attribs2) {
+					attribs[name] = attribs2[name];
+				}
+			}
 
-//export {default as watch, renderWatched} from './watch.js'; // unfinished
+			// 2. Populate fields from attribs.
+			// This does nothing because the fields are overwritten by the child class after this super() constructor executes.
+			//for (let name in attribs || {}) {
+			//	if (name in this) {
+			//		const descriptor = Object.getOwnPropertyDescriptor(this, name);
+			//		if (!descriptor || descriptor.writable || descriptor.set)
+			//			this[name] = attribs[name];
+			//	}
+			//}
+		}
+
+		// 3. Wrap render function so it always provides the attribs argument.
+		// Disabled because this gives us strings for attribute values when we call render manually.
+		// Instead of values given from ${...} expressions.
+		// let originalRender = this.render;
+		// this.render = (attribs, changed=true) => {
+		// 	if (!attribs) // If we have to look up the attribs, we don't know if they changed or not.
+		// 		attribs = Solarite.getAttribs(this);
+		// 	originalRender.call(this, attribs, changed);
+		// }
+	}
+
+	'render'() {
+		throw new Error('render() is not defined for ' + this.constructor.name);
+	}
+
+	/**
+	 * Call render() only if it hasn't already been called.	 */
+	'renderFirstTime'() {
+		if (!Globals.rendered.has(this)) {
+			let attribs = Solarite.getAttribs(this);
+			this.render(attribs); // calls Globals.rendered.add(this); inside the call to h()'...'.
+		}
+	}
+
+	/**
+	 * Called automatically by the browser. */
+	'connectedCallback'() { // quoted so terser doesn't remove it.
+		this.renderFirstTime();
+	}
+
+	static 'define'(tagName=null) {
+		Util.defineClass(this, tagName);
+	}
+
+	static 'getAttribs'(el) {
+		let result = Util.attribsToObject(el);
+		for (let name in result) {
+			let val = result[name];
+			if (val.startsWith('${') && val.endsWith('}'))
+				result[name] = JSON.parse(val.slice(2, -1));
+		}
+		return result;
+	}
+
+
+	// TODO: Do we want to use this to get the tag name from the render() function, instead of having the user define it?
+	/**
+	 * Get the tag name for a class, as defined by the tag used in render().
+	 *
+	 * This will parse the JavaScript code of the render() function to find the tag name.
+	 * It will itarage every character, keeping track of quotes and comments so it can
+	 * skip them until it finds the tag name passed to h(this)`<tagname>` inside the render() function.
+	 *
+	 * */
+	/*
+	static getTagName(Class) {
+		let code = Class.prototype.render.toString();
+		let i = 0;
+		while (i < code.length) {
+			let char = code[i];
+			let next = code[i + 1];
+
+			// Skip single line comments
+			if (char === '/' && next === '/') {
+				i = code.indexOf('\n', i);
+				if (i === -1) break;
+				continue;
+			}
+			// Skip multi-line comments
+			if (char === '/' && next === '*') {
+				i = code.indexOf('*'+'/', i + 2);
+				if (i === -1) break;
+				i += 2;
+				continue;
+			}
+			// Skip strings and template literals
+			if (char === "'" || char === '"' || char === '`') {
+				let quote = char;
+				i++;
+				while (i < code.length) {
+					if (code[i] === '\\') i += 2;
+					else if (code[i] === quote) { i++; break; }
+					else i++;
+				}
+				continue;
+			}
+			// Skip regex literals (simple heuristic)
+			if (char === '/') {
+				let prev = code.slice(Math.max(0, i - 10), i).trim();
+				// If / is preceded by something that indicates an operator or start of expression
+				if (/[=(,;:[!&|?]$|return$|yield$|case$/.test(prev)) {
+					i++;
+					while (i < code.length) {
+						if (code[i] === '\\') i += 2;
+						else if (code[i] === '[') { // Skip character classes
+							i++;
+							while (i < code.length && code[i] !== ']') {
+								if (code[i] === '\\') i += 2;
+								else i++;
+							}
+							i++;
+						}
+						else if (code[i] === '/') { i++; break; }
+						else i++;
+					}
+					continue;
+				}
+			}
+			// Check for h(this)`
+			if (char === 'h' && code.slice(i, i + 8) === 'h(this)`') {
+				i += 8;
+				// We are now inside the template literal.
+				// Skip whitespace and HTML comments
+				while (i < code.length) {
+					// Skip JS template literal end (shouldn't happen before tag, but for safety)
+					if (code[i] === '`') return null;
+
+					// Skip whitespace
+					if (/\s/.test(code[i])) { i++; continue; }
+
+					// Skip HTML comments <!-- ... -->
+					if (code.slice(i, i + 4) === '<!--') {
+						i = code.indexOf('-->', i + 4);
+						if (i === -1) return null;
+						i += 3;
+						continue;
+					}
+
+					// Find the first tag
+					if (code[i] === '<') {
+						let start = ++i;
+						while (i < code.length && /[a-zA-Z0-9-]/.test(code[i])) i++;
+						return code.slice(start, i);
+					}
+
+					// If we encounter anything else (like text before a tag),
+					// we can keep looking or return null depending on how strict we want to be.
+					// For now, let's just skip non-tag characters.
+					i++;
+				}
+			}
+			i++;
+		}
+		return null;
+	}
+	*/
+}
+
+
+/**
+ * Assign fields from `src` to `dest` if they exist in `dest` and their names are not in the `ignore` list.
+ * When a value in `src` is a string and the existing value in `dest` is a boolean, number, or Date,
+ * it will be converted to that type.
+ * This is often used in class constructors that accept an object of arguments.
+ * @param {object} dest
+ * @param {?object} src
+ * @param {string[]} [ignore=[]] */
+export function assignFields(dest, src, ignore=[]) {
+	for (let name in src || {}) {
+		if (name in dest && !ignore.includes(name)) {
+			const descriptor = Object.getOwnPropertyDescriptor(dest, name)
+				|| Object.getOwnPropertyDescriptor(Object.getPrototypeOf(dest), name); // Also find (parent?) setters.  Is this necssary?
+			if (!descriptor || descriptor.writable || descriptor.set) {
+				let srcVal = src[name];
+				let destVal = dest[name];
+				if (typeof src[name] === 'string') {
+					if (typeof destVal === 'boolean') // empty string (when an attribute is present with no value) is true
+						dest[name] = ![false, 'false', 0, '0'].includes(srcVal);
+					else if (typeof destVal === 'number')
+						dest[name] = Number(srcVal);
+					else if (destVal instanceof Date) {
+						dest[name] = new Date(srcVal); // TODO: read it as UTC 0 by default.
+					}
+					else
+						dest[name] = srcVal;
+				}
+				else
+					dest[name] = srcVal;
+			}
+		}
+	}
+}

package/src/Template.js

@@ -1,8 +1,7 @@
-import {assert} from "./assert.js";
+import assert from "./assert.js";
 import {getObjectHash, getObjectId} from "./hash.js";
 import Globals from "./Globals.js";
 import RootNodeGroup from "./RootNodeGroup.js";
-import Util from "./Util.js";
 
 /**
  * The html strings and evaluated expressions from an html tagged template.
@@ -10,23 +9,27 @@ import Util from "./Util.js";
  * Although the reference to the html strings is shared among templates. */
 export default class Template {
 
-	/** @type {(Template|string|function)|(Template|string|function)[]} Evaulated expressions.  */
-	exprs = []
+	/** @type {Expr[]} Evaulated expressions.  */
+	'exprs' = []
 
 	/** @type {string[]} */
-	html = [];
+	'html' = [];
 
 	/** @type {Array} Used for toJSON() and getObjectHash().  Stores values used to quickly create a string hash of this template. */
 	hashedFields;
 
+	closeKey;
+	exactKey;
+
 	isText;
 
 	/**
 	 *
 	 * @param htmlStrings {string[]}
 	 * @param exprs {*[]} */
-	constructor(htmlStrings, exprs) {
+	constructor(htmlStrings=[''], exprs=[]) {
 		this.html = htmlStrings;
+
 		this.exprs = exprs;
 
 		//this.trace = new Error().stack.split(/\n/g)
@@ -50,51 +53,50 @@ export default class Template {
 	 * Called by JSON.serialize when it encounters a Template.
 	 * This prevents the hashed version from being too large. */
 	toJSON() {
-		if (!this.hashedFields)
+		if (this.hashedFields===undefined)
 			this.hashedFields = [getObjectId(this.html), this.exprs];
 
 		return this.hashedFields
 	}
 
 	/**
-	 * Render the main template, which may indirectly call renderTemplate() to create children.
-	 * @param el {HTMLElement}
+	 * Render the main (root) template.
+	 * @param el {?HTMLElement} Null if we're rendering to a standalone element.
 	 * @param options {RenderOptions}
 	 * @return {?DocumentFragment|HTMLElement} */
-	render(el=null, options={}) {
-		let ng;
-		let standalone = !el;
-		let firstTime = false;
-
-		// Rendering a standalone element.
-		// TODO: figure out when to not use RootNodeGroup
-		if (standalone) {
-			ng = new RootNodeGroup(this, null, options);
-			el = ng.getRootNode();
-			Globals.nodeGroups.set(el, ng); // Why was this commented out?
-			firstTime = true;
+	'render'(el=null, options={}) {
+
+
+
+		let ng = el && Globals.rootNodeGroups.get(el);
+		if (!ng) {
+			ng = new RootNodeGroup(this, null, el, options);
+			if (!el) // null if it's a standalone elment.
+				el = ng.getRootNode();
+			Globals.rootNodeGroups.set(el, ng); // All tests still pass if this is commented out!
 		}
-		else {
-			ng = Globals.nodeGroups.get(el);
-			if (!ng) {
-				ng = new RootNodeGroup(this, el, options);
-				Globals.nodeGroups.set(el, ng); // Why was this commented out?
-				firstTime = true;
-			}
 
-			// This can happen if we try manually rendering one template to a NodeGroup that was created expecting a different template.
-			// These don't always have the same length, for example if one attribute has multiple expressions.
-			if (ng.paths.length === 0 && this.exprs.length || ng.paths.length > this.exprs.length)
-				throw new Error(`Solarite Error:  Parent HTMLElement ${ng.template.html.join('${...}')} and ${ng.paths.length} \${value} placeholders can't accomodate a Template with ${this.exprs.length} values.`);		}
+		// Make sure the expresion count matches match the Path "hole" count.
+		// This can happen if we try manually rendering one template to a NodeGroup that was created expecting a different template.
+		// These don't always have the same length, for example if one attribute has multiple expressions.
+		// if (ng.paths.length === 0 && this.exprs.length || ng.paths.length > this.exprs.length)
+		// 	throw new Error(
+		// 		`Solarite Error:  Parent HTMLElement ${ng.template.html.join('${...}')} and ${ng.paths.length} \${value} ` +
+		// 		`placeholders can't accomodate a Template with ${this.exprs.length} values.`);
 
 		// Creating the root nodegroup also renders it.
 		// If we didn't just create it, we need to render it.
-		if (!firstTime) {
-			if (this.html?.length === 1 && !this.html[0])
-				el.innerHTML = ''; // Fast path for empty component.
-			else {
-				ng.applyExprs(this.exprs);
-			}
+		if (this.html?.length === 1 && !this.html[0]) // An empty string.
+			el.innerHTML = ''; // Fast path for empty component.
+		else {
+
+			let oldKey = ng.exactKey;
+			let newKey = this.getExactKey();
+			ng.applyExprs(this.exprs, oldKey !== newKey);
+			ng.exactKey = newKey;
+
+			//if (firstTime)
+			//	ng.instantiateStaticComponents(ng.staticComponents);
 		}
 
 		ng.exprsToRender = new Map();
@@ -102,7 +104,7 @@ export default class Template {
 	}
 
 	getExactKey() {
-		if (!this.exactKey) {
+		if (this.exactKey===undefined) {
 			if (this.exprs.length)
 				this.exactKey = getObjectHash(this);// calls this.toJSON().
 			else // Don't hash plain html.
@@ -113,7 +115,7 @@ export default class Template {
 
 	getCloseKey() {
 		//console.log(this.exprs.length)
-		if (!this.closeKey) {
+		if (this.closeKey===undefined) {
 			if (this.exprs.length)
 				this.closeKey = /*'@' + */this.toJSON()[0];
 			else

package/src/Util.js

@@ -20,6 +20,8 @@ let Util = {
 
 	/**
 	 * Convert HTMLElement attributes to an object.
+	 * Converts dash (kebob-case) attribute names to camelCase.
+	 * See also Solarite.getAttribs()
 	 * @param el {HTMLElement}
 	 * @param ignore {?string} Optionally ignore this attribute.
 	 * @return {Object} */
@@ -135,43 +137,14 @@ let Util = {
 		return str.replace(/-([a-z])/g, g => g[1].toUpperCase());
 	},
 
-	/**
-	 * A generator function that recursively traverses and flattens a value.
-	 *
-	 * - If the input is an array, it recursively traverses and flattens the array.
-	 * - If the input is a function, it calls the function, replaces the function
-	 *   with its result, and flattens the result if necessary. It will recursively
-	 *   call functions that return other functions.
-	 * - Otherwise it yields the value as is.
-	 *
-	 * This function does not create a new array for the flattened values. Instead,
-	 * it lazily yields each item as it is encountered. This can be more memory-efficient
-	 * for large or deeply nested structures.
-	 *
-	 * @param {any} value - The value to flatten. Can be an array, object, function, or primitive.
-	 * @yields {any} - The next item in the flattened structure.
-	 *
-	 * @example
-	 * const complexArray = [
-	 *     1,
-	 *     [2, () => 3, [4, () => [5, 6]], { a: 'object' }],
-	 *     () => () => 7,
-	 *     () => [() => 8, 9],
-	 * ];	 *
-	 * for (const item of flatten(complexArray))
-	 *     console.log(item);  // Outputs: 1, 2, 3, 4, 5, 6, { a: 'object' }, 7, 8, 9
-	 */
-	// *flatten(value) {
-	// 	if (Array.isArray(value)) {
-	// 		for (const item of value) {
-	// 			yield* Util.flatten(item);  // Recursively flatten arrays
-	// 		}
-	// 	} else if (typeof value === 'function') {
-	// 		const result = value();
-	// 		yield* Util.flatten(result);  // Recursively flatten the result of a function
-	// 	} else
-	// 		yield value;  // Yield primitive values as is
-	// },
+	defineClass(Class, tagName) {
+		if (!customElements[getName](Class)) { // If not previously defined.
+			tagName = tagName || Util.camelToDashes(Class.name)
+			if (!tagName.includes('-')) // Browsers require that web components always have a dash in the name.
+				tagName += '-element';
+			customElements[define](tagName, Class)
+		}
+	},
 
 	/**
 	 * Get the value of an input as the most appropriate JavaScript type.
@@ -261,7 +234,7 @@ let Util = {
 
 	/**
 	 * Use an array as the value of a map, appending to it when we add.
-	 * Used by watch.js.
+	 * Used only by watch.js.
 	 * @param map {Map|WeakMap|Object}
 	 * @param key
 	 * @param value */
@@ -275,6 +248,11 @@ let Util = {
 			result.push(value);
 	},
 
+	saveOrphans(nodes) {
+		let fragment = Globals.doc.createDocumentFragment();
+		fragment.append(...nodes);
+	},
+
 	/**
 	 * Remove nodes from the beginning and end that are not:
 	 * 1.  Elements.
@@ -301,6 +279,12 @@ let Util = {
 	}
 };
 
+
+
+// Trick to prevent minifier from renaming these methods.
+let define = 'define';
+let getName = 'getName';
+
 export default Util;
 
 

package/src/assert.js

@@ -1,10 +1,10 @@
-//#IFDEV
+
 /*@__NO_SIDE_EFFECTS__*/
-export function assert(val) {
+export default function assert(val) {
+	//#IFDEV
 	if (!val) {
-		debugger;
+		//debugger;
 		throw new Error('Assertion failed: ' + val);
 	}
+	//#ENDIF
 }
-
-//#ENDIF

package/src/getArg.js

@@ -2,10 +2,11 @@ import Util from "./Util.js";
 
 
 /**
+ * @deprecated Inherit from Solarite and pass arribs to super() instead.
  * There are three ways to create an instance of a Solarite Component:
- * 1.  new ComponentName();                                         // direct class instantiation
- * 2.  this.html = r`<div><component-name></component-name></div>;  // as a child of another RedComponent.
- * 3.  <body><component-name></component-name></body>               // in the Document html.
+ * 1.  new ComponentName(3);                                               // direct class instantiation
+ * 2.  h(this)`<div><component-name user-id=${3}></component-name></div>;  // as a child of another Component.
+ * 3.  <body><component-name user-id="3"></component-name></body>          // in the Document html.
  *
  * When created via #3, Solarite has no way to pass attributes as arguments to the constructor.  So to make
  * sure we get the correct value via all three paths, we write our constructors according to the following
@@ -13,40 +14,38 @@ import Util from "./Util.js";
  * Browsers make all html attribute names lowercase.
  *
  * @example
- * constructor({name, userid=1}={}) {
+ * constructor({name, userId=1}={}) {
  *     super();
  *
  *     // Get value from "name" attriute if persent, otherwise from name constructor arg.
  *     this.name = getArg(this, 'name', name);
  *
  *     // Optionally convert the value to an integer.
- *     this.userId = getArg(this, 'userid', userid, ArgType.Int);
+ *     this.userId = getArg(this, 'user-id', userId, ArgType.Int);
  * }
  *
  * @param el {HTMLElement}
  * @param attributeName {string} Attribute name.  Not case-sensitive.
- * @param defaultValue {*} Default value to use if attribute doesn't exist.
+ * @param defaultValue {*} Default value to use if attribute doesn't exist.  Typically the argument from the constructor.
  * @param type {ArgType|function|Class|*[]}
  *     If an array, use the value if it's in the array, otherwise return undefined.
  *     If it's a function, pass the value to the function and return the result.
- * @param fallback {*} If the defaultValue is undefiend and type can't be parsed as the given type, use this value.
- *     TODO: Should this be merged with the defaultValue argument?
- * @return {*} Undefined if attribute isn't set.  */
-export function getArg(el, attributeName, defaultValue=undefined, type=ArgType.String, fallback=undefined) {
+ * @return {*} Undefined if attribute isn't set and there's no defaultValue, or if the value couldn't be parsed as the type.  */
+export function getArg(el, attributeName, defaultValue=undefined, type=ArgType.String) {
 	let val = defaultValue;
 	let attrVal = el.getAttribute(attributeName) || el.getAttribute(Util.camelToDashes(attributeName));
 	if (attrVal !== null) // If attribute doesn't exist.
 		val = attrVal;
-		
+
 	if (Array.isArray(type))
-		return type.includes(val) ? val : fallback;
-	
+		return type.includes(val) ? val : undefined;
+
 	if (typeof type === 'function') {
 		return type.constructor
 			? new type(val) // arg type is custom Class
 			: type(val); // arg type is custom function
 	}
-	
+
 	// If bool, it's true as long as it exists and its value isn't falsey.
 	if (type===ArgType.Bool) {
 		let lAttrVal = typeof val === 'string' ? val.toLowerCase() : val;
@@ -54,20 +53,17 @@ export function getArg(el, attributeName, defaultValue=undefined, type=ArgType.S
 			return false;
 		if (['true', true].includes(lAttrVal) || parseFloat(lAttrVal) !== 0)
 			return true;
-		return fallback;
+		return undefined;
 	}
-	
+
 	// Attribute doesn't exist
-	let result;
 	switch (type) {
 		case ArgType.Int:
-			result = parseInt(val);
-			return isNaN(result) ? fallback : result;
+			return parseInt(val);
 		case ArgType.Float:
-			result = parseFloat(val);
-			return isNaN(result) ? fallback : result;
+			return parseFloat(val);
 		case ArgType.String:
-			return [undefined, null, false].includes(val) ? '' : val+'';
+			return [undefined, null, false].includes(val) ? '' : (val+'');
 		case ArgType.Json:
 		case ArgType.Eval:
 			if (typeof val === 'string' && val.length)
@@ -89,6 +85,7 @@ export function getArg(el, attributeName, defaultValue=undefined, type=ArgType.S
 
 
 /**
+ * @deprecated for Solarite.getAttribs()
  * Experimental.  Set multiple arguments/attributes all at once.
  * @param el {HTMLElement}
  * @param args {Record<string, any>}
@@ -97,6 +94,10 @@ export function getArg(el, attributeName, defaultValue=undefined, type=ArgType.S
  * @example
  * constructor({user, path}={}) {
  *     setArgs(this, arguments[0], {user: User, path: ArgType.String});
+ *
+ *     // Equivalent to:
+ *     this.user = getArg(this, user, 'user', User); // or new User(user);
+ *     this.path = getArg(this, path, 'path', ArgType.String);
  * }
  */
 export function setArgs(el, args, types) {
@@ -106,15 +107,16 @@ export function setArgs(el, args, types) {
 
 
 /**
+ * @deprecated
  * @enum */
 var ArgType = {
-	
+
 	/**
 	 * false, 0, null, undefined, '0', and 'false' (case-insensitive) become false.
 	 * Anything else, including empty string becomes true.
 	 * Empty string is true because attributes with no value should be evaulated as true. */
 	Bool: 'Bool',
-	
+
 	Int: 'Int',
 	Float: 'Float',
 	String: 'String',