@loadbare/app 0.24.0 → 0.26.0

package/docs/temp-proposals.md

@@ -1,251 +0,0 @@
-# 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.