@mmstack/primitives 19.7.0 → 19.7.1

package/README.md

@@ -19,7 +19,7 @@ npm install @mmstack/primitives
 - [Timing & propagation](#timing--propagation) — `debounced`, `throttled`, `until`
 - [Reactive collections](#reactive-collections) — `indexArray`, `keyArray`, `mapObject`
 - [Effects](#effects) — `nestedEffect`
-- [Concurrency & transitions](#concurrency--transitions) — `keepPrevious`, keep-alive (`MmActivity`), `pausable*` / `providePausableOptions`, Suspense (`mm-suspense`), `startTransition` / `startTransaction`, `holdUntilReady`
+- [Concurrency & transitions](#concurrency--transitions) — `keepPrevious`, keep-alive (`MmActivity`), `pausable*` / `providePausableOptions`, Suspense (`mm-suspense`), hold-and-swap (`*mmTransition`), `startTransition` / `startTransaction`, `holdUntilReady`
 - [History & persistence](#history--persistence) — `withHistory`, `stored`, `tabSync`
 - [Performance helpers](#performance-helpers) — `chunked`, `pooled` / `pooledArray` / `pooledMap` / `pooledSet`
 - [Sensors](#sensors) — `sensor()` facade + browser-state signals
@@ -441,6 +441,25 @@ This is also the pattern for coordinating resources registered _above_ a boundar
 
 **Forwarding scope (advanced).** `provideForwardingTransitionScope()` provides a scope that can be **re-pointed at a different target at runtime** via `setTarget(scope | null)` — reads follow the current target, while `add`/`remove` pin to the target a resource was registered under (so re-pointing never strands a registration). It's the building block for a coordinator that hosts several independent sub-scopes and switches which one it observes — e.g. a router outlet that, per navigation, points at the incoming route's own scope (read it from any injector with `getTransitionScope(injector)`). Most apps reach for `provideTransitionScope()`; this is for that one extra level of control.
 
+### Hold-and-swap — `*mmTransition`
+
+The transition itself, for any branch change — tabs, wizard steps, master-detail. Suspense decides placeholder-vs-content _within_ a branch, but it can't stop an `@switch` from unmounting the old branch the instant the value flips. `*mmTransition` holds it: when the bound value changes, the **old view stays mounted and visible** (keeping its old value) while the **new view mounts hidden with its own transition scope**; resources created in the incoming subtree register there just by existing, and once they've gone in flight and settled the views swap in one frame.
+
+```html
+<div *mmTransition="selectedTab(); let tab">
+  @switch (tab) {
+    @case ('overview') {
+      <overview-pane />
+    }
+    @case ('activity') {
+      <activity-pane />
+    }
+  }
+</div>
+```
+
+The first render is immediate (nothing to hold). An interrupting change mid-hold destroys the half-ready hidden view and re-targets — the stable view stays visible until the newest branch settles. A branch that loads nothing swaps right after its first render, and per-view scopes mean the outgoing branch's background work can never delay the swap. `immediate: true` skips holding; `viewTransition: true` wraps the swap in `document.startViewTransition` (feature detected). This is `@mmstack/router-core`'s `<mm-transition-outlet>` without the router — same semantics, any signal as the trigger.
+
 ### `injectStartTransition`
 
 The analog of React's `useTransition`. `startTransition(fn)` runs your state mutations (which commit immediately); any resource that reloads as a result **holds its value and reveals together once everything settles** — so a multi-resource update lands as one consistent frame instead of a torn mix of new and stale. The returned handle gives you a unified `pending` signal and a `done` promise for imperative coordination (disable a button, await completion).

package/fesm2022/mmstack-primitives.mjs

@@ -945,6 +945,170 @@ function injectStartTransaction() {
     };
 }
 
+/**
+ * Generic hold-and-swap: the non-router `TransitionRouterOutlet`. When the bound value changes,
+ * the OLD view stays mounted and visible (it keeps its old context value — that's the hold) while
+ * the NEW view mounts hidden with its **own transition scope**; resources created in the incoming
+ * subtree register into that scope just by existing, and once they've gone in flight and settled
+ * the views swap in one frame. Tabs, wizard steps, master-detail — any branch change that would
+ * otherwise flash a loading state.
+ *
+ * ```html
+ * <div *mmTransition="selectedTab(); let tab">
+ *   @switch (tab) { ... }
+ * </div>
+ * ```
+ *
+ * Distinct from `<mm-suspense>` (the readiness gate): suspense decides placeholder-vs-content
+ * *within* one branch, but can't stop an `@switch` from unmounting the old branch the instant the
+ * value flips. This directive is the swap itself — the old branch survives until the new one is
+ * ready. Compose them freely: suspense inside a transitioned branch handles its first load.
+ *
+ * Semantics mirror the outlet: the first render is immediate (nothing to hold); an interrupting
+ * value change mid-hold destroys the half-ready hidden view and re-targets; a branch that loads
+ * nothing swaps right after its first render. Per-view scopes mean the outgoing branch's
+ * background work can never delay the swap. Set `mmTransitionImmediate` to skip holding, and
+ * `mmTransitionViewTransition` to wrap the swap in `document.startViewTransition` (feature
+ * detected). On the server every change swaps immediately.
+ */
+class MmTransition {
+    tpl = inject(TemplateRef);
+    vcr = inject(ViewContainerRef);
+    parent = inject(Injector);
+    onServer = isPlatformServer(inject(PLATFORM_ID, { optional: true }) ?? 'browser');
+    /** The value whose changes are transitioned. Each view keeps the value it was created with. */
+    value = input.required({ alias: 'mmTransition' });
+    /** Skip holding entirely — every change swaps at once (the plain re-render behavior). */
+    immediate = input(false, { alias: 'mmTransitionImmediate' });
+    /** Wrap the swap in the View Transitions API for an animated cross-fade (feature detected). */
+    viewTransition = input(false, {
+        alias: 'mmTransitionViewTransition',
+    });
+    current = null;
+    incoming = null;
+    /** Bumped on every re-target/teardown so a superseded (possibly deferred) swap can't commit. */
+    swapEpoch = 0;
+    holding = signal(false);
+    /** True while an incoming view is mounted hidden, waiting to settle. */
+    pending = this.holding.asReadonly();
+    static ngTemplateContextGuard(dir, 
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    ctx) {
+        return true;
+    }
+    constructor() {
+        effect(() => {
+            const v = this.value();
+            untracked(() => this.onValue(v));
+        });
+        inject(DestroyRef).onDestroy(() => {
+            this.swapEpoch++; // a deferred view-transition callback must not touch destroyed state
+            this.dropIncoming();
+            // `current` is destroyed with the container
+        });
+    }
+    onValue(v) {
+        if (!this.current) {
+            // first render: nothing to hold yet — show immediately (also what SSR serializes)
+            this.current = this.createView(v).view;
+            return;
+        }
+        this.dropIncoming(); // an interrupting change supersedes the previous hold
+        this.swapEpoch++;
+        const epoch = this.swapEpoch;
+        if (this.onServer || this.immediate()) {
+            this.finishSwap(epoch, this.createView(v).view);
+            return;
+        }
+        const { view, scope } = this.createView(v);
+        this.setHidden(view, true);
+        this.holding.set(true);
+        // Registration happens synchronously during view creation, so a resource already in
+        // flight counts from the start; later kickoffs are caught by the watcher.
+        let sawPending = untracked(scope.pending);
+        const watcher = effect(() => {
+            const pending = scope.pending();
+            untracked(() => {
+                if (epoch !== this.swapEpoch)
+                    return;
+                if (pending)
+                    sawPending = true;
+                if (sawPending && !pending)
+                    this.commitSwap(epoch, view);
+            });
+        }, { injector: this.parent });
+        this.incoming = { view, watcher };
+        // Fallback for a branch that loads nothing.
+        afterNextRender(() => {
+            if (epoch === this.swapEpoch &&
+                !sawPending &&
+                !untracked(scope.pending)) {
+                this.commitSwap(epoch, view);
+            }
+        }, { injector: this.parent });
+    }
+    commitSwap(epoch, view) {
+        if (epoch !== this.swapEpoch)
+            return;
+        if (this.viewTransition() &&
+            typeof document !== 'undefined' &&
+            document.startViewTransition) {
+            // the browser snapshots the old frame first; the epoch guard covers the deferral
+            document.startViewTransition(() => this.finishSwap(epoch, view));
+        }
+        else {
+            this.finishSwap(epoch, view);
+        }
+    }
+    /** The actual swap: destroy the old view, reveal the new one. Always instant. */
+    finishSwap(epoch, view) {
+        if (epoch !== this.swapEpoch)
+            return; // superseded while deferred — not ours to commit
+        this.swapEpoch++; // consume: the watcher and the render fallback can both fire, one commits
+        this.current?.destroy();
+        this.setHidden(view, false);
+        this.current = view;
+        this.incoming?.watcher.destroy();
+        this.incoming = null;
+        this.holding.set(false);
+    }
+    dropIncoming() {
+        if (!this.incoming)
+            return;
+        this.incoming.watcher.destroy();
+        this.incoming.view.destroy();
+        this.incoming = null;
+        this.holding.set(false);
+    }
+    createView(v) {
+        // Each view gets its own scope, so its subtree's resources register here by existing —
+        // and the outgoing view's background work can't block the swap (per-view isolation).
+        const injector = Injector.create({
+            parent: this.parent,
+            providers: [provideTransitionScope()],
+        });
+        const scope = getTransitionScope(injector);
+        const view = this.vcr.createEmbeddedView(this.tpl, { $implicit: v, mmTransition: v }, { injector });
+        return { view, scope };
+    }
+    setHidden(view, hidden) {
+        for (const node of view.rootNodes) {
+            // covers HTML and SVG roots; text/comment roots can't be styled — prefer an element root
+            if (node instanceof HTMLElement || node instanceof SVGElement)
+                node.style.display = hidden ? 'none' : '';
+        }
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "19.2.19", ngImport: i0, type: MmTransition, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "19.2.19", type: MmTransition, isStandalone: true, selector: "[mmTransition]", inputs: { value: { classPropertyName: "value", publicName: "mmTransition", isSignal: true, isRequired: true, transformFunction: null }, immediate: { classPropertyName: "immediate", publicName: "mmTransitionImmediate", isSignal: true, isRequired: false, transformFunction: null }, viewTransition: { classPropertyName: "viewTransition", publicName: "mmTransitionViewTransition", isSignal: true, isRequired: false, transformFunction: null } }, exportAs: ["mmTransition"], ngImport: i0 });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "19.2.19", ngImport: i0, type: MmTransition, decorators: [{
+            type: Directive,
+            args: [{
+                    selector: '[mmTransition]',
+                    exportAs: 'mmTransition',
+                }]
+        }], ctorParameters: () => [] });
+
 /**
  * @internal
  */
@@ -4661,5 +4825,5 @@ function withHistory(sourceOrValue, opt) {
  * Generated bundle index. Do not edit.
  */
 
-export { MmActivity, PAUSABLE_OPTIONS, SuspenseBoundary, SuspenseBoundaryBase, UnscopedSuspenseBoundary, activeTransaction, batteryStatus, chunked, clipboard, combineWith, createAttributedPending, createForwardingScope, createTransaction, createTransitionScope, debounce, debounced, derived, distinct, elementSize, elementVisibility, extendStore, filter, filterWith, focusWithin, forkStore, geolocation, getTransitionScope, holdUntilReady, idle, indexArray, injectPaused, injectRegisterResource, injectStartTransaction, injectStartTransition, injectTransitionScope, isDerivation, isLeaf, isMutable, isOpaque, isStore, keepPrevious, keyArray, map, mapArray, mapObject, mediaQuery, merge3, mousePosition, mutable, mutableStore, nestedEffect, networkStatus, opaque, orientation, pageVisibility, pairwise, pausableComputed, pausableEffect, pausableSignal, pipeable, piped, pointerDrag, pooled, pooledArray, pooledMap, pooledSet, prefersDarkMode, prefersReducedMotion, provideForwardingTransitionScope, providePausableOptions, providePaused, provideTransitionScope, registerResource, resolvePause, scan, scrollPosition, select, sensor, sensors, signalFromEvent, startWith, store, stored, tabSync, tap, throttle, throttled, toFakeDerivation, toFakeSignalDerivation, toStore, toWritable, until, windowSize, withHistory };
+export { MmActivity, MmTransition, PAUSABLE_OPTIONS, SuspenseBoundary, SuspenseBoundaryBase, UnscopedSuspenseBoundary, activeTransaction, batteryStatus, chunked, clipboard, combineWith, createAttributedPending, createForwardingScope, createTransaction, createTransitionScope, debounce, debounced, derived, distinct, elementSize, elementVisibility, extendStore, filter, filterWith, focusWithin, forkStore, geolocation, getTransitionScope, holdUntilReady, idle, indexArray, injectPaused, injectRegisterResource, injectStartTransaction, injectStartTransition, injectTransitionScope, isDerivation, isLeaf, isMutable, isOpaque, isStore, keepPrevious, keyArray, map, mapArray, mapObject, mediaQuery, merge3, mousePosition, mutable, mutableStore, nestedEffect, networkStatus, opaque, orientation, pageVisibility, pairwise, pausableComputed, pausableEffect, pausableSignal, pipeable, piped, pointerDrag, pooled, pooledArray, pooledMap, pooledSet, prefersDarkMode, prefersReducedMotion, provideForwardingTransitionScope, providePausableOptions, providePaused, provideTransitionScope, registerResource, resolvePause, scan, scrollPosition, select, sensor, sensors, signalFromEvent, startWith, store, stored, tabSync, tap, throttle, throttled, toFakeDerivation, toFakeSignalDerivation, toStore, toWritable, until, windowSize, withHistory };
 //# sourceMappingURL=mmstack-primitives.mjs.map