@loadbare/app 0.13.0 → 0.15.0

package/docs/reference/custom-elements.md

@@ -278,10 +278,10 @@ 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).  The build refuses
-a script that declares a method, accessor or field whose name is `lb`, a
-capital, and anything else Loadbare does not call, so a misspelled
-`lbRowLanded` fails the build rather than never being called.
+the methods it calls; see [When its code runs](#when-its-code-runs).  The
+build refuses a script that declares a method, accessor or field whose name
+is `lb`, a capital, and anything else Loadbare does not call, so a
+misspelled `lbRowLanded` fails the build rather than never being called.
 
 ### What the hub and an element say to each other
 
@@ -291,39 +291,80 @@ Each direction has one mechanism for each kind of message:
 |----------------|--------------------------------------------|-----------------------------|-------|
 | Hub to element | State that lasts                           | An attribute the hub stamps | `lb-column-value`, `lb-key-value`, `lb-query-row-count`, `lb-group-*`, `lb-row-*`, `lb-request-pending`, `lb-request-error` |
 | Hub to element | State the platform already names           | A property                  | A control's `value` |
-| Hub to element | Work the hub needs done now, while landing | An optional `lb` method     | `lbRowsLanded` |
+| Hub to element | What the hub did                           | An optional `lb` method     | `lbAttached`, `lbRowsLanded`, `lbRequestDone`, `lbDetached` |
 | Hub to element | A moment an element started                | A bubbling event            | `lb-request-done` |
 | Element to hub | A moment                                   | A bubbling event            | `lb-request`, and `change`, `click` and `submit` |
 
-State is an attribute: a stylesheet can select on it, and an element that
-upgrades late still finds it. A method is for work the hub cannot go on
-without, done by one element at one point in landing. A moment is an event,
-because the element that cares is often an ancestor of the one it concerns,
-and an event reaches it knowing neither.
+State is an attribute, because a stylesheet can select on it. A method is
+how the hub tells one element what it just did to that element. A moment is
+an event, because the element that cares is often an ancestor of the one it
+concerns, and an event reaches it knowing neither.
 
 ### When its code runs
 
-The hub creates, places and parks elements, and each of those reaches a
-custom element as the browser's lifecycle callbacks. It is the same instance
-from its constructor on, however often it moves:
+The hub tells a custom element what it did through four optional methods,
+named for the hub's own work. The `HubLifecycle` interface in
+`@loadbare/app/types` declares them. Here is an element that closes its
+popup on Escape, listening on `document` only while the hub has it on the
+page:
 
-| What the hub does                                  | Callbacks, in order                         |
-|----------------------------------------------------|---------------------------------------------|
-| Shows a page                                       | `constructor`, `connectedCallback`          |
-| Creates a live row, filled before it is placed     | `constructor`                               |
-| Places a live row for the first time               | `connectedCallback`                         |
-| Places it again, as it does on every set of all rows | `disconnectedCallback`, `connectedCallback` |
-| Removes a live row                                 | `disconnectedCallback`                      |
-| Turns `lb-show` off                                | `disconnectedCallback`, `adoptedCallback`   |
-| Turns `lb-show` on                                 | `adoptedCallback`, `connectedCallback`      |
-| Turns on an element the builder shipped absent     | `constructor`, `connectedCallback`          |
+```ts
+// src/note-popup.browser.ts
+import type { HubLifecycle } from "@loadbare/app/types";
+
+class NotePopup extends HTMLElement implements HubLifecycle {
+  #onKey = (e: KeyboardEvent) => {
+    if (e.key === "Escape") this.querySelector("dialog")?.close();
+  };
+
+  lbAttached() {
+    document.addEventListener("keydown", this.#onKey);
+  }
 
-The builder ships every `lb-show` element inside its template, and nothing
-in a template is upgraded, so such an element has no instance until its
-column first turns on. See
-[Conditional rendering](./data-binding.md#conditional-rendering).
+  lbDetached() {
+    document.removeEventListener("keydown", this.#onKey);
+  }
+}
+
+customElements.define("note-popup", NotePopup);
+```
 
-So each kind of work has one place:
+| Method                          | The hub calls it                                                  |
+|---------------------------------|-------------------------------------------------------------------|
+| `lbAttached()`                  | Once, after it places the element and every column has landed on it |
+| `lbRowsLanded()`                | After rows land on the element, with every row placed and stamped |
+| `lbRequestDone(detail, origin)` | After a request committed by the element, or inside it, has finished |
+| `lbDetached()`                  | Once, after it removes the element                                |
+
+The hub places an element when it starts up the chrome, shows a page,
+creates a live row, or builds a group. It places the chrome and a page as
+the page's first answer lands, or once that round trip fails, so an element
+in either hears `lbAttached` with the page's data in place. It removes an
+element when a live row or a group has finished leaving, and when it shows
+another page in place of the one holding it. Write setup in `lbAttached` and its undoing in
+`lbDetached`; the two pair exactly, so neither guards against running
+twice.
+
+Moving a row and turning `lb-show` off and on are neither placing nor
+removing. The element keeps its instance and hears nothing. An element
+under an `lb-show` that is off is placed inside its template, so its
+`lbAttached` runs whether or not it shows. Measure and focus when the user
+acts, never in `lbAttached`, where the element may not be rendered.
+
+The hub calls `lbAttached` on an outer custom element before the ones
+inside it, and `lbDetached` on the inner ones first. A table that sets the
+`form` attribute on its controls in `lbAttached` does so before each control
+hears its own.
+
+An element a script creates hears none of the four, and neither does the
+copy of a moved row the hub leaves behind while it fades. The hub calls
+them only on what it places.
+
+Never write `connectedCallback`, `disconnectedCallback`, `adoptedCallback`
+or `connectedMoveCallback`. The browser calls those on every move, and the
+build refuses a script that declares one.
+
+Each kind of work then has one place:
 
 1. **A listener on the element itself goes in the constructor.** It is
    attached once and survives every move, and a live row gets its own
@@ -331,15 +372,11 @@ So each kind of work has one place:
    element, so the listener needs no child to exist yet. The constructor
    reads no attribute and no child: an element made with
    `document.createElement` has neither when it runs.
-2. **A child is looked up when it is needed**, in a handler, a getter,
-   or `lbRowsLanded`, and never held from setup.
-3. **`connectedCallback` runs on every move**, so it is written to run
-   again. It rearranges the element's own children into a state it checks
-   for first, or adds a listener to `document` or `window`, which
-   `disconnectedCallback` removes. Work done once per instance that needs
-   the element's attributes, such as a control taking up a value that landed
-   before it upgraded, goes behind a flag there; see
-   [Being a control](#being-a-control).
+2. **A child is looked up when it is needed**, in a handler, a getter, or
+   one of the four methods, and never held from setup.
+3. **Work done once per instance goes in `lbAttached`**, with its undoing
+   in `lbDetached`: rearranging the element's own children, or a listener on
+   `document` or `window`.
 
 ### Being a control
 
@@ -350,20 +387,10 @@ and commits its `lb-request` on `change`:
 
 ```ts
 // src/star-rating.browser.ts
-import { ATTR_COLUMN_VALUE } from "@loadbare/app/constants";
-
 class StarRating extends HTMLElement {
   static formAssociated = true;
   #internals = this.attachInternals();
   #value = "";
-  #connected = false;
-
-  connectedCallback() {
-    if (this.#connected) return;
-    this.#connected = true;
-    const stamped = this.getAttribute(ATTR_COLUMN_VALUE);
-    if (stamped !== null) this.value = stamped;
-  }
 
   get value(): string {
     return this.#value;
@@ -399,22 +426,109 @@ customElements.define("star-rating", StarRating);
 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 control can receive its value before it is a control. An element the
-builder shipped absent, or one whose definition loads after the hub has
-landed, is not upgraded when its column lands, so the hub cannot set its
-`value` and the value arrives as `lb-column-value` alone. Take the stamp up
-the first time the control connects, as `connectedCallback` does above, and
-never again: after that the hub sets `value` itself, and a later move must
-not undo an edit.
-
 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.
 
+A control takes the message of a refusal naming its column when it has
+`setCustomValidity` and `reportValidity`, as a native control does; see
+[Refusals](./data-binding.md#refusals). A control wrapping a native one
+passes both to it, so the browser shows the message there and focus lands
+there.
+
 The `<lb-input>`, `<lb-select>`, `<lb-options>` and `<lb-picker>` widgets
 are controls; see [The Basic Widget Library](./widgets.md).
 
+### Example: a file's text as a value
+
+The hub takes no file input as a control. A custom element wraps one and is
+the control in its place. This one reads the chosen file as text, which
+suits a CSV or a bank statement, and sends the file's name under a second
+column:
+
+```html
+<!-- src/file-text.html -->
+<label>{{label}} <input type="file" accept="{{accept}}" /></label>
+<input type="hidden" lb-column="{{name-column}}" />
+```
+
+```ts
+// src/file-text.browser.ts
+class FileText extends HTMLElement {
+  static formAssociated = true;
+  #internals = this.attachInternals();
+  #value = "";
+
+  constructor() {
+    super();
+    this.addEventListener("change", (e) => {
+      const input = e.target as HTMLInputElement;
+      if (e.target === this || input.type !== "file") return;
+      e.stopPropagation();
+      void this.read(input);
+    });
+  }
+
+  get value(): string {
+    return this.#value;
+  }
+
+  set value(value: string) {
+    this.#value = value ?? "";
+    this.#internals.setFormValue(this.#value);
+  }
+
+  formResetCallback() {
+    this.value = "";
+    this.setName("");
+  }
+
+  async read(input: HTMLInputElement) {
+    const file = input.files?.[0] ?? null;
+    this.value = file ? await file.text() : "";
+    this.setName(file?.name ?? "");
+    this.dispatchEvent(new Event("change", { bubbles: true }));
+  }
+
+  setName(name: string) {
+    const hidden = this.querySelector<HTMLInputElement>('input[type="hidden"]');
+    if (hidden) hidden.value = name;
+  }
+}
+
+customElements.define("file-text", FileText);
+```
+
+```html
+<!-- src/uploads.page.html -->
+<form lb-query="uploads" lb-request="lb-row-insert">
+  <file-text
+    lb-column="filetext"
+    exp-name-column="filename"
+    exp-label="Statement file"
+    exp-accept=".csv,.ofx"
+  ></file-text>
+  <button type="submit">Upload</button>
+</form>
+```
+
+Reading a file is asynchronous, so the element stops the file input's own
+`change` and fires its own once the text is in hand. A form submitted before
+then gathers the empty value, and the handler refuses it as no file.
+
+A control gathers one column, so the name rides in a hidden input that the
+hub gathers as a control of its own. The form gathers both on submit. Its
+reset after the insert clears the file input but not the hidden one, whose
+`value` is its default, so `formResetCallback` clears the name itself.
+
+The text travels in the request's JSON body, which `hubRoutes` limits to
+100 KB unless the server raises it; see [Options](./server.md#options).
+
+The choices here are this application's: text rather than binary, the whole
+file in the request, the name in a second column. A different application
+writes its own element, under its own name, to make different ones.
+
 ### Receiving a value
 
 A custom element that is not a control keeps the content the builder placed
@@ -476,35 +590,42 @@ Let the event bubble, so an ancestor can stop it before the hub sends it.
 ### Hearing how it turned out
 
 Once what a request brought back has landed, or its round trip has failed,
-the hub dispatches `lb-request-done` from the element that committed. It
-bubbles, so the element that cares need not be the one that committed: a
-dialog hears it from the form inside it.
+the hub calls `lbRequestDone(detail, origin)` on the custom element that
+committed and on every custom element around it, innermost first. `origin`
+is the element that committed, so the element that cares need not be the
+one that committed: a dialog hears it from the form inside it.
 
 ```ts
-import { LB_DONE_EVENT_NAME } from "@loadbare/app/constants";
-import type { HubRequestDone } from "@loadbare/app/types";
-
-this.addEventListener(LB_DONE_EVENT_NAME, (e) => {
-  const { request, items, error } = (e as CustomEvent<HubRequestDone>).detail;
-  if (error) return;
-  const item = items.find((i) => i.query === request.query);
-  const created = item?.patch?.rows?.[0];
-  if (created) this.choose(String(created[item!.key]));
-});
+import type { HubLifecycle, HubRequestDone } from "@loadbare/app/types";
+
+class NewRowDialog extends HTMLElement implements HubLifecycle {
+  lbRequestDone({ request, items, error }: HubRequestDone) {
+    if (error) return;
+    const item = items.find((i) => i.query === request.query);
+    const created = item?.patch?.rows?.[0];
+    if (created) this.choose(String(created[item!.key]));
+  }
+}
 ```
 
+The hub then dispatches `lb-request-done` from the element that committed,
+carrying the same `detail` as a bubbling `CustomEvent`, for any other
+listener. Import its name as `LB_DONE_EVENT_NAME`.
+
 `items` is every response item that landed because of the request, in
-order. An answer that moved the URL contributes its `lb-url` item, which
+order. `refusal` is set beside `error` when the handler refused the
+request, holding its `message` and `columns`. An answer that moved the URL contributes its `lb-url` item, which
 carries a key only the server knew, and the page load. `error` is set when
 the round trip failed, and then nothing landed. A new row's key is in the
 answer only when the handler returned it in a patch: a refresh sends all
 rows, and nothing marks which one is new.
 
-By the time the event is dispatched, `lb-request-pending` is gone and the
-page is as the answer left it. A request that was never sent, because the
-hub or an ancestor stopped it, gets no `lb-request-done`. An element the
-answer removed, such as the row a delete took away, dispatches the event
-outside the document, and no ancestor it had there hears it.
+By the time either is called, `lb-request-pending` is gone and the page is
+as the answer left it. A request that was never sent, because the hub or an
+ancestor stopped it, gets neither. An element the answer removed, such as
+the row a delete took away, is outside the document by then: no ancestor it
+had there hears the event, and no custom element the hub has removed hears
+`lbRequestDone`.
 
 ### Holding rows
 
@@ -515,26 +636,22 @@ plain element carrying `lb-query` with a row template inside it needs no
 code, so a custom element holds rows only to do something with them once
 they land.
 
-A custom element carrying `lb-query` and a row template may implement one
-optional method, which the hub calls:
+A custom element carrying `lb-query` and a row template implements
+`lbRowsLanded`, which the hub calls once the rows have landed, with every
+row placed and stamped:
 
 ```ts
-import type { RowsHost } from "@loadbare/app/types";
+import type { HubLifecycle } from "@loadbare/app/types";
 import { ATTR_ROW_REQUESTED, REQUESTED_CREATED } from "@loadbare/app/constants";
 
-class ScrollingList extends HTMLElement implements RowsHost {
+class ScrollingList extends HTMLElement implements HubLifecycle {
   lbRowsLanded() {
-    // Once, after the rows have landed, every row placed and stamped.
     this.querySelector(`[${ATTR_ROW_REQUESTED}="${REQUESTED_CREATED}"]`)
       ?.scrollIntoView({ block: "nearest" });
   }
 }
 ```
 
-| Method         | The hub calls it                                      |
-|----------------|-------------------------------------------------------|
-| `lbRowsLanded` | After the rows land, with every row placed and stamped |
-
 Everything else is the hub's:
 
 | Concern     | The hub                                                  |
@@ -553,11 +670,9 @@ gives each option and `<optgroup>` what landing does not, a value and a
 label, and the other scrolls to the row the page's request created or
 moved.
 
-A custom element the builder shipped absent under `lb-show` has not
-upgraded while its column is off, and the hub places the rows that land on
-it then as it places any. When the column first turns on and the element
-upgrades, the hub lands the query's last answer on it again, as all rows,
-so `lbRowsLanded` runs.
+A custom element under an `lb-show` that is off still holds its rows. The
+hub places the rows that land on it then as it places any, and calls its
+`lbRowsLanded`, so it returns current.
 
 A custom element that walks its own rows finds them with `LIVE_ROW` from
 `@loadbare/app/constants`, never by `lb-key-value`: an element a `row` lands