solarite 0.7.0 → 0.8.0

package/src/h.js

@@ -3,6 +3,8 @@ import Globals from "./Globals.js";
 import toEl from "./toEl.js";
 import Util from "./Util.js";
 import {jsxToTemplate, Fragment} from "./jsx.js";
+import MappedList from "./MappedList.js";
+import Selector from "./Selector.js";
 
 /**
  * Convert strings to HTMLNodes.
@@ -56,7 +58,11 @@ const renderTemplateKey = Symbol('solariteRender');
 // Using `arguments` alongside rest params would force the engine to materialize both per call.
 const noArg = Symbol();
 
-export default function h(htmlStrings=noArg, ...exprs) {
+// The /** @type {*} */ cast on the default keeps TypeScript from inferring the parameter as
+// `symbol` from noArg: TS can't parse the closure-style @param type above (function() without
+// a return type under noImplicitAny), falls back to the default's type, and then flags every
+// h(this) / h`` call in the codebase as an error.  JetBrains reads the @param fine either way.
+export default function h(htmlStrings=/** @type {*} */(noArg), ...exprs) {
 
 	// 1. Tagged template: h`<div>...</div>`
 	if (Array.isArray(htmlStrings)) {
@@ -109,11 +115,14 @@ export default function h(htmlStrings=noArg, ...exprs) {
 			let parent = htmlStrings, options = exprs[0];
 
 			// The closure is cached on the element so repeated renders don't recreate it.
-			if (options === undefined) {
-				let cached = parent[renderTemplateKey];
-				if (cached)
-					return cached;
-			}
+			// Options are cached with it: they only take effect when the element's
+			// RootNodeGroup is first created, so a later render passing different ones is
+			// ignored either way, and caching regardless of them saves an allocation on every
+			// render of a component that passes an options object — which is how render() is
+			// usually written.
+			let cached = parent[renderTemplateKey];
+			if (cached)
+				return cached;
 
 			// Return a tagged template function that applies the tagged template to parent.
 			let renderTemplate = (htmlStrings, ...exprs) => {
@@ -125,8 +134,7 @@ export default function h(htmlStrings=noArg, ...exprs) {
 				let template = new Template(htmlStrings, exprs);
 				return template.render(parent, options);
 			}
-			if (options === undefined)
-				parent[renderTemplateKey] = renderTemplate;
+			parent[renderTemplateKey] = renderTemplate;
 			return renderTemplate;
 		}
 	}
@@ -143,11 +151,11 @@ export default function h(htmlStrings=noArg, ...exprs) {
 	// Intercepts the main h(this)`...` function call inside render().
 	// TODO: This path doesn't handle embeds like data-id="..."
 	else if (typeof htmlStrings === 'object' && Globals.objToEl.has(htmlStrings)) {
+		// The only thing that ever puts an object into objToEl is toEl(), and it rejects anything
+		// that isn't a plain object before it does so, so an object that reaches here has already
+		// been checked and re-checking it can never report anything.
 		let obj = htmlStrings;
 
-		if (obj.constructor.name !== 'Object')
-			throw new Error(`Solarate Web Component class ${obj.constructor?.name} must extend HTMLElement.`);
-
 		// Jsx with h(this, <jsx>)
 		if (exprs[0] instanceof Template) {
 			let template = exprs[0];
@@ -171,14 +179,6 @@ export default function h(htmlStrings=noArg, ...exprs) {
 		throw new Error('h() does not support argument of type: ' + (htmlStrings ? typeof htmlStrings : htmlStrings))
 }
 
-// h.map caches each item's Template keyed by the item's identity, so a re-render returns
-// the SAME Template instance for any item whose reference is unchanged.  The reconciler's
-// `ng.template === item` fast path (PathToNodes.applyKeyed/applyDiff) then skips rebuilding
-// and comparing that row.  A WeakMap is used instead of a symbol property so the idiomatic
-// immutable update `{...item, x}` yields a fresh object that ISN'T in the cache and re-renders;
-// a symbol property would be copied by spread and silently reuse the stale Template.
-const mapCache = new WeakMap();
-
 /**
  * Render a list, reusing each item's DOM for as long as the item is the SAME object.
  *
@@ -195,26 +195,53 @@ const mapCache = new WeakMap();
  *
  * ${h.map(this.rows, row => h`<tr key=${row.id}>${row.label}</tr>`)}
  *
+ * What comes back is a MappedList, not an array: it carries the items and the callback so
+ * the reconciler can match a row to its item by identity and call the callback only for the
+ * rows it can't match.  Put it straight into a template expression, as above; nested inside
+ * an array, or returned from a function, it expands to Templates just the same.
+ *
  * @param items {Array} The list to render.
  * @param fn {function(item:*):Template} Builds an item's Template; called only for new items.
- * @return {Template[]} */
-h.map = (items, fn) => {
-	let result = new Array(items.length);
-	for (let i=0; i<items.length; i++) {
-		let item = items[i];
-		if (item !== null && typeof item === 'object') {
-			let template = mapCache.get(item);
-			if (template === undefined) {
-				template = fn(item);
-				mapCache.set(item, template);
-			}
-			result[i] = template;
-		}
-		else
-			result[i] = fn(item);
-	}
-	return result;
-}
+ * @return {MappedList} */
+h.map = (items, fn) => new MappedList(items, fn);
 
 h.immutableMap = h.map;
 
+/**
+ * Create a selection that updates only the rows it affects.
+ *
+ * A highlight that moves from one row of a thousand to another changes two attributes.
+ * Expressing it as ordinary state means calling render() and letting the reconciler walk the
+ * list to rediscover that.  A selector writes those two attributes directly instead:
+ *
+ *	 class Table extends Solarite {
+ *		 selected = h.selector();
+ *
+ *		 pick(row) {
+ *			 this.selected.set(row.id);   // no render() call
+ *		 }
+ *
+ *		 render() {
+ *			 h(this)`<tbody>${h.map(this.rows, row =>
+ *				 h`<tr key=${row.id} class=${this.selected.when(row.id, 'danger')}
+ *					 onclick=${[this.pick, row]}>${row.label}</tr>`)}</tbody>`;
+ *		 }
+ *	 }
+ *
+ * when() must be a whole attribute value, not part of one and not element content, since it
+ * owns that attribute for as long as the row exists.  An off value of '' leaves no attribute
+ * behind at all.  Selection state lives on the selector, so it survives re-renders, and
+ * set() is safe to call whether or not the rows are currently rendered.
+ *
+ * Two rules follow from how set() finds a row, and both throw a clear error rather than
+ * misbehaving quietly.  **The rows must be keyed** — set() locates a row by looking its key
+ * up in the list, so the row template needs a key=${...}.  And **the attribute must sit on
+ * the row's own root element**, the same one that carries the key, because that is the
+ * element set() writes.  Drawing a row costs nothing either way: when() hands back one of
+ * two shared objects rather than allocating anything per row, so a selector is free to
+ * render over a list of any size and only a change of selection does any work.
+ *
+ * @param key {*} The initially selected key, or null for none.
+ * @return {Selector} */
+h.selector = (key = null) => new Selector(key);
+

package/src/jsx.js

@@ -115,13 +115,10 @@ export function jsxToTemplate(tag, props, children=[], key=undefined) {
 
 		// 2a. Custom element class => emit <tag-name ...props>children</tag-name>; PathToComponent
 		// instantiates it exactly like a tagged-template component.
-		if (tag.prototype instanceof HTMLElement) {
-			Util.defineClass(tag);
-			let tagName = customElements.getName ? customElements.getName(tag) : Util.camelToDashes(tag.name);
-			if (tagName && !tagName.includes('-'))
-				tagName += '-element';
-			return buildIntrinsic(tagName, props, children, key);
-		}
+		// defineClass() hands back the name it registered, or the name the class was already
+		// registered under, so we never have to guess it a second time.
+		if (tag.prototype instanceof HTMLElement)
+			return buildIntrinsic(Util.defineClass(tag), props, children, key);
 
 		// 2b. Plain function component: call it with props (+ children) and expect a Template back.
 		let p = {};

package/src/toEl.js

@@ -41,7 +41,7 @@ export default function toEl(arg) {
 		let obj = arg;
 
 		if (obj.constructor.name !== 'Object')
-			throw new Error(`Solarate Web Component class ${obj.constructor?.name} must extend HTMLElement.`);
+			throw new Error(`Solarite web component class ${obj.constructor?.name} must extend HTMLElement.`);
 
 		// Normal path
 		if (!Globals.objToEl.has(obj)) {

package/src/HtmlParser.js

@@ -1,91 +0,0 @@
-
-export default class HtmlParser {
-	constructor() {
-		this.defaultState = {
-			context: HtmlParser.Text, // possible values: 'TEXT', 'TAG', 'ATTRIBUTE'
-			quote: null, // possible values: null, '"', "'"
-			buffer: '',
-			lastChar: null
-		};
-		this.state = {...this.defaultState};
-	}
-
-	reset() {
-		this.state = {...this.defaultState};
-		return this.state.context;
-	}
-
-	/**
-	 * Parse the next chunk of html, starting with the same context we left off with from the previous chunk.
-	 * @param html {string}
-	 * @param onContextChange {?function(html:string, index:int, prevContext:string, nextContext:string)}
-	 *     Called every time the context changes, and again at the last context.
-	 * @return {('Attribute','Text','Tag')} The context at the end of html.  */
-	parse(html, onContextChange=null) {
-		if (html === null)
-			return this.reset();
-
-		for (let i = 0; i < html.length; i++) {
-			const char = html[i];
-			switch (this.state.context) {
-				case HtmlParser.Text:
-					if (char === '<' && html[i + 1].match(/[/a-z!]/i)) { // Start of a tag or comment.
-						onContextChange?.(html, i, this.state.context, HtmlParser.Tag);
-						this.state.context = HtmlParser.Tag;
-						this.state.buffer = '';
-					}
-					break;
-				case HtmlParser.Tag:
-					if (char === '>') {
-						onContextChange?.(html, i+1, this.state.context, HtmlParser.Text);
-						this.state.context = HtmlParser.Text;
-						this.state.quote = null;
-						this.state.buffer = '';
-					}
-					else if (char === ' ' && !this.state.buffer) {
-						// No attribute name is present. Skipping the space.
-						continue;
-					}
-					else if (char === ' ' || char === '/' || char === '?') {
-						this.state.buffer = ''; // Reset the buffer when a delimiter or potential self-closing sign is found.
-					}
-					else if (char === '"' || char === "'" || char === '=') {
-						onContextChange?.(html, i, this.state.context, HtmlParser.Attribute);
-						this.state.context = HtmlParser.Attribute;
-						this.state.quote = char === '=' ? null : char;
-						this.state.buffer = '';
-					}
-					else
-						this.state.buffer += char;
-					break;
-				case HtmlParser.Attribute:
-					// Start an attribute quote.
-					if (!this.state.quote && !this.state.buffer.length && (char === '"' || char === "'")) {
-						this.state.quote = char;
-					}
-					else if (char === this.state.quote || (!this.state.quote && this.state.buffer.length)) {
-						onContextChange?.(html, i, this.state.context, HtmlParser.Tag);
-						this.state.context = HtmlParser.Tag;
-						this.state.quote = null;
-						this.state.buffer = '';
-					}
-					else if (!this.state.quote && char === '>') {
-						onContextChange?.(html, i+1, this.state.context, HtmlParser.Text);
-						this.state.context = HtmlParser.Text;
-						this.state.quote = null;
-						this.state.buffer = '';
-					}
-					else if (char !== ' ')
-						this.state.buffer += char;
-
-					break;
-			}
-		}
-		onContextChange?.(html, html.length, this.state.context, null);
-		return this.state.context;
-	}
-}
-
-HtmlParser.Attribute = 'Attribute';
-HtmlParser.Text = 'Text';
-HtmlParser.Tag = 'Tag';

package/src/PathToComment.js

@@ -1,8 +0,0 @@
-import Path from "./Path.js";
-
-// This Path renders nothing.
-export default class PathToComment extends Path {
-	constructor(nodeBefore, nodeMarker) {
-		super(nodeBefore, nodeMarker);
-	}
-}