@loadbare/widgets 0.4.0 → 0.6.0

package/docs/lb-select.md

@@ -1,14 +1,14 @@
 # `lb-select`
 
-A wrapper for HTML Select, with the `<option>`s written by hand.
+A control wrapping an HTML `<select>`, with the `<option>`s written by hand.
 
-Apply the `lb-cell` attribute to name the column, and `lb-action` to name the
-action a change sends.
+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-cell="status" exp-label="Status" lb-action="setStatus">
+<lb-select lb-column="status" exp-label="Status" lb-request="setStatus">
   <option value="open">Open</option>
   <option value="closed">Closed</option>
 </lb-select>
@@ -22,30 +22,48 @@ improvements through iterative use.
 ## Parameters
 
 | Parameter   | Fills                      |
-|-------------|----------------------------|
+| ----------- | -------------------------- |
 | `exp-label` | the visible `<label>` text |
 
-## Binding
+## Attributes
 
-| Attribute   | Read from          | Names                       |
-|-------------|--------------------|-----------------------------|
-| `lb-cell`   | the element itself | the column the select shows |
-| `lb-action` | the element itself | the action a change sends   |
-| `lb-query-parm` | the element itself | the query parm a change writes |
+| 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.
 
 ## Choosing
 
-Choosing an option notifies the hub, which fires a request to the server: the
-action named by `lb-action`, carrying the chosen option's value. Declare that
-action on the server.
+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.
 
-`lb-action` is required, unless the select carries `lb-query-parm`, in which
-case the hub writes the choice into the URL and the select sends nothing.
-Without either, a change does nothing.
+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-pending`, and on failure with `lb-error`. Both are there for a
-stylesheet to read.
+`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).

package/docs/lb-table.md

@@ -2,24 +2,28 @@
 
 A wrapper for HTML Table, supplying the `<table>` itself.
 
-Apply the `lb-list` attribute to name the query. Write three `<template>`s
-inside the tag: one marked `lb-template="head"` for the heading row, one
-carrying `lb-key` for the row, and optionally one marked `lb-template="foot"`
-for the footer. Apply `data-sort` and `data-group` to the row template to order
-and section the rows.
+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, 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`.
 
 ```html
-<lb-table lb-list="ledger" exp-caption="Ledger">
-  <template lb-template="head">
+<lb-table lb-query="ledger" exp-caption="Ledger">
+  <template lb-exp-template="head">
     <tr><th>Date</th><th>Amount</th></tr>
   </template>
-  <template lb-key="id" data-sort="date" data-group="month">
-    <tr><td lb-cell="date"></td><td lb-cell="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-template="foot">
-    <tr lb-row="ledger-total"><td>Total</td><td lb-cell="total"></td></tr>
+  <template lb-exp-template="foot">
+    <tr><td>Total</td><td lb-sum="amount"></td></tr>
   </template>
 </lb-table>
 ```
@@ -35,35 +39,65 @@ improvements through iterative use.
 ## Parameters
 
 | Parameter     | Fills                |
-|---------------|----------------------|
+| ------------- | -------------------- |
 | `exp-caption` | the `<caption>` text |
 
-## Binding
+## Attributes
 
-| Attribute  | Read from                        | Names                              |
-|------------|----------------------------------|------------------------------------|
-| `lb-list` | the element itself               | the query whose rows fill the body |
-| `lb-key` | the row template             | the column that identifies a row   |
-| `data-sort`  | the row template                 | the column rows are ordered by     |
-| `data-group` | the row template                 | the column rows are sectioned by   |
-| `lb-cell`  | 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      |
 
-## Sorting and grouping
+The server declares the query's key and its order.
 
-`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.
+## Order and groups
+
+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-row` — a grand total is a second query, 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
 
-`lb-table` carries `lb-row-count` with the number of rows showing, for a
+`lb-table` carries `lb-query-row-count` with the number of rows showing, for a
 stylesheet to read.
 
-For a repeater with no table of its own, see [`lb-list`](./lb-list.md).
+For rows with no table of their own, write the row template inside any element
+that carries `lb-query`.

package/docs/lb-unknown-page.md

@@ -3,13 +3,13 @@
 > Status: a barebones starter.  Iterative use will drive improvements.
 
 The chrome's dialog for a URL that names no page.  Write it once, inside
-`<lb-hub>`, and the hub opens it whenever a path resolves to no page host.
+`<lb-hub>`, and the hub opens it whenever no page's stub matches the path.
 
 ```html
 <lb-hub>
   <nav>
-    <a href="/" lb-nav-link>Home</a>
-    <a href="/about" lb-nav-link>About</a>
+    <a href="/" lb-url-link>Home</a>
+    <a href="/about" lb-url-link>About</a>
   </nav>
   <main></main>
   <lb-unknown-page></lb-unknown-page>
@@ -19,24 +19,22 @@ The chrome's dialog for a URL that names no page.  Write it once, inside
 ## Parameters
 
 | Parameter         | Fills                                 |
-|-------------------|---------------------------------------|
+| ----------------- | ------------------------------------- |
 | `exp-button-text` | the text of the button that closes it |
 
 Leaving `exp-button-text` off labels the button `OK`.
 
 ## Binding
 
-The definition supplies its own binding: a `<dialog lb-unknown-page>` scoped
-to the hub's `lb-navigation` query, which the hub lands on every navigation.
+The definition supplies its own binding: a `<dialog lb-url-unknown>` carrying
+`lb-query="lb-url"`, the query the hub serves and lands on every page load.
 
-| Cell         | Holds                                                     |
-|--------------|-----------------------------------------------------------|
-| `page-label` | the text of the nav anchor for the path, or empty if none |
-| `page-uri`   | the path and query string as the browser has them         |
+| Column    | Holds                    |
+| --------- | ------------------------ |
+| `lb-path` | the path the browser has |
 
-The widget shows both.  It does not yet choose between "the page *Members*
-is not in this app" and "the URL */members* is not in this app"; that is the
-improvement iterative use is expected to drive.
+The widget shows the path.  The dialog opens only when no page matches, so
+there is no page label to show.
 
 ## Inside the hub
 

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.4.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.8.2 <1.0.0"
+    "@loadbare/app": ">=0.13.0 <1.0.0"
   },
   "devDependencies": {
-    "@loadbare/app": ">=0.8.2 <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",