@loadbare/app 0.13.0 → 0.15.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"
@@ -178,7 +178,11 @@ from it.
 query under two names.  Many masters with their details is one `rows` query
 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.
 
@@ -206,7 +210,8 @@ 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`.
 
@@ -224,15 +229,27 @@ 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
 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`.
+the new key in `lbRequestDone`.
+
+**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
@@ -242,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
@@ -344,25 +387,29 @@ element (`static formAssociated = true`) with a `value` property that fires
 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 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.
+**A custom element hears the hub's lifecycle, never the browser's.**  The
+hub calls `lbAttached()` once when it places the element, already filled,
+and `lbDetached()` once when it removes it.  Moving a row and turning
+`lb-show` off and on call neither, and the instance is kept.  Never write
+`connectedCallback`, `disconnectedCallback`, `adoptedCallback` or
+`connectedMoveCallback`; the build refuses them.  Listen on the element
+itself in the constructor, look a child up when it is needed, and put
+once-per-instance setup in `lbAttached` with its undoing in `lbDetached`.
 
 **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: `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.
+on a control.  What the hub did to an element is an optional `lb` method:
+`lbAttached`, `lbRowsLanded`, `lbRequestDone`, `lbDetached`, declared by
+`HubLifecycle`.  A moment is a bubbling event: an element sends
+`lb-request`, and the hub answers by calling `lbRequestDone(detail,
+origin)` on the custom elements from the committing element outward, then
+dispatching `lb-request-done` from it, each carrying the request and the
+response items that landed, or the error.  A dialog choosing the row its
+form just created implements `lbRequestDone`.
 
 **A widget that holds rows may sit under `lb-show`.**  Rows that land while
-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.
+it is away are placed by the hub and its `lbRowsLanded` runs, 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.
@@ -391,11 +438,11 @@ 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 act on rows once they land through the hook the hub calls,
-`lbRowsLanded` (the `RowsHost` interface).
+`lbRowsLanded` (the `HubLifecycle` interface).
 
 Before writing one, check `@loadbare/widgets`: `lb-input`, `lb-select`,
 `lb-options`, `lb-picker`, `lb-table`, `lb-unknown-page`, `lb-confirm`,
-`lb-form`, `lb-insert-dialog`, `lb-master`.  The first four are
+`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`: