@loadbare/app 0.4.0 → 0.5.0

package/docs/application-chrome.md

@@ -1,36 +0,0 @@
-# Application Chrome
-
-The application Chrome - banner, nav, main and footer, is static HTML.
-
-It is found by name, not by location: it can be placed anywhere in the tree
-the builder scans, as any file ending `.chrome.html` — there must be exactly
-one. By convention we name it `src/chrome.chrome.html`.
-
-In our docs we consider chrome to be invariant across pages. This is
-not a strict technical requirement, as loadbare can update anything,
-but we do not provide examples or tests of dynamic chrome.
-
-The minimum requirements for the chrome file are:
-
-- the `<lb-hub>` element as first element below `<body>`
-- an empty `<main></main>` element. Its content is populated by
-  the hub from the application pages.
-
-```html
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="utf-8" />
-    <title><!-- content goes here --></title>
-    <script src="/client.js" defer></script>
-  </head>
-  <body>
-    <lb-hub>
-      <header><!-- content goes here --></header>
-      <nav><!-- content goes here --></nav>
-      <main></main>
-      <footer><!-- content goes here --></footer>
-    </lb-hub>
-  </body>
-</html>
-```

package/docs/building-html-pages.md

@@ -1,130 +0,0 @@
-# Building HTML Pages
-
-A page is authored as one HTML file. It may contain widget tags. Expansion
-turns each one that has a definition into the tree that definition stands
-for. Expansion runs at build time, before there is a request, and before
-there is any data.
-
-`LB-*` is the framework's reserved namespace — Loadbare App's own widgets, and
-the convention its docs use. An application's own widgets should use their
-own prefix instead (`app-nav`, not `lb-nav`); a tag outside the `LB-*`
-namespace expands exactly the same way when it has a definition, but is not
-required to have one — with none, it is assumed to be a plain custom element,
-registered by script alone (see build/elements.ts).
-
-## Definitions
-
-A definition is one HTML file per tag. The file name gives the tag:
-`lb-options.html` defines `LB-OPTIONS`; `app-nav.html` defines `APP-NAV`.
-
-Loadbare App's own widgets live in this package's own `widgets/`, read by
-`loadDefinitions(dirs)`, which takes a list of directories in order — a later
-one overrides an earlier one for the same tag name. An application's own
-definitions are not confined to a directory at all: they are found by
-filename anywhere in its source tree (see `docs/getting-started.md`) and
-overlaid on the built-in set with `addDefinitions`, the same override an
-application directory would give a built-in widget.
-
-The full set of definitions is checked for a cycle in which definitions
-reference each other by tag, and throws if one exists.
-
-## Expanding a page
-
-`expand(source, defs)` walks the authored tree and replaces every widget tag
-that has a matching entry in `defs` with the tree that entry produces. A tag
-in the `LB-*` namespace is required to have one — an unresolved tag there
-throws. Outside that namespace, a tag with no definition is left exactly as
-authored.
-
-A definition may itself use other widget tags. Expansion resolves those the
-same way, as deep as the definitions go.
-
-## Parameters
-
-A definition may declare a placeholder, written `{{name}}`, as the entire
-value of an attribute or the entire text of a text node.
-
-An authored tag supplies a placeholder's value with an attribute named
-`exp-<name>`. `exp-label="Member:"` supplies `{{label}}`.
-
-HTML lowercases attribute names, so a placeholder name may not contain an
-uppercase letter — `loadDefinitions` rejects a definition that declares one.
-
-Supplying `exp-x` on a tag whose definition has no `{{x}}` is an error.
-
-If a placeholder has no value supplied, the attribute it fills is dropped
-rather than emitted empty; a text placeholder becomes empty text.
-
-## The slot
-
-A definition may mark one element `lb-slot`. The authored tag's child nodes
-move into that element, replacing it. A definition with no `lb-slot` rejects
-any non-whitespace content written inside the authored tag.
-
-## Named template destinations
-
-A definition may mark more than one element `lb-template="<name>"`, each a
-destination. An authored tag supplies content for a destination by writing a
-`<template lb-template="<name>">` among its children; expansion moves the
-template's content into the destination and discards the wrapping `<template>`
-tag. A destination with no matching template is left as the definition wrote
-it.
-
-Two templates naming the same destination, or a template naming a destination
-the definition does not declare, is an error.
-
-A definition applies named destinations before the slot: content addressed to
-a destination by name does not also count as slot content.
-
-### Example
-
-`widgets/lb-table.html`:
-
-```html
-<table>
-  <caption>
-    {{caption}}
-  </caption>
-  <thead lb-template="head"></thead>
-  <tbody lb-slot></tbody>
-  <tfoot lb-template="foot"></tfoot>
-</table>
-```
-
-Authored in a page:
-
-```html
-<lb-table exp-caption="Everyone, by team">
-  <template lb-template="head">
-    <tr>
-      <th>Name</th>
-      <th>Role</th>
-    </tr>
-  </template>
-  <tr>
-    <td>Row content for the slot</td>
-  </tr>
-</lb-table>
-```
-
-The `head` template's content becomes the `<thead>`'s children. The `<tr>`
-written outside any `<template>` is slot content and becomes a child of
-`<tbody>`. There is no template addressed to `foot`, so the `<tfoot>` ships
-empty, exactly as the definition wrote it.
-
-## Template content elsewhere on the page
-
-Expansion also descends into the content of any `<template>` on the page,
-including one with no `lb-template` attribute — for example a row template
-consumed by a widget at runtime rather than by expansion. A placeholder or
-widget tag written inside such a template is still expanded.
-
-## Output
-
-`expand(source, defs)` returns HTML text. Substitution is applied to a parsed
-tree through DOM APIs — `setAttribute`, text node values — never to a string,
-so a value supplied through `exp-*` cannot be reparsed as markup.
-
-What `expand` returns is what ships. No value from a request or a database is
-added after expansion; those values land on the already-expanded tree later,
-as attributes.

