@loadbare/app 0.12.0 → 0.14.0

package/docs/comparison.md

@@ -320,9 +320,9 @@ without `.browser` is not bundled, and the build error names it.
   `CustomEvent`.  The hub completes it with `query`, `key` and `values` from
   where the element sits.  An ancestor may stop the event.
 - A custom element carrying `lb-query` and a row template may implement
-  `lbPlaceRow(el, row, template)` to decide where a row goes, and
-  `lbRowsLanded()` to build scaffolding such as group headings.  The hub does
-  the cloning, matching, removal and counting.
+  `lbRowsLanded()` to act on the rows once they land, such as scrolling to
+  the one a request created.  The hub does the cloning, matching, ordering,
+  grouping, removal and counting.
 - Method names beginning with `lb` on a custom element are reserved.
 
 Widget libraries are npm packages listed in `imports.ts`.  The builder scans
@@ -396,7 +396,7 @@ query, the kind and key the server declared, and one of these:
 A column holds one value.  A set of values is a query of its own.  A row
 never contains rows.  Master-detail is a row and rows answered under two
 names.  Many masters with their details is one `rows` query of joined rows,
-grouped for display by a custom element's `lbPlaceRow`.
+shown in groups by a group template.
 
 The application designs no endpoints, routes or serialization format.  The
 names in the markup are the keys in the page's `.queries.ts` and
@@ -467,11 +467,13 @@ The hub stamps the element that committed:
 |----------------------|------------------------------------------------------------|
 | `lb-request-pending` | The round trip is in flight; `aria-busy="true"` is set with it |
 | `lb-request-error`   | The last round trip from this element failed               |
+| `lb-request-refused` | The handler refused it, carrying its message               |
 
 A commit on an element carrying `lb-request-pending` is ignored.  A round
 trip has a ten-second deadline, after which it is aborted and treated as a
 failure.  `lb-request-error` records that a round trip failed, and carries
-no message.
+no message.  A handler's `refusal()` carries words for the user, shown on the
+element and on each control it names.
 
 After a successful `lb-row-insert` gathered from a form, the hub resets the
 form.  A failed insert resets nothing.
@@ -785,11 +787,12 @@ TECHREF-1.0 lists every name Loadbare/app owns in one cross-reference.
 
 | Owned                               | Count | Names                                                         |
 |-------------------------------------|-------|---------------------------------------------------------------|
-| `lb-*` attributes a developer writes | 7    | `lb-query`, `lb-column`, `lb-show`, `lb-request`, `lb-url-link`, `lb-url-push`, `lb-url-unknown` |
-| `lb-*` stamps                       | 8     | `lb-column-value`, `lb-key-value`, `lb-row-live`, `lb-query-row-count`, `lb-request-pending`, `lb-request-error`, `lb-page`, `lb-page-title` |
+| `lb-*` attributes a developer writes | 13   | `lb-query`, `lb-column`, `lb-show`, `lb-group`, `lb-count`, `lb-sum`, `lb-avg`, `lb-min`, `lb-max`, `lb-request`, `lb-url-link`, `lb-url-push`, `lb-url-unknown` |
+| `lb-*` stamps                       | 17    | `lb-column-value`, `lb-key-value`, `lb-row-live`, `lb-query-row-count`, `lb-group-live`, `lb-group-column`, `lb-group-value`, `lb-row-created`, `lb-row-changed`, `lb-row-moved`, `lb-row-requested`, `lb-row-leaving`, `lb-group-leaving`, `lb-request-pending`, `lb-request-error`, `lb-page`, `lb-page-title` |
 | `lb-*` build-time attributes        | 2     | `lb-exp-slot`, `lb-exp-template`                              |
 | Requests Loadbare provides          | 3     | `lb-row-insert`, `lb-row-update`, `lb-row-delete`             |
