@loadbare/app 0.13.0 → 0.14.0

package/docs/reference/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/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
 

package/docs/reference/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:

package/docs/roadmap.md

@@ -102,6 +102,14 @@ 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
@@ -109,8 +117,7 @@ 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 argument whose shape is a 1.0 blocker in
-[TECHREF-1.0](./TECHREF-1.0.md#the-server-api).
+It takes its place in the [options on `createHub`](#options-on-createhub).
 
 ### Data binding utilities
 

package/package.json

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

package/skills/loadbare-app/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: loadbare-app
-description: Build server-bound web applications with Loadbare/app. Covers the file conventions the builder finds by name (`chrome.html`, `*.page.html`, `*.queries.ts`, `*.requests.ts`, `imports.ts`, `<tag>.html`, `<tag>.browser.ts`); the `lb-*` attribute vocabulary that lands query rows on HTML and issues requests (`lb-query`, `lb-column`, `lb-show`, `lb-request`); queries declared with `row(key, run)` and `rows(key, run)`; the URL as the hub's own query `lb-url`, with `lb-url-link`, `lb-url-push` and `lb-url-unknown`; build-time expansion with `exp-*` parameters, `lb-exp-slot` and `lb-exp-template`; custom elements as form-associated controls and row hosts; the Express wiring with `hubRoutes`; and the `@loadbare/widgets` library. Use whenever a task involves `@loadbare/app`, `@loadbare/widgets`, `loadbare-app-build`, an `lb-` attribute, or a page, query, request or custom element file in a Loadbare application. The model is not React, htmx or REST, and cannot be inferred from them.
+description: Build server-bound web applications with Loadbare/app. Covers the file conventions the builder finds by name (`chrome.html`, `*.page.html`, `*.queries.ts`, `*.requests.ts`, `imports.ts`, `<tag>.html`, `<tag>.browser.ts`); the `lb-*` attribute vocabulary that lands query rows on HTML and issues requests (`lb-query`, `lb-column`, `lb-show`, `lb-request`); queries declared with `row(key, run)` and `rows(key, run)`; the URL as the hub's own query `lb-url`, with `lb-url-link`, `lb-url-push` and `lb-url-unknown`; one form pointed at a row by the `--lb-edit`, `--lb-new` and `--lb-release` commands; build-time expansion with `exp-*` parameters, `lb-exp-slot` and `lb-exp-template`; custom elements as form-associated controls and row hosts; the Express wiring with `hubRoutes`; and the `@loadbare/widgets` library. Use whenever a task involves `@loadbare/app`, `@loadbare/widgets`, `loadbare-app-build`, an `lb-` attribute, or a page, query, request or custom element file in a Loadbare application. The model is not React, htmx or REST, and cannot be inferred from them.
 license: Apache-2.0
 metadata:
   package: "@loadbare/app"
@@ -178,7 +178,11 @@ from it.
 query under two names.  Many masters with their details is one `rows` query
 of joined rows, ordered by the master first and shown in groups.  A
 query nested inside another query's row template receives the same rows in
-every outer row; use it for a picker, never for per-row detail.  A new outer
+every outer row; use it for a picker, never for per-row detail.  Inside a
+form, the live rows of a query nested in the form's own are gathered as
+`rows: { <query>: [{ key, values }] }` beside `values`, so a master and a
+subtable of its details (one input per type, say) are entered in one
+submit, and the master's handler writes both.  A new outer
 row is filled from the nested query's last answer, whatever order they land
 in.
 
@@ -206,7 +210,8 @@ leaving row or group `lb-row-leaving` or `lb-group-leaving`, removing it once
 its animations end.  Scrolling to a row is script, in `lbRowsLanded`.
 
 **Every request has one shape.**  `lb-request` names the request, and the
-hub sends `{ name, query, key, values }` as present: `query` from the
+hub sends `{ name, query, key, values }` as present, with `keys` in place
+of `key` for the rows the user selected: `query` from the
 nearest ancestor `lb-query`, `key` from the nearest ancestor row of that
 query, and `values` gathered from controls by their `lb-column`.
 
@@ -224,9 +229,10 @@ with `lb-column` gathers its own value alone.  A `<form>` gathers every
 control whose form owner it is.  An element in a live row gathers that live
 row.  Anything else gathers its form owner's controls.  A `<form>` cannot
 wrap a `<tr>`, so an insert row in a table puts its controls in a form
-elsewhere with the HTML `form` attribute.  Checkboxes, radio buttons and
-file inputs are not controls here: they receive no value and are not
-gathered.
+elsewhere with the HTML `form` attribute.  A checkbox is a control: checked
+unless its column is `false` or null, and gathered as `"true"` or `"false"`.
+Radio buttons and file inputs are not controls here: they receive no value
+and are not gathered.
 
 **A form that adds to a set chosen elsewhere is written once, outside every
 row.**  A form cannot sit inside another form or in a table row, so a dialog
@@ -234,6 +240,17 @@ that creates an account while a posting's picker is choosing one goes at the
 end of the page, and each row opens it with `commandfor`.  The dialog learns
 the new key from `lb-request-done`.
 
+**A set the user edits has one form, pointed at a row.**  Never put a form
+in every row.  Write one form naming the set's query, outside every row,
+often in a `<dialog>`, and give it an `id`.  A `type="button"` with
+`commandfor="<id>"` and `command="--lb-edit"` in a live row fills it from
+that row with no round trip; `--lb-new` starts it empty for an insert;
+`--lb-release` lets it go.  The form's `lb-key-value` is the row's key, empty
+for a new row, absent when not in use, and a stylesheet shows Save or Save
+new by it.  A successful request from the form, or its dialog closing, lets
+it go.  Which row is being edited is never a query parm.  A row that must be
+fetched to be edited is another page, with that row as its master.
+
 **Three requests are Loadbare's.**  `lb-row-insert` needs `query` and
 `values`, `lb-row-update` needs `query`, `key` and `values`, and
 `lb-row-delete` needs `query` and `key`.  The page permits each under
@@ -242,6 +259,32 @@ Each works on a `row` query as well as a `rows` query, since the element a
 `row` lands on carries its key.  Every other request name is a declared
 request, under `handlers`.  Anything undeclared is refused.
 
+**An empty key is a row not yet entered.**  A `row` query answering with an
+empty key, or a form `--lb-new` pointed, carries `lb-key-value=""`.  The hub
+sends inserts and declared requests from it with no `key`, and sends no
+update or delete at all, silently.  So a control with
+`lb-request="lb-row-update"` saves on a row on record and only holds its
+value on a new one.  Never write script to stop such an update.
+
+**Select rows with `lb-select`, never with a column.**  An
+`<input type="checkbox" lb-select>` in a row template selects its row; the
+hub stamps `lb-row-selected`.  A request for that query naming no one row,
+such as a form outside the rows, carries the ticked rows as `keys`.
+`rowUpdate` and `rowDelete` then run once per key with no new code; a
+declared request gets `keys` itself.  With none ticked an update or delete
+is not sent.  Success clears the selection, and so does `lb-show` hiding a
+selector.  A selecting mode kept in the URL reaches the rows as a column the
+query computes from the parm.
+
+**Refuse with `refusal()`, never with a plain throw.**  `throw
+refusal("message")`, `throw refusal({ column: "message" })` or both, from
+`@loadbare/app/server`.  The whole-request message lands as the
+`lb-request-refused` stamp on the element that committed, shown by CSS
+`attr()`; each column's message goes on its control by
+`setCustomValidity`, and the first is reported.  Editing anything the
+request gathered withdraws it all.  Any other throw is a failure with no
+message, so a database error never reaches the page.
+
 **Write `rowUpdate` as a partial update.**  A form sends every control it
 owns; a single control sends its one column.  Set the columns `values`
 names, leave the rest alone, and check the names against the columns the
@@ -395,7 +438,7 @@ own, or to act on rows once they land through the hook the hub calls,
 
 Before writing one, check `@loadbare/widgets`: `lb-input`, `lb-select`,
 `lb-options`, `lb-picker`, `lb-table`, `lb-unknown-page`, `lb-confirm`,
-`lb-form`, `lb-insert-dialog`, `lb-master`.  The first four are
+`lb-form`, `lb-insert-dialog`, `lb-master`, `lb-checkbox`.  The first four are
 form-associated controls that carry `lb-column` and `lb-request`
 themselves.  Install the package and list it in `src/imports.ts`: