@loadbare/app 0.6.0 → 0.7.1

package/docs/reference/data-binding.md

@@ -19,19 +19,21 @@ Here is a page that binds a scalar, a list, and three requests:
 
 <p lb-row="dues">Dues collected this year: <span lb-cell="total"></span></p>
 
-<form lb-action="lb-row-insert" lb-list="roster">
-  <input lb-cell="name" placeholder="Name" />
-  <button type="submit">Add member</button>
-</form>
-
-<ul lb-list="roster">
-  <template lb-key="id">
-    <li>
-      <lb-input lb-cell="name"></lb-input>
-      <button lb-action="lb-row-delete">Remove</button>
-    </li>
-  </template>
-</ul>
+<section lb-list="roster">
+  <form lb-action="lb-row-insert">
+    <input lb-cell="name" placeholder="Name" />
+    <button type="submit">Add member</button>
+  </form>
+
+  <ul>
+    <template lb-key="id">
+      <li>
+        <lb-input lb-cell="name"></lb-input>
+        <button lb-action="lb-row-delete">Remove</button>
+      </li>
+    </template>
+  </ul>
+</section>
 ```
 
 The queries named here — `dues` and `roster` — and the operations the page
@@ -46,7 +48,7 @@ asks for are declared on the server; see [page files](./page-files.md).
 | `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     | Where a widget receives its value         |
+| `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
@@ -85,20 +87,23 @@ value of it. A developer writes the first and never the second.
 
 ### Where a bound value lands
 
-A value lands on a bound element one of two ways.
+A value lands on a bound element one of three ways.
 
-| Element          | Receives the value as    |
-|------------------|--------------------------|
-| A native element | Its `textContent`        |
-| A custom element | Its `lb-value` attribute |
+| Element                                | Receives the value as             |
+|----------------------------------------|-----------------------------------|
+| A custom element                       | Its `lb-value` attribute          |
+| `<select>`, `<textarea>`, or `<input>` | Its `value`, and `lb-value`       |
+| Any other native element               | Its `textContent`, and `lb-value` |
 
-A native element has no behavior of its own, so its value is its text. A
-widget owns whatever control it wraps, so it is handed the value and renders
-it itself — see [Custom Elements](./custom-elements.md#code) for
-observing `lb-value`.
+A widget owns whatever control it wraps, so it is handed the value and
+renders it itself — see [Custom Elements](./custom-elements.md#code) for
+observing `lb-value`. A form control shows its state as its `value`, so a
+`<select>` keeps its options. Any other native element has no behavior of its
+own, so its value is its text. Checkboxes, radio buttons and file inputs
+receive nothing, not even `lb-value`, and the hub reports it to the console.
 
 Nothing an application writes ever sets `lb-value`. It is written by
-Loadbare and read by the widget it is written on.
+Loadbare and read by a widget or a stylesheet.
 
 ### Lists
 
@@ -154,7 +159,9 @@ the wire discriminant: a value beginning with `lb-` is an operation, and
 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. A cell change needs a
+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
+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
 quiet otherwise — an input inside an `lb-row-insert` or `lb-row-update` form is read
@@ -222,7 +229,35 @@ from the same ancestor a delete button reads:
 
 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.
+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:
+
+```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>
+    </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.
+
+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
+refuses it. A widget may dispatch either from any element, and the hub
+gathers the same way; see
+[Sending a request](./custom-elements.md#sending-a-request).
 
 ## Conditional rendering
 
@@ -230,9 +265,33 @@ 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.
 
-Use the standard `hidden` attribute, or CSS, and set it from a value the
-server sent. A widget that receives a value in `lb-value` is the natural
-place to do it — it is handed the current state and decides what to show:
+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:
+
+```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>
+  </tr>
+</template>
+```
+
+```css
+tr:has([lb-cell="locked"][lb-value="true"]) button {
+  display: none;
+}
+```
+
+`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.
+
+Where showing a case takes more than a selector, a widget receives the value
+in `lb-value` and decides what to show:
 
 ```ts
 for (const step of steps) step.hidden = step.dataset.step !== value;

package/docs/reference/server.md

@@ -86,6 +86,24 @@ Run the server under a TypeScript-capable runner. The builder writes
 }
 ```
 
+Node 22.18 and later also runs it with no runner at all, since Node strips
+TypeScript types itself. `dist/pages.ts` imports each `.requests.ts` and
+`.queries.ts` file by its full name, extension included, because Node looks
+for exactly the path an import names.
+
+Enable `allowImportingTsExtensions` in the application's `tsconfig.json`
+when `tsc` type-checks the server. Without it, `tsc` rejects the `.ts`
+extensions in `dist/pages.ts`:
+
+```json
+{
+  "compilerOptions": {
+    "noEmit": true,
+    "allowImportingTsExtensions": true
+  }
+}
+```
+
 Restart the server after adding or changing a `.requests.ts` or `.queries.ts`
 file.
 

package/docs/reference/widgets.md

@@ -27,9 +27,9 @@ for where a listed package sits in the cascade.
 
 Wraps an `<input>`. `lb-value` sets the input's `.value`. The widget sends
 nothing on its own: `lb-action` names what the input's `change` sends. The
-reserved `lb-cell-change` sends `lb-cell-change`, addressed by the widget's own
-`lb-list`/`lb-key-value`/`lb-cell` coordinates; any other name sends that
-action with the input's value.
+reserved `lb-cell-change` sends `lb-cell-change`; any other name sends that
+action. Either carries the input's value, and the hub adds the scope the
+input sits in.
 
 An input inside an `lb-row-insert` or `lb-row-update` form leaves the attribute off.
 The form reads every `lb-cell` in it on submit and sends one request for all

package/docs/theory.md

@@ -344,4 +344,117 @@ I wrote Loadbare originally in 2003, as "Andromeda", before Node existed
 and even 4 years before we had JQuery.  Andromeda was not nearly as
 optimized as Loadbare is now, but the principles were the same then as 
 they are now.  It has always worked for me, and I hope that it will work
-for you.
+for you.
+
+## A Consistency Model
+
+> **LLM-authored, not yet revised by a person.**  Drafted by Claude on
+> 2026-09-13, from a design session against `@loadbare/app` 0.6.0.  Treat
+> it as a proposal for this essay, not as the author's statement.
+
+### From a subjective claim to a checkable one
+
+Whether Loadbare carries less accidental complexity than another tool will
+always be disputable.  A developer fluent in React has muscle memory for its
+rules and will see Loadbare's rules as foreign, and foreign work feels
+accidental.  That objection is about familiarity, and familiarity is a cost
+paid once, in the same way this essay treats the Express boilerplate.
+
+A stronger claim can be checked, and a single counterexample in markup
+would refute it.  The model for applying data to HTML is:
+
+1. **Internally consistent.**  A few rules, each applied the same way
+   everywhere, with no exceptions.
+2. **Consistent with HTML.**  Each rule has a counterpart in how HTML
+   already behaves, and none contradicts it.
+3. **Consistent with relational data.**  What the server sends is the shape
+   a SQL query already returns, so nothing is translated on the way.
+
+### Where the vocabulary comes from
+
+This essay says the vocabulary is small because the operations a database
+affords are small and coherent.  A sharper statement is that the vocabulary
+sits where two systems that are already coherent meet: the relational model
+and HTML's containment model.  Each attribute is a relational idea placed on
+an element.
+
+| Loadbare                                 | Relational                                   | HTML precedent                                               |
+| ---------------------------------------- | -------------------------------------------- | ------------------------------------------------------------ |
+| `lb-list`                                | a relation, a set of rows                    | `<select>`, `<ul>`: a container whose contents are its items |
+| `lb-row`                                 | a single row                                 | `<form>`: one record of fields                               |
+| `lb-cell`                                | a column                                     | `name` on a control: which field this is                     |
+| `lb-key`, `lb-key-value`                 | the primary key                              | `value` on `<option>`: identity apart from the label         |
+| `lb-action`                              | a closed set of writes, and named procedures | `action` on `<form>`: where a submission goes                |
+| scope from ancestors                     |                                              | form ownership, `lang`, `<fieldset disabled>`                |
+| a nested scope begins a new one          |                                              | a nested element owns its own contents                       |
+| `lb-row-count`, `lb-pending`, `lb-error` |                                              | state attributes such as `open` on `<details>`               |
+
+### The rules
+
+1. **An element's own attributes describe what it displays.  Its ancestors
+   describe where it belongs.**  A picker carrying `lb-list` displays that
+   list, and its choice is addressed to the row it sits in, the way a
+   `<select>` displays its options and submits to the form around it.
+2. **A name answers with one shape, a row or a set of rows, and a cell holds
+   one value.**  Master-detail is a row and a list under two names.  Many
+   masters with their details is one list of joined rows, grouped for
+   display.
+3. **A value lands where the element shows its state, and a form gathers
+   from the same places.**  A widget receives `lb-value`, a form control its
+   `value`, and any other element its text.
+4. **A request is an action and a position.**  The hub supplies the position
+   from the document.  Only an interaction supplies a value.
+5. **The hub owns position and reconciliation.  A widget owns interaction and
+   placement.**
+
+### Evidence
+
+The following decisions each removed an exception or a conflict, and none
+added an attribute.  Over the same span the model gained pickers inside rows,
+native selects that show their own state, and nested lists that do not
+destroy each other.
+
+| Decision                                                      | Removed                                                                              |
+| ------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| The hub scopes every request                                  | Native requests were scoped and widget requests were not                             |
+| Scope comes from ancestors, never the element's own `lb-list` | `lb-list` meant "display" in one place and "address" in another                      |
+| A form control receives its value as `value`                  | A `<select>` was treated as text, against HTML, and landing did not mirror gathering |
+| Row and template lookups stop at a nested scope               | Cells respected nesting while rows and templates did not                             |
+| Master-detail is a row and a list                             | An open question born of document-shaped data                                        |
+| `lb-value` on every cell                                      | Only a widget's landed value was visible to a stylesheet                             |
+
+Two signs suggest these are rules rather than patches.  Fixing where a
+request's scope comes from also fixed an unrelated console error about insert
+forms, which was never worked on directly.  Making rows respect nested scopes
+needed no change to the reference, which already described that behavior.
+
+### Where the claim is not yet proven
+
+- **Parameters and view state.**  A query takes no argument from the
+  browser, so there is nowhere to put which record is selected, a filter, a
+  sort, or a collapsed section.  The model is incomplete here rather than
+  inconsistent.  If the answer is HTML's own, the URL, in the way
+  `<form method="get">` puts its fields in the query string, the claim grows
+  stronger.  If it needs a state mechanism with no HTML precedent, that will
+  be the model's first real exception.
+- **Checkboxes and radio buttons.**  HTML's boolean convention is presence or
+  absence, as with `checked`, `hidden` and `disabled`.  A rule following it
+  would avoid inventing truthiness, though it still touches data types.
+- **Data types.**  HTML attributes are strings, so comparing values as strings
+  in a stylesheet is consistent with HTML.  What is not yet reconciled is
+  that a database's typed values arrive untyped.
+- **A nested list shows the same rows in every outer row.**  That follows
+  from the second rule: one name is one relation.  Only a new outer row
+  starting with an empty nested list is a mechanical gap.
+
+### A test for every change
+
+Before a change is made, ask:
+
+- Does it remove an exception, or add one?
+- Does it have an HTML precedent?
+- Does it have a relational counterpart?
+
+Stamping every column of a row onto the row element as `data-*` fails the
+first two: attributes nobody wrote, with no precedent in HTML.  Writing
+`lb-value` on every cell passes all three.

package/docs/tutorials/072-inserting-into-a-list.md

@@ -8,20 +8,23 @@ that allows a user to add a note.
 ```html
 <!-- src/pages/about.page.html -->
 <h2>Notes</h2>
