@loadbare/app 0.12.0 → 0.14.0

package/skills/loadbare-app/references/chrome.md

@@ -72,6 +72,10 @@ Put everything the user interacts with inside `<lb-hub>`. The hub normally
 sits directly inside `<body>`, with banner, nav, footer and `<main>` inside
 it, so Loadbare can act on all of them.
 
+Write exactly one `<lb-hub>` and exactly one `<main>`, with the `<main>`
+inside the hub and empty but for whitespace.  The builder rejects a chrome
+that does otherwise.
+
 The chrome's `<title>` is the document title until the first page shows.
 From then on the hub sets the document title to the page's label; see
 [The URL](#the-url).
@@ -165,7 +169,9 @@ pushes one instead when the element carrying `lb-request` also carries
 
 The hub answers the request itself, with no round trip, then reloads the
 page's queries at the new URL. The page stays in place, and rows that come
-back keep their place.
+back keep their place. A request that changes only `lb-order-<query>`, the
+user's [order](./data-binding.md#order) for a query the hub sorts itself,
+re-sorts the rows already on the page and loads nothing.
 
 A control whose column the URL does not carry lands empty, so every control
 inside `lb-query="lb-url"` shows what the address bar says, after a reload

package/skills/loadbare-app/references/custom-elements.md

@@ -278,7 +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 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.
 
 ### What the hub and an element say to each other
 
@@ -286,9 +289,9 @@ Each direction has one mechanism for each kind of message:
 
 | Direction      | What                                       | How                         | Today |
 |----------------|--------------------------------------------|-----------------------------|-------|
-| Hub to element | State that lasts                           | An attribute the hub stamps | `lb-column-value`, `lb-key-value`, `lb-query-row-count`, `lb-request-pending`, `lb-request-error` |
+| 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     | `lbPlaceRow`, `lbRowsLanded` |
+| Hub to element | Work the hub needs done now, while landing | An optional `lb` method     | `lbRowsLanded` |
 | 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` |
 
@@ -329,7 +332,7 @@ So each kind of work has one place:
    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,
-   `lbPlaceRow` or `lbRowsLanded`, and never held from setup.
+   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
@@ -409,9 +412,104 @@ 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
@@ -491,7 +589,8 @@ this.addEventListener(LB_DONE_EVENT_NAME, (e) => {
 ```
 
 `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
@@ -505,34 +604,32 @@ outside the document, and no ancestor it had there hears it.
 
 ### Holding rows
 
-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.
+The hub lands every row template itself, places every row by the query's
+order, and builds every group the markup's group templates describe; see
+[Order](./data-binding.md#order) and [Groups](./data-binding.md#groups). A
+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 two
-optional methods, which the hub calls:
+A custom element carrying `lb-query` and a row template may implement one
+optional method, which the hub calls:
 
 ```ts
-import type { RowsHost, Row } from "@loadbare/app/types";
-
-class SortedList extends HTMLElement implements RowsHost {
-  lbPlaceRow(el: Element, row: Row, template: HTMLTemplateElement) {
-    // Where this live row goes. Called with the live row detached, on its
-    // first appearance and again whenever all rows decide the order.
-  }
+import type { RowsHost } from "@loadbare/app/types";
+import { ATTR_ROW_REQUESTED, REQUESTED_CREATED } from "@loadbare/app/constants";
 
+class ScrollingList extends HTMLElement implements RowsHost {
   lbRowsLanded() {
-    // 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.
+    // 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    |
-|----------------|---------------------|
-| `lbPlaceRow`   | To place a live row |
-| `lbRowsLanded` | After the rows land |
+| Method         | The hub calls it                                      |
+|----------------|-------------------------------------------------------|
+| `lbRowsLanded` | After the rows land, with every row placed and stamped |
 
 Everything else is the hub's:
 
@@ -540,25 +637,23 @@ Everything else is the hub's:
 |-------------|----------------------------------------------------------|
 | 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-row-live` and `lb-key-value` |
+| Placing     | Places every live row by the query's order               |
+| Grouping    | Builds a group where the order breaks, and removes it with its last row |
+| Removing    | Marks the live rows the response says are gone as leaving, and removes them |
+| Stamping    | Stamps each live row with `lb-row-live`, `lb-key-value`, and what happened to it |
 | 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.
+`lb-options.browser.ts` and `lb-table.browser.ts` in
+[`@loadbare/widgets`](./widgets.md) are two uses of `lbRowsLanded`: one
+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, so it has no `lbPlaceRow` when rows land
-on it then, and the hub places them before the template. 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 every row goes through `lbPlaceRow` and
-`lbRowsLanded` runs. Once upgraded it stays so: when its branch goes away and
-comes back, it has placed every row that landed meanwhile, and nothing is
-landed again.
+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 that walks its own rows finds them with `LIVE_ROW` from
 `@loadbare/app/constants`, never by `lb-key-value`: an element a `row` lands