@loadbare/app 0.20.0 → 0.22.0

package/docs/reference/data-binding.md

@@ -119,9 +119,9 @@ from its nearest ancestor row: the live row it is in, or the element a
 it reads from that query's rows.
 
 An element with `lb-query` and `lb-column` both shows the rows of its own
-query and holds the column of the row around it. This
-[`<lb-options>`](./widgets.md#lb-options) lists the accounts and holds its
-row's `account`:
+query and holds the column of the row around it. This `<lb-options>`, from
+[`@loadbare/widgets`](./widgets.md), lists the accounts and holds its row's
+`account`:
 
 ```html
 <lb-options lb-query="accounts" lb-column="account">
@@ -167,8 +167,8 @@ option for the value shows no selection.
 
 The hub hands every value to the browser as the server sent it. What a
 number, a date or a null looks like is decided in the query, or by a custom
-element that formats it, such as
-[`lb-number` and `lb-date`](./widgets.md#lb-number-and-lb-date). Send a
+element that formats it, such as `lb-number` and `lb-date` in
+[`@loadbare/widgets`](./widgets.md). Send a
 column the user sorts or filters raw, and format it in the element.
 
 ### Checkboxes
@@ -312,9 +312,12 @@ puts it somewhere else, so all rows landing again unchanged move nothing.
 A landing that answers a request sent from inside a list moves none of that
 list's rows. The request is from inside the list when the list is the
 nearest element carrying `lb-query` around the element that sent it: a
-control in a live row, or a ghost row. A form elsewhere on the page is not
-inside the list. A user who changes a value sees the value change, and the
-row stays where they were working:
+control in a live row, or a ghost row. A form that
+[`--lb-edit`](#editing-a-row-in-one-form) pointed at a live row finishes an
+edit begun in that row, so its request is from inside the row's list,
+wherever the form sits. Any other form elsewhere on the page is not inside
+the list. A user who changes a value sees the value change, and the row
+stays where they were working:
 
 | The answer                               | The row                                           |
 |------------------------------------------|---------------------------------------------------|
@@ -941,7 +944,8 @@ nothing is not sent.
 
 For a query the hub serves, `lb-url` or `lb-choices`, the hub answers
 `lb-row-update` itself, with no round trip; see
-[Query parms](./chrome.md#query-parms) and [Choices](#choices).
+[Query parms](./chrome.md#query-parms) and [Choices](#choices). The third,
+`lb-hub`, takes no request.
 
 A key comes from a live row, or from an element a `row` landed on, so all
 three work against either kind:
@@ -958,8 +962,11 @@ update from a form or a live row sends every control it gathers. The
 application writes one `rowUpdate` for both, setting the columns `values`
 names, as an SQL UPDATE does.
 
-After a successful insert gathered from a form, the hub resets the form. A
-failed insert leaves the entry for the user to correct.
+After a successful insert gathered from a form, the hub resets the form,
+unless the answer landed the new row on it. A form over a `row` query not
+yet entered, whose insert answers `url()` to the new key, then shows the row
+just saved, on record. A failed insert leaves the entry for the user to
+correct.
 
 Leave `lb-request` off a control inside a form or a live row that sends its
 own update, or the same edit is written twice.
@@ -1033,6 +1040,12 @@ An `lb-show` in the form reads from the row it was pointed at. With no row,
 every column is null, so `lb-show="!id"` shows only while entering a new
 row.
 
+A request from a form Edit pointed is sent from inside the row's list, so
+the row stays where the user was working, even when the filter would now
+hide it or the order would move it; see
+[Rows the user is working in](#rows-the-user-is-working-in). A form New
+pointed is not inside any list, and its rows are placed by the order.
+
 A successful request from the form lets it go, as Cancel does: the form
 empties, its controls return to their defaults, and the stamps go. A failed
 one leaves the form as the user had it, to correct.
@@ -1245,7 +1258,9 @@ A reset of any form, whether the hub's, a reset button's or a script's,
 returns its controls to their defaults, and the hub removes
 `lb-column-value` from each of them. A cancelled reset keeps both.
 
-A page load that fails lands nothing and is reported to the console. A load
+A page load that fails lands nothing and is reported to the console, and
+the query `lb-hub` says so; see [The hub's state](./chrome.md#the-hubs-state).
+A load
 started by a request for `lb-url` stamps the element that sent it, as any
 request stamps its element.
 

package/docs/reference/dev-server.md

@@ -0,0 +1,171 @@
+# The Dev Server
+
+`@loadbare/app/dev` runs an application while it is being written. After
+any change, to markup, CSS, a query, a handler, a server module or the
+server's entry file, the developer refreshes the browser. Nothing is ever
+restarted by hand, a refresh never meets a refused connection, and it never
+loads a half-written `client.js`.
+
+```ts
+// dev.ts
+import { devServer } from "@loadbare/app/dev";
+
+await devServer({ server: "server.ts" });
+```
+
+```json
+{
+  "scripts": {
+    "dev": "node dev.ts"
+  }
+}
+```
+
+## Why a refresh is enough
+
+- **The static output is read per request.** The server reads
+  `dist/app.html`, and sends `client.js` and `app.css` from disk, so markup,
+  CSS and browser code need only a rebuild.
+- **Only server modules need a restart.** `dist/pages.ts` and everything it
+  imports are loaded once, and Node cannot unload a module. A new process is
+  the honest answer, and a Loadbare server starts in well under a second.
+- **The URL holds the page's state.** A refresh returns the user to the
+  same page, row and query parms, so swapping code into a live page buys
+  almost nothing.
+
+## What it does
+
+```
+browser --> devServer :port --> the application's server :appPort (a child)
+                |
+                +-- the build, watching src (in process)
+```
+
+1. Builds `dist/`, then rebuilds whenever an `.html`, `.ts` or `.css` file
+   under `src` changes.  A burst of changes, such as an editor's save or a
+   branch switch, is one build.
+2. Runs the application's server as a child process, exactly as it runs in
+   production, on `appPort`.
+3. Restarts that server after a build when a server-side file changed: any
+   `.ts` under `src` other than a `.browser.ts`, or a change to the page
+   registry `dist/pages.ts`, which a page gained or lost changes. It also
+   restarts it when the server's entry file changes. CSS, HTML and browser
+   code never restart it.
+4. Holds every request while a build runs or the server restarts, and sends
+   it on when both are done.
+5. Keeps serving the last good build when a build fails, and says why in
+   the console.
+6. Answers 502, "The app server is down; see the dev console.", when the
+   server has exited, for example on a throw at import, and starts it again
+   on the next save.
+7. Says plainly when its port is in use, and exits.
+8. Passes everything else through, method, path, headers and body,
+   `POST /lb/*` included.
+9. Stops the server however the dev server ends: Ctrl-C, a kill, or a
+   crash.
+
+The application's server reads its port from the environment, as the
+[server recipe](./server.md) does:
+
+```ts
+app.listen(Number(process.env.PORT ?? 8787));
+```
+
+## Options
+
+Every option but `server` has a default.
+
+| Option    | Default                          | Meaning                                                |
+|-----------|----------------------------------|--------------------------------------------------------|
+| `server`  | (required)                       | The application's server entry file                    |
+| `port`    | `PORT` from the environment, or `8787` | The port the browser uses                        |
+| `host`    | `127.0.0.1`                      | The host that port listens on                          |
+| `appPort` | `port + 10000`                   | Where the application's server listens                 |
+| `portEnv` | `PORT`                           | The variable the application's server reads its port from |
+| `node`    | `["--env-file-if-exists=.env"]`  | Node's arguments before the entry file                 |
+| `src`     | `src`                            | The builder's source tree                              |
+| `out`     | `dist`                           | The builder's output                                   |
+| `log`     | the console                      | Where progress goes, one line at a time                |
+
+A server written in TypeScript runs under Node's own type stripping, Node
+22.18 and later. For a runner such as tsx, name it in `node`:
+`node: ["--import", "tsx"]`.
+
+`devServer` resolves once the first build is done and the server accepts
+connections, with `{ port, close() }`.
+
+## Assembling your own
+
+`devServer` is a short composition of parts that are exported on their own.
+An application that wants something else, such as other files that restart
+the server, a second server, or a reload pushed to the browser, builds its
+own from them.
+
+| Part         | From                   | Does                                                         |
+|--------------|------------------------|--------------------------------------------------------------|
+| `watchApp`   | `@loadbare/app/build`  | Builds, rebuilds on a change, and reports each build         |
+| `buildApp`   | `@loadbare/app/build`  | Builds once                                                  |
+| `appServer`  | `@loadbare/app/dev`    | The application's server as a child process, restarted on demand |
+| `gate`       | `@loadbare/app/dev`    | Holds requests while any reason to hold them stands          |
+| `devProxy`   | `@loadbare/app/dev`    | The browser's port, passing requests through a gate          |
+
+`watchApp({ src, out, minify, onStart, onBuilt })` builds at once, then
+again on each change. `onStart(changed)` is called as a build begins, with
+the files under `src` that changed, relative to it, and an empty list for
+the first. `onBuilt(outcome)` is called as it ends, with `{ ok: true,
+changed, built }` or `{ ok: false, changed, error }`; `built.files` lists
+what was written. Builds never overlap: changes during one are gathered into
+the next. It returns `{ ready, close() }`, where `ready` resolves with the
+first build's outcome. Paths resolve against the working directory.
+
+`buildApp({ src, out, minify })` builds once, and throws when the build
+fails. A build writes nothing until every output is ready, so a failed one
+leaves the last good build in place. `loadbare-app-build` is a thin command
+over these two.
+
+`appServer({ entry, port, portEnv, node, log })` returns `{ restart(),
+stop(), state }`. `restart()` stops the server if it runs, starts it, and
+resolves once it accepts connections, or has exited instead. `state` is
+`starting`, `running`, `down` for a server that exited on its own, or
+`stopped`. Once stopped, it never starts again. The child is killed when
+this process exits, however it exits.
+
+`gate()` returns `{ close(reason), open(reason), wait(), isOpen }`. Each
+`close` is matched by its own `open`, and `wait()` resolves once every
+close has been. A build and a restart can each hold requests without one
+ending the other's hold.
+
+`devProxy({ port, host, target, gate, isDown })` listens on `port` and
+passes every request to `target` once the gate is open, answering 502 while
+`isDown()` is true. It resolves with the listening server, and rejects with
+a plain message when the port is in use.
+
+A dev server that also restarts on a change to `config/`:
+
+```ts
+import { watch } from "node:fs";
+import { watchApp } from "@loadbare/app/build";
+import { appServer, devProxy, gate } from "@loadbare/app/dev";
+
+const held = gate();
+const app = appServer({ entry: "server.ts", port: 18787 });
+const restart = async () => {
+  held.close("server");
+  await app.restart();
+  held.open("server");
+};
+
+const watcher = watchApp({
+  onStart: () => held.close("build"),
+  onBuilt: async (outcome) => {
+    console.log(outcome.ok ? outcome.built.summary : outcome.error.message);
+    if (outcome.changed.some((f) => f.endsWith(".ts"))) await restart();
+    held.open("build");
+  },
+});
+watch("config", { recursive: true }, () => void restart());
+
+await watcher.ready;
+await restart();
+await devProxy({ port: 8787, target: 18787, gate: held, isDown: () => app.state === "down" });
+```

package/docs/reference/names.md

@@ -103,6 +103,7 @@ assigns one.
 | `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-load-state`, `lb-server-state`, `lb-error`, `lb-pending`, `lb-as-of` on `<lb-hub>` | Hub | [The hub's state](./chrome.md#the-hubs-state) |
 | `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)                 |
@@ -110,12 +111,13 @@ assigns one.
 ## Reserved queries
 
 The hub serves these in the browser.  Every page and the chrome may name
-them, and a page declares neither.
+them, and a page declares none.
 
 | 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)  |
+| `lb-hub`     | `row` | `lb-path` | `lb-path`, `lb-load-state`, `lb-server-state`, `lb-error`, `lb-pending`, `lb-as-of` | [The hub's state](./chrome.md#the-hubs-state) |
 
 No query parm is reserved: a column of `lb-url` whose name begins with
 `lb-` is never a query parm.
@@ -175,6 +177,8 @@ accessor or field named `lb` and a capital.
 | -------------------------- | ---------------------------------------------------------------- | ---------------------------------------------- |
 | `@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/dev`        | `devServer`, `appServer`, `gate`, `devProxy`, `DOWN_MESSAGE`     | [The Dev Server](./dev-server.md)              |
+| `@loadbare/app/build`      | `buildApp`, `watchApp`                                           | [Assembling your own](./dev-server.md#assembling-your-own) |
 | `@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)              |
@@ -244,6 +248,15 @@ imports them rather than writing a string.
 | `URL_COLUMN_PATH`         | `lb-path`                               |
 | `URL_COLUMN_PAGE_LABEL`   | `lb-page-label`                         |
 | `URL_COLUMN_PAGE_UNKNOWN` | `lb-page-unknown`                       |
+| `HUB_QUERY`               | `lb-hub`                                |
+| `HUB_COLUMN_LOAD_STATE`   | `lb-load-state`                         |
+| `HUB_COLUMN_SERVER_STATE` | `lb-server-state`                       |
+| `HUB_COLUMN_ERROR`        | `lb-error`                              |
+| `HUB_COLUMN_PENDING`      | `lb-pending`                            |
+| `HUB_COLUMN_AS_OF`        | `lb-as-of`                              |
+| `HUB_LOAD_LOADING`, `HUB_LOAD_LOADED`, `HUB_LOAD_FAILED` | `loading`, `loaded`, `failed`           |
+| `HUB_SERVER_REACHABLE`, `HUB_SERVER_FAILING`, `HUB_SERVER_UNREACHABLE` | `reachable`, `failing`, `unreachable`   |
+| `HUB_ERROR_NETWORK`, `HUB_ERROR_TIMEOUT` | `network`, `timeout`                    |
 | `ATTR_URL_LINK`           | `lb-url-link`                           |
 | `ATTR_URL_PARM`           | `lb-url-parm`                           |
 | `ATTR_URL_PUSH`           | `lb-url-push`                           |

package/docs/reference/overview.md

@@ -19,6 +19,7 @@ serves, and the custom elements those pages are made of.
 | [`imports.ts`](./builder.md#widgets-from-packages)       | The packages this app takes widgets from  |
 | [`loadbare-app-build`](./builder.md#running-the-builder) | Configuring the build command             |
 | [CSS](./css.md)                                          | How the builder packages css              |
+| [The dev server](./dev-server.md)                        | Refresh after any change, never restart   |
 
 ## Application Pages
 

package/docs/reference/server.md

@@ -35,7 +35,7 @@ app.get(/.*/, (_req, res) =>
   res.type("html").send(readFileSync(path.join(DIST, "app.html"), "utf-8")),
 );
 
