@loadbare/app 0.13.0 → 0.14.0

package/docs/possible-ideas.md

@@ -4,6 +4,51 @@
 > 2026-10-02 against `@loadbare/app` 0.12.0, from a session in ef.  Nothing
 > here is decided or planned.
 
+## Why these are being considered
+
+A custom element is the platform's one way to attach code to markup, and
+widget work keeps running into what that costs.
+
+- No decomposition.  Code that concerns one row has nowhere to live but a
+  wrapper around the whole table, so `lb-table` owns everything inside it.
+  That is how page-specific behavior ends up in a shared widget: the COA
+  page's ghost row per section grew because row-level code could attach
+  only to the table.  It is the overfit the README's test guards against.
+- The browser's lifecycle is not the hub's.  A moved row is disconnected and
+  connected, the copy a move leaves behind is constructed, and an `lb-show`
+  toggle adopts twice, so `connectedCallback` must be written to run again.
+- Clutter.  The page's source is the widget's dialect of named templates
+  rather than HTML, and the shipped page keeps a wrapper tag around what it
+  expanded.
+- Plumbing through the wrapper.  The tag carrying the code is not the
+  control: `WrappedControl` forwards `value`, fires `change` again, and needs
+  `ElementInternals` to join a form.  Focus is searched for inside the
+  wrapper, and `autofocus` on a wrapped `<input>` is lost.
+- Content models reach forms too.  A `<form>` cannot wrap a `<tr>`, so the
+  ghost row joins its controls to a hidden form outside the table by the
+  `form` attribute.  A form cannot hold a form, so `lb-insert-dialog` is
+  written once outside every row instead of beside the control it serves.
+- Ids repeat in a row template.  `lb-confirm` finds its dialog by position,
+  because `commandfor`, HTML's own way to open one with no script, works
+  only by id.
+- Upgrade timing is the hub's problem.  An element shipped inside an
+  `lb-show` template, or whose definition loads late, has not upgraded, so
+  the hub keeps `waiting()`, lands kept answers again once it upgrades, and
+  stamps `lb-column-value` for a control to take up on first connect.
+- A few lines cost a wrapper.  `lb-options` has a script mostly to copy
+  `lb-group-value` into an `<optgroup>`'s `label` and each key into an
+  option's `value`, and for that the whole `<select>` sits inside a custom
+  element.
+- Parameters cannot carry structure.  Expansion parameters are words, so
+  when groups became a template, `lb-picker` lost `exp-group` and a grouped
+  picker went back to a hand-written `lb-options`.
+- CSS and accessibility see an element HTML does not define.  A wrapper tag
+  has no role, shifts child and `:nth-child` selectors, and has no place in
+  a table.  The usual remedy, `display: contents`, has a history of
+  accessibility bugs.
+- One element, one class.  A ghost row that should also save as it is typed
+  in needs a widget combining the two.
+
 ## Code on elements the parser constrains
 
 Loadbare's data vocabulary is attributes, and an attribute goes on any
@@ -20,7 +65,8 @@ table.  Each new need is another named destination, and the page's source
 reads as `lb-table`'s shape rather than a table's.  The shipped HTML is
 honest; the source is a dialect.
 
-Two ways to put code on the element itself follow.
+Two ways to put code on the element itself follow, and only the second
+survives.
 
 ### Customized built-ins
 
