@loadbare/app 0.18.0 → 0.18.1

package/docs/roadmap.md

@@ -1,7 +1,7 @@
 # Roadmap
 
-Release 1.0 is optimized to prove that a Loadbare app can be robust and
-highly performant with a codebase that has very low accidental complexity.
+Release 1.0 is optimized to prove that a Loadbare app holds a median 300ms
+round trip from click to paint.  See [Theory](./theory.md).
 
 What follows is everything not yet decided or not yet built: release
 candidates, risks not worth solving speculatively, and open design
@@ -30,13 +30,6 @@ read from a query parm. Whether a response may say the server already
 sorted it is open: the server may not sort as the browser does, and for a
 thousand rows the hub's sort is a small cost.
 
-### Nesting
-
-Whether a live row may hold rows of its own detail (master-detail, an
-expanding row). [Theory](./theory.md) already flags this as possibly load-bearing if
-disallowed. Worth a decision-in-principle the first time a master-detail
-page is built, even before the mechanism is needed elsewhere.
-
 ### Events while a request is in flight
 
 The hub ignores a commit on an element carrying `lb-request-pending`.
@@ -90,6 +83,9 @@ If the hub were configured with a URL for the data channel, the entire app
 could be delivered from a static origin, such as an S3 bucket or static web
 server.
 
+`<lb-hub>` reads no attributes, so the data channel's URL, and a timeout an
+application outgrows, can arrive as attributes on it.
+
 ### Tree-shaking CSS by tag name
 
 Release 1.0 concatenates every `.css` file under `src`, and every one inside
@@ -110,6 +106,18 @@ Most valuable against a large imported widget library, where an app uses a
 small fraction of what ships. Revisit when a real app's `app.css` is big
 enough to measure.
 
+### HTML validation in the build
+
+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.  The builder could
+run html-validate on the source or the expanded output, as an opt-in.
+
+### A whole row for a custom element
+
+A column lands one element at a time.  An optional `lbAcceptRow` beside
+`lbRowsLanded` would hand a custom element its whole row.
+
 ### Options on `createHub`
 
 Global hooks, transaction wrapping, error handling and a CSRF token each

package/package.json

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

package/skills/loadbare-app/SKILL.md

@@ -244,8 +244,11 @@ 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"`.
-Radio buttons and file inputs are not controls here: they receive no value
-and are not gathered.
+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.
+File inputs are not controls here: they receive no value and are not
+gathered.
 
 **A form that adds to a set chosen elsewhere is written once, outside every
 row.**  A form cannot sit inside another form or in a table row, so a dialog

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

@@ -15,39 +15,14 @@ they must be resolved before we declare 1.0.
 
 ### Data types
 
-Loadbare/app enforces no data types on values between the database and the
-browser.  A uniform and useful approach is difficult to discern, and we do
-not want to pollute 1.0 with a potentially sub-optimal solution.  Until then
-a value is rendered by browser coercion when it lands on an HTML text
-element or a control, and by whatever the custom element does with
-`lb-column-value` when it lands on one that is not a control.
+A value renders by browser coercion when it lands on an HTML text element or
+a control, and by whatever the custom element does with `lb-column-value`
+when it lands on one that is not a control.  A `rows` query may declare a
+column's type, which the [order](#order), a [filter](#filters), `lb-min` and
+`lb-max` read.
 
