@loadbare/app 0.9.0 → 0.11.0

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

@@ -1,17 +1,41 @@
-# Widget Requests
+# Committing a Control
 
-Our list example showed the use of forms and submit.  The inputs
-were passive in the sense that they did not trigger any change on their
-own.
+Our list example saved a note with a form and a Save button.  A control can
+also commit itself: an `<input>`, `<select>` or `<textarea>` carrying
+`lb-request` commits on `change`, and sends its own value alone.
 
-Now we will see how to make a widget that fires events when its value
-changes.
+Then we will write a custom element that works as a control, so it commits
+the same way.
 
-## Writing the widget
+## Committing an input
 
-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/pages/about.page.html -->
+<ul lb-query="notes">
+  <template>
+    <li>
+      <input lb-column="text" lb-request="lb-row-update" />
+      <button lb-request="lb-row-delete">Delete</button>
+    </li>
+  </template>
+</ul>
+```
+
+The form and the Save button are gone.  The input carries `lb-column`, so
+the hub gathers its value alone, as `values` with one member, `text`.  It
+takes `key` from the live row the input is in.  The request is the same
+`lb-row-update` the form sent in
+[Updating a List Item](./076-updating-a-list-item.md), so the `rowUpdate`
+written there answers it unchanged.  A `rowUpdate` sets the columns
+`values` names and leaves the rest alone, as an SQL `UPDATE` does, so one
+handler serves a form and a single control alike.
+
+## Writing a custom control
+
+A custom element is a control when it is form-associated, has a `value`
+property, and fires `change`.  The hub then treats it exactly as it treats
+an `<input>`: it sets its `value` when a row lands, gathers its `value`
+when a request is issued, and commits it on `change`.
 
 ```html
 <!-- src/note-input.html -->
@@ -20,63 +44,67 @@ and the cell, is added by the hub.
 
 ```ts
 // src/note-input.browser.ts
-import { ATTR_VALUE, LB_EVENT_NAME } from "@loadbare/app/constants";
+import { ATTR_COLUMN_VALUE } from "@loadbare/app/constants";
 
 class NoteInput extends HTMLElement {
-  static observedAttributes = [ATTR_VALUE];
+  static formAssociated = true;
+  static observedAttributes = [ATTR_COLUMN_VALUE];
+
+  constructor() {
+    super();
+    this.addEventListener("change", (e) => {
+      if (e.target === this) return;
+      e.stopPropagation();
+      this.dispatchEvent(new Event("change", { bubbles: true }));
+    });
+  }
 
-  attributeChangedCallback(_name: string, _old: string, value: string) {
+  get value(): string {
+    return this.querySelector("input")?.value ?? "";
+  }
+
+  set value(value: string) {
     const input = this.querySelector("input");
     if (input) input.value = value;
   }
 
-  connectedCallback() {
-    this.addEventListener("change", () => {
-      const input = this.querySelector("input");
-      if (!input) return;
-      this.dispatchEvent(
-        new CustomEvent(LB_EVENT_NAME, {
-          bubbles: true,
-          detail: { action: "lb-row-update", value: input.value },
-        }),
-      );
-    });
+  attributeChangedCallback(_name: string, _old: string, value: string) {
+    this.value = value ?? "";
   }
 }
 
 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 dispatches a
-`lb-row-update` carrying the input's value. The hub adds the list and the key
-of the row it is in, and turns the value into a `values` map holding only
-the widget's own `lb-cell`.
+A custom element with both a `.html` and a `.browser.ts` file shares one
+tag name; the build finds each half independently.
+
+`static formAssociated = true` makes the element a form-associated custom
+element, so a form it sits in is its form owner, and the form gathers it.
+The inner `<input>`'s own `change` is stopped at the element, which fires
+`change` from itself, so the element carrying `lb-request` is the one that
+commits.
+
+The hub stamps `lb-column-value` with every value it lands.  Rendering from
+that stamp covers a row the hub fills before the element is upgraded, when
+the element is not yet a control and receives the stamp alone.
 
 ## Using it
 
 ```html
 <!-- src/pages/about.page.html -->
