@loadbare/app 0.14.0 → 0.16.0

package/skills/loadbare-app/SKILL.md

@@ -238,7 +238,7 @@ and are not gathered.
 row.**  A form cannot sit inside another form or in a table row, so a dialog
 that creates an account while a posting's picker is choosing one goes at the
 end of the page, and each row opens it with `commandfor`.  The dialog learns
-the new key from `lb-request-done`.
+the new key in `lbRequestDone`.
 
 **A set the user edits has one form, pointed at a row.**  Never put a form
 in every row.  Write one form naming the set's query, outside every row,
@@ -387,25 +387,29 @@ element (`static formAssociated = true`) with a `value` property that fires
 on `change`.  Any other custom element keeps its content and receives the
 column as its `lb-column-value` attribute.
 
-**A custom element connects many times.**  It is moved, never rebuilt: the
-hub moves a live row the order puts elsewhere, and parks an `lb-show`
-element in a template while it is off, so `connectedCallback` runs on every
-move.  Listen on the element itself in the constructor, look a
-child up when it is needed, and in a control take up `lb-column-value` once,
-on first connect, since a value can land before the element upgrades.
+**A custom element hears the hub's lifecycle, never the browser's.**  The
+hub calls `lbAttached()` once when it places the element, already filled,
+and `lbDetached()` once when it removes it.  Moving a row and turning
+`lb-show` off and on call neither, and the instance is kept.  Never write
+`connectedCallback`, `disconnectedCallback`, `adoptedCallback` or
+`connectedMoveCallback`; the build refuses them.  Listen on the element
+itself in the constructor, look a child up when it is needed, and put
+once-per-instance setup in `lbAttached` with its undoing in `lbDetached`.
 
 **The hub and a custom element talk in four ways, one per kind of
 message.**  State the hub gives an element is an attribute stamp, or `value`
-on a control.  Work the hub needs done while landing is an optional `lb`
-method: `lbRowsLanded`.  A moment is a bubbling event: an
-element sends `lb-request`, and the hub answers on the same element with
-`lb-request-done`, carrying the request and the response items that landed,
-or the error.  Listen for `lb-request-done` on whichever ancestor needs the
-outcome, such as a dialog choosing the row its form just created.
+on a control.  What the hub did to an element is an optional `lb` method:
+`lbAttached`, `lbRowsLanded`, `lbRequestDone`, `lbDetached`, declared by
+`HubLifecycle`.  A moment is a bubbling event: an element sends
+`lb-request`, and the hub answers by calling `lbRequestDone(detail,
+origin)` on the custom elements from the committing element outward, then
+dispatching `lb-request-done` from it, each carrying the request and the
+response items that landed, or the error.  A dialog choosing the row its
+form just created implements `lbRequestDone`.
 
 **A widget that holds rows may sit under `lb-show`.**  Rows that land while
-it is away are placed by the hub, and its `lbRowsLanded` runs once it first
-appears, so hide a table with `lb-show`, not with a stylesheet rule.
+it is away are placed by the hub and its `lbRowsLanded` runs, so hide a
+table with `lb-show`, not with a stylesheet rule.
 
 **Name a custom element script `<tag>.browser.ts`.**  A plain `<tag>.ts`
 stays on the server and the tag goes unregistered.
@@ -434,7 +438,7 @@ parser loses the tag before the build can report it.
 Reach for one only when plain HTML cannot do the job.  A set of rows, a form
 and a condition need none.  A custom element exists to be a control of its
 own, or to act on rows once they land through the hook the hub calls,
-`lbRowsLanded` (the `RowsHost` interface).
+`lbRowsLanded` (the `HubLifecycle` interface).
 
 Before writing one, check `@loadbare/widgets`: `lb-input`, `lb-select`,
 `lb-options`, `lb-picker`, `lb-table`, `lb-unknown-page`, `lb-confirm`,

package/skills/loadbare-app/references/TECHREF-1.0.md

@@ -715,10 +715,9 @@ standing where it stood, and moved back out when the column turns on.  It is
 not rendered, focused, clicked, announced or gathered.  It is moved and
 never rebuilt, so a custom element keeps its instance and a control keeps
 what was typed into it.  Landing reaches into that template, so the element
-and everything inside it return current.  A custom element sees
-`disconnectedCallback` then `adoptedCallback` going in, and
-`adoptedCallback` then `connectedCallback` coming out, and still receives
-`lb-column-value` while it is away.
+and everything inside it return current.  A custom element hears nothing
+going in or coming out, and still receives `lb-column-value` while it is
+away.
 
 The builder ships every `lb-show` element already inside its template, so
 nothing conditional shows until its row lands.  An absent element's template
@@ -1098,8 +1097,10 @@ makes a confirmation wrapper possible without the wrapped element knowing
 about it.
 
 Once what the request brought back has landed, or its round trip has failed,
-the hub dispatches the bubbling `lb-request-done` event from the same
-element.  Its `detail`, `HubRequestDone` in `@loadbare/app/types`, holds
+the hub calls `lbRequestDone(detail, origin)` on the committing element and
+every custom element around it, innermost first (see
+[Lifecycle](#lifecycle)), then dispatches the bubbling `lb-request-done`
+event from the same element.  Its `detail`, `HubRequestDone` in `@loadbare/app/types`, holds
 the request as the hub sent it and `items`, every response item that landed
 because of it, in order.  An answer that moved the URL contributes its
 `lb-url` item and the page load.  `error` is set instead when the round trip
@@ -1884,14 +1885,12 @@ 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, because 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, since it acts on one element at one point in landing and nothing
-else can do it.  A moment is an event, because the element that cares is
+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 with no
 knowledge of either.
 
@@ -1910,45 +1909,47 @@ class NoteField extends HTMLElement {
 }
 ```
 
-A control that is not yet upgraded when its column lands receives
-`lb-column-value` alone, since the hub sets `value` only on a control.  That
-happens to an element the builder shipped absent, and to one whose
-definition loads after the hub lands.  A control takes the stamp up the
-first time it connects, and never again.
-
 A custom element that is not a control receives `lb-column-value` and
 renders it; its content is never replaced.
 
 ### Lifecycle
 
-| The hub                                  | A custom element sees                        |
-| ---------------------------------------- | -------------------------------------------- |
-| Shows a page                             | `constructor`, `connectedCallback`           |
-| Creates a live row, before placing it    | `constructor`                                |
-| Places a live row the first time         | `connectedCallback`                          |
-| Moves a live row the order put elsewhere | `connectedMoveCallback` where the browser moves in place, otherwise `disconnectedCallback`, `connectedCallback` |
-| Leaves a copy of a moved row behind      | The copy's `constructor`, `connectedCallback`, and later `disconnectedCallback` |
-| Removes a live row                       | `disconnectedCallback`, once its animations end |
-| Turns `lb-show` off                      | `disconnectedCallback`, `adoptedCallback`    |
-| Turns `lb-show` on                       | `adoptedCallback`, `connectedCallback`       |
-| Turns on an element shipped absent       | `constructor`, `connectedCallback`           |
+A custom element hears the hub's lifecycle, never the browser's.  The hub
+calls four optional methods, which the `HubLifecycle` interface in
+`@loadbare/app/types` declares:
+
+| The hub                                          | A custom element hears          |
+| ------------------------------------------------ | ------------------------------- |
+| Places it: chrome at startup, a page, a new live row, a new group | `lbAttached()`, once, after every column has landed on it |
+| Lands rows on it                                 | `lbRowsLanded()`                |
+| Finishes a request committed by it or inside it  | `lbRequestDone(detail, origin)` |
+| Removes it: a row or group done leaving, the page replaced | `lbDetached()`, once  |
+| Moves a live row the order put elsewhere         | Nothing                         |
+| Turns `lb-show` off or on                        | Nothing                         |
+| Leaves a copy of a moved row behind              | Nothing, on the copy            |
+
+The chrome and a page are placed as the page's first answer lands, or once
+that round trip fails.  An element under an `lb-show` that is off is placed
+inside its template, so `lbAttached` runs whether it shows or not.  `lbAttached` reaches an outer
+custom element before the ones inside it, and `lbDetached` the inner ones
+first.  `lbRequestDone` reaches the committing element and every custom
+element around it, innermost first, before the `lb-request-done` event.
+An element a script creates hears none of them.
 
 A listener on the element itself goes in the constructor, which reads no
-attribute and no child.  A child is looked up when it is needed.
-`connectedCallback` runs on every move and is written to run again; work
-done once per instance goes behind a flag.
+attribute and no child.  A child is looked up when it is needed.  Work done
+once per instance goes in `lbAttached`, and its undoing in `lbDetached`.
 
-### Row hooks
+The build refuses a script that declares `connectedCallback`,
+`disconnectedCallback`, `adoptedCallback` or `connectedMoveCallback`.
 
-| Method           | Implemented By | The hub calls it                                       |
-| ---------------- | -------------- | ------------------------------------------------------ |
-| `lbRowsLanded()` | Developer      | After the rows land, with every row placed and stamped |
+### Row hooks
 
-The hub calls it on a custom element with `lb-query` and a row template.
-It is optional.  The `RowsHost` interface in `@loadbare/app/types` declares
-it.  The hub places every row and builds every group itself, so a custom
-element reacts to rows and never places them.  Scrolling to the row the
-page's request created is the case:
+The hub calls `lbRowsLanded()` on a custom element with `lb-query` and a row
+template, after the rows land, with every row placed and stamped.  The hub
+places every row and builds every group itself, so a custom element reacts
+to rows and never places them.  Scrolling to the row the page's request
+created is the case:
 
 ```ts
 lbRowsLanded() {
@@ -1957,10 +1958,8 @@ lbRowsLanded() {
 }
 ```
 
-A custom element the builder shipped absent under `lb-show` has not
-upgraded while its column is off.  When the column first turns on and it
-upgrades, the hub lands the query's last answer on it again, as all rows,
-so the hook runs.
+A custom element under an `lb-show` that is off holds its rows all the
+same, and the hook runs as they land.
 
 `applyRow(root, row)`, exported by `@loadbare/app`, fills `root` from one
 row, the same operation that fills a live row.
@@ -2136,9 +2135,12 @@ Loadbare/app owns every DOM event in this table, both the name and what its
 
 ### Reserved methods
 
-| Method         | On                                                 | Defined in              |
-| -------------- | -------------------------------------------------- | ----------------------- |
-| `lbRowsLanded` | A custom element with `lb-query` and a row template | [Row hooks](#row-hooks) |
+| Method          | On                                                  | Defined in              |
+| --------------- | --------------------------------------------------- | ----------------------- |
+| `lbAttached`    | Any custom element the hub places                   | [Lifecycle](#lifecycle) |
+| `lbRowsLanded`  | A custom element with `lb-query` and a row template | [Row hooks](#row-hooks) |
+| `lbRequestDone` | A custom element that committed, or holds one that did | [Lifecycle](#lifecycle) |
+| `lbDetached`    | Any custom element the hub removes                  | [Lifecycle](#lifecycle) |
 
 ### Constants
 

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
@@ -538,7 +557,9 @@ customElements.define("visit-count", VisitCount);
 List `ATTR_COLUMN_VALUE` in `observedAttributes`. The browser calls
 `attributeChangedCallback` for an attribute already present when an element
 upgrades, as well as for one that changes afterward, so the first render and
-every later one go through the one callback.
+every later one go through the one callback.  A landing that brings the value
+the element already carries leaves the attribute alone, and the callback does
+not run.
 
 A custom element carrying `lb-show`, or inside an element that does, still
 receives its column while it is away, so it returns current; see
@@ -571,23 +592,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 +622,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,32 +638,28 @@ 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                                                  |
 |-------------|----------------------------------------------------------|
 | Cloning     | Clones the row template once per new key                 |
-| Matching    | Fills the live row already showing that key              |
+| Matching    | Fills the live row already showing that key, when its values changed |
 | Placing     | Places every live row by the query's order               |
 | Grouping    | Builds a group where the order breaks, and removes it with its last row |
 | Removing    | Marks the live rows the response says are gone as leaving, and removes them |
@@ -649,11 +672,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

@@ -172,6 +172,11 @@ membership: a live row whose key did not arrive leaves. A patch changes only
 the rows it names, and every other live row keeps its content. The hub
 places every live row by the query's order; see [Order](#order).
 
+A live row whose values arrive as it already shows them is not filled
+again. A control in it that the user has typed into and not committed keeps
+what was typed, through a refresh and through a change of order. A row
+whose values changed is filled whole, and its controls show what arrived.
+
 A key is unique within a query. Two rows with one key in the same answer,
 or two live rows showing one key, are reported on the console.
 
@@ -284,10 +289,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 +881,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`