@loadbare/app 0.10.0 → 0.12.0

package/docs/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/docs/comparison.md

@@ -128,16 +128,20 @@ shape of the data an application works with.
 ### Loadbare/app
 
 The hub holds no application data.  There is no store, no signal, no
-observable, and no client cache of query results.
+observable, and no client cache that answers a request.
 
 - A value that has landed exists in the DOM: as `textContent` or `value`, and
   as the `lb-column-value` stamp.
 - The rows of a `rows` query exist as the live rows the hub cloned, each
-  stamped with `lb-key-value`.
+  stamped with `lb-row-live` and `lb-key-value`.
 - The URL is a row too: the hub serves the query `lb-url`, whose columns are
   the path, the page label and the query parms.
 - An element hidden by `lb-show` exists inside a `<template>` standing where
   it stood.
+- The hub keeps each query's last answer until the page changes, only to
+  fill an element that names the query and arrives after it, such as a
+  picker in a new live row.  Nothing is read from it in place of asking the
+  server.
 - The hub keeps two pieces of state of its own: the name of the current page,
   and, until an insert completes, the form it gathered from.
 
@@ -187,7 +191,7 @@ At run time the hub performs a closed set of operations:
 | A value for another native element | Set `textContent`, and stamp `lb-column-value`                     |
 | A value for a custom element that is not a control | Stamp `lb-column-value`                            |
 | A `row` with no row template | Land it on the element itself, stamp `lb-key-value`                      |
-| A new key through a row template | Clone the row template, stamp `lb-key-value`, fill it, insert it     |
+| A new key through a row template | Clone the row template, stamp `lb-row-live` and `lb-key-value`, fill it, insert it |
 | All rows                   | Place every row in the order given, remove rows whose keys did not arrive  |
 | A patch                    | Upsert the rows named, remove the keys named, leave other rows in place    |
 | After rows land            | Stamp `lb-query-row-count`                                                 |
@@ -628,7 +632,7 @@ Nothing is scoped, renamed, added or removed.
 - Light DOM means every selector reaches every element, in the chrome and in
   widgets.
 - The hub stamps attributes a stylesheet can select on: `lb-column-value`,
-  `lb-key-value`, `lb-request-pending`, `lb-request-error`,
+  `lb-key-value`, `lb-row-live`, `lb-request-pending`, `lb-request-error`,
   `lb-query-row-count`.  An empty `rows` query is styled with
   `[lb-query-row-count="0"]`.
 
@@ -685,6 +689,27 @@ A page's server half:
 A query's `run` is `(ctx) => Row` or `(ctx) => Row[]`.  An answer whose
 shape disagrees with its declaration is dropped with a warning.
 
+A page's queries are that page's view model, computed on the server: a
+backend-for-frontend scoped to one page, whose answers are the values the
+page shows.
+
+|                  | Data layer (repository, ORM, API) | Backend-for-frontend | Loadbare/app page files |
+|------------------|-----------------------------------|----------------------|-------------------------|
+| Serves           | Any consumer                      | One client application | One page              |
+| Shaped by        | Entities                          | A client's screens   | One page's elements     |
+| Answers with     | Domain objects, independent of any UI | Data the client still turns into a view | Values as the page shows them, formatted and worded |
+| Client-side work | Mapping, state, view models, components | View models, components | None: the hub lands each column on the element that names it |
+| Keeps the rules  | Yes, in code                      | Usually not          | No: the application keeps them beneath, in its database or in code its handlers share |
+| Reused by        | Many screens                      | One application's screens | No other page      |
+
+A typical stack runs database, ORM or repository, service, API contract,
+client store, view model, component and template.  A Loadbare/app page keeps
+three places: the database with the application's rules, the page files that
+say what one page asks and answers, and the markup that says where each
+answer goes.  Reuse does not happen through a layer.  Two pages showing the
+same data repeat a query's shape or share a database view, and shared
+wording goes in a helper module.
+
 The data channel carries no CSRF token.  Where an options argument for
 hooks, transaction wrapping, error handling and CSRF would go is an open
 blocker.  Serving the static files from a separate origin is a roadmap item.
@@ -761,7 +786,7 @@ TECHREF-1.0 lists every name Loadbare/app owns in one cross-reference.
 | Owned                               | Count | Names                                                         |
 |-------------------------------------|-------|---------------------------------------------------------------|
 | `lb-*` attributes a developer writes | 7    | `lb-query`, `lb-column`, `lb-show`, `lb-request`, `lb-url-link`, `lb-url-push`, `lb-url-unknown` |
-| `lb-*` stamps                       | 7     | `lb-column-value`, `lb-key-value`, `lb-query-row-count`, `lb-request-pending`, `lb-request-error`, `lb-page`, `lb-page-title` |
+| `lb-*` stamps                       | 8     | `lb-column-value`, `lb-key-value`, `lb-row-live`, `lb-query-row-count`, `lb-request-pending`, `lb-request-error`, `lb-page`, `lb-page-title` |
 | `lb-*` build-time attributes        | 2     | `lb-exp-slot`, `lb-exp-template`                              |
 | Requests Loadbare provides          | 3     | `lb-row-insert`, `lb-row-update`, `lb-row-delete`             |
 | `lb*` methods on custom elements    | 2     | `lbPlaceRow`, `lbRowsLanded`                                  |

package/docs/reference/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: