@loadbare/app 0.5.6 → 0.7.0

package/docs/analysis-accidental-complexity.md

@@ -0,0 +1,149 @@
+# Assessing the accidental complexity claim
+
+[Theory](./theory.md) claims that Loadbare/app carries less accidental
+complexity than React, Angular, or the hypermedia libraries.  This document
+tests that claim against [TECHREF-1.0](./TECHREF-1.0.md), which is the
+authoritative statement of what 1.0 means.
+
+Written 2026-09-07, against `@loadbare/app` 0.6.0.
+
+Brooks separates the difficulty of the user's problem from the work the tool
+demands.  The second kind is accidental, and the test applied here is whether
+Loadbare removes such work or relocates it somewhere the author still pays
+for it.
+
+## Where the claim holds
+
+The whole owned surface fits in the technical reference's cross-reference
+section.
+
+| Owned            | Count |
+|------------------|-------|
+| `lb-*` attributes | 15   |
+| `lb*` methods     | 3    |
+| Builder flags     | 4    |
+| Reserved filenames| 8    |
+| Reserved tags     | 1    |
+| Reserved events   | 1    |
+
+React reaches that size before an application adds a router, a data layer, or
+a bundler configuration, and each of those carries a surface of its own.
+Loadbare/app asks for no configuration file today.
+
+The server half is the strongest part of the argument.  A page is markup, a
+queries file, and a requests file.  The application designs no endpoints,
+writes no route table, and picks no serialization contract.  Four lines of
+Express carry the data channel.  Neither the fat frameworks nor the
+hypermedia libraries remove that category of work; htmx in particular leaves
+the developer designing every endpoint and every fragment it answers with.
+
+Building the HTML once removes reconciliation, keys, memoization, and effect
+dependencies together.  That is the largest single deletion in the design,
+and it is the one the hypermedia libraries do not make either, since they
+ship markup at run time and carry swap semantics to place it.
+
+## What the technical reference already knows
+
+Most of what an assessment finds is already on the blocker list.  Each
+concern below adds weight to an open item rather than naming a new one.
+
+| Concern                                    | Blocker                                    |
+|--------------------------------------------|--------------------------------------------|
+| Values carry no type, so every application formats its own dates and money | Data types |
+| No page is reachable by row                | Take a position on the URL space           |
+| A widget receives one cell at a time       | Whether a widget may receive a whole row   |
+| A widget repeats hub code to fire a request| Give a widget a way to fire its own request|
+| Master-detail is unspecified               | Decide what a nested list means            |
+| Every page redeclares the chrome's queries | Give the chrome a way to state its own queries |
+
+The technical reference's own sample query calls `String()` on a count by
+hand, which is the data-type blocker showing up in the documentation.
+
+Two [roadmap](./roadmap.md) items carry the same weight as these and appear
+in the first real application.  Concurrent writers on one list have no
+version or conflict story.  Per-keystroke validation has no home, and the
+roadmap expects it to sit in the widget while the server stays authoritative
+for the same field.
+
+Five sections of the technical reference are still marked `UNEDITED`:
+Binding, Requests, Links, Widgets, and Widget authoring.  Those are the
+mechanisms an author touches on every page.
+
+## Positions that carry a cost
+
+Two constraints appear in the body of the technical reference as current
+behavior rather than on the blocker list, so the project has taken a position
+on each.  Naming the cost is still fair.
+
+The hub reaches its endpoint by absolute path, so an application cannot be
+hosted under a subpath such as `example.com/myapp/`.  A deployment that wants
+several applications behind one host gives each one an origin.
+
+Every route answers 200 with the same document, so the browser detects an
+unknown page after the fact and the chrome's `lb-unknown-page` dialog reports
+it.  A crawler or a monitor that reads status codes sees a healthy response
+for a path the application does not have.
+
+## The gap recorded nowhere
+
+Loadbare/app offers no way to display or style an element according to the
+value that landed in it.
+
+A cell lands on a custom element as the `lb-value` attribute, which a
+stylesheet can select.  A cell lands on a native element as its
+`textContent`, which no selector reaches.  The hub stamps `lb-pending`,
+`lb-error`, and `lb-row-count`, which cover a request in flight, a request
+that failed, and an empty list.  Nothing covers a row whose `status` column
+reads `overdue`.
+
+An application that wants this writes a widget, and a widget that fires a
+request pays the cost the widget-protocol blocker already names.  So the
+missing piece pushes the author toward the mechanism that is itself
+unfinished.
+
+This appears in neither the blockers, the roadmap's open questions, nor the
+decided-against section.  It is the one finding here that the technical
+reference does not already record.
+
+## The general form of the query gap
+
+The URL-space blocker names one consequence of a broader constraint, and
+stating the constraint directly is more useful than stating the consequence.
+
+A query takes no argument from the browser.  Its signature is `(ctx) => Row`
+or `(ctx) => Row[]`, and `ctx` is what the application built from the Express
+request.  The hub's own request carries `page=<name>`.  The hub reads
+`location.pathname`, which drops the query string, so a path segment and a
+search parameter are both invisible to the server.
+
+An application that shows one selected record therefore holds the selection
+in server state.  A click fires an action, the handler records the selection
+where `ctx` reaches it, and the refreshed query reads it back.  That works
+today and needs no new mechanism.  It puts selection in the same territory as
+the roadmap's concurrent-writers question, and it means a reload or a shared
+link does not carry the record.
+
+## Comparison with the hypermedia libraries
+
+Theory rejects the existing tools for combining interpolation with
+conditional and list rendering.  The distinction is narrower than that.
+Loadbare/app interpolates at build time, with defaults and a substitution
+grammar, and renders lists at run time through `<template lb-key>`.  What the
+design rules out is conditionals and interpolation after the build.
+
+Loadbare/app also adds a builder, a filename grammar, and a slot and template
+system, where htmx asks for no build step.  Against React and Angular the
+surface comparison is decisive.  Against htmx it is close, and the server
+half is where Loadbare/app wins instead.
+
+## Verdict
+
+The claim holds on the server, and it holds on the client for everything the
+reconciliation layer used to cost.
+
+On the rest of the client it currently holds partly by not doing several
+things database applications need, and the technical reference lists most of
+them itself.  Whether the claim survives 1.0 depends on how the URL space,
+the row hook, the chrome queries, and value-driven display are answered, and
+an answer of "decided against" counts as an answer only where an application
+can still reach the behavior some other way.

