@loadbare/app 0.12.0 → 0.13.0

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

@@ -278,7 +278,10 @@ A custom element reads `lb-` attributes and never assigns one. The developer
 writes them in markup, and the hub and the builder write their stamps.
 
 Loadbare reserves method names beginning with `lb` on a custom element, for
-the methods it calls; see [Holding rows](#holding-rows).
+the methods it calls; see [Holding rows](#holding-rows).  The build refuses
+a script that declares a method, accessor or field whose name is `lb`, a
+capital, and anything else Loadbare does not call, so a misspelled
+`lbRowLanded` fails the build rather than never being called.
 
 ### What the hub and an element say to each other
 
@@ -286,9 +289,9 @@ 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-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` |
 | Hub to element | State the platform already names           | A property                  | A control's `value` |
-| Hub to element | Work the hub needs done now, while landing | An optional `lb` method     | `lbPlaceRow`, `lbRowsLanded` |
+| Hub to element | Work the hub needs done now, while landing | An optional `lb` method     | `lbRowsLanded` |
 | Hub to element | A moment an element started                | A bubbling event            | `lb-request-done` |
 | Element to hub | A moment                                   | A bubbling event            | `lb-request`, and `change`, `click` and `submit` |
 
@@ -329,7 +332,7 @@ So each kind of work has one place:
    reads no attribute and no child: an element made with
    `document.createElement` has neither when it runs.
 2. **A child is looked up when it is needed**, in a handler, a getter,
-   `lbPlaceRow` or `lbRowsLanded`, and never held from setup.
+   or `lbRowsLanded`, and never held from setup.
 3. **`connectedCallback` runs on every move**, so it is written to run
    again. It rearranges the element's own children into a state it checks
    for first, or adds a listener to `document` or `window`, which
@@ -505,34 +508,32 @@ outside the document, and no ancestor it had there hears it.
 
 ### Holding rows
 
-The hub lands every row template itself. A plain element carrying `lb-query`
-with a row template inside it needs no code, so a custom element holds rows
-only when they need placement or scaffolding that only it can decide.
+The hub lands every row template itself, places every row by the query's
+order, and builds every group the markup's group templates describe; see
+[Order](./data-binding.md#order) and [Groups](./data-binding.md#groups). A
+plain element carrying `lb-query` with a row template inside it needs no
+code, so a custom element holds rows only to do something with them once
+they land.
 
-A custom element carrying `lb-query` and a row template may implement two
-optional methods, which the hub calls:
+A custom element carrying `lb-query` and a row template may implement one
+optional method, which the hub calls:
 
 ```ts
-import type { RowsHost, Row } from "@loadbare/app/types";
-
-class SortedList extends HTMLElement implements RowsHost {
-  lbPlaceRow(el: Element, row: Row, template: HTMLTemplateElement) {
-    // Where this live row goes. Called with the live row detached, on its
-    // first appearance and again whenever all rows decide the order.
-  }
+import type { RowsHost } from "@loadbare/app/types";
+import { ATTR_ROW_REQUESTED, REQUESTED_CREATED } from "@loadbare/app/constants";
 
+class ScrollingList extends HTMLElement implements RowsHost {
   lbRowsLanded() {
-    // Once, after the rows have landed. For scaffolding derived from the
-    // rows: a section heading, an <optgroup>, anything that goes when its
-    // last row does.
+    // Once, after the rows have landed, every row placed and stamped.
+    this.querySelector(`[${ATTR_ROW_REQUESTED}="${REQUESTED_CREATED}"]`)
+      ?.scrollIntoView({ block: "nearest" });
   }
 }
 ```
 
-| Method         | The hub calls it    |
-|----------------|---------------------|
-| `lbPlaceRow`   | To place a live row |
-| `lbRowsLanded` | After the rows land |
+| Method         | The hub calls it                                      |
+|----------------|-------------------------------------------------------|
+| `lbRowsLanded` | After the rows land, with every row placed and stamped |
 
 Everything else is the hub's:
 
@@ -540,25 +541,23 @@ Everything else is the hub's:
 |-------------|----------------------------------------------------------|
 | Cloning     | Clones the row template once per new key                 |
 | Matching    | Fills the live row already showing that key              |
-| Removing    | Removes the live rows the response says are gone         |
-| Stamping    | Stamps each live row with `lb-row-live` and `lb-key-value` |
+| Placing     | Places every live row by the query's order               |
+| Grouping    | Builds a group where the order breaks, and removes it with its last row |
+| Removing    | Marks the live rows the response says are gone as leaving, and removes them |
+| Stamping    | Stamps each live row with `lb-row-live`, `lb-key-value`, and what happened to it |
 | Counting    | Stamps `lb-query-row-count` with the number of live rows |
 
-`lbPlaceRow` receives the live row already filled and not yet in the
-document, so a custom element that reads a column to decide where the row
-goes can. Without it, the hub places a live row immediately before the row
-template, in arrival order. `lb-options.browser.ts` and
-`lb-table.browser.ts` in [`@loadbare/widgets`](./widgets.md) are two
-different placements over the same landing.
+`lb-options.browser.ts` and `lb-table.browser.ts` in
+[`@loadbare/widgets`](./widgets.md) are two uses of `lbRowsLanded`: one
+gives each option and `<optgroup>` what landing does not, a value and a
+label, and the other scrolls to the row the page's request created or
+moved.
 
 A custom element the builder shipped absent under `lb-show` has not
-upgraded while its column is off, so it has no `lbPlaceRow` when rows land
-on it then, and the hub places them before the template. When the column
-first turns on and the element upgrades, the hub lands the query's last
-answer on it again, as all rows, so every row goes through `lbPlaceRow` and
-`lbRowsLanded` runs. Once upgraded it stays so: when its branch goes away and
-comes back, it has placed every row that landed meanwhile, and nothing is
-landed again.
+upgraded while its column is off, and the hub places the rows that land on
+it then as it places any. When the column first turns on and the element
+upgrades, the hub lands the query's last answer on it again, as all rows,
+so `lbRowsLanded` runs.
 
 A custom element that walks its own rows finds them with `LIVE_ROW` from
 `@loadbare/app/constants`, never by `lb-key-value`: an element a `row` lands

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

@@ -153,9 +153,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 +163,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 +265,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

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          |
 
@@ -150,6 +155,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
@@ -240,16 +251,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

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

@@ -91,6 +91,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
+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
 against the contracts in [Custom Elements](./custom-elements.md#html) for its
 definition and [Custom Elements](./custom-elements.md#code) for its class.
 
@@ -43,6 +44,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 +69,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 +79,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 +106,6 @@ one option showing one column:
   lb-request="lb-row-update"
   exp-label="Status"
   exp-column="label"
-  exp-group="category"
 ></lb-picker>
 ```
 
@@ -108,10 +113,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 +127,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 +147,78 @@ 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 widget stops an
+`lb-row-update` that carries no key, so its controls wait for a submit.
+
+| 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: 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.
+
+| 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-unknown-page`