@loadbare/app 0.8.2 → 0.10.0

package/docs/reference/data-binding.md

@@ -1,485 +1,490 @@
 # Data Binding
 
-A page binds its elements to server data with four attributes, and asks the
-server to change that data with one more. The developer writes all five into
-the HTML; the server declares which queries it answers and which operations
-it permits, and refuses anything it has not declared.
+A page shows server data by naming queries and columns in its HTML, and asks
+the server to change that data by naming requests. The developer writes
+seven `lb-` attributes. The server declares every query a page may show and
+every request it may send, and refuses anything it has not declared.
 
-One vocabulary and one containment ladder: a list holds rows, a row holds
-cells. A column is the second axis, and it is what the value of `lb-cell` or
-`lb-key` always holds.
+Everything is a query. A query is a name for rows, of kind `row` or `rows`,
+with a key column. The server declares all three, so the markup names the
+query and the columns it shows, and repeats neither kind nor key.
 
 ## A page that binds data
 
-Here is a page that binds a scalar, a list, and three requests:
+Here is a page that shows one row, lists rows, and sends three requests:
 
 ```html
 <!-- src/pages/members.page.html -->
+<title>Members</title>
 <h1>Members</h1>
 
-<p lb-row="dues">Dues collected this year: <span lb-cell="total"></span></p>
+<p lb-query="dues">Dues collected this year: <span lb-column="total"></span></p>
 
-<section lb-list="roster">
-  <form lb-action="lb-row-insert">
-    <input lb-cell="name" placeholder="Name" />
+<section lb-query="roster">
+  <form lb-request="lb-row-insert">
+    <input lb-column="name" placeholder="Name" />
     <button type="submit">Add member</button>
   </form>
 
   <ul>
-    <template lb-key="id">
+    <template>
       <li>
-        <lb-input lb-cell="name"></lb-input>
-        <button lb-action="lb-row-delete">Remove</button>
+        <input lb-column="name" lb-request="lb-row-update" />
+        <button lb-request="lb-row-delete">Remove</button>
       </li>
     </template>
   </ul>
 </section>
 ```
 
