@loadbare/app 0.21.0 → 0.23.0

package/docs/reference/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.

package/docs/temp-proposals.md

@@ -0,0 +1,251 @@
+# Proposals
+
+Working notes for changes not yet made.  Not part of the skill.
+
+## The mental model
+
+A `row` maps to an HTML form.  It supports select, insert, update and delete.
+The hub handles the basics, such as resetting a form after an insert, and
+lifecycle methods let a custom element add behavior of its own.
+
+`rows` treats each of its rows as a `row`, and allows insert, update and
+delete of several rows at once.  It also places its rows by sorting and
+filtering, each with an automatic or a manual flag.
+
+A form sends a parent `row` with its nested `rows` in one submit, and the
+handler writes them together.  This is the foreign key.
+
+The URL names the page, and its query parms are the server's filters.  The
+user's own sorts and filters are choices, held in `lb-choices`.
+
+Requests go up, from the element that committed through its ancestors to the
+hub, which completes them from what surrounds the element.  Commands go
+sideways, by id to the element they name, carrying the button that sent them,
+and never reach the server.  Lifecycle methods go down, from the hub to the
+custom elements it placed.
+
+What lies past this belongs to the application.  It reaches the hub as fields
+a custom element supplies on a request, and through lifecycle methods the hub
+calls on a custom element.
+
+## 1. Values kept across inserts
+
+Package: `@loadbare/widgets`.  No change to `@loadbare/app`.
+
+### Today
+
+After an insert succeeds, the hub resets the form the insert was gathered
+from, then calls `lbRequestDone` on the attached custom elements from the
+committing element outward.  `detail.request.values` holds the values the
+insert sent, by column.  A ghost row starts over empty, and each control
+returns to its HTML default.
+
+A page that wants some columns to carry over to the next row, such as a date
+or an account during a run of entries, has no way to say so.
+
+### Proposal
+
+A widget around the list, `lb-keep` or similar, names the columns to keep:
+
+```html
+<lb-keep exp-columns="date, account">
+  <lb-table lb-query="entries">
+    ...
+  </lb-table>
+</lb-keep>
+```
+
+In `lbRequestDone`, after a successful `lb-row-insert`, the widget sets each
+named column's control in the committing row back to the value the insert
+sent.  The hub's reset and the refill run in one synchronous stretch, so the
+empty row is never painted.
+
+- A column not named returns to its HTML default: `value` on an input,
+  `selected` on an option.  A control with no default comes back blank.
+- A reset the user asks for, with a reset button, sends no request and is
+  not followed by `lbRequestDone`.  It clears every column.
+- Kept values live in the controls.  A reload starts the row empty.
+
+### Open
+
+- A starting value taken from the page, not from the last insert: ef's
+  paychecks page enters a paycheck while showing a series, and the new
+  paycheck's series is the one showing.  A possible form is a default named
+  as `query.column`.
+- Whether every wrapped control in `@loadbare/widgets` takes an HTML
+  default.
+
+## 2. Sorted and filtered placement
+
+Package: `@loadbare/app`.
+
+### Today
+
+When a patch lands on a list, the hub either places the rows by the order and
+the filter, or holds them where they stand.  It holds them when the request
+was sent from inside the list: the list is the nearest element carrying
+`lb-query` around the element that committed, or the request came from a form
+that `--lb-edit` pointed at one of its rows.
+
+Where the committing element sits is the only input to that decision.  Two
+cases in ef come out wrong:
+
+- Matching.  "Create rule and apply it" is a form in a side panel.  Its answer
+  patches the rows the rule matched, and under the filter "Unmatched only"
+  they disappear.  The user wants them to stay showing for review.  An offset
+  chosen with the form `--lb-edit` points at a row is held, so the two ways of
+  matching a transaction behave differently.
+- Paychecks.  "Change from here…" is a form pointed with `--lb-edit`, so its
+  answer is held.  The answer replaces the rest of the year, and the new
+  paychecks land after the last row of the series, out of date order.  The
+  page carries a Re-sort button for this.
+
+Neither table has edits in its rows.  Every edit on both is made in a form
+outside the table.
+
+### Proposal
+
+The element carrying `lb-query` declares each kind of placement, `auto` or
+`manual`.  Both default to `auto`.  Spelling is open; for illustration:
+
+```html
+<lb-table lb-query="entries" lb-order="entries_order"
+          lb-filter="description, txn_date, is_unmatched"
+          lb-order-placement="manual" lb-filter-placement="manual">
+```
+
+The rule about where a request was sent from is removed.
+
+Each line of today's held behavior falls under one flag:
+
+| The answer                             | `manual`                           | Flag   |
+| -------------------------------------- | ---------------------------------- | ------ |
+| Changes a column the order reads       | The row stays where it stands      | order  |
+| Creates a row                          | The row goes last in its group     | order  |
+| Changes the column its group breaks on | The row stays under its heading    | order  |
+| Changes a row so the filter hides it   | The row stays showing              | filter |
+| Drops a row                            | The row leaves, under either value | —      |
+
+Under `auto`, the rows are placed by the order and the filter on every
+landing.
+
+Every combination has a use:
+
+| Order    | Filter   | Example                                                  |
+| -------- | -------- | -------------------------------------------------------- |
+| `auto`   | `auto`   | Paychecks: a regenerated schedule lands in date order    |
+| `manual` | `manual` | Matching: answered rows stay in place for review         |
+| `auto`   | `manual` | Answered rows stay showing and move into the order       |
+| `manual` | `auto`   | A to-do list: an edit does not move a row, done hides it |
+
+A row left where the order or the filter would not leave it is stamped, as
+`lb-row-unsorted` is today, and counted in `lb-query-unsorted-count`.  The rows
+are placed by both again when the page loads, when the user's order or filter
+changes, and on `--lb-sort`.
+
+### The command
+
+`--lb-sort` today places the rows by both the order and the filter, so a row
+kept despite the filter leaves on it.  Under the flags it is renamed for what
+it does, `--lb-place` or similar.
+
+A side set to `auto` is in place after every landing, so one command does
+what each list needs:
+
+| Order    | Filter   | The command       |
+| -------- | -------- | ----------------- |
+| `manual` | `auto`   | Sorts             |
+| `auto`   | `manual` | Filters           |
+| `manual` | `manual` | Sorts and filters |
+| `auto`   | `auto`   | Changes nothing   |
+
+Separate `--lb-sort` and `--lb-filter` differ from it only when both sides are
+`manual` and the user applies one without the other.  No case for that is in
+hand.
+
+### Effect on ef
+
+- Matching declares both `manual`.  The rule's answer and the offset form
+  behave alike, wherever the form sits.
+- Paychecks declares nothing.  The Re-sort button and its comment are removed.
+
+### Effect on other pages
+
+A list that relies on being held today, such as an editable `lb-table` with a
+ghost row, declares `manual` to keep its behavior.  Under `auto`, a row edited
+in place moves into the order, and a row entered in the ghost row is placed by
+the order.
+
+### Open
+
+- The attribute names.
+- One stamp for both kinds of out-of-place row, or one for each, so a page can
+  style a row out of order apart from a row kept despite the filter.  The
+  commands follow the stamps.  One stamp has one count, one button shown while
+  it is not 0, and one command.  Two stamps let a page show Re-sort and
+  Re-filter apart, each with its own command, `--lb-sort` and `--lb-filter`,
+  beside the one for both.  Every name carries the `--` prefix, or the
+  browser ignores it.
+
+## 3. Child rows entered with their parent
+
+Package: `@loadbare/app`.
+
+### Today
+
+A form gathers the live rows of a query nested in its own, and sends them in
+`rows` beside its own `values`.  The handler writes the parent and its child
+rows together.  A live row is one the nested query answered, so the child rows
+exist before the form is sent: ef's paycheck form sends one amount per
+deduction type, and the types come from the database.
+
+A row not yet entered, carrying `lb-key-value=""`, arises only as a single
+row: a `row` query answering with an empty key, or a form pointed by
+`--lb-new`.  A list holds no row not yet entered.
+
+ptracking's flight page enters a flight, then its arrivals.  The arrivals
+section shows once the flight is on record, and each arrival is its own
+`lb-row-insert` from the ghost row, keyed by the `flight_id` parm.  The
+arrivals handler refuses an insert with no flight: "Save the flight first."
+Most flights have one arrival, and pattern work is one arrival with a
+quantity, so the usual entry is two saves and a second form.
+
+### Proposal
+
+A list may hold rows not yet entered.
+
+1. Inside a parent not yet entered, the list's Add puts a row not yet entered
+   into the list, and sends nothing.
+2. The parent's form gathers those rows with its insert, each with no key,
+   under the nested query's name in `rows`.
+3. The parent's handler inserts the parent and its child rows in one
+   transaction, and answers both.  The rows not yet entered are replaced by
+   the rows the answer lands.
+4. Once the parent is on record, the list's Add inserts as it does today.
+
+A row not yet entered in a list follows the existing rules for one:
+
+- Its controls carrying `lb-request="lb-row-update"` send nothing and hold
+  what the parent's submit gathers.  Once the row is on record, they save as
+  they change.
+- A delete from it sends nothing.  The row is removed from the list.
+- A refusal of the parent's insert leaves it in place, and a column's message
+  goes on its control, as for any control the request gathered.
+
+### Effect on ptracking
+
+- The arrivals list moves inside the flight's form, and loses
+  `lb-show="on_record"`.
+- The flight's `rowInsert` accepts `rows.arrivals` and inserts both.
+  `detailCrud` writes the parent alone today.
+- A flight with one arrival is one save.  A flight with three approaches is
+  three rows not yet entered and one save.
+
+### Open
+
+- The command that adds a row not yet entered: the ghost row's insert,
+  changing meaning while the parent is not on record, or a command of its own.
+- `lb-table` joins the ghost row's controls to a form of its own, outside the
+  table, with the `form` attribute.  A ghost row inside a parent's form then
+  belongs to the ghost row's form, not the parent's.
+- One level only, as for a form over a set of rows today.

