@loadbare/app 0.17.0 → 0.18.1

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
@@ -1854,12 +1848,12 @@ the refreshed ones.  That is how a delta reaches the browser: wrap it in
 `patch()`, naming the rows that arrived or changed and the keys that went.
 
 A refreshed `rows` query sends every row to say what changed.  An update or
-a delete names its row by key, so its handler always knows what changed and
-answers with a patch, which the hub places by the query's [order](#order):
-`createHub` refuses at startup a `crud` `rowUpdate` or `rowDelete` on a
+a delete names its row by key, and an insert has the new row's key once it
+has written it, so each handler knows what changed and answers with a
+patch, which the hub places by the query's [order](#order): `createHub`
+refuses at startup a `crud` `rowInsert`, `rowUpdate` or `rowDelete` on a
 `rows` query whose `refresh` names that same query.  A `row` query sends one
-row and may refresh itself.  An insert may refresh its own query, since its
-key exists only once the row does.
+row and may refresh itself.
 
 `run` may instead return `url()`, a new row for `lb-url`, naming query parms
 only the write can know, such as the key of a row it inserted.  The page

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

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

@@ -337,10 +337,11 @@ A change that seems to need a refresh usually has a patch:
   delete and drop them too.
 
 An update or a delete always has a patch, since it names its row by key and
-removing a row never reorders the rest. `createHub` refuses at startup a
-`crud` `rowUpdate` or `rowDelete` on a `rows` query whose `refresh` names
-that same query. An insert may refresh its own query: where a new row goes
-depends on whether its host places it, which the server cannot see.
+removing a row never reorders the rest. So does an insert, which has the new
+row's key once it has written it, and the hub places the new row by the
+query's order. `createHub` refuses at startup a `crud` `rowInsert`,
+`rowUpdate` or `rowDelete` on a `rows` query whose `refresh` names that same
+query.
 
 Each request's `refresh` is its own, and every query in it needs its own
 reason. A list shared by several requests is a warning sign.

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

@@ -78,6 +78,7 @@ writes the row template inside the widget:
 | Parameter   | Fills                      |
 |-------------|----------------------------|
 | `exp-label` | The visible `<label>` text |
+| `exp-size`  | The `<select>`'s `size`, an open list rather than a drop-down |
 
 - Each option's `value` is its row's key, the `lb-key-value` the hub stamps
   on the live row, so the widget holds a key and shows a label.
@@ -90,6 +91,9 @@ writes the row template inside the widget:
     <optgroup><template><option lb-column="label"></option></template></optgroup>
   </template>
   ```
+- A heading option marked `data-group-label` in the `<optgroup>`, `hidden`
+  and `disabled`, labels the group with its text instead, so the label can
+  be a column of the group's first row.
 - Its `value` selects the option with that key, including an option that
   arrives after the value did.
 
@@ -167,6 +171,9 @@ row, the row template, and optionally a footer, each as a `<template>`:
   cursor back in it once an insert from it succeeds.
 - After rows land, the widget scrolls the row the page's own request created
   or moved into view.
+- Text selected in a cell whose `lb-column` the table's `lb-filter` names
+  becomes that column's filter in `lb-choices`: `=` for the whole text,
+  `^=` from its start, `$=` up to its end, `*=` otherwise.
 
 ## `lb-confirm`
 
@@ -207,6 +214,10 @@ with `commandfor` and `command="show-modal"`. Save is the form's
 `lb-options` around the button that opened it, and closes. The handler
 answers with a patch holding the new row.
 
+While open, the button that opened it carries `insert-dialog-opener` and the
+widget carries `anchored`, for a stylesheet to place the dialog beside the
+button with CSS anchor positioning.
+
 | Parameter   | Fills                                             |
 |-------------|---------------------------------------------------|
 | `exp-id`    | The dialog's `id`                                 |