@loadbare/app 0.8.0 → 0.8.2

package/skills/loadbare-app/references/data-binding.md

@@ -0,0 +1,485 @@
+# Data Binding
+
+A page binds its elements to server data with four attributes, and asks the
+server to change that data with one more. The developer writes all five into
+the HTML; the server declares which queries it answers and which operations
+it permits, and refuses anything it has not declared.
+
+One vocabulary and one containment ladder: a list holds rows, a row holds
+cells. A column is the second axis, and it is what the value of `lb-cell` or
+`lb-key` always holds.
+
+## A page that binds data
+
+Here is a page that binds a scalar, a list, and three requests:
+
+```html
+<!-- src/pages/members.page.html -->
+<h1>Members</h1>
+
+<p lb-row="dues">Dues collected this year: <span lb-cell="total"></span></p>
+
+<section lb-list="roster">
+  <form lb-action="lb-row-insert">
+    <input lb-cell="name" placeholder="Name" />
+    <button type="submit">Add member</button>
+  </form>
+
+  <ul>
+    <template lb-key="id">
+      <li>
+        <lb-input lb-cell="name"></lb-input>
+        <button lb-action="lb-row-delete">Remove</button>
+      </li>
+    </template>
+  </ul>
+</section>
+```
+
+The queries named here — `dues` and `roster` — and the operations the page
+asks for are declared on the server; see [page files](./page-files.md).
+
+## Binding
+
+| Attribute      | Written by  | Names                                                 |
+|----------------|-------------|-------------------------------------------------------|
+| `lb-list`      | a developer | The set of rows a subtree displays                    |
+| `lb-row`       | a developer | The one row a subtree displays                        |
+| `lb-key`       | a developer | The column that identifies a row                      |
+| `lb-cell`      | a developer | The column an element displays                        |
+| `lb-show`      | a developer | The column that decides whether an element is present |
+| `lb-key-value` | the hub     | A live row's own key                                  |
+| `lb-value`     | the hub     | The value that landed on a cell                       |
+
+A binding is scoped by ancestry. Either scope attribute scopes its DOM
+children, and a nested one of either kind begins a new scope, so an element
+binds to the name on its nearest ancestor carrying one, and to the row on its
+nearest ancestor carrying `lb-key-value`. Nothing else establishes scope: an
+element outside every scope is bound to nothing and displays nothing, and a
+result never crosses into a nested scope.
+
+Which of the two a subtree writes is not a choice about display. Cardinality
+is a property of the name, so one name answers with one shape, always. A page
+that shows the roster both as a set and as a single row declares two queries,
+`rosterList` and `rosterRow`, and binds each with the attribute that matches
+what it answers with.
+
+Bind an element to a cell by putting `lb-cell` on the element that shows the
+value. Its value is a column name and never a cell name: a cell has no name
+of its own, because it is identified by its row and its column, and the row
+arrives from scope. The scope's own root counts as a cell if it carries one,
+which is how an `<option>` — whose content model is text — displays the value
+it is.
+
+An element that carries a scope and `lb-cell` both is a cell of the scope
+around it. Its own `lb-list` or `lb-row` names what it displays, and its
+ancestors name where it belongs, so a `<select lb-list="accounts"
+lb-cell="account">` in a row displays the accounts and holds that row's
+`account`. The value lands on it and is gathered from it; the cells inside
+it are the accounts', and neither.
+
+Name the same query on more than one subtree to display it in more than one
+place. Every subtree gets the result.
+
+One name is the hub's rather than the server's: `lb-navigation`, one row
+landed on every navigation with the columns `page-label` and `page-uri`. It binds the
+same way. Its name is reserved, as every value beginning with `lb-` is in
+every `lb-` attribute: the server refuses a page that declares a query so
+named — see [Where the page is](./chrome.md#where-the-page-is).
+
+A key has a name and a value, and they are two attributes. `lb-key` on a row
+template names the column that identifies a row: it is a property of the
+list, since a list without a fixed key column is meaningless, written where
+the rows land. `lb-key-value` on a row that is showing carries that row's
+value of it. A developer writes the first and never the second.
+
+### Where a bound value lands
+
+A value lands on a bound element one of three ways.
+
+| Element                                | Receives the value as             |
+|----------------------------------------|-----------------------------------|
+| A custom element                       | Its `lb-value` attribute          |
+| `<select>`, `<textarea>`, or `<input>` | Its `value`, and `lb-value`       |
+| Any other native element               | Its `textContent`, and `lb-value` |
+
+A widget owns whatever control it wraps, so it is handed the value and
+renders it itself — see [Custom Elements](./custom-elements.md#code) for
+observing `lb-value`. A form control shows its state as its `value`, so a
+`<select>` keeps its options. Any other native element has no behavior of its
+own, so its value is its text. Checkboxes, radio buttons and file inputs
+receive nothing, not even `lb-value`, and the hub reports it to the console.
+
+Nothing an application writes ever sets `lb-value`. It is written by
+Loadbare and read by a widget or a stylesheet.
+
+### Lists
+
+Write `lb-list` on any element, and a `<template>` inside it carrying
+`lb-key`. The hub clones that template once per row, fills each clone, and
+reconciles what is showing against what arrived. No widget is involved, and
+none is needed.
+
+An array is the whole set, so it decides membership and order: a row whose
+key did not arrive is gone. A patch touches only the rows it names and leaves
+every other row's contents and position alone.
+
+A widget enters only where the rows need scaffolding or placement that only
+it can decide — a `<select>` that builds an `<optgroup>` per distinct value, a
+table that sections and sorts. Such a widget carries `lb-list` itself and
+implements one or both of two optional methods; see
+[Decorating a list](./custom-elements.md#decorating-a-list) and
+[The Basic Widget Library](./widgets.md).
+
+A scope with `lb-list` and no row template displays nothing, and that is not
+an error. It is bound to the list without showing it, which is what an insert
+form naming the list it adds a row to already is.
+
+## Requests
+
+One attribute turns an interaction into a request. `lb-action` names what the
+server is asked for: an action the page declared, or one of Loadbare's
+reserved names, which are the CRUD operations.
+
+One attribute name, one wire field, one set of values. The request field
+`action` carries this attribute's value verbatim, so nothing is translated
+between the markup and the server, and the CRUD key is the same value with
+the prefix stripped and the rest camel-cased.
+
+| Written                                   | Asks for     | Carries                       |
+|-------------------------------------------|--------------|-------------------------------|
+| `lb-action="name"`                        | That action  | The scope, and what is in it  |
+| `lb-action="lb-row-delete"`               | `rowDelete`  | `list`, `key`                 |
+| `lb-action="lb-row-insert"` on a `<form>` | `rowInsert`  | `list`, `values`              |
+| `lb-action="lb-row-update"` on a `<form>` | `rowUpdate`  | `list`, `key`, `values`       |
+| `lb-action="lb-row-update"` on a widget cell | `rowUpdate` | `list`, `key`, `values` of one cell |
+
+All three operations are list operations. Each needs a key, and a key exists
+only on a live row the hub stamped inside a list, so a single-row scope is
+read-only and a declared action is the only thing it can send. An application
+that wants a writable single row declares a list that answers with one row.
+
+A name beginning with `lb-` is reserved, in `lb-action` and in either scope
+attribute alike. The server refuses a page that declares an action or a query
+so named, which is what lets a reserved name be added later without colliding
+with one an application already uses. That reservation is also the whole of
+the wire discriminant: a value beginning with `lb-` is an operation, and
+anything else is a name the page declared.
+
+The hub sends a request from a native element on the element's own event: a
+form on submit, anything else on click. An insert or update clicked from a
+button reads the form or row the button is in (see [Forms](#forms)). To
+commit one cell as it changes, put `lb-row-update` on a widget cell instead
+(see [Committing one cell](#committing-one-cell)).
+
+Declare every action on the server, and permit every operation on its list. A
+name the page has not declared, and an operation a list does not permit, are
+refused; see
+[requests, actions, CRUD](./page-files.md#requests-actions-crud).
+
+### Actions
+
+Write `lb-action` on a button to ask the server to do something that is not
+one of the three CRUD operations:
+
+```html
+<button lb-action="mailRoster">Mail the roster</button>
+```
+
+An action carries whatever binding is in scope at the element — `list` or
+`row`, whichever scoped it, plus `key` and `cell` — and nothing else. There is
+no argument list. A button carries no value, so the server computes the whole
+of the new state and the page displays only what came back.
+
+Write `lb-action` on a widget to have the widget decide what performing the
+action means. Loadbare turns a click into a request for a native element
+only, and leaves a widget to send its own — a `<select>` performs its action
+on change, not on click.
+
+### Deleting a row
+
+```html
+<button lb-action="lb-row-delete">Remove</button>
+```
+
+`lb-row-delete` needs nothing declared. The row's `lb-list` and `lb-key-value`
+are already in scope, and they are all the server needs to know which row is
+meant and whether the list permits deleting it.
+
+The hub sends it from a native element. A widget sends its own request.
+
+### Forms
+
+A `<form>` performs its `lb-action` on submit. `lb-row-insert` and `lb-row-update`
+both gather every `lb-cell` of the form into one values map, read from
+the control each cell is or wraps. A cell inside a scope nested in the form
+is that scope's and is not gathered, the same way a value landing on the
+form's row does not reach it. They differ in one thing: `lb-row-update`
+also carries the key of the row it is inside, and `lb-row-insert` carries none,
+because there is no row yet. A declared name on a form sends that action on
+submit, carrying the binding and no values.
+
+Put an `lb-row-update` form inside the row it edits, so it has that row's key
+from the same ancestor a delete button reads:
+
+```html
+<template lb-key="id">
+  <li>
+    <form lb-action="lb-row-update">
+      <input lb-cell="name" />
+      <button type="submit">Save</button>
+    </form>
+  </li>
+</template>
+```
+
+When an `lb-row-insert` succeeds, the hub resets every control it gathered
+from to its default, as `form.reset()` would, so the form is ready for the
+next entry. A failed insert leaves the entry for the user to correct, and a
+control the user changed while the request was in flight keeps the change.
+An `lb-row-update` resets nothing: the row it sent lands back on its cells.
+
+Give every `lb-cell` in a form a control to read. A cell that is neither an
+`<input>`, `<select>`, or `<textarea>` nor wraps one is left out of the
+values map, and a form with no cell to read sends nothing.
+
+An insert or update gathers the row it belongs to: the nearest `<form>`,
+`<tr>` or live row around the element that sends it, inside its scope. A
+button submits its form the same way, whatever else sits beside it.
+
+A form cannot go around a table row's controls, so there the row is the
+form. Put the action on a button in the row, and it inserts every cell in
+the row, wherever in the row the button and the cells are:
+
+```html
+<table lb-list="roster">
+  <tbody>
+    <tr>
+      <td><input lb-cell="name" /></td>
+      <td>
+        <input lb-cell="role" />
+        <button lb-action="lb-row-insert">Add</button>
+      </td>
+    </tr>
+  </tbody>
+</table>
+```
+
+An `lb-row-update` button in a live row saves that row and no other, and a
+form nested in a row gathers only the form. Anywhere else, write the form:
+cells and a button in a `<div>` belong to no row, so the hub refuses the
+request and says to put them in a `<form>`.
+
+Put these two actions on a form or a button, not on an element that holds
+the cells. A click into one of its inputs would send the row, so the hub
+refuses it. A widget may dispatch either from any element, and the hub
+gathers the same way; see
+[Sending a request](./custom-elements.md#sending-a-request).
+
+### Committing one cell
+
+Put `lb-row-update` on a widget that carries `lb-cell` to save that one cell
+whenever it changes. The shipped `<lb-input>` sends it on `change`:
+
+```html
+<template lb-key="id">
+  <tr>
+    <td><lb-input lb-cell="name" lb-action="lb-row-update"></lb-input></td>
+    <td><lb-input lb-cell="note" lb-action="lb-row-update"></lb-input></td>
+  </tr>
+</template>
+```
+
+An element carrying `lb-cell` is a record of one cell, the way a control has
+a value and a form has values. Its update carries `values` holding that cell
+alone, so an edit in one input never sends the other. It reaches the same
+`rowUpdate` a form does. SQL has one UPDATE whether it sets one column or
+many, and the application writes one handler for both.
+
+The widget decides when the cell has changed. A native `<input>` carrying
+`lb-cell` and `lb-row-update` has no such moment, since a click into it
+would send it, so the hub refuses it and says so.
+
+Leave `lb-action` off a widget inside an `lb-row-insert` or `lb-row-update`
+form. The form reads every `lb-cell` in it on submit, so a widget that also
+sent its own would write the same edit twice.
+
+## Query parms
+
+A control that narrows what the page shows writes its value into the query
+string instead of sending a request. `lb-query-parm` names the parm:
+
+```html
+<select lb-query-parm="team">
+  <option value="">Every team</option>
+  <option value="Engines">Engines</option>
+</select>
+```
+
+On `change` the hub sets that one parm in the URL, leaving every other parm
+alone, and takes it out when the value is empty. The write replaces the
+current history entry; add `lb-query-parm-push` to push one instead. The page
+then loads at the new URL, exactly as a cold load of it would, without
+replacing its DOM.
+
+After every load the hub lands each parm on the control that writes it, and
+an absent parm lands empty, so the control shows what the address bar says.
+
+A control that writes a query parm sends no request, and one that also
+carries `lb-action` has that request refused.
+
+The server reads the parms off `req.query` in `contextFor`; see
+[the Express server](./server.md#database-layer). See
+[Query parms](./TECHREF-1.0.md#query-parms) for the whole rule.
+
+## Conditional rendering
+
+Loadbare ships static HTML and hydrates elements that are already in the
+document. There is no `if`, and none is needed: write every possibility into
+the page, and let a column decide which of them is present.
+
+Write `lb-show` on an element, naming the column that decides it:
+
+```html
+<template lb-key="id">
+  <tr>
+    <td lb-cell="name"></td>
+    <td><button lb-action="lb-row-delete" lb-show="removable">Remove</button></td>
+  </tr>
+</template>
+```
+
+```sql
+(ledger_count = 0 AND system_behavior IS NULL) AS removable
+```
+
+A value of `null` or `false` takes the element out of the page, and any other
+value puts it back. The hub never reads a string, so `"false"` is a value like
+any other: have the query answer with a boolean or a null. A row that does not
+carry the column leaves the element as it is, so a query that answers with
+whole rows returns the column in every row.
+
+`lb-show` binds the way `lb-cell` does, to the row on its nearest scoped
+ancestor. On an element that is itself a scope, the column belongs to the
+row around it, so this picker takes its choices from `groups` and whether it
+is present from the account row:
+
+```html
+<select lb-list="groups" lb-cell="group_id" lb-show="group_choice">
+```
+
+An element may show a column and be decided by it, which shows a note only
+when there is one:
+
+```html
+<span lb-cell="note" lb-show="note"></span>
+```
+
+An element that is not present cannot be clicked, but that is presentation:
+the server still refuses what a request may not do.
+
+### Where an absent element is
+
+An element whose column is off is moved into a `<template lb-show>` that
+stands where it stood, and moved back out when the column turns on. The
+developer never writes that template.
+
+- Nothing renders it, whatever a stylesheet says, because a template's content
+  is not its children.
+- It cannot be focused or clicked, assistive technology does not announce it,
+  and a form does not gather it.
+- It is moved, never rebuilt, so a widget keeps its instance and a control
+  keeps what was typed into it.
+- Values keep landing on it, and on every cell and scope inside it, while it
+  is away, so it returns current.
+
+The builder ships every `lb-show` element already inside its template, so
+nothing conditional shows until its row has landed.
+
+A condition never changes the structure of a page. An absent element keeps
+its place among its siblings, so a position selector (`:first-child`,
+`:nth-child`, `:empty`, `+`, `~`) counts its template as a sibling. A selector
+by tag, class or attribute is unaffected. Only a list changes a page's
+structure.
+
+A condition that is only a style is a class on an element that is present or
+not:
+
+```html
+<span lb-show="out_of_balance" class="danger">Out of balance</span>
+```
+
+These are build errors:
+
+- `lb-show` on a row template's root. A row that should not show is left out
+  by the query.
+- `lb-show` with no row around it: outside every scope, on a scope with none
+  around it, or in a list scope outside its row template, where nothing lands.
+- `lb-show` on a `<template>`.
+
+A condition that is not data, such as a collapsed section or an open menu,
+has no column. Use `<details>`, a stylesheet, or a widget. Every cell still
+carries the value that landed on it as `lb-value`, for a widget to read or a
+stylesheet to select on.
+
+### An empty list
+
+The hub stamps every list scope with `lb-row-count`, the number of rows it is
+showing. It is the one conditional a page cannot be sent, because the server
+answers with rows and says nothing about how many survived. It makes an empty
+list a stylesheet rule rather than code anywhere:
+
+```html
+<div lb-list="roster">
+  <ul>
+    <template lb-key="id">
+      <li lb-cell="name"></li>
+    </template>
+  </ul>
+  <p class="roster-empty">No members yet.</p>
+</div>
+```
+
+```css
+.roster-empty {
+  display: none;
+}
+[lb-row-count="0"] .roster-empty {
+  display: revert;
+}
+```
+
+The scope is a `<div>` here rather than the `<ul>`, so that the empty message
+is inside it and the same rule can reach both.
+
+## Request state
+
+Loadbare stamps two attributes on the element a request came from — the
+button, the form, or the widget itself:
+
+| Attribute         | Means                                     |
+|-------------------|-------------------------------------------|
+| `lb-pending` | The request is in flight                  |
+| `lb-error`   | The last request from this element failed |
+
+`lb-pending` is set when the request goes out and removed when it
+settles. `lb-error` is set on a failed response, a network failure, or
+a timeout alike, and cleared when that element sends its next request.
+
+Neither one carries any meaning beyond the fact it states. Dim a pending
+button in a stylesheet, or have a widget watch its own attributes and
+disable itself. An application that styles neither behaves correctly and
+shows nothing.
+
+A native button or form pressed again while it carries `lb-pending` is
+ignored, so a pending one is already disabled and the stylesheet only shows
+it. A widget is not held back, since one that sends on change must send its
+latest value. The hub also sets `aria-busy="true"` for as long as
+`lb-pending` is present.
+
+## Sending a request from a widget
+
+A widget can build and dispatch a request itself instead of carrying one of
+the attributes above — which is what `<lb-input>` does, and what a widget
+carrying `lb-action` must do. See
+[Custom Elements](./custom-elements.md#code).

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

@@ -0,0 +1,38 @@
+# The Elements of a Loadbare Application
+
+This reference is organized into four groups that reflect how an application is
+put together: the shell it lives in, the build that assembles it, the pages it
+serves, and the widgets those pages are made of.
+
+## The application shell
+
+| Topic                                            | Description                                         |
+|--------------------------------------------------|-----------------------------------------------------|
+| [`chrome.html`](./chrome.md)                     | The HTML document w/head, body, banner, main, etc.  |
+| [The Express server](./server.md)                | Serves static assets and handles data channel calls |
+| [The database layer](./server.md#database-layer) | Where the app's database access fits                |
+
+## Building the app
+
+| Topic                                                    | Description                               |
+|----------------------------------------------------------|-------------------------------------------|
+| [`imports.ts`](./builder.md#widgets-from-packages)       | The packages this app takes widgets from  |
+| [`loadbare-app-build`](./builder.md#running-the-builder) | Configuring the build command             |
+| [CSS](./css.md)                                          | How the builder packages css              |
+
+## Application Pages
+
+| Topic                                                   | Description                    |
+|---------------------------------------------------------|--------------------------------|
+| [`<name>.page.html`](./page-files.md#html)              | The page's HTML                |
+| [`<name>.queries.ts`](./page-files.md#queries)          | The data the page displays     |
+| [`<name>.requests.ts`](./page-files.md#requests-actions-crud) | Data Channel handlers          |
+| [Data Binding](./data-binding.md)                       | Connecting HTML to server data |
+
+## Widgets
+
+| Topic                                          | Description                     |
+|------------------------------------------------|---------------------------------|
+| [What a widget is](./custom-elements.md)       | An HTML file, a script, or both |
+| [`<tag-name>.html`](./custom-elements.md#html) | The markup the tag expands into |
+| [`<tag-name>.ts`](./custom-elements.md#code)   | The class the tag registers     |