@loadbare/app 0.19.0 → 0.19.1

package/docs/reference/data-binding.md

@@ -89,7 +89,8 @@ elements as the page needs.
 
 What lands depends on the query's kind and on whether the element holds a
 row template, which is the first `<template>` among its descendants outside
-any nested `lb-query`:
+any nested `lb-query`, or, when that template is a [group
+template](#groups), the innermost template inside it:
 
 | Kind   | Row template | The hub                                |
 |--------|--------------|----------------------------------------|
@@ -128,6 +129,9 @@ row's `account`:
 `lb-column` on an element with `lb-query` is undefined unless the element is
 a control.
 
+A query that arrives with nowhere to land is reported to the console,
+unless its name begins with `lb-`.
+
 An element with `lb-column` and no ancestor row receives nothing. The hub
 still gathers from it, so an insert form writes `lb-column` on controls that
 no row fills.
@@ -150,7 +154,9 @@ 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 file input receives nothing, and the hub reports it to the console.
+A file input receives nothing, not even `lb-column-value`, and the hub
+reports it to the console and gathers nothing from it. A `<select>` with no
+option for the value shows no selection.
 
 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, or by a custom
@@ -221,7 +227,11 @@ what was typed, through a refresh and through a change of order. A row
 whose values changed is filled whole, and its controls show what arrived.
 
 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.
+or two live rows showing one key, are reported on the console. A row
+missing its key column is reported and not landed.
+
+A live row already in the markup when the first answer lands is one of the
+query's rows.
 
 When the focus is in a live row that placing moves, the hub puts it back on
 the same element and scrolls it into view. When that row leaves, or a
@@ -266,14 +276,23 @@ server's order places the rows:
 </ul>
 ```
 
-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, unless the query declares the
+| Values               | Compare                                      |
+|----------------------|----------------------------------------------|
+| Two numbers          | Numerically                                  |
+| Two strings          | As the user's language orders them           |
+| Two booleans         | `false` before `true`                        |
+| Two different types  | Booleans, then numbers, then strings         |
+| `null` or missing    | After everything ascending, first descending |
+
+A number sent as a string sorts as a string, unless the query declares the
 column's [type](./page-files.md#queries): a column declared `number` sorts
 numerically whatever JSON type its values arrive as, and a value that is no
-number sorts with the nulls. Rows that compare equal keep the order they
-arrived in. A row moves only when the order puts it somewhere
-else.
+value of its declared type compares as `null` does. `readAs` in
+`@loadbare/app/types` is the rule the hub applies.
+
+Rows that compare equal keep the order they arrived in, a patch's new rows
+after the rows already showing. A row moves only when the order
+puts it somewhere else, so all rows landing again unchanged move nothing.
 
 ### Filters
 
@@ -323,6 +342,9 @@ The column's type is the one its query declares, if it declares one, and
 its JSON type otherwise. A value that is not of the column's type, and a
 column that is null or missing, pass only `!=`.
 
+`parseFilter`, `passes` and `passesTerm` in `@loadbare/app/types` are the
+rule the hub applies.
+
 ### Groups
 
 A group is a run of rows sharing the order's leading term. Write a
@@ -343,11 +365,32 @@ template. The nth group template breaks on the order's nth term.
 </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.
+The hub clones the group template where the order breaks, and the group's
+contents land immediately before the clone of its nested template, so the
+markup's nesting decides the shape:
+
+| The nested template is       | The group's contents land          | Example                           |
+|------------------------------|------------------------------------|-----------------------------------|
+| Inside the heading's element | Inside it                          | `<tbody>`, `<li>`, `<details>`    |
+| Beside the heading           | After the heading, as its siblings | A heading `<tr>` in one `<tbody>` |
+
+`<tbody>` and `<optgroup>` do not nest, so a table's levels below the first
+are heading rows beside their rows:
+
+```html
+<table lb-query="accounts">
+  <thead><tr><th>Account</th></tr></thead>
+  <template lb-group>
+    <tbody>
+      <tr><th scope="rowgroup" lb-column="category"></th></tr>
+      <template><tr><td lb-column="account_name"></td></tr></template>
+    </tbody>
+  </template>
+</table>
+```
+
+Content after the nested template lands after the group's rows, which is
+where a group's footer goes.
 
 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
@@ -356,6 +399,10 @@ element of a group with `lb-group-live`, `lb-group-column` and
 row. When the order changes, a group whose run goes on is kept and moved,
 and a group whose run ended leaves.
 
+A group template with no nested template is reported to the console. More
+group templates than the order has terms show each extra level as one
+group, and are reported once.
+
 ### Aggregates
 
 `lb-count`, `lb-sum="col"`, `lb-avg="col"`, `lb-min="col"` and
@@ -366,10 +413,24 @@ or of the whole list outside any group:
 <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 showing: a row a filter hides is
-left out.
+| Attribute      | Sets the element to                                       |
+|----------------|-----------------------------------------------------------|
+| `lb-count`     | The number of rows                                        |
+| `lb-sum="col"` | The sum of `col`                                          |
+| `lb-avg="col"` | The average of `col`                                      |
+| `lb-min="col"` | The least value of `col`, by the [order](#order)'s comparison |
+| `lb-max="col"` | The greatest, likewise                                    |
+
+An aggregate lands as a column does, with `lb-column-value`. A sum and an
+average are exact decimals, read from JSON numbers and from strings holding
+a plain decimal, as Postgres sends `numeric`. A sum has as many places as
+the most precise value, and an average up to two more. `null` and empty
+values are left out, as SQL leaves them out, and any other value is left
+out and reported once. The result lands unformatted.
+
+An aggregate covers the rows showing, so a row a filter hides is left out.
+Where the true total matters beyond what the page shows, have the server
+answer it as a row.
 
 ### What happened to a row
 
@@ -384,10 +445,16 @@ Every change to a list is one a stylesheet can see:
 | `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`
+The hub touches a row when an answer names it. `lb-row-created`,
+`lb-row-changed` and `lb-row-moved` are cleared when it next does, and one
+applied again is removed and added as two changes, so an animation keyed to
+it plays again. `lb-row-requested` is cleared at every landing of the row's
+query, and set only by a landing that answers a request from the page.
+
+A row or a group that leaves loses `lb-row-live` or `lb-group-live`, takes
+`lb-row-leaving` or `lb-group-leaving` and `inert`
 ([miswart](../miswarts.md#leaving-rows-are-inert)), and is removed once its
-animations finish, at once when there are none. `lb-row-requested` is
-cleared at every landing; the others when the hub next touches the row.
+animations finish, at once when there are none.
 
 A row is moved when its values changed and the rows whose values did not
 change now stand around it differently. A row it passed is not stamped,
@@ -398,6 +465,11 @@ and a change of the user's order, which changes no values, stamps none.
 [lb-row-leaving] { animation: depart 200ms forwards; }
 ```
 
+A row never travels between its two places, since that takes measuring, and
+measuring takes script. Scrolling to a row is script too: a custom element
+reads `lb-row-requested` in
+[`lbRowsLanded`](./custom-elements.md#holding-rows).
+
 ### What arrives later
 
 The hub keeps each query's last answer until the page changes, with any
@@ -451,6 +523,39 @@ hides is not counted. An empty query is a stylesheet rule:
 The element carrying `lb-query` is a `<div>` here rather than the `<ul>`, so
 that the message is inside it and one rule reaches both.
 
+### Master-detail
+
+A master is a `row` query and its detail is a `rows` query, as two names
+answered side by side. A column never holds rows.
+
+```html
+<section lb-query="invoice">
+  <h2 lb-column="number"></h2>
+  <span lb-column="customer"></span>
+</section>
+
+<table>
+  <tbody lb-query="invoiceLines">
+    <template><tr><td lb-column="item"></td><td lb-column="amount"></td></tr></template>
+  </tbody>
+</table>
+```
+
+Many masters, each with its own detail, is one `rows` query of joined rows:
+each detail row carries its master's columns. A [group template](#groups)
+shows each master as a group, ordered by the master's key first.
+
+A query nested in another query's row template receives the same rows in
+every live row. That serves a picker offering the same choices on every
+row, and is not a way to show a different detail per row; see
+[What arrives later](#what-arrives-later).
+
+Which master a page shows is a query parm, which a query reads off `ctx`,
+since a query takes no argument from the browser; see
+[Query parms](./chrome.md#query-parms). When a write creates or removes the
+master, the handler moves the URL; see
+[Moving the URL](./page-files.md#moving-the-url).
+
 ## Conditional rendering
 
 A page holds every element it can show. Write `lb-show` on an element,
@@ -565,10 +670,14 @@ answers with response items, which land like any others.
 | A control        | `change`                                   |
 | Any other element | `click`                                   |
 
-A click inside an element carrying `lb-request` commits it unless the click
-lands on interactive content between them: a link, a button, a control or a
-label, as HTML defines interactive content. A click into an input inside a
-deletable row focuses the input.
+A click inside an element carrying `lb-request` commits it, as long as the
+element is inside `<lb-hub>` and no interactive content lies between them.
+Interactive content is HTML's: `<a href>`, `<button>`, `<input>` other than
+hidden, `<select>`, `<textarea>`, `<label>`, `<details>`, `<iframe>`,
+`<embed>`, `<audio controls>`, `<video controls>` and `<img usemap>`, plus
+any form-associated custom element. A click on one of them belongs to it: a
+click into an input inside a deletable row focuses the input and deletes
+nothing.
 
 A submit button with a form owner commits with its form. On `submit`, the
 hub sends the submitter's `lb-request` when the submitter carries one, and
@@ -602,7 +711,10 @@ carrying `lb-request`:
 
 The hub gathers from controls only, and skips a control that belongs to a
 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
+query nested in its own; see [A form over a set of rows](#a-form-over-a-set-of-rows).
+An element carrying `lb-query` and `lb-column` both, such as a picker,
+belongs to the row around it, and is gathered with it and sends for that
+row's query. 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:
 
@@ -674,8 +786,10 @@ query's name, in `rows`:
 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.
+- Every live row of the nested query that holds a control goes, whatever
+  its values. What an empty value means, such as no deduction of that type,
+  is the handler's. A picker's options hold no control, so a picker in the
+  form sends its own value and none of its rows.
 - 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
@@ -685,7 +799,9 @@ answers it, and the form shows one input per row.
 - 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).
+the master and its details together; see [crud](./page-files.md#crud). The
+server checks that `rows` holds string keys and string values by query, and
+ignores a request whose `rows` does not.
 
 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
@@ -722,9 +838,14 @@ holds what a submit will gather:
 </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.
+The same holds for a request a custom element sends carrying `key: ""`. No
+ancestor sees a request not sent, and it gets no `lb-request-done`. An
+update or delete with no row around it at all has no key either, and that
+is reported to the console.
+
+A field the request already carries is its issuer's and is kept, so a
+custom element that dispatches its own request with `values` is not
+gathered over.
 
 ### Inserting, updating and deleting rows
 
@@ -741,6 +862,10 @@ The hub sends one of these only when it has what the table lists, and
 otherwise reports to the console. An insert or an update that gathers
 nothing is not sent.
 
+For a query the hub serves, `lb-url` or `lb-choices`, the hub answers
+`lb-row-update` itself, with no round trip; see
+[Query parms](./chrome.md#query-parms) and [Choices](#choices).
+
 A key comes from a live row, or from an element a `row` landed on, so all
 three work against either kind:
 
@@ -804,11 +929,13 @@ 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:
+Pointing a form first empties it: every column it names lands as null, and
+the form resets, so each control returns to its default. Edit then lands
+the row on the form, 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).
+Both focus the form's first control. The form's state is in its
+`lb-key-value` stamp:
 
 | `lb-key-value` | The form is                 |
 |----------------|-----------------------------|
@@ -851,6 +978,11 @@ 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.
 
+A command the hub cannot carry out is reported to the console: Edit from
+outside a live row of the form's query, Edit for a key the hub holds no row
+for, and any command aimed at an element that is not a form carrying
+`lb-query`.
+
 ### Selecting rows
 
 A checkbox carrying `lb-select` in a row template selects the live row it
@@ -927,7 +1059,7 @@ A button carries no value, so a declared request from one sends the values
 of the live row or form it sits in, and the server computes the rest.
 
 A request name beginning with `lb-` that is not one of the three is refused
-by the builder.
+by the builder in markup, and by the hub when a script dispatches it.
 
 ### Request state
 
@@ -992,14 +1124,23 @@ 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).
+[Being a control](./custom-elements.md#being-a-control). A request for
+several rows takes the whole-request message only. A column the request
+gathered no control for is reported to the console.
+
+On the wire a refusal is status 422 with `{ refusal: { message?, columns? } }`;
+see [The data channel](./server.md#the-data-channel).
 
 ### The request event
 
 The hub dispatches every request as a bubbling `lb-request` event from the
 element that committed, with the request as its `detail`, before sending it.
-An ancestor may stop the event, and the request is not sent. A custom
-element may dispatch the event itself; see
+The hub completes the request on the event's way down, so every ancestor
+sees it whole on the way up. An ancestor may stop it, and the request is
+not sent: the event is not cancelable, so an interceptor calls
+`stopPropagation`, not `preventDefault`. That is how a confirmation wrapper
+works without the wrapped element knowing about it. A custom element may
+dispatch the event itself; see
 [Sending a request](./custom-elements.md#sending-a-request).
 
 Once the answer has landed, or the round trip has failed, the hub calls
@@ -1008,6 +1149,37 @@ then dispatches a bubbling `lb-request-done` event from the same element.
 Both carry the request and what landed because of it, or the error; see
 [Hearing how it turned out](./custom-elements.md#hearing-how-it-turned-out).
 
+### The round trip
+
+A request the hub sends has ten seconds to come back. Past that the hub
+aborts it and treats it as a failure, since `fetch` imposes no deadline of
+its own. An application cannot change the deadline.
+
+A round trip fails on a server error, on a network failure, or on that
+deadline, and all three stamp `lb-request-error` on the element that sent
+the request. A refusal is not a failure.
+
+After a successful `lb-row-insert` gathered from a form, the hub resets the
+form, after it lands the response. A failed insert resets nothing, so the
+entry can be corrected. An `lb-row-update` resets nothing: the row it sent
+lands back on its controls.
+
+A reset of any form, whether the hub's, a reset button's or a script's,
+returns its controls to their defaults, and the hub removes
+`lb-column-value` from each of them. A cancelled reset keeps both.
+
+A page load that fails lands nothing and is reported to the console. A load
+started by a request for `lb-url` stamps the element that sent it, as any
+request stamps its element.
+
+A response answers for the URL its request was sent from, path and query
+string both. One that returns after the URL has moved lands nothing, since
+it describes what the user is no longer looking at: a request's answer,
+including any `url()` it carries, and a page load overtaken by a newer one.
+A write whose answer is dropped this way has still happened. Its
+`lb-request-done` carries no items and no error, and an insert still resets
+its form.
+
 ## The URL
 
 The hub serves one query of its own, `lb-url`: one row holding the path, the
@@ -1056,7 +1228,9 @@ The developer writes `lb-` attributes in markup, and script never assigns
 them. The builder checks the markup of the chrome and of every page, after
 expansion, and refuses to build:
 
-- an `lb-` attribute that is not one of the sixteen the developer writes
+- an `lb-` attribute that is not one of the sixteen the developer writes;
+  `lb-exp-slot` and `lb-exp-template` are consumed by expansion and never
+  reach the check
 - `lb-request` naming an `lb-` request other than the three Loadbare provides
 - `lb-query` naming a query the page does not declare; every page and the
   chrome may name `lb-url` and `lb-choices`, and the chrome names no other
@@ -1078,6 +1252,22 @@ expansion, and refuses to build:
   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`
+- `lb-group` on anything but a `<template>`, or on one holding no
+  `<template>` for its contents
+- an aggregate on a `<template>`, or any but `lb-count` naming no column
+- a chrome without exactly one `<lb-hub>` and exactly one `<main>`, a
+  `<main>` outside `<lb-hub>`, or a `<main>` holding anything but whitespace
+- a page carrying an `<lb-hub>` or a `<main>`
+
+The builder also reads the script of every custom element it ships, other
+than `<lb-hub>`, and refuses one that declares a method, accessor or field
+whose name is `lb`, a capital, and anything Loadbare does not call; see
+[Reserved methods](./names.md#reserved-methods).
+
+`lb-column` with no ancestor row is allowed: the hub gathers from it.
+
+Script never assigns an `lb-` attribute, so the markup states every one
+that exists, and checking the markup is sound.
 
 To know what each page declares, the builder loads its `.queries.ts` and
 `.requests.ts` modules, so their import-time code runs during the build, as