@loadbare/app 0.12.0 → 0.14.0

package/docs/reference/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
@@ -153,9 +168,9 @@ places it immediately before the template:
 ```
 
 The hub matches each row to a live row by its key. All rows decide
-membership and order: a live row whose key did not arrive is removed. A
-patch changes only the rows it names, and every other live row keeps its
-content and its place.
+membership: a live row whose key did not arrive leaves. A patch changes only
+the rows it names, and every other live row keeps its content. The hub
+places every live row by the query's order; see [Order](#order).
 
 A key is unique within a query. Two rows with one key in the same answer,
 or two live rows showing one key, are reported on the console.
@@ -163,10 +178,101 @@ or two live rows showing one key, are reported on the console.
 A live row's root counts as a column when it carries `lb-column`, which is
 how an `<option>`, whose content is text, shows the column it is.
 
-A custom element that carries `lb-query` and a row template may decide where
-a row goes and add scaffolding around the rows; see
-[Holding rows](./custom-elements.md#holding-rows) and
-[The Basic Widget Library](./widgets.md).
+A custom element that carries `lb-query` and a row template reacts to the
+rows once they land; see [Holding rows](./custom-elements.md#holding-rows)
+and [The Basic Widget Library](./widgets.md).
+
+### Order
+
+A `rows` query declares its order with the query, as columns separated by
+commas, each descending when written after `-`:
+
+```ts
+roster: rows("id", (ctx) => ctx.db.members(), { order: "team,name" }),
+```
+
+The query parm `lb-order-<query>` replaces it for that query, so a control
+inside `lb-query="lb-url"` writing that parm re-sorts the rows the hub
+already has, with no round trip. With no order, rows show in the order they
+arrived, and a patch's new rows go last.
+
+Values compare by their JSON type: numbers numerically, strings as the
+user's language orders them, `false` before `true`, and `null` last. A
+number sent as a string sorts as a string. Rows that compare equal keep the
+order they arrived in. A row moves only when the order puts it somewhere
+else.
+
+A query that pages or limits its rows reads the parm itself and declares
+`serverSortedByUrl: true`, so a change of order loads the page again.
+
+### Groups
+
+A group is a run of rows sharing the order's leading term. Write a
+`<template lb-group>` where the row template goes, holding the group's
+heading and one nested `<template>`: the next group template, or the row
+template. The nth group template breaks on the order's nth term.
+
+```html
+<ul lb-query="roster">
+  <template lb-group>
+    <li>
+      <h3 lb-column="team"></h3>
+      <ul>
+        <template><li lb-column="name"></li></template>
+      </ul>
+    </li>
+  </template>
+</ul>
+```
+
+The group's contents land immediately before its nested template. When that
+template is inside the heading's element, the contents land inside it; when
+it is beside the heading, they land after it. `<tbody>` and `<optgroup>` do
+not nest, so a table's deeper levels are heading rows. Content after the
+nested template is the group's footer.
+
+A heading is filled from its group's first row, so it may show a column
+other than the one the group breaks on. The hub stamps each top-level
+element of a group with `lb-group-live`, `lb-group-column` and
+`lb-group-value`. A row creates its group, and a group leaves with its last
+row.
+
+### Aggregates
+
+`lb-count`, `lb-sum="col"`, `lb-avg="col"`, `lb-min="col"` and
+`lb-max="col"` set an element from the rows of the nearest group around it,
+or of the whole list outside any group:
+
+```html
+<tr><td><span lb-count></span> people</td><td lb-sum="salary"></td></tr>
+```
+
+A sum and an average are exact, read from JSON numbers and from strings
+holding a plain decimal. `null` and empty values are left out. The result
+lands unformatted, and covers the rows the browser holds.
+
+### What happened to a row
+
+Every change to a list is one a stylesheet can see:
+
+| Attribute          | Means                                                  |
+| ------------------ | ------------------------------------------------------ |
+| `lb-row-created`   | Created when the hub last touched the row              |
+| `lb-row-changed`   | Its values changed when the hub last touched it        |
+| `lb-row-moved`     | The order put it somewhere else when last touched      |
+| `lb-row-requested` | `created`, `changed` or `moved` by this page's request |
+| `lb-row-leaving`   | A row on its way out                                   |
+| `lb-group-leaving` | A group on its way out                                 |
+
+A row that leaves loses `lb-row-live`, takes `inert`, and is removed once
+its animations finish, at once when there are none. A moved row moves, and
+a copy stays behind where it was, leaving. `lb-row-requested` is cleared at
+every landing; the others when the hub next touches the row.
+
+```css
+[lb-row-created] { animation: arrive 200ms; }
+[lb-row-leaving] { animation: depart 200ms forwards; }
+```
 
 ### What arrives later
 
@@ -174,16 +280,14 @@ The hub keeps each query's last answer until the page changes, with any
 patch since applied to it. An element that names a query and arrives after
 that query's answer is filled from what was kept, at the end of the landing
 that follows its arrival. Such an element is a picker in a new live row, or
-scaffolding a custom element builds around its rows, such as a ghost row. So
+scaffolding around rows, such as a group's heading or a ghost row. So
 a query nested in another query's rows need not land again, or land after
 the outer query, for a new outer row to show its choices.
 
 A custom element the builder shipped absent has not upgraded while its
-`lb-show` column is off, so rows that land on it then are not placed by it.
-When the column first turns on and the element upgrades, the hub lands the
-kept answer on it again, and every row goes through its `lbPlaceRow`. So a
-table that groups its rows can sit under `lb-show`. See
-[Holding rows](./custom-elements.md#holding-rows).
+`lb-show` column is off. When the column first turns on and the element
+upgrades, the hub lands the kept answer on it again, so its `lbRowsLanded`
+runs. See [Holding rows](./custom-elements.md#holding-rows).
 
 Nothing is answered from what the hub kept: a request always goes to the
 server, and a query re-runs only when a response names it. A patch that
@@ -325,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
@@ -372,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:
 
@@ -403,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
@@ -439,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
@@ -468,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
@@ -485,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
@@ -531,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`