@loadbare/app 0.8.1 → 0.9.0

package/skills/loadbare-app/references/TECHREF-1.0.md

@@ -106,14 +106,6 @@ in the row.
   stays a flag, since it is what locates the file.  State the precedence
   between a flag and a key once.  Its key names join the permanent surface,
   so this lands before 1.0 or not at all.
-- **Decide whether a URL carries view parameters.** A URL names a page and
-  nothing finer — see [What a URL names](#what-a-url-names) — and a query
-  takes no argument from the browser.  So a page has nowhere to keep which
-  record it shows, a filter, a sort, or a collapsed section: a reload or a
-  shared link loses them, and a filter is lost whenever an action re-runs its
-  query.  Parameters on a page URL, as `<form method="get">` puts its fields
-  in the query string, are one answer.  Deciding against them, and leaving
-  view state to the application, is another.  Write whichever one down.
 - **Decide CSS pairing.** Naming a stylesheet `<tag>.css` beside its
   definition would let the builder ship only what survives expansion.
   Recommend deferring the mechanism and reserving the configuration key, so
@@ -507,8 +499,11 @@ A list nested in another list's rows receives the same rows in every outer
 row.  That serves a picker offering the same choices on every row, and is
 not a way to show a different detail per row.
 
-Which master a page shows is server state reached through `ctx`, since a
-query takes no argument from the browser — see the blocker on view parameters.
+Which master a page shows is a query parm, which a query reads off `ctx`
+since it takes no argument from the browser — see [Query parms](#query-parms).
+When a write creates or removes the master, the server response changes that
+parm — see
+[When a server response changes the query parms](#when-a-server-response-changes-the-query-parms).
 
 ### Requests
 
@@ -638,15 +633,16 @@ A failed insert resets nothing, so the entry can be corrected.
 
 A navigation that fails to load its data sets nothing.  No element
 dispatched it, so there is nothing to stamp, and the hub reports it to the
-console.
+console.  A load started by a control writing a query parm stamps that
+control, as a request stamps its origin.
 
 ### Links
 
 ---- UNEDITED ----
 
 An anchor carrying `lb-nav-link` navigates inside the application: the hub
-catches the click, pushes the anchor's path onto history, and swaps the page
-host in `<main>`.  An anchor without it is left alone and behaves like any
+catches the click, pushes the anchor's path and query string onto history,
+and swaps the page host in `<main>`.  An anchor without it is left alone and behaves like any
 other link, so leaving the application is the default and staying in it is
 the opt-in.
 
@@ -660,6 +656,11 @@ link to determine the path.
 Path space is flat.  A path such as `/members` links to the `members.*` files
 on the server.
 
+The query string is kept.  `/transactions?date_begin=2026-09-01` opens the
+transactions page narrowed to those dates, and a link to the page it is
+already on loads that page again at the new URL without replacing its DOM —
+see [Query parms](#query-parms).
+
 The bare path `/` resolves to `index`.
 
 A path that names no page is detected in the browser, after a successful
@@ -680,19 +681,122 @@ See also [Navigation Row lb-navigation](#lb-navigation).
 
 #### What a URL names
 
-A URL names a page, a place in the application.  It never names a resource,
-and Loadbare/app does not reproduce REST: `/accounts/42` is not a way to
-reach account 42.
+The path names a page, a place in the application.  It never names a
+resource, and Loadbare/app does not reproduce REST: `/accounts/42` is not a
+way to reach account 42.
+
+The query string describes what that page has on screen:
+`/accounts?acct=23&from=2026-09-09`.  It never commands, and the server
+remembers nothing, so a URL is a reproducible view.  Reload it, bookmark it,
+or mail it to someone, and what they see is what the sender saw.
 
 A page declares what it shows, its queries, and what it allows, its actions.
 Loading a page runs its queries.  A request performs an action at a position.
 A row is addressed by `list` and `key`, taken from where the element sits,
 which is how the database already names it.  Nothing is fetched by URL, so an
-application designs no endpoints, and the browser reaches only what a page
-publishes.
+application designs no endpoints.
+
+That last is where query parms move Loadbare's position.  A query still takes
+no argument from the browser, and a parm arrives the way the session cookie
+does, as part of the request the context is built from.  But a user who
+types `?acct=99999` now influences what a query returns.  A query parm is
+user input, validated like any other where the application reads it, and a
+per-session database role means an id outside the caller's reach finds
+nothing.
+
+Loadbare is for applications, not sites.  Every route is answered with the
+same document, and a path that names no page is found out in the browser —
+see [Links](#links).
+
+#### Query parms
+
+A control that narrows what a page shows writes its value into the query
+string, rather than sending it:
+
+```html
+<lb-options lb-list="teams" lb-query-parm="team" exp-label="Team:">
+  <option value="">Every team</option>
+  <template lb-key="id"><option lb-cell="name"></option></template>
+</lb-options>
+```
+
+| Attribute            | Written by | Behavior                                                        |
+| -------------------- | ---------- | --------------------------------------------------------------- |
+| `lb-query-parm`      | Developer  | On a control: its `change` writes this parm and reloads the page |
+| `lb-query-parm-push` | Developer  | With `lb-query-parm`: the write pushes a history entry          |
+
+On `change`, the hub reads the control's value the way a form reads a cell,
+and sets that one parm in the URL.  Every other parm is left as it is, since
+it may have arrived by link with no control on screen to say it again.  An
+empty value takes the parm out, so a URL is as long as the user has narrowed
+the page.  A value the URL already carries does nothing.
+
+The write replaces the current history entry: changing what a page shows is
+not going anywhere, so Back leaves the page rather than walking back through
+every choice.  `lb-query-parm-push` makes the write push an entry instead.
+
+The page then loads at the new URL exactly as a cold load of that URL would:
+`onPageEnter`, then every query.  The page's DOM is kept, and the answer
+lands by key, so a list that gets its rows back keeps them and its scroll
+position.
+
+After every load — cold, by link, by Back, by a write — the hub lands each
+parm on the control that writes it, and an absent parm lands empty.  A
+control therefore shows what the address bar says.
+
+A control that writes a query parm sends no request.  One that also carries
+`lb-action` has that request refused, since the choice would otherwise be
+sent twice.
+
+Every round trip carries the query string the browser is showing, a page
+load and an action alike.  The server hands its parms to `contextFor` — see
+[The Express server](#the-express-server).  Nothing in Loadbare assigns a
+parm a meaning.
 
-Whether a page URL may carry parameters, so that a link can open the page on
-one record, is undecided — see the blockers.
+#### When a server response changes the query parms
+
+Some query parms can only be known once a write has run.  After an insert,
+the key of the new row exists only on the server.  After a delete, only the
+server knows that the row the page was showing is gone.
+
+The usual web answer is Post/Redirect/Get: the server answers the write with
+a redirect to a URL naming the result, and the browser makes a second request
+to load it.  Loadbare/app does the same work in one round trip, and never
+changes the path.
+
+A request's `run` returns `queryParms()`, naming the parms the write decided.
+The server loads the page with those parms set, as a cold load of the
+resulting URL would: `onPageEnter`, then every query.  The server response
+carries the parms and that load together.  The hub sets the parms in the URL,
+replacing the history entry, and then lands the load.
+
+```ts
+rowInsert: {
+  run: async (ctx, { values }) => {
+    const id = await ctx.db.addAccount(values);
+    return queryParms({ acct: String(id) });
+  },
+  refresh: [],
+},
+```
+
+- Only query parms change.  A server response cannot send the browser to
+  another page.
+- Parms the response does not name are left as they are.  An empty value
+  removes its parm.
+- At least one parm is named, and every value is a string.  Otherwise the
+  server warns, ignores the parms, and runs the refresh set as usual.
+- The refresh set does not run, and anything else `run` returned is dropped.
+  Both were answers for the query string the page is leaving.
+- If loading the page fails, the write has still happened.  The response
+  carries the parms alone, and the hub loads the page itself.  A failure
+  there is a page load's, and is not stamped on the element that sent the
+  request.
+- A user who has left the page by the time the response arrives keeps the
+  URL they are on.
+
+The page is loaded with a second context, built by `contextFor` from the new
+parms — see [The Express server](#the-express-server).
 
 ### lb-navigation
 
@@ -706,10 +810,11 @@ like a server-produced result.
 | Cell         | Holds                                                               |
 | ------------ | ------------------------------------------------------------------- |
 | `page-label` | The text of the link to the current page, empty if no link names it |
-| `page-uri`   | The path as the browser has it, such as `/members`                  |
+| `page-uri`   | The path and query string as the browser has them, such as `/members?team=Engines` |
 
 The `page-uri` is taken from the current URL.  The `page-label` is taken from the first
-`lb-nav-link` link in the document (presumably in a nav bar) that matches the URI.
+`lb-nav-link` link in the document (presumably in a nav bar) whose path matches the
+current path, so the query string does not change it.
 
 The row lands before the page is looked up, so a path that names no page has
 it too, and an `lb-unknown-page` dialog, where the chrome has one, displays
@@ -871,6 +976,24 @@ Explaining Express is beyond the scope of this technical reference.  The
 only real requirement is that the catch-all for app.html is at the end,
 so it does not catch any other files.
 
+`hubRoutes` answers `POST /lb/<page>`, with the query string the browser is
+showing after it, verbatim.  It hands `contextFor` that query string's parms
+as a second argument, and `contextFor` puts on the context whatever a query
+reads from them.  They are user input:
+
+```ts
+function contextFor(req: Request, parms: URLSearchParams): HubContext {
+  return { db: openDb(), acct: parms.get("acct") ?? "" };
+}
+```
+
+Read the parms from that argument, not from `req.query`.  After a request
+whose `run` returned `queryParms()`, `contextFor` is called a second time for
+the same request, with the new parms, to load the page at them.  So it must
+be safe to call twice, and a write must be visible to the second context by
+the time its `run` returns.  A handle opened per request without a
+transaction around it is both.
+
 Give the server the origin root.  The hub reaches its own endpoints by
 absolute path, so an application cannot be hosted under a subpath such as
 `example.com/myapp/`, and anything proxying in front of the server passes
@@ -941,6 +1064,13 @@ interaction happened, as `list`, `row`, `key`, `cell` and `value`.  Under
 ones.  That is how a delta reaches the browser: wrap it in `patch()`, naming
 the rows that arrived or changed and the keys that went.
 
+`run` may instead return `queryParms()`, naming query parms only the write
+can know, such as the key of a row it inserted.  The page then loads at them
+in the same round trip, in place of the refresh set — see
+[When a server response changes the query parms](#when-a-server-response-changes-the-query-parms).
+A `rowDelete` that removes the row on screen returns `queryParms({ acct: "" })`
+and leaves any other delete to its refresh set.
+
 ```ts
 // members.requests.ts
 import { patch, type Requests } from "@loadbare/app/server";
@@ -1148,6 +1278,8 @@ Each attribute is defined in one section, and this table says which.
 | `lb-value`        | Hub           | [How a value lands](#how-a-value-lands)             |
 | `lb-action`       | Developer     | [Requests](#requests)                               |
 | `lb-nav-link`     | Developer     | [Links](#links)                                     |
+| `lb-query-parm`   | Developer     | [Query parms](#query-parms)                         |
+| `lb-query-parm-push` | Developer  | [Query parms](#query-parms)                         |
 | `lb-pending`      | Hub           | [Request state](#request-state)                     |
 | `lb-error`        | Hub           | [Request state](#request-state)                     |
 | `lb-row-count`    | Hub           | [Request state](#request-state)                     |

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

@@ -73,7 +73,9 @@ sits directly inside `<body>`, with banner, nav, footer and `<main>` inside
 it, so Loadbare can act on all of them.
 
 A navigation anchor's `href` is a path, and the path names a page:
-`/members` shows `members.page.html`. A bare `/` resolves to `index`, so the
+`/members` shows `members.page.html`. A query string on it is kept, so
+`/members?team=Engines` opens the page narrowed; see
+[Query parms](./data-binding.md#query-parms). A bare `/` resolves to `index`, so the
 landing page is the one named `index.page.html`. An anchor without
 `lb-nav-link` is left alone and behaves like any other link.
 
@@ -100,10 +102,10 @@ shows a value — so a chrome displays the current page with no code at all:
 | Cell         | Holds                                                     |
 |--------------|-----------------------------------------------------------|
 | `page-label` | The text of the `lb-nav-link` anchor for the path, or empty if none |
-| `page-uri`   | The path as the browser has it, such as `/members`        |
+| `page-uri`   | The path and query string as the browser has them, such as `/members?team=Engines` |
 
 The label is the nav's. The hub takes it from the first `lb-nav-link`
-anchor whose `href` names the current page, so a click, a reload and the
+anchor whose path names the current page, whatever its query string, so a click, a reload and the
 back button all land the same text, and a path no anchor names lands an
 empty label. A chrome that shows the label somewhere fixed should expect
 that case for a page reachable only by URL.

package/skills/loadbare-app/references/data-binding.md

@@ -304,6 +304,39 @@ Leave `lb-action` off a widget inside an `lb-row-insert` or `lb-row-update`
 form. The form reads every `lb-cell` in it on submit, so a widget that also
 sent its own would write the same edit twice.
 
+## Query parms
+
+A control that narrows what the page shows writes its value into the query
+string instead of sending a request. `lb-query-parm` names the parm:
+
+```html
+<select lb-query-parm="team">
+  <option value="">Every team</option>
+  <option value="Engines">Engines</option>
+</select>
+```
+
+On `change` the hub sets that one parm in the URL, leaving every other parm
+alone, and takes it out when the value is empty. The write replaces the
+current history entry; add `lb-query-parm-push` to push one instead. The page
+then loads at the new URL, exactly as a cold load of it would, without
+replacing its DOM.
+
+After every load the hub lands each parm on the control that writes it, and
+an absent parm lands empty, so the control shows what the address bar says.
+
+A control that writes a query parm sends no request, and one that also
+carries `lb-action` has that request refused.
+
+A request can write parms too, when only the write knows their value, such as
+the key of a row it inserted; see
+[refresh and patch](./page-files.md#refresh-and-patch). The page loads at
+them in the same round trip, and they land on their controls as above.
+
+The server hands the parms to `contextFor`; see
+[the Express server](./server.md#database-layer). See
+[Query parms](./TECHREF-1.0.md#query-parms) for the whole rule.
+
 ## Conditional rendering
 
 Loadbare ships static HTML and hydrates elements that are already in the

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

@@ -192,3 +192,42 @@ resetRoster: {
   refresh: ["roster"],
 },
 ```
+
+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:
+
+```ts
+// src/pages/accounts.requests.ts
+import { queryParms, 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 queryParms({ acct: String(id) });
+        },
+        refresh: [],
+      },
+      rowDelete: {
+        run: async (ctx, { key }) => {
+          await ctx.db.deleteAccount(key);
+          if (key === ctx.acct) return queryParms({ acct: "" });
+        },
+        refresh: ["accounts"],
+      },
+    },
+  },
+};
+```
+
+Only parms: `run` cannot send the browser to another page. The loaded page
+reads the new parms through `contextFor` like any others; see
+[the Express server](./server.md#database-layer).

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

@@ -137,6 +137,23 @@ declare module "@loadbare/app/server" {
 }
 ```
 
+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, 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 [refresh and patch](./page-files.md#refresh-and-patch). 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).

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

@@ -56,7 +56,8 @@ action carries a value.
 | ---------- | ----- |
 | `exp-label` | the visible `<label>` text |
 
-Requires `lb-action` — a change with none logs and sends nothing.
+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`
 
@@ -81,8 +82,11 @@ hand. The author supplies the row template inside the widget (via
   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`.
+  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.