@loadbare/app 0.18.2 → 0.19.0

package/skills/loadbare-app/references/TECHREF-1.0.md

@@ -5,68 +5,6 @@ This is the complete technical reference to the upcoming Release 1.0.
 Method-of-work is to continually revise this document to what we want
 to be true, then revise the code, docs, and tests to ensure it is true.
 
-## Blockers
-
-We cannot declare 1.0 until we determine if these blockers can be
-added later w/o breaking changes.  If we are reasonably confident
-that they can be decided later w/o breaking changes, then we rename
-them to "Out of Scope" or move them to the roadmap.  Otherwise, 
-they must be resolved before we declare 1.0.
-
-### Nested queries
-
-Imagine an HTML `<select>` that shows a fixed set of choices on every row of
-a table, such as `customer_type` for a table of customers.  When every
-customer may take every customer type, the system as written today is
-fine, because every `<select>` receives the same rows.
-
-But the allowed values may depend on other values in the row.
-
-- **Decide whether a nested query's rows may depend on its row.** A nested
-  query has one answer, which every live row receives.  See
-  [Master-detail](#master-detail) for what a nested query is for.
-
-```html
-<tbody lb-query="accounts">
-  <template><tr>
-    <td lb-column="name"></td>
-    <td><select lb-query="statuses" lb-column="status"><template><option lb-column="label"></option></template></select></td>
-  </tr></template>
-</tbody>
-```
-
-### The server API
-
-- **Land `staticRoutes`.**  It closes the last place where an
-  application hand-writes facts the builder owns.
-
-### The builder
-
-- **Adopt a configuration file and fold `imports.ts` into it.** It holds
-  `out`, `minify` and `imports`, and lives where `imports.ts` lives now, so a
-  repository with several applications gets one per application.  `--src`
-  stays a flag, since it is what locates the file.  State the precedence
-  between a flag and a key once.  Its key names join the permanent surface,
-  so this lands before 1.0 or not at all.  It reserves a key for the
-  roadmap's tree-shaking CSS by tag name.
-- **Confirm the three output names.** `app.html`, `client.js` and `app.css`
-  are about to be fixed in `staticRoutes` as well as in the builder.
-
-### The internal surface
-
-None of this is surface.  It is listed here because trimming it is free
-today and breaking after 1.0.
-
-- **Audit what the hub does.** Every routine it runs answers to an `lb-*`
-  attribute, a [reserved query](#reserved-queries), or a
-  [reserved event](#reserved-events) or [method](#reserved-methods).  Trim
-  whatever does not, and leave what stays clean: no dead code, no routine
-  written twice, no comment the code contradicts.
-- **Keep the rest as constants.** The endpoint, `index` and the timeout are
-  linkage between the builder and the hub rather than facts an application
-  varies.  Adding a knob for any of them buys a second shape of application
-  to reason about.
-
 ## The build
 
 ### Running the builder
@@ -173,8 +111,8 @@ it is sent to the browser on initial page load, no HTML is ever sent
 again.
 
 The developer writes `lb-*` attributes in markup.  Script never assigns
-them.  The hub and the builder write only their stamps, and the hub writes
-the `name` of a radio button in a row template.  See
+them.  The hub and the builder write only their stamps, apart from the
+few exceptions listed in [Miswarts](./miswarts.md).  See
 [The markup checks](#the-markup-checks).
 
 ### Expansion
@@ -1366,10 +1304,10 @@ new URL carries only the query parms the request names.
 
 Every load lands `lb-url`, and a parm the URL does not carry lands empty on
 every element naming it as a column, so a control shows what the address
-bar says after Back as well as after a reload.  This is the one exception
-to landing, where a row sets the columns it names and leaves the rest as
-they were: the hub reads the column names under `lb-query="lb-url"` and
-names each one in the row it lands.
+bar says after Back as well as after a reload
+([miswart](./miswarts.md#lb-url-lands-every-parm-it-names)): the hub reads the
+column names under `lb-query="lb-url"` and names each one in the row it
+lands.
 
 The hub sends the query parms with every round trip, a page load and a
 request alike.  The server passes them to `contextFor` — see
@@ -1518,6 +1456,15 @@ to build on any of these:
   reach the check.
 - `lb-request` naming a value that begins with `lb-` and is not one of the
   three request names.
+- `lb-query` naming a query the page does not declare.  `lb-url` and
+  `lb-choices` are the hub's, and every page and the chrome may name them.
+  The chrome belongs to no page, and names no other query.
+- `lb-request` naming a request the page does not declare under `handlers`.
+  The chrome sends none of them.
+- One of the three request names for a query whose `crud` entry does not
+  declare it, and any but `lb-row-update` for `lb-url` or `lb-choices`.  The
+  query is a form's own when the form carries `lb-query`, and otherwise the
+  nearest `lb-query` around the element.
 - `lb-url-link` on anything but an `<a>`.
 - `lb-url-push` on an element with no `lb-request`.
 - `lb-url-unknown` on anything but a `<dialog>`, and in the chrome, outside
@@ -1547,6 +1494,10 @@ whose name begins with `lb` and a capital and is not in
 
 `lb-column` with no ancestor row is allowed: the hub gathers from it.
 
+To know what each page declares, the builder loads the page's
+`.queries.ts` and `.requests.ts` modules, so their import-time code runs
+during the build, as it does when the server starts.
+
 Script never assigns an `lb-` attribute, so the markup states every one
 that exists, and checking the markup is sound.
 
@@ -1559,7 +1510,8 @@ uncommon, and Loadbare/app does not shape itself around them.
   by `name`, and a row template repeats one `name` in every live row.  The
   hub stamps each radio button's `name` with the `name` written, or its
   column when none is, followed by `-` and the live row's key, so each live
-  row holds a group of its own.
+  row holds a group of its own
+  ([miswart](./miswarts.md#radio-button-names-in-a-row-template)).
 - **Several rows not yet entered, each holding radio buttons.**  A
   [row not yet entered](#a-row-not-yet-entered) has an empty key, so the
   radio buttons of every such row share one `name` and form one group.
@@ -1821,9 +1773,12 @@ It has four optional keys.
 | `onChoices`   | Nothing               | Runs with every choice made on the page, each time the user makes one |
 
 The server resolves a declared request against `handlers`, and a request
-Loadbare provides against `crud` under the request's query.  A name with no
-entry there logs a server console warning naming the page and the missing
-entry, and answers 200 with no response items, so nothing lands and
+Loadbare provides against `crud` under the request's query.  The builder
+refuses markup naming a request the page does not declare; see
+[The markup checks](#the-markup-checks).  A name with no entry there can
+still arrive, from a widget's script or from outside the page, and it
+logs a server console warning naming the page and the missing entry, and
+answers 200 with no response items, so nothing lands and
 `lb-request-pending` clears from the element that issued the request.  A
 request carrying no name answers 400, and a `run` that throws answers 500.
 

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

@@ -128,11 +128,18 @@ substitution rules — wraps each expanded page in
 `<template lb-page="<stub>">`, and splices them into the chrome's `<body>`.
 It removes a page file's `<title>` and stamps its text on the page's
 template as `lb-page-title`; see [The page title](./page-files.md#the-page-title).
-It formats the result with Prettier when the application has it installed.
+It formats the result with Prettier, which ships with `@loadbare/app`, and
+keeps the unformatted result if Prettier fails.
 
 The builder checks the `lb-` attributes of the chrome and every page after
 expansion, and stops on the first file with a problem; see
-[The markup checks](./data-binding.md#the-markup-checks).
+[The markup checks](./data-binding.md#the-markup-checks). The names
+`lb-query` and `lb-request` carry are checked against what each page
+declares, which the builder reads by loading the page's `.queries.ts` and
+`.requests.ts` modules. Their import-time code runs during the build, as it
+does when the server starts, so a module that connects to a database at
+import connects during the build too; open connections in `contextFor`
+instead.
 
 The builder writes `app.css` only when it finds a stylesheet, and `pages.ts`
 only when some page has a `.requests.ts` or a `.queries.ts` file. Import `hub`

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

@@ -224,7 +224,8 @@ being visibly empty — so it's the whole document that needs to wait, not
 just the piece that was empty.
 
 The `<noscript>` block is the escape hatch for a visitor with JavaScript
-disabled. `<lb-hub>` is what removes `hidden` from `<body>`, so a browser
+disabled. `<lb-hub>` is what removes `hidden` from `<body>`
+([miswart](./miswarts.md#the-hub-unhides-the-body)), so a browser
 that never runs `client.js` would otherwise be stuck looking at a
 permanently blank page. `<noscript>` content is only rendered when scripting
 is off, so the fallback rule only ever applies in exactly that case — it

package/skills/loadbare-app/references/custom-elements.md

@@ -290,7 +290,7 @@ Each direction has one mechanism for each kind of message:
 
 | Direction      | What                                       | How                         | Today |
 |----------------|--------------------------------------------|-----------------------------|-------|
-| Hub to element | State that lasts                           | An attribute the hub stamps | `lb-column-value`, `lb-key-value`, `lb-query-row-count`, `lb-group-*`, `lb-row-*`, `lb-request-pending`, `lb-request-error` |
+| Hub to element | State that lasts                           | An attribute the hub stamps | `lb-column-value`, `lb-key-value`, `lb-query-row-count`, `lb-group-*`, `lb-row-*`, `lb-request-pending`, `lb-request-error`, `lb-request-refused` |
 | Hub to element | State the platform already names           | A property                  | A control's `value` |
 | Hub to element | What the hub did                           | An optional `lb` method     | `lbAttached`, `lbRowsLanded`, `lbRequestDone`, `lbDetached` |
 | Hub to element | A moment an element started                | A bubbling event            | `lb-request-done` |

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

@@ -2,7 +2,7 @@
 
 A page shows server data by naming queries and columns in its HTML, and asks
 the server to change that data by naming requests. The developer writes
-nine `lb-` attributes. The server declares every query a page may show and
+sixteen `lb-` attributes. The server declares every query a page may show and
 every request it may send, and refuses anything it has not declared.
 
 Everything is a query. A query is a name for rows, of kind `row` or `rows`,
@@ -48,6 +48,10 @@ each with its key, and permits the three requests on `roster`; see
 | `lb-show`        | Any element but `<template>`  | The column that decides whether it is present  |
 | `lb-order`       | An element with `lb-query`    | The choice holding the user's order; see [Order](#order) |
 | `lb-filter`      | An element with `lb-query`    | The columns a choice filters; see [Filters](#filters) |
+| `lb-group`       | A `<template>`                | Nothing: it marks a group template; see [Groups](#groups) |
+| `lb-count`       | Any element                   | Nothing: it shows a count of rows; see [Aggregates](#aggregates) |
+| `lb-sum`, `lb-avg`, `lb-min`, `lb-max` | Any element | The column aggregated; see [Aggregates](#aggregates) |
+| `lb-select`      | A checkbox in a row template  | Nothing: it selects its live row; see [Selecting rows](#selecting-rows) |
 | `lb-request`     | Any element                   | The request it sends when it commits           |
 | `lb-url-link`    | An `<a>`                      | A link between pages; see [chrome](./chrome.md#links) |
 | `lb-url-push`    | An element with `lb-request`  | A URL change that pushes a history entry       |
@@ -62,8 +66,14 @@ builder writes a stamp, and a stylesheet or a custom element reads it.
 | `lb-key-value`       | The key of a live row, or of a `row` landed on an element |
 | `lb-row-live`        | The element is a live row                          |
 | `lb-query-row-count` | The number of live rows an element shows           |
+| `lb-group-live`, `lb-group-column`, `lb-group-value` | A group, the column it breaks on, and its value; see [Groups](#groups) |
+| `lb-row-created`, `lb-row-changed`, `lb-row-moved`, `lb-row-requested` | What happened to a row; see [What happened to a row](#what-happened-to-a-row) |
+| `lb-row-leaving`, `lb-group-leaving` | A row or group on its way out      |
+| `lb-row-editing`     | The row a form is pointed at; see [Editing a row in one form](#editing-a-row-in-one-form) |
+| `lb-row-selected`    | A row whose `lb-select` is ticked                  |
 | `lb-request-pending` | The element's request is in flight                 |
 | `lb-request-error`   | The element's last request failed                  |
+| `lb-request-refused` | The handler refused it; see [Refusals](#refusals)  |
 | `lb-page`            | The stub of a page, on its `<template>`            |
 | `lb-page-title`      | The text of a page file's `<title>`                |
 
@@ -151,7 +161,8 @@ column the user sorts or filters raw, and format it in the element.
 ### Checkboxes
 
 A checkbox is a control. It is checked when its column is anything but
-`false` or null, and it sends `"true"` or `"false"`:
+`false` or null, and it sends `"true"` or `"false"`
+([miswart](./miswarts.md#checkboxes-and-radio-groups-always-gather-a-value)):
 
 ```html
 <input type="checkbox" lb-column="active" lb-request="lb-row-update" />
@@ -176,8 +187,9 @@ when none is:
 
 In a row template, the hub stamps each radio button's `name` with the
 `name` written, or its column when none is, followed by `-` and the live
-row's key, so each live row holds a group of its own.  Rows not yet entered
-share the empty key, and so share one group.
+row's key, so each live row holds a group of its own
+([miswart](./miswarts.md#radio-button-names-in-a-row-template)).  Rows not yet
+entered share the empty key, and so share one group.
 
 A radio button in a query's row template answers to that query's row, as
 any element there does.  A choice among a query's rows is better made with
@@ -280,7 +292,8 @@ its rows the user may filter, separated by commas. The column of
 ```
 
 A row that does not pass every filter is `hidden`, and a ticked `lb-select`
-in it is cleared. A group whose rows are all hidden is hidden too. An empty
+in it is cleared. A group whose rows are all hidden is hidden too
+([miswart](./miswarts.md#rows-hidden-by-a-filter)). An empty
 choice filters nothing.
 
 A filter is one or more terms, each an operator followed by a value:
@@ -371,8 +384,9 @@ 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`, and is removed once
-its animations finish, at once when there are none. `lb-row-requested` is
+A row that leaves loses `lb-row-live`, takes `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.
 
 A row is moved when its values changed and the rows whose values did not
@@ -927,7 +941,8 @@ The hub stamps the element that committed:
 
 `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
-`aria-busy="true"` for as long as `lb-request-pending` is present.
+`aria-busy="true"` for as long as `lb-request-pending` is present
+([miswart](./miswarts.md#busy-elements-carry-aria-busy)).
 
 The hub ignores a commit on an element carrying `lb-request-pending`, so a
 pending button is already disabled and a stylesheet only shows it:
@@ -1041,8 +1056,16 @@ 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 nine the developer writes
+- an `lb-` attribute that is not one of the sixteen the developer writes
 - `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
+- `lb-request` naming a request the page does not declare under `handlers`;
+  the chrome sends none
+- one of the three requests for a query whose `crud` entry does not declare
+  it, or any but `lb-row-update` for `lb-url` or `lb-choices`; the query is
+  a form's own when the form carries `lb-query`, and otherwise the nearest
+  `lb-query` around the element
 - `lb-url-link` on anything but an `<a>`
 - `lb-url-push` on an element without `lb-request`
 - `lb-url-unknown` on anything but a `<dialog>`, or outside `<lb-hub>`
@@ -1055,3 +1078,7 @@ 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`
+
+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
+it does when the server starts.

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

@@ -0,0 +1,140 @@
+# Miswarts
+
+A miswart is a place where Loadbare/app breaks one of its own rules.
+Anybody paying attention will see it as a violation, and they will be
+right.  Yet in context it turns out to be the RightThing(tm), and doing it
+any other way would be worse for the user or the developer.
+
+The reference describes each miswart's behavior where it applies, and
+links here.  This document is the one place that admits they are
+exceptions, and says why each one is allowed to stay.
+
+## The test
+
+A miswart must be:
+
+- **Small.**  It can be stated in a sentence or two.
+- **Orthogonal.**  It has no interaction with any other miswart.
+- **Terminating.**  It does not, by logical extension, require another
+  miswart.  If fixing the edges of one exception calls for a second, we
+  probably should be looking for a weakness in earlier implementation
+  decisions. 
+
+Each entry also names two things:
+
+- **The rule it breaks.**  If we cannot name the rule, it is not a
+  miswart, it is undocumented behavior.
+- **The motivation that justifies it**: performance, correctness or
+  ergonomics, as set out in the theory document.  That is what makes it
+  the RightThing(tm) rather than a convenience.
+
+## Radio button names in a row template
+
+**What.**  The hub stamps the `name` of each radio button in a row
+template with the `name` written, or its column when none is, followed by
+`-` and the live row's key.
+
+**Rule broken.**  The hub writes only its own stamps, which always
+begin with `lb-`.
+
+**Why it is the RightThing(tm).**  Correctness.  The browser groups radio
+buttons by `name`, and a row template repeats one `name` in every live
+row, so without the stamp every row's buttons would form a single group,
+and checking one row would uncheck all the others.
+
+**Why it terminates.**  It applies only to radio buttons inside a row
+template, and only the `name`.
+
+## Checkboxes and radio groups always gather a value
+
+**What.**  An unchecked checkbox gathers `"false"`, a checked one
+`"true"`, and its `value` attribute means nothing to the hub.  A radio
+group with none checked gathers `""`.
+
+**Rule broken.**  Where HTML already has an opinion, Loadbare/app
+follows it.  HTML sends a checkbox's `value` when it
+is checked, and sends nothing for an unchecked checkbox or an empty radio
+group.
+
+**Why it is the RightThing(tm).**  Correctness.  A write must be able to
+set a flag back to false, or clear a choice, and nothing on the wire
+cannot say either.
+
+**Why it terminates.**  It applies only to gathering from these two
+controls.  Landing still follows HTML's own idea of checked.
+
+## Rows hidden by a filter
+
+**What.**  A row that does not pass the user's filter gets the `hidden`
+attribute, and so does a group whose rows are all hidden.
+
+**Rule broken.**  The hub writes only its own stamps, which always
+begin with `lb-`.
+
+**Why it is the RightThing(tm).**  Performance and ergonomics.  A filter
+over rows already on the page needs no round trip, and `hidden` is HTML's
+own word for an element that is present but not shown.  A stamp of our
+own would make every stylesheet restate what the browser already does.
+
+**Why it terminates.**  It applies only to live rows and groups under a
+filter.
+
+## Leaving rows are inert
+
+**What.**  A row on its way out takes `inert` while its animation runs,
+and is removed when the animation finishes.
+
+**Rule broken.**  The hub writes only its own stamps, which always
+begin with `lb-`.
+
+**Why it is the RightThing(tm).**  Correctness.  A row that is gone from
+the database must not take a click or the focus during its exit
+animation, and `inert` is exactly HTML's word for that.
+
+**Why it terminates.**  It applies only to a row already stamped
+`lb-row-leaving`, which never comes back.
+
+## Busy elements carry aria-busy
+
+**What.**  While an element's request is in flight, it carries
+`aria-busy="true"` alongside `lb-request-pending`.
+
+**Rule broken.**  The hub writes only its own stamps, which always
+begin with `lb-`.
+
+**Why it is the RightThing(tm).**  Correctness, for a user of assistive
+technology.  `lb-request-pending` tells a stylesheet, and `aria-busy` tells
+a screen reader, the same fact.
+
+**Why it terminates.**  It rides with `lb-request-pending` and nothing
+else.
+
+## The hub unhides the body
+
+**What.**  When the chrome writes `<body hidden>`, the hub removes
+`hidden` once the first page has landed.
+
+**Rule broken.**  The hub writes only its own stamps, which always
+begin with `lb-`.
+
+**Why it is the RightThing(tm).**  Performance, as the user perceives it.
+Without it, the first load blinks an empty page before the data lands.
+Only the hub knows when the first page has landed.
+
+**Why it terminates.**  It happens once, to `<body>`, and only when the
+application opted in by writing `hidden`.
+
+## `lb-url` lands every parm it names
+
+**What.**  When `lb-url` lands, a query parm the URL does not carry lands
+empty on every element naming it as a column.
+
+**Rule broken.**  Landing a row sets the columns the row carries, and
+leaves the rest as they were.
+
+**Why it is the RightThing(tm).**  Correctness.  A control must show what
+the address bar says, after Back as well as after a reload, and a parm
+that is absent from the URL is a parm whose value is empty.
+
+**Why it terminates.**  It applies only to `lb-url`, the one query whose
+columns are the URL itself.

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

@@ -229,8 +229,9 @@ export const requests: Requests = {
 };
 ```
 
-Declare every request the page allows. The server refuses a name the page
-does not declare.
+Declare every request the page allows. The builder refuses markup naming a
+request the page does not declare, and the server refuses one that arrives
+anyway; see [The markup checks](./data-binding.md#the-markup-checks).
 
 ### crud
 
@@ -293,8 +294,9 @@ export const requests: Requests = {
 };
 ```
 
-Declare every request the query permits. The server refuses a request a
-query does not declare, and a query with no `crud` entry permits none.
+Declare every request the query permits. The builder refuses markup sending
+a request a query does not declare, and the server refuses one that arrives
+anyway. A query with no `crud` entry permits none.
 
 Write `rowUpdate` to set the columns `values` names and leave every other
 column as it is. A form or a live row sends every control it gathers, and a
@@ -303,6 +305,36 @@ columns the page may edit.
 
 Every value in `values` is a string, as a control's value is.
 
+Two users writing the same row overlap only on the columns their requests
+carry, and the last write wins.  A single control sends its own column, so
+two users editing different columns of a row do not overwrite each other.
+A form sends every control it gathers, so two forms saved over one row
+overlap on all of their columns.
+
+A write whose outcome matters states its precondition in its own SQL, and
+refuses when no row was updated:
+
+```ts
+handlers: {
+  approve: {
+    run: async (ctx, { key }) => {
+      const updated = await ctx.db.run(
+        "UPDATE invoice SET status = 'approved' WHERE id = $1 AND status = 'pending'",
+        [key],
+      );
+      if (updated === 0) {
+        throw refusal("Someone else has already decided this invoice.");
+      }
+    },
+    refresh: ["invoice"],
+  },
+},
+```
+
+The request's name says what the user meant, and the precondition follows
+from it, so no earlier value is needed.  See
+[Refusing a request](#refusing-a-request).
+
 ### refresh and patch
 
 List in `refresh` every query whose whole answer the request changed.