@mmstack/primitives 19.4.2 → 19.5.1

package/README.md

@@ -418,6 +418,8 @@ export class UserProfile {
 
 This is also the pattern for coordinating resources registered _above_ a boundary (e.g. an app-builder page whose connectors register at a higher injector): the outer `provideTransitionScope()` is the shared scope, and any number of `<mm-unscoped-suspense>` boundaries observe it.
 
+**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.
+
 ### `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

@@ -1,5 +1,5 @@
 import * as i0 from '@angular/core';
-import { isDevMode, inject, Injector, untracked, effect, DestroyRef, linkedSignal, InjectionToken, TemplateRef, ViewContainerRef, input, computed, Directive, signal, PLATFORM_ID, runInInjectionContext, ResourceStatus, afterNextRender, Component, isSignal, ElementRef, Injectable } from '@angular/core';
+import { isDevMode, inject, Injector, untracked, effect, DestroyRef, linkedSignal, InjectionToken, TemplateRef, ViewContainerRef, PLATFORM_ID, input, computed, Directive, signal, runInInjectionContext, ResourceStatus, afterNextRender, Component, isSignal, ElementRef, Injectable } from '@angular/core';
 import { isPlatformServer } from '@angular/common';
 import { SIGNAL } from '@angular/core/primitives/signals';
 
@@ -80,7 +80,7 @@ function popFrame() {
  * ]);
  *
  * // The fine-grained mapped list
- * const mappedUsers = mapArray(
+ * const mappedUsers = indexArray(
  *   users,
  *   (userSignal, index) => {
  *     // 1. Create a fine-grained SIDE EFFECT for *this item*
@@ -101,7 +101,7 @@ function popFrame() {
  *     };
  *   },
  *   {
- *     // 3. Tell mapArray HOW to clean up when an item is removed, this needs to be manual as it's not a nestedEffect itself
+ *     // 3. Tell indexArray HOW to clean up when an item is removed, this needs to be manual as it's not a nestedEffect itself
  *     onDestroy: (mappedItem) => {
  *       mappedItem.destroyEffect();
  *     }
@@ -248,6 +248,7 @@ class MmActivity {
     tpl = inject(TemplateRef);
     vcr = inject(ViewContainerRef);
     parent = inject(Injector);
+    onServer = isPlatformServer(inject(PLATFORM_ID, { optional: true }) ?? 'browser');
     /** When false, keep the content mounted but hidden + CD-detached. */
     visible = input.required({ alias: 'mmActivity' });
     /** Paused == not visible — handed to the kept subtree as PAUSED_CONTEXT. */
@@ -270,6 +271,8 @@ class MmActivity {
                 }),
             });
         }
+        if (this.onServer)
+            return;
         for (const node of this.view.rootNodes) {
             // covers HTML and SVG roots; text/comment roots can't be styled — their CD is still
             // detached, but prefer an element root for true visual hiding
@@ -567,6 +570,47 @@ function injectTransitionScope() {
     }
     return scope;
 }
+function createForwardingScope() {
+    const own = createTransitionScope();
+    const target = signal(null);
+    const eff = () => target() ?? own;
+    const owners = new Map();
+    return {
+        setTarget: (t) => target.set(t),
+        resources: computed(() => eff().resources()),
+        pending: computed(() => eff().pending()),
+        suspended: (type) => eff().suspended(type),
+        add: (ref, opt) => {
+            const t = untracked(target) ?? own;
+            owners.set(ref, t);
+            t.add(ref, opt);
+        },
+        remove: (ref) => {
+            const t = owners.get(ref) ?? untracked(target) ?? own;
+            t.remove(ref);
+            owners.delete(ref);
+        },
+        commit: (value) => linkedSignal({
+            source: () => ({ v: value(), settled: !eff().pending() }),
+            computation: (curr, prev) => curr.settled || prev === undefined ? curr.v : prev.value,
+        }),
+        holding: computed(() => eff().holding()),
+        beginHold: () => (untracked(target) ?? own).beginHold(),
+        endHold: () => (untracked(target) ?? own).endHold(),
+        hold: (value) => linkedSignal({
+            source: () => ({ v: value(), held: eff().holding() }),
+            computation: (curr, prev) => prev !== undefined && curr.held ? prev.value : curr.v,
+        }),
+    };
+}
+/** Provide a forwarding transition scope at a boundary (used by the transition outlet). */
+function provideForwardingTransitionScope() {
+    return { provide: TRANSITION_SCOPE, useFactory: createForwardingScope };
+}
+/** Read the transition scope reachable from `injector`, or null if none is provided there. */
+function getTransitionScope(injector) {
+    return injector.get(TRANSITION_SCOPE, null);
+}
 /**
  * Returns a register function bound to the nearest transition scope: it adds a resource
  * to the scope and removes it when the caller's injection context is destroyed. Pass any
@@ -604,6 +648,7 @@ function registerResource(res, opt) {
 function injectStartTransition() {
     const scope = injectTransitionScope();
     const injector = inject(Injector);
+    const onServer = isPlatformServer(inject(PLATFORM_ID, { optional: true }) ?? 'browser');
     return (fn) => {
         untracked(fn);
         let sawPending = false;
@@ -618,6 +663,13 @@ function injectStartTransition() {
                     resolve();
                 }
             }, { injector });
+            if (onServer) {
+                if (!untracked(scope.pending)) {
+                    watcher.destroy();
+                    resolve();
+                }
+                return;
+            }
             // no-async fallback: once the reactive system has processed the writes (afterNextRender),
             // if nothing ever went in flight, the transition is already complete.
             afterNextRender(() => {
@@ -758,6 +810,7 @@ function runInTransaction(txn, fn) {
 function injectStartTransaction() {
     const scope = injectTransitionScope();
     const injector = inject(Injector);
+    const onServer = isPlatformServer(inject(PLATFORM_ID, { optional: true }) ?? 'browser');
     return (fn) => {
         const txn = createTransaction();
         // Hold BEFORE the writes, so the display freezes at pre-transaction values.
@@ -799,11 +852,17 @@ function injectStartTransaction() {
             if (sawPending && !p)
                 finish(false);
         }, { injector });
-        // no-async fallback: if nothing ever went in flight, settle once the writes are processed.
-        afterNextRender(() => {
-            if (!sawPending && !untracked(scope.pending))
+        if (onServer) {
+            if (!untracked(scope.pending))
                 finish(false);
-        }, { injector });
+        }
+        else {
+            // no-async fallback: if nothing ever went in flight, settle once the writes are processed.
+            afterNextRender(() => {
+                if (!sawPending && !untracked(scope.pending))
+                    finish(false);
+            }, { injector });
+        }
         return {
             pending: scope.pending,
             done,
@@ -4263,5 +4322,5 @@ function withHistory(sourceOrValue, opt) {
  * Generated bundle index. Do not edit.
  */
 
-export { MmActivity, SuspenseBoundary, SuspenseBoundaryBase, UnscopedSuspenseBoundary, activeTransaction, batteryStatus, chunked, clipboard, combineWith, createTransaction, createTransitionScope, debounce, debounced, derived, distinct, elementSize, elementVisibility, filter, filterWith, focusWithin, forkStore, geolocation, 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, pooled, pooledArray, pooledMap, pooledSet, prefersDarkMode, prefersReducedMotion, 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, SuspenseBoundary, SuspenseBoundaryBase, UnscopedSuspenseBoundary, activeTransaction, batteryStatus, chunked, clipboard, combineWith, createForwardingScope, createTransaction, createTransitionScope, debounce, debounced, derived, distinct, elementSize, elementVisibility, 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, pooled, pooledArray, pooledMap, pooledSet, prefersDarkMode, prefersReducedMotion, provideForwardingTransitionScope, 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