@loadbare/app 0.10.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,11 +226,42 @@ 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.
-
-**Format values in the query.**  The hub does no type conversion.  What a
-number, date or null looks like is decided on the server.
+`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
+the words a reader sees, such as "12 postings".  The hub does no type
+conversion, so what a number, date or null looks like is decided on the
+server.  A value the page reads back stays data: a column on a control, the
+key, an `lb-show` condition, a value a stylesheet selects on.  What pages
+share goes beneath them, in a database view or a helper module, never in a
+layer between the page and its queries.
 
 **A URL's path names a page, never a resource.**  Do not design
 `/accounts/42`.  A row is addressed by `query` and `key`, taken from where
@@ -241,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: "" })`
@@ -279,6 +326,26 @@ element (`static formAssociated = true`) with a `value` property that fires
 on `change`.  Any other custom element keeps its content and receives the
 column as its `lb-column-value` attribute.
 
+**A custom element connects many times.**  It is moved, never rebuilt: the
+hub places every live row again on each set of all rows, and parks an
+`lb-show` element in a template while it is off, so `connectedCallback` runs
+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.
 
@@ -296,6 +363,13 @@ A custom element is `<tag>.html`, `<tag>.browser.ts`, or both, and a tag
 with neither is a build error.  The HTML is expanded at build time into the
 tag's children; the class is an ordinary custom element with no base class.
 
+Place a custom element where HTML allows what its definition holds.  One
+whose definition has a `<div>` or a `<dialog>` cannot sit inside a `<p>`, and
+the build refuses it; see
+[Where a custom element can go](references/custom-elements.md#where-a-custom-element-can-go).
+Never write one inside `<select>`, `<option>` or `<textarea>`, where the
+parser loses the tag before the build can report it.
+
 Reach for one only when plain HTML cannot do the job.  A set of rows, a form
 and a condition need none.  A custom element exists to be a control of its
 own, or to place and scaffold rows through the two hooks the hub calls,
@@ -322,10 +396,12 @@ with the package, so no network is needed.
 - [`references/data-binding.md`](references/data-binding.md) — landing,
   gathering, requests, conditions and request state.  Start here for
   anything in a page.
-- [`references/page-files.md`](references/page-files.md) — queries,
-  `onPageEnter`, handlers, `crud`, refresh and patch, and `url()`.
+- [`references/page-files.md`](references/page-files.md) — what page
+  files are, queries, `onPageEnter`, handlers, `crud`, refresh and patch,
+  and `url()`.
 - [`references/custom-elements.md`](references/custom-elements.md) —
-  expansion, parameters, slots, destinations, and custom element code.
+  expansion, parameters, slots, destinations, and custom element code and
+  when it runs.
 - [`references/chrome.md`](references/chrome.md) — the chrome, and the URL
   as the query `lb-url`.
 - [`references/server.md`](references/server.md) — the Express server and

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
@@ -109,6 +126,13 @@ But the allowed values may depend on other values in the row.
 - **Land the remaining validations.** One `lb-hub` and one empty `<main>`.
   Recommend landing these now, because refusing markup that used to build is
   the kind of change 1.0 gives up.
+- **Decide whether the build validates HTML.** A page can be well formed and
+  still break HTML's rules for what an element may hold, such as a `<div>`
+  inside a `<p>`.  The parser rearranges it silently, the same way at build
+  time and in the browser, so nothing reports it.  Checking those rules is a
+  validator's job, and html-validate is one the builder could run on the
+  source or on the expanded output.  Deciding it after 1.0 is free if it
+  lands as an opt-in, and it may need a configuration key.
 - **Confirm the three output names.** `app.html`, `client.js` and `app.css`
   are about to be fixed in `staticRoutes` as well as in the builder.
 
@@ -251,6 +275,12 @@ A custom element with no element file is left alone.  A custom element
 with neither an element file nor a `.browser.ts` script is a build error, as
 stated in [Custom elements](#custom-elements).
 
+Each file is parsed on its own, and expansion joins them through the DOM,
+which applies none of HTML's rules for what an element may hold.  The browser
+reads the shipped text by those rules, so a join it would rearrange, such as
+a definition's `<dialog>` inside a page's `<p>`, is a build error naming the
+file, the custom element and the path to what would move.
+
 #### Build time parameters
 
 A build time parameter is supplied as an attribute on a custom element,
@@ -412,12 +442,13 @@ 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           |
 | -------------------- | -------------------------------- |
 | `lb-column-value`    | The value it set                 |
 | `lb-key-value`       | The row's key                    |
+| `lb-row-live`        | Nothing; it marks a live row     |
 | `lb-query-row-count` | The number of live rows it holds |
 
 The markup names a query and the columns it shows.  The kind and the key are
@@ -425,7 +456,8 @@ the server's, and the markup states neither.
 
 The row template is the first `<template>` among the descendants of an
 element with `lb-query`, outside any nested `lb-query`.  A live row is an
-element the hub cloned from a row template for one row.
+element the hub cloned from a row template for one row, and carries
+`lb-row-live`.
 
 | Kind   | Row template | The hub                             |
 | ------ | ------------ | ----------------------------------- |
@@ -498,6 +530,13 @@ refresh, and does not need to.
 
 The hub matches each row to a live row by its key.  It stamps
 `lb-key-value` on each live row, and on an element a `row` lands on itself.
+It stamps `lb-row-live` on each live row and nowhere else, so a `row`
+landed inside another query, such as a total in a table's foot, is not one
+of that query's rows.  A stylesheet or a custom element selects live rows
+with `[lb-row-live]`, and never with `[lb-key-value]`.
+
+A key is unique within a query.  Two rows with one key in the same answer,
+or two live rows showing one key, are reported on the console.
 
 All rows decide membership and order: every row is placed in the order
 given, and a live row whose key did not arrive is removed.  A patch touches
@@ -536,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.
@@ -556,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.
@@ -586,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).
@@ -745,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
@@ -782,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 ----
@@ -812,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.
@@ -981,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).
@@ -1005,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.
 
@@ -1254,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.
@@ -1262,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
@@ -1375,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
@@ -1390,9 +1496,33 @@ class NoteField extends HTMLElement {
 }
 ```
 
+A control that is not yet upgraded when its column lands receives
+`lb-column-value` alone, since the hub sets `value` only on a control.  That
+happens to an element the builder shipped absent, and to one whose
+definition loads after the hub lands.  A control takes the stamp up the
+first time it connects, and never again.
+
 A custom element that is not a control receives `lb-column-value` and
 renders it; its content is never replaced.
 
+### Lifecycle
+
+| The hub                                  | A custom element sees                        |
+| ---------------------------------------- | -------------------------------------------- |
+| Shows a page                             | `constructor`, `connectedCallback`           |
+| Creates a live row, before placing it    | `constructor`                                |
+| Places a live row the first time         | `connectedCallback`                          |
+| Places it again, on every set of all rows | `disconnectedCallback`, `connectedCallback` |
+| Removes a live row                       | `disconnectedCallback`                       |
+| Turns `lb-show` off                      | `disconnectedCallback`, `adoptedCallback`    |
+| Turns `lb-show` on                       | `adoptedCallback`, `connectedCallback`       |
+| Turns on an element shipped absent       | `constructor`, `connectedCallback`           |
+
+A listener on the element itself goes in the constructor, which reads no
+attribute and no child.  A child is looked up when it is needed.
+`connectedCallback` runs on every move and is written to run again; work
+done once per instance goes behind a flag.
+
 ### Row hooks
 
 | Method                          | Implemented By | The hub calls it                                   |
@@ -1404,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.
 
@@ -1505,6 +1640,7 @@ it may define tomorrow.
 | `lb-exp-template` | Developer     | An element file, and a `<template>` | [Slots and templates](#slots-and-templates)   |
 | `lb-column-value` | Hub           | Every element set from a column     | [How a column lands](#how-a-column-lands)     |
 | `lb-key-value`    | Hub           | A live row, and an element a `row` lands on | [Rows](#rows)                         |
+| `lb-row-live`     | Hub           | A live row                          | [Rows](#rows)                                 |
 | `lb-query-row-count` | Hub        | An element with a row template      | [Rows](#rows)                                 |
 | `lb-request-pending` | Hub        | The element that issued a request   | [Request state](#request-state)               |
 | `lb-request-error`   | Hub        | The element that issued a request   | [Request state](#request-state)               |
@@ -1546,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
 
@@ -1566,6 +1703,8 @@ imports them rather than writing a string.
 | `ATTR_SHOW`               | `lb-show`                               |
 | `ATTR_COLUMN_VALUE`       | `lb-column-value`                       |
 | `ATTR_KEY_VALUE`          | `lb-key-value`                          |
+| `ATTR_ROW_LIVE`           | `lb-row-live`                           |
+| `LIVE_ROW`                | `[lb-row-live]`, the selector for a live row |
 | `ATTR_QUERY_ROW_COUNT`    | `lb-query-row-count`                    |
 | `ATTR_REQUEST`            | `lb-request`                            |
 | `ATTR_REQUEST_PENDING`    | `lb-request-pending`                    |
@@ -1579,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: