@loadbare/app 0.11.0 → 0.12.0

package/skills/loadbare-app/SKILL.md

@@ -159,7 +159,9 @@ row template lands on the element itself.  A `rows` query with no row
 template lands nothing, which is what an insert form naming its query is.  A
 condition is `lb-show="<column>"`: write every possibility into the page and
 let a column decide which is present.  The column is a boolean or null; the
-string `"false"` counts as present.
+string `"false"` counts as present.  `lb-show="!<column>"` is present when
+the column is not, so one column decides both sides and the query never
+sends a flag and its opposite.
 
 **`{{placeholder}}` is build time only.**  It reads an `exp-` attribute on
 the tag, never data.  Write it as an entire attribute value or an entire
@@ -176,7 +178,9 @@ from it.
 query under two names.  Many masters with their details is one `rows` query
 of joined rows, grouped for display by a custom element's `lbPlaceRow`.  A
 query nested inside another query's row template receives the same rows in
-every outer row; use it for a picker, never for per-row detail.
+every outer row; use it for a picker, never for per-row detail.  A new outer
+row is filled from the nested query's last answer, whatever order they land
+in.
 
 **Every request has one shape.**  `lb-request` names the request, and the
 hub sends `{ name, query, key, values }` as present: `query` from the
@@ -201,6 +205,12 @@ elsewhere with the HTML `form` attribute.  Checkboxes, radio buttons and
 file inputs are not controls here: they receive no value and are not
 gathered.
 
+**A form that adds to a set chosen elsewhere is written once, outside every
+row.**  A form cannot sit inside another form or in a table row, so a dialog
+that creates an account while a posting's picker is choosing one goes at the
+end of the page, and each row opens it with `commandfor`.  The dialog learns
+the new key from `lb-request-done`.
+
 **Three requests are Loadbare's.**  `lb-row-insert` needs `query` and
 `values`, `lb-row-update` needs `query`, `key` and `values`, and
 `lb-row-delete` needs `query` and `key`.  The page permits each under
@@ -216,8 +226,33 @@ page may edit.
 
 **Return a patch when the change has a known extent.**  `patch({ rows })`
 for rows added or edited, `patch({ drop })` for keys removed, with
-`refresh: []`.  List a query in `refresh` only when its membership or order
-changed in a way the handler cannot name.
+`refresh: []`.  A refreshed `rows` query sends every row, and the hub places
+every row again, which moves each element and takes focus from the control
+the user is in.  List a query in `refresh` only when its membership or order
+changed in a way the handler cannot name.  Never list one only to fill the
+picker in a row the request adds: its answer did not change, and the hub
+fills a new row from the last one.
+
+**The usual reasons for a refresh each have a patch.**
+- A placeholder row standing in for an empty set or section: drop its key
+  in the patch that adds the first real row, and add it back in the patch
+  that drops the last.
+- A row whose position changes: the rows host places it, as `lb-table` does
+  by `data-sort`.
+- A row whose other columns change with the edit: re-read the row and patch
+  it.
+- Rows the database removes with a deleted one: select their keys before
+  the delete and drop them too.
+
+An update or a delete names its row by key, and removing a row never
+reorders the rest, so each always has a patch: `createHub` refuses at
+startup a `rowUpdate` or `rowDelete` whose `refresh` names its own `rows`
+query.  An insert may refresh its own query, and should only when the new
+row's place matters and nothing places it: a patched row lands where its
+host puts it, in order under `lb-table` with `data-sort`, last in plain
+markup and in `lb-options`.
+Each handler's `refresh` is its own, and every query in it needs its own
+reason.  A list shared by several handlers is a warning sign.
 
 **A page's queries are its view model, not a data layer.**  Each answers
 one page's elements in the form they show: formatted dates and amounts, and
@@ -247,6 +282,12 @@ puts parms onto `ctx`, and a query reads them there.  Read them from
 request.  A parm is user input, so validate it where it is read.  Do not
 keep a selection in server state set by a handler.
 
+**Where focus starts is the hub's.**  On entering a page, once its queries
+have landed, the hub focuses the first control in `<main>` the user can
+operate; a change of query parm leaves focus where it is.  Order the page so
+that control is the one to start in, and write no `autofocus` and no script
+that focuses on load.
+
 **A handler moves the URL with `url()`.**  After an insert, only the server
 knows the new key; after a delete, only the server knows the parm should
 go.  Have `run` return `url({ acct: String(id) })`, or `url({ acct: "" })`
@@ -292,6 +333,19 @@ on every move.  Listen on the element itself in the constructor, look a
 child up when it is needed, and in a control take up `lb-column-value` once,
 on first connect, since a value can land before the element upgrades.
 
+**The hub and a custom element talk in four ways, one per kind of
+message.**  State the hub gives an element is an attribute stamp, or `value`
+on a control.  Work the hub needs done while landing is an optional `lb`
+method: `lbPlaceRow`, `lbRowsLanded`.  A moment is a bubbling event: an
+element sends `lb-request`, and the hub answers on the same element with
+`lb-request-done`, carrying the request and the response items that landed,
+or the error.  Listen for `lb-request-done` on whichever ancestor needs the
+outcome, such as a dialog choosing the row its form just created.
+
+**A widget that holds rows may sit under `lb-show`.**  Rows that land while
+it is away are placed by its `lbPlaceRow` once it first appears, so hide a
+table with `lb-show`, not with a stylesheet rule.
+
 **Name a custom element script `<tag>.browser.ts`.**  A plain `<tag>.ts`
 stays on the server and the tag goes unregistered.
 

package/skills/loadbare-app/references/TECHREF-1.0.md

@@ -64,10 +64,9 @@ fine, because every `<select>` receives the same rows.
 
 But the allowed values may depend on other values in the row.
 
