@loadbare/app 0.21.0 → 0.23.0

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

@@ -1,8 +1,7 @@
 # The Basic Widget Library
 
-Thirteen widgets: `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` and `lb-date`. Every one of them is an ordinary custom element, written
+`@loadbare/widgets` is the basic widget set: controls, a table, dialogs, and
+elements that format a value. 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.
 
@@ -30,282 +29,16 @@ see [Being a control](./custom-elements.md#being-a-control). Each passes a
 refusal's message for its column to the native control inside it; see
 [Refusals](./data-binding.md#refusals).
 
-## `lb-input`
+## Each widget
 
-Wraps an `<input>`. The hub sets its `value` from the column `lb-column`
-names, and `lb-request` names what the widget sends on `change`:
+Each widget's parameters, the attributes it reads, and what a change sends
+are documented once, in the package that ships it: one page per widget,
+which the loadbare-widgets skill carries. Install that skill beside this one:
 
-```html
-<lb-input lb-column="name" lb-request="lb-row-update" exp-label="Name"></lb-input>
 ```
-
-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.
-
-| Parameter      | Fills                            |
-|----------------|----------------------------------|
-| `exp-label`    | The visible `<label>` text       |
-| `exp-type`     | The input's `type`, `text` when absent |
-| `exp-readonly` | The input's `readonly` attribute |
-
-## `lb-select`
-
-Wraps a `<select>` whose `<option>`s the page writes inside the tag:
-
-```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>
-```
-
-| Parameter   | Fills                      |
-|-------------|----------------------------|
-| `exp-label` | The visible `<label>` text |
-
-## `lb-options`
-
-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-query="statuses" lb-column="status" lb-request="lb-row-update" exp-label="Status">
-  <template><option lb-column="label"></option></template>
-</lb-options>
-```
-
-| Parameter   | Fills                      |
-|-------------|----------------------------|
-| `exp-label` | The visible `<label>` text |
-| `exp-size`  | The `<select>`'s `size`, an open list rather than a drop-down |
-
-- 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.
-- A group template holding an `<optgroup>` puts the options in groups, one
-  per run of the query's order's leading term. The widget labels each
-  `<optgroup>` from the `lb-group-value` the hub stamps on it:
-
-  ```html
-  <template lb-group>
-    <optgroup><template><option lb-column="label"></option></template></optgroup>
-  </template>
-  ```
-- A heading option marked `data-group-label` in the `<optgroup>`, `hidden`
-  and `disabled`, labels the group with its text instead, so the label can
-  be a column of the group's first row.
-- 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"
-></lb-picker>
+npx loadbare-widgets skills install
 ```
 
-| Parameter    | Fills                                   |
-|--------------|-----------------------------------------|
-| `exp-label`  | The visible `<label>` text              |
-| `exp-column` | The column each option shows            |
-
-An option built from two columns, a row with a second element, or options
-in groups, is `lb-options` with the page's own templates.
-
-## `lb-table`
-
-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-query="ledger" exp-caption="Ledger">
-  <template lb-exp-template="head">
-    <tr><th>Date</th><th>Amount</th></tr>
-  </template>
-  <template lb-group>
-    <tr><th colspan="2" lb-column="month"></th></tr>
-    <template>
-      <tr><td lb-column="date"></td><td lb-column="amount"></td></tr>
-    </template>
-  </template>
-  <template lb-exp-template="foot">
-    <tr><td>Total</td><td lb-sum="amount"></td></tr>
-  </template>
-</lb-table>
-```
-
-| Parameter     | Fills                |
-|---------------|----------------------|
-| `exp-caption` | The `<caption>` text |
-
-| Template                          | Fills                                   |
-|-----------------------------------|-----------------------------------------|
-| `<template lb-exp-template="head">` | The `<thead>`                         |
-| `<template lb-exp-template="foot">` | The `<tfoot>`                         |
-| Any other `<template>`            | The row or group template, in the `<tbody>` |
-
-- The hub places the rows by the query's order and builds its groups, and
-  leaves them where they stand for an edit from inside the table; see
-  [Rows the user is working in](./data-binding.md#rows-the-user-is-working-in). The
-  rows land in the one `<tbody>`, so a group here is a heading row with its
-  rows after it.
-- `lb-order` and `lb-filter` go on the `lb-table` itself, beside
-  `lb-query`; see [Order](./data-binding.md#order) and
-  [Filters](./data-binding.md#filters).
-- The footer is not a row of `ledger`. An aggregate there covers every row
-  showing;
-  a figure that is not a sum of the rows, such as a budget, is a `<tr>`
-  naming a `row` query of its own.
-- A `<template lb-exp-template="ghost">` is a blank row for entering a new
-  one, in a `<tbody>` of its own. The widget joins its controls to a form
-  outside the table, since a `<form>` cannot wrap a `<tr>`, and puts the
-  cursor back in it once an insert from it succeeds.
-- After rows land, the widget scrolls the row the page's own request created
-  or moved into view.
-- Text selected in a cell whose `lb-column` the table's `lb-filter` names
-  becomes that column's filter in `lb-choices`: `=` for the whole text,
-  `^=` from its start, `$=` up to its end, `*=` otherwise.
-- The heading of the order's leading column carries a triangle for the
-  direction, read from [`lb-query-order`](./data-binding.md#order). A
-  heading's column is the `lb-column` in the cell at its position in the row
-  template. While rows stand out of order the triangle carries
-  `data-unsorted` and a click on its heading re-sorts. With `lb-order`, a
-  click on the sorted heading reverses the order and a click on another
-  sorts by its column. Not on a grouped table.
-
-## `lb-confirm`
-
-A button that asks before it sends. The page writes the question inside the
-tag, and the request goes on the dialog's confirm button, so nothing reaches
-the hub until the user says yes:
-
-```html
-<lb-confirm exp-label="Delete" exp-request="lb-row-delete">
-  Delete <b lb-column="name"></b>?
-</lb-confirm>
-```
-
-| 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 widget closes the dialog once the request succeeds, and leaves it open
-on a refusal.
-
-## `lb-form`
-
-A `<form>` over one row's controls. A row with a key saves each control's
-column on `change`; a row whose key is empty is new, and the hub sends no
-update for it, so its controls wait for a submit. A definition only.
-
-| Parameter | Fills           |
-|-----------|-----------------|
-| `exp-id`  | The form's `id` |
-
-## `lb-insert-dialog`
-
-A row entered in a modal dialog, written once outside every row and opened
-with `commandfor` and `command="show-modal"`. Save is the form's
-`lb-row-insert`; on success the widget chooses the new row in the nearest
-`lb-options` around the button that opened it, and closes. The handler
-answers with a patch holding the new row.
-
-While 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.
-
-| Parameter   | Fills                                             |
-|-------------|---------------------------------------------------|
-| `exp-id`    | The dialog's `id`                                 |
-| `exp-title` | The dialog's heading                              |
-| `exp-query` | The form's `lb-query`, which it inserts into      |
-| `exp-save`  | The Save button's text, `Save` when absent        |
-
-## `lb-master`
-
-A set, one of its rows, and the buttons that act on the set: New, Copy,
-Delete, Save new and Cancel, each shown only for a row on record or a new
-one. A definition only, built from `lb-form` and `lb-confirm`. New sends
-`new` and Copy sends `copy`, requests the page declares; `new` returns
-`url()` emptying the parm that names the row.
-
-| Parameter     | Fills                                      |
-|---------------|--------------------------------------------|
-| `exp-row`     | The `lb-query` of the row the form shows   |
-| `exp-form-id` | The form's `id`, `master-form` when absent |
-
-## `lb-checkbox`
-
-A checkbox and its label as one element, for an application to style. A
-definition only: a native checkbox is already a control (see
-[Checkboxes](./data-binding.md#checkboxes)), so the widget is the markup, a
-`<label>` holding the `<input type="checkbox">` and a `<span>` with the
-text. The column and request go on the checkbox inside, so they arrive as
-expansion attributes.
-
-Unlike `lb-input`, it has no script making the tag the control. A value
-that lands before a widget's script has loaded arrives only as the string
-stamp `lb-column-value`, and a script checkbox would read `"false"` as
-checked. The hub sets a native checkbox's `checked` directly.
-
-| 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 |
-
-## `lb-number` and `lb-date`
-
-A number shown by the browser's `Intl.NumberFormat`, and a date or time
-shown by `Intl.DateTimeFormat`.  Neither is a control: `lb-column` goes on
-the tag, and the widget renders the `lb-column-value` the hub stamps; see
-[Receiving a value](./custom-elements.md#receiving-a-value).
-
-```html
-<lb-number lb-column="balance" exp-style="currency" exp-currency="USD"></lb-number>
-<lb-date lb-column="due" exp-date-style="medium"></lb-date>
-```
-
-Each parameter is one of Intl's options in kebab-case, as `exp-currency-sign`
-for `currencySign`, plus `exp-locale`.  A value that is no number or date
-shows as it arrived, and a date alone, `YYYY-MM-DD`, shows as that day in
-every time zone.  The stamp keeps the raw value, so a stylesheet selects on
-it:
-
-```css
-lb-number[lb-column-value^="-"] { color: var(--negative); }
-```
-
-## `lb-unknown-page`
-
-The chrome's dialog for a URL that names no page, as one tag:
-
-```html
-<lb-hub>
-  <nav>...</nav>
-  <main></main>
-  <lb-unknown-page></lb-unknown-page>
-</lb-hub>
-```
-
-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 |
+For a reader without the skill, the package's
+[README](https://gitlab.com/kendowns/loadbare/-/blob/main/packages/widgets/README.md)
+lists the widgets and links each page.