-app.listen(8787);
+app.listen(Number(process.env.PORT ?? 8787));
 ```
 
 ## What the server serves
@@ -96,16 +96,21 @@ The limit covers every page's requests.
 ## Running the server
 
 Run the server under a TypeScript-capable runner. The builder writes
-`dist/pages.ts`, which exports `hub`, as TypeScript:
+`dist/pages.ts`, which exports `hub`, as TypeScript. During development,
+[the dev server](./dev-server.md) runs it, and restarts it when a server
+module changes:
 
 ```json
 {
   "scripts": {
-    "dev": "loadbare-app-build --watch & tsx server.ts"
+    "dev": "node dev.ts"
   }
 }
 ```
 
+The server reads its port from `PORT`, which is how the dev server tells it
+where to listen.
+
 Node 22.18 and later also runs it with no runner at all, since Node strips
 TypeScript types itself. `dist/pages.ts` imports each `.requests.ts` and
 `.queries.ts` file by its full name, extension included, because Node looks

package/docs/reference/widgets.md

@@ -1,8 +1,7 @@
 # The Basic Widget Library
 
-Thirteen widgets: `lb-input`, `lb-select`, `lb-options`, `lb-picker`,
-`lb-table`, `lb-unknown-page`, `lb-confirm`, `lb-form`, `lb-insert-dialog`,
-`lb-master`, `lb-checkbox`, `lb-number` and `lb-date`. Every one of them is an ordinary custom element, written
+`@loadbare/widgets` is the basic widget set: controls, a table, dialogs, and
+elements that format a value. Every one of them is an ordinary custom element, written
 against the contracts in [Custom Elements](./custom-elements.md#html) for its
 definition and [Custom Elements](./custom-elements.md#code) for its class.
 
@@ -30,282 +29,16 @@ see [Being a control](./custom-elements.md#being-a-control). Each passes a
 refusal's message for its column to the native control inside it; see
 [Refusals](./data-binding.md#refusals).
 
-## `lb-input`
+## Each widget
 
-Wraps an `<input>`. The hub sets its `value` from the column `lb-column`
-names, and `lb-request` names what the widget sends on `change`:
+Each widget's parameters, the attributes it reads, and what a change sends
+are documented once, in the package that ships it: one page per widget,
+which the loadbare-widgets skill carries. Install that skill beside this one:
 
-```html
-<lb-input lb-column="name" lb-request="lb-row-update" exp-label="Name"></lb-input>
 ```
-
-Inside a form, leave `lb-request` off. The form gathers the widget on submit
-like any other control, so a widget that also sent its own request would
-write the same edit twice.
-
-| Parameter      | Fills                            |
-|----------------|----------------------------------|
-| `exp-label`    | The visible `<label>` text       |
-| `exp-type`     | The input's `type`, `text` when absent |
-| `exp-readonly` | The input's `readonly` attribute |
-
-## `lb-select`
-
-Wraps a `<select>` whose `<option>`s the page writes inside the tag:
-
-```html
-<lb-select lb-column="team" lb-request="lb-row-update" exp-label="Team">
-  <option value="">No team</option>
-  <option value="Engines">Engines</option>
-</lb-select>
-```
-
-| Parameter   | Fills                      |
-|-------------|----------------------------|
-| `exp-label` | The visible `<label>` text |
-
-## `lb-options`
-
-A `<select>` whose `<option>`s are the rows of the query it names. The page
-writes the row template inside the widget:
-
-```html
-<lb-options lb-query="statuses" lb-column="status" lb-request="lb-row-update" exp-label="Status">
-  <template><option lb-column="label"></option></template>
-</lb-options>
-```
-
-| Parameter   | Fills                      |
-|-------------|----------------------------|
-| `exp-label` | The visible `<label>` text |
-| `exp-size`  | The `<select>`'s `size`, an open list rather than a drop-down |
-
-- Each option's `value` is its row's key, the `lb-key-value` the hub stamps
-  on the live row, so the widget holds a key and shows a label.
-- A group template holding an `<optgroup>` puts the options in groups, one
-  per run of the query's order's leading term. The widget labels each
-  `<optgroup>` from the `lb-group-value` the hub stamps on it:
-
-  ```html
-  <template lb-group>
-    <optgroup><template><option lb-column="label"></option></template></optgroup>
-  </template>
-  ```
-- A heading option marked `data-group-label` in the `<optgroup>`, `hidden`
-  and `disabled`, labels the group with its text instead, so the label can
-  be a column of the group's first row.
-- Its `value` selects the option with that key, including an option that
-  arrives after the value did.
-
-`lb-picker` is the same class with the row template supplied by its
-definition.
-
-## `lb-picker`
-
-`lb-options`, with the row template built in, for a list where every row is
-one option showing one column:
-
-```html
-<lb-picker
-  lb-query="statuses"
-  lb-column="status"
-  lb-request="lb-row-update"
-  exp-label="Status"
-  exp-column="label"
-></lb-picker>
+npx loadbare-widgets skills install
 ```
 
-| Parameter    | Fills                                   |
-|--------------|-----------------------------------------|
-| `exp-label`  | The visible `<label>` text              |
-| `exp-column` | The column each option shows            |
-
-An option built from two columns, a row with a second element, or options
-in groups, is `lb-options` with the page's own templates.
-
-## `lb-table`
-
-A `<table>` that supplies its own scaffolding. The page supplies the heading
-row, the row template, and optionally a footer, each as a `<template>`:
-
-```html
-<lb-table lb-query="ledger" exp-caption="Ledger">
-  <template lb-exp-template="head">
-    <tr><th>Date</th><th>Amount</th></tr>
-  </template>
-  <template lb-group>
-    <tr><th colspan="2" lb-column="month"></th></tr>
-    <template>
-      <tr><td lb-column="date"></td><td lb-column="amount"></td></tr>
-    </template>
-  </template>
-  <template lb-exp-template="foot">
-    <tr><td>Total</td><td lb-sum="amount"></td></tr>
-  </template>
-</lb-table>
-```
-
-| Parameter     | Fills                |
-|---------------|----------------------|
-| `exp-caption` | The `<caption>` text |
-
-| Template                          | Fills                                   |
-|-----------------------------------|-----------------------------------------|
-| `<template lb-exp-template="head">` | The `<thead>`                         |
-| `<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, 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
-  `lb-query`; see [Order](./data-binding.md#order) and
-  [Filters](./data-binding.md#filters).
-- The footer is not a row of `ledger`. An aggregate there covers every row
-  showing;
-  a figure that is not a sum of the rows, such as a budget, is a `<tr>`
-  naming a `row` query of its own.
-- A `<template lb-exp-template="ghost">` is a blank row for entering a new
-  one, in a `<tbody>` of its own. The widget joins its controls to a form
-  outside the table, since a `<form>` cannot wrap a `<tr>`, and puts the
-  cursor back in it once an insert from it succeeds.
-- After rows land, the widget scrolls the row the page's own request created
-  or moved into view.
-- 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`
-
-A button that asks before it sends. The page writes the question inside the
-tag, and the request goes on the dialog's confirm button, so nothing reaches
-the hub until the user says yes:
-
-```html
-<lb-confirm exp-label="Delete" exp-request="lb-row-delete">
-  Delete <b lb-column="name"></b>?
-</lb-confirm>
-```
-
-| Parameter     | Fills                                            |
-|---------------|--------------------------------------------------|
-| `exp-label`   | The text of the button that opens the dialog     |
-| `exp-request` | The confirm button's `lb-request`                |
-| `exp-confirm` | The confirm button's text, `Confirm` when absent |
-
-The widget closes the dialog once the request succeeds, and leaves it open
-on a refusal.
-
-## `lb-form`
-
-A `<form>` over one row's controls. A row with a key saves each control's
-column on `change`; a row whose key is empty is new, and the hub sends no
-update for it, so its controls wait for a submit. A definition only.
-
-| Parameter | Fills           |
-|-----------|-----------------|
-| `exp-id`  | The form's `id` |
-
-## `lb-insert-dialog`
-
-A row entered in a modal dialog, written once outside every row and opened
-with `commandfor` and `command="show-modal"`. Save is the form's
-`lb-row-insert`; on success the widget chooses the new row in the nearest
-`lb-options` around the button that opened it, and closes. The handler
-answers with a patch holding the new row.
-
-While open, the button that opened it carries `insert-dialog-opener` and the
-widget carries `anchored`, for a stylesheet to place the dialog beside the
-button with CSS anchor positioning.
-
-| Parameter   | Fills                                             |
-|-------------|---------------------------------------------------|
-| `exp-id`    | The dialog's `id`                                 |
-| `exp-title` | The dialog's heading                              |
-| `exp-query` | The form's `lb-query`, which it inserts into      |
-| `exp-save`  | The Save button's text, `Save` when absent        |
-
-## `lb-master`
-
-A set, one of its rows, and the buttons that act on the set: New, Copy,
-Delete, Save new and Cancel, each shown only for a row on record or a new
-one. A definition only, built from `lb-form` and `lb-confirm`. New sends
-`new` and Copy sends `copy`, requests the page declares; `new` returns
-`url()` emptying the parm that names the row.
-
-| Parameter     | Fills                                      |
-|---------------|--------------------------------------------|
-| `exp-row`     | The `lb-query` of the row the form shows   |
-| `exp-form-id` | The form's `id`, `master-form` when absent |
-
-## `lb-checkbox`
-
-A checkbox and its label as one element, for an application to style. A
-definition only: a native checkbox is already a control (see
-[Checkboxes](./data-binding.md#checkboxes)), so the widget is the markup, a
-`<label>` holding the `<input type="checkbox">` and a `<span>` with the
-text. The column and request go on the checkbox inside, so they arrive as
-expansion attributes.
-
-Unlike `lb-input`, it has no script making the tag the control. A value
-that lands before a widget's script has loaded arrives only as the string
-stamp `lb-column-value`, and a script checkbox would read `"false"` as
-checked. The hub sets a native checkbox's `checked` directly.
-
-| Parameter     | Fills                                         |
-|---------------|-----------------------------------------------|
-| `exp-column`  | The checkbox's `lb-column`                    |
-| `exp-label`   | The label's text                              |
-| `exp-request` | The checkbox's `lb-request`, none when absent |
-
-## `lb-number` and `lb-date`
-
-A number shown by the browser's `Intl.NumberFormat`, and a date or time
-shown by `Intl.DateTimeFormat`.  Neither is a control: `lb-column` goes on
-the tag, and the widget renders the `lb-column-value` the hub stamps; see
-[Receiving a value](./custom-elements.md#receiving-a-value).
-
-```html
-<lb-number lb-column="balance" exp-style="currency" exp-currency="USD"></lb-number>
-<lb-date lb-column="due" exp-date-style="medium"></lb-date>
-```
-
-Each parameter is one of Intl's options in kebab-case, as `exp-currency-sign`
-for `currencySign`, plus `exp-locale`.  A value that is no number or date
-shows as it arrived, and a date alone, `YYYY-MM-DD`, shows as that day in
-every time zone.  The stamp keeps the raw value, so a stylesheet selects on
-it:
-
-```css
-lb-number[lb-column-value^="-"] { color: var(--negative); }
-```
-
-## `lb-unknown-page`
-
-The chrome's dialog for a URL that names no page, as one tag:
-
-```html
-<lb-hub>
-  <nav>...</nav>
-  <main></main>
-  <lb-unknown-page></lb-unknown-page>
-</lb-hub>
-```
-
-It expands to a `<dialog lb-url-unknown lb-query="lb-url">` showing
-`lb-path`, and the hub opens it when no page's stub matches the path. See
-[An unknown page](./chrome.md#an-unknown-page) for the same dialog written
-by hand.
-
-| Parameter         | Fills                                    |
-|-------------------|------------------------------------------|
-| `exp-button-text` | The text of the button that closes it, `OK` by default |
+For a reader without the skill, the package's
+[README](https://gitlab.com/kendowns/loadbare/-/blob/main/packages/widgets/README.md)
+lists the widgets and links each page.

package/docs/testing.md

@@ -274,7 +274,8 @@ What the hub is tested for here:
   a pending element is ignored
 - a round trip the server never answers is aborted at the ten-second
   deadline, under mocked timers, and fails the way any round trip fails
-- a successful insert gathered from a form resets the form
+- a successful insert gathered from a form resets the form, unless the
+  answer landed the new row on it
 - a path with no page reports, lands `lb-page-unknown`, and opens the
   `lb-url-unknown` dialog; two pages for one stub report and take the first
 - `lb-url` lands with the path, the page's `lb-page-title` or stub as