@loadbare/app 0.8.0 → 0.8.1

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

@@ -0,0 +1,134 @@
+# The Builder
+
+The application runs `loadbare-app-build`. The builder reads the application's
+source tree and writes the files the server serves.
+
+## Running the builder
+
+```
+loadbare-app-build [--src src] [--out dist] [--watch] [--minify]
+```
+
+| Option     | Effect                                               |
+|------------|------------------------------------------------------|
+| `--src`    | The tree to scan, default `src`                      |
+| `--out`    | Where output lands, default `dist`                   |
+| `--watch`  | Build once, then again on every change under `--src` |
+| `--minify` | Minify `client.js` and `app.css`                     |
+
+Run it from the application's own `package.json`:
+
+```json
+{
+  "scripts": {
+    "dev": "loadbare-app-build --watch & tsx server.ts"
+  }
+}
+```
+
+`--watch` watches every `.html`, `.ts`, and `.css` file under `--src`, and
+reports a failed build to the console without stopping. It runs no dev server
+and reloads no browser.
+
+`--minify` leaves `app.html` alone.
+
+## What the builder reads
+
+The builder classifies by name, not location.
+
+| Name                       | Role                                              |
+|----------------------------|---------------------------------------------------|
+| `chrome.html`              | The chrome — see [`chrome.html`](./chrome.md)     |
+| `*.page.html`              | A page                                            |
+| `*.requests.ts`               | A page's requests, matched by base name              |
+| `*.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>.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.
+
+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
+`--src` stays on the server side of the build, whatever it is called. Write
+`<tag>.ts` and the tag goes unregistered — the build says so, and names the
+file to rename.
+
+## Widgets from packages
+
+List a package in `imports.ts` to take widgets from it:
+
+```ts
+// src/imports.ts
+export default ["@acme/widgets"];
+```
+
+The builder scans one directory of that package the same way it scans `--src`,
+finding a widget by its filename. Nothing names a tag: `acme-widget.html` and
+`acme-widget.js` there define and register `<acme-widget>`.
+
+Which directory is the package's own to declare, in its `package.json`:
+
+```json
+{
+  "loadbare": { "widgets": "./dist" }
+}
+```
+
+A package that declares nothing has its whole installed directory scanned.
+That is what a package of hand-written widgets wants and it needs no field at
+all; a package that compiles wants the field, because its source and its
+compiled output both carry `acme-widget`, and two files claiming one tag in one
+origin is an error. Declaring the directory that ships settles which one the
+builder means, and leaves the rest of the package — the README, the docs, the
+tests — out of the question entirely.
+
+The path must be inside the package and must exist in it once installed;
+either failure names the package and stops the build.
+
+An application author writes nothing for this and installs the package as they
+would any other. The declaration is the package author's, made once.
+
+## Where the builder looks
+
+Definitions, scripts and stylesheets all come from the same ordered origins:
+
+| Order | Origin                                             |
+|-------|----------------------------------------------------|
+| 1     | `@loadbare/app` itself, which supplies `lb-hub`    |
+| 2     | Each package in `imports.ts`, in the order listed   |
+| 3     | The application's own `--src` tree                 |
+
+The first origin holds one tag. Every application has a hub whether or not it
+says so, so the builder supplies that one and nothing else; a widget comes
+from a package the application lists, including
+[`@loadbare/widgets`](./widgets.md).
+
+Two files claiming one tag within a single origin is an error, naming both.
+Across origins the later one wins, so the application overrides a package,
+and a package overrides `lb-hub`. Stylesheets follow the same order — see
+[CSS](./css.md).
+
+A tag with neither a script nor a definition in any origin is an error.
+
+## What the builder writes
+
+| File        | Contents                                            |
+|-------------|-----------------------------------------------------|
+| `app.html`  | The chrome, with every page inside a `<template>`   |
+| `client.js` | Every widget class the document uses, in one bundle |
+| `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
+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.
+
+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
+wiring.

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

@@ -0,0 +1,158 @@
+# chrome.html
+
+The chrome is the application's one HTML document. Banner, navigation,
+footer, dialogs — everything that is not a page lives in the chrome, written
+once.
+
+The builder finds the chrome by name: exactly one file called `chrome.html`,
+anywhere in the `src/` tree. Any directory will do.
+
+## A complete chrome
+
+Here is a minimal but fully complaint chrome for a typical app:
+
+```html
+<!-- src/chrome.html -->
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>Membership Roster</title>
+    <script src="/client.js" defer></script>
+    <link rel="stylesheet" href="/app.css" />
+    <noscript><style>body[hidden] { display: block; }</style></noscript>
+  </head>
+  <body hidden>
+    <lb-hub>
+      <header lb-row="lb-navigation">
+        <h1>Membership Roster</h1>
+        <h2 lb-cell="page-label"></h2>
+      </header>
+      <nav>
+        <a href="/" lb-nav-link>Home</a>
+        <a href="/members" lb-nav-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-hub>
+  </body>
+</html>
+```
+
+The chrome is plain HTML; nothing in it is generated or templated.
+
+## The parts of a chrome
+
+| Required                            | Description                               |
+|-------------------------------------|-------------------------------------------|
+| Exactly one `chrome.html` in `src/` | The one chrome file, found by name        |
+| 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 |
+
+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    |
+| `<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 
+
+Anything the user interacts with must be 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 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 `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.
+
+## Where the page is
+
+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:
+
+```html
+<header lb-row="lb-navigation">
+  <h1>Membership Roster</h1>
+  <h2 lb-cell="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 as the browser has it, such as `/members`        |
+
+The label is the nav's. The hub takes it from the first `lb-nav-link`
+anchor whose `href` names the current page, 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.
+
+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.
+
+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:
+
+```html
+<dialog lb-unknown-page lb-row="lb-navigation">
+  The URL <span lb-cell="page-uri"></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
+[The Basic Widget Library](./widgets.md#lb-unknown-page).
+
+## Preventing the first-load blink
+
+`client.js` loads with `defer`, so the browser can — and typically does —
+paint the document before the script has run. Without help, that means a
+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.
+
+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
+chrome being shown *before* `<main>` has real content, not from `<main>`
+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
+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
+never runs, and never races with the hub, on a normal visit.
+
+Both are optional. An app that doesn't mind the blink, or has no chrome
+complex enough for it to be noticeable, can leave `<body>` unhidden and skip
+the `<noscript>` block entirely.

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

@@ -0,0 +1,44 @@
+# CSS
+
+The builder concatenates every `.css` file it finds into one stylesheet,
+`<out>/app.css`. Nothing is scoped, renamed, or removed.
+
+Write ordinary CSS against ordinary markup. Loadbare uses light DOM, so
+every selector reaches every element, in the chrome and in a widget alike.
+
+Put stylesheets anywhere under `src/`. The builder finds them by extension
+and pairs them with nothing — a `.css` file is not a widget's, a page's, or
+the chrome's.
+
+## Order
+
+The bundle is assembled in partitions, one per origin:
+
+| Partition                        | Holds                                     |
+|----------------------------------|-------------------------------------------|
+| Each package in `imports.ts`     | Every `.css` file inside that package     |
+| The application's own `src` tree | Every `.css` file under `--src`           |
+
+Package partitions come first, in the order `imports.ts` first mentions each
+package. The application's own partition is always last, so its rules have
+the final say over any imported package's.
+
+A package's partition excludes that package's own nested `node_modules`.
+
+Within a partition, files sort by filename. The directory does not affect
+the order, and the full path only breaks a tie. Name a global stylesheet
+`00-reset.css`, or similar, to sort it to the front of its partition.
+
+## What ships
+
+The builder writes `app.css` only when it finds at least one stylesheet.
+Serve it at `/app.css` and link it from the chrome:
+
+```html
+<link rel="stylesheet" href="/app.css" />
+```
+
+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>