@loadbare/app 0.9.0 → 0.10.0

package/docs/reference/custom-elements.md

@@ -1,12 +1,12 @@
 # Custom Elements
 
-A widget is a custom element, written as a set of files sharing one tag
-name. It serves two purposes, and an application uses it for either or for
-both at once.
+A custom element is written as a set of files sharing one tag name. It
+serves two purposes, and an application uses it for either or for both at
+once.
 
 | File                     | Holds                            |
 |--------------------------|----------------------------------|
-| `<tag-name>.html`        | The markup the tag expands into  |
+| `<tag-name>.html`        | The element file: the markup the tag expands into |
 | `<tag-name>.browser.ts`  | The class the tag registers      |
 
 Write one of the two, or both, but write at least one. A tag with neither is
@@ -26,13 +26,13 @@ either.
 Put the files anywhere under `src/`. The builder finds them by name, the
 same way it finds pages — see [The Builder](./builder.md).
 
-Loadbare uses light DOM throughout. A widget's markup is ordinary markup in
+Loadbare uses light DOM throughout. A custom element's markup is ordinary markup in
 the document, visible in view-source, reachable by `closest()` and by the
 application's stylesheets.
 
 ## HTML
 
-An `.html` file named for a tag defines that tag. When the builder finds the
+An element file is an `.html` file named for a tag, and defines that tag. When the builder finds the
 tag in the chrome, in a page, or in another definition, it inserts the
 definition's content as children of the tag.  We call this process 
 'HTML expansion'. 
@@ -44,13 +44,13 @@ application's.
 ### Parameters
 
 A definition takes parameters. Three namespaces share the attributes of a
-widget tag, and the prefix says which namespace an attribute is in:
+custom element's tag, and the prefix says which namespace an attribute is in:
 
-| Prefix      | Belongs to | Read                        |
-|-------------|------------|-----------------------------|
-| `exp-`      | Expansion  | By the builder, at build time |
-| `lb-`       | The hub    | By Loadbare, in the browser |
-| No prefix   | HTML       | By the browser, as HTML says |
+| Prefix      | Belongs to | Read                          |
+|-------------|------------|-------------------------------|
+| `exp-`      | The definition | By the builder, at build time |
+| `lb-`       | Loadbare   | By the builder and the hub    |
+| No prefix   | HTML       | By the browser, as HTML says  |
 
 Pass a parameter by writing `exp-<name>` on the tag. Read it in the
 definition by writing `{{<name>}}`. The prefix marks the attribute as
@@ -64,11 +64,11 @@ supplies `{{label}}`:
 
 ```html
 <!-- authored -->
-<note-field lb-cell="name" exp-label="Name"></note-field>
+<note-field exp-label="Name"></note-field>
 ```
 
-Write `class`, `title`, or any other unprefixed attribute on a widget
-freely. They are HTML's, and never collide with a definition's parameters.
+Write `class`, `title`, or any other unprefixed attribute on a custom
+element freely. They are HTML's, and never collide with a definition's parameters.
 
 Write a placeholder as an entire attribute value or an entire text node.
 Nothing inside one is evaluated, and expansion has no data to branch on —
@@ -102,12 +102,12 @@ escaping.
 
 ### The slot
 
-`lb-slot` marks the one element in a definition whose children receive
+`lb-exp-slot` marks the one element in a definition whose children receive
 whatever the author wrote inside the tag:
 
 ```html
 <!-- definition: src/note-card.html -->
-<article class="card"><div lb-slot></div></article>
+<article class="card"><div lb-exp-slot></div></article>
 ```
 
 ```html
@@ -130,35 +130,35 @@ whatever the author wrote inside the tag:
 </note-card>
 ```
 
-The tag stays and the definition becomes its children. `lb-slot` itself is
-gone from what ships, having done its job at build time.
+The tag stays and the definition becomes its children. The builder removes
+`lb-exp-slot` from what ships.
 
-Give a definition at most one `lb-slot`. A definition with a slot and
+Give a definition at most one `lb-exp-slot`. A definition with a slot and
 nothing written inside it leaves the slot empty.
 
-`lb-slot` is an attribute rather than an element because HTML's content
+`lb-exp-slot` is an attribute rather than an element because HTML's content
 model discards foreign elements inside `<select>` and `<table>`. A slot
 marker has to survive on an element the surrounding tag already permits.
 
 ### Destinations
 
