@loadbare/app 0.4.0 → 0.5.1

package/docs/guide.md

@@ -1,1164 +0,0 @@
-# Programmer's Guide
-
-Loadbare App is a web application framework for data-driven applications.  
-
-Loadbare App's "Axiom zero" is that both users and developers are best served
-when static host code displays and allows user interactions with 
-fixed-schema data.  
-
-Most frameworks assume that the entire DOM is subject to change, and they
-carry considerable plumbing to chase down the implications of that assumption.
-Loadbare App assumes only data values change.  When the data populates a SELECT,
-TABLE, or some type of tree, there are necessary DOM changes, but they fit
-within the model of a fixed static application, the application author does
-not need to think about how the DOM changes happen.
-
----
-
-## The Counter App But Server Persisted
-
-Loadbare App assumes the critical path is server state.  Here we will show the
-universal example of a counter (two counters actually) where the value is
-persisted on the server. 
-
-This section shows the files that make a page: the host, its
-queries, its hooks, and the service they call. That is the whole of what you
-write per page.  
-
-### The host: `demo/pages/hello.html`
-
-The host declares the structure of the page and declares which elements
-dynamically display data.  Whenever a request is made to the server, the
-response contains data updates.  The hub matches the returned data
-to the declarations and updates whatever matches.  
-
-A complete Loadbare App page includes named queries that retrieve data.  In this
-example there are two queries, each of which returns a tuple with one
-keyed value:
-
-
-```html
-<h2>Hello, World!</h2>
-
-<div lb-query="pageStats">
-  <p>
-    This page has been visited
-    <span lb-cell="visit_count"></span> times!
-  </p>
-</div>
-
-<p>Reload, or navigate away and back, to increase the count.</p>
-
-<div lb-query="counter">
-  <p>Button count: <span lb-cell="count"></span></p>
-  <button lb-action="increment">+1</button>
-</div>
-```
-
-`lb-query` marks the region that displays one query.  All DOM nodes 
-within the subtree are scoped to that query.  The `lb-cell` attribute marks
-the leaf that displays a single keyed value.
-
-In this demo, both queries return a plain object with one value, and both
-displays are simple text.  When `lb-cell` is on an ordinary element, Loadbare App
-assigns the value to the element's `textContent` property.
-
-The attribute `lb-action` names something the page declares it can do on the server.
-The hub turns the
-click into a request and sends it. In this case there are no parameters
-for the task, so the button carries no additional attributes.
-
-### The request context in `demo/services.ts:19`
-
-Server code consists of hooks and queries, which we will see shortly.
-Each of those is an asynchronous routine that takes a context, `ctx` as
-it only argument.  Loadbare App declares it as an empty interface: 
-
-
-```ts
-export interface HubContext {}
-```
-
-The application expands it using `declare module`.  In the demo this code
-is in `demo/services.ts`, and declares that the demo pages will recieve an
-object providing database access.  The internals of that object are not
-discussed here, they can be found in `demo/services.ts`.
-
-```ts
-declare module "@loadbare/app/server" {
-  interface HubContext {
-    db: Db;
-  }
-}
-```
-
-### The queries: `pages/hello.queries.ts`
-
-A query is a named asynchronous routine that calls out to the
-application data store and returns results that can be displayed
-in the host HTML.  Here are the two queries we declared in `pages/hello.html`.
-
-```ts
-import type { Queries } from "@loadbare/app/server";
-
-export const queries: Queries = {
-  pageStats: async (ctx) => ({
-    visit_count: String(await ctx.db.visitCount()),
-  }),
-  counter: async (ctx) => ({ count: String(await ctx.db.buttonCount()) }),
-};
-```
-
-The query namespace is local to the page, so query names must be unique within
-a page but need not be unique across pages. The file is named for its page, so
-nothing declares which page runs it.
-
-### The hooks and actions: `pages/hello.hooks.ts`
-
-When the app loads a page, a request is sent to the server to run all 
-queries and return the results.  The `beforeGet` hook fires before
-the queries run.  In this case the `recordVisit()` implementation increases
-the count by one.
-
-```ts
-import type { Hooks } from "@loadbare/app/server";
-
-export const hooks: Hooks = {
-  beforeGet: (ctx) => ctx.db.recordVisit(),
-  actions: {
-    increment: {
-      run: (ctx) => ctx.db.raiseButtonCount(),
-      refresh: ["counter"],
-    },
-  },
-};
-```
-
-The actions are declared with the hooks.  In our host HTML we declared that
-a button had `lb-action` named 'increment', so we must provide an implementation
-of action 'increment'.  The action names a routine to run, and which queries
-should be refreshed afterward.
-
-### Serving it
-
-Those are all the files the page needed. Naming the page in a registry,
-assembling the document that carries it, and answering the two endpoints are
-done once for an application rather than once per page, so they are in
-[Hosting a Loadbare App Application](./hosting.md). The demo does them in
-`demo/pages.ts` and `demo/server.ts`.
-
-### Run it
-
-```
-npm run dev
-```
-
-Open `http://localhost:8787/hello`. The visit count rises on every load and
-on every navigation back to the page. The button raises its own count and
-leaves the visit count alone.
-
----
-
-
-## Widgets
-
-A widget is the basic composable unit of the UI.  A widget is an HTML
-file and a Typescript containing the class.
-
-A page author writes a widget's tag, and the attributes written on that tag
-control how the definition expands.  Expansion happens at compile time.  It
-is a build operation, not a runtime one: it runs once, before any request
-exists, and what it produces is permanent.  The expanded markup ships to the
-browser and never changes there.
-
-### Simple Example
-
-A widget is two files with the same basename, in the same directory.  The tag
-name is the filename.  Here is `lb-input`, which ships with the framework
-and wraps a labeled `<input>`.
-
-The definition, `widgets/lb-input.html`, is markup that will go inside of
-the custom element. 
-
-```html
-<label>{{label}} <input readonly="{{readonly}}" /></label>
-```
-
-A name in double braces is a placeholder.  It stands for a parameter the page
-author supplies on the tag, and it may occupy an entire attribute value or an
-entire text node.  
-
-The element, `widgets/lb-input.ts`, is the class that gives the definition
-behavior:
-
-```ts
-import { ATTR_VALUE } from "@loadbare/app/constants";
-
-class LbInput extends HTMLElement {
-  static observedAttributes = [ATTR_VALUE];
-
-  attributeChangedCallback(_name: string, _old: string, value: string) {
-    this.querySelector("input")!.value = value;
-  }
-}
-
-customElements.define("lb-input", LbInput);
-```
-
-When the hub receives a data payload from the server, and finds a
-match on `lb-query` and `lb-cell`, it updates the attribute value
-`lb-value`. The widget's job is to forward that value to whatever
-control it owns.  Here the `<input>` is not checked for before it is used,
-because the definition beside this file is what places it.  
-
-A page author writes the tag, as `demo/pages/entity.html` does, supplying each
-parameter as an `exp-` attribute:
-
-```html
-<lb-input lb-cell="name" exp-label="Name" exp-readonly></lb-input>
-```
-
-In Loadbare App terms, we say the `<lb-input>` is "expanded" at build time,
-resulting in the following HTML going out to the page:
-
-```html
-<lb-input lb-cell="name" exp-label="Name" exp-readonly=""><label>Name <input readonly=""></label></lb-input>
-```
-
-The tag survives expansion exactly as written, and the definition became its
-children.  So the shipped page shows what was asked for beside what it
-produced, and the class can find its `<input>` with an ordinary
-`querySelector`.
-
-Three namespaces share the tag, and each has one owner.  `lb-` belongs to the
-hub, which is how it addresses this widget at run time.  `exp-` belongs to
-expansion, and is gone by the time the browser matters.  Everything unprefixed
-belongs to HTML and means exactly what HTML says it means, so `class`,
-`title`, `hidden` and their kind can be written on any widget, whatever that
-widget's parameters happen to be called.
-
-Marking the parameters buys an error message.  A definition declares which
-ones it has, so `exp-labl` is a name that resolves to nothing, and the build
-says so rather than shipping a blank label:
-
-```
-expand: <lb-input> was given exp-labl, but its definition has no {{labl}}.
-```
-
-The reverse is not an error, because it is how an optional parameter works.
-Written without `exp-readonly`, the placeholder has nothing behind it and the
-attribute is dropped rather than emitted empty, which is HTML's own rule for
-boolean attributes:
-
-```html
-<lb-input lb-cell="name" exp-label="Name"></lb-input>
-<!-- ships as -->
-<lb-input lb-cell="name" exp-label="Name"><label>Name <input></label></lb-input>
-```
-
-Because expansion runs before any request exists, it has no data to branch on,
-and definitions have no control flow.  If you find yourself wanting a
-conditional in a definition, something data-shaped has leaked into the static
-half; find the leak.
-
-### Slots and Children
-
-A parameter carries a word.  Some widgets need to be given markup instead —
-the options of a select, the cells of a row, the contents of a panel.  A
-widget that accepts markup marks one element in its definition with
-`lb-slot`, and whatever the page author writes inside the tag becomes that
-element's children.
-
-`lb-select` is the case.  Its definition, `widgets/lb-select.html`,
-supplies the label and the control and says where the choices go:
-
-```html
-<label
-  >{{label}}
-  <select lb-slot></select
-></label>
-```
-
-The page author writes them, as `demo/pages/entity.html` does:
-
-```html
-<lb-select lb-cell="id" lb-action="selectEntity" exp-label="Show:">
-  <option value="e1">Ada</option>
-  <option value="e2">Grace</option>
-  <option value="e3">Alan</option>
-</lb-select>
-```
-
-And the two are joined at build time.  The definition became the tag's
-children, and the authored content landed inside the `<select>`, which no
-longer carries the marker:
-
-```html
-<lb-select lb-cell="id" lb-action="selectEntity" exp-label="Show:"><label>Show:
-  <select>
-    <option value="e1">Ada</option>
-    <option value="e2">Grace</option>
-    <option value="e3">Alan</option>
-  </select></label></lb-select>
-```
-
-The content moves rather than copies, so each option appears once, in the
-place the definition chose for it.
-
-The slot is an attribute rather than an element because of where slots are
-needed.  HTML's content models discard foreign elements inside `<select>` and
-`<table>`, so a `<lb-slot>` tag written in either would be dropped by the
-parser before expansion ever saw it.  An attribute rides on an element the
-content model already accepts.
-
-A definition may mark at most one element.  Two is an error, because nothing
-would say which one the content meant:
-
-```
-expand: <lb-panel> declares more than one lb-slot
-```
-
-Writing content inside a widget whose definition has no slot is also an error,
-rather than content silently vanishing:
-
-```
-expand: content was written inside <lb-input>, whose definition has no lb-slot
-```
-
-A definition with a slot that nobody fills is not an error.  The slot element
-ships empty, exactly as an unsupplied parameter ships nothing.
-
-Two things follow from the order the build works in.  Placeholders are
-substituted into the definition before the slot is filled, so `{{label}}`
-written in authored content is literal text, not a parameter — parameters
-belong to the tag, content belongs to the page.  Expansion then descends into
-what it just produced, so a widget written inside another widget's slot is
-expanded in place.
-
-Children are static, like everything else in the host.  The three options
-above are the three options the application has; they are not a list that came
-from a query.  The value that arrives from the server is the one that gets
-selected, not the set that gets offered.  Choices that come from data are list
-processing, below.
-
-### Markup the Parser Would Drop
-
-A slot receives what the author wrote inside the tag.  Some of what an author
-needs to write cannot get there, and the obstacle is the parser rather than the
-slot.
-
-A `<thead>` written inside `<lb-table>` is not inside a table.  The
-tokenizer has nowhere to put the tag, so it drops it and keeps the text:
-
-```html
-<lb-table><thead><tr><th>Name</th></tr></thead></lb-table>
-<!-- is parsed as -->
-<lb-table>Name</lb-table>
-```
-
-That is the same fact as the one that keeps a custom element out of `<tbody>`,
-seen from the other side.  Table markup and a custom element cannot be written
-adjacent, in either order.
-
-A `<template>` survives anywhere, and its contents are parsed as though they
-were already in the place they describe, so the wrapper is what gets the markup
-through intact.  The author names a destination on it, and the definition marks
-the destination by the same name:
-
-```html
-<!-- widgets/lb-table.html -->
-<table>
-  <caption>{{caption}}</caption>
-  <thead lb-template="head"></thead>
-  <tbody lb-slot></tbody>
-  <tfoot lb-template="foot"></tfoot>
-</table>
-```
-
-```html
-<!-- demo/pages/staff.html -->
-<lb-table lb-query="staff" exp-caption="Everyone, by team">
-  <template lb-template="head">
-    <tr><th>Name</th><th>Role</th><th></th></tr>
-  </template>
-
-  <template lb-key="id" lb-group="team" lb-sort="name">
-    <tr>…</tr>
-  </template>
-</lb-table>
-```
-
-`lb-template` is one name in two positions, like `lb-key`: in a definition it
-marks a destination, on an authored `<template>` it names the destination that
-template is for.  It is never ambiguous, because a destination is not a
-template.
-
-The destination is filled with the template's contents rather than with the
-template, so the wrapper is gone by the time anything ships and what the browser
-holds is an ordinary `<thead>` with ordinary rows in it:
-
-```html
-<lb-table lb-query="staff" exp-caption="Everyone, by team"><table>
-  <caption>Everyone, by team</caption>
-  <thead><tr><th>Name</th><th>Role</th><th></th></tr></thead>
-  <tbody><template lb-key="id" lb-group="team" lb-sort="name">…</template></tbody>
-  <tfoot></tfoot>
-</table></lb-table>
-```
-
-The `<tfoot>` is empty because this page named no template for it.  A
-destination nobody fills is an empty element rather than an absent one, which
-is the same rule presence propagation follows for an attribute: what the
-definition declares, the definition emits.
-
-Named templates are taken first and the slot gets what is left, which is why
-the row template above needs no name — it is content, and content goes where
-content goes.  Whitespace between named templates is not content, so a widget
-with destinations and no slot is not accused of having been given any.
-
-A definition may declare several destinations, and only one slot.  They are
-counted differently because the reason for each is different.  One slot is a
-statement that a widget has one place for what an author writes.  Destinations
-exist to carry markup past the parser, and how many are needed is a question
-about the parser: a table has a head, a body and a foot, and each needs its own
-way through.
-
-Both directions of a mismatch are build errors, and a name is matched exactly
-rather than approximately:
-
-```
-expand: a <template lb-template="footer"> was written inside <lb-table>, whose definition has no destination by that name.
-```
-
-The name may be empty, which is a name.  A widget with one destination costs the
-author nothing but the attribute.
-
-### Conditional Rendering With Visibility Flags and CSS
-
-A framework that mutates the DOM needs a conditional, and gets one cheaply.  If
-the tree is a function of the data, an `if` in the template is the natural way
-to say that a panel is absent.  Loadbare App hydrates attributes and text and does
-nothing else, so there is no operation here that could make an element exist,
-and no place to put the `if` even if there were.
-
-What replaces it is stated in [data-binding.md](../docs-llm-slop/data-binding.md): visibility
-is the boolean case, cells are the general one.  Everything ships.  A value
-decides what is showing, never what is there.  So the section that would be
-about conditionals in another framework is, here, three examples and one line
-of framework code.
-
-#### Tabs
-
-`demo/pages/tabs.html` ships all three panels, with two of them carrying
-`hidden`, which is HTML's own visibility flag and needs nothing from us.  The
-widget is addressed like any leaf:
-
-```html
-<lb-tabs lb-query="prefs" lb-cell="active_tab" lb-action="selectTab">
-  <template lb-template="strip">
-    <button data-tab="summary" aria-selected="true">Summary</button>
-    <button data-tab="detail">Detail</button>
-    <button data-tab="history">History</button>
-  </template>
-
-  <section data-panel="summary">…</section>
-  <section data-panel="detail" hidden>…</section>
-  <section data-panel="history" hidden>…</section>
-</lb-tabs>
-```
-
-Which tab is showing is a cell, so it arrives as `lb-value` and the widget
-forwards it — to the `hidden` attribute of its panels rather than to the value
-of an `<input>`, which is the whole of the difference between `lb-tabs` and
-`lb-input`.  Nothing in the vocabulary is new, and the framework was not
-consulted.
-
-A click is the widget's own interaction, so it switches the panel itself and
-sends the choice afterward, and the action refreshes nothing — the browser is
-already showing what it just asked for, and saying so again would spend a round
-trip on nothing.  Persistence rides along behind a paint that already happened.
-
-That is what makes the returning user work.  The choice is a stored value like
-the visit count, so navigating away and back re-runs the query and the third
-tab is what the server answers with.  There is no blink, and no mechanism was
-needed for that either: the hub inserts a page host and lands its data in one
-synchronous block, and the browser does not paint mid-task, so the first tab is
-never on screen.  Hydration is early enough by construction rather than by
-timing.
-
-A value naming no panel changes nothing.  That is deliberate, and it is what
-makes the page's authored state the starting state: the host ships showing
-something, and a value only ever moves it.
-
-#### A wizard, decided by the server
-
-`demo/pages/wizard.html` is the same shape with the decision on the other side.
-Every step ships, one of them visible.  Back and Next are ordinary buttons
-carrying `lb-action`, so the hub sends the click, `wizard.hooks.ts` computes
-the step and clamps it at the ends, and the step comes back as a value.  The
-widget owns no arithmetic, and the browser never displays a step the server has
-not confirmed — the rule the counter follows for its number.
-
-Tabs switch first and tell the server after; a wizard waits.  A tab is a view
-of what is already there, and a wizard step is a position the server is
-entitled to refuse.  Both are the widget's decision about its own interaction,
-and neither is a framework feature.
-
-The disabled ends are derived rather than sent.  Which step is first is a fact
-about the page's markup, so the widget reads it there rather than being told
-twice — the same argument that gives a section heading its `colspan`.
-
-#### The empty list
-
-One conditional cannot be sent, and it is the one this framework owes a page.
-The server answers a list query with rows and says nothing about how many
-survived reconciliation, so after a delete the count exists only in the DOM.
-Without help, every list widget would grow its own copy of the same three
-lines.
-
-So `applyRows` stamps it, once, for every list widget there will ever be:
-
-```html
-<lb-list lb-query="roster" data-rows="0">
-```
-
-It is `data-` rather than `lb-` for the reason the section heading in
-`lb-table` is: it is derived from rows the hub already knows, and nothing
-addresses it.  The page then says what empty looks like in a stylesheet, and no
-widget has a conditional in it:
-
-```css
-.empty {
-  display: none;
-}
-[data-rows="0"] .empty {
-  display: block;
-}
-```
-
-```html
-<lb-list lb-query="roster">
-  <table>…</table>
-  <p class="empty">No members yet.</p>
-</lb-list>
-```
-
-Hidden is the default and shown is the rule, which is the ordering that matters:
-the stamp is absent until a projection has landed, and absent is not zero.  A
-list still waiting for its first response says nothing, rather than announcing
-that it is empty and then correcting itself.
-
-#### Where a flag may land
-
-A value lands on a widget as `lb-value` and on a native element as its
-`textContent`.  That is the whole of `land`, and two things follow for anyone
-writing a visibility rule.
-
-A flag cell must be a leaf.  `<section lb-cell="state">` wrapping anything at
-all replaces its children with a string, because assigning `textContent` is
-what a native cell means.  A cell names a place a value goes, and a container
-is not one.
-
-And CSS reaches an ancestor with `:has()`, which is how a leaf flag governs the
-box around it:
-
-```css
-.panel:has([lb-cell="state"][lb-value="stale"]) { … }
-```
-
-Only a widget carries `lb-value`, so a page with no widget in it can branch on
-a flag's text but not on an attribute.  That is the limit, and it is not much of
-one: by the time a page has a visibility rule worth writing it has behavior, and
-behavior is a widget.
-
-The flag is an attribute and the branching is a stylesheet.  Neither an inline
-`style` nor a placeholder that produces one is available — those are unsafe
-sinks, and expansion has no data to fill them with anyway.
-
-### List processing
-
-Everything so far has been one tuple.  A query may instead return many, and
-what displays them is a `<template>` the page author wrote and a widget that
-owns where each row goes.
-
-#### The table
-
-`demo/pages/roster.html` is the plain case.  The page author writes the table,
-and writes one row inside a `<template>`:
-
-```html
-<lb-list lb-query="roster">
-  <table>
-    <thead>
-      <tr><th>Name</th><th>Role</th><th>Team</th><th></th></tr>
-    </thead>
-    <tbody>
-      <template lb-key="id">
-        <tr>
-          <td lb-cell="name"></td>
-          <td lb-cell="role"></td>
-          <td lb-cell="team"></td>
-          <td><button lb-action="deleteMember">Delete</button></td>
-        </tr>
-      </template>
-    </tbody>
-  </table>
-</lb-list>
-```
-
-Inside the template, nothing is new.  `lb-cell` names a column and lands a
-value exactly as it does anywhere else on the page, because a row is a scope
-that happens to be small.  One function fills both, and a list widget imports
-it rather than reimplementing it:
-
-```ts
-import { applyTuple } from "@loadbare/app";
-```
-
-`lb-key` on the template names the column that identifies a row.  On a live
-row the same attribute carries that row's value, which is never ambiguous
-because a template is not a row.  The rows are the template's preceding
-siblings, so the template stays put as the insertion marker and static markup
-can sit on either side of the list.
-
-The widget is around the table rather than in it.  A custom element written
-inside `<tbody>` is discarded by the parser before expansion could ever see
-it, but a `<template>` is allowed there, which is why the template is the unit
-the page author writes and the widget is the element that wraps it.
-
-The delete button needs no wiring.  The hub builds a request from the
-attributes the element already sits under — `lb-query` from the widget,
-`lb-key` from the row — so the action arrives knowing which row was clicked,
-and the page never passed an argument.
-
-#### Two results, because a widget must know the difference
-
-A query returns the whole of its set.  It cannot know why it was re-run, so it
-never sends a delta:
-
-```ts
-import { rows, type Queries } from "@loadbare/app/server";
-
-export const queries: Queries = {
-  roster: async (ctx) => rows(await ctx.db.members()),
-};
-```
-
-An action does know what it changed, and can say only that.  So an action may
-return results of its own, laid over whatever its refresh set produced:
-
-```ts
-import { patch, type Hooks } from "@loadbare/app/server";
-
-export const hooks: Hooks = {
-  actions: {
-    addMember: {
-      run: async (ctx) => ({ roster: patch({ rows: [await ctx.db.addMember()] }) }),
-      refresh: [],
-    },
-    deleteMember: {
-      run: async (ctx, where) => {
-        await ctx.db.deleteMember(where.key ?? "");
-        return { roster: patch({ drop: [where.key ?? ""] }) };
-      },
-      refresh: [],
-    },
-    resetRoster: {
-      run: (ctx) => ctx.db.resetMembers(),
-      refresh: ["roster"],
-    },
-  },
-};
-```
-
-Those are the two results a list can receive:
-
-`rows` is the entire set, and therefore also the order.  Every row it names is
-placed in the order given, and a row whose key it does not name is gone.
-
-`patch` names only what changed.  Rows it lists arrive or are updated, keys in
-`drop` are gone, and a row it does not mention keeps both its contents and its
-position.
-
-Adding and removing are one result rather than two because the interesting
-cases are both at once — a row whose sort key changed has to move, a swap is
-one out and one in — and two messages would paint the state in between.
-
-`resetRoster` could have been a patch too, and is not, because membership and
-order both changed and the whole set is the honest answer.  The other two
-declare no refresh set at all.  Re-running `roster` would have shown the same
-thing, but it would be the server saying "here is everything" when it knows
-the answer is "one more row" — and only the narrower statement is something a
-widget that sorts or groups can act on.
-
-#### Where a row goes is the widget's
-
-`demo/pages/picker.html` puts the same rows in a `<select>`:
-
-```html
-<lb-options lb-query="choices" lb-action="pickMember" exp-label="Member:">
-  <template lb-key="id" lb-group="team">
-    <option lb-cell="name"></option>
-  </template>
-</lb-options>
-```
-
-Two things are different, and both follow from `<option>`.
-
-Its content model is text, so there is no element to put inside it and the row
-itself carries `lb-cell`.  A row root counts as a cell when it declares one.
-
-It also needs a `value`, which is a second destination, and a native element
-has only one.  Rather than invent a way to aim a cell at an attribute, the
-widget uses what it already has: the identity of the row is the value of the
-option, so `lb-key` supplies both and the page declares it once.
-
-Then the grouping.  Nothing on the wire knows what an `<optgroup>` is — the
-rows arrive flat, and `team` is a column like any other.  `lb-group` names it
-and `lb-options` builds one group per distinct value, reuses a group a
-later row belongs to, and removes one when its last row leaves:
-
-```html
-<select>
-  <optgroup label="Engines">
-    <option lb-key="m1" value="m1" lb-cell="name">Ada Lovelace</option>
-    <option lb-key="m3" value="m3" lb-cell="name">Alan Turing</option>
-  </optgroup>
-  <optgroup label="Compilers">
-    <option lb-key="m2" value="m2" lb-cell="name">Grace Hopper</option>
-  </optgroup>
-  <template lb-key="id" lb-group="team">…</template>
-</select>
-```
-
-This is the whole reason placement belongs to the widget.  Sorting, grouping,
-and section headings are one question — *where does this row go?* — and the
-answer is always local.  The hub delivers flat keyed rows and stops.  A widget
-that has nothing to say supplies nothing and rows accumulate in the order the
-server sent, which is what `lb-list` does.
-
-Because grouping is placement, it is derived and not addressed.  An
-`<optgroup>` carries no `lb-key` and the hub cannot see it; it is the
-widget's own scaffolding around rows the hub does know.
-
-#### How it reaches the widget
-
-A projection has to land on a widget.  A native element has one destination
-for a value and no way to acquire children, so a list is not something it can
-be asked to show, and the hub says so rather than doing nothing:
-
-```
-lb-hub: query 'oops' returned rows, but <div> is not a list widget
-```
-
-The hub calls one method and stops.  It tests for the method, never for the
-element, so it holds no table of tag names:
-
-```ts
-export interface HubRowHost {
-  acceptRows(result: Projection): void;
-}
-```
-
-A list widget is small, because everything above the placement decision is
-shared.  `lb-list` in its entirety:
-
-```ts
-class LbList extends HTMLElement implements HubRowHost {
-  acceptRows(result: Projection) {
-    applyRows(this, result);
-  }
-}
-```
-
-`applyRows` clones the template, matches each tuple to the row already showing
-it, fills that row with `applyTuple`, and drops what left.  A widget that
-places rows itself passes a third argument and writes nothing else:
-
-```ts
-applyRows(this, result, (row, tuple, template) => { … });
-```
-
-Rows are filled before they are inserted, so a widget inside a row has its
-attributes already set when it upgrades.  That is the same thing that makes
-hydration and refresh one operation everywhere else on the page.
-
-#### Widgets that own the scaffolding
-
-`lb-list` and `lb-options` are the framework's two answers to *where does
-a row go?* — nowhere in particular, and in a group.  Both leave the rest of the
-markup to the page.  `demo/pages/staff.html` and `demo/pages/chooser.html` are
-the same two lists again, in widgets that take the markup as well.
-
-`lb-table` supplies the table and answers the placement question twice.
-`lb-sort` names the column rows are ordered by, `lb-group` names the column
-they are sectioned by, and the page writes only what the page knows:
-
-```html
-<lb-table lb-query="staff" exp-caption="Everyone, by team">
-  <template lb-template="head">
-    <tr><th>Name</th><th>Role</th><th></th></tr>
-  </template>
-
-  <template lb-key="id" lb-group="team" lb-sort="name">
-    <tr>
-      <td lb-cell="name"></td>
-      <td lb-cell="role"></td>
-      <td><button lb-action="dropMember">Delete</button></td>
-    </tr>
-  </template>
-</lb-table>
-```
-
-Its `place` inserts a row before the first row in its section that sorts after
-it, which keeps the section ordered whatever else is in it — so a whole set and
-a single patched row take the same path and neither needs to know which it is.
-Add one member and the server sends one row and says nothing about order; it
-lands in its team's section, in name order, because that is the whole of what
-placement decides.
-
-The section heading is a `<tr>` the widget builds, exactly as `lb-options`
-builds an `<optgroup>`, and it is scaffolding for the same reason: derived from
-rows the hub knows, invisible to the hub itself, and gone when its last row
-leaves.  It carries `data-group` rather than a name from the vocabulary,
-because nothing addresses it.  Its `colspan` is the number of cells in the row
-the page author wrote, which is the only place that number exists.
-
-`lb-picker` goes the other way and supplies the row template.  Every option
-is one column of one row, so what is left to say is which columns — and those
-are words, which is what a parameter carries:
-
-```html
-<lb-picker lb-query="choices" lb-action="chooseMember"
-  exp-label="Member:" exp-key="id" exp-cell="name" exp-group="team"></lb-picker>
-```
-
-```html
-<!-- widgets/lb-picker.html -->
-<label>{{label}}
-  <select>
-    <template lb-key="{{key}}" lb-group="{{group}}">
-      <option lb-cell="{{cell}}"></option>
-    </template>
-  </select>
-</label>
-```
-
-What ships is the template the picker page wrote by hand, and the behavior is
-`lb-options` inherited whole — a distinct class exists only because
-`customElements.define` wants one constructor per name.  Drop `exp-group` and
-the placeholder has nothing behind it, so `lb-group` is dropped with it and
-the options arrive ungrouped: presence propagation doing the work a conditional
-would do elsewhere.
-
-Neither widget is more capable than the pair it wraps, and that is the point.
-A page that wants a second element in a row, or an option built from two
-columns, writes the template itself and gets the plain repeater.  These are for
-when it does not.
-
-#### Subtotals, and where a total goes
-
-`demo/pages/ledger.html` is a report: detail lines, a subtotal under each
-section, and a total under the table.  It is the shape a balance sheet has, and
-it is the one case that looks like it needs the browser to calculate something.
-
-It does not, and the reason is that the calculation was already done by
-something better at it.  Every SQL database produces a set with subtotals in it
-— `GROUP BY ROLLUP`, or `GROUPING SETS` for finer control — so a report can
-leave the database finished, in report order, as flat keyed rows.  That is the
-shape the data channel already carries.  Nothing new is on the wire, and the
-page writes one row template:
-
-```html
-<lb-table class="report" lb-query="ledger" exp-caption="Expenses by department">
-  <template lb-template="head">
-    <tr><th>Account</th><th class="amount">Amount</th></tr>
-  </template>
-
-  <template lb-key="key" lb-group="dept">
-    <tr>
-      <td lb-cell="line"></td>
-      <td class="amount" lb-cell="amount"></td>
-    </tr>
-  </template>
-
-  <template lb-template="foot">
-    <tr lb-query="ledgerTotal">
-      <th scope="row" lb-cell="line"></th>
-      <td class="amount" lb-cell="amount"></td>
-    </tr>
-  </template>
-</lb-table>
-```
-
-There is no `lb-sort`, and its absence is what makes this a report rather than
-a table.  A set is the order it arrived in, so the server decides where a
-subtotal sits — which is the only place that decision can be correct, since
-only the server knows what the subtotal is under.  `lb-group` stays, and the
-section headings are the scaffolding `lb-table` already builds.  A subtotal
-row carries its section like any other row, so it lands in that section, at the
-end, because that is where it arrived.
-
-**The key says which kind of row it is.**  A subtotal has no `id` of its own
-and needs a key anyway, so the server mints one, and the prefix it chooses is
-the only discriminator the page needs:
-
-```json
-{ "key": "d:x1", "dept": "Engineering", "line": "Salaries", "amount": "184,500.00" },
-{ "key": "s:Engineering", "dept": "Engineering", "line": "Total, Engineering", "amount": "213,650.00" }
-```
-
-`lb-key` lands on the row as an attribute, which is what makes this reachable.
-A cell would not be: a cell lands as *text* on a native element, and no selector
-matches text.  So the stylesheet is the whole of the difference between a
-subtotal and a detail line, and no widget carries a conditional:
-
-```css
-.report tr[lb-key^="d:"] td:first-child { padding-left: 1.5rem; }
-.report tr[lb-key^="s:"] { font-weight: bold; }
-.report tr[lb-key^="s:"] td { border-top: 1px solid; padding-top: 0.35rem; }
-```
-
-Blank lines are `padding` and rules are `border`.  A spacer row would be a row
-with a key, which is data standing in for whitespace, and a delete away from
-being wrong.
-
-**The total under the table is not a row.**  It is one line that does not
-repeat, so it is a tuple, from a second query, landing in a scope of its own —
-`lb-query="ledgerTotal"` on the `<tfoot>` row.  Two projections of one table
-on one page is what the query name is for, and `applyData` resolves the two
-independently: one selector finds the widget and delivers rows, another finds
-the footer row and fills its cells, and neither knows the second is inside the
-first.
-
-A full `ROLLUP` would have produced that total as a row as well, with a null
-department.  It is a tuple here for two reasons, and the first is mechanical: a
-row belonging to no section has nowhere to land in a grouped body.  The second
-is that a footer is often not a sum of what is above it at all — a prior
-period, a budget, a check figure — and those are the same markup and a
-different query.
-
-**What the server spends and the page never sees.**  `GROUPING(line)` is what
-tells a subtotal from a detail row, and it is the query's own answer rather
-than a column anyone invented.  It is spent server-side, on the key prefix and
-the label, and never reaches the browser.  Amounts are integer cents until the
-last moment and arrive formatted, because cells are strings and formatting
-money is the same kind of decision as rounding it.
-
-The whole of it generalizes downward without further mechanism.  A third-order
-subtotal is another grouping set and another key prefix; depth is a column like
-any other.  A report of any depth is still a flat ordered list of keyed rows,
-because that is what a rendered report is.
-
-Two things do not survive, and both are shape rather than value.  A subtotal
-label cannot span columns, since `colspan` is not something a value can
-produce — the label goes in the first cell and the rest stay empty.  And
-indentation by arbitrary depth needs a `style` attribute, which is an unsafe
-sink and closed: a fixed ladder of selectors covers a report whose depth is
-known, and a deeper one indents in the label.
-
-#### What a page still cannot do
-
-A projection is a top-level query result and its values are strings.  A tuple
-may not contain one, so a page that wants master and detail declares two
-queries, as `picker` does: `choices` returns the set, `picked` returns the one
-that was chosen.  A projection and a tuple cannot arrive on the same element,
-so they arrive on two.
-
-That limit is what a report has to be flattened past rather than a wall a
-report stops at, and the section above is what paying it looks like: the
-hierarchy is resolved by whatever computed it, and what arrives is flat.  What
-remains genuinely out of reach is structure whose *depth* is data — a comment
-tree, an org chart — where the number of levels is not known when the template
-is written.
-
-An empty set is an empty list and nothing more.  Saying "no members yet" is a
-conditional rather than a repetition, so it is not here: `applyRows` stamps
-`data-rows` and a stylesheet says the rest, in the section above.
-
----
-
-## Reference
-
-### Attribute vocabulary
-
-Import every name from `core/lb-constants.ts`.  Do not write one as a string
-literal in a widget, a page, a test or a document.
-
-| attribute      | constant        | goes on             | names                       |
-| -------------- | --------------- | ------------------- | --------------------------- |
-| `lb-query`    | `ATTR_QUERY`    | scope element       | a declared query            |
-| `lb-key`      | `ATTR_KEY`      | row template, row   | key column, then its value  |
-| `lb-group`    | `ATTR_GROUP`    | a row template      | column a widget groups by   |
-| `lb-cell`     | `ATTR_CELL`     | leaf widget         | column within scope         |
-| `lb-value`    | `ATTR_VALUE`    | leaf widget         | where the value lands       |
-| `lb-action`   | `ATTR_ACTION`   | any element         | a declared action           |
-| `lb-sort`     | `ATTR_SORT`     | a row template      | column a widget sorts by    |
-| `lb-slot`     | `ATTR_SLOT`     | inside a definition | where authored content goes |
-| `lb-template` | `ATTR_TEMPLATE` | definition, template | a named destination        |
-| `lb-nav-link` | `ATTR_NAV_LINK` | an anchor           | intercept this navigation   |
-| `data-rows`    | `ATTR_ROW_COUNT`| a list widget       | how many rows are showing   |
-
-`data-rows` is the one name in the table that is not Loadbare App's namespace.  The row
-machinery writes it and a stylesheet reads it; nothing addresses it, so it is
-`data-`, like the section heading `lb-table` builds.  It is in the table
-because it is written by shared code and read by pages, which makes it
-published — and a published name is imported like any other.
-
-`lb-group` and `lb-sort` are the two names in the table the hub never reads.
-Placement is the widget's, but the names are shared, because a grouped
-`<select>` and a table with section headings ask the same thing of the same
-data, and a table that sorts asks it of the same column a page author would
-name anywhere else.  Loadbare App has no namespace for an attribute that is a
-widget's alone.
-
-The `lb-` prefix is load bearing rather than decorative.  `data-*` is the
-handler-prop namespace, so a prop named `cell` or `key` would collide with an
-addressing attribute.
-
-Endpoints: `LB_DATA_ENDPOINT` is `/lb/data`, `LB_REQUEST_ENDPOINT` is
-`/lb`.  Page hosts ship as `<template id="page-<name>">`.
-
-### The definition language
-
-The rules a definition obeys, beyond the ones the Widgets section shows by
-example.
-
-Registry.  Every `.html` file in a definition directory defines the tag matching
-its basename.  Directories are searched in order and later ones win, so an
-application overrides a built-in widget by putting a file of the same name in
-its own directory.
-
-Scope.  Only tags matching `lb-*` are expanded, and every one of them must
-have a definition.  An unknown widget tag fails the build by name.
-
-Lowercase names.  Placeholder names are lowercase, hyphenated if they need a
-break: `{{input-class}}`, never `{{inputClass}}`.  HTML lowercases attribute
-names, so a capital is a name no tag could ever supply.  A definition that
-declares one is rejected when definitions load, naming the file and the
-spelling to use.
-
-Attribute survival.  Every authored attribute stays on the tag after expansion,
-`exp-` ones included.  Placing a parameter in the definition copies it inward;
-it does not move it.
-
-Recursion.  A definition may use other widgets.  The graph is checked for cycles
-once at load and rejected by name.  There is no depth cap.
-
-Templates.  Expansion descends into `<template>` content, for substitution as
-well as for expansion, so a row template ships already expanded — whether the
-page author wrote it or the definition did — and the browser only ever clones a
-finished tree.
-
-Named destinations.  A definition may mark elements with `lb-template`, and an
-authored `<template>` carrying the same name is unwrapped into the matching
-one.  Named templates are taken before the slot, both directions of a mismatch
-fail the build, and there may be several, because each exists to carry markup
-past a parse context the slot cannot reach.
-
-Substitution is applied to a parsed tree with `setAttribute` and node data, and
-serialized once through the DOM's own serializer.  Write no escaping code.
-
-Two known holes.  A placeholder nobody supplies cannot be detected, because that
-is indistinguishable from presence propagation dropping an attribute.  And a
-definition is parsed in a body context, so one whose root is `<tr>` or
-`<option>` is mangled before substitution runs.
-
-### Applying a response
-
-Every response is a set of query results, and every one lands through the same
-path, whether it is a cold start or the narrowest refresh.  The hub calls
-`applyData(main, data)`, which for each query finds every element carrying that
-`lb-query`, and within it sets `lb-value` on every element carrying a matching
-`lb-cell`.
-
-A query in the response with no scope on the page logs a warning and is skipped.
-A cell with no element is silently ignored.
-
-Hydration and refresh are the same call.  The browser runs
-`attributeChangedCallback` for attributes already present at upgrade, so a widget
-never asks when its data arrived.
-
-### Requests
-
-A widget has two options and no third.  Handle the interaction itself, or send a
-request.  It never asks the framework to change something on its behalf.
-
-To send, dispatch one bubbling `CustomEvent` named `LB_EVENT_NAME` carrying a
-`HubRequest` as its detail:
-
-```ts
-this.dispatchEvent(
-  new CustomEvent(LB_EVENT_NAME, {
-    bubbles: true,
-    detail: { op: "action", name, value: select.value },
-  }),
-);
-```
-
-The hub sits above every widget, POSTs anything that reaches it to `/lb`, and
-applies the response through the path above.  Build the request from the
-attributes the widget already carries — its `lb-cell`, the `lb-key` of its
-row, the `lb-query` of its scope.  The vocabulary runs in both directions;
-declare nothing twice.
-
-On a native element the hub turns a click into the request.  On a widget it does
-not: the widget owns its own interaction and decides what counts as performing
-it, which for `lb-select` is a change rather than a click.
-
-The operation set is closed:
-
-```ts
-type HubRequest =
-  | { op: "cell-change"; query: string; key: string; cell: string; value: string }
-  | { op: "tuple-insert"; query: string; values: Record<string, string> }
-  | { op: "tuple-update"; query: string; key: string; values: Record<string, string> }
-  | { op: "tuple-delete"; query: string; key: string }
-  | { op: "action"; name: string; query?: string; key?: string; cell?: string; value?: string };
-```
-
-The four CRUD operations name a query, never a table.  The fifth names something
-the page declared it can do, and what keeps it from being an RPC endpoint is
-that the name must already appear in the page's hooks — the wire cannot reach
-anything the page has not published.
-
-An action carries at most one value, because a control has at most one.  A
-button has none, so the server computes the whole of the result.  A `<select>`
-has one, because the choice is the interaction.  There is no argument list.
-
-State the refresh set yourself, in `pages/<name>.hooks.ts`.  There is no
-automatic mapping from an operation to the queries it affects.
-
-### Widget author's contract
-
-- Extend `HTMLElement`.  No Shadow DOM.
-- Events travel up, method calls travel down.
-- List the attributes you read in `observedAttributes` and render in
-  `attributeChangedCallback`.  Do not ask when the data arrived.
-- Take your value from `lb-value` and forward it to whatever control you own.
-  The hub writes one attribute name for every widget type and holds no table of
-  native attribute names.
-- Find your control with `querySelector`.  It is a child, placed by your
-  definition.
-- Build no children on upgrade.  Everything in the live DOM must appear in
-  view-source, except values, control state, and clones whose count came from a
-  query.
-- To show a list, implement `acceptRows` and call `applyRows`.  Decide where a
-  row goes and nothing else — cloning, matching and filling are shared, and a
-  second implementation of them is a second set of bugs.
-- Attach listeners in `connectedCallback`.  A parent may read its children there
-  but may not call widget methods on them until insertion completes.
-- Ship no guard against your own definition.  The control you `querySelector` is
-  placed by the file beside you, so a check for its absence is unreachable code
-  that a test should have caught.  Write the straight line.
-- Guard what a page author supplied.  A missing `lb-action` or an unset
-  `lb-cell` comes from a hand-written page, and nothing rejects it today.
-  `console.error` with the tag name, return, and disturb nothing else.
-
-The line between the last two is who wrote the thing you are checking.  Your
-definition is yours and is tested.  A page host is the application's and is not.
-
-A widget is for behavior.  `lb-select` is one: it receives its value like any
-other cell, and on change it sends a request.  A widget that only forwards a
-value to a control it wraps, or only sends a click, is doing work the hub
-already does.