@loadbare/app 0.11.0 → 0.13.0

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

@@ -72,6 +72,10 @@ Put everything the user interacts with inside `<lb-hub>`. The hub normally
 sits directly inside `<body>`, with banner, nav, footer and `<main>` inside
 it, so Loadbare can act on all of them.
 
+Write exactly one `<lb-hub>` and exactly one `<main>`, with the `<main>`
+inside the hub and empty but for whitespace.  The builder rejects a chrome
+that does otherwise.
+
 The chrome's `<title>` is the document title until the first page shows.
 From then on the hub sets the document title to the page's label; see
 [The URL](#the-url).
@@ -108,6 +112,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:
@@ -150,7 +169,9 @@ pushes one instead when the element carrying `lb-request` also carries
 
 The hub answers the request itself, with no round trip, then reloads the
 page's queries at the new URL. The page stays in place, and rows that come
-back keep their place.
+back keep their place. A request that changes only `lb-order-<query>`, the
+user's [order](./data-binding.md#order) for a query the hub sorts itself,
+re-sorts the rows already on the page and loads nothing.
 
 A control whose column the URL does not carry lands empty, so every control
 inside `lb-query="lb-url"` shows what the address bar says, after a reload

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-`                |
@@ -276,7 +278,28 @@ A custom element reads `lb-` attributes and never assigns one. The developer
 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).
+the methods it calls; see [Holding rows](#holding-rows).  The build refuses
+a script that declares a method, accessor or field whose name is `lb`, a
+capital, and anything else Loadbare does not call, so a misspelled
+`lbRowLanded` fails the build rather than never being called.
+
+### 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-group-*`, `lb-row-*`, `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     | `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
 
@@ -309,7 +332,7 @@ So each kind of work has one place:
    reads no attribute and no child: an element made with
    `document.createElement` has neither when it runs.
 2. **A child is looked up when it is needed**, in a handler, a getter,
-   `lbPlaceRow` or `lbRowsLanded`, and never held from setup.
+   or `lbRowsLanded`, and never held from setup.
 3. **`connectedCallback` runs on every move**, so it is written to run
    again. It rearranges the element's own children into a state it checks
    for first, or adds a listener to `document` or `window`, which
@@ -450,36 +473,67 @@ 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`
-with a row template inside it needs no code, so a custom element holds rows
-only when they need placement or scaffolding that only it can decide.
+The hub lands every row template itself, places every row by the query's
+order, and builds every group the markup's group templates describe; see
+[Order](./data-binding.md#order) and [Groups](./data-binding.md#groups). A
+plain element carrying `lb-query` with a row template inside it needs no
+code, so a custom element holds rows only to do something with them once
+they land.
 
-A custom element carrying `lb-query` and a row template may implement two
-optional methods, which the hub calls:
+A custom element carrying `lb-query` and a row template may implement one
+optional method, which the hub calls:
 
 ```ts
-import type { RowsHost, Row } from "@loadbare/app/types";
-
-class SortedList extends HTMLElement implements RowsHost {
-  lbPlaceRow(el: Element, row: Row, template: HTMLTemplateElement) {
-    // Where this live row goes. Called with the live row detached, on its
-    // first appearance and again whenever all rows decide the order.
-  }
+import type { RowsHost } from "@loadbare/app/types";
+import { ATTR_ROW_REQUESTED, REQUESTED_CREATED } from "@loadbare/app/constants";
 
+class ScrollingList extends HTMLElement implements RowsHost {
   lbRowsLanded() {
-    // Once, after the rows have landed. For scaffolding derived from the
-    // rows: a section heading, an <optgroup>, anything that goes when its
-    // last row does.
+    // Once, after the rows have landed, every row placed and stamped.
+    this.querySelector(`[${ATTR_ROW_REQUESTED}="${REQUESTED_CREATED}"]`)
+      ?.scrollIntoView({ block: "nearest" });
   }
 }
 ```
 
-| Method         | The hub calls it    |
-|----------------|---------------------|
-| `lbPlaceRow`   | To place a live row |
-| `lbRowsLanded` | After the rows land |
+| Method         | The hub calls it                                      |
+|----------------|-------------------------------------------------------|
+| `lbRowsLanded` | After the rows land, with every row placed and stamped |
 
 Everything else is the hub's:
 
@@ -487,16 +541,23 @@ Everything else is the hub's:
 |-------------|----------------------------------------------------------|
 | Cloning     | Clones the row template once per new key                 |
 | Matching    | Fills the live row already showing that key              |
-| Removing    | Removes the live rows the response says are gone         |
-| Stamping    | Stamps each live row with `lb-row-live` and `lb-key-value` |
+| Placing     | Places every live row by the query's order               |
+| Grouping    | Builds a group where the order breaks, and removes it with its last row |
+| Removing    | Marks the live rows the response says are gone as leaving, and removes them |
+| Stamping    | Stamps each live row with `lb-row-live`, `lb-key-value`, and what happened to it |
 | Counting    | Stamps `lb-query-row-count` with the number of live rows |
 
-`lbPlaceRow` receives the live row already filled and not yet in the
-document, so a custom element that reads a column to decide where the row
-goes can. Without it, the hub places a live row immediately before the row
-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.
+`lb-options.browser.ts` and `lb-table.browser.ts` in
+[`@loadbare/widgets`](./widgets.md) are two uses of `lbRowsLanded`: one
+gives each option and `<optgroup>` what landing does not, a value and a
+label, and the other scrolls to the row the page's request created or
+moved.
+
+A custom element the builder shipped absent under `lb-show` has not
+upgraded while its column is off, and the hub places the rows that land on
+it then as it places any. 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 `lbRowsLanded` runs.
 
 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

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

@@ -153,9 +153,9 @@ places it immediately before the template:
 ```
 
 The hub matches each row to a live row by its key. All rows decide
-membership and order: a live row whose key did not arrive is removed. A
-patch changes only the rows it names, and every other live row keeps its
-content and its place.
+membership: a live row whose key did not arrive leaves. A patch changes only
+the rows it names, and every other live row keeps its content. The hub
+places every live row by the query's order; see [Order](#order).
 
 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.
@@ -163,10 +163,121 @@ or two live rows showing one key, are reported on the console.
 A live row's root counts as a column when it carries `lb-column`, which is
 how an `<option>`, whose content is text, shows the column it is.
 
-A custom element that carries `lb-query` and a row template may decide where
-a row goes and add scaffolding around the rows; see
-[Holding rows](./custom-elements.md#holding-rows) and
-[The Basic Widget Library](./widgets.md).
+A custom element that carries `lb-query` and a row template reacts to the
+rows once they land; see [Holding rows](./custom-elements.md#holding-rows)
+and [The Basic Widget Library](./widgets.md).
+
+### Order
+
+A `rows` query declares its order with the query, as columns separated by
+commas, each descending when written after `-`:
+
+```ts
+roster: rows("id", (ctx) => ctx.db.members(), { order: "team,name" }),
+```
+
+The query parm `lb-order-<query>` replaces it for that query, so a control
+inside `lb-query="lb-url"` writing that parm re-sorts the rows the hub
+already has, with no round trip. With no order, rows show in the order they
+arrived, and a patch's new rows go last.
+
+Values compare by their JSON type: numbers numerically, strings as the
+user's language orders them, `false` before `true`, and `null` last. A
+number sent as a string sorts as a string. Rows that compare equal keep the
+order they arrived in. A row moves only when the order puts it somewhere
+else.
+
+A query that pages or limits its rows reads the parm itself and declares
+`serverSortedByUrl: true`, so a change of order loads the page again.
+
+### Groups
+
+A group is a run of rows sharing the order's leading term. Write a
+`<template lb-group>` where the row template goes, holding the group's
+heading and one nested `<template>`: the next group template, or the row
+template. The nth group template breaks on the order's nth term.
+
+```html
+<ul lb-query="roster">
+  <template lb-group>
+    <li>
+      <h3 lb-column="team"></h3>
+      <ul>
+        <template><li lb-column="name"></li></template>
+      </ul>
+    </li>
+  </template>
+</ul>
+```
+
+The group's contents land immediately before its nested template. When that
+template is inside the heading's element, the contents land inside it; when
+it is beside the heading, they land after it. `<tbody>` and `<optgroup>` do
+not nest, so a table's deeper levels are heading rows. Content after the
+nested template is the group's footer.
+
+A heading is filled from its group's first row, so it may show a column
+other than the one the group breaks on. The hub stamps each top-level
+element of a group with `lb-group-live`, `lb-group-column` and
+`lb-group-value`. A row creates its group, and a group leaves with its last
+row.
+
+### Aggregates
+
+`lb-count`, `lb-sum="col"`, `lb-avg="col"`, `lb-min="col"` and
+`lb-max="col"` set an element from the rows of the nearest group around it,
+or of the whole list outside any group:
+
+```html
+<tr><td><span lb-count></span> people</td><td lb-sum="salary"></td></tr>
+```
+
+A sum and an average are exact, read from JSON numbers and from strings
+holding a plain decimal. `null` and empty values are left out. The result
+lands unformatted, and covers the rows the browser holds.
+
+### What happened to a row
+
+Every change to a list is one a stylesheet can see:
+
+| Attribute          | Means                                                  |
+| ------------------ | ------------------------------------------------------ |
+| `lb-row-created`   | Created when the hub last touched the row              |
+| `lb-row-changed`   | Its values changed when the hub last touched it        |
+| `lb-row-moved`     | The order put it somewhere else when last touched      |
+| `lb-row-requested` | `created`, `changed` or `moved` by this page's request |
+| `lb-row-leaving`   | A row on its way out                                   |
+| `lb-group-leaving` | A group on its way out                                 |
+
+A row that leaves loses `lb-row-live`, takes `inert`, and is removed once
+its animations finish, at once when there are none. A moved row moves, and
+a copy stays behind where it was, leaving. `lb-row-requested` is cleared at
+every landing; the others when the hub next touches the row.
+
+```css
+[lb-row-created] { animation: arrive 200ms; }
+[lb-row-leaving] { animation: depart 200ms forwards; }
+```
+
+### 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 around rows, such as a group's heading or 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. When the column first turns on and the element
+upgrades, the hub lands the kept answer on it again, so its `lbRowsLanded`
+runs. 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
@@ -225,6 +336,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 +582,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 +619,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

@@ -48,7 +48,8 @@ page touches that page's files.
 ## HTML
 
 Write the page as a fragment. The fragment lands in `<main>`, which
-[chrome.html](./chrome.md) supplies.
+[chrome.html](./chrome.md) supplies.  A page carries no `<main>` and no
+`<lb-hub>` of its own; the builder rejects one that does.
 
 ```html
 <!-- src/pages/about.page.html -->
@@ -89,14 +90,18 @@ export const queries: Queries = {
     page: "directory",
     count: String(await ctx.db.visitCount()),
   })),
-  directory: rows("id", (ctx) => ctx.db.directory()),
+  directory: rows("id", (ctx) => ctx.db.directory(), { order: "name" }),
 };
 ```
 
-| Declared with     | Answers with                              |
-|-------------------|-------------------------------------------|
-| `row(key, run)`   | One row, an object                        |
-| `rows(key, run)`  | All its rows, an array of objects, in order |
+| Declared with              | Answers with                              |
+|----------------------------|-------------------------------------------|
+| `row(key, run)`            | One row, an object                        |
+| `rows(key, run, options)`  | All its rows, an array of objects         |
+
+`options` are a `rows` query's order: `order`, the columns the hub places
+its rows by, and `serverSortedByUrl`, set when the query reads the user's
+order parm itself. See [Order](./data-binding.md#order).
 
 `key` names the column that identifies a row. Give every row that column,
 including a `row` query's: an aggregate row answers with a constant key. The
@@ -109,8 +114,8 @@ page that needs the same data as one row and as a set declares two queries.
 The hub hands each value to the browser untouched, so what a number, a date
 or a null looks like is decided here, in the query.
 
-Return the full answer every time, and the rows in the order the page shows
-them. Sending only what changed is a request's job — see
+Return the full answer every time. With no `order`, the rows show in the
+order they are returned. Sending only what changed is a request's job — see
 [refresh and patch](#refresh-and-patch).
 
 ## Requests
@@ -120,7 +125,7 @@ optional:
 
 | Key           | Runs                                                   |
 |---------------|--------------------------------------------------------|
-| `onPageEnter` | Before the page's queries, when the page loads         |
+| `onPageEnter` | Before the page's queries, when the page loads; may move the URL |
 | `handlers`    | The page's declared requests, by request name          |
 | `crud`        | The requests Loadbare provides, by query name          |
 
@@ -150,6 +155,12 @@ export const requests: Requests = {
 
 Declare no refresh set here. The page's queries run afterward.
 
+It may return `url()` instead, to move the page to other query parms before
+anything shows, as restoring the filters and order the user last had does.
+The page loads there in the same round trip, and that load does not follow
+`onPageEnter` again. A `url()` leading to the parms already in hand is
+ignored. See [Moving the URL](#moving-the-url).
+
 ### handlers
 
 Declare a request under the name the HTML gives `lb-request`. Pair what it
@@ -223,6 +234,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 +250,31 @@ 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 to say what one row could.
+
+A change that seems to need a refresh usually has a patch:
+
+- A row whose position changes: the hub places it by the query's
+  [order](./data-binding.md#order).
+- A group that appears or goes: the hub makes a group with its first row
+  and removes it with its last, so no row stands in for an empty one.
+- 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: {

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

@@ -91,6 +91,10 @@ TypeScript types itself. `dist/pages.ts` imports each `.requests.ts` and
 `.queries.ts` file by its full name, extension included, because Node looks
 for exactly the path an import names.
 
+The `hub` it exports comes from `createHub`, the only implementation of
+the `Hub` interface. That interface may gain members in any release, so an
+application never implements it.
+
 Enable `allowImportingTsExtensions` in the application's `tsconfig.json`
 when `tsc` type-checks the server. Without it, `tsc` rejects the `.ts`
 extensions in `dist/pages.ts`: