@loadbare/app 0.18.2 → 0.19.1

package/docs/departures.md

@@ -0,0 +1,63 @@
+# Departures
+
+The theory says Loadbare/app follows HTML wherever HTML already has an
+opinion, and does not reimplement browser behavior.  In two places it
+departs from HTML's model on purpose, both for the 300ms budget.
+
+A departure is not a [miswart](./miswarts.md).  A miswart is small,
+orthogonal and terminating.  A departure is large, other behavior rests
+on it, and it cannot be removed without redesigning the framework.
+
+Each entry states what HTML does, what Loadbare/app does instead, what
+that buys, what it costs, and what rests on it.
+
+## Navigation
+
+**What HTML does.**  One document per URL.  Following a link fetches a
+new document from the server, and a URL that names nothing is answered
+with a 404.
+
+**What Loadbare/app does.**  One document holds every page, each as a
+`<template>`.  The server answers every route with that one document,
+and the hub shows the page the path names by cloning its template into
+`<main>`.  A path that names no page is found out in the browser, not
+answered with a 404.
+
+**What it buys.**  Performance.  Moving between pages fetches no HTML
+and no code, only the page's data.  The browser parses every page once,
+when the document first loads.
+
+**What it costs.**
+
+- The first load carries every page, whether or not the user visits it.
+- There is no 404 status for a path that names no page.  Loadbare/app is
+  for applications, not sites, so no crawler is expected to care.
+- The application must be served from the origin root, not a subpath.
+
+**What rests on it.**  The hub's link handling, the URL as the query
+`lb-url`, the server's catch-all route, and the unknown-page dialog.
+
+## The wire
+
+**What HTML does.**  The server sends HTML, and the browser renders it.
+Libraries that extend HTML, such as htmx, keep that model and send HTML
+fragments.
+
+**What Loadbare/app does.**  After the first load, the server sends only
+data: rows as JSON, a patch of the rows that changed, or a refusal.  The
+HTML that shows the rows is already in the browser, and the hub lands
+the rows into it.
+
+**What it buys.**  Performance.  Rows are far smaller than the markup
+that displays them, the server renders nothing, and nearly all of its
+time for a request is the database's time.
+
+**What it costs.**
+
+- The application does not work without JavaScript.
+- The server cannot shape the markup per request.  What varies by
+  request must be data, landed by the rules every row follows.
+
+**What rests on it.**  Landing, patches, the response items every
+request answers with, and the server's page code, which returns rows
+and never markup.

package/docs/miswarts.md

@@ -0,0 +1,140 @@
+# Miswarts
+
+A miswart is a place where Loadbare/app breaks one of its own rules.
+Anybody paying attention will see it as a violation, and they will be
+right.  Yet in context it turns out to be the RightThing(tm), and doing it
+any other way would be worse for the user or the developer.
+
+The reference describes each miswart's behavior where it applies, and
+links here.  This document is the one place that admits they are
+exceptions, and says why each one is allowed to stay.
+
+## The test
+
+A miswart must be:
+
+- **Small.**  It can be stated in a sentence or two.
+- **Orthogonal.**  It has no interaction with any other miswart.
+- **Terminating.**  It does not, by logical extension, require another
+  miswart.  If fixing the edges of one exception calls for a second, we
+  probably should be looking for a weakness in earlier implementation
+  decisions. 
+
+Each entry also names two things:
+
+- **The rule it breaks.**  If we cannot name the rule, it is not a
+  miswart, it is undocumented behavior.
+- **The motivation that justifies it**: performance, correctness or
+  ergonomics, as set out in the theory document.  That is what makes it
+  the RightThing(tm) rather than a convenience.
+
+## Radio button names in a row template
+
+**What.**  The hub stamps the `name` of each radio button in a row
+template with the `name` written, or its column when none is, followed by
+`-` and the live row's key.
+
+**Rule broken.**  The hub writes only its own stamps, which always
+begin with `lb-`.
+
+**Why it is the RightThing(tm).**  Correctness.  The browser groups radio
+buttons by `name`, and a row template repeats one `name` in every live
+row, so without the stamp every row's buttons would form a single group,
+and checking one row would uncheck all the others.
+
+**Why it terminates.**  It applies only to radio buttons inside a row
+template, and only the `name`.
+
+## Checkboxes and radio groups always gather a value
+
+**What.**  An unchecked checkbox gathers `"false"`, a checked one
+`"true"`, and its `value` attribute means nothing to the hub.  A radio
+group with none checked gathers `""`.
+
+**Rule broken.**  Where HTML already has an opinion, Loadbare/app
+follows it.  HTML sends a checkbox's `value` when it
+is checked, and sends nothing for an unchecked checkbox or an empty radio
+group.
+
+**Why it is the RightThing(tm).**  Correctness.  A write must be able to
+set a flag back to false, or clear a choice, and nothing on the wire
+cannot say either.
+
+**Why it terminates.**  It applies only to gathering from these two
+controls.  Landing still follows HTML's own idea of checked.
+
+## Rows hidden by a filter
+
+**What.**  A row that does not pass the user's filter gets the `hidden`
+attribute, and so does a group whose rows are all hidden.
+
+**Rule broken.**  The hub writes only its own stamps, which always
+begin with `lb-`.
+
+**Why it is the RightThing(tm).**  Performance and ergonomics.  A filter
+over rows already on the page needs no round trip, and `hidden` is HTML's
+own word for an element that is present but not shown.  A stamp of our
+own would make every stylesheet restate what the browser already does.
+
+**Why it terminates.**  It applies only to live rows and groups under a
+filter.
+
+## Leaving rows are inert
+
+**What.**  A row on its way out takes `inert` while its animation runs,
+and is removed when the animation finishes.
+
+**Rule broken.**  The hub writes only its own stamps, which always
+begin with `lb-`.
+
+**Why it is the RightThing(tm).**  Correctness.  A row that is gone from
+the database must not take a click or the focus during its exit
+animation, and `inert` is exactly HTML's word for that.
+
+**Why it terminates.**  It applies only to a row already stamped
+`lb-row-leaving`, which never comes back.
+
+## Busy elements carry aria-busy
+
+**What.**  While an element's request is in flight, it carries
+`aria-busy="true"` alongside `lb-request-pending`.
+
+**Rule broken.**  The hub writes only its own stamps, which always
+begin with `lb-`.
+
+**Why it is the RightThing(tm).**  Correctness, for a user of assistive
+technology.  `lb-request-pending` tells a stylesheet, and `aria-busy` tells
+a screen reader, the same fact.
+
+**Why it terminates.**  It rides with `lb-request-pending` and nothing
+else.
+
+## The hub unhides the body
+
+**What.**  When the chrome writes `<body hidden>`, the hub removes
+`hidden` once the first page has landed.
+
+**Rule broken.**  The hub writes only its own stamps, which always
+begin with `lb-`.
+
+**Why it is the RightThing(tm).**  Performance, as the user perceives it.
+Without it, the first load blinks an empty page before the data lands.
+Only the hub knows when the first page has landed.
+
+**Why it terminates.**  It happens once, to `<body>`, and only when the
+application opted in by writing `hidden`.
+
+## `lb-url` lands every parm it names
+
+**What.**  When `lb-url` lands, a query parm the URL does not carry lands
+empty on every element naming it as a column.
+
+**Rule broken.**  Landing a row sets the columns the row carries, and
+leaves the rest as they were.
+
+**Why it is the RightThing(tm).**  Correctness.  A control must show what
+the address bar says, after Back as well as after a reload, and a parm
+that is absent from the URL is a parm whose value is empty.
+
+**Why it terminates.**  It applies only to `lb-url`, the one query whose
+columns are the URL itself.

package/docs/opinions.md