-- **Decide how a new live row fills a nested query.** A row added to the
-  outer query starts with its nested query empty, and it fills only when the
-  nested query's name lands again.  See [Master-detail](#master-detail) for
-  what a nested query is for.
+- **Decide whether a nested query's rows may depend on its row.** A nested
+  query has one answer, which every live row receives.  See
+  [Master-detail](#master-detail) for what a nested query is for.
 
 ```html
 <tbody lb-query="accounts">
@@ -78,6 +77,24 @@ But the allowed values may depend on other values in the row.
 </tbody>
 ```
 
+### Who creates and orders rows
+
+The hub creates every live row from a row template and places it in the
+query's order, unless the element holding the rows has `lbPlaceRow`, in
+which case the custom element decides where each row goes.  Custom elements
+also create rows of their own: `lb-table` clones a ghost row per section and
+builds each section's heading.  Neither side owns creation or order.
+
+- **Decide who creates rows and who orders them.** A patch cannot say where
+  a new row goes, so it lands where the host puts it: in order under
+  `lb-table` with `data-sort`, last in plain markup and in `lb-options`.
+  Whether an insert may answer with a patch therefore depends on markup the
+  server cannot see, and the server cannot refuse an insert that refreshes
+  its own query the way it refuses an update or a delete.
+- **Decide whether landing all rows moves rows already in place.** It moves
+  every row today, which takes focus from the control the user is in, and
+  `lbPlaceRow` does the same.
+
 ### The server API
 
 - **Give the chrome a way to state its own queries.** A custom element in
@@ -425,7 +442,7 @@ query.
 | ----------- | -------- | -------------------------------------------------- |
 | `lb-query`  | a query  | Puts its rows in the element's content             |
 | `lb-column` | a column | Sets the element from that column                  |
-| `lb-show`   | a column | Removes it while the named column is null or false |
+| `lb-show`   | a column | Removes it while the named column is null or false; `!column` reverses it |
 
 | Stamp                | The hub stamps it with           |
 | -------------------- | -------------------------------- |
@@ -558,6 +575,10 @@ so `"false"` is on, and a query spells a condition as a boolean or a null.
 </template>
 ```
 
+Write `!` before the column to reverse it: `lb-show="!chosen"` is present
+while `chosen` is null or false.  One column then decides both of two
+elements, rather than a column and its opposite, which could disagree.
+
 It reads from the nearest ancestor row, as `lb-column` does, and on an
 element that carries `lb-query` the column belongs to the row around it.  A
 row that does not carry the column leaves the element as it is.
@@ -578,7 +599,8 @@ nothing conditional shows until its row lands.  An absent element's template
 keeps its place among its siblings, and a position selector counts it.
 
 These are build errors: `lb-show` on a row template's root, `lb-show` with
-no `lb-query` around it, and `lb-show` on a `<template>`.
+no `lb-query` around it, `lb-show` on a `<template>`, and `lb-show="!"` or
+`lb-show="!!column"`.
 
 Hiding is presentation, and the server still refuses what a request may not
 do.
@@ -608,7 +630,9 @@ each detail row carries its master's columns.  A custom element's
 
 A query nested in another query's row template receives the same rows in
 every live row.  That serves a picker offering the same choices on every
-row, and is not a way to show a different detail per row.
+row, and is not a way to show a different detail per row.  A live row added
+later is filled from the nested query's last answer, so a request that adds
+one does not refresh the nested query to fill it.
 
 Which master a page shows is a query parm, which a query reads off `ctx`
 since it takes no argument from the browser — see [Query parms](#query-parms).
@@ -767,6 +791,18 @@ interceptor calls `stopPropagation`, not `preventDefault`.  This is what
 makes a confirmation wrapper possible without the wrapped element knowing
 about it.
 
+Once what the request brought back has landed, or its round trip has failed,
+the hub dispatches the bubbling `lb-request-done` event from the same
+element.  Its `detail`, `HubRequestDone` in `@loadbare/app/types`, holds
+the request as the hub sent it and `items`, every response item that landed
+because of it, in order.  An answer that moved the URL contributes its
+`lb-url` item and the page load.  `error` is set instead when the round trip
+failed.  By then `lb-request-pending` is gone, and a listener sees the page
+as the answer left it.  A request the hub or an ancestor stopped was never
+sent, and gets no `lb-request-done`.  An element the answer removed from the
+document, such as the row a delete took away, dispatches the event where it
+now is, and no ancestor it had on the page hears it.
+
 #### Request state
 
 The hub stamps `lb-request-pending` on the element that issued a request
@@ -804,6 +840,14 @@ A page load that fails lands nothing and is reported to the console.  A load
 started by a request for `lb-url` stamps the element that issued it, as any
 request stamps its element.
 
+A response answers for the URL its request was sent from, path and query
+string both.  One that returns after the URL has moved lands nothing, since
+it describes what the user is no longer looking at: a request's answer,
+including any `url()` it carries, and a page load overtaken by a newer one.
+A write whose answer is dropped this way has still happened.  Its
+`lb-request-done` carries no items and no error, and an insert still resets
+its form.
+
 ### The URL
 
 ---- UNEDITED ----
@@ -834,6 +878,14 @@ server runs its `onPageEnter`, then its queries.  When a query parm takes a
 new value, the hub reloads the page's queries, and keeps the page's DOM, so
 live rows that come back keep their place.
 
+Once an entered page's queries have landed, the hub focuses the first
+element in `<main>` the user can operate: not disabled, not in a closed
+`<dialog>`, not `inert`, not `hidden`, not in an absent `lb-show` branch,
+and one that takes the focus.  Entering is a cold load, a new `lb-path`,
+and Back or Forward to another page.  A change of query parm enters no
+page, and focus stays where it is, as it does when it is already in
+`<main>`.
+
 The page's title is the text of the page file's `<title>`, which the builder
 stamps on the page as `lb-page-title`.  The hub sets the document title to
 `lb-page-label` when it is not null.
@@ -1003,8 +1055,8 @@ rowInsert: {
   carries the `lb-url` item alone, and the hub loads the page itself.  A
   failure there is a page load's, and is not stamped on the element that
   issued the request.
-- A user who has left the page by the time the response arrives keeps the
-  URL they are on.
+- A user who has moved by the time the response arrives, to another page or
+  to other query parms, keeps the URL they are on.
 
 The page is loaded with a second context, built by `contextFor` from the new
 parms — see [The Express server](#the-express-server).
@@ -1027,6 +1079,7 @@ to build on any of these:
   `<lb-hub>`.
 - `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-column` with no ancestor row is allowed: the hub gathers from it.
 
@@ -1276,6 +1329,9 @@ request carrying no name answers 400, and a `run` that throws answers 500.
 
 Every handler under `handlers` and `crud` has the same two members.  `run`
 performs the work, and `refresh` names the queries to re-run once it has.
+A query belongs there when its answer changed, never to fill an element the
+request's answer creates: that element is filled from the last answer its
+query landed.
 
 `run` receives the same `ctx` and the request less its name: `query`, `key`
 and `values`, as present.
@@ -1284,6 +1340,15 @@ and `values`, as present.
 the refreshed ones.  That is how a delta reaches the browser: wrap it in
 `patch()`, naming the rows that arrived or changed and the keys that went.
 
+A refreshed `rows` query sends every row, and the hub places every row
+again, which moves each element and takes focus from the control the user
+is in.  An update or a delete names its row by key, and removing a row
+never reorders the rest, so its handler always knows what changed:
+`createHub` refuses at startup a `crud` `rowUpdate` or `rowDelete` on a
+`rows` query whose `refresh` names that same query.  A `row` query sends one
+row and may refresh itself.  An insert may refresh its own query; see
+[Who creates and orders rows](#who-creates-and-orders-rows).
+
 `run` may instead return `url()`, a new row for `lb-url`, naming query parms
 only the write can know, such as the key of a row it inserted.  The page
 then loads at them in the same round trip, in place of the refresh set — see
@@ -1397,6 +1462,25 @@ export default ["@scope/library-name"];
 Import every attribute name from `@loadbare/app/constants` — see
 [Constants](#constants).  Never write one as a string literal.
 
+### What the hub and an element say to each other
+
+Each direction has one mechanism for each kind of message:
+
+| Direction      | What                                        | How                          | Today                                            |
+| -------------- | ------------------------------------------- | ---------------------------- | ------------------------------------------------ |
+| Hub to element | State that lasts                            | An attribute the hub stamps  | `lb-column-value`, `lb-key-value`, `lb-query-row-count`, `lb-request-pending`, `lb-request-error` |
+| Hub to element | State the platform already names           | A property                   | A control's `value`                              |
+| Hub to element | Work the hub needs done now, while landing  | An optional `lb` method      | `lbPlaceRow`, `lbRowsLanded`                     |
+| Hub to element | A moment an element started                 | A bubbling event             | `lb-request-done`                                |
+| Element to hub | A moment                                    | A bubbling event             | `lb-request`, and `change`, `click` and `submit` |
+
+State is an attribute, because a stylesheet can select on it and an element
+that upgrades late still finds it.  A method is for work the hub cannot go
+on without, since it acts on one element at one point in landing and nothing
+else can do it.  A moment is an event, because the element that cares is
+often an ancestor of the one it concerns, and an event reaches it with no
+knowledge of either.
+
 ### Controls
 
 A form-associated custom element with a `value` property that fires
@@ -1450,6 +1534,11 @@ The hub calls both on a custom element with `lb-query` and a row template.
 Both are optional.  The `RowsHost` interface in `@loadbare/app/types`
 declares them.
 
+A custom element the builder shipped absent under `lb-show` has not
+upgraded while its column is off, and rows that land on it then are placed
+without it.  When the column first turns on and it upgrades, the hub lands
+the query's last answer on it again, as all rows, so both hooks run.
+
 `applyRow(root, row)`, exported by `@loadbare/app`, fills `root` from one
 row, the same operation that fills a live row.
 
@@ -1593,6 +1682,7 @@ Loadbare/app owns every DOM event in this table, both the name and what its
 | Event        | Dispatched from                  | Bubbles | Cancelable | Defined in                              |
 | ------------ | -------------------------------- | ------- | ---------- | --------------------------------------- |
 | `lb-request` | The element that committed       | Yes     | No         | [The request event](#the-request-event) |
+| `lb-request-done` | The element that committed  | Yes     | No         | [The request event](#the-request-event) |
 
 ### Reserved methods
 
@@ -1628,6 +1718,8 @@ imports them rather than writing a string.
 | `ATTR_PAGE_TITLE`         | `lb-page-title`                         |
 | `DEVELOPER_ATTRIBUTES`    | The seven 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` |
 | `LB_RESERVED_PREFIX`      | `lb-`                                   |
 | `REQUEST_ROW_INSERT`      | `lb-row-insert`                         |
 | `REQUEST_ROW_UPDATE`      | `lb-row-update`                         |

package/skills/loadbare-app/references/chrome.md

@@ -108,6 +108,21 @@ tab and the browser history show the page.
 `lb-url` is the one query a page may use that the server does not declare. A
 page names it the same way, anywhere inside the hub.
 
+### Where focus starts
+
+On entering a page, once its queries have landed, the hub focuses the first
+element in `<main>` the user can operate, so a keyboard user starts in the
+page rather than on the document. The chrome comes first in the document,
+and is passed over. So is anything disabled, in a closed `<dialog>`,
+`inert`, `hidden`, in an absent `lb-show` branch, or that does not take
+the focus when asked. A widget's native control counts, so write no
+`autofocus` to restate this.
+
+A page is entered on a cold load, a new `lb-path` from a link or from a
+handler's `url()`, and Back or Forward to another page. A change of query
+parm enters no page: the user who chose a record in a picker stays in the
+picker. Focus the user has already put in `<main>` is left there.
+
 ### Links
 
 Write `lb-url-link` on an `<a>` to move between pages:

package/skills/loadbare-app/references/custom-elements.md

@@ -268,6 +268,8 @@ one as a string literal:
 | `REQUEST_ROW_INSERT`, `REQUEST_ROW_UPDATE`, `REQUEST_ROW_DELETE` | The requests Loadbare provides |
 | `LB_ROW_REQUESTS`      | All three, in one array |
 | `LB_EVENT_NAME`        | `lb-request`, the event every request travels as |
+| `LB_DONE_EVENT_NAME`   | `lb-request-done`, the event that says how it turned out |
+| `SHOW_NOT`             | `!`, written before a column in `lb-show` |
 | `URL_QUERY`            | `lb-url`             |
 | `URL_COLUMN_PATH`, `URL_COLUMN_PAGE_LABEL`, `URL_COLUMN_PAGE_UNKNOWN` | `lb-path`, `lb-page-label`, `lb-page-unknown` |
 | `LB_RESERVED_PREFIX`   | `lb-`                |
@@ -278,6 +280,24 @@ writes them in markup, and the hub and the builder write their stamps.
 Loadbare reserves method names beginning with `lb` on a custom element, for
 the methods it calls; see [Holding rows](#holding-rows).
 
+### What the hub and an element say to each other
+
+Each direction has one mechanism for each kind of message:
+
+| Direction      | What                                       | How                         | Today |
+|----------------|--------------------------------------------|-----------------------------|-------|
+| Hub to element | State that lasts                           | An attribute the hub stamps | `lb-column-value`, `lb-key-value`, `lb-query-row-count`, `lb-request-pending`, `lb-request-error` |
+| Hub to element | State the platform already names           | A property                  | A control's `value` |
+| Hub to element | Work the hub needs done now, while landing | An optional `lb` method     | `lbPlaceRow`, `lbRowsLanded` |
+| Hub to element | A moment an element started                | A bubbling event            | `lb-request-done` |
+| Element to hub | A moment                                   | A bubbling event            | `lb-request`, and `change`, `click` and `submit` |
+
+State is an attribute: a stylesheet can select on it, and an element that
+upgrades late still finds it. A method is for work the hub cannot go on
+without, done by one element at one point in landing. A moment is an event,
+because the element that cares is often an ancestor of the one it concerns,
+and an event reaches it knowing neither.
+
 ### When its code runs
 
 The hub creates, places and parks elements, and each of those reaches a
@@ -450,6 +470,39 @@ missing a field its name needs, and stamps the dispatching element with
 
 Let the event bubble, so an ancestor can stop it before the hub sends it.
 
+### Hearing how it turned out
+
+Once what a request brought back has landed, or its round trip has failed,
+the hub dispatches `lb-request-done` from the element that committed. It
+bubbles, so the element that cares need not be the one that committed: a
+dialog hears it from the form inside it.
+
+```ts
+import { LB_DONE_EVENT_NAME } from "@loadbare/app/constants";
+import type { HubRequestDone } from "@loadbare/app/types";
+
+this.addEventListener(LB_DONE_EVENT_NAME, (e) => {
+  const { request, items, error } = (e as CustomEvent<HubRequestDone>).detail;
+  if (error) return;
+  const item = items.find((i) => i.query === request.query);
+  const created = item?.patch?.rows?.[0];
+  if (created) this.choose(String(created[item!.key]));
+});
+```
+
+`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
+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
+rows, and nothing marks which one is new.
+
+By the time the event is dispatched, `lb-request-pending` is gone and the
+page is as the answer left it. A request that was never sent, because the
+hub or an ancestor stopped it, gets no `lb-request-done`. An element the
+answer removed, such as the row a delete took away, dispatches the event
+outside the document, and no ancestor it had there hears it.
+
 ### Holding rows
 
 The hub lands every row template itself. A plain element carrying `lb-query`
@@ -498,6 +551,15 @@ 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 landing.
 
+A custom element the builder shipped absent under `lb-show` has not
+upgraded while its column is off, so it has no `lbPlaceRow` when rows land
+on it then, and the hub places them before the template. When the column
+first turns on and the element upgrades, the hub lands the query's last
+answer on it again, as all rows, so every row goes through `lbPlaceRow` and
+`lbRowsLanded` runs. Once upgraded it stays so: when its branch goes away and
+comes back, it has placed every row that landed meanwhile, and nothing is
+landed again.
+
 A custom element that walks its own rows finds them with `LIVE_ROW` from
 `@loadbare/app/constants`, never by `lb-key-value`: an element a `row` lands
 on carries a key too, and may sit among the rows, as a total in a table's

package/skills/loadbare-app/references/data-binding.md

@@ -168,6 +168,28 @@ a row goes and add scaffolding around the rows; see
 [Holding rows](./custom-elements.md#holding-rows) and
 [The Basic Widget Library](./widgets.md).
 
+### What arrives later
+
+The hub keeps each query's last answer until the page changes, with any
+patch since applied to it. An element that names a query and arrives after
+that query's answer is filled from what was kept, at the end of the landing
+that follows its arrival. Such an element is a picker in a new live row, or
+scaffolding a custom element builds around its rows, such as a ghost row. So
+a query nested in another query's rows need not land again, or land after
+the outer query, for a new outer row to show its choices.
+
+A custom element the builder shipped absent has not upgraded while its
+`lb-show` column is off, so rows that land on it then are not placed by it.
+When the column first turns on and the element upgrades, the hub lands the
+kept answer on it again, and every row goes through its `lbPlaceRow`. So a
+table that groups its rows can sit under `lb-show`. See
+[Holding rows](./custom-elements.md#holding-rows).
+
+Nothing is answered from what the hub kept: a request always goes to the
+server, and a query re-runs only when a response names it. A patch that
+arrives before all of a query's rows is not kept, since it is not the whole
+of anything.
+
 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.
@@ -225,6 +247,14 @@ 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.
 
+Write `!` before the column to reverse it. One column then decides between
+two elements, rather than a column and its opposite, which could disagree:
+
+```html
+<h2 lb-show="chosen" lb-column="title"></h2>
+<p lb-show="!chosen">Choose a batch.</p>
+```
+
 `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
@@ -463,6 +493,11 @@ 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).
 
+Once the answer has landed, or the round trip has failed, the hub dispatches
+a bubbling `lb-request-done` event from the same element, carrying the
+request and what landed because of it, or the error; see
+[Hearing how it turned out](./custom-elements.md#hearing-how-it-turned-out).
+
 ## The URL
 
 The hub serves one query of its own, `lb-url`: one row holding the path, the
@@ -495,3 +530,4 @@ expansion, and refuses to build:
 - `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
+- `lb-show="!"` or `lb-show="!!column"`, which reverse no column

package/skills/loadbare-app/references/page-files.md

@@ -223,6 +223,9 @@ Every value in `values` is a string, as a control's value is.
 ### refresh and patch
 
 List in `refresh` every query whose whole answer the request changed.
+Never list one only to fill what the request's answer creates, such as the
+picker in a new row: the hub fills that from the query's last answer. See
+[What arrives later](./data-binding.md#what-arrives-later).
 
 Return answers from `run` to state a narrower change than re-running a query
 would. What `run` returns is keyed by query name and laid over the refreshed
@@ -236,8 +239,33 @@ queries:
 | `patch({ drop: [...] })` | These keys are gone; the rest stand         |
 
 Return a patch for a change the request knows the extent of — one row added,
-one row dropped, one row edited — and leave `refresh` empty. Re-run the query
-instead when membership or order changed in a way the request cannot name:
+one row dropped, one row edited — and leave `refresh` empty. A refreshed
+`rows` query sends every row, and the hub places every row again, which moves
+each element and takes focus from the control the user is in.
+
+A change that seems to need a refresh usually has a patch:
+
+- A placeholder row standing in for an empty set or section: drop its key in
+  the patch that adds the first real row, and add it back in the patch that
+  drops the last.
+- A row whose position changes: the rows host places it, as
+  [`lb-table`](./widgets.md#lb-table) does by `data-sort`.
+- A row whose other columns change with the edit: re-read the row and patch
+  it.
+- Rows the database removes with a deleted one: select their keys before the
+  delete and drop them too.
+
+An update or a delete always has a patch, since it names its row by key and
+removing a row never reorders the rest. `createHub` refuses at startup a
+`crud` `rowUpdate` or `rowDelete` on a `rows` query whose `refresh` names
+that same query. An insert may refresh its own query: where a new row goes
+depends on whether its host places it, which the server cannot see.
+
+Each request's `refresh` is its own, and every query in it needs its own
+reason. A list shared by several requests is a warning sign.
+
+Re-run the query when membership or order changed in a way the request
+cannot name:
 
 ```ts
 resetRoster: {