@loadbare/app 0.13.0 → 0.15.0

package/docs/comparison.md

@@ -319,10 +319,11 @@ without `.browser` is not bundled, and the build error names it.
 - A widget may send a request by dispatching a bubbling `lb-request`
   `CustomEvent`.  The hub completes it with `query`, `key` and `values` from
   where the element sits.  An ancestor may stop the event.
-- A custom element carrying `lb-query` and a row template may implement
-  `lbRowsLanded()` to act on the rows once they land, such as scrolling to
-  the one a request created.  The hub does the cloning, matching, ordering,
-  grouping, removal and counting.
+- A custom element hears the hub's lifecycle rather than the browser's:
+  `lbAttached()` and `lbDetached()` once each, when the hub places and
+  removes it, `lbRowsLanded()` once rows land on it, and `lbRequestDone()`
+  when a request from inside it finishes.  The hub does the cloning,
+  matching, ordering, grouping, removal and counting.
 - Method names beginning with `lb` on a custom element are reserved.
 
 Widget libraries are npm packages listed in `imports.ts`.  The builder scans
@@ -467,11 +468,13 @@ The hub stamps the element that committed:
 |----------------------|------------------------------------------------------------|
 | `lb-request-pending` | The round trip is in flight; `aria-busy="true"` is set with it |
 | `lb-request-error`   | The last round trip from this element failed               |
+| `lb-request-refused` | The handler refused it, carrying its message               |
 
 A commit on an element carrying `lb-request-pending` is ignored.  A round
 trip has a ten-second deadline, after which it is aborted and treated as a
 failure.  `lb-request-error` records that a round trip failed, and carries
-no message.
+no message.  A handler's `refusal()` carries words for the user, shown on the
+element and on each control it names.
 
 After a successful `lb-row-insert` gathered from a form, the hub resets the
 form.  A failed insert resets nothing.
@@ -789,7 +792,7 @@ TECHREF-1.0 lists every name Loadbare/app owns in one cross-reference.
 | `lb-*` stamps                       | 17    | `lb-column-value`, `lb-key-value`, `lb-row-live`, `lb-query-row-count`, `lb-group-live`, `lb-group-column`, `lb-group-value`, `lb-row-created`, `lb-row-changed`, `lb-row-moved`, `lb-row-requested`, `lb-row-leaving`, `lb-group-leaving`, `lb-request-pending`, `lb-request-error`, `lb-page`, `lb-page-title` |
 | `lb-*` build-time attributes        | 2     | `lb-exp-slot`, `lb-exp-template`                              |
 | Requests Loadbare provides          | 3     | `lb-row-insert`, `lb-row-update`, `lb-row-delete`             |
-| `lb*` methods on custom elements    | 1     | `lbRowsLanded`                                                |
+| `lb*` methods on custom elements    | 4     | `lbAttached`, `lbRowsLanded`, `lbRequestDone`, `lbDetached`   |
 | Query parms Loadbare reads          | 1     | `lb-order-<query>`                                            |
 | Attribute namespace for expansion   | 1     | `exp-*`                                                       |
 | Reserved tags                       | 1     | `<lb-hub>`                                                    |
@@ -822,7 +825,7 @@ cross-reference, so no count is given for them here.
 - A widget's markup is in the document and in view-source.
 - On navigation the hub sets `document.title` from the page's `<title>`.  It
   does not move focus or announce the new page.
-- Checkboxes and radio buttons are not implemented for landing or gathering.
+- Radio buttons are not implemented for landing or gathering.
 
 ### Elsewhere
 
@@ -917,9 +920,9 @@ Roadmap.
 | Nested data                   | A row never holds rows.  Trees are sent as joined rows.                 |
 | Record URLs and view parameters | A path names a page.  A record or a filter is a query parm, `/accounts?acct=23`. |
 | Query arguments from the browser | None.  Query parms reach queries through `contextFor` and `ctx`.     |
-| Checkboxes, radio buttons, file inputs | Not landed and not gathered.  Open blocker.                    |
+| Radio buttons, file inputs    | Not landed and not gathered.  Radio buttons are an open blocker. Checkboxes land and gather as `true` and `false`. |
 | Data types and formatting     | No conversion.  Queries format values.  Open blocker.                  |
-| Error messages                | `lb-request-error` carries no message.                                 |
+| Error messages                | A handler's `refusal()` reaches the user; any other failure carries no message. |
 | Field validation              | No mechanism.  Per-keystroke validation is a roadmap question.         |
 | Optimistic updates            | None.                                                                  |
 | Concurrent writers            | No version or conflict check.  Roadmap question.                       |
@@ -1183,6 +1186,7 @@ Each equivalent is approximate.
 | `exp-` parameter              | A prop fixed at build time                                                       |
 | `lb-exp-slot`, `lb-exp-template` | Default slot and named slots; `ng-content` with `select`                         |
 | `lbRowsLanded`                | An effect after a list renders                                                   |
