@loadbare/app 0.12.0 → 0.13.0

package/docs/reference/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`
 

package/docs/roadmap.md

@@ -29,12 +29,6 @@ expanding row). [Theory](./theory.md) already flags this as possibly load-bearin
 disallowed. Worth a decision-in-principle the first time a master-detail
 page is built, even before the mechanism is needed elsewhere.
 
-### Pending appearance
-
-A value that hasn't arrived yet is probably derivable from an absent
-`lb-column-value` rather than needing a signal of its own. Not yet needed because
-nothing currently produces that gap in practice — revisit if one does.
-
 ### Events while a request is in flight
 
 The hub ignores a commit on an element carrying `lb-request-pending`.
@@ -108,6 +102,16 @@ Most valuable against a large imported widget library, where an app uses a
 small fraction of what ships. Revisit when a real app's `app.css` is big
 enough to measure.
 
+### Queries stated by the chrome
+
+A custom element in the chrome naming a query forces every page to declare
+that query, since the page load covers one page's set.  `lb-url` shows the
+pattern from the framework side, and an application has no equivalent.
+
+A chrome-level query set on `createHub` would close this, and it is additive.
+It takes its place in the options argument whose shape is a 1.0 blocker in
+[TECHREF-1.0](./TECHREF-1.0.md#the-server-api).
+
 ### Data binding utilities
 
 A custom element that finds its own nearest ancestor `lb-query`,

package/docs/testing.md

@@ -86,6 +86,9 @@ anything ships:
   `lb-url-unknown` off a `<dialog>` or outside `<lb-hub>`
 - `lb-show` on a `<template>`, on a row template's root, or with no row
   around it
+- a chrome without exactly one `<lb-hub>` and one empty `<main>` inside it,
+  and a page carrying either
+- a widget script declaring an `lb` method Loadbare does not define
 
 A page file's `<title>` is lifted out and stamped as `lb-page-title`.
 
@@ -119,6 +122,13 @@ The rest of the build — `assemble`, `elements`, `pages`, `styles`,
 `package-css` — is tested the same way and in the same tier, since none of it
 needs a browser either.
 
+**The command.** `loadbare-app-build` itself runs in a child process against
+a temporary project, which carries a stand-in `@loadbare/app` pointing at
+the hub's source so the test needs no prior build.  It is tested for its
+default `src` and `dist`, every file it writes, `--minify`, a failed build's
+exit code, and `--watch` rebuilding on a change, skipping a file it does not
+watch, and surviving a failed build.
+
 ## Tier 2 — The engine
 
 `createHub` takes a plain object and returns an object. Nothing in
@@ -163,14 +173,14 @@ evidence here.
   the row around it, and the columns inside it are its own query's
 - a query nothing names is reported and skipped; several elements naming one
   query are all filled
-- all rows decide membership and order, so a key that did not arrive is gone
-- a patch disturbs only what it names, in contents and in position
+- all rows decide membership, so a key that did not arrive is gone
+- a patch disturbs only what it names, in contents, and a row moves only
+  when the order puts it somewhere else
 - `lb-query-row-count` is counted from the DOM after reconciliation, so all
   rows and a patch ending in the same state report the same number
-- `lbPlaceRow` is called for a fresh row always, and for an existing row
-  only under all rows. That is today's behavior, not a decision — a patch
-  therefore never re-places a row whose sort key changed. The test states
-  what is true now, and is the one that flips if that changes.
+- the order places all rows and a patch alike, groups come and go with
+  their rows to any depth, aggregates follow every landing, and every change
+  leaves a stamp a stylesheet can see (`lb-order.test.ts`)
 - `lb-show` moves an element into a template and back, and landing reaches
   inside it
 
@@ -223,6 +233,8 @@ What the hub is tested for here:
   `lb-request-error` replaces it on failure, and the next request clears
   it; `aria-busy` comes and goes with `lb-request-pending`, and a commit on
   a pending element is ignored
+- a round trip the server never answers is aborted at the ten-second
+  deadline, under mocked timers, and fails the way any round trip fails
 - a successful insert gathered from a form resets the form
 - a path with no page reports, lands `lb-page-unknown`, and opens the
   `lb-url-unknown` dialog; two pages for one stub report and take the first
@@ -235,7 +247,7 @@ What the hub is tested for here:
 - an `lb-url` item in a server answer writes the URL and lands the page
   loaded there
 - `hidden` comes off the body once a page has landed, including the page
-  that failed to load
+  that failed to load, and a link whose page fails to load marks no element
 
 Widgets are small and their logic is local, so jsdom carries them: a value
 reaches the control the widget owns, the widget is a form-associated control
@@ -266,9 +278,8 @@ No browser test runner is installed and none of the following exists. They
 are recorded here as the shape of the work, not as coverage:
 
 1. a cold load fills `<main>` with no empty flash
-2. the ten-second deadline aborts a request that never answers
-3. the wizard never displays a step the server has not confirmed
-4. the view-source invariant
+2. the wizard never displays a step the server has not confirmed
+3. the view-source invariant
 
 The last is the one worth a browser. Loadbare's central claim is that no
 markup exists in the DOM that is not in view-source, and that the difference

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@loadbare/app",
   "description": "High performance web app framework for server-bound applications",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "type": "module",
   "files": [
     "dist",
@@ -22,8 +22,7 @@
     "./constants": "./dist/core/lb-constants.js",
     "./types": "./dist/core/lb-types.js",
     "./server": "./dist/server/lb-server.js",
-    "./express": "./dist/server/lb-express.js",
-    "./build": "./dist/build/elements.js"
+    "./express": "./dist/server/lb-express.js"
   },
   "scripts": {
     "prepublishOnly": "npm run typecheck && npm run test && npm run build",

package/skills/loadbare-app/SKILL.md

@@ -176,12 +176,35 @@ from it.
 
 **A column never holds rows.**  Master-detail is a `row` query and a `rows`
 query under two names.  Many masters with their details is one `rows` query
-of joined rows, grouped for display by a custom element's `lbPlaceRow`.  A
+of joined rows, ordered by the master first and shown in groups.  A
 query nested inside another query's row template receives the same rows in
 every outer row; use it for a picker, never for per-row detail.  A new outer
 row is filled from the nested query's last answer, whatever order they land
 in.
 
+**A `rows` query declares its order, and the hub places every row by it.**
+`rows("id", run, { order: "category_order,name" })`; a column after `-` sorts
+descending, and values compare by JSON type, so a numeric sort column is a
+JSON number.  The parm `lb-order-<query>` replaces the order, and a control
+writing it inside `lb-query="lb-url"` re-sorts with no round trip.  A query
+that pages or limits reads the parm itself and declares
+`serverSortedByUrl: true`.  Never sort in a widget, and never send a
+placeholder row to hold a place.
+
+**Groups are templates.**  A `<template lb-group>` holds a heading and one
+nested `<template>`, the next level or the row template; the nth breaks on
+the order's nth term, to any depth.  Contents land before the nested
+template, so put it inside the heading's element for a container and beside
+the heading for a heading row.  `<tbody>` and `<optgroup>` do not nest.  The
+heading is filled from the group's first row.  `lb-count`, `lb-sum="col"`,
+`lb-avg`, `lb-min` and `lb-max` total the nearest group, or the whole list
+outside any.
+
+**Animate with CSS.**  The hub stamps `lb-row-created`, `lb-row-changed`,
+`lb-row-moved`, and `lb-row-requested` for this page's request, and marks a
+leaving row or group `lb-row-leaving` or `lb-group-leaving`, removing it once
+its animations end.  Scrolling to a row is script, in `lbRowsLanded`.
+
 **Every request has one shape.**  `lb-request` names the request, and the
 hub sends `{ name, query, key, values }` as present: `query` from the
 nearest ancestor `lb-query`, `key` from the nearest ancestor row of that
@@ -226,19 +249,16 @@ page may edit.
 
 **Return a patch when the change has a known extent.**  `patch({ rows })`
 for rows added or edited, `patch({ drop })` for keys removed, with
-`refresh: []`.  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.  List a query in `refresh` only when its membership or order
-changed in a way the handler cannot name.  Never list one only to fill the
+`refresh: []`.  A refreshed `rows` query sends every row to say what one row
+could.  List a query in `refresh` only when its membership changed in a way
+the handler cannot name.  Never list one only to fill the
 picker in a row the request adds: its answer did not change, and the hub
 fills a new row from the last one.
 
 **The usual reasons for a refresh each have 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` does
