@loadbare/app 0.5.6 → 0.7.0

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,40 @@ that allows a user to add a note.
 ```html
 <!-- src/pages/about.page.html -->
 <h2>Notes</h2>
-<form lb-insert lb-query="notes">
-  <input lb-cell="text" placeholder="Write a note" />
-  <button type="submit">Add</button>
-</form>
+<section lb-list="notes">
+  <form lb-action="lb-row-insert">
+    <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>
+</section>
 ```
 
-`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 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.
 
 ## 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 +53,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

@@ -9,11 +9,9 @@ changes.
 
 ## Writing the widget
 
-Our new custom input will no longer rely on Loadbare's form handling,
-and so it must reimplement the data scoping logic that is in
-Loadbare.  This reimplementation approach is neither encouraged nor
-discouraged.  This tutorial shows only that it is possible, and exposes
-how Loadbare internals work.
+Our new custom input will no longer rely on Loadbare's form handling.  It
+says what happened and what its value is.  Where it sits, the list, the row
+and the cell, is added by the hub.
 
 ```html
 <!-- src/note-input.html -->
@@ -22,13 +20,7 @@ how Loadbare internals work.
 
 ```ts
 // src/note-input.browser.ts
-import {
-  ATTR_CELL,
-  ATTR_KEY,
-  ATTR_QUERY,
-  ATTR_VALUE,
-  LB_EVENT_NAME,
-} from "@loadbare/app/constants";
+import { ATTR_VALUE, LB_EVENT_NAME } from "@loadbare/app/constants";
 
 class NoteInput extends HTMLElement {
   static observedAttributes = [ATTR_VALUE];
@@ -42,14 +34,10 @@ 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 cell = this.getAttribute(ATTR_CELL);
-      if (!query || !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", value: input.value },
         }),
       );
     });
@@ -60,40 +48,39 @@ 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.
+build finds each half independently. On change, it dispatches a
+`lb-cell-change` carrying the input's value. The hub adds the list, the key
+of the row it is in and its own `lb-cell`, the same way it does for a
+`lb-row-update` 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.7.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"
@@ -33,7 +32,7 @@
     "prebuild": "node --eval \"fs.rmSync('dist',{recursive:true,force:true})\" --input-type=module",
     "build:server": "tsc --project tsconfig.build.json",
     "build": "npm run build:server",
-    "postbuild": "node --eval \"fs.chmodSync('dist/build/cli.js', 0o755)\" --input-type=module",
+    "postbuild": "node --eval \"fs.chmodSync('dist/build/cli.js', 0o755)\" --input-type=module && node ../../scripts/check-dist-imports.mjs",
     "test": "tsx --test \"tests/**/*.test.ts\"",
     "typecheck": "tsc --noEmit",
     "format": "prettier --write .",

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"}

package/dist/hub/lb-rows.js

@@ -1,106 +0,0 @@
-/// <reference lib="dom" />
-/**
- * The row machinery a list widget shares — see docs/reference/custom-elements.md,
- * "Accepting rows".
- *
- * A widget owns where a row goes and nothing else. Cloning the template,
- * matching a tuple to the row already showing it, and filling that row are
- * the same in every list, so they are here, and a widget that sorts or groups
- * supplies one function rather than a second implementation of all of it.
- */
-import { ATTR_KEY, ATTR_ROW_COUNT } from "../core/lb-constants";
-import { applyTuple } from "./lb-apply";
-const before = (row, _tuple, template) => {
-    template.parentElement.insertBefore(row, template);
-};
-/** The row template: the one the page author wrote inside this widget. */
-function templateIn(scope) {
-    const template = scope.querySelector("template");
-    if (!template) {
-        console.error(`lb-rows: <${scope.localName}> has no <template> to clone`);
-        return null;
-    }
-    if (!template.getAttribute(ATTR_KEY)) {
-        console.error(`lb-rows: the <template> in <${scope.localName}> has no ${ATTR_KEY} ` +
-            `naming the column that identifies a row`);
-        return null;
-    }
-    return template;
-}
-/**
- * The rows already showing, by the key value each carries.
- *
- * `lb-key` names the key column on the template and carries the key value on
- * a live row. One name in two positions, and never ambiguous, because a
- * template is not a row.
- */
-function showing(scope, template) {
-    const rows = new Map();
-    for (const el of scope.querySelectorAll(`[${ATTR_KEY}]`)) {
-        if (el !== template)
-            rows.set(el.getAttribute(ATTR_KEY), el);
-    }
-    return rows;
-}
-/**
- * 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 function applyRows(scope, result, place = before) {
-    const template = templateIn(scope);
-    if (!template)
-        return;
-    const keyCell = template.getAttribute(ATTR_KEY);
-    const rows = showing(scope, template);
-    const upsert = (tuple) => {
-        const key = tuple[keyCell];
-        if (key === undefined) {
-            console.error(`lb-rows: a tuple for <${scope.localName}> has no '${keyCell}' cell`);
-            return null;
-        }
-        let row = rows.get(key);
-        const fresh = row === undefined;
-        if (!row) {
-            row = template.content.firstElementChild.cloneNode(true);
-            row.setAttribute(ATTR_KEY, key);
-            rows.set(key, row);
-        }
-        // Fill before insertion. The attributes are already there when the row
-        // upgrades, which is the same thing that makes hydration and refresh one
-        // operation everywhere else.
-        applyTuple(row, tuple);
-        if (fresh || result.op === "rows")
-            place(row, tuple, template);
-        return key;
-    };
-    if (result.op === "rows") {
-        const arrived = new Set();
-        for (const tuple of result.rows) {
-            const key = upsert(tuple);
-            if (key !== null)
-                arrived.add(key);
-        }
-        for (const [key, row] of rows)
-            if (!arrived.has(key))
-                row.remove();
-    }
-    else {
-        for (const tuple of result.rows ?? [])
-            upsert(tuple);
-        for (const key of result.drop ?? [])
-            rows.get(key)?.remove();
-    }
-    // How many rows are showing, counted from the DOM rather than from either
-    // branch above, so a set and a patch report the same fact the same way.
-    //
-    // It is stamped here because only this function knows the count: it is the
-    // one conditional a page cannot be sent, since the server answers with rows
-    // and says nothing about how many survived reconciliation. A page says what
-    // an empty list looks like in a stylesheet, and no list widget carries code
-    // for it. See docs/reference/data-binding.md.
-    scope.setAttribute(ATTR_ROW_COUNT, String(showing(scope, template).size));
-}

package/dist/tests/assemble.test.d.ts

@@ -1,8 +0,0 @@
-/**
- * Assembling a chrome file and its pages — see build/assemble.ts.
- *
- * The chrome and pages together are one write to a temp tree per test,
- * since assemble() reads from disk rather than taking sources in memory.
- */
-export {};
-//# sourceMappingURL=assemble.test.d.ts.map

package/dist/tests/assemble.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"assemble.test.d.ts","sourceRoot":"","sources":["../../tests/assemble.test.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}