+| `lbAttached`, `lbDetached`    | Mount and unmount; `onMounted` and `onUnmounted` (Vue); `onMount` and `onDestroy` (Svelte) |
 | `order`, `lb-group`           | `ORDER BY` with report-writer control breaks (`BREAK ON`, group bands)          |
 | `ctx` / `HubContext`          | `event.locals` (SvelteKit); loader `context` (React Router 7); request-scoped dependency injection |
 | `imports.ts`                  | Installing and registering a component library                                   |

package/docs/possible-ideas.md

@@ -4,6 +4,57 @@
 > 2026-10-02 against `@loadbare/app` 0.12.0, from a session in ef.  Nothing
 > here is decided or planned.
 
+> **Status, 2026-10-04.**  The lifecycle in the hub's terms was adopted, on
+> custom elements rather than on behaviors: see
+> [When its code runs](./reference/custom-elements.md#when-its-code-runs).
+> Behavior by attribute, and expansion that replaces the tag, were set aside.
+> What follows is kept as the record of how the decision was reached.
+
+## Why these are being considered
+
+A custom element is the platform's one way to attach code to markup, and
+widget work keeps running into what that costs.
+
+- No decomposition.  Code that concerns one row has nowhere to live but a
+  wrapper around the whole table, so `lb-table` owns everything inside it.
+  That is how page-specific behavior ends up in a shared widget: the COA
+  page's ghost row per section grew because row-level code could attach
+  only to the table.  It is the overfit the README's test guards against.
+- The browser's lifecycle is not the hub's.  A moved row is disconnected and
+  connected, the copy a move leaves behind is constructed, and an `lb-show`
+  toggle adopts twice, so `connectedCallback` must be written to run again.
+- Clutter.  The page's source is the widget's dialect of named templates
+  rather than HTML, and the shipped page keeps a wrapper tag around what it
+  expanded.
+- Plumbing through the wrapper.  The tag carrying the code is not the
+  control: `WrappedControl` forwards `value`, fires `change` again, and needs
+  `ElementInternals` to join a form.  Focus is searched for inside the
+  wrapper, and `autofocus` on a wrapped `<input>` is lost.
+- Content models reach forms too.  A `<form>` cannot wrap a `<tr>`, so the
+  ghost row joins its controls to a hidden form outside the table by the
+  `form` attribute.  A form cannot hold a form, so `lb-insert-dialog` is
+  written once outside every row instead of beside the control it serves.
+- Ids repeat in a row template.  `lb-confirm` finds its dialog by position,
+  because `commandfor`, HTML's own way to open one with no script, works
+  only by id.
+- Upgrade timing is the hub's problem.  An element shipped inside an
+  `lb-show` template, or whose definition loads late, has not upgraded, so
+  the hub keeps `waiting()`, lands kept answers again once it upgrades, and
+  stamps `lb-column-value` for a control to take up on first connect.
+- A few lines cost a wrapper.  `lb-options` has a script mostly to copy
+  `lb-group-value` into an `<optgroup>`'s `label` and each key into an
+  option's `value`, and for that the whole `<select>` sits inside a custom
+  element.
+- Parameters cannot carry structure.  Expansion parameters are words, so
+  when groups became a template, `lb-picker` lost `exp-group` and a grouped
+  picker went back to a hand-written `lb-options`.
+- CSS and accessibility see an element HTML does not define.  A wrapper tag
+  has no role, shifts child and `:nth-child` selectors, and has no place in
+  a table.  The usual remedy, `display: contents`, has a history of
+  accessibility bugs.
+- One element, one class.  A ghost row that should also save as it is typed
+  in needs a widget combining the two.
+
 ## Code on elements the parser constrains
 
 Loadbare's data vocabulary is attributes, and an attribute goes on any
@@ -20,7 +71,8 @@ table.  Each new need is another named destination, and the page's source
 reads as `lb-table`'s shape rather than a table's.  The shipped HTML is
 honest; the source is a dialect.
 
-Two ways to put code on the element itself follow.
+Two ways to put code on the element itself follow, and only the second
+survives.
 
 ### Customized built-ins
 
@@ -28,25 +80,11 @@ Two ways to put code on the element itself follow.
 <tr is="lb-ghost-row">…</tr>
 ```
 
-The platform's own answer: a class extending `HTMLTableRowElement`,
-registered with `customElements.define(name, cls, { extends: "tr" })`.  The
-parser sees a `<tr>`, so the element sits wherever a `<tr>` may, keeps every
-native behavior of one, and gets the custom element lifecycle.
-
-- Chrome and Firefox ship it.  WebKit has declined to, on principle
-  (subclassing a built-in breaks when its internals change), so Safari needs
-  a polyfill for as long as the feature exists.
-- Every browser on iOS and iPadOS is WebKit, Chrome included.  The polyfill
-  is therefore not a Safari fallback but the code path on every iPhone and
-  iPad, permanently.  The usual one, `@ungap/custom-elements`, watches the
-  document with a `MutationObserver`, so on those devices the lifecycle runs
-  because something noticed.
-- `is` must be present when the element is created; setting it later does
-  nothing.  Cloning a template preserves it, so a row template carrying
-  `is` yields upgraded rows.
-- A customized built-in cannot be form-associated (`ElementInternals` is for
-  autonomous custom elements), which matters little: the built-in elements
-  that controls are already take part in forms.
+The platform's own answer: a class extending `HTMLTableRowElement`, which
+the parser treats as a `<tr>`.  WebKit has declined to ship it, and every
+browser on iOS and iPadOS is WebKit, so a polyfill, usually a
+`MutationObserver`, would be the code path on every iPhone and iPad for
+good.  That rules it out.
 
 ### Behavior by attribute
 
@@ -114,13 +152,12 @@ A rule for choosing: a custom element makes a new kind of element (its own
 markup, expansion, or a control built from scratch); a behavior adds code to
 an element HTML already has.
 
-### Where each would land
+### Where it would land
 
-Either one lets a page write a real `<table lb-query>` with code on the rows
-that need it, and leaves `lb-table` to supply only what is truly the
-table's.  Customized built-ins borrow the platform's lifecycle at the cost of
-a permanent polyfill; behavior by attribute keeps the parser and the browser
-matrix out of it, at the cost of a lifecycle the hub would define.
+Behavior by attribute lets a page write a real `<table lb-query>` with code
+on the rows that need it, and leaves `lb-table` to supply only what is truly
+the table's.  It keeps the parser and the browser matrix out of it, at the
+cost of a lifecycle the hub would define.
 
 ## Expansion that replaces the tag
 
@@ -186,3 +223,92 @@ source, the `lb-behavior` attribute and the comment already give.
    the page passes them as parameters (`exp-column`, written into the file as
    `lb-column="{{column}}"`), which works today but reads less naturally
    than `lb-column`.  This wants worked examples before a rule.
+
+## The case for behaviors
+
+Today's model is simple to state: a widget is a name, and a name is one or
+both of a `.html` and a `.browser.ts`.  One name is one element the
+developer writes, so what a widget does is easy to predict.  Most of what
+that costs is paid inside Loadbare, in service of the simple model.  The one
+place it leaks to the developer is the lifecycle, where a widget author must
+follow strict rules to get the behavior they expect.
+
+Behaviors would simplify the hub, but they seem to spread code that a
+custom element keeps in one file.  The containment comes from the element
+file, though, not from the tag.
+
+### What one file bundles today
+
+`lb-table`'s script does three jobs, joined by where they sit rather than by
+any data they share:
+
+| Job                        | Reads and writes                                   |
+| -------------------------- | -------------------------------------------------- |
+| Table scaffolding          | Caption, head and foot destinations; expansion only |
+| The ghost row              | The ghost row's controls, its form, and focus      |
+| Scrolling to the saved row | The list's rows and their stamps                   |
+
+It is one file, and three concerns in one class, none reusable without the
+others.  A `<ul>` cannot have a ghost row without becoming an `lb-table`.
+
+### Two units
+
+- A widget is markup.  Its element file decides what elements exist, at
+  build time, as now.
+- A behavior is what one element does.  Its code attaches to the element
+  that carries it, and runs on the hub's lifecycle.
+
+An element file may write `lb-behavior` on its own inner elements:
+
+```html
+<!-- lb-table.html -->
+<table lb-behavior="scroll-to-saved">
+  <thead lb-exp-template="head"></thead>
+  <tbody lb-exp-slot></tbody>
+  <tbody lb-exp-template="ghost" lb-behavior="ghost-row"></tbody>
+</table>
+```
+
+`lb-table` stays the one place to read, and its element file says which code
+runs on which element.  The code is split into files by job, and the widget
+assembles them.  A page that wants a ghost row in a `<ul>` writes
+`lb-behavior="ghost-row"` on it.
+
+### Where code goes
+
+Code goes on the element it reads and writes.
+
+- The ghost row's code touches the ghost row's controls and form, so it is a
+  behavior on the ghost row.
+- Scrolling touches the list's rows, so it is a behavior on the list.
+- Code that seems to need two elements is the sign to stop.  Behaviors never
+  call each other.  They speak only through what widgets use today:
+  attributes the hub stamps, and bubbling events such as `lb-request-done`.
+  The scrolling behavior knows nothing of the ghost row; it reads
+  `lb-row-requested`.
+
+The rule also refuses the overfit that started this: a ghost row per
+section would be a behavior on the table reaching into every section.
+
+### Where the leak moves
+
+Today the leak is the browser's lifecycle: `connectedCallback` written to
+run again, and a value stamp adopted on first connect.  With behaviors it
+becomes three rules Loadbare states:
+
+1. Only elements the hub places get behaviors.
+2. A behavior is attached and detached exactly once.
+3. Behaviors speak only through stamps and events.
+
+They are fewer, and in the hub's terms rather than the browser's.  The cost
+moves to Loadbare's design: the ordering the platform gives custom elements
+must be stated, such as whether a host's behavior attaches before or after
+its rows land, and the order among nested behaviors.
+
+### Both, not one
+
+Custom elements stay.  A control built from scratch still needs
+`ElementInternals`, and a tag with no code is expansion alone.  Behaviors
+cover what a tag does badly: code on an element HTML already has, inside
+content models that forbid a tag.  The developer's question becomes whether
+they are making a new kind of element, or giving an existing element a job.