@loadbare/app 0.4.0 → 0.5.0

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

@@ -0,0 +1,124 @@
+# Widget Requests
+
+Our list example showed the use of forms and submit.  The inputs
+were passive in the sense that they did not trigger any change on their
+own.
+
+Now we will see how to make a widget that fires events when its value
+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.
+
+```html
+<!-- src/note-input.html -->
+<input type="text" />
+```
+
+```ts
+// src/note-input.ts
+import {
+  ATTR_CELL,
+  ATTR_KEY,
+  ATTR_QUERY,
+  ATTR_VALUE,
+  LB_EVENT_NAME,
+} from "@loadbare/app/constants";
+
+class NoteInput extends HTMLElement {
+  static observedAttributes = [ATTR_VALUE];
+
+  attributeChangedCallback(_name: string, _old: string, value: string) {
+    const input = this.querySelector("input");
+    if (input) input.value = value;
+  }
+
+  connectedCallback() {
+    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 },
+        }),
+      );
+    });
+  }
+}
+
+customElements.define("note-input", NoteInput);
+```
+
+A widget with both a `.html` and a `.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.
+
+## 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>
+```
+
+The `<form lb-update>` 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
+import { patch } from "@loadbare/app/server";
+
+export const hooks = {
+  // ...beforeGet and actions unchanged...
+  crud: {
+    notes: {
+      // ...tupleInsert, tupleDelete, tupleUpdate unchanged...
+      cellChange: {
+        run: async (ctx, { key, value }) => {
+          const note = await ctx.db.updateNote(key, value);
+          return { notes: patch({ rows: [note] }) };
+        },
+        refresh: [],
+      },
+    },
+  },
+};
+```
+
+`cellChange` reuses `updateNote` from [Updating a List Item](./076-updating-a-list-item.md)
+— the database doesn't care whether the edit came from a form's values
+map or one widget's value.
+
+## Run it
+
+```
+npm run dev
+```
+
+Edit a note's text and click elsewhere — it commits immediately, no Save
+button. Reload — the change is still there.
+
+---
+Prev: [Updating a List Item](./076-updating-a-list-item.md)
+Next: [Using Widget Libraries](./090-using-widget-libraries.md)

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

@@ -0,0 +1,75 @@
+# Using Widget Libraries
+
+[Displaying a List](./070-displaying-a-list.md) already installed one widget
+library, `@loadbare/widgets`. This tutorial covers what that step actually
+did, and why it is the same step for a library from anywhere else.
+
+[Custom Element Code](./060-custom-element-code.md) and
+[Widget Requests](./080-widget-requests.md) wrote widgets by hand, one
+file per tag, discovered because the tag turned up in a page. A widget
+installed from a package works the same way once the package is listed —
+listing the package is the only new piece.
+
+## Installing the library
+
+```
+npm install @loadbare/widgets
+```
+
+## Declaring the package
+
+The builder finds a widget by scanning for its filename. It scans the
+application's own `src/` without being asked; an installed package has to
+be listed first. That list lives in one file, `imports.ts`, at the root of
+`src/`:
+
+```ts
+// src/imports.ts
+export default ["@loadbare/widgets"];
+```
+
+List the package, not its tags. The builder scans it the same way it scans
+`src/`, so `lb-select.html` and `lb-select.js` inside the package define and
+register `<lb-select>` with nothing else written down. A package that ships
+compiled says which of its directories holds those files — see
+[Widgets from packages](../reference/builder.md#widgets-from-packages) — and
+that is the package author's line to write, not the application's.
+
+Only tags actually used in the chrome file or a page are bundled. Listing a
+package says where to look; it does not import anything on its own.
+
+## Using a tag
+
+Once the package is listed, a tag from the library is used exactly like a
+widget written by hand — the query scope and cell attributes work the same
+regardless of where the script came from:
+
+```html
+<!-- src/pages/index.page.html -->
+<div lb-query="status">
+  <lb-select lb-cell="state">
+    <option value="open">Open</option>
+    <option value="closed">Closed</option>
+  </lb-select>
+</div>
+```
+
+`lb-select` follows the `lb-value` contract
+[Custom Element Code](./060-custom-element-code.md) described: the hub
+writes the query result to `lb-value`, and the widget's own class —
+imported from `@loadbare/widgets`, not written in this
+application — reacts to it.
+
+## Where this stops
+
+This only covers consuming a published widget, not writing one for
+publication — that's the same class shape
+[Custom Element Code](./060-custom-element-code.md) and
+[Widget Requests](./080-widget-requests.md) already wrote, packaged and
+given an import specifier instead of living in an application's `src/`.
+It doesn't cover `lb-table`'s footer destination or `lb-picker`'s
+expansion parameters, which are in
+[The Basic Widget Library](../reference/widgets.md).
+
+---
+Prev: [Widget Requests](./080-widget-requests.md)

package/package.json

@@ -1,11 +1,10 @@
 {
   "name": "@loadbare/app",
   "description": "High performance web app framework for server-bound applications",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "type": "module",
   "files": [
     "dist",
-    "widgets",
     "docs",
     "README.md"
   ],
@@ -22,8 +21,7 @@
     "./rows": "./dist/hub/lb-rows.js",
     "./server": "./dist/server/lb-server.js",
     "./express": "./dist/server/lb-express.js",
-    "./build": "./dist/build/elements.js",
-    "./widgets/*": "./dist/widgets/*.js"
+    "./build": "./dist/build/elements.js"
   },
   "scripts": {
     "prepublishOnly": "npm run typecheck && npm run test && npm run build",
@@ -33,16 +31,10 @@
     "release:minor": "node scripts/bump-release.mjs minor",
     "release:major": "node scripts/bump-release.mjs major",
     "prebuild": "node --eval \"fs.rmSync('dist',{recursive:true,force:true})\" --input-type=module",
-    "build:client": "esbuild client/main.ts --bundle --format=iife --outfile=dist/client.js",
     "build:server": "tsc --project tsconfig.build.json",
-    "build": "npm run build:server && npm run build:client",
-    "build:demo": "npm run build:server && tsx build/cli.ts --src demo --out dist/demo",
-    "dev": "npm run build:demo && (tsx build/cli.ts --src demo --out dist/demo --watch & tsx demo/server.ts)",
-    "build:demo-static": "npm run build:server && tsx build/cli.ts --src demo-static/src --out dist/demo-static",
-    "dev:demo-static": "npm run build:demo-static -- --watch & node demo-static/serve.mjs",
+    "build": "npm run build:server",
+    "postbuild": "node --eval \"fs.chmodSync('dist/build/cli.js', 0o755)\" --input-type=module",
     "test": "tsx --test \"tests/**/*.test.ts\"",
-    "test:golden": "UPDATE_GOLDEN=1 tsx --test tests/golden.test.ts",
-    "pretypecheck": "npm run build:demo",
     "typecheck": "tsc --noEmit",
     "format": "prettier --write .",
     "format:check": "prettier --check ."