@loadbare/app 0.11.0 → 0.13.0

package/docs/comparison.md

@@ -128,7 +128,7 @@ shape of the data an application works with.
 ### Loadbare/app
 
 The hub holds no application data.  There is no store, no signal, no
-observable, and no client cache of query results.
+observable, and no client cache that answers a request.
 
 - A value that has landed exists in the DOM: as `textContent` or `value`, and
   as the `lb-column-value` stamp.
@@ -138,6 +138,10 @@ observable, and no client cache of query results.
   the path, the page label and the query parms.
 - An element hidden by `lb-show` exists inside a `<template>` standing where
   it stood.
+- The hub keeps each query's last answer until the page changes, only to
+  fill an element that names the query and arrives after it, such as a
+  picker in a new live row.  Nothing is read from it in place of asking the
+  server.
 - The hub keeps two pieces of state of its own: the name of the current page,
   and, until an insert completes, the form it gathered from.
 
@@ -316,9 +320,9 @@ without `.browser` is not bundled, and the build error names it.
   `CustomEvent`.  The hub completes it with `query`, `key` and `values` from
   where the element sits.  An ancestor may stop the event.
 - A custom element carrying `lb-query` and a row template may implement
-  `lbPlaceRow(el, row, template)` to decide where a row goes, and
-  `lbRowsLanded()` to build scaffolding such as group headings.  The hub does
-  the cloning, matching, removal and counting.
+  `lbRowsLanded()` to act on the rows once they land, such as scrolling to
+  the one a request created.  The hub does the cloning, matching, ordering,
+  grouping, removal and counting.
 - Method names beginning with `lb` on a custom element are reserved.
 
 Widget libraries are npm packages listed in `imports.ts`.  The builder scans
@@ -392,7 +396,7 @@ query, the kind and key the server declared, and one of these:
 A column holds one value.  A set of values is a query of its own.  A row
 never contains rows.  Master-detail is a row and rows answered under two
 names.  Many masters with their details is one `rows` query of joined rows,
-grouped for display by a custom element's `lbPlaceRow`.
+shown in groups by a group template.
 
 The application designs no endpoints, routes or serialization format.  The
 names in the markup are the keys in the page's `.queries.ts` and
@@ -781,11 +785,12 @@ TECHREF-1.0 lists every name Loadbare/app owns in one cross-reference.
 
 | Owned                               | Count | Names                                                         |
 |-------------------------------------|-------|---------------------------------------------------------------|
-| `lb-*` attributes a developer writes | 7    | `lb-query`, `lb-column`, `lb-show`, `lb-request`, `lb-url-link`, `lb-url-push`, `lb-url-unknown` |
-| `lb-*` stamps                       | 8     | `lb-column-value`, `lb-key-value`, `lb-row-live`, `lb-query-row-count`, `lb-request-pending`, `lb-request-error`, `lb-page`, `lb-page-title` |
+| `lb-*` attributes a developer writes | 13   | `lb-query`, `lb-column`, `lb-show`, `lb-group`, `lb-count`, `lb-sum`, `lb-avg`, `lb-min`, `lb-max`, `lb-request`, `lb-url-link`, `lb-url-push`, `lb-url-unknown` |
+| `lb-*` stamps                       | 17    | `lb-column-value`, `lb-key-value`, `lb-row-live`, `lb-query-row-count`, `lb-group-live`, `lb-group-column`, `lb-group-value`, `lb-row-created`, `lb-row-changed`, `lb-row-moved`, `lb-row-requested`, `lb-row-leaving`, `lb-group-leaving`, `lb-request-pending`, `lb-request-error`, `lb-page`, `lb-page-title` |
 | `lb-*` build-time attributes        | 2     | `lb-exp-slot`, `lb-exp-template`                              |
 | Requests Loadbare provides          | 3     | `lb-row-insert`, `lb-row-update`, `lb-row-delete`             |