-<ul lb-list="notes">
-  <template lb-key="id">
+<ul lb-query="notes">
+  <template>
     <li>
-      <note-input lb-cell="text"></note-input>
-      <button lb-action="lb-row-delete">Delete</button>
+      <note-input lb-column="text" lb-request="lb-row-update"></note-input>
+      <button lb-request="lb-row-delete">Delete</button>
     </li>
   </template>
 </ul>
 ```
 
-The `lb-row-update` form and Save button are gone — `note-input` commits on
-every change, so there's nothing left to batch.
-
-## Answering it server-side
-
-There is nothing to add. The request is the same `lb-row-update` the form
-sent in [Updating a List Item](./076-updating-a-list-item.md), with `values`
-holding only `text`, so the `rowUpdate` written there answers it unchanged.
-A `rowUpdate` sets the columns `values` names and leaves the rest alone, as
-an SQL `UPDATE` does, so one handler serves a form and a widget alike.
+Inside a form, leave `lb-request` off the control.  The form gathers it on
+submit along with every other control it owns.
 
 ## Run it
 

package/docs/tutorials/090-using-widget-libraries.md

@@ -1,12 +1,11 @@
 # Using Widget Libraries
 
-[Displaying a List](./070-displaying-a-list.md) already installed one widget
-library, `@loadbare/widgets`. This tutorial covers what that step actually
-did, and why it is the same step for a library from anywhere else.
+This tutorial installs one widget library, `@loadbare/widgets`, and covers
+why installing a library from anywhere else is the same step.
 
 [Custom Element Code](./060-custom-element-code.md) and
-[Widget Requests](./080-widget-requests.md) wrote widgets by hand, one
-file per tag, discovered because the tag turned up in a page. A widget
+[Committing a Control](./080-widget-requests.md) wrote custom elements by
+hand, one file per tag, discovered because the tag turned up in a page. A widget
 installed from a package works the same way once the package is listed —
 listing the package is the only new piece.
 
@@ -41,57 +40,58 @@ package says where to look; it does not import anything on its own.
 ## Using a tag
 
 Once the package is listed, a tag from the library is used exactly like a
-widget written by hand — the query scope and cell attributes work the same
-regardless of where the script came from:
+custom element written by hand — `lb-query`, `lb-column` and `lb-request`
+work the same regardless of where the script came from:
 
 ```html
 <!-- src/pages/index.page.html -->
-<div lb-row="status">
-  <lb-select lb-cell="state">
+<div lb-query="status">
+  <lb-select lb-column="state" lb-request="lb-row-update" exp-label="State">
     <option value="open">Open</option>
     <option value="closed">Closed</option>
   </lb-select>
 </div>
 ```
 
-`lb-select` follows the `lb-value` contract
-[Custom Element Code](./060-custom-element-code.md) described: the hub
-writes the query result to `lb-value`, and the widget's own class —
-imported from `@loadbare/widgets`, not written in this
-application — reacts to it.
+`lb-select` is a form-associated control, like the `note-input`
+[Committing a Control](./080-widget-requests.md) wrote: the hub sets its
+`value` from the row, and it commits `lb-row-update` on `change`.  Its
+class is imported from `@loadbare/widgets`, not written in this
+application.  `exp-label` fills the widget's `<label>` at build time.
 
 ## The unknown-page dialog, as a widget
 
 [Pages and Navigation](./010-pages-and-navigation.md) wrote a
-`<dialog lb-unknown-page>` by hand.  The library ships the same dialog as a
+`<dialog lb-url-unknown>` by hand.  The library ships the same dialog as a
 widget, so a chrome that lists the package can replace the dialog with one
 tag:
 
 ```html
 <lb-hub>
   <nav>