@@ -28,25 +74,11 @@ Two ways to put code on the element itself follow.
 <tr is="lb-ghost-row">…</tr>
 ```
 
-The platform's own answer: a class extending `HTMLTableRowElement`,
-registered with `customElements.define(name, cls, { extends: "tr" })`.  The
-parser sees a `<tr>`, so the element sits wherever a `<tr>` may, keeps every
-native behavior of one, and gets the custom element lifecycle.
-
-- Chrome and Firefox ship it.  WebKit has declined to, on principle
-  (subclassing a built-in breaks when its internals change), so Safari needs
-  a polyfill for as long as the feature exists.
-- Every browser on iOS and iPadOS is WebKit, Chrome included.  The polyfill
-  is therefore not a Safari fallback but the code path on every iPhone and
-  iPad, permanently.  The usual one, `@ungap/custom-elements`, watches the
-  document with a `MutationObserver`, so on those devices the lifecycle runs
-  because something noticed.
-- `is` must be present when the element is created; setting it later does
-  nothing.  Cloning a template preserves it, so a row template carrying
-  `is` yields upgraded rows.
-- A customized built-in cannot be form-associated (`ElementInternals` is for
-  autonomous custom elements), which matters little: the built-in elements
-  that controls are already take part in forms.
+The platform's own answer: a class extending `HTMLTableRowElement`, which
+the parser treats as a `<tr>`.  WebKit has declined to ship it, and every
+browser on iOS and iPadOS is WebKit, so a polyfill, usually a
+`MutationObserver`, would be the code path on every iPhone and iPad for
+good.  That rules it out.
 
 ### Behavior by attribute
 
@@ -114,13 +146,12 @@ A rule for choosing: a custom element makes a new kind of element (its own
 markup, expansion, or a control built from scratch); a behavior adds code to
 an element HTML already has.
 
-### Where each would land
+### Where it would land
 
-Either one lets a page write a real `<table lb-query>` with code on the rows
-that need it, and leaves `lb-table` to supply only what is truly the
-table's.  Customized built-ins borrow the platform's lifecycle at the cost of
-a permanent polyfill; behavior by attribute keeps the parser and the browser
-matrix out of it, at the cost of a lifecycle the hub would define.
+Behavior by attribute lets a page write a real `<table lb-query>` with code
+on the rows that need it, and leaves `lb-table` to supply only what is truly
+the table's.  It keeps the parser and the browser matrix out of it, at the
+cost of a lifecycle the hub would define.
 
 ## Expansion that replaces the tag
 
@@ -186,3 +217,92 @@ source, the `lb-behavior` attribute and the comment already give.
    the page passes them as parameters (`exp-column`, written into the file as
    `lb-column="{{column}}"`), which works today but reads less naturally
    than `lb-column`.  This wants worked examples before a rule.
+
+## The case for behaviors
+
+Today's model is simple to state: a widget is a name, and a name is one or
+both of a `.html` and a `.browser.ts`.  One name is one element the
+developer writes, so what a widget does is easy to predict.  Most of what
+that costs is paid inside Loadbare, in service of the simple model.  The one
+place it leaks to the developer is the lifecycle, where a widget author must
+follow strict rules to get the behavior they expect.
+
+Behaviors would simplify the hub, but they seem to spread code that a
+custom element keeps in one file.  The containment comes from the element
+file, though, not from the tag.
+
+### What one file bundles today
+
+`lb-table`'s script does three jobs, joined by where they sit rather than by
+any data they share:
+
+| Job                        | Reads and writes                                   |
+| -------------------------- | -------------------------------------------------- |
+| Table scaffolding          | Caption, head and foot destinations; expansion only |
+| The ghost row              | The ghost row's controls, its form, and focus      |
+| Scrolling to the saved row | The list's rows and their stamps                   |
+
+It is one file, and three concerns in one class, none reusable without the
+others.  A `<ul>` cannot have a ghost row without becoming an `lb-table`.
+
+### Two units
+
+- A widget is markup.  Its element file decides what elements exist, at
+  build time, as now.
+- A behavior is what one element does.  Its code attaches to the element
+  that carries it, and runs on the hub's lifecycle.
+
+An element file may write `lb-behavior` on its own inner elements:
+
+```html
+<!-- lb-table.html -->
+<table lb-behavior="scroll-to-saved">
+  <thead lb-exp-template="head"></thead>
+  <tbody lb-exp-slot></tbody>
+  <tbody lb-exp-template="ghost" lb-behavior="ghost-row"></tbody>
+</table>
+```
+
+`lb-table` stays the one place to read, and its element file says which code
+runs on which element.  The code is split into files by job, and the widget
+assembles them.  A page that wants a ghost row in a `<ul>` writes
+`lb-behavior="ghost-row"` on it.
+
+### Where code goes
+
+Code goes on the element it reads and writes.
+
+- The ghost row's code touches the ghost row's controls and form, so it is a
+  behavior on the ghost row.
+- Scrolling touches the list's rows, so it is a behavior on the list.
+- Code that seems to need two elements is the sign to stop.  Behaviors never
+  call each other.  They speak only through what widgets use today:
+  attributes the hub stamps, and bubbling events such as `lb-request-done`.
+  The scrolling behavior knows nothing of the ghost row; it reads
+  `lb-row-requested`.
+
+The rule also refuses the overfit that started this: a ghost row per
+section would be a behavior on the table reaching into every section.
+
+### Where the leak moves
+
+Today the leak is the browser's lifecycle: `connectedCallback` written to
+run again, and a value stamp adopted on first connect.  With behaviors it
+becomes three rules Loadbare states:
+
+1. Only elements the hub places get behaviors.
+2. A behavior is attached and detached exactly once.
+3. Behaviors speak only through stamps and events.
+
+They are fewer, and in the hub's terms rather than the browser's.  The cost
+moves to Loadbare's design: the ordering the platform gives custom elements
+must be stated, such as whether a host's behavior attaches before or after
+its rows land, and the order among nested behaviors.
+
+### Both, not one
+
+Custom elements stay.  A control built from scratch still needs
+`ElementInternals`, and a tag with no code is expansion alone.  Behaviors
+cover what a tag does badly: code on an element HTML already has, inside
+content models that forbid a tag.  The developer's question becomes whether
+they are making a new kind of element, or giving an existing element a job.

package/docs/reference/custom-elements.md

@@ -412,9 +412,104 @@ 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
 after a successful insert.
 
+A control takes the message of a refusal naming its column when it has
+`setCustomValidity` and `reportValidity`, as a native control does; see
+[Refusals](./data-binding.md#refusals). A control wrapping a native one
+passes both to it, so the browser shows the message there and focus lands
+there.
+
 The `<lb-input>`, `<lb-select>`, `<lb-options>` and `<lb-picker>` widgets
 are controls; see [The Basic Widget Library](./widgets.md).
 
+### Example: a file's text as a value
+
+The hub takes no file input as a control. A custom element wraps one and is
+the control in its place. This one reads the chosen file as text, which
+suits a CSV or a bank statement, and sends the file's name under a second
+column:
+
+```html
+<!-- src/file-text.html -->
+<label>{{label}} <input type="file" accept="{{accept}}" /></label>
+<input type="hidden" lb-column="{{name-column}}" />
+```
+
+```ts
+// src/file-text.browser.ts
+class FileText extends HTMLElement {
+  static formAssociated = true;
+  #internals = this.attachInternals();
+  #value = "";
+
+  constructor() {
+    super();
+    this.addEventListener("change", (e) => {
+      const input = e.target as HTMLInputElement;
+      if (e.target === this || input.type !== "file") return;
+      e.stopPropagation();
+      void this.read(input);
+    });
+  }
+
+  get value(): string {
+    return this.#value;
+  }
+
+  set value(value: string) {
+    this.#value = value ?? "";
+    this.#internals.setFormValue(this.#value);
+  }
+
+  formResetCallback() {
+    this.value = "";
+    this.setName("");
+  }
+
+  async read(input: HTMLInputElement) {
+    const file = input.files?.[0] ?? null;
+    this.value = file ? await file.text() : "";
+    this.setName(file?.name ?? "");
+    this.dispatchEvent(new Event("change", { bubbles: true }));
+  }
+
+  setName(name: string) {
+    const hidden = this.querySelector<HTMLInputElement>('input[type="hidden"]');
+    if (hidden) hidden.value = name;
+  }
+}
+
+customElements.define("file-text", FileText);
+```
+
+```html
+<!-- src/uploads.page.html -->
+<form lb-query="uploads" lb-request="lb-row-insert">
+  <file-text
+    lb-column="filetext"
+    exp-name-column="filename"
+    exp-label="Statement file"
+    exp-accept=".csv,.ofx"
+  ></file-text>
+  <button type="submit">Upload</button>
+</form>
+```
+
+Reading a file is asynchronous, so the element stops the file input's own
+`change` and fires its own once the text is in hand. A form submitted before
+then gathers the empty value, and the handler refuses it as no file.
+
+A control gathers one column, so the name rides in a hidden input that the
+hub gathers as a control of its own. The form gathers both on submit. Its
+reset after the insert clears the file input but not the hidden one, whose
+`value` is its default, so `formResetCallback` clears the name itself.
+
+The text travels in the request's JSON body, which `hubRoutes` limits to
+100 KB unless the server raises it; see [Options](./server.md#options).
+
+The choices here are this application's: text rather than binary, the whole
+file in the request, the name in a second column. A different application
+writes its own element, under its own name, to make different ones.
+
 ### Receiving a value
 
 A custom element that is not a control keeps the content the builder placed
@@ -494,7 +589,8 @@ this.addEventListener(LB_DONE_EVENT_NAME, (e) => {
 ```
 
 `items` is every response item that landed because of the request, in
