@loadbare/app 0.4.0 → 0.5.0

package/dist/tests/styles.test.js

@@ -9,6 +9,7 @@ import { mkdtemp, mkdir, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import { resolveLocations } from "../build/locations";
+import { cssFrom, scanAll } from "../build/origins";
 import { stylesSource } from "../build/styles";
 const CHROME = `<!doctype html><body><lb-hub><main></main></lb-hub></body>`;
 async function tree(files) {
@@ -23,12 +24,13 @@ async function tree(files) {
 describe("discovering CSS", () => {
     it("finds a .css file anywhere under src", async () => {
         const src = await tree({
-            "chrome.chrome.html": CHROME,
+            "chrome.html": CHROME,
             "widgets/app-box.css": ".app-box {}",
             "styles/00-reset.css": "* { margin: 0; }",
         });
         try {
-            const { cssFiles } = await resolveLocations({ src, out: `${src}/dist` });
+            const locations = await resolveLocations({ src, out: `${src}/dist` });
+            const cssFiles = cssFrom(await scanAll(locations, src, locations.importsFile));
             assert.equal(cssFiles.length, 2);
         }
         finally {
@@ -37,12 +39,13 @@ describe("discovering CSS", () => {
     });
     it("orders by filename, not by directory, so a global sorts first by naming itself 00-", async () => {
         const src = await tree({
-            "chrome.chrome.html": CHROME,
+            "chrome.html": CHROME,
             "widgets/app-box.css": ".app-box {}",
             "00-reset.css": "* { margin: 0; }",
         });
         try {
-            const { cssFiles } = await resolveLocations({ src, out: `${src}/dist` });
+            const locations = await resolveLocations({ src, out: `${src}/dist` });
+            const cssFiles = cssFrom(await scanAll(locations, src, locations.importsFile));
             assert.deepEqual(cssFiles.map((f) => path.basename(f)), ["00-reset.css", "app-box.css"]);
         }
         finally {

package/docs/reference/builder.md

@@ -0,0 +1,128 @@
+# 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                                            |
+| `*.hooks.ts`               | A page's hooks, 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 |
+| Any other tag-shaped `.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 `.hooks.ts` and `.queries.ts` a `.page.html` of the same base name.
+
+## 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 id="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 `.hooks.ts` or a `.queries.ts` file. Import `hub`
+from `pages.ts` — see [The Express Server](./server.md) for the rest of the
+wiring.

package/docs/reference/chrome.md

@@ -0,0 +1,75 @@
+# 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" />
+  </head>
+  <body>
+    <lb-hub>
+      <header><h1>Membership Roster</h1></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>
+        The page <span lb-cell="page"></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                    |
+| `<dialog lb-unknown-page>`                | A message when a URL matches no page        |
+| Custom elements                           | The chrome, decomposed into widget files    |
+| 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 it, `lb-cell="page"` shows the name of the page that was asked for.

package/docs/reference/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>

package/docs/reference/custom-elements.md

@@ -0,0 +1,327 @@
+# Custom Elements
+
+A widget is a custom element, written as a set of files sharing one tag
+name. It serves two purposes, and an application uses it for either or for
+both at once.
+
+| File             | Holds                            |
+|------------------|----------------------------------|
+| `<tag-name>.html` | The markup the tag expands into |
+| `<tag-name>.ts`   | The class the tag registers     |
+
+Write one of the two, or both, but write at least one. A tag with neither is
+a build error.
+
+Custom elements are the only mechanism Loadbare offers for either purpose.
+An application decomposes its HTML by defining a tag, and delivers behavior
+to the browser by registering one; the builder recognizes no other way to do
+either.
+
+Put the files anywhere under `src/`. The builder finds them by name, the
+same way it finds pages — see [The Builder](./builder.md).
+
+Loadbare uses light DOM throughout. A widget's markup is ordinary markup in
+the document, visible in view-source, reachable by `closest()` and by the
+application's stylesheets.
+
+## HTML
+
+An `.html` file named for a tag defines that tag. When the builder finds the
+tag in the chrome, in a page, or in another definition, it inserts the
+definition's content as children of the tag.  We call this process 
+'HTML expansion'. 
+
+A package listed in `imports.ts` loads first and an application's own
+definitions load after, so a tag defined in both resolves to the
+application's.
+
+### Parameters
+
+A definition takes parameters. Three namespaces share the attributes of a
+widget tag, and the prefix says which namespace an attribute is in:
+
+| Prefix      | Belongs to | Read                        |
+|-------------|------------|-----------------------------|
+| `exp-`      | Expansion  | By the builder, at build time |
+| `lb-`       | The hub    | By Loadbare, in the browser |
+| No prefix   | HTML       | By the browser, as HTML says |
+
+Pass a parameter by writing `exp-<name>` on the tag. Read it in the
+definition by writing `{{<name>}}`. The prefix marks the attribute as
+expansion's input and is not part of the parameter's name, so `exp-label`
+supplies `{{label}}`:
+
+```html
+<!-- definition: src/note-field.html -->
+<label>{{label}} <input readonly="{{readonly}}" /></label>
+```
+
+```html
+<!-- authored -->
+<note-field lb-cell="name" exp-label="Name"></note-field>
+```
+
+Write `class`, `title`, or any other unprefixed attribute on a widget
+freely. They are HTML's, and never collide with a definition's parameters.
+
+Write a placeholder as an entire attribute value or an entire text node.
+Nothing inside one is evaluated, and expansion has no data to branch on —
+see [Conditional rendering](./data-binding.md#conditional-rendering) for
+what to write instead of a branch.
+
+Name a parameter in lowercase. HTML lowercases attribute names before
+expansion sees them, so `exp-inputClass` arrives as `exp-inputclass` and
+could never fill `{{inputClass}}`. Write `{{input-class}}` instead; a
+definition declaring such a name is rejected when it loads.
+
+Leave a parameter unsupplied to drop what reads it. An attribute whose
+value is a placeholder is removed rather than shipped empty, which is how
+`readonly="{{readonly}}"` works as an ordinary boolean attribute. A
+placeholder in a text node resolves to nothing, and the whitespace around
+it survives.
+
+Every attribute stays on the tag after expansion, `exp-` ones included.
+
+Parameter values reach a definition through the DOM rather than through
+string substitution, so a value is never reparsed as markup and needs no
+escaping.
+
+### The slot
+
+`lb-slot` marks the one element in a definition whose children receive
+whatever the author wrote inside the tag:
+
+```html
+<!-- definition: src/note-card.html -->
+<article class="card"><div lb-slot></div></article>
+```
+
+```html
+<!-- authored -->
+<note-card>
+  <h3>Meeting notes</h3>
+  <p>Bring the roster.</p>
+</note-card>
+```
+
+```html
+<!-- ships -->
+<note-card>
+  <article class="card">
+    <div>
+      <h3>Meeting notes</h3>
+      <p>Bring the roster.</p>
+    </div>
+  </article>
+</note-card>
+```
+
+The tag stays and the definition becomes its children. `lb-slot` itself is
+gone from what ships, having done its job at build time.
+
+Give a definition at most one `lb-slot`. A definition with a slot and
+nothing written inside it leaves the slot empty.
+
+`lb-slot` is an attribute rather than an element because HTML's content
+model discards foreign elements inside `<select>` and `<table>`. A slot
+marker has to survive on an element the surrounding tag already permits.
+
+### Destinations
+
+`lb-template` names a destination in a definition. On an authored
+`<template lb-template="name">`, it names the destination that template
+fills:
+
+```html
+<!-- definition: src/ledger-table.html -->
+<table>
+  <caption>{{caption}}</caption>
+  <thead lb-template="head"></thead>
+  <tbody lb-slot></tbody>
+</table>
+```
+
+```html
+<!-- authored -->
+<ledger-table exp-caption="Ledger">
+  <template lb-template="head">
+    <tr><th>Date</th><th>Amount</th></tr>
+  </template>
+  <tbody>
+    <!-- row template -->
+  </tbody>
+</ledger-table>
+```
+
+Declare as many destinations as the definition needs, one per name. An
+author fills none, some, or all of them, and a destination nobody fills
+stays and is empty.
+
+Wrap authored content for a destination in a `<template>`, which exists only
+to survive the parser. A `<thead>` written directly inside `<ledger-table>`
+is not inside a `<table>`, so the tokenizer drops the tag before expansion
+sees it. A `<template>` survives anywhere and parses its contents as though
+already in place. What lands in the destination is the template's contents —
+an ordinary `<thead>` in view-source — not the template element.
+
+### Recursion
+
+A definition may use other widgets. Expansion repeats until nothing new
+appears, so a widget built out of other widgets needs nothing declared for
+it.
+
+Keep the definition graph acyclic. A cycle is a build error, reported as the
+path that closes it.
+
+Expansion runs over `<template>` contents wherever they occur, so a widget's
+row template ships already expanded, `{{placeholder}}` included.
+
+### What fails at build time
+
+Each of these is reported with the tag and file name, and nothing is
+shipped:
+
+- a tag in the `LB-*` namespace with no definition
+- a cycle in the definition graph
+- an `exp-` attribute the definition never declared
+- a `{{placeholder}}` spelled so that no `exp-` attribute could supply it
+- content written inside a tag whose definition has no `lb-slot`
+- more than one `lb-slot` in one definition
+- a `<template lb-template="name">` naming a destination the definition
+  does not have
+- two templates for the same destination
+
+An unfilled `{{placeholder}}` is not among these. That is presence
+propagation working as intended, indistinguishable from an author who left
+an optional parameter out.
+
+## Code
+
+A `.ts` file named for a tag registers that tag's class. A widget is an
+ordinary custom element — Loadbare imposes no base class — and it takes part
+in data binding through three contracts: it receives a value, it sends a
+request, and it accepts a set of rows.
+
+Import every attribute name from `@loadbare/app/constants`. Never write one
+as a string literal.
+
+| Constant         | Value      |
+|------------------|------------|
+| `ATTR_VALUE`     | `lb-value` |
+| `ATTR_CELL`      | `lb-cell`  |
+| `ATTR_QUERY`     | `lb-query` |
+| `ATTR_KEY`       | `lb-key`   |
+| `ATTR_GROUP`     | `lb-group` |
+| `ATTR_SORT`      | `lb-sort`  |
+| `ATTR_ACTION`    | `lb-action`|
+| `ATTR_ROW_COUNT` | `data-rows`|
+| `LB_EVENT_NAME`  | `lb-request` |
+
+### Receiving a value
+
+A bound cell lands on a widget as the `lb-value` attribute rather than as
+text — see [Data Binding](./data-binding.md#where-a-bound-value-lands).
+Observe it, and render the value however the widget renders things:
+
+```ts
+// src/visit-count.ts
+import { ATTR_VALUE } from "@loadbare/app/constants";
+
+class VisitCount extends HTMLElement {
+  static observedAttributes = [ATTR_VALUE];
+
+  attributeChangedCallback(_name: string, _old: string, value: string) {
+    this.textContent = `visited ${value} times`;
+  }
+}
+
+customElements.define("visit-count", VisitCount);
+```
+
+List `ATTR_VALUE` in `observedAttributes`, or `attributeChangedCallback`
+never fires. The browser calls it for an attribute already present when an
+element upgrades, not only for one that changes afterward, so a widget's
+first render and every later refresh go through the one callback. There is
+no separate hydration path to write.
+
+### Sending a request
+
+A widget that owns its own interaction — a `<select>`'s choice rather than a
+click — builds its own request and dispatches it as a bubbling
+`CustomEvent` named `LB_EVENT_NAME`, carrying one of the `HubRequest` shapes
+as its `detail`:
+
+```ts
+import { ATTR_CELL, ATTR_KEY, ATTR_QUERY, LB_EVENT_NAME } from "@loadbare/app/constants";
+import type { HubRequest } from "@loadbare/app/types";
+
+const detail: HubRequest = {
+  op: "cell-change",
+  query: this.closest(`[${ATTR_QUERY}]`)!.getAttribute(ATTR_QUERY)!,
+  key: this.closest(`[${ATTR_KEY}]`)!.getAttribute(ATTR_KEY)!,
+  cell: this.getAttribute(ATTR_CELL)!,
+  value: input.value,
+};
+this.dispatchEvent(new CustomEvent(LB_EVENT_NAME, { bubbles: true, detail }));
+```
+
+Find `query` and `key` by walking up with `closest()`, the same way the hub
+finds the binding for a native element. See
+[Data Binding](./data-binding.md#requests) for the request vocabulary and
+what each operation carries.
+
+Let the event bubble, so an ancestor widget can intercept and stop it before
+the hub sees it. A hand-written widget and a native element carrying
+`lb-action` produce the same event.
+
+### Accepting rows
+
+A query answering with many rows is delivered to whichever element carries
+an `acceptRows` method. It is a protocol, not a tag name — the hub tests for
+the method and never for the element:
+
+```ts
+import { applyRows } from "@loadbare/app/rows";
+import type { Projection, HubRowHost } from "@loadbare/app/types";
+
+class UpdateList extends HTMLElement implements HubRowHost {
+  acceptRows(result: Projection) {
+    applyRows(this, result);
+  }
+}
+```
+
+Call `applyRows(scope, result, place?)` rather than reimplementing rows.
+Every built-in list widget uses it, and it settles four things:
+
+| Concern     | What `applyRows` does                                   |
+|-------------|---------------------------------------------------------|
+| Cloning     | Clones the `<template lb-key="...">` in the widget      |
+| Matching    | Updates the row already showing that key, or clones one |
+| Reconciling | Removes the rows the response says are gone             |
+| Counting    | Stamps `data-rows` with the number of rows showing      |
+
+`rows` is the whole set, so it decides membership and order, and a key
+absent from it is removed. `patch` touches only the rows it names and leaves
+every other row's contents and position alone.
+
+Supply a `place` function to decide where a row goes — `(row, tuple,
+template) => void`, called with a fresh or reordered row. The default
+inserts immediately before the template, so rows accumulate in arrival
+order. A widget that groups or sorts supplies its own `place` instead of
+reimplementing matching and cloning around it; `lb-options.ts` and
+`lb-table.ts` in [`@loadbare/widgets`](./widgets.md) are two different
+`place` functions over the same `applyRows`.
+
+Style an empty list against `data-rows` rather than carrying an empty-state
+conditional in the widget — see
+[Conditional rendering](./data-binding.md#conditional-rendering).
+
+### Filling a scope by hand
+
+`@loadbare/app/rows` also exports `applyTuple(root, cells)`, the same
+tuple-landing operation a page host uses. Call it in a widget that builds
+its own rows or scopes rather than relying on `acceptRows`. It fills `root`
+itself when `root` carries a matching `lb-cell`, and every matching
+descendant.
+</content>