-<form lb-action="lb-row-insert" lb-list="notes">
-  <input lb-cell="text" placeholder="Write a note" />
-  <button type="submit">Add</button>
-</form>
-
-<ul lb-list="notes">
-  <template lb-key="id">
-    <li lb-cell="text"></li>
-  </template>
-</ul>
+<section lb-list="notes">
+  <form lb-action="lb-row-insert">
+    <input lb-cell="text" placeholder="Write a note" />
+    <button type="submit">Add</button>
+  </form>
+
+  <ul>
+    <template lb-key="id">
+      <li lb-cell="text"></li>
+    </template>
+  </ul>
+</section>
 ```
 
 `lb-action="lb-row-insert"` on a `<form>` gathers its `lb-cell`s into a values
-map on submit and sends them against `lb-list`. The name is one of
+map on submit and sends them against the `lb-list` around it, the way an
+`<input>` belongs to the `<form>` around it. The name is one of
 Loadbare's reserved ones — every value beginning with `lb-` is — so it
 needs no declaring, and nothing of yours may be called that. There's no `lb-key-value` — there's no row
 yet.

package/docs/tutorials/080-widget-requests.md

@@ -9,11 +9,9 @@ changes.
 
 ## Writing the widget
 
-Our new custom input will no longer rely on Loadbare's form handling,
-and so it must reimplement the data scoping logic that is in
-Loadbare.  This reimplementation approach is neither encouraged nor
-discouraged.  This tutorial shows only that it is possible, and exposes
-how Loadbare internals work.
+Our new custom input will no longer rely on Loadbare's form handling.  It
+says what happened and what its value is.  Where it sits, the list, the row
+and the cell, is added by the hub.
 
 ```html
 <!-- src/note-input.html -->