-order. An answer that moved the URL contributes its `lb-url` item, which
+order. `refusal` is set beside `error` when the handler refused the
+request, holding its `message` and `columns`. An answer that moved the URL contributes its `lb-url` item, which
 carries a key only the server knew, and the page load. `error` is set when
 the round trip failed, and then nothing landed. A new row's key is in the
 answer only when the handler returned it in a patch: a refresh sends all

package/docs/reference/data-binding.md

@@ -121,6 +121,7 @@ no row fills.
 | Element                                              | Receives the value as                   |
 |------------------------------------------------------|-----------------------------------------|
 | `<input>`, `<select>`, `<textarea>`                  | Its `value`, and `lb-column-value`      |
+| `<input type="checkbox">`                            | Its `checked`, 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` |
@@ -132,12 +133,26 @@ element that is not a control keeps the content the builder placed in it
 from its element file, and renders `lb-column-value` itself; see
 [Custom Elements](./custom-elements.md#receiving-a-value).
 
-A checkbox, a radio button and a file input receive nothing, and the hub
-reports it to the console.
+A radio button and a file input receive nothing, and the hub reports it to
+the console.
 
 The hub hands every value to the browser as the server sent it. What a
 number, a date or a null looks like is decided in the query.
 
+### Checkboxes
+
+A checkbox is a control. It is checked when its column is anything but
+`false` or null, and it sends `"true"` or `"false"`:
+
+```html
+<input type="checkbox" lb-column="active" lb-request="lb-row-update" />
+```
+
+Checked follows the rule `lb-show` follows, so a query spells a flag as a
+boolean, and the string `"false"` is checked. Unchecked sends `"false"`
+rather than nothing, so a flag can be set back. The checkbox's `value`
+attribute means nothing to the hub.
+
 ### Rows
 
 Write a `<template>` inside the element carrying `lb-query`, holding one
@@ -414,7 +429,8 @@ Every request has one shape:
 ```
 
 The hub takes `query`, `key` and `values` from where the element sits, and
