@loadbare/app 0.8.0 → 0.8.2

package/skills/loadbare-app/references/page-files.md

@@ -0,0 +1,194 @@
+# Page Files
+
+A page is a set of files sharing one base name. The application writes the
+HTML, and adds queries and requests when the page shows data.
+
+| File                 | Holds                         |
+|----------------------|-------------------------------|
+| `<name>.page.html`   | The page's HTML               |
+| `<name>.queries.ts`  | The data the page displays    |
+| `<name>.requests.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-row="visits">
+  <p>This page has been visited <span lb-cell="count"></span> times.</p>
+</div>
+```
+
+Bind elements to data with `lb-list` or `lb-row`, `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-list` or `lb-row`, and each value takes the request context and returns
+that query's result:
+
+```ts
+// src/pages/about.queries.ts
+import { row, type Queries } from "@loadbare/app/server";
+
+export const queries: Queries = {
+  visits: row(async (ctx) => ({ count: String(await ctx.db.visitCount()) })),
+};
+```
+
+Declare each query with `row()` or `list()`. Cardinality is a property of the
+name rather than of any one answer, so one name answers with one shape,
+always, and `createHub` refuses an answer that disagrees. A page that needs
+the same data as one row and as a set declares two queries.
+
+The hub hands each cell to the browser untouched and takes no position on
+its type, so what a number, a date or a null looks like is decided here, in
+the query. Formatting it here means the browser displays a value it never
+computes.
+
+Declare a query that answers with many rows using `list()`, and return the
+array itself:
+
+```ts
+// src/pages/directory.queries.ts
+import { list, type Queries } from "@loadbare/app/server";
+
+export const queries: Queries = {
+  directory: list((ctx) => ctx.db.directory()),
+};
+```
+
+Give every row a column that identifies it, and name that column 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 request's job —
+see [refresh and patch](#refresh-and-patch).
+
+## Requests, actions, CRUD
+
+Export `requests` from `<name>.requests.ts`. It holds three keys, each optional:
+
+| Key           | Runs                                                 |
+|---------------|------------------------------------------------------|
+| `onPageEnter` | Before the page's queries, on entering the page      |
+| `actions`     | What the page may be asked to do, by name            |
+| `crud`        | The three operations a list permits on its rows      |
+
+### onPageEnter
+
+```ts
+// src/pages/about.requests.ts
+import { type Requests } from "@loadbare/app/server";
+
+export const requests: Requests = {
+  onPageEnter: (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 requests: Requests = {
+  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 `list` or `row`, whichever attribute scoped the element, plus `key`,
+`cell` and `value` when the element that dispatched the request had them.
+
+### crud
+
+Declare CRUD operations under `crud`, keyed by the list they operate on. All
+three are list operations: each needs a key, and a key exists only on a live
+row inside a list, so a single-row scope is read-only and a declared action is
+the only thing it can send. Each operation takes the binding its trigger
+supplies:
+
+| Operation   | The page writes                                                        | `run` receives  |
+|-------------|------------------------------------------------------------------------|-----------------|
+| `rowDelete` | `lb-action="lb-row-delete"`                                            | `key`           |
+| `rowInsert` | `<form lb-action="lb-row-insert">`                                     | `values`        |
+| `rowUpdate` | `<form lb-action="lb-row-update">` or `<lb-input lb-action="lb-row-update">` | `key`, `values` |
+
+Write `rowUpdate` to set the columns `values` names and leave every other
+column as it is. A form sends the cells it holds, and a widget cell sends
+itself alone. Check the names in `values` against the columns the list lets
+the page edit.
+
+The operation names are reserved: a name beginning with `lb-` cannot be
+declared under `actions` or as a query, and `createHub` refuses a page that
+tries.
+
+```ts
+// src/pages/directory.requests.ts
+import { patch, type Requests } from "@loadbare/app/server";
+
+export const requests: Requests = {
+  crud: {
+    directory: {
+      rowInsert: {
+        run: async (ctx, { values }) => {
+          const entry = await ctx.db.addDirectoryEntry(values);
+          return { directory: patch({ rows: [entry] }) };
+        },
+        refresh: [],
+      },
+    },
+  },
+};
+```
+
+Declare every operation the list permits. An operation a list does not
+declare is refused, and a name 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                                      |
+|--------------------------|---------------------------------------------|
+| `[...]`                  | 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 row 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/skills/loadbare-app/references/server.md

@@ -0,0 +1,153 @@
+# 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)` | The hub's own route            |
+| 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. The hub reaches its own route by absolute
+path, so the application cannot be hosted under a subpath such as
+`example.com/myapp/`, and anything proxying in front of the server passes the
+whole path space through unchanged.
+
+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"
+  }
+}
+```
+
+Node 22.18 and later also runs it with no runner at all, since Node strips
+TypeScript types itself. `dist/pages.ts` imports each `.requests.ts` and
+`.queries.ts` file by its full name, extension included, because Node looks
+for exactly the path an import names.
+
+Enable `allowImportingTsExtensions` in the application's `tsconfig.json`
+when `tsc` type-checks the server. Without it, `tsc` rejects the `.ts`
+extensions in `dist/pages.ts`:
+
+```json
+{
+  "compilerOptions": {
+    "noEmit": true,
+    "allowImportingTsExtensions": true
+  }
+}
+```
+
+Restart the server after adding or changing a `.requests.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;
+  }
+}
+```
+
+The query string the browser is showing arrives on every data request, so
+`req.query` holds the page's query parms. Put on the context whatever a query
+reads from them, and treat them as user input:
+
+```ts
+function contextFor(req: Request): HubContext {
+  const { team } = req.query;
+  return { db: openDb(), team: typeof team === "string" ? team : "" };
+}
+```
+
+Add a field for anything else a request needs — the authenticated user, a
+request id, a feature flag set. Queries and requests read them from `ctx`; see
+[page files](./page-files.md).

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

@@ -0,0 +1,178 @@
+# The Basic Widget Library
+
+Seven widgets: `lb-input`, `lb-select`, `lb-list`, `lb-options`, `lb-table`,
+`lb-picker`, `lb-unknown-page`. Every one of them is written against the same two contracts
+documented elsewhere — [Custom Elements](./custom-elements.md#html) for its
+definition, [Custom Elements](./custom-elements.md#code) for its class —
+nothing here is special-cased machinery.
+
+They ship compiled, in `@loadbare/widgets`, a package the builder resolves the
+way it resolves anyone else's — it declares `"loadbare": { "widgets": "./dist" }`
+and the builder scans that. Install it and list it:
+
+```
+npm install @loadbare/widgets
+```
+
+```ts
+// src/imports.ts
+export default ["@loadbare/widgets"];
+```
+
+See [Widgets from packages](./builder.md#widgets-from-packages) for what
+listing a package does, and [The Builder](./builder.md#where-the-builder-looks)
+for where a listed package sits in the cascade.
+
+## `lb-input`
+
+Wraps an `<input>`. `lb-value` sets the input's `.value`. The widget sends
+nothing on its own: `lb-action` names what the input's `change` sends. The
+reserved `lb-row-update` saves the input's own cell; any other name sends that
+action. Either carries the input's value, and the hub adds the scope the
+input sits in.
+
+An input inside an `lb-row-insert` or `lb-row-update` form leaves the attribute off.
+The form reads every `lb-cell` in it on submit and sends one request for all
+of them, so an input that also sent its own would write the same edit twice.
+
+| Parameter | Fills |
+| ---------- | ----- |
+| `exp-label` | the visible `<label>` text |
+| `exp-readonly` | the input's `readonly` attribute |
+
+| Attribute | Asks for |
+| ---------- | ----- |
+| `lb-action` | what to send on `change`; `lb-row-update` to save the cell's own edit |
+
+## `lb-select`
+
+Wraps a `<select>` whose `<option>`s the author writes directly inside (via
+`lb-slot`). `lb-value` sets the select's `.value`; a `change` sends the
+action named by `lb-action`, with the select's `.value` as the request's
+`value` — the choice is the interaction, so this is the case where an
+action carries a value.
+
+| Parameter | Fills |
+| ---------- | ----- |
+| `exp-label` | the visible `<label>` text |
+
+Requires `lb-action` or `lb-query-parm` — a change with neither logs and
+sends nothing. With `lb-query-parm` the hub writes the choice into the URL.
+
+## `lb-options`
+
+A `<select>` whose `<option>`s come from a query instead of being written by
+hand. The author supplies the row template inside the widget (via
+`lb-slot`), same as any list widget:
+
+```html
+<lb-options lb-list="statuses" exp-label="Status" lb-action="setStatus">
+  <template lb-key="id" data-group="category">
+    <option lb-cell="label"></option>
+  </template>
+</lb-options>
+```
+
+| Parameter | Fills |
+| ---------- | ----- |
+| `exp-label` | the visible `<label>` text |
+
+- The row's key becomes the option's `value`: the `lb-key-value` the hub
+  stamps on each option is copied across, so the page names the key column
+  once, with `lb-key`.
+- `data-group` on the row template sections the options into `<optgroup>`s,
+  one per distinct value, created and removed as rows arrive and leave.
+- `lb-value` selects the option with that key, including one that arrives
+  after the value did.
+- A `change` sends the action named by `lb-action`, value from the
+  select's `.value`. With `lb-query-parm` instead, the hub writes the
+  choice into the URL.
+
+`lb-picker` is this same class with its row template supplied by the
+definition instead of the page — see below.
+
+## `lb-table`
+
+A `<table>` that supplies its own scaffolding; the author supplies the
+heading row, the row template, and optionally a footer, each as a
+`<template>` matched to a destination:
+
+```html
+<lb-table lb-list="ledger" exp-caption="Ledger">
+  <template lb-template="head">
+    <tr><th>Date</th><th>Amount</th></tr>
+  </template>
+  <template lb-key="id" data-sort="date" data-group="month">
+    <tr><td lb-cell="date"></td><td lb-cell="amount"></td></tr>
+  </template>
+  <template lb-template="foot">
+    <tr lb-row="ledger-total"><td>Total</td><td lb-cell="total"></td></tr>
+  </template>
+</lb-table>
+```
+
+| Parameter | Fills |
+| ---------- | ----- |
+| `exp-caption` | the `<caption>` text |
+
+| Destination | Fills |
+| ------------ | ----- |
+| `head` (`lb-template="head"`) | the `<thead>` content |
+| `foot` (`lb-template="foot"`) | the `<tfoot>` content |
+| slot (no `lb-template`) | the row template, via `lb-slot` on `<tbody>` |
+
+- `data-group` on the row template sections rows under a derived heading row,
+  one per distinct value, whose `colSpan` matches the row's own column
+  count. `data-sort` orders rows within a section (or the whole body, with no
+  grouping) by comparing each row's cell text.
+- The `foot` destination is not delivered through `lbPlaceRow` — it's an
+  ordinary scope carrying its own `lb-row`, resolved by name like any
+  other on the page. A grand total is a second query over the same
+  data, not a row the hub hands the table.
+
+## `lb-picker`
+
+`lb-options`, with the row template supplied by the definition instead of
+the page — for when every row is one option and nothing else varies:
+
+```html
+<lb-picker
+  lb-list="statuses"
+  exp-label="Status"
+  exp-key="id"
+  exp-cell="label"
+  exp-group="category"
+  lb-action="setStatus"
+></lb-picker>
+```
+
+| Parameter | Fills |
+| ---------- | ----- |
+| `exp-label` | the visible `<label>` text |
+| `exp-key` | the row template's `lb-key` |
+| `exp-cell` | the option's `lb-cell` |
+| `exp-group` | the row template's `data-group` |
+
+Behavior — grouping, key-as-value, the action on change — is inherited
+whole from `lb-options`; a page author who needs a second element in the
+row, or an option built from two columns, writes `lb-options` and its own
+`<template>` instead.
+
+## `lb-unknown-page`
+
+The chrome's dialog for a URL that names no page, as one tag:
+
+```html
+<lb-hub>
+  <nav>...</nav>
+  <main></main>
+  <lb-unknown-page></lb-unknown-page>
+</lb-hub>
+```
+
+It expands to a `<dialog lb-unknown-page>` scoped to the hub's own
+`lb-navigation` query, so `page-label` and `page-uri` land in it the way any
+cell lands anywhere, and the hub opens it on a miss. It takes no parameters
+and, so far, shows both cells rather than choosing between them. See
+[`chrome.html`](./chrome.md#where-the-page-is) for the query, and for the same
+dialog written by hand.