@loadbare/app 0.10.0 → 0.11.0

package/skills/loadbare-app/references/TECHREF-1.0.md

@@ -109,6 +109,13 @@ But the allowed values may depend on other values in the row.
 - **Land the remaining validations.** One `lb-hub` and one empty `<main>`.
   Recommend landing these now, because refusing markup that used to build is
   the kind of change 1.0 gives up.
+- **Decide whether the build validates HTML.** A page can be well formed and
+  still break HTML's rules for what an element may hold, such as a `<div>`
+  inside a `<p>`.  The parser rearranges it silently, the same way at build
+  time and in the browser, so nothing reports it.  Checking those rules is a
+  validator's job, and html-validate is one the builder could run on the
+  source or on the expanded output.  Deciding it after 1.0 is free if it
+  lands as an opt-in, and it may need a configuration key.
 - **Confirm the three output names.** `app.html`, `client.js` and `app.css`
   are about to be fixed in `staticRoutes` as well as in the builder.
 
@@ -251,6 +258,12 @@ A custom element with no element file is left alone.  A custom element
 with neither an element file nor a `.browser.ts` script is a build error, as
 stated in [Custom elements](#custom-elements).
 
+Each file is parsed on its own, and expansion joins them through the DOM,
+which applies none of HTML's rules for what an element may hold.  The browser
+reads the shipped text by those rules, so a join it would rearrange, such as
+a definition's `<dialog>` inside a page's `<p>`, is a build error naming the
+file, the custom element and the path to what would move.
+
 #### Build time parameters
 
 A build time parameter is supplied as an attribute on a custom element,
@@ -418,6 +431,7 @@ query.
 | -------------------- | -------------------------------- |
 | `lb-column-value`    | The value it set                 |
 | `lb-key-value`       | The row's key                    |
+| `lb-row-live`        | Nothing; it marks a live row     |
 | `lb-query-row-count` | The number of live rows it holds |
 
 The markup names a query and the columns it shows.  The kind and the key are
@@ -425,7 +439,8 @@ the server's, and the markup states neither.
 
 The row template is the first `<template>` among the descendants of an
 element with `lb-query`, outside any nested `lb-query`.  A live row is an
-element the hub cloned from a row template for one row.
+element the hub cloned from a row template for one row, and carries
+`lb-row-live`.
 
 | Kind   | Row template | The hub                             |
 | ------ | ------------ | ----------------------------------- |
@@ -498,6 +513,13 @@ refresh, and does not need to.
 
 The hub matches each row to a live row by its key.  It stamps
 `lb-key-value` on each live row, and on an element a `row` lands on itself.
+It stamps `lb-row-live` on each live row and nowhere else, so a `row`
+landed inside another query, such as a total in a table's foot, is not one
+of that query's rows.  A stylesheet or a custom element selects live rows
+with `[lb-row-live]`, and never with `[lb-key-value]`.
+
+A key is unique within a query.  Two rows with one key in the same answer,
+or two live rows showing one key, are reported on the console.
 
 All rows decide membership and order: every row is placed in the order
 given, and a live row whose key did not arrive is removed.  A patch touches
@@ -1390,9 +1412,33 @@ class NoteField extends HTMLElement {
 }
 ```
 
+A control that is not yet upgraded when its column lands receives
+`lb-column-value` alone, since the hub sets `value` only on a control.  That
+happens to an element the builder shipped absent, and to one whose
+definition loads after the hub lands.  A control takes the stamp up the
+first time it connects, and never again.
+
 A custom element that is not a control receives `lb-column-value` and
 renders it; its content is never replaced.
 
+### Lifecycle
+
+| The hub                                  | A custom element sees                        |
+| ---------------------------------------- | -------------------------------------------- |
+| Shows a page                             | `constructor`, `connectedCallback`           |
+| Creates a live row, before placing it    | `constructor`                                |
+| Places a live row the first time         | `connectedCallback`                          |
+| Places it again, on every set of all rows | `disconnectedCallback`, `connectedCallback` |
+| Removes a live row                       | `disconnectedCallback`                       |
+| Turns `lb-show` off                      | `disconnectedCallback`, `adoptedCallback`    |
+| Turns `lb-show` on                       | `adoptedCallback`, `connectedCallback`       |
+| Turns on an element shipped absent       | `constructor`, `connectedCallback`           |
+
+A listener on the element itself goes in the constructor, which reads no
+attribute and no child.  A child is looked up when it is needed.
+`connectedCallback` runs on every move and is written to run again; work
+done once per instance goes behind a flag.
+
 ### Row hooks
 
 | Method                          | Implemented By | The hub calls it                                   |
@@ -1505,6 +1551,7 @@ it may define tomorrow.
 | `lb-exp-template` | Developer     | An element file, and a `<template>` | [Slots and templates](#slots-and-templates)   |
 | `lb-column-value` | Hub           | Every element set from a column     | [How a column lands](#how-a-column-lands)     |
 | `lb-key-value`    | Hub           | A live row, and an element a `row` lands on | [Rows](#rows)                         |
+| `lb-row-live`     | Hub           | A live row                          | [Rows](#rows)                                 |
 | `lb-query-row-count` | Hub        | An element with a row template      | [Rows](#rows)                                 |
 | `lb-request-pending` | Hub        | The element that issued a request   | [Request state](#request-state)               |
 | `lb-request-error`   | Hub        | The element that issued a request   | [Request state](#request-state)               |
@@ -1566,6 +1613,8 @@ imports them rather than writing a string.
 | `ATTR_SHOW`               | `lb-show`                               |
 | `ATTR_COLUMN_VALUE`       | `lb-column-value`                       |
 | `ATTR_KEY_VALUE`          | `lb-key-value`                          |
+| `ATTR_ROW_LIVE`           | `lb-row-live`                           |
+| `LIVE_ROW`                | `[lb-row-live]`, the selector for a live row |
 | `ATTR_QUERY_ROW_COUNT`    | `lb-query-row-count`                    |
 | `ATTR_REQUEST`            | `lb-request`                            |
 | `ATTR_REQUEST_PENDING`    | `lb-request-pending`                    |

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

@@ -190,6 +190,36 @@ path that closes it.
 Expansion runs over `<template>` contents wherever they occur, so a
 definition's row template ships already expanded, `{{placeholder}}` included.
 
+### Where a custom element can go
+
+HTML limits what an element may hold. A `<p>` holds only phrasing content,
+such as text, `<span>` and `<button>`, and a `<button>` may not hold another
+`<button>`. The parser does not refuse markup that breaks these rules; it
+rearranges it. `<p>Total <div>12</div></p>` becomes a paragraph, then a div,
+then an empty paragraph, with nothing logged.
+
+Each file is parsed on its own, so a page file and an element file each get
+the tree the browser would give them. Expansion then places one inside the
+other, and that join is where a rule can break. A definition containing a
+`<div>` or a `<dialog>` cannot go inside a `<p>`, since the browser would
+close the paragraph early and move the rest of the definition out of its
+element. The build refuses such a page, naming the file, the custom element
+and the path to what would move:
+
+```
+assemble: 'src/pages/ledger.page.html': expand: <lb-confirm> puts <dialog>
+where the browser's parser would not keep it, at p > lb-confirm > dialog.
+```
+
+Put a custom element whose definition holds block content, such as a
+`<div>`, a `<dialog>` or a `<p>`, in a `<div>`, a `<li>`, a `<td>` or another
+element that holds flow content.
+
+Never write a custom element inside a `<select>`, an `<option>` or a
+`<textarea>`. The parser drops the tag inside the first two, and inside a
+`<textarea>` it is text. Both happen when the page file is read, before
+expansion, so the build cannot see the element to report it.
+
 ### What fails at build time
 
 Each of these is reported with the tag and file name, and nothing is
@@ -204,6 +234,8 @@ shipped:
 - a `<template lb-exp-template="name">` naming a destination the definition
   does not have
 - two templates for the same destination
+- a custom element placed where the browser's parser would move its
+  contents; see [Where a custom element can go](#where-a-custom-element-can-go)
 
 An unfilled `{{placeholder}}` is not among these. That is presence
 propagation working as intended, indistinguishable from an author who left
@@ -228,6 +260,8 @@ one as a string literal:
 | `ATTR_REQUEST`         | `lb-request`         |
 | `ATTR_COLUMN_VALUE`    | `lb-column-value`    |
 | `ATTR_KEY_VALUE`       | `lb-key-value`       |
+| `ATTR_ROW_LIVE`        | `lb-row-live`        |
+| `LIVE_ROW`             | `[lb-row-live]`      |
 | `ATTR_QUERY_ROW_COUNT` | `lb-query-row-count` |
 | `ATTR_REQUEST_PENDING` | `lb-request-pending` |
 | `ATTR_REQUEST_ERROR`   | `lb-request-error`   |
@@ -244,6 +278,46 @@ writes them in markup, and the hub and the builder write their stamps.
 Loadbare reserves method names beginning with `lb` on a custom element, for
 the methods it calls; see [Holding rows](#holding-rows).
 
+### When its code runs
+
+The hub creates, places and parks elements, and each of those reaches a
+custom element as the browser's lifecycle callbacks. It is the same instance
+from its constructor on, however often it moves:
+
+| What the hub does                                  | Callbacks, in order                         |
+|----------------------------------------------------|---------------------------------------------|
+| Shows a page                                       | `constructor`, `connectedCallback`          |
+| Creates a live row, filled before it is placed     | `constructor`                               |
+| Places a live row for the first time               | `connectedCallback`                         |
+| Places it again, as it does on every set of all rows | `disconnectedCallback`, `connectedCallback` |
+| Removes a live row                                 | `disconnectedCallback`                      |
+| Turns `lb-show` off                                | `disconnectedCallback`, `adoptedCallback`   |
+| Turns `lb-show` on                                 | `adoptedCallback`, `connectedCallback`      |
+| Turns on an element the builder shipped absent     | `constructor`, `connectedCallback`          |
+
+The builder ships every `lb-show` element inside its template, and nothing
+in a template is upgraded, so such an element has no instance until its
+column first turns on. See
+[Conditional rendering](./data-binding.md#conditional-rendering).
+
+So each kind of work has one place:
+
+1. **A listener on the element itself goes in the constructor.** It is
+   attached once and survives every move, and a live row gets its own
+   because each row is a new instance. An event from a child bubbles to the
+   element, so the listener needs no child to exist yet. The constructor
+   reads no attribute and no child: an element made with
+   `document.createElement` has neither when it runs.
+2. **A child is looked up when it is needed**, in a handler, a getter,
+   `lbPlaceRow` or `lbRowsLanded`, and never held from setup.
+3. **`connectedCallback` runs on every move**, so it is written to run
+   again. It rearranges the element's own children into a state it checks
+   for first, or adds a listener to `document` or `window`, which
+   `disconnectedCallback` removes. Work done once per instance that needs
+   the element's attributes, such as a control taking up a value that landed
+   before it upgraded, goes behind a flag there; see
+   [Being a control](#being-a-control).
+
 ### Being a control
 
 A form-associated custom element with a `value` property that fires `change`
@@ -253,10 +327,20 @@ and commits its `lb-request` on `change`:
 
 ```ts
 // src/star-rating.browser.ts
+import { ATTR_COLUMN_VALUE } from "@loadbare/app/constants";
+
 class StarRating extends HTMLElement {
   static formAssociated = true;
   #internals = this.attachInternals();
   #value = "";
+  #connected = false;
+
+  connectedCallback() {
+    if (this.#connected) return;
+    this.#connected = true;
+    const stamped = this.getAttribute(ATTR_COLUMN_VALUE);
+    if (stamped !== null) this.value = stamped;
+  }
 
   get value(): string {
     return this.#value;
@@ -292,6 +376,14 @@ 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.
 
+A control can receive its value before it is a control. An element the
+builder shipped absent, or one whose definition loads after the hub has
+landed, is not upgraded when its column lands, so the hub cannot set its
+`value` and the value arrives as `lb-column-value` alone. Take the stamp up
+the first time the control connects, as `connectedCallback` does above, and
+never again: after that the hub sets `value` itself, and a later move must
+not undo an edit.
+
 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
@@ -330,14 +422,9 @@ List `ATTR_COLUMN_VALUE` in `observedAttributes`. The browser calls
 upgrades, as well as for one that changes afterward, so the first render and
 every later one go through the one callback.
 
-A custom element carrying `lb-show`, or inside an element that does, is
-moved into a template while its column is off and back out when it turns on
-— see [Conditional rendering](./data-binding.md#conditional-rendering).
-Going in, it sees `disconnectedCallback` and then `adoptedCallback`; coming
-out, `adoptedCallback` and then `connectedCallback`. It is the same instance
-throughout, and it still receives its column while it is away, so write
-`connectedCallback` to run more than once, as a live row the hub reorders
-already requires.
+A custom element carrying `lb-show`, or inside an element that does, still
+receives its column while it is away, so it returns current; see
+[When its code runs](#when-its-code-runs).
 
 ### Sending a request
 
@@ -401,7 +488,7 @@ Everything else is the hub's:
 | Cloning     | Clones the row template once per new key                 |
 | Matching    | Fills the live row already showing that key              |
 | Removing    | Removes the live rows the response says are gone         |
-| Stamping    | Stamps each live row with `lb-key-value`                 |
+| Stamping    | Stamps each live row with `lb-row-live` and `lb-key-value` |
 | Counting    | Stamps `lb-query-row-count` with the number of live rows |
 
 `lbPlaceRow` receives the live row already filled and not yet in the
@@ -411,6 +498,11 @@ template, in arrival order. `lb-options.browser.ts` and
 `lb-table.browser.ts` in [`@loadbare/widgets`](./widgets.md) are two
 different placements over the same landing.
 
+A custom element that walks its own rows finds them with `LIVE_ROW` from
+`@loadbare/app/constants`, never by `lb-key-value`: an element a `row` lands
+on carries a key too, and may sit among the rows, as a total in a table's
+foot does.
+
 Style an empty query against `lb-query-row-count` rather than carrying an
 empty state in the custom element — see
 [Counting rows](./data-binding.md#counting-rows).

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

@@ -58,6 +58,7 @@ builder writes a stamp, and a stylesheet or a custom element reads it.
 |----------------------|----------------------------------------------------|
 | `lb-column-value`    | The value the hub set from a column                |
 | `lb-key-value`       | The key of a live row, or of a `row` landed on an element |
+| `lb-row-live`        | The element is a live row                          |
 | `lb-query-row-count` | The number of live rows an element holds           |
 | `lb-request-pending` | The element's request is in flight                 |
 | `lb-request-error`   | The element's last request failed                  |
@@ -86,8 +87,11 @@ any nested `lb-query`:
 | `rows` | no           | Lands nothing                          |
 
 A live row is an element the hub cloned from a row template for one row.
-The hub stamps it with `lb-key-value`, the row's key. An element a `row`
-lands on itself carries `lb-key-value` as well.
+The hub stamps it with `lb-row-live`, and with `lb-key-value`, the row's
+key. An element a `row` lands on itself carries `lb-key-value` as well, but
+not `lb-row-live`, so a `row` shown inside another query, such as a total in
+a table's foot, is not one of that query's rows. Select live rows with
+`[lb-row-live]`, never with `[lb-key-value]`.
 
 Write `lb-column` on each element that shows a column. The element reads
 from its nearest ancestor row: the live row it is in, or the element a
@@ -153,6 +157,9 @@ membership and order: a live row whose key did not arrive is removed. A
 patch changes only the rows it names, and every other live row keeps its
 content and its place.
 
+A key is unique within a query. Two rows with one key in the same answer,
+or two live rows showing one key, are reported on the console.
+
 A live row's root counts as a column when it carries `lb-column`, which is
 how an `<option>`, whose content is text, shows the column it is.
 

package/skills/loadbare-app/references/page-files.md

@@ -16,6 +16,35 @@ every other path names the page whose stub it is.
 Put the files anywhere under `src/`. The builder pairs them by stub, not by
 directory; `src/pages/` is the convention.
 
+## What the page files are
+
+A page's queries are that page's view model, answered on the server. Each
+is shaped for the elements that name it, on one page, so it answers in the
+form the page shows: a date formatted, an amount with its separators, and
+the phrase a reader sees, such as "no postings yet" or "12 postings",
+rather than a count for the browser to word. The hub does no conversion,
+so there is no later place for that work to go. The markup says where each
+value goes, and the query says what it is.
+
+A value the page reads back, rather than only shows, stays data:
+
+| Value                              | Read back by                    | So it is                          |
+|------------------------------------|---------------------------------|-----------------------------------|
+| A column that lands on a control   | The request that gathers it     | What the handler expects to receive |
+| The key column                     | Every request from the row      | What the handler looks the row up by |
+| A column `lb-show` names           | The hub                         | `null` or `false` for off         |
+| A column a stylesheet selects on   | `[lb-column-value="…"]`         | A fixed token, not wording        |
+
+The page files are not a data layer; they sit on one. The application
+opens its own database and keeps its rules there, or in code its handlers
+share, and the page files stay thin because integrity is not their job.
+
+What two pages share goes beneath them, not between. Two pages showing the
+same data each write the query, or both read a database view. Shared
+wording and shared parm reading go in a helper module the queries import.
+Everything that belongs to one page stays in one place, so a change to a
+page touches that page's files.
+
 ## HTML
 
 Write the page as a fragment. The fragment lands in `<main>`, which