-`lb-template` names a destination in a definition. On an authored
-`<template lb-template="name">`, it names the destination that template
+`lb-exp-template` names a destination in a definition. On an authored
+`<template lb-exp-template="name">`, it names the destination that template
 fills:
 
 ```html
 <!-- definition: src/ledger-table.html -->
 <table>
   <caption>{{caption}}</caption>
-  <thead lb-template="head"></thead>
-  <tbody lb-slot></tbody>
+  <thead lb-exp-template="head"></thead>
+  <tbody lb-exp-slot></tbody>
 </table>
 ```
 
 ```html
 <!-- authored -->
 <ledger-table exp-caption="Ledger">
-  <template lb-template="head">
+  <template lb-exp-template="head">
     <tr><th>Date</th><th>Amount</th></tr>
   </template>
   <tbody>
@@ -180,15 +180,15 @@ an ordinary `<thead>` in view-source — not the template element.
 
 ### Recursion
 
-A definition may use other widgets. Expansion repeats until nothing new
-appears, so a widget built out of other widgets needs nothing declared for
-it.
+A definition may use other custom elements. Expansion repeats until nothing
+new appears, so a custom element built out of others needs nothing declared
+for it.
 
 Keep the definition graph acyclic. A cycle is a build error, reported as the
 path that closes it.
 
-Expansion runs over `<template>` contents wherever they occur, so a widget's
-row template ships already expanded, `{{placeholder}}` included.
+Expansion runs over `<template>` contents wherever they occur, so a
+definition's row template ships already expanded, `{{placeholder}}` included.
 
 ### What fails at build time
 
@@ -199,9 +199,9 @@ shipped:
 - a cycle in the definition graph
 - an `exp-` attribute the definition never declared
 - a `{{placeholder}}` spelled so that no `exp-` attribute could supply it
-- content written inside a tag whose definition has no `lb-slot`
-- more than one `lb-slot` in one definition
-- a `<template lb-template="name">` naming a destination the definition
+- content written inside a tag whose definition has no `lb-exp-slot`
+- more than one `lb-exp-slot` in one definition
+- a `<template lb-exp-template="name">` naming a destination the definition
   does not have
 - two templates for the same destination
 
@@ -209,44 +209,109 @@ An unfilled `{{placeholder}}` is not among these. That is presence
 propagation working as intended, indistinguishable from an author who left
 an optional parameter out.
 
+
 ## Code
 
-A `<tag>.browser.ts` file registers that tag's class. A widget is an
-ordinary custom element — Loadbare imposes no base class — and it takes part
-in data binding through three contracts: it receives a value, it sends a
-request, and it accepts a set of rows.
-
-Import every attribute name from `@loadbare/app/constants`. Never write one
-as a string literal.
-
-| Constant         | Value      |
-|------------------|------------|
-| `ATTR_VALUE`     | `lb-value` |
-| `ATTR_CELL`      | `lb-cell`  |
-| `ATTR_SHOW`      | `lb-show`  |
-| `ATTR_LIST`      | `lb-list`  |
-| `ATTR_ROW`       | `lb-row`   |
-| `ATTR_KEY`       | `lb-key`   |
-| `ATTR_KEY_VALUE` | `lb-key-value` |
-| `ATTR_ACTION`    | `lb-action`|
-| `ACTION_ROW_INSERT`, `ACTION_ROW_DELETE`, `ACTION_ROW_UPDATE` | the reserved `lb-action` values |
-| `LB_ACTIONS`     | all three 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` |
+A `<tag>.browser.ts` file registers that tag's class. The class is an
+ordinary custom element, and Loadbare imposes no base class. A custom element
+takes part in data binding in one of four ways: it is a control, it renders
+a value, it sends a request, or it holds rows.
+
+Import every Loadbare name from `@loadbare/app/constants`, and never write
+one as a string literal:
+
+| Constant               | Value                |
+|------------------------|----------------------|
+| `ATTR_QUERY`           | `lb-query`           |
+| `ATTR_COLUMN`          | `lb-column`          |
+| `ATTR_SHOW`            | `lb-show`            |
+| `ATTR_REQUEST`         | `lb-request`         |
+| `ATTR_COLUMN_VALUE`    | `lb-column-value`    |
+| `ATTR_KEY_VALUE`       | `lb-key-value`       |
+| `ATTR_QUERY_ROW_COUNT` | `lb-query-row-count` |
+| `ATTR_REQUEST_PENDING` | `lb-request-pending` |
+| `ATTR_REQUEST_ERROR`   | `lb-request-error`   |
+| `REQUEST_ROW_INSERT`, `REQUEST_ROW_UPDATE`, `REQUEST_ROW_DELETE` | The requests Loadbare provides |
+| `LB_ROW_REQUESTS`      | All three, in one array |
+| `LB_EVENT_NAME`        | `lb-request`, the event every request travels as |
+| `URL_QUERY`            | `lb-url`             |
+| `URL_COLUMN_PATH`, `URL_COLUMN_PAGE_LABEL`, `URL_COLUMN_PAGE_UNKNOWN` | `lb-path`, `lb-page-label`, `lb-page-unknown` |
+| `LB_RESERVED_PREFIX`   | `lb-`                |
+
+A custom element reads `lb-` attributes and never assigns one. The developer
+writes them in markup, and the hub and the builder write their stamps.
+
+Loadbare reserves method names beginning with `lb` on a custom element, for
+the methods it calls; see [Holding rows](#holding-rows).
+
+### Being a control
+
+A form-associated custom element with a `value` property that fires `change`
+is a control, the same as an `<input>`. The hub sets its `value` from the
+column its `lb-column` names, gathers its `value` back under that column,
+and commits its `lb-request` on `change`:
+
+```ts
+// src/star-rating.browser.ts
+class StarRating extends HTMLElement {
+  static formAssociated = true;
+  #internals = this.attachInternals();
+  #value = "";
+
+  get value(): string {
+    return this.#value;
+  }
+
+  set value(value: string) {
+    this.#value = value ?? "";
+    this.#internals.setFormValue(this.#value);
+    this.render();
+  }
+
+  formResetCallback() {
+    this.value = "";
+  }
+
+  pick(stars: number) {
+    this.value = String(stars);
+    this.dispatchEvent(new Event("change", { bubbles: true }));
+  }
+
+  render() {
+    // Draw this.#value stars.
+  }
+}
+
+customElements.define("star-rating", StarRating);
+```
+
+```html
+<star-rating lb-column="rating" lb-request="lb-row-update"></star-rating>
+```
+
+Dispatch `change` with `bubbles: true`, as a native control's does, when the
+user commits an edit. Setting `value` from the hub fires nothing.
+
+A form owns a form-associated custom element the way it owns an `<input>`,
+including through the HTML `form` attribute, so a form gathers it on submit.
+Write `formResetCallback` to restore the default value: the hub resets a form
+after a successful insert.
+
+The `<lb-input>`, `<lb-select>`, `<lb-options>` and `<lb-picker>` widgets
+are controls; see [The Basic Widget Library](./widgets.md).
 
 ### Receiving a value
 
-A bound cell lands on a widget as the `lb-value` attribute rather than as
-text — see [Data Binding](./data-binding.md#where-a-bound-value-lands).
-Observe it, and render the value however the widget renders things:
+A custom element that is not a control keeps the content the builder placed
+in it, and receives a column as its `lb-column-value` attribute. Observe it,
+and render the value:
 
 ```ts
 // src/visit-count.browser.ts
-import { ATTR_VALUE } from "@loadbare/app/constants";
+import { ATTR_COLUMN_VALUE } from "@loadbare/app/constants";
 
 class VisitCount extends HTMLElement {
-  static observedAttributes = [ATTR_VALUE];
+  static observedAttributes = [ATTR_COLUMN_VALUE];
 
   attributeChangedCallback(_name: string, _old: string, value: string) {
     this.textContent = `visited ${value} times`;
@@ -256,142 +321,103 @@ class VisitCount extends HTMLElement {
 customElements.define("visit-count", VisitCount);
 ```
 
-`value` is `null` when the attribute is removed, which the hub does to the
-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
-first render and every later refresh go through the one callback. There is
-no separate hydration path to write.
+```html
+<p lb-query="visits"><visit-count lb-column="count"></visit-count></p>
+```
+
+List `ATTR_COLUMN_VALUE` in `observedAttributes`. The browser calls
+`attributeChangedCallback` for an attribute already present when an element
+upgrades, as well as for one that changes afterward, so the first render and
+every later one go through the one callback.
+
+A custom element 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 its column while it is away, so write
+`connectedCallback` to run more than once, as a live row the hub reorders
+already requires.
 
 ### Sending a request
 
-A widget that owns its own interaction — a `<select>`'s choice rather than a
-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`:
+A custom element that carries `lb-request` and is not a control commits on
+`click`, as a button does. To send a request at a moment of its own, a
+custom element dispatches the `lb-request` event itself, a bubbling
+`CustomEvent` whose `detail` is the request:
 
 ```ts
 import { LB_EVENT_NAME } from "@loadbare/app/constants";
 import type { HubRequest } from "@loadbare/app/types";
 
-const detail: HubRequest = { action: "lb-row-update", value: input.value };
+const detail: HubRequest = { name: "archiveOld" };
 this.dispatchEvent(new CustomEvent(LB_EVENT_NAME, { bubbles: true, detail }));
 ```
 
-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.
-
-A widget that carries `lb-cell` and sends `lb-row-insert` or `lb-row-update`
-sends that one cell. The hub builds `values` from the cell's name and the
-`value` the widget sent, or reads the control the widget wraps when it sent
-none.
-
-A widget that carries no `lb-cell` doesn't read its own 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(
-  new CustomEvent(LB_EVENT_NAME, {
-    bubbles: true,
-    detail: { action: "lb-row-insert" } as HubRequest,
-  }),
-);
-```
-
-Values the widget supplies itself are kept, and nothing is gathered over
-them.
-
-When an insert succeeds, the hub resets the controls it gathered to their
-defaults, so a blank row for entering a new one is blank again without the
-widget watching the request settle. A hidden input the widget added keeps
-its value, since a hidden input's default is its value. Values the widget
-supplied in the request were not gathered, and are not reset.
+The hub completes the request from where the element sits before any
+ancestor sees the event, gathering as it does for an element carrying
+`lb-request`; see [Gathering](./data-binding.md#gathering). A field the
+element supplies in `detail` is kept. The hub does not send a request
+missing a field its name needs, and stamps the dispatching element with
+`lb-request-pending` and `lb-request-error` as it would any other.
 
-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.
+Let the event bubble, so an ancestor can stop it before the hub sends it.
 
-### Decorating a list
+### Holding rows
 
-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.
+The hub lands every row template itself. A plain element carrying `lb-query`
+with a row template inside it needs no code, so a custom element holds rows
+only when they need placement or scaffolding 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:
+A custom element carrying `lb-query` and a row template may implement two
+optional methods, which the hub calls:
 
 ```ts
-import type { ListHost, Row } from "@loadbare/app/types";
+import type { RowsHost, Row } from "@loadbare/app/types";
 
-class SortedList extends HTMLElement implements ListHost {
+class SortedList extends HTMLElement implements RowsHost {
   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.
+    // Where this live row goes. Called with the live row detached, on its
+    // first appearance and again whenever all rows decide the order.
   }
 
   lbRowsLanded() {
-    // Once, after the result has landed. For scaffolding derived from the
+    // Once, after the rows have landed. For scaffolding derived from the
     // rows: a section heading, an <optgroup>, anything that goes when its
     // last row does.
   }
 }
 ```
 
-Everything else is the hub's, and a widget never reimplements it:
-
-| Concern     | What the hub does                                       |
-|-------------|---------------------------------------------------------|
-| 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 `lb-row-count` with the number of rows showing   |
-
-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.
-
-`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 `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` 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>
+| Method         | The hub calls it    |
+|----------------|---------------------|
+| `lbPlaceRow`   | To place a live row |
+| `lbRowsLanded` | After the rows land |
+
+Everything else is the hub's:
+
+| Concern     | The hub                                                  |
+|-------------|----------------------------------------------------------|
+| Cloning     | Clones the row template once per new key                 |
+| Matching    | Fills the live row already showing that key              |
+| Removing    | Removes the live rows the response says are gone         |
+| Stamping    | Stamps each live row with `lb-key-value`                 |
+| Counting    | Stamps `lb-query-row-count` with the number of live rows |
+
+`lbPlaceRow` receives the live row already filled and not yet in the
+document, so a custom element that reads a column to decide where the row
+goes can. Without it, the hub places a live row immediately before the row
+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 landing.
+
+Style an empty query against `lb-query-row-count` rather than carrying an
+empty state in the custom element — see
+[Counting rows](./data-binding.md#counting-rows).
+
+### Filling a subtree by hand
+
+`@loadbare/app` exports `applyRow(root, row)`, the operation that lands a
+`row` on an element. Call it in a custom element that fills a subtree of its
+own rather than one the hub lands on. It sets every element carrying a
+matching `lb-column` inside `root`, outside any nested `lb-query`.