@loadbare/app 0.14.0 → 0.15.0

package/skills/loadbare-app/references/custom-elements.md

@@ -278,10 +278,10 @@ A custom element reads `lb-` attributes and never assigns one. The developer
 writes them in markup, and the hub and the builder write their stamps.
 
 Loadbare reserves method names beginning with `lb` on a custom element, for
-the methods it calls; see [Holding rows](#holding-rows).  The build refuses
-a script that declares a method, accessor or field whose name is `lb`, a
-capital, and anything else Loadbare does not call, so a misspelled
-`lbRowLanded` fails the build rather than never being called.
+the methods it calls; see [When its code runs](#when-its-code-runs).  The
+build refuses a script that declares a method, accessor or field whose name
+is `lb`, a capital, and anything else Loadbare does not call, so a
+misspelled `lbRowLanded` fails the build rather than never being called.
 
 ### What the hub and an element say to each other
 
@@ -291,39 +291,80 @@ Each direction has one mechanism for each kind of message:
 |----------------|--------------------------------------------|-----------------------------|-------|
 | Hub to element | State that lasts                           | An attribute the hub stamps | `lb-column-value`, `lb-key-value`, `lb-query-row-count`, `lb-group-*`, `lb-row-*`, `lb-request-pending`, `lb-request-error` |
 | Hub to element | State the platform already names           | A property                  | A control's `value` |
-| Hub to element | Work the hub needs done now, while landing | An optional `lb` method     | `lbRowsLanded` |
+| Hub to element | What the hub did                           | An optional `lb` method     | `lbAttached`, `lbRowsLanded`, `lbRequestDone`, `lbDetached` |
 | Hub to element | A moment an element started                | A bubbling event            | `lb-request-done` |
 | Element to hub | A moment                                   | A bubbling event            | `lb-request`, and `change`, `click` and `submit` |
 
-State is an attribute: a stylesheet can select on it, and an element that
-upgrades late still finds it. A method is for work the hub cannot go on
-without, done by one element at one point in landing. A moment is an event,
-because the element that cares is often an ancestor of the one it concerns,
-and an event reaches it knowing neither.
+State is an attribute, because a stylesheet can select on it. A method is
+how the hub tells one element what it just did to that element. A moment is
+an event, because the element that cares is often an ancestor of the one it
+concerns, and an event reaches it knowing neither.
 
 ### When its code runs
 
-The hub creates, places and parks elements, and each of those reaches a
-custom element as the browser's lifecycle callbacks. It is the same instance
-from its constructor on, however often it moves:
+The hub tells a custom element what it did through four optional methods,
+named for the hub's own work. The `HubLifecycle` interface in
+`@loadbare/app/types` declares them. Here is an element that closes its
+popup on Escape, listening on `document` only while the hub has it on the
+page:
 
-| What the hub does                                  | Callbacks, in order                         |
-|----------------------------------------------------|---------------------------------------------|
-| Shows a page                                       | `constructor`, `connectedCallback`          |
-| Creates a live row, filled before it is placed     | `constructor`                               |
-| Places a live row for the first time               | `connectedCallback`                         |
-| Places it again, as it does on every set of all rows | `disconnectedCallback`, `connectedCallback` |
-| Removes a live row                                 | `disconnectedCallback`                      |
-| Turns `lb-show` off                                | `disconnectedCallback`, `adoptedCallback`   |
-| Turns `lb-show` on                                 | `adoptedCallback`, `connectedCallback`      |
-| Turns on an element the builder shipped absent     | `constructor`, `connectedCallback`          |
+```ts
+// src/note-popup.browser.ts
+import type { HubLifecycle } from "@loadbare/app/types";
+
+class NotePopup extends HTMLElement implements HubLifecycle {
+  #onKey = (e: KeyboardEvent) => {
+    if (e.key === "Escape") this.querySelector("dialog")?.close();
+  };
 
-The builder ships every `lb-show` element inside its template, and nothing
-in a template is upgraded, so such an element has no instance until its
-column first turns on. See
-[Conditional rendering](./data-binding.md#conditional-rendering).
+  lbAttached() {
+    document.addEventListener("keydown", this.#onKey);
+  }
 
-So each kind of work has one place:
+  lbDetached() {
+    document.removeEventListener("keydown", this.#onKey);
+  }
+}
+
+customElements.define("note-popup", NotePopup);
+```
+
+| Method                          | The hub calls it                                                  |
+|---------------------------------|-------------------------------------------------------------------|
+| `lbAttached()`                  | Once, after it places the element and every column has landed on it |
+| `lbRowsLanded()`                | After rows land on the element, with every row placed and stamped |
+| `lbRequestDone(detail, origin)` | After a request committed by the element, or inside it, has finished |
+| `lbDetached()`                  | Once, after it removes the element                                |
+
+The hub places an element when it starts up the chrome, shows a page,
+creates a live row, or builds a group. It places the chrome and a page as
+the page's first answer lands, or once that round trip fails, so an element
+in either hears `lbAttached` with the page's data in place. It removes an
+element when a live row or a group has finished leaving, and when it shows
+another page in place of the one holding it. Write setup in `lbAttached` and its undoing in
+`lbDetached`; the two pair exactly, so neither guards against running
+twice.
+
+Moving a row and turning `lb-show` off and on are neither placing nor
+removing. The element keeps its instance and hears nothing. An element
+under an `lb-show` that is off is placed inside its template, so its
+`lbAttached` runs whether or not it shows. Measure and focus when the user
+acts, never in `lbAttached`, where the element may not be rendered.
+
+The hub calls `lbAttached` on an outer custom element before the ones
+inside it, and `lbDetached` on the inner ones first. A table that sets the
+`form` attribute on its controls in `lbAttached` does so before each control
+hears its own.
+
+An element a script creates hears none of the four, and neither does the
+copy of a moved row the hub leaves behind while it fades. The hub calls
+them only on what it places.
+
+Never write `connectedCallback`, `disconnectedCallback`, `adoptedCallback`
+or `connectedMoveCallback`. The browser calls those on every move, and the
+build refuses a script that declares one.
+
+Each kind of work then has one place:
 
 1. **A listener on the element itself goes in the constructor.** It is
    attached once and survives every move, and a live row gets its own
@@ -331,15 +372,11 @@ So each kind of work has one place:
    element, so the listener needs no child to exist yet. The constructor
    reads no attribute and no child: an element made with
    `document.createElement` has neither when it runs.
-2. **A child is looked up when it is needed**, in a handler, a getter,
-   or `lbRowsLanded`, and never held from setup.
-3. **`connectedCallback` runs on every move**, so it is written to run
-   again. It rearranges the element's own children into a state it checks
-   for first, or adds a listener to `document` or `window`, which
-   `disconnectedCallback` removes. Work done once per instance that needs
-   the element's attributes, such as a control taking up a value that landed
-   before it upgraded, goes behind a flag there; see
-   [Being a control](#being-a-control).
+2. **A child is looked up when it is needed**, in a handler, a getter, or
+   one of the four methods, and never held from setup.
+3. **Work done once per instance goes in `lbAttached`**, with its undoing
+   in `lbDetached`: rearranging the element's own children, or a listener on
+   `document` or `window`.
 
 ### Being a control
 
@@ -350,20 +387,10 @@ and commits its `lb-request` on `change`:
 
 ```ts
 // src/star-rating.browser.ts
-import { ATTR_COLUMN_VALUE } from "@loadbare/app/constants";
-
 class StarRating extends HTMLElement {
   static formAssociated = true;
   #internals = this.attachInternals();
   #value = "";
-  #connected = false;
-
-  connectedCallback() {
-    if (this.#connected) return;
-    this.#connected = true;
-    const stamped = this.getAttribute(ATTR_COLUMN_VALUE);
-    if (stamped !== null) this.value = stamped;
-  }
 
   get value(): string {
     return this.#value;
@@ -399,14 +426,6 @@ customElements.define("star-rating", StarRating);
 Dispatch `change` with `bubbles: true`, as a native control's does, when the
 user commits an edit. Setting `value` from the hub fires nothing.
 
-A control can receive its value before it is a control. An element the
-builder shipped absent, or one whose definition loads after the hub has
-landed, is not upgraded when its column lands, so the hub cannot set its
-`value` and the value arrives as `lb-column-value` alone. Take the stamp up
-the first time the control connects, as `connectedCallback` does above, and
-never again: after that the hub sets `value` itself, and a later move must
-not undo an edit.
-
 A form owns a form-associated custom element the way it owns an `<input>`,
 including through the HTML `form` attribute, so a form gathers it on submit.
 Write `formResetCallback` to restore the default value: the hub resets a form
@@ -571,23 +590,28 @@ Let the event bubble, so an ancestor can stop it before the hub sends it.
 ### Hearing how it turned out
 
 Once what a request brought back has landed, or its round trip has failed,
-the hub dispatches `lb-request-done` from the element that committed. It
-bubbles, so the element that cares need not be the one that committed: a
-dialog hears it from the form inside it.
+the hub calls `lbRequestDone(detail, origin)` on the custom element that
+committed and on every custom element around it, innermost first. `origin`
+is the element that committed, so the element that cares need not be the
+one that committed: a dialog hears it from the form inside it.
 
 ```ts
-import { LB_DONE_EVENT_NAME } from "@loadbare/app/constants";
-import type { HubRequestDone } from "@loadbare/app/types";
-
-this.addEventListener(LB_DONE_EVENT_NAME, (e) => {
-  const { request, items, error } = (e as CustomEvent<HubRequestDone>).detail;
-  if (error) return;
-  const item = items.find((i) => i.query === request.query);
-  const created = item?.patch?.rows?.[0];
-  if (created) this.choose(String(created[item!.key]));
-});
+import type { HubLifecycle, HubRequestDone } from "@loadbare/app/types";
+
+class NewRowDialog extends HTMLElement implements HubLifecycle {
+  lbRequestDone({ request, items, error }: HubRequestDone) {
+    if (error) return;
+    const item = items.find((i) => i.query === request.query);
+    const created = item?.patch?.rows?.[0];
+    if (created) this.choose(String(created[item!.key]));
+  }
+}
 ```
 
+The hub then dispatches `lb-request-done` from the element that committed,
+carrying the same `detail` as a bubbling `CustomEvent`, for any other
+listener. Import its name as `LB_DONE_EVENT_NAME`.
+
 `items` is every response item that landed because of the request, in
 order. `refusal` is set beside `error` when the handler refused the
 request, holding its `message` and `columns`. An answer that moved the URL contributes its `lb-url` item, which
@@ -596,11 +620,12 @@ the round trip failed, and then nothing landed. A new row's key is in the
 answer only when the handler returned it in a patch: a refresh sends all
 rows, and nothing marks which one is new.
 
-By the time the event is dispatched, `lb-request-pending` is gone and the
-page is as the answer left it. A request that was never sent, because the
-hub or an ancestor stopped it, gets no `lb-request-done`. An element the
-answer removed, such as the row a delete took away, dispatches the event
-outside the document, and no ancestor it had there hears it.
+By the time either is called, `lb-request-pending` is gone and the page is
+as the answer left it. A request that was never sent, because the hub or an
+ancestor stopped it, gets neither. An element the answer removed, such as
+the row a delete took away, is outside the document by then: no ancestor it
+had there hears the event, and no custom element the hub has removed hears
+`lbRequestDone`.
 
 ### Holding rows
 
@@ -611,26 +636,22 @@ plain element carrying `lb-query` with a row template inside it needs no
 code, so a custom element holds rows only to do something with them once
 they land.
 
-A custom element carrying `lb-query` and a row template may implement one
-optional method, which the hub calls:
+A custom element carrying `lb-query` and a row template implements
+`lbRowsLanded`, which the hub calls once the rows have landed, with every
+row placed and stamped:
 
 ```ts
-import type { RowsHost } from "@loadbare/app/types";
+import type { HubLifecycle } from "@loadbare/app/types";
 import { ATTR_ROW_REQUESTED, REQUESTED_CREATED } from "@loadbare/app/constants";
 
-class ScrollingList extends HTMLElement implements RowsHost {
+class ScrollingList extends HTMLElement implements HubLifecycle {
   lbRowsLanded() {
-    // Once, after the rows have landed, every row placed and stamped.
     this.querySelector(`[${ATTR_ROW_REQUESTED}="${REQUESTED_CREATED}"]`)
       ?.scrollIntoView({ block: "nearest" });
   }
 }
 ```
 
-| Method         | The hub calls it                                      |
-|----------------|-------------------------------------------------------|
-| `lbRowsLanded` | After the rows land, with every row placed and stamped |
-
 Everything else is the hub's:
 
 | Concern     | The hub                                                  |
@@ -649,11 +670,9 @@ gives each option and `<optgroup>` what landing does not, a value and a
 label, and the other scrolls to the row the page's request created or
 moved.
 
-A custom element the builder shipped absent under `lb-show` has not
-upgraded while its column is off, and the hub places the rows that land on
-it then as it places any. When the column first turns on and the element
-upgrades, the hub lands the query's last answer on it again, as all rows,
-so `lbRowsLanded` runs.
+A custom element under an `lb-show` that is off still holds its rows. The
+hub places the rows that land on it then as it places any, and calls its
+`lbRowsLanded`, so it returns current.
 
 A custom element that walks its own rows finds them with `LIVE_ROW` from
 `@loadbare/app/constants`, never by `lb-key-value`: an element a `row` lands

package/skills/loadbare-app/references/data-binding.md

@@ -284,10 +284,9 @@ scaffolding around rows, such as a group's heading or a ghost row. So
 a query nested in another query's rows need not land again, or land after
 the outer query, for a new outer row to show its choices.
 
-A custom element the builder shipped absent has not upgraded while its
-`lb-show` column is off. When the column first turns on and the element
-upgrades, the hub lands the kept answer on it again, so its `lbRowsLanded`
-runs. See [Holding rows](./custom-elements.md#holding-rows).
+A custom element under an `lb-show` that is off is filled like any other,
+and its `lbRowsLanded` runs as its rows land. See
+[Holding rows](./custom-elements.md#holding-rows).
 
 Nothing is answered from what the hub kept: a request always goes to the
 server, and a query re-runs only when a response names it. A patch that
@@ -877,9 +876,10 @@ An ancestor may stop the event, and the request is not sent. A custom
 element may dispatch the event itself; see
 [Sending a request](./custom-elements.md#sending-a-request).
 
-Once the answer has landed, or the round trip has failed, the hub dispatches
-a bubbling `lb-request-done` event from the same element, carrying the
-request and what landed because of it, or the error; see
+Once the answer has landed, or the round trip has failed, the hub calls
+`lbRequestDone` on the custom elements from the committing element outward,
+then dispatches a bubbling `lb-request-done` event from the same element.
+Both carry the request and what landed because of it, or the error; see
 [Hearing how it turned out](./custom-elements.md#hearing-how-it-turned-out).
 
 ## The URL

package/skills/loadbare-app/references/widgets.md

@@ -182,8 +182,8 @@ the hub until the user says yes:
 | `exp-request` | The confirm button's `lb-request`                |
 | `exp-confirm` | The confirm button's text, `Confirm` when absent |
 
-The widget closes the dialog once `lb-request-done` says the request
-succeeded, and leaves it open on a refusal.
+The widget closes the dialog once the request succeeds, and leaves it open
+on a refusal.
 
 ## `lb-form`