@loadbare/app 0.4.0

package/dist/widgets/lb-select.js

@@ -0,0 +1,43 @@
+/// <reference lib="dom" />
+import { ATTR_ACTION, ATTR_VALUE, LB_EVENT_NAME, } from "../core/lb-constants";
+/**
+ * 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, _old, value) {
+        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 = {
+                op: "action",
+                name,
+                value: select.value,
+            };
+            this.dispatchEvent(new CustomEvent(LB_EVENT_NAME, { bubbles: true, detail }));
+        });
+    }
+}
+customElements.define("lb-select", LbSelect);

package/dist/widgets/lb-table.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=lb-table.d.ts.map

package/dist/widgets/lb-table.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lb-table.d.ts","sourceRoot":"","sources":["../../widgets/lb-table.ts"],"names":[],"mappings":""}

package/dist/widgets/lb-table.js

@@ -0,0 +1,113 @@
+/// <reference lib="dom" />
+import { ATTR_CELL, ATTR_GROUP, ATTR_KEY, ATTR_SORT, } from "../core/lb-constants";
+import { applyRows } 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 {
+    acceptRows(result) {
+        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.
+     */
+    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.
+     */
+    section(heading) {
+        const template = this.querySelector("template");
+        const rows = [];
+        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. */
+    headingFor(template, label) {
+        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, cell) {
+    const selector = `[${ATTR_CELL}="${cell}"]`;
+    const el = row.matches(selector) ? row : row.querySelector(selector);
+    return el?.textContent ?? "";
+}
+customElements.define("lb-table", LbTable);

package/docs/application-chrome.md

@@ -0,0 +1,36 @@
+# Application Chrome
+
+The application Chrome - banner, nav, main and footer, is static HTML.
+
+It is found by name, not by location: it can be placed anywhere in the tree
+the builder scans, as any file ending `.chrome.html` — there must be exactly
+one. By convention we name it `src/chrome.chrome.html`.
+
+In our docs we consider chrome to be invariant across pages. This is
+not a strict technical requirement, as loadbare can update anything,
+but we do not provide examples or tests of dynamic chrome.
+
+The minimum requirements for the chrome file are:
+
+- the `<lb-hub>` element as first element below `<body>`
+- an empty `<main></main>` element. Its content is populated by
+  the hub from the application pages.
+
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title><!-- content goes here --></title>
+    <script src="/client.js" defer></script>
+  </head>
+  <body>
+    <lb-hub>
+      <header><!-- content goes here --></header>
+      <nav><!-- content goes here --></nav>
+      <main></main>
+      <footer><!-- content goes here --></footer>
+    </lb-hub>
+  </body>
+</html>
+```

package/docs/building-html-pages.md

@@ -0,0 +1,130 @@
+# Building HTML Pages
+
+A page is authored as one HTML file. It may contain widget tags. Expansion
+turns each one that has a definition into the tree that definition stands
+for. Expansion runs at build time, before there is a request, and before
+there is any data.
+
+`LB-*` is the framework's reserved namespace — Loadbare App's own widgets, and
+the convention its docs use. An application's own widgets should use their
+own prefix instead (`app-nav`, not `lb-nav`); a tag outside the `LB-*`
+namespace expands exactly the same way when it has a definition, but is not
+required to have one — with none, it is assumed to be a plain custom element,
+registered by script alone (see build/elements.ts).
+
+## Definitions
+
+A definition is one HTML file per tag. The file name gives the tag:
+`lb-options.html` defines `LB-OPTIONS`; `app-nav.html` defines `APP-NAV`.
+
+Loadbare App's own widgets live in this package's own `widgets/`, read by
+`loadDefinitions(dirs)`, which takes a list of directories in order — a later
+one overrides an earlier one for the same tag name. An application's own
+definitions are not confined to a directory at all: they are found by
+filename anywhere in its source tree (see `docs/getting-started.md`) and
+overlaid on the built-in set with `addDefinitions`, the same override an
+application directory would give a built-in widget.
+
+The full set of definitions is checked for a cycle in which definitions
+reference each other by tag, and throws if one exists.
+
+## Expanding a page
+
+`expand(source, defs)` walks the authored tree and replaces every widget tag
+that has a matching entry in `defs` with the tree that entry produces. A tag
+in the `LB-*` namespace is required to have one — an unresolved tag there
+throws. Outside that namespace, a tag with no definition is left exactly as
+authored.
+
+A definition may itself use other widget tags. Expansion resolves those the
+same way, as deep as the definitions go.
+
+## Parameters
+
+A definition may declare a placeholder, written `{{name}}`, as the entire
+value of an attribute or the entire text of a text node.
+
+An authored tag supplies a placeholder's value with an attribute named
+`exp-<name>`. `exp-label="Member:"` supplies `{{label}}`.
+
+HTML lowercases attribute names, so a placeholder name may not contain an
+uppercase letter — `loadDefinitions` rejects a definition that declares one.
+
+Supplying `exp-x` on a tag whose definition has no `{{x}}` is an error.
+
+If a placeholder has no value supplied, the attribute it fills is dropped
+rather than emitted empty; a text placeholder becomes empty text.
+
+## The slot
+
+A definition may mark one element `lb-slot`. The authored tag's child nodes
+move into that element, replacing it. A definition with no `lb-slot` rejects
+any non-whitespace content written inside the authored tag.
+
+## Named template destinations
+
+A definition may mark more than one element `lb-template="<name>"`, each a
+destination. An authored tag supplies content for a destination by writing a
+`<template lb-template="<name>">` among its children; expansion moves the
+template's content into the destination and discards the wrapping `<template>`
+tag. A destination with no matching template is left as the definition wrote
+it.
+
+Two templates naming the same destination, or a template naming a destination
+the definition does not declare, is an error.
+
+A definition applies named destinations before the slot: content addressed to
+a destination by name does not also count as slot content.
+
+### Example
+
+`widgets/lb-table.html`:
+
+```html
+<table>
+  <caption>
+    {{caption}}
+  </caption>
+  <thead lb-template="head"></thead>
+  <tbody lb-slot></tbody>
+  <tfoot lb-template="foot"></tfoot>
+</table>
+```
+
+Authored in a page:
+
+```html
+<lb-table exp-caption="Everyone, by team">
+  <template lb-template="head">
+    <tr>
+      <th>Name</th>
+      <th>Role</th>
+    </tr>
+  </template>
+  <tr>
+    <td>Row content for the slot</td>
+  </tr>
+</lb-table>
+```
+
+The `head` template's content becomes the `<thead>`'s children. The `<tr>`
+written outside any `<template>` is slot content and becomes a child of
+`<tbody>`. There is no template addressed to `foot`, so the `<tfoot>` ships
+empty, exactly as the definition wrote it.
+
+## Template content elsewhere on the page
+
+Expansion also descends into the content of any `<template>` on the page,
+including one with no `lb-template` attribute — for example a row template
+consumed by a widget at runtime rather than by expansion. A placeholder or
+widget tag written inside such a template is still expanded.
+
+## Output
+
+`expand(source, defs)` returns HTML text. Substitution is applied to a parsed
+tree through DOM APIs — `setAttribute`, text node values — never to a string,
+so a value supplied through `exp-*` cannot be reparsed as markup.
+
+What `expand` returns is what ships. No value from a request or a database is
+added after expansion; those values land on the already-expanded tree later,
+as attributes.

package/docs/getting-started.md

@@ -0,0 +1,120 @@
+# Getting Started
+
+We begin with the smallest working application. This app does not even
+have any pages, but it will load without error, and is inspectable.
+
+## The chrome file
+
+Write a file ending `.chrome.html` — say, `src/chrome.chrome.html`. There
+must be exactly one of these anywhere under `src/`; the builder finds it by
+that name, not by which directory it's in.
+
+At minimum, the chrome must contain:
+
+- a link to the `client.js` script
+- The `<lb-hub>` element just inside `<body>`
+- an empty `<main>` inside `<lb-hub>`
+
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>Getting Started</title>
+    <script src="/client.js" defer></script>
+  </head>
+  <body>
+    <lb-hub>
+      <main></main>
+    </lb-hub>
+  </body>
+</html>
+```
+
+The client script is generated by the builder, and contains some core code
+and the Javascript
+for all custom elements in the app. Since we have only `lb-hub`, the build
+will produce a `client.js` containing the core code and only the class for `lb-hub`.
+
+## Serving It
+
+Create `server.js` as an express server:
+
+```js
+import express from "express";
+import { readFileSync } from "node:fs";
+
+const app = express();
+
+app.get("/", (_req, res) =>
+  res.type("html").send(readFileSync("dist/app.html", "utf-8")),
+);
+app.use("/client.js", express.static("dist/client.js"));
+
+app.listen(8787);
+```
+
+`dist/app.html` is read on every request rather than once at startup, so a
+rebuild in watch mode is visible without restarting the server.
+
+## The dev Script
+
+Add to package.json:
+
+```json
+{
+  "scripts": {
+    "dev": "loadbare-app-build --watch & node server.js"
+  }
+}
+```
+
+`loadbare-app-build` scans `src/` by default; `--src` overrides which tree. It
+takes no other location flags — everything under that tree is found by what
+a file is named, not by which directory holds it:
+
+- `*.chrome.html` — the one chrome file
+- `*.page.html` — a page, named for the part before the suffix
+- any other `.html` — a widget definition, named for its own filename
+- a `.ts` file shaped like a custom element tag (e.g. `lb-nav.ts`,
+  `app-box.ts`) — a widget's script
+- `*.hooks.ts` / `*.queries.ts` — a page's server half, paired with a
+  `*.page.html` by sharing its basename
+- `.css` — a stylesheet, concatenated with every other one found
+- `elements.ts` — third-party custom elements: a default export mapping tag
+  to import specifier, e.g. `{ "acme-date-picker": "@acme/date-picker" }`
+
+A widget's markup and script don't need to sit in the same place, or in any
+particular directory at all — `src/pages/home.page.html` and
+`src/lb-nav.html` are both found the same way `src/widgets/lb-nav.html`
+would be.
+
+## CSS
+
+Every `.css` file anywhere under `src/` is concatenated into `dist/app.css`,
+in one order: sorted by filename, not by directory. Put a stylesheet next to
+the markup it styles, wherever that is convenient — a global one sorts to
+the front on its own by naming itself `00-reset.css` or `aa-globals.css`,
+regardless of which directory it lives in. Nothing here knows about widgets
+or pages; it is exactly the concatenation of what was authored, with no
+scoping and no plain `style="..."` attribute anywhere the framework writes
+markup, since that is inline code the same way `<script>` is, and Loadbare App
+targets a CSP that refuses both.
+
+The chrome links it like any other asset — `<link rel="stylesheet"
+href="/app.css" />` — the builder never writes into the chrome itself.
+
+This script runs the Loadbare App builder in watch mode, alongside the server.
+With `--watch`, every `.html`, `.ts` and `.css` file under `src/` is watched —
+a page, a widget's markup, a widget's class, a stylesheet, and `elements.ts`
+all feed the build.
+
+Loadbare App does not reload the browser on a rebuild. Watch mode keeps
+`dist/app.html`, `dist/client.js` and `dist/app.css` current on disk; the
+browser picks up a change on the next manual refresh.
+
+## Run it
+
+Try `npm run dev`, and navigate the browser to localhost:8787, you
+should see an empty page, with a console message, and the view source
+option should show exactly our page.