-Three places read a value's type today.  The [order](#order) compares
-values by their JSON type, a [filter](#filters) reads its value as the
-column's type, and an [aggregate](#aggregates) reads a sum or an average
-from a JSON number or a string holding a plain decimal.  A `rows` query may
-declare a column's type, which the order, a filter, `lb-min` and `lb-max`
-read the column as in place of its JSON type.  No declared type changes how
-a value renders.
-
-We will then see if a useful solution emerges that Loadbare/app should
-handle.
-
-### Form controls
-
-- **Radio buttons are not implemented.** A value does not land on one and
-  the hub does not gather one.  A radio group is several elements answering
-  to one column.
-
-### Custom element hooks
-
-Loadbare/app owns every method name beginning with `lb` on a custom element.
-That decision is firm; what the set contains is not.
-
-- **Decide whether a custom element may receive a whole row.** A column
-  lands one element at a time and offers no escape hatch.  An optional
-  `lbAcceptRow` would sit beside `lbRowsLanded`, and this is the most likely
-  first request from a custom element author.
+- **Decide who formats a value.**  The hub could own formatting, or take it
+  from the application as configuration or as code.
 
 ### Nested queries
 
@@ -83,18 +58,8 @@ But the allowed values may depend on other values in the row.
   repository with several applications gets one per application.  `--src`
   stays a flag, since it is what locates the file.  State the precedence
   between a flag and a key once.  Its key names join the permanent surface,
-  so this lands before 1.0 or not at all.
-- **Decide CSS pairing.** Naming a stylesheet `<tag>.css` beside its
-  definition would let the builder ship only what survives expansion.
-  Recommend deferring the mechanism and reserving the configuration key, so
-  that it lands as an opt-in rather than as a silent drop.
-- **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.
+  so this lands before 1.0 or not at all.  It reserves a key for the
+  roadmap's tree-shaking CSS by tag name.
 - **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.
 
@@ -103,16 +68,15 @@ But the allowed values may depend on other values in the row.
 None of this is surface.  It is listed here because trimming it is free
 today and breaking after 1.0.
 
-- **Audit what the hub does.** It appears to have routines that go beyond
-  what the `lb-*` attribute namespace specifies.
+- **Audit what the hub does.** Every routine it runs answers to an `lb-*`
+  attribute, a [reserved query](#reserved-queries), or a
+  [reserved event](#reserved-events) or [method](#reserved-methods).  Trim
+  whatever does not, and leave what stays clean: no dead code, no routine
+  written twice, no comment the code contradicts.
 - **Keep the rest as constants.** The endpoint, `index` and the timeout are
   linkage between the builder and the hub rather than facts an application
   varies.  Adding a knob for any of them buys a second shape of application
   to reason about.
-- **Give the hub a configuration channel without using it.** `<lb-hub>` reads
-  no attributes at all, which is the free landing spot for the roadmap's
-  static-origin split and for a timeout an application eventually outgrows.
-  Reserve the idea, build nothing.
 
 ## The build
 
@@ -220,7 +184,8 @@ it is sent to the browser on initial page load, no HTML is ever sent
 again.
 
 The developer writes `lb-*` attributes in markup.  Script never assigns
-them.  The hub and the builder write only their stamps.  See
+them.  The hub and the builder write only their stamps, and the hub writes
+the `name` of a radio button in a row template.  See
 [The markup checks](#the-markup-checks).
 
 ### Expansion
@@ -457,8 +422,8 @@ unless its name begins with `lb-`.
 | Any other element                                | Its text content               |
 
 A control is an `<input>`, `<select>` or `<textarea>`, or a form-associated
-custom element with a `value` property that fires `change`.  A checkbox is a
-control too, by the rule below.  A
+custom element with a `value` property that fires `change`.  A checkbox and
+a radio button are controls too, by the rules below.  A
 form-associated custom element declares `static formAssociated = true`.
 
 The hub stamps `lb-column-value` with the value on every element it sets.
@@ -481,9 +446,18 @@ attribute means nothing to the hub.
 <input type="checkbox" lb-column="active" lb-request="lb-row-update" />
 ```
 
-An `<input>` of type `radio` or `file` receives nothing, not even
-`lb-column-value`, and the hub reports it to the console.  The hub does not
-gather one either.
+A radio button's state is `checked` as well.  The hub checks it when its
+`value` attribute equals the value as a string, and unchecks it otherwise,
+`null` included.  Of the radio buttons naming one column, the hub gathers
+the `value` of the one checked, or `""` when none is.
+
+```html
+<input type="radio" lb-column="shift" value="day" lb-request="lb-row-update" />
+<input type="radio" lb-column="shift" value="night" lb-request="lb-row-update" />
+```
+
+An `<input>` of type `file` receives nothing, not even `lb-column-value`,
+and the hub reports it to the console.  The hub does not gather one either.
 
 A `<select>` with no option for the value shows no selection.
 
@@ -1583,6 +1557,26 @@ whose name begins with `lb` and a capital and is not in
 Script never assigns an `lb-` attribute, so the markup states every one
 that exists, and checking the markup is sound.
 
+### Uncommon layouts
+
+The hub supports these layouts and adds no check to refuse them.  They are
+uncommon, and Loadbare/app does not shape itself around them.
+
+- **A radio button in a row template.**  The browser groups radio buttons
+  by `name`, and a row template repeats one `name` in every live row.  The
+  hub stamps each radio button's `name` with the `name` written, or its
+  column when none is, followed by `-` and the live row's key, so each live
+  row holds a group of its own.
+- **Several rows not yet entered, each holding radio buttons.**  A
+  [row not yet entered](#a-row-not-yet-entered) has an empty key, so the
+  radio buttons of every such row share one `name` and form one group.
+- **Radio buttons populated from a query.**  A radio button in a query's row
+  template answers to that query's row, as any element there does, so which
+  row and column it lands from and gathers to follows from where the layout
+  puts it.  The result is the same as in any framework that populates radio
+  buttons from a query.  A choice among a query's rows is better made with a
+  form-associated control, such as `lb-options` in `@loadbare/widgets`.
+
 ## Application files
 
 ### Chrome

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

@@ -124,6 +124,7 @@ no row fills.
 |------------------------------------------------------|-----------------------------------------|
 | `<input>`, `<select>`, `<textarea>`                  | Its `value`, and `lb-column-value`      |
 | `<input type="checkbox">`                            | Its `checked`, and `lb-column-value`    |
+| `<input type="radio">`                               | Its `checked`, and `lb-column-value`    |
 | A form-associated custom element with `value`        | Its `value`, and `lb-column-value`      |
 | Any other custom element                             | `lb-column-value` only                  |
 | Any other element                                    | Its text content, and `lb-column-value` |
@@ -135,8 +136,7 @@ element that is not a control keeps the content the builder placed in it
 from its element file, and renders `lb-column-value` itself; see
 [Custom Elements](./custom-elements.md#receiving-a-value).
 
-A radio button and a file input receive nothing, and the hub reports it to
-the console.
+A file input receives nothing, and the hub reports it to the console.
 
 The hub hands every value to the browser as the server sent it. What a
 number, a date or a null looks like is decided in the query.
@@ -155,6 +155,27 @@ 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.
 
+### Radio buttons
+
+A radio button is a control.  It is checked when its `value` is the
+column's value as a string, and unchecked otherwise.  Of the radio buttons
+naming one column, the hub gathers the `value` of the one checked, or `""`
+when none is:
+
+```html
+<input type="radio" lb-column="shift" value="day" lb-request="lb-row-update" />
+<input type="radio" lb-column="shift" value="night" lb-request="lb-row-update" />
+```
+
+In a row template, the hub stamps each radio button's `name` with the
+`name` written, or its column when none is, followed by `-` and the live
+row's key, so each live row holds a group of its own.  Rows not yet entered
+share the empty key, and so share one group.
+
+A radio button in a query's row template answers to that query's row, as
+any element there does.  A choice among a query's rows is better made with
+a form-associated control, such as `lb-options` in `@loadbare/widgets`.
+
 ### Rows
 
 Write a `<template>` inside the element carrying `lb-query`, holding one