@loadbare/app 0.12.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
 
@@ -77,38 +68,13 @@ But the allowed values may depend on other values in the row.
 </tbody>
 ```
 
-### Who creates and orders rows
-
-The hub creates every live row from a row template and places it in the
-query's order, unless the element holding the rows has `lbPlaceRow`, in
-which case the custom element decides where each row goes.  Custom elements
-also create rows of their own: `lb-table` clones a ghost row per section and
-builds each section's heading.  Neither side owns creation or order.
-
-- **Decide who creates rows and who orders them.** A patch cannot say where
-  a new row goes, so it lands where the host puts it: in order under
-  `lb-table` with `data-sort`, last in plain markup and in `lb-options`.
-  Whether an insert may answer with a patch therefore depends on markup the
-  server cannot see, and the server cannot refuse an insert that refreshes
-  its own query the way it refuses an update or a delete.
-- **Decide whether landing all rows moves rows already in place.** It moves
-  every row today, which takes focus from the control the user is in, and
-  `lbPlaceRow` does the same.
-
 ### 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
@@ -123,9 +89,6 @@ builds each section's heading.  Neither side owns creation or order.
   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
@@ -141,9 +104,6 @@ builds each section's heading.  Neither side owns creation or order.
 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
@@ -455,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                             |
 | ------ | ------------ | ----------------------------------- |
@@ -538,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
@@ -560,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.
@@ -624,9 +742,9 @@ 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
@@ -993,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
 
@@ -1058,6 +1178,29 @@ rowInsert: {
 - 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).
 
@@ -1067,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.
@@ -1080,6 +1224,18 @@ to build on any of these:
 - `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.
 
@@ -1099,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:
@@ -1209,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
@@ -1273,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.
 
@@ -1291,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,
@@ -1318,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
@@ -1340,14 +1501,13 @@ 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, and the hub places every row
-again, which moves each element and takes focus from the control the user
-is in.  An update or a delete names its row by key, and removing a row
-never reorders the rest, so its handler always knows what changed:
+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; see
-[Who creates and orders rows](#who-creates-and-orders-rows).
+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
@@ -1430,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
 
@@ -1468,9 +1633,9 @@ 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-request-pending`, `lb-request-error` |
+| 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      | `lbPlaceRow`, `lbRowsLanded`                     |
+| 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` |
 
@@ -1512,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`           |
@@ -1525,19 +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, and rows that land on it then are placed
-without it.  When the column first turns on and it upgrades, the hub lands
-the query's last answer on it again, as all rows, so both hooks run.
+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.
@@ -1636,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) |
@@ -1657,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                          |
@@ -1688,7 +1873,6 @@ Loadbare/app owns every DOM event in this table, both the name and what its
 
 | 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
@@ -1706,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`                      |
@@ -1716,7 +1916,7 @@ 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` |

package/skills/loadbare-app/references/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).
@@ -165,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