@loadbare/app 0.18.1 → 0.19.0

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
@@ -229,8 +229,9 @@ export const requests: Requests = {
 };
 ```
 
-Declare every request the page allows. The server refuses a name the page
-does not declare.
+Declare every request the page allows. The builder refuses markup naming a
+request the page does not declare, and the server refuses one that arrives
+anyway; see [The markup checks](./data-binding.md#the-markup-checks).
 
 ### crud
 
@@ -293,8 +294,9 @@ export const requests: Requests = {
 };
 ```
 
-Declare every request the query permits. The server refuses a request a
-query does not declare, and a query with no `crud` entry permits none.
+Declare every request the query permits. The builder refuses markup sending
+a request a query does not declare, and the server refuses one that arrives
+anyway. A query with no `crud` entry permits none.
 
 Write `rowUpdate` to set the columns `values` names and leave every other
 column as it is. A form or a live row sends every control it gathers, and a
@@ -303,6 +305,36 @@ columns the page may edit.
 
 Every value in `values` is a string, as a control's value is.
 
+Two users writing the same row overlap only on the columns their requests
+carry, and the last write wins.  A single control sends its own column, so
+two users editing different columns of a row do not overwrite each other.
+A form sends every control it gathers, so two forms saved over one row
+overlap on all of their columns.
+
+A write whose outcome matters states its precondition in its own SQL, and
+refuses when no row was updated:
+
+```ts
+handlers: {
+  approve: {
+    run: async (ctx, { key }) => {
+      const updated = await ctx.db.run(
+        "UPDATE invoice SET status = 'approved' WHERE id = $1 AND status = 'pending'",
+        [key],
+      );
+      if (updated === 0) {
+        throw refusal("Someone else has already decided this invoice.");
+      }
+    },
+    refresh: ["invoice"],
+  },
+},
+```
+
+The request's name says what the user meant, and the precondition follows
+from it, so no earlier value is needed.  See
+[Refusing a request](#refusing-a-request).
+
 ### refresh and patch
 
 List in `refresh` every query whose whole answer the request changed.
@@ -317,6 +349,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:

package/docs/possible-ideas.md

@@ -1,314 +0,0 @@
-# Possible Ideas
-
-> **LLM-authored, not yet revised by a person.**  Drafted by Claude on
-> 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
-element: `<tr lb-query>`, `<option lb-column>`, `<tbody lb-show>`.  Behavior
-is different.  The platform attaches code to markup through a custom element
-tag, and a tag must survive the parser.  In a table, a `<select>`, or a `<p>`
-it does not: an unexpected tag is dropped, moved out of the table, or closes
-the paragraph.
-
-So code that concerns one row lives on a wrapper around the whole table.
-`lb-table` owns the `<table>`, and the page writes its contents as named
-templates (`head`, `foot`, `ghost`) that the builder joins back into a
-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, and only the second
-survives.
-
-### Customized built-ins
-
-```html
-<tr is="lb-ghost-row">…</tr>
-```
-
-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
-
-```html
-<tr lb-behavior="ghost-row">…</tr>
-```
-
-Code bound to any element by an attribute, as Stimulus does with
-`data-controller`.  It fits the parser everywhere and needs no polyfill.
-
-- What usually drives it is a `MutationObserver`, which is incidental: the
-  code runs because something noticed.  The hub, though, already knows every
-  time it puts an element in the page: it shows a page, clones a row, builds
-  a group, and moves an element in and out of an `lb-show` template.  A
-  behavior attached and detached at those moments would be explicit.
-- Elements the hub does not add (a widget's own scaffolding, anything a
-  script creates) would get no behavior, which may be the right rule rather
-  than a limitation.
-- No form association of its own, and mostly none needed: a behavior on a
-  native control leaves it a native control, which joins its form, takes
-  focus and honors `autofocus` as it always did.  Only a control whose UI is
-  built from scratch needs `ElementInternals`, and stays an autonomous
-  custom element.
-- The platform has discussed a registry for custom attributes, which would
-  be this idea built in.  It has not shipped.  Without it the browser has no
-  part in a behavior: everything below is the hub's.
-
-#### A lifecycle in the hub's terms
-
-A custom element's lifecycle is the browser's, and it speaks of insertion:
-connected, disconnected, adopted.  The hub's work rarely lines up with it.  A
-moved row is disconnected and connected, the copy a move leaves behind is
-constructed, an `lb-show` toggle adopts twice, which is why a custom element
-must write `connectedCallback` to run again.
-
-A behavior's lifecycle would be calls the hub makes from its own code, at
-moments it already knows, named for what the hub did:
-
-| The hub                                                        | A behavior hears                                            |
-| -------------------------------------------------------------- | ----------------------------------------------------------- |
-| Shows a page, places a cloned row, builds a group, first shows an element shipped absent | `attached()`, once, after the element is placed and filled |
-| Lands new values on the element's row                          | `landed(row)`                                               |
-| Moves a row the order put elsewhere                            | `moved()`; the instance is kept                             |
-| Leaves a copy of a moved row behind                            | Nothing; the copy gets no behavior                          |
-| Turns `lb-show` off, then on                                   | `hidden()`, then `shown()`; the instance is kept            |
-| Removes a row, once its animations end                         | `detached()`, once                                          |
-| Finishes a request issued from inside the element              | `requestDone(detail)`                                       |
-
-- `attached` and `detached` pair exactly, so setup and teardown need no
-  guard against running twice.
-- The calls are the code-side twin of the stamps a stylesheet already sees
-  (`lb-row-created`, `lb-row-changed`, `lb-row-moved`, `lb-row-leaving`):
-  one vocabulary for CSS and code, in the hub's relational terms.
-- The hub keeps one instance per element and behavior name.  An element may
-  carry several, `lb-behavior="ghost-row autosave"`, which a tag cannot.
-- A behavior is a class in a file the builder finds by name, as it finds
-  `<tag>.browser.ts`, and a name with no file is a build error.
-
-What the hub would have to define and keep: whether `attached` comes before
-or after the rows inside a host land, and the order of calls among nested
-behaviors.  A custom element gets its ordering from the platform; here it is
-loadbare's to state.
-
-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 it would land
-
-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
-
-Today a custom element's tag does two jobs: at build time it is expanded,
-and at run time it carries code.  Because the code needs the tag, the tag
-ships as a wrapper around what it expanded, and the wrapper is the source of
-most widget friction: focus searched for inside it, values forwarded through
-it, `autofocus` lost, and no place in a table.
-
-With behaviors carrying the code, expansion is free to stop shipping the
-tag.
-
-```html
-<!-- page -->
-<lb-field exp-label="Name" lb-column="name"></lb-field>
-
-<!-- what ships -->
-<!-- lb-field exp-label="Name" lb-column="name" -->
-<label lb-behavior="lb-field">Name <input lb-column="name" /></label>
-```
-
-- **The tag becomes a comment.**  The shipped DOM keeps a trail back to the
-  source at no run-time cost.  A comment is legal anywhere, tables included,
-  and is invisible to CSS, `:nth-child` and the hub's counting.
-- **The builder puts the behavior on the root.**  When
-  `<name>.behavior.ts` exists, the expanded root gets `lb-behavior="<name>"`;
-  the author never writes it.  `[lb-behavior~="lb-field"]` then serves CSS
-  and `querySelector` as the tag selector `lb-field` does now.
-- **Every widget inherits one base class.**  A `Behavior` holds `this.el`,
-  has empty methods for every call in the hub's lifecycle, and types
-  `landed(row)` and `requestDone(detail)`.  A widget overrides only what it
-  uses, as it extends `HTMLElement` or `WrappedControl` today.
-
-The file convention decides which path an element takes:
-
-| The element has                            | The builder                                        | At run time            |
-| ------------------------------------------ | -------------------------------------------------- | ---------------------- |
-| An element file, no script                 | Replaces the tag, leaves a comment                 | Plain HTML             |
-| An element file and `<name>.behavior.ts`   | Replaces the tag, puts `lb-behavior` on the root   | The hub's lifecycle    |
-| `<name>.browser.ts`                        | Keeps the tag, as today                            | The browser's lifecycle |
-
-The third row is for controls built from scratch, the only elements that
-still need `ElementInternals`.
-
-### A flag to keep the tag
-
-Considered and set aside.  It gives every widget two DOM shapes, so its CSS
-and code must work in both.  It cannot apply where replacing pays off most,
-since a kept tag still has no place in a table.  And what people would keep
-the tag for, a name to find and style the widget by and a trail to its
-source, the `lb-behavior` attribute and the comment already give.
-
-### To settle
-
-1. **One root.**  A behavior attaches to one element, so an element file with
-   a behavior has exactly one top-level element, and anything more is a
-   build error.
-2. **Where the tag's attributes go.**  The wrapper used to keep them; once
-   the tag is gone each needs a destination.  The natural default is the
-   root, and `lb-field` breaks it: its root is the `<label>`, but
-   `lb-column` belongs on the `<input>` inside while `lb-show` belongs on the
-   label.  Either the element file marks a target for data attributes, or
-   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.