@loadbare/app 0.11.0 → 0.13.0

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

@@ -22,6 +22,10 @@ a value is rendered by browser coercion when it lands on an HTML text
 element or a control, and by whatever the custom element does with
 `lb-column-value` when it lands on one that is not a control.
 
+Two places read a value's type today.  The [order](#order) compares values
+by their JSON type, and an [aggregate](#aggregates) reads a sum or an
+average from a JSON number or a string holding a plain decimal.
+
 We will then see if a useful solution emerges that Loadbare/app should
 handle.
 
@@ -32,28 +36,15 @@ handle.
   what counts as checked, which waits on [Data types](#data-types), and a
   radio group is several elements answering to one column.
 
-### Run-time stamps
-
-The hub stamps `lb-query-row-count`, `lb-request-pending` and
-`lb-request-error` for a stylesheet to read.  Their consumer is CSS rather
-than code.
-
-- **Decide whether an unarrived value needs a signal.** An element whose
-  column has not landed carries no `lb-column-value`.  Recommend confirming
-  that as the signal and adding nothing.
-
 ### Custom element hooks
 
 Loadbare/app owns every method name beginning with `lb` on a custom element.
 That decision is firm; what the set contains is not.
 
-- **Decide what the build does with an unknown `lb*` method.** An element
-  carrying a method beginning with `lb` that Loadbare/app does not define may
-  be an error, a warning, or ignored.
 - **Decide whether a custom element may receive a whole row.** A column
   lands one element at a time and offers no escape hatch.  An optional
-  `lbAcceptRow` would sit beside `lbPlaceRow` and `lbRowsLanded`, and this is
-  the most likely first request from a custom element author.
+  `lbAcceptRow` would sit beside `lbRowsLanded`, and this is the most likely
+  first request from a custom element author.
 
 ### Nested queries
 
@@ -64,10 +55,9 @@ fine, because every `<select>` receives the same rows.
 
 But the allowed values may depend on other values in the row.
 
-- **Decide how a new live row fills a nested query.** A row added to the
-  outer query starts with its nested query empty, and it fills only when the
-  nested query's name lands again.  See [Master-detail](#master-detail) for
-  what a nested query is for.
+- **Decide whether a nested query's rows may depend on its row.** A nested
+  query has one answer, which every live row receives.  See
+  [Master-detail](#master-detail) for what a nested query is for.
 
 ```html
 <tbody lb-query="accounts">
@@ -80,18 +70,11 @@ But the allowed values may depend on other values in the row.
 
 ### The server API
 
-- **Give the chrome a way to state its own queries.** A custom element in
-  the chrome naming a query forces every page to declare that query, since
-  the page load covers one page's set.  `lb-url` shows the pattern from the
-  framework side, and an application has no equivalent.  Recommend a
-  chrome-level query set on `createHub`.
-- **State that only `createHub` implements `Hub`.** Otherwise a third call
-  breaks anyone who wrote the interface by hand.
 - **Decide the options-argument shape once.** Global hooks, transaction
   wrapping, error handling and a CSRF token all want the same trailing
   parameter on `createHub` and `hubRoutes`.  Build none of them, but pick
   where they go.
-- **Land `staticRoutes`.** See NEXT.md.  It closes the last place where an
+- **Land `staticRoutes`.**  It closes the last place where an
   application hand-writes facts the builder owns.
 
 ### The builder
@@ -106,9 +89,6 @@ But the allowed values may depend on other values in the row.
   definition would let the builder ship only what survives expansion.
   Recommend deferring the mechanism and reserving the configuration key, so
   that it lands as an opt-in rather than as a silent drop.
-- **Land the remaining validations.** One `lb-hub` and one empty `<main>`.
-  Recommend landing these now, because refusing markup that used to build is
-  the kind of change 1.0 gives up.
 - **Decide whether the build validates HTML.** A page can be well formed and
   still break HTML's rules for what an element may hold, such as a `<div>`
   inside a `<p>`.  The parser rearranges it silently, the same way at build
@@ -124,9 +104,6 @@ But the allowed values may depend on other values in the row.
 None of this is surface.  It is listed here because trimming it is free
 today and breaking after 1.0.
 
-- **Drop `./build` from the exports map.** Nothing in the repository imports
-  it, and nothing outside the CLI should call `resolveElements` or
-  `clientEntrySource`.
 - **Audit what the hub does.** It appears to have routines that go beyond
   what the `lb-*` attribute namespace specifies.
 - **Keep the rest as constants.** The endpoint, `index` and the timeout are
@@ -425,7 +402,7 @@ query.
 | ----------- | -------- | -------------------------------------------------- |
 | `lb-query`  | a query  | Puts its rows in the element's content             |
 | `lb-column` | a column | Sets the element from that column                  |
-| `lb-show`   | a column | Removes it while the named column is null or false |
+| `lb-show`   | a column | Removes it while the named column is null or false; `!column` reverses it |
 
 | Stamp                | The hub stamps it with           |
 | -------------------- | -------------------------------- |
@@ -438,9 +415,10 @@ The markup names a query and the columns it shows.  The kind and the key are
 the server's, and the markup states neither.
 
 The row template is the first `<template>` among the descendants of an
-element with `lb-query`, outside any nested `lb-query`.  A live row is an
-element the hub cloned from a row template for one row, and carries
-`lb-row-live`.
+element with `lb-query`, outside any nested `lb-query`, or, when that
+template is a [group template](#groups), the innermost template inside it.
+A live row is an element the hub cloned from a row template for one row,
+and carries `lb-row-live`.
 
 | Kind   | Row template | The hub                             |
 | ------ | ------------ | ----------------------------------- |
@@ -521,14 +499,15 @@ with `[lb-row-live]`, and never with `[lb-key-value]`.
 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.
 
-All rows decide membership and order: every row is placed in the order
-given, and a live row whose key did not arrive is removed.  A patch touches
-only the rows it names and leaves every other live row's contents and
-position alone.
+All rows decide membership: a live row whose key did not arrive leaves —
+see [What happened to a row](#what-happened-to-a-row).  A patch touches only
+the rows it names, and leaves every other live row's contents alone.
 
-A new live row lands immediately before the row template, so rows
-accumulate in the order they arrive.  A custom element carrying `lb-query`
-and a row template may place them itself — see [Row hooks](#row-hooks).
+The hub places every live row by the query's [order](#order), immediately
+before the row template, or before its clone in the row's
+[group](#groups).  A row moves only when the order puts it somewhere else,
+so all rows landing again unchanged move nothing.  A live row already in the
+markup when the first answer lands is one of the query's rows.
 
 After every landing the hub stamps the element with `lb-query-row-count`,
 the number of live rows it holds.  The server answers with rows and says
@@ -543,6 +522,162 @@ sent.  It makes an empty query a stylesheet rule:
 
 A row missing its key column is reported to the console and not landed.
 
+#### Order
+
+A `rows` query's order is a rule over its columns.  The server declares it
+with the query, and the URL may carry the user's own:
+
+```ts
+accounts: rows("id", (ctx) => ctx.db.accounts(), {
+  order: "category_order,account_name",
+}),
+```
+
+An order is columns separated by commas.  A column written after `-` sorts
+descending.  The query parm `lb-order-<query>` replaces the declared order
+for that query: `/coa?lb-order-accounts=-account_name`.  With neither, rows
+show in the order the server sent them, and a patch's new rows go last.
+
+| Values               | Compare                                    |
+| -------------------- | ------------------------------------------ |
+| Two numbers          | Numerically                                |
+| Two strings          | As the user's language orders them         |
+| Two booleans         | `false` before `true`                      |
+| Two different types  | Booleans, then numbers, then strings       |
+| `null` or missing    | After everything ascending, first descending |
+
+A number sent as a string sorts as a string, so a column the order reads
+numerically arrives as a JSON number.  Rows that compare equal keep the
+order they arrived in, and a patch's new rows come after the rows already
+showing.
+
+The hub sorts the rows it has, so a control that writes the order parm
+re-sorts the page with no round trip:
+
+```html
+<div lb-query="lb-url">
+  <select lb-column="lb-order-accounts" lb-request="lb-row-update">
+    <option value="">By category</option>
+    <option value="account_name">By name</option>
+  </select>
+</div>
+```
+
+A query that pages or limits its rows decides membership by its order, so
+it reads the parm itself, from the parms `contextFor` receives, and declares
+`serverSortedByUrl: true` beside `order`.  A change of the user's order then
+loads the page again.  The hub still places the rows it receives by the same
+order, so a patch lands in its place.
+
+#### Groups
+
+A group is a run of rows sharing the order's leading term.  A group
+template is a `<template lb-group>` in the row template's place, holding the
+group's heading and exactly one nested `<template>`, which is where the
+group's contents go: the next group template, or the row template.  The nth
+group template breaks on the order's nth term, so groups nest to any depth.
+
+```html
+<table lb-query="accounts">
+  <thead><tr><th>Account</th></tr></thead>
+  <template lb-group>
+    <tbody>
+      <tr><th scope="rowgroup" lb-column="category"></th></tr>
+      <template><tr><td lb-column="account_name"></td></tr></template>
+    </tbody>
+  </template>
+</table>
+```
+
+The hub clones the group template where the order breaks and puts the
+group's contents immediately before the clone of its nested template.  The
+markup's nesting decides the shape:
+
+| The nested template is            | The group's contents land           | Example                          |
+| --------------------------------- | ----------------------------------- | -------------------------------- |
+| Inside the heading's element      | Inside it                           | `<tbody>`, `<li>`, `<details>`   |
+| Beside the heading                | After the heading, as its siblings  | A heading `<tr>` in one `<tbody>` |
+
+`<tbody>` and `<optgroup>` do not nest, so a table's levels below the first
+are heading rows beside their rows.  Content after the nested template lands
+after the group's rows, which is where a group's footer goes.
+
+A group's heading is filled from its first row, the same way a live row is
+filled, so it shows any column of the row.  The example breaks on
+`category_order` and shows `category`.  The hub fills it from no other row.
+
+The hub stamps each top-level element of a group's clone with
+`lb-group-live`, `lb-group-column`, the column it breaks on, and
+`lb-group-value`, its value there.  A row creates its group, and a group
+leaves with its last row.  Groups never move: when a change of order puts
+the groups at a level in another order, each of them is made again.
+
+A group template with no nested template is reported to the console.  More
+group templates than the order has terms show each extra level as one
+group, and are reported once.
+
+#### Aggregates
+
+An aggregate attribute sets an element from the rows of the nearest group
+around it, or of the whole list outside any group.
+
+| Attribute       | Sets the element to                           |
+| --------------- | --------------------------------------------- |
+| `lb-count`      | The number of rows                            |
+| `lb-sum="col"`  | The sum of `col`                              |
+| `lb-avg="col"`  | The average of `col`                          |
+| `lb-min="col"`  | The least value of `col`, by the [order](#order)'s comparison |
+| `lb-max="col"`  | The greatest, likewise                        |
+
+```html
+<tr><td><span lb-count></span> accounts</td><td lb-sum="balance"></td></tr>
+```
+
+It lands as a column does, with `lb-column-value`.  A sum and an average
+are exact decimals, read from JSON numbers and from strings holding a plain
+decimal, as Postgres sends `numeric`.  A sum has as many places as the most
+precise value, and an average up to two more.  `null` and empty values are
+left out, as SQL leaves them out.  Any other value is left out and reported
+once.  The hub does not format the result.
+
+An aggregate covers the rows the browser holds.  Where the true total
+matters beyond what the page shows, it is a row the server answers.
+
+#### What happened to a row
+
+Every change the hub makes to a list is one a stylesheet can see, so an
+application animates with CSS alone and the hub starts no animation.
+
+| Attribute          | On                   | Means                                              |
+| ------------------ | -------------------- | -------------------------------------------------- |
+| `lb-row-created`   | A live row           | Created when the hub last touched it               |
+| `lb-row-changed`   | A live row           | Its values changed when the hub last touched it    |
+| `lb-row-moved`     | A live row           | The order put it somewhere else when last touched  |
+| `lb-row-requested` | A live row           | `created`, `changed` or `moved` by this page's request |
+| `lb-row-leaving`   | A row on its way out | No longer live                                     |
+| `lb-group-leaving` | A group on its way out | No longer live                                   |
+
+The hub touches a row when an answer names it.  `lb-row-created`,
+`lb-row-changed` and `lb-row-moved` are cleared when it next does, and one
+applied again is removed and added as two changes, so an animation keyed to
+it plays again.  `lb-row-requested` is cleared at every landing of the
+row's query, and set only by a landing that answers a request from the page.
+
+A row or a group that leaves loses `lb-row-live` or `lb-group-live`, takes
+`lb-row-leaving` or `lb-group-leaving` and `inert`, and is removed once the
+animations running on it have finished, at once when there are none.  A
+moved row stays live and moves.  A copy of it stays behind where it was,
+leaving.
+
+```css
+[lb-row-created] { animation: arrive 200ms; }
+[lb-row-leaving] { animation: depart 200ms forwards; }
+```
+
+A row never travels between the two places, since that takes measuring, and
+measuring takes script.  Scrolling to a row is script too: a custom element
+reads `lb-row-requested` in [`lbRowsLanded`](#row-hooks).
+
 #### Displaying by condition
 
 `lb-show` names the column that decides whether an element is present.
@@ -558,6 +693,10 @@ so `"false"` is on, and a query spells a condition as a boolean or a null.
 </template>
 ```
 
+Write `!` before the column to reverse it: `lb-show="!chosen"` is present
+while `chosen` is null or false.  One column then decides both of two
+elements, rather than a column and its opposite, which could disagree.
+
 It reads from the nearest ancestor row, as `lb-column` does, and on an
 element that carries `lb-query` the column belongs to the row around it.  A
 row that does not carry the column leaves the element as it is.
@@ -578,7 +717,8 @@ nothing conditional shows until its row lands.  An absent element's template
 keeps its place among its siblings, and a position selector counts it.
 
 These are build errors: `lb-show` on a row template's root, `lb-show` with
-no `lb-query` around it, and `lb-show` on a `<template>`.
+no `lb-query` around it, `lb-show` on a `<template>`, and `lb-show="!"` or
+`lb-show="!!column"`.
 
 Hiding is presentation, and the server still refuses what a request may not
 do.
@@ -602,13 +742,15 @@ answered side by side.  A column never holds rows.
 ```
 
 Many masters, each with its own detail, is one `rows` query of joined rows:
-each detail row carries its master's columns.  A custom element's
-`lbPlaceRow` groups them for display, as `lb-table` builds sections and
-`lb-options` builds `<optgroup>`s.
+each detail row carries its master's columns.  A [group
+template](#groups) shows each master as a group, ordered by the master's
+key first.
 
 A query nested in another query's row template receives the same rows in
 every live row.  That serves a picker offering the same choices on every
-row, and is not a way to show a different detail per row.
+row, and is not a way to show a different detail per row.  A live row added
+later is filled from the nested query's last answer, so a request that adds
+one does not refresh the nested query to fill it.
 
 Which master a page shows is a query parm, which a query reads off `ctx`
 since it takes no argument from the browser — see [Query parms](#query-parms).
@@ -767,6 +909,18 @@ interceptor calls `stopPropagation`, not `preventDefault`.  This is what
 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 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
+failed.  By then `lb-request-pending` is gone, and a listener sees the page
+as the answer left it.  A request the hub or an ancestor stopped was never
+sent, and gets no `lb-request-done`.  An element the answer removed from the
+document, such as the row a delete took away, dispatches the event where it
+now is, and no ancestor it had on the page hears it.
+
 #### Request state
 
 The hub stamps `lb-request-pending` on the element that issued a request
@@ -804,6 +958,14 @@ A page load that fails lands nothing and is reported to the console.  A load
 started by a request for `lb-url` stamps the element that issued it, as any
 request stamps its element.
 
+A response answers for the URL its request was sent from, path and query
+string both.  One that returns after the URL has moved lands nothing, since
+it describes what the user is no longer looking at: a request's answer,
+including any `url()` it carries, and a page load overtaken by a newer one.
+A write whose answer is dropped this way has still happened.  Its
+`lb-request-done` carries no items and no error, and an insert still resets
+its form.
+
 ### The URL
 
 ---- UNEDITED ----
@@ -834,6 +996,14 @@ server runs its `onPageEnter`, then its queries.  When a query parm takes a
 new value, the hub reloads the page's queries, and keeps the page's DOM, so
 live rows that come back keep their place.
 
+Once an entered page's queries have landed, the hub focuses the first
+element in `<main>` the user can operate: not disabled, not in a closed
+`<dialog>`, not `inert`, not `hidden`, not in an absent `lb-show` branch,
+and one that takes the focus.  Entering is a cold load, a new `lb-path`,
+and Back or Forward to another page.  A change of query parm enters no
+page, and focus stays where it is, as it does when it is already in
+`<main>`.
+
 The page's title is the text of the page file's `<title>`, which the builder
 stamps on the page as `lb-page-title`.  The hub sets the document title to
 `lb-page-label` when it is not null.
@@ -941,8 +1111,10 @@ names each one in the row it lands.
 
 The hub sends the query parms with every round trip, a page load and a
 request alike.  The server passes them to `contextFor` — see
-[The Express server](#the-express-server).  Nothing in Loadbare assigns a
-parm a meaning.
+[The Express server](#the-express-server).  Loadbare assigns one parm a
+meaning, `lb-order-<query>`, the user's [order](#order) for a query, and it
+reaches `contextFor` like any other.  A request that changes only order
+parms of queries the hub sorts itself makes no round trip.
 
 #### An unknown page
 
@@ -1003,8 +1175,31 @@ rowInsert: {
   carries the `lb-url` item alone, and the hub loads the page itself.  A
   failure there is a page load's, and is not stamped on the element that
   issued the request.
-- A user who has left the page by the time the response arrives keeps the
-  URL they are on.
+- A user who has moved by the time the response arrives, to another page or
+  to other query parms, keeps the URL they are on.
+
+`onPageEnter` may return `url()` the same way, to move the page before
+anything shows, as an application restoring the filters and order the user
+last had does.  The page loads at the new URL in the same round trip, and
+that load does not follow `onPageEnter` again.  A `url()` leading to the
+page and parms already in hand is ignored, so the page loads once.  When to
+restore is the application's rule, such as only when the URL carries no
+parms of its own.
+
+```ts
+// The application put the parms on ctx in contextFor.
+onPageEnter: async (ctx) => {
+  if (ctx.parms.size > 0) return;
+  const saved = await ctx.db.savedView("accounts");
+  if (saved) return url(saved);
+},
+```
+
+Saving what the user has on screen is a declared request with
+`refresh: []`, whose handler each page passes to a routine the
+application's pages share.  A custom element naming `lb-url` sees every
+change of the URL and issues it, a change of order that made no round trip
+included.
 
 The page is loaded with a second context, built by `contextFor` from the new
 parms — see [The Express server](#the-express-server).
@@ -1015,7 +1210,8 @@ The builder checks the chrome and every page, after expansion, and refuses
 to build on any of these:
 
 - An `lb-` attribute that is not a developer attribute: `lb-query`,
-  `lb-column`, `lb-show`, `lb-request`, `lb-url-link`, `lb-url-push`,
+  `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`.  Every other `lb-` attribute is a stamp.
   `lb-exp-slot` and `lb-exp-template` are consumed by expansion and never
   reach the check.
@@ -1027,6 +1223,19 @@ to build on any of these:
   `<lb-hub>`.
 - `lb-show` on a `<template>`, on a row template's root, or with no
   `lb-query` around it.
+- `lb-show="!"` or `lb-show="!!column"`, which reverse no column.
+- `lb-group` on anything but a `<template>`, or on one holding no
+  `<template>` for its contents.
+- An aggregate on a `<template>`, and any but `lb-count` naming no column.
+- A chrome without exactly one `<lb-hub>` and exactly one `<main>`, a
+  `<main>` outside `<lb-hub>`, or a `<main>` with anything in it but
+  whitespace.
+- A page carrying an `<lb-hub>` or a `<main>`.
+
+The builder also reads the script of every custom element it ships, other
+than `<lb-hub>`, and refuses one that declares a method, accessor or field
+whose name begins with `lb` and a capital and is not in
+[Reserved methods](#reserved-methods).
 
 `lb-column` with no ancestor row is allowed: the hub gathers from it.
 
@@ -1046,7 +1255,8 @@ where the standard landmarks go: header, nav, footer, main.
 The file is an HTML document, which must contain:
 - `<lb-hub>` inside `<body>`.  The hub can only act on its children,
   that is why it is usually nested right below `<body>`. 
-- One empty `<main>` inside `<lb-hub>`.  
+- One empty `<main>` inside `<lb-hub>`.  The builder refuses a chrome
+  without exactly one of each, and a page carrying either.
 - The script tag for `/client.js`, the javascript bundle.
 
 It may also contain:
@@ -1156,6 +1366,8 @@ The builder writes `pages.ts` into `--out` whenever any page has a
 `.queries.ts` or a `.requests.ts` file.  It imports each of them, calls
 `createHub()` once over the lot, and exports the result as `hub`.  The
 server imports that rather than maintaining the registry by hand.
+`createHub` is the only implementation of the `Hub` interface, which may
+gain members in any release; an application never implements it.
 
 ```ts
 // server.ts
@@ -1220,7 +1432,8 @@ the whole path space through unchanged.
 Each key is a query name, which the markup names with `lb-query`.
 
 A query's kind and key belong to its name.  Declare each query with
-`row(key, run)` or `rows(key, run)`, naming the key column first.  A query
+`row(key, run)` or `rows(key, run, options)`, naming the key column first.
+A `rows` query's `options` declare its [order](#order).  A query
 cannot be built without one of these functions.  Every query has a key; an
 aggregate row answers with a constant one.
 
@@ -1238,14 +1451,15 @@ export const queries: Queries = {
 ```
 
 A `row` query returns one object, and a `rows` query returns an array of
-objects in the order the page shows them.  An answer that disagrees with
+objects, which the page shows in that order when the query declares none.  An answer that disagrees with
 its declared kind is left out of the response, with a warning naming the
 query.
 
 Query names cannot begin with `lb-`, that namespace is reserved for
 Loadbare/app queries the hub serves in the browser, such as
 [`lb-url`](#the-url).  `createHub` refuses at startup a page that declares
-such a name as a query, a handler or a `crud` entry.
+such a name as a query, a handler or a `crud` entry, and a query whose order
+has a term naming no column.
 
 Every query and every handler receives `ctx`, the application's own request
 context.  The application builds it once per request and hands it to the hub,
@@ -1265,7 +1479,7 @@ It has three optional keys.
 | ------------- | --------------------- | -------------------------------------------------- |
 | `handlers`    | The request name      | The page's declared requests                       |
 | `crud`        | A query name          | The three requests Loadbare provides               |
-| `onPageEnter` | Nothing               | Runs once on entering the page, before its queries |
+| `onPageEnter` | Nothing               | Runs once on entering the page, before its queries, and may move the URL |
 
 The server resolves a declared request against `handlers`, and a request
 Loadbare provides against `crud` under the request's query.  A name with no
@@ -1276,6 +1490,9 @@ request carrying no name answers 400, and a `run` that throws answers 500.
 
 Every handler under `handlers` and `crud` has the same two members.  `run`
 performs the work, and `refresh` names the queries to re-run once it has.
+A query belongs there when its answer changed, never to fill an element the
+request's answer creates: that element is filled from the last answer its
+query landed.
 
 `run` receives the same `ctx` and the request less its name: `query`, `key`
 and `values`, as present.
@@ -1284,6 +1501,14 @@ and `values`, as present.
 the refreshed ones.  That is how a delta reaches the browser: wrap it in
 `patch()`, naming the rows that arrived or changed and the keys that went.
 
+A refreshed `rows` query sends every row to say what changed.  An update or
+a delete names its row by key, so its handler always knows what changed and
+answers with a patch, which the hub places by the query's [order](#order):
+`createHub` refuses at startup a `crud` `rowUpdate` or `rowDelete` on a
+`rows` query whose `refresh` names that same query.  A `row` query sends one
+row and may refresh itself.  An insert may refresh its own query, since its
+key exists only once the row does.
+
 `run` may instead return `url()`, a new row for `lb-url`, naming query parms
 only the write can know, such as the key of a row it inserted.  The page
 then loads at them in the same round trip, in place of the refresh set — see
@@ -1365,9 +1590,14 @@ A response item carries exactly one of `row`, `rows` or `patch`.  A patch
 answers a `rows` query only: rows named in `rows` are added or updated, keys
 in `drop` are removed, and every other row is left alone.
 
+A `rows` item also carries `order` and `serverSortedByUrl` when the query
+declares them.
+
 `createHub(pages)` builds the `Hub`, which has two calls, both answering
-with response items: `dataForPage(page, ctx)` for a page load, and
-`runRequest(page, request, ctx)` for a request.
+with response items: `dataForPage(page, ctx, options)` for a page load, and
+`runRequest(page, request, ctx)` for a request.  `options.parms` are the
+parms the page is loaded at, and `options.follow` false ignores a `url()`
+from `onPageEnter`; `hubRoutes` passes both.
 
 ## Custom elements
 
@@ -1397,6 +1627,25 @@ export default ["@scope/library-name"];
 Import every attribute name from `@loadbare/app/constants` — see
 [Constants](#constants).  Never write one as a string literal.
 
+### 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, 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
+often an ancestor of the one it concerns, and an event reaches it with no
+knowledge of either.
+
 ### Controls
 
 A form-associated custom element with a `value` property that fires
@@ -1428,8 +1677,9 @@ renders it; its content is never replaced.
 | Shows a page                             | `constructor`, `connectedCallback`           |
 | Creates a live row, before placing it    | `constructor`                                |
 | Places a live row the first time         | `connectedCallback`                          |
-| Places it again, on every set of all rows | `disconnectedCallback`, `connectedCallback` |
-| Removes a live row                       | `disconnectedCallback`                       |
+| 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`           |
@@ -1441,14 +1691,27 @@ done once per instance goes behind a flag.
 
 ### Row hooks
 
-| Method                          | Implemented By | The hub calls it                                   |
-| ------------------------------- | -------------- | -------------------------------------------------- |
-| `lbPlaceRow(el, row, template)` | Developer      | To place a live row, detached, on its first arrival and whenever all rows decide the order |
-| `lbRowsLanded()`                | Developer      | After the rows land                                |
+| Method           | Implemented By | The hub calls it                                       |
+| ---------------- | -------------- | ------------------------------------------------------ |
+| `lbRowsLanded()` | Developer      | After the rows land, with every row placed and stamped |
 
-The hub calls both on a custom element with `lb-query` and a row template.
-Both are optional.  The `RowsHost` interface in `@loadbare/app/types`
-declares them.
+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:
+
+```ts
+lbRowsLanded() {
+  this.querySelector(`[${ATTR_ROW_REQUESTED}="${REQUESTED_CREATED}"]`)
+    ?.scrollIntoView({ block: "nearest" });
+}
+```
+
+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.
 
 `applyRow(root, row)`, exported by `@loadbare/app`, fills `root` from one
 row, the same operation that fills a live row.
@@ -1547,12 +1810,17 @@ it may define tomorrow.
 | `lb-url-link`     | Developer     | An `<a>`                            | [Links](#links)                               |
 | `lb-url-push`     | Developer     | An element with `lb-request`        | [Query parms](#query-parms)                   |
 | `lb-url-unknown`  | Developer     | A `<dialog>` inside `<lb-hub>`      | [An unknown page](#an-unknown-page)           |
+| `lb-group`        | Developer     | A `<template>` holding a `<template>` | [Groups](#groups)                           |
+| `lb-count`, `lb-sum`, `lb-avg`, `lb-min`, `lb-max` | Developer | Any element but a `<template>` | [Aggregates](#aggregates) |
 | `lb-exp-slot`     | Developer     | One element in an element file      | [Slots and templates](#slots-and-templates)   |
 | `lb-exp-template` | Developer     | An element file, and a `<template>` | [Slots and templates](#slots-and-templates)   |
 | `lb-column-value` | Hub           | Every element set from a column     | [How a column lands](#how-a-column-lands)     |
 | `lb-key-value`    | Hub           | A live row, and an element a `row` lands on | [Rows](#rows)                         |
 | `lb-row-live`     | Hub           | A live row                          | [Rows](#rows)                                 |
 | `lb-query-row-count` | Hub        | An element with a row template      | [Rows](#rows)                                 |
+| `lb-group-live`, `lb-group-column`, `lb-group-value` | Hub | Each top-level element of a group | [Groups](#groups) |
+| `lb-row-created`, `lb-row-changed`, `lb-row-moved`, `lb-row-requested` | Hub | A live row | [What happened to a row](#what-happened-to-a-row) |
+| `lb-row-leaving`, `lb-group-leaving` | Hub | A row or a group on its way out | [What happened to a row](#what-happened-to-a-row) |
 | `lb-request-pending` | Hub        | The element that issued a request   | [Request state](#request-state)               |
 | `lb-request-error`   | Hub        | The element that issued a request   | [Request state](#request-state)               |
 | `lb-show` on a `<template>` | Hub and builder | Where an absent element stands | [Displaying by condition](#displaying-by-condition) |
@@ -1568,6 +1836,12 @@ The builder refuses any other `lb-` attribute in markup — see
 | -------- | ----- | --------- | --------------------------------------------------------------- | ------------------- |
 | `lb-url` | `row` | `lb-path` | `lb-path`, `lb-page-label`, `lb-page-unknown`, every query parm | [The URL](#the-url) |
 
+### Reserved query parms
+
+| Parm               | Means                       | Defined in      |
+| ------------------ | --------------------------- | --------------- |
+| `lb-order-<query>` | The user's order for a query | [Order](#order) |
+
 ### Reserved request names
 
 | Request name    | Runs under `crud` | Defined in                          |
@@ -1593,12 +1867,12 @@ Loadbare/app owns every DOM event in this table, both the name and what its
 | Event        | Dispatched from                  | Bubbles | Cancelable | Defined in                              |
 | ------------ | -------------------------------- | ------- | ---------- | --------------------------------------- |
 | `lb-request` | The element that committed       | Yes     | No         | [The request event](#the-request-event) |
+| `lb-request-done` | The element that committed  | Yes     | No         | [The request event](#the-request-event) |
 
 ### Reserved methods
 
 | Method         | On                                                 | Defined in              |
 | -------------- | -------------------------------------------------- | ----------------------- |
-| `lbPlaceRow`   | A custom element with `lb-query` and a row template | [Row hooks](#row-hooks) |
 | `lbRowsLanded` | A custom element with `lb-query` and a row template | [Row hooks](#row-hooks) |
 
 ### Constants
@@ -1616,6 +1890,22 @@ imports them rather than writing a string.
 | `ATTR_ROW_LIVE`           | `lb-row-live`                           |
 | `LIVE_ROW`                | `[lb-row-live]`, the selector for a live row |
 | `ATTR_QUERY_ROW_COUNT`    | `lb-query-row-count`                    |
+| `ATTR_GROUP`              | `lb-group`                              |
+| `ATTR_GROUP_LIVE`         | `lb-group-live`                         |
+| `ATTR_GROUP_COLUMN`       | `lb-group-column`                       |
+| `ATTR_GROUP_VALUE`        | `lb-group-value`                        |
+| `LIVE_GROUP`              | `[lb-group-live]`, the selector for a group's element |
+| `ATTR_COUNT`, `ATTR_SUM`, `ATTR_AVG`, `ATTR_MIN`, `ATTR_MAX` | `lb-count`, `lb-sum`, `lb-avg`, `lb-min`, `lb-max` |
+| `AGGREGATES`              | All five aggregate attributes           |
+| `ORDER_PARM_PREFIX`       | `lb-order-`                             |
+| `ORDER_DESCENDING`        | `-`, written before a column in an order |
+| `ATTR_ROW_CREATED`        | `lb-row-created`                        |
+| `ATTR_ROW_CHANGED`        | `lb-row-changed`                        |
+| `ATTR_ROW_MOVED`          | `lb-row-moved`                          |
+| `ATTR_ROW_REQUESTED`      | `lb-row-requested`                      |
+| `REQUESTED_CREATED`, `REQUESTED_CHANGED`, `REQUESTED_MOVED` | `created`, `changed`, `moved` |
+| `ATTR_ROW_LEAVING`        | `lb-row-leaving`                        |
+| `ATTR_GROUP_LEAVING`      | `lb-group-leaving`                      |
 | `ATTR_REQUEST`            | `lb-request`                            |
 | `ATTR_REQUEST_PENDING`    | `lb-request-pending`                    |
 | `ATTR_REQUEST_ERROR`      | `lb-request-error`                      |
@@ -1626,8 +1916,10 @@ imports them rather than writing a string.
 | `ATTR_EXP_TEMPLATE`       | `lb-exp-template`                       |
 | `ATTR_PAGE`               | `lb-page`                               |
 | `ATTR_PAGE_TITLE`         | `lb-page-title`                         |
-| `DEVELOPER_ATTRIBUTES`    | The seven attributes a developer writes |
+| `DEVELOPER_ATTRIBUTES`    | The thirteen attributes a developer writes |
 | `LB_EVENT_NAME`           | `lb-request`                            |
+| `LB_DONE_EVENT_NAME`      | `lb-request-done`                       |
+| `SHOW_NOT`                | `!`, written before a column in `lb-show` |
 | `LB_RESERVED_PREFIX`      | `lb-`                                   |
 | `REQUEST_ROW_INSERT`      | `lb-row-insert`                         |
 | `REQUEST_ROW_UPDATE`      | `lb-row-update`                         |