-    <a href="/" lb-nav-link>Home</a>
-    <a href="/about" lb-nav-link>About</a>
+    <a href="/" lb-url-link>Home</a>
+    <a href="/about" lb-url-link>About</a>
   </nav>
   <main></main>
   <lb-unknown-page></lb-unknown-page>
 </lb-hub>
 ```
 
-Its definition is the dialog, already scoped to the hub's `lb-navigation`
-query and carrying both of its cells.  Nothing else changes: the hub still
-finds a `<dialog lb-unknown-page>` inside itself and opens it on a miss.
+Its definition is the dialog, a `<dialog lb-url-unknown lb-query="lb-url">`
+showing the `lb-path` column of the hub's own `lb-url` query.  Nothing else
+changes: the hub still finds a `<dialog lb-url-unknown>` inside itself and
+opens it on a miss.
 
 ## Where this stops
 
 This only covers consuming a published widget, not writing one for
 publication — that's the same class shape
 [Custom Element Code](./060-custom-element-code.md) and
-[Widget Requests](./080-widget-requests.md) already wrote, packaged and
+[Committing a Control](./080-widget-requests.md) already wrote, packaged and
 given an import specifier instead of living in an application's `src/`.
 It doesn't cover `lb-table`'s footer destination or `lb-picker`'s
 expansion parameters, which are in
 [The Basic Widget Library](../reference/widgets.md).
 
 ---
-Prev: [Widget Requests](./080-widget-requests.md)
+Prev: [Committing a Control](./080-widget-requests.md)

package/docs/what-does-loadbare-extend.md

@@ -0,0 +1,124 @@
+# What Does Loadbare Extend?
+
+> **LLM-authored, not yet revised by a person.**  Drafted by Claude on
+> 2026-09-27 against `@loadbare/app` 0.10.0.
+
+The question: what is `@loadbare/app`'s foundation, the thing it adds to
+rather than replaces, and does the package stand on that foundation the way
+`@loadbare/db` stands on Postgres?
+
+The short answer: the browser half of `@loadbare/app` is honestly "HTML+", in
+the same way `@loadbare/db` is "Postgres+".  The package as a whole is not.
+The framing that covers all of it, and ties it to db, is relational rather
+than HTML.
+
+## The precise reading
+
+### Where "extension to HTML" is literally true
+
+- **It uses the platform's own extension point.**  Custom elements are how
+  HTML is meant to be extended.  The whole browser runtime is one custom
+  element, `<lb-hub>`.  Custom elements are also the only way Loadbare lets an
+  application split up markup or ship behaviour.  There are no components, no
+  JSX, and no expressions evaluated at run time.
+- **The attributes copy HTML's own ideas.**  [Theory](./theory.md#data-binding)
+  already sets this out in a table:
+  - `lb-column` works like `name`.
+  - `lb-query` works like `<form>` or `<select>`, a container of records.
+  - `lb-show` works like `hidden`.
+  - `lb-key-value` works like an `<option>`'s `value` sitting apart from its
+    text.
+- **HTML decides behaviour wherever it already has an opinion.**  Commits
+  follow HTML's events: a form on submit, a control on change, anything else
+  on click.  Gathering follows the form owner, including `form="…"`.  Resets
+  go through `formResetCallback`.  Busy state uses `aria-busy`.  The unknown
+  page is a real `<dialog>`, and links are real `<a href>`.
+- **What ships is plain HTML.**  It can be read in view-source, it uses light
+  DOM, and CSS is left untouched.  A page that shows no data is just an HTML
+  file.
+- **There is historical precedent.**  IE4's `datasrc`/`datafld` really was
+  data binding added to HTML, and [Prior art](./prior-art.md) finds its
+  vocabulary maps almost one to one onto Loadbare's.
+
+### Where it is inaccurate or strained
+
+- **The attributes don't conform to the spec.**  HTML sets aside `data-*` for
+  author attributes, and a validator will flag `lb-*`.  htmx and Alpine have
+  the same problem, so it's defensible.  But a literal claim of "extension to
+  HTML" is only half true: Loadbare uses one of the sanctioned extension
+  points (custom elements) fully and skips the other (`data-*`).
+- **Build-time expansion is a preprocessor.**  `exp-` parameters and `{{…}}`
+  are a small template language that runs before HTML exists.  The output is
+  HTML; the source a developer writes is not quite HTML.
+- **Navigation overrides HTML's model on purpose.**  HTML's model is one
+  document per URL.  Loadbare ships every page as a `<template>` in one
+  document and answers every route with `app.html`, with no 404.  Keeping the
+  address bar truthful softens this, but it is still a replacement.
+- **The wire is JSON, not hypermedia.**  In the ecosystem, "extends HTML"
+  usually means htmx's argument that HTML is unfinished hypertext.  Loadbare
+  rejects that model after the first load.  Calling it an HTML extension
+  invites exactly the comparison [Theory](./theory.md) spends paragraphs
+  getting out of.
+- **Half of what a developer writes isn't HTML.**  `queries.ts` and
+  `requests.ts`, with `row`/`rows`/`patch`, crud entries and refresh lists,
+  have no HTML counterpart at all.
+
+## The db comparison
+
+db earns "Postgres+" because it passes four tests:
+
+1. What it builds is plain Postgres, inspectable with psql.
+2. Its vocabulary extends Postgres's own concepts: the foreign key becomes the
+   channel for values flowing down and aggregates flowing up.
+3. A developer can drop to plain SQL anywhere.
+4. Postgres does the heavy lifting.
+
+The browser half of app passes all four:
+
+1. The output is plain HTML.
+2. The vocabulary extends `name`, `form` and `hidden`.
+3. Any HTML works, and a custom element is still just a custom element.
+4. The platform does the work: `cloneNode` of templates, the selector engine,
+   form owners, `showModal`, the History API.
+
+The rule behind it is the same as db's: **defer where the foundation has an
+answer, and add only where it is silent.**  HTML is silent about data, and
+that's where the seven attributes live.
+
+The difference is that db never overrides Postgres.  It adds to Postgres and
+replaces the application's logic layer.  app overrides HTML twice, in
+navigation and on the wire, both for the 300ms budget.  Those are deliberate
+departures, not add-ons.
+
+## How it feels
+
+- **Writing a page** feels like writing HTML: forms and tables with a few
+  attributes, much like data-bound HTML in 1999 without the ActiveX.
+- **Writing a widget** feels like writing web components.
+- **Writing `requests.ts`** feels like neither.  A nested declaration such as
+  `crud.invoiceLines.rowDelete.{run, refresh}` feels like a framework's
+  configuration map.  db has no equivalent seam, because its DSL reads as DDL
+  all the way down.  That file is where the "HTML+" feel breaks.
+
+## A better framing
+
+The idea that runs through every layer of app is not HTML.  It is the
+**row**: query, row, rows, column and key.  That's where the scope decision in
+[Theory](./theory.md#data-binding) lands, and it's what the protocol carries.
+HTML is the surface, and relations are the substance.
+
+Framed that way, the two packages form one story rather than two:
+
+- **db** is the relational model with derived values, built on Postgres.
+- **app** is the relational model shown and edited on screen, with HTML as its
+  surface.
+- **The row** is the only thing that crosses between them.
+
+So "Relational+ from end to end, with Postgres at one end and HTML at the
+other" is accurate everywhere.  "HTML+" is accurate only for page and widget
+authoring.  It also explains the server half: `queries.ts` and `requests.ts`
+aren't HTML because they're the relational half of the contract.
+
+"HTML+" still works as a description of how page authoring feels.  It fails
+as a statement of what the package is, and it pulls readers toward the
+hypermedia comparison Loadbare would rather avoid.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@loadbare/app",
   "description": "High performance web app framework for server-bound applications",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "type": "module",
   "files": [
     "dist",