-| `lb*` methods on custom elements    | 2     | `lbPlaceRow`, `lbRowsLanded`                                  |
+| `lb*` methods on custom elements    | 1     | `lbRowsLanded`                                                |
+| Query parms Loadbare reads          | 1     | `lb-order-<query>`                                            |
 | Attribute namespace for expansion   | 1     | `exp-*`                                                       |
 | Reserved tags                       | 1     | `<lb-hub>`                                                    |
 | Reserved events                     | 1     | `lb-request`                                                  |
@@ -821,7 +824,7 @@ cross-reference, so no count is given for them here.
 - A widget's markup is in the document and in view-source.
 - On navigation the hub sets `document.title` from the page's `<title>`.  It
   does not move focus or announce the new page.
-- Checkboxes and radio buttons are not implemented for landing or gathering.
+- Radio buttons are not implemented for landing or gathering.
 
 ### Elsewhere
 
@@ -916,9 +919,9 @@ Roadmap.
 | Nested data                   | A row never holds rows.  Trees are sent as joined rows.                 |
 | Record URLs and view parameters | A path names a page.  A record or a filter is a query parm, `/accounts?acct=23`. |
 | Query arguments from the browser | None.  Query parms reach queries through `contextFor` and `ctx`.     |
-| Checkboxes, radio buttons, file inputs | Not landed and not gathered.  Open blocker.                    |
+| Radio buttons, file inputs    | Not landed and not gathered.  Radio buttons are an open blocker. Checkboxes land and gather as `true` and `false`. |
 | Data types and formatting     | No conversion.  Queries format values.  Open blocker.                  |
-| Error messages                | `lb-request-error` carries no message.                                 |
+| Error messages                | A handler's `refusal()` reaches the user; any other failure carries no message. |
 | Field validation              | No mechanism.  Per-keystroke validation is a roadmap question.         |
 | Optimistic updates            | None.                                                                  |
 | Concurrent writers            | No version or conflict check.  Roadmap question.                       |
@@ -926,7 +929,7 @@ Roadmap.
 | Offline or local-first use    | None.                                                                  |
 | Server-side rendering for crawlers | None.  Every path answers the same document with status 200.      |
 | Subpath hosting               | Not possible.  The hub uses absolute paths.                            |
-| Chrome-level queries          | A widget in the chrome bound to a query requires every page to declare it.  Open blocker. |
+| Chrome-level queries          | A widget in the chrome bound to a query requires every page to declare it.  On the roadmap. |
 | A widget receiving a whole row | Not available.  Open blocker.                                         |
 | A nested `rows` query per outer row | A nested query receives the same rows in every outer row.  A new outer row's nested query stays empty until its name lands again.  Open blocker. |
 | Configurable request deadline | Fixed at ten seconds.                                                  |
@@ -1181,7 +1184,8 @@ Each equivalent is approximate.
 | Expansion                     | Server-side include; partial; build-time component render (Astro)                |
 | `exp-` parameter              | A prop fixed at build time                                                       |
 | `lb-exp-slot`, `lb-exp-template` | Default slot and named slots; `ng-content` with `select`                         |
-| `lbPlaceRow`, `lbRowsLanded`  | Custom list rendering; a render prop                                             |
+| `lbRowsLanded`                | An effect after a list renders                                                   |
+| `order`, `lb-group`           | `ORDER BY` with report-writer control breaks (`BREAK ON`, group bands)          |
 | `ctx` / `HubContext`          | `event.locals` (SvelteKit); loader `context` (React Router 7); request-scoped dependency injection |
 | `imports.ts`                  | Installing and registering a component library                                   |
 | `pages.ts`                    | Generated route manifest                                                         |

package/docs/possible-ideas.md

