|
@@ -97,7 +97,7 @@ Rewrites to `{attr}="/_statum/resource/{value}"`. `<script
|
|
|
pstm-res-src="statum-core.js">` becomes `<script
|
|
pstm-res-src="statum-core.js">` becomes `<script
|
|
|
src="/_statum/resource/statum-core.js">`. Works for any attribute name
|
|
src="/_statum/resource/statum-core.js">`. Works for any attribute name
|
|
|
(`src`, `href`, ...). The named resource must be registered server-side
|
|
(`src`, `href`, ...). The named resource must be registered server-side
|
|
|
-(`StatumConfigurator.add_resource` or the three default client modules).
|
|
|
|
|
|
|
+(`StatumConfigurator.add_resource` or the four default client modules).
|
|
|
|
|
|
|
|
### The legacy `statum.js` expansion (script tags)
|
|
### The legacy `statum.js` expansion (script tags)
|
|
|
|
|
|
|
@@ -114,7 +114,7 @@ One build warning per page names the page and the expansion. Pages that
|
|
|
reference module files directly are untouched and unwarned. A page mixing
|
|
reference module files directly are untouched and unwarned. A page mixing
|
|
|
the legacy reference with explicit module tags is deduplicated — each module
|
|
the legacy reference with explicit module tags is deduplicated — each module
|
|
|
appears exactly once, in canonical order — and the warning says so. Plain
|
|
appears exactly once, in canonical order — and the warning says so. Plain
|
|
|
-`src="…"` scripts are never touched. In new pages, write the three tags
|
|
|
|
|
|
|
+`src="…"` scripts are never touched. In new pages, write the four tags
|
|
|
explicitly (see Part III for the load contract).
|
|
explicitly (see Part III for the load contract).
|
|
|
|
|
|
|
|
### What never reaches the browser
|
|
### What never reaches the browser
|
|
@@ -162,28 +162,20 @@ handler itself guards (see `stm-prefill`'s dirty tracking for the pattern).
|
|
|
|
|
|
|
|
### Section: statum-core.js
|
|
### Section: statum-core.js
|
|
|
|
|
|
|
|
-Slot protocol, HTTP, directives, realtime, boot, public JS API. Attributes it
|
|
|
|
|
-owns:
|
|
|
|
|
-
|
|
|
|
|
-- **`stm-entrypoint`**, **`stm-slots`**, **`stm-channel`**, **`stm-worker`**
|
|
|
|
|
- (on `<body>`): override the four endpoint URLs (defaults
|
|
|
|
|
- `/_statum/entrypoint`, `/_statum/slots`, `/_statum/channel`,
|
|
|
|
|
- `/_statum/resource/statum-worker.js`). Read once at init.
|
|
|
|
|
-- **`stm-preloader`** / **`stm-content`**: boot visibility. While the
|
|
|
|
|
- entrypoint loads, `stm-preloader` elements are shown and `stm-content`
|
|
|
|
|
- elements hidden; once ready, the reverse. Set `hidden` on `stm-content`
|
|
|
|
|
- yourself in the HTML to avoid a flash of unbound template.
|
|
|
|
|
-- **`stm-guard`** (a `<link rel="stm-guard" require="…" href="…">`, plus the
|
|
|
|
|
- `pre-entrypoint` attribute on the link): a client-side UX gate — when
|
|
|
|
|
- `require` evaluates false, the page redirects to `href`. Re-checked every
|
|
|
|
|
- render cycle; guards without `pre-entrypoint` only evaluate after the
|
|
|
|
|
- entrypoint has loaded. This is UX sugar, NOT security.
|
|
|
|
|
-- **`stm-on-error`** (on action elements): space-separated class names
|
|
|
|
|
- applied while the action's request is failing / after an `error` directive.
|
|
|
|
|
-- **`stm-class.{name}`**: class-list predicates shared by core's busy-state
|
|
|
|
|
- logic and the document walk (see below for semantics).
|
|
|
|
|
-- **`stm-disabled`**: predicate disabling the element and its descendant form
|
|
|
|
|
- controls.
|
|
|
|
|
|
|
+The slot protocol and nothing else — core is HEADLESS and owns **no
|
|
|
|
|
+`stm-*` attributes at all**: no DOM scanning, no bindings. It keeps the
|
|
|
|
|
+state store and persistence, `X-Statum-Slot` assembly, entrypoint/action
|
|
|
|
|
+requests, directive dispatch, the SSE/SharedWorker realtime channel, the
|
|
|
|
|
+alert/confirm/notify override mechanism, and the internal bridge that later
|
|
|
|
|
+modules register presentation hooks into. A page can run core alone as a
|
|
|
|
|
+pure state layer under any other templating framework: point
|
|
|
|
|
+`statum.config` at your endpoints before `init()` and consume
|
|
|
|
|
+`read`/`getSnapshot`/`state`/`act` yourself.
|
|
|
|
|
+
|
|
|
|
|
+(The four `<body>` endpoint overrides — `stm-entrypoint`, `stm-slots`,
|
|
|
|
|
+`stm-channel`, `stm-worker` — are read by the DOCUMENT module at load and
|
|
|
|
|
+written into core's mutable `statum.config`; see that section. They are
|
|
|
|
|
+inert on a core-only page, which sets `statum.config` directly.)
|
|
|
|
|
|
|
|
Directives (server → client, `application/vnd.statum+json`): `set`, `clear`,
|
|
Directives (server → client, `application/vnd.statum+json`): `set`, `clear`,
|
|
|
`invalidate`, `subscribe`, `unsubscribe`, `notify`, `transmit`, `error`,
|
|
`invalidate`, `subscribe`, `unsubscribe`, `notify`, `transmit`, `error`,
|
|
@@ -194,28 +186,47 @@ and before navigate/post. See `model.md` for payloads.
|
|
|
Public JS API (on `window.statum`): the essentials are `version`, `config`,
|
|
Public JS API (on `window.statum`): the essentials are `version`, `config`,
|
|
|
`init`, `read`, `getSnapshot`, `getFrame`, `state`, `clear`, `act`,
|
|
`init`, `read`, `getSnapshot`, `getFrame`, `state`, `clear`, `act`,
|
|
|
`addStateListener` / `removeStateListener`, `beforeEvaluate` /
|
|
`addStateListener` / `removeStateListener`, `beforeEvaluate` /
|
|
|
-`afterEvaluate`, `Error`, the `onConfirmHandler` / `onNotifyHandler` /
|
|
|
|
|
|
|
+`afterEvaluate`, `Error`, and the `onConfirmHandler` / `onNotifyHandler` /
|
|
|
`onErrorHandler` getter/setter pairs (the override mechanism for
|
|
`onErrorHandler` getter/setter pairs (the override mechanism for
|
|
|
`stm-confirm` / `notify` / failures — frontend-demo installs toast handlers
|
|
`stm-confirm` / `notify` / failures — frontend-demo installs toast handlers
|
|
|
-through it), and `registerAttribute` (below).
|
|
|
|
|
-
|
|
|
|
|
-**`statum.registerAttribute(name, fn, {after, before})`** — the extension
|
|
|
|
|
-seam. `name` is an exact attribute name or, ending with `.`, a prefix
|
|
|
|
|
-matcher. `fn(el, scope)` runs once per element per render cycle for elements
|
|
|
|
|
-carrying a match; iterate `el.attributes` yourself when several match a
|
|
|
|
|
-prefix. `after`/`before` name another registered attribute and position the
|
|
|
|
|
-handler relative to it; an anchor that is not (yet) registered warns and
|
|
|
|
|
-keeps registration order — order is resolved at registration time, so a
|
|
|
|
|
-module that wants to be after `stm-html` should load after statum-document.
|
|
|
|
|
-Duplicate names warn and are ignored. Handler exceptions abort that render
|
|
|
|
|
-cycle (caught by renderAll's single try/catch) — same contract as the
|
|
|
|
|
-built-ins.
|
|
|
|
|
|
|
+through it). `registerAttribute` is DOCUMENT API (next section) — it is
|
|
|
|
|
+absent on a core-only page.
|
|
|
|
|
|
|
|
|
|
|
|
|
### Section: statum-document.js
|
|
### Section: statum-document.js
|
|
|
|
|
|
|
|
The render walk and the structural/value bindings. Installs the render
|
|
The render walk and the structural/value bindings. Installs the render
|
|
|
-driver. Attributes:
|
|
|
|
|
|
|
+driver and owns EVERY `stm-*` attribute that touches the DOM, including the
|
|
|
|
|
+ones that used to be listed under core:
|
|
|
|
|
+
|
|
|
|
|
+- **`stm-entrypoint`**, **`stm-slots`**, **`stm-channel`**, **`stm-worker`**
|
|
|
|
|
+ (on `<body>`): endpoint overrides. Document reads them at load and writes
|
|
|
|
|
+ them into core's mutable `statum.config` before init runs (defaults
|
|
|
|
|
+ `/_statum/entrypoint`, `/_statum/slots`, `/_statum/channel`,
|
|
|
|
|
+ `/_statum/resource/statum-worker.js`).
|
|
|
|
|
+- **`stm-preloader`** / **`stm-content`**: boot visibility. While the
|
|
|
|
|
+ entrypoint loads, `stm-preloader` elements are shown and `stm-content`
|
|
|
|
|
+ elements hidden; once ready, the reverse. Set `hidden` on `stm-content`
|
|
|
|
|
+ yourself in the HTML to avoid a flash of unbound template.
|
|
|
|
|
+- **`stm-guard`** (a `<link rel="stm-guard" require="…" href="…">`, plus the
|
|
|
|
|
+ `pre-entrypoint` attribute on the link): a client-side UX gate — when
|
|
|
|
|
+ `require` evaluates false, the page redirects to `href`. Re-checked every
|
|
|
|
|
+ render cycle; guards without `pre-entrypoint` only evaluate after the
|
|
|
|
|
+ entrypoint has loaded. This is UX sugar, NOT security.
|
|
|
|
|
+**`statum.registerAttribute(name, fn, {after, before})`** — the extension
|
|
|
|
|
+seam, provided by this module. `name` is an exact attribute name or, ending
|
|
|
|
|
+with `.`, a prefix matcher. `fn(el, scope)` runs once per element per render
|
|
|
|
|
+cycle for elements carrying a match; iterate `el.attributes` yourself when
|
|
|
|
|
+several match a prefix. `after`/`before` name another registered attribute
|
|
|
|
|
+and position the handler relative to it; an anchor that is not (yet)
|
|
|
|
|
+registered warns and keeps registration order — order is resolved at
|
|
|
|
|
+registration time, so a module that wants to be after `stm-html` should load
|
|
|
|
|
+after statum-document. Duplicate names warn and are ignored. Handler
|
|
|
|
|
+exceptions abort that render cycle (caught by renderAll's single try/catch)
|
|
|
|
|
+— same contract as the built-ins. Registering against core alone is safe:
|
|
|
|
|
+core queues the registration until document installs the registry.
|
|
|
|
|
+
|
|
|
|
|
+Walk bindings:
|
|
|
|
|
|
|
|
- **`stm-if` / `stm-else-if` / `stm-else`**: conditional chains among
|
|
- **`stm-if` / `stm-else-if` / `stm-else`**: conditional chains among
|
|
|
siblings. Branches are toggled with the `hidden` attribute (they stay in
|
|
siblings. Branches are toggled with the `hidden` attribute (they stay in
|
|
@@ -257,7 +268,9 @@ driver. Attributes:
|
|
|
- **`stm-confirm`**: gates the action behind the confirm handler
|
|
- **`stm-confirm`**: gates the action behind the confirm handler
|
|
|
(`statum.onConfirmHandler`; default `window.confirm`).
|
|
(`statum.onConfirmHandler`; default `window.confirm`).
|
|
|
- **`stm-busy-class`**: classes applied to the action element while busy.
|
|
- **`stm-busy-class`**: classes applied to the action element while busy.
|
|
|
- - **`stm-on-error`**: see core section.
|
|
|
|
|
|
|
+ - **`stm-on-error`** / **`stm-on-success`**: class names applied on
|
|
|
|
|
+ failure / success respectively (mirrored: each clears the other; a new
|
|
|
|
|
+ attempt clears both).
|
|
|
The element's `__stmAction` promise (and `__stmActionFailed` flag) are
|
|
The element's `__stmAction` promise (and `__stmActionFailed` flag) are
|
|
|
stashed per trigger for `stm-clear-on-success`.
|
|
stashed per trigger for `stm-clear-on-success`.
|
|
|
|
|
|