-  by `data-sort`.
+- A row whose position changes: the hub places it by the query's order.
+- A group that appears or goes: the hub makes it with its first row and
+  removes it with its last.
 - 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
@@ -247,10 +267,8 @@ fills a new row from the last one.
 An update or a delete names its row by key, and removing a row never
 reorders the rest, so each always has a patch: `createHub` refuses at
 startup a `rowUpdate` or `rowDelete` whose `refresh` names its own `rows`
-query.  An insert may refresh its own query, and should only when the new
-row's place matters and nothing places it: a patched row lands where its
-host puts it, in order under `lb-table` with `data-sort`, last in plain
-markup and in `lb-options`.
+query.  An insert may refresh its own query, though a patch of the new row
+lands in its place by the order.
 Each handler's `refresh` is its own, and every query in it needs its own
 reason.  A list shared by several handlers is a warning sign.
 
@@ -327,24 +345,24 @@ on `change`.  Any other custom element keeps its content and receives the
 column as its `lb-column-value` attribute.
 
 **A custom element connects many times.**  It is moved, never rebuilt: the
-hub places every live row again on each set of all rows, and parks an
-`lb-show` element in a template while it is off, so `connectedCallback` runs
-on every move.  Listen on the element itself in the constructor, look a
+hub moves a live row the order puts elsewhere, and parks an `lb-show`
+element in a template while it is off, so `connectedCallback` runs on every
+move.  Listen on the element itself in the constructor, look a
 child up when it is needed, and in a control take up `lb-column-value` once,
 on first connect, since a value can land before the element upgrades.
 
 **The hub and a custom element talk in four ways, one per kind of
 message.**  State the hub gives an element is an attribute stamp, or `value`
 on a control.  Work the hub needs done while landing is an optional `lb`
