@loadbare/app 0.4.0 → 0.5.0

package/docs/tutorials/000-getting-started.md

@@ -0,0 +1,86 @@
+# Getting Started
+
+This first tutorial sets us up with an empty application shell
+and a simple express server.  This will be the foundation for 
+creating a full database application.
+
+## The chrome file
+
+Write a file `src/chrome.html`.  The location is convention, in
+fact Loadbare only requires exactly one file named `chrome.html`
+anywhere in the `src/` tree.
+
+The chrome is plain old HTML.  All Loadbare chrome, pages, and 
+widgets are plain old HTML and custom elements. 
+
+At minimum, the chrome must contain:
+
+- a link to the `client.js` script
+- The `<lb-hub>` custom element just inside `<body>`
+- an empty `<main>` inside `<lb-hub>`
+
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>@Loadbare/app Tutorials</title>
+    <script src="/client.js" defer></script>
+  </head>
+  <body>
+    <lb-hub>
+      <main></main>
+    </lb-hub>
+  </body>
+</html>
+```
+
+The client script `client.js` is generated by the builder.  In loadbare, 
+`client.js` is the combination of Javascript class definitions for all of
+the custom elements used anywhere in `src/`.   In this basic starting point,
+we have `<lb-hub>` as the only custom element, so `client.js` will just
+contain the Javascript class `LbHub`.
+
+## The dev script
+
+Add a command to package.json that builds the app. 
+
+```json
+{
+  "scripts": {
+    "dev": "loadbare-app-build --watch & node server.js"
+  }
+}
+```
+
+By default the builder puts all output into `dist/`.
+
+## The express server
+
+Create `server.js` as an express server:
+
+```js
+import express from "express";
+import { readFileSync } from "node:fs";
+
+const app = express();
+
+app.use("/client.js", express.static("dist/client.js"));
+
+app.get("/", (_req, res) =>
+  res.type("html").send(readFileSync("dist/app.html", "utf-8")),
+);
+
+app.listen(8787);
+```
+
+## Run it
+
+Try `npm run dev`, and navigate the browser to localhost:8787, you
+should see an empty page, with a console message, and the view source
+option will show exactly the chrome as it was written on disk
+with its empty `<main>`.
+
+---
+
+Next: [Pages and Navigation](./010-pages-and-navigation.md)

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

@@ -0,0 +1,129 @@
+# Pages and Navigation
+
+In our first tutorial, [Getting Started](./000-getting-started.md), we 
+create an empty
+`<main>` with no content. 
+
+Now we will see how to make pages and navigate between them by creating
+two simple static pages.
+
+## Two page files
+
+Write two files ending `.page.html` for two pages,
+`src/pages/index.page.html` and `src/pages/about.page.html`. Like the
+chrome, a page is found by its filename, not its directory; we use 
+the `src/pages` directory by convention and for convenience.
+
+The file `index.page.html` is special in Loadbare.  Loadbare considers
+this the landing page.  If a user navigates to `myapp.example.com` without
+a page specified, Loadbare displays `index.page.html`.
+
+
+```html
+<!-- src/pages/index.page.html -->
+<h1>Home</h1>
+<p>This is the home page.</p>
+```
+
+```html
+<!-- src/pages/about.page.html -->
+<h1>About</h1>
+<p>This is the about page.</p>
+```
+
+## Linking between them
+
+Add a `<nav>` to the chrome, with one anchor per page.  
+
+Also add the `<dialog lb-unknown-page>` element, so the hub `<lb-hub>` can
+display something to the user if they type a URL that has no matching page.
+
+```html
+<!-- src/chrome.html -->
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>Pages and Navigation</title>
+    <script src="/client.js" defer></script>
+  </head>
+  <body>
+    <lb-hub>
+      <nav>
+        <!-- a bare link to "/" goes to page "index" -->
+        <a href="/" lb-nav-link>Home</a>
+        <a href="/about" lb-nav-link>About</a>
+      </nav>
+      <main></main>
+      <dialog lb-unknown-page>The page <span lb-cell="page"></span> is not in this app.</dialog>
+    </lb-hub>
+  </body>
+</html>
+```
+
+Here we introduce the attribute `lb-nav-link`, which indicates the link
+should navigate within the app.  When the user clicks, the hub `<lb-hub>`
+intercepts the event and swaps the page's HTML into the `<main>` element. 
+The hub ensures the back button works by calling `history.pushState` on 
+navigation, and catching the browser's `popstate` event.  
+
+An anchor without `lb-nav-link` is left alone and behaves like an ordinary
+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-cell` attribute will be explained when we get to data binding.
+
+## Serving every route
+
+The server sends the same document for every route, which is a monolithic
+assembly of chrome and all pages (as `<template>` elements). The hub
+`<lb-hub>` picks which page to show from the URL.
+
+With this in mind, we modify the code from the previous example to
+serve the monolithic HTML for any get route.
+
+```js
+// server.js
+import express from "express";
+import { readFileSync } from "node:fs";
+
+const app = express();
+
+app.use("/client.js", express.static("dist/client.js"));
+
+// Getting Started had app.get("/", ...); this catches every path instead
+app.get(/.*/, (_req, res) =>
+  res.type("html").send(readFileSync("dist/app.html", "utf-8")),
+);
+
+app.listen(8787);
+```
+
+The static route for `/client.js` has to come before the catch-all, or the
+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.
+
+## Run it
+
+```
+npm run dev
+```
+
+Open `http://localhost:8787/`. Click between Home and About — `<main>`
+swaps instantly, with no server request for markup. View source still shows
+exactly what's on disk: the chrome, both page hosts (each inside its own
+`<template>`), and the `<dialog>`. Then try a path neither page defines,
+like `http://localhost:8787/badpagename`, and confirm the dialog announces it.
+
+---
+Prev: [Getting Started](./000-getting-started.md)
+Next: [Adding CSS](./020-css.md)

package/docs/tutorials/020-css.md

@@ -0,0 +1,103 @@
+# Adding CSS
+
+Loadbare has a precise precedence opinion for CSS — see [CSS](../reference/css.md)
+for the full rule and why. For now we just want to load some styles onto
+the two pages from [Pages and Navigation](./010-pages-and-navigation.md).
+
+The Loadbare build concatenates every `.css` file anywhere under `src` 
+into one bundle, sorted alphabetically by filename; a
+directory never affects that order, so a global stylesheet sorts first by
+naming itself something like `00-reset.css`.
+
+## Adding CSS to our two static pages
+
+We'll add two stylesheets: one global, one specific to a single page.
+
+```css
+/* src/00-global.css */
+body {
+  font-family: system-ui, sans-serif;
+  margin: 2rem;
+}
+
+nav a {
+  margin-right: 1rem;
+}
+```
+
+```css
+/* src/pages/about.css */
+.about-note {
+  color: #555;
+  font-style: italic;
+}
+```
+
+Loadbare doesn't pair a stylesheet with a page.  
+The name `about.css` for the page `about.page.html` is only a convention we're
+choosing for easy identification. Loadbare never enforces or
+even notices that the file has the same stem as an HTML page.
+
+Use the class in the page:
+
+```html
+<!-- src/pages/about.page.html -->
+<h1>About</h1>
+<p class="about-note">This is the about page.</p>
+```
+
+## Linking the bundle
+
+Add the stylesheet link to the chrome:
+
+```html
+<!-- src/chrome.html -->
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>Pages and Navigation</title>
+    <script src="/client.js" defer></script>
+    <!-- Add a standard stylesheet link -->
+    <link rel="stylesheet" href="/app.css" />
+  </head>
+  <body>
+    <lb-hub>
+      <nav>
+        <a href="/" lb-nav-link>Home</a>
+        <a href="/about" lb-nav-link>About</a>
+      </nav>
+      <main></main>
+      <dialog lb-unknown-page>The page <span lb-cell="page"></span> is not in this app.</dialog>
+    </lb-hub>
+  </body>
+</html>
+```
+
+And a static route for it in the server, the same way `/client.js` already
+has one:
+
+```js
+// server.js
+app.use("/client.js", express.static("dist/client.js"));
+app.use("/app.css", express.static("dist/app.css"));
+```
+
+Like `/client.js`, this has to come before the catch-all route, or the
+catch-all answers that request too.
+
+## Run it
+
+```
+npm run dev
+```
+
+Open `http://localhost:8787/`. Both pages should now use the system font
+and the wider margin from `00-global.css`; the About page's note should be
+grey and italic. View `dist/app.css` — it's `00-global.css`'s contents
+followed by `about.css`'s, in exactly that order, because `00-global.css`
+sorts first by name.
+
+---
+Prev: [Pages and Navigation](./010-pages-and-navigation.md)
+Next: [HTML Decomposition](./030-html-decomposition.md)

