@loadbare/app 0.4.0 → 0.5.0

package/docs/hosting.md

@@ -1,218 +0,0 @@
-# Hosting a Loadbare App Application
-
-Everything here is written once for an application and then left alone. None
-of it is per-page knowledge — for that, see the [Programmer's
-Guide](./guide.md), which builds a page and stops at the point where the page
-has to be served.
-
-Loadbare App ships no HTTP server, no router and no data layer. The engine in
-`@loadbare/app/server` imports one thing — its own wire types — and never
-sees a request object. So hosting is an adapter you write once, and this
-document is that adapter.
-
-Status: runs, except where marked.
-
----
-
-## Register the page
-
-Status: partial. Nothing loads `pages/<name>.queries.ts` or
-`pages/<name>.hooks.ts` by name yet, so an application names its pages in a
-registry. `demo/pages.ts` is the demo's:
-
-```ts
-import { createHub } from "@loadbare/app/server";
-
-export const hub = createHub({
-  hello: { queries: helloQueries, hooks: helloHooks },
-});
-```
-
-`createHub` returns two functions, `dataForPage` and `runAction`. The pages
-are fixed at startup; the context is not, and arrives with each call.
-
-When the loader ships, this file disappears and the directory is the registry.
-
-## The shell
-
-The shell is the one document the server sends for every route and every user.
-It carries the chrome — whatever surrounds the page, such as a header and a
-nav — an empty `<main>`, and every page host in the application, each wrapped
-in a `<template>`:
-
-```html
-<lb-hub>
-  <header><h1>Loadbare App Demo</h1></header>
-  <nav>
-    <a href="/hello" lb-nav-link>Hello</a>
-    <a href="/counter" lb-nav-link>Counter</a>
-  </nav>
-  <main></main>
-</lb-hub>
-<template id="page-hello">…</template>
-<template id="page-counter">…</template>
-```
-
-`<lb-hub>` is the hub: a single custom element that sits above every page,
-outside `<main>`. It survives navigation, so it needs no id. It receives every
-request a widget sends, POSTs it, and applies the response.
-
-Because the shell carries no data, it is identical for every user and every
-route, which is what makes it cacheable indefinitely. Values arrive later, on
-the data channel, and land on the tree as attributes.
-
-Assembling it is a build step: read each page host, expand its widgets, wrap
-each in `<template id="page-<name>">`, and concatenate. `demo/shell.ts` does
-this at startup rather than at build time, which is a convenience of the demo
-and not the design.
-
-## Navigation
-
-Every page host already ships in the document, so navigation moves markup that
-is already there. Mark an anchor to have the hub intercept it:
-
-```html
-<a href="/entity" lb-nav-link>Entity</a>
-```
-
-The hub calls `history.pushState`, selects the host with
-`getElementById("page-" + name)`, fetches that page's data, then inserts and
-hydrates in one synchronous block. The browser does not paint mid-task, so
-there is no empty flash.
-
-Anchors without the attribute are left alone. There is no fetch on the host
-channel, no route table, and no in-flight state.
-
-The path-to-page rule is one segment. An empty path currently resolves to
-`counter`, which is demo leakage in `hub/lb-hub.ts` and should be
-configuration.
-
----
-
-## Serving it with Express
-
-The demo runs on Express, because Loadbare App has no opinion about which server you
-bring and the community has a settled answer. The demo splits the work along
-the line that matters:
-
-| file                   | whose it is                                     |
-| ---------------------- | ----------------------------------------------- |
-| `demo/lb-routes.ts` | Loadbare App's. Every application writes this same file. |
-| `demo/server.ts`       | the demo's. Its store, its bundle, its shell.   |
-
-### Two endpoints, and no third
-
-```
-GET  /lb/data?page=<name>   the page's whole query set
-POST /lb?page=<name>        one operation, then its refresh set
-```
-
-Both names are constants — `LB_DATA_ENDPOINT` and
-`LB_REQUEST_ENDPOINT`. The page rides on the query string rather than in
-the body, which is what lets the operation set stay closed.
-
-They mount as an ordinary router:
-
-```ts
-export function hubRoutes(hub: Hub, contextFor: ContextFor): Router {
-  const router = express.Router();
-
-  // Scoped here, not on the app: the routes that need a parsed body are the
-  // routes that say so.
-  router.use(express.json());
-
-  router.get(LB_DATA_ENDPOINT, async (req, res) => {
-    const page = String(req.query.page ?? "");
-    res.json(await hub.dataForPage(page, contextFor(req)));
-  });
-
-  router.post(LB_REQUEST_ENDPOINT, async (req, res) => {
-    const { name, query, key, cell, value } = req.body as HubRequest;
-    const page = String(req.query.page ?? "");
-    res.json(
-      await hub.runAction(
-        page,
-        name,
-        { query, key, cell, value },
-        contextFor(req),
-      ),
-    );
-  });
-
-  return router;
-}
-```
-
-Note what the POST handler does not do. It does not look up a function by a
-name from the wire, and it does not read a payload. It passes a declared name
-and the addressing coordinates to `runAction`, which refuses any name the page
-did not declare.
-
-### The context is injected, because it is yours
-
-`contextFor` is a parameter rather than something the router builds, because
-building it is the one part of this that is genuinely the application's:
-
-```ts
-export type ContextFor = (req: Request) => HubContext;
-```
-
-The demo's opens the same store every time. A real one opens it for the
-authenticated caller — which is the whole reason the engine takes a context
-per request rather than holding one for the life of the process:
-
-```ts
-function contextFor(req: Request): HubContext {
-  return { db: openDb(req.user) };
-}
-```
-
-### Ordering is yours, and Loadbare App asks for one thing
-
-Express keeps one ordered list of middleware and walks it top to bottom.
-Nothing about `app.use` makes authentication run first; it runs first because
-you registered it first. Loadbare App's only requirement is the obvious one: the
-context must be built per request, after whatever establishes identity, and
-before a Loadbare App route runs.
-
-```ts
-const app = express();
-
-app.use(session(...));
-app.use(authenticate);                     // sets req.user, or 401s
-app.use(hubRoutes(hub, contextFor));   // now req.user exists
-
-app.get("/client.js", serveBundle);
-app.get(/.*/, serveShell);                 // last, or it swallows everything
-app.use(errors);                           // four arguments, last of all
-```
-
-You can scope instead of sequence — `app.use("/lb", authenticate)` covers
-both endpoints, since `use` matches on prefix and they share one. Either way
-the decision is yours; Loadbare App never sees the request.
-
-### The demo's own routes
-
-Everything below the Loadbare App mount is this application's, and would differ in
-yours:
-
-```ts
-app.get(/.*/, async (_req, res) => {
-  res.type("html").send(await buildShell());
-});
-```
-
-Every remaining route gets the same shell. The demo rebuilds it per request
-only so that editing a page host shows up on reload; it is a build step
-wearing a route's clothes.
-
-### Three things that will bite you, none of them Loadbare App's
-
-- **The catch-all must be last.** It is a route like any other, and Express
-  takes the first match. Put it above the Loadbare App mount and it answers
-  `/lb/data` with HTML.
-- **Express 5 changed the wildcard.** A bare `"*"` is no longer a valid path;
-  use a regex or `"/*splat"`.
-- **Express 4 does not catch async rejections.** An `await` that throws inside
-  a handler hangs the request rather than reaching your error middleware.
-  Express 5 forwards it. The demo is on 5 and has no `try`/`catch` anywhere.

