@loadbare/app 0.18.2 → 0.19.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@loadbare/app",
   "description": "High performance web app framework for server-bound applications",
-  "version": "0.18.2",
+  "version": "0.19.1",
   "type": "module",
   "files": [
     "dist",

package/skills/loadbare-app/SKILL.md

@@ -42,8 +42,10 @@ tsc --noEmit
 `dist/pages.ts` imports page files with their `.ts` extensions, so the
 application's `tsconfig.json` needs `allowImportingTsExtensions`.
 
-Write, build, fix, and repeat until the build is clean.  Then start the
-server: `createHub` refuses a page that declares a reserved name at startup,
+Write, build, fix, and repeat until the build is clean.  The build loads
+each page's `.queries.ts` and `.requests.ts` to check the names the markup
+carries, so their import-time code runs then; open a database in
+`contextFor`, not at import.  Then start the server: `createHub` refuses a page that declares a reserved name at startup,
 and the server console reports a query that answers with the wrong kind.
 Restart the server after adding or changing a `.queries.ts` or
 `.requests.ts` file.
@@ -70,7 +72,8 @@ server.ts
 
 The chrome carries `<lb-hub>` inside `<body>`, an empty `<main>` inside the
 hub, and `<script src="/client.js" defer>`.  Everything a user touches sits
-inside `<lb-hub>`.
+inside `<lb-hub>`.  The chrome belongs to no page, so it names only the
+hub's queries, `lb-url` and `lb-choices`, and sends no declared request.
 
 A page is an HTML fragment that lands in `<main>`:
 
@@ -274,7 +277,9 @@ fetched to be edited is another page, with that row as its master.
 `crud`, keyed by query name, as `rowInsert`, `rowUpdate` and `rowDelete`.
 Each works on a `row` query as well as a `rows` query, since the element a
 `row` lands on carries its key.  Every other request name is a declared
-request, under `handlers`.  Anything undeclared is refused.
+request, under `handlers`.  The build refuses markup naming a query or
+request the page does not declare.  One that arrives anyway, from a script,
+is warned about on the server console and answered with nothing.
 
 **An empty key is a row not yet entered.**  A `row` query answering with an
 empty key, or a form `--lb-new` pointed, carries `lb-key-value=""`.  The hub
@@ -387,10 +392,13 @@ lb-query="lb-url">` in the chrome for it.
 whole data channel.
 
 **The developer writes `lb-*` attributes in markup, and script never
-assigns them.**  The builder refuses any `lb-` attribute other than
-`lb-query`, `lb-column`, `lb-show`, `lb-order`, `lb-filter`, `lb-request`,
-`lb-url-link`, `lb-url-push` and `lb-url-unknown`.  Everything else with the
-prefix is a stamp the hub or the builder writes.
+assigns them.**  The builder refuses any `lb-` attribute other than the
+sixteen in [Attributes](references/names.md#attributes): `lb-query`,
+`lb-column`, `lb-show`, `lb-order`, `lb-filter`, `lb-group`, `lb-count`,
+`lb-sum`, `lb-avg`, `lb-min`, `lb-max`, `lb-select`, `lb-request`,
+`lb-url-link`, `lb-url-push` and `lb-url-unknown`.  `lb-exp-slot` and
+`lb-exp-template` are expansion's, and never reach the page.  Everything
+else with the prefix is a stamp the hub or the builder writes.
 
 **`lb-` belongs to Loadbare.**  The application should never name anything
 with the `lb-` prefix anywhere: no attribute, query, column, request, custom
@@ -495,8 +503,6 @@ with the package, so no network is needed.
 - [`references/css.md`](references/css.md) — how stylesheets are ordered.
 - [`references/widgets.md`](references/widgets.md) — the basic widget
   library.
-- [`references/TECHREF-1.0.md`](references/TECHREF-1.0.md) — the reserved
-  names, what a URL names and
-  [query parms](references/TECHREF-1.0.md#query-parms), and the open items
-  that block 1.0.  Read it before designing around something the other
-  references do not mention.
+- [`references/names.md`](references/names.md) — every name Loadbare
+  owns, the constants, and the section defining each.  Check a name here
+  before designing around something the other references do not mention.

package/skills/loadbare-app/references/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/skills/loadbare-app/references/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/skills/loadbare-app/references/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/skills/loadbare-app/references/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` |