@loadbare/app 0.8.2 → 0.10.0

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

@@ -2,7 +2,7 @@
 
 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.
+serves, and the custom elements those pages are made of.
 
 ## The application shell
 
@@ -24,15 +24,17 @@ serves, and the widgets those pages are made of.
 
 | 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>.requests.ts`](./page-files.md#requests-actions-crud) | Data Channel handlers          |
+| [`<stub>.page.html`](./page-files.md#html)              | The page's HTML                |
+| [`<stub>.queries.ts`](./page-files.md#queries)          | The queries the page shows     |
+| [`<stub>.requests.ts`](./page-files.md#requests)        | The page's request handlers    |
 | [Data Binding](./data-binding.md)                       | Connecting HTML to server data |
+| [The URL](./chrome.md#the-url)                          | Pages, links and query parms   |
 
-## Widgets
+## Custom elements
 
-| 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     |
+| Topic                                                  | Description                     |
+|--------------------------------------------------------|---------------------------------|
+| [What a custom element 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>.browser.ts`](./custom-elements.md#code)   | The class the tag registers     |
+| [The Basic Widget Library](./widgets.md)               | `@loadbare/widgets`             |

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

@@ -1,92 +1,112 @@
 # 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.
+A page is a set of files sharing one stub, the file name less its suffix.
+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 |
+| `<stub>.page.html`   | The page's HTML               |
+| `<stub>.queries.ts`  | The queries the page shows    |
+| `<stub>.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.
+every other path names the page whose stub it is.
 
-Put the files anywhere under `src/`. The builder pairs them by base name, not
-by directory; `src/pages/` is the convention.
+Put the files anywhere under `src/`. The builder pairs them by stub, 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).
+Write the page as a fragment. The fragment lands in `<main>`, which
+[chrome.html](./chrome.md) supplies.
 
 ```html
 <!-- src/pages/about.page.html -->
+<title>About</title>
 <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 lb-query="visits">
+  <p>This page has been visited <span lb-column="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).
+Show data with `lb-query`, `lb-column`, and the rest of the attributes in
+[Data Binding](./data-binding.md).
 
-A page that displays no data needs no other file.
+A page that shows no data needs no other file.
+
+### The page title
+
+Write a `<title>` in the page file to name the page. The builder removes it
+from the page and stamps its text on the page's `<template>` as
+`lb-page-title`. The hub shows it as the `lb-url` column `lb-page-label`, and
+sets the document title to it; see [The URL](./chrome.md#the-url). A page
+with no `<title>` is labeled by its stub.
 
 ## 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:
+Export `queries` from `<stub>.queries.ts`. Each key is a query name the HTML
+names with `lb-query`, and each value declares the query's kind, its key
+column, and the function that answers it:
 
 ```ts
-// src/pages/about.queries.ts
-import { row, type Queries } from "@loadbare/app/server";
+// src/pages/directory.queries.ts
+import { row, rows, type Queries } from "@loadbare/app/server";
 
 export const queries: Queries = {
-  visits: row(async (ctx) => ({ count: String(await ctx.db.visitCount()) })),
+  visits: row("page", async (ctx) => ({
+    page: "directory",
+    count: String(await ctx.db.visitCount()),
+  })),
+  directory: rows("id", (ctx) => ctx.db.directory()),
 };
 ```
 
-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.
+| Declared with     | Answers with                              |
+|-------------------|-------------------------------------------|
+| `row(key, run)`   | One row, an object                        |
+| `rows(key, run)`  | All its rows, an array of objects, in order |
 
-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.
+`key` names the column that identifies a row. Give every row that column,
+including a `row` query's: an aggregate row answers with a constant key. The
+hub matches rows to live rows by key, and a request names a row by key.
 
-Declare a query that answers with many rows using `list()`, and return the
-array itself:
+Kind and key belong to the name, so one name answers with one shape, always,
+and `createHub` leaves out an answer that disagrees with its declaration. A
+page that needs the same data as one row and as a set declares two queries.
 
-```ts
-// src/pages/directory.queries.ts
-import { list, type Queries } from "@loadbare/app/server";
+The hub hands each value to the browser untouched, so what a number, a date
+or a null looks like is decided here, in the query.
 
-export const queries: Queries = {
-  directory: list((ctx) => ctx.db.directory()),
-};
-```
+Return the full answer every time, and the rows in the order the page shows
+them. Sending only what changed is a request's job — see
+[refresh and patch](#refresh-and-patch).
+
+## Requests
 
-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.
+Export `requests` from `<stub>.requests.ts`. It holds three keys, each
+optional:
 
-Return the full result every time. Sending only what changed is a request's job —
-see [refresh and patch](#refresh-and-patch).
+| Key           | Runs                                                   |
+|---------------|--------------------------------------------------------|
+| `onPageEnter` | Before the page's queries, when the page loads         |
+| `handlers`    | The page's declared requests, by request name          |
+| `crud`        | The requests Loadbare provides, by query name          |
 
-## Requests, actions, CRUD
+Every request arrives with one shape, and a handler receives it less its
+name:
 
-Export `requests` from `<name>.requests.ts`. It holds three keys, each optional:
+| Field    | Holds                                                    |
+|----------|----------------------------------------------------------|
+| `name`   | The request name, from `lb-request`                      |
+| `query`  | The query the request is for                             |
+| `key`    | The key of the row the request is for                    |
+| `values` | The gathered control values, by column                   |
 
-| 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      |
+The hub sends `query`, `key` and `values` when it finds them; see
+[Gathering](./data-binding.md#gathering).
 
 ### onPageEnter
 
@@ -101,51 +121,39 @@ export const requests: Requests = {
 
 Declare no refresh set here. The page's queries run afterward.
 
-### actions
+### handlers
 
-Declare an action under the name the HTML gives `lb-action`. Pair what it
+Declare a request under the name the HTML gives `lb-request`. Pair what it
 does with the queries to re-run once it has:
 
 ```ts
 export const requests: Requests = {
-  actions: {
+  handlers: {
     resetVisits: {
       run: (ctx) => ctx.db.resetVisits(),
       refresh: ["visits"],
     },
+    sendReminder: {
+      run: (ctx, { key }) => ctx.mail.remind(key),
+      refresh: [],
+    },
   },
 };
 ```
 
-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.
+Declare every request the page allows. The server refuses a name the page
+does not declare.
 
 ### 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:
+Declare what the three requests Loadbare provides do under `crud`, keyed by
+the query they operate on:
 
-| 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.
+| Request name    | Runs        | `run` receives   |
+|-----------------|-------------|------------------|
+| `lb-row-insert` | `rowInsert` | `query`, `values` |
+| `lb-row-update` | `rowUpdate` | `query`, `key`, `values` |
+| `lb-row-delete` | `rowDelete` | `query`, `key`   |
 
 ```ts
 // src/pages/directory.requests.ts
@@ -161,30 +169,46 @@ export const requests: Requests = {
         },
         refresh: [],
       },
+      rowUpdate: {
+        run: async (ctx, { key, values }) => {
+          const entry = await ctx.db.updateDirectoryEntry(key, 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.
+Declare every request the query permits. The server refuses a request a
+query does not declare, and a query with no `crud` entry permits none.
+
+Write `rowUpdate` to set the columns `values` names and leave every other
+column as it is. A form or a live row sends every control it gathers, and a
+single control sends itself alone. Check the names in `values` against the
+columns the page may edit.
+
+Every value in `values` is a string, as a control's value is.
 
 ### refresh and patch
 
-List in `refresh` every query whose whole answer the operation changed.
+List in `refresh` every query whose whole answer the request 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:
+Return answers from `run` to state a narrower change than re-running a query
+would. What `run` returns is keyed by query name and laid over the refreshed
+queries:
 
-| Result                   | States                                      |
+| Answer                   | States                                      |
 |--------------------------|---------------------------------------------|
-| `[...]`                  | The entire set, and its order               |
+| `{ ... }`                | The row of a `row` query                    |
+| `[...]`                  | All rows of a `rows` query, and their 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,
+Return a patch for a change the request 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:
+instead when membership or order changed in a way the request cannot name:
 
 ```ts
 resetRoster: {
@@ -192,3 +216,54 @@ resetRoster: {
   refresh: ["roster"],
 },
 ```
+
+### Moving the URL
+
+Return `url()` from `run` when the request changes what the URL should say:
+after an insert, only the server knows the new key, and after a delete, only
+the server knows the parm should go. `url()` takes columns of the `lb-url`
+query; see [The URL](./chrome.md#the-url).
+
+```ts
+// src/pages/accounts.requests.ts
+import { url, type Requests } from "@loadbare/app/server";
+
+export const requests: Requests = {
+  crud: {
+    accounts: {
+      rowInsert: {
+        run: async (ctx, { values }) => {
+          const id = await ctx.db.addAccount(values);
+          return url({ acct: String(id) });
+        },
+        refresh: [],
+      },
+      rowDelete: {
+        run: async (ctx, { key }) => {
+          await ctx.db.deleteAccount(key);
+          if (key === ctx.acct) return url({ acct: "" });
+        },
+        refresh: ["accounts"],
+      },
+    },
+  },
+};
+```
+
+A column other than `lb-path` is a query parm: set, or taken out when its
+value is an empty string. Name at least one column, and give each a string.
+With `lb-path` naming another page, the page is entered with only the parms
+named:
+
+```ts
+return url({ "lb-path": "/accounts", acct: String(id) });
+```
+
+The server loads the page at the new URL in the same round trip, as a cold
+load of it would, and the hub writes the URL: it pushes a history entry when
+the page changes, or when the element that sent the request carries
+`lb-url-push`, and replaces the current one otherwise. This is
+Post/Redirect/Get without the redirect. The refresh set does not run, and
+nothing else `run` returned is sent, since both answered for the URL the page
+left. The loaded page reads the new parms through `contextFor`; see
+[the Express server](./server.md#database-layer).

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

@@ -64,7 +64,7 @@ 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.
+`<dialog lb-url-unknown>` 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
@@ -137,17 +137,23 @@ declare module "@loadbare/app/server" {
 }
 ```
 
-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:
+The query string the browser is showing arrives on every data request, and
+`contextFor` gets its parms as a second argument. 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 : "" };
+function contextFor(req: Request, parms: URLSearchParams): HubContext {
+  return { db: openDb(), team: parms.get("team") ?? "" };
 }
 ```
 
+Read the parms from that argument, not from `req.query`. When a server
+response changes the query parms, `contextFor` is called a second time for
+that request, with the new parms, to load the page at them; see [Moving the URL](./page-files.md#moving-the-url). Write it to
+be safe to call twice, and make a write visible to the second context by the
+time `run` returns: a handle opened per request, with no transaction held
+open across the two, is both.
+
 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).