@loadbare/app 0.23.0 → 0.24.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
-seventeen `lb-` attributes. The server declares every query a page may show and
+eighteen `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`,
@@ -67,10 +67,10 @@ builder writes a stamp, and a stylesheet or a custom element reads it.
 | `lb-key-value`       | The key of a live row, or of a `row` landed on an element |
 | `lb-row-live`        | The element is a live row                          |
 | `lb-query-row-count` | The number of live rows an element shows           |
-| `lb-query-unsorted-count` | The number of them out of order; see [Rows the user is working in](#rows-the-user-is-working-in) |
+| `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-unsorted` | What happened to a row; see [What happened to a row](#what-happened-to-a-row) |
+| `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`, `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-row-selected`    | A row whose `lb-select` is ticked                  |
@@ -146,6 +146,7 @@ no row fills.
 | `<input>`, `<select>`, `<textarea>`                  | Its `value`, and `lb-column-value`      |
 | `<input type="checkbox">`                            | Its `checked`, and `lb-column-value`    |
 | `<input type="radio">`                               | Its `checked`, and `lb-column-value`    |
+| `<select multiple>`                                  | Its selected options, and `lb-column-value` |
 | A form-associated custom element with `value`        | Its `value`, and `lb-column-value`      |
 | Any other custom element                             | `lb-column-value` only                  |
 | Any other element                                    | Its text content, and `lb-column-value` |
@@ -186,8 +187,9 @@ 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
 checkbox is unchecked. Unchecked sends `"false"` rather than nothing, so a
-flag can be set back. The checkbox's `value` attribute means nothing to the
-hub.
+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
+[Several values](./chrome.md#several-values).
 
 ### Radio buttons
 
@@ -228,9 +230,9 @@ places it immediately before the template:
 The hub matches each row to a live row by its key. All rows decide
 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 live rows by the query's order, except that an edit from inside the
-list leaves them where they stand; see [Order](#order) and
-[Rows the user is working in](#rows-the-user-is-working-in). A row that
+places live rows by the query's order, except where the list's `lb-manual`
+leaves them where they stand; see [Order](#order) and
+[Placing by hand](#placing-by-hand). A row that
 does not pass the user's filter is `hidden`; see [Filters](#filters).
 
 A live row whose values arrive as it already shows them is not filled
@@ -310,41 +312,50 @@ Rows that compare equal keep the order they arrived in, a patch's new rows
 after the rows already showing. A row moves only when the order
 puts it somewhere else, so all rows landing again unchanged move nothing.
 
-### Rows the user is working in
-
-A landing that answers a request sent from inside a list moves none of that
-list's rows. The request is from inside the list when the list is the
-nearest element carrying `lb-query` around the element that sent it: a
-control in a live row, or a ghost row. A form that
-[`--lb-edit`](#editing-a-row-in-one-form) pointed at a live row finishes an
-edit begun in that row, so its request is from inside the row's list,
-wherever the form sits. Any other form elsewhere on the page is not inside
-the list. A user who changes a value sees the value change, and the row
-stays where they were working:
-
-| The answer                               | The row                                           |
-|------------------------------------------|---------------------------------------------------|
-| Changes a column the order reads         | Stays where it stands                             |
-| Creates a row                            | Goes after the last row of its group, or last of all |
-| Drops a row                              | Leaves                                            |
-| Changes a row so the filter hides it     | Stays showing                                     |
-| Changes the column its group breaks on   | Stays under its group's heading                   |
-
-A patch and all rows answering the same edit land the same way. A row left
-where the order or the filter would not leave it is stamped
-`lb-row-unsorted`, and the element carrying `lb-query` carries
-`lb-query-unsorted-count`, the number of such rows. Another element naming
-the same query places its rows by the order: the user was not working
-there.
-
-The rows are placed by the order again, and every `lb-row-unsorted` is
-cleared, when the user asks: when the page loads, when the user's order or
-filter changes, or on `--lb-sort`. A button names the list with HTML's
+### Placing by hand
+
+By default the hub places a list's rows by the order and the filter on
+every landing. Write `lb-manual` on the element carrying `lb-query` to leave
+one side or both to the user, so rows do not jump about or vanish while the
+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-filter="description, is_unmatched" lb-manual="order filter">
+```
+
+A landing that answers a request leaves alone each side the list names,
+wherever the request was sent from: a control in a live row, a ghost row, a
+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 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                         |          |
+
+A side not named is placed on every landing. A list that names only
+`filter` moves an edited row into the order and keeps it showing; one that
+names only `order` leaves it where it stands and hides it once the filter
+says so.
+
+A patch and all rows answering the same edit land the same way. A showing
+row left where the order or the filter would not leave it is stamped
+`lb-row-unplaced`, and the element carrying `lb-query` carries
+`lb-query-unplaced-count`, the number of such rows. One stamp covers both
+sides. Each element naming the query places by its own `lb-manual`.
+
+The rows are placed by the order and the filter again, and every
+`lb-row-unplaced` is cleared, when the page loads, when the user's order or
+filter changes, or on `--lb-place`. A button names the list with HTML's
 `commandfor`, and a stylesheet shows it only while it has something to do:
 
 ```html
-<div id="roster" lb-query="roster">
-  <button type="button" class="resort" commandfor="roster" command="--lb-sort">Re-sort</button>
+<div id="roster" lb-query="roster" lb-manual="order">
+  <button type="button" class="place" commandfor="roster" command="--lb-place">Re-sort</button>
   <ul>
     <template><li><input lb-column="name" lb-request="lb-row-update" /></li></template>
   </ul>
@@ -352,19 +363,19 @@ filter changes, or on `--lb-sort`. A button names the list with HTML's
 ```
 
 ```css
-.resort {
+.place {
   display: none;
 }
-[lb-query-unsorted-count]:not([lb-query-unsorted-count="0"]) .resort {
+[lb-query-unplaced-count]:not([lb-query-unplaced-count="0"]) .place {
   display: revert;
 }
 ```
 
-`--lb-sort` places the rows the hub holds, with no round trip. Aimed at an
+`--lb-place` places the rows the hub holds, with no round trip. Aimed at an
 element that carries no `lb-query`, or shows no rows the hub holds, it is
 reported to the console. A custom element that reorders rows by a request of
 its own dispatches the same command on the list once the answer lands, with
-`new CommandEvent("command", { command: "--lb-sort" })`: the user asked for
+`new CommandEvent("command", { command: "--lb-place" })`: the user asked for
 the move.
 
 ### Filters
@@ -384,9 +395,9 @@ its rows the user may filter, separated by commas. The column of
 ```
 
 A row that does not pass every filter is `hidden`, and a ticked `lb-select`
-in it is cleared. A row an edit from inside the list changed stays showing
-until the rows are placed again; see
-[Rows the user is working in](#rows-the-user-is-working-in). A group whose rows are all hidden is hidden too
+in it is cleared. Under `lb-manual="filter"`, a row an answer changed stays
+showing until the rows are placed again; see
+[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.
 
@@ -469,7 +480,7 @@ 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. A row an edit from inside the list
+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
@@ -520,7 +531,7 @@ Every change to a list is one a stylesheet can see:
 | `lb-row-changed`   | Its values changed when the hub last touched it        |
 | `lb-row-moved`     | Its values changed, and it now stands elsewhere        |
 | `lb-row-requested` | `created`, `changed` or `moved` by this page's request |
-| `lb-row-unsorted`  | Stands where the order would not put it                |
+| `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                                 |
 
@@ -529,9 +540,9 @@ The hub touches a row when an answer names it. `lb-row-created`,
 applied again is removed and added as two changes, so an animation keyed to
 it plays again. `lb-row-requested` is cleared at every landing of the row's
 query, and set only by a landing that answers a request from the page.
-`lb-row-unsorted` is a state, not an event: it stays until the rows are
-placed by the order; see
-[Rows the user is working in](#rows-the-user-is-working-in).
+`lb-row-unplaced` is a state, not an event: it stays until the rows are
+placed again; see
+[Placing by hand](#placing-by-hand).
 
 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`
@@ -580,9 +591,9 @@ insert form above: it sits inside `lb-query="roster"` so its request is for
 
 The hub stamps every element that holds a row template with
 `lb-query-row-count`, the number of live rows it shows. A row a filter
-hides is not counted. Beside it, `lb-query-unsorted-count` is the number of
-rows out of order; see
-[Rows the user is working in](#rows-the-user-is-working-in). An empty query is a stylesheet rule:
+hides is not counted. Beside it, `lb-query-unplaced-count` is the number of
+rows out of place; see
+[Placing by hand](#placing-by-hand). An empty query is a stylesheet rule:
 
 ```html
 <div lb-query="roster">
@@ -793,6 +804,10 @@ carrying `lb-request`:
 3. The element is in a live row: every control in that live row.
 4. Otherwise: every control whose form owner is the element's form owner.
 
+A control that holds several values, a `<select multiple>` or a set of
+checkboxes carrying `value`, gathers an array of strings; see
+[Several values](./chrome.md#several-values).
+
 The hub gathers from controls only, and skips a control that belongs to a
 query nested inside the group, except that a form gathers the rows of a
 query nested in its own; see [A form over a set of rows](#a-form-over-a-set-of-rows).
@@ -1044,11 +1059,9 @@ An `lb-show` in the form reads from the row it was pointed at. With no row,
 every column is null, so `lb-show="!id"` shows only while entering a new
 row.
 
-A request from a form Edit pointed is sent from inside the row's list, so
-the row stays where the user was working, even when the filter would now
-hide it or the order would move it; see
-[Rows the user is working in](#rows-the-user-is-working-in). A form New
-pointed is not inside any list, and its rows are placed by the order.
+The rows a form's answer lands are placed by the list's `lb-manual`, as any
+answer's are, whether the form was pointed by Edit or by New; see
+[Placing by hand](#placing-by-hand).
 
 A successful request from the form lets it go, as Cancel does: the form
 empties, its controls return to their defaults, and the stamps go. A failed
@@ -1324,7 +1337,7 @@ 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 seventeen the developer writes;
+- an `lb-` attribute that is not one of the eighteen 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
@@ -1341,12 +1354,17 @@ expansion, and refuses to build:
   column, naming columns not separated by commas or one beginning `lb-`, or
   with no row around it
 - `lb-url-push` on an element without `lb-request`
+- `lb-column` on an element carrying `multiple`, or on a checkbox carrying
+  `value`, with any query but `lb-url` around it: only a query parm holds
+  several values
 - `lb-url-unknown` on anything but a `<dialog>`, or outside `<lb-hub>`
 - `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-manual` on an element not carrying `lb-query`, or naming anything but
+  `order`, `filter` or both
 - `lb-select` on anything but `<input type="checkbox">`, outside a row
   template, or beside `lb-column` or `lb-request`
 - a `command` beginning `--lb-` that is not one of the four commands

package/docs/reference/names.md

@@ -66,7 +66,7 @@ A widget package declares these.  An application never does.
 
 ## Attributes
 
-The developer writes seventeen attributes in pages and the chrome, and the
+The developer writes eighteen 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
@@ -79,6 +79,7 @@ assigns one.
 | `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-count`, `lb-sum`, `lb-avg`, `lb-min`, `lb-max` | Developer | [Aggregates](./data-binding.md#aggregates)       |
 | `lb-select`          | Developer       | [Selecting rows](./data-binding.md#selecting-rows)               |
@@ -93,7 +94,7 @@ assigns one.
 | `lb-key-value`       | Hub             | [Landing](./data-binding.md#landing), [Editing a row in one form](./data-binding.md#editing-a-row-in-one-form) |
 | `lb-row-live`        | Hub             | [Landing](./data-binding.md#landing)                             |
 | `lb-query-row-count` | Hub             | [Counting rows](./data-binding.md#counting-rows)                 |
-| `lb-query-unsorted-count`, `lb-row-unsorted` | Hub | [Rows the user is working in](./data-binding.md#rows-the-user-is-working-in) |
+| `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) |
@@ -140,7 +141,7 @@ Loadbare/app owns every value of HTML's `command` attribute beginning with
 | `--lb-edit`    | [Editing a row in one form](./data-binding.md#editing-a-row-in-one-form) |
 | `--lb-new`     | [Editing a row in one form](./data-binding.md#editing-a-row-in-one-form) |
 | `--lb-release` | [Editing a row in one form](./data-binding.md#editing-a-row-in-one-form) |
-| `--lb-sort`    | [Rows the user is working in](./data-binding.md#rows-the-user-is-working-in) |
+| `--lb-place`    | [Placing by hand](./data-binding.md#placing-by-hand) |
 
 ## Reserved tags
 
@@ -199,7 +200,7 @@ imports them rather than writing a string.
 | `ATTR_ROW_LIVE`           | `lb-row-live`                           |
 | `LIVE_ROW`                | `[lb-row-live]`, the selector for a live row |
 | `ATTR_QUERY_ROW_COUNT`    | `lb-query-row-count`                    |
-| `ATTR_QUERY_UNSORTED_COUNT` | `lb-query-unsorted-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`                         |
@@ -213,13 +214,15 @@ imports them rather than writing a string.
 | `CHOICES_QUERY`           | `lb-choices`                            |
 | `ATTR_ORDER`              | `lb-order`                              |
 | `ATTR_FILTER`             | `lb-filter`                             |
+| `ATTR_MANUAL`             | `lb-manual`                             |
+| `MANUAL_ORDER`, `MANUAL_FILTER` | `order`, `filter`: the sides `lb-manual` names |
 | `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`                          |
 | `ATTR_ROW_REQUESTED`      | `lb-row-requested`                      |
 | `REQUESTED_CREATED`, `REQUESTED_CHANGED`, `REQUESTED_MOVED` | `created`, `changed`, `moved` |
-| `ATTR_ROW_UNSORTED`       | `lb-row-unsorted`                       |
+| `ATTR_ROW_UNPLACED`       | `lb-row-unplaced`                       |
 | `ATTR_ROW_LEAVING`        | `lb-row-leaving`                        |
 | `ATTR_GROUP_LEAVING`      | `lb-group-leaving`                      |
 | `ATTR_REQUEST`            | `lb-request`                            |
@@ -229,7 +232,7 @@ imports them rather than writing a string.
 | `ATTR_REQUEST_ERROR`      | `lb-request-error`                      |
 | `ATTR_REQUEST_REFUSED`    | `lb-request-refused`                    |
 | `LB_REFUSAL_STATUS`       | `422`                                   |
-| `COMMAND_EDIT`, `COMMAND_NEW`, `COMMAND_RELEASE`, `COMMAND_SORT` | `--lb-edit`, `--lb-new`, `--lb-release`, `--lb-sort` |
+| `COMMAND_EDIT`, `COMMAND_NEW`, `COMMAND_RELEASE`, `COMMAND_PLACE` | `--lb-edit`, `--lb-new`, `--lb-release`, `--lb-place` |
 | `LB_COMMANDS`             | All four commands                       |
 | `LB_COMMAND_PREFIX`       | `--lb-`                                 |
 | `ATTR_ROW_EDITING`        | `lb-row-editing`                        |
@@ -265,7 +268,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 seventeen attributes a developer writes |
+| `DEVELOPER_ATTRIBUTES`    | The eighteen attributes a developer writes |
 | `HUB_TAG_NAME`            | `lb-hub`                                |
 | `LB_ENDPOINT`             | `/lb`                                   |
 | `LB_REQUEST_TIMEOUT_MS`   | `10000`                                 |

package/docs/reference/page-files.md

@@ -382,8 +382,9 @@ one row dropped, one row edited — and leave `refresh` empty. A refreshed
 A change that seems to need a refresh usually has a patch:
 
 - A row whose position changes: the hub places it by the query's
-  [order](./data-binding.md#order), or leaves it where the user is working
-  when the request came from inside its list; a refresh would do the same.
+  [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
@@ -445,7 +446,9 @@ export const requests: Requests = {
 ```
 
 A column other than `lb-path` is a query parm: set, or taken out when its
-value is an empty string. Name at least one column, and give each a string.
+value is an empty string. Name at least one column, and give each a string,
+or an array of strings to repeat the parm; see
+[Several values](./chrome.md#several-values).
 With `lb-path` naming another page, the page is entered with only the parms
 named:
 
@@ -462,7 +465,8 @@ nothing else `run` returned is sent, since both answered for the URL the page
 left. The loaded page reads the new parms through `contextFor`; see
 [the Express server](./server.md#database-layer).
 
-- A `url()` naming no column, or holding a value that is not a string, is
+- A `url()` naming no column, or holding a value that is neither a string
+  nor an array of strings, is
   warned about on the server console and ignored, and the refresh set runs
   as usual.
 - If loading the page fails, the write has still happened. The response

package/docs/testing.md

@@ -208,9 +208,9 @@ evidence here.
 - `lb-query-row-count` counts the rows showing, so all rows and a patch
   ending in the same state report the same number, and a row a filter hides
   is not counted
-- the order places all rows and a patch alike, except where an edit came
-  from inside the list, which leaves its rows standing and stamped until
-  the user asks for the order; groups come and go with
+- 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; 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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@loadbare/app",
   "description": "High performance web app framework for server-bound applications",
-  "version": "0.23.0",
+  "version": "0.24.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-parm`, `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`; whether the page loaded and the server answers as the hub's query `lb-hub`; one form pointed at a row by the `--lb-edit`, `--lb-new` and `--lb-release` commands; re-sorting a list with `--lb-sort`; 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-parm`, `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`; whether the page loaded and the server answers as the hub's query `lb-hub`; one form pointed at a row by the `--lb-edit`, `--lb-new` and `--lb-release` commands; rows that hold still under `lb-manual` and are placed again with `--lb-place`; 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"
@@ -194,11 +194,17 @@ row is filled from the nested query's last answer, whatever order they land
 in.
 
 **A `rows` query declares its order, and the hub places every row by it.**
-An edit sent from inside a list, or from a form `--lb-edit` pointed at one
-of its rows, leaves that list's rows where they stand, stamped `lb-row-unsorted` where out of order, until the page loads, the
-user's order or filter changes, or a button with `commandfor` naming the
-list sends `command="--lb-sort"`, which places them with no round trip;
-show it by `[lb-query-unsorted-count]`.  Never refresh to make rows hold
+It places them by the order and the user's filter on every landing.  A list
+whose rows must hold still while the user works through them carries
+`lb-manual="order"`, `"filter"` or `"order filter"`: an answer to any
+request, from wherever it was sent, then leaves that side alone, so an
+edited row stays where it stands, a new row goes last in its group, and a
+row the filter would hide stays showing.  A row left out of place is
+stamped `lb-row-unplaced` until the page loads, the user's order or filter
+changes, or a button with `commandfor` naming the list sends
+`command="--lb-place"`, which places them with no round trip; show it by
+`[lb-query-unplaced-count]`.  An editable list with a ghost row usually
+wants `lb-manual="order"`.  Never refresh to make rows hold
 still, and never to put them back in order.
 `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
@@ -266,7 +272,8 @@ row.  Anything else gathers its form owner's controls.  A `<form>` cannot
 wrap a `<tr>`, so an insert row in a table puts its controls in a form
 elsewhere with the HTML `form` attribute.  A checkbox is a control: checked
 unless its column is `false`, null, `"false"` or `""`, and gathered as
-`"true"` or `"false"`.
+`"true"` or `"false"`; one carrying `value` is instead one of a set
+holding a repeated query parm.
 A radio button is a control: checked when its `value` is the column's
 value, and the group gathers the one checked, or `""`.  In a row template
 the hub stamps its `name` with the row's key, so each row is its own group.
@@ -284,7 +291,7 @@ in every row.  Write one form naming the set's query, outside every row,
 often in a `<dialog>`, and give it an `id`.  A `type="button"` with
 `commandfor="<id>"` and `command="--lb-edit"` in a live row fills it from
 that row with no round trip; `--lb-new` starts it empty for an insert;
-`--lb-release` lets it go.  (`--lb-sort` is the fourth command, for a list,
+`--lb-release` lets it go.  (`--lb-place` is the fourth command, for a list,
 not a form.)  The form's `lb-key-value` is the row's key, empty
 for a new row, absent when not in use, and a stylesheet shows Save or Save
 new by it.  A successful request from the form, or its dialog closing, lets
@@ -342,7 +349,7 @@ fills a new row from the last one.
 
 **The usual reasons for a refresh each have a patch.**
 - A row whose position changes: the hub places it by the query's order, or
-  holds it where the user is working; a refresh changes neither.
+  holds it where it stands under `lb-manual`; a refresh changes neither.
 - A group that appears or goes: the hub makes it with its first row and
   removes it with its last.
 - A row whose other columns change with the edit: re-read the row and patch
@@ -379,7 +386,11 @@ keyed by `lb-path`, with `lb-page-label`, `lb-page-unknown`, and one column
 per query parm.  A control inside `lb-query="lb-url"` carrying
 `lb-request="lb-row-update"` writes its parm; the hub replaces the history
 entry, or pushes one when the control carries `lb-url-push`, and reloads the
-page's queries with no request to the server.  An `<a lb-url-link>` moves
+page's queries with no request to the server.  A parm the URL repeats,
+`?band=3&band=5`, is one column holding an array of strings: a
+`<select multiple>`, or checkboxes carrying `value` and naming one column,
+write it, `url()` takes an array, and `contextFor` reads it with
+`parms.getAll`.  Only a query parm holds several values.  An `<a lb-url-link>` moves
 to its `href`; inside a row, `lb-url-parm="topic_id"` adds that column of
 the row to the `href` as the parm of the same name, so a link to another
 page narrowed by the row is a link, never a request or script.  Queries still take no arguments: `contextFor(req, parms)`
@@ -416,8 +427,8 @@ whole data channel.
 
 **The developer writes `lb-*` attributes in markup, and script never
 assigns them.**  The builder refuses any `lb-` attribute other than the
-seventeen in [Attributes](references/names.md#attributes): `lb-query`,
-`lb-column`, `lb-show`, `lb-order`, `lb-filter`, `lb-group`, `lb-count`,
+eighteen in [Attributes](references/names.md#attributes): `lb-query`,
+`lb-column`, `lb-show`, `lb-order`, `lb-filter`, `lb-manual`, `lb-group`, `lb-count`,
 `lb-sum`, `lb-avg`, `lb-min`, `lb-max`, `lb-select`, `lb-request`,
 `lb-url-link`, `lb-url-parm`, `lb-url-push` and `lb-url-unknown`.  `lb-exp-slot` and
 `lb-exp-template` are expansion's, and never reach the page.  Everything

package/skills/loadbare-app/references/chrome.md

@@ -238,6 +238,48 @@ and after Back alike
 Loadbare assigns no parm a meaning, and a column of `lb-url` whose name
 begins with `lb-` is never a query parm.
 
+### Several values
+
+A URL may repeat a parm, `/statements?band=3&band=5`, as an HTML form does
+for a `<select multiple>` or for checkboxes sharing a name. That column of
+`lb-url` holds every value, in order, as an array of strings. A parm the URL
+carries once is a string, as it always is. Two controls hold several values:
+
+```html
+<div lb-query="lb-url">
+  <select multiple lb-column="band" lb-request="lb-row-update">
+    <option value="3">Cash</option>
+    <option value="5">Investments</option>
+  </select>
+</div>
+
+<form lb-query="lb-url" lb-request="lb-row-update">
+  <label><input type="checkbox" lb-column="band" value="3" /> Cash</label>
+  <label><input type="checkbox" lb-column="band" value="5" /> Investments</label>
+  <button>Show</button>
+</form>
+```
+
+- A `<select multiple>` selects each option whose `value` is among the
+  column's, and writes the values of the options selected.
+- A checkbox carrying `value` is one of a set naming the column. It is
+  checked when its `value` is among the column's, and the set writes the
+  values of the ones checked. A checkbox without `value` is a flag; see
+  [Checkboxes](./data-binding.md#checkboxes).
+- Writing no value takes the parm out of the URL.
+- Either control carries the values as a JSON array in `lb-column-value`.
+- A control that holds one value, and any other element, shows the first,
+  as `URLSearchParams.get` reads it. A form-associated custom element
+  receives the value as it is, a string or an array, and may give an array
+  back; see [Being a control](./custom-elements.md#being-a-control).
+- A handler's `url()` writes several values as an array of strings, and
+  `contextFor` reads them with `parms.getAll`.
+
+Only a column of `lb-url` holds several values. Every other column holds
+one, so the builder refuses a control holding several anywhere but inside
+`lb-query="lb-url"`, and the server ignores a request that carries several
+for a column of its own.
+
 A query parm is user input. A query still takes no argument from the
 browser, and a parm arrives the way the session cookie does, as part of the
 request the context is built from, but a user who types `?acct=99999`

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

@@ -268,7 +268,7 @@ 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-query-unsorted-count`, `lb-query-order`, `lb-group-*`, `lb-row-*`, `lb-request-pending`, `lb-request-error`, `lb-request-refused` |
+| Hub to element | State that lasts                           | An attribute the hub stamps | `lb-column-value`, `lb-key-value`, `lb-query-row-count`, `lb-query-unplaced-count`, `lb-query-order`, `lb-group-*`, `lb-row-*`, `lb-request-pending`, `lb-request-error`, `lb-request-refused` |
 | Hub to element | State the platform already names           | A property                  | A control's `value` |
 | Hub to element | What the hub did                           | An optional `lb` method     | `lbAttached`, `lbRowsLanded`, `lbRequestDone`, `lbDetached` |
 | Hub to element | A moment an element started                | A bubbling event            | `lb-request-done` |
@@ -404,6 +404,11 @@ customElements.define("star-rating", StarRating);
 Dispatch `change` with `bubbles: true`, as a native control's does, when the
 user commits an edit. Setting `value` from the hub fires nothing.
 
+Inside `lb-query="lb-url"`, a control may hold several values. The hub sets
+its `value` to a string, or to an array of strings when the URL repeats the
+parm, and gathers an array back when `value` gives one; see
+[Several values](./chrome.md#several-values).
+
 A form owns a form-associated custom element the way it owns an `<input>`,
 including through the HTML `form` attribute, so a form gathers it on submit.
 Write `formResetCallback` to restore the default value: the hub resets a form
@@ -627,7 +632,7 @@ had there hears the event, and no custom element the hub has removed hears
 ### Holding rows
 
 The hub lands every row template itself, places every row by the query's
-order (see [Rows the user is working in](./data-binding.md#rows-the-user-is-working-in)
+order (see [Placing by hand](./data-binding.md#placing-by-hand)
 for when it does not), 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
@@ -656,12 +661,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 user's order or the query's, and leaves them where they stand for an edit from inside the list |
+| Placing     | Places every live row by the user's order or the query's, and leaves them where they stand for an answer under `lb-manual` |
 | 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 showing, `lb-query-unsorted-count` with the number out of order, and `lb-query-order` with the order placing them |
+| Counting    | Stamps `lb-query-row-count` with the number of live rows showing, `lb-query-unplaced-count` with the number out of place, and `lb-query-order` with the order placing them |
 
 `lb-options.browser.ts` and `lb-table.browser.ts` in
 [`@loadbare/widgets`](./widgets.md) are two uses of `lbRowsLanded`: one