Sfoglia il codice sorgente

Fix stale module attributions in the docs after the rearchitecture

TEMPLATES.md's core section still listed the six stm-* attributes Task E moved to document (endpoint overrides, preloader/content, guard, on-error, class, disabled) and presented registerAttribute as core API; core now documented as it is: headless, zero stm-* attributes, with the moved attributes re-attributed to the document section and on-error/on-success documented as mirrored companions. Also corrects the module count in three leftover references (WHATS_NEW, TEMPLATES, getting-started) that still said three tags/modules.
saddle-ClankerSaddle 2 settimane fa
parent
commit
6db186040a
3 ha cambiato i file con 55 aggiunte e 42 eliminazioni
  1. 53 40
      TEMPLATES.md
  2. 1 1
      WHATS_NEW.md
  3. 1 1
      getting-started.md

+ 53 - 40
TEMPLATES.md

@@ -97,7 +97,7 @@ Rewrites to `{attr}="/_statum/resource/{value}"`. `<script
 pstm-res-src="statum-core.js">` becomes `<script
 src="/_statum/resource/statum-core.js">`. Works for any attribute name
 (`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)
 
@@ -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
 the legacy reference with explicit module tags is deduplicated — each module
 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).
 
 ### 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
 
-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`,
 `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`,
 `init`, `read`, `getSnapshot`, `getFrame`, `state`, `clear`, `act`,
 `addStateListener` / `removeStateListener`, `beforeEvaluate` /
-`afterEvaluate`, `Error`, the `onConfirmHandler` / `onNotifyHandler` /
+`afterEvaluate`, `Error`, and the `onConfirmHandler` / `onNotifyHandler` /
 `onErrorHandler` getter/setter pairs (the override mechanism for
 `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
 
 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
   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
     (`statum.onConfirmHandler`; default `window.confirm`).
   - **`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
   stashed per trigger for `stm-clear-on-success`.
 

+ 1 - 1
WHATS_NEW.md

@@ -41,7 +41,7 @@ Cherry-picking still works (core first, always): a headless page loads only
 core; a page without markdown loads core+document.
 
 Legacy pages that still say `<script pstm-res-src="statum.js"></script>` keep
-working: `statum-mkpstm` expands that reference at build time into the three
+working: `statum-mkpstm` expands that reference at build time into the four
 tags above (one build warning per page names the expansion; explicit module
 tags are deduplicated). The single-file artifact itself no longer exists.
 

+ 1 - 1
getting-started.md

@@ -143,7 +143,7 @@ All `pstm-*` elements **must appear inside `<head>`** (except `pstm-content` and
 | `<pstm-fragment name="card" />` | body | Inlines a fragment (component) by name. |
 | `pstm-materialise-as="div"` | `<body>` attr | When this body is composited into a template or fragment, it is wrapped in the named element. |
 | `pstm-res-src="logo.png"` | any attr | Rewrites to `src="/_statum/resource/logo.png"`. Also `pstm-res-href`, etc. |
-| `pstm-res-src="statum.js"` | `<script>` | **Legacy.** Expands at build time into the three client module tags in load order (one warning per page; explicit module tags are deduped). Prefer the three explicit tags. |
+| `pstm-res-src="statum.js"` | `<script>` | **Legacy.** Expands at build time into the four client module tags in load order (one warning per page; explicit module tags are deduped). Prefer the four explicit tags. |
 
 ### Head merging