@loadbare/app 0.12.0 → 0.14.0

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