package/docs/latent-risks.md

@@ -1,20 +0,0 @@
-# Latent Risks
-
-Issues that a single developer iterating on one app is unlikely to hit by
-accident, but that are expensive to retrofit once real usage exposes them.
-Not being built speculatively — read this when the symptom below actually
-shows up, as a prompt to come back and decide the shape deliberately.
-
-## Staleness and concurrent writers
-
-Two tabs, or two users, updating the same projection at once. A solo
-developer testing in one browser will not produce this by accident, and
-retrofitting a version or conflict check onto every tuple after the fact
-touches every widget that writes.
-
-## Nesting
-
-Whether a tuple may contain a projection (master-detail, an expanding row).
-`theory.md` already flags this as possibly load-bearing if disallowed. Worth
-a decision-in-principle the first time a master-detail page is built, even
-before the mechanism is needed elsewhere.

package/widgets/index.ts

@@ -1,6 +0,0 @@
-import "./lb-input";
-import "./lb-select";
-import "./lb-list";
-import "./lb-options";
-import "./lb-table";
-import "./lb-picker";

package/widgets/lb-input.html

@@ -1 +0,0 @@
-<label>{{label}} <input readonly="{{readonly}}" /></label>

package/widgets/lb-input.ts

@@ -1,64 +0,0 @@
-/// <reference lib="dom" />
-
-import {
-  ATTR_CELL,
-  ATTR_KEY,
-  ATTR_QUERY,
-  ATTR_VALUE,
-  LB_EVENT_NAME,
-} from "../core/lb-constants";
-import type { HubRequest } from "../core/lb-types";
-
-/**
- * A leaf cell wrapping an <input>. The hub writes one attribute name for
- * every widget type, so the value lands in `lb-value` and the widget
- * forwards it to the control it owns.
- *
- * The other direction of the same cell: on change it sends `cell-change`,
- * addressed by the same lb-query/lb-key/lb-cell coordinates the value
- * arrived on. A `readonly` input never fires `change` from user input, so a
- * readonly cell sends nothing on its own.
- */
-class LbInput extends HTMLElement {
-  static observedAttributes = [ATTR_VALUE];
-
-  attributeChangedCallback(_name: string, _old: string, value: string) {
-    const input = this.querySelector("input");
-    if (!input) {
-      console.error(`lb-input: no <input> to receive the value`);
-      return;
-    }
-    input.value = value;
-  }
-
-  connectedCallback() {
-    this.addEventListener("change", () => {
-      const input = this.querySelector("input");
-      if (!input) {
-        console.error(`lb-input: change with no <input>, ignoring`);
-        return;
-      }
-      const query = this.closest(`[${ATTR_QUERY}]`)?.getAttribute(ATTR_QUERY);
-      const key = this.closest(`[${ATTR_KEY}]`)?.getAttribute(ATTR_KEY);
-      const cell = this.getAttribute(ATTR_CELL);
-      if (!query || !key || !cell) {
-        console.error(
-          `lb-input: change with no query/key/cell coordinates, ignoring`,
-        );
-        return;
-      }
-      const detail: HubRequest = {
-        op: "cell-change",
-        query,
-        key,
-        cell,
-        value: input.value,
-      };
-      this.dispatchEvent(
-        new CustomEvent(LB_EVENT_NAME, { bubbles: true, detail }),
-      );
-    });
-  }
-}
-
-customElements.define("lb-input", LbInput);

