@loadbare/app 0.22.0 → 0.23.0

package/docs/reference/data-binding.md

@@ -173,18 +173,21 @@ column the user sorts or filters raw, and format it in the element.
 
 ### Checkboxes
 
-A checkbox is a control. It is checked when its column is anything but
-`false` or null, and it sends `"true"` or `"false"`
-([miswart](../miswarts.md#checkboxes-and-radio-groups-always-gather-a-value)):
+A checkbox is a control. It sends `"true"` or `"false"`
+([miswart](../miswarts.md#checkboxes-and-radio-groups-always-gather-a-value)),
+and it is checked when its column is anything but `false`, null, `"false"`
+or `""`:
 
 ```html
 <input type="checkbox" lb-column="active" lb-request="lb-row-update" />
 ```
 
-Checked follows the rule `lb-show` follows, so a query spells a flag as a
-boolean, and the string `"false"` is checked. Unchecked sends `"false"`
-rather than nothing, so a flag can be set back. The checkbox's `value`
-attribute means nothing to the hub.
+A checkbox lands what it sends, so it shows the same state after a round
+trip through a query whose values are strings, such as `lb-url` or
+`lb-choices`. A query parm the URL does not carry lands as `""`, so the
+checkbox is unchecked. Unchecked sends `"false"` rather than nothing, so a
+flag can be set back. The checkbox's `value` attribute means nothing to the
+hub.
 
 ### Radio buttons
 
@@ -464,8 +467,9 @@ are heading rows beside their rows:
 Content after the nested template lands after the group's rows, which is
 where a group's footer goes.
 
-A heading is filled from its group's first row, so it may show a column
-other than the one the group breaks on. A row an edit from inside the list
+A heading is filled from its group's first row as an element in a row is,
+`href`s from `lb-url-parm` included, so it may show a column other than the
+one the group breaks on. A row an edit from inside the list
 moved to another group stays under its old heading, and the heading shows
 the row as it stood, until the rows are placed again. The hub stamps each top-level
 element of a group with `lb-group-live`, `lb-group-column` and

package/docs/reference/dev-server.md

@@ -105,6 +105,7 @@ own from them.
 |--------------|------------------------|--------------------------------------------------------------|
 | `watchApp`   | `@loadbare/app/build`  | Builds, rebuilds on a change, and reports each build         |
 | `buildApp`   | `@loadbare/app/build`  | Builds once                                                  |
+| `watchTree`  | `@loadbare/app/build`  | Reports each changed file under a directory                  |
 | `appServer`  | `@loadbare/app/dev`    | The application's server as a child process, restarted on demand |
 | `gate`       | `@loadbare/app/dev`    | Holds requests while any reason to hold them stands          |
 | `devProxy`   | `@loadbare/app/dev`    | The browser's port, passing requests through a gate          |
@@ -123,6 +124,13 @@ fails. A build writes nothing until every output is ready, so a failed one
 leaves the last good build in place. `loadbare-app-build` is a thin command
 over these two.
 
+`watchTree(root, onFile)` calls `onFile(file)` for each file under `root`
+that is changed, added or removed, with its path relative to `root`. It
+watches each directory, including those made later, so a file saved by
+replacing it, as `sed -i` and many editors save, is reported on every save.
+Node's `fs.watch` with `recursive: true` loses such a file on Linux after
+its first save. It returns `{ close() }`. `watchApp` watches `src` with it.
+
 `appServer({ entry, port, portEnv, node, log })` returns `{ restart(),
 stop(), state }`. `restart()` stops the server if it runs, starts it, and
 resolves once it accepts connections, or has exited instead. `state` is
@@ -143,8 +151,7 @@ a plain message when the port is in use.
 A dev server that also restarts on a change to `config/`:
 
 ```ts
-import { watch } from "node:fs";
-import { watchApp } from "@loadbare/app/build";
+import { watchApp, watchTree } from "@loadbare/app/build";
 import { appServer, devProxy, gate } from "@loadbare/app/dev";
 
 const held = gate();
@@ -163,7 +170,7 @@ const watcher = watchApp({
     held.open("build");
   },
 });
-watch("config", { recursive: true }, () => void restart());
+watchTree("config", () => void restart());
 
 await watcher.ready;
 await restart();

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/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.23.0",
   "type": "module",
   "files": [
     "dist",

package/skills/loadbare-app/SKILL.md

@@ -265,7 +265,8 @@ 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"`.
 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.

package/skills/loadbare-app/references/data-binding.md

@@ -173,18 +173,21 @@ column the user sorts or filters raw, and format it in the element.
 
 ### Checkboxes
 
-A checkbox is a control. It is checked when its column is anything but
-`false` or null, and it sends `"true"` or `"false"`
-([miswart](./miswarts.md#checkboxes-and-radio-groups-always-gather-a-value)):
+A checkbox is a control. It sends `"true"` or `"false"`
+([miswart](./miswarts.md#checkboxes-and-radio-groups-always-gather-a-value)),
+and it is checked when its column is anything but `false`, null, `"false"`
+or `""`:
 
 ```html
 <input type="checkbox" lb-column="active" lb-request="lb-row-update" />
 ```
 
-Checked follows the rule `lb-show` follows, so a query spells a flag as a
-boolean, and the string `"false"` is checked. Unchecked sends `"false"`
-rather than nothing, so a flag can be set back. The checkbox's `value`
-attribute means nothing to the hub.
+A checkbox lands what it sends, so it shows the same state after a round
+trip through a query whose values are strings, such as `lb-url` or
+`lb-choices`. A query parm the URL does not carry lands as `""`, so the
+checkbox is unchecked. Unchecked sends `"false"` rather than nothing, so a
+flag can be set back. The checkbox's `value` attribute means nothing to the
+hub.
 
 ### Radio buttons
 
@@ -464,8 +467,9 @@ are heading rows beside their rows:
 Content after the nested template lands after the group's rows, which is
 where a group's footer goes.
 
-A heading is filled from its group's first row, so it may show a column
-other than the one the group breaks on. A row an edit from inside the list
+A heading is filled from its group's first row as an element in a row is,
+`href`s from `lb-url-parm` included, so it may show a column other than the
+one the group breaks on. A row an edit from inside the list
 moved to another group stays under its old heading, and the heading shows
 the row as it stood, until the rows are placed again. The hub stamps each top-level
 element of a group with `lb-group-live`, `lb-group-column` and

package/skills/loadbare-app/references/dev-server.md

@@ -105,6 +105,7 @@ own from them.
 |--------------|------------------------|--------------------------------------------------------------|
 | `watchApp`   | `@loadbare/app/build`  | Builds, rebuilds on a change, and reports each build         |
 | `buildApp`   | `@loadbare/app/build`  | Builds once                                                  |
+| `watchTree`  | `@loadbare/app/build`  | Reports each changed file under a directory                  |
 | `appServer`  | `@loadbare/app/dev`    | The application's server as a child process, restarted on demand |
 | `gate`       | `@loadbare/app/dev`    | Holds requests while any reason to hold them stands          |
 | `devProxy`   | `@loadbare/app/dev`    | The browser's port, passing requests through a gate          |
@@ -123,6 +124,13 @@ fails. A build writes nothing until every output is ready, so a failed one
 leaves the last good build in place. `loadbare-app-build` is a thin command
 over these two.
 
+`watchTree(root, onFile)` calls `onFile(file)` for each file under `root`
+that is changed, added or removed, with its path relative to `root`. It
+watches each directory, including those made later, so a file saved by
+replacing it, as `sed -i` and many editors save, is reported on every save.
+Node's `fs.watch` with `recursive: true` loses such a file on Linux after
+its first save. It returns `{ close() }`. `watchApp` watches `src` with it.
+
 `appServer({ entry, port, portEnv, node, log })` returns `{ restart(),
 stop(), state }`. `restart()` stops the server if it runs, starts it, and
 resolves once it accepts connections, or has exited instead. `state` is
@@ -143,8 +151,7 @@ a plain message when the port is in use.
 A dev server that also restarts on a change to `config/`:
 
 ```ts
-import { watch } from "node:fs";
-import { watchApp } from "@loadbare/app/build";
+import { watchApp, watchTree } from "@loadbare/app/build";
 import { appServer, devProxy, gate } from "@loadbare/app/dev";
 
 const held = gate();
@@ -163,7 +170,7 @@ const watcher = watchApp({
     held.open("build");
   },
 });
-watch("config", { recursive: true }, () => void restart());
+watchTree("config", () => void restart());
 
 await watcher.ready;
 await restart();

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

@@ -60,8 +60,9 @@ group.
 set a flag back to false, or clear a choice, and nothing on the wire
 cannot say either.
 
-**Why it terminates.**  It applies only to gathering from these two
-controls.  Landing still follows HTML's own idea of checked.
+**Why it terminates.**  It applies only to these two controls.  A
+checkbox lands `"false"` and `""` as unchecked, so it lands what it
+gathered.
 
 ## Rows hidden by a filter