@loadbare/app 0.9.0 → 0.11.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 binds HTML to server data and sends requests (`lb-list`, `lb-row`, `lb-cell`, `lb-key`, `lb-show`, `lb-action`); query parms in the URL with `lb-query-parm`; build-time widget expansion with `exp-*` parameters, `lb-slot` and `lb-template`; custom element code; 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 widget 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`; 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"
@@ -11,17 +11,19 @@ metadata:
 
 Loadbare/app builds a whole application into one HTML document, one client
 script and one stylesheet.  The server answers named queries with rows and
-performs named requests; the browser lands those rows on elements that name
-them.  No component renders anything, and no page fetches anything.
+runs named requests; the hub in the browser lands those rows on the elements
+that name them.  No component renders anything, and no page fetches
+anything.
 
-The wire is relational.  A name answers with one row or a set of rows, a
-row holds cells, and a cell holds one value.  Hold on to that: most wrong
-designs come from sending a shape a relational answer cannot have.
+Everything is a query.  A query is a name for rows, of kind `row` or `rows`,
+with a key column.  A row holds columns, and a column holds one value.  The
+URL itself is a query, `lb-url`, that the hub serves.  Hold on to that: most
+wrong designs come from sending a shape a relational answer cannot have.
 
 ## Build every change before handing it over
 
-`loadbare-app-build` is the checker.  It expands every page and widget and
-refuses what it cannot ship, naming the tag and the file:
+`loadbare-app-build` is the checker.  It expands every page and custom
+element and refuses what it cannot ship, naming the tag and the file:
 
 ```bash
 loadbare-app-build --src src --out dist
@@ -40,9 +42,9 @@ tsc --noEmit
 `dist/pages.ts` imports page files with their `.ts` extensions, so the
 application's `tsconfig.json` needs `allowImportingTsExtensions`.
 
-**Write, build, fix, repeat until it is clean.**  Then start the server:
-`createHub` refuses a query that answers with the wrong shape and a page
-that declares a reserved name, and those refusals only appear at run time.
+Write, build, fix, and repeat until the build is clean.  Then start the
+server: `createHub` refuses a page that declares a reserved name at startup,
+and the server console reports a query that answers with the wrong kind.
 Restart the server after adding or changing a `.queries.ts` or
 `.requests.ts` file.
 
@@ -58,9 +60,9 @@ src/
   pages/
     index.page.html        the page for /
     members.page.html      the page for /members
-    members.queries.ts     what members displays
-    members.requests.ts    what members may be asked to do
-  widgets/
+    members.queries.ts     the queries members shows
+    members.requests.ts    the requests members answers
+  elements/
     note-card.html         the markup <note-card> expands into
     visit-count.browser.ts the class <visit-count> registers
 server.ts
@@ -74,18 +76,22 @@ A page is an HTML fragment that lands in `<main>`:
 
 ```html
 <!-- src/pages/members.page.html -->
-<p lb-row="dues">Collected this year: <span lb-cell="total"></span></p>
+<title>Members</title>
+<h1>Members</h1>
 
-<section lb-list="roster">
-  <form lb-action="lb-row-insert">
-    <input lb-cell="name" />
-    <button type="submit">Add</button>
+<p lb-query="dues">Dues collected this year: <span lb-column="total"></span></p>
+
+<section lb-query="roster">
+  <form lb-request="lb-row-insert">
+    <input lb-column="name" placeholder="Name" />
+    <button type="submit">Add member</button>
   </form>
+
   <ul>
-    <template lb-key="id">
+    <template>
       <li>
-        <span lb-cell="name"></span>
-        <button lb-action="lb-row-delete">Remove</button>
+        <input lb-column="name" lb-request="lb-row-update" />
+        <button lb-request="lb-row-delete">Remove</button>
       </li>
     </template>
   </ul>
@@ -94,11 +100,11 @@ A page is an HTML fragment that lands in `<main>`:
 
 ```ts
 // src/pages/members.queries.ts
