@loadbare/app 0.18.1 → 0.18.2

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

@@ -42,3 +42,166 @@ See [`chrome.html`](./chrome.md) for the link, [The Express
 server](./server.md) for the route, and
 [`loadbare-app-build`](./builder.md#running-the-builder) for `--minify`.
 </content>
+
+## Selecting what the hub stamps
+
+The hub tells a stylesheet everything it knows through attributes, so an
+application styles state with selectors and writes no script for it.  Each
+stamp is an `lb-` attribute the hub writes; never write one in markup.
+
+### A value
+
+Every element a column lands on carries the value as `lb-column-value`,
+exactly as the query sent it, and loses it when the value is null.  Select
+on the column and the value:
+
+```css
+[lb-column="status"][lb-column-value="locked"] { opacity: 0.5; }
+[lb-column="balance"][lb-column-value^="-"] { color: var(--negative); }
+[lb-column="note"]:not([lb-column-value]) { display: none; }
+```
+
+A widget that formats its value, such as `lb-number`, keeps the raw value
+in the stamp, so the selector reads the number and not its text.  See
+[Where a column lands](./data-binding.md#where-a-column-lands).
+
+### A row
+
+| Select               | For                                             |
+|----------------------|-------------------------------------------------|
+| `[lb-row-live]`      | Every live row of a list                        |
+| `[lb-row-selected]`  | A row its `lb-select` checkbox ticks            |
+| `[lb-row-editing]`   | The row a pointed form is editing               |
+| `[lb-key-value="…"]` | One row, by its key                             |
+| `[hidden]`           | A row a filter hides; the browser hides it      |
+
+An element a `row` query lands on carries `lb-key-value` while the query has
+a row, and loses it when the query answers `null`:
+
+```css
+[lb-query="member"]:not([lb-key-value]) .member-missing { display: revert; }
+```
+
+Select live rows with `[lb-row-live]`, never with `[lb-key-value]`: a `row`
+landed inside a list, such as a total in a table's foot, carries a key and
+is not one of the list's rows.
+
+```css
+[lb-row-selected] { background: var(--selected); }
+[lb-row-editing] { outline: 2px solid var(--accent); }
+```
+
+See [Rows](./data-binding.md#rows), [Selecting rows](./data-binding.md#selecting-rows)
+and [Editing a row in one form](./data-binding.md#editing-a-row-in-one-form).
+
+### A group
+
+Each top-level element of a group carries `lb-group-live`, the column it
+breaks on as `lb-group-column`, and its value there as `lb-group-value`:
+
+```css
+[lb-group-column="category"][lb-group-value="Income"] { color: var(--income); }
+```
+
+See [Groups](./data-binding.md#groups).
+
+### What just happened to a row
+
+The hub stamps what its last landing did, so a stylesheet animates with
+nothing else:
+
+| Select                         | For                                            |
+|--------------------------------|------------------------------------------------|
+| `[lb-row-created]`             | A row that arrived                             |
+| `[lb-row-changed]`             | A row whose values changed                     |
+| `[lb-row-moved]`               | A row whose values changed and now stands elsewhere; it carries `lb-row-changed` too |
+| `[lb-row-requested]`           | Any of the three, done by this page's request, as `created`, `changed` or `moved` |
+| `[lb-row-leaving]`, `[lb-group-leaving]` | A row or group on its way out; the hub removes it when its animations end |
+
+```css
+[lb-row-created] { animation: arrive 200ms; }
+[lb-row-requested="changed"] { animation: flash 600ms; }
+[lb-row-leaving] { animation: depart 200ms forwards; }
+```
+
+A row stamped again plays its animation again.  See
+[What happened to a row](./data-binding.md#what-happened-to-a-row).
+
+### How many rows show
+
+An element carrying `lb-query` and a row template carries
+`lb-query-row-count`, the number of live rows showing.  A row a filter hides
+is not counted.
+
+```css
+.roster-empty { display: none; }
+[lb-query-row-count="0"] .roster-empty { display: revert; }
+```
+
+See [Counting rows](./data-binding.md#counting-rows).
+
+### A request
+
+| Select                 | For                                                     |
+|------------------------|---------------------------------------------------------|
+| `[lb-request-pending]` | The element that committed, while its round trip is out; `aria-busy="true"` rides with it |
+| `[lb-request-error]`   | The element whose round trip failed, until it commits again |
+| `[lb-request-refused]` | The element whose request the handler refused, holding the message, empty when there is none |
+| `:invalid`             | A control a refusal named a column for                  |
+
+The hub ignores a commit on a pending element, so the stylesheet only has to
+show it:
+
+```css
+[lb-request-pending] { cursor: progress; opacity: 0.6; }
+[lb-request-error] { outline: 2px solid var(--error); }
+[lb-request-refused]:not([lb-request-refused=""])::after {
+  content: attr(lb-request-refused);
+}
+```
+
+See [Request state](./data-binding.md#request-state) and
+[Refusals](./data-binding.md#refusals).
+
+### A form pointed at a row
+
+A pointed form's `lb-key-value` says what it is doing:
+
+| Select                       | The form is        |
+|------------------------------|--------------------|
+| `form[lb-key-value]:not([lb-key-value=""])` | Editing a row |
+| `form[lb-key-value=""]`      | Entering a new row |
+| `form:not([lb-key-value])`   | Not in use         |
+
+```css
+form[lb-key-value=""] .save-existing,
+form:not([lb-key-value=""]) .save-new { display: none; }
+```
+
+See [Editing a row in one form](./data-binding.md#editing-a-row-in-one-form).
+
+### The user's choices
+
+An order or a filter the user chose is a column of `lb-choices`, so the
+element showing it carries it as `lb-column-value`.  Style anything else by
+it with `:has()`:
+
+```css
+table:has([lb-column="accounts_order"][lb-column-value="-balance"])
+  th.balance::after { content: "▼"; }
+```
+
+See [Choices](./data-binding.md#choices).
+
+### Content shown by condition
+
+An element `lb-show` turns off is moved into a `<template>`, so no selector
+reaches it and nothing about it needs styling.  The `<template>` keeps its
+place, so `:nth-child()` counts it; prefer `:nth-child(… of …)` or a class
+over position.  See [Where an absent element is](./data-binding.md#where-an-absent-element-is).
+
+### The first load
+
+Write `hidden` on the chrome's `<body>`, and the hub removes it once the
+first page has landed.  See
+[Preventing the first-load blink](./chrome.md#preventing-the-first-load-blink).

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

@@ -95,6 +95,10 @@ 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]`.
 
+A `row` query answering `null` found no row. The hub lands every column the
+element names as null and removes its `lb-key-value`; under a row template,
+the live row leaves.
+
 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
 `row` landed on. A nested `lb-query` begins a new query, and what is inside
@@ -139,7 +143,10 @@ from its element file, and renders `lb-column-value` itself; see
 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.
+number, a date or a null looks like is decided in the query, or by a custom
+element that formats it, such as
+[`lb-number` and `lb-date`](./widgets.md#lb-number-and-lb-date). Send a
+column the user sorts or filters raw, and format it in the element.
 
 ### Checkboxes
 

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

@@ -96,7 +96,7 @@ export const queries: Queries = {
 
 | Declared with              | Answers with                              |
 |----------------------------|-------------------------------------------|
-| `row(key, run)`            | One row, an object                        |
+| `row(key, run)`            | One row, an object, or `null` for none    |
 | `rows(key, run, options)`  | All its rows, an array of objects         |
 
 `options` are a `rows` query's order and column types. `order` is the
@@ -317,6 +317,7 @@ queries:
 | Answer                   | States                                      |
 |--------------------------|---------------------------------------------|
 | `{ ... }`                | The row of a `row` query                    |
+| `null`                   | A `row` query found no row                  |
 | `[...]`                  | All rows of a `rows` query, and their order |
 | `patch({ rows: [...] })` | These rows arrive or change; the rest stand |
 | `patch({ drop: [...] })` | These keys are gone; the rest stand         |

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

@@ -1,8 +1,8 @@
 # The Basic Widget Library
 
-Eleven widgets: `lb-input`, `lb-select`, `lb-options`, `lb-picker`,
+Thirteen widgets: `lb-input`, `lb-select`, `lb-options`, `lb-picker`,
 `lb-table`, `lb-unknown-page`, `lb-confirm`, `lb-form`, `lb-insert-dialog`,
-`lb-master` and `lb-checkbox`. Every one of them is an ordinary custom element, written
+`lb-master`, `lb-checkbox`, `lb-number` and `lb-date`. Every one of them is an ordinary custom element, written
 against the contracts in [Custom Elements](./custom-elements.md#html) for its
 definition and [Custom Elements](./custom-elements.md#code) for its class.
 
@@ -258,6 +258,28 @@ checked. The hub sets a native checkbox's `checked` directly.
 | `exp-label`   | The label's text                              |
 | `exp-request` | The checkbox's `lb-request`, none when absent |
 
+## `lb-number` and `lb-date`
+
+A number shown by the browser's `Intl.NumberFormat`, and a date or time
+shown by `Intl.DateTimeFormat`.  Neither is a control: `lb-column` goes on
+the tag, and the widget renders the `lb-column-value` the hub stamps; see
+[Receiving a value](./custom-elements.md#receiving-a-value).
+
+```html
+<lb-number lb-column="balance" exp-style="currency" exp-currency="USD"></lb-number>
+<lb-date lb-column="due" exp-date-style="medium"></lb-date>
+```
+
+Each parameter is one of Intl's options in kebab-case, as `exp-currency-sign`
+for `currencySign`, plus `exp-locale`.  A value that is no number or date
+shows as it arrived, and a date alone, `YYYY-MM-DD`, shows as that day in
+every time zone.  The stamp keeps the raw value, so a stylesheet selects on
+it:
+
+```css
+lb-number[lb-column-value^="-"] { color: var(--negative); }
+```
+
 ## `lb-unknown-page`
 
 The chrome's dialog for a URL that names no page, as one tag: