@loadbare/app 0.4.0 → 0.5.1

package/docs/reference/data-binding.md

@@ -0,0 +1,240 @@
+# Data Binding
+
+A page binds its elements to server data with four attributes, and asks the
+server to change that data with four more. The page writes all eight into
+its HTML; the server declares which queries it answers and which operations
+it permits, and refuses anything it has not declared.
+
+## A page that binds data
+
+Here is a page that binds a scalar, a list, and three requests:
+
+```html
+<!-- src/pages/members.page.html -->
+<h1>Members</h1>
+
+<p lb-query="dues">Dues collected this year: <span lb-cell="total"></span></p>
+
+<form lb-insert lb-query="roster">
+  <input lb-cell="name" placeholder="Name" />
+  <button type="submit">Add member</button>
+</form>
+
+<lb-list lb-query="roster">
+  <ul>
+    <template lb-key="id">
+      <li>
+        <lb-input lb-cell="name"></lb-input>
+        <button lb-delete>Remove</button>
+      </li>
+    </template>
+  </ul>
+</lb-list>
+```
+
+The queries named here — `dues` and `roster` — and the operations the page
+asks for are declared on the server; see [page files](./page-files.md).
+
+## Binding
+
+| Attribute  | Names                                                    |
+|------------|----------------------------------------------------------|
+| `lb-query` | The query a subtree displays                             |
+| `lb-key`   | The cell that identifies a row, and a live row's own key |
+| `lb-cell`  | The cell an element displays                             |
+| `lb-value` | Where a widget receives its value                        |
+
+A binding is scoped by ancestry. An element binds to the query on its
+nearest ancestor carrying `lb-query`, and to the row on its nearest ancestor
+carrying `lb-key`. Nothing else establishes scope: an element outside every
+`lb-query` is bound to nothing and displays nothing.
+
+Bind an element to a cell by putting `lb-cell` on the element that shows the
+value. The scope's own root counts as a cell if it carries one, which is how
+an `<option>` — whose content model is text — displays the value it is.
+
+Name the same query on more than one subtree to display it in more than one
+place. Every subtree gets the result.
+
+`lb-key` holds one name in two positions. On a row template it names the
+cell that identifies a row; on a row that is showing, it carries that row's
+key value. A template is never a row, so the two never collide.
+
+### Where a bound value lands
+
+A value lands on a bound element one of two ways.
+
+| Element          | Receives the value as    |
+|------------------|--------------------------|
+| A native element | Its `textContent`        |
+| A custom element | Its `lb-value` attribute |
+
+A native element has no behavior of its own, so its value is its text. A
+widget owns whatever control it wraps, so it is handed the value and renders
+it itself — see [Custom Elements](./custom-elements.md#code) for
+observing `lb-value`.
+
+Nothing an application writes ever sets `lb-value`. It is written by
+Loadbare and read by the widget it is written on.
+
+### Rows
+
+A query that answers with many rows is delivered to a list widget, which
+clones its row template once per row and binds each clone to one row. A
+native element has one destination for a value and cannot acquire children,
+so a query that answers with rows must be bound to a widget that accepts
+them.
+
+Bind the widget to the query with `lb-query`, and name the key cell on the
+`<template>` inside it with `lb-key`. See
+[The Basic Widget Library](./widgets.md) for the widgets that accept
+rows, and for `lb-group` and `lb-sort`, which a list widget reads to decide
+where a row goes.
+
+## Requests
+
+Four attributes turn an interaction into a request:
+
+| Written                   | Asks for         | Carries                      |
+|---------------------------|------------------|------------------------------|
+| `lb-action="name"`        | The named action | `name`, and what is in scope |
+| `lb-delete`               | `tupleDelete`    | `query`, `key`               |
+| `lb-insert` on a `<form>` | `tupleInsert`    | `query`, `values`            |
+| `lb-update` on a `<form>` | `tupleUpdate`    | `query`, `key`, `values`     |
+
+The shipped `<lb-input>` widget asks for a fifth, `cellChange`, carrying
+`query`, `key`, `cell`, and `value`. It sends one when the page applies
+`data-fire-on-change` to it, and stays quiet otherwise — an input inside an
+`lb-insert` or `lb-update` form is read again by the form on submit, so a
+widget that sent on its own would write the same edit twice.
+
+Declare every one of these on the server. A name the page has not declared,
+and an operation a query does not permit, are refused; see
+[hooks, actions, CRUD](./page-files.md#hooks-actions-crud).
+
+### Actions
+
+Write `lb-action` on a button to ask the server to do something that is not
+one of the four CRUD operations:
+
+```html
+<button lb-action="mailRoster">Mail the roster</button>
+```
+
+An action carries whatever binding is in scope at the element — `query`,
+`key`, `cell` — and nothing else. There is no argument list. A button
+carries no value, so the server computes the whole of the new state and the
+page displays only what came back.
+
+Write `lb-action` on a widget to have the widget decide what performing the
+action means. Loadbare turns a click into a request for a native element
+only, and leaves a widget to send its own — a `<select>` performs its action
+on change, not on click.
+
+### Deleting a row
+
+```html
+<button lb-delete>Remove</button>
+```
+
+`lb-delete` needs no name. The row's `lb-query` and `lb-key` are already in
+scope, and they are all the server needs to know which row is meant and
+whether the query permits deleting it.
+
+Write `lb-delete` on a native element, the same as `lb-action`. A widget
+sends its own request.
+
+### Forms
+
+`lb-insert` and `lb-update` both gather every `lb-cell` inside the form into
+one values map, read from the control each cell is or wraps. They differ in
+one thing: `lb-update` also carries the key of the row it is inside, and
+`lb-insert` carries none, because there is no row yet.
+
+Put an `lb-update` form inside the row it edits, so it has that row's key
+from the same ancestor a delete button reads:
+
+```html
+<template lb-key="id">
+  <li>
+    <form lb-update>
+      <input lb-cell="name" />
+      <button type="submit">Save</button>
+    </form>
+  </li>
+</template>
+```
+
+Give every `lb-cell` in a form a control to read. A cell that is neither an
+`<input>`, `<select>`, or `<textarea>` nor wraps one is left out of the
+values map.
+
+## Conditional rendering
+
+Loadbare ships static HTML and hydrates elements that are already in the
+document. There is no `if`, and none is needed: write every possibility into
+the page, and control which of them is showing.
+
+Use the standard `hidden` attribute, or CSS, and set it from a value the
+server sent. A widget that receives a value in `lb-value` is the natural
+place to do it — it is handed the current state and decides what to show:
+
+```ts
+for (const step of steps) step.hidden = step.dataset.step !== value;
+```
+
+Ship the case that is showing on arrival unhidden, and hide the rest in the
+HTML.
+
+### An empty list
+
+A list widget stamps itself with `data-rows`, the number of rows it is
+showing. It is the one conditional a page cannot be sent, because the server
+answers with rows and says nothing about how many survived. It makes an
+empty list a stylesheet rule rather than code in every list widget:
+
+```html
+<lb-list lb-query="roster">
+  <ul>
+    <template lb-key="id">
+      <li lb-cell="name"></li>
+    </template>
+  </ul>
+  <p class="roster-empty">No members yet.</p>
+</lb-list>
+```
+
+```css
+.roster-empty {
+  display: none;
+}
+lb-list[data-rows="0"] .roster-empty {
+  display: revert;
+}
+```
+
+## Request state
+
+Loadbare stamps two attributes on the element a request came from — the
+button, the form, or the widget itself:
+
+| Attribute         | Means                                     |
+|-------------------|-------------------------------------------|
+| `data-lb-pending` | The request is in flight                  |
+| `data-lb-error`   | The last request from this element failed |
+
+`data-lb-pending` is set when the request goes out and removed when it
+settles. `data-lb-error` is set on a failed response, a network failure, or
+a timeout alike, and cleared when that element sends its next request.
+
+Neither one carries any meaning beyond the fact it states. Dim a pending
+button in a stylesheet, or have a widget watch its own attributes and
+disable itself. An application that styles neither behaves correctly and
+shows nothing.
+
+## Sending a request from a widget
+
+A widget can build and dispatch a request itself instead of carrying one of
+the attributes above — which is what `<lb-input>` does, and what a widget
+carrying `lb-action` must do. See
+[Custom Elements](./custom-elements.md#code).

package/docs/reference/overview.md

@@ -0,0 +1,38 @@
+# The Elements of a Loadbare Application
+
+This reference is organized into four groups that reflect how an application is
+put together: the shell it lives in, the build that assembles it, the pages it
+serves, and the widgets those pages are made of.
+
+## The application shell
+
+| Topic                                            | Description                                         |
+|--------------------------------------------------|-----------------------------------------------------|
+| [`chrome.html`](./chrome.md)                     | The HTML document w/head, body, banner, main, etc.  |
+| [The Express server](./server.md)                | Serves static assets and handles data channel calls |
+| [The database layer](./server.md#database-layer) | Where the app's database access fits                |
+
+## Building the app
+
+| Topic                                                    | Description                               |
+|----------------------------------------------------------|-------------------------------------------|
+| [`imports.ts`](./builder.md#widgets-from-packages)       | The packages this app takes widgets from  |
+| [`loadbare-app-build`](./builder.md#running-the-builder) | Configuring the build command             |
+| [CSS](./css.md)                                          | How the builder packages css              |
+
+## Application Pages
+
+| Topic                                                   | Description                    |
+|---------------------------------------------------------|--------------------------------|
+| [`<name>.page.html`](./page-files.md#html)              | The page's HTML                |
+| [`<name>.queries.ts`](./page-files.md#queries)          | The data the page displays     |
+| [`<name>.hooks.ts`](./page-files.md#hooks-actions-crud) | Data Channel handlers          |
+| [Data Binding](./data-binding.md)                       | Connecting HTML to server data |
+
+## Widgets
+
+| Topic                                          | Description                     |
+|------------------------------------------------|---------------------------------|
+| [What a widget is](./custom-elements.md)       | An HTML file, a script, or both |
+| [`<tag-name>.html`](./custom-elements.md#html) | The markup the tag expands into |
+| [`<tag-name>.ts`](./custom-elements.md#code)   | The class the tag registers     |

package/docs/reference/page-files.md

@@ -0,0 +1,175 @@
+# Page Files
+
+A page is a set of files sharing one base name. The application writes the
+HTML, and adds queries and hooks when the page shows data.
+
+| File                | Holds                         |
+|---------------------|-------------------------------|
+| `<name>.page.html`  | The page's HTML               |
+| `<name>.queries.ts` | The data the page displays    |
+| `<name>.hooks.ts`   | What the page does when asked |
+
+Name the landing page `index.page.html`. A bare `/` resolves to `index`, and
+every other path names the page of the same name.
+
+Put the files anywhere under `src/`. The builder pairs them by base name, not
+by directory; `src/pages/` is the convention.
+
+## HTML
+
+Write the page as a fragment. The fragment will land in `<main>`, which
+is supplied by [chrome.html](./chrome.md).
+
+```html
+<!-- src/pages/about.page.html -->
+<h1>About</h1>
+<p>This is the about page.</p>
+
+<div lb-query="visits">
+  <p>This page has been visited <span lb-cell="count"></span> times.</p>
+</div>
+```
+
+Bind elements to data with `lb-query`, `lb-cell`, and the rest of the
+attribute vocabulary in [Data Binding](./data-binding.md).
+
+A page that displays no data needs no other file.
+
+## Queries
+
+Export `queries` from `<name>.queries.ts`. Each key is a name the HTML binds
+to with `lb-query`, and each value takes the request context and returns
+that query's result:
+
+```ts
+// src/pages/about.queries.ts
+import { type Queries } from "@loadbare/app/server";
+
+export const queries: Queries = {
+  visits: async (ctx) => ({ count: String(await ctx.db.visitCount()) }),
+};
+```
+
+Return every cell as a string. Format numbers, dates, and money in the query,
+so the browser displays a value it never computes.
+
+Return many rows through `rows()`:
+
+```ts
+// src/pages/directory.queries.ts
+import { rows, type Queries } from "@loadbare/app/server";
+
+export const queries: Queries = {
+  directory: async (ctx) => rows(await ctx.db.directory()),
+};
+```
+
+Give every row a cell that identifies it, and name that cell with `lb-key` in
+the HTML. Return the rows in the order the page shows them.
+
+Return the full result every time. Sending only what changed is a hook's job —
+see [refresh and patch](#refresh-and-patch).
+
+## Hooks, actions, CRUD
+
+Export `hooks` from `<name>.hooks.ts`. It holds three keys, each optional:
+
+| Key         | Runs                                                 |
+|-------------|------------------------------------------------------|
+| `beforeGet` | Before the page's queries, on a request for the page |
+| `actions`   | What the page may be asked to do, by name            |
+| `crud`      | The four operations a query permits on its rows      |
+
+### beforeGet
+
+```ts
+// src/pages/about.hooks.ts
+import { type Hooks } from "@loadbare/app/server";
+
+export const hooks: Hooks = {
+  beforeGet: (ctx) => ctx.db.recordVisit(),
+};
+```
+
+Declare no refresh set here. The page's queries run afterward.
+
+### actions
+
+Declare an action under the name the HTML gives `lb-action`. Pair what it
+does with the queries to re-run once it has:
+
+```ts
+export const hooks: Hooks = {
+  actions: {
+    resetVisits: {
+      run: (ctx) => ctx.db.resetVisits(),
+      refresh: ["visits"],
+    },
+  },
+};
+```
+
+Declare every action the page allows. A name the page does not declare is
+refused.
+
+Read where the interaction happened from `run`'s second argument, which
+carries `query`, `key`, `cell`, and `value` when the element that dispatched
+the request had them.
+
+### crud
+
+Declare CRUD operations under `crud`, keyed by the query they operate on. Each
+one takes the binding its trigger supplies:
+
+| Operation     | The page writes    | `run` receives         |
+|---------------|--------------------|------------------------|
+| `cellChange`  | `<lb-input data-fire-on-change>` | `key`, `cell`, `value` |
+| `tupleDelete` | `lb-delete`        | `key`                  |
+| `tupleInsert` | `<form lb-insert>` | `values`               |
+| `tupleUpdate` | `<form lb-update>` | `key`, `values`        |
+
+```ts
+// src/pages/directory.hooks.ts
+import { patch, type Hooks } from "@loadbare/app/server";
+
+export const hooks: Hooks = {
+  crud: {
+    directory: {
+      tupleInsert: {
+        run: async (ctx, { values }) => {
+          const entry = await ctx.db.addDirectoryEntry(values);
+          return { directory: patch({ rows: [entry] }) };
+        },
+        refresh: [],
+      },
+    },
+  },
+};
+```
+
+Declare every operation the query permits. An operation a query does not
+declare is refused, and a query with no `crud` entry permits none.
+
+### refresh and patch
+
+List in `refresh` every query whose whole answer the operation changed.
+
+Return a result from `run` to state a narrower change than re-running a query
+would. What `run` returns is laid over the refreshed queries:
+
+| Result                   | States                                      |
+|--------------------------|---------------------------------------------|
+| `rows([...])`            | The entire set, and its order               |
+| `patch({ rows: [...] })` | These rows arrive or change; the rest stand |
+| `patch({ drop: [...] })` | These keys are gone; the rest stand         |
+
+Return a patch for a change the operation knows the extent of — one row added,
+one row dropped, one cell edited — and leave `refresh` empty. Re-run the query
+instead when membership or order changed in a way the operation cannot name:
+
+```ts
+resetRoster: {
+  run: (ctx) => ctx.db.resetMembers(),
+  refresh: ["roster"],
+},
+```

package/docs/reference/server.md

@@ -0,0 +1,123 @@
+# The Express Server
+
+Loadbare ships no server. The application writes an ordinary Express app and
+serves four things from it: the client script, the stylesheet, the data
+channel, and the one HTML document.
+
+Express is a peer dependency. The application installs it.
+
+## A complete server
+
+Here is a minimal but complete server for a typical app:
+
+```ts
+// server.ts
+import path from "node:path";
+import { readFileSync } from "node:fs";
+import express, { type Request } from "express";
+import { hubRoutes } from "@loadbare/app/express";
+import type { HubContext } from "@loadbare/app/server";
+import { hub } from "./dist/pages";
+import { openDb } from "./src/database";
+
+const DIST = path.resolve("dist");
+const app = express();
+
+app.get("/client.js", (_req, res) => res.sendFile(path.join(DIST, "client.js")));
+app.get("/app.css", (_req, res) => res.sendFile(path.join(DIST, "app.css")));
+
+function contextFor(_req: Request): HubContext {
+  return { db: openDb() };
+}
+app.use(hubRoutes(hub, contextFor));
+
+app.get(/.*/, (_req, res) =>
+  res.type("html").send(readFileSync(path.join(DIST, "app.html"), "utf-8")),
+);
+
+app.listen(8787);
+```
+
+## What the server serves
+
+| Required                     | Serves                        |
+|------------------------------|-------------------------------|
+| `/client.js`                 | `dist/client.js`              |
+| `/app.css`                   | `dist/app.css`                |
+| `hubRoutes(hub, contextFor)` | `GET /lb/data` and `POST /lb` |
+| Every other GET              | `dist/app.html`               |
+
+Everything else is optional:
+
+| Optional                      | Description                                  |
+|-------------------------------|----------------------------------------------|
+| Middleware before `hubRoutes` | Sessions, authentication, logging            |
+| The application's own routes  | Uploads, webhooks, anything outside Loadbare |
+| An error handler              | Express sends its own 500 without one        |
+
+
+## Rules for writing the server
+
+Register the static routes and `hubRoutes` before the catch-all.
+
+Register authentication before `hubRoutes`.
+
+Serve `dist/app.html` for every route the application does not claim,
+including a path that names no page. See [`chrome.html`](./chrome.md) for the
+`<dialog lb-unknown-page>` that announces that case to the user.
+
+Give the server the origin root. A proxy in front of it passes `/lb/data` and
+`/lb` through unchanged, and the application cannot be hosted under a subpath
+such as `example.com/myapp/`.
+
+Leave `express.json()` to `hubRoutes`, which mounts it on its own routes.
+
+## Running the server
+
+Run the server under a TypeScript-capable runner. The builder writes
+`dist/pages.ts`, which exports `hub`, as TypeScript:
+
+```json
+{
+  "scripts": {
+    "dev": "loadbare-app-build --watch & tsx server.ts"
+  }
+}
+```
+
+Restart the server after adding or changing a `.hooks.ts` or `.queries.ts`
+file.
+
+## Database layer
+
+Loadbare ships no data layer. The application opens its own database and hands
+it to Loadbare as the request context.
+
+The application writes `contextFor` and passes it to `hubRoutes`. Loadbare
+calls it on every data request:
+
+```ts
+// server.ts
+function contextFor(req: Request): HubContext {
+  return { db: openDb(req.session.userId) };
+}
+```
+
+Open the handle in `contextFor` rather than once at startup, so that each
+request works through a database opened for the caller it authenticated.
+
+Declare what the context holds, once, anywhere in the application's own
+source. Next to the database module is the natural place:
+
+```ts
+// src/database.ts
+declare module "@loadbare/app/server" {
+  interface HubContext {
+    db: Db;
+  }
+}
+```
+
+Add a field for anything else a request needs — the authenticated user, a
+request id, a feature flag set. Queries and hooks read them from `ctx`; see
+[page files](./page-files.md).