@loadbare/app 0.9.0 → 0.10.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/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.10.0",
   "type": "module",
   "files": [
     "dist",