@loadbare/app 0.9.0 → 0.11.0

package/docs/tutorials/040-displaying-data.md

@@ -7,21 +7,23 @@ data-centric apps, displaying data.
 
 ## Data Binding 
 
-Loadbare can understand and process scalar cells, entities, and
-collections.  We begin with a simple scalar cell.
+Loadbare displays rows.  A query is a name for rows, of kind `row` or
+`rows`, and the server declares each query a page shows.  We begin with a
+query of kind `row` holding one value.
 
-All data that is displayed in the app is scoped to a named query that
-is implemented on the server.  In the code below we scope the div
-to query `visits`, then specify that the span will display
-the cell `count`.
+All data that is displayed in the app belongs to a named query that
+is implemented on the server.  In the code below we give the div
+the query `visits` with `lb-query`, then specify that the span will display
+the column `count` with `lb-column`.
 
 ```html
 <!-- src/pages/about.page.html -->
+<title>About</title>
 <h1>About</h1>
 <p class="about-note">This is the about page.</p>
 
-<div lb-row="visits">
-  <p>This page has been visited <span lb-cell="count"></span> times.</p>
+<div lb-query="visits">
+  <p>This page has been visited <span lb-column="count"></span> times.</p>
 </div>
 ```
 
@@ -32,11 +34,26 @@ Put the query into `about.queries.ts`, which uses the same page stem,
 
 ```ts
 // src/pages/about.queries.ts
+import { row } from "@loadbare/app/server";
+
 export const queries = {
-  visits: async (ctx) => ({ count: String(await ctx.db.visitCount()) }),
+  visits: row("page", async (ctx) => ({
+    page: "about",
+    count: String(await ctx.db.visitCount()),
+  })),
 };
 ```
 
+`row()` declares a query of kind `row`, and `rows()` declares one of kind
+`rows`.  The first argument names the key, the column whose value
+identifies a row.  Every query has a key, so a row holding a single count
+carries a constant one, here `page`.  The markup names neither the kind nor
+the key: the server sends both with every answer.
+
+The hub lands the row on the `<div>` itself, since it holds no
+`<template>`, and sets the text of each element whose `lb-column` names one
+of the row's columns.
+
 We have not yet implemented `ctx.db`, we will do that shortly.
 
 ## Write the Before Get Hook
@@ -160,10 +177,10 @@ to About.
 View source on either page: the host HTML is exactly what's on disk. Only
 the `<span>`'s text changes, never the markup around it.
 
-This tutorial only used `lb-row` and `lb-cell` to display one value.
-The full attribute vocabulary — actions, CRUD operations, lists, and
-navigation — is in [Data Binding](../reference/data-binding.md).
+This tutorial only used `lb-query` and `lb-column` to display one value.
+The full attribute vocabulary — requests, inserting, updating and deleting
+rows, and many rows at once — is in [Data Binding](../reference/data-binding.md).
 
 ---
 Prev: [HTML Decomposition](./030-html-decomposition.md)
-Next: [Actions](./050-actions.md)
+Next: [Requests](./050-requests.md)

package/docs/tutorials/{050-actions.md → 050-requests.md}

@@ -1,35 +1,41 @@
-# Actions
+# Requests
 
-So far we have used data binding to display a single cell of a named
-query.  Before we go on to CRUD operations, we will show an "action",
-which is a named routine on the server that cna be invoked from the
-client.
+So far we have used data binding to display a single column of a named
+query.  Before we go on to inserting, updating and deleting rows, we will
+show a declared request, which is a named routine on the server that can be
+invoked from the client.
 
-## An action in the client
+## A request in the client
 
 Modify the about page to include a button that requests the server
 to reset the visit count.
 
 ```html
 <!-- src/pages/about.page.html -->
+<title>About</title>
 <h1>About</h1>
 <p class="about-note">This is the about page.</p>
 
-<div lb-row="visits">
-  <p>This page has been visited <span lb-cell="count"></span> times.</p>
-  <button lb-action="resetVisits">Reset count</button>
+<div lb-query="visits">
+  <p>This page has been visited <span lb-column="count"></span> times.</p>
+  <button lb-request="resetVisits">Reset count</button>
 </div>
 ```
 
-## Implement the action on the server
+`lb-request` names the request an element issues when it commits.  A button
+commits on click, a form on submit, and a control such as an `<input>` on
+change.  The hub sends the request name to the server, together with the
+query the button sits in.
 
-Actions go into the page's requests file:
+## Implement the request on the server
+
+Declared requests go under `handlers` in the page's requests file:
 
 ```ts
 // src/pages/about.requests.ts
 export const requests = {
   onPageEnter: (ctx) => ctx.db.recordVisit(),
-  actions: {
+  handlers: {
     resetVisits: {
       run: (ctx) => ctx.db.resetVisits(),
       refresh: ["visits"],
@@ -38,10 +44,14 @@ export const requests = {
 };
 ```
 
-An action is a `run` paired with a `refresh` list.  After the `run` code
+A handler is a `run` paired with a `refresh` list.  After the `run` code
 is executed, all of the named queries in `refresh` are rerun and their
-results go to the browser, where the Loadbare hub `<lb-hub>` refreshes
-the bound elements.
+results go to the browser, where the Loadbare hub `<lb-hub>` lands them on
+the elements that name them.
+
+The server runs only the handlers a page declares, and refuses any other
+request name.  Names beginning with `lb-` are Loadbare's; the application
+should never name anything with the `lb-` prefix anywhere.
 
 ## Extending the database
 

package/docs/tutorials/060-custom-element-code.md

@@ -1,12 +1,11 @@
 # Custom Element Code
 
-So far we have simple scalar data binding, and server-implemented
-actions that can be requested from the server.
+So far we have simple data binding of one row, and declared requests
+that the server implements.
 
-The natural next step is CRUD operations, but those will require
-custom elements for list operations. 
-To set the stage for custom elements and list operations, we will
-first implement a much simpler custom element to see how they work.
+The natural next step is inserting, updating and deleting rows.  Before
+that, we will implement a simple custom element to see how custom element
+code works.
 
 ## Using the element
 
@@ -16,15 +15,17 @@ then implement.
 
 ```html
 <!-- src/pages/about.page.html -->
-<div lb-row="visits">
-  <p>This page has been <visit-count lb-cell="count"></visit-count>.</p>
-  <button lb-action="resetVisits">Reset count</button>
+<div lb-query="visits">
+  <p>This page has been <visit-count lb-column="count"></visit-count>.</p>
+  <button lb-request="resetVisits">Reset count</button>
 </div>
 ```
 
 When we drop in a custom element, we bind the custom element
-to the cell value `count` the same as we did for the span,
-using `lb-cell="count"`.
+to the column `count` the same as we did for the span,
+using `lb-column="count"`.  The hub never replaces a custom element's
+content.  It stamps the value on the element as the attribute
+`lb-column-value`, and the element renders it.
 
 ## Writing the class
 
@@ -43,10 +44,10 @@ be able to pull it into the browser.
 
 ```ts
 // src/visit-count.browser.ts
-import { ATTR_VALUE } from "@loadbare/app/constants";
+import { ATTR_COLUMN_VALUE } from "@loadbare/app/constants";
 
 class VisitCount extends HTMLElement {
-  static observedAttributes = [ATTR_VALUE];
+  static observedAttributes = [ATTR_COLUMN_VALUE];
 
   attributeChangedCallback(_name: string, _old: string, value: string) {
     const count = Number(value);
@@ -62,8 +63,8 @@ exactly, and we don't use Shadow DOM.  For more specifics, see
 [Custom Elements](../reference/custom-elements.md#code).
 
 In brief, custom elements can name which attributes should trigger a callback
-when their values change.  Here we specify only one, the standard attribute
-used for a cell's value, defined in constant `ATTR_VALUE`.  When the 
+when their values change.  Here we specify only one, the stamp the hub
+writes with a column's value, defined in constant `ATTR_COLUMN_VALUE`.  When the 
 attribute changes, `attributeChangedCallback` fires and rewrites the text.
 
 ## Run it
@@ -76,5 +77,5 @@ Open the About page. Where the plain number was, it now reads "visited 7
 times" (or "visited 1 time" the first time).
 
 ---
-Prev: [Actions](./050-actions.md)
+Prev: [Requests](./050-requests.md)
 Next: [Conditional Rendering](./065-conditional-rendering.md)

package/docs/tutorials/065-conditional-rendering.md

@@ -19,7 +19,8 @@ two of them carry the standard `hidden` attribute.
 ```html
 <!-- src/pages/about.page.html -->
 <h2>Sign up</h2>
