@loadbare/app 0.5.6 → 0.6.0

package/docs/tutorials/010-pages-and-navigation.md

@@ -56,7 +56,7 @@ display something to the user if they type a URL that has no matching page.
         <a href="/about" lb-nav-link>About</a>
       </nav>
       <main></main>
-      <dialog lb-unknown-page lb-query="lb-navigation">
+      <dialog lb-unknown-page lb-row="lb-navigation">
         The URL <span lb-cell="page-uri"></span> is not in this app.
       </dialog>
     </lb-hub>
@@ -75,7 +75,7 @@ link.
 
 If a `<dialog lb-unknown-page>` element is present in the HTML, it will be
 displayed to the user when a URL is entered that has no matching page in the app.
-The `lb-query` and `lb-cell` attributes will be explained when we get to data
+The `lb-row` and `lb-cell` attributes will be explained when we get to data
 binding; for now, know that `lb-navigation` is a query the hub itself answers
 on every navigation, and `page-uri` is the path that was asked for.  The
 widget library ships this dialog ready-made as `<lb-unknown-page>`, which
@@ -112,12 +112,12 @@ catch-all answers that request too.
 
 ## If you look at the console
 
-On every navigation, the hub also asks the server for that page's data, at
-`/lb/data?page=<name>`.  Neither of these pages is serving any data, and our
-Express server has no route handler for /lb/*, so the catch-all route is currently
-returning the same `app.html` for data requests as it does for the inital 
-app load.  This is expected in this early stage of the tutorial, we will fix
-it when we get to data binding and handling.
+On every navigation, the hub also asks the server for that page's data.  It
+posts that request, so it never collides with the routes above.  Neither of
+these pages is serving any data, and our Express server has no route handler
+for the hub yet, so those posts currently go unanswered.  This is expected in
+this early stage of the tutorial, we will fix it when we get to data binding
+and handling.
 
 ## Run it
 

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

@@ -20,7 +20,7 @@ the cell `count`.
 <h1>About</h1>
 <p class="about-note">This is the about page.</p>
 
-<div lb-query="visits">
+<div lb-row="visits">
   <p>This page has been visited <span lb-cell="count"></span> times.</p>
 </div>
 ```
@@ -45,14 +45,14 @@ When the user navigates to a page, the loadbare hub `<lb-hub>` swaps
 the contents of `<main>` and sends a request to the server for the
 query results defined for that page.  
 
-For a visit counter, we need to write a `beforeGet` hook to fire first
+For a visit counter, we need to write a `onPageEnter` hook to fire first
 and increment the counter:
 
 
 ```ts
-// src/pages/about.hooks.ts
-export const hooks = {
-  beforeGet: (ctx) => ctx.db.recordVisit(),
+// src/pages/about.requests.ts
+export const requests = {
+  onPageEnter: (ctx) => ctx.db.recordVisit(),
 };
 ```
 
@@ -103,7 +103,7 @@ the authenticated caller instead of the same file for everyone.
 
 ## Wiring the server
 
-The Loadbare builder compiles a list of all hooks and queries.  
+The Loadbare builder compiles a list of all requests and queries.  
 Add the four
 lines below, and our server will correctly route all data channel 
 requests to the correct page code.
@@ -121,8 +121,8 @@ const app = express();
 app.use("/client.js", express.static("dist/client.js"));
 app.use("/app.css", express.static("dist/app.css"));
 
-// New: answers GET /lb/data?page=<name> and POST /lb?page=<name>.
-// Must come before the catch-all, or the catch-all answers these too.
+// New: answers the hub's own route, which is the one the browser posts to.
+// Must come before the catch-all, or the catch-all answers it too.
 function contextFor(_req) {
   return { db: openDb() };
 }
@@ -160,7 +160,7 @@ 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-query` and `lb-cell` to display one value.
+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).
 

package/docs/tutorials/050-actions.md

@@ -15,7 +15,7 @@ to reset the visit count.
 <h1>About</h1>
 <p class="about-note">This is the about page.</p>
 
-<div lb-query="visits">
+<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>
@@ -23,12 +23,12 @@ to reset the visit count.
 
 ## Implement the action on the server
 
-Actions go into the page's hooks file:
+Actions go into the page's requests file:
 
 ```ts
-// src/pages/about.hooks.ts
-export const hooks = {
-  beforeGet: (ctx) => ctx.db.recordVisit(),
+// src/pages/about.requests.ts
+export const requests = {
+  onPageEnter: (ctx) => ctx.db.recordVisit(),
   actions: {
     resetVisits: {
       run: (ctx) => ctx.db.resetVisits(),

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

@@ -16,7 +16,7 @@ then implement.
 
 ```html
 <!-- src/pages/about.page.html -->
-<div lb-query="visits">
+<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>

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

@@ -19,7 +19,7 @@ two of them carry the standard `hidden` attribute.
 ```html
 <!-- src/pages/about.page.html -->
 <h2>Sign up</h2>
-<lb-wizard lb-query="signup" lb-cell="step">
+<lb-wizard lb-row="signup" lb-cell="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>
@@ -96,9 +96,9 @@ export const queries = {
 ```
 
 ```ts
-// src/pages/about.hooks.ts
-export const hooks = {
-  // ...beforeGet, resetVisits, and crud unchanged...
+// src/pages/about.requests.ts
+export const requests = {
+  // ...onPageEnter, resetVisits, and crud unchanged...
   actions: {
     resetVisits: { run: (ctx) => ctx.db.resetVisits(), refresh: ["visits"] },
     wizardBack: { run: (ctx) => ctx.db.moveSignup(-1), refresh: ["signup"] },

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

@@ -1,22 +1,24 @@
 # Displaying a List
 
-Every query so far has answered with one tuple. Now we add a query that
-answers with many rows, and a widget to show them: `<lb-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.
 
 ## Writing the query
 
 ```ts
 // src/pages/about.queries.ts
-import { rows } from "@loadbare/app/server";
+import { list, row } from "@loadbare/app/server";
 
 export const queries = {
-  visits: async (ctx) => ({ count: String(await ctx.db.visitCount()) }),
-  notes: async (ctx) => rows(await ctx.db.notes()),
+  visits: row(async (ctx) => ({ count: String(await ctx.db.visitCount()) })),
+  notes: list((ctx) => ctx.db.notes()),
 };
 ```
 
-Loadbare assumes a query's results are always one tuple.  We tell it that
-we are returning a set of rows by wrapping the query in `rows()`.
+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.
 
 ## Extending the database
 
@@ -64,35 +66,11 @@ export function openDb() {
 `write` is now a merge, not a whole-file replace — otherwise saving
 `notes` would erase `visitCount`.
 
-## Installing the widget library
-
-`<lb-list>` is the first widget we take from a library rather than write
-ourselves.  It ships in `@loadbare/widgets`:
-
-```
-npm install @loadbare/widgets
-```
-
-The builder scans `src/` on its own, but it will not go looking through
-`node_modules` uninvited.  List the package in `src/imports.ts`:
-
-```ts
-// src/imports.ts
-export default ["@loadbare/widgets"];
-```
-
-That is the whole of it.  List the package, not its tags — the builder finds
-`<lb-list>` by filename, and bundles only the tags a page actually uses.
-[Using Widget Libraries](./090-using-widget-libraries.md) covers the same
-step for anyone else's package.
-
 ## A list display with a template
 
-The `<lb-list>` widget will display a list, but when we use that widget
-we need to tell it what a list item looks like.  We do that by
-putting a `<template>` inside of it.  The widget itself contains a loop
-to display one template per row, and invokes code in the hub `<lb-hub>` to
-display bound data values.
+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.
 
 > Loadbare does not use Shadow DOM because Shadow DOM is generally obtuse,
 > interferes with CSS scoping, and makes templates difficult to supply at point
@@ -103,24 +81,23 @@ display bound data values.
 > Rather than mess with the Shadow DOM, we use Light DOM.
 > We take advantage of the fact that `<template>`
 > elements are not rendered, so we drop the `<template>` directly
-> into the light DOM, where it's easy to see how `<lb-list>` is
-> going to render our list.
+> 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 a query with
-`lb-query="X"`.  Now we see the use of `lb-key="id"`, which further
-scopes a subtree to a specific row within the query, naming the 
-primary key field that uniquely identifies the row.
+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.
 
 ```html
 <!-- src/pages/about.page.html -->
 <h2>Notes</h2>
-<lb-list lb-query="notes">
-  <ul>
-    <template lb-key="id">
-      <li lb-cell="text"></li>
-    </template>
-  </ul>
-</lb-list>
+<ul lb-list="notes">
+  <template lb-key="id">
+    <li lb-cell="text"></li>
+  </template>
+</ul>
 ```
 
 ## Run it

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

@@ -8,37 +8,37 @@ that allows a user to add a note.
 ```html
 <!-- src/pages/about.page.html -->
 <h2>Notes</h2>
-<form lb-insert lb-query="notes">
+<form lb-action="lb-row-insert" lb-list="notes">
   <input lb-cell="text" placeholder="Write a note" />
   <button type="submit">Add</button>
 </form>
 
-<lb-list lb-query="notes">
-  <ul>
-    <template lb-key="id">
-      <li lb-cell="text"></li>
-    </template>
-  </ul>
-</lb-list>
+<ul lb-list="notes">
+  <template lb-key="id">
+    <li lb-cell="text"></li>
+  </template>
+</ul>
 ```
 
-`lb-insert` on a `<form>` gathers its `lb-cell`s into a values map and
-submits them against `lb-query`. There's no `lb-key` — there's no row
+`lb-action="lb-row-insert"` on a `<form>` gathers its `lb-cell`s into a values
+map on submit and sends them against `lb-list`. 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.
 
 ## Implementing CRUD server-side
 
-Our CRUD operations go into the page's hooks file:
+Our CRUD operations go into the page's requests file:
 
 ```ts
-// src/pages/about.hooks.ts
+// src/pages/about.requests.ts
 import { patch } from "@loadbare/app/server";
 
-export const hooks = {
-  // ...beforeGet and actions unchanged...
+export const requests = {
+  // ...onPageEnter and actions unchanged...
   crud: {
     notes: {
-      tupleInsert: {
+      rowInsert: {
         run: async (ctx, { values }) => {
           const note = await ctx.db.addNote(values.text);
           return { notes: patch({ rows: [note] }) };
@@ -50,12 +50,12 @@ export const hooks = {
 };
 ```
 
-`tupleInsert` is a CRUD operation, declared under `crud` and keyed by
+`rowInsert` is a CRUD operation, declared under `crud` and keyed by
 query name.  
 
 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` 
-with a single new row and the `<lb-list>` element just adds the row.
+with a single new row and the hub just adds the row.
 
 ## Extending the database
 

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

@@ -6,34 +6,32 @@ Now that we can add notes, we need to be able to delete a note.
 
 ```html
 <!-- src/pages/about.page.html -->
-<lb-list lb-query="notes">
-  <ul>
-    <template lb-key="id">
-      <li>
-        <span lb-cell="text"></span>
-        <button lb-delete>Delete</button>
-      </li>
-    </template>
-  </ul>
-</lb-list>
+<ul lb-list="notes">
+  <template lb-key="id">
+    <li>
+      <span lb-cell="text"></span>
+      <button lb-action="lb-row-delete">Delete</button>
+    </li>
+  </template>
+</ul>
 ```
 
 The `<li>` now has two children, so the text moves onto its own `<span>`.
-`lb-delete` needs no form — just the `lb-query` and `lb-key` already in
-scope from its ancestors.
+`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.
 
 ## Implementing delete server-side
 
 ```ts
-// src/pages/about.hooks.ts
+// src/pages/about.requests.ts
 import { patch } from "@loadbare/app/server";
 
-export const hooks = {
-  // ...beforeGet and actions unchanged...
+export const requests = {
+  // ...onPageEnter and actions unchanged...
   crud: {
     notes: {
-      // ...tupleInsert unchanged...
-      tupleDelete: {
+      // ...rowInsert unchanged...
+      rowDelete: {
         run: async (ctx, { key }) => {
           await ctx.db.deleteNote(key);
           return { notes: patch({ drop: [key] }) };

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

@@ -6,37 +6,35 @@ Now we edit a row in place, instead of removing and re-adding it.
 
 ```html
 <!-- src/pages/about.page.html -->
-<lb-list lb-query="notes">
-  <ul>
-    <template lb-key="id">
-      <li>
-        <form lb-update>
-          <input lb-cell="text" />
-          <button type="submit">Save</button>
-        </form>
-        <button lb-delete>Delete</button>
-      </li>
-    </template>
-  </ul>
-</lb-list>
+<ul lb-list="notes">
+  <template lb-key="id">
+    <li>
+      <form lb-action="lb-row-update">
+        <input lb-cell="text" />
+        <button type="submit">Save</button>
+      </form>
+      <button lb-action="lb-row-delete">Delete</button>
+    </li>
+  </template>
+</ul>
 ```
 
-`lb-update` gathers its `lb-cell`s the same way `lb-insert` does, but
-also reads `lb-key` from the row it's inside — the same ancestor
-`lb-delete` already reads.
+`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.
 
 ## Implementing update server-side
 
 ```ts
-// src/pages/about.hooks.ts
+// src/pages/about.requests.ts
 import { patch } from "@loadbare/app/server";
 
-export const hooks = {
-  // ...beforeGet and actions unchanged...
+export const requests = {
+  // ...onPageEnter and actions unchanged...
   crud: {
     notes: {
-      // ...tupleInsert, tupleDelete unchanged...
-      tupleUpdate: {
+      // ...rowInsert, rowDelete unchanged...
+      rowUpdate: {
         run: async (ctx, { key, values }) => {
           const note = await ctx.db.updateNote(key, values.text);
           return { notes: patch({ rows: [note] }) };
@@ -50,7 +48,7 @@ export const hooks = {
 
 With more than one note, `key` is what says which row this request
 means. `patch({ rows: [note] })` looks like insert's response, but since
-this id already exists, `<lb-list>` updates that row instead of adding
+this id already exists, the hub updates that row instead of adding
 one.
 
 ## Extending the database

package/docs/tutorials/080-widget-requests.md

@@ -24,8 +24,8 @@ how Loadbare internals work.
 // src/note-input.browser.ts
 import {
   ATTR_CELL,
-  ATTR_KEY,
-  ATTR_QUERY,
+  ATTR_KEY_VALUE,
+  ATTR_LIST,
   ATTR_VALUE,
   LB_EVENT_NAME,
 } from "@loadbare/app/constants";
@@ -42,14 +42,20 @@ class NoteInput extends HTMLElement {
     this.addEventListener("change", () => {
       const input = this.querySelector("input");
       if (!input) return;
-      const query = this.closest(`[${ATTR_QUERY}]`)?.getAttribute(ATTR_QUERY);
-      const key = this.closest(`[${ATTR_KEY}]`)?.getAttribute(ATTR_KEY);
+      const list = this.closest(`[${ATTR_LIST}]`)?.getAttribute(ATTR_LIST);
+      const key = this.closest(`[${ATTR_KEY_VALUE}]`)?.getAttribute(ATTR_KEY_VALUE);
       const cell = this.getAttribute(ATTR_CELL);
-      if (!query || !key || !cell) return;
+      if (!list || !key || !cell) return;
       this.dispatchEvent(
         new CustomEvent(LB_EVENT_NAME, {
           bubbles: true,
-          detail: { op: "cell-change", query, key, cell, value: input.value },
+          detail: {
+            action: "lb-cell-change",
+            list,
+            key,
+            cell,
+            value: input.value,
+          },
         }),
       );
     });
@@ -61,39 +67,37 @@ customElements.define("note-input", NoteInput);
 
 A widget with both a `.html` and a `.browser.ts` file shares one tag name; the
 build finds each half independently. On change, it reads its own
-`lb-query`/`lb-key`/`lb-cell` coordinates and dispatches a `cell-change`
-request itself, the way `lb-update` does for a whole form.
+`lb-list`/`lb-key-value`/`lb-cell` coordinates and dispatches a `lb-cell-change`
+request itself, the way `lb-row-update` does for a whole form.
 
 ## Using it
 
 ```html
 <!-- src/pages/about.page.html -->
-<lb-list lb-query="notes">
-  <ul>
-    <template lb-key="id">
-      <li>
-        <note-input lb-cell="text"></note-input>
-        <button lb-delete>Delete</button>
-      </li>
-    </template>
-  </ul>
-</lb-list>
+<ul lb-list="notes">
+  <template lb-key="id">
+    <li>
+      <note-input lb-cell="text"></note-input>
+      <button lb-action="lb-row-delete">Delete</button>
+    </li>
+  </template>
+</ul>
 ```
 
-The `<form lb-update>` and Save button are gone — `note-input` commits on
+The `lb-row-update` form and Save button are gone — `note-input` commits on
 every change, so there's nothing left to batch.
 
 ## Answering it server-side
 
 ```ts
-// src/pages/about.hooks.ts
+// src/pages/about.requests.ts
 import { patch } from "@loadbare/app/server";
 
-export const hooks = {
-  // ...beforeGet and actions unchanged...
+export const requests = {
+  // ...onPageEnter and actions unchanged...
   crud: {
     notes: {
-      // ...tupleInsert, tupleDelete, tupleUpdate unchanged...
+      // ...rowInsert, rowDelete, rowUpdate unchanged...
       cellChange: {
         run: async (ctx, { key, value }) => {
           const note = await ctx.db.updateNote(key, value);

package/docs/tutorials/090-using-widget-libraries.md

@@ -46,7 +46,7 @@ regardless of where the script came from:
 
 ```html
 <!-- src/pages/index.page.html -->
-<div lb-query="status">
+<div lb-row="status">
   <lb-select lb-cell="state">
     <option value="open">Open</option>
     <option value="closed">Closed</option>

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@loadbare/app",
   "description": "High performance web app framework for server-bound applications",
-  "version": "0.5.6",
+  "version": "0.6.0",
   "type": "module",
   "files": [
     "dist",
@@ -18,7 +18,6 @@
     ".": "./dist/hub/lb-hub.browser.js",
     "./constants": "./dist/core/lb-constants.js",
     "./types": "./dist/core/lb-types.js",
-    "./rows": "./dist/hub/lb-rows.js",
     "./server": "./dist/server/lb-server.js",
     "./express": "./dist/server/lb-express.js",
     "./build": "./dist/build/elements.js"

package/dist/hub/lb-rows.d.ts

@@ -1,18 +0,0 @@
-import type { Projection, QueryResult } from "../core/lb-types";
-/**
- * Where a row belongs, called with the row detached on its first appearance.
- *
- * The default puts it immediately before the template, so rows accumulate in
- * the order they arrive and the template stays put as the insertion marker.
- */
-export type Place = (row: Element, tuple: QueryResult, template: HTMLTemplateElement) => void;
-/**
- * Land a projection in a widget's subtree.
- *
- * `rows` is the whole set, so it decides membership and order: every row is
- * placed in the order given, and a row whose key did not arrive is gone.
- * `patch` disturbs only what it names — a row it did not mention keeps its
- * contents and its position.
- */
-export declare function applyRows(scope: Element, result: Projection, place?: Place): void;
-//# sourceMappingURL=lb-rows.d.ts.map

package/dist/hub/lb-rows.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"lb-rows.d.ts","sourceRoot":"","sources":["../../hub/lb-rows.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAGhE;;;;;GAKG;AACH,MAAM,MAAM,KAAK,GAAG,CAClB,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,WAAW,EAClB,QAAQ,EAAE,mBAAmB,KAC1B,IAAI,CAAC;AAsCV;;;;;;;GAOG;AACH,wBAAgB,SAAS,CACvB,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,UAAU,EAClB,KAAK,GAAE,KAAc,GACpB,IAAI,CAkDN"}