@loadbare/app 0.12.0 → 0.13.0

package/docs/comparison.md

@@ -320,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
@@ -396,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
@@ -785,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`                                                  |
@@ -926,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.                                                  |
@@ -1181,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).
@@ -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

package/docs/reference/custom-elements.md

@@ -278,7 +278,10 @@ A custom element reads `lb-` attributes and never assigns one. The developer
 writes them in markup, and the hub and the builder write their stamps.
 
 Loadbare reserves method names beginning with `lb` on a custom element, for
-the methods it calls; see [Holding rows](#holding-rows).
+the 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
 
@@ -286,9 +289,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` |
 
@@ -329,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
@@ -505,34 +508,32 @@ 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:
 
@@ -540,25 +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, so it has no `lbPlaceRow` when rows land
-on it then, and the hub places them before the template. 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 every row goes through `lbPlaceRow` and
-`lbRowsLanded` runs. Once upgraded it stays so: when its branch goes away and
-comes back, it has placed every row that landed meanwhile, and nothing is
-landed again.
+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,101 @@ 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
 
@@ -174,16 +265,14 @@ 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 a custom element builds around its rows, such as a ghost row. So
+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, so rows that land on it then are not placed by it.
-When the column first turns on and the element upgrades, the hub lands the
-kept answer on it again, and every row goes through its `lbPlaceRow`. So a
-table that groups its rows can sit under `lb-show`. See
-[Holding rows](./custom-elements.md#holding-rows).
+`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

package/docs/reference/page-files.md

@@ -48,7 +48,8 @@ page touches that page's files.
 ## HTML
 
 Write the page as a fragment. The fragment lands in `<main>`, which
-[chrome.html](./chrome.md) supplies.
+[chrome.html](./chrome.md) supplies.  A page carries no `<main>` and no
+`<lb-hub>` of its own; the builder rejects one that does.
 
 ```html
 <!-- src/pages/about.page.html -->
@@ -89,14 +90,18 @@ export const queries: Queries = {
     page: "directory",
     count: String(await ctx.db.visitCount()),
   })),
-  directory: rows("id", (ctx) => ctx.db.directory()),
+  directory: rows("id", (ctx) => ctx.db.directory(), { order: "name" }),
 };
 ```
 
-| Declared with     | Answers with                              |
-|-------------------|-------------------------------------------|
-| `row(key, run)`   | One row, an object                        |
-| `rows(key, run)`  | All its rows, an array of objects, in order |
+| Declared with              | Answers with                              |
+|----------------------------|-------------------------------------------|
+| `row(key, run)`            | One row, an object                        |
+| `rows(key, run, options)`  | All its rows, an array of objects         |
+
+`options` are a `rows` query's order: `order`, the columns the hub places
+its rows by, and `serverSortedByUrl`, set when the query reads the user's
+order parm itself. See [Order](./data-binding.md#order).
 
 `key` names the column that identifies a row. Give every row that column,
 including a `row` query's: an aggregate row answers with a constant key. The
@@ -109,8 +114,8 @@ page that needs the same data as one row and as a set declares two queries.
 The hub hands each value to the browser untouched, so what a number, a date
 or a null looks like is decided here, in the query.
 
-Return the full answer every time, and the rows in the order the page shows
-them. Sending only what changed is a request's job — see
+Return the full answer every time. With no `order`, the rows show in the
+order they are returned. Sending only what changed is a request's job — see
 [refresh and patch](#refresh-and-patch).
 
 ## Requests
@@ -120,7 +125,7 @@ optional:
 
 | Key           | Runs                                                   |
 |---------------|--------------------------------------------------------|
-| `onPageEnter` | Before the page's queries, when the page loads         |
+| `onPageEnter` | Before the page's queries, when the page loads; may move the URL |
 | `handlers`    | The page's declared requests, by request name          |
 | `crud`        | The requests Loadbare provides, by query name          |
 
@@ -150,6 +155,12 @@ export const requests: Requests = {
 
 Declare no refresh set here. The page's queries run afterward.
 
+It may return `url()` instead, to move the page to other query parms before
+anything shows, as restoring the filters and order the user last had does.
+The page loads there in the same round trip, and that load does not follow
+`onPageEnter` again. A `url()` leading to the parms already in hand is
+ignored. See [Moving the URL](#moving-the-url).
+
 ### handlers
 
 Declare a request under the name the HTML gives `lb-request`. Pair what it
@@ -240,16 +251,14 @@ queries:
 
 Return a patch for a change the request knows the extent of — one row added,
 one row dropped, one row edited — and leave `refresh` empty. 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.
+`rows` query sends every row to say what one row could.
 
 A change that seems to need a refresh usually has a patch:
 
-- A placeholder row standing in for an empty set or section: drop its key in
-  the patch that adds the first real row, and add it back in the patch that
-  drops the last.
-- A row whose position changes: the rows host places it, as
-  [`lb-table`](./widgets.md#lb-table) does by `data-sort`.
+- A row whose position changes: the hub places it by the query's
+  [order](./data-binding.md#order).
+- A group that appears or goes: the hub makes a group with its first row
+  and removes it with its last, so no row stands in for an empty one.
 - A row whose other columns change with the edit: re-read the row and patch
   it.
 - Rows the database removes with a deleted one: select their keys before the

package/docs/reference/server.md

@@ -91,6 +91,10 @@ TypeScript types itself. `dist/pages.ts` imports each `.requests.ts` and
 `.queries.ts` file by its full name, extension included, because Node looks
 for exactly the path an import names.
 
+The `hub` it exports comes from `createHub`, the only implementation of
+the `Hub` interface. That interface may gain members in any release, so an
+application never implements it.
+
 Enable `allowImportingTsExtensions` in the application's `tsconfig.json`
 when `tsc` type-checks the server. Without it, `tsc` rejects the `.ts`
 extensions in `dist/pages.ts`: