@loadbare/app 0.18.2 → 0.19.0

package/docs/roadmap.md

@@ -15,13 +15,6 @@ mechanism Release 1.0 already ships. Each is here because deciding it
 speculatively, before a real page forces the question, risks designing the
 wrong thing. Revisit when the described symptom actually shows up.
 
-### Staleness and concurrent writers
-
-Two tabs, or two users, updating the same rows at once. A solo developer
-testing in one browser will not produce this by accident, and retrofitting a
-version or conflict check onto every row after the fact touches every widget
-that writes.
-
 ### A query that pages or limits its rows
 
 The user's order and filters apply to the rows the browser holds. A query
@@ -49,6 +42,31 @@ end up living in the widget while the server remains authoritative for the
 same field. Not yet designed — revisit the first time an application needs
 inline validation.
 
+### Compound foreign keys
+
+A picker is the UI for a foreign key.  `<select lb-query="statuses"
+lb-column="status">` says the row's `status` references a row of
+`statuses`, and offers every one of them.  For a single-column foreign key
+that is exactly right, which is why a query in a row template answers the
+same rows in every live row.
+
+A compound foreign key cannot be expressed.  When `(type, status)`
+references `allowed_statuses(type, status)`, the choices for `status`
+depend on the row's own `type`, and every row is offered every status.
+The database knows the constraint, and the UI cannot say it, so a user is
+offered choices the server will refuse.
+
+A likely direction keeps one query and one answer: the lookup answers every
+allowed pair as ordinary rows, the picker names the columns of its row that
+restrict it, and the hub shows each picker only the rows that match, as it
+already filters the rows it holds.  Two questions come with it:
+
+- Whether the restricting value is the one that landed or the control's
+  current value, so the choices follow an edit before it is saved.
+- What becomes of a chosen value the restriction no longer allows.
+
+Revisit when an application needs a choice restricted by its row.
+
 ## Release 1.1 candidates
 
 Net-new scope, not gaps in 1.0. Release 1.1 will optimize for operational
@@ -128,9 +146,10 @@ breaks nothing.
 
 ### Queries stated by the chrome
 
-A custom element in the chrome naming a query forces every page to declare
-that query, since the page load covers one page's set.  `lb-url` shows the
-pattern from the framework side, and an application has no equivalent.
+The chrome belongs to no page, so the builder refuses an application query
+named there, and a custom element in the chrome cannot show application
+data.  `lb-url` and `lb-choices` show the pattern from the framework side,
+and an application has no equivalent.
 
 A chrome-level query set on `createHub` would close this, and it is additive.
 It takes its place in the [options on `createHub`](#options-on-createhub).
@@ -159,39 +178,6 @@ A query parm write replaces the history entry, and `lb-url-push` pushes
 one.  Which of the two a user wants may be the user's to say, rather
 than the page's.
 
-### Build-time checking of `lb-request` against the declared requests
-
-Release 1.0 resolves every `lb-request` value at request time. A value naming
-no entry under `handlers`, or one of the requests Loadbare provides for a
-query with no entry under `crud`, is found on the first commit: a server
-console warning and an empty answer, described in
-[Page files](./reference/page-files.md). A typo builds cleanly.
-
-The builder already expands each page and walks the finished document in
-`walkMarkup`, tracking the enclosing `lb-query`, so collecting every request
-name together with the query it is issued for needs no new machinery. What
-it lacks is the other half of the comparison: it knows the path of a
-`.requests.ts` file and never reads its contents.
-
-Two routes to the declared names, and the choice is the decision:
-
-- **Load the built module.** Bundle the generated `pages.ts`, import it, and
-  read the keys off the finished objects. Exact, and indifferent to how the
-  object was written. The build then executes application import-time code,
-  and a builder that only reads files stops being that.
-- **Parse the source.** Read the keys statically with the TypeScript compiler
-  API. No application code runs, at the price of a real dependency and of
-  guessing wrong on anything not written as a plain object literal.
-
-Two smaller calls come with either route. The chrome belongs to no page, so
-a request there can only be required of every page or forbidden. A page with
-no requests file makes any request on it an error. The check is sound
-because the developer writes `lb-*` attributes in markup and script never
-assigns them.
-
-The same machinery would then also let `lb-query` names be checked against
-the declared queries.
-
 ### A language server
 
 ...for Loadbare HTML.
@@ -203,6 +189,23 @@ expansion allows a strings file.  We could either preserve the fully
 static build-time system and create multiple versions of `app.html`, or we
 could add label hydration to the page navigation stage.
 
+### Version checks on update and delete
+
+The last write to a row wins, at the grain of the columns each request
+carries, and a write whose outcome matters states its precondition in its
+own SQL; see [crud](./reference/page-files.md#crud).  A plain edit has no
+such precondition: only the value the user saw, or a version standing for
+it, tells that the row changed in between, and the server remembers
+nothing.
+
+A query would declare its version column.  The hub keeps every query's
+last answer, patches included, so it would send the version it holds with
+each update and delete for that query, and the handler would put it in its
+`WHERE`.  No widget changes, and a control committing alone takes part.
+
+Revisit when an application needs a write refused because the row changed
+since the user saw it.
+
 ## Decided against
 
 Settled questions, kept here so they are not reopened.  Each names what was
@@ -222,3 +225,12 @@ attribute value, with no escape for either.
 
 Text has a workaround: `<div>Hello, <span>{{world}}</span></div>` places the
 placeholder in a text node of its own.  Attribute values have none.
+
+### Serving the static files
+
+A router beside `hubRoutes` that serves `client.js`, `app.css` and
+`app.html` would save an application three routes.  It would also decide
+for every application how those files are read, cached and placed among
+its own routes, and whether a path naming no page answers `app.html`.
+Loadbare/app ships no server, and serving the build's output is the
+application's choice, as the rest of its server is.

package/docs/testing.md

@@ -1,5 +1,9 @@
 # Testing
 
+> LLM-authored and LLM-maintained.  This is acceptable because the
+> document is fact-based, describing tests that exist in this package, and
+> is written to be consumed by an LLM working on the package.
+
 A contributor's document, and a companion to [theory.md](./theory.md). It
 describes how this package tests itself.
 
@@ -26,6 +30,23 @@ All four tiers run under `npm test` today and need no dependency that is not
 already installed. A fifth environment — a real browser — is discussed at the
 end and is not built.
 
+## What the tests are evidence for
+
+[Theory](./theory.md) makes three claims that can be checked, and this suite
+carries evidence for two of them.
+
+- **Correctness.**  Most of what Theory's correctness section names is
+  tested here: rows landed by key, an unchanged row left alone with what the
+  user typed, an answer in the wrong shape left out, a write sent once, a
+  refusal shown on the controls it names, and a server that refuses what a
+  page did not declare.
+- **The vocabulary rule.**  The markup checks in tier 1 enforce it at build
+  time: an `lb-` attribute outside the set the developer writes is a build
+  that fails.
+- **Performance.**  No tier measures the 300ms round trip.  Node and jsdom
+  have no network and no paint, so they are not evidence for it, and this
+  suite does not try.
+
 ## The runner
 
 `node:test`, run through `tsx`:
@@ -78,17 +99,14 @@ the most of what Loadbare promises, so it is first.
 - more than one `lb-exp-slot`
 
 **Markup checks.** The assembled chrome and every page are checked before
-anything ships:
-
-- an `lb-` attribute that is not one the developer writes
-- `lb-request="lb-…"` naming none of the requests Loadbare provides
-- `lb-url-link` off an `<a>`, `lb-url-push` without `lb-request`, and
-  `lb-url-unknown` off a `<dialog>` or outside `<lb-hub>`
-- `lb-show` on a `<template>`, on a row template's root, or with no row
-  around it
-- a chrome without exactly one `<lb-hub>` and one empty `<main>` inside it,
-  and a page carrying either
-- a widget script declaring an `lb` method Loadbare does not define
+anything ships, against the list in
+[The markup checks](./reference/data-binding.md#the-markup-checks).  Each one
+is a build that must not produce output.  The checks of `lb-query` and
+`lb-request` names take each page's declarations as `loadDeclared` reads
+them, and `loadDeclared` is tested against real page modules: names read
+off objects built with spreads and computed keys, nothing declared for a
+page with no modules, nothing left in the output directory, and a module
+that throws named in the error.
 
 A page file's `<title>` is lifted out and stamped as `lb-page-title`.
 
@@ -118,7 +136,7 @@ Review the golden files rather than blessing them. `npm run test:golden -w
 @loadbare/demo` rewrites them; the diff is the point, and a diff nobody read
 is a test nobody ran.
 
-The rest of the build — `assemble`, `elements`, `pages`, `styles`,
+The rest of the build — `assemble`, `declared`, `elements`, `pages`, `styles`,
 `package-css` — is tested the same way and in the same tier, since none of it
 needs a browser either.
 
@@ -126,7 +144,7 @@ needs a browser either.
 a temporary project, which carries a stand-in `@loadbare/app` pointing at
 the hub's source so the test needs no prior build.  It is tested for its
 default `src` and `dist`, every file it writes, `--minify`, a failed build's
-exit code, and `--watch` rebuilding on a change, skipping a file it does not
+exit code, a name the page does not declare, and `--watch` rebuilding on a change, skipping a file it does not
 watch, and surviving a failed build.
 
 ## Tier 2 — The engine
@@ -149,11 +167,22 @@ watch, and surviving a failed build.
   operator away from silently reversing
 - a handler returning `url()` answers with the `lb-url` item alone, and runs
   no refresh set
+- a `row` query that finds no row answers `null`
+- at startup, a malformed order, an unknown column type, and a crud request
+  that refreshes its own `rows` query are refused
+- an update or delete for several rows runs once per key, lays the patches
+  together, and refreshes once
+- `onPageEnter` may return `url()` or `choices()`, and `onChoices` hears
+  every choice the user makes
+- a refusal carries a message, columns or both, and passes through the
+  engine untouched
 
 `tests/lb-express.test.ts` runs against a listening app: the page comes from
 the path, the query parms reach `contextFor`, a `url()` answer is followed by
-the page loaded at the new URL, an undeclared request is refused, and a
-malformed body does not throw.
+the page loaded at the new URL, an undeclared request is refused, a
+malformed body does not throw, an oversized body is refused, a refusal
+answers 422 with its words, and any other throw answers 500 with nothing in
+it.
 
 ## Tier 3 — Landing
 
@@ -187,6 +216,10 @@ evidence here.
   groups and leaving them out of counts and aggregates (`lb-choices.test.ts`)
 - `lb-show` moves an element into a template and back, and landing reaches
   inside it
+- a row whose values arrive as it already shows them is not filled again,
+  so what the user typed into it stays
+- a `row` query answered with no row empties the columns it names and drops
+  its key
 
 Two properties, written as loops rather than with a library. Applying the
 same rows twice is applying them once. And rows reached through any sequence
@@ -252,6 +285,17 @@ What the hub is tested for here:
   loaded there
 - `hidden` comes off the body once a page has landed, including the page
   that failed to load, and a link whose page fails to load marks no element
+- an answer that returns after the user has moved to another URL does not
+  land
+- focus goes to the first element the user can operate once a page's
+  queries land
+- a form pointed at a row by `commandfor` fills from the row the hub holds,
+  and a row not yet entered sends no update or delete
+- ticked `lb-select` rows travel as `keys`, and the selection clears once
+  the request succeeds
+- a refusal lands its message on the element that committed and on each
+  control it names
+- `lb-request-done` reaches the element that committed and its ancestors
 
 Widgets are small and their logic is local, so jsdom carries them: a value
 reaches the control the widget owns, the widget is a form-associated control
@@ -282,18 +326,8 @@ No browser test runner is installed and none of the following exists. They
 are recorded here as the shape of the work, not as coverage:
 
 1. a cold load fills `<main>` with no empty flash
-2. the wizard never displays a step the server has not confirmed
-3. the view-source invariant
-
-The last is the one worth a browser. Loadbare's central claim is that no
-markup exists in the DOM that is not in view-source, and that the difference
-between the two is exactly the dynamic half. That is a property, it is stated
-precisely in [theory.md](./theory.md), and it should be enforced mechanically
-rather than believed: fetch the shell as text, compare the element set
-against the live document after interaction, and assert that the only
-additions are clones of row templates.
-
-See [TODO.md](../TODO.md) for this and the rest of the open work.
+2. the wizard page in `@loadbare/demo` never displays a step the server has
+   not confirmed
 
 ## Continuous integration
 
@@ -307,7 +341,7 @@ tiers here stay fast enough to run on every save.
 ## One change the tests want
 
 The client reports through `console.error` and `console.warn` directly, from
-roughly twenty places across `hub/` and `@loadbare/widgets`. Routing those through a
+more than twenty places across `hub/` and `@loadbare/widgets`. Routing those through a
 single `report()` in `core/` would give the tests one seam to observe instead
 of a global to mock per file, and would put the framework's error channel in
 the same file as the rest of its vocabulary. It is a small change and it is