package/docs/tutorials/030-html-decomposition.md

@@ -0,0 +1,79 @@
+# HTML Decomposition
+
+So far we have been building a monolithic chrome, but this will soon
+become unwieldy.  We need to break it up so we can work with subtrees
+of the HTML in isolation.
+
+Loadbare interprets custom elements as server-side HTML 
+includes.  When the HTML contains `<my-custom-widget>`, and there
+is a file `my-custom-widget.html` anywhere in `src/`, the 
+Loadbare builder inserts the contents of `my-custom-widget.html` as the
+children of `<my-custom-widget>`.
+
+This HTML include feature has options for attributes and slots, but
+for now we will just do a static example.
+
+## Static decomposition of the navigation bar
+
+We begin by replacing the literal nav bar with an empty custom
+element, not yet defined:
+
+```html
+<!-- src/chrome.html -->
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>Pages and Navigation</title>
+    <script src="/client.js" defer></script>
+    <link rel="stylesheet" href="/app.css" />
+  </head>
+  <body>
+    <lb-hub>
+      <!-- replace this from the previous tutorial...
+      <nav>
+        <a href="/" lb-nav-link>Home</a>
+        <a href="/about" lb-nav-link>About</a>
+      </nav>
+      -->
+      <!-- ...with this empty custom element: -->
+      <app-nav></app-nav>
+      <main></main>
+      <dialog lb-unknown-page>The page <span lb-cell="page"></span> is not in this app.</dialog>
+    </lb-hub>
+  </body>
+</html>
+```
+
+Now we specify the HTML that should be inserted as children
+of `<app-nav>` by writing `src/app-nav.html`.
+
+```html
+<nav>
+    <a href="/" lb-nav-link>Home</a>
+    <a href="/about" lb-nav-link>About</a>
+</nav>
+```
+
+During the build, Loadbare locates `app-nav.html` and inserts its contents
+into the `<app-nav>` custom element, so the actual result will look like this:
+
+```html
+      <app-nav>
+        <nav>
+          <a href="/" lb-nav-link>Home</a>
+          <a href="/about" lb-nav-link>About</a>
+        </nav>
+      </app-nav>
+```
+
+## Dynamic Composition
+
+There is much more to HTML decomposition.  Custom elements can have
+slots and attributes that are resolved at build time.  Read all about
+them in [Custom Elements](../reference/custom-elements.md#html).
+
+---
+Prev: [CSS](./020-css.md)
+Next: [Displaying Data](040-displaying-data.md)
+

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

@@ -0,0 +1,169 @@
+# Displaying Data
+
+We now have the basics of a Loadbare app: the chrome, the express server,
+some CSS, and two pages.  But they are static, and the entire point of
+Loadbare is to build data-centric apps.  So now we add the first half of
+data-centric apps, displaying data. 
+
+## Data Binding 
+
+Loadbare can understand and process scalar cells, entities, and
+collections.  We begin with a simple scalar cell.
+
+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`.
+
+```html
+<!-- src/pages/about.page.html -->
+<h1>About</h1>
+<p class="about-note">This is the about page.</p>
+
+<div lb-query="visits">
+  <p>This page has been visited <span lb-cell="count"></span> times.</p>
+</div>
+```
+
+## Write the Query
+
+Put the query into `about.queries.ts`, which uses the same page stem,
+`about`, as `about.page.html`.
+
+```ts
+// src/pages/about.queries.ts
+export const queries = {
+  visits: async (ctx) => ({ count: String(await ctx.db.visitCount()) }),
+};
+```
+
+We have not yet implemented `ctx.db`, we will do that shortly.
+
+## Write the Before Get Hook
+
+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
+and increment the counter:
+
+
+```ts
+// src/pages/about.hooks.ts
+export const hooks = {
+  beforeGet: (ctx) => ctx.db.recordVisit(),
+};
+```
+
+Once again we are referring to a method on `ctx.db`, which we must now
+implement. 
+
+## Implement a simple database
+
+In a real application we would be connecting to some database server,
+but we want to keep the tutorial simple and step-by-step, so we will mock
+up a file-based database server that only does what the tutorial needs.
+
+
+```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 JSON.parse(await readFile(DATA_FILE, "utf-8"));
+  } catch {
+    return { visitCount: 0 };
+  }
+}
+
+export function openDb() {
+  return {
+    async visitCount() {
+      return (await read()).visitCount;
+    },
+    async recordVisit() {
+      const current = await read();
+      await writeFile(
+        DATA_FILE,
+        JSON.stringify({ visitCount: current.visitCount + 1 }),
+        "utf-8",
+      );
+    },
+  };
+}
+```
+
+Nothing here is Loadbare's concern — it never looks inside `ctx`. A real
+application would put a real database behind `openDb`, and would open it for
+the authenticated caller instead of the same file for everyone.
+
+## Wiring the server
+
+The Loadbare builder compiles a list of all hooks and queries.  
+Add the four
+lines below, and our server will correctly route all data channel 
+requests to the correct page code.
+
+```js
+// server.js
+import express from "express";
+import { readFileSync } from "node:fs";
+import { hubRoutes } from "@loadbare/app/express";
+import { hub } from "./dist/pages";
+import { openDb } from "./src/database";
+
+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.
+function contextFor(_req) {
+  return { db: openDb() };
+}
+app.use(hubRoutes(hub, contextFor));
+
+app.get(/.*/, (_req, res) =>
+  res.type("html").send(readFileSync("dist/app.html", "utf-8")),
+);
+
+app.listen(8787);
+```
+
+`dist/pages.ts` and our own `.ts` files mean `server.js` is no longer
+runnable by plain `node`. Swap the dev script to a TypeScript-capable
+runner:
+
+```json
+{
+  "scripts": {
+    "dev": "loadbare-app-build --watch & tsx server.js"
+  }
+}
+```
+
+## Run it
+
+```
+npm run dev
+```
+
+Open `http://localhost:8787/` and navigate to About a few times, using the
+nav links so `<main>` swaps in place. The count rises by one on every visit
+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.
+The full attribute vocabulary — actions, CRUD operations, lists, and
+navigation — is in [Data Binding](../reference/data-binding.md).
+
+---
+Prev: [HTML Decomposition](./030-html-decomposition.md)
+Next: [Actions](./050-actions.md)