@@ -0,0 +1,155 @@
+# The Opinions of Loadbare/app
+
+Every framework forces some decisions on the people who use it.  This
+document lists the ones Loadbare/app forces, so a developer can see
+them in one place before writing an application.  The reasons for each
+are in the [theory](./theory.md).
+
+## What counts as an opinion
+
+An opinion is a position that is:
+
+1. Forced.  There is no supported way around it.  A position the
+   developer can opt out of is a default.
+2. Contested.  Competent frameworks in the wild decide otherwise.  A
+   position nobody takes differently is just how the platform works.
+3. Pervasive.  It shows up in most of what the developer writes, most
+   pages and most handlers, rather than in one feature.
+
+An opinion limits what the developer can express.  A convention limits
+only where they put it.  The file names `<stub>.page.html`,
+`<stub>.queries.ts` and `<stub>.requests.ts` are forced and pervasive,
+but they are a convention, and are not listed here.
+
+The [departures](./departures.md) are measured against HTML, and the
+[miswarts](./miswarts.md) against Loadbare/app's own rules.  The
+opinions are measured against the developer's freedom.  An entry can be
+more than one of these: the wire is both a departure and an opinion.
+
+## Two shapes, and every row has a key
+
+Loadbare/app understands two data shapes, a `row` and a set of `rows`.
+Every row arrives with its key.  Column values are atomic.  A document
+that embeds child rows in a parent row must be split into two query
+results before Loadbare/app can show it.
+
+Other frameworks accept any JSON the server sends, nested to any depth,
+and leave identity to the developer.  In Loadbare/app, every query a
+developer writes answers in one of the two shapes, and every element
+that shows data is bound to one of them.
+
+## HTML is static
+
+The developer writes each page's markup once.  The server does not
+generate markup per request, and there is no templating language in
+the browser.  Whatever varies from one request to the next must be
+data, and it reaches the screen by the same rules every row follows.
+
+Server-side templates, JSX, and libraries that send HTML fragments all
+generate markup at run time.  In Loadbare/app, every page is plain
+HTML, and every visible difference between two users or two moments is
+a column value.
+
+## The server answers only with data
+
+After the first load, the server sends rows, a patch of the rows that
+changed, or a refusal.  It never sends markup, and it never sends
+instructions for the browser to carry out.
+
+Applications in the wild answer with HTML, with JSON, with redirects,
+with scripts, and with every combination of them.  In Loadbare/app,
+every handler a developer writes returns rows or refuses.  See
+[the wire](./departures.md#the-wire).
+
+## The screen changes only when the server answers
+
+Loadbare/app changes the screen from what the server sent, and never
+ahead of it.  There are no optimistic updates.  A write shows on screen
+when the rows it changed come back.
+
+Many frameworks update the screen first and reconcile when the server
+answers.  In Loadbare/app, every write a developer designs is shown by
+the rows its handler returns.
+
+## Requests come from the document
+
+A request is named on an element with `lb-request`.  The hub supplies
+the query and the key from where the element sits, and gathers the
+values from the controls bound to columns.  The developer writes no
+`fetch`, designs no endpoints, and never passes a key by hand.
+
+Most frameworks have the developer write the call to the server, choose
+its URL, and assemble its body.  In Loadbare/app, every button, form,
+and control that writes is a named request on an element.
+
+## A page declares what it shows and what it allows
+
+A page's queries are what it shows, and its requests are what it
+allows.  The server refuses any request a page did not declare.
+Nothing is reachable from the browser that a page has not published.
+
+Elsewhere, any route the server registers is reachable, and access is
+checked inside each handler.  In Loadbare/app, every page carries its
+own list, and the list is the whole of what the browser can ask for.
+
+## The URL names a place
+
+The path names a page.  It never names a resource, so `/accounts/42`
+is not a way to reach account 42.  The query string describes what the
+page has on screen, and it never commands.  The server remembers
+nothing about the view, so a URL reloads, bookmarks, and mails as the
+same view.
+
+REST names resources in the path, and many applications keep view
+state on the server or in the browser's memory.  In Loadbare/app,
+every link and every query parm follows this rule.  See
+[Query parms](./reference/chrome.md#query-parms).
+
+## Framework state is a row
+
+What the framework itself keeps is presented as rows.  The URL is the
+query `lb-url`, of kind `row`, and lands like any server query.  User
+preferences and choices on a page are sent as `lb-row-update` for `lb-choices`,
+and can land anywhere on the page.
+
+Most frameworks keep their own state in a store with its own interface.
+In Loadbare/app, a developer shows the current page's label or a
+query parm the same way they show a customer's name.
+
+## Mistakes stop the build or the server
+
+What can be checked before the application runs is checked, and a
+mistake stops the build or the server.  The builder refuses a custom
+element it cannot find, and any `lb-` attribute the developer is not
+allowed to write.  The server refuses known wrong patterns at startup.
+What cannot be checked ahead of time is reported on the console when
+it happens.
+
+Many frameworks tolerate a mistake and render what they can.  In
+Loadbare/app, every page and every handler passes these checks before
+it runs.
+
+## Constraints belong to the database
+
+Business rules are enforced by the database or by the application's
+server code.  A handler refuses a request with words written for the
+user, for the request as a whole or for each column, and the browser
+shows them on the controls they belong to.  Any other failure reaches
+the browser as a plain failure, with no stack trace or database
+message.
+
+Many frameworks validate in the browser and again on the server, with
+two sets of rules to keep in step.  In Loadbare/app, every rule the
+user can break is answered by a refusal from the server.
+
+## Widgets are custom elements
+
+A widget, what other frameworks call a component, is a custom element.
+There is no component model of Loadbare/app's own.  A widget talks to
+the hub through the attributes, events, and methods described in
+[Custom Elements](./reference/custom-elements.md#code).
+
+Most frameworks define their own component model, with its own
+lifecycle and its own way of passing data.  In Loadbare/app, every
+widget, those in `@loadbare/widgets` and those an application writes,
+is a standard custom element.

package/docs/reference/builder.md

@@ -44,11 +44,16 @@ The builder classifies by name, not location.
 | `*.queries.ts`             | A page's queries, matched by base name            |
 | `imports.ts`               | The packages this app takes widgets from          |
 | `*.css`                    | A stylesheet — see [CSS](./css.md)                |
-| Any other `.html`          | A widget definition, named for the tag it defines |
+| `<tag-name>.html`          | A widget definition, named for the tag it defines |
 | `<tag>.browser.ts`         | A widget script, named for the tag it registers   |
 
 Give the application exactly one `chrome.html` and at most one `imports.ts`.
-Give every `.requests.ts` and `.queries.ts` a `.page.html` of the same base name.
+Give every `.requests.ts` and `.queries.ts` a `.page.html` of the same base name;
+one with no page is a build error.
+
+A widget definition is exactly `<kebab-case-name>.html`. Any other `.html`
+file is an error when it looks like a definition with capitals in its name,
+and is skipped otherwise.
 
 Name a widget script `<tag>.browser.ts`, not `<tag>.ts`. Only a file whose
 name carries `.browser` is bundled for the browser; every other module under
@@ -128,11 +133,22 @@ substitution rules — wraps each expanded page in
 `<template lb-page="<stub>">`, and splices them into the chrome's `<body>`.
 It removes a page file's `<title>` and stamps its text on the page's
 template as `lb-page-title`; see [The page title](./page-files.md#the-page-title).
-It formats the result with Prettier when the application has it installed.
+It formats the result with Prettier, which ships with `@loadbare/app`, and
+keeps the unformatted result if Prettier fails.
 
 The builder checks the `lb-` attributes of the chrome and every page after
 expansion, and stops on the first file with a problem; see
-[The markup checks](./data-binding.md#the-markup-checks).
+[The markup checks](./data-binding.md#the-markup-checks). The names
+`lb-query` and `lb-request` carry are checked against what each page
+declares, which the builder reads by loading the page's `.queries.ts` and
+`.requests.ts` modules. Their import-time code runs during the build, as it
+does when the server starts, so a module that connects to a database at
+import connects during the build too; open connections in `contextFor`
+instead.
+
+It also writes `client-entry.ts`, the generated entry `client.js` is bundled
+from, and leaves it there. Nothing reads it after the bundle, and an
+application neither writes nor imports it.
 
 The builder writes `app.css` only when it finds a stylesheet, and `pages.ts`
 only when some page has a `.requests.ts` or a `.queries.ts` file. Import `hub`

package/docs/reference/chrome.md

@@ -103,6 +103,12 @@ server's row lands, so a chrome shows where the page is with no code:
 | `lb-page-unknown` | `true` when no page's stub matches the path             |
 | Any other name    | The query parm of that name, or empty when it is absent |
 
+The path names a page, never a resource: `/accounts/42` is not a way to
+reach account 42, and an application designs no endpoints. The query string
+describes what that page has on screen, `/accounts?acct=23`, and never
+commands. The server remembers nothing about the view, so a URL reloads,
+bookmarks and mails as the same view.
+
 A path names a page by its stub: `/members` shows `members.page.html`, and
 `/` shows `index.page.html`. A page's title is the text of the `<title>` its
 page file carries; see [page files](./page-files.md#the-page-title). The hub
@@ -139,11 +145,17 @@ Write `lb-url-link` on an `<a>` to move between pages:
 </nav>
 ```
 
-On a plain primary click, the hub pushes a history entry for the `href`,
-path and query string both, and shows the page it names. A click with a
-modifier key or another button, and a link without `lb-url-link`, behave as
-the browser has them behave. Back and Forward show the page at the URL they
-arrive at.
+On a plain primary click, the first button with no modifier key and not
+already handled, the hub pushes a history entry for the `href`, path and
+query string both, and shows the page it names. Any other click, and a link
+without `lb-url-link`, behave as the browser has them behave, so leaving the
+application is the default and staying in it is the opt-in. The attribute
+takes no value. Back and Forward show the page at the URL they arrive at.
+
+Path space is flat: `/members` shows `members.page.html` wherever under
+`--src` it sits. The query string is kept, so
+`/transactions?date_begin=2026-09-01` opens the page narrowed to those
+dates.
 
 ### Query parms
 
@@ -170,11 +182,28 @@ pushes one instead when the element carrying `lb-request` also carries
 
 The hub answers the request itself, with no round trip, then reloads the
 page's queries at the new URL. The page stays in place, and rows that come
-back keep their place.
+back keep their place. A request that leaves the URL as it was does
+nothing. `lb-page-label` and `lb-page-unknown` are the hub's, and a request
+never sets them.
+
+A request that gives `lb-path` a new value enters that page, pushes a
+history entry, and the new URL carries only the query parms the request
+names.
 
 A control whose column the URL does not carry lands empty, so every control
 inside `lb-query="lb-url"` shows what the address bar says, after a reload
-and after Back alike.
+and after Back alike
+([miswart](../miswarts.md#lb-url-lands-every-parm-it-names)).
+
+Loadbare assigns no parm a meaning, and a column of `lb-url` whose name
+begins with `lb-` is never a query parm.
+
+A query parm is user input. A query still takes no argument from the
+browser, and a parm arrives the way the session cookie does, as part of the
+request the context is built from, but a user who types `?acct=99999`
+influences what a query returns. Validate it where the application reads
+it; a per-session database role means an id outside the caller's reach
+finds nothing.
 
 An order or a filter the hub applies to rows the page already holds is not
 a query parm. It is a [choice](./data-binding.md#choices), which holds until
@@ -198,8 +227,13 @@ show the path:
 ```
 
 When no page's stub matches the path, `lb-page-unknown` is `true`,
-`lb-page-label` is null, `<main>` keeps the page it had, and the hub calls
-`showModal()` on the dialog.
+`lb-page-label` is null, `<main>` keeps the page it had, the hub calls
+`showModal()` on the dialog, and reports the path to the console. A chrome
+with no dialog shows nothing. `lb-url` lands before the page is looked up,
+so the dialog shows the path by naming it like any other element.
+
+Every route gets the same document, so an unknown path is found out in the
+browser after a successful 200, and there is no server-delivered 404.
 
 `@loadbare/widgets` ships this dialog as `<lb-unknown-page>`, for a chrome
 that would rather write one tag; see
@@ -224,7 +258,8 @@ being visibly empty — so it's the whole document that needs to wait, not
 just the piece that was empty.
 
 The `<noscript>` block is the escape hatch for a visitor with JavaScript
-disabled. `<lb-hub>` is what removes `hidden` from `<body>`, so a browser
+disabled. `<lb-hub>` is what removes `hidden` from `<body>`
+([miswart](../miswarts.md#the-hub-unhides-the-body)), so a browser
 that never runs `client.js` would otherwise be stuck looking at a
 permanently blank page. `<noscript>` content is only rendered when scripting
 is off, so the fallback rule only ever applies in exactly that case — it

package/docs/reference/css.md

@@ -41,7 +41,6 @@ Serve it at `/app.css` and link it from the chrome:
 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
 

package/docs/reference/custom-elements.md

@@ -250,30 +250,8 @@ takes part in data binding in one of four ways: it is a control, it renders
 a value, it sends a request, or it holds rows.
 
 Import every Loadbare name from `@loadbare/app/constants`, and never write
-one as a string literal:
-
-| Constant               | Value                |
-|------------------------|----------------------|
-| `ATTR_QUERY`           | `lb-query`           |
-| `ATTR_COLUMN`          | `lb-column`          |
-| `ATTR_SHOW`            | `lb-show`            |
-| `ATTR_REQUEST`         | `lb-request`         |
-| `ATTR_COLUMN_VALUE`    | `lb-column-value`    |
-| `ATTR_KEY_VALUE`       | `lb-key-value`       |
-| `ATTR_ROW_LIVE`        | `lb-row-live`        |
-| `LIVE_ROW`             | `[lb-row-live]`      |
-| `ATTR_QUERY_ROW_COUNT` | `lb-query-row-count` |
-| `ATTR_REQUEST_PENDING` | `lb-request-pending` |
-| `ATTR_REQUEST_ERROR`   | `lb-request-error`   |
-| `REQUEST_ROW_INSERT`, `REQUEST_ROW_UPDATE`, `REQUEST_ROW_DELETE` | The requests Loadbare provides |
-| `LB_ROW_REQUESTS`      | All three, in one array |
-| `LB_EVENT_NAME`        | `lb-request`, the event every request travels as |
-| `LB_DONE_EVENT_NAME`   | `lb-request-done`, the event that says how it turned out |
-| `SHOW_NOT`             | `!`, written before a column in `lb-show` |
-| `URL_QUERY`            | `lb-url`             |
-| `CHOICES_QUERY`        | `lb-choices`         |
-| `URL_COLUMN_PATH`, `URL_COLUMN_PAGE_LABEL`, `URL_COLUMN_PAGE_UNKNOWN` | `lb-path`, `lb-page-label`, `lb-page-unknown` |
-| `LB_RESERVED_PREFIX`   | `lb-`                |
+one as a string literal: `ATTR_COLUMN_VALUE` rather than `"lb-column-value"`.
+[Constants](./names.md#constants) lists them all.
 
 A custom element reads `lb-` attributes and never assigns one. The developer
 writes them in markup, and the hub and the builder write their stamps.
@@ -290,7 +268,7 @@ Each direction has one mechanism for each kind of message:
 
 | Direction      | What                                       | How                         | Today |
 |----------------|--------------------------------------------|-----------------------------|-------|
-| Hub to element | State that lasts                           | An attribute the hub stamps | `lb-column-value`, `lb-key-value`, `lb-query-row-count`, `lb-group-*`, `lb-row-*`, `lb-request-pending`, `lb-request-error` |
+| Hub to element | State that lasts                           | An attribute the hub stamps | `lb-column-value`, `lb-key-value`, `lb-query-row-count`, `lb-group-*`, `lb-row-*`, `lb-request-pending`, `lb-request-error`, `lb-request-refused` |
 | Hub to element | State the platform already names           | A property                  | A control's `value` |
 | Hub to element | What the hub did                           | An optional `lb` method     | `lbAttached`, `lbRowsLanded`, `lbRequestDone`, `lbDetached` |
 | Hub to element | A moment an element started                | A bubbling event            | `lb-request-done` |