-| `lb*` methods on custom elements    | 2     | `lbPlaceRow`, `lbRowsLanded`                                  |
+| `lb*` methods on custom elements    | 1     | `lbRowsLanded`                                                |
+| Query parms Loadbare reads          | 1     | `lb-order-<query>`                                            |
 | Attribute namespace for expansion   | 1     | `exp-*`                                                       |
 | Reserved tags                       | 1     | `<lb-hub>`                                                    |
 | Reserved events                     | 1     | `lb-request`                                                  |
@@ -922,7 +927,7 @@ Roadmap.
 | Offline or local-first use    | None.                                                                  |
 | Server-side rendering for crawlers | None.  Every path answers the same document with status 200.      |
 | Subpath hosting               | Not possible.  The hub uses absolute paths.                            |
-| Chrome-level queries          | A widget in the chrome bound to a query requires every page to declare it.  Open blocker. |
+| Chrome-level queries          | A widget in the chrome bound to a query requires every page to declare it.  On the roadmap. |
 | A widget receiving a whole row | Not available.  Open blocker.                                         |
 | A nested `rows` query per outer row | A nested query receives the same rows in every outer row.  A new outer row's nested query stays empty until its name lands again.  Open blocker. |
 | Configurable request deadline | Fixed at ten seconds.                                                  |
@@ -1177,7 +1182,8 @@ Each equivalent is approximate.
 | Expansion                     | Server-side include; partial; build-time component render (Astro)                |
 | `exp-` parameter              | A prop fixed at build time                                                       |
 | `lb-exp-slot`, `lb-exp-template` | Default slot and named slots; `ng-content` with `select`                         |
-| `lbPlaceRow`, `lbRowsLanded`  | Custom list rendering; a render prop                                             |
+| `lbRowsLanded`                | An effect after a list renders                                                   |
+| `order`, `lb-group`           | `ORDER BY` with report-writer control breaks (`BREAK ON`, group bands)          |
 | `ctx` / `HubContext`          | `event.locals` (SvelteKit); loader `context` (React Router 7); request-scoped dependency injection |
 | `imports.ts`                  | Installing and registering a component library                                   |
 | `pages.ts`                    | Generated route manifest                                                         |

package/docs/possible-ideas.md

@@ -0,0 +1,188 @@
+# Possible Ideas
+
+> **LLM-authored, not yet revised by a person.**  Drafted by Claude on
+> 2026-10-02 against `@loadbare/app` 0.12.0, from a session in ef.  Nothing
+> here is decided or planned.
+
+## Code on elements the parser constrains
+
+Loadbare's data vocabulary is attributes, and an attribute goes on any
+element: `<tr lb-query>`, `<option lb-column>`, `<tbody lb-show>`.  Behavior
+is different.  The platform attaches code to markup through a custom element
+tag, and a tag must survive the parser.  In a table, a `<select>`, or a `<p>`
+it does not: an unexpected tag is dropped, moved out of the table, or closes
+the paragraph.
+
+So code that concerns one row lives on a wrapper around the whole table.
+`lb-table` owns the `<table>`, and the page writes its contents as named
+templates (`head`, `foot`, `ghost`) that the builder joins back into a
+table.  Each new need is another named destination, and the page's source
+reads as `lb-table`'s shape rather than a table's.  The shipped HTML is
+honest; the source is a dialect.
+
+Two ways to put code on the element itself follow.
+
+### Customized built-ins
+
+```html
+<tr is="lb-ghost-row">…</tr>
+```
+
+The platform's own answer: a class extending `HTMLTableRowElement`,
+registered with `customElements.define(name, cls, { extends: "tr" })`.  The
+parser sees a `<tr>`, so the element sits wherever a `<tr>` may, keeps every
+native behavior of one, and gets the custom element lifecycle.
+
+- Chrome and Firefox ship it.  WebKit has declined to, on principle
+  (subclassing a built-in breaks when its internals change), so Safari needs
+  a polyfill for as long as the feature exists.
+- Every browser on iOS and iPadOS is WebKit, Chrome included.  The polyfill
+  is therefore not a Safari fallback but the code path on every iPhone and
+  iPad, permanently.  The usual one, `@ungap/custom-elements`, watches the
+  document with a `MutationObserver`, so on those devices the lifecycle runs
+  because something noticed.
+- `is` must be present when the element is created; setting it later does
+  nothing.  Cloning a template preserves it, so a row template carrying
+  `is` yields upgraded rows.
+- A customized built-in cannot be form-associated (`ElementInternals` is for
+  autonomous custom elements), which matters little: the built-in elements
+  that controls are already take part in forms.
+
+### Behavior by attribute
+
+```html
+<tr lb-behavior="ghost-row">…</tr>
+```
+
+Code bound to any element by an attribute, as Stimulus does with
+`data-controller`.  It fits the parser everywhere and needs no polyfill.
+
+- What usually drives it is a `MutationObserver`, which is incidental: the
+  code runs because something noticed.  The hub, though, already knows every
+  time it puts an element in the page: it shows a page, clones a row, builds
+  a group, and moves an element in and out of an `lb-show` template.  A
+  behavior attached and detached at those moments would be explicit.
+- Elements the hub does not add (a widget's own scaffolding, anything a
+  script creates) would get no behavior, which may be the right rule rather
+  than a limitation.
+- No form association of its own, and mostly none needed: a behavior on a
+  native control leaves it a native control, which joins its form, takes
+  focus and honors `autofocus` as it always did.  Only a control whose UI is
+  built from scratch needs `ElementInternals`, and stays an autonomous
+  custom element.
+- The platform has discussed a registry for custom attributes, which would
+  be this idea built in.  It has not shipped.  Without it the browser has no
+  part in a behavior: everything below is the hub's.
+
+#### A lifecycle in the hub's terms
+
+A custom element's lifecycle is the browser's, and it speaks of insertion:
+connected, disconnected, adopted.  The hub's work rarely lines up with it.  A
+moved row is disconnected and connected, the copy a move leaves behind is
+constructed, an `lb-show` toggle adopts twice, which is why a custom element
+must write `connectedCallback` to run again.
+
+A behavior's lifecycle would be calls the hub makes from its own code, at
+moments it already knows, named for what the hub did:
+
+| The hub                                                        | A behavior hears                                            |
+| -------------------------------------------------------------- | ----------------------------------------------------------- |
+| Shows a page, places a cloned row, builds a group, first shows an element shipped absent | `attached()`, once, after the element is placed and filled |
+| Lands new values on the element's row                          | `landed(row)`                                               |
+| Moves a row the order put elsewhere                            | `moved()`; the instance is kept                             |
+| Leaves a copy of a moved row behind                            | Nothing; the copy gets no behavior                          |
+| Turns `lb-show` off, then on                                   | `hidden()`, then `shown()`; the instance is kept            |
+| Removes a row, once its animations end                         | `detached()`, once                                          |
+| Finishes a request issued from inside the element              | `requestDone(detail)`                                       |
+
+- `attached` and `detached` pair exactly, so setup and teardown need no
+  guard against running twice.
+- The calls are the code-side twin of the stamps a stylesheet already sees
+  (`lb-row-created`, `lb-row-changed`, `lb-row-moved`, `lb-row-leaving`):
+  one vocabulary for CSS and code, in the hub's relational terms.
+- The hub keeps one instance per element and behavior name.  An element may
+  carry several, `lb-behavior="ghost-row autosave"`, which a tag cannot.
+- A behavior is a class in a file the builder finds by name, as it finds
+  `<tag>.browser.ts`, and a name with no file is a build error.
+
+What the hub would have to define and keep: whether `attached` comes before
+or after the rows inside a host land, and the order of calls among nested
+behaviors.  A custom element gets its ordering from the platform; here it is
+loadbare's to state.
+
+A rule for choosing: a custom element makes a new kind of element (its own
+markup, expansion, or a control built from scratch); a behavior adds code to
+an element HTML already has.
+
+### Where each would land
+
+Either one lets a page write a real `<table lb-query>` with code on the rows
+that need it, and leaves `lb-table` to supply only what is truly the
+table's.  Customized built-ins borrow the platform's lifecycle at the cost of
+a permanent polyfill; behavior by attribute keeps the parser and the browser
+matrix out of it, at the cost of a lifecycle the hub would define.
+
+## Expansion that replaces the tag
+
+Today a custom element's tag does two jobs: at build time it is expanded,
+and at run time it carries code.  Because the code needs the tag, the tag
+ships as a wrapper around what it expanded, and the wrapper is the source of
+most widget friction: focus searched for inside it, values forwarded through
+it, `autofocus` lost, and no place in a table.
+
+With behaviors carrying the code, expansion is free to stop shipping the
+tag.
+
+```html
+<!-- page -->
+<lb-field exp-label="Name" lb-column="name"></lb-field>
+
+<!-- what ships -->
+<!-- lb-field exp-label="Name" lb-column="name" -->
+<label lb-behavior="lb-field">Name <input lb-column="name" /></label>
+```
+
+- **The tag becomes a comment.**  The shipped DOM keeps a trail back to the
+  source at no run-time cost.  A comment is legal anywhere, tables included,
+  and is invisible to CSS, `:nth-child` and the hub's counting.
+- **The builder puts the behavior on the root.**  When
+  `<name>.behavior.ts` exists, the expanded root gets `lb-behavior="<name>"`;
+  the author never writes it.  `[lb-behavior~="lb-field"]` then serves CSS
+  and `querySelector` as the tag selector `lb-field` does now.
+- **Every widget inherits one base class.**  A `Behavior` holds `this.el`,
+  has empty methods for every call in the hub's lifecycle, and types
+  `landed(row)` and `requestDone(detail)`.  A widget overrides only what it
+  uses, as it extends `HTMLElement` or `WrappedControl` today.
+
+The file convention decides which path an element takes:
+
+| The element has                            | The builder                                        | At run time            |
+| ------------------------------------------ | -------------------------------------------------- | ---------------------- |
+| An element file, no script                 | Replaces the tag, leaves a comment                 | Plain HTML             |
+| An element file and `<name>.behavior.ts`   | Replaces the tag, puts `lb-behavior` on the root   | The hub's lifecycle    |
+| `<name>.browser.ts`                        | Keeps the tag, as today                            | The browser's lifecycle |
+
+The third row is for controls built from scratch, the only elements that
+still need `ElementInternals`.
+
+### A flag to keep the tag
+
+Considered and set aside.  It gives every widget two DOM shapes, so its CSS
+and code must work in both.  It cannot apply where replacing pays off most,
+since a kept tag still has no place in a table.  And what people would keep
+the tag for, a name to find and style the widget by and a trail to its
+source, the `lb-behavior` attribute and the comment already give.
+
+### To settle
+
+1. **One root.**  A behavior attaches to one element, so an element file with
+   a behavior has exactly one top-level element, and anything more is a
+   build error.
+2. **Where the tag's attributes go.**  The wrapper used to keep them; once
+   the tag is gone each needs a destination.  The natural default is the
+   root, and `lb-field` breaks it: its root is the `<label>`, but
+   `lb-column` belongs on the `<input>` inside while `lb-show` belongs on the
+   label.  Either the element file marks a target for data attributes, or
+   the page passes them as parameters (`exp-column`, written into the file as
+   `lb-column="{{column}}"`), which works today but reads less naturally
+   than `lb-column`.  This wants worked examples before a rule.