-sends each when it has one. The server runs the handler for the name and
+sends each when it has one. A request acting on several rows carries `keys`
+in place of `key`; see [Selecting rows](#selecting-rows). The server runs the handler for the name and
 answers with response items, which land like any others.
 
 ### Committing
@@ -461,7 +477,8 @@ carrying `lb-request`:
 4. Otherwise: every control whose form owner is the element's form owner.
 
 The hub gathers from controls only, and skips a control that belongs to a
-query nested inside the group. A form owner includes a control outside the
+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). A form owner includes a control outside the
 form that names it with the HTML `form` attribute, which is how a table row,
 where a form cannot go, sends one:
 
@@ -492,6 +509,99 @@ ancestor `lb-query` and row of the element carrying `lb-request` instead.
 Controls gathered from two different queries are an error, and the hub
 sends nothing.
 
+### A form over a set of rows
+
+A form gathers the live rows of a query nested in its own query as well as
+its own controls: a master and its details, entered together. Each nested
+row goes as its key and the values of its own controls, under the nested
+query's name, in `rows`:
+
+```html
+<form lb-query="paychecks" lb-request="lb-row-insert">
+  <input lb-column="pay_date" type="date" />
+  <table>
+    <tbody lb-query="deduction_types">
+      <template>
+        <tr>
+          <td lb-column="label"></td>
+          <td><input lb-column="amount" /></td>
+        </tr>
+      </template>
+    </tbody>
+  </table>
+  <button type="submit">Save</button>
+</form>
+```
+
+```json
+{
+  "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 list of deduction types lives only in the database: the nested query
+answers it, and the form shows one input per row.
+
+- Every live row of the nested query goes, whatever its values. What an
+  empty value means, such as no deduction of that type, is the handler's.
+- One level only. A query nested inside a nested row shows the same rows in
+  every row around it, so it is not gathered.
+- An insert, an update and a declared request carry `rows`. A delete does
+  not.
+- A form whose only controls are in nested rows still sends, for its own
+  query, with empty `values`.
+- A live row gathers nothing nested, as before.
+
+The handler for the form's query receives `rows` beside `values`, and writes
+the master and its details together; see [crud](./page-files.md#crud).
+
+A nested query answers once for the page, so its rows are the same wherever
+they show. The form enters a new master with its details, or edits the
+master the page shows, whose details the nested query reads from the same
+query parm. A form [pointed at a row](#editing-a-row-in-one-form) fills its
+own controls from that row; its nested rows stay the nested query's answer.
+
+### A row not yet entered
+
+A row whose key is empty is a new one, not yet entered. It arises two ways:
+a `row` query answers with an empty key, as one showing the master a query
+parm names does when the parm is empty, or New points a form (see
+[Editing a row in one form](#editing-a-row-in-one-form)). Either way the
+element carries `lb-key-value=""`.
+
+| Request          | From a row not yet entered            |
+|------------------|---------------------------------------|
+| `lb-row-insert`  | Sent, with no `key`                   |
+| A declared one   | Sent, with no `key`                   |
+| `lb-row-update`  | Not sent: there is nothing to update  |
+| `lb-row-delete`  | Not sent: there is nothing to delete  |
+
+An update or delete not sent is the row's state, not a mistake, and nothing
+is reported. So a control that saves its own column with
+`lb-request="lb-row-update"` saves on a row on record, and on a new row only
+holds what a submit will gather:
+
+```html
+<section lb-query="account">
+  <form id="account-form">
+    <input lb-column="name" lb-request="lb-row-update" />
+  </form>
+  <button type="submit" form="account-form" lb-request="lb-row-insert">Save new</button>
+</section>
+```
+
+The same holds for a request a custom element sends carrying `key: ""`.
+An update or delete with no row around it at all has no key either, and
+that is reported to the console.
+
 ### Inserting, updating and deleting rows
 
 Loadbare provides three requests. Each runs the handler the page declares
@@ -528,6 +638,152 @@ failed insert leaves the entry for the user to correct.
 Leave `lb-request` off a control inside a form or a live row that sends its
 own update, or the same edit is written twice.
 
+### Editing a row in one form
+
+A table, or any other set of rows, that the user edits or adds to has one
+form on the page, naming the same query. It sits anywhere, outside every
+row. Buttons point it with HTML's `commandfor` 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 `--`.
+
+```html
+<tbody lb-query="paychecks">
+  <template>
+    <tr>
+      <td lb-column="pay_date"></td>
+      <td lb-column="gross"></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" />
+    <input lb-column="gross" />
+    <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>
+```
+
+Edit fills the form from the row as the hub already holds it, with no
+round trip, including columns no element in the table shows. The user
+edits a row they can see, so the row is on the page. A row that has to be
+fetched to be edited is another page, with that row as its master.
+
+The hub stamps the form with the row's key, so the form's request carries
+it, and stamps the row `lb-row-editing`. New stamps an empty key, making the
+form [a row not yet entered](#a-row-not-yet-entered), and resets every
+control to its default. The form's state is in its `lb-key-value`
+stamp:
+
+| `lb-key-value` | The form is                 |
+|----------------|-----------------------------|
+| A key          | Editing that row            |
+| Empty          | Entering a new row          |
+| Absent         | Not in use                  |
+
+A stylesheet shows Save or Save new by it:
+
+```css
+form[lb-key-value=""] [type="submit"]:not([lb-request]),
+form:not([lb-key-value=""]) [lb-request="lb-row-insert"] {
+  display: none;
+}
+```
+
+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 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
+one leaves the form as the user had it, to correct.
+
+Inside a `<dialog>`, Edit and New open the dialog modally, and letting go
+closes it. The dialog closing in any way HTML closes one lets the form go:
+Escape, `command="close"`, or `method="dialog"`. A form in no dialog opens
+nothing. It is always showing, as a detail panel beside the table is, or a
+stylesheet shows it while it has a key:
+
+```css
+form:not([lb-key-value]) {
+  display: none;
+}
+```
+
+The form names a `rows` query and holds no row template, so the query
+landing again lands nothing on it, and what the user has typed stays.
+
+A button inside a form that carries a command is `type="button"`, or it
+submits the form instead.
+
+### Selecting rows
+
+A checkbox carrying `lb-select` in a row template selects the live row it
+sits in. It is not a column: it carries no `lb-column`, lands nothing and
+is not gathered. The hub stamps the row `lb-row-selected` while it is
+ticked.
+
+A request for the query that names no one row then acts on the rows
+selected, and carries their keys as `keys`:
+
+```html
+<tbody lb-query="transactions">
+  <template>
+    <tr>
+      <td><input type="checkbox" lb-select lb-show="selecting" /></td>
+      <td lb-column="description"></td>
+      <td lb-column="amount"></td>
+    </tr>
+  </template>
+</tbody>
+
+<form lb-query="transactions" lb-request="lb-row-update">
+  <lb-picker lb-query="accounts" lb-column="acct" exp-label="Account" exp-column="name"></lb-picker>
+  <button type="submit">Apply</button>
+  <button type="button" lb-request="lb-row-delete">Delete</button>
+</form>
+```
+
+```json
+{ "name": "lb-row-update", "query": "transactions", "keys": ["4", "9"], "values": { "acct": "12" } }
+```
+
+| Request          | With rows selected                     | With none ticked     |
+|------------------|----------------------------------------|----------------------|
+| `lb-row-update`  | Sent with `keys`                       | Not sent             |
+| `lb-row-delete`  | Sent with `keys`                       | Not sent             |
+| A declared one   | Sent with `keys`                       | Sent with `keys: []` |
+| `lb-row-insert`  | Sent as ever; the selection is not its | Sent as ever         |
+
+An update or delete with nothing ticked has nothing to act on, and nothing
+is reported. A request from inside a row still names that row alone. The
+server runs the page's `rowUpdate` or `rowDelete` once for each key, as for
+each row alone, and refreshes once; see [crud](./page-files.md#crud).
+
+After the request succeeds, the hub clears the selection. A failed one
+leaves it, to try again.
+
+Only a checkbox that is showing counts. Turning a selector off with
+`lb-show` also clears its tick, so leaving a selecting mode abandons the
+selection rather than keeping it out of sight. With every selector off, a
+request for the query is an ordinary one again.
+
+Which rows are selected, and whether the page is in a selecting mode, is
+interaction state. A mode the URL keeps, such as `?selecting=1`, reaches
+the rows as a column the query computes from the parm, which `lb-show`
+reads.
+
 ### Declared requests
 
 A request name the page declares under `handlers` runs the application's
@@ -557,6 +813,7 @@ The hub stamps the element that committed:
 |----------------------|-----------------------------------------------|
 | `lb-request-pending` | The round trip is in flight                   |
 | `lb-request-error`   | The round trip failed, until the next request |
+| `lb-request-refused` | The handler refused it; see [Refusals](#refusals) |
 
 `lb-request-error` covers a non-2xx response, a network failure and a
 timeout alike. The hub aborts a round trip after ten seconds, and sets
@@ -574,6 +831,44 @@ pending button is already disabled and a stylesheet only shows it:
 }
 ```
 
