@loadbare/widgets 0.10.1 → 0.11.0

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).

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

@@ -0,0 +1,53 @@
+# `lb-picker`
+
+[`lb-options`](./lb-options.md) with the row template built in, for when every
+row is one option and only the column it shows varies.  It takes no
+children.  Options in groups take a group template, which is `lb-options`
+with the page's own templates.
+
+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.
+
+Provide `exp-label` and `exp-column`.
+
+```html
+<lb-picker
+  lb-query="statuses"
+  lb-column="status_id"
+  exp-label="Status"
+  exp-column="label"
+  lb-request="setStatus"
+></lb-picker>
+```
+
+## 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-column` | the column the option shows |
+
+`exp-column` is required.  The server declares the query's key, which
+becomes each option's `value`.
+
+## Attributes
+
+| Attribute    | Names                                      |
+| ------------ | ------------------------------------------ |
+| `lb-query`   | the query whose rows become options        |
+| `lb-column`  | the column the choice shows and gathers to |
+| `lb-request` | the request a change issues                |
+
+## Choosing
+
+The same as [`lb-options`](./lb-options.md): grouping, the key as the option's
+value, the control's `value`, `lb-query-row-count`, and the request on change.
+
+Write `lb-options` and the template instead for a row that needs a second
+element, or an option built from two columns.

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

@@ -0,0 +1,70 @@
+# `lb-select`
+
+A control wrapping an HTML `<select>`, with the `<option>`s written by hand.
+
+Apply the `lb-column` attribute to name the column, and `lb-request` to name the
+request a change issues.
+
+Provide `exp-label`.
+
+```html
+<lb-select lb-column="status" exp-label="Status" lb-request="setStatus">
+  <option value="open">Open</option>
+  <option value="closed">Closed</option>
+</lb-select>
+```
+
+## 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 |
+
+## Attributes
+
+| Attribute    | Names                                      |
+| ------------ | ------------------------------------------ |
+| `lb-column`  | the column the select shows and gathers to |
+| `lb-request` | the request a change issues                |
+
+## The control
+
+`lb-select` 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 option marked
+`selected`, or the first option.  A refusal's message for its column goes to
+the `<select>`, as HTML's own validity.
+
+## Choosing
+
+With `lb-request`, the `lb-select` commits on `change`.  The hub gathers its
+value alone and sends the request with the `query` and `key` of the row around
+it, and `values` holding the chosen option's value under its column.  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-select` gathers its value.
+
+Inside `lb-query="lb-url"`, `lb-request="lb-row-update"` writes the choice as a
+query parm, and the hub answers with no round trip.
+
+```html
+<div lb-query="lb-url">
+  <lb-select lb-column="status" exp-label="Status" lb-request="lb-row-update">
+    <option value="">All</option>
+    <option value="open">Open</option>
+  </lb-select>
+</div>
+```
+
+While the request is in flight the hub marks the `lb-select` with
+`lb-request-pending`, and on failure with `lb-request-error`.  Both are there
+for a stylesheet to read.
+
+For a `<select>` whose options come from a query, see
+[`lb-options`](./lb-options.md) and [`lb-picker`](./lb-picker.md).