@loadbare/app 0.4.0 → 0.5.0

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

@@ -0,0 +1,73 @@
+# Custom Element Code
+
+So far we have simple scalar data binding, and server-implemented
+actions that can be requested from the server.
+
+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.
+
+## Using the element
+
+We will improve the visit counter to show either "1 time" or "x times".
+The first step is to refer to a new custom element, which we will
+then implement.
+
+```html
+<!-- src/pages/about.page.html -->
+<div lb-query="visits">
+  <p>This page has been <visit-count lb-cell="count"></visit-count>.</p>
+  <button lb-action="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"`.
+
+## Writing the class
+
+We put the Javascript class implementation into a file named 
+after the tag: `visit-count.ts`.  The loadbare builder will recognize
+the file as being associated with a custom element that was used 
+in the app, and add its class to `client.js`.
+
+
+```ts
+// src/visit-count.ts
+import { ATTR_VALUE } from "@loadbare/app/constants";
+
+class VisitCount extends HTMLElement {
+  static observedAttributes = [ATTR_VALUE];
+
+  attributeChangedCallback(_name: string, _old: string, value: string) {
+    const count = Number(value);
+    this.textContent = `visited ${count} ${count === 1 ? "time" : "times"}`;
+  }
+}
+
+customElements.define("visit-count", VisitCount);
+```
+
+A Loadbare custom widget is just a custom element, we follow the standards
+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 
+attribute changes, `attributeChangedCallback` fires and rewrites the text.
+
+## Run it
+
+```
+npm run dev
+```
+
+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)
+Next: [Conditional Rendering](./065-conditional-rendering.md)

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