-<lb-wizard lb-row="signup" lb-cell="step">
+<div lb-query="signup">
+<signup-wizard lb-column="step">
   <section data-step="name">
     <h3>1. Name</h3>
     <p>This step is not hidden, because it's the one the page ships showing.</p>
@@ -31,27 +32,32 @@ two of them carry the standard `hidden` attribute.
     <h3>3. Confirm</h3>
   </section>
 
-  <button data-nav="back" lb-action="wizardBack" disabled>Back</button>
-  <button data-nav="next" lb-action="wizardNext">Next</button>
-</lb-wizard>
+  <button data-nav="back" lb-request="wizardBack" disabled>Back</button>
+  <button data-nav="next" lb-request="wizardNext">Next</button>
+</signup-wizard>
+</div>
 ```
 
-`lb-cell="step"` on `<lb-wizard>` works exactly the way it did on
+`lb-column="step"` on `<signup-wizard>` works exactly the way it did on
 `<visit-count>` in [Custom Element Code](./060-custom-element-code.md):
-because the tag has a hyphen, the value lands on the `lb-value` attribute
-instead of `textContent`, and the class decides what to do with it. Back
-and Next are plain buttons carrying `lb-action`, the same mechanism as the
-Reset button in [Actions](./050-actions.md) — the wizard owns no
-arithmetic of its own.
+because the tag is a custom element, the value lands on the
+`lb-column-value` attribute instead of `textContent`, and the class decides
+what to do with it. Back and Next are plain buttons carrying `lb-request`,
+the same mechanism as the Reset button in [Requests](./050-requests.md) —
+the wizard owns no arithmetic of its own.
+
+The element is named `signup-wizard` rather than anything beginning with
+`lb-`.  The `lb-` prefix is Loadbare's, and the application should never
+name anything with the `lb-` prefix anywhere.
 
 ## Writing the class
 
 ```ts
-// src/lb-wizard.browser.ts
-import { ATTR_VALUE } from "@loadbare/app/constants";
+// src/signup-wizard.browser.ts
+import { ATTR_COLUMN_VALUE } from "@loadbare/app/constants";
 
