@loadbare/app 0.19.1 → 0.21.0

package/skills/loadbare-app/references/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/skills/loadbare-app/references/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/skills/loadbare-app/references/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/skills/loadbare-app/references/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`