package/docs/reference/builder.md

@@ -40,7 +40,7 @@ The builder classifies by name, not location.
 |----------------------------|---------------------------------------------------|
 | `chrome.html`              | The chrome — see [`chrome.html`](./chrome.md)     |
 | `*.page.html`              | A page                                            |
-| `*.hooks.ts`               | A page's hooks, matched by base name              |
+| `*.requests.ts`               | A page's requests, matched by base name              |
 | `*.queries.ts`             | A page's queries, matched by base name            |
 | `imports.ts`               | The packages this app takes widgets from          |
 | `*.css`                    | A stylesheet — see [CSS](./css.md)                |
@@ -48,7 +48,7 @@ The builder classifies by name, not location.
 | `<tag>.browser.ts`         | A widget script, named for the tag it registers   |
 
 Give the application exactly one `chrome.html` and at most one `imports.ts`.
-Give every `.hooks.ts` and `.queries.ts` a `.page.html` of the same base name.
+Give every `.requests.ts` and `.queries.ts` a `.page.html` of the same base name.
 
 Name a widget script `<tag>.browser.ts`, not `<tag>.ts`. Only a file whose
 name carries `.browser` is bundled for the browser; every other module under
@@ -125,10 +125,10 @@ A tag with neither a script nor a definition in any origin is an error.
 The builder expands the chrome and every page against the available widget
 definitions — see [Custom Elements](./custom-elements.md#html) for the
 substitution rules — wraps each expanded page in
-`<template id="page-<name>">`, and splices them into the chrome's `<body>`. It formats the result with
+`<template lb-page="<name>">`, and splices them into the chrome's `<body>`. It formats the result with
 Prettier when the application has it installed.
 
 The builder writes `app.css` only when it finds a stylesheet, and `pages.ts`
-only when some page has a `.hooks.ts` or a `.queries.ts` file. Import `hub`
+only when some page has a `.requests.ts` or a `.queries.ts` file. Import `hub`
 from `pages.ts` — see [The Express Server](./server.md) for the rest of the
 wiring.

package/docs/reference/chrome.md

@@ -24,7 +24,7 @@ Here is a minimal but fully complaint chrome for a typical app:
   </head>
   <body hidden>
     <lb-hub>
-      <header lb-query="lb-navigation">
+      <header lb-row="lb-navigation">
         <h1>Membership Roster</h1>
         <h2 lb-cell="page-label"></h2>
       </header>
@@ -34,7 +34,7 @@ Here is a minimal but fully complaint chrome for a typical app:
         <a href="https://example.org/">Our website</a>
       </nav>
       <main></main>
-      <dialog lb-unknown-page lb-query="lb-navigation">
+      <dialog lb-unknown-page lb-row="lb-navigation">
         The URL <span lb-cell="page-uri"></span> is not in this app.
       </dialog>
     </lb-hub>
@@ -60,7 +60,7 @@ Everything else is optional:
 |-------------------------------------------|---------------------------------------------|
 | `<link rel="stylesheet" href="/app.css">` | The bundled stylesheet                      |
 | `<a lb-nav-link>`                         | Navigation between pages                    |
-| `lb-query="lb-navigation"`                | Where the page is — see below               |
+| `lb-row="lb-navigation"`                | Where the page is — see below               |
 | `<dialog lb-unknown-page>`                | A message when a URL matches no page        |
 | Custom elements                           | The chrome, decomposed into widget files    |
 | `<body hidden>` + a `<noscript>` fallback | Avoids a first-load blink — see below       |
@@ -77,8 +77,9 @@ A navigation anchor's `href` is a path, and the path names a page:
 landing page is the one named `index.page.html`. An anchor without
 `lb-nav-link` is left alone and behaves like any other link.
 
-The `lb-unknown-page` attribute, if used, must appear on a `<dialog>`. The
-hub opens it when a path names no page. What it says is up to the chrome:
+The `lb-unknown-page` attribute, if used, must appear on a `<dialog>` inside
+`<lb-hub>`; the builder rejects it anywhere else. The hub opens it when a
+path names no page. What it says is up to the chrome:
 the dialog is a subtree like any other, and it displays where the page is by
 naming the hub's own query, described next.
 
@@ -86,11 +87,11 @@ naming the hub's own query, described next.
 
 On every navigation the hub lands a query of its own, `lb-navigation`, on
 any subtree inside the hub that names it. It arrives the way a server's
-query arrives — `lb-query` on the subtree, `lb-cell` on each element that
+row arrives — `lb-row` on the subtree, `lb-cell` on each element that
 shows a value — so a chrome displays the current page with no code at all:
 
 ```html
-<header lb-query="lb-navigation">
+<header lb-row="lb-navigation">
   <h1>Membership Roster</h1>
   <h2 lb-cell="page-label"></h2>
 </header>
@@ -112,12 +113,12 @@ namespace: no server answers a query so named. It is landed only where a
 subtree names it, so a chrome that displays no navigation is not warned
 about a query with no scope.
 
-The same tuple is what an unknown-page dialog has to work with. It lands
+The same row is what an unknown-page dialog has to work with. It lands
 before the page host is looked up, so a miss has it too. Name the query on
 the dialog and show whichever cell fits:
 
 ```html
-<dialog lb-unknown-page lb-query="lb-navigation">
+<dialog lb-unknown-page lb-row="lb-navigation">
   The URL <span lb-cell="page-uri"></span> is not in this app.
 </dialog>
 ```

package/docs/reference/custom-elements.md

@@ -223,12 +223,15 @@ as a string literal.
 |------------------|------------|
 | `ATTR_VALUE`     | `lb-value` |
 | `ATTR_CELL`      | `lb-cell`  |
-| `ATTR_QUERY`     | `lb-query` |
+| `ATTR_LIST`      | `lb-list`  |
+| `ATTR_ROW`       | `lb-row`   |
 | `ATTR_KEY`       | `lb-key`   |
-| `ATTR_GROUP`     | `lb-group` |
-| `ATTR_SORT`      | `lb-sort`  |
+| `ATTR_KEY_VALUE` | `lb-key-value` |
 | `ATTR_ACTION`    | `lb-action`|
-| `ATTR_ROW_COUNT` | `data-rows`|
+| `ACTION_ROW_INSERT`, `ACTION_ROW_DELETE`, `ACTION_ROW_UPDATE`, `ACTION_CELL_CHANGE` | the reserved `lb-action` values |
+| `LB_ACTIONS`     | all four of them, in one array |
+| `LB_RESERVED_PREFIX` | `lb-`, the prefix every reserved name begins with |
+| `ATTR_ROW_COUNT` | `lb-row-count`|
 | `LB_EVENT_NAME`  | `lb-request` |
 
 ### Receiving a value
@@ -261,81 +264,86 @@ no separate hydration path to write.
 ### Sending a request
 
 A widget that owns its own interaction — a `<select>`'s choice rather than a
-click — builds its own request and dispatches it as a bubbling
-`CustomEvent` named `LB_EVENT_NAME`, carrying one of the `HubRequest` shapes
-as its `detail`:
+click — dispatches its own request as a bubbling `CustomEvent` named
+`LB_EVENT_NAME`, carrying the action and, where it wraps a control, that
+control's value as its `detail`:
 
 ```ts
-import { ATTR_CELL, ATTR_KEY, ATTR_QUERY, LB_EVENT_NAME } from "@loadbare/app/constants";
+import { LB_EVENT_NAME } from "@loadbare/app/constants";
 import type { HubRequest } from "@loadbare/app/types";
 
-const detail: HubRequest = {
-  op: "cell-change",
-  query: this.closest(`[${ATTR_QUERY}]`)!.getAttribute(ATTR_QUERY)!,
-  key: this.closest(`[${ATTR_KEY}]`)!.getAttribute(ATTR_KEY)!,
-  cell: this.getAttribute(ATTR_CELL)!,
-  value: input.value,
-};
+const detail: HubRequest = { action: "lb-cell-change", value: input.value };
 this.dispatchEvent(new CustomEvent(LB_EVENT_NAME, { bubbles: true, detail }));
 ```
 
-Find `query` and `key` by walking up with `closest()`, the same way the hub
-finds the binding for a native element. See
-[Data Binding](./data-binding.md#requests) for the request vocabulary and
-what each operation carries.
+The hub fills in the scope the widget sits in before any ancestor sees the
+event, and does not send a request missing a field its operation requires.
+See [TECHREF-1.0](../TECHREF-1.0.md#requests) for what each operation is
+filled with.
 
 Let the event bubble, so an ancestor widget can intercept and stop it before
 the hub sees it. A hand-written widget and a native element carrying
 `lb-action` produce the same event.
 
-### Accepting rows
+### Decorating a list
 
-A query answering with many rows is delivered to whichever element carries
-an `acceptRows` method. It is a protocol, not a tag name — the hub tests for
-the method and never for the element:
+The hub reconciles every list scope itself. A plain element carrying
+`lb-list` with a row template inside it is a whole list and needs no widget,
+so a widget exists only when the rows need scaffolding or placement that
+only it can decide.
+
+Two optional methods say what it decides. Both are named in the `lb`
+namespace, which Loadbare reserves for methods it calls on classes it does
+not own, so a widget's own methods can never collide with a later one:
 
 ```ts
-import { applyRows } from "@loadbare/app/rows";
-import type { Projection, HubRowHost } from "@loadbare/app/types";
+import type { ListHost, Row } from "@loadbare/app/types";
+
+class SortedList extends HTMLElement implements ListHost {
+  lbPlaceRow(el: Element, row: Row, template: HTMLTemplateElement) {
+    // Where this row goes. Called with the element detached, on its first
+    // appearance and again whenever a whole set decides the order.
+  }
 
-class UpdateList extends HTMLElement implements HubRowHost {
-  acceptRows(result: Projection) {
-    applyRows(this, result);
+  lbRowsLanded() {
+    // Once, after the result has landed. For scaffolding derived from the
+    // rows: a section heading, an <optgroup>, anything that goes when its
+    // last row does.
   }
 }
 ```
 
-Call `applyRows(scope, result, place?)` rather than reimplementing rows.
-Every built-in list widget uses it, and it settles four things:
+Everything else is the hub's, and a widget never reimplements it:
 
-| Concern     | What `applyRows` does                                   |
+| Concern     | What the hub does                                       |
 |-------------|---------------------------------------------------------|
-| Cloning     | Clones the `<template lb-key="...">` in the widget      |
+| Cloning     | Clones the `<template lb-key="...">` in the scope       |
 | Matching    | Updates the row already showing that key, or clones one |
 | Reconciling | Removes the rows the response says are gone             |
-| Counting    | Stamps `data-rows` with the number of rows showing      |
+| Counting    | Stamps `lb-row-count` with the number of rows showing   |
 
-`rows` is the whole set, so it decides membership and order, and a key
-absent from it is removed. `patch` touches only the rows it names and leaves
+An array is the whole set, so it decides membership and order, and a key
+absent from it is removed. A patch touches only the rows it names and leaves
 every other row's contents and position alone.
 
-Supply a `place` function to decide where a row goes — `(row, tuple,
-template) => void`, called with a fresh or reordered row. The default
-inserts immediately before the template, so rows accumulate in arrival
-order. A widget that groups or sorts supplies its own `place` instead of
-reimplementing matching and cloning around it; `lb-options.browser.ts` and
-`lb-table.browser.ts` in [`@loadbare/widgets`](./widgets.md) are two different
-`place` functions over the same `applyRows`.
+`lbPlaceRow` is called with the row already filled and not yet in the
+document, so a widget that reads a cell to decide where the row goes can. A
+scope without it lands rows immediately before the template, in arrival
+order. `lb-options.browser.ts` and `lb-table.browser.ts` in
+[`@loadbare/widgets`](./widgets.md) are two different placements over the
+same machinery.
+
+A list scope with no row template displays nothing, which is not an error.
 
-Style an empty list against `data-rows` rather than carrying an empty-state
+Style an empty list against `lb-row-count` rather than carrying an empty-state
 conditional in the widget — see
 [Conditional rendering](./data-binding.md#conditional-rendering).
 
 ### Filling a scope by hand
 
-`@loadbare/app/rows` also exports `applyTuple(root, cells)`, the same
-tuple-landing operation a page host uses. Call it in a widget that builds
-its own rows or scopes rather than relying on `acceptRows`. It fills `root`
+`@loadbare/app` also exports `applyRow(root, row)`, the same row-landing
+operation a page host uses. Call it in a widget that builds a scope of its
+own rather than one the hub reconciles. It fills `root`
 itself when `root` carries a matching `lb-cell`, and every matching
 descendant.
 </content>