@loadbare/app 0.9.0 → 0.11.0

package/dist/hub/lb-apply.js

@@ -1,26 +1,27 @@
 /// <reference lib="dom" />
 /**
- * Landing data on a live host — see docs/reference/data-binding.md.
+ * Landing — see docs/reference/data-binding.md.
  *
- * One containment ladder, and one function per rung. `applyData` lands a
- * whole response, `applyList` lands one list result, `applyRow` fills one
- * scope from one row. Filling a live row and filling a single-row scope are
- * the same operation, and the only difference is how much of the page the
- * root covers.
+ * The hub lands a response item's rows on every element whose `lb-query`
+ * names its query. The item says the query's kind and key, so the markup
+ * says neither:
  *
- * The row machinery used to live in its own file because every list widget
- * imported and called it. The hub reconciles a list scope itself now, so a
- * widget supplies placement and scaffolding through two optional hooks and
- * never sees a whole result. Cloning the template, matching a row to the
- * element already showing it, and filling that element are the same in every
- * list, so no widget can get them wrong.
+ *   kind   row template   the hub
+ *   row    no             lands the row on the element itself
+ *   row    yes            lands one live row
+ *   rows   yes            lands one live row per row
+ *   rows   no             lands nothing
+ *
+ * Filling a live row and filling an element a `row` lands on are the same
+ * operation, and the only difference is how much of the page the root
+ * covers.
  *
  * A condition is the one other thing landing moves. An element whose
  * `lb-show` column is off stands in the document inside a template, and
  * landing reaches in there as it reaches everywhere else, so a branch that
  * returns is already current. Nothing but landing reaches in.
  */
-import { ATTR_CELL, ATTR_KEY, ATTR_KEY_VALUE, ATTR_LIST, ATTR_QUERY_PARM, ATTR_ROW, ATTR_ROW_COUNT, ATTR_SHOW, ATTR_VALUE, } from "../core/lb-constants.js";
+import { ATTR_COLUMN, ATTR_COLUMN_VALUE, ATTR_KEY_VALUE, ATTR_QUERY, ATTR_QUERY_ROW_COUNT, ATTR_ROW_LIVE, ATTR_SHOW, KIND_ROW, LIVE_ROW, } from "../core/lb-constants.js";
 import { isPatch, } from "../core/lb-types.js";
 /** The template holding an absent branch — see ATTR_SHOW. */
 const PARKED = `template[${ATTR_SHOW}]`;
@@ -29,64 +30,73 @@ const FRAGMENT_NODE = 11;
 /** The input types whose state is not their `value`, or cannot be set. */
 const UNLANDED_INPUTS = ["checkbox", "radio", "file"];
 /**
- * A form control whose state is its `value`: a `<select>`, a `<textarea>`,
- * or an `<input>` of any type but checkbox, radio and file. Landing and
- * gathering draw the same line, so a value read back from a form is the one
- * that landed there.
+ * A native control whose state is its `value`: a `<select>`, a
+ * `<textarea>`, or an `<input>` of any type but checkbox, radio and file.
  *
  * Told apart by tag name and type rather than by class, so it holds for an
  * element from any document.
  */
-export function isValueControl(el) {
+function isNativeControl(el) {
     if (el.localName === "select" || el.localName === "textarea")
         return true;
     return (el.localName === "input" &&
         !UNLANDED_INPUTS.includes(el.type));
 }
 /**
- * A cell lands one of three ways. A custom element owns whatever control it
- * wraps, so it receives the value as an attribute and renders it itself.
- * Because the browser runs `attributeChangedCallback` for attributes already
- * present when a widget upgrades, that is the same operation whether the host
- * was inserted a microsecond ago or an hour ago.
- *
- * A form control shows its state as its `value`, so that is where the value
- * goes; its text is its options, for a select. Any other native element has
- * no behavior of its own, so its value is its text. Either one also carries
- * the value as `lb-value`, so a stylesheet can select on what landed.
- * Checkboxes and radio buttons are not implemented, and receive nothing — see
- * docs/TECHREF-1.0.md, "Blockers".
+ * A form-associated custom element with a `value` property. HTML marks one
+ * with `static formAssociated = true` on its class, and a control has a value.
+ */
+export function isFormAssociated(el) {
+    const ctor = el.constructor;
+    return ctor.formAssociated === true && "value" in el;
+}
+/**
+ * A control: an `<input>`, `<select>` or `<textarea>`, or a form-associated
+ * custom element with a `value` property. Landing and gathering draw the
+ * same line, so a value read back is the one that landed there.
+ */
+export function isControl(el) {
+    return isNativeControl(el) || isFormAssociated(el);
+}
+/**
+ * Set an element from a column. A control's `value` is set. A custom element
+ * that is not a control keeps its content, which the builder placed there
+ * from its element file, and renders the stamp instead. Any other element's
+ * text content is set. Every one carries the value as `lb-column-value`.
  */
 function land(el, value) {
     // Untouched, whatever the server sent: the browser decides what a
     // non-string looks like. See Row in core/lb-types.ts.
-    if (el.localName.includes("-")) {
-        el.setAttribute(ATTR_VALUE, value);
+    if (value === null || value === undefined) {
+        if (isControl(el))
+            el.value = "";
+        else if (!el.localName.includes("-") && el.localName !== "input") {
+            el.textContent = "";
+        }
+        el.removeAttribute(ATTR_COLUMN_VALUE);
+        return;
     }
-    else if (isValueControl(el)) {
+    if (isControl(el)) {
         el.value = value;
-        el.setAttribute(ATTR_VALUE, value);
     }
     else if (el.localName === "input") {
         console.warn(`lb-hub: a value does not land on <input type="${el.type}">, ignoring`, el);
+        return;
     }
-    else {
+    else if (!el.localName.includes("-")) {
         el.textContent = value;
-        el.setAttribute(ATTR_VALUE, value);
     }
+    el.setAttribute(ATTR_COLUMN_VALUE, value);
 }
 /**
- * Whether an element under `root` belongs to root's scope, rather than to a
- * scope nested inside it.
+ * Whether an element under `root` belongs to root's query, rather than to a
+ * query nested inside it.
  *
- * Both scope attributes scope their DOM children, and a nested one of either
- * kind begins a new scope (docs/reference/data-binding.md). So a descendant
- * is in root's scope unless something between it and root carries one. The
- * element's own attribute does not count: it names what the element
- * displays, and where it belongs is its ancestors', so a picker carrying
- * `lb-list` and `lb-cell` is a cell of the row around it. Root's own
- * attribute does not count either: root is the scope being filled, whatever
- * it carries.
+ * A descendant is root's unless something between it and root carries
+ * `lb-query`. The element's own `lb-query` does not count: it names what the
+ * element holds, and the row it reads from is its ancestors'. So a picker
+ * carrying `lb-query` and `lb-column` is set from the row around it. Root's
+ * own attribute does not count either: root is what is being filled.
  *
  * Root may be the content of a template holding an absent branch. The walk
  * up from an element inside it stops at the top of that content, which has
@@ -94,17 +104,17 @@ function land(el, value) {
  */
 function inScope(root, el) {
     for (let node = el.parentElement; node && node !== root;) {
-        if (node.hasAttribute(ATTR_LIST) || node.hasAttribute(ATTR_ROW)) {
+        if (node.hasAttribute(ATTR_QUERY))
             return false;
-        }
         node = node.parentElement;
     }
     return true;
 }
 /**
- * Root if it matches, then every descendant in root's scope that does.
- * Gathering finds cells through here. It does not reach into an absent
- * branch, so a form reads back from the places a row lands that are showing.
+ * Root if it matches, then every descendant in root's query that does.
+ * Gathering finds columns through here. It does not reach into an absent
+ * branch, so a live row is read back from the places a row lands that are
+ * showing.
  */
 export function within(root, selector) {
     const found = root.matches(selector) ? [root] : [];
@@ -115,11 +125,11 @@ export function within(root, selector) {
     return found;
 }
 /**
- * Every descendant in root's scope that matches, absent branches included.
+ * Every descendant in root's query that matches, absent branches included.
  *
  * `querySelectorAll` does not enter template content, so an element that is
  * off would otherwise miss everything landed while it was away, and return
- * stale or with its lists empty. A template holding one is in root's scope by
+ * stale or with its rows empty. A template holding one is in root's query by
  * the ordinary rule, and its content is searched as if it stood there.
  */
 function below(root, selector) {
@@ -135,15 +145,9 @@ function below(root, selector) {
     }
     return found;
 }
-/** What `within` is for gathering, `reach` is for landing. */
-function reach(root, selector) {
-    const found = below(root, selector);
-    return root.matches(selector) ? [root, ...found] : found;
-}
 /**
- * Every element in a whole response's root that matches, absent branches
- * included. A name is looked up this way before any scope is known, so
- * nothing is filtered out by scope.
+ * Every element in root that matches, absent branches included. A query is
+ * looked up this way before any row is known, so nothing is filtered out.
  */
 function everywhere(root, selector) {
     const found = [...root.querySelectorAll(selector)];
@@ -158,9 +162,9 @@ function everywhere(root, selector) {
  * says.
  *
  * Off is inside a template that stands where the element stood, carrying the
- * same `lb-show`. The element is moved rather than rebuilt, so a widget keeps
- * its instance and a control keeps what was typed into it. On moves it back
- * and the template goes.
+ * same `lb-show`. The element is moved rather than rebuilt, so a custom
+ * element keeps its instance and a control keeps what was typed into it. On
+ * moves it back and the template goes.
  *
  * Landing reaches into that template, so both it and the element it holds
  * arrive here. The template decides; the element it holds, whose parent is
@@ -181,23 +185,27 @@ function present(el, on) {
     parked.content.append(el);
 }
 /**
- * Fill one scope from one row.
+ * Fill from one row: every `lb-column` and `lb-show` in root's query.
  *
- * The root counts as a cell if it carries one. A `<tr>` holds its cells in
- * `<td>` children, but `<option>`'s content model is text, so an option row
- * has to be the cell it displays. Requiring a wrapper there would require an
- * element HTML does not allow.
+ * A live row is its own row, so its root counts when it carries
+ * `lb-column`: `<option>`'s content model is text, so an option row has to
+ * be the column it displays. An element a `row` lands on is not its own
+ * ancestor, so its own `lb-column` reads from the row around it and is left
+ * alone here.
  */
-export function applyRow(root, row) {
+export function applyRow(root, row, liveRow = false) {
     for (const [column, value] of Object.entries(row)) {
-        for (const el of reach(root, `[${ATTR_CELL}="${column}"]`)) {
+        const selector = `[${ATTR_COLUMN}="${column}"]`;
+        const columns = below(root, selector);
+        if (liveRow && root.matches(selector))
+            columns.unshift(root);
+        for (const el of columns)
             land(el, value);
-        }
         // Only null and false are off. A string is never read, so "false" is on,
         // and the query spells a condition as a boolean or a null.
         //
-        // Never the root's own: a scope's condition is a cell of the row around
-        // it, the way its lb-cell is, and a row template's root carries none.
+        // Never the root's own: a row template's root carries none, and the
+        // element a row lands on reads its condition from the row around it.
         const on = value !== null && value !== false;
         for (const el of below(root, `[${ATTR_SHOW}="${column}"]`)) {
             present(el, on);
@@ -205,171 +213,159 @@ export function applyRow(root, row) {
     }
 }
 /**
- * The row template: the one the developer wrote inside this list scope, or
- * null when this scope shows nothing. A template inside a nested scope is
- * that scope's, and a template holding an absent branch is not a row
- * template: rows land before the row template, so one inside the first live
- * row comes first in document order.
- *
- * A scope with no template is bound to the list without displaying it.
- * That is not a mistake, so it is silent. A template that does not name its
- * key column is a mistake, and says so.
+ * The row template: the first `<template>` among the element's descendants,
+ * outside any nested `lb-query`. A template holding an absent branch is not a
+ * row template: rows land before the row template, so one inside the first
+ * live row comes first in document order.
  */
-function templateIn(scope) {
-    const template = within(scope, `template:not([${ATTR_SHOW}])`)[0];
-    if (!template)
-        return null;
-    if (!template.getAttribute(ATTR_KEY)) {
-        console.error(`lb-hub: the <template> in <${scope.localName}> has no ${ATTR_KEY} ` +
-            `naming the column that identifies a row`);
-        return null;
-    }
-    return template;
+export function templateIn(el) {
+    const template = within(el, `template:not([${ATTR_SHOW}])`).find((t) => t !== el);
+    return template ?? null;
 }
 /**
- * The rows already showing, by the key value each carries. Only a live row
- * carries one: the template names the key column under a different name.
- *
- * A row of a nested scope is that scope's. A row's own `lb-list` or `lb-row`
- * names what it displays, not which list it is a row of, which is the same
- * test a cell gets.
+ * The live rows of the element's query, in document order. A row of a nested
+ * query is that query's. An element a `row` query landed on carries a key and
+ * is not a live row, so a `row` shown in a table's head or foot is not one of
+ * the table's rows.
  */
-function showing(scope) {
+function liveRows(el) {
+    return [...el.querySelectorAll(LIVE_ROW)].filter((row) => inScope(el, row));
+}
+/**
+ * The live rows already showing, by the key each carries. Two live rows with
+ * one key are a mistake nothing downstream can recover from: only one of them
+ * would ever be matched, and the other would stay until the page goes.
+ */
+function showing(el) {
     const rows = new Map();
-    for (const el of scope.querySelectorAll(`[${ATTR_KEY_VALUE}]`)) {
-        if (inScope(scope, el)) {
-            rows.set(el.getAttribute(ATTR_KEY_VALUE), el);
+    for (const row of liveRows(el)) {
+        const key = row.getAttribute(ATTR_KEY_VALUE);
+        if (rows.has(key)) {
+            console.error(`lb-hub: <${el.localName}> shows two rows with the key '${key}'`);
         }
+        rows.set(key, row);
     }
     return rows;
 }
 /**
- * Land a list result in a list scope.
+ * Land rows through a row template.
  *
- * An array is the whole set, so it decides membership and order: every row is
- * placed in the order given, and a row whose key did not arrive is gone. A
- * patch disturbs only what it names — a row it did not mention keeps its
- * contents and its position.
+ * All rows decide membership and order: every row is placed in the order
+ * given, and a row whose key did not arrive is gone. A patch disturbs only
+ * what it names — a row it did not mention keeps its contents and its
+ * position.
  *
- * A widget that carries `lbPlaceRow` decides where a row goes, because only
- * it knows whether it sorts or groups. Without it a row lands immediately
- * before the template, so rows accumulate in the order they arrive and the
- * template stays put as the insertion marker.
+ * A custom element that carries `lbPlaceRow` decides where a row goes,
+ * because only it knows whether it sorts or groups. Without it a row lands
+ * immediately before the template, so rows accumulate in the order they
+ * arrive and the template stays put as the insertion marker.
  */
-export function applyList(scope, result) {
-    const template = templateIn(scope);
-    if (!template)
-        return;
-    const keyColumn = template.getAttribute(ATTR_KEY);
-    const shown = showing(scope);
-    const host = scope;
+export function applyRows(el, template, keyColumn, result) {
+    const shown = showing(el);
+    const host = el;
     const whole = !isPatch(result);
-    const place = (el, row) => {
+    const landed = new Set();
+    const place = (row, data) => {
         if (host.lbPlaceRow)
-            host.lbPlaceRow(el, row, template);
+            host.lbPlaceRow(row, data, template);
         else
-            template.parentElement.insertBefore(el, template);
+            template.parentElement.insertBefore(row, template);
     };
-    const upsert = (row) => {
-        if (row[keyColumn] === undefined) {
-            console.error(`lb-hub: a row for <${scope.localName}> has no '${keyColumn}' column`);
-            return null;
+    const upsert = (data) => {
+        if (data[keyColumn] === undefined) {
+            console.error(`lb-hub: a row for <${el.localName}> has no '${keyColumn}' column`);
+            return;
         }
         // The key is stored on the row as an attribute and read back from
         // there, so it is compared as the string the attribute holds.
-        const key = String(row[keyColumn]);
-        let el = shown.get(key);
-        const fresh = el === undefined;
-        if (!el) {
-            el = template.content.firstElementChild.cloneNode(true);
-            el.setAttribute(ATTR_KEY_VALUE, key);
-            shown.set(key, el);
+        const key = String(data[keyColumn]);
+        if (landed.has(key)) {
+            console.error(`lb-hub: two rows for <${el.localName}> have the key '${key}'; ` +
+                `the last one shows`);
+        }
+        landed.add(key);
+        let row = shown.get(key);
+        const fresh = row === undefined;
+        if (!row) {
+            // Imported rather than cloned: template content belongs to a document
+            // with no custom element definitions, so a clone would not upgrade
+            // until inserted, and a form-associated control would be filled as if
+            // it were not one.
+            row = el.ownerDocument.importNode(template.content.firstElementChild, true);
+            row.setAttribute(ATTR_ROW_LIVE, "");
+            row.setAttribute(ATTR_KEY_VALUE, key);
+            shown.set(key, row);
         }
         // Fill before insertion. The attributes are already there when the row
-        // upgrades, which is the same thing that makes hydration and refresh one
-        // operation everywhere else.
-        applyRow(el, row);
+        // upgrades, which is the same thing that makes a first landing and a
+        // refresh one operation everywhere else.
+        applyRow(row, data, true);
         if (fresh || whole)
-            place(el, row);
-        return key;
+            place(row, data);
     };
     if (Array.isArray(result)) {
-        const arrived = new Set();
-        for (const row of result) {
-            const key = upsert(row);
-            if (key !== null)
-                arrived.add(key);
-        }
-        for (const [key, el] of shown)
-            if (!arrived.has(key))
-                el.remove();
+        for (const data of result)
+            upsert(data);
+        for (const [key, row] of shown)
+            if (!landed.has(key))
+                row.remove();
     }
     else {
-        for (const row of result.rows ?? [])
-            upsert(row);
+        for (const data of result.rows ?? [])
+            upsert(data);
         for (const key of result.drop ?? [])
             shown.get(String(key))?.remove();
     }
-    // How many rows are showing, counted from the DOM rather than from either
-    // branch above, so a whole set and a patch report the same fact the same
-    // way.
-    //
-    // It is stamped here because only this function knows the count: it is the
-    // one conditional a page cannot be sent, since the server answers with rows
-    // and says nothing about how many survived reconciliation. A page says what
-    // an empty list looks like in a stylesheet, and no list widget carries code
-    // for it. See docs/reference/data-binding.md.
-    scope.setAttribute(ATTR_ROW_COUNT, String(showing(scope).size));
+    // Counted from the DOM rather than from either branch above, so all rows
+    // and a patch report the same fact the same way. Only here is the count
+    // known: the server answers with rows and says nothing about how many
+    // survived reconciliation.
+    el.setAttribute(ATTR_QUERY_ROW_COUNT, String(liveRows(el).length));
     // Derived scaffolding — a section heading, an <optgroup> — goes when its
-    // last row does, and only the widget knows it exists.
+    // last row does, and only the custom element knows it exists.
     host.lbRowsLanded?.();
 }
-/** Land a whole response. Every result arrives through here. */
-export function applyData(root, data) {
-    for (const [name, result] of Object.entries(data)) {
-        const lists = everywhere(root, `[${ATTR_LIST}="${name}"]`);
-        const rows = everywhere(root, `[${ATTR_ROW}="${name}"]`);
-        if (lists.length === 0 && rows.length === 0) {
-            console.warn(`lb-hub: no scope for '${name}', skipping`);
-            continue;
-        }
-        // Cardinality is a property of the name, so one name is a list or a row
-        // and never both. Two spellings of it on one page is a mistake in the
-        // markup rather than a case to reconcile.
-        if (lists.length > 0 && rows.length > 0) {
-            console.error(`lb-hub: '${name}' is bound as a list in one place and a row in ` +
-                `another; a name answers with one shape`);
-            continue;
+/** Land one response item on one element that names its query. */
+function landItem(el, item) {
+    const template = templateIn(el);
+    if (item.kind === KIND_ROW) {
+        const row = item.row ?? {};
+        if (template) {
+            applyRows(el, template, item.key, [row]);
+            return;
         }
-        if (lists.length > 0) {
-            for (const scope of lists)
-                applyList(scope, result);
-            continue;
-        }
-        // The only disagreement visible from here: a patch and a row are both
-        // objects, so an array arriving at a row scope is the one case the
-        // browser can name. createHub holds the stronger check, because it knows
-        // what the query declared.
-        if (Array.isArray(result)) {
-            console.error(`lb-hub: '${name}' is bound with ${ATTR_ROW} but answered with rows`);
-            continue;
+        applyRow(el, row);
+        const key = row[item.key];
+        if (key !== undefined && key !== null) {
+            el.setAttribute(ATTR_KEY_VALUE, String(key));
         }
-        for (const scope of rows)
-            applyRow(scope, result);
+        return;
     }
+    // A `rows` query with no row template lands nothing: an insert form names
+    // the query it adds to, and shows none of its rows.
+    if (!template)
+        return;
+    const result = item.patch ?? item.rows ?? [];
+    applyRows(el, template, item.key, result);
 }
 /**
- * Land the query string on every control that writes one of its parms, the
- * way a cell lands a column. A parm the URL does not carry lands empty, so a
- * control shows what the address bar says after Back as well as after a
- * reload: the URL is what is on screen, and nothing else is.
+ * Land response items. Every answer arrives through here.
  *
- * Landed after the page's data, so a picker already has the options its
- * value selects.
+ * `quiet` names queries that may have nowhere to land without a warning: the
+ * hub's own `lb-url` lands wherever a chrome or page names it, and nowhere
+ * otherwise.
  */
-export function applyQueryParms(root, parms) {
-    for (const el of everywhere(root, `[${ATTR_QUERY_PARM}]`)) {
-        land(el, parms.get(el.getAttribute(ATTR_QUERY_PARM)) ?? "");
+export function applyResponse(root, items, quiet = []) {
+    for (const item of items) {
+        const targets = everywhere(root, `[${ATTR_QUERY}="${item.query}"]`);
+        if (targets.length === 0) {
+            if (!quiet.includes(item.query)) {
+                console.warn(`lb-hub: nothing names '${item.query}', skipping`);
+            }
+            continue;
+        }
+        for (const el of targets)
+            landItem(el, item);
     }
 }
 //# sourceMappingURL=lb-apply.js.map