@loadbare/app 0.4.0 → 0.5.0

package/docs/reference/widgets.md

@@ -0,0 +1,163 @@
+# The Basic Widget Library
+
+Six widgets: `lb-input`, `lb-select`, `lb-list`, `lb-options`, `lb-table`,
+`lb-picker`. Every one of them is written against the same two contracts
+documented elsewhere — [Custom Elements](./custom-elements.md#html) for its
+definition, [Custom Elements](./custom-elements.md#code) for its class —
+nothing here is special-cased machinery.
+
+They ship compiled, in `@loadbare/widgets`, a package the builder resolves the
+way it resolves anyone else's — it declares `"loadbare": { "widgets": "./dist" }`
+and the builder scans that. Install it and list it:
+
+```
+npm install @loadbare/widgets
+```
+
+```ts
+// src/imports.ts
+export default ["@loadbare/widgets"];
+```
+
+See [Using Widget Libraries](../tutorials/090-using-widget-libraries.md) for
+what listing a package does, and [The Builder](./builder.md#where-the-builder-looks)
+for where a listed package sits in the cascade.
+
+## `lb-input`
+
+Wraps an `<input>`. `lb-value` sets the input's `.value`. The widget sends
+nothing on its own: `data-fire-on-change` asks it to send `cell-change` on the
+input's `change`, addressed by its own `lb-query`/`lb-key`/`lb-cell`
+coordinates.
+
+An input inside an `lb-insert` or `lb-update` form leaves the attribute off.
+The form reads every `lb-cell` in it on submit and sends one request for all
+of them, so an input that also sent its own would write the same edit twice.
+
+| Parameter | Fills |
+| ---------- | ----- |
+| `exp-label` | the visible `<label>` text |
+| `exp-readonly` | the input's `readonly` attribute |
+
+| Attribute | Asks for |
+| ---------- | ----- |
+| `data-fire-on-change` | an edit to be sent, on `change` |
+
+## `lb-select`
+
+Wraps a `<select>` whose `<option>`s the author writes directly inside (via
+`lb-slot`). `lb-value` sets the select's `.value`; a `change` sends the
+action named by `lb-action`, with the select's `.value` as the request's
+`value` — the choice is the interaction, so this is the case where an
+action carries a value.
+
+| Parameter | Fills |
+| ---------- | ----- |
+| `exp-label` | the visible `<label>` text |
+
+Requires `lb-action` — a change with none logs and sends nothing.
+
+## `lb-list`
+
+The plain repeater: whatever the author writes inside a
+`<template lb-key="...">` is cloned once per row, in arrival order. No
+grouping, no sorting, no request of its own — it exists because a
+`Projection` has to land on something with `acceptRows`, and a bare
+`<table>` can't be one (a custom element written inside `<tbody>` is
+discarded by the parser).
+
+## `lb-options`
+
+A `<select>` whose `<option>`s come from a query instead of being written by
+hand. The author supplies the row template inside the widget (via
+`lb-slot`), same as any list widget:
+
+```html
+<lb-options lb-query="statuses" exp-label="Status" lb-action="setStatus">
+  <template lb-key="id" lb-group="category">
+    <option lb-cell="label"></option>
+  </template>
+</lb-options>
+```
+
+| Parameter | Fills |
+| ---------- | ----- |
+| `exp-label` | the visible `<label>` text |
+
+- The row's key becomes the option's `value` — `lb-key` supplies both, so
+  nothing is declared twice.
+- `lb-group` on the row template sections the options into `<optgroup>`s,
+  one per distinct value, created and removed as rows arrive and leave.
+- `lb-sort` is not read by this widget.
+- A `change` sends the action named by `lb-action`, value from the
+  select's `.value`.
+
+`lb-picker` is this same class with its row template supplied by the
+definition instead of the page — see below.
+
+## `lb-table`
+
+A `<table>` that supplies its own scaffolding; the author supplies the
+heading row, the row template, and optionally a footer, each as a
+`<template>` matched to a destination:
+
+```html
+<lb-table lb-query="ledger" exp-caption="Ledger">
+  <template lb-template="head">
+    <tr><th>Date</th><th>Amount</th></tr>
+  </template>
+  <template lb-key="id" lb-sort="date" lb-group="month">
+    <tr><td lb-cell="date"></td><td lb-cell="amount"></td></tr>
+  </template>
+  <template lb-template="foot">
+    <tr lb-query="ledger-total"><td>Total</td><td lb-cell="total"></td></tr>
+  </template>
+</lb-table>
+```
+
+| Parameter | Fills |
+| ---------- | ----- |
+| `exp-caption` | the `<caption>` text |
+
+| Destination | Fills |
+| ------------ | ----- |
+| `head` (`lb-template="head"`) | the `<thead>` content |
+| `foot` (`lb-template="foot"`) | the `<tfoot>` content |
+| slot (no `lb-template`) | the row template, via `lb-slot` on `<tbody>` |
+
+- `lb-group` on the row template sections rows under a derived heading row,
+  one per distinct value, whose `colSpan` matches the row's own column
+  count. `lb-sort` orders rows within a section (or the whole body, with no
+  grouping) by comparing each row's cell text.
+- The `foot` destination is not delivered through `acceptRows` — it's an
+  ordinary scope carrying its own `lb-query`, resolved by name like any
+  other on the page. A grand total is a second projection of the same
+  data, not a row the hub hands the table.
+
+## `lb-picker`
+
+`lb-options`, with the row template supplied by the definition instead of
+the page — for when every row is one option and nothing else varies:
+
+```html
+<lb-picker
+  lb-query="statuses"
+  exp-label="Status"
+  exp-key="id"
+  exp-cell="label"
+  exp-group="category"
+  lb-action="setStatus"
+></lb-picker>
+```
+
+| Parameter | Fills |
+| ---------- | ----- |
+| `exp-label` | the visible `<label>` text |
+| `exp-key` | the row template's `lb-key` |
+| `exp-cell` | the option's `lb-cell` |
+| `exp-group` | the row template's `lb-group` |
+
+Behavior — grouping, key-as-value, the action on change — is inherited
+whole from `lb-options`; a page author who needs a second element in the
+row, or an option built from two columns, writes `lb-options` and its own
+`<template>` instead.

package/docs/roadmap.md

@@ -0,0 +1,130 @@
+# Roadmap
+
+Release 1.0 is optimized to prove that a Loadbare app can be robust and
+highly performant with a codebase that has very low accidental complexity.
+
+What follows is everything not yet decided or not yet built: release
+candidates, risks not worth solving speculatively, and open design
+questions. None of it is current behavior — for that, see
+[Reference](./reference/overview.md).
+
+## Open questions in the 1.0 mechanism
+
+These are not new scope — they're gaps deliberately left unresolved in the
+mechanism Release 1.0 already ships. Each is here because deciding it
+speculatively, before a real page forces the question, risks designing the
+wrong thing. Revisit when the described symptom actually shows up.
+
+### Staleness and concurrent writers
+
+Two tabs, or two users, updating the same projection at once. A solo
+developer testing in one browser will not produce this by accident, and
+retrofitting a version or conflict check onto every tuple after the fact
+touches every widget that writes.
+
+### Nesting
+
+Whether a tuple may contain a projection (master-detail, an expanding
+row). [Theory](./theory.md) already flags this as possibly load-bearing if
+disallowed. Worth a decision-in-principle the first time a master-detail
+page is built, even before the mechanism is needed elsewhere.
+
+### Whether `lb-query` may be inherited
+
+Currently every scope states its own `lb-query`; nothing resolves one from
+an ancestor. Inheritance would be friendlier to the page author but adds a
+resolution rule, and a resolution rule is a mechanism this framework has
+otherwise avoided. Worth deciding before an application grows deep enough
+nesting that restating the query on every level starts to hurt.
+
+### Whether `lb-key` is always required
+
+Undecided whether every row needs `lb-key`, or only a row something
+targets (a delete button, an update form). Revisit if a list widget shows
+up that never needs to address an individual row by key.
+
+### Pending appearance
+
+A value that hasn't arrived yet is probably derivable from an absent
+`lb-value` rather than needing a signal of its own. Not yet needed because
+nothing currently produces that gap in practice — revisit if one does.
+
+### Validation placement
+
+Per-keystroke feedback cannot afford a round trip, so some validation will
+end up living in the widget while the server remains authoritative for the
+same field. Not yet designed — revisit the first time an application needs
+inline validation.
+
+## Release 1.1 candidates
+
+Net-new scope, not gaps in 1.0. Release 1.1 will optimize for operational
+concerns: maintaining high performance and focus on the essentials in
+different deployment scenarios.
+
+### Lazy loading of page templates
+
+Release 1.0 packages all pages into HTML `<template>` elements, delivered
+along with the app shell as an HTML monolith on the first page `GET`.
+
+For a low page count with fairly simple pages, the monolithic load is
+probably faster than any other approach, and is definitely the simplest
+approach.
+
+For a high page count with complex pages, the one-time load of a monolith
+could degrade performance on the first load, not to mention producing a
+very cluttered result in View Page Source.
+
+If we add addressable pages, the hub could do a non-blocking gradual load
+of all templates. It could also load each template at first use.
+
+### Split data channel from static assets
+
+Release 1.0 assumes that static assets are delivered through the same URL
+as data responses.
+
+But in Loadbare we have an advantage: the entire browser bundle is static,
+all HTML, JavaScript and CSS is fixed at the time of release.
+
+If the hub were configured with a URL for the data channel, the entire app
+could be delivered from a static origin, such as an S3 bucket or static web
+server.
+
+### Tree-shaking CSS by tag name
+
+Release 1.0 concatenates every `.css` file under `src`, and every one inside
+each imported package. A stylesheet is paired with nothing, so an app ships
+the styles of every widget in every package it imports, used or not.
+
+Naming a stylesheet for a tag — `<tag-name>.css` beside `<tag-name>.html`
+and `<tag-name>.ts` — would let the builder ship only the stylesheets whose
+tags survive expansion into the finished document. A `.css` file whose name
+is not a tag would keep today's rule and always ship, which is what
+`00-reset.css` and the rest of an app's own styling already are.
+
+This would make a widget three files rather than two, so it changes the
+file set in [Custom Elements](./reference/custom-elements.md) and the
+"paired with nothing" rule in [CSS](./reference/css.md).
+
+Most valuable against a large imported widget library, where an app uses a
+small fraction of what ships. Revisit when a real app's `app.css` is big
+enough to measure.
+
+### Data binding utilities
+
+If a dev team wishes to make their own widgets that identify `lb-query`,
+`lb-key`, `lb-cell`, they must repeat the code that is present in the hub.
+
+Perhaps a utility that can be called, like `getDataScope(el)`, to help
+clean up the code in these cases.
+
+### A language server
+
+...for Loadbare HTML.
+
+### I18N
+
+Internationalization would require a potential extension to build-time
+expansion allows a strings file.  We could either preserve the fully 
+static build-time system and create multiple versions of `app.html`, or we
+could add label hydration to the page navigation stage.

package/docs/testing.md

@@ -0,0 +1,228 @@
+# Testing
+
+A contributor's document, and a companion to [theory.md](./theory.md). It
+describes how this package tests itself.
+
+## Position
+
+Loadbare App is four layers with four different relationships to the browser,
+and a single testing strategy would have to be the weakest of them. So there
+are four tiers, and each is tested by the cheapest thing that constitutes
+evidence for it.
+
+The ordering principle is that a test should fail for the reason it is named
+after. A test of expansion that needs a browser has bought a second failure
+mode it does not want, and a test of navigation that runs under a DOM
+emulation has given up the only failure mode it was looking for.
+
+| Tier | Covers                                           | Environment |
+|------|--------------------------------------------------|-------------|
+| 1    | Expansion and the build — `build/`               | node        |
+| 2    | The engine — `server/`, and the Express adapter  | node        |
+| 3    | Landing — `hub/lb-apply.ts`, `hub/lb-rows.ts`    | jsdom       |
+| 4    | The hub — `hub/lb-hub.ts`                        | jsdom       |
+
+All four tiers run under `npm test` today and need no dependency that is not
+already installed. A fifth environment — a real browser — is discussed at the
+end and is not built.
+
+## The runner
+
+`node:test`, run through `tsx`:
+
+```
+npm test
+```
+
+No test framework is installed, because none is needed. Node ships the
+runner, `tsx` is already here, and jsdom is already here for expansion.
+
+Tests live in `tests/`, one file per source file, named for it:
+`tests/expand.test.ts` covers `build/expand.ts`.
+
+Write a definition inline, beside the assertion that reads it — a two-line
+definition is shorter than the reference that would point at it.
+`tests/fixtures/` holds only what has to be a file: the checks that run while
+definitions are being loaded, and the directory ordering that lets an
+application override a built-in.
+
+## The console is an interface
+
+The browser half of Loadbare App reports every failure it survives through
+`console.error` and `console.warn` — a query with no scope, a list widget
+with no template, a change event with no coordinates. These are not
+diagnostics. They are the framework's entire error channel on the client, and
+the behavior under test is frequently *that Loadbare reported and carried on*
+rather than that it produced a value.
+
+So tests assert on that channel. `tests/helpers/console.ts` is the seam that
+makes it pleasant rather than fiddly.
+
+## Tier 1 — Expansion and the build
+
+Expansion is string in, string out, with no data, no browser, and no clock.
+It is also the layer whose failure mode is settled: it throws rather than
+ships. That combination makes it both the easiest tier and the one carrying
+the most of what Loadbare promises, so it is first.
+
+**Rejections.** Every one of these is a build that must not produce output:
+
+- an `lb-*` tag with no definition
+- `exp-foo` supplied to a definition with no `{{foo}}`
+- `{{camelCase}}` in a definition, which no tag could ever supply
+- a cycle in the definition graph
+- two `lb-template` destinations with one name
+- two authored templates for one destination
+- a template naming a destination the definition does not have
+- content written inside a definition with no `lb-slot`
+- more than one `lb-slot`
+
+**Substitution.** An unset placeholder drops the attribute rather than
+emitting it empty, which is what HTML's boolean attributes require and what
+`readonly="{{readonly}}"` in `lb-input` depends on. Whitespace around a text
+placeholder is preserved, because `{{label}} <input>` needs that space.
+Placeholders inside `<template>` content are expanded, which is why
+`lb-picker` can ship a row template of its own. `exp-` attributes survive on
+the expanded tag, so what ships shows what was asked for beside what it
+produced.
+
+**Injection is impossible by construction**, because substitution goes
+through `setAttribute` and node values rather than through a string. That
+claim gets a test: a parameter whose value is markup ships as text. It exists
+to fail if anyone ever reaches for string concatenation here.
+
+**Golden files.** These live in `@loadbare/demo`, not here. Each demo
+application is built by the installed `loadbare-app-build` and its assembled
+`app.html` compared to a stored copy — the whole chain at once, including the
+origin ordering that lets an application override a widget from a package,
+exercised the way a consumer exercises it rather than by wiring this
+package's own modules together. See
+[`packages/demo/AGENTS.md`](../../demo/AGENTS.md).
+
+Review the golden files rather than blessing them. `npm run test:golden -w
+@loadbare/demo` rewrites them; the diff is the point, and a diff nobody read
+is a test nobody ran.
+
+The rest of the build — `assemble`, `elements`, `pages`, `styles`,
+`package-css` — is tested the same way and in the same tier, since none of it
+needs a browser either.
+
+## Tier 2 — The engine
+
+`createHub` takes a plain object and returns an object. Nothing in
+`server/lb-server.ts` opens a socket, so the fixtures are counting stubs.
+
+- `beforeGet` runs before any query, and the whole query set runs after it
+- an unknown page answers `{}` and says so
+- an unknown query name in a refresh set is skipped, and its siblings run
+- an action the page did not declare is refused — the rule that keeps the
+  wire from reaching anything the page has not published
+- the refresh set runs after the action, against the same context
+- **what the action stated wins over what the refresh produced**, because
+  that is how a `patch` reaches the browser at all, and it is one spread
+  operator away from silently reversing
+
+`tests/lb-express.test.ts` runs against a listening app: the page comes from
+the query string, an undeclared operation is refused with a 400, and a
+malformed body does not throw.
+
+## Tier 3 — Landing
+
+`applyData`, `applyTuple` and `applyRows` are the most intricate code in the
+framework and the most likely to break in ways nobody notices. They are also
+pure DOM: no fetch, no widget upgrade, no history. jsdom is real evidence
+here.
+
+- a native element receives its value as text, a hyphenated one as `lb-value`
+- the root of a scope counts as a cell if it carries one, which is what makes
+  an `<option>` row possible
+- a query with no scope is reported and skipped; several scopes for one query
+  are all filled; a projection landing on something that is not a list widget
+  is reported rather than thrown
+- `rows` decides membership and order, so a key that did not arrive is gone
+- `patch` disturbs only what it names, in contents and in position
+- `data-rows` is counted from the DOM after reconciliation, so a set and a
+  patch ending in the same state report the same number
+- the `place` callback is called for a fresh row always, and for an existing
+  row only under `rows`. That is today's behavior, not a decision — a patch
+  therefore never re-places a row whose sort key changed. The test states what
+  is true now, and is the one that flips if that changes.
+
+**Two properties**, written as loops rather than with a library. Applying the
+same `rows` twice is applying it once. And `rows(S)` reached through any
+sequence of patches is `rows(S)` reached from empty. Convergence is the
+actual contract of a reconciler, and those two say it better than twenty
+examples.
+
+## Tier 4 — The hub
+
+The widget half of this tier lives in `@loadbare/widgets` and is tested
+there, against the same jsdom harness described below — see
+[`packages/widgets/AGENTS.md`](../../widgets/AGENTS.md). What follows applies
+to both, and the hub is what remains here.
+
+Widgets are small and their logic is local, so jsdom carries them: a value
+reaches the control the widget owns, a change dispatches the declared action,
+an absent control or absent action is reported rather than thrown,
+`lb-options` turns a key into a value and removes an emptied `<optgroup>`,
+`lb-table` groups and sorts, removes an emptied section heading, and takes
+its `colSpan` from the row template the page wrote.
+
+A widget extends `HTMLElement` and registers itself as its module loads, so
+unlike tier 3 it needs a window before the module exists. `installWindow()`
+puts one in place and the widget module is imported after it, dynamically.
+One window per file, which is what running each file in its own process gives
+for free — registration is global and permanent, so sharing a process across
+widget files would mean sharing a registry.
+
+What that buys is real upgrades: the constructor, `connectedCallback`, and
+`attributeChangedCallback` for attributes already present. That last one is
+the mechanism by which hydration and refresh are one operation, and it
+behaves the same in jsdom as in a browser. What it does not buy is layout,
+painting, or navigation.
+
+## Not built: the browser tier
+
+The hub is where jsdom stops being evidence. Fetch, `history.pushState`,
+`popstate`, and the claim that insertion and hydration in one synchronous
+block never paint an empty frame are all statements about a browser.
+
+No browser test runner is installed and none of the following exists. They
+are recorded here as the shape of the work, not as coverage:
+
+1. a cold load fills `<main>` with no empty flash
+2. `lb-nav-link` pushes state, swaps the host and lands data; `popstate`
+   reverses it; an ordinary anchor is not hijacked
+3. a native action button produces the same event a widget produces
+4. the wizard never displays a step the server has not confirmed
+5. the view-source invariant
+
+The last is the one worth a browser. Loadbare's central claim is that no
+markup exists in the DOM that is not in view-source, and that the difference
+between the two is exactly the dynamic half. That is a property, it is stated
+precisely in [theory.md](./theory.md), and it should be enforced mechanically
+rather than believed: fetch the shell as text, compare the element set
+against the live document after interaction, and assert that the only
+additions are clones of row templates.
+
+See [TODO.md](../TODO.md) for this and the rest of the open work.
+
+## Continuous integration
+
+```
+npm run typecheck && npm run format:check && npm test
+```
+
+Add the browser specs as a separate job if they are ever written, so the four
+tiers here stay fast enough to run on every save.
+
+## One change the tests want
+
+The client reports through `console.error` and `console.warn` directly, from
+roughly twenty places across `hub/` and `@loadbare/widgets`. Routing those through a
+single `report()` in `core/` would give the tests one seam to observe instead
+of a global to mock per file, and would put the framework's error channel in
+the same file as the rest of its vocabulary. It is a small change and it is
+not urgent, but it is the only place where testing asks anything of the
+design.
+</content>