@@ -22,13 +20,7 @@ how Loadbare internals work.
 
 ```ts
 // src/note-input.browser.ts
-import {
-  ATTR_CELL,
-  ATTR_KEY_VALUE,
-  ATTR_LIST,
-  ATTR_VALUE,
-  LB_EVENT_NAME,
-} from "@loadbare/app/constants";
+import { ATTR_VALUE, LB_EVENT_NAME } from "@loadbare/app/constants";
 
 class NoteInput extends HTMLElement {
   static observedAttributes = [ATTR_VALUE];
@@ -42,20 +34,10 @@ class NoteInput extends HTMLElement {
     this.addEventListener("change", () => {
       const input = this.querySelector("input");
       if (!input) return;
-      const list = this.closest(`[${ATTR_LIST}]`)?.getAttribute(ATTR_LIST);
-      const key = this.closest(`[${ATTR_KEY_VALUE}]`)?.getAttribute(ATTR_KEY_VALUE);
-      const cell = this.getAttribute(ATTR_CELL);
-      if (!list || !key || !cell) return;
       this.dispatchEvent(
         new CustomEvent(LB_EVENT_NAME, {
           bubbles: true,
-          detail: {
-            action: "lb-cell-change",
-            list,
-            key,
-            cell,
-            value: input.value,
-          },
+          detail: { action: "lb-cell-change", value: input.value },
         }),
       );
     });
@@ -66,9 +48,10 @@ customElements.define("note-input", NoteInput);
 ```
 
 A widget with both a `.html` and a `.browser.ts` file shares one tag name; the
-build finds each half independently. On change, it reads its own
-`lb-list`/`lb-key-value`/`lb-cell` coordinates and dispatches a `lb-cell-change`
-request itself, the way `lb-row-update` does for a whole form.
+build finds each half independently. On change, it dispatches a
+`lb-cell-change` carrying the input's value. The hub adds the list, the key
+of the row it is in and its own `lb-cell`, the same way it does for a
+`lb-row-update` form.
 
 ## Using it
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@loadbare/app",
   "description": "High performance web app framework for server-bound applications",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "type": "module",
   "files": [
     "dist",
@@ -32,7 +32,7 @@
     "prebuild": "node --eval \"fs.rmSync('dist',{recursive:true,force:true})\" --input-type=module",
     "build:server": "tsc --project tsconfig.build.json",
     "build": "npm run build:server",
-    "postbuild": "node --eval \"fs.chmodSync('dist/build/cli.js', 0o755)\" --input-type=module",
+    "postbuild": "node --eval \"fs.chmodSync('dist/build/cli.js', 0o755)\" --input-type=module && node ../../scripts/check-dist-imports.mjs",
     "test": "tsx --test \"tests/**/*.test.ts\"",
     "typecheck": "tsc --noEmit",
     "format": "prettier --write .",

package/dist/tests/assemble.test.d.ts

@@ -1,8 +0,0 @@
-/**
- * Assembling a chrome file and its pages — see build/assemble.ts.
- *
- * The chrome and pages together are one write to a temp tree per test,
- * since assemble() reads from disk rather than taking sources in memory.
- */
-export {};
-//# sourceMappingURL=assemble.test.d.ts.map

package/dist/tests/assemble.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"assemble.test.d.ts","sourceRoot":"","sources":["../../tests/assemble.test.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}