@loadbare/app 0.19.0 → 0.20.0

package/skills/loadbare-app/references/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/skills/loadbare-app/references/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/skills/loadbare-app/references/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/skills/loadbare-app/references/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/skills/loadbare-app/references/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`