@loadbare/app 0.7.2 → 0.7.4

package/docs/prior-art.md

@@ -0,0 +1,216 @@
+# Prior art
+
+> **LLM-researched, not yet revised by a person.**  Compiled by Claude on
+> 2026-09-16 from web sources, against `@loadbare/app` 0.7.3, while designing
+> conditional rendering.  The sources are listed under each section.
+
+Loadbare binds HTML to data by attributes and lets the platform do the DOM
+work.  That idea has been tried before.  This document records the two
+closest predecessors, where Loadbare agrees with them and where it parts
+ways, and what other frameworks do about conditional rendering.
+
+## The short version
+
+Loadbare is not Model-Driven Views, although MDV is the better-known name.
+MDV's model is a mutable object graph in the browser that the view observes.
+Loadbare has no model in the browser: the view is driven by server responses
+that say what changed.
+
+The closer ancestor is Internet Explorer 4's data binding, from 1997, whose
+vocabulary of record sets, single records and columns maps almost one to one
+onto Loadbare's.
+
+Loadbare can be described as IE4's relational binding vocabulary, on the
+`<template>` element that MDV left behind, with the server as the model.
+Andromeda (2003), where Loadbare began, sits between the two.
+
+## Internet Explorer 4 data binding (1997)
+
+Internet Explorer 4.0 bound HTML to data through attributes, built from four
+parts: a data source object (DSO), data consumers, a binding agent and a
+table repetition agent.  A DSO might take "an Open Database Connectivity
+(ODBC) connection string and an Structured Query Language (SQL) statement,"
+and had to expose its data through OLE DB.
+
+| IE4                                                                         | Loadbare              |
+|-----------------------------------------------------------------------------|-----------------------|
+| `DATASRC` on a table repeats "an entire set of records" ("set binding")     | `lb-list`             |
+| A single-valued consumer takes one value "from the current record"          | `lb-row`              |
+| `DATAFLD` names "a column in the data set"                                  | `lb-cell`             |
+| The repetition agent "uses the table row (tr) in the table body as a template" | `<template lb-key>` |
+| The DSO's SQL statement                                                     | a page's queries      |
+| The binding agent "work[s] completely behind the scenes"                    | the hub               |
+
+It differed from Loadbare in three ways:
+
+- **The data lived in the browser.**  "Since the DSO maintains the data on the
+  client, it also manages how the data is sorted and filtered."
+- **Binding was two-way.**  "When a user updates a databound element on the
+  page, the binding agent notifies the DSO."  Loadbare sends a request and
+  lands the answer.
+- **It was proprietary.**  A DSO was an ActiveX control or applet, and the
+  feature ended with Internet Explorer.
+
+Sources:
+[About Data Binding Architecture](https://learn.microsoft.com/en-us/previous-versions/windows/internet-explorer/ie-developer/platform-apis/ms531384(v=vs.85)),
+[Using the Tabular Data Control](https://www.sitepoint.com/control-internet-explorer/).
+
+## Model-Driven Views (2011–2015)
+
+### What it was
+
+Rafael Weinstein proposed MDV to the W3C WebApps group in April 2011:
+"Myself and a few other chromium folks have been working on a design for a
+formalized separation between View and Model in the browser."  Its README
+calls it "a way to write _dynamic_ HTML _using_ HTML," with the goal of native
+implementation in browsers.
+
+- `{{path.to.value}}` placeholders in text and attribute values, with a
+  custom syntax API for expressions.
+- `<template bind>` for one instance, `<template repeat>` for one instance
+  per array item, `<template if>` to make either conditional, and
+  `<template ref>` to reuse another template's content.
+- Two-way binding on inputs: "If DOM elements which collect user input are
+  bound, they _push_ the collected value into the model."
+- A conditional attribute, `hidden?`: "the attribute will be set to the empty
+  string if the value is reachable and truthy, otherwise the attribute will be
+  removed."
+- Models are plain JavaScript objects, observed through `Object.observe`.
+
+In the TemplateBinding implementation, a template stays in the document and
+its instances are inserted after it, tracked by a terminator node.  When `if`
+turns false, instances are removed and their bindings closed.
+
+### What became of it
+
+The W3C group asked for MDV to be broken into primitives.  In Weinstein's
+account those became DOM Mutation Observers, **the HTML `<template>`
+element**, and `Object.observe`.  `<template>` was specified by Weinstein and
+reported stable in May 2013.  No source found states outright that
+`<template>` was created for MDV, but they share an author, a period and a
+design.
+
+The rest did not survive:
+
+- `Object.observe` was withdrawn from TC39 in November 2015.  It disabled
+  optimization paths in V8, and Polymer found that complex applications made
+  "tens of thousands of O.o calls."
+- Without native observation, MDV had to keep a list of bindings, and a node
+  discarded without being unbound was never garbage collected.
+- The Polymer community debated whether the model or the markup should be the
+  source of truth, and settled on the model.
+- The binding half continues in Apple's Template Instantiation proposal (2017)
+  and Chrome's DOM Parts, which as of 2025 was pending, with no signals from
+  Gecko or WebKit.
+
+Sources:
+[Weinstein, "Model-driven Views"](https://lists.w3.org/Archives/Public/public-webapps/2011AprJun/0309.html),
+[MDV README](https://github.com/toolkitchen/mdv),
+[MDV template.md](https://raw.githubusercontent.com/toolkitchen/mdv/master/docs/template.md),
+[MDV node_bind.md](https://raw.githubusercontent.com/toolkitchen/mdv/master/docs/node_bind.md),
+[TemplateBinding source](https://raw.githubusercontent.com/googlearchive/TemplateBinding/master/src/TemplateBinding.js),
+[Will MDV become a standard?](https://groups.google.com/g/polymer-dev/c/4RSYaKmbtEk/m/uYnY3900wpIJ),
+[MDV or markup as data](https://groups.google.com/g/polymer-dev/c/FJQLrcSKGT0),
+[Polymer issue #154](https://github.com/Polymer/polymer/issues/154),
+[W3C HTML Templates, 2013](https://www.w3.org/TR/2013/WD-html-templates-20130214/),
+[InfoQ: Object.observe withdrawn](https://www.infoq.com/news/2015/11/object-observe-withdrawn/),
+[esdiscuss: An update on Object.observe](https://esdiscuss.org/topic/an-update-on-object-observe),
+[Template Instantiation](https://github.com/WICG/webcomponents/blob/gh-pages/proposals/Template-Instantiation.md),
+[DOM Parts](https://github.com/WICG/webcomponents/blob/gh-pages/proposals/DOM-Parts.md),
+[Intent to Prototype: DOM Parts](https://groups.google.com/a/chromium.org/g/blink-dev/c/wIADRnljZDA).
+
+## Where the three overlap
+
+**All three:**
+
+- Dynamic HTML declared in HTML.
+- Attributes naming data on ordinary elements.
+- The platform, not the application, performs the DOM work, with no virtual
+  DOM.
+
+**Loadbare and MDV:**
+
+- `<template>` as the unit of repetition and of conditions.
+- Built toward web standards, not a proprietary runtime.
+
+**Loadbare and IE4:**
+
+- A relational vocabulary: a record set, a single record, a column per
+  element.
+- The row as the repetition template.
+- SQL behind the data source.
+
+**MDV and IE4, and not Loadbare:**
+
+- The data lives in the browser.
+- Two-way binding.
+- The view keeps itself synchronized with changes to that data.
+
+**MDV only:**
+
+- Runtime `{{}}` placeholders and expressions.
+- Paths into nested object trees.
+- Change observation, and bindings that have to be closed.
+- A false `if` destroys its instances.
+
+**Loadbare only:**
+
+- The server is the source of truth, and the hub holds no data.
+- A response says what changed, as a whole list, a patch or a row, so nothing
+  is observed.
+- Writes are requests (`lb-action` and the CRUD operations) whose answers land
+  back.
+- A request's position is read from the document.
+- A build step: expansion, tree shaking, pages shipped as templates.
+- Navigation and request state carried by the hub.
+
+Two of Loadbare's central decisions reject what ended MDV.  There is no
+client-side model to observe, which is what made `Object.observe` too slow in
+practice.  And data comes only as rows and sets of rows, never as the nested
+object paths MDV bound to.
+
+## Conditional rendering elsewhere
+
+Frameworks handle a false branch in one of two ways.  Either it is hidden
+with CSS and keeps its state, or it is removed and rebuilt from scratch when
+it returns.  A few keep a removed branch alive in framework memory.
+
+| Framework                        | The false branch                                                                 | State kept | Updated while hidden |
+|----------------------------------|-----------------------------------------------------------------------------------|------------|----------------------|
+| MDV `<template if>`              | Instances removed after the template, bindings closed                            | no         | no                   |
+| Alpine `<template x-if>`         | Cloned from the template and inserted after it on show, destroyed and removed on hide | no     | no                   |
+| Knockout `if`                    | Comment nodes mark the place, contents re-rendered completely                     | no         | no                   |
+| Angular `*ngIf`                  | `<ng-template>` rendered as a comment anchor; a view can be detached and reinserted | if detached | no                |
+| Aurelia `if.bind`                | Removed from the DOM, views cached by default and reused                          | yes        | not documented       |
+| Vue `<KeepAlive>`                | Detached from the document but not unmounted                                      | yes        | no                   |
+| Lit `cache()`                    | DOM kept in a `DocumentFragment`, swapped back in                                 | yes        | on swap-in           |
+| Polymer `dom-if`                 | `style.display = 'none'`; `restamp` destroys and re-creates instead               | yes        | yes                  |
+| React `<Activity mode="hidden">` | `display: none`, Effects destroyed                                                | yes        | yes, at lower priority |
+
+Loadbare's `lb-show` moves the live element into a `<template>` that takes
+its place, and landing still reaches it there.  Each
+part has precedent: templates as conditions (MDV, Alpine, Angular), branches
+kept rather than rebuilt (Aurelia, Angular, Vue), and hidden branches kept
+current (Polymer, React).  No source found keeps the branch in a template in
+the document, standing where the element stood, with no framework cache.  The
+hub has nowhere else to keep one.
+
+Loadbare's recommendation before `lb-show`, a stylesheet rule on `lb-value`,
+is the same family as Polymer's `dom-if` and MDV's `hidden?`: the element stays and
+CSS hides it.
+
+Sources:
+[Alpine x-if source](https://raw.githubusercontent.com/alpinejs/alpine/main/packages/alpinejs/src/directives/x-if.js),
+[Alpine x-if](https://alpinejs.dev/directives/if),
+[Knockout virtual elements](https://knockoutjs.com/documentation/custom-bindings-for-virtual-elements.html),
+[Knockout if/with re-rendering](https://www.knockmeout.net/2012/03/knockoutjs-performance-gotcha-1ifwith.html),
+[Angular NgIf](https://angular.dev/api/common/NgIf),
+[Reusing views in Angular](https://angular.love/optimization-techniques-reusing-views/),
+[Aurelia conditional rendering](https://docs.aurelia.io/templates/conditional-rendering),
+[Vue KeepAlive](https://vuejs.org/guide/built-ins/keep-alive.html),
+[Lit directives](https://lit.dev/docs/templates/directives/),
+[Lit cache.ts](https://github.com/lit/lit/blob/lit-html-1.x/src/directives/cache.ts),
+[Polymer dom-if](https://polymer-library.polymer-project.org/2.0/docs/devguide/templates),
+[Polymer display caching](https://github.com/Polymer/polymer/commit/2611285),
+[Polymer issue #2712](https://github.com/Polymer/polymer/issues/2712),
+[React Activity](https://react.dev/reference/react/Activity).

package/docs/reference/custom-elements.md

@@ -223,6 +223,7 @@ as a string literal.
 |------------------|------------|
 | `ATTR_VALUE`     | `lb-value` |
 | `ATTR_CELL`      | `lb-cell`  |
+| `ATTR_SHOW`      | `lb-show`  |
 | `ATTR_LIST`      | `lb-list`  |
 | `ATTR_ROW`       | `lb-row`   |
 | `ATTR_KEY`       | `lb-key`   |
@@ -260,6 +261,15 @@ cells a successful insert resets — see
 [TECHREF-1.0](../TECHREF-1.0.md#the-round-trip). Read it as nothing landed,
 and show the widget's default. A blank string is a value that landed.
 
+A widget carrying `lb-show`, or inside an element that does, is moved into a
+template while its column is off and back out when it turns on — see
+[Conditional rendering](./data-binding.md#conditional-rendering). Going in, it
+sees `disconnectedCallback` and then `adoptedCallback`; coming out,
+`adoptedCallback` and then `connectedCallback`. It is the same instance
+throughout, and it still receives `lb-value` while it is away, so write
+`connectedCallback` to run more than once, as a row a list reorders already
+requires.
+
 List `ATTR_VALUE` in `observedAttributes`, or `attributeChangedCallback`
 never fires. The browser calls it for an attribute already present when an
 element upgrades, not only for one that changes afterward, so a widget's
@@ -287,9 +297,14 @@ See [TECHREF-1.0](../TECHREF-1.0.md#requests) for what each operation is
 filled with.
 
 A widget sending `lb-row-insert` or `lb-row-update` doesn't read its own
-controls. It dispatches the bare action from the element holding the cells,
-a `<tr>` as readily as a `<form>`, or from anything inside it, and the hub
-gathers `values` from the nearest element holding a readable `lb-cell`:
+controls. It dispatches the bare action from the row, or from anything
+inside it, and the hub gathers `values` from the row the event came from:
+the nearest `<form>`, `<tr>` or live row around the dispatching element,
+itself included, inside its scope. Every readable `lb-cell` in that row is
+gathered, wherever in the row it sits, except the cells of a scope nested in
+it: a picker carrying `lb-list` and `lb-cell` gives its own value, not its
+options'. A request from an element in no such
+row is not sent, and the console says to use a `<form>`.
 
 ```ts
 row.dispatchEvent(

package/docs/reference/data-binding.md

@@ -41,14 +41,15 @@ asks for are declared on the server; see [page files](./page-files.md).
 
 ## Binding
 
-| Attribute      | Written by  | Names                                     |
-|----------------|-------------|-------------------------------------------|
-| `lb-list`      | a developer | The set of rows a subtree displays        |
-| `lb-row`       | a developer | The one row a subtree displays            |
-| `lb-key`       | a developer | The column that identifies a row          |
-| `lb-cell`      | a developer | The column an element displays            |
-| `lb-key-value` | the hub     | A live row's own key                      |
-| `lb-value`     | the hub     | The value that landed on a cell           |
+| Attribute      | Written by  | Names                                                 |
+|----------------|-------------|-------------------------------------------------------|
+| `lb-list`      | a developer | The set of rows a subtree displays                    |
+| `lb-row`       | a developer | The one row a subtree displays                        |
+| `lb-key`       | a developer | The column that identifies a row                      |
+| `lb-cell`      | a developer | The column an element displays                        |
+| `lb-show`      | a developer | The column that decides whether an element is present |
+| `lb-key-value` | the hub     | A live row's own key                                  |
+| `lb-value`     | the hub     | The value that landed on a cell                       |
 
 A binding is scoped by ancestry. Either scope attribute scopes its DOM
 children, and a nested one of either kind begins a new scope, so an element
@@ -70,6 +71,13 @@ arrives from scope. The scope's own root counts as a cell if it carries one,
 which is how an `<option>` — whose content model is text — displays the value
 it is.
 
+An element that carries a scope and `lb-cell` both is a cell of the scope
+around it. Its own `lb-list` or `lb-row` names what it displays, and its
+ancestors name where it belongs, so a `<select lb-list="accounts"
+lb-cell="account">` in a row displays the accounts and holds that row's
+`account`. The value lands on it and is gathered from it; the cells inside
+it are the accounts', and neither.
+
 Name the same query on more than one subtree to display it in more than one
 place. Every subtree gets the result.
 
@@ -160,7 +168,7 @@ anything else is a name the page declared.
 
 The hub sends the first four from a native element on the element's own
 event: a form on submit, anything else on click. An insert or update clicked
-from a button reads the cells around the button (see [Forms](#forms)). A
+from a button reads the form or row the button is in (see [Forms](#forms)). A
 cell change needs a
 widget to say what a change is, so only a widget sends it: the shipped
 `<lb-input>` does when it carries `lb-action="lb-cell-change"`, and stays
@@ -207,8 +215,10 @@ The hub sends it from a native element. A widget sends its own request.
 ### Forms
 
 A `<form>` performs its `lb-action` on submit. `lb-row-insert` and `lb-row-update`
-both gather every `lb-cell` inside the form into one values map, read from
-the control each cell is or wraps. They differ in one thing: `lb-row-update`
+both gather every `lb-cell` of the form into one values map, read from
+the control each cell is or wraps. A cell inside a scope nested in the form
+is that scope's and is not gathered, the same way a value landing on the
+form's row does not reach it. They differ in one thing: `lb-row-update`
 also carries the key of the row it is inside, and `lb-row-insert` carries none,
 because there is no row yet. A declared name on a form sends that action on
 submit, carrying the binding and no values.
@@ -237,27 +247,32 @@ Give every `lb-cell` in a form a control to read. A cell that is neither an
 `<input>`, `<select>`, or `<textarea>` nor wraps one is left out of the
 values map, and a form with no cell to read sends nothing.
 
-Where the cells cannot sit in a form, as in a table row, put the action on a
-button beside them. The hub gathers from the nearest element around the
-button that holds a cell to read, so a button in a row for a new entry
-inserts that row's cells:
+An insert or update gathers the row it belongs to: the nearest `<form>`,
+`<tr>` or live row around the element that sends it, inside its scope. A
+button submits its form the same way, whatever else sits beside it.
+
+A form cannot go around a table row's controls, so there the row is the
+form. Put the action on a button in the row, and it inserts every cell in
+the row, wherever in the row the button and the cells are:
 
 ```html
 <table lb-list="roster">
   <tbody>
     <tr>
       <td><input lb-cell="name" /></td>
-      <td><input lb-cell="role" /></td>
-      <td><button lb-action="lb-row-insert">Add</button></td>
+      <td>
+        <input lb-cell="role" />
+        <button lb-action="lb-row-insert">Add</button>
+      </td>
     </tr>
   </tbody>
 </table>
 ```
 
-The search stops at the live row the button is in, so an `lb-row-update`
-button in a row saves only that row, and it never takes in the list scope
-itself. Keep the button's own cell apart from the others: a button sharing
-a `<td>` with one input gathers only that input.
+An `lb-row-update` button in a live row saves that row and no other, and a
+form nested in a row gathers only the form. Anywhere else, write the form:
+cells and a button in a `<div>` belong to no row, so the hub refuses the
+request and says to put them in a `<form>`.
 
 Put these two actions on a form or a button, not on an element that holds
 the cells. A click into one of its inputs would send the row, so the hub
@@ -269,42 +284,91 @@ gathers the same way; see
 
 Loadbare ships static HTML and hydrates elements that are already in the
 document. There is no `if`, and none is needed: write every possibility into
-the page, and control which of them is showing.
+the page, and let a column decide which of them is present.
 
-Every cell carries the value that landed on it as `lb-value`, so a
-stylesheet can show or hide part of a page from a value the server sent. Bind
-a column the page does not display to a hidden element:
+Write `lb-show` on an element, naming the column that decides it:
 
 ```html
 <template lb-key="id">
   <tr>
     <td lb-cell="name"></td>
-    <td lb-cell="locked" hidden></td>
-    <td><button lb-action="lb-row-delete">Remove</button></td>
+    <td><button lb-action="lb-row-delete" lb-show="removable">Remove</button></td>
   </tr>
 </template>
 ```
 
-```css
-tr:has([lb-cell="locked"][lb-value="true"]) button {
-  display: none;
-}
+```sql
+(ledger_count = 0 AND system_behavior IS NULL) AS removable
 ```
 
-`lb-value` holds the string the query sent, so the query decides the spelling
-the selector matches. A stylesheet can hide a control but cannot disable one,
-and hiding is presentation: the server still refuses what a request may not
-do.
+A value of `null` or `false` takes the element out of the page, and any other
+value puts it back. The hub never reads a string, so `"false"` is a value like
+any other: have the query answer with a boolean or a null. A row that does not
+carry the column leaves the element as it is, so a query that answers with
+whole rows returns the column in every row.
+
+`lb-show` binds the way `lb-cell` does, to the row on its nearest scoped
+ancestor. On an element that is itself a scope, the column belongs to the
+row around it, so this picker takes its choices from `groups` and whether it
+is present from the account row:
 
-Where showing a case takes more than a selector, a widget receives the value
-in `lb-value` and decides what to show:
+```html
+<select lb-list="groups" lb-cell="group_id" lb-show="group_choice">
+```
+
+An element may show a column and be decided by it, which shows a note only
+when there is one:
 
-```ts
-for (const step of steps) step.hidden = step.dataset.step !== value;
+```html
+<span lb-cell="note" lb-show="note"></span>
 ```
 
-Ship the case that is showing on arrival unhidden, and hide the rest in the
-HTML.
+An element that is not present cannot be clicked, but that is presentation:
+the server still refuses what a request may not do.
+
+### Where an absent element is
+
+An element whose column is off is moved into a `<template lb-show>` that
+stands where it stood, and moved back out when the column turns on. The
+developer never writes that template.
+
+- Nothing renders it, whatever a stylesheet says, because a template's content
+  is not its children.
+- It cannot be focused or clicked, assistive technology does not announce it,
+  and a form does not gather it.
+- It is moved, never rebuilt, so a widget keeps its instance and a control
+  keeps what was typed into it.
+- Values keep landing on it, and on every cell and scope inside it, while it
+  is away, so it returns current.
+
+The builder ships every `lb-show` element already inside its template, so
+nothing conditional shows until its row has landed.
+
+A condition never changes the structure of a page. An absent element keeps
+its place among its siblings, so a position selector (`:first-child`,
+`:nth-child`, `:empty`, `+`, `~`) counts its template as a sibling. A selector
+by tag, class or attribute is unaffected. Only a list changes a page's
+structure.
+
+A condition that is only a style is a class on an element that is present or
+not:
+
+```html
+<span lb-show="out_of_balance" class="danger">Out of balance</span>
+```
+
+These are build errors:
+
+- `lb-show` on a row template's root. A row that should not show is left out
+  by the query.
+- `lb-show` with no row around it: outside every scope, on a scope with none
+  around it, or in a list scope outside its row template, where nothing lands.
+- `lb-show` on a `<template>`.
+
+A condition that is not data, such as a collapsed section or an open menu,
+has no column. Use `<details>`, a stylesheet, or a widget. Every cell still
+carries the value that landed on it as `lb-value`, for a widget to read or a
+stylesheet to select on.
 
 ### An empty list
 
@@ -355,6 +419,12 @@ button in a stylesheet, or have a widget watch its own attributes and
 disable itself. An application that styles neither behaves correctly and
 shows nothing.
 
+A native button or form pressed again while it carries `lb-pending` is
+ignored, so a pending one is already disabled and the stylesheet only shows
+it. A widget is not held back, since one that sends on change must send its
+latest value. The hub also sets `aria-busy="true"` for as long as
+`lb-pending` is present.
+
 ## Sending a request from a widget
 
 A widget can build and dispatch a request itself instead of carrying one of

package/docs/testing.md

@@ -136,6 +136,8 @@ here.
 - a native element receives its value as text, a hyphenated one as `lb-value`
 - the root of a scope counts as a cell if it carries one, which is what makes
   an `<option>` row possible
+- an element carrying both a scope and `lb-cell` is a cell of the row around
+  it, and the cells inside it are its own scope's
 - a query with no scope is reported and skipped; several scopes for one query
   are all filled; a set of rows landing on a scope bound with `lb-row`
   is reported rather than thrown
@@ -182,10 +184,18 @@ What the hub is tested for here:
 - a click finds the nearest `lb-action`, and skips a hyphenated tag and a
   form, both of which own the interaction themselves
 - a submit gathers the form's cells, and reports a cell with no control
+- an insert or update gathers the nearest form, `<tr>` or live row inside
+  its scope, whatever shares the button's cell: one ghost row among its
+  neighbours, a whole live row, a form nested in a row, a button's form
+  owner; and refuses a `<div>` holding cells, pointing to `<form>`
+- gathering skips the cells of a nested scope, so a picker in a row sends
+  its own cell and nothing about its options
 - a request arriving with no action, or with a reserved name that is not one
   of the four, is refused before it reaches the wire
 - `lb-pending` lands on the element that dispatched, `lb-error` replaces it
   on failure, and the next request clears it
+- `aria-busy` comes and goes with `lb-pending`; a native button or form
+  performed again while pending sends nothing, and a widget still sends
 - a path with no page host reports and opens the unknown-page dialog; two
   hosts for one name report and take the first
 - `lb-navigation` lands with the path and the label of the link that names it