+### Refusals
+
+A handler that refuses a request says why, in words for the user; see
+[Refusing a request](./page-files.md#refusing-a-request). The hub shows
+them where they belong:
+
+- A message for the request as a whole is the value of the
+  `lb-request-refused` stamp on the element that committed, empty when the
+  refusal has none.
+- A message for a column goes on the control the request gathered it from,
+  as HTML's own validity: `setCustomValidity`, the `:invalid` pseudo-class,
+  and the browser's own bubble for the first, which takes focus.
+
+A stylesheet shows the whole-request message with no script:
+
+```css
+form[lb-request-refused]:not([lb-request-refused=""])::after {
+  content: attr(lb-request-refused);
+  color: firebrick;
+}
+input:invalid {
+  outline: 2px solid firebrick;
+}
+```
+
+A refusal is not a failure: `lb-request-error` is not stamped, and nothing
+is reported to the console.
+
+A refusal stands until the user edits any control the request gathered,
+resets its form, or sends from the same element again. Then every message
+it put up goes at once, since the next submit is a new question for the
+handler. While a control carries a message the browser holds its form's
+submit, as for any invalid control, so the user edits before trying again.
+
+A form-associated custom element takes a column's message when it has
+`setCustomValidity` and `reportValidity`; see
+[Being a control](./custom-elements.md#being-a-control).
+
 ### The request event
 
 The hub dispatches every request as a bubbling `lb-request` event from the
@@ -620,3 +915,7 @@ expansion, and refuses to build:
 - `lb-show` on a `<template>`, or on a row template's root
 - `lb-show` with no `lb-query` around it
 - `lb-show="!"` or `lb-show="!!column"`, which reverse no column
+- `lb-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 three commands
+- one of the three commands with no `commandfor`