@loadbare/app 0.7.4 → 0.8.1

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

@@ -0,0 +1,397 @@
+# 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.
+
+| File                     | Holds                            |
+|--------------------------|----------------------------------|
+| `<tag-name>.html`        | 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
+a build error.
+
+The script says `.browser` because that is the file that crosses to the
+browser. Name it `<tag-name>.ts` and the builder leaves it alone: an
+unmarked module is server-side code as far as the build is concerned, which
+is what keeps a `stripe.ts` or a `config.ts` out of the bundle no matter what
+tag someone writes later.
+
+Custom elements are the only mechanism Loadbare offers for either purpose.
+An application decomposes its HTML by defining a tag, and delivers behavior
+to the browser by registering one; the builder recognizes no other way to do
+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
+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
+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'. 
+
+A package listed in `imports.ts` loads first and an application's own
+definitions load after, so a tag defined in both resolves to the
+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:
+
+| 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 |
+
+Pass a parameter by writing `exp-<name>` on the tag. Read it in the
+definition by writing `{{<name>}}`. The prefix marks the attribute as
+expansion's input and is not part of the parameter's name, so `exp-label`
+supplies `{{label}}`:
+
+```html
+<!-- definition: src/note-field.html -->
+<label>{{label}} <input readonly="{{readonly}}" /></label>
+```
+
+```html
+<!-- authored -->
+<note-field lb-cell="name" 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 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 —
+see [Conditional rendering](./data-binding.md#conditional-rendering) for
+what to write instead of a branch.
+
+Name a parameter in lowercase. HTML lowercases attribute names before
+expansion sees them, so `exp-inputClass` arrives as `exp-inputclass` and
+could never fill `{{inputClass}}`. Write `{{input-class}}` instead; a
+definition declaring such a name is rejected when it loads.
+
+Leave a parameter unsupplied to drop what reads it. An attribute whose
+value is a placeholder is removed rather than shipped empty, which is how
+`readonly="{{readonly}}"` works as an ordinary boolean attribute. A
+placeholder in a text node resolves to nothing, and the whitespace around
+it survives.
+
+Give a placeholder a default with a pipe: `{{button-text|OK}}` reads
+`exp-button-text` when the tag supplies it and `OK` when it does not. The
+default is a literal, not an expression. Whitespace around the name and the
+default is not part of either, so `{{ button-text | OK }}` is the same
+placeholder. An empty default, `readonly="{{readonly|}}"`, is the one that
+differs from no default at all: it emits the attribute, empty, rather than
+dropping it, so a definition can ship a boolean attribute switched on.
+
+Every attribute stays on the tag after expansion, `exp-` ones included.
+
+Parameter values reach a definition through the DOM rather than through
+string substitution, so a value is never reparsed as markup and needs no
+escaping.
+
+### The slot
+
+`lb-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>
+```
+
+```html
+<!-- authored -->
+<note-card>
+  <h3>Meeting notes</h3>
+  <p>Bring the roster.</p>
+</note-card>
+```
+
+```html
+<!-- ships -->
+<note-card>
+  <article class="card">
+    <div>
+      <h3>Meeting notes</h3>
+      <p>Bring the roster.</p>
+    </div>
+  </article>
+</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.
+
+Give a definition at most one `lb-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
+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
+fills:
+
+```html
+<!-- definition: src/ledger-table.html -->
+<table>
+  <caption>{{caption}}</caption>
+  <thead lb-template="head"></thead>
+  <tbody lb-slot></tbody>
+</table>
+```
+
+```html
+<!-- authored -->
+<ledger-table exp-caption="Ledger">
+  <template lb-template="head">
+    <tr><th>Date</th><th>Amount</th></tr>
+  </template>
+  <tbody>
+    <!-- row template -->
+  </tbody>
+</ledger-table>
+```
+
+Declare as many destinations as the definition needs, one per name. An
+author fills none, some, or all of them, and a destination nobody fills
+stays and is empty.
+
+Wrap authored content for a destination in a `<template>`, which exists only
+to survive the parser. A `<thead>` written directly inside `<ledger-table>`
+is not inside a `<table>`, so the tokenizer drops the tag before expansion
+sees it. A `<template>` survives anywhere and parses its contents as though
+already in place. What lands in the destination is the template's contents —
+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.
+
+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.
+
+### What fails at build time
+
+Each of these is reported with the tag and file name, and nothing is
+shipped:
+
+- a tag in the `LB-*` namespace with no definition
+- 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
+  does not have
+- two templates for the same destination
+
+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` |
+
+### 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:
+
+```ts
+// src/visit-count.browser.ts
+import { ATTR_VALUE } from "@loadbare/app/constants";
+
+class VisitCount extends HTMLElement {
+  static observedAttributes = [ATTR_VALUE];
+
+  attributeChangedCallback(_name: string, _old: string, value: string) {
+    this.textContent = `visited ${value} times`;
+  }
+}
+
+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.
+
+### 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`:
+
+```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 };
+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.
+
+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.
+
+### Decorating a list
+
+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.
+
+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:
+
+```ts
+import type { ListHost, Row } from "@loadbare/app/types";
+
+class SortedList extends HTMLElement implements ListHost {
+  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.
+  }
+
+  lbRowsLanded() {
+    // Once, after the result has 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>