-import { list, row, type Queries } from "@loadbare/app/server";
+import { row, rows, type Queries } from "@loadbare/app/server";
 
 export const queries: Queries = {
-  dues: row((ctx) => ctx.db.duesTotal()),
-  roster: list((ctx) => ctx.db.members()),
+  dues: row("year", (ctx) => ctx.db.duesTotal()),
+  roster: rows("id", (ctx) => ctx.db.members()),
 };
 ```
 
@@ -115,6 +121,12 @@ export const requests: Requests = {
         }),
         refresh: ["dues"],
       },
+      rowUpdate: {
+        run: async (ctx, { key, values }) => ({
+          roster: patch({ rows: [await ctx.db.updateMember(key, values)] }),
+        }),
+        refresh: [],
+      },
       rowDelete: {
         run: async (ctx, { key }) => {
           await ctx.db.removeMember(key);
@@ -133,122 +145,186 @@ Re-read this list when a build fails or a design will not fit.  Each item is
 a place a reasonable instinct from React, Vue, htmx or REST produces an
 error or a dead end.
 
+**The server declares every query's kind and key.**  Declare each query with
+`row(key, run)` or `rows(key, run)`, key column first.  The markup names the
+query with `lb-query` and the columns it shows with `lb-column`, and repeats
+neither the kind nor the key.  A page that needs the same data as one row
+and as a set declares two queries.  Every query has a key; an aggregate row
+answers with a constant one.
+
 **There is no template language.**  No `{#if}`, no `v-for`, no `map()`.  A
-list is an element carrying `lb-list` with a `<template lb-key="...">`
-inside it, and the hub clones the template once per row.  A condition is
-`lb-show="<column>"`: write every possibility into the page and let a column
-decide which is present.  The column must be a boolean or null; the string
-`"false"` counts as present.
+set of rows is an element carrying `lb-query` with a `<template>` inside it,
+the row template, which the hub clones once per row.  A `row` query with no
+row template lands on the element itself.  A `rows` query with no row
+template lands nothing, which is what an insert form naming its query is.  A
+condition is `lb-show="<column>"`: write every possibility into the page and
+let a column decide which is present.  The column is a boolean or null; the
+string `"false"` counts as present.
 
 **`{{placeholder}}` is build time only.**  It reads an `exp-` attribute on
 the tag, never data.  Write it as an entire attribute value or an entire
 text node.  Name parameters in lowercase with hyphens: HTML lowercases
 `exp-inputClass` before expansion sees it.
 
-**Scope comes from ancestry, not props.**  An `lb-cell` binds to the row on
-its nearest ancestor carrying `lb-row` or a live list row.  An element
-outside every scope displays nothing.  A value of `lb-cell` is a column name.
+**Position comes from ancestry, not props.**  `lb-column` and `lb-show` read
+from the nearest ancestor row: a live row, or an element a `row` query
+landed on.  A nested `lb-query` begins a new query.  An element with
+`lb-column` and no ancestor row receives nothing, and the hub still gathers
+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
+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.
+
+**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
+query, and `values` gathered from controls by their `lb-column`.
+
+**An element commits on its own event.**  A form on `submit`, a control on
+`change`, anything else on `click`.  A click on interactive content inside
+the element (a link, a button, a control, a label) belongs to that content
+and commits nothing.  A submit button never commits on click;
+on submit, the submitter's `lb-request` wins over the form's.  A native
+`<input lb-column="name" lb-request="lb-row-update">` saves that one column
+on `change`.  Inside a form, leave `lb-request` off the controls and put it
+on the form.
+
+**Gathering follows the form, the live row, or the form owner.**  An element
+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.
+
+**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
+`crud`, keyed by query name, as `rowInsert`, `rowUpdate` and `rowDelete`.
+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.
+
+**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
+page may edit.
 
-**One name, one cardinality.**  Declare every query with `row()` or
-`list()`.  A page that needs the same data as a row and as a set declares
-two queries.
+**Return a patch when the change has a known extent.**  `patch({ rows })`
+for rows added or edited, `patch({ drop })` for keys removed, with
+`refresh: []`.  List a query in `refresh` only when its membership or order
+changed in a way the handler cannot name.
 
-**A cell never holds rows.**  Master-detail is a row and a list under two
-names.  Many masters with their details is one list of joined rows, grouped
-for display by a widget's `lbPlaceRow`.  A list nested inside another list's
-rows receives the same rows in every outer row; use it for a picker, never
-for per-row detail.
+**A page's queries are its view model, not a data layer.**  Each answers
+one page's elements in the form they show: formatted dates and amounts, and
+the words a reader sees, such as "12 postings".  The hub does no type
+conversion, so what a number, date or null looks like is decided on the
+server.  A value the page reads back stays data: a column on a control, the
+key, an `lb-show` condition, a value a stylesheet selects on.  What pages
+share goes beneath them, in a database view or a helper module, never in a
+layer between the page and its queries.
 
 **A URL's path names a page, never a resource.**  Do not design
-`/accounts/42`.  A row is addressed by `list` and `key`, taken from where the
-element sits.
+`/accounts/42`.  A row is addressed by `query` and `key`, taken from where
+the element sits.
 
 **The query string is what the page has on screen.**  Which record a page
 shows, a filter, a date range: each is a query parm,
 `/accounts?acct=23&from=2026-09-09`, so a reload, a bookmark or a mailed link
-shows the same thing.  A control writes one with `lb-query-parm="acct"`, which
-replaces the history entry, reloads the page at the new URL, and sends no
-request.  A link writes several with an ordinary `lb-nav-link` href.  Queries
-still take no arguments: `contextFor(req, parms)` puts parms onto `ctx`, and
-a query reads them there.  Read them from `parms`, never `req.query`, because
-`contextFor` may be called twice for one request.  A parm is user input, so
-validate it where you read it.  Do not keep a selection in server state set
-by an action; that forces `refresh: []` and a hand-written re-answer of
-everything the selection touches.
-
-**When a server response changes the query parms.**  After an insert, only
-the server knows the new key.  After a delete, only the server knows the parm
-should go.  Have `run` return `queryParms({ acct: String(id) })`, or
-`queryParms({ acct: "" })` to remove the parm.  The page loads at the new
-query string in the same round trip, and the history entry is replaced to
-match.  This is Post/Redirect/Get without the redirect: the path never
-changes, and there is no second request.  Do not reach for a redirect, a
-hand-written refresh of every query, or server state holding the selection.
-See [refresh and patch](references/page-files.md#refresh-and-patch).
+shows the same thing.  The hub serves the query `lb-url`, of kind `row`,
+keyed by `lb-path`, with `lb-page-label`, `lb-page-unknown`, and one column
+per query parm.  A control inside `lb-query="lb-url"` carrying
+`lb-request="lb-row-update"` writes its parm; the hub replaces the history
+entry, or pushes one when the control carries `lb-url-push`, and reloads the
+page's queries with no request to the server.  An `<a lb-url-link>` moves
+to its `href`.  Queries still take no arguments: `contextFor(req, parms)`
+puts parms onto `ctx`, and a query reads them there.  Read them from
+`parms`, never `req.query`, because `contextFor` may be called twice for one
+request.  A parm is user input, so validate it where it is read.  Do not
+keep a selection in server state set by a handler.
+
+**A handler moves the URL with `url()`.**  After an insert, only the server
+knows the new key; after a delete, only the server knows the parm should
+go.  Have `run` return `url({ acct: String(id) })`, or `url({ acct: "" })`
+to remove the parm, or `url({ "lb-path": "/accounts", acct: "5" })` to
+enter another page with only the parms named.  The page loads at the new URL
+in the same round trip.  This is Post/Redirect/Get without the redirect.  See
+[moving the URL](references/page-files.md#moving-the-url).
+
+**A page names itself with `<title>`.**  The builder lifts a page file's
+`<title>` and the hub shows it as `lb-page-label` and as the document title.
+A page without one is labeled by its stub.
 
 **Loadbare is for applications, not sites.**  Every route is answered with
 `app.html`, and a path that names no page is found in the browser, not
-answered with a 404.  That is the design, not a defect to report.
+answered with a 404.  The hub opens a `<dialog lb-url-unknown
+lb-query="lb-url">` in the chrome for it.
 
 **There are no endpoints to write.**  `hubRoutes(hub, contextFor)` is the
-whole data channel.  Declare every action under `actions` and every
-permitted operation under `crud`; anything undeclared is refused.
-
-**All three CRUD operations are list operations.**  Each needs a key, and a
-key exists only on a live row inside `lb-list`.  An `lb-row` scope is
-read-only; give a writable single row a list that answers with one row.
-
-**Write `rowUpdate` as a partial update.**  A form sends every cell it
-holds; a widget carrying `lb-cell` and `lb-action="lb-row-update"` sends its
-one cell.  Set the columns `values` names, leave the rest alone, and check
-the names against the columns the page may edit.
-
-**Put `lb-row-insert` and `lb-row-update` on a `<form>` or a button.**  The
-hub gathers the nearest `<form>`, `<tr>` or live row.  Cells in a bare
-`<div>` belong to no row and the request is refused.  A native `<input>`
-carrying `lb-row-update` is refused; commit one cell with a widget such as
-`<lb-input>`.  Inside a form, leave `lb-action` off the widgets.
-
-**Return a patch when the change has a known extent.**  `patch({ rows })`
-for rows added or edited, `patch({ drop })` for keys removed, with
-`refresh: []`.  List a query in `refresh` only when its membership or order
-changed in a way the operation cannot name.
-
-**Format values in the query.**  The hub does no type conversion.  What a
-number, date or null looks like is decided on the server.
-
-**Checkboxes, radio buttons and file inputs are not bound.**  They receive
-no value and are not gathered.  This is an open item, not a mistake in the
-page.
-
-**`lb-` belongs to Loadbare.**  Invent no `lb-` attribute, and name no
-query or action with the prefix.  Import attribute names in widget code from
-`@loadbare/app/constants`; never write them as string literals.
-
-**Name a widget script `<tag>.browser.ts`.**  A plain `<tag>.ts` stays on
-the server and the tag goes unregistered.
-
-**Light DOM, global CSS.**  No shadow root, no scoping.  Style empty lists
-with `[lb-row-count="0"]`, pending requests with `[lb-pending]`, and failed
-ones with `[lb-error]`.
+whole data channel.
+
+**The developer writes `lb-*` attributes in markup, and script never
+assigns them.**  The builder refuses any `lb-` attribute other than
+`lb-query`, `lb-column`, `lb-show`, `lb-request`, `lb-url-link`,
+`lb-url-push` and `lb-url-unknown`.  Everything else with the prefix is a
+stamp the hub or the builder writes.
+
+**`lb-` belongs to Loadbare.**  The application should never name anything
+with the `lb-` prefix anywhere: no attribute, query, column, request, custom
+element, event, or custom element method beginning `lb`.  Import attribute
+names in custom element code from `@loadbare/app/constants`; never write
+them as string literals.
+
+**A custom element takes part as a control.**  A form-associated custom
+element (`static formAssociated = true`) with a `value` property that fires
+`change` is a control: the hub sets its `value`, gathers it, and commits it
+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
+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.
+
+**Name a custom element script `<tag>.browser.ts`.**  A plain `<tag>.ts`
+stays on the server and the tag goes unregistered.
+
+**Light DOM, global CSS.**  No shadow root, no scoping.  Style an empty
+query with `[lb-query-row-count="0"]`, a request in flight with
+`[lb-request-pending]`, a failed one with `[lb-request-error]`, and a value
+with `[lb-column-value="overdue"]`.
 
 **Host at the origin root.**  The hub reaches its route by absolute path, so
 a subpath such as `example.com/myapp/` does not work.
 
-## Widgets
+## Custom elements
+
+A custom element is `<tag>.html`, `<tag>.browser.ts`, or both, and a tag
+with neither is a build error.  The HTML is expanded at build time into the
+tag's children; the class is an ordinary custom element with no base class.
 
-A widget is `<tag>.html`, `<tag>.browser.ts`, or both, and a tag with
-neither is a build error.  The HTML is expanded at build time into the tag's
-children; the class is an ordinary custom element with no base class.
+Place a custom element where HTML allows what its definition holds.  One
+whose definition has a `<div>` or a `<dialog>` cannot sit inside a `<p>`, and
+the build refuses it; see
+[Where a custom element can go](references/custom-elements.md#where-a-custom-element-can-go).
+Never write one inside `<select>`, `<option>` or `<textarea>`, where the
+parser loses the tag before the build can report it.
 
-Reach for a widget only when plain HTML cannot do the job.  A list, a form
-and a condition need none.  A widget exists to wrap a control that decides
-its own moment to send (`<lb-input>` on `change`), or to place and scaffold
-rows (`lbPlaceRow`, `lbRowsLanded`).
+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).
 
 Before writing one, check `@loadbare/widgets`: `lb-input`, `lb-select`,
-`lb-options`, `lb-table`, `lb-picker`, `lb-unknown-page`.  Install it and
-list it in `src/imports.ts`:
+`lb-options`, `lb-picker`, `lb-table`, `lb-unknown-page`.  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
 export default ["@loadbare/widgets"];
@@ -263,15 +339,17 @@ with the package, so no network is needed.
 
 - [`references/overview.md`](references/overview.md) — the map of the
   reference, by part of the application.
-- [`references/data-binding.md`](references/data-binding.md) — every `lb-`
-  attribute, requests, forms, query parms, conditions and request state.
-  Start here for anything in a page.
-- [`references/page-files.md`](references/page-files.md) — queries,
-  `onPageEnter`, actions, CRUD, refresh and patch.
+- [`references/data-binding.md`](references/data-binding.md) — landing,
+  gathering, requests, conditions and request state.  Start here for
+  anything in a page.
+- [`references/page-files.md`](references/page-files.md) — what page
+  files are, queries, `onPageEnter`, handlers, `crud`, refresh and patch,
+  and `url()`.
 - [`references/custom-elements.md`](references/custom-elements.md) —
-  expansion, parameters, slots, destinations, and widget code.
-- [`references/chrome.md`](references/chrome.md) — the chrome,
-  navigation and `lb-navigation`.
+  expansion, parameters, slots, destinations, and custom element code and
+  when it runs.
+- [`references/chrome.md`](references/chrome.md) — the chrome, and the URL
+  as the query `lb-url`.
 - [`references/server.md`](references/server.md) — the Express server and
   the request context.
 - [`references/builder.md`](references/builder.md) — the builder's options,
@@ -282,5 +360,5 @@ with the package, so no network is needed.
 - [`references/TECHREF-1.0.md`](references/TECHREF-1.0.md) — the reserved
   names, what a URL names and
   [query parms](references/TECHREF-1.0.md#query-parms), and the open items
-  that block 1.0.  Read it before designing around
-  something the other references do not mention.
+  that block 1.0.  Read it before designing around something the other
+  references do not mention.