@loadbare/widgets 0.5.0 → 0.6.0

package/docs/lb-master.md

@@ -0,0 +1,53 @@
+# `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                                          |
+| -------- | ----------------- | --------------------------------------------- |
+| 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.  New is not a button:
+a button cannot write a query parm, so choosing the picker's blank starts a
+new row.
+
+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/docs/lb-options.md

@@ -6,8 +6,8 @@ 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.  Apply
-`data-group` to the template to section the options.
+the `<option>` itself — an `<option>` holds text, not elements.  For options
+in groups, write a group template holding an `<optgroup>`.
 
 Provide `exp-label`.
 
@@ -18,8 +18,10 @@ Provide `exp-label`.
   exp-label="Status"
   lb-request="setStatus"
 >
-  <template data-group="category">
-    <option lb-column="label"></option>
+  <template lb-group>
+    <optgroup>
+      <template><option lb-column="label"></option></template>
+    </optgroup>
   </template>
 </lb-options>
 ```
@@ -42,7 +44,7 @@ improvements through iterative use.
 | `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                |
-| `data-group` | the row template   | the column that sections the options       |
+| `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
@@ -50,8 +52,10 @@ The server declares the query's key.  The widget copies each option's
 
 ## Grouping
 
-`data-group` names a column whose distinct values become `<optgroup>`s, each
-labelled with the value.
+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.
 
 ## The control
 

package/docs/lb-picker.md

@@ -1,13 +1,15 @@
 # `lb-picker`
 
 [`lb-options`](./lb-options.md) with the row template built in, for when every
-row is one option and only the column names vary.  It takes no children.
+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`, `exp-column`, and optionally `exp-group`.
+Provide `exp-label` and `exp-column`.
 
 ```html
 <lb-picker
@@ -15,7 +17,6 @@ Provide `exp-label`, `exp-column`, and optionally `exp-group`.
   lb-column="status_id"
   exp-label="Status"
   exp-column="label"
-  exp-group="category"
   lb-request="setStatus"
 ></lb-picker>
 ```
@@ -27,15 +28,13 @@ improvements through iterative use.
 
 ## Parameters
 
-| Parameter    | Fills                                            |
-| ------------ | ------------------------------------------------ |
-| `exp-label`  | the visible `<label>` text                       |
-| `exp-column` | the column the option shows                      |
-| `exp-group`  | the column that sections the options, if grouped |
+| Parameter    | Fills                       |
+| ------------ | --------------------------- |
+| `exp-label`  | the visible `<label>` text  |
+| `exp-column` | the column the option shows |
 
-`exp-column` is required.  Leaving `exp-group` off leaves the options
-ungrouped.  The server declares the query's key, which becomes each option's
-`value`.
+`exp-column` is required.  The server declares the query's key, which
+becomes each option's `value`.
 
 ## Attributes
 

package/docs/lb-table.md

@@ -4,9 +4,10 @@ A wrapper for HTML Table, supplying the `<table>` itself.
 
 Apply the `lb-query` attribute to name the query.  Write three `<template>`s
 inside the tag: one marked `lb-exp-template="head"` for the heading row, one
-unmarked for the row, and optionally one marked `lb-exp-template="foot"` for
-the footer.  Apply `data-sort` and `data-group` to the row template to order
-and section the rows.
+unmarked for the row, or a group template holding it, and optionally one
+marked `lb-exp-template="ghost"` for a ghost row and one marked
+`lb-exp-template="foot"` for the footer.  The query's order places the
+rows.
 
 Provide `exp-caption`.
 
@@ -15,11 +16,14 @@ Provide `exp-caption`.
   <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>
 ```
@@ -40,27 +44,55 @@ improvements through iterative use.
 
 ## Attributes
 
-| Attribute    | On                               | Names                              |
-| ------------ | -------------------------------- | ---------------------------------- |
-| `lb-query`   | the element itself               | the query whose rows fill the body |
-| `data-sort`  | the row template                 | the column rows are ordered by     |
-| `data-group` | the row template                 | the column rows are sectioned by   |
-| `lb-column`  | elements inside the row template | the column each element shows      |
+| Attribute   | On                               | Names                              |
+| ----------- | -------------------------------- | ---------------------------------- |
+| `lb-query`  | the element itself               | the query whose rows fill the body |
+| `lb-group`  | a template holding the row template | a group, one per run of the order's leading term |
+| `lb-column` | elements inside the row template | the column each element shows      |
 
-The server declares the query's key.
+The server declares the query's key and its order.
 
-## Sorting and grouping
+## Order and groups
 
-`data-sort` names the column rows are ordered by, comparing the text each row
-shows.  `data-group` names the column they are sectioned by: each distinct
-value gets a heading row of its own, spanning the width of the row template,
-and rows sort within their section.
+The hub places the rows by the query's order and builds its groups.  The
+rows land in the table's one `<tbody>`, and a `<tbody>` cannot hold another,
+so a group here is a heading row with its rows after it.  For a `<tbody>` per
+group, write a plain `<table lb-query>` whose group template is the
+`<tbody>`.
+
+## The ghost row
+
+The `ghost` template is a blank row for entering a new one, in a `<tbody>` of
+its own between the rows and the footer.  It is not a live row: the hub never
+reconciles it and never counts it, and lands on whatever in it names a query.
+
+```html
+<template lb-exp-template="ghost">
+  <tr>
+    <td><lb-input lb-column="name" exp-label="Name"></lb-input></td>
+    <td><button lb-request="lb-row-insert">Save</button></td>
+  </tr>
+</template>
+```
+
+A `<form>` cannot wrap a `<tr>`, so the widget makes one outside the table
+and joins the row's controls and buttons to it with the `form` attribute.  A
+button carrying `lb-row-insert` submits that form, the hub gathers what the
+form owns, and resets it once the insert succeeds.  The widget then puts the
+cursor back in the row's first control.  A refused insert leaves the cursor
+where it was.
+
+## Scrolling
+
+After rows land, the widget scrolls into view the row the page's own request
+created, or moved by changing a column the order reads.
 
 ## The footer
 
 The footer is an ordinary part of the page, not a row from the table's query.
-Give it its own `lb-query` — a grand total is a second query of kind `row`,
-declared on the server like any other.
+An aggregate there covers every row.  A figure that is not a sum of the rows,
+such as a budget, is an element with its own `lb-query`, a query of kind
+`row` declared on the server like any other.
 
 ## Styling an empty table
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@loadbare/widgets",
-  "description": "The basic widget set for @loadbare/app: input, select, options, picker, table, unknown-page",
-  "version": "0.5.0",
+  "description": "The basic widget set for @loadbare/app: input, select, options, picker, table, unknown-page, confirm, form, insert-dialog, master",
+  "version": "0.6.0",
   "type": "module",
   "files": [
     "dist",
@@ -49,10 +49,10 @@
     "node": ">=22"
   },
   "peerDependencies": {
-    "@loadbare/app": ">=0.10.0 <1.0.0"
+    "@loadbare/app": ">=0.13.0 <1.0.0"
   },
   "devDependencies": {
-    "@loadbare/app": ">=0.10.0 <1.0.0",
+    "@loadbare/app": ">=0.13.0 <1.0.0",
     "@types/jsdom": "^21.1.7",
     "@types/node": "^22.0.0",
     "jsdom": "^25.0.0",