@loadbare/app 0.19.1 → 0.21.0

package/docs/reference/custom-elements.md

@@ -268,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` |
@@ -627,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
@@ -655,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

package/docs/reference/data-binding.md

@@ -2,7 +2,7 @@
 
 A page shows server data by naming queries and columns in its HTML, and asks
 the server to change that data by naming requests. The developer writes
-sixteen `lb-` attributes. The server declares every query a page may show and
+seventeen `lb-` attributes. The server declares every query a page may show and
 every request it may send, and refuses anything it has not declared.
 
 Everything is a query. A query is a name for rows, of kind `row` or `rows`,
@@ -54,6 +54,7 @@ each with its key, and permits the three requests on `roster`; see
 | `lb-select`      | A checkbox in a row template  | Nothing: it selects its live row; see [Selecting rows](#selecting-rows) |
 | `lb-request`     | Any element                   | The request it sends when it commits           |
 | `lb-url-link`    | An `<a>`                      | A link between pages; see [chrome](./chrome.md#links) |
+| `lb-url-parm`    | An `<a lb-url-link>` in a row | Columns of the row its `href` carries as parms; see [chrome](./chrome.md#a-link-from-a-row) |
 | `lb-url-push`    | An element with `lb-request`  | A URL change that pushes a history entry       |
 | `lb-url-unknown` | A `<dialog>` in the chrome    | The dialog for a URL that names no page        |
 
@@ -66,8 +67,10 @@ builder writes a stamp, and a stylesheet or a custom element reads it.
 | `lb-key-value`       | The key of a live row, or of a `row` landed on an element |
 | `lb-row-live`        | The element is a live row                          |
 | `lb-query-row-count` | The number of live rows an element shows           |
+| `lb-query-unsorted-count` | The number of them out of order; see [Rows the user is working in](#rows-the-user-is-working-in) |
+| `lb-query-order`     | The order placing them; see [Order](#order)        |
 | `lb-group-live`, `lb-group-column`, `lb-group-value` | A group, the column it breaks on, and its value; see [Groups](#groups) |
-| `lb-row-created`, `lb-row-changed`, `lb-row-moved`, `lb-row-requested` | What happened to a row; see [What happened to a row](#what-happened-to-a-row) |
+| `lb-row-created`, `lb-row-changed`, `lb-row-moved`, `lb-row-requested`, `lb-row-unsorted` | What happened to a row; see [What happened to a row](#what-happened-to-a-row) |
 | `lb-row-leaving`, `lb-group-leaving` | A row or group on its way out      |
 | `lb-row-editing`     | The row a form is pointed at; see [Editing a row in one form](#editing-a-row-in-one-form) |
 | `lb-row-selected`    | A row whose `lb-select` is ticked                  |
@@ -147,6 +150,10 @@ no row fills.
 | Any other custom element                             | `lb-column-value` only                  |
 | Any other element                                    | Its text content, and `lb-column-value` |
 
+A column lands in one attribute besides: the `href` of a link carrying
+`lb-url-parm` that names it; see
+[A link from a row](./chrome.md#a-link-from-a-row).
+
 A control is an `<input>`, `<select>` or `<textarea>`, or a form-associated
 custom element with a `value` property that fires `change`. The hub sets a
 control's `value`, and gathers it back under the same column. A custom
@@ -218,7 +225,9 @@ places it immediately before the template:
 The hub matches each row to a live row by its key. All rows decide
 membership: a live row whose key did not arrive leaves. A patch changes only
 the rows it names, and every other live row keeps its content. The hub
-places every live row by the query's order; see [Order](#order). A row that
+places live rows by the query's order, except that an edit from inside the
+list leaves them where they stand; see [Order](#order) and
+[Rows the user is working in](#rows-the-user-is-working-in). A row that
 does not pass the user's filter is `hidden`; see [Filters](#filters).
 
 A live row whose values arrive as it already shows them is not filled
@@ -290,10 +299,71 @@ numerically whatever JSON type its values arrive as, and a value that is no
 value of its declared type compares as `null` does. `readAs` in
 `@loadbare/app/types` is the rule the hub applies.
 
+The element carrying `lb-query` carries `lb-query-order`, the order
+placing its rows as an order's text, the user's when one is chosen and
+the server's otherwise. Rows with no order carry none.
+
 Rows that compare equal keep the order they arrived in, a patch's new rows
 after the rows already showing. A row moves only when the order
 puts it somewhere else, so all rows landing again unchanged move nothing.
 
+### Rows the user is working in
+
+A landing that answers a request sent from inside a list moves none of that
+list's rows. The request is from inside the list when the list is the
+nearest element carrying `lb-query` around the element that sent it: a
+control in a live row, or a ghost row. A form that
+[`--lb-edit`](#editing-a-row-in-one-form) pointed at a live row finishes an
+edit begun in that row, so its request is from inside the row's list,
+wherever the form sits. Any other form elsewhere on the page is not inside
+the list. A user who changes a value sees the value change, and the row
+stays where they were working:
+
+| The answer                               | The row                                           |
+|------------------------------------------|---------------------------------------------------|
+| Changes a column the order reads         | Stays where it stands                             |
+| Creates a row                            | Goes after the last row of its group, or last of all |
+| Drops a row                              | Leaves                                            |
+| Changes a row so the filter hides it     | Stays showing                                     |
+| Changes the column its group breaks on   | Stays under its group's heading                   |
+
+A patch and all rows answering the same edit land the same way. A row left
+where the order or the filter would not leave it is stamped
+`lb-row-unsorted`, and the element carrying `lb-query` carries
+`lb-query-unsorted-count`, the number of such rows. Another element naming
+the same query places its rows by the order: the user was not working
+there.
+
+The rows are placed by the order again, and every `lb-row-unsorted` is
+cleared, when the user asks: when the page loads, when the user's order or
+filter changes, or on `--lb-sort`. A button names the list with HTML's
+`commandfor`, and a stylesheet shows it only while it has something to do:
+
+```html
+<div id="roster" lb-query="roster">
+  <button type="button" class="resort" commandfor="roster" command="--lb-sort">Re-sort</button>
+  <ul>
+    <template><li><input lb-column="name" lb-request="lb-row-update" /></li></template>
+  </ul>
+</div>
+```
+
+```css
+.resort {
+  display: none;
+}
+[lb-query-unsorted-count]:not([lb-query-unsorted-count="0"]) .resort {
+  display: revert;
+}
+```
+
+`--lb-sort` places the rows the hub holds, with no round trip. Aimed at an
+element that carries no `lb-query`, or shows no rows the hub holds, it is
+reported to the console. A custom element that reorders rows by a request of
+its own dispatches the same command on the list once the answer lands, with
+`new CommandEvent("command", { command: "--lb-sort" })`: the user asked for
+the move.
+
 ### Filters
 
 Write `lb-filter` on the element carrying `lb-query`, naming the columns of
@@ -311,7 +381,9 @@ its rows the user may filter, separated by commas. The column of
 ```
 
 A row that does not pass every filter is `hidden`, and a ticked `lb-select`
