@loadbare/app 0.26.0 → 0.27.0

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

@@ -68,7 +68,7 @@ gathered.
 ## Rows hidden by a filter
 
 **What.**  A row that does not pass the user's filter gets the `hidden`
-attribute.
+attribute, and so does a group whose rows are all hidden.
 
 **Rule broken.**  The hub writes only its own stamps, which always
 begin with `lb-`.
@@ -78,7 +78,7 @@ over rows already on the page needs no round trip, and `hidden` is HTML's
 own word for an element that is present but not shown.  A stamp of our
 own would make every stylesheet restate what the browser already does.
 
-**Why it terminates.**  It applies only to live rows under a
+**Why it terminates.**  It applies only to live rows and groups under a
 filter.
 
 ## Leaving rows are inert

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

@@ -65,7 +65,7 @@ A widget package declares these.  An application never does.
 
 ## Attributes
 
-The developer writes fourteen attributes in pages and the chrome, and the
+The developer writes ten 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
@@ -76,9 +76,10 @@ assigns one.
 | `lb-query`           | Developer       | [Landing](./data-binding.md#landing)                             |
 | `lb-column`          | Developer       | [Landing](./data-binding.md#landing)                             |
 | `lb-show`            | Developer       | [Conditional rendering](./data-binding.md#conditional-rendering) |
-| `lb-order`           | Developer       | [Order](./data-binding.md#order)                                 |
 | `lb-filter`          | Developer       | [Filters](./data-binding.md#filters)                             |
 | `lb-manual`          | Developer       | [Placing by hand](./data-binding.md#placing-by-hand)             |
+| `lb-group`           | Developer       | [Groups](./data-binding.md#groups)                               |
+| `lb-aggregate`       | Developer       | [Aggregates](./data-binding.md#aggregates)                       |
 | `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)               |
@@ -92,8 +93,9 @@ assigns one.
 | `lb-query-row-count` | Hub             | [Counting rows](./data-binding.md#counting-rows)                 |
 | `lb-query-unplaced-count`, `lb-row-unplaced` | Hub | [Placing by hand](./data-binding.md#placing-by-hand) |
 | `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` | 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) |
 | `lb-row-editing`     | Hub             | [Editing a row in one form](./data-binding.md#editing-a-row-in-one-form) |
 | `lb-request-pending` | Hub             | [Request state](./data-binding.md#request-state)                 |
 | `lb-request-error`   | Hub             | [Request state](./data-binding.md#request-state)                 |
@@ -111,7 +113,8 @@ them, and a page declares none.
 | Query        | Kind  | Key       | Columns                                                         | Defined in                            |
 | ------------ | ----- | --------- | --------------------------------------------------------------- | ------------------------------------- |
 | `lb-url`     | `row` | `lb-path` | `lb-path`, `lb-page-label`, every query parm                    | [The URL](./chrome.md#the-url)        |
-| `lb-choices` | `row` | `lb-path` | `lb-path`, every choice                                         | [Choices](./data-binding.md#choices)  |
+| `lb-sort`     | `rows` | `query` | `query`, `order`                                                | [Sort and filters](./data-binding.md#sort-and-filters) |
+| `lb-filters`  | `rows` | `query` | `query`, every filter column                                    | [Sort and filters](./data-binding.md#sort-and-filters) |
 | `lb-hub-status` | `row` | `lb-path` | `lb-path`, `lb-load-state`, `lb-server-state`, `lb-error`, `lb-pending`, `lb-as-of` | [The hub's state](./chrome.md#the-hubs-state) |
 
 No query parm is reserved: a column of `lb-url` whose name begins with
@@ -170,7 +173,7 @@ accessor or field named `lb` and a capital.
 
 | Entry point                | Exports                                                          | Defined in                                     |
 | -------------------------- | ---------------------------------------------------------------- | ---------------------------------------------- |
-| `@loadbare/app/server`     | `row`, `rows`, `patch`, `url`, `choices`, `refusal`, `createHub`, and the types `Queries`, `Requests`, `HubContext`, `Hub` | [Page Files](./page-files.md), [The data channel](./server.md#the-data-channel) |
+| `@loadbare/app/server`     | `row`, `rows`, `patch`, `url`, `sort`, `filters`, `refusal`, `createHub`, and the types `Queries`, `Requests`, `HubContext`, `Hub` | [Page Files](./page-files.md), [The data channel](./server.md#the-data-channel) |
 | `@loadbare/app/express`    | `hubRoutes`                                                      | [The Express Server](./server.md)              |
 | `@loadbare/app/dev`        | `devServer`, `appServer`, `gate`, `devProxy`, `DOWN_MESSAGE`     | [The Dev Server](./dev-server.md)              |
 | `@loadbare/app/build`      | `buildApp`, `watchApp`                                           | [Assembling your own](./dev-server.md#assembling-your-own) |
@@ -196,10 +199,21 @@ imports them rather than writing a string.
 | `ATTR_QUERY_ROW_COUNT`    | `lb-query-row-count`                    |
 | `ATTR_QUERY_UNPLACED_COUNT` | `lb-query-unplaced-count`             |
 | `ATTR_QUERY_ORDER`        | `lb-query-order`                        |
+| `ATTR_GROUP`              | `lb-group`                              |
+| `ATTR_GROUP_LIVE`         | `lb-group-live`                         |
+| `ATTR_GROUP_COLUMN`       | `lb-group-column`                       |
+| `ATTR_GROUP_VALUE`        | `lb-group-value`                        |
+| `LIVE_GROUP`              | `[lb-group-live]`, the selector for a group's element |
+| `ATTR_AGGREGATE`          | `lb-aggregate`                          |
+| `AGGREGATE_COUNT`, `AGGREGATE_SUM`, `AGGREGATE_AVG`, `AGGREGATE_MIN`, `AGGREGATE_MAX` | `count`, `sum`, `avg`, `min`, `max` |
+| `AGGREGATES`              | All five aggregate functions            |
 | `ORDER_DESCENDING`        | `-`, written before a column in an order |
 | `COLUMN_TYPES`            | `number`, `boolean`, `text`             |
-| `CHOICES_QUERY`           | `lb-choices`                            |
-| `ATTR_ORDER`              | `lb-order`                              |
+| `SORT_QUERY`              | `lb-sort`                               |
+| `SORT_COLUMN_QUERY`       | `query`                                 |
+| `SORT_COLUMN_ORDER`       | `order`                                 |
+| `FILTERS_QUERY`           | `lb-filters`                            |
+| `FILTERS_COLUMN_QUERY`    | `query`                                 |
 | `ATTR_FILTER`             | `lb-filter`                             |
 | `ATTR_MANUAL`             | `lb-manual`                             |
 | `MANUAL_ORDER`, `MANUAL_FILTER` | `order`, `filter`: the sides `lb-manual` names |
@@ -211,6 +225,7 @@ imports them rather than writing a string.
 | `REQUESTED_CREATED`, `REQUESTED_CHANGED`, `REQUESTED_MOVED` | `created`, `changed`, `moved` |
 | `ATTR_ROW_UNPLACED`       | `lb-row-unplaced`                       |
 | `ATTR_ROW_LEAVING`        | `lb-row-leaving`                        |
+| `ATTR_GROUP_LEAVING`      | `lb-group-leaving`                      |
 | `ATTR_REQUEST`            | `lb-request`                            |
 | `LB_EVENT_NAME`           | `lb-request`, the event every request travels as |
 | `LB_DONE_EVENT_NAME`      | `lb-request-done`                       |
@@ -252,7 +267,7 @@ imports them rather than writing a string.
 | `ATTR_EXP_TEMPLATE`       | `lb-exp-template`                       |
 | `ATTR_PAGE`               | `lb-page`                               |
 | `ATTR_PAGE_TITLE`         | `lb-page-title`                         |
-| `DEVELOPER_ATTRIBUTES`    | The fourteen attributes a developer writes |
+| `DEVELOPER_ATTRIBUTES`    | The ten 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

@@ -152,8 +152,8 @@ optional:
 
 | Key           | Runs                                                   |
 |---------------|--------------------------------------------------------|
-| `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                      |
+| `onPageEnter` | Before the page's queries, when the page loads; may move the URL or restore the user's order and filters |
+| `onChoices`   | Each time the user changes the order or a filter        |
 | `handlers`    | The page's declared requests, by request name          |
 | `crud`        | The requests Loadbare provides, by query name          |
 
@@ -190,34 +190,41 @@ 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:
+It may return `sort()` and `filters()`, alone or beside `url()`, to restore
+the user's [order and filters](./data-binding.md#sort-and-filters) for the
+page:
 
 ```ts
 // src/pages/directory.requests.ts
-import { choices, url, type Requests } from "@loadbare/app/server";
+import { sort, filters, 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) };
+    if (saved) {
+      return {
+        ...url(saved.parms),
+        ...sort(saved.order),
+        ...filters(saved.filters),
+      };
+    }
   },
-  onChoices: (ctx, chosen) => ctx.db.saveChoices("directory", chosen),
+  onChoices: (ctx, change) => ctx.db.saveChoices(change),
 };
 ```
 
-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.
+The page load answers `lb-sort` and `lb-filters` first, so the rows land by
+the order and the filters. When `url()` moves the page, the choices arrive
+with the load at the new URL. `sort()` and `filters()`, like `url()`, take
+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.
+`onChoices` runs each time the user changes the order or a filter, with the
+query and its new `sort` or `filters`, 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
 
@@ -377,6 +384,8 @@ A change that seems to need a refresh usually has a patch:
   [order](./data-binding.md#order), or leaves it where it stands under the
   list's [`lb-manual`](./data-binding.md#placing-by-hand); 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
   it.
 - Rows the database removes with a deleted one: select their keys before the

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

@@ -228,9 +228,9 @@ in `drop` are removed, and every other row is left alone. A `rows` item on
 the answer that loads the page also carries the query's declared `order`
 and `types`, which the hub keeps for every answer after it.
 
-A choice is sent as `lb-row-update` for `lb-choices`, keyed by the path,
-with every choice made on the page as `values`; see
-[Choices](./data-binding.md#choices).
+A sort or a filter is sent as `lb-row-update` for `lb-sort` or `lb-filters`,
+keyed by the query's name, with the new order or filter as `values`; see
+[Sort and filters](./data-binding.md#sort-and-filters).
 
 `createHub(pages)` builds the `Hub`, which has two calls, both answering
 with response items: `dataForPage(page, ctx, options)` for a page load, and