@loadbare/app 0.7.4 → 0.8.1

package/skills/loadbare-app/SKILL.md

@@ -0,0 +1,258 @@
+---
+name: loadbare-app
+description: Build server-bound web applications with Loadbare/app. Covers the file conventions the builder finds by name (`chrome.html`, `*.page.html`, `*.queries.ts`, `*.requests.ts`, `imports.ts`, `<tag>.html`, `<tag>.browser.ts`); the `lb-*` attribute vocabulary that binds HTML to server data and sends requests (`lb-list`, `lb-row`, `lb-cell`, `lb-key`, `lb-show`, `lb-action`); build-time widget expansion with `exp-*` parameters, `lb-slot` and `lb-template`; custom element code; the Express wiring with `hubRoutes`; and the `@loadbare/widgets` library. Use whenever a task involves `@loadbare/app`, `@loadbare/widgets`, `loadbare-app-build`, an `lb-` attribute, or a page, query, request or widget file in a Loadbare application. The model is not React, htmx or REST, and cannot be inferred from them.
+license: Apache-2.0
+metadata:
+  package: "@loadbare/app"
+  homepage: https://gitlab.com/kendowns/loadbare
+---
+
+# Working with Loadbare/app
+
+Loadbare/app builds a whole application into one HTML document, one client
+script and one stylesheet.  The server answers named queries with rows and
+performs named requests; the browser lands those rows on elements that name
+them.  No component renders anything, and no page fetches anything.
+
+The wire is relational.  A name answers with one row or a set of rows, a
+row holds cells, and a cell holds one value.  Hold on to that: most wrong
+designs come from sending a shape a relational answer cannot have.
+
+## Build every change before handing it over
+
+`loadbare-app-build` is the checker.  It expands every page and widget and
+refuses what it cannot ship, naming the tag and the file:
+
+```bash
+loadbare-app-build --src src --out dist
+```
+
+It exits non-zero on the first failure and prints
+`loadbare-app-build: <message>`.  A clean run prints the files it wrote and
+the number of custom elements it bundled.
+
+Type-check the server side as well:
+
+```bash
+tsc --noEmit
+```
+
+`dist/pages.ts` imports page files with their `.ts` extensions, so the
+application's `tsconfig.json` needs `allowImportingTsExtensions`.
+
+**Write, build, fix, repeat until it is clean.**  Then start the server:
+`createHub` refuses a query that answers with the wrong shape and a page
+that declares a reserved name, and those refusals only appear at run time.
+Restart the server after adding or changing a `.queries.ts` or
+`.requests.ts` file.
+
+## The shape of an application
+
+The builder classifies files by name, never by directory:
+
+```
+src/
+  chrome.html              exactly one; the document every page lands in
+  imports.ts               at most one; the widget packages to scan
+  00-reset.css             any .css anywhere, concatenated
+  pages/
+    index.page.html        the page for /
+    members.page.html      the page for /members
+    members.queries.ts     what members displays
+    members.requests.ts    what members may be asked to do
+  widgets/
+    note-card.html         the markup <note-card> expands into
+    visit-count.browser.ts the class <visit-count> registers
+server.ts
+```
+
+The chrome carries `<lb-hub>` inside `<body>`, an empty `<main>` inside the
+hub, and `<script src="/client.js" defer>`.  Everything a user touches sits
+inside `<lb-hub>`.
+
+A page is an HTML fragment that lands in `<main>`:
+
+```html
+<!-- src/pages/members.page.html -->
+<p lb-row="dues">Collected this year: <span lb-cell="total"></span></p>
+
+<section lb-list="roster">
+  <form lb-action="lb-row-insert">
+    <input lb-cell="name" />
+    <button type="submit">Add</button>
+  </form>
+  <ul>
+    <template lb-key="id">
+      <li>
+        <span lb-cell="name"></span>
+        <button lb-action="lb-row-delete">Remove</button>
+      </li>
+    </template>
+  </ul>
+</section>
+```
+
+```ts
+// src/pages/members.queries.ts
+import { list, row, type Queries } from "@loadbare/app/server";
+
+export const queries: Queries = {
+  dues: row((ctx) => ctx.db.duesTotal()),
+  roster: list((ctx) => ctx.db.members()),
+};
+```
+
+```ts
+// src/pages/members.requests.ts
+import { patch, type Requests } from "@loadbare/app/server";
+
+export const requests: Requests = {
+  crud: {
+    roster: {
+      rowInsert: {
+        run: async (ctx, { values }) => ({
+          roster: patch({ rows: [await ctx.db.addMember(values)] }),
+        }),
+        refresh: ["dues"],
+      },
+      rowDelete: {
+        run: async (ctx, { key }) => {
+          await ctx.db.removeMember(key);
+          return { roster: patch({ drop: [key] }) };
+        },
+        refresh: ["dues"],
+      },
+    },
+  },
+};
+```
+
+## Where front-end knowledge misleads
+
+Re-read this list when a build fails or a design will not fit.  Each item is
+a place a reasonable instinct from React, Vue, htmx or REST produces an
+error or a dead end.
+
+**There is no template language.**  No `{#if}`, no `v-for`, no `map()`.  A
+list is an element carrying `lb-list` with a `<template lb-key="...">`
+inside it, and the hub clones the template once per row.  A condition is
+`lb-show="<column>"`: write every possibility into the page and let a column
+decide which is present.  The column must be a boolean or null; the string
+`"false"` counts as present.
+
+**`{{placeholder}}` is build time only.**  It reads an `exp-` attribute on
+the tag, never data.  Write it as an entire attribute value or an entire
+text node.  Name parameters in lowercase with hyphens: HTML lowercases
+`exp-inputClass` before expansion sees it.
+
+**Scope comes from ancestry, not props.**  An `lb-cell` binds to the row on
+its nearest ancestor carrying `lb-row` or a live list row.  An element
+outside every scope displays nothing.  A value of `lb-cell` is a column name.
+
+**One name, one cardinality.**  Declare every query with `row()` or
+`list()`.  A page that needs the same data as a row and as a set declares
+two queries.
+
+**A cell never holds rows.**  Master-detail is a row and a list under two
+names.  Many masters with their details is one list of joined rows, grouped
+for display by a widget's `lbPlaceRow`.  A list nested inside another list's
+rows receives the same rows in every outer row; use it for a picker, never
+for per-row detail.
+
+**A URL names a page, never a resource.**  Do not design `/accounts/42`.  A
+row is addressed by `list` and `key`, taken from where the element sits.
+Queries take no arguments from the browser; which record a page shows is
+server state reached through `ctx`.
+
+**There are no endpoints to write.**  `hubRoutes(hub, contextFor)` is the
+whole data channel.  Declare every action under `actions` and every
+permitted operation under `crud`; anything undeclared is refused.
+
+**All three CRUD operations are list operations.**  Each needs a key, and a
+key exists only on a live row inside `lb-list`.  An `lb-row` scope is
+read-only; give a writable single row a list that answers with one row.
+
+**Write `rowUpdate` as a partial update.**  A form sends every cell it
+holds; a widget carrying `lb-cell` and `lb-action="lb-row-update"` sends its
+one cell.  Set the columns `values` names, leave the rest alone, and check
+the names against the columns the page may edit.
+
+**Put `lb-row-insert` and `lb-row-update` on a `<form>` or a button.**  The
+hub gathers the nearest `<form>`, `<tr>` or live row.  Cells in a bare
+`<div>` belong to no row and the request is refused.  A native `<input>`
+carrying `lb-row-update` is refused; commit one cell with a widget such as
+`<lb-input>`.  Inside a form, leave `lb-action` off the widgets.
+
+**Return a patch when the change has a known extent.**  `patch({ rows })`
+for rows added or edited, `patch({ drop })` for keys removed, with
+`refresh: []`.  List a query in `refresh` only when its membership or order
+changed in a way the operation cannot name.
+
+**Format values in the query.**  The hub does no type conversion.  What a
+number, date or null looks like is decided on the server.
+
+**Checkboxes, radio buttons and file inputs are not bound.**  They receive
+no value and are not gathered.  This is an open item, not a mistake in the
+page.
+
+**`lb-` belongs to Loadbare.**  Invent no `lb-` attribute, and name no
+query or action with the prefix.  Import attribute names in widget code from
+`@loadbare/app/constants`; never write them as string literals.
+
+**Name a widget script `<tag>.browser.ts`.**  A plain `<tag>.ts` stays on
+the server and the tag goes unregistered.
+
+**Light DOM, global CSS.**  No shadow root, no scoping.  Style empty lists
+with `[lb-row-count="0"]`, pending requests with `[lb-pending]`, and failed
+ones with `[lb-error]`.
+
+**Host at the origin root.**  The hub reaches its route by absolute path, so
+a subpath such as `example.com/myapp/` does not work.
+
+## Widgets
+
+A widget is `<tag>.html`, `<tag>.browser.ts`, or both, and a tag with
+neither is a build error.  The HTML is expanded at build time into the tag's
+children; the class is an ordinary custom element with no base class.
+
+Reach for a widget only when plain HTML cannot do the job.  A list, a form
+and a condition need none.  A widget exists to wrap a control that decides
+its own moment to send (`<lb-input>` on `change`), or to place and scaffold
+rows (`lbPlaceRow`, `lbRowsLanded`).
+
+Before writing one, check `@loadbare/widgets`: `lb-input`, `lb-select`,
+`lb-options`, `lb-table`, `lb-picker`, `lb-unknown-page`.  Install it and
+list it in `src/imports.ts`:
+
+```ts
+export default ["@loadbare/widgets"];
+```
+
+The application's own definition of a tag overrides a package's.
+
+## Reference material
+
+Read these when the summary above does not settle the question.  They ship
+with the package, so no network is needed.
+
+- [`references/overview.md`](references/overview.md) — the map of the
+  reference, by part of the application.
+- [`references/data-binding.md`](references/data-binding.md) — every `lb-`
+  attribute, requests, forms, conditions and request state.  Start here for
+  anything in a page.
+- [`references/page-files.md`](references/page-files.md) — queries,
+  `onPageEnter`, actions, CRUD, refresh and patch.
+- [`references/custom-elements.md`](references/custom-elements.md) —
+  expansion, parameters, slots, destinations, and widget code.
+- [`references/chrome.md`](references/chrome.md) — the chrome,
+  navigation and `lb-navigation`.
+- [`references/server.md`](references/server.md) — the Express server and
+  the request context.
+- [`references/builder.md`](references/builder.md) — the builder's options,
+  what it reads, and where it looks.
+- [`references/css.md`](references/css.md) — how stylesheets are ordered.
+- [`references/widgets.md`](references/widgets.md) — the basic widget
+  library.
+- [`references/TECHREF-1.0.md`](references/TECHREF-1.0.md) — the reserved
+  names, and the open items that block 1.0.  Read it before designing around
+  something the other references do not mention.