package/docs/tutorials/050-actions.md

@@ -0,0 +1,77 @@
+# Actions
+
+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.
+
+## An action 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 -->
+<h1>About</h1>
+<p class="about-note">This is the about page.</p>
+
+<div lb-query="visits">
+  <p>This page has been visited <span lb-cell="count"></span> times.</p>
+  <button lb-action="resetVisits">Reset count</button>
+</div>
+```
+
+## Implement the action on the server
+
+Actions go into the page's hooks file:
+
+```ts
+// src/pages/about.hooks.ts
+export const hooks = {
+  beforeGet: (ctx) => ctx.db.recordVisit(),
+  actions: {
+    resetVisits: {
+      run: (ctx) => ctx.db.resetVisits(),
+      refresh: ["visits"],
+    },
+  },
+};
+```
+
+An action 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.
+
+## Extending the database
+
+We have to extend our bespoke database with `resetVisits`.
+
+```ts
+// src/database.ts
+export function openDb() {
+  return {
+    // ...visitCount() and recordVisit() unchanged...
+    async resetVisits() {
+      await write({ visitCount: 0 });
+    },
+  };
+}
+```
+
+`write` already merges over whatever's stored, so this only ever touches
+`visitCount`.
+
+## Run it
+
+```
+npm run dev
+```
+
+Open the About page a few times to raise the count, then click "Reset
+count" — it drops to zero in place, no reload. Reload anyway: it stays at
+zero, because the reset happened on the server, not just in the browser.
+
+---
+Prev: [Displaying Data](./040-displaying-data.md)
+Next: [Custom Element Code](./060-custom-element-code.md)