@loadbare/app 0.19.0 → 0.19.1

package/docs/comparison.md

@@ -12,7 +12,7 @@
 
 This document states how `@loadbare/app` differs from the frameworks and
 libraries most used for front-end development today.  It repeats material
-from [Theory](./theory.md), [TECHREF-1.0](./TECHREF-1.0.md) and
+from [Theory](./theory.md), the [Reference](./reference/overview.md) and
 [Prior art](./prior-art.md) so that it can be read on its own.  Where this document and
 [Theory](./theory.md) disagree, Theory is authoritative.
 
@@ -21,9 +21,8 @@ goals and the one decision that serves them.  Two are deliberate departures
 from HTML's own model, in navigation and on the wire, and are set out in
 [Departures](./departures.md).
 
-Loadbare/app has not reached 1.0.  Five sections of
-[TECHREF-1.0](./TECHREF-1.0.md) are marked `UNEDITED`.  Anything below that describes Loadbare/app describes the
-code as it stands.
+Loadbare/app has not reached 1.0.  Anything below that describes
+Loadbare/app describes the code as it stands.
 
 ## Contents
 
@@ -974,7 +973,8 @@ performance measurements are published as of this writing.
 
 ## Surface area
 
-TECHREF-1.0 lists every name Loadbare/app owns in one cross-reference.
+[Names](./reference/names.md) lists every name Loadbare/app owns in one
+cross-reference.
 
 | Owned                                | Count | Names                                                                                                                                                                                                                                                                                                                                                                       |
 | ------------------------------------ | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -1131,7 +1131,8 @@ should not mistake one for the other.
 
 ### Gaps and open items
 
-Each is current behavior or an open item named in TECHREF-1.0 or the
+Each is current behavior or an open item named in the
+[Reference](./reference/overview.md) or the
 [Roadmap](./roadmap.md).
 
 | Area                                | Status                                                                                                                                               |

package/docs/opinions.md

@@ -103,7 +103,7 @@ 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
-[What a URL names](./TECHREF-1.0.md#what-a-url-names).
+[Query parms](./reference/chrome.md#query-parms).
 
 ## Framework state is a row
 
@@ -147,7 +147,7 @@ user can break is answered by a refusal from the server.
 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](./TECHREF-1.0.md#custom-elements).
+[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

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
@@ -141,6 +146,10 @@ 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`
 from `pages.ts` — see [The Express Server](./server.md) for the rest of the

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

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.