@loadbare/app 0.16.0 → 0.18.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
-seven `lb-` attributes. The server declares every query a page may show and
+nine `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`,
@@ -46,6 +46,8 @@ each with its key, and permits the three requests on `roster`; see
 | `lb-query`       | Any element                   | The query whose rows land in it                |
 | `lb-column`      | Any element                   | The column it shows, and the column it gathers |
 | `lb-show`        | Any element but `<template>`  | The column that decides whether it is present  |
+| `lb-order`       | An element with `lb-query`    | The choice holding the user's order; see [Order](#order) |
+| `lb-filter`      | An element with `lb-query`    | The columns a choice filters; see [Filters](#filters) |
 | `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-push`    | An element with `lb-request`  | A URL change that pushes a history entry       |
@@ -59,7 +61,7 @@ builder writes a stamp, and a stylesheet or a custom element reads it.
 | `lb-column-value`    | The value the hub set from a column                |
 | `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 holds           |
+| `lb-query-row-count` | The number of live rows an element shows           |
 | `lb-request-pending` | The element's request is in flight                 |
 | `lb-request-error`   | The element's last request failed                  |
 | `lb-page`            | The stub of a page, on its `<template>`            |
@@ -170,7 +172,8 @@ 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).
+places every live row by the query's order; see [Order](#order). 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
 again. A control in it that the user has typed into and not committed keeps
@@ -180,6 +183,11 @@ whose values changed is filled whole, and its controls show what arrived.
 A key is unique within a query. Two rows with one key in the same answer,
 or two live rows showing one key, are reported on the console.
 
+When the focus is in a live row that placing moves, the hub puts it back on
+the same element and scrolls it into view. When that row leaves, or a
+filter hides it, the focus goes to the first element the user can operate
+in the first row showing.
+
 A live row's root counts as a column when it carries `lb-column`, which is
 how an `<option>`, whose content is text, shows the column it is.
 
@@ -196,19 +204,83 @@ commas, each descending when written after `-`:
 roster: rows("id", (ctx) => ctx.db.members(), { order: "team,name" }),
 ```
 
-The query parm `lb-order-<query>` replaces it for that query, so a control
-inside `lb-query="lb-url"` writing that parm re-sorts the rows the hub
-already has, with no round trip. With no order, rows show in the order they
-arrived, and a patch's new rows go last.
+With no order, rows show in the order they arrived, and a patch's new rows
+go last.
+
+The user's order replaces the server's. Write `lb-order` on the element
+carrying `lb-query`, naming a column of [`lb-choices`](#choices). That
+column holds an order written the same way, and while it is empty the
+server's order places the rows:
+
+```html
+<div lb-query="lb-choices">
+  <select lb-column="roster_order" lb-request="lb-row-update">
+    <option value="">By team</option>
+    <option value="name">By name</option>
+    <option value="-joined">Newest first</option>
+  </select>
+</div>
+
+<ul lb-query="roster" lb-order="roster_order">
+  <template><li lb-column="name"></li></template>
+</ul>
+```
 
 Values compare by their JSON type: numbers numerically, strings as the
 user's language orders them, `false` before `true`, and `null` last. A
-number sent as a string sorts as a string. Rows that compare equal keep the
-order they arrived in. A row moves only when the order puts it somewhere
+number sent as a string sorts as a string, unless the query declares the
+column's [type](./page-files.md#queries): a column declared `number` sorts
+numerically whatever JSON type its values arrive as, and a value that is no
+number sorts with the nulls. Rows that compare equal keep the order they
+arrived in. A row moves only when the order puts it somewhere
 else.
 
-A query that pages or limits its rows reads the parm itself and declares
-`serverSortedByUrl: true`, so a change of order loads the page again.
+### Filters
+
+Write `lb-filter` on the element carrying `lb-query`, naming the columns of
+its rows the user may filter, separated by commas. The column of
+[`lb-choices`](#choices) of the same name holds the filter for each:
+
+```html
+<div lb-query="lb-choices">
+  <input lb-column="name" lb-request="lb-row-update" placeholder="Name" />
+</div>
+
+<ul lb-query="roster" lb-filter="name, team">
+  <template><li lb-column="name"></li></template>
+</ul>
+```
+
+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. An empty
+choice filters nothing.
+
+A filter is one or more terms, each an operator followed by a value:
+
+| Operator | A column passes when it                  |
+|----------|------------------------------------------|
+| `=`      | Equals the value                         |
+| `!=`     | Does not equal the value                 |
+| `<`      | Is less than the value                   |
+| `<=`     | Is at most the value                     |
+| `>`      | Is greater than the value                |
+| `>=`     | Is at least the value                    |
+| `^=`     | Begins with the value                    |
+| `$=`     | Ends with the value                      |
+| `*=`     | Contains the value                       |
+
+Text with no operator is `*=`. A term begins wherever whitespace comes
+before an operator, so a value may hold spaces. Every term must pass, which
+is how a range is written: `>=2026-01-01 <=2026-03-31`. A term with no
+value is left out, so a filter being typed filters nothing until it has
+one.
+
+`^=`, `$=` and `*=` read the column as text and ignore case. The others
+compare as the order compares, with the value read as the column's type: a
+number for a number, `true` or `false` for a boolean, and text otherwise.
+The column's type is the one its query declares, if it declares one, and
+its JSON type otherwise. A value that is not of the column's type, and a
+column that is null or missing, pass only `!=`.
 
 ### Groups
 
@@ -240,7 +312,8 @@ 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
 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.
+row. When the order changes, a group whose run goes on is kept and moved,
+and a group whose run ended leaves.
 
 ### Aggregates
 
@@ -254,7 +327,8 @@ or of the whole list outside any group:
 
 A sum and an average are exact, read from JSON numbers and from strings
 holding a plain decimal. `null` and empty values are left out. The result
-lands unformatted, and covers the rows the browser holds.
+lands unformatted, and covers the rows showing: a row a filter hides is
+left out.
 
 ### What happened to a row
 
@@ -264,15 +338,18 @@ Every change to a list is one a stylesheet can see:
 | ------------------ | ------------------------------------------------------ |
 | `lb-row-created`   | Created when the hub last touched the row              |
 | `lb-row-changed`   | Its values changed when the hub last touched it        |
-| `lb-row-moved`     | The order put it somewhere else when last touched      |
+| `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-leaving`   | A row on its way out                                   |
 | `lb-group-leaving` | A group on its way out                                 |
 
 A row that leaves loses `lb-row-live`, takes `inert`, and is removed once
-its animations finish, at once when there are none. A moved row moves, and
-a copy stays behind where it was, leaving. `lb-row-requested` is cleared at
-every landing; the others when the hub next touches the row.
+its animations finish, at once when there are none. `lb-row-requested` is
+cleared at every landing; the others when the hub next touches the row.
+
+A row is moved when its values changed and the rows whose values did not
+change now stand around it differently. A row it passed is not stamped,
+and a change of the user's order, which changes no values, stamps none.
 
 ```css
 [lb-row-created] { animation: arrive 200ms; }
@@ -293,8 +370,9 @@ A custom element under an `lb-show` that is off is filled like any other,
 and its `lbRowsLanded` runs as its rows land. See
 [Holding rows](./custom-elements.md#holding-rows).
 
-Nothing is answered from what the hub kept: a request always goes to the
-server, and a query re-runs only when a response names it. A patch that
+A request always goes to the server, and a query re-runs only when a
+response names it. A [choice](#choices) is the one thing landed from what
+the hub kept. A patch that
 arrives before all of a query's rows is not kept, since it is not the whole
 of anything.
 
@@ -305,8 +383,8 @@ insert form above: it sits inside `lb-query="roster"` so its request is for
 ### Counting rows
 
 The hub stamps every element that holds a row template with
-`lb-query-row-count`, the number of live rows it holds. An empty query is a
-stylesheet rule:
+`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:
 
 ```html
 <div lb-query="roster">
@@ -906,13 +984,36 @@ answers it with no round trip:
 See [The URL](./chrome.md#the-url) for its columns, links, history, and the
 unknown-page dialog.
 
+## Choices
+
+The hub serves a second query, `lb-choices`: one row keyed by `lb-path`,
+with a column for each choice the user made for how rows show, an
+[order](#order) or a [filter](#filters). The application names the
+columns. A control inside `lb-query="lb-choices"` that sends
+`lb-row-update` makes a choice, and an element anywhere may make one by
+dispatching the `lb-request` event with `lb-row-update` for `lb-choices`,
+which the hub keys by the path; see
+[Sending a request](./custom-elements.md#sending-a-request).
+
+A choice joins the ones already made, and shows with no round trip: every
+element whose `lb-order` or `lb-filter` reads a column that changed lands
+its query's last answer again, as a round trip carrying the choice would
+have. Then the hub sends the server every choice made on the page, as
+strings, in `lb-row-update` for `lb-choices`. No element waits on it, and
+the page's [`onChoices`](./page-files.md#onchoices) runs, when it has one.
+
+Choices hold until the page changes, and a change of query parm keeps them.
+On entering a page, every column named under `lb-query="lb-choices"` lands
+empty, unless the page's `onPageEnter` restores them. Choices are not query
+parms, and the URL does not carry them.
+
 ## The markup checks
 
 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 seven the developer writes
+- an `lb-` attribute that is not one of the nine the developer writes
 - `lb-request` naming an `lb-` request other than the three Loadbare provides
 - `lb-url-link` on anything but an `<a>`
 - `lb-url-push` on an element without `lb-request`
@@ -920,6 +1021,8 @@ expansion, and refuses to build:
 - `lb-show` on a `<template>`, or on a row template's root
 - `lb-show` with no `lb-query` around it
 - `lb-show="!"` or `lb-show="!!column"`, which reverse no column
+- `lb-order` or `lb-filter` on an element not carrying `lb-query`, or naming
+  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

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

@@ -99,9 +99,23 @@ export const queries: Queries = {
 | `row(key, run)`            | One row, an object                        |
 | `rows(key, run, options)`  | All its rows, an array of objects         |
 
-`options` are a `rows` query's order: `order`, the columns the hub places
-its rows by, and `serverSortedByUrl`, set when the query reads the user's
-order parm itself. See [Order](./data-binding.md#order).
+`options` are a `rows` query's order and column types. `order` is the
+columns the hub places its rows by, and the user's order, a choice, replaces
+it. See [Order](./data-binding.md#order). `types` names a type for any of
+its columns, `number`, `boolean` or `text`, and the hub sorts and filters
+that column read as its type:
+
+```ts
+payroll: rows("id", (ctx) => ctx.db.payroll(), {
+  order: "-amount",
+  types: { amount: "number" },
+}),
+```
+
+Declare a type for a column whose values arrive as some other JSON type,
+such as a Postgres `numeric` sent as a string. A column with no type
+compares by its JSON type. The order and the types go to the browser once,
+with the answer that loads the page.
 
 `key` names the column that identifies a row. Give every row that column,
 including a `row` query's: an aggregate row answers with a constant key. The
@@ -120,12 +134,13 @@ order they are returned. Sending only what changed is a request's job — see
 
 ## Requests
 
-Export `requests` from `<stub>.requests.ts`. It holds three keys, each
+Export `requests` from `<stub>.requests.ts`. It holds four keys, each
 optional:
 
 | Key           | Runs                                                   |
 |---------------|--------------------------------------------------------|
-| `onPageEnter` | Before the page's queries, when the page loads; may move the URL |
+| `onPageEnter` | Before the page's queries, when the page loads; may move the URL or restore choices |
+| `onChoices`   | Each time the user makes a choice                      |
 | `handlers`    | The page's declared requests, by request name          |
 | `crud`        | The requests Loadbare provides, by query name          |
 
@@ -160,11 +175,40 @@ export const requests: Requests = {
 Declare no refresh set here. The page's queries run afterward.
 
 It may return `url()` instead, to move the page to other query parms before
-anything shows, as restoring the filters and order the user last had does.
-The page loads there in the same round trip, and that load does not follow
+anything shows, as restoring the parms the user last had does. The page
+loads there in the same round trip, and that load does not follow
 `onPageEnter` again. A `url()` leading to the parms already in hand is
 ignored. See [Moving the URL](#moving-the-url).
 
+It may return `choices()`, alone or beside `url()`, to restore the user's
+[choices](./data-binding.md#choices) for the page:
+
+```ts
+// src/pages/directory.requests.ts
+import { choices, url, type Requests } from "@loadbare/app/server";
+
+export const requests: Requests = {
+  onPageEnter: async (ctx) => {
+    const saved = await ctx.db.savedView("directory");
+    if (saved) return { ...url(saved.parms), ...choices(saved.choices) };
+  },
+  onChoices: (ctx, chosen) => ctx.db.saveChoices("directory", chosen),
+};
+```
+
+The page load answers `lb-choices` first, so the rows land by the choices.
+When `url()` moves the page, the choices arrive with the load at the new
+URL. `choices()`, like `url()`, takes columns whose values are strings, at
+least one of them; anything else is reported on the server console and
+ignored.
+
+### onChoices
+
+`onChoices` runs each time the user makes a choice, with every choice made
+on the page, by column, as strings. It is how an application keeps them for
+`onPageEnter` to restore, and answers nothing, by convention. Whatever it
+returns lands. A page without it is not told.
+
 ### handlers
 
 Declare a request under the name the HTML gives `lb-request`. Pair what it
@@ -293,10 +337,11 @@ A change that seems to need a refresh usually has a patch:
   delete and drop them too.
 
 An update or a delete always has a patch, since it names its row by key and
-removing a row never reorders the rest. `createHub` refuses at startup a
-`crud` `rowUpdate` or `rowDelete` on a `rows` query whose `refresh` names
-that same query. An insert may refresh its own query: where a new row goes
-depends on whether its host places it, which the server cannot see.
+removing a row never reorders the rest. So does an insert, which has the new
+row's key once it has written it, and the hub places the new row by the
+query's order. `createHub` refuses at startup a `crud` `rowInsert`,
+`rowUpdate` or `rowDelete` on a `rows` query whose `refresh` names that same
+query.
 
 Each request's `refresh` is its own, and every query in it needs its own
 reason. A list shared by several requests is a warning sign.

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

@@ -78,6 +78,7 @@ writes the row template inside the widget:
 | Parameter   | Fills                      |
 |-------------|----------------------------|
 | `exp-label` | The visible `<label>` text |
+| `exp-size`  | The `<select>`'s `size`, an open list rather than a drop-down |
 
 - Each option's `value` is its row's key, the `lb-key-value` the hub stamps
   on the live row, so the widget holds a key and shows a label.
@@ -90,6 +91,9 @@ writes the row template inside the widget:
     <optgroup><template><option lb-column="label"></option></template></optgroup>
   </template>
   ```
+- A heading option marked `data-group-label` in the `<optgroup>`, `hidden`
+  and `disabled`, labels the group with its text instead, so the label can
+  be a column of the group's first row.
 - Its `value` selects the option with that key, including an option that
   arrives after the value did.
 
@@ -154,7 +158,11 @@ row, the row template, and optionally a footer, each as a `<template>`:
 - The hub places the rows by the query's order and builds its groups. The
   rows land in the one `<tbody>`, so a group here is a heading row with its
   rows after it.
-- The footer is not a row of `ledger`. An aggregate there covers every row;
+- `lb-order` and `lb-filter` go on the `lb-table` itself, beside
+  `lb-query`; see [Order](./data-binding.md#order) and
+  [Filters](./data-binding.md#filters).
+- The footer is not a row of `ledger`. An aggregate there covers every row
+  showing;
   a figure that is not a sum of the rows, such as a budget, is a `<tr>`
   naming a `row` query of its own.
 - A `<template lb-exp-template="ghost">` is a blank row for entering a new
@@ -163,6 +171,9 @@ row, the row template, and optionally a footer, each as a `<template>`:
   cursor back in it once an insert from it succeeds.
 - After rows land, the widget scrolls the row the page's own request created
   or moved into view.
+- 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.
 
 ## `lb-confirm`
 
@@ -203,6 +214,10 @@ with `commandfor` and `command="show-modal"`. Save is the form's
 `lb-options` around the button that opened it, and closes. The handler
 answers with a patch holding the new row.
 
+While open, the button that opened it carries `insert-dialog-opener` and the
+widget carries `anchored`, for a stylesheet to place the dialog beside the
+button with CSS anchor positioning.
+
 | Parameter   | Fills                                             |
 |-------------|---------------------------------------------------|
 | `exp-id`    | The dialog's `id`                                 |