@loadbare/app 0.26.0 → 0.27.0

package/docs/reference/data-binding.md

@@ -2,7 +2,7 @@
 
 A page shows server data by naming queries and columns in its HTML, and asks
 the server to change that data by naming requests. The developer writes
-fourteen `lb-` attributes. The server declares every query a page may show and
+ten `lb-` attributes. The server declares every query a page may show and
 every request it may send, and refuses anything it has not declared.
 
 Everything is a query. A query is a name for rows, of kind `row` or `rows`,
@@ -46,8 +46,9 @@ each with its key, and permits the three requests on `roster`; see
 | `lb-query`       | Any element                   | The query whose rows land in it                |
 | `lb-column`      | Any element                   | The column it shows, and the column it gathers |
 | `lb-show`        | Any element but `<template>`  | The column that decides whether it is present  |
-| `lb-order`       | An element with `lb-query`    | The choice holding the user's order; see [Order](#order) |
-| `lb-filter`      | An element with `lb-query`    | The columns a choice filters; see [Filters](#filters) |
+| `lb-filter`      | An element with `lb-query`    | The columns the user may filter; see [Filters](#filters) |
+| `lb-group`       | A `<template>`                | Nothing: it marks a group template; see [Groups](#groups) |
+| `lb-aggregate`   | Any element                   | The function it applies to `lb-column`; see [Aggregates](#aggregates) |
 | `lb-request`     | Any element                   | The request it sends when it commits           |
 | `lb-url-link`    | An `<a>`                      | A link between pages; see [chrome](./chrome.md#links) |
 | `lb-url-parm`    | An `<a lb-url-link>` in a row | Columns of the row its `href` carries as parms; see [chrome](./chrome.md#a-link-from-a-row) |
@@ -65,8 +66,9 @@ builder writes a stamp, and a stylesheet or a custom element reads it.
 | `lb-query-row-count` | The number of live rows an element shows           |
 | `lb-query-unplaced-count` | The number of them out of place; see [Placing by hand](#placing-by-hand) |
 | `lb-query-order`     | The order placing them; see [Order](#order)        |
+| `lb-group-live`, `lb-group-column`, `lb-group-value` | A group, the column it breaks on, and its value; see [Groups](#groups) |
 | `lb-row-created`, `lb-row-changed`, `lb-row-moved`, `lb-row-requested`, `lb-row-unplaced` | What happened to a row; see [What happened to a row](#what-happened-to-a-row) |
-| `lb-row-leaving` | A row on its way out      |
+| `lb-row-leaving`, `lb-group-leaving` | A row or group on its way out      |
 | `lb-row-editing`     | The row a form is pointed at; see [Editing a row in one form](#editing-a-row-in-one-form) |
 | `lb-request-pending` | The element's request is in flight                 |
 | `lb-request-error`   | The element's last request failed                  |
@@ -86,7 +88,8 @@ elements as the page needs.
 
 What lands depends on the query's kind and on whether the element holds a
 row template, which is the first `<template>` among its descendants outside
-any nested `lb-query`:
+any nested `lb-query`, or, when that template is a [group
+template](#groups), the innermost template inside it:
 
 | Kind   | Row template | The hub                                |
 |--------|--------------|----------------------------------------|
@@ -178,7 +181,7 @@ or `""`:
 
 A checkbox lands what it sends, so it shows the same state after a round
 trip through a query whose values are strings, such as `lb-url` or
-`lb-choices`. A query parm the URL does not carry lands as `""`, so the
+`lb-filters`. A query parm the URL does not carry lands as `""`, so the
 checkbox is unchecked. Unchecked sends `"false"` rather than nothing, so a
 flag can be set back. A checkbox carrying a `value` attribute is not a flag
 but one of a set, holding a query parm the URL repeats; see
@@ -264,25 +267,22 @@ roster: rows("id", (ctx) => ctx.db.members(), { order: "team,name" }),
 With no order, rows show in the order they arrived, and a patch's new rows
 go last.
 
-The user's order replaces the server's. Write `lb-order` on the element
-carrying `lb-query`, naming a column of [`lb-choices`](#choices). That
-column holds an order written the same way, and while it is empty the
-server's order places the rows:
+The user's order replaces the server's. The hub serves the query
+[`lb-sort`](#sort-and-filters), one row per `rows` query, keyed by the
+query's name, whose `order` column holds an order written the same way.
+While it is empty, the server's order places the rows:
 
 ```html
-<div lb-query="lb-choices">
-  <select lb-column="roster_order" lb-request="lb-row-update">
-    <option value="">By team</option>
-    <option value="name">By name</option>
-    <option value="-joined">Newest first</option>
-  </select>
-</div>
-
-<ul lb-query="roster" lb-order="roster_order">
+<ul lb-query="roster">
   <template><li lb-column="name"></li></template>
 </ul>
 ```
 
+A control makes a choice by sending `lb-row-update` for `lb-sort`, keyed by
+the query's name; the `<lb-table>` widget's sortable headings do this for
+each column. The hub places the rows again from the ones it already holds,
+and tells the server through `onChoices`.
+
 | Values               | Compare                                      |
 |----------------------|----------------------------------------------|
 | Two numbers          | Numerically                                  |
@@ -314,7 +314,7 @@ user works through them. It names `order`, `filter` or both, separated by a
 space:
 
 ```html
-<lb-table lb-query="entries" lb-order="entries_order"
+<lb-table lb-query="entries"
           lb-filter="description, is_unmatched" lb-manual="order filter">
 ```
 
@@ -325,7 +325,8 @@ form `--lb-edit` pointed at a row, or a form elsewhere on the page.
 | The answer                             | Under `lb-manual`, the row                        | Side     |
 |----------------------------------------|---------------------------------------------------|----------|
 | Changes a column the order reads       | Stays where it stands                             | `order`  |
-| Creates a row                          | Goes last                                         | `order`  |
+| Creates a row                          | Goes after the last row of its group, or last of all | `order`  |
+| Changes the column its group breaks on | Stays under its group's heading                   | `order`  |
 | Changes a row so the filter hides it   | Stays showing                                     | `filter` |
 | Drops a row                            | Leaves, under either side                         |          |
 
@@ -374,21 +375,22 @@ the move.
 
 Write `lb-filter` on the element carrying `lb-query`, naming the columns of
 its rows the user may filter, separated by commas. The column of
-[`lb-choices`](#choices) of the same name holds the filter for each:
+[`lb-filters`](#sort-and-filters) of the same name holds the filter for
+each:
 
 ```html
-<div lb-query="lb-choices">
-  <input lb-column="name" lb-request="lb-row-update" placeholder="Name" />
-</div>
-
 <ul lb-query="roster" lb-filter="name, team">
   <template><li lb-column="name"></li></template>
 </ul>
 ```
 
+A filter is made by sending `lb-row-update` for `lb-filters`, keyed by the
+query's name; the `<lb-table>` widget's selection does this.
+
 A row that does not pass every filter is `hidden`. Under `lb-manual="filter"`, a row an answer changed stays
 showing until the rows are placed again; see
-[Placing by hand](#placing-by-hand). An empty
+[Placing by hand](#placing-by-hand). A group whose rows are all hidden is hidden too
+([miswart](../miswarts.md#rows-hidden-by-a-filter)). An empty
 choice filters nothing.
 
 A filter is one or more terms, each an operator followed by a value:
@@ -421,6 +423,97 @@ column that is null or missing, pass only `!=`.
 `parseFilter`, `passes` and `passesTerm` in `@loadbare/app/types` are the
 rule the hub applies.
 
+### 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 hub clones the group template where the order breaks, and the group's
+contents land immediately before the clone of its nested template, so 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:
+
+```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>
+```
+
+Content after the nested template lands after the group's rows, which is
+where a group's footer goes.
+
+A heading is filled from its group's first row as an element in a row is,
+`href`s from `lb-url-parm` included, so it may show a column other than the
+one the group breaks on. Under `lb-manual="order"`, a row an answer
+moved to another group stays under its old heading, and the heading shows
+the row as it stood, until the rows are placed again. 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. When the order changes, a group whose run goes on is kept and moved,
+and a group whose run ended leaves.
+
+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
+
+`lb-aggregate` sets an element from the rows of the nearest group around
+it, or of the whole list outside any group. It names the function, and
+`lb-column` names the column:
+
+```html
+<tr><td><span lb-aggregate="count"></span> people</td><td lb-aggregate="sum" lb-column="salary"></td></tr>
+```
+
+| `lb-aggregate` | Sets the element to                                       |
+|----------------|-----------------------------------------------------------|
+| `count`        | The number of rows; with `lb-column`, the values in it that are not null |
+| `sum`          | The sum of the column                                     |
+| `avg`          | The average of the column                                 |
+| `min`          | The least value of the column, by the [order](#order)'s comparison |
+| `max`          | The greatest, likewise                                    |
+
+An aggregate lands as a column does, with `lb-column-value`; its
+`lb-column` names the column it totals, and no row lands on it. 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, and any other value is left
+out and reported once. The result lands unformatted.
+
+An aggregate covers the rows showing, so a row a filter hides is left out.
+Where the true total matters beyond what the page shows, have the server
+answer it as a row.
+
 ### What happened to a row
 
 Every change to a list is one a stylesheet can see:
@@ -433,6 +526,7 @@ Every change to a list is one a stylesheet can see:
 | `lb-row-requested` | `created`, `changed` or `moved` by this page's request |
 | `lb-row-unplaced`  | Stands where the order or the filter would not leave it |
 | `lb-row-leaving`   | A row on its way out                                   |
+| `lb-group-leaving` | A group on its way out                                 |
 
 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
@@ -443,8 +537,8 @@ query, and set only by a landing that answers a request from the page.
 placed again; see
 [Placing by hand](#placing-by-hand).
 
-A row that leaves loses `lb-row-live`, takes
-`lb-row-leaving` and `inert`
+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`
 ([miswart](../miswarts.md#leaving-rows-are-inert)), and is removed once its
 animations finish, at once when there are none.
 
@@ -468,7 +562,7 @@ The hub keeps each query's last answer until the page changes, with any
 patch since applied to it. An element that names a query and arrives after
 that query's answer is filled from what was kept, at the end of the landing
 that follows its arrival. Such an element is a picker in a new live row, or
-scaffolding around rows, such as a 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.
 
@@ -477,8 +571,8 @@ and its `lbRowsLanded` runs as its rows land. See
 [Holding rows](./custom-elements.md#holding-rows).
 
 A request always goes to the server, and a query re-runs only when a
-response names it. A [choice](#choices) is the one thing landed from what
-the hub kept. A patch that
+response names it. A [sort or a filter](#sort-and-filters) is the one thing
+landed from what the hub kept. A patch that
 arrives before all of a query's rows is not kept, since it is not the whole
 of anything.
 
@@ -536,8 +630,8 @@ 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, ordered by the master's key
-first.
+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
@@ -827,7 +921,7 @@ it, and sends nothing:
   Its controls start at their HTML defaults, and its `lb-show` branches are
   as for a row whose every column is null.
 - It stands after every row of the list, in the order added, and is not
-  ordered or filtered, since it holds no data. It counts in
+  ordered, filtered or aggregated, since it holds no data. It counts in
   `lb-query-row-count`.
 - The form's submit carries it in `rows`, with `key: ""`, beside the rows on
   record: an insert while the master is not on record, an update once it
@@ -907,10 +1001,10 @@ The hub sends one of these only when it has what the table lists, and
 otherwise reports to the console. An insert or an update that gathers
 nothing is not sent.
 
-For a query the hub serves, `lb-url` or `lb-choices`, the hub answers
-`lb-row-update` itself, with no round trip; see
-[Query parms](./chrome.md#query-parms) and [Choices](#choices). The third,
-`lb-hub-status`, takes no request.
+For a query the hub serves, `lb-url`, `lb-sort` or `lb-filters`, the hub
+answers `lb-row-update` itself, with no round trip; see
+[Query parms](./chrome.md#query-parms) and
+[Sort and filters](#sort-and-filters). `lb-hub-status` takes no request.
 
 A key comes from a live row, or from an element a `row` landed on, so all
 three work against either kind:
@@ -1225,28 +1319,28 @@ answers it with no round trip:
 See [The URL](./chrome.md#the-url) for its columns, links, history, and the
 unknown-page dialog.
 
-## Choices
+## Sort and filters
 
-The hub serves a second query, `lb-choices`: one row keyed by `lb-path`,
-with a column for each choice the user made for how rows show, an
-[order](#order) or a [filter](#filters). The application names the
-columns. A control inside `lb-query="lb-choices"` that sends
-`lb-row-update` makes a choice, and an element anywhere may make one by
-dispatching the `lb-request` event with `lb-row-update` for `lb-choices`,
-which the hub keys by the path; see
+The hub serves two queries for how rows show: `lb-sort` and `lb-filters`,
+one row per `rows` query, keyed by the query's name. `lb-sort` holds each
+query's order as the server resolved it; `lb-filters` holds each query's
+filter values. An element makes a sort or a filter by dispatching
+`lb-request` with `lb-row-update` for `lb-sort` or `lb-filters`, keyed by
+the query's name; the `<lb-table>` widget's sortable headings and its
+selection do this; see
 [Sending a request](./custom-elements.md#sending-a-request).
 
-A choice joins the ones already made, and shows with no round trip: every
-element whose `lb-order` or `lb-filter` reads a column that changed lands
-its query's last answer again, as a round trip carrying the choice would
-have. Then the hub sends the server every choice made on the page, as
-strings, in `lb-row-update` for `lb-choices`. No element waits on it, and
-the page's [`onChoices`](./page-files.md#onchoices) runs, when it has one.
+A sort or a filter shows with no round trip: the hub places and filters the
+rows it already holds again, as a round trip carrying the choice would
+have. Then it sends the server the choice, in `lb-row-update` for `lb-sort`
+or `lb-filters`. No element waits on it, and the page's
+[`onChoices`](./page-files.md#onchoices) runs, when it has one, with the
+query and its new `sort` or `filters`.
 
 Choices hold until the page changes, and a change of query parm keeps them.
-On entering a page, every column named under `lb-query="lb-choices"` lands
-empty, unless the page's `onPageEnter` restores them. Choices are not query
-parms, and the URL does not carry them.
+On entering a page, `lb-sort` and `lb-filters` land empty, unless the
+page's `onPageEnter` restores them with `sort()` and `filters()`. Choices
+are not query parms, and the URL does not carry them.
 
 ## The markup checks
 
@@ -1254,16 +1348,18 @@ The developer writes `lb-` attributes in markup, and script never assigns
 them. The builder checks the markup of the chrome and of every page, after
 expansion, and refuses to build:
 
-- an `lb-` attribute that is not one of the fourteen the developer writes;
+- an `lb-` attribute that is not one of the ten the developer writes;
   `lb-exp-slot` and `lb-exp-template` are consumed by expansion and never
   reach the check
 - `lb-request` naming an `lb-` request other than the three Loadbare provides
 - `lb-query` naming a query the page does not declare; every page and the
-  chrome may name `lb-url` and `lb-choices`, and the chrome names no other
+  chrome may name `lb-url`, `lb-sort`, `lb-filters` and `lb-hub-status`,
+  and the chrome names no other
 - `lb-request` naming a request the page does not declare under `handlers`;
   the chrome sends none
 - one of the three requests for a query whose `crud` entry does not declare
-  it, or any but `lb-row-update` for `lb-url` or `lb-choices`; the query is
+  it, or any but `lb-row-update` for `lb-url`, `lb-sort` or `lb-filters`;
+  the query is
   a form's own when the form carries `lb-query`, and otherwise the nearest
   `lb-query` around the element
 - `lb-url-link` on anything but an `<a>`
@@ -1278,10 +1374,16 @@ expansion, and refuses to build:
 - `lb-show` on a `<template>`, or on a row template's root
 - `lb-show` with no `lb-query` around it
 - `lb-show="!"` or `lb-show="!!column"`, which reverse no column
-- `lb-order` or `lb-filter` on an element not carrying `lb-query`, or naming
-  no column
+- `lb-filter` on an element not carrying `lb-query`, or naming no column
 - `lb-manual` on an element not carrying `lb-query`, or naming anything but
   `order`, `filter` or both
+- `lb-group` on anything but a `<template>`, or on one holding no
+  `<template>` for its contents
+- `lb-aggregate` on a `<template>`, naming a function other than `count`,
+  `sum`, `avg`, `min` or `max`, or, for any but `count`, beside no
+  `lb-column`
+- `lb-count`, `lb-sum`, `lb-avg`, `lb-min` or `lb-max`, with what to write
+  instead
 - a `command` beginning `--lb-` that is not one of the four commands
 - one of the four commands with no `commandfor`
 - `--lb-new` aimed at an element the markup holds that is neither a

package/docs/reference/names.md

@@ -65,7 +65,7 @@ A widget package declares these.  An application never does.
 
 ## Attributes
 
-The developer writes fourteen attributes in pages and the chrome, and the
+The developer writes ten attributes in pages and the chrome, and the
 builder refuses any other `lb-` attribute there.  `lb-exp-slot` and
 `lb-exp-template` are written for expansion, which removes them before the
 check.  The hub and the builder write the rest, as stamps, and script never
@@ -76,9 +76,10 @@ assigns one.
 | `lb-query`           | Developer       | [Landing](./data-binding.md#landing)                             |
 | `lb-column`          | Developer       | [Landing](./data-binding.md#landing)                             |
 | `lb-show`            | Developer       | [Conditional rendering](./data-binding.md#conditional-rendering) |
-| `lb-order`           | Developer       | [Order](./data-binding.md#order)                                 |
 | `lb-filter`          | Developer       | [Filters](./data-binding.md#filters)                             |
 | `lb-manual`          | Developer       | [Placing by hand](./data-binding.md#placing-by-hand)             |
+| `lb-group`           | Developer       | [Groups](./data-binding.md#groups)                               |
+| `lb-aggregate`       | Developer       | [Aggregates](./data-binding.md#aggregates)                       |
 | `lb-request`         | Developer       | [Requests](./data-binding.md#requests)                           |
 | `lb-url-link`        | Developer       | [Links](./chrome.md#links)                                       |
 | `lb-url-parm`        | Developer       | [A link from a row](./chrome.md#a-link-from-a-row)               |
@@ -92,8 +93,9 @@ assigns one.
 | `lb-query-row-count` | Hub             | [Counting rows](./data-binding.md#counting-rows)                 |
 | `lb-query-unplaced-count`, `lb-row-unplaced` | Hub | [Placing by hand](./data-binding.md#placing-by-hand) |
 | `lb-query-order`     | Hub             | [Order](./data-binding.md#order)                                 |
+| `lb-group-live`, `lb-group-column`, `lb-group-value` | Hub | [Groups](./data-binding.md#groups)                       |
 | `lb-row-created`, `lb-row-changed`, `lb-row-moved`, `lb-row-requested` | Hub | [What happened to a row](./data-binding.md#what-happened-to-a-row) |
-| `lb-row-leaving` | Hub | [What happened to a row](./data-binding.md#what-happened-to-a-row) |
+| `lb-row-leaving`, `lb-group-leaving` | Hub | [What happened to a row](./data-binding.md#what-happened-to-a-row) |
 | `lb-row-editing`     | Hub             | [Editing a row in one form](./data-binding.md#editing-a-row-in-one-form) |
 | `lb-request-pending` | Hub             | [Request state](./data-binding.md#request-state)                 |
 | `lb-request-error`   | Hub             | [Request state](./data-binding.md#request-state)                 |
@@ -111,7 +113,8 @@ them, and a page declares none.
 | Query        | Kind  | Key       | Columns                                                         | Defined in                            |
 | ------------ | ----- | --------- | --------------------------------------------------------------- | ------------------------------------- |
 | `lb-url`     | `row` | `lb-path` | `lb-path`, `lb-page-label`, every query parm                    | [The URL](./chrome.md#the-url)        |
-| `lb-choices` | `row` | `lb-path` | `lb-path`, every choice                                         | [Choices](./data-binding.md#choices)  |
+| `lb-sort`     | `rows` | `query` | `query`, `order`                                                | [Sort and filters](./data-binding.md#sort-and-filters) |
+| `lb-filters`  | `rows` | `query` | `query`, every filter column                                    | [Sort and filters](./data-binding.md#sort-and-filters) |
 | `lb-hub-status` | `row` | `lb-path` | `lb-path`, `lb-load-state`, `lb-server-state`, `lb-error`, `lb-pending`, `lb-as-of` | [The hub's state](./chrome.md#the-hubs-state) |
 
 No query parm is reserved: a column of `lb-url` whose name begins with
@@ -170,7 +173,7 @@ accessor or field named `lb` and a capital.
 
 | Entry point                | Exports                                                          | Defined in                                     |
 | -------------------------- | ---------------------------------------------------------------- | ---------------------------------------------- |
-| `@loadbare/app/server`     | `row`, `rows`, `patch`, `url`, `choices`, `refusal`, `createHub`, and the types `Queries`, `Requests`, `HubContext`, `Hub` | [Page Files](./page-files.md), [The data channel](./server.md#the-data-channel) |
+| `@loadbare/app/server`     | `row`, `rows`, `patch`, `url`, `sort`, `filters`, `refusal`, `createHub`, and the types `Queries`, `Requests`, `HubContext`, `Hub` | [Page Files](./page-files.md), [The data channel](./server.md#the-data-channel) |
 | `@loadbare/app/express`    | `hubRoutes`                                                      | [The Express Server](./server.md)              |
 | `@loadbare/app/dev`        | `devServer`, `appServer`, `gate`, `devProxy`, `DOWN_MESSAGE`     | [The Dev Server](./dev-server.md)              |
 | `@loadbare/app/build`      | `buildApp`, `watchApp`                                           | [Assembling your own](./dev-server.md#assembling-your-own) |
@@ -196,10 +199,21 @@ imports them rather than writing a string.
 | `ATTR_QUERY_ROW_COUNT`    | `lb-query-row-count`                    |
 | `ATTR_QUERY_UNPLACED_COUNT` | `lb-query-unplaced-count`             |
 | `ATTR_QUERY_ORDER`        | `lb-query-order`                        |
+| `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_AGGREGATE`          | `lb-aggregate`                          |
+| `AGGREGATE_COUNT`, `AGGREGATE_SUM`, `AGGREGATE_AVG`, `AGGREGATE_MIN`, `AGGREGATE_MAX` | `count`, `sum`, `avg`, `min`, `max` |
+| `AGGREGATES`              | All five aggregate functions            |
 | `ORDER_DESCENDING`        | `-`, written before a column in an order |
 | `COLUMN_TYPES`            | `number`, `boolean`, `text`             |
-| `CHOICES_QUERY`           | `lb-choices`                            |
-| `ATTR_ORDER`              | `lb-order`                              |
+| `SORT_QUERY`              | `lb-sort`                               |
+| `SORT_COLUMN_QUERY`       | `query`                                 |
+| `SORT_COLUMN_ORDER`       | `order`                                 |
+| `FILTERS_QUERY`           | `lb-filters`                            |
+| `FILTERS_COLUMN_QUERY`    | `query`                                 |
 | `ATTR_FILTER`             | `lb-filter`                             |
 | `ATTR_MANUAL`             | `lb-manual`                             |
 | `MANUAL_ORDER`, `MANUAL_FILTER` | `order`, `filter`: the sides `lb-manual` names |
@@ -211,6 +225,7 @@ imports them rather than writing a string.
 | `REQUESTED_CREATED`, `REQUESTED_CHANGED`, `REQUESTED_MOVED` | `created`, `changed`, `moved` |
 | `ATTR_ROW_UNPLACED`       | `lb-row-unplaced`                       |
 | `ATTR_ROW_LEAVING`        | `lb-row-leaving`                        |
+| `ATTR_GROUP_LEAVING`      | `lb-group-leaving`                      |
 | `ATTR_REQUEST`            | `lb-request`                            |
 | `LB_EVENT_NAME`           | `lb-request`, the event every request travels as |
 | `LB_DONE_EVENT_NAME`      | `lb-request-done`                       |
@@ -252,7 +267,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 fourteen attributes a developer writes |
+| `DEVELOPER_ATTRIBUTES`    | The ten attributes a developer writes |
 | `HUB_TAG_NAME`            | `lb-hub`                                |
 | `LB_ENDPOINT`             | `/lb`                                   |
 | `LB_REQUEST_TIMEOUT_MS`   | `10000`                                 |

package/docs/reference/page-files.md

@@ -152,8 +152,8 @@ optional:
 
 | Key           | Runs                                                   |
 |---------------|--------------------------------------------------------|
-| `onPageEnter` | Before the page's queries, when the page loads; may move the URL or restore choices |
-| `onChoices`   | Each time the user makes a choice                      |
+| `onPageEnter` | Before the page's queries, when the page loads; may move the URL or restore the user's order and filters |
+| `onChoices`   | Each time the user changes the order or a filter        |
 | `handlers`    | The page's declared requests, by request name          |
 | `crud`        | The requests Loadbare provides, by query name          |
 
@@ -190,34 +190,41 @@ 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).
 
-It may return `choices()`, alone or beside `url()`, to restore the user's
-[choices](./data-binding.md#choices) for the page:
+It may return `sort()` and `filters()`, alone or beside `url()`, to restore
+the user's [order and filters](./data-binding.md#sort-and-filters) for the
+page:
 
 ```ts
 // src/pages/directory.requests.ts
-import { choices, url, type Requests } from "@loadbare/app/server";
+import { sort, filters, url, type Requests } from "@loadbare/app/server";
 
 export const requests: Requests = {
   onPageEnter: async (ctx) => {
     const saved = await ctx.db.savedView("directory");
-    if (saved) return { ...url(saved.parms), ...choices(saved.choices) };
+    if (saved) {
+      return {
+        ...url(saved.parms),
+        ...sort(saved.order),
+        ...filters(saved.filters),
+      };
+    }
   },
-  onChoices: (ctx, chosen) => ctx.db.saveChoices("directory", chosen),
+  onChoices: (ctx, change) => ctx.db.saveChoices(change),
 };
 ```
 
-The page load answers `lb-choices` first, so the rows land by the choices.
-When `url()` moves the page, the choices arrive with the load at the new
-URL. `choices()`, like `url()`, takes columns whose values are strings, at
-least one of them; anything else is reported on the server console and
-ignored.
+The page load answers `lb-sort` and `lb-filters` first, so the rows land by
+the order and the filters. When `url()` moves the page, the choices arrive
+with the load at the new URL. `sort()` and `filters()`, like `url()`, take
+columns whose values are strings, at least one of them; anything else is
+reported on the server console and ignored.
 
 ### onChoices
 
-`onChoices` runs each time the user makes a choice, with every choice made
-on the page, by column, as strings. It is how an application keeps them for
-`onPageEnter` to restore, and answers nothing, by convention. Whatever it
-returns lands. A page without it is not told.
+`onChoices` runs each time the user changes the order or a filter, with the
+query and its new `sort` or `filters`, as strings. It is how an application
+keeps them for `onPageEnter` to restore, and answers nothing, by
+convention. Whatever it returns lands. A page without it is not told.
 
 ### handlers
 
@@ -377,6 +384,8 @@ A change that seems to need a refresh usually has a patch:
   [order](./data-binding.md#order), or leaves it where it stands under the
   list's [`lb-manual`](./data-binding.md#placing-by-hand); a refresh would do
   the same.
+- 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

@@ -228,9 +228,9 @@ in `drop` are removed, and every other row is left alone. A `rows` item on
 the answer that loads the page also carries the query's declared `order`
 and `types`, which the hub keeps for every answer after it.
 
-A choice is sent as `lb-row-update` for `lb-choices`, keyed by the path,
-with every choice made on the page as `values`; see
-[Choices](./data-binding.md#choices).
+A sort or a filter is sent as `lb-row-update` for `lb-sort` or `lb-filters`,
+keyed by the query's name, with the new order or filter as `values`; see
+[Sort and filters](./data-binding.md#sort-and-filters).
 
 `createHub(pages)` builds the `Hub`, which has two calls, both answering
 with response items: `dataForPage(page, ctx, options)` for a page load, and

package/docs/roadmap.md

@@ -148,8 +148,8 @@ breaks nothing.
 
 The chrome belongs to no page, so the builder refuses an application query
 named there, and a custom element in the chrome cannot show application
-data.  `lb-url` and `lb-choices` show the pattern from the framework side,
-and an application has no equivalent.
+data.  `lb-url`, `lb-sort` and `lb-filters` show the pattern from the
+framework side, and an application has no equivalent.
 
 A chrome-level query set on `createHub` would close this, and it is additive.
 It takes its place in the [options on `createHub`](#options-on-createhub).

package/docs/testing.md

@@ -172,8 +172,8 @@ watch, and surviving a failed build.
   that refreshes its own `rows` query are refused
 - an update or delete for several rows runs once per key, lays the patches
   together, and refreshes once
-- `onPageEnter` may return `url()` or `choices()`, and `onChoices` hears
-  every choice the user makes
+- `onPageEnter` may return `url()`, `sort()` or `filters()`, and
+  `onChoices` hears every order and filter the user makes
 - a refusal carries a message, columns or both, and passes through the
   engine untouched
 
@@ -210,11 +210,12 @@ evidence here.
   is not counted
 - the order and the filter place all rows and a patch alike, except where
   the list's `lb-manual` leaves a side to the user, which keeps its rows
-  standing and stamped until they are placed again, and every change
+  standing and stamped until they are placed again; groups come and go with
+  their rows to any depth, aggregates follow every landing, and every change
   leaves a stamp a stylesheet can see (`lb-order.test.ts`)
 - a filter's text reads and passes values as documented, and a choice of
   order or filter places the rows already landed again, hiding rows and
-  leaving them out of counts (`lb-choices.test.ts`)
+  groups and leaving them out of counts and aggregates (`lb-choices.test.ts`)
 - `lb-show` moves an element into a template and back, and landing reaches
   inside it
 - a row whose values arrive as it already shows them is not filled again,
@@ -275,8 +276,9 @@ What the hub is tested for here:
   deadline, under mocked timers, and fails the way any round trip fails
 - a successful insert gathered from a form resets the form, unless the
   answer landed the new row on it
-- a path with no page reports, lands `lb-page-unknown`, and opens the
-  `lb-url-unknown` dialog; two pages for one stub report and take the first
+- a path naming a page that does not exist reports, lands `lb-page-label`
+  as null, and opens the `lb-url-unknown` dialog; two pages for one stub
+  report and take the first
 - `lb-url` lands with the path, the page's `lb-page-title` or stub as
   `lb-page-label`, and a column per query parm, and sets the document title
 - `lb-url-link` pushes state and swaps the page on a plain primary click,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@loadbare/app",
   "description": "High performance web app framework for server-bound applications",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "type": "module",
   "files": [
     "dist",