@loadbare/app 0.7.4 → 0.8.1

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

@@ -0,0 +1,142 @@
+# 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;
+  }
+}
+```
+
+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,174 @@
+# 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` — a change with none logs and sends nothing.
+
+## `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.
+- A `change` sends the action named by `lb-action`, value from the
+  select's `.value`.
+
+`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.