@loadbare/app 0.13.0 → 0.14.0

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

@@ -121,6 +121,7 @@ no row fills.
 | Element                                              | Receives the value as                   |
 |------------------------------------------------------|-----------------------------------------|
 | `<input>`, `<select>`, `<textarea>`                  | Its `value`, and `lb-column-value`      |
+| `<input type="checkbox">`                            | Its `checked`, and `lb-column-value`    |
 | A form-associated custom element with `value`        | Its `value`, and `lb-column-value`      |
 | Any other custom element                             | `lb-column-value` only                  |
 | Any other element                                    | Its text content, and `lb-column-value` |
@@ -132,12 +133,26 @@ element that is not a control keeps the content the builder placed in it
 from its element file, and renders `lb-column-value` itself; see
 [Custom Elements](./custom-elements.md#receiving-a-value).
 
-A checkbox, a radio button and a file input receive nothing, and the hub
-reports it to the console.
+A radio button and a file input receive nothing, and the hub reports it to
+the console.
 
 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.
 
+### Checkboxes
+
+A checkbox is a control. It is checked when its column is anything but
+`false` or null, and it sends `"true"` or `"false"`:
+
+```html
+<input type="checkbox" lb-column="active" lb-request="lb-row-update" />
+```
+
+Checked follows the rule `lb-show` follows, so a query spells a flag as a
+boolean, and the string `"false"` is checked. Unchecked sends `"false"`
+rather than nothing, so a flag can be set back. The checkbox's `value`
+attribute means nothing to the hub.
+
 ### Rows
 
 Write a `<template>` inside the element carrying `lb-query`, holding one
@@ -414,7 +429,8 @@ Every request has one shape:
 ```
 
 The hub takes `query`, `key` and `values` from where the element sits, and
-sends each when it has one. The server runs the handler for the name and
+sends each when it has one. A request acting on several rows carries `keys`
+in place of `key`; see [Selecting rows](#selecting-rows). The server runs the handler for the name and
 answers with response items, which land like any others.
 
 ### Committing
@@ -461,7 +477,8 @@ carrying `lb-request`:
 4. Otherwise: every control whose form owner is the element's form owner.
 
 The hub gathers from controls only, and skips a control that belongs to a
-query nested inside the group. A form owner includes a control outside the
+query nested inside the group, except that a form gathers the rows of a
+query nested in its own; see [A form over a set of rows](#a-form-over-a-set-of-rows). A form owner includes a control outside the
 form that names it with the HTML `form` attribute, which is how a table row,
 where a form cannot go, sends one:
 
@@ -492,6 +509,99 @@ ancestor `lb-query` and row of the element carrying `lb-request` instead.
 Controls gathered from two different queries are an error, and the hub
 sends nothing.
 
+### A form over a set of rows
+
+A form gathers the live rows of a query nested in its own query as well as
+its own controls: a master and its details, entered together. Each nested
+row goes as its key and the values of its own controls, under the nested
+query's name, in `rows`:
+
+```html
+<form lb-query="paychecks" lb-request="lb-row-insert">
+  <input lb-column="pay_date" type="date" />
+  <table>
+    <tbody lb-query="deduction_types">
+      <template>
+        <tr>
+          <td lb-column="label"></td>
+          <td><input lb-column="amount" /></td>
+        </tr>
+      </template>
+    </tbody>
+  </table>
+  <button type="submit">Save</button>
+</form>
+```
+
+```json
+{
+  "name": "lb-row-insert",
+  "query": "paychecks",
+  "values": { "pay_date": "2026-10-02" },
+  "rows": {
+    "deduction_types": [
+      { "key": "401k", "values": { "amount": "50" } },
+      { "key": "dental", "values": { "amount": "" } }
+    ]
+  }
+}
+```
+
+The list of deduction types lives only in the database: the nested query
+answers it, and the form shows one input per row.
+
+- Every live row of the nested query goes, whatever its values. What an
+  empty value means, such as no deduction of that type, is the handler's.
+- One level only. A query nested inside a nested row shows the same rows in
+  every row around it, so it is not gathered.
+- An insert, an update and a declared request carry `rows`. A delete does
+  not.
+- A form whose only controls are in nested rows still sends, for its own
+  query, with empty `values`.
+- A live row gathers nothing nested, as before.
+
+The handler for the form's query receives `rows` beside `values`, and writes
+the master and its details together; see [crud](./page-files.md#crud).
+
+A nested query answers once for the page, so its rows are the same wherever
+they show. The form enters a new master with its details, or edits the
+master the page shows, whose details the nested query reads from the same
+query parm. A form [pointed at a row](#editing-a-row-in-one-form) fills its
+own controls from that row; its nested rows stay the nested query's answer.
+
+### A row not yet entered
+
+A row whose key is empty is a new one, not yet entered. It arises two ways:
+a `row` query answers with an empty key, as one showing the master a query
+parm names does when the parm is empty, or New points a form (see
+[Editing a row in one form](#editing-a-row-in-one-form)). Either way the
+element carries `lb-key-value=""`.
+
+| Request          | From a row not yet entered            |
+|------------------|---------------------------------------|
+| `lb-row-insert`  | Sent, with no `key`                   |
+| A declared one   | Sent, with no `key`                   |
+| `lb-row-update`  | Not sent: there is nothing to update  |
+| `lb-row-delete`  | Not sent: there is nothing to delete  |
+
+An update or delete not sent is the row's state, not a mistake, and nothing
+is reported. So a control that saves its own column with
+`lb-request="lb-row-update"` saves on a row on record, and on a new row only
+holds what a submit will gather:
+
+```html
+<section lb-query="account">
+  <form id="account-form">
+    <input lb-column="name" lb-request="lb-row-update" />
+  </form>
+  <button type="submit" form="account-form" lb-request="lb-row-insert">Save new</button>
+</section>
+```
+
+The same holds for a request a custom element sends carrying `key: ""`.
+An update or delete with no row around it at all has no key either, and
+that is reported to the console.
+
 ### Inserting, updating and deleting rows
 
 Loadbare provides three requests. Each runs the handler the page declares
@@ -528,6 +638,152 @@ 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.
 
+### Editing a row in one form
+
+A table, or any other set of rows, that the user edits or adds to has one
+form on the page, naming the same query. It sits anywhere, outside every
+row. Buttons point it with HTML's `commandfor` and `command`:
+
+| Command        | On a button                         | The hub                                     |
+|----------------|-------------------------------------|---------------------------------------------|
+| `--lb-edit`    | In a live row of the form's query   | Fills the form from that row, keyed by it   |
+| `--lb-new`     | Anywhere                            | Starts the form empty, for an insert        |
+| `--lb-release` | Anywhere                            | Lets the form go without saving             |
+
+HTML requires a custom command to begin with `--`.
+
+```html
+<tbody lb-query="paychecks">
+  <template>
+    <tr>
+      <td lb-column="pay_date"></td>
+      <td lb-column="gross"></td>
+      <td><button type="button" commandfor="paycheck" command="--lb-edit">Edit</button></td>
+    </tr>
+  </template>
+</tbody>
+<button type="button" commandfor="paycheck" command="--lb-new">New</button>
+
+<dialog>
+  <form id="paycheck" lb-query="paychecks" lb-request="lb-row-update">
+    <input lb-column="pay_date" type="date" />
+    <input lb-column="gross" />
+    <button type="submit">Save</button>
+    <button type="submit" lb-request="lb-row-insert">Save new</button>
+    <button type="button" commandfor="paycheck" command="--lb-release">Cancel</button>
+  </form>
+</dialog>
+```
+
+Edit fills the form from the row as the hub already holds it, with no
+round trip, including columns no element in the table shows. The user
+edits a row they can see, so the row is on the page. A row that has to be
+fetched to be edited is another page, with that row as its master.
+
+The hub stamps the form with the row's key, so the form's request carries
+it, and stamps the row `lb-row-editing`. New stamps an empty key, making the
+form [a row not yet entered](#a-row-not-yet-entered), and resets every
+control to its default. The form's state is in its `lb-key-value`
+stamp:
+
+| `lb-key-value` | The form is                 |
+|----------------|-----------------------------|
+| A key          | Editing that row            |
+| Empty          | Entering a new row          |
+| Absent         | Not in use                  |
+
+A stylesheet shows Save or Save new by it:
+
+```css
+form[lb-key-value=""] [type="submit"]:not([lb-request]),
+form:not([lb-key-value=""]) [lb-request="lb-row-insert"] {
+  display: none;
+}
+```
+
+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 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.
+
+Inside a `<dialog>`, Edit and New open the dialog modally, and letting go
+closes it. The dialog closing in any way HTML closes one lets the form go:
+Escape, `command="close"`, or `method="dialog"`. A form in no dialog opens
+nothing. It is always showing, as a detail panel beside the table is, or a
+stylesheet shows it while it has a key:
+
+```css
+form:not([lb-key-value]) {
+  display: none;
+}
+```
+
+The form names a `rows` query and holds no row template, so the query
+landing again lands nothing on it, and what the user has typed stays.
+
+A button inside a form that carries a command is `type="button"`, or it
+submits the form instead.
+
+### Selecting rows
+
+A checkbox carrying `lb-select` in a row template selects the live row it
+sits in. It is not a column: it carries no `lb-column`, lands nothing and
+is not gathered. The hub stamps the row `lb-row-selected` while it is
+ticked.
+
+A request for the query that names no one row then acts on the rows
+selected, and carries their keys as `keys`:
+
+```html
+<tbody lb-query="transactions">
+  <template>
+    <tr>
+      <td><input type="checkbox" lb-select lb-show="selecting" /></td>
+      <td lb-column="description"></td>
+      <td lb-column="amount"></td>
+    </tr>
+  </template>
+</tbody>
+
+<form lb-query="transactions" lb-request="lb-row-update">
+  <lb-picker lb-query="accounts" lb-column="acct" exp-label="Account" exp-column="name"></lb-picker>
+  <button type="submit">Apply</button>
+  <button type="button" lb-request="lb-row-delete">Delete</button>
+</form>
+```
+
+```json
+{ "name": "lb-row-update", "query": "transactions", "keys": ["4", "9"], "values": { "acct": "12" } }
+```
+
+| Request          | With rows selected                     | With none ticked     |
+|------------------|----------------------------------------|----------------------|
+| `lb-row-update`  | Sent with `keys`                       | Not sent             |
+| `lb-row-delete`  | Sent with `keys`                       | Not sent             |
+| A declared one   | Sent with `keys`                       | Sent with `keys: []` |
+| `lb-row-insert`  | Sent as ever; the selection is not its | Sent as ever         |
+
+An update or delete with nothing ticked has nothing to act on, and nothing
+is reported. A request from inside a row still names that row alone. The
+server runs the page's `rowUpdate` or `rowDelete` once for each key, as for
+each row alone, and refreshes once; see [crud](./page-files.md#crud).
+
+After the request succeeds, the hub clears the selection. A failed one
+leaves it, to try again.
+
+Only a checkbox that is showing counts. Turning a selector off with
+`lb-show` also clears its tick, so leaving a selecting mode abandons the
+selection rather than keeping it out of sight. With every selector off, a
+request for the query is an ordinary one again.
+
+Which rows are selected, and whether the page is in a selecting mode, is
+interaction state. A mode the URL keeps, such as `?selecting=1`, reaches
+the rows as a column the query computes from the parm, which `lb-show`
+reads.
+
 ### Declared requests
 
 A request name the page declares under `handlers` runs the application's
@@ -557,6 +813,7 @@ The hub stamps the element that committed:
 |----------------------|-----------------------------------------------|
 | `lb-request-pending` | The round trip is in flight                   |
 | `lb-request-error`   | The round trip failed, until the next request |
+| `lb-request-refused` | The handler refused it; see [Refusals](#refusals) |
 
 `lb-request-error` covers a non-2xx response, a network failure and a
 timeout alike. The hub aborts a round trip after ten seconds, and sets
@@ -574,6 +831,44 @@ pending button is already disabled and a stylesheet only shows it:
 }
 ```
 
+### Refusals
+
+A handler that refuses a request says why, in words for the user; see
+[Refusing a request](./page-files.md#refusing-a-request). The hub shows
+them where they belong:
+
+- A message for the request as a whole is the value of the
+  `lb-request-refused` stamp on the element that committed, empty when the
+  refusal has none.
+- A message for a column goes on the control the request gathered it from,
+  as HTML's own validity: `setCustomValidity`, the `:invalid` pseudo-class,
+  and the browser's own bubble for the first, which takes focus.
+
+A stylesheet shows the whole-request message with no script:
+
+```css
+form[lb-request-refused]:not([lb-request-refused=""])::after {
+  content: attr(lb-request-refused);
+  color: firebrick;
+}
+input:invalid {
+  outline: 2px solid firebrick;
+}
+```
+
+A refusal is not a failure: `lb-request-error` is not stamped, and nothing
+is reported to the console.
+
+A refusal stands until the user edits any control the request gathered,
+resets its form, or sends from the same element again. Then every message
+it put up goes at once, since the next submit is a new question for the
+handler. While a control carries a message the browser holds its form's
+submit, as for any invalid control, so the user edits before trying again.
+
+A form-associated custom element takes a column's message when it has
+`setCustomValidity` and `reportValidity`; see
+[Being a control](./custom-elements.md#being-a-control).
+
 ### The request event
 
 The hub dispatches every request as a bubbling `lb-request` event from the
@@ -620,3 +915,7 @@ expansion, and refuses to build:
 - `lb-show` on a `<template>`, or on a row template's root
 - `lb-show` with no `lb-query` around it
 - `lb-show="!"` or `lb-show="!!column"`, which reverse no column
+- `lb-select` on anything but `<input type="checkbox">`, outside a row
+  template, or beside `lb-column` or `lb-request`
+- a `command` beginning `--lb-` that is not one of the three commands
+- one of the three commands with no `commandfor`

package/skills/loadbare-app/references/page-files.md

@@ -137,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
 
@@ -191,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";
@@ -333,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/skills/loadbare-app/references/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
 

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

@@ -1,8 +1,8 @@
 # The Basic Widget Library
 
-Ten widgets: `lb-input`, `lb-select`, `lb-options`, `lb-picker`, `lb-table`,
-`lb-unknown-page`, `lb-confirm`, `lb-form`, `lb-insert-dialog` and
-`lb-master`. 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.
 
@@ -26,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`
 
@@ -186,8 +188,8 @@ 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 widget stops an
-`lb-row-update` that carries no key, so its controls wait for a submit.
+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           |
 |-----------|-----------------|
@@ -210,16 +212,37 @@ answers with a patch holding the new row.
 
 ## `lb-master`
 
-A set, one of its rows, and the buttons that act on the set: 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`. Copy sends `copy`, a
-request the page declares.
+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`
 
 The chrome's dialog for a URL that names no page, as one tag: