@loadbare/app 0.22.0 → 0.24.0

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

@@ -208,9 +208,9 @@ evidence here.
 - `lb-query-row-count` counts the rows showing, so all rows and a patch
   ending in the same state report the same number, and a row a filter hides
   is not counted
-- the order places all rows and a patch alike, except where an edit came
-  from inside the list, which leaves its rows standing and stamped until
-  the user asks for the order; groups come and go with
+- the order and the filter place all rows and a patch alike, except where
+  the list's `lb-manual` leaves a side to the user, which keeps its rows
+  standing and stamped until they are placed again; groups come and go with
   their rows to any depth, aggregates follow every landing, and every change
   leaves a stamp a stylesheet can see (`lb-order.test.ts`)
 - a filter's text reads and passes values as documented, and a choice of

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@loadbare/app",
   "description": "High performance web app framework for server-bound applications",
-  "version": "0.22.0",
+  "version": "0.24.0",
   "type": "module",
   "files": [
     "dist",

package/skills/loadbare-app/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: loadbare-app
-description: Build server-bound web applications with Loadbare/app. Covers the file conventions the builder finds by name (`chrome.html`, `*.page.html`, `*.queries.ts`, `*.requests.ts`, `imports.ts`, `<tag>.html`, `<tag>.browser.ts`); the `lb-*` attribute vocabulary that lands query rows on HTML and issues requests (`lb-query`, `lb-column`, `lb-show`, `lb-request`); queries declared with `row(key, run)` and `rows(key, run)`; the URL as the hub's own query `lb-url`, with `lb-url-link`, `lb-url-parm`, `lb-url-push` and `lb-url-unknown`; the user's order and filters as the hub's query `lb-choices`, read by `lb-order` and `lb-filter`; whether the page loaded and the server answers as the hub's query `lb-hub`; one form pointed at a row by the `--lb-edit`, `--lb-new` and `--lb-release` commands; re-sorting a list with `--lb-sort`; build-time expansion with `exp-*` parameters, `lb-exp-slot` and `lb-exp-template`; custom elements as form-associated controls and row hosts; the Express wiring with `hubRoutes`; and the `@loadbare/widgets` library. Use whenever a task involves `@loadbare/app`, `@loadbare/widgets`, `loadbare-app-build`, an `lb-` attribute, or a page, query, request or custom element file in a Loadbare application. The model is not React, htmx or REST, and cannot be inferred from them.
+description: Build server-bound web applications with Loadbare/app. Covers the file conventions the builder finds by name (`chrome.html`, `*.page.html`, `*.queries.ts`, `*.requests.ts`, `imports.ts`, `<tag>.html`, `<tag>.browser.ts`); the `lb-*` attribute vocabulary that lands query rows on HTML and issues requests (`lb-query`, `lb-column`, `lb-show`, `lb-request`); queries declared with `row(key, run)` and `rows(key, run)`; the URL as the hub's own query `lb-url`, with `lb-url-link`, `lb-url-parm`, `lb-url-push` and `lb-url-unknown`; the user's order and filters as the hub's query `lb-choices`, read by `lb-order` and `lb-filter`; whether the page loaded and the server answers as the hub's query `lb-hub`; one form pointed at a row by the `--lb-edit`, `--lb-new` and `--lb-release` commands; rows that hold still under `lb-manual` and are placed again with `--lb-place`; build-time expansion with `exp-*` parameters, `lb-exp-slot` and `lb-exp-template`; custom elements as form-associated controls and row hosts; the Express wiring with `hubRoutes`; and the `@loadbare/widgets` library. Use whenever a task involves `@loadbare/app`, `@loadbare/widgets`, `loadbare-app-build`, an `lb-` attribute, or a page, query, request or custom element file in a Loadbare application. The model is not React, htmx or REST, and cannot be inferred from them.
 license: Apache-2.0
 metadata:
   package: "@loadbare/app"
@@ -194,11 +194,17 @@ row is filled from the nested query's last answer, whatever order they land
 in.
 
 **A `rows` query declares its order, and the hub places every row by it.**
-An edit sent from inside a list, or from a form `--lb-edit` pointed at one
-of its rows, leaves that list's rows where they stand, stamped `lb-row-unsorted` where out of order, until the page loads, the
-user's order or filter changes, or a button with `commandfor` naming the
-list sends `command="--lb-sort"`, which places them with no round trip;
-show it by `[lb-query-unsorted-count]`.  Never refresh to make rows hold
+It places them by the order and the user's filter on every landing.  A list
+whose rows must hold still while the user works through them carries
+`lb-manual="order"`, `"filter"` or `"order filter"`: an answer to any
+request, from wherever it was sent, then leaves that side alone, so an
+edited row stays where it stands, a new row goes last in its group, and a
+row the filter would hide stays showing.  A row left out of place is
+stamped `lb-row-unplaced` until the page loads, the user's order or filter
+changes, or a button with `commandfor` naming the list sends
+`command="--lb-place"`, which places them with no round trip; show it by
+`[lb-query-unplaced-count]`.  An editable list with a ghost row usually
+wants `lb-manual="order"`.  Never refresh to make rows hold
 still, and never to put them back in order.
 `rows("id", run, { order: "category_order,name" })`; a column after `-` sorts
 descending, and values compare by JSON type, so a numeric sort column is a
@@ -265,7 +271,9 @@ control whose form owner it is.  An element in a live row gathers that live
 row.  Anything else gathers its form owner's controls.  A `<form>` cannot
 wrap a `<tr>`, so an insert row in a table puts its controls in a form
 elsewhere with the HTML `form` attribute.  A checkbox is a control: checked
-unless its column is `false` or null, and gathered as `"true"` or `"false"`.
+unless its column is `false`, null, `"false"` or `""`, and gathered as
+`"true"` or `"false"`; one carrying `value` is instead one of a set
+holding a repeated query parm.
 A radio button is a control: checked when its `value` is the column's
 value, and the group gathers the one checked, or `""`.  In a row template
 the hub stamps its `name` with the row's key, so each row is its own group.
@@ -283,7 +291,7 @@ in every row.  Write one form naming the set's query, outside every row,
 often in a `<dialog>`, and give it an `id`.  A `type="button"` with
 `commandfor="<id>"` and `command="--lb-edit"` in a live row fills it from
 that row with no round trip; `--lb-new` starts it empty for an insert;
-`--lb-release` lets it go.  (`--lb-sort` is the fourth command, for a list,
+`--lb-release` lets it go.  (`--lb-place` is the fourth command, for a list,
 not a form.)  The form's `lb-key-value` is the row's key, empty
 for a new row, absent when not in use, and a stylesheet shows Save or Save
 new by it.  A successful request from the form, or its dialog closing, lets
@@ -341,7 +349,7 @@ fills a new row from the last one.
 
 **The usual reasons for a refresh each have a patch.**
 - A row whose position changes: the hub places it by the query's order, or
-  holds it where the user is working; a refresh changes neither.
+  holds it where it stands under `lb-manual`; a refresh changes neither.
 - A group that appears or goes: the hub makes it with its first row and
   removes it with its last.
 - A row whose other columns change with the edit: re-read the row and patch
@@ -378,7 +386,11 @@ keyed by `lb-path`, with `lb-page-label`, `lb-page-unknown`, and one column
 per query parm.  A control inside `lb-query="lb-url"` carrying
 `lb-request="lb-row-update"` writes its parm; the hub replaces the history
 entry, or pushes one when the control carries `lb-url-push`, and reloads the
-page's queries with no request to the server.  An `<a lb-url-link>` moves
+page's queries with no request to the server.  A parm the URL repeats,
+`?band=3&band=5`, is one column holding an array of strings: a
+`<select multiple>`, or checkboxes carrying `value` and naming one column,
+write it, `url()` takes an array, and `contextFor` reads it with
+`parms.getAll`.  Only a query parm holds several values.  An `<a lb-url-link>` moves
 to its `href`; inside a row, `lb-url-parm="topic_id"` adds that column of
 the row to the `href` as the parm of the same name, so a link to another
 page narrowed by the row is a link, never a request or script.  Queries still take no arguments: `contextFor(req, parms)`
@@ -415,8 +427,8 @@ whole data channel.
 
 **The developer writes `lb-*` attributes in markup, and script never
 assigns them.**  The builder refuses any `lb-` attribute other than the
-seventeen in [Attributes](references/names.md#attributes): `lb-query`,
-`lb-column`, `lb-show`, `lb-order`, `lb-filter`, `lb-group`, `lb-count`,
+eighteen in [Attributes](references/names.md#attributes): `lb-query`,
+`lb-column`, `lb-show`, `lb-order`, `lb-filter`, `lb-manual`, `lb-group`, `lb-count`,
 `lb-sum`, `lb-avg`, `lb-min`, `lb-max`, `lb-select`, `lb-request`,
 `lb-url-link`, `lb-url-parm`, `lb-url-push` and `lb-url-unknown`.  `lb-exp-slot` and
 `lb-exp-template` are expansion's, and never reach the page.  Everything

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

@@ -238,6 +238,48 @@ and after Back alike
 Loadbare assigns no parm a meaning, and a column of `lb-url` whose name
 begins with `lb-` is never a query parm.
 
+### Several values
+
+A URL may repeat a parm, `/statements?band=3&band=5`, as an HTML form does
+for a `<select multiple>` or for checkboxes sharing a name. That column of
+`lb-url` holds every value, in order, as an array of strings. A parm the URL
+carries once is a string, as it always is. Two controls hold several values:
+
+```html
+<div lb-query="lb-url">
+  <select multiple lb-column="band" lb-request="lb-row-update">
+    <option value="3">Cash</option>
+    <option value="5">Investments</option>
+  </select>
+</div>
+
+<form lb-query="lb-url" lb-request="lb-row-update">
+  <label><input type="checkbox" lb-column="band" value="3" /> Cash</label>
+  <label><input type="checkbox" lb-column="band" value="5" /> Investments</label>
+  <button>Show</button>
+</form>
+```
+
+- A `<select multiple>` selects each option whose `value` is among the
+  column's, and writes the values of the options selected.
+- A checkbox carrying `value` is one of a set naming the column. It is
+  checked when its `value` is among the column's, and the set writes the
+  values of the ones checked. A checkbox without `value` is a flag; see
+  [Checkboxes](./data-binding.md#checkboxes).
+- Writing no value takes the parm out of the URL.
+- Either control carries the values as a JSON array in `lb-column-value`.
+- A control that holds one value, and any other element, shows the first,
+  as `URLSearchParams.get` reads it. A form-associated custom element
+  receives the value as it is, a string or an array, and may give an array
+  back; see [Being a control](./custom-elements.md#being-a-control).
+- A handler's `url()` writes several values as an array of strings, and
+  `contextFor` reads them with `parms.getAll`.
+
+Only a column of `lb-url` holds several values. Every other column holds
+one, so the builder refuses a control holding several anywhere but inside
+`lb-query="lb-url"`, and the server ignores a request that carries several
+for a column of its own.
+
 A query parm is user input. A query still takes no argument from the
 browser, and a parm arrives the way the session cookie does, as part of the
 request the context is built from, but a user who types `?acct=99999`

package/skills/loadbare-app/references/custom-elements.md

@@ -268,7 +268,7 @@ Each direction has one mechanism for each kind of message:
 
 | Direction      | What                                       | How                         | Today |
 |----------------|--------------------------------------------|-----------------------------|-------|
-| Hub to element | State that lasts                           | An attribute the hub stamps | `lb-column-value`, `lb-key-value`, `lb-query-row-count`, `lb-query-unsorted-count`, `lb-query-order`, `lb-group-*`, `lb-row-*`, `lb-request-pending`, `lb-request-error`, `lb-request-refused` |
+| Hub to element | State that lasts                           | An attribute the hub stamps | `lb-column-value`, `lb-key-value`, `lb-query-row-count`, `lb-query-unplaced-count`, `lb-query-order`, `lb-group-*`, `lb-row-*`, `lb-request-pending`, `lb-request-error`, `lb-request-refused` |
 | Hub to element | State the platform already names           | A property                  | A control's `value` |
 | Hub to element | What the hub did                           | An optional `lb` method     | `lbAttached`, `lbRowsLanded`, `lbRequestDone`, `lbDetached` |
 | Hub to element | A moment an element started                | A bubbling event            | `lb-request-done` |
@@ -404,6 +404,11 @@ customElements.define("star-rating", StarRating);
 Dispatch `change` with `bubbles: true`, as a native control's does, when the
 user commits an edit. Setting `value` from the hub fires nothing.
 
+Inside `lb-query="lb-url"`, a control may hold several values. The hub sets
+its `value` to a string, or to an array of strings when the URL repeats the
+parm, and gathers an array back when `value` gives one; see
+[Several values](./chrome.md#several-values).
+
 A form owns a form-associated custom element the way it owns an `<input>`,
 including through the HTML `form` attribute, so a form gathers it on submit.
 Write `formResetCallback` to restore the default value: the hub resets a form
@@ -627,7 +632,7 @@ had there hears the event, and no custom element the hub has removed hears
 ### Holding rows
 
 The hub lands every row template itself, places every row by the query's
-order (see [Rows the user is working in](./data-binding.md#rows-the-user-is-working-in)
+order (see [Placing by hand](./data-binding.md#placing-by-hand)
 for when it does not), and builds every group the markup's group templates describe; see
 [Order](./data-binding.md#order) and [Groups](./data-binding.md#groups). A
 plain element carrying `lb-query` with a row template inside it needs no
@@ -656,12 +661,12 @@ Everything else is the hub's:
 |-------------|----------------------------------------------------------|
 | Cloning     | Clones the row template once per new key                 |
 | Matching    | Fills the live row already showing that key, when its values changed |
-| Placing     | Places every live row by the user's order or the query's, and leaves them where they stand for an edit from inside the list |
+| Placing     | Places every live row by the user's order or the query's, and leaves them where they stand for an answer under `lb-manual` |
 | Filtering   | Hides a row the user's filter does not pass, and a group whose rows are all hidden |
 | Grouping    | Builds a group where the order breaks, keeps it while its run goes on, and removes it with its last row |
 | Removing    | Marks the live rows the response says are gone as leaving, and removes them |
 | Stamping    | Stamps each live row with `lb-row-live`, `lb-key-value`, and what happened to it |
-| Counting    | Stamps `lb-query-row-count` with the number of live rows showing, `lb-query-unsorted-count` with the number out of order, and `lb-query-order` with the order placing them |
+| Counting    | Stamps `lb-query-row-count` with the number of live rows showing, `lb-query-unplaced-count` with the number out of place, and `lb-query-order` with the order placing them |
 
 `lb-options.browser.ts` and `lb-table.browser.ts` in
 [`@loadbare/widgets`](./widgets.md) are two uses of `lbRowsLanded`: one