-class LbWizard extends HTMLElement {
-  static observedAttributes = [ATTR_VALUE];
+class SignupWizard extends HTMLElement {
+  static observedAttributes = [ATTR_COLUMN_VALUE];
 
   attributeChangedCallback(_name: string, _old: string, value: string) {
     const steps = [...this.querySelectorAll<HTMLElement>("[data-step]")];
@@ -69,7 +75,7 @@ class LbWizard extends HTMLElement {
   }
 }
 
-customElements.define("lb-wizard", LbWizard);
+customElements.define("signup-wizard", SignupWizard);
 ```
 
 The whole conditional is one line: `step.hidden = step.dataset.step !==
@@ -81,7 +87,7 @@ all of them from the current value.
 
 A multi-step signup form is exactly the kind of thing a user gets
 interrupted out of when they close the tab, the browser crashes, they come
-back an hour later. If `step` were just a private field on the `LbWizard`
+back an hour later. If `step` were just a private field on the `SignupWizard`
 instance, none of that would survive: a reload constructs a fresh element
 with no memory of where the user was, and they'd have to start over from
 Step 1. So the step lives on the server, the same way the visit count
@@ -89,17 +95,22 @@ does, and every reload asks for it again instead of assuming it.
 
 ```ts
 // src/pages/about.queries.ts
+import { row } from "@loadbare/app/server";
+
 export const queries = {
-  // ...visits and notes unchanged...
-  signup: async (ctx) => ({ step: await ctx.db.signupStep() }),
+  // ...visits unchanged...
+  signup: row("id", async (ctx) => ({
+    id: "signup",
+    step: await ctx.db.signupStep(),
+  })),
 };
 ```
 
 ```ts
 // src/pages/about.requests.ts
 export const requests = {
-  // ...onPageEnter, resetVisits, and crud unchanged...
-  actions: {
+  // ...onPageEnter unchanged...
+  handlers: {
     resetVisits: { run: (ctx) => ctx.db.resetVisits(), refresh: ["visits"] },
     wizardBack: { run: (ctx) => ctx.db.moveSignup(-1), refresh: ["signup"] },
     wizardNext: { run: (ctx) => ctx.db.moveSignup(1), refresh: ["signup"] },
@@ -109,7 +120,7 @@ export const requests = {
 
 Back and Next both `refresh: ["signup"]` — a click sends the request, the
 server computes and clamps the new step, and the answer comes back through
-the normal query/cell path. The browser never shows a step the server
+the normal query and column path. The browser never shows a step the server
 hasn't confirmed, the same rule the visit count follows for its number.
 
 ## Extending the database
@@ -120,7 +131,7 @@ const STEPS = ["name", "address", "confirm"];
 
 export function openDb() {
   return {
-    // ...visitCount(), recordVisit(), resetVisits(), notes, etc. unchanged...
+    // ...visitCount(), recordVisit(), resetVisits() unchanged...
     async signupStep() {
       return (await read()).step ?? STEPS[0];
     },
@@ -150,7 +161,7 @@ both buttons are enabled.
 Now click Next once more so Step 3 is showing, and reload the page. Step
 3 is still what's showing — not Step 1. If `step` had been client-only
 state instead of a query result, the reload would have built a brand new
-`LbWizard` with nothing to tell it otherwise, and it would have landed
+`SignupWizard` with nothing to tell it otherwise, and it would have landed
 back on Step 1 like the very first visit.
 
 View source: all three `<section>`s are on the page the whole time. Only

package/docs/tutorials/070-displaying-a-list.md

@@ -1,24 +1,28 @@
 # Displaying a List
 
 Every query so far has answered with one row. Now we add a query that
-answers with many rows, and markup to show them. No widget is involved: the
-hub reconciles a list itself.
+answers with many rows, and markup to show them. No custom element is
+involved: the hub lands the rows itself.
 
 ## Writing the query
 
 ```ts
 // src/pages/about.queries.ts
-import { list, row } from "@loadbare/app/server";
+import { row, rows } from "@loadbare/app/server";
 
 export const queries = {
-  visits: row(async (ctx) => ({ count: String(await ctx.db.visitCount()) })),
-  notes: list((ctx) => ctx.db.notes()),
+  visits: row("page", async (ctx) => ({
+    page: "about",
+    count: String(await ctx.db.visitCount()),
+  })),
+  notes: rows("id", (ctx) => ctx.db.notes()),
 };
 ```
 
-Every query says which shape it answers with. `row()` answers with one row
-and `list()` answers with a set of them, and a name never answers with both.
-A page that needs the same data both ways declares two queries.
+Every query declares its kind and its key. `row()` answers with one row
+and `rows()` answers with any number of them, and a name never answers with
+both. A page that needs the same data both ways declares two queries. The
+key of `notes` is `id`, the column whose value identifies each note.
 
 ## Extending the database
 
@@ -66,17 +70,18 @@ export function openDb() {
 `write` is now a merge, not a whole-file replace — otherwise saving
 `notes` would erase `visitCount`.
 
-## A list display with a template
+## A row template
 
-A list scope needs to be told what one row looks like, and we say so with a
-`<template>` inside it. The hub clones that template once per row and fills
-each clone the same way it fills any other scope.
+An element whose query answers with many rows needs to be told what one
+row looks like, and we say so with a `<template>` inside it, the row
+template. The hub clones that template once per row and fills each clone,
+a live row, the same way it filled the `visits` element.
 
 > Loadbare does not use Shadow DOM because Shadow DOM is generally obtuse,
 > interferes with CSS scoping, and makes templates difficult to supply at point
 > of use. Shadow DOM also prevents `closest()` from reaching outside an 
 > element's shadow root, and `closest()` is fundamental
-> to identifying the data-binding scope of elements.  
+> to finding the row and the query an element belongs to.  
 >
 > Rather than mess with the Shadow DOM, we use Light DOM.
 > We take advantage of the fact that `<template>`
@@ -84,22 +89,25 @@ each clone the same way it fills any other scope.
 > into the light DOM, where it's easy to see how a row
 > is going to be rendered.
 
-We know already that a DOM subtree can be scoped to one row with
-`lb-row="X"`.  A set of rows uses `lb-list="X"` instead, and adds
-`lb-key="id"`, which names the column that uniquely identifies a row. Each
-row the hub clones is stamped with `lb-key-value`, holding that row's key,
-which is what scopes the row's subtree to one specific row.
+The markup is the same `lb-query` we used for one row.  The server
+declared `notes` of kind `rows` with the key `id`, so the markup says
+neither. Each live row the hub clones is stamped with `lb-key-value`,
+holding that row's key, which is how the hub matches a row that arrives
+again to the live row already showing it.
 
 ```html
 <!-- src/pages/about.page.html -->
 <h2>Notes</h2>
-<ul lb-list="notes">
-  <template lb-key="id">
-    <li lb-cell="text"></li>
+<ul lb-query="notes">
+  <template>
+    <li lb-column="text"></li>
   </template>
 </ul>
 ```
 
+The live row's own `lb-column` counts, which is how an `<li>` or an
+`<option>` shows a column as its text.
+
 ## Run it
 
 ```

package/docs/tutorials/072-inserting-into-a-list.md

@@ -8,37 +8,44 @@ that allows a user to add a note.
 ```html
 <!-- src/pages/about.page.html -->
 <h2>Notes</h2>
-<section lb-list="notes">
-  <form lb-action="lb-row-insert">
-    <input lb-cell="text" placeholder="Write a note" />
+<section lb-query="notes">
+  <form lb-request="lb-row-insert">
+    <input lb-column="text" placeholder="Write a note" />
     <button type="submit">Add</button>
   </form>
 
   <ul>
-    <template lb-key="id">
-      <li lb-cell="text"></li>
+    <template>
+      <li lb-column="text"></li>
     </template>
   </ul>
 </section>
 ```
 
-`lb-action="lb-row-insert"` on a `<form>` gathers its `lb-cell`s into a values
-map on submit and sends them against the `lb-list` around it, the way an
-`<input>` belongs to the `<form>` around it. The name is one of
-Loadbare's reserved ones — every value beginning with `lb-` is — so it
-needs no declaring, and nothing of yours may be called that. There's no `lb-key-value` — there's no row
-yet.
+`lb-query="notes"` moves from the `<ul>` to a `<section>` that holds both
+the form and the list, so the form is inside the query it adds to.
 
-## Implementing CRUD server-side
+A `<form>` commits on submit.  `lb-request="lb-row-insert"` on it gathers
+the value of every control carrying `lb-column` whose form owner is the
+form, under the column each names, and sends them as `values` for the
+nearest `lb-query` around those controls, `notes`.  `lb-row-insert` is one
+of the requests Loadbare provides, so the page declares no handler for it.
+The request carries no key, since there is no row yet.
 
-Our CRUD operations go into the page's requests file:
+After a successful insert from a form, the hub resets the form, so the
+input is empty for the next note.
+
+## Implementing the insert server-side
+
+The requests Loadbare provides run what the page declares under `crud`, in
+the page's requests file:
 
 ```ts
 // src/pages/about.requests.ts
 import { patch } from "@loadbare/app/server";
 
 export const requests = {
-  // ...onPageEnter and actions unchanged...
+  // ...onPageEnter and handlers unchanged...
   crud: {
     notes: {
       rowInsert: {
@@ -53,8 +60,9 @@ export const requests = {
 };
 ```
 
-`rowInsert` is a CRUD operation, declared under `crud` and keyed by
-query name.  
+`lb-row-insert` runs `rowInsert`, declared under `crud` and keyed by
+query name.  A query with no `crud` entry permits none of the three
+requests.
 
 Notice that we do not use the `refresh` mechanism, as that would return
 the entire query which would be wasteful.  We instead return a `patch` 

package/docs/tutorials/074-deleting-from-a-list.md

@@ -6,19 +6,21 @@ Now that we can add notes, we need to be able to delete a note.
 
 ```html
 <!-- src/pages/about.page.html -->
-<ul lb-list="notes">
-  <template lb-key="id">
+<ul lb-query="notes">
+  <template>
     <li>
-      <span lb-cell="text"></span>
-      <button lb-action="lb-row-delete">Delete</button>
+      <span lb-column="text"></span>
+      <button lb-request="lb-row-delete">Delete</button>
     </li>
   </template>
 </ul>
 ```
 
 The `<li>` now has two children, so the text moves onto its own `<span>`.
-`lb-row-delete` is a reserved name, so it needs no form and no declaring — just
-the `lb-list` and `lb-key-value` already in scope from its ancestors.
+A button commits on click.  The button sits in a live row, so the hub
+sends `lb-row-delete` for the live row's query, `notes`, with the live
+row's `lb-key-value` as `key`.  The request needs no form, and the page
+declares no handler for it beyond `crud`.
 
 ## Implementing delete server-side
 
@@ -27,7 +29,7 @@ the `lb-list` and `lb-key-value` already in scope from its ancestors.
 import { patch } from "@loadbare/app/server";
 
 export const requests = {
-  // ...onPageEnter and actions unchanged...
+  // ...onPageEnter and handlers unchanged...
   crud: {
     notes: {
       // ...rowInsert unchanged...

package/docs/tutorials/076-updating-a-list-item.md

@@ -6,22 +6,23 @@ Now we edit a row in place, instead of removing and re-adding it.
 
 ```html
 <!-- src/pages/about.page.html -->
-<ul lb-list="notes">
-  <template lb-key="id">
+<ul lb-query="notes">
+  <template>
     <li>
-      <form lb-action="lb-row-update">
-        <input lb-cell="text" />
+      <form lb-request="lb-row-update">
+        <input lb-column="text" />
         <button type="submit">Save</button>
       </form>
-      <button lb-action="lb-row-delete">Delete</button>
+      <button lb-request="lb-row-delete">Delete</button>
     </li>
   </template>
 </ul>
 ```
 
-`lb-row-update` gathers its `lb-cell`s the same way `lb-row-insert` does, but
-also reads `lb-key-value` from the row it's inside — the same ancestor
-`lb-row-delete` already reads.
+`lb-row-update` gathers the form's controls the same way `lb-row-insert`
+does, and also takes `key` from the live row it's inside — the same
+`lb-key-value` that `lb-row-delete` already reads.  An update resets
+nothing: the updated row lands back on the input.
 
 ## Implementing update server-side
 
@@ -30,7 +31,7 @@ also reads `lb-key-value` from the row it's inside — the same ancestor
 import { patch } from "@loadbare/app/server";
 
 export const requests = {
-  // ...onPageEnter and actions unchanged...
+  // ...onPageEnter and handlers unchanged...
   crud: {
     notes: {
       // ...rowInsert, rowDelete unchanged...
@@ -81,4 +82,4 @@ the other doesn't move. Reload — the edit is still there.
 
 ---
 Prev: [Deleting From a List](./074-deleting-from-a-list.md)
-Next: [Widget Requests](./080-widget-requests.md)
+Next: [Committing a Control](./080-widget-requests.md)