@mmstack/primitives 20.6.2 → 20.7.0

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

@@ -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();
  *     }
@@ -573,6 +573,47 @@ function injectTransitionScope() {
     }
     return scope;
 }
+function createForwardingScope() {
+    const own = createTransitionScope();
+    const target = signal(null, ...(ngDevMode ? [{ debugName: "target" }] : []));
+    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
@@ -4278,5 +4319,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