@@ -0,0 +1,161 @@
+# Conditional Rendering
+
+Every widget so far has data to display, always. Real apps also need to
+show or hide a whole chunk of markup depending on state — a wizard step,
+a tab, a form that only appears once a checkbox is ticked. In a framework
+that builds the DOM from a template, that's an `if` in the template.
+
+Loadbare only ships static HTML, and hydrates elements that are already
+there.  We do not have an `if`, but we also do not need one.  For
+conditional rendering, all possibilities ship in the HTML, and visibility
+is controlled by the custom element.
+
+## Adding a wizard to the About page
+
+We'll add a small three-step wizard, unrelated to the notes and visit
+count already on the page. Every step is in the document from the start;
+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">
+  <section data-step="name">
+    <h3>1. Name</h3>
+    <p>This step is not hidden, because it's the one the page ships showing.</p>
+  </section>
+  <section data-step="address" hidden>
+    <h3>2. Address</h3>
+  </section>
+  <section data-step="confirm" hidden>
+    <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>
+```
+
+`lb-cell="step"` on `<lb-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.
+
+## Writing the class
+
+```ts
+// src/lb-wizard.ts
+import { ATTR_VALUE } from "@loadbare/app/constants";
+
+class LbWizard extends HTMLElement {
+  static observedAttributes = [ATTR_VALUE];
+
+  attributeChangedCallback(_name: string, _old: string, value: string) {
+    const steps = [...this.querySelectorAll<HTMLElement>("[data-step]")];
+    const at = steps.findIndex((step) => step.dataset.step === value);
+    if (at === -1) return;
+
+    for (const step of steps) step.hidden = step.dataset.step !== value;
+    this.end("back", at === 0);
+    this.end("next", at === steps.length - 1);
+  }
+
+  private end(nav: string, disabled: boolean): void {
+    const button = this.querySelector<HTMLButtonElement>(`[data-nav="${nav}"]`);
+    if (button) button.disabled = disabled;
+  }
+}
+
+customElements.define("lb-wizard", LbWizard);
+```
+
+The whole conditional is one line: `step.hidden = step.dataset.step !==
+value`. Every step is walked on every value change, so the widget never
+needs to remember which one was showing before — it just sets `hidden` on
+all of them from the current value.
+
+## Implementing it server-side
+
+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`
+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
+does, and every reload asks for it again instead of assuming it.
+
+```ts
+// src/pages/about.queries.ts
+export const queries = {
+  // ...visits and notes unchanged...
+  signup: async (ctx) => ({ step: await ctx.db.signupStep() }),
+};
+```
+
+```ts
+// src/pages/about.hooks.ts
+export const hooks = {
+  // ...beforeGet, resetVisits, and crud unchanged...
+  actions: {
+    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"] },
+  },
+};
+```
+
+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
+hasn't confirmed, the same rule the visit count follows for its number.
+
+## Extending the database
+
+```ts
+// src/database.ts
+const STEPS = ["name", "address", "confirm"];
+
+export function openDb() {
+  return {
+    // ...visitCount(), recordVisit(), resetVisits(), notes, etc. unchanged...
+    async signupStep() {
+      return (await read()).step ?? STEPS[0];
+    },
+    async moveSignup(delta) {
+      const current = await read();
+      const at = STEPS.indexOf(current.step ?? STEPS[0]);
+      const step = STEPS[Math.min(Math.max(at + delta, 0), STEPS.length - 1)];
+      await write({ step });
+    },
+  };
+}
+```
+
+Clamping happens here, not in the widget — the widget only ever displays
+a step name it's given, it never computes one.
+
+## Run it
+
+```
+npm run dev
+```
+
+Open the About page. Step 1 is showing, Back is disabled. Click Next
+twice — Step 3 shows and Next disables. Click Back — Step 2 reappears and
+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
+back on Step 1 like the very first visit.
+
+View source: all three `<section>`s are on the page the whole time. Only
+their `hidden` attribute changes.
+
+---
+Prev: [Custom Element Code](./060-custom-element-code.md)
+Next: [Displaying a List](./070-displaying-a-list.md)

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

@@ -0,0 +1,137 @@
+# 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>`.
+
+## Writing the query
+
+```ts
+// src/pages/about.queries.ts
+import { rows } from "@loadbare/app/server";
+
+export const queries = {
+  visits: async (ctx) => ({ count: String(await ctx.db.visitCount()) }),
+  notes: async (ctx) => rows(await 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()`.
+
+## Extending the database
+
+Now let's extend our bespoke json-based database with operations on a list
+of notes.
+
+```ts
+// src/database.ts
+import { readFile, writeFile } from "node:fs/promises";
+
+const DATA_FILE = new URL("./.lb-data.json", import.meta.url);
+
+async function read() {
+  try {
+    return { visitCount: 0, notes: [], ...JSON.parse(await readFile(DATA_FILE, "utf-8")) };
+  } catch {
+    return { visitCount: 0, notes: [] };
+  }
+}
+
+async function write(patch) {
+  const current = await read();
+  await writeFile(DATA_FILE, JSON.stringify({ ...current, ...patch }), "utf-8");
+}
+
+export function openDb() {
+  return {
+    async visitCount() {
+      return (await read()).visitCount;
+    },
+    async recordVisit() {
+      const current = await read();
+      await write({ visitCount: current.visitCount + 1 });
+    },
+    async resetVisits() {
+      await write({ visitCount: 0 });
+    },
+    async notes() {
+      return (await read()).notes;
+    },
+  };
+}
+```
+
+`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.
+
+> 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.  
+>
+> 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.
+
+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.
+
+```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>
+```
+
+## Run it
+
+```
+npm run dev
+```
+
+Open the About page. `notes` is empty, so the list renders no `<li>` —
+just an empty `<ul>`.  Next up we will see how to add to the list.
+
+---
+Prev: [Conditional Rendering](./065-conditional-rendering.md)
+Next: [Inserting Into a List](./072-inserting-into-a-list.md)

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

@@ -0,0 +1,88 @@
+# Inserting Into a List
+
+So far we have a read-only empty list of notes.  Now we will add a form
+that allows a user to add a note.
+
+## Adding the form
+
+```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>
+
+<lb-list lb-query="notes">
+  <ul>
+    <template lb-key="id">
+      <li lb-cell="text"></li>
+    </template>
+  </ul>
+</lb-list>
+```
+
+`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
+yet.
+
+## Implementing CRUD server-side
+
+Our CRUD operations go into the page's hooks file:
+
+```ts
+// src/pages/about.hooks.ts
+import { patch } from "@loadbare/app/server";
+
+export const hooks = {
+  // ...beforeGet and actions unchanged...
+  crud: {
+    notes: {
+      tupleInsert: {
+        run: async (ctx, { values }) => {
+          const note = await ctx.db.addNote(values.text);
+          return { notes: patch({ rows: [note] }) };
+        },
+        refresh: [],
+      },
+    },
+  },
+};
+```
+
+`tupleInsert` 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.
+
+## Extending the database
+
+```ts
+// src/database.ts
+export function openDb() {
+  return {
+    // ...visitCount(), recordVisit(), resetVisits(), notes() unchanged...
+    async addNote(text) {
+      const current = await read();
+      const note = { id: crypto.randomUUID(), text };
+      await write({ notes: [...current.notes, note] });
+      return note;
+    },
+  };
+}
+```
+
+## Run it
+
+```
+npm run dev
+```
+
+Open the About page. Type a note, click Add — it appears in the list.
+Reload — it's still there.
+
+---
+Prev: [Displaying a List](./070-displaying-a-list.md)
+Next: [Deleting From a List](./074-deleting-from-a-list.md)

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

