@loadbare/app 0.13.0 → 0.14.0

package/skills/loadbare-app/references/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.
 
@@ -782,9 +790,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 +864,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 +879,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 +945,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 +961,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
@@ -935,6 +1123,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 +1171,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 +1440,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 +1453,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 +1637,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 +1813,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 {
@@ -1791,6 +2040,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 +2057,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 +2066,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 +2076,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 +2104,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
@@ -1906,9 +2171,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 +2189,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` |

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