package/docs/getting-started.md

@@ -1,120 +0,0 @@
-# Getting Started
-
-We begin with the smallest working application. This app does not even
-have any pages, but it will load without error, and is inspectable.
-
-## The chrome file
-
-Write a file ending `.chrome.html` — say, `src/chrome.chrome.html`. There
-must be exactly one of these anywhere under `src/`; the builder finds it by
-that name, not by which directory it's in.
-
-At minimum, the chrome must contain:
-
-- a link to the `client.js` script
-- The `<lb-hub>` element just inside `<body>`
-- an empty `<main>` inside `<lb-hub>`
-
-```html
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="utf-8" />
-    <title>Getting Started</title>
-    <script src="/client.js" defer></script>
-  </head>
-  <body>
-    <lb-hub>
-      <main></main>
-    </lb-hub>
-  </body>
-</html>
-```
-
-The client script is generated by the builder, and contains some core code
-and the Javascript
-for all custom elements in the app. Since we have only `lb-hub`, the build
-will produce a `client.js` containing the core code and only the class for `lb-hub`.
-
-## Serving It
-
-Create `server.js` as an express server:
-
-```js
-import express from "express";
-import { readFileSync } from "node:fs";
-
-const app = express();
-
-app.get("/", (_req, res) =>
-  res.type("html").send(readFileSync("dist/app.html", "utf-8")),
-);
-app.use("/client.js", express.static("dist/client.js"));
-
-app.listen(8787);
-```
-
-`dist/app.html` is read on every request rather than once at startup, so a
-rebuild in watch mode is visible without restarting the server.
-
-## The dev Script
-
-Add to package.json:
-
-```json
-{
-  "scripts": {
-    "dev": "loadbare-app-build --watch & node server.js"
-  }
-}
-```
-
-`loadbare-app-build` scans `src/` by default; `--src` overrides which tree. It
-takes no other location flags — everything under that tree is found by what
-a file is named, not by which directory holds it:
-
-- `*.chrome.html` — the one chrome file
-- `*.page.html` — a page, named for the part before the suffix
-- any other `.html` — a widget definition, named for its own filename
-- a `.ts` file shaped like a custom element tag (e.g. `lb-nav.ts`,
-  `app-box.ts`) — a widget's script
-- `*.hooks.ts` / `*.queries.ts` — a page's server half, paired with a
-  `*.page.html` by sharing its basename
-- `.css` — a stylesheet, concatenated with every other one found
-- `elements.ts` — third-party custom elements: a default export mapping tag
-  to import specifier, e.g. `{ "acme-date-picker": "@acme/date-picker" }`
-
-A widget's markup and script don't need to sit in the same place, or in any
-particular directory at all — `src/pages/home.page.html` and
-`src/lb-nav.html` are both found the same way `src/widgets/lb-nav.html`
-would be.
-
-## CSS
-
-Every `.css` file anywhere under `src/` is concatenated into `dist/app.css`,
-in one order: sorted by filename, not by directory. Put a stylesheet next to
-the markup it styles, wherever that is convenient — a global one sorts to
-the front on its own by naming itself `00-reset.css` or `aa-globals.css`,
-regardless of which directory it lives in. Nothing here knows about widgets
-or pages; it is exactly the concatenation of what was authored, with no
-scoping and no plain `style="..."` attribute anywhere the framework writes
-markup, since that is inline code the same way `<script>` is, and Loadbare App
-targets a CSP that refuses both.
-
-The chrome links it like any other asset — `<link rel="stylesheet"
-href="/app.css" />` — the builder never writes into the chrome itself.
-
-This script runs the Loadbare App builder in watch mode, alongside the server.
-With `--watch`, every `.html`, `.ts` and `.css` file under `src/` is watched —
-a page, a widget's markup, a widget's class, a stylesheet, and `elements.ts`
-all feed the build.
-
-Loadbare App does not reload the browser on a rebuild. Watch mode keeps
-`dist/app.html`, `dist/client.js` and `dist/app.css` current on disk; the
-browser picks up a change on the next manual refresh.
-
-## 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 should show exactly our page.