@@ -0,0 +1,308 @@
+# Possible Ideas
+
+> **LLM-authored, not yet revised by a person.**  Drafted by Claude on
+> 2026-10-02 against `@loadbare/app` 0.12.0, from a session in ef.  Nothing
+> here is decided or planned.
+
+## Why these are being considered
+
+A custom element is the platform's one way to attach code to markup, and
+widget work keeps running into what that costs.
+
+- No decomposition.  Code that concerns one row has nowhere to live but a
+  wrapper around the whole table, so `lb-table` owns everything inside it.
+  That is how page-specific behavior ends up in a shared widget: the COA
+  page's ghost row per section grew because row-level code could attach
+  only to the table.  It is the overfit the README's test guards against.
+- The browser's lifecycle is not the hub's.  A moved row is disconnected and
+  connected, the copy a move leaves behind is constructed, and an `lb-show`
+  toggle adopts twice, so `connectedCallback` must be written to run again.
+- Clutter.  The page's source is the widget's dialect of named templates
+  rather than HTML, and the shipped page keeps a wrapper tag around what it
+  expanded.
+- Plumbing through the wrapper.  The tag carrying the code is not the
+  control: `WrappedControl` forwards `value`, fires `change` again, and needs
+  `ElementInternals` to join a form.  Focus is searched for inside the
+  wrapper, and `autofocus` on a wrapped `<input>` is lost.
+- Content models reach forms too.  A `<form>` cannot wrap a `<tr>`, so the
+  ghost row joins its controls to a hidden form outside the table by the
+  `form` attribute.  A form cannot hold a form, so `lb-insert-dialog` is
+  written once outside every row instead of beside the control it serves.
+- Ids repeat in a row template.  `lb-confirm` finds its dialog by position,
+  because `commandfor`, HTML's own way to open one with no script, works
+  only by id.
+- Upgrade timing is the hub's problem.  An element shipped inside an
+  `lb-show` template, or whose definition loads late, has not upgraded, so
+  the hub keeps `waiting()`, lands kept answers again once it upgrades, and
+  stamps `lb-column-value` for a control to take up on first connect.
+- A few lines cost a wrapper.  `lb-options` has a script mostly to copy
+  `lb-group-value` into an `<optgroup>`'s `label` and each key into an
+  option's `value`, and for that the whole `<select>` sits inside a custom
+  element.
+- Parameters cannot carry structure.  Expansion parameters are words, so
+  when groups became a template, `lb-picker` lost `exp-group` and a grouped
+  picker went back to a hand-written `lb-options`.
+- CSS and accessibility see an element HTML does not define.  A wrapper tag
+  has no role, shifts child and `:nth-child` selectors, and has no place in
+  a table.  The usual remedy, `display: contents`, has a history of
+  accessibility bugs.
+- One element, one class.  A ghost row that should also save as it is typed
+  in needs a widget combining the two.
+
+## Code on elements the parser constrains
+
+Loadbare's data vocabulary is attributes, and an attribute goes on any
+element: `<tr lb-query>`, `<option lb-column>`, `<tbody lb-show>`.  Behavior
+is different.  The platform attaches code to markup through a custom element
+tag, and a tag must survive the parser.  In a table, a `<select>`, or a `<p>`
+it does not: an unexpected tag is dropped, moved out of the table, or closes
+the paragraph.
+
+So code that concerns one row lives on a wrapper around the whole table.
+`lb-table` owns the `<table>`, and the page writes its contents as named
+templates (`head`, `foot`, `ghost`) that the builder joins back into a
+table.  Each new need is another named destination, and the page's source
+reads as `lb-table`'s shape rather than a table's.  The shipped HTML is
+honest; the source is a dialect.
+
+Two ways to put code on the element itself follow, and only the second
+survives.
+
+### Customized built-ins
+
+```html
+<tr is="lb-ghost-row">…</tr>
+```
+
+The platform's own answer: a class extending `HTMLTableRowElement`, which
+the parser treats as a `<tr>`.  WebKit has declined to ship it, and every
+browser on iOS and iPadOS is WebKit, so a polyfill, usually a
+`MutationObserver`, would be the code path on every iPhone and iPad for
+good.  That rules it out.
+
+### Behavior by attribute
+
+```html
+<tr lb-behavior="ghost-row">…</tr>
+```
+
+Code bound to any element by an attribute, as Stimulus does with
+`data-controller`.  It fits the parser everywhere and needs no polyfill.
+
+- What usually drives it is a `MutationObserver`, which is incidental: the
+  code runs because something noticed.  The hub, though, already knows every
+  time it puts an element in the page: it shows a page, clones a row, builds
+  a group, and moves an element in and out of an `lb-show` template.  A
+  behavior attached and detached at those moments would be explicit.
+- Elements the hub does not add (a widget's own scaffolding, anything a
+  script creates) would get no behavior, which may be the right rule rather
+  than a limitation.
+- No form association of its own, and mostly none needed: a behavior on a
+  native control leaves it a native control, which joins its form, takes
+  focus and honors `autofocus` as it always did.  Only a control whose UI is
+  built from scratch needs `ElementInternals`, and stays an autonomous
+  custom element.
+- The platform has discussed a registry for custom attributes, which would
+  be this idea built in.  It has not shipped.  Without it the browser has no
+  part in a behavior: everything below is the hub's.
+
+#### A lifecycle in the hub's terms
+
+A custom element's lifecycle is the browser's, and it speaks of insertion:
+connected, disconnected, adopted.  The hub's work rarely lines up with it.  A
+moved row is disconnected and connected, the copy a move leaves behind is
+constructed, an `lb-show` toggle adopts twice, which is why a custom element
+must write `connectedCallback` to run again.
+
+A behavior's lifecycle would be calls the hub makes from its own code, at
+moments it already knows, named for what the hub did:
+
+| The hub                                                        | A behavior hears                                            |
+| -------------------------------------------------------------- | ----------------------------------------------------------- |
+| Shows a page, places a cloned row, builds a group, first shows an element shipped absent | `attached()`, once, after the element is placed and filled |
+| Lands new values on the element's row                          | `landed(row)`                                               |
+| Moves a row the order put elsewhere                            | `moved()`; the instance is kept                             |
+| Leaves a copy of a moved row behind                            | Nothing; the copy gets no behavior                          |
+| Turns `lb-show` off, then on                                   | `hidden()`, then `shown()`; the instance is kept            |
+| Removes a row, once its animations end                         | `detached()`, once                                          |
+| Finishes a request issued from inside the element              | `requestDone(detail)`                                       |
+
+- `attached` and `detached` pair exactly, so setup and teardown need no
+  guard against running twice.
+- The calls are the code-side twin of the stamps a stylesheet already sees
+  (`lb-row-created`, `lb-row-changed`, `lb-row-moved`, `lb-row-leaving`):
+  one vocabulary for CSS and code, in the hub's relational terms.
+- The hub keeps one instance per element and behavior name.  An element may
+  carry several, `lb-behavior="ghost-row autosave"`, which a tag cannot.
+- A behavior is a class in a file the builder finds by name, as it finds
+  `<tag>.browser.ts`, and a name with no file is a build error.
+
+What the hub would have to define and keep: whether `attached` comes before
+or after the rows inside a host land, and the order of calls among nested
+behaviors.  A custom element gets its ordering from the platform; here it is
+loadbare's to state.
+
+A rule for choosing: a custom element makes a new kind of element (its own
+markup, expansion, or a control built from scratch); a behavior adds code to
+an element HTML already has.
+
+### Where it would land
+
+Behavior by attribute lets a page write a real `<table lb-query>` with code
+on the rows that need it, and leaves `lb-table` to supply only what is truly
+the table's.  It keeps the parser and the browser matrix out of it, at the
+cost of a lifecycle the hub would define.
+
+## Expansion that replaces the tag
+
+Today a custom element's tag does two jobs: at build time it is expanded,
+and at run time it carries code.  Because the code needs the tag, the tag
+ships as a wrapper around what it expanded, and the wrapper is the source of
+most widget friction: focus searched for inside it, values forwarded through
+it, `autofocus` lost, and no place in a table.
+
+With behaviors carrying the code, expansion is free to stop shipping the
+tag.
+
+```html
+<!-- page -->
+<lb-field exp-label="Name" lb-column="name"></lb-field>
+
+<!-- what ships -->
+<!-- lb-field exp-label="Name" lb-column="name" -->
+<label lb-behavior="lb-field">Name <input lb-column="name" /></label>
+```
+
+- **The tag becomes a comment.**  The shipped DOM keeps a trail back to the
+  source at no run-time cost.  A comment is legal anywhere, tables included,
+  and is invisible to CSS, `:nth-child` and the hub's counting.
+- **The builder puts the behavior on the root.**  When
+  `<name>.behavior.ts` exists, the expanded root gets `lb-behavior="<name>"`;
+  the author never writes it.  `[lb-behavior~="lb-field"]` then serves CSS
+  and `querySelector` as the tag selector `lb-field` does now.
+- **Every widget inherits one base class.**  A `Behavior` holds `this.el`,
+  has empty methods for every call in the hub's lifecycle, and types
+  `landed(row)` and `requestDone(detail)`.  A widget overrides only what it
+  uses, as it extends `HTMLElement` or `WrappedControl` today.
+
+The file convention decides which path an element takes:
+
+| The element has                            | The builder                                        | At run time            |
+| ------------------------------------------ | -------------------------------------------------- | ---------------------- |
+| An element file, no script                 | Replaces the tag, leaves a comment                 | Plain HTML             |
+| An element file and `<name>.behavior.ts`   | Replaces the tag, puts `lb-behavior` on the root   | The hub's lifecycle    |
+| `<name>.browser.ts`                        | Keeps the tag, as today                            | The browser's lifecycle |
+
+The third row is for controls built from scratch, the only elements that
+still need `ElementInternals`.
+
+### A flag to keep the tag
+
+Considered and set aside.  It gives every widget two DOM shapes, so its CSS
+and code must work in both.  It cannot apply where replacing pays off most,
+since a kept tag still has no place in a table.  And what people would keep
+the tag for, a name to find and style the widget by and a trail to its
+source, the `lb-behavior` attribute and the comment already give.
+
+### To settle
+
+1. **One root.**  A behavior attaches to one element, so an element file with
+   a behavior has exactly one top-level element, and anything more is a
+   build error.
+2. **Where the tag's attributes go.**  The wrapper used to keep them; once
+   the tag is gone each needs a destination.  The natural default is the
+   root, and `lb-field` breaks it: its root is the `<label>`, but
+   `lb-column` belongs on the `<input>` inside while `lb-show` belongs on the
+   label.  Either the element file marks a target for data attributes, or
+   the page passes them as parameters (`exp-column`, written into the file as
+   `lb-column="{{column}}"`), which works today but reads less naturally
+   than `lb-column`.  This wants worked examples before a rule.
+
+## The case for behaviors
+
+Today's model is simple to state: a widget is a name, and a name is one or
+both of a `.html` and a `.browser.ts`.  One name is one element the
+developer writes, so what a widget does is easy to predict.  Most of what
+that costs is paid inside Loadbare, in service of the simple model.  The one
+place it leaks to the developer is the lifecycle, where a widget author must
+follow strict rules to get the behavior they expect.
+
+Behaviors would simplify the hub, but they seem to spread code that a
+custom element keeps in one file.  The containment comes from the element
+file, though, not from the tag.
+
+### What one file bundles today
+
+`lb-table`'s script does three jobs, joined by where they sit rather than by
+any data they share:
+
+| Job                        | Reads and writes                                   |
+| -------------------------- | -------------------------------------------------- |
+| Table scaffolding          | Caption, head and foot destinations; expansion only |
+| The ghost row              | The ghost row's controls, its form, and focus      |
+| Scrolling to the saved row | The list's rows and their stamps                   |
+
+It is one file, and three concerns in one class, none reusable without the
+others.  A `<ul>` cannot have a ghost row without becoming an `lb-table`.
+
+### Two units
+
+- A widget is markup.  Its element file decides what elements exist, at
+  build time, as now.
+- A behavior is what one element does.  Its code attaches to the element
+  that carries it, and runs on the hub's lifecycle.
+
+An element file may write `lb-behavior` on its own inner elements:
+
+```html
+<!-- lb-table.html -->
+<table lb-behavior="scroll-to-saved">
+  <thead lb-exp-template="head"></thead>
+  <tbody lb-exp-slot></tbody>
+  <tbody lb-exp-template="ghost" lb-behavior="ghost-row"></tbody>
+</table>
+```
+
+`lb-table` stays the one place to read, and its element file says which code
+runs on which element.  The code is split into files by job, and the widget
+assembles them.  A page that wants a ghost row in a `<ul>` writes
+`lb-behavior="ghost-row"` on it.
+
+### Where code goes
+
+Code goes on the element it reads and writes.
+
+- The ghost row's code touches the ghost row's controls and form, so it is a
+  behavior on the ghost row.
+- Scrolling touches the list's rows, so it is a behavior on the list.
+- Code that seems to need two elements is the sign to stop.  Behaviors never
+  call each other.  They speak only through what widgets use today:
+  attributes the hub stamps, and bubbling events such as `lb-request-done`.
+  The scrolling behavior knows nothing of the ghost row; it reads
+  `lb-row-requested`.
+
+The rule also refuses the overfit that started this: a ghost row per
+section would be a behavior on the table reaching into every section.
+
+### Where the leak moves
+
+Today the leak is the browser's lifecycle: `connectedCallback` written to
+run again, and a value stamp adopted on first connect.  With behaviors it
+becomes three rules Loadbare states:
+
+1. Only elements the hub places get behaviors.
+2. A behavior is attached and detached exactly once.
+3. Behaviors speak only through stamps and events.
+
+They are fewer, and in the hub's terms rather than the browser's.  The cost
+moves to Loadbare's design: the ordering the platform gives custom elements
+must be stated, such as whether a host's behavior attaches before or after
+its rows land, and the order among nested behaviors.
+
+### Both, not one
+
+Custom elements stay.  A control built from scratch still needs
+`ElementInternals`, and a tag with no code is expansion alone.  Behaviors
+cover what a tag does badly: code on an element HTML already has, inside
+content models that forbid a tag.  The developer's question becomes whether
+they are making a new kind of element, or giving an existing element a job.

package/docs/reference/chrome.md

@@ -72,6 +72,10 @@ Put everything the user interacts with inside `<lb-hub>`. The hub normally
 sits directly inside `<body>`, with banner, nav, footer and `<main>` inside
 it, so Loadbare can act on all of them.
 
+Write exactly one `<lb-hub>` and exactly one `<main>`, with the `<main>`
+inside the hub and empty but for whitespace.  The builder rejects a chrome
+that does otherwise.
+
 The chrome's `<title>` is the document title until the first page shows.
 From then on the hub sets the document title to the page's label; see
 [The URL](#the-url).
@@ -165,7 +169,9 @@ pushes one instead when the element carrying `lb-request` also carries
 
 The hub answers the request itself, with no round trip, then reloads the
 page's queries at the new URL. The page stays in place, and rows that come
-back keep their place.
+back keep their place. A request that changes only `lb-order-<query>`, the
+user's [order](./data-binding.md#order) for a query the hub sorts itself,
+re-sorts the rows already on the page and loads nothing.
 
 A control whose column the URL does not carry lands empty, so every control
 inside `lb-query="lb-url"` shows what the address bar says, after a reload