@loadbare/app 0.16.0 → 0.17.0

package/package.json

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

package/skills/loadbare-app/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: loadbare-app
-description: Build server-bound web applications with Loadbare/app. Covers the file conventions the builder finds by name (`chrome.html`, `*.page.html`, `*.queries.ts`, `*.requests.ts`, `imports.ts`, `<tag>.html`, `<tag>.browser.ts`); the `lb-*` attribute vocabulary that lands query rows on HTML and issues requests (`lb-query`, `lb-column`, `lb-show`, `lb-request`); queries declared with `row(key, run)` and `rows(key, run)`; the URL as the hub's own query `lb-url`, with `lb-url-link`, `lb-url-push` and `lb-url-unknown`; one form pointed at a row by the `--lb-edit`, `--lb-new` and `--lb-release` commands; build-time expansion with `exp-*` parameters, `lb-exp-slot` and `lb-exp-template`; custom elements as form-associated controls and row hosts; the Express wiring with `hubRoutes`; and the `@loadbare/widgets` library. Use whenever a task involves `@loadbare/app`, `@loadbare/widgets`, `loadbare-app-build`, an `lb-` attribute, or a page, query, request or custom element file in a Loadbare application. The model is not React, htmx or REST, and cannot be inferred from them.
+description: Build server-bound web applications with Loadbare/app. Covers the file conventions the builder finds by name (`chrome.html`, `*.page.html`, `*.queries.ts`, `*.requests.ts`, `imports.ts`, `<tag>.html`, `<tag>.browser.ts`); the `lb-*` attribute vocabulary that lands query rows on HTML and issues requests (`lb-query`, `lb-column`, `lb-show`, `lb-request`); queries declared with `row(key, run)` and `rows(key, run)`; the URL as the hub's own query `lb-url`, with `lb-url-link`, `lb-url-push` and `lb-url-unknown`; the user's order and filters as the hub's query `lb-choices`, read by `lb-order` and `lb-filter`; one form pointed at a row by the `--lb-edit`, `--lb-new` and `--lb-release` commands; build-time expansion with `exp-*` parameters, `lb-exp-slot` and `lb-exp-template`; custom elements as form-associated controls and row hosts; the Express wiring with `hubRoutes`; and the `@loadbare/widgets` library. Use whenever a task involves `@loadbare/app`, `@loadbare/widgets`, `loadbare-app-build`, an `lb-` attribute, or a page, query, request or custom element file in a Loadbare application. The model is not React, htmx or REST, and cannot be inferred from them.
 license: Apache-2.0
 metadata:
   package: "@loadbare/app"
@@ -189,11 +189,23 @@ in.
 **A `rows` query declares its order, and the hub places every row by it.**
 `rows("id", run, { order: "category_order,name" })`; a column after `-` sorts
 descending, and values compare by JSON type, so a numeric sort column is a
-JSON number.  The parm `lb-order-<query>` replaces the order, and a control
-writing it inside `lb-query="lb-url"` re-sorts with no round trip.  A query
-that pages or limits reads the parm itself and declares
-`serverSortedByUrl: true`.  Never sort in a widget, and never send a
-placeholder row to hold a place.
+JSON number or is declared one: `types: { amount: "number" }` beside
+`order`.  Never sort in a widget, and never send a placeholder row to
+hold a place.
+
+**The user's order and filters are choices, not query parms.**  The hub
+serves a second query, `lb-choices`, keyed by `lb-path`, one column per
+choice, named by the application.  A control inside
+`lb-query="lb-choices"` with `lb-request="lb-row-update"` makes a choice.
+`lb-order="<choice>"` on the element carrying `lb-query` places its rows by
+the order that choice holds, in place of the server's while it is not
+empty.  `lb-filter="col, col"` there hides each row that does not pass the
+choice of the same name: `^=Amazon`, `>=2026-01-01 <=2026-03-31`, or plain
+text for contains.  A choice shows with no round trip, then the server's
+`onChoices(ctx, choices)` hears every choice, to keep them;
+`onPageEnter` returns `choices()` to restore them.  Choices hold until the
+page changes.  A filter that decides which rows the server sends is a query
+parm.
 
 **Groups are templates.**  A `<template lb-group>` holds a heading and one
 nested `<template>`, the next level or the row template; the nth breaks on
@@ -201,11 +213,12 @@ the order's nth term, to any depth.  Contents land before the nested
 template, so put it inside the heading's element for a container and beside
 the heading for a heading row.  `<tbody>` and `<optgroup>` do not nest.  The
 heading is filled from the group's first row.  `lb-count`, `lb-sum="col"`,
-`lb-avg`, `lb-min` and `lb-max` total the nearest group, or the whole list
-outside any.
+`lb-avg`, `lb-min` and `lb-max` total the rows showing in the nearest group,
+or in the whole list outside any.
 
 **Animate with CSS.**  The hub stamps `lb-row-created`, `lb-row-changed`,
-`lb-row-moved`, and `lb-row-requested` for this page's request, and marks a
+`lb-row-moved` (its values changed and it now stands elsewhere), and
+`lb-row-requested` for this page's request, and marks a
 leaving row or group `lb-row-leaving` or `lb-group-leaving`, removing it once
 its animations end.  Scrolling to a row is script, in `lbRowsLanded`.
 
@@ -329,7 +342,7 @@ layer between the page and its queries.
 the element sits.
 
 **The query string is what the page has on screen.**  Which record a page
-shows, a filter, a date range: each is a query parm,
+shows, a filter the server applies, a date range: each is a query parm,
 `/accounts?acct=23&from=2026-09-09`, so a reload, a bookmark or a mailed link
 shows the same thing.  The hub serves the query `lb-url`, of kind `row`,
 keyed by `lb-path`, with `lb-page-label`, `lb-page-unknown`, and one column
@@ -371,9 +384,9 @@ whole data channel.
 
 **The developer writes `lb-*` attributes in markup, and script never
 assigns them.**  The builder refuses any `lb-` attribute other than
-`lb-query`, `lb-column`, `lb-show`, `lb-request`, `lb-url-link`,
-`lb-url-push` and `lb-url-unknown`.  Everything else with the prefix is a
-stamp the hub or the builder writes.
+`lb-query`, `lb-column`, `lb-show`, `lb-order`, `lb-filter`, `lb-request`,
+`lb-url-link`, `lb-url-push` and `lb-url-unknown`.  Everything else with the
+prefix is a stamp the hub or the builder writes.
 
 **`lb-` belongs to Loadbare.**  The application should never name anything
 with the `lb-` prefix anywhere: no attribute, query, column, request, custom
@@ -463,8 +476,8 @@ with the package, so no network is needed.
   gathering, requests, conditions and request state.  Start here for
   anything in a page.
 - [`references/page-files.md`](references/page-files.md) — what page
-  files are, queries, `onPageEnter`, handlers, `crud`, refresh and patch,
-  and `url()`.
+  files are, queries, `onPageEnter`, `onChoices`, handlers, `crud`, refresh
+  and patch, `url()` and `choices()`.
 - [`references/custom-elements.md`](references/custom-elements.md) —
   expansion, parameters, slots, destinations, and custom element code and
   when it runs.

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

@@ -22,9 +22,13 @@ 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.
+Three places read a value's type today.  The [order](#order) compares
+values by their JSON type, a [filter](#filters) reads its value as the
+column's type, and an [aggregate](#aggregates) reads a sum or an average
+from a JSON number or a string holding a plain decimal.  A `rows` query may
+declare a column's type, which the order, a filter, `lb-min` and `lb-max`
+read the column as in place of its JSON type.  No declared type changes how
+a value renders.
 
 We will then see if a useful solution emerges that Loadbare/app should
 handle.
@@ -404,7 +408,7 @@ query.
 | `lb-column-value`    | The value it set                 |
 | `lb-key-value`       | The row's key                    |
 | `lb-row-live`        | Nothing; it marks a live row     |
-| `lb-query-row-count` | The number of live rows it holds |
+| `lb-query-row-count` | The number of live rows it shows |
 
 The markup names a query and the columns it shows.  The kind and the key are
 the server's, and the markup states neither.
@@ -441,7 +445,8 @@ element is a control.
 Name one query on more than one element to show it in more than one place.
 Every one of them receives it.
 
-A query that arrives with nowhere to land is reported to the console.
+A query that arrives with nowhere to land is reported to the console,
+unless its name begins with `lb-`.
 
 #### How a column lands
 
@@ -518,7 +523,8 @@ 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
+the number of live rows it shows.  A row a [filter](#filters) hides is not
+counted.  The server answers with rows and says
 nothing about how many survived, so this is the one fact a page cannot be
 sent.  It makes an empty query a stylesheet rule:
 
@@ -530,10 +536,15 @@ sent.  It makes an empty query a stylesheet rule:
 
 A row missing its key column is reported to the console and not landed.
 
+When the focus is in a live row that placing moves, the hub puts it back on
+the same element and scrolls it into view.  When that row leaves, or a
+filter hides it, the focus goes to the first element the user can operate
+in the first row showing.
+
 #### 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:
+with the query, and the user may choose another:
 
 ```ts
 accounts: rows("id", (ctx) => ctx.db.accounts(), {
@@ -542,9 +553,10 @@ accounts: rows("id", (ctx) => ctx.db.accounts(), {
 ```
 
 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.
+descending.  `lb-order`, on the element carrying `lb-query`, names a column
+of [`lb-choices`](#choices) holding the user's order, and while that column
+is not empty it replaces the declared order.  With neither, rows show in the
+order the server sent them, and a patch's new rows go last.
 
 | Values               | Compare                                    |
 | -------------------- | ------------------------------------------ |
@@ -555,27 +567,75 @@ show in the order the server sent them, and a patch's new rows go last.
 | `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.
+numerically arrives as a JSON number, or its query declares its type.
+`types` names a type for any of a `rows` query's columns, one of `number`,
+`boolean` and `text`, and the column compares read as that type whatever
+JSON type its values arrive as:
+
+```ts
+accounts: rows("id", (ctx) => ctx.db.accounts(), {
+  order: "-balance",
+  types: { balance: "number" },
+}),
+```
+
+A value that is no value of its declared type compares as `null` does.
+`createHub` refuses at startup a type it does not know.
+
+The declared order and types travel once, on the answer that loads the
+page, and the hub keeps them with the query's answer for every answer after
+it, all rows or a patch.  `readAs` in
+`@loadbare/app/types` is the rule the hub applies.
+
+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:
+The hub sorts the rows it has, so a choice of order places them again with
+no round trip:
 
 ```html
-<div lb-query="lb-url">
-  <select lb-column="lb-order-accounts" lb-request="lb-row-update">
+<div lb-query="lb-choices">
+  <select lb-column="accounts_order" lb-request="lb-row-update">
     <option value="">By category</option>
     <option value="account_name">By name</option>
   </select>
 </div>
+
+<table lb-query="accounts" lb-order="accounts_order">
+  ...
+</table>
+```
+
+#### Filters
+
+`lb-filter`, on the element carrying `lb-query`, names the columns of its
+rows a choice may filter, separated by commas.  The column of
+[`lb-choices`](#choices) of the same name holds the filter.  A row that does
+not pass every filter is `hidden`, and a ticked `lb-select` in it is
+cleared.  A group whose rows are all hidden is hidden.  An empty choice
+filters nothing.
+
+```html
+<table lb-query="accounts" lb-filter="account_name, balance">
 ```
 
-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.
+A filter is terms, each an operator and a value.  A term begins wherever
+whitespace comes before an operator, so a value may hold spaces.  Text with
+no operator is `*=`.  A term with no value is left out.  Every term must
+pass: `>=2026-01-01 <=2026-03-31`.
+
+| Operator                   | Compares                                          |
+| -------------------------- | ------------------------------------------------- |
+| `^=`, `$=`, `*=`           | As text, ignoring case: begins with, ends with, contains |
+| `=`, `!=`, `<`, `<=`, `>`, `>=` | As the [order](#order) compares, with the value read as the column's type |
+
+The column's type is its declared [type](#order), if its query declares
+one.  Otherwise it is a number for a JSON number, `true` or `false` for a
+boolean, and text otherwise.  A value that is not of the column's type, and
+a column that is null or missing, pass only `!=`.
+
+`parseFilter`, `passes` and `passesTerm` in `@loadbare/app/types` are the
+rule the hub applies.
 
 #### Groups
 
@@ -617,8 +677,8 @@ filled, so it shows any column of the row.  The example breaks on
 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.
+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
@@ -648,7 +708,8 @@ 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
+An aggregate covers the rows showing, so a row a [filter](#filters) hides
+is left out.  Where the true total
 matters beyond what the page shows, it is a row the server answers.
 
 #### What happened to a row
@@ -660,7 +721,7 @@ application animates with CSS alone and the hub starts no animation.
 | ------------------ | -------------------- | -------------------------------------------------- |
 | `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-moved`     | A live row           | Its values changed, and it now stands elsewhere    |
 | `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                                   |
@@ -674,8 +735,12 @@ 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.
+row leaves when all rows arrive without its key, or a patch drops it.
+
+A row is moved when its values changed and the nearest rows whose values did
+not change, before and after it, are not the ones it stood between.  A row
+it passed is not stamped, and a change of the user's order, which changes no
+values, stamps none.  A moved row stays live and moves.
 
 ```css
 [lb-row-created] { animation: arrive 200ms; }
@@ -1341,10 +1406,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).  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.
+[The Express server](#the-express-server).  Loadbare assigns no parm a
+meaning: a column of `lb-url` whose name begins with `lb-` is never a query
+parm.  An order or a filter the hub applies to rows already on the page is
+a [choice](#choices), not a parm.
 
 #### An unknown page
 
@@ -1409,8 +1474,8 @@ rowInsert: {
   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
+anything shows, as an application restoring the parms 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
@@ -1428,12 +1493,51 @@ onPageEnter: async (ctx) => {
 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.
+change of the URL and issues it.
 
 The page is loaded with a second context, built by `contextFor` from the new
 parms — see [The Express server](#the-express-server).
 
+### Choices
+
+The hub serves the query `lb-choices`, of kind `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.  It lands wherever an element names it, like any server query.
+
+A control inside `lb-query="lb-choices"` that sends `lb-row-update` makes a
+choice.  A request with `lb-row-update` for `lb-choices` or `lb-url` from
+anywhere on the page is keyed by the path, so a custom element may
+dispatch one without sitting inside the query.
+
+A choice joins the ones already made, and needs no round trip to show:
+every element whose `lb-order` or `lb-filter` reads a column that changed
+lands its query's last answer again, so it shows what a round trip carrying
+the choice would.  Then the hub sends `lb-row-update` for `lb-choices`,
+keyed by the path, with every choice made on the page as `values`, and no
+element pending.  The server runs the page's `onChoices` with them, when it
+has one, and otherwise answers nothing.  Whatever `onChoices` returns lands,
+and by convention it returns nothing.
+
+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.  `onPageEnter` restores them by returning `choices()`, alone or
+spread beside `url()`:
+
+```ts
+onPageEnter: async (ctx) => {
+  const saved = await ctx.db.savedChoices("accounts");
+  if (saved) return choices(saved);
+},
+onChoices: (ctx, chosen) => ctx.db.saveChoices("accounts", chosen),
+```
+
+The page load then answers the `lb-choices` item first, then the queries.
+When `url()` moves the page, the choices arrive with the load at the new
+URL.  A
+`choices()` naming no column, or holding a value that is not a string, is
+reported on the server console and ignored, as for `url()`.
+
 ### The markup checks
 
 The builder checks the chrome and every page, after expansion, and refuses
@@ -1441,8 +1545,8 @@ to build on any of these:
 
 - An `lb-` attribute that is not a developer attribute: `lb-query`,
   `lb-column`, `lb-show`, `lb-group`, `lb-count`, `lb-sum`, `lb-avg`,
-  `lb-min`, `lb-max`, `lb-request`, `lb-select`, `lb-url-link`,
-  `lb-url-push`, `lb-url-unknown`.  Every other `lb-` attribute is a stamp.
+  `lb-min`, `lb-max`, `lb-order`, `lb-filter`, `lb-request`, `lb-select`,
+  `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.
 - `lb-request` naming a value that begins with `lb-` and is not one of the
@@ -1454,6 +1558,8 @@ 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-order` or `lb-filter` on an element not carrying `lb-query`, or naming
+  no column.
 - `lb-select` on anything but an `<input type="checkbox">`, outside a row
   template, or beside `lb-column` or `lb-request`.
 - A `command` beginning `--lb-` that is not one of the three
@@ -1718,13 +1824,14 @@ as explained in the next section.
 ### Page Requests
 
 `<stub>.requests.ts` exports one object named `requests`, typed `Requests`.
-It has three optional keys.
+It has four optional keys.
 
 | Key           | Keyed by              | Answers                                            |
 | ------------- | --------------------- | -------------------------------------------------- |
 | `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, and may move the URL |
+| `onPageEnter` | Nothing               | Runs once on entering the page, before its queries, and may move the URL or restore [choices](#choices) |
+| `onChoices`   | Nothing               | Runs with every choice made on the page, each time the user makes one |
 
 The server resolves a declared request against `handlers`, and a request
 Loadbare provides against `crud` under the request's query.  A name with no
@@ -1840,8 +1947,10 @@ 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.
+A `rows` item also carries `order` when the query declares one.
+
+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](#choices).
 
 `createHub(pages)` builds the `Hub`, which has two calls, both answering
 with response items: `dataForPage(page, ctx, options)` for a page load, and
@@ -1926,7 +2035,7 @@ calls four optional methods, which the `HubLifecycle` interface in
 | Removes it: a row or group done leaving, the page replaced | `lbDetached()`, once  |
 | Moves a live row the order put elsewhere         | Nothing                         |
 | Turns `lb-show` off or on                        | Nothing                         |
-| Leaves a copy of a moved row behind              | Nothing, on the copy            |
+| Hides a row or a group for a filter              | Nothing                         |
 
 The chrome and a page are placed as the page's first answer lands, or once
 that round trip fails.  An element under an `lb-show` that is off is placed
@@ -2062,6 +2171,8 @@ it may define tomorrow.
 | `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-order`        | Developer     | An element with `lb-query`          | [Order](#order)                               |
+| `lb-filter`       | Developer     | An element with `lb-query`          | [Filters](#filters)                           |
 | `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)     |
@@ -2088,12 +2199,12 @@ The builder refuses any other `lb-` attribute in markup — see
 | Query    | Kind  | Key       | Columns                                                         | Defined in          |
 | -------- | ----- | --------- | --------------------------------------------------------------- | ------------------- |
 | `lb-url` | `row` | `lb-path` | `lb-path`, `lb-page-label`, `lb-page-unknown`, every query parm | [The URL](#the-url) |
+| `lb-choices` | `row` | `lb-path` | `lb-path`, every choice                                     | [Choices](#choices) |
 
 ### Reserved query parms
 
-| Parm               | Means                       | Defined in      |
-| ------------------ | --------------------------- | --------------- |
-| `lb-order-<query>` | The user's order for a query | [Order](#order) |
+None.  A column of `lb-url` whose name begins with `lb-` is never a query
+parm — see [Query parms](#query-parms).
 
 ### Reserved request names
 
@@ -2164,8 +2275,11 @@ imports them rather than writing a string.
 | `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 |
+| `CHOICES_QUERY`           | `lb-choices`                            |
+| `ATTR_ORDER`              | `lb-order`                              |
+| `ATTR_FILTER`             | `lb-filter`                             |
+| `FILTER_OPERATORS`        | Every filter operator, the longer first |
 | `ATTR_ROW_CREATED`        | `lb-row-created`                        |
 | `ATTR_ROW_CHANGED`        | `lb-row-changed`                        |
 | `ATTR_ROW_MOVED`          | `lb-row-moved`                          |
@@ -2191,7 +2305,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 sixteen 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

@@ -109,8 +109,9 @@ page file carries; see [page files](./page-files.md#the-page-title). The hub
 sets the document title to `lb-page-label` whenever it is not null, so the
 tab and the browser history show the page.
 
-`lb-url` is the one query a page may use that the server does not declare. A
-page names it the same way, anywhere inside the hub.
+`lb-url` is one of two queries a page may use that the server does not
+declare. The other is [`lb-choices`](./data-binding.md#choices). A page
+names either the same way, anywhere inside the hub.
 
 ### Where focus starts
 
@@ -169,14 +170,16 @@ 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. 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.
+back keep their place.
 
 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
 and after Back alike.
 
+An order or a filter the hub applies to rows the page already holds is not
+a query parm. It is a [choice](./data-binding.md#choices), which holds until
+the page changes.
+
 The hub sends the query parms with every round trip, and the server hands
 them to `contextFor`; see [the Express server](./server.md#database-layer).
 A handler moves the URL by returning `url()`, when only the server knows the

package/skills/loadbare-app/references/custom-elements.md

@@ -271,6 +271,7 @@ one as a string literal:
 | `LB_DONE_EVENT_NAME`   | `lb-request-done`, the event that says how it turned out |
 | `SHOW_NOT`             | `!`, written before a column in `lb-show` |
 | `URL_QUERY`            | `lb-url`             |
+| `CHOICES_QUERY`        | `lb-choices`         |
 | `URL_COLUMN_PATH`, `URL_COLUMN_PAGE_LABEL`, `URL_COLUMN_PAGE_UNKNOWN` | `lb-path`, `lb-page-label`, `lb-page-unknown` |
 | `LB_RESERVED_PREFIX`   | `lb-`                |
 
@@ -356,9 +357,8 @@ inside it, and `lbDetached` on the inner ones first. A table that sets the
 `form` attribute on its controls in `lbAttached` does so before each control
 hears its own.
 
-An element a script creates hears none of the four, and neither does the
-copy of a moved row the hub leaves behind while it fades. The hub calls
-them only on what it places.
+An element a script creates hears none of the four. The hub calls them only
+on what it places.
 
 Never write `connectedCallback`, `disconnectedCallback`, `adoptedCallback`
 or `connectedMoveCallback`. The browser calls those on every move, and the
@@ -589,6 +589,22 @@ missing a field its name needs, and stamps the dispatching element with
 
 Let the event bubble, so an ancestor can stop it before the hub sends it.
 
+A request with `lb-row-update` for `lb-url` or `lb-choices` is keyed by the
+path, so an element anywhere on the page may set a query parm or make a
+[choice](./data-binding.md#choices) without sitting inside the query:
+
+```ts
+import { CHOICES_QUERY, LB_EVENT_NAME, REQUEST_ROW_UPDATE } from "@loadbare/app/constants";
+import type { HubRequest } from "@loadbare/app/types";
+
+const detail: HubRequest = {
+  name: REQUEST_ROW_UPDATE,
+  query: CHOICES_QUERY,
+  values: { ledger_order: "-amount" },
+};
+this.dispatchEvent(new CustomEvent(LB_EVENT_NAME, { bubbles: true, detail }));
+```
+
 ### Hearing how it turned out
 
 Once what a request brought back has landed, or its round trip has failed,
@@ -617,7 +633,8 @@ listener. Import its name as `LB_DONE_EVENT_NAME`.
 `items` is every response item that landed because of the request, in
 order. `refusal` is set beside `error` when the handler refused the
 request, holding its `message` and `columns`. An answer that moved the URL contributes its `lb-url` item, which
-carries a key only the server knew, and the page load. `error` is set when
+carries a key only the server knew, and the page load. A choice contributes
+the row of `lb-choices` it made. `error` is set when
 the round trip failed, and then nothing landed. A new row's key is in the
 answer only when the handler returned it in a patch: a refresh sends all
 rows, and nothing marks which one is new.
@@ -660,11 +677,12 @@ Everything else is the hub's:
 |-------------|----------------------------------------------------------|
 | Cloning     | Clones the row template once per new key                 |
 | Matching    | Fills the live row already showing that key, when its values changed |
-| 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 |
+| Placing     | Places every live row by the user's order or the query's |
+| Filtering   | Hides a row the user's filter does not pass, and a group whose rows are all hidden |
+| Grouping    | Builds a group where the order breaks, keeps it while its run goes on, 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 |
+| Counting    | Stamps `lb-query-row-count` with the number of live rows showing |
 
 `lb-options.browser.ts` and `lb-table.browser.ts` in
 [`@loadbare/widgets`](./widgets.md) are two uses of `lbRowsLanded`: one