-The queries named here — `dues` and `roster` — and the operations the page
-asks for are declared on the server; see [page files](./page-files.md).
-
-## Binding
-
-| Attribute      | Written by  | Names                                                 |
-|----------------|-------------|-------------------------------------------------------|
-| `lb-list`      | a developer | The set of rows a subtree displays                    |
-| `lb-row`       | a developer | The one row a subtree displays                        |
-| `lb-key`       | a developer | The column that identifies a row                      |
-| `lb-cell`      | a developer | The column an element displays                        |
-| `lb-show`      | a developer | The column that decides whether an element is present |
-| `lb-key-value` | the hub     | A live row's own key                                  |
-| `lb-value`     | the hub     | The value that landed on a cell                       |
-
-A binding is scoped by ancestry. Either scope attribute scopes its DOM
-children, and a nested one of either kind begins a new scope, so an element
-binds to the name on its nearest ancestor carrying one, and to the row on its
-nearest ancestor carrying `lb-key-value`. Nothing else establishes scope: an
-element outside every scope is bound to nothing and displays nothing, and a
-result never crosses into a nested scope.
-
-Which of the two a subtree writes is not a choice about display. Cardinality
-is a property of the name, so one name answers with one shape, always. A page
-that shows the roster both as a set and as a single row declares two queries,
-`rosterList` and `rosterRow`, and binds each with the attribute that matches
-what it answers with.
-
-Bind an element to a cell by putting `lb-cell` on the element that shows the
-value. Its value is a column name and never a cell name: a cell has no name
-of its own, because it is identified by its row and its column, and the row
-arrives from scope. The scope's own root counts as a cell if it carries one,
-which is how an `<option>` — whose content model is text — displays the value
-it is.
-
-An element that carries a scope and `lb-cell` both is a cell of the scope
-around it. Its own `lb-list` or `lb-row` names what it displays, and its
-ancestors name where it belongs, so a `<select lb-list="accounts"
-lb-cell="account">` in a row displays the accounts and holds that row's
-`account`. The value lands on it and is gathered from it; the cells inside
-it are the accounts', and neither.
-
-Name the same query on more than one subtree to display it in more than one
-place. Every subtree gets the result.
-
-One name is the hub's rather than the server's: `lb-navigation`, one row
-landed on every navigation with the columns `page-label` and `page-uri`. It binds the
-same way. Its name is reserved, as every value beginning with `lb-` is in
-every `lb-` attribute: the server refuses a page that declares a query so
-named — see [Where the page is](./chrome.md#where-the-page-is).
-
-A key has a name and a value, and they are two attributes. `lb-key` on a row
-template names the column that identifies a row: it is a property of the
-list, since a list without a fixed key column is meaningless, written where
-the rows land. `lb-key-value` on a row that is showing carries that row's
-value of it. A developer writes the first and never the second.
-
-### Where a bound value lands
-
-A value lands on a bound element one of three ways.
-
-| Element                                | Receives the value as             |
-|----------------------------------------|-----------------------------------|
-| A custom element                       | Its `lb-value` attribute          |
-| `<select>`, `<textarea>`, or `<input>` | Its `value`, and `lb-value`       |
-| Any other native element               | Its `textContent`, and `lb-value` |
-
-A widget owns whatever control it wraps, so it is handed the value and
-renders it itself — see [Custom Elements](./custom-elements.md#code) for
-observing `lb-value`. A form control shows its state as its `value`, so a
-`<select>` keeps its options. Any other native element has no behavior of its
-own, so its value is its text. Checkboxes, radio buttons and file inputs
-receive nothing, not even `lb-value`, and the hub reports it to the console.
-
-Nothing an application writes ever sets `lb-value`. It is written by
-Loadbare and read by a widget or a stylesheet.
-
-### Lists
-
-Write `lb-list` on any element, and a `<template>` inside it carrying
-`lb-key`. The hub clones that template once per row, fills each clone, and
-reconciles what is showing against what arrived. No widget is involved, and
-none is needed.
-
-An array is the whole set, so it decides membership and order: a row whose
-key did not arrive is gone. A patch touches only the rows it names and leaves
-every other row's contents and position alone.
-
-A widget enters only where the rows need scaffolding or placement that only
-it can decide — a `<select>` that builds an `<optgroup>` per distinct value, a
-table that sections and sorts. Such a widget carries `lb-list` itself and
-implements one or both of two optional methods; see
-[Decorating a list](./custom-elements.md#decorating-a-list) and
-[The Basic Widget Library](./widgets.md).
-
-A scope with `lb-list` and no row template displays nothing, and that is not
-an error. It is bound to the list without showing it, which is what an insert
-form naming the list it adds a row to already is.
-
-## Requests
-
-One attribute turns an interaction into a request. `lb-action` names what the
-server is asked for: an action the page declared, or one of Loadbare's
-reserved names, which are the CRUD operations.
-
-One attribute name, one wire field, one set of values. The request field
-`action` carries this attribute's value verbatim, so nothing is translated
-between the markup and the server, and the CRUD key is the same value with
-the prefix stripped and the rest camel-cased.
-
-| Written                                   | Asks for     | Carries                       |
-|-------------------------------------------|--------------|-------------------------------|
-| `lb-action="name"`                        | That action  | The scope, and what is in it  |
-| `lb-action="lb-row-delete"`               | `rowDelete`  | `list`, `key`                 |
-| `lb-action="lb-row-insert"` on a `<form>` | `rowInsert`  | `list`, `values`              |
-| `lb-action="lb-row-update"` on a `<form>` | `rowUpdate`  | `list`, `key`, `values`       |
-| `lb-action="lb-row-update"` on a widget cell | `rowUpdate` | `list`, `key`, `values` of one cell |
-
-All three operations are list operations. Each needs a key, and a key exists
-only on a live row the hub stamped inside a list, so a single-row scope is
-read-only and a declared action is the only thing it can send. An application
-that wants a writable single row declares a list that answers with one row.
-
-A name beginning with `lb-` is reserved, in `lb-action` and in either scope
-attribute alike. The server refuses a page that declares an action or a query
-so named, which is what lets a reserved name be added later without colliding
-with one an application already uses. That reservation is also the whole of
-the wire discriminant: a value beginning with `lb-` is an operation, and
-anything else is a name the page declared.
-
-The hub sends a request from a native element on the element's own event: a
-form on submit, anything else on click. An insert or update clicked from a
-button reads the form or row the button is in (see [Forms](#forms)). To
-commit one cell as it changes, put `lb-row-update` on a widget cell instead
-(see [Committing one cell](#committing-one-cell)).
-
-Declare every action on the server, and permit every operation on its list. A
-name the page has not declared, and an operation a list does not permit, are
-refused; see
-[requests, actions, CRUD](./page-files.md#requests-actions-crud).
-
-### Actions
-
-Write `lb-action` on a button to ask the server to do something that is not
-one of the three CRUD operations:
+The server declares `dues` as a `row` query and `roster` as a `rows` query,
+each with its key, and permits the three requests on `roster`; see
+[page files](./page-files.md).
+
+| Attribute        | Goes on                       | Names                                          |
+|------------------|-------------------------------|------------------------------------------------|
+| `lb-query`       | Any element                   | The query whose rows land in it                |
+| `lb-column`      | Any element                   | The column it shows, and the column it gathers |
+| `lb-show`        | Any element but `<template>`  | The column that decides whether it is present  |
+| `lb-request`     | Any element                   | The request it sends when it commits           |
+| `lb-url-link`    | An `<a>`                      | A link between pages; see [chrome](./chrome.md#links) |
+| `lb-url-push`    | An element with `lb-request`  | A URL change that pushes a history entry       |
+| `lb-url-unknown` | A `<dialog>` in the chrome    | The dialog for a URL that names no page        |
+
+Every other `lb-` attribute in the document is a stamp. The hub or the
+builder writes a stamp, and a stylesheet or a custom element reads it.
+
+| Stamp                | Carries                                            |
+|----------------------|----------------------------------------------------|
+| `lb-column-value`    | The value the hub set from a column                |
+| `lb-key-value`       | The key of a live row, or of a `row` landed on an element |
+| `lb-query-row-count` | The number of live rows an element holds           |
+| `lb-request-pending` | The element's request is in flight                 |
+| `lb-request-error`   | The element's last request failed                  |
+| `lb-page`            | The stub of a page, on its `<template>`            |
+| `lb-page-title`      | The text of a page file's `<title>`                |
+
+The application should never name anything with the `lb-` prefix anywhere:
+no attribute, query, column, request, custom element or event.
+
+## Landing
+
+Write `lb-query` on an element to show a query there. Every response from
+the server carries response items, one per query, and the hub lands each on
+every element whose `lb-query` names its query. Name a query on as many
+elements as the page needs.
+
+What lands depends on the query's kind and on whether the element holds a
+row template, which is the first `<template>` among its descendants outside
+any nested `lb-query`:
+
+| Kind   | Row template | The hub                                |
+|--------|--------------|----------------------------------------|
+| `row`  | no           | Lands the row on the element itself    |
+| `row`  | yes          | Lands one live row                     |
+| `rows` | yes          | Lands one live row per row             |
+| `rows` | no           | Lands nothing                          |
+
+A live row is an element the hub cloned from a row template for one row.
+The hub stamps it with `lb-key-value`, the row's key. An element a `row`
+lands on itself carries `lb-key-value` as well.
+
+Write `lb-column` on each element that shows a column. The element reads
+from its nearest ancestor row: the live row it is in, or the element a
+`row` landed on. A nested `lb-query` begins a new query, and what is inside
+it reads from that query's rows.
+
+An element with `lb-query` and `lb-column` both shows the rows of its own
+query and holds the column of the row around it. This
+[`<lb-options>`](./widgets.md#lb-options) lists the accounts and holds its
+row's `account`:
 
 ```html
-<button lb-action="mailRoster">Mail the roster</button>
+<lb-options lb-query="accounts" lb-column="account">
+  <template><option lb-column="name"></option></template>
+</lb-options>
 ```
 
-An action carries whatever binding is in scope at the element — `list` or
-`row`, whichever scoped it, plus `key` and `cell` — and nothing else. There is
-no argument list. A button carries no value, so the server computes the whole
-of the new state and the page displays only what came back.
+`lb-column` on an element with `lb-query` is undefined unless the element is
+a control.
 
-Write `lb-action` on a widget to have the widget decide what performing the
-action means. Loadbare turns a click into a request for a native element
-only, and leaves a widget to send its own — a `<select>` performs its action
-on change, not on click.
+An element with `lb-column` and no ancestor row receives nothing. The hub
+still gathers from it, so an insert form writes `lb-column` on controls that
+no row fills.
 
-### Deleting a row
+### Where a column lands
 
-```html
-<button lb-action="lb-row-delete">Remove</button>
-```
+| Element                                              | Receives the value as                   |
+|------------------------------------------------------|-----------------------------------------|
+| `<input>`, `<select>`, `<textarea>`                  | Its `value`, 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` |
 
-`lb-row-delete` needs nothing declared. The row's `lb-list` and `lb-key-value`
-are already in scope, and they are all the server needs to know which row is
-meant and whether the list permits deleting it.
+A control is an `<input>`, `<select>` or `<textarea>`, or a form-associated
+custom element with a `value` property that fires `change`. The hub sets a
+control's `value`, and gathers it back under the same column. A custom
+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).
 
-The hub sends it from a native element. A widget sends its own request.
+A checkbox, a radio button and a file input receive nothing, and the hub
+reports it to the console.
 
-### Forms
+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.
 
-A `<form>` performs its `lb-action` on submit. `lb-row-insert` and `lb-row-update`
-both gather every `lb-cell` of the form into one values map, read from
-the control each cell is or wraps. A cell inside a scope nested in the form
-is that scope's and is not gathered, the same way a value landing on the
-form's row does not reach it. They differ in one thing: `lb-row-update`
-also carries the key of the row it is inside, and `lb-row-insert` carries none,
-because there is no row yet. A declared name on a form sends that action on
-submit, carrying the binding and no values.
+### Rows
 
-Put an `lb-row-update` form inside the row it edits, so it has that row's key
-from the same ancestor a delete button reads:
+Write a `<template>` inside the element carrying `lb-query`, holding one
+element: the row. The hub clones it once per row, fills each clone, and
+places it immediately before the template:
 
 ```html
-<template lb-key="id">
-  <li>
-    <form lb-action="lb-row-update">
-      <input lb-cell="name" />
-      <button type="submit">Save</button>
-    </form>
-  </li>
-</template>
+<ul lb-query="roster">
+  <template>
+    <li lb-column="name"></li>
+  </template>
+</ul>
 ```
 
-When an `lb-row-insert` succeeds, the hub resets every control it gathered
-from to its default, as `form.reset()` would, so the form is ready for the
-next entry. A failed insert leaves the entry for the user to correct, and a
-control the user changed while the request was in flight keeps the change.
-An `lb-row-update` resets nothing: the row it sent lands back on its cells.
+The hub matches each row to a live row by its key. All rows decide
+membership and order: a live row whose key did not arrive is removed. A
+patch changes only the rows it names, and every other live row keeps its
+content and its place.
+
+A live row's root counts as a column when it carries `lb-column`, which is
+how an `<option>`, whose content is text, shows the column it is.
+
+A custom element that carries `lb-query` and a row template may decide where
+a row goes and add scaffolding around the rows; see
+[Holding rows](./custom-elements.md#holding-rows) and
+[The Basic Widget Library](./widgets.md).
 
-Give every `lb-cell` in a form a control to read. A cell that is neither an
-`<input>`, `<select>`, or `<textarea>` nor wraps one is left out of the
-values map, and a form with no cell to read sends nothing.
+A `rows` query on an element with no row template lands nothing. That is the
+insert form above: it sits inside `lb-query="roster"` so its request is for
+`roster`, and it shows none of its rows.
 
-An insert or update gathers the row it belongs to: the nearest `<form>`,
-`<tr>` or live row around the element that sends it, inside its scope. A
-button submits its form the same way, whatever else sits beside it.
+### Counting rows
 
-A form cannot go around a table row's controls, so there the row is the
-form. Put the action on a button in the row, and it inserts every cell in
-the row, wherever in the row the button and the cells are:
+The hub stamps every element that holds a row template with
+`lb-query-row-count`, the number of live rows it holds. An empty query is a
+stylesheet rule:
 
 ```html
-<table lb-list="roster">
-  <tbody>
-    <tr>
-      <td><input lb-cell="name" /></td>
-      <td>
-        <input lb-cell="role" />
-        <button lb-action="lb-row-insert">Add</button>
-      </td>
-    </tr>
-  </tbody>
-</table>
+<div lb-query="roster">
+  <ul>
+    <template>
+      <li lb-column="name"></li>
+    </template>
+  </ul>
+  <p class="roster-empty">No members yet.</p>
+</div>
 ```
 
-An `lb-row-update` button in a live row saves that row and no other, and a
-form nested in a row gathers only the form. Anywhere else, write the form:
-cells and a button in a `<div>` belong to no row, so the hub refuses the
-request and says to put them in a `<form>`.
+```css
+.roster-empty {
+  display: none;
+}
+[lb-query-row-count="0"] .roster-empty {
+  display: revert;
+}
+```
 
-Put these two actions on a form or a button, not on an element that holds
-the cells. A click into one of its inputs would send the row, so the hub
-refuses it. A widget may dispatch either from any element, and the hub
-gathers the same way; see
-[Sending a request](./custom-elements.md#sending-a-request).
+The element carrying `lb-query` is a `<div>` here rather than the `<ul>`, so
+that the message is inside it and one rule reaches both.
 
-### Committing one cell
+## Conditional rendering
 
-Put `lb-row-update` on a widget that carries `lb-cell` to save that one cell
-whenever it changes. The shipped `<lb-input>` sends it on `change`:
+A page holds every element it can show. Write `lb-show` on an element,
+naming the column that decides whether it is present:
 
 ```html
-<template lb-key="id">
+<template>
   <tr>
-    <td><lb-input lb-cell="name" lb-action="lb-row-update"></lb-input></td>
-    <td><lb-input lb-cell="note" lb-action="lb-row-update"></lb-input></td>
+    <td lb-column="name"></td>
+    <td><button lb-request="lb-row-delete" lb-show="removable">Remove</button></td>
   </tr>
 </template>
 ```
 
-An element carrying `lb-cell` is a record of one cell, the way a control has
-a value and a form has values. Its update carries `values` holding that cell
-alone, so an edit in one input never sends the other. It reaches the same
-`rowUpdate` a form does. SQL has one UPDATE whether it sets one column or
-many, and the application writes one handler for both.
+```sql
+(ledger_count = 0 AND system_behavior IS NULL) AS removable
+```
+
+A value of `null` or `false` takes the element out of the page, and any other
+value puts it back. The hub never reads a string, so `"false"` is present:
+have the query answer with a boolean or a null. A row that does not carry
+the column leaves the element as it is, so a query answers with the column
+in every row.
 
-The widget decides when the cell has changed. A native `<input>` carrying
-`lb-cell` and `lb-row-update` has no such moment, since a click into it
-would send it, so the hub refuses it and says so.
+`lb-show` reads from the nearest ancestor row, as `lb-column` does. On an
+element that also carries `lb-query`, the column belongs to the row around
+it, so this picker takes its choices from `groups` and whether it is present
+from the account row:
 
-Leave `lb-action` off a widget inside an `lb-row-insert` or `lb-row-update`
-form. The form reads every `lb-cell` in it on submit, so a widget that also
-sent its own would write the same edit twice.
+```html
+<lb-options lb-query="groups" lb-column="group_id" lb-show="group_choice">
+  <template><option lb-column="name"></option></template>
+</lb-options>
+```
+
+An element may show a column and be decided by it, which shows a note only
+when there is one:
 
-## Query parms
+```html
+<span lb-column="note" lb-show="note"></span>
+```
 
-A control that narrows what the page shows writes its value into the query
-string instead of sending a request. `lb-query-parm` names the parm:
+A condition that is only a style is a class on an element that is present or
+not:
 
 ```html
-<select lb-query-parm="team">
-  <option value="">Every team</option>
-  <option value="Engines">Engines</option>
-</select>
+<span lb-show="out_of_balance" class="danger">Out of balance</span>
 ```
 
-On `change` the hub sets that one parm in the URL, leaving every other parm
-alone, and takes it out when the value is empty. The write replaces the
-current history entry; add `lb-query-parm-push` to push one instead. The page
-then loads at the new URL, exactly as a cold load of it would, without
-replacing its DOM.
+A condition that is not data, such as a collapsed section or an open menu,
+has no column. Use `<details>`, a stylesheet, or a custom element. Every
+element set from a column carries the value as `lb-column-value`, for a
+stylesheet to select on.
 
-After every load the hub lands each parm on the control that writes it, and
-an absent parm lands empty, so the control shows what the address bar says.
+An element that is not present cannot be clicked. The server still refuses
+what a request may not do.
 
-A control that writes a query parm sends no request, and one that also
-carries `lb-action` has that request refused.
+### Where an absent element is
 
-The server reads the parms off `req.query` in `contextFor`; see
-[the Express server](./server.md#database-layer). See
-[Query parms](../TECHREF-1.0.md#query-parms) for the whole rule.
+The hub moves an element whose column is off into a `<template lb-show>`
+that stands where it stood, and moves it back out when the column turns on.
+The builder ships every `lb-show` element already inside its template, so
+nothing conditional shows until its row has landed. The developer never
+writes that template.
 
-## Conditional rendering
+- Nothing renders it, whatever a stylesheet says.
+- It cannot be focused or clicked, assistive technology does not announce it,
+  and the hub does not gather from it.
+- It is moved rather than rebuilt, so a custom element keeps its instance and
+  a control keeps what was typed into it.
+- Rows keep landing on it and on everything inside it while it is away, so it
+  returns current.
 
-Loadbare ships static HTML and hydrates elements that are already in the
-document. There is no `if`, and none is needed: write every possibility into
-the page, and let a column decide which of them is present.
+An absent element keeps its place among its siblings, so a position selector
+(`:first-child`, `:nth-child`, `:empty`, `+`, `~`) counts its template as a
+sibling. A selector by tag, class or attribute is unaffected.
 
-Write `lb-show` on an element, naming the column that decides it:
+## Requests
+
+Write `lb-request` on an element to send a request when the element commits.
+Its value is the request name: one of the three requests Loadbare provides,
+or a name the page declares.
 
 ```html
-<template lb-key="id">
-  <tr>
-    <td lb-cell="name"></td>
-    <td><button lb-action="lb-row-delete" lb-show="removable">Remove</button></td>
-  </tr>
-</template>
+<button lb-request="mailRoster">Mail the roster</button>
 ```
 
-```sql
-(ledger_count = 0 AND system_behavior IS NULL) AS removable
+Every request has one shape:
+
+```json
+{ "name": "lb-row-update", "query": "roster", "key": "17", "values": { "name": "Ada" } }
 ```
 
-A value of `null` or `false` takes the element out of the page, and any other
-value puts it back. The hub never reads a string, so `"false"` is a value like
-any other: have the query answer with a boolean or a null. A row that does not
-carry the column leaves the element as it is, so a query that answers with
-whole rows returns the column in every row.
+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
+answers with response items, which land like any others.
+
+### Committing
+
+| Element          | Commits on                                 |
+|------------------|--------------------------------------------|
+| A `<form>`       | `submit`                                   |
+| A control        | `change`                                   |
+| Any other element | `click`                                   |
 
-`lb-show` binds the way `lb-cell` does, to the row on its nearest scoped
-ancestor. On an element that is itself a scope, the column belongs to the
-row around it, so this picker takes its choices from `groups` and whether it
-is present from the account row:
+A click inside an element carrying `lb-request` commits it unless the click
+lands on interactive content between them: a link, a button, a control or a
+label, as HTML defines interactive content. A click into an input inside a
+deletable row focuses the input.
+
+A submit button with a form owner commits with its form. On `submit`, the
+hub sends the submitter's `lb-request` when the submitter carries one, and
+the form's otherwise, the way `formaction` overrides `action`:
 
 ```html
-<select lb-list="groups" lb-cell="group_id" lb-show="group_choice">
+<template>
+  <li>
+    <form lb-request="lb-row-update">
+      <input lb-column="name" />
+      <button type="submit">Save</button>
+      <button type="submit" lb-request="lb-row-delete">Remove</button>
+    </form>
+  </li>
+</template>
 ```
 
-An element may show a column and be decided by it, which shows a note only
-when there is one:
+A control carrying `lb-request` sends on every `change`, which for an
+`<input>` is when the user leaves it with a new value.
+
+### Gathering
+
+The hub gathers each control's value under the column its `lb-column` names.
+It gathers from one group, the first of these that applies to the element
+carrying `lb-request`:
+
+1. The element carries `lb-column`: the element alone.
+2. The element is a `<form>`: every control whose form owner is the form.
+3. The element is in a live row: every control in that live row.
+4. Otherwise: every control whose form owner is the element's form owner.
+
+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
+form that names it with the HTML `form` attribute, which is how a table row,
+where a form cannot go, sends one:
 
 ```html
-<span lb-cell="note" lb-show="note"></span>
+<form id="add-member" lb-request="lb-row-insert"></form>
+<table lb-query="roster">
+  <tbody>
+    <template>
+      <tr><td lb-column="name"></td><td lb-column="role"></td></tr>
+    </template>
+  </tbody>
+  <tfoot>
+    <tr>
+      <td><input lb-column="name" form="add-member" /></td>
+      <td>
+        <input lb-column="role" form="add-member" />
+        <button form="add-member">Add</button>
+      </td>
+    </tr>
+  </tfoot>
+</table>
 ```
 
-An element that is not present cannot be clicked, but that is presentation:
-the server still refuses what a request may not do.
+The hub sends the request for the nearest ancestor `lb-query` of the
+controls it gathered, and takes `key` from their nearest ancestor row when
+that row is of the same query. When it gathers nothing, it uses the nearest
+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.
 
-### Where an absent element is
+### Inserting, updating and deleting rows
 
-An element whose column is off is moved into a `<template lb-show>` that
-stands where it stood, and moved back out when the column turns on. The
-developer never writes that template.
+Loadbare provides three requests. Each runs the handler the page declares
+for its query under `crud`; see [page files](./page-files.md#crud).
 
-- Nothing renders it, whatever a stylesheet says, because a template's content
-  is not its children.
-- It cannot be focused or clicked, assistive technology does not announce it,
-  and a form does not gather it.
-- It is moved, never rebuilt, so a widget keeps its instance and a control
-  keeps what was typed into it.
-- Values keep landing on it, and on every cell and scope inside it, while it
-  is away, so it returns current.
+| Request name    | Needs                    | Runs        |
+|-----------------|--------------------------|-------------|
+| `lb-row-insert` | `query`, `values`        | `rowInsert` |
+| `lb-row-update` | `query`, `key`, `values` | `rowUpdate` |
+| `lb-row-delete` | `query`, `key`           | `rowDelete` |
 
-The builder ships every `lb-show` element already inside its template, so
-nothing conditional shows until its row has landed.
-
-A condition never changes the structure of a page. An absent element keeps
-its place among its siblings, so a position selector (`:first-child`,
-`:nth-child`, `:empty`, `+`, `~`) counts its template as a sibling. A selector
-by tag, class or attribute is unaffected. Only a list changes a page's
-structure.
+The hub sends one of these only when it has what the table lists, and
+otherwise reports to the console. An insert or an update that gathers
+nothing is not sent.
 
-A condition that is only a style is a class on an element that is present or
-not:
+A key comes from a live row, or from an element a `row` landed on, so all
+three work against either kind:
 
 ```html
-<span lb-show="out_of_balance" class="danger">Out of balance</span>
+<form lb-query="profile" lb-request="lb-row-update">
+  <input lb-column="email" />
+  <button type="submit">Save</button>
+</form>
 ```
 
-These are build errors:
+An update from a single control sends that control's column alone. An
+update from a form or a live row sends every control it gathers. The
+application writes one `rowUpdate` for both, setting the columns `values`
+names, as an SQL UPDATE does.
 
-- `lb-show` on a row template's root. A row that should not show is left out
-  by the query.
-- `lb-show` with no row around it: outside every scope, on a scope with none
-  around it, or in a list scope outside its row template, where nothing lands.
-- `lb-show` on a `<template>`.
+After a successful insert gathered from a form, the hub resets the form. A
+failed insert leaves the entry for the user to correct.
 
-A condition that is not data, such as a collapsed section or an open menu,
-has no column. Use `<details>`, a stylesheet, or a widget. Every cell still
-carries the value that landed on it as `lb-value`, for a widget to read or a
-stylesheet to select on.
+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.
 
-### An empty list
+### Declared requests
 
-The hub stamps every list scope with `lb-row-count`, the number of rows it is
-showing. It is the one conditional a page cannot be sent, because the server
-answers with rows and says nothing about how many survived. It makes an empty
-list a stylesheet rule rather than code anywhere:
+A request name the page declares under `handlers` runs the application's
+handler; see [page files](./page-files.md#handlers). It gathers the same way
+and carries `query`, `key` and `values` when it finds them:
 
 ```html
-<div lb-list="roster">
-  <ul>
-    <template lb-key="id">
-      <li lb-cell="name"></li>
-    </template>
-  </ul>
-  <p class="roster-empty">No members yet.</p>
-</div>
+<template>
+  <li>
+    <span lb-column="name"></span>
+    <button lb-request="sendReminder">Remind</button>
+  </li>
+</template>
 ```
 
+A button carries no value, so a declared request from one sends the values
+of the live row or form it sits in, and the server computes the rest.
+
+A request name beginning with `lb-` that is not one of the three is refused
+by the builder.
+
+### Request state
+
+The hub stamps the element that committed:
+
+| Stamp                | Means                                         |
+|----------------------|-----------------------------------------------|
+| `lb-request-pending` | The round trip is in flight                   |
+| `lb-request-error`   | The round trip failed, until the next request |
+
+`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
+`aria-busy="true"` for as long as `lb-request-pending` is present.
+
+The hub ignores a commit on an element carrying `lb-request-pending`, so a
+pending button is already disabled and a stylesheet only shows it:
+
 ```css
-.roster-empty {
-  display: none;
+[lb-request-pending] {
+  opacity: 0.5;
 }
-[lb-row-count="0"] .roster-empty {
-  display: revert;
+[lb-request-error] {
+  outline: 2px solid red;
 }
 ```
 
-The scope is a `<div>` here rather than the `<ul>`, so that the empty message
-is inside it and the same rule can reach both.
+### The request event
 
-## Request state
+The hub dispatches every request as a bubbling `lb-request` event from the
+element that committed, with the request as its `detail`, before sending it.
+An ancestor may stop the event, and the request is not sent. A custom
+element may dispatch the event itself; see
+[Sending a request](./custom-elements.md#sending-a-request).
 
-Loadbare stamps two attributes on the element a request came from — the
-button, the form, or the widget itself:
+## The URL
 
-| Attribute         | Means                                     |
-|-------------------|-------------------------------------------|
-| `lb-pending` | The request is in flight                  |
-| `lb-error`   | The last request from this element failed |
+The hub serves one query of its own, `lb-url`: one row holding the path, the
+page's title, and every query parm as a column. A control inside
+`lb-query="lb-url"` that sends `lb-row-update` sets a query parm, and the hub
+answers it with no round trip:
 
-`lb-pending` is set when the request goes out and removed when it
-settles. `lb-error` is set on a failed response, a network failure, or
-a timeout alike, and cleared when that element sends its next request.
+```html
+<div lb-query="lb-url">
+  <select lb-column="team" lb-request="lb-row-update">
+    <option value="">Every team</option>
+    <option value="Engines">Engines</option>
+  </select>
+</div>
+```
 
-Neither one carries any meaning beyond the fact it states. Dim a pending
-button in a stylesheet, or have a widget watch its own attributes and
-disable itself. An application that styles neither behaves correctly and
-shows nothing.
+See [The URL](./chrome.md#the-url) for its columns, links, history, and the
+unknown-page dialog.
 
-A native button or form pressed again while it carries `lb-pending` is
-ignored, so a pending one is already disabled and the stylesheet only shows
-it. A widget is not held back, since one that sends on change must send its
-latest value. The hub also sets `aria-busy="true"` for as long as
-`lb-pending` is present.
+## The markup checks
 
-## Sending a request from a widget
+The developer writes `lb-` attributes in markup, and script never assigns
+them. The builder checks the markup of the chrome and of every page, after
+expansion, and refuses to build:
 
-A widget can build and dispatch a request itself instead of carrying one of
-the attributes above — which is what `<lb-input>` does, and what a widget
-carrying `lb-action` must do. See
-[Custom Elements](./custom-elements.md#code).
+- an `lb-` attribute that is not one of the seven the developer writes
+- `lb-request` naming an `lb-` request other than the three Loadbare provides
+- `lb-url-link` on anything but an `<a>`
+- `lb-url-push` on an element without `lb-request`
+- `lb-url-unknown` on anything but a `<dialog>`, or outside `<lb-hub>`
+- `lb-show` on a `<template>`, or on a row template's root
+- `lb-show` with no `lb-query` around it