package/docs/testing.md

@@ -274,7 +274,8 @@ What the hub is tested for here:
   a pending element is ignored
 - a round trip the server never answers is aborted at the ten-second
   deadline, under mocked timers, and fails the way any round trip fails
-- a successful insert gathered from a form resets the form
+- a successful insert gathered from a form resets the form, unless the
+  answer landed the new row on it
 - a path with no page reports, lands `lb-page-unknown`, and opens the
   `lb-url-unknown` dialog; two pages for one stub report and take the first
 - `lb-url` lands with the path, the page's `lb-page-title` or stub as

package/docs/tutorials/000-getting-started.md

@@ -57,7 +57,7 @@ Add a command to package.json that builds the app.
 ```json
 {
   "scripts": {
-    "dev": "loadbare-app-build --watch & node server.js"
+    "dev": "loadbare-app-build --watch & trap 'kill $! 2>/dev/null' EXIT INT TERM; node server.js"
   }
 }
 ```

package/docs/tutorials/040-displaying-data.md

@@ -159,7 +159,7 @@ runner:
 ```json
 {
   "scripts": {
-    "dev": "loadbare-app-build --watch & tsx server.js"
+    "dev": "loadbare-app-build --watch & trap 'kill $! 2>/dev/null' EXIT INT TERM; tsx server.js"
   }
 }
 ```

package/docs/tutorials/090-using-widget-libraries.md

@@ -90,7 +90,7 @@ publication — that's the same class shape
 [Committing a Control](./080-widget-requests.md) already wrote, packaged and
 given an import specifier instead of living in an application's `src/`.
 It doesn't cover `lb-table`'s footer destination or `lb-picker`'s
-expansion parameters, which are in
+expansion parameters, which each widget's own page covers; see
 [The Basic Widget Library](../reference/widgets.md).
 
 ---

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@loadbare/app",
   "description": "High performance web app framework for server-bound applications",
-  "version": "0.21.0",
+  "version": "0.23.0",
   "type": "module",
   "files": [
     "dist",
@@ -22,7 +22,9 @@
     "./constants": "./dist/core/lb-constants.js",
     "./types": "./dist/core/lb-types.js",
     "./server": "./dist/server/lb-server.js",
-    "./express": "./dist/server/lb-express.js"
+    "./express": "./dist/server/lb-express.js",
+    "./build": "./dist/build/build.js",
+    "./dev": "./dist/dev/lb-dev.js"
   },
   "scripts": {
     "prepublishOnly": "npm run typecheck && npm run test && npm run build",