@loadbare/app 0.5.5 → 0.6.0

package/docs/reference/builder.md

@@ -40,7 +40,7 @@ The builder classifies by name, not location.
 |----------------------------|---------------------------------------------------|
 | `chrome.html`              | The chrome — see [`chrome.html`](./chrome.md)     |
 | `*.page.html`              | A page                                            |
-| `*.hooks.ts`               | A page's hooks, matched by base name              |
+| `*.requests.ts`               | A page's requests, matched by base name              |
 | `*.queries.ts`             | A page's queries, matched by base name            |
 | `imports.ts`               | The packages this app takes widgets from          |
 | `*.css`                    | A stylesheet — see [CSS](./css.md)                |
@@ -48,7 +48,7 @@ The builder classifies by name, not location.
 | `<tag>.browser.ts`         | A widget script, named for the tag it registers   |
 
 Give the application exactly one `chrome.html` and at most one `imports.ts`.
-Give every `.hooks.ts` and `.queries.ts` a `.page.html` of the same base name.
+Give every `.requests.ts` and `.queries.ts` a `.page.html` of the same base name.
 
 Name a widget script `<tag>.browser.ts`, not `<tag>.ts`. Only a file whose
 name carries `.browser` is bundled for the browser; every other module under
@@ -125,10 +125,10 @@ A tag with neither a script nor a definition in any origin is an error.
 The builder expands the chrome and every page against the available widget
 definitions — see [Custom Elements](./custom-elements.md#html) for the
 substitution rules — wraps each expanded page in
-`<template id="page-<name>">`, and splices them into the chrome's `<body>`. It formats the result with
+`<template lb-page="<name>">`, and splices them into the chrome's `<body>`. It formats the result with
 Prettier when the application has it installed.
 
 The builder writes `app.css` only when it finds a stylesheet, and `pages.ts`
-only when some page has a `.hooks.ts` or a `.queries.ts` file. Import `hub`
+only when some page has a `.requests.ts` or a `.queries.ts` file. Import `hub`
 from `pages.ts` — see [The Express Server](./server.md) for the rest of the
 wiring.

package/docs/reference/chrome.md

@@ -24,15 +24,18 @@ Here is a minimal but fully complaint chrome for a typical app:
   </head>
   <body hidden>
     <lb-hub>
-      <header><h1>Membership Roster</h1></header>
+      <header lb-row="lb-navigation">
+        <h1>Membership Roster</h1>
+        <h2 lb-cell="page-label"></h2>
+      </header>
       <nav>
         <a href="/" lb-nav-link>Home</a>
         <a href="/members" lb-nav-link>Members</a>
         <a href="https://example.org/">Our website</a>
       </nav>
       <main></main>
-      <dialog lb-unknown-page>
-        The page <span lb-cell="page"></span> is not in this app.
+      <dialog lb-unknown-page lb-row="lb-navigation">
+        The URL <span lb-cell="page-uri"></span> is not in this app.
       </dialog>
     </lb-hub>
   </body>
@@ -57,6 +60,7 @@ Everything else is optional:
 |-------------------------------------------|---------------------------------------------|
 | `<link rel="stylesheet" href="/app.css">` | The bundled stylesheet                      |
 | `<a lb-nav-link>`                         | Navigation between pages                    |
+| `lb-row="lb-navigation"`                | Where the page is — see below               |
 | `<dialog lb-unknown-page>`                | A message when a URL matches no page        |
 | Custom elements                           | The chrome, decomposed into widget files    |
 | `<body hidden>` + a `<noscript>` fallback | Avoids a first-load blink — see below       |
@@ -73,8 +77,55 @@ A navigation anchor's `href` is a path, and the path names a page:
 landing page is the one named `index.page.html`. An anchor without
 `lb-nav-link` is left alone and behaves like any other link.
 
-The `lb-unknown-page` attribute, if used, must appear on a `<dialog>`.
-Inside it, `lb-cell="page"` shows the name of the page that was asked for.
+The `lb-unknown-page` attribute, if used, must appear on a `<dialog>` inside
+`<lb-hub>`; the builder rejects it anywhere else. The hub opens it when a
+path names no page. What it says is up to the chrome:
+the dialog is a subtree like any other, and it displays where the page is by
+naming the hub's own query, described next.
+
+## Where the page is
+
+On every navigation the hub lands a query of its own, `lb-navigation`, on
+any subtree inside the hub that names it. It arrives the way a server's
+row arrives — `lb-row` on the subtree, `lb-cell` on each element that
+shows a value — so a chrome displays the current page with no code at all:
+
+```html
+<header lb-row="lb-navigation">
+  <h1>Membership Roster</h1>
+  <h2 lb-cell="page-label"></h2>
+</header>
+```
+
+| Cell         | Holds                                                     |
+|--------------|-----------------------------------------------------------|
+| `page-label` | The text of the `lb-nav-link` anchor for the path, or empty if none |
+| `page-uri`   | The path as the browser has it, such as `/members`        |
+
+The label is the nav's. The hub takes it from the first `lb-nav-link`
+anchor whose `href` names the current page, so a click, a reload and the
+back button all land the same text, and a path no anchor names lands an
+empty label. A chrome that shows the label somewhere fixed should expect
+that case for a page reachable only by URL.
+
+The `lb-` prefix on the query name is what keeps it out of the server's
+namespace: no server answers a query so named. It is landed only where a
+subtree names it, so a chrome that displays no navigation is not warned
+about a query with no scope.
+
+The same row is what an unknown-page dialog has to work with. It lands
+before the page host is looked up, so a miss has it too. Name the query on
+the dialog and show whichever cell fits:
+
+```html
+<dialog lb-unknown-page lb-row="lb-navigation">
+  The URL <span lb-cell="page-uri"></span> is not in this app.
+</dialog>
+```
+
+`@loadbare/widgets` ships this dialog as a widget, `<lb-unknown-page>`, for a
+chrome that would rather write one tag — see
+[The Basic Widget Library](./widgets.md#lb-unknown-page).
 
 ## Preventing the first-load blink
 

package/docs/reference/custom-elements.md

@@ -86,6 +86,14 @@ value is a placeholder is removed rather than shipped empty, which is how
 placeholder in a text node resolves to nothing, and the whitespace around
 it survives.
 
+Give a placeholder a default with a pipe: `{{button-text|OK}}` reads
+`exp-button-text` when the tag supplies it and `OK` when it does not. The
+default is a literal, not an expression. Whitespace around the name and the
+default is not part of either, so `{{ button-text | OK }}` is the same
+placeholder. An empty default, `readonly="{{readonly|}}"`, is the one that
+differs from no default at all: it emits the attribute, empty, rather than
+dropping it, so a definition can ship a boolean attribute switched on.
+
 Every attribute stays on the tag after expansion, `exp-` ones included.
 
 Parameter values reach a definition through the DOM rather than through
@@ -215,12 +223,15 @@ as a string literal.
 |------------------|------------|
 | `ATTR_VALUE`     | `lb-value` |
 | `ATTR_CELL`      | `lb-cell`  |
-| `ATTR_QUERY`     | `lb-query` |
+| `ATTR_LIST`      | `lb-list`  |
+| `ATTR_ROW`       | `lb-row`   |
 | `ATTR_KEY`       | `lb-key`   |
-| `ATTR_GROUP`     | `lb-group` |
-| `ATTR_SORT`      | `lb-sort`  |
+| `ATTR_KEY_VALUE` | `lb-key-value` |
 | `ATTR_ACTION`    | `lb-action`|
-| `ATTR_ROW_COUNT` | `data-rows`|
+| `ACTION_ROW_INSERT`, `ACTION_ROW_DELETE`, `ACTION_ROW_UPDATE`, `ACTION_CELL_CHANGE` | the reserved `lb-action` values |
+| `LB_ACTIONS`     | all four of them, in one array |
+| `LB_RESERVED_PREFIX` | `lb-`, the prefix every reserved name begins with |
+| `ATTR_ROW_COUNT` | `lb-row-count`|
 | `LB_EVENT_NAME`  | `lb-request` |
 
 ### Receiving a value
@@ -258,20 +269,20 @@ click — builds its own request and dispatches it as a bubbling
 as its `detail`:
 
 ```ts
-import { ATTR_CELL, ATTR_KEY, ATTR_QUERY, LB_EVENT_NAME } from "@loadbare/app/constants";
+import { ATTR_CELL, ATTR_KEY_VALUE, ATTR_LIST, LB_EVENT_NAME } from "@loadbare/app/constants";
 import type { HubRequest } from "@loadbare/app/types";
 
 const detail: HubRequest = {
-  op: "cell-change",
-  query: this.closest(`[${ATTR_QUERY}]`)!.getAttribute(ATTR_QUERY)!,
-  key: this.closest(`[${ATTR_KEY}]`)!.getAttribute(ATTR_KEY)!,
+  action: "lb-cell-change",
+  list: this.closest(`[${ATTR_LIST}]`)!.getAttribute(ATTR_LIST)!,
+  key: this.closest(`[${ATTR_KEY_VALUE}]`)!.getAttribute(ATTR_KEY_VALUE)!,
   cell: this.getAttribute(ATTR_CELL)!,
   value: input.value,
 };
 this.dispatchEvent(new CustomEvent(LB_EVENT_NAME, { bubbles: true, detail }));
 ```
 
-Find `query` and `key` by walking up with `closest()`, the same way the hub
+Find the scope name and `key` by walking up with `closest()`, the same way the hub
 finds the binding for a native element. See
 [Data Binding](./data-binding.md#requests) for the request vocabulary and
 what each operation carries.
@@ -280,54 +291,66 @@ Let the event bubble, so an ancestor widget can intercept and stop it before
 the hub sees it. A hand-written widget and a native element carrying
 `lb-action` produce the same event.
 
-### Accepting rows
+### Decorating a list
+
+The hub reconciles every list scope itself. A plain element carrying
+`lb-list` with a row template inside it is a whole list and needs no widget,
+so a widget exists only when the rows need scaffolding or placement that
+only it can decide.
 
-A query answering with many rows is delivered to whichever element carries
-an `acceptRows` method. It is a protocol, not a tag name — the hub tests for
-the method and never for the element:
+Two optional methods say what it decides. Both are named in the `lb`
+namespace, which Loadbare reserves for methods it calls on classes it does
+not own, so a widget's own methods can never collide with a later one:
 
 ```ts
-import { applyRows } from "@loadbare/app/rows";
-import type { Projection, HubRowHost } from "@loadbare/app/types";
+import type { ListHost, Row } from "@loadbare/app/types";
 
-class UpdateList extends HTMLElement implements HubRowHost {
-  acceptRows(result: Projection) {
-    applyRows(this, result);
+class SortedList extends HTMLElement implements ListHost {
+  lbPlaceRow(el: Element, row: Row, template: HTMLTemplateElement) {
+    // Where this row goes. Called with the element detached, on its first
+    // appearance and again whenever a whole set decides the order.
+  }
+
+  lbRowsLanded() {
+    // Once, after the result has landed. For scaffolding derived from the
+    // rows: a section heading, an <optgroup>, anything that goes when its
+    // last row does.
   }
 }
 ```
 
-Call `applyRows(scope, result, place?)` rather than reimplementing rows.
-Every built-in list widget uses it, and it settles four things:
+Everything else is the hub's, and a widget never reimplements it:
 
-| Concern     | What `applyRows` does                                   |
+| Concern     | What the hub does                                       |
 |-------------|---------------------------------------------------------|
-| Cloning     | Clones the `<template lb-key="...">` in the widget      |
+| Cloning     | Clones the `<template lb-key="...">` in the scope       |
 | Matching    | Updates the row already showing that key, or clones one |
 | Reconciling | Removes the rows the response says are gone             |
-| Counting    | Stamps `data-rows` with the number of rows showing      |
+| Counting    | Stamps `lb-row-count` with the number of rows showing   |
 
-`rows` is the whole set, so it decides membership and order, and a key
-absent from it is removed. `patch` touches only the rows it names and leaves
+An array is the whole set, so it decides membership and order, and a key
+absent from it is removed. A patch touches only the rows it names and leaves
 every other row's contents and position alone.
 
-Supply a `place` function to decide where a row goes — `(row, tuple,
-template) => void`, called with a fresh or reordered row. The default
-inserts immediately before the template, so rows accumulate in arrival
-order. A widget that groups or sorts supplies its own `place` instead of
-reimplementing matching and cloning around it; `lb-options.browser.ts` and
-`lb-table.browser.ts` in [`@loadbare/widgets`](./widgets.md) are two different
-`place` functions over the same `applyRows`.
+`lbPlaceRow` is called with the row already filled and not yet in the
+document, so a widget that reads a cell to decide where the row goes can. A
+scope without it lands rows immediately before the template, in arrival
+order. `lb-options.browser.ts` and `lb-table.browser.ts` in
+[`@loadbare/widgets`](./widgets.md) are two different placements over the
+same machinery.
+
+A list scope with no row template displays nothing, which is not an error: an
+insert form names the list it adds a row to and has no rows of its own.
 
-Style an empty list against `data-rows` rather than carrying an empty-state
+Style an empty list against `lb-row-count` rather than carrying an empty-state
 conditional in the widget — see
 [Conditional rendering](./data-binding.md#conditional-rendering).
 
 ### Filling a scope by hand
 
-`@loadbare/app/rows` also exports `applyTuple(root, cells)`, the same
-tuple-landing operation a page host uses. Call it in a widget that builds
-its own rows or scopes rather than relying on `acceptRows`. It fills `root`
+`@loadbare/app` also exports `applyRow(root, row)`, the same row-landing
+operation a page host uses. Call it in a widget that builds a scope of its
+own rather than one the hub reconciles. It fills `root`
 itself when `root` carries a matching `lb-cell`, and every matching
 descendant.
 </content>

package/docs/reference/data-binding.md

@@ -1,10 +1,14 @@
 # Data Binding
 
 A page binds its elements to server data with four attributes, and asks the
-server to change that data with four more. The page writes all eight into
-its HTML; the server declares which queries it answers and which operations
+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.
 
+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.
+
 ## A page that binds data
 
 Here is a page that binds a scalar, a list, and three requests:
@@ -13,23 +17,21 @@ Here is a page that binds a scalar, a list, and three requests:
 <!-- src/pages/members.page.html -->
 <h1>Members</h1>
 
-<p lb-query="dues">Dues collected this year: <span lb-cell="total"></span></p>
+<p lb-row="dues">Dues collected this year: <span lb-cell="total"></span></p>
 
-<form lb-insert lb-query="roster">
+<form lb-action="lb-row-insert" lb-list="roster">
   <input lb-cell="name" placeholder="Name" />
   <button type="submit">Add member</button>
 </form>
 
-<lb-list lb-query="roster">
-  <ul>
-    <template lb-key="id">
-      <li>
-        <lb-input lb-cell="name"></lb-input>
-        <button lb-delete>Remove</button>
-      </li>
-    </template>
-  </ul>
-</lb-list>
+<ul lb-list="roster">
+  <template lb-key="id">
+    <li>
+      <lb-input lb-cell="name"></lb-input>
+      <button lb-action="lb-row-delete">Remove</button>
+    </li>
+  </template>
+</ul>
 ```
 
 The queries named here — `dues` and `roster` — and the operations the page
@@ -37,28 +39,49 @@ asks for are declared on the server; see [page files](./page-files.md).
 
 ## Binding
 
-| Attribute  | Names                                                    |
-|------------|----------------------------------------------------------|
-| `lb-query` | The query a subtree displays                             |
-| `lb-key`   | The cell that identifies a row, and a live row's own key |
-| `lb-cell`  | The cell an element displays                             |
-| `lb-value` | Where a widget receives its value                        |
-
-A binding is scoped by ancestry. An element binds to the query on its
-nearest ancestor carrying `lb-query`, and to the row on its nearest ancestor
-carrying `lb-key`. Nothing else establishes scope: an element outside every
-`lb-query` is bound to nothing and displays nothing.
+| 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-key-value` | the hub     | A live row's own key                      |
+| `lb-value`     | the hub     | Where a widget receives its value         |
+
+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. 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.
+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.
 
 Name the same query on more than one subtree to display it in more than one
 place. Every subtree gets the result.
 
-`lb-key` holds one name in two positions. On a row template it names the
-cell that identifies a row; on a row that is showing, it carries that row's
-key value. A template is never a row, so the two never collide.
+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
 
@@ -77,40 +100,71 @@ observing `lb-value`.
 Nothing an application writes ever sets `lb-value`. It is written by
 Loadbare and read by the widget it is written on.
 
-### Rows
-
-A query that answers with many rows is delivered to a list widget, which
-clones its row template once per row and binds each clone to one row. A
-native element has one destination for a value and cannot acquire children,
-so a query that answers with rows must be bound to a widget that accepts
-them.
+### Lists
 
-Bind the widget to the query with `lb-query`, and name the key cell on the
-`<template>` inside it with `lb-key`. See
-[The Basic Widget Library](./widgets.md) for the widgets that accept
-rows, and for `lb-group` and `lb-sort`, which a list widget reads to decide
-where a row goes.
+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.
 
-## Requests
+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.
 
-Four attributes turn an interaction into a request:
+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).
 
-| Written                   | Asks for         | Carries                      |
-|---------------------------|------------------|------------------------------|
-| `lb-action="name"`        | The named action | `name`, and what is in scope |
-| `lb-delete`               | `tupleDelete`    | `query`, `key`               |
-| `lb-insert` on a `<form>` | `tupleInsert`    | `query`, `values`            |
-| `lb-update` on a `<form>` | `tupleUpdate`    | `query`, `key`, `values`     |
+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.
 
-The shipped `<lb-input>` widget asks for a fifth, `cellChange`, carrying
-`query`, `key`, `cell`, and `value`. It sends one when the page applies
-`data-fire-on-change` to it, and stays quiet otherwise — an input inside an
-`lb-insert` or `lb-update` form is read again by the form on submit, so a
-widget that sent on its own would write the same edit twice.
+## Requests
 
-Declare every one of these on the server. A name the page has not declared,
-and an operation a query does not permit, are refused; see
-[hooks, actions, CRUD](./page-files.md#hooks-actions-crud).
+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-cell-change"` on a widget  | `cellChange` | `list`, `key`, `cell`, `value`|
+
+All four 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 the first four from a native element on the element's own
+event: a form on submit, anything else on click. A cell change needs a
+widget to say what a change is, so only a widget sends it: the shipped
+`<lb-input>` does when it carries `lb-action="lb-cell-change"`, and stays
+quiet otherwise — an input inside an `lb-row-insert` or `lb-row-update` form is read
+again by the form on submit, so a widget that sent on its own would write
+the same edit twice.
+
+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
 
@@ -121,10 +175,10 @@ one of the four CRUD operations:
 <button lb-action="mailRoster">Mail the roster</button>
 ```
 
-An action carries whatever binding is in scope at the element — `query`,
-`key`, `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.
+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.
 
 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
@@ -134,30 +188,31 @@ on change, not on click.
 ### Deleting a row
 
 ```html
-<button lb-delete>Remove</button>
+<button lb-action="lb-row-delete">Remove</button>
 ```
 
-`lb-delete` needs no name. The row's `lb-query` and `lb-key` are already in
-scope, and they are all the server needs to know which row is meant and
-whether the query permits deleting it.
+`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.
 
-Write `lb-delete` on a native element, the same as `lb-action`. A widget
-sends its own request.
+The hub sends it from a native element. A widget sends its own request.
 
 ### Forms
 
-`lb-insert` and `lb-update` both gather every `lb-cell` inside the form into
-one values map, read from the control each cell is or wraps. They differ in
-one thing: `lb-update` also carries the key of the row it is inside, and
-`lb-insert` carries none, because there is no row yet.
+A `<form>` performs its `lb-action` on submit. `lb-row-insert` and `lb-row-update`
+both gather every `lb-cell` inside the form into one values map, read from
+the control each cell is or wraps. 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.
 
-Put an `lb-update` form inside the row it edits, so it has that row's key
+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:
 
 ```html
 <template lb-key="id">
   <li>
-    <form lb-update>
+    <form lb-action="lb-row-update">
       <input lb-cell="name" />
       <button type="submit">Save</button>
     </form>
@@ -188,31 +243,34 @@ HTML.
 
 ### An empty list
 
-A list widget stamps itself with `data-rows`, the number of rows it is
+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 in every list widget:
+answers with rows and says nothing about how many survived. It makes an empty
+list a stylesheet rule rather than code anywhere:
 
 ```html
-<lb-list lb-query="roster">
+<div lb-list="roster">
   <ul>
     <template lb-key="id">
       <li lb-cell="name"></li>
     </template>
   </ul>
   <p class="roster-empty">No members yet.</p>
-</lb-list>
+</div>
 ```
 
 ```css
 .roster-empty {
   display: none;
 }
-lb-list[data-rows="0"] .roster-empty {
+[lb-row-count="0"] .roster-empty {
   display: revert;
 }
 ```
 
+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.
+
 ## Request state
 
 Loadbare stamps two attributes on the element a request came from — the
@@ -220,11 +278,11 @@ button, the form, or the widget itself:
 
 | Attribute         | Means                                     |
 |-------------------|-------------------------------------------|
-| `data-lb-pending` | The request is in flight                  |
-| `data-lb-error`   | The last request from this element failed |
+| `lb-pending` | The request is in flight                  |
+| `lb-error`   | The last request from this element failed |
 
-`data-lb-pending` is set when the request goes out and removed when it
-settles. `data-lb-error` is set on a failed response, a network failure, or
+`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.
 
 Neither one carries any meaning beyond the fact it states. Dim a pending

package/docs/reference/overview.md

@@ -26,7 +26,7 @@ serves, and the widgets those pages are made of.
 |---------------------------------------------------------|--------------------------------|
 | [`<name>.page.html`](./page-files.md#html)              | The page's HTML                |
 | [`<name>.queries.ts`](./page-files.md#queries)          | The data the page displays     |
-| [`<name>.hooks.ts`](./page-files.md#hooks-actions-crud) | Data Channel handlers          |
+| [`<name>.requests.ts`](./page-files.md#requests-actions-crud) | Data Channel handlers          |
 | [Data Binding](./data-binding.md)                       | Connecting HTML to server data |
 
 ## Widgets