@loadbare/app 0.23.0 → 0.24.0

package/skills/loadbare-app/references/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/skills/loadbare-app/references/miswarts.md

@@ -47,9 +47,10 @@ template, and only the `name`.
 
 ## Checkboxes and radio groups always gather a value
 
-**What.**  An unchecked checkbox gathers `"false"`, a checked one
-`"true"`, and its `value` attribute means nothing to the hub.  A radio
-group with none checked gathers `""`.
+**What.**  A checkbox without a `value` attribute is a flag: unchecked it
+gathers `"false"`, checked `"true"`.  A radio group with none checked
+gathers `""`.  A checkbox carrying `value` is one of a set holding a query
+parm, and gathers as HTML has it.
 
 **Rule broken.**  Where HTML already has an opinion, Loadbare/app
 follows it.  HTML sends a checkbox's `value` when it

package/skills/loadbare-app/references/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/skills/loadbare-app/references/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