@loadbare/app 0.13.0 → 0.15.0

package/docs/TECHREF-1.0.md

@@ -31,10 +31,9 @@ handle.
 
 ### Form controls
 
-- **Checkboxes and radio buttons are not implemented.** A value does not
-  land on one and the hub does not gather one.  Landing needs a decision on
-  what counts as checked, which waits on [Data types](#data-types), and a
-  radio group is several elements answering to one column.
+- **Radio buttons are not implemented.** A value does not land on one and
+  the hub does not gather one.  A radio group is several elements answering
+  to one column.
 
 ### Custom element hooks
 
@@ -70,10 +69,6 @@ But the allowed values may depend on other values in the row.
 
 ### The server API
 
-- **Decide the options-argument shape once.** Global hooks, transaction
-  wrapping, error handling and a CSRF token all want the same trailing
-  parameter on `createHub` and `hubRoutes`.  Build none of them, but pick
-  where they go.
 - **Land `staticRoutes`.**  It closes the last place where an
   application hand-writes facts the builder owns.
 
@@ -457,7 +452,8 @@ A query that arrives with nowhere to land is reported to the console.
 | Any other element                                | Its text content               |
 
 A control is an `<input>`, `<select>` or `<textarea>`, or a form-associated
-custom element with a `value` property that fires `change`.  A
+custom element with a `value` property that fires `change`.  A checkbox is a
+control too, by the rule below.  A
 form-associated custom element declares `static formAssociated = true`.
 
 The hub stamps `lb-column-value` with the value on every element it sets.
@@ -468,9 +464,21 @@ renders `lb-column-value` itself.
 The hub gathers from the same controls it lands on, so a value read back is
 the one that landed.
 
-An `<input>` of type `checkbox`, `radio`, or `file` receives nothing, not
-even `lb-column-value`, and the hub reports it to the console.  The hub does
-not gather one either.
+A checkbox's state is `checked`, not `value`: HTML's quirk, and so the
+hub's, so that every other part of the vocabulary treats it as any control.
+The hub checks it by the rule `lb-show` is on by: `null` and `false` are
+unchecked, and every other value is checked, with no string read.  It
+gathers `"true"` or `"false"`, so an unchecked box still says so, where a
+native form submission leaves it out.  The checkbox's own `value`
+attribute means nothing to the hub.
+
+```html
+<input type="checkbox" lb-column="active" lb-request="lb-row-update" />
+```
+
+An `<input>` of type `radio` or `file` receives nothing, not even
+`lb-column-value`, and the hub reports it to the console.  The hub does not
+gather one either.
 
 A `<select>` with no option for the value shows no selection.
 
@@ -707,10 +715,9 @@ standing where it stood, and moved back out when the column turns on.  It is
 not rendered, focused, clicked, announced or gathered.  It is moved and
 never rebuilt, so a custom element keeps its instance and a control keeps
 what was typed into it.  Landing reaches into that template, so the element
-and everything inside it return current.  A custom element sees
-`disconnectedCallback` then `adoptedCallback` going in, and
-`adoptedCallback` then `connectedCallback` coming out, and still receives
-`lb-column-value` while it is away.
+and everything inside it return current.  A custom element hears nothing
+going in or coming out, and still receives `lb-column-value` while it is
+away.
 
 The builder ships every `lb-show` element already inside its template, so
 nothing conditional shows until its row lands.  An absent element's template
@@ -782,9 +789,13 @@ Every request has one shape, on the event and on the wire:
 { name: "lb-row-update", query: "roster", key: "42", values: { name: "Ann" } }
 { name: "lb-row-delete", query: "roster", key: "42" }
 { name: "mailRoster",    query: "roster", key: "42" }
+{ name: "lb-row-update", query: "roster", keys: ["42", "43"], values: { role: "lead" } }
+{ name: "lb-row-insert", query: "invoice", values: { memo: "May" }, rows: { lines: [{ key: "1", values: { qty: "3" } }] } }
 ```
 
-The hub sends `query`, `key` and `values` as present.
+The hub sends `query`, `key` and `values` as present, and `keys` in place of
+`key` for a request acting on the rows selected — see
+[Selecting rows](#selecting-rows).
 
 #### Committing
 
@@ -852,7 +863,8 @@ controls belong to a form that cannot wrap a `<tr>`:
 
 The hub gathers from controls only.  It skips a control whose nearest
 ancestor `lb-query` is a descendant of the live row or form, since that
-control belongs to a nested query.  An element carrying `lb-query` and
+control belongs to a nested query, 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).  An element carrying `lb-query` and
 `lb-column` both, such as a picker, belongs to the row around it and is
 gathered.
 
@@ -866,6 +878,61 @@ ancestor `lb-query` of the element carrying `lb-request`, and takes `key`
 from that element's nearest ancestor row when that row is of the same
 query.
 
+#### A form over a set of rows
+
+A form gathers the live rows of a query nested directly in its own query,
+besides its own controls.  Each goes as its key and the values of the
+controls in it, under the nested query's name:
+
+```
+{ name: "lb-row-insert", query: "paychecks", values: { pay_date: "2026-10-02" },
+  rows: { deduction_types: [{ key: "401k", values: { amount: "50" } },
+                            { key: "dental", values: { amount: "" } }] } }
+```
+
+The form's own query is the one it carries, or else the nearest around it.
+A nested query is gathered when its nearest ancestor `lb-query` is the
+form's own, so one level only: a query nested deeper shows the same rows in
+every row around it, and its keys would repeat.  Every live row of it goes,
+whatever its values, and only controls inside a live row of it.
+
+An insert, an update and a declared request carry `rows`; a delete does
+not.  A form whose only controls are in nested rows sends for its own query,
+keyed by the row landed on it or the row it is pointed at, with empty
+`values`.  A live row gathers nothing nested.
+
+The handler for the form's query receives `rows` beside `values`, so the
+master and its details are written together.  The server checks that
+`rows` holds string keys and string values by query, and ignores a request
+whose `rows` does not.
+
+A nested query answers once for the page, as anywhere — see
+[Master-detail](#master-detail).  The form enters a new master with its
+details, or edits the master the page shows by a query parm, whose details
+the nested query reads from the same parm.  A pointed form fills its own
+controls from the row it points at, and its nested rows stay the nested
+query's answer.
+
+#### A row not yet entered
+
+A row whose key is the empty string is a new one, not yet entered.  It
+arises two ways: a `row` query answers with an empty key, as one reading
+the master's key from an empty query parm does, or `--lb-new` points a form
+(see [A form pointed at a row](#a-form-pointed-at-a-row)).  Either way the
+element carries `lb-key-value=""`.
+
+The hub sends no `key` for it, whether the key came from where the element
+sits or from a request a custom element dispatched.  An `lb-row-insert` and
+a declared request are sent without one.  An `lb-row-update` and an
+`lb-row-delete` are not sent, because nothing is on record to change, and
+nothing is reported: it is the row's state, not a mistake.  So a control
+saving its own column on `change` saves on a row on record, and on a new
+row only holds what a submit will gather.  No ancestor sees a request not
+sent, and it gets no `lb-request-done`.
+
+An update or a delete with no row around it at all has no key either, and
+is reported to the console, as any request missing what it needs is.
+
 A field the request already carries is its issuer's and is kept.  A custom
 element that dispatches its own request with `values` is not gathered over.
 
@@ -877,7 +944,8 @@ element that dispatches its own request with `values` is not gathered over.
 | `lb-row-update` | `query`, `key`, `values` | `rowUpdate`       |
 | `lb-row-delete` | `query`, `key`           | `rowDelete`       |
 
-The hub issues one of these only when it has what the table lists.  An
+`keys` stands in for `key`.  The hub issues one of these only when it has
+what the table lists.  An
 `lb-row-insert` or `lb-row-update` that gathers nothing is not issued.  A
 request that is not issued is reported to the console.
 
@@ -892,6 +960,125 @@ For a query the hub serves, the hub answers the request itself, with no
 round trip.  The hub serves `lb-url`, and answers `lb-row-update` for it —
 see [Query parms](#query-parms).
 
+#### A form pointed at a row
+
+A set of rows the user edits or adds to has one form on the page, naming
+the same query, outside every row.  A button points it with HTML's
+`commandfor`, naming the form's `id`, and `command`:
+
+| Command        | On a button                       | The hub                                   |
+| -------------- | --------------------------------- | ----------------------------------------- |
+| `--lb-edit`    | In a live row of the form's query | Fills the form from that row, keyed by it |
+| `--lb-new`     | Anywhere                          | Starts the form empty, for an insert      |
+| `--lb-release` | Anywhere                          | Lets the form go without saving           |
+
+HTML requires a custom command to begin with `--`, and fires it as a
+`command` event on the form, which the hub hears.
+
+```html
+<tbody lb-query="paychecks">
+  <template><tr>
+    <td lb-column="pay_date"></td>
+    <td><button type="button" commandfor="paycheck" command="--lb-edit">Edit</button></td>
+  </tr></template>
+</tbody>
+<button type="button" commandfor="paycheck" command="--lb-new">New</button>
+
+<dialog>
+  <form id="paycheck" lb-query="paychecks" lb-request="lb-row-update">
+    <input lb-column="pay_date" type="date" />
+    <button type="submit">Save</button>
+    <button type="submit" lb-request="lb-row-insert">Save new</button>
+    <button type="button" commandfor="paycheck" command="--lb-release">Cancel</button>
+  </form>
+</dialog>
+```
+
+Which row a form edits is interaction state, not a view, so it is not a
+query parm.  The user edits only a row they can see, so Edit fills the form
+from the row as the hub holds it, every column the query answered, with no
+round trip.  A row that must be fetched to be edited is another page, with
+that row as its master.
+
+Pointing a form first empties it: every column it names lands as null, and
+the form resets, so each control returns to its default.  Edit then lands
+the row on the form as on any element a `row` lands on, stamps the form
+`lb-key-value` with the row's key, and stamps the row `lb-row-editing`.
+Gathering then takes the key from the form.  New stamps an empty key, making
+the form [a row not yet entered](#a-row-not-yet-entered).  Both focus the
+form's first control.
+
+| The form's `lb-key-value` | The form is        |
+| ------------------------- | ------------------ |
+| A key                     | Editing that row   |
+| Empty                     | Entering a new row |
+| Absent                    | Not in use         |
+
+A stylesheet shows the form's buttons by it, such as Save while it has a
+key and Save new while the key is empty.
+
+A request from the form that succeeds lets it go, as `--lb-release` does:
+the form empties, and both stamps go.  One that fails leaves the form
+pointed, as the user had it.
+
+When the form is inside a `<dialog>`, Edit and New call `showModal()` on it,
+and letting go closes it.  The dialog closing by any of HTML's means,
+Escape, `command="close"` or `method="dialog"`, lets the form go.  A form in
+no dialog opens nothing; it is always showing, or a stylesheet shows it
+while it carries `lb-key-value`.
+
+The form names a `rows` query and holds no row template, so that query's
+answers land nothing on it, and what the user typed survives a refresh.
+
+A command the hub cannot carry out is reported to the console: Edit from
+outside a live row of the form's query, Edit for a key the hub holds no row
+for, and any command aimed at an element that is not a form carrying
+`lb-query`.
+
+#### Selecting rows
+
+A checkbox carrying `lb-select` in a row template selects the live row it
+sits in, and the hub stamps the row `lb-row-selected` while it is ticked.
+It is not a column: it carries no `lb-column` or `lb-request`, lands
+nothing, and is not gathered.
+
+A request for the query that names no one row, neither from inside one of
+its rows nor from a form pointed at one, acts on the rows selected.  When
+any `lb-select` checkbox of that query is showing, the hub adds the keys of
+those ticked as `keys`:
+
+```
+{ name: "lb-row-update", query: "transactions", keys: ["4", "9"], values: { acct: "12" } }
+```
+
+- `lb-row-update` and `lb-row-delete` are sent with `keys`, and with none
+  ticked are not sent, silently, as for [a row not yet
+  entered](#a-row-not-yet-entered).
+- A declared request is sent with `keys`, empty when none is ticked, and the
+  handler decides.
+- `lb-row-insert` adds a row, and the selection is not its.
+- With no `lb-select` checkbox of the query showing, the request is an
+  ordinary one, and carries no `keys`.
+
+The server runs the page's `rowUpdate` or `rowDelete` once for each key,
+with that key, as for each row alone, so a handler written for one row
+serves several.  It lays the patches the runs return together, and runs the
+refresh set once.  A run returning `url()` is reported and ignored, since
+several rows cannot each choose one view.  A declared request receives
+`keys` as sent.
+
+After the request succeeds, the hub clears every `lb-select` checkbox of the
+query and the stamps with them.  A failed request leaves the selection.
+
+Only a checkbox that is showing counts: one parked by `lb-show` is in
+template content, out of reach.  Parking one also clears its tick, so a
+selection never waits out of sight to return stale.
+
+Which rows are selected is interaction state, as which row a form edits is.
+A selecting mode the page keeps in the URL reaches the rows as a column the
+query computes from the parm, which `lb-show` reads, since `lb-show` reads
+from the row it sits in.
+
 #### The request event
 
 The hub dispatches every request as the bubbling `lb-request` event before
@@ -910,8 +1097,10 @@ makes a confirmation wrapper possible without the wrapped element knowing
 about it.
 
 Once what the request brought back has landed, or its round trip has failed,
-the hub dispatches the bubbling `lb-request-done` event from the same
-element.  Its `detail`, `HubRequestDone` in `@loadbare/app/types`, holds
+the hub calls `lbRequestDone(detail, origin)` on the committing element and
+every custom element around it, innermost first (see
+[Lifecycle](#lifecycle)), then dispatches the bubbling `lb-request-done`
+event from the same element.  Its `detail`, `HubRequestDone` in `@loadbare/app/types`, holds
 the request as the hub sent it and `items`, every response item that landed
 because of it, in order.  An answer that moved the URL contributes its
 `lb-url` item and the page load.  `error` is set instead when the round trip
@@ -935,6 +1124,46 @@ failed one.
 The hub ignores a commit on an element carrying `lb-request-pending`, so a
 pending element is disabled in fact and a stylesheet only has to show it.
 
+#### Refusals
+
+A handler refuses a request by throwing `refusal()`, exported by
+`@loadbare/app/server`, with words written for the user: a message for the
+request as a whole, a message per column, or both.
+
+```ts
+throw refusal("That series already has paychecks entered.");
+throw refusal({ amount: "Must be more than zero" });
+throw refusal("Two fields need attention.", { amount: "…", pay_date: "…" });
+```
+
+It is thrown rather than returned, so it may come from anything the handler
+calls, and rolls back whatever the application has open as any throw does.
+`hubRoutes` answers it with status 422 and `{ refusal: { message?, columns? } }`.
+Anything else thrown is a failure, answered 500 with no body, so no stack
+or database message reaches the browser.
+
+The hub shows a refusal where it belongs:
+
+- It stamps the element that committed `lb-request-refused`, whose value is
+  the whole-request message, empty when there is none.  A stylesheet shows
+  it with `attr()`.
+- For each column, it calls `setCustomValidity(message)` on the control the
+  request gathered that column from, and `reportValidity()` on the first,
+  so the browser shows the message there and moves focus to it.  A column
+  the request gathered no such control for is reported to the console.
+- `lb-request-done` carries the refusal as `refusal`, beside `error`.
+
+A refusal is not a failure: `lb-request-error` is not stamped and nothing is
+reported.  It stands until the user edits any control the request gathered,
+a form holding them resets, or the element that committed sends again;
+then every message it put up is withdrawn at once.  While a control carries
+one, the browser holds its form's submit, as for any invalid control.
+
+A form-associated custom element takes a column's message when it defines
+`setCustomValidity` and `reportValidity`; one wrapping a native control
+passes both to it.  A request for several rows takes the whole-request
+message only.
+
 #### The round trip
 
 A request the hub sends has ten seconds to come back.  Past that the hub
@@ -943,7 +1172,8 @@ its own.  An application cannot change the deadline.
 
 A round trip fails on a server error, on a network failure, or on that
 deadline, and all three stamp `lb-request-error` on the element that issued
-the request — see [Request state](#request-state).
+the request — see [Request state](#request-state).  A refusal is not a
+failure — see [Refusals](#refusals).
 
 After a successful `lb-row-insert` gathered from a form, the hub resets the
 form, after it lands the response.  A failed insert resets nothing, so the
@@ -1211,8 +1441,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-url-link`, `lb-url-push`,
-  `lb-url-unknown`.  Every other `lb-` attribute is a stamp.
+  `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-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
@@ -1224,6 +1454,11 @@ 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-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
+  [commands](#a-form-pointed-at-a-row), and one of them with no
+  `commandfor`.
 - `lb-group` on anything but a `<template>`, or on one holding no
   `<template>` for its contents.
 - An aggregate on a `<template>`, and any but `lb-count` naming no column.
@@ -1403,6 +1638,16 @@ Explaining Express is beyond the scope of this technical reference.  The
 only real requirement is that the catch-all for app.html is at the end,
 so it does not catch any other files.
 
+`hubRoutes` mounts `express.json()` on its own routes, and takes that
+function's options under `json` in an optional third argument.  The default
+limit of 100 KB refuses an oversized body with a 413 before any handler
+runs, and the server log names the option.  A page that sends a file's text
+as a value needs more:
+
+```ts
+app.use(hubRoutes(hub, contextFor, { json: { limit: "5mb" } }));
+```
+
 `hubRoutes` answers `POST /lb/<stub>`, with the query string the browser is
 showing after it, verbatim.  It hands `contextFor` that query string's parms
 as a second argument, and `contextFor` puts on the context whatever a query
@@ -1569,11 +1814,16 @@ interface HubRequest {
   name: string;
   query?: string;
   key?: string;
+  keys?: string[];
   values?: Record<string, string>;
+  rows?: Record<string, { key: string; values: Record<string, string> }[]>;
 }
 ```
 
-Every response is an array of response items:
+A refused request is answered with status 422 and
+`{ refusal: { message?, columns? } }`, and any other failure with 500 and
+no body — see [Refusals](#refusals).  Every other response is an array of
+response items:
 
 ```ts
 interface ResponseItem {
@@ -1635,14 +1885,12 @@ Each direction has one mechanism for each kind of message:
 | -------------- | ------------------------------------------- | ---------------------------- | ------------------------------------------------ |
 | Hub to element | State that lasts                            | An attribute the hub stamps  | `lb-column-value`, `lb-key-value`, `lb-query-row-count`, `lb-group-*`, `lb-row-*`, `lb-request-pending`, `lb-request-error` |
 | Hub to element | State the platform already names           | A property                   | A control's `value`                              |
-| Hub to element | Work the hub needs done now, while landing  | An optional `lb` method      | `lbRowsLanded`                                   |
+| 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`                                |
 | Element to hub | A moment                                    | A bubbling event             | `lb-request`, and `change`, `click` and `submit` |
 
-State is an attribute, because a stylesheet can select on it and an element
-that upgrades late still finds it.  A method is for work the hub cannot go
-on without, since it acts on one element at one point in landing and nothing
-else can do it.  A moment is an event, because the element that cares is
+State is an attribute, because a stylesheet can select on it.  A method is
+how the hub tells one element what it just did to that element.  A moment is an event, because the element that cares is
 often an ancestor of the one it concerns, and an event reaches it with no
 knowledge of either.
 
@@ -1661,45 +1909,47 @@ class NoteField extends HTMLElement {
 }
 ```
 
-A control that is not yet upgraded when its column lands receives
-`lb-column-value` alone, since the hub sets `value` only on a control.  That
-happens to an element the builder shipped absent, and to one whose
-definition loads after the hub lands.  A control takes the stamp up the
-first time it connects, and never again.
-
 A custom element that is not a control receives `lb-column-value` and
 renders it; its content is never replaced.
 
 ### Lifecycle
 
-| The hub                                  | A custom element sees                        |
-| ---------------------------------------- | -------------------------------------------- |
-| Shows a page                             | `constructor`, `connectedCallback`           |
-| Creates a live row, before placing it    | `constructor`                                |
-| Places a live row the first time         | `connectedCallback`                          |
-| Moves a live row the order put elsewhere | `connectedMoveCallback` where the browser moves in place, otherwise `disconnectedCallback`, `connectedCallback` |
-| Leaves a copy of a moved row behind      | The copy's `constructor`, `connectedCallback`, and later `disconnectedCallback` |
-| Removes a live row                       | `disconnectedCallback`, once its animations end |
-| Turns `lb-show` off                      | `disconnectedCallback`, `adoptedCallback`    |
-| Turns `lb-show` on                       | `adoptedCallback`, `connectedCallback`       |
-| Turns on an element shipped absent       | `constructor`, `connectedCallback`           |
+A custom element hears the hub's lifecycle, never the browser's.  The hub
+calls four optional methods, which the `HubLifecycle` interface in
+`@loadbare/app/types` declares:
+
+| The hub                                          | A custom element hears          |
+| ------------------------------------------------ | ------------------------------- |
+| Places it: chrome at startup, a page, a new live row, a new group | `lbAttached()`, once, after every column has landed on it |
+| Lands rows on it                                 | `lbRowsLanded()`                |
+| Finishes a request committed by it or inside it  | `lbRequestDone(detail, origin)` |
+| 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            |
+
+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
+inside its template, so `lbAttached` runs whether it shows or not.  `lbAttached` reaches an outer
+custom element before the ones inside it, and `lbDetached` the inner ones
+first.  `lbRequestDone` reaches the committing element and every custom
+element around it, innermost first, before the `lb-request-done` event.
+An element a script creates hears none of them.
 
 A listener on the element itself goes in the constructor, which reads no
-attribute and no child.  A child is looked up when it is needed.
-`connectedCallback` runs on every move and is written to run again; work
-done once per instance goes behind a flag.
+attribute and no child.  A child is looked up when it is needed.  Work done
+once per instance goes in `lbAttached`, and its undoing in `lbDetached`.
 
-### Row hooks
+The build refuses a script that declares `connectedCallback`,
+`disconnectedCallback`, `adoptedCallback` or `connectedMoveCallback`.
 
-| Method           | Implemented By | The hub calls it                                       |
-| ---------------- | -------------- | ------------------------------------------------------ |
-| `lbRowsLanded()` | Developer      | After the rows land, with every row placed and stamped |
+### Row hooks
 
-The hub calls it on a custom element with `lb-query` and a row template.
-It is optional.  The `RowsHost` interface in `@loadbare/app/types` declares
-it.  The hub places every row and builds every group itself, so a custom
-element reacts to rows and never places them.  Scrolling to the row the
-page's request created is the case:
+The hub calls `lbRowsLanded()` on a custom element with `lb-query` and a row
+template, after the rows land, with every row placed and stamped.  The hub
+places every row and builds every group itself, so a custom element reacts
+to rows and never places them.  Scrolling to the row the page's request
+created is the case:
 
 ```ts
 lbRowsLanded() {
@@ -1708,10 +1958,8 @@ lbRowsLanded() {
 }
 ```
 
-A custom element the builder shipped absent under `lb-show` has not
-upgraded while its column is off.  When the column first turns on and it
-upgrades, the hub lands the query's last answer on it again, as all rows,
-so the hook runs.
+A custom element under an `lb-show` that is off holds its rows all the
+same, and the hook runs as they land.
 
 `applyRow(root, row)`, exported by `@loadbare/app`, fills `root` from one
 row, the same operation that fills a live row.
@@ -1791,6 +2039,7 @@ ownership of its behavior are stated separately, because they differ.
 | Namespace | Applies to                                                  | Loadbare owns                                       | Defined in                                      |
 | --------- | ----------------------------------------------------------- | --------------------------------------------------- | ----------------------------------------------- |
 | `lb-*`    | Attributes, their values, queries, columns of `lb-` queries, requests, custom elements, events | The names and their behavior | [The lb-* namespace](#the-lb--namespace)        |
+| `--lb-*`  | Values of HTML's `command` attribute                        | The names and their behavior                        | [Reserved commands](#reserved-commands)         |
 | `exp-*`   | Attributes on a custom element                              | The behavior; element file authors pick the names   | [Build time parameters](#build-time-parameters) |
 | `lb*`     | Methods on custom elements                                  | The names and their behavior                        | [Row hooks](#row-hooks)                         |
 
@@ -1807,6 +2056,7 @@ it may define tomorrow.
 | `lb-column`       | Developer     | Any element                         | [Landing](#landing)                           |
 | `lb-show`         | Developer     | Any element but a `<template>`      | [Displaying by condition](#displaying-by-condition) |
 | `lb-request`      | Developer     | Any element                         | [Requests](#requests)                         |
+| `lb-select`       | Developer     | A checkbox in a row template        | [Selecting rows](#selecting-rows)             |
 | `lb-url-link`     | Developer     | An `<a>`                            | [Links](#links)                               |
 | `lb-url-push`     | Developer     | An element with `lb-request`        | [Query parms](#query-parms)                   |
 | `lb-url-unknown`  | Developer     | A `<dialog>` inside `<lb-hub>`      | [An unknown page](#an-unknown-page)           |
@@ -1815,7 +2065,9 @@ it may define tomorrow.
 | `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)     |
-| `lb-key-value`    | Hub           | A live row, and an element a `row` lands on | [Rows](#rows)                         |
+| `lb-key-value`    | Hub           | A live row, an element a `row` lands on, and a pointed form | [Rows](#rows), [A form pointed at a row](#a-form-pointed-at-a-row) |
+| `lb-row-editing`  | Hub           | The live row a form is pointed at   | [A form pointed at a row](#a-form-pointed-at-a-row) |
+| `lb-row-selected` | Hub           | A live row its `lb-select` checkbox ticks | [Selecting rows](#selecting-rows)       |
 | `lb-row-live`     | Hub           | A live row                          | [Rows](#rows)                                 |
 | `lb-query-row-count` | Hub        | An element with a row template      | [Rows](#rows)                                 |
 | `lb-group-live`, `lb-group-column`, `lb-group-value` | Hub | Each top-level element of a group | [Groups](#groups) |
@@ -1823,6 +2075,7 @@ it may define tomorrow.
 | `lb-row-leaving`, `lb-group-leaving` | Hub | A row or a group on its way out | [What happened to a row](#what-happened-to-a-row) |
 | `lb-request-pending` | Hub        | The element that issued a request   | [Request state](#request-state)               |
 | `lb-request-error`   | Hub        | The element that issued a request   | [Request state](#request-state)               |
+| `lb-request-refused` | Hub        | The element whose request was refused | [Refusals](#refusals)                       |
 | `lb-show` on a `<template>` | Hub and builder | Where an absent element stands | [Displaying by condition](#displaying-by-condition) |
 | `lb-page`         | Builder       | A page's `<template>`               | [Page HTML](#page-html)                       |
 | `lb-page-title`   | Builder       | A page's `<template>`               | [Page HTML](#page-html)                       |
@@ -1850,6 +2103,17 @@ The builder refuses any other `lb-` attribute in markup — see
 | `lb-row-update` | `rowUpdate`       | [The request names](#the-request-names) |
 | `lb-row-delete` | `rowDelete`       | [The request names](#the-request-names) |
 
+### Reserved commands
+
+Loadbare/app owns every value of HTML's `command` attribute beginning with
+`--lb-`.
+
+| Command        | Defined in                                          |
+| -------------- | --------------------------------------------------- |
+| `--lb-edit`    | [A form pointed at a row](#a-form-pointed-at-a-row) |
+| `--lb-new`     | [A form pointed at a row](#a-form-pointed-at-a-row) |
+| `--lb-release` | [A form pointed at a row](#a-form-pointed-at-a-row) |
+
 ### Reserved tags
 
 Loadbare/app owns every tag in this table.  An application writes them and
@@ -1871,9 +2135,12 @@ Loadbare/app owns every DOM event in this table, both the name and what its
 
 ### Reserved methods
 
-| Method         | On                                                 | Defined in              |
-| -------------- | -------------------------------------------------- | ----------------------- |
-| `lbRowsLanded` | A custom element with `lb-query` and a row template | [Row hooks](#row-hooks) |
+| Method          | On                                                  | Defined in              |
+| --------------- | --------------------------------------------------- | ----------------------- |
+| `lbAttached`    | Any custom element the hub places                   | [Lifecycle](#lifecycle) |
+| `lbRowsLanded`  | A custom element with `lb-query` and a row template | [Row hooks](#row-hooks) |
+| `lbRequestDone` | A custom element that committed, or holds one that did | [Lifecycle](#lifecycle) |
+| `lbDetached`    | Any custom element the hub removes                  | [Lifecycle](#lifecycle) |
 
 ### Constants
 
@@ -1906,9 +2173,17 @@ imports them rather than writing a string.
 | `REQUESTED_CREATED`, `REQUESTED_CHANGED`, `REQUESTED_MOVED` | `created`, `changed`, `moved` |
 | `ATTR_ROW_LEAVING`        | `lb-row-leaving`                        |
 | `ATTR_GROUP_LEAVING`      | `lb-group-leaving`                      |
+| `COMMAND_EDIT`, `COMMAND_NEW`, `COMMAND_RELEASE` | `--lb-edit`, `--lb-new`, `--lb-release` |
+| `LB_COMMANDS`             | All three commands                      |
+| `LB_COMMAND_PREFIX`       | `--lb-`                                 |
+| `ATTR_ROW_EDITING`        | `lb-row-editing`                        |
+| `ATTR_SELECT`             | `lb-select`                             |
+| `ATTR_ROW_SELECTED`       | `lb-row-selected`                       |
 | `ATTR_REQUEST`            | `lb-request`                            |
 | `ATTR_REQUEST_PENDING`    | `lb-request-pending`                    |
 | `ATTR_REQUEST_ERROR`      | `lb-request-error`                      |
+| `ATTR_REQUEST_REFUSED`    | `lb-request-refused`                    |
+| `LB_REFUSAL_STATUS`       | `422`                                   |
 | `ATTR_URL_LINK`           | `lb-url-link`                           |
 | `ATTR_URL_PUSH`           | `lb-url-push`                           |
 | `ATTR_URL_UNKNOWN`        | `lb-url-unknown`                        |
@@ -1916,7 +2191,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 thirteen attributes a developer writes |
+| `DEVELOPER_ATTRIBUTES`    | The fourteen 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` |