@loadbare/app 0.13.0 → 0.15.0

package/dist/hub/lb-hub.browser.js

@@ -1,7 +1,8 @@
 /// <reference lib="dom" />
-import { ATTR_COLUMN, ATTR_COLUMN_VALUE, ATTR_KEY_VALUE, ATTR_PAGE, ATTR_PAGE_TITLE, ATTR_QUERY, ATTR_REQUEST, ATTR_REQUEST_ERROR, ATTR_REQUEST_PENDING, ATTR_URL_LINK, ATTR_URL_PUSH, ATTR_URL_UNKNOWN, HUB_TAG_NAME, KIND_ROW, LB_DONE_EVENT_NAME, LB_ENDPOINT, LB_EVENT_NAME, LB_REQUEST_TIMEOUT_MS, LB_RESERVED_PREFIX, LIVE_ROW, ORDER_PARM_PREFIX, REQUEST_ROW_DELETE, REQUEST_ROW_INSERT, REQUEST_ROW_UPDATE, URL_COLUMN_PAGE_LABEL, URL_COLUMN_PAGE_UNKNOWN, URL_COLUMN_PATH, URL_QUERY, } from "../core/lb-constants.js";
+import { ATTR_COLUMN, ATTR_COLUMN_VALUE, ATTR_KEY_VALUE, ATTR_PAGE, ATTR_PAGE_TITLE, ATTR_QUERY, ATTR_REQUEST, ATTR_REQUEST_ERROR, ATTR_REQUEST_PENDING, ATTR_REQUEST_REFUSED, ATTR_ROW_EDITING, ATTR_SELECT, ATTR_URL_LINK, ATTR_URL_PUSH, ATTR_URL_UNKNOWN, COMMAND_EDIT, COMMAND_NEW, COMMAND_RELEASE, HUB_TAG_NAME, KIND_ROW, LB_DONE_EVENT_NAME, LB_ENDPOINT, LB_EVENT_NAME, LB_REFUSAL_STATUS, LB_REQUEST_TIMEOUT_MS, LB_COMMAND_PREFIX, LB_RESERVED_PREFIX, LIVE_ROW, ORDER_PARM_PREFIX, REQUEST_ROW_DELETE, REQUEST_ROW_INSERT, REQUEST_ROW_UPDATE, URL_COLUMN_PAGE_LABEL, URL_COLUMN_PAGE_UNKNOWN, URL_COLUMN_PATH, URL_QUERY, } from "../core/lb-constants.js";
 import { isRowRequest, nextLocation, orderParm, pageNameFor, } from "../core/lb-types.js";
-import { applyResponse, forget, isControl, isFormAssociated, keptAnswer, reland, within, } from "./lb-apply.js";
+import { applyResponse, applyRow, blankRow, controlValue, select, forget, isControl, isFormAssociated, keptAnswer, reland, within, } from "./lb-apply.js";
+import { attachPlaced, detachRemoved, placed, requestDone, upgradeAbsent, } from "./lb-lifecycle.js";
 export { applyResponse, applyRow } from "./lb-apply.js";
 /** What each request Loadbare provides cannot be issued without. */
 const NEEDS = {
@@ -80,31 +81,123 @@ function groupFor(el) {
         return { controls: controlsOf(form), form, root: form };
     return null;
 }
-/** The gathered controls, with their values under their columns. */
+/**
+ * The gathered controls, with their values under their columns.
+ *
+ * A form also gathers the live rows of a query nested in its own, each with
+ * the values of its own controls, under the nested query's name: a master's
+ * details, entered beside it. One level only, since a query nested deeper
+ * shows the same rows in every row around it, and its keys would repeat. A
+ * live row gathers nothing nested.
+ */
 function gather(group) {
     const controls = [];
     const values = {};
+    const nestedControls = [];
+    const byQuery = new Map();
+    const form = group?.form;
+    const own = form
+        ? form.hasAttribute(ATTR_QUERY)
+            ? form
+            : queryOf(form)
+        : null;
     for (const el of group?.controls ?? []) {
         const column = el.getAttribute(ATTR_COLUMN);
         if (column === null || !isControl(el))
             continue;
         const nested = queryOf(el);
         if (nested && nested !== group.root && group.root.contains(nested)) {
+            const live = liveRowOf(el);
+            if (own &&
+                queryOf(nested) === own &&
+                live &&
+                queryOf(live) === nested) {
+                const name = nested.getAttribute(ATTR_QUERY);
+                const key = live.getAttribute(ATTR_KEY_VALUE);
+                const set = byQuery.get(name) ?? new Map();
+                byQuery.set(name, set);
+                const row = set.get(key) ?? {};
+                set.set(key, row);
+                row[column] = controlValue(el);
+                nestedControls.push(el);
+            }
             continue;
         }
         controls.push(el);
-        values[column] = el.value;
+        values[column] = controlValue(el);
+    }
+    const rows = {};
+    for (const [name, set] of byQuery) {
+        rows[name] = [...set].map(([key, row]) => ({ key, values: row }));
+    }
+    return { controls, values, rows, nestedControls, own };
+}
+/** The controls each request gathered, so a refusal can find them. */
+const gatheredFrom = new WeakMap();
+/** A request's round trip came back refused, with the handler's words. */
+class RefusedError extends Error {
+    refusal;
+    constructor(refusal) {
+        super(refusal.message ?? "refused");
+        this.refusal = refusal;
+        this.name = "RefusedError";
+    }
+}
+const shown = [];
+function validates(el) {
+    const v = el;
+    return (typeof v.setCustomValidity === "function" &&
+        typeof v.reportValidity === "function");
+}
+/** Take a refusal off show: its messages, and the stamp on its origin. */
+function withdraw(refused) {
+    for (const el of refused.marked)
+        el.setCustomValidity("");
+    refused.origin?.removeAttribute(ATTR_REQUEST_REFUSED);
+    shown.splice(shown.indexOf(refused), 1);
+}
+/** Withdraw every refusal whose request gathered `el`, or what holds it. */
+function edited(target) {
+    for (const refused of [...shown]) {
+        if (refused.gathered.some((c) => c === target || c.contains(target))) {
+            withdraw(refused);
+        }
     }
-    return { controls, values };
 }
 /** The form each insert gathered from, until its round trip succeeds. */
 const insertedFrom = new WeakMap();
+/**
+ * Every form a button has pointed, with the live row it is pointed at: null
+ * when it was started empty, for an insert.
+ */
+const pointed = new WeakMap();
+/** The pointed form each request gathered from, until it succeeds. */
+const savedFrom = new WeakMap();
+/**
+ * The `lb-select` checkboxes showing for a query, under the hub an element
+ * is in. One parked by `lb-show` is in template content, out of reach, so
+ * only a selection the user can see counts.
+ */
+function selectorsFor(el, query) {
+    const root = el.closest(HUB_TAG_NAME) ?? el.ownerDocument;
+    return [...root.querySelectorAll(`[${ATTR_SELECT}]`)].filter((box) => {
+        const live = liveRowOf(box);
+        return live !== null && queryOf(live)?.getAttribute(ATTR_QUERY) === query;
+    });
+}
+/** The keys of the rows a query's showing checkboxes select. */
+function selectedKeys(boxes) {
+    return boxes
+        .filter((box) => box.checked)
+        .map((box) => liveRowOf(box).getAttribute(ATTR_KEY_VALUE));
+}
 /**
  * Complete a request from where its element sits. Every request passes
  * through here, whoever issued it; a field it already carries is its
  * issuer's to decide and is left as it is.
  *
- * False when the request cannot be issued, having said why.
+ * False when the request cannot be issued, having said why, or when it is
+ * an update or delete for a row not yet entered, which is not sent.
  */
 function complete(request, el) {
     if (!request?.name) {
@@ -118,10 +211,19 @@ function complete(request, el) {
         return false;
     }
     const group = groupFor(el);
-    const { controls, values } = gather(group);
+    const { controls, values, rows, nestedControls, own } = gather(group);
+    gatheredFrom.set(request, [...controls, ...nestedControls]);
     if (request.values === undefined && controls.length > 0) {
         request.values = values;
     }
+    // A form's nested rows go with what it writes, and not with a delete. A
+    // form of nested rows alone still writes, with no values of its own.
+    if (request.rows === undefined &&
+        Object.keys(rows).length > 0 &&
+        name !== REQUEST_ROW_DELETE) {
+        request.rows = rows;
+        request.values ??= {};
+    }
     // The request is for the nearest `lb-query` of what it gathered, or of the
     // element itself when it gathered nothing.
     const queries = new Set(controls.map(queryOf));
@@ -129,21 +231,66 @@ function complete(request, el) {
         console.error(`lb-hub: '${name}' gathered controls of more than one query, not sent`, el);
         return false;
     }
-    const from = controls[0] ?? el;
-    const query = controls.length > 0 ? [...queries][0] : queryOf(el);
-    if (query) {
-        request.query ??= query.getAttribute(ATTR_QUERY);
-        const key = keyFrom(from, query);
-        if (key !== undefined)
+    // A form of nested rows alone is for its own query, and keyed by the row
+    // landed on it or the row it is pointed at, if any.
+    if (controls.length === 0 && nestedControls.length > 0 && own) {
+        request.query ??= own.getAttribute(ATTR_QUERY);
+        const key = own.getAttribute(ATTR_KEY_VALUE);
+        if (key !== null)
             request.key ??= key;
     }
+    else {
+        const from = controls[0] ?? el;
+        const query = controls.length > 0 ? [...queries][0] : queryOf(el);
+        if (query) {
+            request.query ??= query.getAttribute(ATTR_QUERY);
+            const key = keyFrom(from, query);
+            if (key !== undefined)
+                request.key ??= key;
+        }
+    }
     if (name === REQUEST_ROW_INSERT && group?.form) {
         insertedFrom.set(request, group.form);
     }
+    if (group?.form && pointed.has(group.form)) {
+        savedFrom.set(request, group.form);
+    }
+    // A row not yet entered: its key is empty, from a `row` the server
+    // answered with no key yet, or from a form New pointed. It has no key to
+    // send, and nothing on record to update or delete, so those two are not
+    // sent. That is the row's state, not a mistake, and nothing is reported.
+    const unentered = request.key === "";
+    if (unentered) {
+        delete request.key;
+        if (name === REQUEST_ROW_UPDATE || name === REQUEST_ROW_DELETE) {
+            return false;
+        }
+    }
+    // A request that names no one row acts on the rows the user selected,
+    // when its query shows checkboxes to select them by. An insert adds a row
+    // and selects nothing. With none ticked, an update or a delete has
+    // nothing to act on, and is not sent, as for a row not yet entered.
+    if (request.key === undefined &&
+        request.keys === undefined &&
+        request.query !== undefined &&
+        !unentered &&
+        name !== REQUEST_ROW_INSERT) {
+        const boxes = selectorsFor(el, request.query);
+        if (boxes.length > 0) {
+            request.keys = selectedKeys(boxes);
+            if (request.keys.length === 0 &&
+                (name === REQUEST_ROW_UPDATE || name === REQUEST_ROW_DELETE)) {
+                return false;
+            }
+        }
+    }
     const needs = NEEDS[name];
     if (needs) {
-        const missing = needs.filter((field) => request[field] === undefined ||
-            (field === "values" && Object.keys(request.values).length === 0));
+        const missing = needs.filter((field) => (request[field] === undefined &&
+            !(field === "key" && request.keys !== undefined)) ||
+            (field === "values" &&
+                Object.keys(request.values).length === 0 &&
+                request.rows === undefined));
         if (missing.length > 0) {
             console.error(`lb-hub: '${name}' from <${el.localName}> has no ` +
                 `${missing.join(", ")}, not sent`, el);
@@ -245,6 +392,10 @@ async function fetchItems(page, request) {
             body: JSON.stringify(request ?? {}),
             signal: controller.signal,
         });
+        if (res.status === LB_REFUSAL_STATUS) {
+            const body = (await res.json().catch(() => ({})));
+            throw new RefusedError(body.refusal ?? {});
+        }
         if (!res.ok) {
             throw new Error(`lb-hub: server responded ${res.status} for ${url}`);
         }
@@ -260,6 +411,7 @@ function pending(el, on) {
         return;
     if (on) {
         el.removeAttribute(ATTR_REQUEST_ERROR);
+        el.removeAttribute(ATTR_REQUEST_REFUSED);
         el.setAttribute(ATTR_REQUEST_PENDING, "");
         el.setAttribute("aria-busy", "true");
     }
@@ -269,15 +421,21 @@ function pending(el, on) {
     }
 }
 /**
- * Tell the element that committed how its request turned out. Raised after
- * everything the request brought back has landed, so a listener sees the
- * page as the answer left it, and `lb-request-pending` is already gone.
+ * Tell the element that committed how its request turned out: the custom
+ * elements from it outward first, then any listener. Told after everything
+ * the request brought back has landed, so each sees the page as the answer
+ * left it, and `lb-request-pending` is already gone.
  */
 function done(origin, request, landed) {
-    const detail = landed instanceof Error
-        ? { request, items: [], error: landed }
-        : { request, items: landed };
-    origin?.dispatchEvent(new CustomEvent(LB_DONE_EVENT_NAME, { bubbles: true, detail }));
+    const detail = landed instanceof RefusedError
+        ? { request, items: [], error: landed, refusal: landed.refusal }
+        : landed instanceof Error
+            ? { request, items: [], error: landed }
+            : { request, items: landed };
+    if (!origin)
+        return;
+    requestDone(origin, detail);
+    origin.dispatchEvent(new CustomEvent(LB_DONE_EVENT_NAME, { bubbles: true, detail }));
 }
 /** What can take focus, before asking whether it can be operated. */
 const FOCUSABLE = `a[href], button, input:not([type="hidden"]), select, textarea, ` +
@@ -293,7 +451,11 @@ const FOCUSABLE = `a[href], button, input:not([type="hidden"]), select, textarea
 function focusFirst(main) {
     if (main.contains(document.activeElement))
         return;
-    for (const el of main.querySelectorAll(FOCUSABLE)) {
+    focusIn(main);
+}
+/** Focus the first element in `root` the user can operate. */
+function focusIn(root) {
+    for (const el of root.querySelectorAll(FOCUSABLE)) {
         if (el.matches(":disabled"))
             continue;
         if (el.closest(`dialog:not([open]), [inert], [hidden]`))
@@ -305,6 +467,47 @@ function focusFirst(main) {
             return;
     }
 }
+/**
+ * Empty a form of whatever row it showed: every column it names lands as
+ * null, so text and `lb-show` read as no row, and then the form resets, so
+ * each control returns to its default.
+ */
+function clear(form) {
+    pointed.get(form)?.removeAttribute(ATTR_ROW_EDITING);
+    applyRow(form, blankRow(form));
+    form.reset();
+}
+/**
+ * Point a form at a row: fill it from the row and key it by the row's key,
+ * so gathering sends that key. With no row, the form starts empty and its
+ * key is empty, for an insert. A form inside a `<dialog>` opens it.
+ */
+function point(form, row, key, live) {
+    clear(form);
+    if (row)
+        applyRow(form, row);
+    form.setAttribute(ATTR_KEY_VALUE, key);
+    live?.setAttribute(ATTR_ROW_EDITING, "");
+    pointed.set(form, live);
+    const dialog = form.closest("dialog");
+    if (dialog && !dialog.open)
+        dialog.showModal();
+    focusIn(form);
+}
+/**
+ * Let a pointed form go: empty it and drop its key. A form inside a
+ * `<dialog>` closes it, and the dialog's `close` finds nothing left to do.
+ */
+function release(form) {
+    if (!pointed.has(form))
+        return;
+    clear(form);
+    form.removeAttribute(ATTR_KEY_VALUE);
+    pointed.delete(form);
+    const dialog = form.closest("dialog");
+    if (dialog?.open)
+        dialog.close();
+}
 /**
  * The URL a round trip answers for: its path and its query string. An answer
  * that returns to another is not landed.
@@ -354,6 +557,12 @@ class LbHub extends HTMLElement {
      * same page does not set it: the user is where they chose to be.
      */
     entering = false;
+    /**
+     * What the hub has shown and not yet placed: the chrome when it starts,
+     * and <main> each time it shows a page. Placed as the page's first answer
+     * lands, so each custom element in it is filled before it is attached.
+     */
+    unplaced = [];
     connectedCallback() {
         this.main = this.querySelector("main");
         // Completed in the capture phase, on the way down, so every ancestor
@@ -395,12 +604,30 @@ class LbHub extends HTMLElement {
         });
         // A reset returns a form's controls to their defaults, so none of them
         // shows what landed any longer. The browser resets the controls; the
-        // hub drops its own stamp from the same controls a submit gathers.
+        // hub drops its own stamp from the same controls a submit gathers, and
+        // any refusal they were answering.
         this.addEventListener("reset", (e) => {
             if (e.defaultPrevented)
                 return;
             for (const el of controlsOf(e.target)) {
                 el.removeAttribute(ATTR_COLUMN_VALUE);
+                edited(el);
+            }
+        });
+        // An edit to anything a refused request gathered withdraws the refusal.
+        // Heard on the way down, so a control's own request on change goes out
+        // with its message already gone.
+        for (const type of ["input", "change"]) {
+            this.addEventListener(type, (e) => {
+                if (shown.length > 0)
+                    edited(e.target);
+            }, { capture: true });
+        }
+        // A selector selects its row, and is no column.
+        this.addEventListener("change", (e) => {
+            const box = e.target;
+            if (box?.hasAttribute(ATTR_SELECT)) {
+                select(box, box.checked);
             }
         });
         // A control commits on change.
@@ -446,17 +673,85 @@ class LbHub extends HTMLElement {
             this.moveTo(row, true);
             void this.navigate();
         });
+        // A button points a form with HTML's own commandfor and command. The
+        // command event goes to the form and does not bubble, so it is heard on
+        // the way down.
+        this.addEventListener("command", (e) => {
+            const { command, source } = e;
+            if (!command?.startsWith(LB_COMMAND_PREFIX))
+                return;
+            const form = e.target;
+            if (form.localName !== "form" || !form.hasAttribute(ATTR_QUERY)) {
+                console.error(`lb-hub: '${command}' is for a <form> carrying ${ATTR_QUERY}, ` +
+                    `not <${form.localName}>, ignoring`, form);
+                return;
+            }
+            this.command(command, form, source ?? null);
+        }, { capture: true });
+        // A dialog closes however HTML closes it — Escape, a close command,
+        // `method="dialog"` — and a form pointed inside it lets go.
+        this.addEventListener("close", (e) => {
+            const dialog = e.target;
+            if (dialog.localName !== "dialog")
+                return;
+            for (const form of dialog.querySelectorAll("form"))
+                release(form);
+        }, { capture: true });
         addEventListener("popstate", () => void this.navigate());
+        upgradeAbsent(this, document);
+        this.unplaced = [...this.children];
         void this.navigate();
     }
+    /**
+     * A command for a form. Edit fills the form from the row the button sits
+     * in, as the hub holds it: no round trip, since the user can only edit a
+     * row they can see.
+     */
+    command(command, form, source) {
+        const query = form.getAttribute(ATTR_QUERY);
+        switch (command) {
+            case COMMAND_EDIT: {
+                const live = source ? liveRowOf(source) : null;
+                if (!live || queryOf(live)?.getAttribute(ATTR_QUERY) !== query) {
+                    console.error(`lb-hub: '${command}' comes from no row of '${query}', ignoring`, source);
+                    return;
+                }
+                const key = live.getAttribute(ATTR_KEY_VALUE);
+                const item = keptAnswer(this, query);
+                const row = item?.rows?.find((r) => String(r[item.key]) === key);
+                if (!row) {
+                    console.error(`lb-hub: the hub holds no row of '${query}' keyed '${key}', ` +
+                        `ignoring`);
+                    return;
+                }
+                point(form, row, key, live);
+                return;
+            }
+            case COMMAND_NEW:
+                point(form, null, "", null);
+                return;
+            case COMMAND_RELEASE:
+                release(form);
+                return;
+            default:
+                console.error(`lb-hub: '${command}' begins with '${LB_COMMAND_PREFIX}' but ` +
+                    `names no command Loadbare provides, ignoring`);
+        }
+    }
     /**
      * Send a request to the server and land its answer. An answer naming
      * `lb-url` moves the URL first; the server has already loaded the page
      * there, in the same round trip.
      */
     async send(request, origin) {
+        // Sending again answers the last refusal from here, whatever it said.
+        for (const refused of shown.filter((r) => r.origin === origin)) {
+            withdraw(refused);
+        }
         const at = here();
         const items = await this.roundTrip(this.page, request, origin);
+        if (items instanceof RefusedError)
+            this.refused(request, items, origin);
         if (items instanceof Error)
             return done(origin, request, items);
         let landed = [];
@@ -474,9 +769,43 @@ class LbHub extends HTMLElement {
             else
                 landed = await this.follow(url, load, origin);
         }
-        insertedFrom.get(request)?.reset();
+        // The selected rows have been acted on, and the selection is done.
+        if (request.keys !== undefined && request.query !== undefined) {
+            for (const box of selectorsFor(this, request.query))
+                select(box, false);
+        }
+        // A pointed form has done what it was pointed for, and lets go.
+        const saved = savedFrom.get(request);
+        if (saved)
+            release(saved);
+        else
+            insertedFrom.get(request)?.reset();
         done(origin, request, landed);
     }
+    /**
+     * Show a refusal. The message for the request as a whole is stamped on the
+     * element that committed, for a stylesheet to show. Each column's message
+     * goes on the control the request gathered it from, as HTML's own
+     * validity, and the first is reported: the browser shows its message
+     * there and moves focus to it.
+     */
+    refused(request, { refusal }, origin) {
+        const gathered = gatheredFrom.get(request) ?? [];
+        const marked = [];
+        for (const [column, message] of Object.entries(refusal.columns ?? {})) {
+            const control = gathered.find((c) => c.getAttribute(ATTR_COLUMN) === column);
+            if (!control || !validates(control)) {
+                console.warn(`lb-hub: '${request.name}' was refused for '${column}', but ` +
+                    `gathered no control there that takes a message`);
+                continue;
+            }
+            control.setCustomValidity(message);
+            marked.push(control);
+        }
+        origin?.setAttribute(ATTR_REQUEST_REFUSED, refusal.message ?? "");
+        shown.push({ gathered, marked, origin });
+        marked[0]?.reportValidity();
+    }
     /**
      * One round trip for a page: a request, or with none a page load. The
      * element that issued it carries `lb-request-pending` while it is in
@@ -488,6 +817,10 @@ class LbHub extends HTMLElement {
             return await fetchItems(page, request);
         }
         catch (err) {
+            // A refusal is the handler's answer, not a failure: the request's
+            // sender shows it, and nothing is reported.
+            if (err instanceof RefusedError)
+                return err;
             console.error(`lb-hub: request failed for '${page}'`, err);
             origin?.setAttribute(ATTR_REQUEST_ERROR, "");
             return err instanceof Error ? err : new Error(String(err));
@@ -575,8 +908,11 @@ class LbHub extends HTMLElement {
             return again instanceof Error ? [item] : [item, ...again];
         }
         const template = this.arrive();
+        this.place();
         if (template)
             applyResponse(this, load, LANDING);
+        else
+            attachPlaced();
         this.entered();
         return template ? [item, ...load] : [item];
     }
@@ -598,13 +934,18 @@ class LbHub extends HTMLElement {
      */
     async navigate(origin) {
         const template = this.arrive();
-        if (!template)
+        if (!template) {
+            this.place();
+            attachPlaced();
             return [];
+        }
         const at = here();
         const items = await this.roundTrip(this.page, undefined, origin);
         if (here() !== at)
             return items instanceof Error ? items : [];
         if (items instanceof Error) {
+            this.place();
+            attachPlaced();
             this.entered();
             return items;
         }
@@ -614,10 +955,20 @@ class LbHub extends HTMLElement {
         if (url) {
             return this.follow(url, items.filter((item) => item !== url), origin);
         }
+        this.place();
         applyResponse(this, items, LANDING);
         this.entered();
         return items;
     }
+    /**
+     * Place what the hub has shown since it last placed anything, for the
+     * landing that follows to attach.
+     */
+    place() {
+        for (const root of this.unplaced)
+            placed(root);
+        this.unplaced = [];
+    }
     /**
      * A page that was entered has landed its queries, so its first control
      * exists: a row cloned, a branch shown, a picker's options in place.
@@ -640,7 +991,12 @@ class LbHub extends HTMLElement {
             // The template is already in the document, so the page's markup goes
             // in before its data arrives rather than leaving <main> empty. What
             // the last page's queries answered goes with it.
+            const last = [...this.main.childNodes];
             this.main.replaceChildren(template.content.cloneNode(true));
+            detachRemoved(last);
+            upgradeAbsent(this.main, document);
+            if (!this.unplaced.includes(this.main))
+                this.unplaced.push(this.main);
             forget(this);
             this.entering = true;
         }