@loadbare/app 0.9.0 → 0.11.0

package/skills/loadbare-app/references/builder.md

@@ -122,11 +122,17 @@ A tag with neither a script nor a definition in any origin is an error.
 | `app.css`   | Every stylesheet, concatenated                      |
 | `pages.ts`  | The `hub` the server passes to `hubRoutes`          |
 
-The builder expands the chrome and every page against the available widget
+The builder expands the chrome and every page against the available
 definitions — see [Custom Elements](./custom-elements.md#html) for the
 substitution rules — wraps each expanded page in
-`<template lb-page="<name>">`, and splices them into the chrome's `<body>`. It formats the result with
-Prettier when the application has it installed.
+`<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.
+
+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 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

@@ -9,7 +9,7 @@ anywhere in the `src/` tree. Any directory will do.
 
 ## A complete chrome
 
-Here is a minimal but fully complaint chrome for a typical app:
+Here is a minimal but complete chrome for a typical app:
 
 ```html
 <!-- src/chrome.html -->
@@ -24,18 +24,18 @@ Here is a minimal but fully complaint chrome for a typical app:
   </head>
   <body hidden>
     <lb-hub>
-      <header lb-row="lb-navigation">
+      <header lb-query="lb-url">
         <h1>Membership Roster</h1>
-        <h2 lb-cell="page-label"></h2>
+        <h2 lb-column="lb-page-label"></h2>
       </header>
       <nav>
-        <a href="/" lb-nav-link>Home</a>
-        <a href="/members" lb-nav-link>Members</a>
+        <a href="/" lb-url-link>Home</a>
+        <a href="/members" lb-url-link>Members</a>
         <a href="https://example.org/">Our website</a>
       </nav>
       <main></main>
-      <dialog lb-unknown-page lb-row="lb-navigation">
-        The URL <span lb-cell="page-uri"></span> is not in this app.
+      <dialog lb-url-unknown lb-query="lb-url">
+        The URL <span lb-column="lb-path"></span> is not in this app.
       </dialog>
     </lb-hub>
   </body>
@@ -52,81 +52,133 @@ The chrome is plain HTML; nothing in it is generated or templated.
 | A complete HTML document            | Doctype, `<html>`, `<head>`, `<body>`     |
 | `<lb-hub>` inside `<body>`          | The application's live element            |
 | An empty `<main>` inside `<lb-hub>` | Holds the current page                    |
-| `<script src="/client.js" defer>`   | Defines `<lb-hub>` and every other widget |
+| `<script src="/client.js" defer>`   | Defines `<lb-hub>` and every other custom element |
 
 Everything else is optional:
 
 | Optional                                  | Description                                 |
 |-------------------------------------------|---------------------------------------------|
 | `<link rel="stylesheet" href="/app.css">` | The bundled stylesheet                      |
-| `<a lb-nav-link>`                         | Navigation between pages                    |
-| `lb-row="lb-navigation"`                | Where the page is — see below               |
-| `<dialog lb-unknown-page>`                | A message when a URL matches no page        |
-| Custom elements                           | The chrome, decomposed into widget files    |
+| `<a lb-url-link>`                         | A link between pages                        |
+| `lb-query="lb-url"`                       | Where the page is — see below               |
+| `<dialog lb-url-unknown>`                 | A message when a URL matches no page        |
+| Custom elements                           | The chrome, decomposed into element files   |
 | `<body hidden>` + a `<noscript>` fallback | Avoids a first-load blink — see below       |
 | Any other HTML                            | Header, footer, skip links, meta tags, etc. |
 
-## Rules for writing chrome 
+## Rules for writing chrome
 
-Anything the user interacts with must be inside `<lb-hub>`. The hub normally
+Put everything the user interacts with inside `<lb-hub>`. The hub normally
 sits directly inside `<body>`, with banner, nav, footer and `<main>` inside
 it, so Loadbare can act on all of them.
 
-A navigation anchor's `href` is a path, and the path names a page:
-`/members` shows `members.page.html`. A query string on it is kept, so
-`/members?team=Engines` opens the page narrowed; see
-[Query parms](./data-binding.md#query-parms). A bare `/` resolves to `index`, so the
-landing page is the one named `index.page.html`. An anchor without
-`lb-nav-link` is left alone and behaves like any other link.
+The chrome's `<title>` is the document title until the first page shows.
+From then on the hub sets the document title to the page's label; see
+[The URL](#the-url).
 
-The `lb-unknown-page` attribute, if used, must appear on a `<dialog>` inside
-`<lb-hub>`; the builder rejects it anywhere else. The hub opens it when a
-path names no page. What it says is up to the chrome:
-the dialog is a subtree like any other, and it displays where the page is by
-naming the hub's own query, described next.
+Put `lb-url-unknown` on a `<dialog>` inside `<lb-hub>`; the builder rejects
+it anywhere else.
 
-## Where the page is
+## The URL
 
-On every navigation the hub lands a query of its own, `lb-navigation`, on
-any subtree inside the hub that names it. It arrives the way a server's
-row arrives — `lb-row` on the subtree, `lb-cell` on each element that
-shows a value — so a chrome displays the current page with no code at all:
+The hub serves one query of its own, `lb-url`, of kind `row`, keyed by
+`lb-path`. It lands on every element inside the hub that names it, the way a
+server's row lands, so a chrome shows where the page is with no code:
 
 ```html
-<header lb-row="lb-navigation">
+<header lb-query="lb-url">
   <h1>Membership Roster</h1>
-  <h2 lb-cell="page-label"></h2>
+  <h2 lb-column="lb-page-label"></h2>
 </header>
 ```
 
-| Cell         | Holds                                                     |
-|--------------|-----------------------------------------------------------|
-| `page-label` | The text of the `lb-nav-link` anchor for the path, or empty if none |
-| `page-uri`   | The path and query string as the browser has them, such as `/members?team=Engines` |
+| Column            | Holds                                                   |
+|-------------------|---------------------------------------------------------|
+| `lb-path`         | The path, such as `/members`. The row's key             |
+| `lb-page-label`   | The page's title, or its stub when it has none          |
+| `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 label is the nav's. The hub takes it from the first `lb-nav-link`
-anchor whose path names the current page, whatever its query string, so a click, a reload and the
-back button all land the same text, and a path no anchor names lands an
-empty label. A chrome that shows the label somewhere fixed should expect
-that case for a page reachable only by URL.
+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
+sets the document title to `lb-page-label` whenever it is not null, so the
+tab and the browser history show the page.
 
-The `lb-` prefix on the query name is what keeps it out of the server's
-namespace: no server answers a query so named. It is landed only where a
-subtree names it, so a chrome that displays no navigation is not warned
-about a query with no scope.
+`lb-url` is the one query a page may use that the server does not declare. A
+page names it the same way, anywhere inside the hub.
 
-The same row is what an unknown-page dialog has to work with. It lands
-before the page host is looked up, so a miss has it too. Name the query on
-the dialog and show whichever cell fits:
+### Links
+
+Write `lb-url-link` on an `<a>` to move between pages:
+
+```html
+<nav>
+  <a href="/" lb-url-link>Home</a>
+  <a href="/members?team=Engines" lb-url-link>Engines</a>
+</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.
+
+### Query parms
+
+A query parm is a column of `lb-url`. A control inside `lb-query="lb-url"`
+that sends `lb-row-update` writes its value into the query string:
+
+```html
+<div lb-query="lb-url">
+  <select lb-column="team" lb-request="lb-row-update">
+    <option value="">Every team</option>
+    <option value="Engines">Engines</option>
+  </select>
+</div>
+```
+
+On `change`, the hub sets that parm and keeps every other, and takes the
+parm out when the value is empty. It replaces the current history entry, and
+pushes one instead when the element carrying `lb-request` also carries
+`lb-url-push`:
+
+```html
+<input lb-column="q" lb-request="lb-row-update" lb-url-push />
+```
+
+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.
+
+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.
+
+The hub sends the query parms with every round trip, and the server hands
+them to `contextFor`; see [the Express server](./server.md#database-layer).
+A handler moves the URL by returning `url()`, when only the server knows the
+new value; see [page files](./page-files.md#moving-the-url).
+
+### An unknown page
+
+A path that names no page shows the unknown-page dialog. Write it in the
+chrome as a `<dialog>` carrying `lb-url-unknown`, and name `lb-url` on it to
+show the path:
 
 ```html
-<dialog lb-unknown-page lb-row="lb-navigation">
-  The URL <span lb-cell="page-uri"></span> is not in this app.
+<dialog lb-url-unknown lb-query="lb-url">
+  The URL <span lb-column="lb-path"></span> is not in this app.
 </dialog>
 ```
 
-`@loadbare/widgets` ships this dialog as a widget, `<lb-unknown-page>`, for a
-chrome that would rather write one tag — see
+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.
+
+`@loadbare/widgets` ships this dialog as `<lb-unknown-page>`, for a chrome
+that would rather write one tag; see
 [The Basic Widget Library](./widgets.md#lb-unknown-page).
 
 ## Preventing the first-load blink
@@ -137,10 +189,9 @@ visible flash: the chrome appears first, then `<main>`'s real content pops in
 a moment later and shifts everything around it.
 
 `<body hidden>` avoids this by hiding the whole document, not just `<main>`,
-until the hub has something to show. `<lb-hub>` un-hides `<body>` itself the
-first time `navigate()` finishes, so the chrome and the first page's content
-always appear together, already in their final layout — there is no
-intermediate state to flash.
+until the hub has something to show. `<lb-hub>` un-hides `<body>` itself
+once it has put the first page in `<main>`, so the chrome and the first
+page's markup appear together, already in their final layout.
 
 Hiding `<main>` alone doesn't work: an empty `<main>` already renders at zero
 height, so hiding it changes nothing visible. The pop-in comes from the