@@ -0,0 +1,77 @@
+# Deleting From a List
+
+Now that we can add notes, we need to be able to delete a note.
+
+## Adding the button
+
+```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>
+```
+
+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.
+
+## Implementing delete server-side
+
+```ts
+// src/pages/about.hooks.ts
+import { patch } from "@loadbare/app/server";
+
+export const hooks = {
+  // ...beforeGet and actions unchanged...
+  crud: {
+    notes: {
+      // ...tupleInsert unchanged...
+      tupleDelete: {
+        run: async (ctx, { key }) => {
+          await ctx.db.deleteNote(key);
+          return { notes: patch({ drop: [key] }) };
+        },
+        refresh: [],
+      },
+    },
+  },
+};
+```
+
+`patch({ drop: [key] })` removes exactly that row and leaves every other
+one alone.
+
+## Extending the database
+
+```ts
+// src/database.ts
+export function openDb() {
+  return {
+    // ...visitCount(), recordVisit(), resetVisits(), notes(), addNote() unchanged...
+    async deleteNote(id) {
+      const current = await read();
+      await write({ notes: current.notes.filter((note) => note.id !== id) });
+    },
+  };
+}
+```
+
+## Run it
+
+```
+npm run dev
+```
+
+Add a couple of notes, then click Delete on one — it disappears, the
+other stays put. Reload — it's still gone.
+
+---
+Prev: [Inserting Into a List](./072-inserting-into-a-list.md)
+Next: [Updating a List Item](./076-updating-a-list-item.md)

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

@@ -0,0 +1,86 @@
+# Updating a List Item
+
+Now we edit a row in place, instead of removing and re-adding it.
+
+## Adding the form
+
+```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>
+```
+
+`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.
+
+## Implementing update server-side
+
+```ts
+// src/pages/about.hooks.ts
+import { patch } from "@loadbare/app/server";
+
+export const hooks = {
+  // ...beforeGet and actions unchanged...
+  crud: {
+    notes: {
+      // ...tupleInsert, tupleDelete unchanged...
+      tupleUpdate: {
+        run: async (ctx, { key, values }) => {
+          const note = await ctx.db.updateNote(key, values.text);
+          return { notes: patch({ rows: [note] }) };
+        },
+        refresh: [],
+      },
+    },
+  },
+};
+```
+
+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
+one.
+
+## Extending the database
+
+```ts
+// src/database.ts
+export function openDb() {
+  return {
+    // ...visitCount(), recordVisit(), resetVisits(), notes(), addNote(), deleteNote() unchanged...
+    async updateNote(id, text) {
+      const current = await read();
+      const notes = current.notes.map((note) =>
+        note.id === id ? { ...note, text } : note,
+      );
+      await write({ notes });
+      return notes.find((note) => note.id === id);
+    },
+  };
+}
+```
+
+## Run it
+
+```
+npm run dev
+```
+
+Add a couple of notes, change one's text, click Save — that row updates,
+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)