package/widgets/lb-list.html

@@ -1 +0,0 @@
-<div lb-slot></div>

package/widgets/lb-list.ts

@@ -1,21 +0,0 @@
-/// <reference lib="dom" />
-
-import type { Projection, HubRowHost } from "../core/lb-types";
-import { applyRows } from "../hub/lb-rows";
-
-/**
- * The plain repeater: whatever the page author wrote inside is repeated once
- * per tuple, in the order the server sent.
- *
- * It exists because a projection has to land on a widget, and because a
- * `<table>` cannot be one — a custom element written inside `<tbody>` is
- * discarded by the parser, so the widget goes around the table and the
- * template goes inside it, where the content model already allows it.
- */
-class LbList extends HTMLElement implements HubRowHost {
-  acceptRows(result: Projection) {
-    applyRows(this, result);
-  }
-}
-
-customElements.define("lb-list", LbList);

package/widgets/lb-options.html

@@ -1,4 +0,0 @@
-<label
-  >{{label}}
-  <select lb-slot></select
-></label>

package/widgets/lb-options.ts

@@ -1,88 +0,0 @@
-/// <reference lib="dom" />
-
-import {
-  ATTR_ACTION,
-  ATTR_GROUP,
-  ATTR_KEY,
-  LB_EVENT_NAME,
-} from "../core/lb-constants";
-import type {
-  Projection,
-  HubRequest,
-  HubRowHost,
-} from "../core/lb-types";
-import { applyRows, type Place } from "../hub/lb-rows";
-
-/**
- * A `<select>` whose choices come from a query, and the case that shows why
- * placement belongs to the widget rather than to the framework.
- *
- * The rows arrive flat and keyed. Nothing on the wire knows about
- * `<optgroup>`, and nothing needs to: a group is a column like any other, and
- * turning a repeated column value into an element is exactly the local
- * knowledge a widget has and the hub does not. A table wanting section
- * headings would read the same `lb-group` and build something else.
- *
- * The identity of a row is the value of the option, so `lb-key` supplies
- * both and the page declares it once.
- *
- * Exported because `lb-picker` is this widget with its row template
- * supplied by the definition instead of by the page. Nothing about the
- * behavior changes, so nothing about the behavior is written twice.
- */
-export class LbOptions extends HTMLElement implements HubRowHost {
-  acceptRows(result: Projection) {
-    applyRows(this, result, this.place);
-    // The identity of the row is the value of the option, so nothing on the
-    // page has to say so twice.
-    for (const option of this.querySelectorAll(`option[${ATTR_KEY}]`)) {
-      option.setAttribute("value", option.getAttribute(ATTR_KEY)!);
-    }
-    // A group is derived, so it goes when its last row does.
-    for (const group of this.querySelectorAll("optgroup")) {
-      if (!group.querySelector("option")) group.remove();
-    }
-  }
-
-  private place: Place = (row, tuple, template) => {
-    const select = this.querySelector("select")!;
-    const groupCell = template.getAttribute(ATTR_GROUP);
-    if (!groupCell) {
-      select.insertBefore(row, template);
-      return;
-    }
-    this.groupFor(select, template, tuple[groupCell] ?? "").append(row);
-  };
-
-  /** The group with this label, or a new one in front of the template. */
-  private groupFor(select: Element, template: Element, label: string): Element {
-    for (const group of select.querySelectorAll("optgroup")) {
-      if (group.label === label) return group;
-    }
-    const group = document.createElement("optgroup");
-    group.label = label;
-    select.insertBefore(group, template);
-    return group;
-  }
-
-  connectedCallback() {
-    this.addEventListener("change", () => {
-      const select = this.querySelector("select");
-      if (!select) {
-        console.error(`lb-options: change with no <select>, ignoring`);
-        return;
-      }
-      const name = this.getAttribute(ATTR_ACTION);
-      if (!name) {
-        console.error(`lb-options: no ${ATTR_ACTION}, nothing to send`);
-        return;
-      }
-      const detail: HubRequest = { op: "action", name, value: select.value };
-      this.dispatchEvent(
-        new CustomEvent(LB_EVENT_NAME, { bubbles: true, detail }),
-      );
-    });
-  }
-}
-
-customElements.define("lb-options", LbOptions);

package/widgets/lb-picker.html

@@ -1,7 +0,0 @@
-<label
-  >{{label}}
-  <select>
-    <template lb-key="{{key}}" lb-group="{{group}}">
-      <option lb-cell="{{cell}}"></option>
-    </template></select
-></label>

package/widgets/lb-picker.ts

@@ -1,27 +0,0 @@
-/// <reference lib="dom" />
-
-import { LbOptions } from "./lb-options";
-
-/**
- * The same `<select>` as `lb-options`, with the row template supplied by
- * the definition instead of by the page.
- *
- * A row template is markup, so writing it is the page author's job — until
- * every row is one option and the only thing that varies is which columns it
- * reads. Those are words, and words are parameters: `exp-key`, `exp-cell` and
- * `exp-group` fill the placeholders in the template the definition already
- * has, at build time, and the page writes one tag with no children.
- *
- * It is the same trade as anywhere else in expansion. A page author who wants
- * a second element in the row, or an option built from two columns, writes
- * `lb-options` and the template themselves. This one is for when they do
- * not.
- *
- * The behavior is inherited whole, because it is the same behavior: rows land
- * in groups, the key becomes the value, and a change sends the declared
- * action. A distinct class exists only because `customElements.define`
- * requires one constructor per name.
- */
-class LbPicker extends LbOptions {}
-
-customElements.define("lb-picker", LbPicker);

package/widgets/lb-select.html

@@ -1,4 +0,0 @@
-<label
-  >{{label}}
-  <select lb-slot></select
-></label>

package/widgets/lb-select.ts

@@ -1,55 +0,0 @@
-/// <reference lib="dom" />
-
-import {
-  ATTR_ACTION,
-  ATTR_VALUE,
-  LB_EVENT_NAME,
-} from "../core/lb-constants";
-import type { HubRequest } from "../core/lb-types";
-
-/**
- * A leaf cell wrapping a <select>. It receives its value like any other cell,
- * and on change it sends the action the page declared for it — the request
- * vocabulary and the addressing vocabulary running in both directions on one
- * widget.
- *
- * The choice is the interaction, so this is the case where an action carries
- * a value. The server still decides what that choice means.
- */
-class LbSelect extends HTMLElement {
-  static observedAttributes = [ATTR_VALUE];
-
-  attributeChangedCallback(_name: string, _old: string, value: string) {
-    const select = this.querySelector("select");
-    if (!select) {
-      console.error(`lb-select: no <select> to receive the value`);
-      return;
-    }
-    select.value = value;
-  }
-
-  connectedCallback() {
-    this.addEventListener("change", () => {
-      const select = this.querySelector("select");
-      if (!select) {
-        console.error(`lb-select: change with no <select>, ignoring`);
-        return;
-      }
-      const name = this.getAttribute(ATTR_ACTION);
-      if (!name) {
-        console.error(`lb-select: no ${ATTR_ACTION}, nothing to send`);
-        return;
-      }
-      const detail: HubRequest = {
-        op: "action",
-        name,
-        value: select.value,
-      };
-      this.dispatchEvent(
-        new CustomEvent(LB_EVENT_NAME, { bubbles: true, detail }),
-      );
-    });
-  }
-}
-
-customElements.define("lb-select", LbSelect);

package/widgets/lb-table.html

@@ -1,8 +0,0 @@
-<table>
-  <caption>
-    {{caption}}
-  </caption>
-  <thead lb-template="head"></thead>
-  <tbody lb-slot></tbody>
-  <tfoot lb-template="foot"></tfoot>
-</table>

package/widgets/lb-table.ts

@@ -1,126 +0,0 @@
-/// <reference lib="dom" />
-
-import {
-  ATTR_CELL,
-  ATTR_GROUP,
-  ATTR_KEY,
-  ATTR_SORT,
-} from "../core/lb-constants";
-import type { Projection, HubRowHost } from "../core/lb-types";
-import { applyRows, type Place } from "../hub/lb-rows";
-
-/**
- * A table that owns its own scaffolding, and the case that shows what a list
- * widget is for once the repeater exists.
- *
- * `lb-list` goes around a table the page author wrote. This one supplies
- * the table, and the page writes what only the page knows: the heading row
- * and the row template. That division is forced rather than chosen — a
- * `<thead>` written inside a custom element is not inside a table, so the
- * parser drops the tag and keeps the text. A `<template>` survives anywhere,
- * so the heading row arrives wrapped and expansion unwraps it into the
- * `lb-template` destination beside the slot.
- *
- * What it adds at run time is placement, and only placement. `lb-sort` names
- * the column rows are ordered by; `lb-group` names the column they are
- * sectioned by, and is the same attribute a grouped `<select>` reads, because
- * a table with section headings and an `<optgroup>` are asking the same thing
- * of the same data.
- *
- * The `foot` destination is the head's argument a second time and needs no
- * code here. A `<tfoot>` is a place on the page, not a row the hub delivers,
- * so what lands in it is an ordinary scope carrying its own `lb-query` — a
- * grand total is a second projection of the same table, and the hub resolves
- * it by name like any other. See demo/pages/ledger.html.
- */
-
-/**
- * The heading row of a section, carrying the value it stands for.
- *
- * The widget's own scaffolding, so it is HTML's namespace rather than
- * Loadbare App's: it is derived from rows the hub knows and is invisible to the hub
- * itself, exactly as the `<optgroup>` in `lb-options` is. Nothing
- * addresses it, so it carries no `lb-key` and no name from the vocabulary.
- */
-const GROUP_ROW = "data-group";
-
-class LbTable extends HTMLElement implements HubRowHost {
-  acceptRows(result: Projection) {
-    applyRows(this, result, this.place);
-    // A section is derived, so it goes when its last row does.
-    for (const heading of this.querySelectorAll(`tr[${GROUP_ROW}]`)) {
-      if (this.section(heading).rows.length === 0) heading.remove();
-    }
-  }
-
-  /**
-   * Group first, then sort within the group.
-   *
-   * Inserting a row before the first one that sorts after it keeps the
-   * section ordered, whatever else is in it — which is what lets a whole set
-   * and a single patched row take the same path.
-   */
-  private place: Place = (row, tuple, template) => {
-    const groupCell = template.getAttribute(ATTR_GROUP);
-    const sortCell = template.getAttribute(ATTR_SORT);
-    const heading = groupCell
-      ? this.headingFor(template, tuple[groupCell] ?? "")
-      : null;
-    const { rows, end } = this.section(heading);
-
-    const value = sortCell ? (tuple[sortCell] ?? "") : "";
-    const after = sortCell
-      ? rows.find((other) => other !== row && cellOf(other, sortCell) > value)
-      : undefined;
-    template.parentElement!.insertBefore(row, after ?? end);
-  };
-
-  /**
-   * The rows of one section, and the node it ends at.
-   *
-   * A section runs from its heading to the next heading, or to the template
-   * if there is none after it. Without grouping there is one section and it
-   * is the whole body — the heading row the page wrote is skipped along the
-   * way, because it carries no key and is therefore not a row.
-   */
-  private section(heading: Element | null): { rows: Element[]; end: Element } {
-    const template = this.querySelector("template")!;
-    const rows: Element[] = [];
-    let node = heading
-      ? heading.nextElementSibling
-      : template.parentElement!.firstElementChild;
-    while (node && node !== template && !node.hasAttribute(GROUP_ROW)) {
-      if (node.hasAttribute(ATTR_KEY)) rows.push(node);
-      node = node.nextElementSibling;
-    }
-    return { rows, end: node ?? template };
-  }
-
-  /** The section with this label, or a new one in front of the template. */
-  private headingFor(template: HTMLTemplateElement, label: string): Element {
-    const body = template.parentElement!;
-    for (const heading of body.querySelectorAll(`tr[${GROUP_ROW}]`)) {
-      if (heading.getAttribute(GROUP_ROW) === label) return heading;
-    }
-    const heading = document.createElement("tr");
-    heading.setAttribute(GROUP_ROW, label);
-    const cell = document.createElement("th");
-    cell.setAttribute("scope", "rowgroup");
-    // How wide the table is, from the row the page author wrote. Nothing
-    // else knows, and nothing had to be told twice.
-    cell.colSpan = template.content.firstElementChild?.childElementCount ?? 1;
-    cell.textContent = label;
-    heading.append(cell);
-    body.insertBefore(heading, template);
-    return heading;
-  }
-}
-
-/** What a live row is showing in one column. */
-function cellOf(row: Element, cell: string): string {
-  const selector = `[${ATTR_CELL}="${cell}"]`;
-  const el = row.matches(selector) ? row : row.querySelector(selector);
-  return el?.textContent ?? "";
-}
-
-customElements.define("lb-table", LbTable);