@loadbare/app 0.19.0 → 0.20.0

package/docs/reference/names.md

@@ -0,0 +1,258 @@
+# Names
+
+Every name Loadbare/app owns, in one place.  Each row links to the section
+that defines it, and the definition lives there and only there.
+
+An application names nothing with the `lb-` prefix: no attribute, query,
+column, request, command, custom element or event.  A name Loadbare has not
+defined today it may define tomorrow.  `createHub` refuses at startup a page
+that declares a query, a handler or a `crud` entry whose name begins with
+`lb-`, and the builder refuses the rest; see
+[The markup checks](./data-binding.md#the-markup-checks).
+
+## Builder flags
+
+| Flag       | Default | Names                                     | Defined in                                          |
+| ---------- | ------- | ----------------------------------------- | --------------------------------------------------- |
+| `--src`    | `src`   | The application's own tree, scanned whole | [Running the builder](./builder.md#running-the-builder) |
+| `--out`    | `dist`  | Where the builder writes                  | [Running the builder](./builder.md#running-the-builder) |
+| `--watch`  | off     | Rebuild on change under `--src`           | [Running the builder](./builder.md#running-the-builder) |
+| `--minify` | off     | Minify `client.js` and `app.css`          | [Running the builder](./builder.md#running-the-builder) |
+
+## Reserved file names
+
+A file so named carries its meaning wherever it sits in the `--src` tree,
+so an application uses none of these names for anything else.
+
+| File                    | How many                       | Holds                                                    | Defined in                                          |
+| ----------------------- | ------------------------------ | -------------------------------------------------------- | --------------------------------------------------- |
+| `chrome.html`           | Exactly one                    | The application's one HTML document                      | [chrome.html](./chrome.md)                          |
+| `imports.ts`            | Zero or one                    | Default-exports an array of widget package names         | [Widgets from packages](./builder.md#widgets-from-packages) |
+| `<stub>.page.html`      | One per page                   | One page's markup, as a fragment                         | [HTML](./page-files.md#html)                        |
+| `<stub>.queries.ts`     | Zero or one per page           | That page's queries                                      | [Queries](./page-files.md#queries)                  |
+| `<stub>.requests.ts`    | Zero or one per page           | That page's requests                                     | [Requests](./page-files.md#requests)                |
+| `<tag-name>.html`       | Zero or one per custom element | One element file, as a fragment                          | [HTML](./custom-elements.md#html)                   |
+| `<tag-name>.browser.ts` | Zero or one per custom element | One custom element's script, `.js` also accepted         | [Code](./custom-elements.md#code)                   |
+| `*.css`                 | Any number                     | A stylesheet, concatenated into `app.css`                | [CSS](./css.md)                                     |
+
+## Build outputs
+
+The builder writes these into `--out`.
+
+| File              | Written           | Holds                                                              | Defined in                                              |
+| ----------------- | ----------------- | ------------------------------------------------------------------ | ------------------------------------------------------- |
+| `app.html`        | Always            | The chrome, with every page inside a `<template>`                  | [What the builder writes](./builder.md#what-the-builder-writes) |
+| `client.js`       | Always            | `<lb-hub>` and every custom element the application uses           | [What the builder writes](./builder.md#what-the-builder-writes) |
+| `client-entry.ts` | Always            | The generated entry `client.js` is bundled from                    | [What the builder writes](./builder.md#what-the-builder-writes) |
+| `app.css`         | With a stylesheet | Every stylesheet in the cascade, concatenated                      | [CSS](./css.md)                                         |
+| `pages.ts`        | With page data    | The one `createHub()` call, over every page's queries and requests | [Running the server](./server.md#running-the-server)    |
+
+## Reserved package.json keys
+
+A widget package declares these.  An application never does.
+
+| Key                | Value                     | Means                                                              | Defined in                                          |
+| ------------------ | ------------------------- | ------------------------------------------------------------------ | --------------------------------------------------- |
+| `loadbare.widgets` | A path inside the package | Where its custom elements are; absent means the whole installed directory | [Widgets from packages](./builder.md#widgets-from-packages) |
+
+## Reserved namespaces
+
+| Namespace | Applies to                                                  | Loadbare owns                                     | Defined in                                       |
+| --------- | ----------------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------ |
+| `lb-*`    | Attributes, their values, queries, columns of `lb-` queries, requests, custom elements, events | The names and their behavior | [Attributes](#attributes)                        |
+| `--lb-*`  | Values of HTML's `command` attribute                        | The names and their behavior                      | [Reserved commands](#reserved-commands)          |
+| `exp-*`   | Attributes on a custom element                              | The behavior; element file authors pick the names | [Parameters](./custom-elements.md#parameters)    |
+| `lb*`     | Methods on custom elements: `lb` and a capital              | The names and their behavior                      | [Reserved methods](#reserved-methods)            |
+
+## Attributes
+
+The developer writes seventeen attributes in pages and the chrome, and the
+builder refuses any other `lb-` attribute there.  `lb-exp-slot` and
+`lb-exp-template` are written for expansion, which removes them before the
+check.  The hub and the builder write the rest, as stamps, and script never
+assigns one.
+
+| Attribute            | Written by      | Defined in                                                       |
+| -------------------- | --------------- | ---------------------------------------------------------------- |
+| `lb-query`           | Developer       | [Landing](./data-binding.md#landing)                             |
+| `lb-column`          | Developer       | [Landing](./data-binding.md#landing)                             |
+| `lb-show`            | Developer       | [Conditional rendering](./data-binding.md#conditional-rendering) |
+| `lb-order`           | Developer       | [Order](./data-binding.md#order)                                 |
+| `lb-filter`          | Developer       | [Filters](./data-binding.md#filters)                             |
+| `lb-group`           | Developer       | [Groups](./data-binding.md#groups)                               |
+| `lb-count`, `lb-sum`, `lb-avg`, `lb-min`, `lb-max` | Developer | [Aggregates](./data-binding.md#aggregates)       |
+| `lb-select`          | Developer       | [Selecting rows](./data-binding.md#selecting-rows)               |
+| `lb-request`         | Developer       | [Requests](./data-binding.md#requests)                           |
+| `lb-url-link`        | Developer       | [Links](./chrome.md#links)                                       |
+| `lb-url-parm`        | Developer       | [A link from a row](./chrome.md#a-link-from-a-row)               |
+| `lb-url-push`        | Developer       | [Query parms](./chrome.md#query-parms)                           |
+| `lb-url-unknown`     | Developer       | [An unknown page](./chrome.md#an-unknown-page)                   |
+| `lb-exp-slot`        | Developer, consumed by expansion | [The slot](./custom-elements.md#the-slot)       |
+| `lb-exp-template`    | Developer, consumed by expansion | [Destinations](./custom-elements.md#destinations) |
+| `lb-column-value`    | Hub             | [Where a column lands](./data-binding.md#where-a-column-lands)   |
+| `lb-key-value`       | Hub             | [Landing](./data-binding.md#landing), [Editing a row in one form](./data-binding.md#editing-a-row-in-one-form) |
+| `lb-row-live`        | Hub             | [Landing](./data-binding.md#landing)                             |
+| `lb-query-row-count` | Hub             | [Counting rows](./data-binding.md#counting-rows)                 |
+| `lb-query-unsorted-count`, `lb-row-unsorted` | Hub | [Rows the user is working in](./data-binding.md#rows-the-user-is-working-in) |
+| `lb-query-order`     | Hub             | [Order](./data-binding.md#order)                                 |
+| `lb-group-live`, `lb-group-column`, `lb-group-value` | Hub | [Groups](./data-binding.md#groups)                       |
+| `lb-row-created`, `lb-row-changed`, `lb-row-moved`, `lb-row-requested` | Hub | [What happened to a row](./data-binding.md#what-happened-to-a-row) |
+| `lb-row-leaving`, `lb-group-leaving` | Hub | [What happened to a row](./data-binding.md#what-happened-to-a-row) |
+| `lb-row-editing`     | Hub             | [Editing a row in one form](./data-binding.md#editing-a-row-in-one-form) |
+| `lb-row-selected`    | Hub             | [Selecting rows](./data-binding.md#selecting-rows)               |
+| `lb-request-pending` | Hub             | [Request state](./data-binding.md#request-state)                 |
+| `lb-request-error`   | Hub             | [Request state](./data-binding.md#request-state)                 |
+| `lb-request-refused` | Hub             | [Refusals](./data-binding.md#refusals)                           |
+| `lb-show` on a `<template>` | Hub and builder | [Where an absent element is](./data-binding.md#where-an-absent-element-is) |
+| `lb-page`            | Builder         | [What the builder writes](./builder.md#what-the-builder-writes)  |
+| `lb-page-title`      | Builder         | [The page title](./page-files.md#the-page-title)                 |
+
+## Reserved queries
+
+The hub serves these in the browser.  Every page and the chrome may name
+them, and a page declares neither.
+
+| Query        | Kind  | Key       | Columns                                                         | Defined in                            |
+| ------------ | ----- | --------- | --------------------------------------------------------------- | ------------------------------------- |
+| `lb-url`     | `row` | `lb-path` | `lb-path`, `lb-page-label`, `lb-page-unknown`, every query parm | [The URL](./chrome.md#the-url)        |
+| `lb-choices` | `row` | `lb-path` | `lb-path`, every choice                                         | [Choices](./data-binding.md#choices)  |
+
+No query parm is reserved: a column of `lb-url` whose name begins with
+`lb-` is never a query parm.
+
+## Reserved request names
+
+| Request name    | Runs under `crud` | Defined in                                                                  |
+| --------------- | ----------------- | --------------------------------------------------------------------------- |
+| `lb-row-insert` | `rowInsert`       | [Inserting, updating and deleting rows](./data-binding.md#inserting-updating-and-deleting-rows) |
+| `lb-row-update` | `rowUpdate`       | [Inserting, updating and deleting rows](./data-binding.md#inserting-updating-and-deleting-rows) |
+| `lb-row-delete` | `rowDelete`       | [Inserting, updating and deleting rows](./data-binding.md#inserting-updating-and-deleting-rows) |
+
+## Reserved commands
+
+Loadbare/app owns every value of HTML's `command` attribute beginning with
+`--lb-`.
+
+| Command        | Defined in                                                               |
+| -------------- | ------------------------------------------------------------------------ |
+| `--lb-edit`    | [Editing a row in one form](./data-binding.md#editing-a-row-in-one-form) |
+| `--lb-new`     | [Editing a row in one form](./data-binding.md#editing-a-row-in-one-form) |
+| `--lb-release` | [Editing a row in one form](./data-binding.md#editing-a-row-in-one-form) |
+| `--lb-sort`    | [Rows the user is working in](./data-binding.md#rows-the-user-is-working-in) |
+
+## Reserved tags
+
+An application writes these and never defines them.
+
+| Tag        | Written in | Means                          | Defined in                                         |
+| ---------- | ---------- | ------------------------------ | -------------------------------------------------- |
+| `<lb-hub>` | The chrome | The application's live element | [The parts of a chrome](./chrome.md#the-parts-of-a-chrome) |
+
+## Reserved events
+
+Loadbare/app owns each event's name and what its `detail` carries.
+
+| Event             | Dispatched from            | Bubbles | Cancelable | Defined in                                                  |
+| ----------------- | -------------------------- | ------- | ---------- | ----------------------------------------------------------- |
+| `lb-request`      | The element that committed | Yes     | No         | [The request event](./data-binding.md#the-request-event)    |
+| `lb-request-done` | The element that committed | Yes     | No         | [Hearing how it turned out](./custom-elements.md#hearing-how-it-turned-out) |
+
+## Reserved methods
+
+The build refuses a custom element script declaring any other method,
+accessor or field named `lb` and a capital.
+
+| Method          | On                                                     | Defined in                                                  |
+| --------------- | ------------------------------------------------------ | ----------------------------------------------------------- |
+| `lbAttached`    | Any custom element the hub places                      | [When its code runs](./custom-elements.md#when-its-code-runs) |
+| `lbRowsLanded`  | A custom element with `lb-query` and a row template    | [Holding rows](./custom-elements.md#holding-rows)           |
+| `lbRequestDone` | A custom element that committed, or holds one that did | [Hearing how it turned out](./custom-elements.md#hearing-how-it-turned-out) |
+| `lbDetached`    | Any custom element the hub removes                     | [When its code runs](./custom-elements.md#when-its-code-runs) |
+
+## Exports
+
+| Entry point                | Exports                                                          | Defined in                                     |
+| -------------------------- | ---------------------------------------------------------------- | ---------------------------------------------- |
+| `@loadbare/app/server`     | `row`, `rows`, `patch`, `url`, `choices`, `refusal`, `createHub`, and the types `Queries`, `Requests`, `HubContext`, `Hub` | [Page Files](./page-files.md), [The data channel](./server.md#the-data-channel) |
+| `@loadbare/app/express`    | `hubRoutes`                                                      | [The Express Server](./server.md)              |
+| `@loadbare/app/types`      | `HubRequest`, `ResponseItem`, `HubRequestDone`, `HubLifecycle`, and the rules the hub applies: `readAs`, `parseFilter`, `passes`, `passesTerm` | [The data channel](./server.md#the-data-channel), [Order](./data-binding.md#order), [Filters](./data-binding.md#filters) |
+| `@loadbare/app`            | `applyRow`                                                       | [Filling a subtree by hand](./custom-elements.md#filling-a-subtree-by-hand) |
+| `@loadbare/app/constants`  | Every name on this page; see [Constants](#constants)             | [Code](./custom-elements.md#code)              |
+
+## Constants
+
+`@loadbare/app/constants` exports every name above.  Custom element code
+imports them rather than writing a string.
+
+| Constant                  | Value                                   |
+| ------------------------- | --------------------------------------- |
+| `ATTR_QUERY`              | `lb-query`                              |
+| `ATTR_COLUMN`             | `lb-column`                             |
+| `ATTR_SHOW`               | `lb-show`                               |
+| `SHOW_NOT`                | `!`, written before a column in `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_QUERY_UNSORTED_COUNT` | `lb-query-unsorted-count`             |
+| `ATTR_QUERY_ORDER`        | `lb-query-order`                        |
+| `ATTR_GROUP`              | `lb-group`                              |
+| `ATTR_GROUP_LIVE`         | `lb-group-live`                         |
+| `ATTR_GROUP_COLUMN`       | `lb-group-column`                       |
+| `ATTR_GROUP_VALUE`        | `lb-group-value`                        |
+| `LIVE_GROUP`              | `[lb-group-live]`, the selector for a group's element |
+| `ATTR_COUNT`, `ATTR_SUM`, `ATTR_AVG`, `ATTR_MIN`, `ATTR_MAX` | `lb-count`, `lb-sum`, `lb-avg`, `lb-min`, `lb-max` |
+| `AGGREGATES`              | All five aggregate attributes           |
+| `ORDER_DESCENDING`        | `-`, written before a column in an order |
+| `COLUMN_TYPES`            | `number`, `boolean`, `text`             |
+| `CHOICES_QUERY`           | `lb-choices`                            |
+| `ATTR_ORDER`              | `lb-order`                              |
+| `ATTR_FILTER`             | `lb-filter`                             |
+| `FILTER_OPERATORS`        | Every filter operator, the longer first |
+| `ATTR_ROW_CREATED`        | `lb-row-created`                        |
+| `ATTR_ROW_CHANGED`        | `lb-row-changed`                        |
+| `ATTR_ROW_MOVED`          | `lb-row-moved`                          |
+| `ATTR_ROW_REQUESTED`      | `lb-row-requested`                      |
+| `REQUESTED_CREATED`, `REQUESTED_CHANGED`, `REQUESTED_MOVED` | `created`, `changed`, `moved` |
+| `ATTR_ROW_UNSORTED`       | `lb-row-unsorted`                       |
+| `ATTR_ROW_LEAVING`        | `lb-row-leaving`                        |
+| `ATTR_GROUP_LEAVING`      | `lb-group-leaving`                      |
+| `ATTR_REQUEST`            | `lb-request`                            |
+| `LB_EVENT_NAME`           | `lb-request`, the event every request travels as |
+| `LB_DONE_EVENT_NAME`      | `lb-request-done`                       |
+| `ATTR_REQUEST_PENDING`    | `lb-request-pending`                    |
+| `ATTR_REQUEST_ERROR`      | `lb-request-error`                      |
+| `ATTR_REQUEST_REFUSED`    | `lb-request-refused`                    |
+| `LB_REFUSAL_STATUS`       | `422`                                   |
+| `COMMAND_EDIT`, `COMMAND_NEW`, `COMMAND_RELEASE`, `COMMAND_SORT` | `--lb-edit`, `--lb-new`, `--lb-release`, `--lb-sort` |
+| `LB_COMMANDS`             | All four commands                       |
+| `LB_COMMAND_PREFIX`       | `--lb-`                                 |
+| `ATTR_ROW_EDITING`        | `lb-row-editing`                        |
+| `ATTR_SELECT`             | `lb-select`                             |
+| `ATTR_ROW_SELECTED`       | `lb-row-selected`                       |
+| `LB_RESERVED_PREFIX`      | `lb-`                                   |
+| `REQUEST_ROW_INSERT`      | `lb-row-insert`                         |
+| `REQUEST_ROW_UPDATE`      | `lb-row-update`                         |
+| `REQUEST_ROW_DELETE`      | `lb-row-delete`                         |
+| `LB_ROW_REQUESTS`         | All three request names                 |
+| `LB_METHODS`              | The four reserved methods               |
+| `BROWSER_LIFECYCLE`       | The browser callbacks the build refuses |
+| `KIND_ROW`                | `row`                                   |
+| `KIND_ROWS`               | `rows`                                  |
+| `URL_QUERY`               | `lb-url`                                |
+| `URL_COLUMN_PATH`         | `lb-path`                               |
+| `URL_COLUMN_PAGE_LABEL`   | `lb-page-label`                         |
+| `URL_COLUMN_PAGE_UNKNOWN` | `lb-page-unknown`                       |
+| `ATTR_URL_LINK`           | `lb-url-link`                           |
+| `ATTR_URL_PARM`           | `lb-url-parm`                           |
+| `ATTR_URL_PUSH`           | `lb-url-push`                           |
+| `ATTR_URL_UNKNOWN`        | `lb-url-unknown`                        |
+| `ATTR_EXP_SLOT`           | `lb-exp-slot`                           |
+| `ATTR_EXP_TEMPLATE`       | `lb-exp-template`                       |
+| `ATTR_PAGE`               | `lb-page`                               |
+| `ATTR_PAGE_TITLE`         | `lb-page-title`                         |
+| `DEVELOPER_ATTRIBUTES`    | The seventeen attributes a developer writes |
+| `HUB_TAG_NAME`            | `lb-hub`                                |
+| `LB_ENDPOINT`             | `/lb`                                   |
+| `LB_REQUEST_TIMEOUT_MS`   | `10000`                                 |

package/docs/reference/overview.md

@@ -38,3 +38,9 @@ serves, and the custom elements those pages are made of.
 | [`<tag-name>.html`](./custom-elements.md#html)         | The markup the tag expands into |
 | [`<tag-name>.browser.ts`](./custom-elements.md#code)   | The class the tag registers     |
 | [The Basic Widget Library](./widgets.md)               | `@loadbare/widgets`             |
+
+## Names
+
+| Topic                    | Description                                                  |
+|--------------------------|--------------------------------------------------------------|
+| [Names](./names.md)      | Every name Loadbare owns, the constants, and where each is defined |

package/docs/reference/page-files.md

@@ -14,7 +14,9 @@ Name the landing page `index.page.html`. A bare `/` resolves to `index`, and
 every other path names the page whose stub it is.
 
 Put the files anywhere under `src/`. The builder pairs them by stub, not by
-directory; `src/pages/` is the convention.
+directory; `src/pages/` is the convention. The page namespace is flat, so
+`src/deep/path/mypage.page.html` is the page for `/mypage`, and a stub is
+unique across the application.
 
 ## What the page files are
 
@@ -122,8 +124,19 @@ including a `row` query's: an aggregate row answers with a constant key. The
 hub matches rows to live rows by key, and a request names a row by key.
 
 Kind and key belong to the name, so one name answers with one shape, always,
-and `createHub` leaves out an answer that disagrees with its declaration. A
-page that needs the same data as one row and as a set declares two queries.
+and `createHub` leaves out an answer that disagrees with its declaration,
+with a warning naming the query. A page that needs the same data as one row
+and as a set declares two queries.
+
+`createHub` refuses at startup a page that declares a query, a handler or a
+`crud` entry whose name begins with `lb-`, a query whose order has a term
+naming no column, and a type it does not know.
+
+Every query and every handler receives `ctx`, the application's own request
+context, built by `contextFor`; see
+[the Express server](./server.md#database-layer). Loadbare declares it
+empty and never reads it, so a query finds exactly what the application put
+there.
 
 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.
@@ -230,13 +243,20 @@ export const requests: Requests = {
 ```
 
 Declare every request the page allows. The builder refuses markup naming a
-request the page does not declare, and the server refuses one that arrives
-anyway; see [The markup checks](./data-binding.md#the-markup-checks).
+request the page does not declare; see
+[The markup checks](./data-binding.md#the-markup-checks). One can still
+arrive, from a widget's script or from outside the page. The server then
+warns on its console, naming the page and the missing entry, and answers
+200 with no response items, so nothing lands and `lb-request-pending`
+clears. A request carrying no name answers 400, and a `run` that throws
+anything but a [refusal](#refusing-a-request) answers 500.
 
 ### crud
 
 Declare what the three requests Loadbare provides do under `crud`, keyed by
-the query they operate on:
+the query they operate on. Each key is the request name with its `lb-`
+stripped and the rest camel-cased, so the attribute, the wire and the key
+are one vocabulary:
 
 | Request name    | Runs        | `run` receives   |
 |-----------------|-------------|------------------|
@@ -295,8 +315,9 @@ export const requests: Requests = {
 ```
 
 Declare every request the query permits. The builder refuses markup sending
-a request a query does not declare, and the server refuses one that arrives
-anyway. A query with no `crud` entry permits none.
+a request a query does not declare, and the server answers one that arrives
+anyway as it does an undeclared handler, with a console warning and nothing
+to land. A query with no `crud` entry permits none.
 
 Write `rowUpdate` to set the columns `values` names and leave every other
 column as it is. A form or a live row sends every control it gathers, and a
@@ -361,7 +382,8 @@ one row dropped, one row edited — and leave `refresh` empty. A refreshed
 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).
+  [order](./data-binding.md#order), or leaves it where the user is working
+  when the request came from inside its list; a refresh would do the same.
 - 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
@@ -374,7 +396,7 @@ removing a row never reorders the rest. So does an insert, which has the new
 row's key once it has written it, and the hub places the new row by the
 query's order. `createHub` refuses at startup a `crud` `rowInsert`,
 `rowUpdate` or `rowDelete` on a `rows` query whose `refresh` names that same
-query.
+query. A `row` query sends one row and may refresh itself.
 
 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.
@@ -440,6 +462,21 @@ nothing else `run` returned is sent, since both answered for the URL the page
 left. The loaded page reads the new parms through `contextFor`; see
 [the Express server](./server.md#database-layer).
 
+- A `url()` naming no column, or holding a value that is not a string, is
+  warned about on the server console and ignored, and the refresh set runs
+  as usual.
+- If loading the page fails, the write has still happened. The response
+  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
+  sent the request.
+- 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.
+
+Saving what the user has on screen, for `onPageEnter` to restore, is a
+declared request with `refresh: []`, whose handler each page passes to a
+routine the application's pages share. A custom element naming `lb-url`
+sees every change of the URL and sends it.
+
 ### Refusing a request
 
 A handler refuses a request by throwing `refusal()`, with words written for

package/docs/reference/server.md

@@ -17,7 +17,7 @@ import { readFileSync } from "node:fs";
 import express, { type Request } from "express";
 import { hubRoutes } from "@loadbare/app/express";
 import type { HubContext } from "@loadbare/app/server";
-import { hub } from "./dist/pages";
+import { hub } from "./dist/pages.ts";
 import { openDb } from "./src/database";
 
 const DIST = path.resolve("dist");
@@ -181,3 +181,56 @@ open across the two, is both.
 Add a field for anything else a request needs — the authenticated user, a
 request id, a feature flag set. Queries and requests read them from `ctx`; see
 [page files](./page-files.md).
+
+## The data channel
+
+One path, one method. The hub sends every round trip as
+`POST /lb/<stub>?<query string>`, with the query string the browser is
+showing, verbatim. An empty body, or `{}`, asks for the page load. Any other
+body is a request:
+
+```ts
+interface HubRequest {
+  name: string;
+  query?: string;
+  key?: string;
+  keys?: string[];
+  values?: Record<string, string>;
+  rows?: Record<string, { key: string; values: Record<string, string> }[]>;
+}
+```
+
+A refused request is answered with status 422 and
+`{ refusal: { message?, columns? } }`, a request with no name with 400 and
+`[]`, and
+any other failure with 500 and no body; see
+[Refusing a request](./page-files.md#refusing-a-request). Every other
+response is an array of response items:
+
+```ts
+interface ResponseItem {
+  query: string;
+  kind: "row" | "rows";
+  key: string;
+  row?: Row;
+  rows?: Row[];
+  patch?: { rows?: Row[]; drop?: unknown[] };
+}
+```
+
+A response item carries exactly one of `row`, `rows` or `patch`. A patch
+answers a `rows` query only: rows named in `rows` are added or updated, keys
+in `drop` are removed, and every other row is left alone. A `rows` item on
+the answer that loads the page also carries the query's declared `order`
+and `types`, which the hub keeps for every answer after it.
+
+A choice is sent as `lb-row-update` for `lb-choices`, keyed by the path,
+with every choice made on the page as `values`; see
+[Choices](./data-binding.md#choices).
+
+`createHub(pages)` builds the `Hub`, which has two calls, both answering
+with response items: `dataForPage(page, ctx, options)` for a page load, and
+`runRequest(page, request, ctx)` for a request. `options.parms` are the
+parms the page is loaded at, and `options.follow` false ignores a `url()`
+from `onPageEnter`. `hubRoutes` passes both, and an application calls
+neither.

package/docs/reference/widgets.md

@@ -155,7 +155,9 @@ row, the row template, and optionally a footer, each as a `<template>`:
 | `<template lb-exp-template="foot">` | The `<tfoot>`                         |
 | Any other `<template>`            | The row or group template, in the `<tbody>` |
 
-- The hub places the rows by the query's order and builds its groups. The
+- The hub places the rows by the query's order and builds its groups, and
+  leaves them where they stand for an edit from inside the table; see
+  [Rows the user is working in](./data-binding.md#rows-the-user-is-working-in). The
   rows land in the one `<tbody>`, so a group here is a heading row with its
   rows after it.
 - `lb-order` and `lb-filter` go on the `lb-table` itself, beside
@@ -174,6 +176,13 @@ row, the row template, and optionally a footer, each as a `<template>`:
 - Text selected in a cell whose `lb-column` the table's `lb-filter` names
   becomes that column's filter in `lb-choices`: `=` for the whole text,
   `^=` from its start, `$=` up to its end, `*=` otherwise.
+- The heading of the order's leading column carries a triangle for the
+  direction, read from [`lb-query-order`](./data-binding.md#order). A
+  heading's column is the `lb-column` in the cell at its position in the row
+  template. While rows stand out of order the triangle carries
+  `data-unsorted` and a click on its heading re-sorts. With `lb-order`, a
+  click on the sorted heading reverses the order and a click on another
+  sorts by its column. Not on a grouped table.
 
 ## `lb-confirm`
 

package/docs/testing.md

@@ -208,7 +208,9 @@ evidence here.
 - `lb-query-row-count` counts the rows showing, so all rows and a patch
   ending in the same state report the same number, and a row a filter hides
   is not counted
-- the order places all rows and a patch alike, groups come and go with
+- the order places all rows and a patch alike, except where an edit came
+  from inside the list, which leaves its rows standing and stamped until
+  the user asks for the order; groups come and go with
   their rows to any depth, aggregates follow every landing, and every change
   leaves a stamp a stylesheet can see (`lb-order.test.ts`)
 - a filter's text reads and passes values as documented, and a choice of
@@ -279,6 +281,8 @@ What the hub is tested for here:
   `lb-page-label`, and a column per query parm, and sets the document title
 - `lb-url-link` pushes state and swaps the page on a plain primary click,
   `popstate` reverses it, and an ordinary anchor is left alone
+- `lb-url-parm` writes a link's `href` from its row as held, starting from
+  the `href` as written every time (`lb-apply.test.ts`)
 - a control inside `lb-query="lb-url"` writes its parm, replacing the history
   entry or pushing one with `lb-url-push`, and the page's queries reload
 - an `lb-url` item in a server answer writes the URL and lands the page

package/docs/tutorials/040-displaying-data.md

@@ -130,7 +130,7 @@ requests to the correct page code.
 import express from "express";
 import { readFileSync } from "node:fs";
 import { hubRoutes } from "@loadbare/app/express";
-import { hub } from "./dist/pages";
+import { hub } from "./dist/pages.ts";
 import { openDb } from "./src/database";
 
 const app = express();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@loadbare/app",
   "description": "High performance web app framework for server-bound applications",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "type": "module",
   "files": [
     "dist",

package/skills/loadbare-app/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: loadbare-app
-description: Build server-bound web applications with Loadbare/app. Covers the file conventions the builder finds by name (`chrome.html`, `*.page.html`, `*.queries.ts`, `*.requests.ts`, `imports.ts`, `<tag>.html`, `<tag>.browser.ts`); the `lb-*` attribute vocabulary that lands query rows on HTML and issues requests (`lb-query`, `lb-column`, `lb-show`, `lb-request`); queries declared with `row(key, run)` and `rows(key, run)`; the URL as the hub's own query `lb-url`, with `lb-url-link`, `lb-url-push` and `lb-url-unknown`; the user's order and filters as the hub's query `lb-choices`, read by `lb-order` and `lb-filter`; one form pointed at a row by the `--lb-edit`, `--lb-new` and `--lb-release` commands; build-time expansion with `exp-*` parameters, `lb-exp-slot` and `lb-exp-template`; custom elements as form-associated controls and row hosts; the Express wiring with `hubRoutes`; and the `@loadbare/widgets` library. Use whenever a task involves `@loadbare/app`, `@loadbare/widgets`, `loadbare-app-build`, an `lb-` attribute, or a page, query, request or custom element file in a Loadbare application. The model is not React, htmx or REST, and cannot be inferred from them.
+description: Build server-bound web applications with Loadbare/app. Covers the file conventions the builder finds by name (`chrome.html`, `*.page.html`, `*.queries.ts`, `*.requests.ts`, `imports.ts`, `<tag>.html`, `<tag>.browser.ts`); the `lb-*` attribute vocabulary that lands query rows on HTML and issues requests (`lb-query`, `lb-column`, `lb-show`, `lb-request`); queries declared with `row(key, run)` and `rows(key, run)`; the URL as the hub's own query `lb-url`, with `lb-url-link`, `lb-url-parm`, `lb-url-push` and `lb-url-unknown`; the user's order and filters as the hub's query `lb-choices`, read by `lb-order` and `lb-filter`; one form pointed at a row by the `--lb-edit`, `--lb-new` and `--lb-release` commands; re-sorting a list with `--lb-sort`; build-time expansion with `exp-*` parameters, `lb-exp-slot` and `lb-exp-template`; custom elements as form-associated controls and row hosts; the Express wiring with `hubRoutes`; and the `@loadbare/widgets` library. Use whenever a task involves `@loadbare/app`, `@loadbare/widgets`, `loadbare-app-build`, an `lb-` attribute, or a page, query, request or custom element file in a Loadbare application. The model is not React, htmx or REST, and cannot be inferred from them.
 license: Apache-2.0
 metadata:
   package: "@loadbare/app"
@@ -191,6 +191,12 @@ row is filled from the nested query's last answer, whatever order they land
 in.
 
 **A `rows` query declares its order, and the hub places every row by it.**
+An edit sent from inside a list leaves that list's rows where they stand,
+stamped `lb-row-unsorted` where out of order, until the page loads, the
+user's order or filter changes, or a button with `commandfor` naming the
+list sends `command="--lb-sort"`, which places them with no round trip;
+show it by `[lb-query-unsorted-count]`.  Never refresh to make rows hold
+still, and never to put them back in order.
 `rows("id", run, { order: "category_order,name" })`; a column after `-` sorts
 descending, and values compare by JSON type, so a numeric sort column is a
 JSON number or is declared one: `types: { amount: "number" }` beside
@@ -265,7 +271,8 @@ in every row.  Write one form naming the set's query, outside every row,
 often in a `<dialog>`, and give it an `id`.  A `type="button"` with
 `commandfor="<id>"` and `command="--lb-edit"` in a live row fills it from
 that row with no round trip; `--lb-new` starts it empty for an insert;
-`--lb-release` lets it go.  The form's `lb-key-value` is the row's key, empty
+`--lb-release` lets it go.  (`--lb-sort` is the fourth command, for a list,
+not a form.)  The form's `lb-key-value` is the row's key, empty
 for a new row, absent when not in use, and a stylesheet shows Save or Save
 new by it.  A successful request from the form, or its dialog closing, lets
 it go.  Which row is being edited is never a query parm.  A row that must be
@@ -278,8 +285,8 @@ fetched to be edited is another page, with that row as its master.
 Each works on a `row` query as well as a `rows` query, since the element a
 `row` lands on carries its key.  Every other request name is a declared
 request, under `handlers`.  The build refuses markup naming a query or
-request the page does not declare, and the server refuses one that arrives
-anyway.
+request the page does not declare.  One that arrives anyway, from a script,
+is warned about on the server console and answered with nothing.
 
 **An empty key is a row not yet entered.**  A `row` query answering with an
 empty key, or a form `--lb-new` pointed, carries `lb-key-value=""`.  The hub
@@ -321,7 +328,8 @@ 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 row whose position changes: the hub places it by the query's order.
+- A row whose position changes: the hub places it by the query's order, or
+  holds it where the user is working; a refresh changes neither.
 - A group that appears or goes: the hub makes it with its first row and
   removes it with its last.
 - A row whose other columns change with the edit: re-read the row and patch
@@ -359,7 +367,9 @@ per query parm.  A control inside `lb-query="lb-url"` carrying
 `lb-request="lb-row-update"` writes its parm; the hub replaces the history
 entry, or pushes one when the control carries `lb-url-push`, and reloads the
 page's queries with no request to the server.  An `<a lb-url-link>` moves
-to its `href`.  Queries still take no arguments: `contextFor(req, parms)`
+to its `href`; inside a row, `lb-url-parm="topic_id"` adds that column of
+the row to the `href` as the parm of the same name, so a link to another
+page narrowed by the row is a link, never a request or script.  Queries still take no arguments: `contextFor(req, parms)`
 puts parms onto `ctx`, and a query reads them there.  Read them from
 `parms`, never `req.query`, because `contextFor` may be called twice for one
 request.  A parm is user input, so validate it where it is read.  Do not
@@ -392,10 +402,13 @@ lb-query="lb-url">` in the chrome for it.
 whole data channel.
 
 **The developer writes `lb-*` attributes in markup, and script never
-assigns them.**  The builder refuses any `lb-` attribute other than
-`lb-query`, `lb-column`, `lb-show`, `lb-order`, `lb-filter`, `lb-request`,
-`lb-url-link`, `lb-url-push` and `lb-url-unknown`.  Everything else with the
-prefix is a stamp the hub or the builder writes.
+assigns them.**  The builder refuses any `lb-` attribute other than the
+seventeen in [Attributes](references/names.md#attributes): `lb-query`,
+`lb-column`, `lb-show`, `lb-order`, `lb-filter`, `lb-group`, `lb-count`,
+`lb-sum`, `lb-avg`, `lb-min`, `lb-max`, `lb-select`, `lb-request`,
+`lb-url-link`, `lb-url-parm`, `lb-url-push` and `lb-url-unknown`.  `lb-exp-slot` and
+`lb-exp-template` are expansion's, and never reach the page.  Everything
+else with the prefix is a stamp the hub or the builder writes.
 
 **`lb-` belongs to Loadbare.**  The application should never name anything
 with the `lb-` prefix anywhere: no attribute, query, column, request, custom
@@ -500,7 +513,6 @@ with the package, so no network is needed.
 - [`references/css.md`](references/css.md) — how stylesheets are ordered.
 - [`references/widgets.md`](references/widgets.md) — the basic widget
   library.
-- [`references/TECHREF-1.0.md`](references/TECHREF-1.0.md) — the reserved
-  names, what a URL names and
-  [query parms](references/TECHREF-1.0.md#query-parms).  Read it before designing around something the other
-  references do not mention.
+- [`references/names.md`](references/names.md) — every name Loadbare
+  owns, the constants, and the section defining each.  Check a name here
+  before designing around something the other references do not mention.

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

@@ -44,11 +44,16 @@ The builder classifies by name, not location.
 | `*.queries.ts`             | A page's queries, matched by base name            |
 | `imports.ts`               | The packages this app takes widgets from          |
 | `*.css`                    | A stylesheet — see [CSS](./css.md)                |
-| Any other `.html`          | A widget definition, named for the tag it defines |
+| `<tag-name>.html`          | A widget definition, named for the tag it defines |
 | `<tag>.browser.ts`         | A widget script, named for the tag it registers   |
 
 Give the application exactly one `chrome.html` and at most one `imports.ts`.
-Give every `.requests.ts` and `.queries.ts` a `.page.html` of the same base name.
+Give every `.requests.ts` and `.queries.ts` a `.page.html` of the same base name;
+one with no page is a build error.
+
+A widget definition is exactly `<kebab-case-name>.html`. Any other `.html`
+file is an error when it looks like a definition with capitals in its name,
+and is skipped otherwise.
 
 Name a widget script `<tag>.browser.ts`, not `<tag>.ts`. Only a file whose
 name carries `.browser` is bundled for the browser; every other module under
@@ -141,6 +146,10 @@ does when the server starts, so a module that connects to a database at
 import connects during the build too; open connections in `contextFor`
 instead.
 
+It also writes `client-entry.ts`, the generated entry `client.js` is bundled
+from, and leaves it there. Nothing reads it after the bundle, and an
+application neither writes nor imports it.
+
 The builder writes `app.css` only when it finds a stylesheet, and `pages.ts`
 only when some page has a `.requests.ts` or a `.queries.ts` file. Import `hub`
 from `pages.ts` — see [The Express Server](./server.md) for the rest of the