-in it is cleared. A group whose rows are all hidden is hidden too
+in it is cleared. A row an edit from inside the list changed stays showing
+until the rows are placed again; see
+[Rows the user is working in](#rows-the-user-is-working-in). A group whose rows are all hidden is hidden too
 ([miswart](../miswarts.md#rows-hidden-by-a-filter)). An empty
 choice filters nothing.
 
@@ -393,7 +465,9 @@ Content after the nested template lands after the group's rows, which is
 where a group's footer goes.
 
 A heading is filled from its group's first row, so it may show a column
-other than the one the group breaks on. The hub stamps each top-level
+other than the one the group breaks on. A row an edit from inside the list
+moved to another group stays under its old heading, and the heading shows
+the row as it stood, until the rows are placed again. The hub stamps each top-level
 element of a group with `lb-group-live`, `lb-group-column` and
 `lb-group-value`. A row creates its group, and a group leaves with its last
 row. When the order changes, a group whose run goes on is kept and moved,
@@ -442,6 +516,7 @@ Every change to a list is one a stylesheet can see:
 | `lb-row-changed`   | Its values changed when the hub last touched it        |
 | `lb-row-moved`     | Its values changed, and it now stands elsewhere        |
 | `lb-row-requested` | `created`, `changed` or `moved` by this page's request |
+| `lb-row-unsorted`  | Stands where the order would not put it                |
 | `lb-row-leaving`   | A row on its way out                                   |
 | `lb-group-leaving` | A group on its way out                                 |
 
@@ -450,6 +525,9 @@ The hub touches a row when an answer names it. `lb-row-created`,
 applied again is removed and added as two changes, so an animation keyed to
 it plays again. `lb-row-requested` is cleared at every landing of the row's
 query, and set only by a landing that answers a request from the page.
+`lb-row-unsorted` is a state, not an event: it stays until the rows are
+placed by the order; see
+[Rows the user is working in](#rows-the-user-is-working-in).
 
 A row or a group that leaves loses `lb-row-live` or `lb-group-live`, takes
 `lb-row-leaving` or `lb-group-leaving` and `inert`
@@ -498,7 +576,9 @@ insert form above: it sits inside `lb-query="roster"` so its request is for
 
 The hub stamps every element that holds a row template with
 `lb-query-row-count`, the number of live rows it shows. A row a filter
-hides is not counted. An empty query is a stylesheet rule:
+hides is not counted. Beside it, `lb-query-unsorted-count` is the number of
+rows out of order; see
+[Rows the user is working in](#rows-the-user-is-working-in). An empty query is a stylesheet rule:
 
 ```html
 <div lb-query="roster">
@@ -956,6 +1036,12 @@ An `lb-show` in the form reads from the row it was pointed at. With no row,
 every column is null, so `lb-show="!id"` shows only while entering a new
 row.
 
+A request from a form Edit pointed is sent from inside the row's list, so
+the row stays where the user was working, even when the filter would now
+hide it or the order would move it; see
+[Rows the user is working in](#rows-the-user-is-working-in). A form New
+pointed is not inside any list, and its rows are placed by the order.
+
 A successful request from the form lets it go, as Cancel does: the form
 empties, its controls return to their defaults, and the stamps go. A failed
 one leaves the form as the user had it, to correct.
@@ -980,8 +1066,8 @@ submits the form instead.
 
 A command the hub cannot carry out is reported to the console: Edit from
 outside a live row of the form's query, Edit for a key the hub holds no row
-for, and any command aimed at an element that is not a form carrying
-`lb-query`.
+for, and any of these three commands aimed at an element that is not a form
+carrying `lb-query`.
 
 ### Selecting rows
 
@@ -1228,7 +1314,7 @@ The developer writes `lb-` attributes in markup, and script never assigns
 them. The builder checks the markup of the chrome and of every page, after
 expansion, and refuses to build:
 
-- an `lb-` attribute that is not one of the sixteen the developer writes;
+- an `lb-` attribute that is not one of the seventeen the developer writes;
   `lb-exp-slot` and `lb-exp-template` are consumed by expansion and never
   reach the check
 - `lb-request` naming an `lb-` request other than the three Loadbare provides
@@ -1241,6 +1327,9 @@ expansion, and refuses to build:
   a form's own when the form carries `lb-query`, and otherwise the nearest
   `lb-query` around the element
 - `lb-url-link` on anything but an `<a>`
+- `lb-url-parm` on anything but an `<a>` carrying `lb-url-link`, naming no
+  column, naming columns not separated by commas or one beginning `lb-`, or
+  with no row around it
 - `lb-url-push` on an element without `lb-request`
 - `lb-url-unknown` on anything but a `<dialog>`, or outside `<lb-hub>`
 - `lb-show` on a `<template>`, or on a row template's root
@@ -1250,8 +1339,8 @@ expansion, and refuses to build:
   no column
 - `lb-select` on anything but `<input type="checkbox">`, outside a row
   template, or beside `lb-column` or `lb-request`
-- a `command` beginning `--lb-` that is not one of the three commands
-- one of the three commands with no `commandfor`
+- a `command` beginning `--lb-` that is not one of the four commands
+- one of the four commands with no `commandfor`
 - `lb-group` on anything but a `<template>`, or on one holding no
   `<template>` for its contents
 - an aggregate on a `<template>`, or any but `lb-count` naming no column

package/docs/reference/names.md

@@ -66,7 +66,7 @@ A widget package declares these.  An application never does.
 
 ## Attributes
 
-The developer writes sixteen attributes in pages and the chrome, and the
+The developer writes seventeen attributes in pages and the chrome, and the
 builder refuses any other `lb-` attribute there.  `lb-exp-slot` and
 `lb-exp-template` are written for expansion, which removes them before the
 check.  The hub and the builder write the rest, as stamps, and script never
@@ -84,6 +84,7 @@ assigns one.
 | `lb-select`          | Developer       | [Selecting rows](./data-binding.md#selecting-rows)               |
 | `lb-request`         | Developer       | [Requests](./data-binding.md#requests)                           |
 | `lb-url-link`        | Developer       | [Links](./chrome.md#links)                                       |
+| `lb-url-parm`        | Developer       | [A link from a row](./chrome.md#a-link-from-a-row)               |
 | `lb-url-push`        | Developer       | [Query parms](./chrome.md#query-parms)                           |
 | `lb-url-unknown`     | Developer       | [An unknown page](./chrome.md#an-unknown-page)                   |
 | `lb-exp-slot`        | Developer, consumed by expansion | [The slot](./custom-elements.md#the-slot)       |
@@ -92,6 +93,8 @@ assigns one.
 | `lb-key-value`       | Hub             | [Landing](./data-binding.md#landing), [Editing a row in one form](./data-binding.md#editing-a-row-in-one-form) |
 | `lb-row-live`        | Hub             | [Landing](./data-binding.md#landing)                             |
 | `lb-query-row-count` | Hub             | [Counting rows](./data-binding.md#counting-rows)                 |
+| `lb-query-unsorted-count`, `lb-row-unsorted` | Hub | [Rows the user is working in](./data-binding.md#rows-the-user-is-working-in) |
+| `lb-query-order`     | Hub             | [Order](./data-binding.md#order)                                 |
 | `lb-group-live`, `lb-group-column`, `lb-group-value` | Hub | [Groups](./data-binding.md#groups)                       |
 | `lb-row-created`, `lb-row-changed`, `lb-row-moved`, `lb-row-requested` | Hub | [What happened to a row](./data-binding.md#what-happened-to-a-row) |
 | `lb-row-leaving`, `lb-group-leaving` | Hub | [What happened to a row](./data-binding.md#what-happened-to-a-row) |
@@ -135,6 +138,7 @@ Loadbare/app owns every value of HTML's `command` attribute beginning with
 | `--lb-edit`    | [Editing a row in one form](./data-binding.md#editing-a-row-in-one-form) |
 | `--lb-new`     | [Editing a row in one form](./data-binding.md#editing-a-row-in-one-form) |
 | `--lb-release` | [Editing a row in one form](./data-binding.md#editing-a-row-in-one-form) |
+| `--lb-sort`    | [Rows the user is working in](./data-binding.md#rows-the-user-is-working-in) |
 
 ## Reserved tags
 
@@ -191,6 +195,8 @@ imports them rather than writing a string.
 | `ATTR_ROW_LIVE`           | `lb-row-live`                           |
 | `LIVE_ROW`                | `[lb-row-live]`, the selector for a live row |
 | `ATTR_QUERY_ROW_COUNT`    | `lb-query-row-count`                    |
+| `ATTR_QUERY_UNSORTED_COUNT` | `lb-query-unsorted-count`             |
+| `ATTR_QUERY_ORDER`        | `lb-query-order`                        |
 | `ATTR_GROUP`              | `lb-group`                              |
 | `ATTR_GROUP_LIVE`         | `lb-group-live`                         |
 | `ATTR_GROUP_COLUMN`       | `lb-group-column`                       |
@@ -209,6 +215,7 @@ imports them rather than writing a string.
 | `ATTR_ROW_MOVED`          | `lb-row-moved`                          |
 | `ATTR_ROW_REQUESTED`      | `lb-row-requested`                      |
 | `REQUESTED_CREATED`, `REQUESTED_CHANGED`, `REQUESTED_MOVED` | `created`, `changed`, `moved` |
+| `ATTR_ROW_UNSORTED`       | `lb-row-unsorted`                       |
 | `ATTR_ROW_LEAVING`        | `lb-row-leaving`                        |
 | `ATTR_GROUP_LEAVING`      | `lb-group-leaving`                      |
 | `ATTR_REQUEST`            | `lb-request`                            |
@@ -218,8 +225,8 @@ imports them rather than writing a string.
 | `ATTR_REQUEST_ERROR`      | `lb-request-error`                      |
 | `ATTR_REQUEST_REFUSED`    | `lb-request-refused`                    |
 | `LB_REFUSAL_STATUS`       | `422`                                   |
-| `COMMAND_EDIT`, `COMMAND_NEW`, `COMMAND_RELEASE` | `--lb-edit`, `--lb-new`, `--lb-release` |
-| `LB_COMMANDS`             | All three commands                      |
+| `COMMAND_EDIT`, `COMMAND_NEW`, `COMMAND_RELEASE`, `COMMAND_SORT` | `--lb-edit`, `--lb-new`, `--lb-release`, `--lb-sort` |
+| `LB_COMMANDS`             | All four commands                       |
 | `LB_COMMAND_PREFIX`       | `--lb-`                                 |
 | `ATTR_ROW_EDITING`        | `lb-row-editing`                        |
 | `ATTR_SELECT`             | `lb-select`                             |
@@ -238,13 +245,14 @@ imports them rather than writing a string.
 | `URL_COLUMN_PAGE_LABEL`   | `lb-page-label`                         |
 | `URL_COLUMN_PAGE_UNKNOWN` | `lb-page-unknown`                       |
 | `ATTR_URL_LINK`           | `lb-url-link`                           |
+| `ATTR_URL_PARM`           | `lb-url-parm`                           |
 | `ATTR_URL_PUSH`           | `lb-url-push`                           |
 | `ATTR_URL_UNKNOWN`        | `lb-url-unknown`                        |
 | `ATTR_EXP_SLOT`           | `lb-exp-slot`                           |
 | `ATTR_EXP_TEMPLATE`       | `lb-exp-template`                       |
 | `ATTR_PAGE`               | `lb-page`                               |
 | `ATTR_PAGE_TITLE`         | `lb-page-title`                         |
-| `DEVELOPER_ATTRIBUTES`    | The sixteen attributes a developer writes |
+| `DEVELOPER_ATTRIBUTES`    | The seventeen attributes a developer writes |
 | `HUB_TAG_NAME`            | `lb-hub`                                |
 | `LB_ENDPOINT`             | `/lb`                                   |
 | `LB_REQUEST_TIMEOUT_MS`   | `10000`                                 |

package/docs/reference/page-files.md

@@ -382,7 +382,8 @@ one row dropped, one row edited — and leave `refresh` empty. A refreshed
 A change that seems to need a refresh usually has a patch:
 
 - A row whose position changes: the hub places it by the query's
-  [order](./data-binding.md#order).
+  [order](./data-binding.md#order), or leaves it where the user is working
+  when the request came from inside its list; a refresh would do the same.
 - A group that appears or goes: the hub makes a group with its first row
   and removes it with its last, so no row stands in for an empty one.
 - A row whose other columns change with the edit: re-read the row and patch

package/docs/reference/widgets.md

@@ -155,7 +155,9 @@ row, the row template, and optionally a footer, each as a `<template>`:
 | `<template lb-exp-template="foot">` | The `<tfoot>`                         |
 | Any other `<template>`            | The row or group template, in the `<tbody>` |
 
-- The hub places the rows by the query's order and builds its groups. The
+- The hub places the rows by the query's order and builds its groups, and
+  leaves them where they stand for an edit from inside the table; see
+  [Rows the user is working in](./data-binding.md#rows-the-user-is-working-in). The
   rows land in the one `<tbody>`, so a group here is a heading row with its
   rows after it.
 - `lb-order` and `lb-filter` go on the `lb-table` itself, beside
@@ -174,6 +176,13 @@ row, the row template, and optionally a footer, each as a `<template>`:
 - Text selected in a cell whose `lb-column` the table's `lb-filter` names
   becomes that column's filter in `lb-choices`: `=` for the whole text,
   `^=` from its start, `$=` up to its end, `*=` otherwise.
+- The heading of the order's leading column carries a triangle for the
+  direction, read from [`lb-query-order`](./data-binding.md#order). A
+  heading's column is the `lb-column` in the cell at its position in the row
+  template. While rows stand out of order the triangle carries
+  `data-unsorted` and a click on its heading re-sorts. With `lb-order`, a
+  click on the sorted heading reverses the order and a click on another
+  sorts by its column. Not on a grouped table.
 
 ## `lb-confirm`
 

package/docs/testing.md

@@ -208,7 +208,9 @@ evidence here.
 - `lb-query-row-count` counts the rows showing, so all rows and a patch
   ending in the same state report the same number, and a row a filter hides
   is not counted
-- the order places all rows and a patch alike, groups come and go with
+- the order places all rows and a patch alike, except where an edit came
+  from inside the list, which leaves its rows standing and stamped until
+  the user asks for the order; groups come and go with
   their rows to any depth, aggregates follow every landing, and every change
   leaves a stamp a stylesheet can see (`lb-order.test.ts`)
 - a filter's text reads and passes values as documented, and a choice of
@@ -279,6 +281,8 @@ What the hub is tested for here:
   `lb-page-label`, and a column per query parm, and sets the document title
 - `lb-url-link` pushes state and swaps the page on a plain primary click,
   `popstate` reverses it, and an ordinary anchor is left alone
+- `lb-url-parm` writes a link's `href` from its row as held, starting from
+  the `href` as written every time (`lb-apply.test.ts`)
 - a control inside `lb-query="lb-url"` writes its parm, replacing the history
   entry or pushing one with `lb-url-push`, and the page's queries reload
 - an `lb-url` item in a server answer writes the URL and lands the page

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@loadbare/app",
   "description": "High performance web app framework for server-bound applications",
-  "version": "0.19.1",
+  "version": "0.21.0",
   "type": "module",
   "files": [
     "dist",

package/skills/loadbare-app/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: loadbare-app
-description: Build server-bound web applications with Loadbare/app. Covers the file conventions the builder finds by name (`chrome.html`, `*.page.html`, `*.queries.ts`, `*.requests.ts`, `imports.ts`, `<tag>.html`, `<tag>.browser.ts`); the `lb-*` attribute vocabulary that lands query rows on HTML and issues requests (`lb-query`, `lb-column`, `lb-show`, `lb-request`); queries declared with `row(key, run)` and `rows(key, run)`; the URL as the hub's own query `lb-url`, with `lb-url-link`, `lb-url-push` and `lb-url-unknown`; the user's order and filters as the hub's query `lb-choices`, read by `lb-order` and `lb-filter`; one form pointed at a row by the `--lb-edit`, `--lb-new` and `--lb-release` commands; build-time expansion with `exp-*` parameters, `lb-exp-slot` and `lb-exp-template`; custom elements as form-associated controls and row hosts; the Express wiring with `hubRoutes`; and the `@loadbare/widgets` library. Use whenever a task involves `@loadbare/app`, `@loadbare/widgets`, `loadbare-app-build`, an `lb-` attribute, or a page, query, request or custom element file in a Loadbare application. The model is not React, htmx or REST, and cannot be inferred from them.
+description: Build server-bound web applications with Loadbare/app. Covers the file conventions the builder finds by name (`chrome.html`, `*.page.html`, `*.queries.ts`, `*.requests.ts`, `imports.ts`, `<tag>.html`, `<tag>.browser.ts`); the `lb-*` attribute vocabulary that lands query rows on HTML and issues requests (`lb-query`, `lb-column`, `lb-show`, `lb-request`); queries declared with `row(key, run)` and `rows(key, run)`; the URL as the hub's own query `lb-url`, with `lb-url-link`, `lb-url-parm`, `lb-url-push` and `lb-url-unknown`; the user's order and filters as the hub's query `lb-choices`, read by `lb-order` and `lb-filter`; one form pointed at a row by the `--lb-edit`, `--lb-new` and `--lb-release` commands; re-sorting a list with `--lb-sort`; build-time expansion with `exp-*` parameters, `lb-exp-slot` and `lb-exp-template`; custom elements as form-associated controls and row hosts; the Express wiring with `hubRoutes`; and the `@loadbare/widgets` library. Use whenever a task involves `@loadbare/app`, `@loadbare/widgets`, `loadbare-app-build`, an `lb-` attribute, or a page, query, request or custom element file in a Loadbare application. The model is not React, htmx or REST, and cannot be inferred from them.
 license: Apache-2.0
 metadata:
   package: "@loadbare/app"
@@ -191,6 +191,12 @@ row is filled from the nested query's last answer, whatever order they land
 in.
 
 **A `rows` query declares its order, and the hub places every row by it.**
+An edit sent from inside a list, or from a form `--lb-edit` pointed at one
+of its rows, leaves that list's rows where they stand, stamped `lb-row-unsorted` where out of order, until the page loads, the
+user's order or filter changes, or a button with `commandfor` naming the
+list sends `command="--lb-sort"`, which places them with no round trip;
+show it by `[lb-query-unsorted-count]`.  Never refresh to make rows hold
+still, and never to put them back in order.
 `rows("id", run, { order: "category_order,name" })`; a column after `-` sorts
 descending, and values compare by JSON type, so a numeric sort column is a
 JSON number or is declared one: `types: { amount: "number" }` beside
@@ -265,7 +271,8 @@ in every row.  Write one form naming the set's query, outside every row,
 often in a `<dialog>`, and give it an `id`.  A `type="button"` with
 `commandfor="<id>"` and `command="--lb-edit"` in a live row fills it from
 that row with no round trip; `--lb-new` starts it empty for an insert;
-`--lb-release` lets it go.  The form's `lb-key-value` is the row's key, empty
+`--lb-release` lets it go.  (`--lb-sort` is the fourth command, for a list,
+not a form.)  The form's `lb-key-value` is the row's key, empty
 for a new row, absent when not in use, and a stylesheet shows Save or Save
 new by it.  A successful request from the form, or its dialog closing, lets
 it go.  Which row is being edited is never a query parm.  A row that must be
@@ -321,7 +328,8 @@ picker in a row the request adds: its answer did not change, and the hub
 fills a new row from the last one.
 
 **The usual reasons for a refresh each have a patch.**
-- A row whose position changes: the hub places it by the query's order.
+- A row whose position changes: the hub places it by the query's order, or
+  holds it where the user is working; a refresh changes neither.
 - A group that appears or goes: the hub makes it with its first row and
   removes it with its last.
 - A row whose other columns change with the edit: re-read the row and patch
@@ -359,7 +367,9 @@ per query parm.  A control inside `lb-query="lb-url"` carrying
 `lb-request="lb-row-update"` writes its parm; the hub replaces the history
 entry, or pushes one when the control carries `lb-url-push`, and reloads the
 page's queries with no request to the server.  An `<a lb-url-link>` moves
-to its `href`.  Queries still take no arguments: `contextFor(req, parms)`
+to its `href`; inside a row, `lb-url-parm="topic_id"` adds that column of
+the row to the `href` as the parm of the same name, so a link to another
+page narrowed by the row is a link, never a request or script.  Queries still take no arguments: `contextFor(req, parms)`
 puts parms onto `ctx`, and a query reads them there.  Read them from
 `parms`, never `req.query`, because `contextFor` may be called twice for one
 request.  A parm is user input, so validate it where it is read.  Do not
@@ -393,10 +403,10 @@ whole data channel.
 
 **The developer writes `lb-*` attributes in markup, and script never
 assigns them.**  The builder refuses any `lb-` attribute other than the
-sixteen in [Attributes](references/names.md#attributes): `lb-query`,
+seventeen in [Attributes](references/names.md#attributes): `lb-query`,
 `lb-column`, `lb-show`, `lb-order`, `lb-filter`, `lb-group`, `lb-count`,
 `lb-sum`, `lb-avg`, `lb-min`, `lb-max`, `lb-select`, `lb-request`,
-`lb-url-link`, `lb-url-push` and `lb-url-unknown`.  `lb-exp-slot` and
+`lb-url-link`, `lb-url-parm`, `lb-url-push` and `lb-url-unknown`.  `lb-exp-slot` and
 `lb-exp-template` are expansion's, and never reach the page.  Everything
 else with the prefix is a stamp the hub or the builder writes.
 

package/skills/loadbare-app/references/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   |
@@ -157,6 +158,45 @@ Path space is flat: `/members` shows `members.page.html` wherever under
 `/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
 
 A query parm is a column of `lb-url`. A control inside `lb-query="lb-url"`

package/skills/loadbare-app/references/custom-elements.md

@@ -268,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` |
@@ -627,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
@@ -655,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