@loadbare/app 0.9.0 → 0.11.0

package/docs/reference/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/docs/reference/page-files.md

@@ -1,92 +1,141 @@
 # 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.
+
+## What the page files are
+
+A page's queries are that page's view model, answered on the server. Each
+is shaped for the elements that name it, on one page, so it answers in the
+form the page shows: a date formatted, an amount with its separators, and
+the phrase a reader sees, such as "no postings yet" or "12 postings",
+rather than a count for the browser to word. The hub does no conversion,
+so there is no later place for that work to go. The markup says where each
+value goes, and the query says what it is.
+
+A value the page reads back, rather than only shows, stays data:
+
+| Value                              | Read back by                    | So it is                          |
+|------------------------------------|---------------------------------|-----------------------------------|
+| A column that lands on a control   | The request that gathers it     | What the handler expects to receive |
+| The key column                     | Every request from the row      | What the handler looks the row up by |
+| A column `lb-show` names           | The hub                         | `null` or `false` for off         |
+| A column a stylesheet selects on   | `[lb-column-value="…"]`         | A fixed token, not wording        |
+
+The page files are not a data layer; they sit on one. The application
+opens its own database and keeps its rules there, or in code its handlers
+share, and the page files stay thin because integrity is not their job.
+
+What two pages share goes beneath them, not between. Two pages showing the
+same data each write the query, or both read a database view. Shared
+wording and shared parm reading go in a helper module the queries import.
+Everything that belongs to one page stays in one place, so a change to a
+page touches that page's files.
 
 ## 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 shows no data needs no other file.
+
+### The page title
 
-A page that displays no data needs no other file.
+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).
 
-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.
+## Requests
 
-Return the full result every time. Sending only what changed is a request's job —
-see [refresh and patch](#refresh-and-patch).
+Export `requests` from `<stub>.requests.ts`. It holds three keys, each
+optional:
 
-## Requests, actions, CRUD
+| 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          |
 
-Export `requests` from `<name>.requests.ts`. It holds three keys, each optional:
+Every request arrives with one shape, and a handler receives it less its
+name:
 
-| 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      |
+| 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                   |
+
+The hub sends `query`, `key` and `values` when it finds them; see
+[Gathering](./data-binding.md#gathering).
 
 ### onPageEnter
 
@@ -101,51 +150,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:
-
-| 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.
+Declare what the three requests Loadbare provides do under `crud`, keyed by
+the query they operate on:
 
-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 +198,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: {
@@ -193,18 +246,16 @@ resetRoster: {
 },
 ```
 
-Return `queryParms()` instead when the server response changes the query
-parms: after an insert, only the server knows the new key, and after a delete,
-only the server knows the parm should go. The page loads at the query string
-with those parms set, in the same round trip, and the hub writes them into the
-URL, replacing the history entry. 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 query string the page left. Name at least
-one parm, give each a string, and use an empty string to take one out:
+### 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 { queryParms, type Requests } from "@loadbare/app/server";
+import { url, type Requests } from "@loadbare/app/server";
 
 export const requests: Requests = {
   crud: {
@@ -212,14 +263,14 @@ export const requests: Requests = {
       rowInsert: {
         run: async (ctx, { values }) => {
           const id = await ctx.db.addAccount(values);
-          return queryParms({ acct: String(id) });
+          return url({ acct: String(id) });
         },
         refresh: [],
       },
       rowDelete: {
         run: async (ctx, { key }) => {
           await ctx.db.deleteAccount(key);
-          if (key === ctx.acct) return queryParms({ acct: "" });
+          if (key === ctx.acct) return url({ acct: "" });
         },
         refresh: ["accounts"],
       },
@@ -228,6 +279,20 @@ export const requests: Requests = {
 };
 ```
 
-Only parms: `run` cannot send the browser to another page. The loaded page
-reads the new parms through `contextFor` like any others; see
+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/docs/reference/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
@@ -149,7 +149,7 @@ function contextFor(req: Request, parms: URLSearchParams): HubContext {
 
 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 [refresh and patch](./page-files.md#refresh-and-patch). Write it to
+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.