@loadbare/app 0.12.0 → 0.14.0

package/skills/loadbare-app/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: loadbare-app
-description: Build server-bound web applications with Loadbare/app. Covers the file conventions the builder finds by name (`chrome.html`, `*.page.html`, `*.queries.ts`, `*.requests.ts`, `imports.ts`, `<tag>.html`, `<tag>.browser.ts`); the `lb-*` attribute vocabulary that lands query rows on HTML and issues requests (`lb-query`, `lb-column`, `lb-show`, `lb-request`); queries declared with `row(key, run)` and `rows(key, run)`; the URL as the hub's own query `lb-url`, with `lb-url-link`, `lb-url-push` and `lb-url-unknown`; build-time expansion with `exp-*` parameters, `lb-exp-slot` and `lb-exp-template`; custom elements as form-associated controls and row hosts; the Express wiring with `hubRoutes`; and the `@loadbare/widgets` library. Use whenever a task involves `@loadbare/app`, `@loadbare/widgets`, `loadbare-app-build`, an `lb-` attribute, or a page, query, request or custom element file in a Loadbare application. The model is not React, htmx or REST, and cannot be inferred from them.
+description: Build server-bound web applications with Loadbare/app. Covers the file conventions the builder finds by name (`chrome.html`, `*.page.html`, `*.queries.ts`, `*.requests.ts`, `imports.ts`, `<tag>.html`, `<tag>.browser.ts`); the `lb-*` attribute vocabulary that lands query rows on HTML and issues requests (`lb-query`, `lb-column`, `lb-show`, `lb-request`); queries declared with `row(key, run)` and `rows(key, run)`; the URL as the hub's own query `lb-url`, with `lb-url-link`, `lb-url-push` and `lb-url-unknown`; one form pointed at a row by the `--lb-edit`, `--lb-new` and `--lb-release` commands; build-time expansion with `exp-*` parameters, `lb-exp-slot` and `lb-exp-template`; custom elements as form-associated controls and row hosts; the Express wiring with `hubRoutes`; and the `@loadbare/widgets` library. Use whenever a task involves `@loadbare/app`, `@loadbare/widgets`, `loadbare-app-build`, an `lb-` attribute, or a page, query, request or custom element file in a Loadbare application. The model is not React, htmx or REST, and cannot be inferred from them.
 license: Apache-2.0
 metadata:
   package: "@loadbare/app"
@@ -176,14 +176,42 @@ 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
+every outer row; use it for a picker, never for per-row detail.  Inside a
+form, the live rows of a query nested in the form's own are gathered as
+`rows: { <query>: [{ key, values }] }` beside `values`, so a master and a
+subtable of its details (one input per type, say) are entered in one
+submit, and the master's handler writes both.  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
+hub sends `{ name, query, key, values }` as present, with `keys` in place
+of `key` for the rows the user selected: `query` from the
 nearest ancestor `lb-query`, `key` from the nearest ancestor row of that
 query, and `values` gathered from controls by their `lb-column`.
 
@@ -201,9 +229,10 @@ with `lb-column` gathers its own value alone.  A `<form>` gathers every
 control whose form owner it is.  An element in a live row gathers that live
 row.  Anything else gathers its form owner's controls.  A `<form>` cannot
 wrap a `<tr>`, so an insert row in a table puts its controls in a form
-elsewhere with the HTML `form` attribute.  Checkboxes, radio buttons and
-file inputs are not controls here: they receive no value and are not
-gathered.
+elsewhere with the HTML `form` attribute.  A checkbox is a control: checked
+unless its column is `false` or null, and gathered as `"true"` or `"false"`.
+Radio buttons and file inputs are not controls here: they receive no value
+and are not gathered.
 
 **A form that adds to a set chosen elsewhere is written once, outside every
 row.**  A form cannot sit inside another form or in a table row, so a dialog
@@ -211,6 +240,17 @@ that creates an account while a posting's picker is choosing one goes at the
 end of the page, and each row opens it with `commandfor`.  The dialog learns
 the new key from `lb-request-done`.
 
+**A set the user edits has one form, pointed at a row.**  Never put a form
+in every row.  Write one form naming the set's query, outside every row,
+often in a `<dialog>`, and give it an `id`.  A `type="button"` with
+`commandfor="<id>"` and `command="--lb-edit"` in a live row fills it from
+that row with no round trip; `--lb-new` starts it empty for an insert;
+`--lb-release` lets it go.  The form's `lb-key-value` is the row's key, empty
+for a new row, absent when not in use, and a stylesheet shows Save or Save
+new by it.  A successful request from the form, or its dialog closing, lets
+it go.  Which row is being edited is never a query parm.  A row that must be
+fetched to be edited is another page, with that row as its master.
+
 **Three requests are Loadbare's.**  `lb-row-insert` needs `query` and
 `values`, `lb-row-update` needs `query`, `key` and `values`, and
 `lb-row-delete` needs `query` and `key`.  The page permits each under
@@ -219,6 +259,32 @@ Each works on a `row` query as well as a `rows` query, since the element a
 `row` lands on carries its key.  Every other request name is a declared
 request, under `handlers`.  Anything undeclared is refused.
 
+**An empty key is a row not yet entered.**  A `row` query answering with an
+empty key, or a form `--lb-new` pointed, carries `lb-key-value=""`.  The hub
+sends inserts and declared requests from it with no `key`, and sends no
+update or delete at all, silently.  So a control with
+`lb-request="lb-row-update"` saves on a row on record and only holds its
+value on a new one.  Never write script to stop such an update.
+
+**Select rows with `lb-select`, never with a column.**  An
+`<input type="checkbox" lb-select>` in a row template selects its row; the
+hub stamps `lb-row-selected`.  A request for that query naming no one row,
+such as a form outside the rows, carries the ticked rows as `keys`.
+`rowUpdate` and `rowDelete` then run once per key with no new code; a
+declared request gets `keys` itself.  With none ticked an update or delete
+is not sent.  Success clears the selection, and so does `lb-show` hiding a
+selector.  A selecting mode kept in the URL reaches the rows as a column the
+query computes from the parm.
+
+**Refuse with `refusal()`, never with a plain throw.**  `throw
+refusal("message")`, `throw refusal({ column: "message" })` or both, from
+`@loadbare/app/server`.  The whole-request message lands as the
+`lb-request-refused` stamp on the element that committed, shown by CSS
+`attr()`; each column's message goes on its control by
+`setCustomValidity`, and the first is reported.  Editing anything the
+request gathered withdraws it all.  Any other throw is a failure with no
+message, so a database error never reaches the page.
+
 **Write `rowUpdate` as a partial update.**  A form sends every control it
 owns; a single control sends its one column.  Set the columns `values`
 names, leave the rest alone, and check the names against the columns the
@@ -226,19 +292,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 +310,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 +388,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 +433,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`, `lb-checkbox`.  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