@loadbare/app 0.11.0 → 0.13.0

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

@@ -1,7 +1,8 @@
 # The Basic Widget Library
 
-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
+Ten widgets: `lb-input`, `lb-select`, `lb-options`, `lb-picker`, `lb-table`,
+`lb-unknown-page`, `lb-confirm`, `lb-form`, `lb-insert-dialog` and
+`lb-master`. 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.
 
@@ -43,6 +44,7 @@ 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`
@@ -67,9 +69,7 @@ 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 data-group="category">
-    <option lb-column="label"></option>
-  </template>
+  <template><option lb-column="label"></option></template>
 </lb-options>
 ```
 
@@ -79,9 +79,15 @@ writes the row template inside the widget:
 
 - 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 of that column, added and removed as rows arrive
-  and leave.
+- 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>
+  ```
 - Its `value` selects the option with that key, including an option that
   arrives after the value did.
 
@@ -100,7 +106,6 @@ one option showing one column:
   lb-request="lb-row-update"
   exp-label="Status"
   exp-column="label"
-  exp-group="category"
 ></lb-picker>
 ```
 
@@ -108,10 +113,9 @@ one option showing one column:
 |--------------|-----------------------------------------|
 | `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.
+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`
 
@@ -123,11 +127,14 @@ row, the row template, and optionally a footer, each as a `<template>`:
   <template lb-exp-template="head">
     <tr><th>Date</th><th>Amount</th></tr>
   </template>
-  <template data-sort="date" data-group="month">
-    <tr><td lb-column="date"></td><td lb-column="amount"></td></tr>
+  <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 lb-query="ledger-total"><td>Total</td><td lb-column="total"></td></tr>
+    <tr><td>Total</td><td lb-sum="amount"></td></tr>
   </template>
 </lb-table>
 ```
@@ -140,15 +147,78 @@ row, the row template, and optionally a footer, each as a `<template>`:
 |-----------------------------------|-----------------------------------------|
 | `<template lb-exp-template="head">` | The `<thead>`                         |
 | `<template lb-exp-template="foot">` | The `<tfoot>`                         |
-| Any other `<template>`            | The row template, in the `<tbody>`      |
-
-- `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.
+| 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. The
+  rows land in the one `<tbody>`, so a group here is a heading row with its
+  rows after it.
+- The footer is not a row of `ledger`. An aggregate there covers every row;
+  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.
+
+## `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 `lb-request-done` says the request
+succeeded, 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 widget stops an
+`lb-row-update` that carries no key, so its controls wait for a submit.
+
+| 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.
+
+| 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: 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`. Copy sends `copy`, a
+request the page declares.
+
+| 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-unknown-page`