@loadbare/app 0.8.2 → 0.10.0

package/docs/reference/widgets.md

@@ -1,13 +1,12 @@
 # The Basic Widget Library
 
-Seven widgets: `lb-input`, `lb-select`, `lb-list`, `lb-options`, `lb-table`,
-`lb-picker`, `lb-unknown-page`. Every one of them is written against the same two contracts
-documented elsewhere — [Custom Elements](./custom-elements.md#html) for its
-definition, [Custom Elements](./custom-elements.md#code) for its class —
-nothing here is special-cased machinery.
+Six widgets: `lb-input`, `lb-select`, `lb-options`, `lb-picker`, `lb-table`,
+`lb-unknown-page`. Every one of them is an ordinary custom element, written
+against the contracts in [Custom Elements](./custom-elements.md#html) for its
+definition and [Custom Elements](./custom-elements.md#code) for its class.
 
 They ship compiled, in `@loadbare/widgets`, a package the builder resolves the
-way it resolves anyone else's — it declares `"loadbare": { "widgets": "./dist" }`
+way it resolves any other: it declares `"loadbare": { "widgets": "./dist" }`
 and the builder scans that. Install it and list it:
 
 ```
@@ -23,140 +22,133 @@ See [Widgets from packages](./builder.md#widgets-from-packages) for what
 listing a package does, and [The Builder](./builder.md#where-the-builder-looks)
 for where a listed package sits in the cascade.
 
+`lb-input`, `lb-select`, `lb-options` and `lb-picker` are controls:
+form-associated custom elements with a `value` property that fire `change`.
+Each carries `lb-column` and `lb-request` itself, the way an `<input>` does;
+see [Being a control](./custom-elements.md#being-a-control).
+
 ## `lb-input`
 
-Wraps an `<input>`. `lb-value` sets the input's `.value`. The widget sends
-nothing on its own: `lb-action` names what the input's `change` sends. The
-reserved `lb-row-update` saves the input's own cell; any other name sends that
-action. Either carries the input's value, and the hub adds the scope the
-input sits in.
+Wraps an `<input>`. The hub sets its `value` from the column `lb-column`
+names, and `lb-request` names what the widget sends on `change`:
 
-An input inside an `lb-row-insert` or `lb-row-update` form leaves the attribute off.
-The form reads every `lb-cell` in it on submit and sends one request for all
-of them, so an input that also sent its own would write the same edit twice.
+```html
+<lb-input lb-column="name" lb-request="lb-row-update" exp-label="Name"></lb-input>
+```
 
-| Parameter | Fills |
-| ---------- | ----- |
-| `exp-label` | the visible `<label>` text |
-| `exp-readonly` | the input's `readonly` attribute |
+Inside a form, leave `lb-request` off. The form gathers the widget on submit
+like any other control, so a widget that also sent its own request would
+write the same edit twice.
 
-| Attribute | Asks for |
-| ---------- | ----- |
-| `lb-action` | what to send on `change`; `lb-row-update` to save the cell's own edit |
+| Parameter      | Fills                            |
+|----------------|----------------------------------|
+| `exp-label`    | The visible `<label>` text       |
+| `exp-readonly` | The input's `readonly` attribute |
 
 ## `lb-select`
 
-Wraps a `<select>` whose `<option>`s the author writes directly inside (via
-`lb-slot`). `lb-value` sets the select's `.value`; a `change` sends the
-action named by `lb-action`, with the select's `.value` as the request's
-`value` — the choice is the interaction, so this is the case where an
-action carries a value.
+Wraps a `<select>` whose `<option>`s the page writes inside the tag:
 
-| Parameter | Fills |
-| ---------- | ----- |
-| `exp-label` | the visible `<label>` text |
+```html
+<lb-select lb-column="team" lb-request="lb-row-update" exp-label="Team">
+  <option value="">No team</option>
+  <option value="Engines">Engines</option>
+</lb-select>
+```
 
-Requires `lb-action` or `lb-query-parm` — a change with neither logs and
-sends nothing. With `lb-query-parm` the hub writes the choice into the URL.
+| Parameter   | Fills                      |
+|-------------|----------------------------|
+| `exp-label` | The visible `<label>` text |
 
 ## `lb-options`
 
-A `<select>` whose `<option>`s come from a query instead of being written by
-hand. The author supplies the row template inside the widget (via
-`lb-slot`), same as any list widget:
+A `<select>` whose `<option>`s are the rows of the query it names. The page
+writes the row template inside the widget:
 
 ```html
-<lb-options lb-list="statuses" exp-label="Status" lb-action="setStatus">
-  <template lb-key="id" data-group="category">
-    <option lb-cell="label"></option>
+<lb-options lb-query="statuses" lb-column="status" lb-request="lb-row-update" exp-label="Status">
+  <template data-group="category">
+    <option lb-column="label"></option>
   </template>
 </lb-options>
 ```
 
-| Parameter | Fills |
-| ---------- | ----- |
-| `exp-label` | the visible `<label>` text |
+| Parameter   | Fills                      |
+|-------------|----------------------------|
+| `exp-label` | The visible `<label>` text |
 
-- The row's key becomes the option's `value`: the `lb-key-value` the hub
-  stamps on each option is copied across, so the page names the key column
-  once, with `lb-key`.
+- Each option's `value` is its row's key, the `lb-key-value` the hub stamps
+  on the live row, so the widget holds a key and shows a label.
 - `data-group` on the row template sections the options into `<optgroup>`s,
-  one per distinct value, created and removed as rows arrive and leave.
-- `lb-value` selects the option with that key, including one that arrives
-  after the value did.
-- A `change` sends the action named by `lb-action`, value from the
-  select's `.value`. With `lb-query-parm` instead, the hub writes the
-  choice into the URL.
+  one per distinct value of that column, added and removed as rows arrive
+  and leave.
+- Its `value` selects the option with that key, including an option that
+  arrives after the value did.
+
+`lb-picker` is the same class with the row template supplied by its
+definition.
+
+## `lb-picker`
+
+`lb-options`, with the row template built in, for a list where every row is
+one option showing one column:
+
+```html
+<lb-picker
+  lb-query="statuses"
+  lb-column="status"
+  lb-request="lb-row-update"
+  exp-label="Status"
+  exp-column="label"
+  exp-group="category"
+></lb-picker>
+```
 
-`lb-picker` is this same class with its row template supplied by the
-definition instead of the page — see below.
+| Parameter    | Fills                                   |
+|--------------|-----------------------------------------|
+| `exp-label`  | The visible `<label>` text              |
+| `exp-column` | The column each option shows            |
+| `exp-group`  | The row template's `data-group`         |
+
+An option built from two columns, or a row with a second element, is
+`lb-options` with the page's own row template.
 
 ## `lb-table`
 
-A `<table>` that supplies its own scaffolding; the author supplies the
-heading row, the row template, and optionally a footer, each as a
-`<template>` matched to a destination:
+A `<table>` that supplies its own scaffolding. The page supplies the heading
+row, the row template, and optionally a footer, each as a `<template>`:
 
 ```html
-<lb-table lb-list="ledger" exp-caption="Ledger">
-  <template lb-template="head">
+<lb-table lb-query="ledger" exp-caption="Ledger">
+  <template lb-exp-template="head">
     <tr><th>Date</th><th>Amount</th></tr>
   </template>
-  <template lb-key="id" data-sort="date" data-group="month">
-    <tr><td lb-cell="date"></td><td lb-cell="amount"></td></tr>
+  <template data-sort="date" data-group="month">
+    <tr><td lb-column="date"></td><td lb-column="amount"></td></tr>
   </template>
-  <template lb-template="foot">
-    <tr lb-row="ledger-total"><td>Total</td><td lb-cell="total"></td></tr>
+  <template lb-exp-template="foot">
+    <tr lb-query="ledger-total"><td>Total</td><td lb-column="total"></td></tr>
   </template>
 </lb-table>
 ```
 
-| Parameter | Fills |
-| ---------- | ----- |
-| `exp-caption` | the `<caption>` text |
-
-| Destination | Fills |
-| ------------ | ----- |
-| `head` (`lb-template="head"`) | the `<thead>` content |
-| `foot` (`lb-template="foot"`) | the `<tfoot>` content |
-| slot (no `lb-template`) | the row template, via `lb-slot` on `<tbody>` |
-
-- `data-group` on the row template sections rows under a derived heading row,
-  one per distinct value, whose `colSpan` matches the row's own column
-  count. `data-sort` orders rows within a section (or the whole body, with no
-  grouping) by comparing each row's cell text.
-- The `foot` destination is not delivered through `lbPlaceRow` — it's an
-  ordinary scope carrying its own `lb-row`, resolved by name like any
-  other on the page. A grand total is a second query over the same
-  data, not a row the hub hands the table.
-
-## `lb-picker`
-
-`lb-options`, with the row template supplied by the definition instead of
-the page — for when every row is one option and nothing else varies:
-
-```html
-<lb-picker
-  lb-list="statuses"
-  exp-label="Status"
-  exp-key="id"
-  exp-cell="label"
-  exp-group="category"
-  lb-action="setStatus"
-></lb-picker>
-```
+| Parameter     | Fills                |
+|---------------|----------------------|
+| `exp-caption` | The `<caption>` text |
 
-| Parameter | Fills |
-| ---------- | ----- |
-| `exp-label` | the visible `<label>` text |
-| `exp-key` | the row template's `lb-key` |
-| `exp-cell` | the option's `lb-cell` |
-| `exp-group` | the row template's `data-group` |
+| Template                          | Fills                                   |
+|-----------------------------------|-----------------------------------------|
+| `<template lb-exp-template="head">` | The `<thead>`                         |
+| `<template lb-exp-template="foot">` | The `<tfoot>`                         |
+| Any other `<template>`            | The row template, in the `<tbody>`      |
 
-Behavior — grouping, key-as-value, the action on change — is inherited
-whole from `lb-options`; a page author who needs a second element in the
-row, or an option built from two columns, writes `lb-options` and its own
-`<template>` instead.
+- `data-group` on the row template sections rows under a heading row, one
+  per distinct value of that column, spanning every column of the row.
+- `data-sort` orders rows within a section, or within the whole body with no
+  grouping, by the text of that column.
+- The footer is not a row of `ledger`. Its `<tr>` names a `row` query of its
+  own, which lands on the `<tr>` itself. A grand total is a second query over
+  the same data.
 
 ## `lb-unknown-page`
 
@@ -170,9 +162,11 @@ The chrome's dialog for a URL that names no page, as one tag:
 </lb-hub>
 ```
 
-It expands to a `<dialog lb-unknown-page>` scoped to the hub's own
-`lb-navigation` query, so `page-label` and `page-uri` land in it the way any
-cell lands anywhere, and the hub opens it on a miss. It takes no parameters
-and, so far, shows both cells rather than choosing between them. See
-[`chrome.html`](./chrome.md#where-the-page-is) for the query, and for the same
-dialog written by hand.
+It expands to a `<dialog lb-url-unknown lb-query="lb-url">` showing
+`lb-path`, and the hub opens it when no page's stub matches the path. See
+[An unknown page](./chrome.md#an-unknown-page) for the same dialog written
+by hand.
+
+| Parameter         | Fills                                    |
+|-------------------|------------------------------------------|
+| `exp-button-text` | The text of the button that closes it, `OK` by default |

package/docs/roadmap.md

@@ -17,23 +17,36 @@ wrong thing. Revisit when the described symptom actually shows up.
 
 ### Staleness and concurrent writers
 
-Two tabs, or two users, updating the same list at once. A solo developer
+Two tabs, or two users, updating the same rows at once. A solo developer
 testing in one browser will not produce this by accident, and retrofitting a
 version or conflict check onto every row after the fact touches every widget
 that writes.
 
 ### Nesting
 
-Whether a row may contain a list (master-detail, an expanding row). [Theory](./theory.md) already flags this as possibly load-bearing if
+Whether a live row may hold rows of its own detail (master-detail, an
+expanding row). [Theory](./theory.md) already flags this as possibly load-bearing if
 disallowed. Worth a decision-in-principle the first time a master-detail
 page is built, even before the mechanism is needed elsewhere.
 
 ### Pending appearance
 
 A value that hasn't arrived yet is probably derivable from an absent
-`lb-value` rather than needing a signal of its own. Not yet needed because
+`lb-column-value` rather than needing a signal of its own. Not yet needed because
 nothing currently produces that gap in practice — revisit if one does.
 
+### Events while a request is in flight
+
+The hub ignores a commit on an element carrying `lb-request-pending`.
+Nothing holds back any other element, so two round trips can be out at once
+and the one that answers last is what lands, whichever the user started
+last.
+
+A control that commits on `change` while its own round trip is in flight has
+that change ignored, so its latest value is not sent.  Whether the hub should
+send it once the round trip settles, and whether it should refuse every
+commit while anything is in flight, is open.
+
 ### Validation placement
 
 Per-keystroke feedback cannot afford a round trip, so some validation will
@@ -97,15 +110,15 @@ enough to measure.
 
 ### Data binding utilities
 
-If a dev team wishes to make their own widgets that identify `lb-list` or `lb-row`,
-`lb-key-value`, `lb-cell`, they must repeat the code that is present in the hub.
+A custom element that finds its own nearest ancestor `lb-query`,
+`lb-key-value` or `lb-column` repeats code that is present in the hub.
 
-Perhaps a utility that can be called, like `getDataScope(el)`, to help
-clean up the code in these cases.
+Perhaps a utility that can be called, like `nearestRow(el)`, to help clean up
+the code in these cases.
 
 ### Refresh narrowed by query parm
 
-A query parm write loads the whole page again, every query at once.  Keyed
+A query parm write reloads every query of the page at once.  Keyed
 landing keeps the rows that came back, so nothing on screen is disturbed, but
 the server does work for queries the parm never touched.
 
@@ -115,21 +128,21 @@ only the queries that read one of them, and still remember nothing.
 
 ### Query parm history as a user preference
 
-A query parm write replaces the history entry, and `lb-query-parm-push`
-pushes one.  Which of the two a user wants may be the user's to say, rather
+A query parm write replaces the history entry, and `lb-url-push` pushes
+one.  Which of the two a user wants may be the user's to say, rather
 than the page's.
 
-### Build-time checking of `lb-action` against the declared requests
+### Build-time checking of `lb-request` against the declared requests
 
-Release 1.0 resolves every `lb-action` value at request time. A value naming
-no entry under `actions`, or a reserved operation naming a list with no entry
-under `crud`, is found on the first click: a server console warning and an
-empty answer, described in
+Release 1.0 resolves every `lb-request` value at request time. A value naming
+no entry under `handlers`, or one of the requests Loadbare provides for a
+query with no entry under `crud`, is found on the first commit: a server
+console warning and an empty answer, described in
 [Page files](./reference/page-files.md). A typo builds cleanly.
 
 The builder already expands each page and walks the finished document in
-`checkBinding`, tracking the enclosing `lb-list` scope, so collecting every
-action name together with the list it sits in needs no new machinery. What
+`walkMarkup`, tracking the enclosing `lb-query`, so collecting every request
+name together with the query it is issued for needs no new machinery. What
 it lacks is the other half of the comparison: it knows the path of a
 `.requests.ts` file and never reads its contents.
 
@@ -143,23 +156,15 @@ Two routes to the declared names, and the choice is the decision:
   API. No application code runs, at the price of a real dependency and of
   guessing wrong on anything not written as a plain object literal.
 
-Three smaller calls come with either route. The chrome belongs to no page, so
-an action there can only be required of every page or forbidden. A page with
-no requests file makes any action on it an error. And the check sees markup
-only, so it is sound only if `lb-action` is authored and never assigned by
-script — no widget assigns it today, and the rule has never been written
-down.
+Two smaller calls come with either route. The chrome belongs to no page, so
+a request there can only be required of every page or forbidden. A page with
+no requests file makes any request on it an error. The check is sound
+because the developer writes `lb-*` attributes in markup and script never
+assigns them.
 
-This reverses the position stated above `walkBinding`, that markup and server
-are separate artifacts and the comparison belongs to `createHub`. The same
-machinery would then also let `lb-list` and `lb-row` names be checked against
+The same machinery would then also let `lb-query` names be checked against
 the declared queries.
 
-One piece is separable and needs none of the above: an `lb-action` beginning
-with `lb-` that names none of the three operations is a typo the builder can
-refuse from markup alone. `LB_ACTIONS` in `core/lb-constants.ts` exists for
-this, and the builder does not yet import it.
-
 ### A language server
 
 ...for Loadbare HTML.

package/docs/terms-of-art.md

@@ -0,0 +1,57 @@
+# Terms of art
+
+This document uses these terms exactly as their specs define them.
+
+DOM:
+- element: a node with a name and attributes
+- attribute: a name-value pair on an element
+- attribute value: the string an attribute holds
+- ancestor: a parent, or a parent's ancestor
+- descendant: a child, or a child's descendant
+- content: the child nodes of an element
+- text content: the data of all descendant text nodes
+- clone: a copy of a node and descendants
+- event: an object dispatched to signal an occurrence
+- bubbles: the event also dispatches to each ancestor
+- abort: stop an operation through its AbortSignal
+
+HTML:
+- control: an `<input>`, `<select>` or `<textarea>`, or a form-associated
+  custom element with a `value` property that fires `change`
+- control value: the current value of a control
+- custom element: an element defined by `customElements.define`
+- form-associated custom element: a custom element declaring
+  `static formAssociated = true`
+- `<template>`: an element holding inert content for cloning
+- `<title>`: the element holding a document's title
+- document title: the title the tab and session history show
+- click: the event an element's activation fires
+- submit: the event a form's submission fires
+- submitter: the submit button that submitted a form
+- change: the event a committed control edit fires
+- reset: restore a form's controls to defaults
+- form owner: the form a control is associated with
+- `form` attribute: names a form owner by id, from anywhere
+- `href`: the attribute holding a link's URL
+- history entry: one entry in the session history
+- push: add a session history entry
+- replace: change the current session history entry
+
+URL:
+- path: the slash-separated segments after the host
+- query parm: a name-value pair in the URL's query
+
+HTTP:
+- request: the message a client sends a server
+- response: the message a server returns for a request
+
+JSON:
+- object: zero or more members between braces
+- member: one name-value pair of an object
+- array: an ordered sequence of values
+- null, true, false: literal values
+
+SQL:
+- row: one record of a result set
+- column: a named field of every row
+- key: a column whose value identifies one row