@xmachines/play-dom 2.2.0 → 3.0.0

package/README.md

@@ -2,7 +2,7 @@
 
 Vanilla DOM renderer for XMachines Play architecture with signal-driven rendering.
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Version](https://img.shields.io/badge/version-2.2.0-blue)](https://www.npmjs.com/package/@xmachines/play-dom)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Version](https://img.shields.io/badge/version-3.0.0-blue)](https://www.npmjs.com/package/@xmachines/play-dom)
 
 ## Installation
 
@@ -114,7 +114,7 @@ disconnect();
 
 Use `createPlayUI` when you need a render error handler, a fallback element, a navigation integration, a computed function, or a custom check. Use it also when your code needs the `registryResult` value, for example for `executeAction`.
 
-The factory holds the factory options (`functions`, `validationFunctions`, `navigate`, `onRenderError`, and `fallback`) from the moment of its creation, and it applies them on every `mount()` call. Give the mount options (`store` and `loading`) to `mount()` itself.
+The factory holds the factory options (`functions`, `validationFunctions`, `navigate`, `onRenderError`, `onError`, and `fallback`) from the moment of its creation, and it applies them on every `mount()` call. Give the mount options (`store` and `loading`) to `mount()` itself.
 
 ```typescript
 import { defineRegistry, createPlayUI, schema } from "@xmachines/play-dom";
@@ -277,6 +277,69 @@ The order of the arguments is the same as in the `RenderErrorHandler` type of `@
 
 Without `onRenderError`, the renderer writes all three types of error to `console.error`, then stops them. No exception goes to the caller, and no promise rejection stays unhandled.
 
+### The renderer contains a failed rebuild — a change of behaviour in 2.3.0
+
+**Read this if you catch what `mount()` or `connect()` throws.**
+
+In 2.2.0 the renderer had no containment. A view that failed the rebuild threw out of
+`mount()` and out of the callback of the signal watcher, so a `try` of the host, an error
+boundary of the framework around it, or the global handler of the page received it.
+
+In 2.3.0 the renderer contains such a failure ALWAYS. No option turns the containment on,
+and no option turns it off. The renderer clears the container, it shows the `fallback`,
+and `mount()` returns normally. A host that shows its own error page from a `catch` around
+`mount()` sees that `catch` never again.
+
+The four framework renderers contain a failed render always, because an error boundary of
+a framework is not an option that a caller turns off. This change puts play-dom on the
+same rule.
+
+**To escalate a failure, raise it from a task of your own:**
+
+```typescript
+const mount = createPlayUI(registryResult, {
+	onError: (err) => {
+		reportToSentry(err);
+		queueMicrotask(() => {
+			throw err; // the page keeps its own global handler
+		});
+	},
+});
+```
+
+A throw that leaves the handler itself reaches no caller. The renderer contains it and
+writes it to `console.error`, exactly as the four framework renderers do. The five hold
+this one rule, so a host learns it one time and writes the same handler for each of them.
+
+### `onError` — the failure of a complete rebuild
+
+`onRenderError` covers one element: the inner renderer contains a render error of a component, and a rejection of an action handler, per element, and the rebuild continues. Some failures escape that boundary — a `$computed` function that throws during the resolution of a prop, for example — and they abort the complete rebuild.
+
+`onError` receives such a failure. The renderer contains it with this option and without it: it resets the state of the failed rebuild, so that the next emission makes a complete render again, and it clears the container. `connect()` renders the first view synchronously, so a bad initial view makes `connect()` throw no more.
+
+A write of the store takes the same path. The renderer resolves the props of every element that the write touched, so a `$computed` function that throws on the new state aborts that render too. The renderer contains such a failure as well, and the action handler that wrote the state receives no exception.
+
+The second parameter is the **reset**, for a retry that the host starts. It renders the view that the actor holds at the moment of the call, so a retry cannot rewind the screen to the view that failed. A reset that the host calls from inside the handler does nothing, because no input changed between the two attempts, and a reset after the provider goes away does nothing. The five renderers hold the same three rules.
+
+A reset of `PlayRenderer` belongs to ONE connection. `connect()` starts a connection, and the reset of a report of an older connection does nothing. A host that calls `connect()` again from inside the handler abandons the connection that reported. The "Retry" button of that report must not render into the connection that took its place. Call the reset of the newest report.
+
+A fourth rule holds in all five: each of them CONTAINS a handler that throws, and writes the throw to `console.error`. A host that must escalate raises the failure from a task of its own, as the section above shows.
+
+```typescript
+const mount = createPlayUI(registryResult, {
+	onError: (err) => reportToSentry(err),
+	fallback: document.getElementById("crashed")!,
+});
+```
+
+`createPlayUI` adds the parity with the framework providers: the renderer contains the failure, and it appends the `fallback` to the container that the failed rebuild left clear. A later view that renders clears the container again, which removes the fallback.
+
+`onError` says WHERE the report goes, and `fallback` says what the empty container shows. Neither option turns the containment on. Without `onError` the renderer writes the contained error to `console.error`, in the same way as it does for a component that throws without an `onRenderError` handler. Give `onError` to send the failure to your own observability tool instead.
+
+**One fallback element belongs to one mount.** `appendChild` moves a node. Two mounts of the same factory therefore take the element from each other on every null view, and the container of the first one goes empty without a notice. Build one element for each `mount()` call.
+
+**A `fallback` producer that throws is contained too — on a null view and after a failed rebuild alike — and it reports to `console.error` and NOT to `onError`.** After a failed rebuild the renderer calls the producer from inside the containment of the view, so a second trip through `onError` would report the failure of your fallback as a failure of the view. The container stays empty, and the renderer renders the next view that works.
+
 A component implementation can also read the handler at `ctx.ctx.onRenderError`. A component therefore sends its own internal errors through the same channel:
 
 ```typescript
@@ -296,14 +359,15 @@ const Home: ComponentFn<typeof catalog, "Home"> = ({ ctx }) => {
 
 ### XMachines Layer
 
-| Export                                   | Kind     | Description                                                                       |
-| ---------------------------------------- | -------- | --------------------------------------------------------------------------------- |
-| `createRenderer(catalog, components)`    | function | The one-call factory. It returns `mount(actor, container, options?) → disconnect` |
-| `createPlayUI(registryResult, options?)` | function | The complete factory. It returns a `MountFn`                                      |
-| `PlayRenderer`                           | class    | The renderer class, with a `connect()` and `disconnect()` lifecycle               |
-| `defineRegistry(catalog, options)`       | function | Build a catalog-typed `DomRegistry` with typed handlers                           |
-| `renderSpec(...)`                        | function | The pure low-level Spec → DOM renderer                                            |
-| `schema`                                 | const    | The `@xmachines/json-render-dom` schema — pass to `defineCatalog()`               |
+| Export                                   | Kind     | Description                                                         |
+| ---------------------------------------- | -------- | ------------------------------------------------------------------- |
+| `createRenderer(catalog, components)`    | function | The one-call factory. Its `mount` hands a `Cleanup` back            |
+| `createPlayUI(registryResult, options?)` | function | The complete factory. It returns a `DisposablePlayUI`               |
+| `PlayRenderer`                           | class    | The renderer class, with a `connect()` and `disconnect()` lifecycle |
+| `defineRegistry(catalog, options)`       | function | Build a catalog-typed `DomRegistry` with typed handlers             |
+| `renderSpec(...)`                        | function | The pure low-level Spec → DOM renderer                              |
+| `schema`                                 | const    | The `@xmachines/json-render-dom` schema — pass to `defineCatalog()` |
+| `Cleanup`                                | type     | The release a mount returns, re-exported from `@xmachines/play`     |
 
 ### Key Types
 
@@ -315,21 +379,23 @@ const Home: ComponentFn<typeof catalog, "Home"> = ({ ctx }) => {
 | `EventHandle`            | The handle that `on(eventName)` returns. It has `emit()`, `shouldPreventDefault`, and `bound` |
 | `SetState`               | State updater: `(prev => next) => void`                                                       |
 | `DefineRegistryResult`   | The result of `defineRegistry`. It has `registry`, `handlers`, and `executeAction`            |
-| `PlayDomOptions`         | Options for `PlayRenderer` — extends `UIProviderOptions`                                      |
-| `CreatePlayUIOptions`    | Options for `createPlayUI` — extends `UIProviderOptions`, adds `fallback`                     |
+| `PlayDomOptions`         | Options for `PlayRenderer` — extends `UIProviderOptions`, adds `fallback` and `onError`       |
+| `CreatePlayUIOptions`    | Options for `createPlayUI` — extends `UIProviderOptions`, adds `fallback` and `onError`       |
 | `MountOptions`           | Per-mount options for `MountFn`: `store`, `loading`                                           |
-| `MountFn`                | The mount function that `createPlayUI` returns: `(actor, container, options?) → disconnect`   |
+| `MountFn`                | The type of a mount that a consumer writes: `(actor, container, options?) → disconnect`       |
+| `DisposablePlayUI`       | The mount that `createPlayUI` builds. It hands a `Cleanup` back, so `using` releases it       |
 | `UIProviderOptions`      | Shared options: `functions`, `validationFunctions`, `navigate`, `onRenderError`               |
 | `BaseComponentProps<P>`  | Catalog-agnostic component props for shared component libraries                               |
 | `DomRegistry`            | Raw registry type: `Record<string, DomComponentRenderer>`                                     |
 | `DomSchema`              | Type of the `schema` export                                                                   |
 | `ComputedFunction`       | The type of a named compute function for the `functions` option                               |
+| `Cleanup`                | The release of a mount, re-exported from `@xmachines/play`                                    |
 
 ## Rendering Behavior
 
 - **The first render is synchronous** — the renderer fills the container before `connect()` returns.
 - **A signal-driven render waits for a microtask** — `watchSignal` puts each update on the next tick of the microtask queue.
-- **A null view** clears the container. The renderer can show a `fallback` element on the first mount, when the view is `null`. It does **not** add that element again when the view returns to `null` after a view that was not null.
+- **A null view** clears the container, and the renderer then shows the `fallback` element when you give one. It shows it for every null view, and not for the first mount only — the four framework providers hold the same rule for their placeholder content.
 - **A second `connect()` is safe** — a `connect()` call on a connected renderer disconnects it first.
 - **`disconnect()` clears the container** and cancels every signal watcher and store watcher.
 

package/dist/PlayRenderer.d.ts

@@ -64,6 +64,15 @@ export declare class PlayRenderer {
     private readonly actor;
     private readonly registry;
     private readonly options;
+    /**
+     * True from the start of `connect()` to the end of `disconnect()`.
+     *
+     * The watcher cannot answer this question. `connect()` installs it AFTER the
+     * synchronous first render, so a host that calls `connect()` again from the `onError`
+     * of that render finds no watcher, and a test of the watcher alone would skip the
+     * `disconnect()` and leave the guard of the abandoned connection alive for ever.
+     */
+    private connected;
     private unwatch;
     private storeUnsubscribe;
     /**
@@ -88,6 +97,8 @@ export declare class PlayRenderer {
      */
     private lastViewKey;
     private currentStore;
+    /** The fallback element, built at the first moment that the renderer shows it. */
+    private fallbackElement;
     /**
      * The shared coordinator of the store lifecycle, from @xmachines/play-actor. It
      * seeds the store again on a change of the viewKey, it refreshes /context in place
@@ -104,6 +115,25 @@ export declare class PlayRenderer {
      * call, which is rare but correct, changes no detached DOM tree.
      */
     private alive;
+    /**
+     * The report guard, from @xmachines/play-actor.
+     *
+     * It blocks a reset that the host calls from INSIDE the report, and every reset once
+     * the renderer is disconnected. The five renderers share the one implementation.
+     *
+     * `alive` cannot answer the second half. A contained failure sets that flag to `false`
+     * and the next emission sets it back, because it guards the callback of the store
+     * subscription — a reset that a host keeps outlives both.
+     */
+    private guard;
+    /**
+     * The retry that every report of THIS connection hands the host.
+     *
+     * `connect()` builds one, beside the guard that it belongs to. The four framework
+     * renderers hand the host one reset for the life of the provider, and this field holds
+     * the same rule for the life of the connection.
+     */
+    private retry;
     /**
      * @param container - The `HTMLElement` to render into. Each view transition clears it and fills it again.
      * @param actor     - The actor with the `currentView` signal. It must implement `Viewable`.
@@ -117,6 +147,8 @@ export declare class PlayRenderer {
      *   - `validationFunctions` — your own check functions. They are available at `ctx.ctx.validationFunctions`.
      *   - `navigate`            — the navigation callback. The renderer calls it for `onSuccess: { navigate: "..." }`.
      *   - `onRenderError`       — the `(error, name)` handler of a component render error and of an action handler rejection. It stops the `console.error` fallback.
+     *   - `onError`             — the `(error, reset)` handler of a failure of a complete rebuild. The renderer contains such a failure always, and this option says where the report goes.
+     *   - `fallback`            — the element to show for every null view, and after a contained failure.
      */
     constructor(container: HTMLElement, actor: AbstractActor<AnyActorLogic> & Viewable, registry: DomRegistry, options?: PlayDomOptions);
     /**
@@ -142,11 +174,77 @@ export declare class PlayRenderer {
      */
     get watchCleanupCount(): number;
     private render;
+    /**
+     * The end of a render that failed, in ONE place.
+     *
+     * Three paths render — the fast path of a slice, the complete rebuild, and the write
+     * of the store — and each one ends here. The ORDER is load-bearing: the reset takes
+     * the registrations of the dead tree down BEFORE the report, so a handler of the host
+     * that renders again meets a renderer that holds nothing of the failed attempt. A
+     * second copy of the pair is a second chance to put the two in the other order.
+     *
+     * @param error - The failure that the renderer contains.
+     */
+    private failView;
+    /**
+     * Clears the screen of the failed view, shows the fallback, and reports the failure.
+     *
+     * The renderer contains such a failure ALWAYS. No option turns the containment on,
+     * and none turns it off: `onError` says where the report goes, and `fallback` says
+     * what the empty container shows. The four framework renderers hold the same rule,
+     * because an error boundary of a framework is not an option that a caller turns off.
+     * A host that must escalate a failure raises it from a task of its own —
+     * `queueMicrotask(() => { throw error; })` — because the guard contains a handler
+     * that throws, exactly as the four framework renderers do.
+     *
+     * The container is cleared FIRST. The fast path of a slice holds the live tree of the
+     * previous emission, and that tree is dead as soon as the refresh throws, so the
+     * renderer must not keep it on the screen. A clear container also lets the fallback
+     * stand alone.
+     *
+     * The SCREEN comes first, and the report second: a handler that throws — a reporter
+     * that fails, or one that re-raises to escalate — must not defeat the containment
+     * that it was given to observe. With the order reversed the container stays empty AND
+     * the error escapes, which is both outcomes that the containment exists to prevent.
+     */
+    private contain;
+    /**
+     * Builds the retry that one report hands the host.
+     *
+     * The read of the signal happens at the moment of the CALL: a retry that held the view
+     * that failed would take a host off the healthy screen and back onto the one that
+     * threw.
+     *
+     * The retry belongs to the guard of ITS connection, and it asks that guard alone. A
+     * host may KEEP the callback — a "Retry" button of a toast outlives the route that
+     * opened it — and `disconnect()` disposes the guard that was live then. `connect()`
+     * disconnects a connected renderer first, so every guard that leaves the field is a
+     * disposed guard, and a retry of an older connection stays dead. The rule of the prop
+     * is one rule: a reset after `disconnect()` does nothing.
+     *
+     * @param guard - The guard of the connection that this retry belongs to.
+     */
+    private retryOf;
+    /**
+     * Appends the fallback element to the container, which the caller cleared already.
+     * The renderer calls it for a null view, and after a failure of a rebuild that it
+     * contains. Both callers clear the container first. `appendChild` moves the node.
+     * Therefore a second call adds no copy.
+     */
+    private showFallback;
     /**
      * A rebuild that fails must not leave the guard of the fast path armed on a dead
      * tree, because the container is empty already. Therefore this code resets the view
      * identity. The next emission, also one with the same viewKey, then makes a
      * complete render again. It does not patch a store that nothing shows.
+     *
+     * It releases the watch subscriptions of the dead tree too. A complete rebuild
+     * releases them before it builds again, and disconnect() releases them at the end of
+     * the life of the renderer — but a failure takes the DOM down HERE, between those two
+     * moments. Without this step one update of the store of the host runs every watch
+     * action of a tree that nothing shows, against detached elements, with `send` still
+     * bound to the actor. The fast path of a slice leaves a live tree of its own, and it
+     * reaches this code only when it fails.
      */
     private resetFailedRebuild;
     /**

package/dist/PlayRenderer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PlayRenderer.d.ts","sourceRoot":"","sources":["../src/PlayRenderer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAQH,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAY,MAAM,uBAAuB,CAAC;AAC/E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAG5C,OAAO,KAAK,EAAE,WAAW,EAAY,MAAM,4BAA4B,CAAC;AACxE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,qBAAa,YAAY;IA2DvB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO;IA7DzB,OAAO,CAAC,OAAO,CAA6B;IAC5C,OAAO,CAAC,gBAAgB,CAA6B;IACrD;;;;;;;OAOG;IACH,OAAO,CAAC,aAAa,CAAyB;IAC9C;;;;;;;;;;OAUG;IACH,OAAO,CAAC,WAAW,CAAiC;IACpD,OAAO,CAAC,YAAY,CAA2B;IAC/C;;;;;;;OAOG;IACH,OAAO,CAAC,QAAQ,CAAC,cAAc,CAE7B;IACF;;;;;OAKG;IACH,OAAO,CAAC,KAAK,CAAQ;IAErB;;;;;;;;;;;;;OAaG;gBAEe,SAAS,EAAE,WAAW,EACtB,KAAK,EAAE,aAAa,CAAC,aAAa,CAAC,GAAG,QAAQ,EAC9C,QAAQ,EAAE,WAAW,EACrB,OAAO,GAAE,cAAmB;IAG9C;;;;;;;;OAQG;IACH,OAAO,IAAI,IAAI;IAMf;;OAEG;IACH,UAAU,IAAI,IAAI;IAyBlB;;;;;;OAMG;IACH,IAAI,iBAAiB,IAAI,MAAM,CAE9B;IAED,OAAO,CAAC,MAAM;IAqEd;;;;;OAKG;IACH,OAAO,CAAC,kBAAkB;IAS1B;;;;;;;OAOG;IACH,OAAO,CAAC,UAAU;CA+GlB"}
+{"version":3,"file":"PlayRenderer.d.ts","sourceRoot":"","sources":["../src/PlayRenderer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAYH,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAY,MAAM,uBAAuB,CAAC;AAC/E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAG5C,OAAO,KAAK,EAAE,WAAW,EAAY,MAAM,4BAA4B,CAAC;AACxE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAyDjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,qBAAa,YAAY;IA+FvB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAjGzB;;;;;;;OAOG;IACH,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,OAAO,CAA6B;IAC5C,OAAO,CAAC,gBAAgB,CAA6B;IACrD;;;;;;;OAOG;IACH,OAAO,CAAC,aAAa,CAAyB;IAC9C;;;;;;;;;;OAUG;IACH,OAAO,CAAC,WAAW,CAAiC;IACpD,OAAO,CAAC,YAAY,CAA2B;IAC/C,kFAAkF;IAClF,OAAO,CAAC,eAAe,CAA4B;IACnD;;;;;;;OAOG;IACH,OAAO,CAAC,QAAQ,CAAC,cAAc,CAE7B;IACF;;;;;OAKG;IACH,OAAO,CAAC,KAAK,CAAQ;IAErB;;;;;;;;;OASG;IAGH,OAAO,CAAC,KAAK,CAAkD;IAE/D;;;;;;OAMG;IACH,OAAO,CAAC,KAAK,CAAwC;IAErD;;;;;;;;;;;;;;;OAeG;gBAEe,SAAS,EAAE,WAAW,EACtB,KAAK,EAAE,aAAa,CAAC,aAAa,CAAC,GAAG,QAAQ,EAC9C,QAAQ,EAAE,WAAW,EACrB,OAAO,GAAE,cAAmB;IAG9C;;;;;;;;OAQG;IACH,OAAO,IAAI,IAAI;IAyCf;;OAEG;IACH,UAAU,IAAI,IAAI;IA4BlB;;;;;;OAMG;IACH,IAAI,iBAAiB,IAAI,MAAM,CAE9B;IAED,OAAO,CAAC,MAAM;IAmGd;;;;;;;;;;OAUG;IACH,OAAO,CAAC,QAAQ;IAKhB;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,OAAO,CAAC,OAAO;IAiBf;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,OAAO;IAOf;;;;;OAKG;IACH,OAAO,CAAC,YAAY;IA4BpB;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,kBAAkB;IAuB1B;;;;;;;OAOG;IACH,OAAO,CAAC,UAAU;CA6HlB"}