@loadbare/app 0.12.0 → 0.14.0

package/docs/reference/page-files.md

@@ -48,7 +48,8 @@ page touches that page's files.
 ## HTML
 
 Write the page as a fragment. The fragment lands in `<main>`, which
-[chrome.html](./chrome.md) supplies.
+[chrome.html](./chrome.md) supplies.  A page carries no `<main>` and no
+`<lb-hub>` of its own; the builder rejects one that does.
 
 ```html
 <!-- src/pages/about.page.html -->
@@ -89,14 +90,18 @@ export const queries: Queries = {
     page: "directory",
     count: String(await ctx.db.visitCount()),
   })),
-  directory: rows("id", (ctx) => ctx.db.directory()),
+  directory: rows("id", (ctx) => ctx.db.directory(), { order: "name" }),
 };
 ```
 
-| Declared with     | Answers with                              |
-|-------------------|-------------------------------------------|
-| `row(key, run)`   | One row, an object                        |
-| `rows(key, run)`  | All its rows, an array of objects, in order |
+| Declared with              | Answers with                              |
+|----------------------------|-------------------------------------------|
+| `row(key, run)`            | One row, an object                        |
+| `rows(key, run, options)`  | All its rows, an array of objects         |
+
+`options` are a `rows` query's order: `order`, the columns the hub places
+its rows by, and `serverSortedByUrl`, set when the query reads the user's
+order parm itself. See [Order](./data-binding.md#order).
 
 `key` names the column that identifies a row. Give every row that column,
 including a `row` query's: an aggregate row answers with a constant key. The
@@ -109,8 +114,8 @@ page that needs the same data as one row and as a set declares two queries.
 The hub hands each value to the browser untouched, so what a number, a date
 or a null looks like is decided here, in the query.
 
-Return the full answer every time, and the rows in the order the page shows
-them. Sending only what changed is a request's job — see
+Return the full answer every time. With no `order`, the rows show in the
+order they are returned. Sending only what changed is a request's job — see
 [refresh and patch](#refresh-and-patch).
 
 ## Requests
@@ -120,7 +125,7 @@ optional:
 
 | Key           | Runs                                                   |
 |---------------|--------------------------------------------------------|
-| `onPageEnter` | Before the page's queries, when the page loads         |
+| `onPageEnter` | Before the page's queries, when the page loads; may move the URL |
 | `handlers`    | The page's declared requests, by request name          |
 | `crud`        | The requests Loadbare provides, by query name          |
 
@@ -132,10 +137,14 @@ name:
 | `name`   | The request name, from `lb-request`                      |
 | `query`  | The query the request is for                             |
 | `key`    | The key of the row the request is for                    |
+| `keys`   | The keys of the rows selected, in place of `key`         |
+| `rows`   | A form's nested rows, by query: each `key` and `values`  |
 | `values` | The gathered control values, by column                   |
 
 The hub sends `query`, `key` and `values` when it finds them; see
-[Gathering](./data-binding.md#gathering).
+[Gathering](./data-binding.md#gathering). It sends `keys` for a request that
+acts on the rows the user selected; see
+[Selecting rows](./data-binding.md#selecting-rows).
 
 ### onPageEnter
 
@@ -150,6 +159,12 @@ export const requests: Requests = {
 
 Declare no refresh set here. The page's queries run afterward.
 
+It may return `url()` instead, to move the page to other query parms before
+anything shows, as restoring the filters and order the user last had does.
+The page loads there in the same round trip, and that load does not follow
+`onPageEnter` again. A `url()` leading to the parms already in hand is
+ignored. See [Moving the URL](#moving-the-url).
+
 ### handlers
 
 Declare a request under the name the HTML gives `lb-request`. Pair what it
@@ -180,10 +195,34 @@ the query they operate on:
 
 | Request name    | Runs        | `run` receives   |
 |-----------------|-------------|------------------|
-| `lb-row-insert` | `rowInsert` | `query`, `values` |
-| `lb-row-update` | `rowUpdate` | `query`, `key`, `values` |
+| `lb-row-insert` | `rowInsert` | `query`, `values`, and `rows` from a form |
+| `lb-row-update` | `rowUpdate` | `query`, `key`, `values`, and `rows` from a form |
 | `lb-row-delete` | `rowDelete` | `query`, `key`   |
 
+An `lb-row-update` or `lb-row-delete` carrying `keys` runs `rowUpdate` or
+`rowDelete` once for each key, with that key, so a handler written for one
+row serves several. The patches the runs return are laid together, and the
+refresh set runs once. A `url()` returned for one of several rows is
+reported and ignored. A declared request receives `keys` as it is.
+
+`rows` holds the rows of a query nested in the form the request came from,
+by query name, each with its `key` and the `values` of its own controls; see
+[A form over a set of rows](./data-binding.md#a-form-over-a-set-of-rows).
+The handler writes the master and its details together, deciding what each
+row's values mean, such as an empty amount being no row at all:
+
+```ts
+rowInsert: {
+  run: async (ctx, { values, rows }) => {
+    const id = await ctx.db.insertPaycheck(values);
+    for (const { key, values: row } of rows?.deduction_types ?? []) {
+      if (row.amount !== "") await ctx.db.insertDeduction(id, key, row.amount);
+    }
+  },
+  refresh: ["paychecks"],
+},
+```
+
 ```ts
 // src/pages/directory.requests.ts
 import { patch, type Requests } from "@loadbare/app/server";
@@ -240,16 +279,14 @@ queries:
 
 Return a patch for a change the request knows the extent of — one row added,
 one row dropped, one row edited — and leave `refresh` empty. A refreshed
-`rows` query sends every row, and the hub places every row again, which moves
-each element and takes focus from the control the user is in.
+`rows` query sends every row to say what one row could.
 
 A change that seems to need a refresh usually has a patch:
 
-- A placeholder row standing in for an empty set or section: drop its key in
-  the patch that adds the first real row, and add it back in the patch that
-  drops the last.
-- A row whose position changes: the rows host places it, as
-  [`lb-table`](./widgets.md#lb-table) does by `data-sort`.
+- A row whose position changes: the hub places it by the query's
+  [order](./data-binding.md#order).
+- A group that appears or goes: the hub makes a group with its first row
+  and removes it with its last, so no row stands in for an empty one.
 - A row whose other columns change with the edit: re-read the row and patch
   it.
 - Rows the database removes with a deleted one: select their keys before the
@@ -324,3 +361,48 @@ Post/Redirect/Get without the redirect. The refresh set does not run, and
 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).
+
+### Refusing a request
+
+A handler refuses a request by throwing `refusal()`, with words written for
+the user:
+
+```ts
+import { refusal, type Requests } from "@loadbare/app/server";
+
+export const requests: Requests = {
+  handlers: {
+    enterPaycheck: {
+      run: async (ctx, { values }) => {
+        if (Number(values!.amount) <= 0) {
+          throw refusal({ amount: "Must be more than zero" });
+        }
+        const overlap = await ctx.db.overlappingSeries(values!);
+        if (overlap) {
+          throw refusal(
+            `That series already has paychecks from ${overlap.from} through ${overlap.to}.`,
+          );
+        }
+        await ctx.db.enterPaycheck(values!);
+      },
+      refresh: ["paychecks"],
+    },
+  },
+};
+```
+
+| Call                             | The browser shows                          |
+|----------------------------------|--------------------------------------------|
+| `refusal("message")`             | The message, for the request as a whole    |
+| `refusal({ column: "message" })` | Each message on the control for its column |
+| `refusal("message", { ... })`    | Both                                       |
+
+Throw it, from the handler or from anything the handler calls, and whatever
+the application has open rolls back as for any throw. A column names a
+control the request gathered. See [Refusals](./data-binding.md#refusals)
+for how the browser shows them.
+
+A refusal is the only error whose words reach the browser. Anything else a
+handler throws is a failure, answered with nothing in it, so a stack or a
+database message never reaches a page.
+

package/docs/reference/server.md

@@ -72,6 +72,26 @@ path, so the application cannot be hosted under a subpath such as
 whole path space through unchanged.
 
 Leave `express.json()` to `hubRoutes`, which mounts it on its own routes.
+Pass its options through `hubRoutes` instead.
+
+## Options
+
+`hubRoutes` takes an optional third argument, an object with one key per
+concern:
+
+| Option | Description                                              |
+|--------|----------------------------------------------------------|
+| `json` | Options for `express.json()`, passed to it unchanged     |
+
+A request body over 100 KB, the `express.json()` default, is refused with a
+413 before any handler runs, and the server log names the option that raises
+it. Raise it for an application whose pages send a file's text as a value:
+
+```ts
+app.use(hubRoutes(hub, contextFor, { json: { limit: "5mb" } }));
+```
+
+The limit covers every page's requests.
 
 ## Running the server
 
@@ -91,6 +111,10 @@ TypeScript types itself. `dist/pages.ts` imports each `.requests.ts` and
 `.queries.ts` file by its full name, extension included, because Node looks
 for exactly the path an import names.
 
+The `hub` it exports comes from `createHub`, the only implementation of
+the `Hub` interface. That interface may gain members in any release, so an
+application never implements it.
+
 Enable `allowImportingTsExtensions` in the application's `tsconfig.json`
 when `tsc` type-checks the server. Without it, `tsc` rejects the `.ts`
 extensions in `dist/pages.ts`:

package/docs/reference/widgets.md

@@ -1,7 +1,8 @@
 # The Basic Widget Library
 
-Six widgets: `lb-input`, `lb-select`, `lb-options`, `lb-picker`, `lb-table`,
-`lb-unknown-page`. Every one of them is an ordinary custom element, written
+Eleven widgets: `lb-input`, `lb-select`, `lb-options`, `lb-picker`,
+`lb-table`, `lb-unknown-page`, `lb-confirm`, `lb-form`, `lb-insert-dialog`,
+`lb-master` and `lb-checkbox`. 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.
 
@@ -25,7 +26,9 @@ for where a listed package sits in the cascade.
 `lb-input`, `lb-select`, `lb-options` and `lb-picker` are controls:
 form-associated custom elements with a `value` property that fire `change`.
 Each carries `lb-column` and `lb-request` itself, the way an `<input>` does;
-see [Being a control](./custom-elements.md#being-a-control).
+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`
 
@@ -43,6 +46,7 @@ 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`
@@ -67,9 +71,7 @@ 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 data-group="category">
-    <option lb-column="label"></option>
-  </template>
+  <template><option lb-column="label"></option></template>
 </lb-options>
 ```
 
@@ -79,9 +81,15 @@ writes the row template inside the widget:
 
 - 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.
-- `data-group` on the row template sections the options into `<optgroup>`s,
-  one per distinct value of that column, added and removed as rows arrive
-  and leave.
+- 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>
+  ```
 - Its `value` selects the option with that key, including an option that
   arrives after the value did.
 
@@ -100,7 +108,6 @@ one option showing one column:
   lb-request="lb-row-update"
   exp-label="Status"
   exp-column="label"
-  exp-group="category"
 ></lb-picker>
 ```
 
@@ -108,10 +115,9 @@ one option showing one column:
 |--------------|-----------------------------------------|
 | `exp-label`  | The visible `<label>` text              |
 | `exp-column` | The column each option shows            |
-| `exp-group`  | The row template's `data-group`         |
 
-An option built from two columns, or a row with a second element, is
-`lb-options` with the page's own row template.
+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`
 
@@ -123,11 +129,14 @@ row, the row template, and optionally a footer, each as a `<template>`:
   <template lb-exp-template="head">
     <tr><th>Date</th><th>Amount</th></tr>
   </template>
-  <template data-sort="date" data-group="month">
-    <tr><td lb-column="date"></td><td lb-column="amount"></td></tr>
+  <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 lb-query="ledger-total"><td>Total</td><td lb-column="total"></td></tr>
+    <tr><td>Total</td><td lb-sum="amount"></td></tr>
   </template>
 </lb-table>
 ```
@@ -140,15 +149,99 @@ row, the row template, and optionally a footer, each as a `<template>`:
 |-----------------------------------|-----------------------------------------|
 | `<template lb-exp-template="head">` | The `<thead>`                         |
 | `<template lb-exp-template="foot">` | The `<tfoot>`                         |
-| Any other `<template>`            | The row template, in the `<tbody>`      |
-
-- `data-group` on the row template sections rows under a heading row, one
-  per distinct value of that column, spanning every column of the row.
-- `data-sort` orders rows within a section, or within the whole body with no
-  grouping, by the text of that column.
-- The footer is not a row of `ledger`. Its `<tr>` names a `row` query of its
-  own, which lands on the `<tr>` itself. A grand total is a second query over
-  the same data.
+| 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
+  rows land in the one `<tbody>`, so a group here is a heading row with its
+  rows after it.
+- The footer is not a row of `ledger`. An aggregate there covers every row;
+  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.
+
+## `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 `lb-request-done` says the request
+succeeded, 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.
+
+| 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-unknown-page`
 

package/docs/roadmap.md

@@ -29,12 +29,6 @@ expanding row). [Theory](./theory.md) already flags this as possibly load-bearin
 disallowed. Worth a decision-in-principle the first time a master-detail
 page is built, even before the mechanism is needed elsewhere.
 
-### Pending appearance
-
-A value that hasn't arrived yet is probably derivable from an absent
-`lb-column-value` rather than needing a signal of its own. Not yet needed because
-nothing currently produces that gap in practice — revisit if one does.
-
 ### Events while a request is in flight
 
 The hub ignores a commit on an element carrying `lb-request-pending`.
@@ -108,6 +102,23 @@ Most valuable against a large imported widget library, where an app uses a
 small fraction of what ships. Revisit when a real app's `app.css` is big
 enough to measure.
 
+### Options on `createHub`
+
+Global hooks, transaction wrapping, error handling and a CSRF token each
+want an option on `createHub`, `hubRoutes`, or both. `hubRoutes` already
+takes a trailing options object, one key per concern. `createHub` takes
+the same shape when its first option arrives, which adds a parameter and
+breaks nothing.
+
+### Queries stated by the chrome
+
+A custom element in the chrome naming a query forces every page to declare
+that query, since the page load covers one page's set.  `lb-url` shows the
+pattern from the framework side, and an application has no equivalent.
+
+A chrome-level query set on `createHub` would close this, and it is additive.
+It takes its place in the [options on `createHub`](#options-on-createhub).
+
 ### Data binding utilities
 
 A custom element that finds its own nearest ancestor `lb-query`,

package/docs/testing.md

@@ -86,6 +86,9 @@ anything ships:
   `lb-url-unknown` off a `<dialog>` or outside `<lb-hub>`
 - `lb-show` on a `<template>`, on a row template's root, or with no row
   around it
+- a chrome without exactly one `<lb-hub>` and one empty `<main>` inside it,
+  and a page carrying either
+- a widget script declaring an `lb` method Loadbare does not define
 
 A page file's `<title>` is lifted out and stamped as `lb-page-title`.
 
@@ -119,6 +122,13 @@ The rest of the build — `assemble`, `elements`, `pages`, `styles`,
 `package-css` — is tested the same way and in the same tier, since none of it
 needs a browser either.
 
+**The command.** `loadbare-app-build` itself runs in a child process against
+a temporary project, which carries a stand-in `@loadbare/app` pointing at
+the hub's source so the test needs no prior build.  It is tested for its
+default `src` and `dist`, every file it writes, `--minify`, a failed build's
+exit code, and `--watch` rebuilding on a change, skipping a file it does not
+watch, and surviving a failed build.
+
 ## Tier 2 — The engine
 
 `createHub` takes a plain object and returns an object. Nothing in
@@ -163,14 +173,14 @@ evidence here.
   the row around it, and the columns inside it are its own query's
 - a query nothing names is reported and skipped; several elements naming one
   query are all filled
-- all rows decide membership and order, so a key that did not arrive is gone
-- a patch disturbs only what it names, in contents and in position
+- all rows decide membership, so a key that did not arrive is gone
+- a patch disturbs only what it names, in contents, and a row moves only
+  when the order puts it somewhere else
 - `lb-query-row-count` is counted from the DOM after reconciliation, so all
   rows and a patch ending in the same state report the same number
-- `lbPlaceRow` is called for a fresh row always, and for an existing row
-  only under all rows. That is today's behavior, not a decision — a patch
-  therefore never re-places a row whose sort key changed. The test states
-  what is true now, and is the one that flips if that changes.
+- the order places all rows and a patch alike, 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`)
 - `lb-show` moves an element into a template and back, and landing reaches
   inside it
 
@@ -223,6 +233,8 @@ What the hub is tested for here:
   `lb-request-error` replaces it on failure, and the next request clears
   it; `aria-busy` comes and goes with `lb-request-pending`, and a commit on
   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 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
@@ -235,7 +247,7 @@ What the hub is tested for here:
 - an `lb-url` item in a server answer writes the URL and lands the page
   loaded there
 - `hidden` comes off the body once a page has landed, including the page
-  that failed to load
+  that failed to load, and a link whose page fails to load marks no element
 
 Widgets are small and their logic is local, so jsdom carries them: a value
 reaches the control the widget owns, the widget is a form-associated control
@@ -266,9 +278,8 @@ No browser test runner is installed and none of the following exists. They
 are recorded here as the shape of the work, not as coverage:
 
 1. a cold load fills `<main>` with no empty flash
-2. the ten-second deadline aborts a request that never answers
-3. the wizard never displays a step the server has not confirmed
-4. the view-source invariant
+2. the wizard never displays a step the server has not confirmed
+3. the view-source invariant
 
 The last is the one worth a browser. Loadbare's central claim is that no
 markup exists in the DOM that is not in view-source, and that the difference

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@loadbare/app",
   "description": "High performance web app framework for server-bound applications",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "type": "module",
   "files": [
     "dist",
@@ -22,8 +22,7 @@
     "./constants": "./dist/core/lb-constants.js",
     "./types": "./dist/core/lb-types.js",
     "./server": "./dist/server/lb-server.js",
-    "./express": "./dist/server/lb-express.js",
-    "./build": "./dist/build/elements.js"
+    "./express": "./dist/server/lb-express.js"
   },
   "scripts": {
     "prepublishOnly": "npm run typecheck && npm run test && npm run build",