@loadbare/app 0.19.0 → 0.20.0

package/docs/reference/chrome.md

@@ -60,6 +60,7 @@ Everything else is optional:
 |-------------------------------------------|---------------------------------------------|
 | `<link rel="stylesheet" href="/app.css">` | The bundled stylesheet                      |
 | `<a lb-url-link>`                         | A link between pages                        |
+| `<a lb-url-link lb-url-parm>`             | A link carrying columns of its row          |
 | `lb-query="lb-url"`                       | Where the page is — see below               |
 | `<dialog lb-url-unknown>`                 | A message when a URL matches no page        |
 | Custom elements                           | The chrome, decomposed into element files   |
@@ -103,6 +104,12 @@ server's row lands, so a chrome shows where the page is with no code:
 | `lb-page-unknown` | `true` when no page's stub matches the path             |
 | Any other name    | The query parm of that name, or empty when it is absent |
 
+The path names a page, never a resource: `/accounts/42` is not a way to
+reach account 42, and an application designs no endpoints. The query string
+describes what that page has on screen, `/accounts?acct=23`, and never
+commands. The server remembers nothing about the view, so a URL reloads,
+bookmarks and mails as the same view.
+
 A path names a page by its stub: `/members` shows `members.page.html`, and
 `/` shows `index.page.html`. A page's title is the text of the `<title>` its
 page file carries; see [page files](./page-files.md#the-page-title). The hub
@@ -139,11 +146,56 @@ Write `lb-url-link` on an `<a>` to move between pages:
 </nav>
 ```
 
-On a plain primary click, the hub pushes a history entry for the `href`,
-path and query string both, and shows the page it names. A click with a
-modifier key or another button, and a link without `lb-url-link`, behave as
-the browser has them behave. Back and Forward show the page at the URL they
-arrive at.
+On a plain primary click, the first button with no modifier key and not
+already handled, the hub pushes a history entry for the `href`, path and
+query string both, and shows the page it names. Any other click, and a link
+without `lb-url-link`, behave as the browser has them behave, so leaving the
+application is the default and staying in it is the opt-in. The attribute
+takes no value. Back and Forward show the page at the URL they arrive at.
+
+Path space is flat: `/members` shows `members.page.html` wherever under
+`--src` it sits. The query string is kept, so
+`/transactions?date_begin=2026-09-01` opens the page narrowed to those
+dates.
+
+### A link from a row
+
+Write `lb-url-parm` on an `<a lb-url-link>` inside a row to carry columns
+of that row to the page the link names. It names columns, separated by
+commas, and the hub adds each to the link's query string as the parm of the
+same name:
+
+```html
+<table lb-query="topics">
+  <template>
+    <tr>
+      <td lb-column="title"></td>
+      <td><a href="/events" lb-url-link lb-url-parm="topic_id" lb-column="times_presented"></a></td>
+    </tr>
+  </template>
+</table>
+```
+
+In topic 5's row the link is `<a href="/events?topic_id=5">`. The `href` is
+written when the row lands and rewritten when it changes, so hovering,
+copying, a middle click and a plain click all go to the same place.
+
+- The parm is the column. Where the names differ, the row's query renames
+  the column in its SQL: `select id as topic_id`.
+- The hub reads the row it holds, so a column no element shows is carried
+  as well as one that is.
+- The `href` as written is the base. Its path, its parms and its fragment
+  are kept, and a named column replaces a parm of the same name.
+- A null, empty or missing column leaves its parm off, as an empty value
+  takes a parm out of the URL. A string is written as it is, a number or a
+  boolean as JSON writes it, and any other value is left off and reported
+  on the console, as is a named column the row does not have.
+- The row is the nearest around the link: a live row, or an element a `row`
+  landed on.
+
+`lb-url-parm` goes only on a link carrying `lb-url-link`, since the parms it
+writes are the application's own; see
+[The markup checks](./data-binding.md#the-markup-checks).
 
 ### Query parms
 
@@ -170,11 +222,28 @@ pushes one instead when the element carrying `lb-request` also carries
 
 The hub answers the request itself, with no round trip, then reloads the
 page's queries at the new URL. The page stays in place, and rows that come
-back keep their place.
+back keep their place. A request that leaves the URL as it was does
+nothing. `lb-page-label` and `lb-page-unknown` are the hub's, and a request
+never sets them.
+
+A request that gives `lb-path` a new value enters that page, pushes a
+history entry, and the new URL carries only the query parms the request
+names.
 
 A control whose column the URL does not carry lands empty, so every control
 inside `lb-query="lb-url"` shows what the address bar says, after a reload
-and after Back alike.
+and after Back alike
+([miswart](../miswarts.md#lb-url-lands-every-parm-it-names)).
+
+Loadbare assigns no parm a meaning, and a column of `lb-url` whose name
+begins with `lb-` is never a query parm.
+
+A query parm is user input. 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`
+influences what a query returns. Validate it where the application reads
+it; a per-session database role means an id outside the caller's reach
+finds nothing.
 
 An order or a filter the hub applies to rows the page already holds is not
 a query parm. It is a [choice](./data-binding.md#choices), which holds until
@@ -198,8 +267,13 @@ show the path:
 ```
 
 When no page's stub matches the path, `lb-page-unknown` is `true`,
-`lb-page-label` is null, `<main>` keeps the page it had, and the hub calls
-`showModal()` on the dialog.
+`lb-page-label` is null, `<main>` keeps the page it had, the hub calls
+`showModal()` on the dialog, and reports the path to the console. A chrome
+with no dialog shows nothing. `lb-url` lands before the page is looked up,
+so the dialog shows the path by naming it like any other element.
+
+Every route gets the same document, so an unknown path is found out in the
+browser after a successful 200, and there is no server-delivered 404.
 
 `@loadbare/widgets` ships this dialog as `<lb-unknown-page>`, for a chrome
 that would rather write one tag; see

package/docs/reference/css.md

@@ -41,7 +41,6 @@ Serve it at `/app.css` and link it from the chrome:
 See [`chrome.html`](./chrome.md) for the link, [The Express
 server](./server.md) for the route, and
 [`loadbare-app-build`](./builder.md#running-the-builder) for `--minify`.
-</content>
 
 ## Selecting what the hub stamps
 

package/docs/reference/custom-elements.md

@@ -250,30 +250,8 @@ takes part in data binding in one of four ways: it is a control, it renders
 a value, it sends a request, or it holds rows.
 
 Import every Loadbare name from `@loadbare/app/constants`, and never write
-one as a string literal:
-
-| Constant               | Value                |
-|------------------------|----------------------|
-| `ATTR_QUERY`           | `lb-query`           |
-| `ATTR_COLUMN`          | `lb-column`          |
-| `ATTR_SHOW`            | `lb-show`            |
-| `ATTR_REQUEST`         | `lb-request`         |
-| `ATTR_COLUMN_VALUE`    | `lb-column-value`    |
-| `ATTR_KEY_VALUE`       | `lb-key-value`       |
-| `ATTR_ROW_LIVE`        | `lb-row-live`        |
-| `LIVE_ROW`             | `[lb-row-live]`      |
-| `ATTR_QUERY_ROW_COUNT` | `lb-query-row-count` |
-| `ATTR_REQUEST_PENDING` | `lb-request-pending` |
-| `ATTR_REQUEST_ERROR`   | `lb-request-error`   |
-| `REQUEST_ROW_INSERT`, `REQUEST_ROW_UPDATE`, `REQUEST_ROW_DELETE` | The requests Loadbare provides |
-| `LB_ROW_REQUESTS`      | All three, in one array |
-| `LB_EVENT_NAME`        | `lb-request`, the event every request travels as |
-| `LB_DONE_EVENT_NAME`   | `lb-request-done`, the event that says how it turned out |
-| `SHOW_NOT`             | `!`, written before a column in `lb-show` |
-| `URL_QUERY`            | `lb-url`             |
-| `CHOICES_QUERY`        | `lb-choices`         |
-| `URL_COLUMN_PATH`, `URL_COLUMN_PAGE_LABEL`, `URL_COLUMN_PAGE_UNKNOWN` | `lb-path`, `lb-page-label`, `lb-page-unknown` |
-| `LB_RESERVED_PREFIX`   | `lb-`                |
+one as a string literal: `ATTR_COLUMN_VALUE` rather than `"lb-column-value"`.
+[Constants](./names.md#constants) lists them all.
 
 A custom element reads `lb-` attributes and never assigns one. The developer
 writes them in markup, and the hub and the builder write their stamps.
@@ -290,7 +268,7 @@ Each direction has one mechanism for each kind of message:
 
 | Direction      | What                                       | How                         | Today |
 |----------------|--------------------------------------------|-----------------------------|-------|
-| Hub to element | State that lasts                           | An attribute the hub stamps | `lb-column-value`, `lb-key-value`, `lb-query-row-count`, `lb-group-*`, `lb-row-*`, `lb-request-pending`, `lb-request-error`, `lb-request-refused` |
+| Hub to element | State that lasts                           | An attribute the hub stamps | `lb-column-value`, `lb-key-value`, `lb-query-row-count`, `lb-query-unsorted-count`, `lb-query-order`, `lb-group-*`, `lb-row-*`, `lb-request-pending`, `lb-request-error`, `lb-request-refused` |
 | Hub to element | State the platform already names           | A property                  | A control's `value` |
 | Hub to element | What the hub did                           | An optional `lb` method     | `lbAttached`, `lbRowsLanded`, `lbRequestDone`, `lbDetached` |
 | Hub to element | A moment an element started                | A bubbling event            | `lb-request-done` |
@@ -649,7 +627,8 @@ had there hears the event, and no custom element the hub has removed hears
 ### Holding rows
 
 The hub lands every row template itself, places every row by the query's
-order, and builds every group the markup's group templates describe; see
+order (see [Rows the user is working in](./data-binding.md#rows-the-user-is-working-in)
+for when it does not), and builds every group the markup's group templates describe; see
 [Order](./data-binding.md#order) and [Groups](./data-binding.md#groups). A
 plain element carrying `lb-query` with a row template inside it needs no
 code, so a custom element holds rows only to do something with them once
@@ -677,12 +656,12 @@ Everything else is the hub's:
 |-------------|----------------------------------------------------------|
 | Cloning     | Clones the row template once per new key                 |
 | Matching    | Fills the live row already showing that key, when its values changed |
-| Placing     | Places every live row by the user's order or the query's |
+| Placing     | Places every live row by the user's order or the query's, and leaves them where they stand for an edit from inside the list |
 | Filtering   | Hides a row the user's filter does not pass, and a group whose rows are all hidden |
 | Grouping    | Builds a group where the order breaks, keeps it while its run goes on, and removes it with its last row |
 | Removing    | Marks the live rows the response says are gone as leaving, and removes them |
 | Stamping    | Stamps each live row with `lb-row-live`, `lb-key-value`, and what happened to it |
-| Counting    | Stamps `lb-query-row-count` with the number of live rows showing |
+| Counting    | Stamps `lb-query-row-count` with the number of live rows showing, `lb-query-unsorted-count` with the number out of order, and `lb-query-order` with the order placing them |
 
 `lb-options.browser.ts` and `lb-table.browser.ts` in
 [`@loadbare/widgets`](./widgets.md) are two uses of `lbRowsLanded`: one