-method: `lbPlaceRow`, `lbRowsLanded`.  A moment is a bubbling event: an
+method: `lbRowsLanded`.  A moment is a bubbling event: an
 element sends `lb-request`, and the hub answers on the same element with
 `lb-request-done`, carrying the request and the response items that landed,
 or the error.  Listen for `lb-request-done` on whichever ancestor needs the
 outcome, such as a dialog choosing the row its form just created.
 
 **A widget that holds rows may sit under `lb-show`.**  Rows that land while
-it is away are placed by its `lbPlaceRow` once it first appears, so hide a
-table with `lb-show`, not with a stylesheet rule.
+it is away are placed by the hub, and its `lbRowsLanded` runs once it first
+appears, so hide a table with `lb-show`, not with a stylesheet rule.
 
 **Name a custom element script `<tag>.browser.ts`.**  A plain `<tag>.ts`
 stays on the server and the tag goes unregistered.
@@ -372,12 +390,13 @@ parser loses the tag before the build can report it.
 
 Reach for one only when plain HTML cannot do the job.  A set of rows, a form
 and a condition need none.  A custom element exists to be a control of its
-own, or to place and scaffold rows through the two hooks the hub calls,
-`lbPlaceRow` and `lbRowsLanded` (the `RowsHost` interface).
+own, or to act on rows once they land through the hook the hub calls,
+`lbRowsLanded` (the `RowsHost` interface).
 
 Before writing one, check `@loadbare/widgets`: `lb-input`, `lb-select`,
-`lb-options`, `lb-picker`, `lb-table`, `lb-unknown-page`.  The first four
-are form-associated controls that carry `lb-column` and `lb-request`
+`lb-options`, `lb-picker`, `lb-table`, `lb-unknown-page`, `lb-confirm`,
+`lb-form`, `lb-insert-dialog`, `lb-master`.  The first four are
+form-associated controls that carry `lb-column` and `lb-request`
 themselves.  Install the package and list it in `src/imports.ts`:
 
 ```ts