package/docs/reference/chrome.md

@@ -72,6 +72,10 @@ Put everything the user interacts with inside `<lb-hub>`. The hub normally
 sits directly inside `<body>`, with banner, nav, footer and `<main>` inside
 it, so Loadbare can act on all of them.
 
+Write exactly one `<lb-hub>` and exactly one `<main>`, with the `<main>`
+inside the hub and empty but for whitespace.  The builder rejects a chrome
+that does otherwise.
+
 The chrome's `<title>` is the document title until the first page shows.
 From then on the hub sets the document title to the page's label; see
 [The URL](#the-url).
@@ -108,6 +112,21 @@ tab and the browser history show the page.
 `lb-url` is the one query a page may use that the server does not declare. A
 page names it the same way, anywhere inside the hub.
 
+### Where focus starts
+
+On entering a page, once its queries have landed, the hub focuses the first
+element in `<main>` the user can operate, so a keyboard user starts in the
+page rather than on the document. The chrome comes first in the document,
+and is passed over. So is anything disabled, in a closed `<dialog>`,
+`inert`, `hidden`, in an absent `lb-show` branch, or that does not take
+the focus when asked. A widget's native control counts, so write no
+`autofocus` to restate this.
+
+A page is entered on a cold load, a new `lb-path` from a link or from a
+handler's `url()`, and Back or Forward to another page. A change of query
+parm enters no page: the user who chose a record in a picker stays in the
+picker. Focus the user has already put in `<main>` is left there.
+
 ### Links
 
 Write `lb-url-link` on an `<a>` to move between pages:
@@ -150,7 +169,9 @@ pushes one instead when the element carrying `lb-request` also carries
 
 The hub answers the request itself, with no round trip, then reloads the
 page's queries at the new URL. The page stays in place, and rows that come
-back keep their place.
+back keep their place. A request that changes only `lb-order-<query>`, the
+user's [order](./data-binding.md#order) for a query the hub sorts itself,
+re-sorts the rows already on the page and loads nothing.
 
 A control whose column the URL does not carry lands empty, so every control
 inside `lb-query="lb-url"` shows what the address bar says, after a reload

package/docs/reference/custom-elements.md

@@ -268,6 +268,8 @@ one as a string literal:
 | `REQUEST_ROW_INSERT`, `REQUEST_ROW_UPDATE`, `REQUEST_ROW_DELETE` | The requests Loadbare provides |
 | `LB_ROW_REQUESTS`      | All three, in one array |
 | `LB_EVENT_NAME`        | `lb-request`, the event every request travels as |
+| `LB_DONE_EVENT_NAME`   | `lb-request-done`, the event that says how it turned out |
+| `SHOW_NOT`             | `!`, written before a column in `lb-show` |
 | `URL_QUERY`            | `lb-url`             |
 | `URL_COLUMN_PATH`, `URL_COLUMN_PAGE_LABEL`, `URL_COLUMN_PAGE_UNKNOWN` | `lb-path`, `lb-page-label`, `lb-page-unknown` |
 | `LB_RESERVED_PREFIX`   | `lb-`                |
@@ -276,7 +278,28 @@ 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 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.
+
+### What the hub and an element say to each other
+
+Each direction has one mechanism for each kind of message:
+
+| Direction      | What                                       | How                         | Today |
+|----------------|--------------------------------------------|-----------------------------|-------|
+| 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 | 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.
 
 ### When its code runs
 
@@ -309,7 +332,7 @@ So each kind of work has one place:
    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,
-   `lbPlaceRow` or `lbRowsLanded`, and never held from setup.
+   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
@@ -450,36 +473,67 @@ missing a field its name needs, and stamps the dispatching element with
 
 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.
+
+```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]));
+});
+```
+
+`items` is every response item that landed because of the request, in
+order. An answer that moved the URL contributes its `lb-url` item, which
+carries a key only the server knew, and the page load. `error` is set when
+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.
+
 ### Holding rows
 
-The hub lands every row template itself. A plain element carrying `lb-query`
-with a row template inside it needs no code, so a custom element holds rows
-only when they need placement or scaffolding that only it can decide.
+The hub lands every row template itself, places every row by the query's
+order, and builds every group the markup's group templates describe; see
+[Order](./data-binding.md#order) and [Groups](./data-binding.md#groups). A
+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 two
-optional methods, which the hub calls:
+A custom element carrying `lb-query` and a row template may implement one
+optional method, which the hub calls:
 
 ```ts
-import type { RowsHost, Row } from "@loadbare/app/types";
-
-class SortedList extends HTMLElement implements RowsHost {
-  lbPlaceRow(el: Element, row: Row, template: HTMLTemplateElement) {
-    // Where this live row goes. Called with the live row detached, on its
-    // first appearance and again whenever all rows decide the order.
-  }
+import type { RowsHost } from "@loadbare/app/types";
+import { ATTR_ROW_REQUESTED, REQUESTED_CREATED } from "@loadbare/app/constants";
 
+class ScrollingList extends HTMLElement implements RowsHost {
   lbRowsLanded() {
-    // Once, after the rows have landed. For scaffolding derived from the
-    // rows: a section heading, an <optgroup>, anything that goes when its
-    // last row does.
+    // 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    |
-|----------------|---------------------|
-| `lbPlaceRow`   | To place a live row |
-| `lbRowsLanded` | After the rows land |
+| Method         | The hub calls it                                      |
+|----------------|-------------------------------------------------------|
+| `lbRowsLanded` | After the rows land, with every row placed and stamped |
 
 Everything else is the hub's:
 
@@ -487,16 +541,23 @@ Everything else is the hub's:
 |-------------|----------------------------------------------------------|
 | Cloning     | Clones the row template once per new key                 |
 | Matching    | Fills the live row already showing that key              |
-| Removing    | Removes the live rows the response says are gone         |
-| Stamping    | Stamps each live row with `lb-row-live` and `lb-key-value` |
+| 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 |
+| Stamping    | Stamps each live row with `lb-row-live`, `lb-key-value`, and what happened to it |
 | Counting    | Stamps `lb-query-row-count` with the number of live rows |
 
-`lbPlaceRow` receives the live row already filled and not yet in the
-document, so a custom element that reads a column to decide where the row
-goes can. Without it, the hub places a live row immediately before the row
-template, in arrival order. `lb-options.browser.ts` and
-`lb-table.browser.ts` in [`@loadbare/widgets`](./widgets.md) are two
-different placements over the same landing.
+`lb-options.browser.ts` and `lb-table.browser.ts` in
+[`@loadbare/widgets`](./widgets.md) are two uses of `lbRowsLanded`: one
+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 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/docs/reference/data-binding.md

@@ -153,9 +153,9 @@ places it immediately before the template:
 ```
 
 The hub matches each row to a live row by its key. All rows decide
-membership and order: a live row whose key did not arrive is removed. A
-patch changes only the rows it names, and every other live row keeps its
-content and its place.
+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 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.
@@ -163,10 +163,121 @@ or two live rows showing one key, are reported on the console.
 A live row's root counts as a column when it carries `lb-column`, which is
 how an `<option>`, whose content is text, shows the column it is.
 
-A custom element that carries `lb-query` and a row template may decide where
-a row goes and add scaffolding around the rows; see
-[Holding rows](./custom-elements.md#holding-rows) and
-[The Basic Widget Library](./widgets.md).
+A custom element that carries `lb-query` and a row template reacts to the
+rows once they land; see [Holding rows](./custom-elements.md#holding-rows)
+and [The Basic Widget Library](./widgets.md).
+
+### Order
+
+A `rows` query declares its order with the query, as columns separated by
+commas, each descending when written after `-`:
+
+```ts
+roster: rows("id", (ctx) => ctx.db.members(), { order: "team,name" }),
+```
+
+The query parm `lb-order-<query>` replaces it for that query, so a control
+inside `lb-query="lb-url"` writing that parm re-sorts the rows the hub
+already has, with no round trip. With no order, rows show in the order they
+arrived, and a patch's new rows go last.
+
+Values compare by their JSON type: numbers numerically, strings as the
+user's language orders them, `false` before `true`, and `null` last. A
+number sent as a string sorts as a string. Rows that compare equal keep the
+order they arrived in. A row moves only when the order puts it somewhere
+else.
+
+A query that pages or limits its rows reads the parm itself and declares
+`serverSortedByUrl: true`, so a change of order loads the page again.
+
+### Groups
+
+A group is a run of rows sharing the order's leading term. Write a
+`<template lb-group>` where the row template goes, holding the group's
+heading and one nested `<template>`: the next group template, or the row
+template. The nth group template breaks on the order's nth term.
+
+```html
+<ul lb-query="roster">
+  <template lb-group>
+    <li>
+      <h3 lb-column="team"></h3>
+      <ul>
+        <template><li lb-column="name"></li></template>
+      </ul>
+    </li>
+  </template>
+</ul>
+```
+
+The group's contents land immediately before its nested template. When that
+template is inside the heading's element, the contents land inside it; when
+it is beside the heading, they land after it. `<tbody>` and `<optgroup>` do
+not nest, so a table's deeper levels are heading rows. Content after the
+nested template is the group's footer.
+
+A heading is filled from its group's first row, so it may show a column
+other than the one the group breaks on. The hub stamps each top-level
+element of a group with `lb-group-live`, `lb-group-column` and
+`lb-group-value`. A row creates its group, and a group leaves with its last
+row.
+
+### Aggregates
+
+`lb-count`, `lb-sum="col"`, `lb-avg="col"`, `lb-min="col"` and
+`lb-max="col"` set an element from the rows of the nearest group around it,
+or of the whole list outside any group:
+
+```html
+<tr><td><span lb-count></span> people</td><td lb-sum="salary"></td></tr>
+```
+
+A sum and an average are exact, read from JSON numbers and from strings
+holding a plain decimal. `null` and empty values are left out. The result
+lands unformatted, and covers the rows the browser holds.
+
+### What happened to a row
+
+Every change to a list is one a stylesheet can see:
+
+| Attribute          | Means                                                  |
+| ------------------ | ------------------------------------------------------ |
+| `lb-row-created`   | Created when the hub last touched the row              |
+| `lb-row-changed`   | Its values changed when the hub last touched it        |
+| `lb-row-moved`     | The order put it somewhere else when last touched      |
+| `lb-row-requested` | `created`, `changed` or `moved` by this page's request |
+| `lb-row-leaving`   | A row on its way out                                   |
+| `lb-group-leaving` | A group on its way out                                 |
+
+A row that leaves loses `lb-row-live`, takes `inert`, and is removed once
+its animations finish, at once when there are none. A moved row moves, and
+a copy stays behind where it was, leaving. `lb-row-requested` is cleared at
+every landing; the others when the hub next touches the row.
+
+```css
+[lb-row-created] { animation: arrive 200ms; }
+[lb-row-leaving] { animation: depart 200ms forwards; }
+```
+
+### What arrives later
+
+The hub keeps each query's last answer until the page changes, with any
+patch since applied to it. An element that names a query and arrives after
+that query's answer is filled from what was kept, at the end of the landing
+that follows its arrival. Such an element is a picker in a new live row, or
+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).
+
+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
+arrives before all of a query's rows is not kept, since it is not the whole
+of anything.
 
 A `rows` query on an element with no row template lands nothing. That is the
 insert form above: it sits inside `lb-query="roster"` so its request is for
@@ -225,6 +336,14 @@ have the query answer with a boolean or a null. A row that does not carry
 the column leaves the element as it is, so a query answers with the column
 in every row.
 
+Write `!` before the column to reverse it. One column then decides between
+two elements, rather than a column and its opposite, which could disagree:
+
+```html
+<h2 lb-show="chosen" lb-column="title"></h2>
+<p lb-show="!chosen">Choose a batch.</p>
+```
+
 `lb-show` reads from the nearest ancestor row, as `lb-column` does. On an
 element that also carries `lb-query`, the column belongs to the row around
 it, so this picker takes its choices from `groups` and whether it is present
@@ -463,6 +582,11 @@ 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
+[Hearing how it turned out](./custom-elements.md#hearing-how-it-turned-out).
+
 ## The URL
 
 The hub serves one query of its own, `lb-url`: one row holding the path, the
@@ -495,3 +619,4 @@ expansion, and refuses to build:
 - `lb-url-unknown` on anything but a `<dialog>`, or outside `<lb-hub>`
 - `lb-show` on a `<template>`, or on a row template's root
 - `lb-show` with no `lb-query` around it
+- `lb-show="!"` or `lb-show="!!column"`, which reverse no column