@loadbare/widgets 0.10.0 → 0.11.0

package/skills/loadbare-widgets/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: loadbare-widgets
+description: The basic widget set for Loadbare/app, shipped as `@loadbare/widgets`. Covers each widget's parameters, the attributes it reads, and what a change sends; `lb-input`, `lb-select`, `lb-options`, `lb-picker`, `lb-table`, `lb-unknown-page`, `lb-confirm`, `lb-form`, `lb-insert-dialog`, `lb-master`, `lb-checkbox`, `lb-number`, `lb-date`, `lb-tel` and `lb-mailto`. Use whenever a task writes or changes markup using one of these tags, or decides whether a page needs a custom element of its own. The pages, queries and requests the widgets sit in are the loadbare-app skill's.
+license: Apache-2.0
+metadata:
+  package: "@loadbare/widgets"
+  homepage: https://gitlab.com/kendowns/loadbare
+---
+
+# Working with @loadbare/widgets
+
+Every widget is an ordinary custom element for `@loadbare/app`: markup with
+`lb-*` attributes and `exp-*` parameters, landed and gathered by the hub like
+any other element.  How pages, queries, requests and custom elements work is
+in the loadbare-app skill.  This skill covers only what each widget takes and
+does.
+
+Install the package and list it in the application's `src/imports.ts`:
+
+```ts
+export default ["@loadbare/widgets"];
+```
+
+The builder then bundles the definition and script of each widget a page
+uses, and nothing else.  The application's own definition of a tag
+overrides the package's.
+
+`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.
+Inside a form that sends one request for all its controls, leave
+`lb-request` off.
+
+## Reference material
+
+One page per widget.  They ship with the package, so no network is needed.
+
+| Widget | Is |
+| --- | --- |
+| [`lb-input`](references/lb-input.md) | a control wrapping an `<input>` |
+| [`lb-select`](references/lb-select.md) | a control wrapping a `<select>` whose options the page writes |
+| [`lb-options`](references/lb-options.md) | a control wrapping a `<select>` whose options come from a query |
+| [`lb-picker`](references/lb-picker.md) | `lb-options` with the row template built in |
+| [`lb-table`](references/lb-table.md) | a `<table>` supplying its own scaffolding and a ghost row |
+| [`lb-unknown-page`](references/lb-unknown-page.md) | the chrome's dialog for a URL that names no page |
+| [`lb-confirm`](references/lb-confirm.md) | a button that asks before it sends |
+| [`lb-form`](references/lb-form.md) | a form over one row, which saves per control once the row is on record |
+| [`lb-insert-dialog`](references/lb-insert-dialog.md) | a row entered in a modal dialog, chosen in the picker that opened it |
+| [`lb-master`](references/lb-master.md) | a set, one of its rows, and the buttons that act on the set |
+| [`lb-checkbox`](references/lb-checkbox.md) | a checkbox and its label, as markup to style |
+| [`lb-number`](references/lb-number.md) | a number shown by `Intl.NumberFormat` |
+| [`lb-date`](references/lb-date.md) | a date or time shown by `Intl.DateTimeFormat` |
+| [`lb-tel`](references/lb-tel.md) | a phone number shown as a `tel:` link |
+| [`lb-mailto`](references/lb-mailto.md) | an email address shown as a `mailto:` link |
+
+## The other loadbare skills
+
+`npx loadbare-widgets skills install` puts this skill where a coding agent
+finds it.  `npx loadbare-app skills install` and
+`npx loadbare-db skills install` do the same for the loadbare-app and
+loadbare-db skills.

package/skills/loadbare-widgets/references/lb-checkbox.md

@@ -0,0 +1,63 @@
+# `lb-checkbox`
+
+> Status: a barebones starter.  Iterative use will drive improvements.
+
+A checkbox and its label as one element, for an application to style.  A
+definition only, with no script: the hub treats a native checkbox as a
+control, so the widget adds nothing but the markup.
+
+Requires `exp-column` and `exp-label`.
+
+```html
+<div lb-query="people">
+  <template>
+    <div>
+      <lb-checkbox exp-column="active" exp-label="Active" exp-request="lb-row-update"></lb-checkbox>
+    </div>
+  </template>
+</div>
+```
+
+## Expansion Attributes
+
+| Parameter     | Fills                                           |
+| ------------- | ----------------------------------------------- |
+| `exp-column`  | the checkbox's `lb-column`                      |
+| `exp-label`   | the label's text                                |
+| `exp-request` | the checkbox's `lb-request`, none when absent   |
+
+The column and request go on the checkbox inside, since it is the control,
+so they are expansion attributes here rather than `lb-column` and
+`lb-request` on the tag.
+
+## Why it is not like `lb-input`
+
+`lb-input` has a script that makes the tag itself the control, so the page
+writes `lb-column` on the tag.  `lb-checkbox` cannot do the same.  A value
+that lands before a widget's script has loaded reaches it only as the
+`lb-column-value` stamp, a string, and a checkbox's state is a boolean.  A
+script `lb-checkbox` would read the stamp `"false"` as checked, since no
+string is read.  The native checkbox has no such gap: the hub sets `checked`
+on it directly.
+
+`lb-input` could equally be markup alone; its script is a convention, kept
+for now.
+
+## The control
+
+The checkbox is checked when its column is anything but `false` or null, and
+sends `"true"` or `"false"`.  See "Checkboxes" in the data-binding reference
+of the loadbare-app skill.
+
+## Styling
+
+The definition is a `<label>` holding the `<input type="checkbox">` and a
+`<span>` with the text:
+
+```css
+lb-checkbox label {
+  display: inline-flex;
+  gap: 0.5em;
+  align-items: center;
+}
+```

package/skills/loadbare-widgets/references/lb-confirm.md

@@ -0,0 +1,44 @@
+# `lb-confirm`
+
+> Status: a barebones starter.  Iterative use will drive improvements.
+
+A button that asks before it sends.  The button opens a dialog holding the
+message the page writes inside the tag, a Cancel button, and a confirm button
+carrying the request.
+
+Requires `exp-label` and `exp-request`.
+
+```html
+<template>
+  <tr>
+    <td lb-column="name"></td>
+    <td>
+      <lb-confirm exp-label="Delete" exp-request="lb-row-delete">
+        Delete <b lb-column="name"></b>?
+      </lb-confirm>
+    </td>
+  </tr>
+</template>
+```
+
+## Expansion Attributes
+
+| Parameter     | Fills                                         |
+| ------------- | --------------------------------------------- |
+| `exp-label`   | the text of the button that opens the dialog  |
+| `exp-request` | the confirm button's `lb-request`             |
+| `exp-confirm` | the confirm button's text, `Confirm` when absent |
+
+## The request
+
+The request is on the dialog's confirm button, never on the tag, so nothing
+reaches the hub until the user says yes.  The dialog sits in the row the tag
+sits in, so the request carries that row's query and key, and the message
+can show the row's columns with `lb-column`.
+
+Cancel comes first and takes focus, so Enter on a dialog opened by accident
+sends nothing.  The widget closes the dialog when the request succeeds.  A refused request leaves it open, with the hub's
+`lb-request-error` on the confirm button.
+
+The dialog is found by its place in the tag, not by id, so the tag works in a
+row template, where the hub clones it once per row.

package/skills/loadbare-widgets/references/lb-date.md

@@ -0,0 +1,48 @@
+# `lb-date`
+
+> Status: a barebones starter.  Iterative use will drive improvements.
+
+A date or a time shown by the browser's `Intl.DateTimeFormat`.  Not a
+control: write `lb-column` on the tag, and the hub lands the column on it
+and never gathers it.
+
+```html
+<lb-date lb-column="due" exp-date-style="medium"></lb-date>
+```
+
+## Expansion Attributes
+
+Each parameter is one of `Intl.DateTimeFormat`'s options, in kebab-case.  A
+parameter not given leaves Intl's default.
+
+| Parameter            | `Intl.DateTimeFormat` option          |
+| -------------------- | ------------------------------------- |
+| `exp-locale`         | the locale, the browser's when absent |
+| `exp-date-style`     | `dateStyle`                           |
+| `exp-time-style`     | `timeStyle`                           |
+| `exp-time-zone`      | `timeZone`                            |
+| `exp-time-zone-name` | `timeZoneName`                        |
+| `exp-hour-cycle`     | `hourCycle`                           |
+| `exp-weekday`        | `weekday`                             |
+| `exp-era`            | `era`                                 |
+| `exp-year`           | `year`                                |
+| `exp-month`          | `month`                               |
+| `exp-day`            | `day`                                 |
+| `exp-hour`           | `hour`                                |
+| `exp-minute`         | `minute`                              |
+| `exp-second`         | `second`                              |
+
+Intl refuses `exp-date-style` or `exp-time-style` beside any of
+`exp-weekday` through `exp-second`.
+
+## The value
+
+The widget reads the value as JavaScript's `Date` does.  A date alone, as
+`YYYY-MM-DD`, shows as that day in every time zone.  A value that is no
+date shows as it arrived.  Null shows nothing.
+
+## Styling
+
+The definition is a `<time>` whose text is the formatted date and whose
+`datetime` is the value as it arrived.  The hub stamps the tag with
+`lb-column-value`, the value as it arrived.

package/skills/loadbare-widgets/references/lb-form.md

@@ -0,0 +1,35 @@
+# `lb-form`
+
+> Status: a barebones starter.  Iterative use will drive improvements.
+
+A `<form>` over one row's controls, in one of two modes the row decides.
+
+Requires `exp-id`.
+
+```html
+<section lb-query="account">
+  <lb-form exp-id="account-form">
+    <lb-input lb-column="name" exp-label="Name" lb-request="lb-row-update"></lb-input>
+  </lb-form>
+  <button type="submit" form="account-form" lb-request="lb-row-insert">Save new</button>
+</section>
+```
+
+## Expansion Attributes
+
+| Parameter | Fills              |
+| --------- | ------------------ |
+| `exp-id`  | the form's `id`    |
+
+## Two modes
+
+A row with a key is on record, and each control saves its own column on
+`change` with `lb-request="lb-row-update"`.  A row whose key is empty is a new
+one not yet entered: the hub sends no update for it, so the controls only
+hold what a submit will gather.  See "A row not yet entered" in the
+data-binding reference of the loadbare-app skill.
+
+A definition only, with no script of its own.
+
+A button that acts on the row as a whole, such as one adding it to the set,
+belongs to whatever holds the set, and reaches the form by `form="<id>"`.

package/skills/loadbare-widgets/references/lb-input.md

@@ -0,0 +1,77 @@
+# `lb-input`
+
+> Status: a barebones starter.  Iterative use will drive improvements.
+
+A control wrapping an HTML `<input>`.  The hub sets it from a column and
+gathers it back under the same column, as it does a native `<input>`.
+
+Requires attributes `lb-column` and `exp-label`.
+
+```html
+<div lb-query="people">
+  <template>
+    <div>
+      <lb-input lb-column="name" exp-label="Name" lb-request="lb-row-update"></lb-input>
+      <lb-input lb-column="email" exp-label="Email" exp-readonly></lb-input>
+    </div>
+  </template>
+</div>
+```
+
+## Expansion Attributes
+
+These are the parameters that control build-time expansion of the final HTML.
+
+| Parameter      | Fills                            |
+| -------------- | -------------------------------- |
+| `exp-label`    | the visible `<label>` text       |
+| `exp-type`     | the input's `type`, `text` when absent |
+| `exp-readonly` | the input's `readonly` attribute |
+
+Any value on `exp-readonly` makes the input readonly.  Leaving the parameter
+off drops the attribute.
+
+## Attributes
+
+| Attribute    | Names                                     |
+| ------------ | ----------------------------------------- |
+| `lb-column`  | the column the input shows and gathers to |
+| `lb-request` | the request a change issues               |
+
+## The control
+
+`lb-input` is a form-associated custom element.  Its `value` property gets and
+sets the value of the `<input>` inside it, and it fires `change` on itself when
+that `<input>` fires `change`.  A form reset returns the `<input>` to its
+default.  A refusal's message for its column goes to the `<input>`, as HTML's
+own validity.
+
+## Inside a form
+
+An `lb-input` inside an `lb-row-insert` or `lb-row-update` form carries no
+`lb-request`.  The hub gathers every `lb-column` whose form owner is the form
+on submit and sends one request for all of them, so a widget that also sent
+its own would write the same edit twice.
+
+```html
+<form lb-query="people" lb-request="lb-row-insert">
+  <lb-input lb-column="name" exp-label="Name"></lb-input>
+  <lb-input lb-column="email" exp-label="Email"></lb-input>
+  <button type="submit">Add</button>
+</form>
+```
+
+## Editing one column
+
+With `lb-request`, the `lb-input` commits on `change`.  The hub gathers its
+value alone, so `lb-request="lb-row-update"` sends an `lb-row-update` for the
+query and key of the row around it, with `values` holding that one column.
+Any other request name sends that request with the same `query`, `key` and
+`values`.
+
+Inside `lb-query="lb-url"`, `lb-request="lb-row-update"` writes the column as a
+query parm, and the hub answers with no round trip.
+
+While the request is in flight the hub marks the `lb-input` with
+`lb-request-pending`, and on failure with `lb-request-error`.  Both are there
+for a stylesheet to read.

package/skills/loadbare-widgets/references/lb-insert-dialog.md

@@ -0,0 +1,73 @@
+# `lb-insert-dialog`
+
+> Status: a barebones starter.  Iterative use will drive improvements.
+
+A row entered in a modal dialog, for a set being chosen from elsewhere on the
+page, such as creating an account while a picker chooses one.  The page
+writes the controls inside the tag; the dialog supplies the form, Cancel and
+Save.
+
+Requires `exp-id`, `exp-title` and `exp-query`.
+
+```html
+<lb-options lb-query="accounts" lb-column="account_id" exp-label="Account">
+  <template><option lb-column="name"></option></template>
+</lb-options>
+<button type="button" commandfor="new-account" command="show-modal">New</button>
+
+<lb-insert-dialog exp-id="new-account" exp-title="New account" exp-query="accounts">
+  <lb-input lb-column="name" exp-label="Name"></lb-input>
+</lb-insert-dialog>
+```
+
+## Expansion Attributes
+
+| Parameter   | Fills                                        |
+| ----------- | -------------------------------------------- |
+| `exp-id`    | the dialog's `id`, which buttons open        |
+| `exp-title` | the dialog's heading                         |
+| `exp-query` | the `lb-query` of the form, which it inserts into |
+| `exp-save`  | the Save button's text, `Save` when absent   |
+
+## Where it goes
+
+Write it once, outside every row and every form, and open it with HTML's own
+`commandfor` and `command="show-modal"` from as many buttons as need it.  A
+form inside another form is dropped by the parser, and `lb-table` joins every
+control in a ghost row to that row's form, so the dialog cannot sit beside
+the control it serves.
+
+## What it does
+
+Save is the form's `lb-row-insert`.  When it succeeds, the widget chooses the new row in the nearest `lb-options` around
+the button that opened the dialog, fires `change` on it, and closes the
+dialog.  The new key comes from the patch the insert answers with, so the
+handler answers with the row it created.  A picker that saves its own column
+saves it; one in a ghost row or a new record holds it until Save.
+
+A refused insert leaves the dialog open to correct.  Cancel and Escape close
+it, and closing resets the form.
+
+## Opening beside the button
+
+While the dialog is open, the button that opened it carries
+`insert-dialog-opener` and the widget carries `anchored`, for a stylesheet to
+place the dialog beside the button with CSS anchor positioning:
+
+```css
+[insert-dialog-opener] {
+  anchor-name: --insert-dialog-opener;
+}
+
+lb-insert-dialog[anchored] .lb-insert-dialog {
+  position-anchor: --insert-dialog-opener;
+  inset: auto;
+  margin: 0;
+  position-area: block-end span-inline-end;
+  position-try-fallbacks: flip-block, flip-inline, flip-block flip-inline;
+}
+```
+
+Only one modal is open at a time, so one anchor name serves every dialog.
+Without such a rule, or opened with no button, the dialog stays where the
+browser puts a modal.

package/skills/loadbare-widgets/references/lb-mailto.md

@@ -0,0 +1,29 @@
+# `lb-mailto`
+
+> Status: a barebones starter.  Iterative use will drive improvements.
+
+An email address shown as written, as a `mailto:` link.  Not a control:
+write `lb-column` on the tag, and the hub lands the column on it and never
+gathers it.
+
+```html
+<lb-mailto lb-column="email"></lb-mailto>
+```
+
+It takes no parameters.  To edit the address, use
+`<lb-input exp-type="email">`.
+
+## The value
+
+The link's text is the value as it arrived.  Its `href` is `mailto:` and the
+address, encoded, so a value carrying `?` or `&` cannot add a subject, a body
+or another recipient to the message.
+
+A value with no `@` shows as it arrived, with no `href`.  Null shows
+nothing.
+
+## Styling
+
+The definition is an `<a>`, with no `href` while there is no address, so
+`lb-mailto a:not([href])` selects a value that is no link.  The hub stamps
+the tag with `lb-column-value`, the value as it arrived.

package/skills/loadbare-widgets/references/lb-master.md

@@ -0,0 +1,65 @@
+# `lb-master`
+
+> Status: a barebones starter.  Iterative use will drive improvements.
+
+A set on one side, one of its rows on the other, and the buttons that act on
+the set.  A definition only, with no script of its own: it is built from
+[`lb-form`](./lb-form.md) and [`lb-confirm`](./lb-confirm.md).
+
+Requires `exp-row`.
+
+```html
+<lb-master exp-row="account">
+  <template lb-exp-template="picker">
+    <div lb-query="lb-url">
+      <lb-picker lb-query="accounts" lb-column="acct" lb-request="lb-row-update"
+        exp-label="Account" exp-column="name"></lb-picker>
+    </div>
+  </template>
+  <lb-input lb-column="name" exp-label="Name" lb-request="lb-row-update"></lb-input>
+  <template lb-exp-template="delete-message">
+    Delete <b lb-column="name"></b>?
+  </template>
+</lb-master>
+```
+
+## Expansion Attributes
+
+| Parameter      | Fills                                          |
+| -------------- | ---------------------------------------------- |
+| `exp-row`      | the `lb-query` of the row the form shows       |
+| `exp-form-id`  | the form's `id`, `master-form` when absent     |
+
+| Template                                    | Fills                         |
+| ------------------------------------------- | ----------------------------- |
+| `<template lb-exp-template="picker">`       | the side that chooses the row |
+| `<template lb-exp-template="delete-message">` | the question Delete asks    |
+
+## The buttons
+
+| Button   | Shows             | Does                                          |
+| -------- | ----------------- | --------------------------------------------- |
+| New      | A row on record   | Sends `new`, a request the page declares, and pushes a history entry |
+| Copy     | A row on record   | Sends `copy`, a request the page declares     |
+| Delete   | A row on record   | Asks, then sends `lb-row-delete`              |
+| Save new | A new row         | Submits the form as `lb-row-insert`, and pushes a history entry |
+| Cancel   | A new row         | Resets the form                               |
+
+Each carries `data-mode`, `on-record` or `new`, and the stylesheet shows each
+only in its mode.  A new row is one whose key is empty, a row not yet entered
+(see that section in the data-binding reference of the loadbare-app skill).
+
+Which row shows is a query parm, and only the page knows its name, so New is
+a request the page declares.  Its handler empties the parm, and the row
+query answers a row with an empty key:
+
+```ts
+handlers: {
+  new: { run: async () => url({ acct: "" }), refresh: [] },
+},
+```
+
+Choosing the picker's blank does the same.
+
+Copy goes to the server rather than filling the form, because a copy is a new
+row in the set, and only the server can bring its children along.

package/skills/loadbare-widgets/references/lb-number.md

@@ -0,0 +1,53 @@
+# `lb-number`
+
+> Status: a barebones starter.  Iterative use will drive improvements.
+
+A number shown by the browser's `Intl.NumberFormat`.  Not a control: write
+`lb-column` on the tag, and the hub lands the column on it and never gathers
+it.
+
+```html
+<lb-number lb-column="balance" exp-style="currency" exp-currency="USD"></lb-number>
+```
+
+## Expansion Attributes
+
+Each parameter is one of `Intl.NumberFormat`'s options, in kebab-case.  A
+parameter not given leaves Intl's default.
+
+| Parameter                        | `Intl.NumberFormat` option             |
+| -------------------------------- | -------------------------------------- |
+| `exp-locale`                     | the locale, the browser's when absent  |
+| `exp-style`                      | `style`                                |
+| `exp-currency`                   | `currency`                             |
+| `exp-currency-display`           | `currencyDisplay`                      |
+| `exp-currency-sign`              | `currencySign`                         |
+| `exp-unit`                       | `unit`                                 |
+| `exp-unit-display`               | `unitDisplay`                          |
+| `exp-notation`                   | `notation`                             |
+| `exp-compact-display`            | `compactDisplay`                       |
+| `exp-sign-display`               | `signDisplay`                          |
+| `exp-minimum-integer-digits`     | `minimumIntegerDigits`                 |
+| `exp-minimum-fraction-digits`    | `minimumFractionDigits`                |
+| `exp-maximum-fraction-digits`    | `maximumFractionDigits`                |
+| `exp-minimum-significant-digits` | `minimumSignificantDigits`             |
+| `exp-maximum-significant-digits` | `maximumSignificantDigits`             |
+
+## The value
+
+The widget formats the value as the string it arrived as, so a decimal the
+query sends as a string keeps every digit.  A value that is no number shows
+as it arrived.  Null shows nothing.
+
+## Styling
+
+The definition is a `<data>` whose text is the formatted number and whose
+`value` is the number as it arrived.  The hub stamps the tag with
+`lb-column-value`, the number as it arrived, so a stylesheet selects on the
+value itself:
+
+```css
+lb-number[lb-column-value^="-"] {
+  color: var(--negative);
+}
+```

package/skills/loadbare-widgets/references/lb-options.md

@@ -0,0 +1,113 @@
+# `lb-options`
+
+A control wrapping an HTML `<select>`, with the `<option>`s coming from a
+query.
+
+Apply the `lb-query` attribute to name the query, `lb-column` to name the
+column the choice shows and gathers to, and `lb-request` to name the request a
+change issues.  Write a `<template>` inside the tag, and apply `lb-column` to
+the `<option>` itself — an `<option>` holds text, not elements.  For options
+in groups, write a group template holding an `<optgroup>`.
+
+Provide `exp-label`.
+
+```html
+<lb-options
+  lb-query="statuses"
+  lb-column="status_id"
+  exp-label="Status"
+  lb-request="setStatus"
+>
+  <template lb-group>
+    <optgroup>
+      <template><option lb-column="label"></option></template>
+    </optgroup>
+  </template>
+</lb-options>
+```
+
+## Status
+
+Barebones starter to prove out the publish/consume chain and identify necessary
+improvements through iterative use.
+
+## Parameters
+
+| Parameter   | Fills                      |
+| ----------- | -------------------------- |
+| `exp-label` | the visible `<label>` text |
+| `exp-size`  | the `<select>`'s `size`, an open list of that many rows rather than a drop-down |
+
+## Attributes
+
+| Attribute    | On                 | Names                                      |
+| ------------ | ------------------ | ------------------------------------------ |
+| `lb-query`   | the element itself | the query whose rows become options        |
+| `lb-column`  | the element itself | the column the choice shows and gathers to |
+| `lb-request` | the element itself | the request a change issues                |
+| `lb-group`   | a template holding an `<optgroup>` | a group of options        |
+| `lb-column`  | the `<option>`     | the column the option shows                |
+
+The server declares the query's key.  The widget copies each option's
+`lb-key-value` to its `value`.
+
+## Grouping
+
+The hub makes one `<optgroup>` per run of the query's order's leading term.
+An `<optgroup>` takes its label from an attribute, which landing does not
+set, so the widget labels each from the `lb-group-value` the hub stamps on
+it: the value the group breaks on.
+
+That value is often a number kept for sorting, such as a category's display
+order, and a number is no label.  For a label from a column of the group's
+first row, write a heading option marked `data-group-label` in the
+`<optgroup>`, filled like any group heading:
+
+```html
+<template lb-group>
+  <optgroup>
+    <option data-group-label hidden disabled lb-column="category"></option>
+    <template><option lb-column="account_name"></option></template>
+  </optgroup>
+</template>
+```
+
+The widget takes the heading option's text as the label.  Mark it `hidden`
+and `disabled` so it is never a choice.
+
+## The control
+
+`lb-options` is a form-associated custom element.  Its `value` property gets
+and sets the value of the `<select>` inside it, and it fires `change` on itself
+when that `<select>` fires `change`.  A form reset selects the first option.
+A refusal's message for its column goes to the `<select>`, as HTML's own
+validity.
+
+The hub reads the element's own `lb-column` from the row around it, and lands
+the rows of its `lb-query` inside it.  A value set before the option it names
+has landed selects that option when the rows land.
+
+## Choosing
+
+With `lb-request`, the `lb-options` commits on `change`.  The hub gathers its
+value alone, the key of the chosen row, and sends the request with the `query`
+and `key` of the row around it.  Declare that request on the server, or name
+`lb-row-update`.
+
+Without `lb-request`, a change commits nothing, and the form or live row around
+the `lb-options` gathers its value.
+
+Inside `lb-query="lb-url"`, `lb-request="lb-row-update"` writes the chosen key
+as a query parm, and the hub answers with no round trip.
+
+While the request is in flight the hub marks the `lb-options` with
+`lb-request-pending`, and on failure with `lb-request-error`.  Both are there
+for a stylesheet to read.
+
+## Styling an empty list
+
+`lb-options` carries `lb-query-row-count` with the number of options showing,
+for a stylesheet to read.
+
+For the case where every row is one option and only the column names vary,
+see [`lb-picker`](./lb-picker.md).