@mmstack/primitives 22.1.2 → 22.2.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, afterNextRender, Component, isWritableSignal as isWritableSignal$2, isSignal, ElementRef, Injectable } from '@angular/core';
+import { isDevMode, inject, Injector, untracked, effect, DestroyRef, linkedSignal, InjectionToken, TemplateRef, ViewContainerRef, PLATFORM_ID, input, computed, Directive, signal, runInInjectionContext, afterNextRender, Component, isWritableSignal as isWritableSignal$2, 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();
  *     }
@@ -246,6 +246,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({ ...(ngDevMode ? { debugName: "visible" } : /* istanbul ignore next */ {}), alias: 'mmActivity' });
     /** Paused == not visible — handed to the kept subtree as PAUSED_CONTEXT. */
@@ -269,6 +270,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
@@ -280,10 +283,10 @@ class MmActivity {
         else
             this.view.detach();
     }
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.0", ngImport: i0, type: MmActivity, deps: [], target: i0.ɵɵFactoryTarget.Directive });
-    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "22.0.0", type: MmActivity, isStandalone: true, selector: "[mmActivity]", inputs: { visible: { classPropertyName: "visible", publicName: "mmActivity", isSignal: true, isRequired: true, transformFunction: null } }, ngImport: i0 });
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: MmActivity, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "22.0.2", type: MmActivity, isStandalone: true, selector: "[mmActivity]", inputs: { visible: { classPropertyName: "visible", publicName: "mmActivity", isSignal: true, isRequired: true, transformFunction: null } }, ngImport: i0 });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.0", ngImport: i0, type: MmActivity, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: MmActivity, decorators: [{
             type: Directive,
             args: [{
                     selector: '[mmActivity]',
@@ -565,6 +568,48 @@ function injectTransitionScope() {
     }
     return scope;
 }
+function createForwardingScope() {
+    const own = createTransitionScope();
+    const target = signal(null, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "target" }] : /* istanbul ignore next */ []));
+    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
@@ -602,6 +647,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;
@@ -616,6 +662,13 @@ function injectStartTransition() {
                     resolve();
                 }
             }, { ...(ngDevMode ? { debugName: "watcher" } : /* istanbul ignore next */ {}), 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(() => {
@@ -652,10 +705,10 @@ class SuspenseBoundaryBase {
     pending = this.scope.pending;
     suspended = computed(() => this.scope.suspended(this.type()), /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "suspended" }] : /* istanbul ignore next */ []));
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.0", ngImport: i0, type: SuspenseBoundaryBase, deps: [], target: i0.ɵɵFactoryTarget.Directive });
-    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "22.0.0", type: SuspenseBoundaryBase, isStandalone: true, inputs: { type: { classPropertyName: "type", publicName: "type", isSignal: true, isRequired: false, transformFunction: null } }, ngImport: i0 });
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: SuspenseBoundaryBase, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "22.0.2", type: SuspenseBoundaryBase, isStandalone: true, inputs: { type: { classPropertyName: "type", publicName: "type", isSignal: true, isRequired: false, transformFunction: null } }, ngImport: i0 });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.0", ngImport: i0, type: SuspenseBoundaryBase, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: SuspenseBoundaryBase, decorators: [{
             type: Directive
         }], propDecorators: { type: [{ type: i0.Input, args: [{ isSignal: true, alias: "type", required: false }] }] } });
 const SUSPENSE_TEMPLATE = `
@@ -683,10 +736,10 @@ const SUSPENSE_HOST = {
  * `provideTransitionScope()`. The common case.
  */
 class SuspenseBoundary extends SuspenseBoundaryBase {
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.0", ngImport: i0, type: SuspenseBoundary, deps: null, target: i0.ɵɵFactoryTarget.Component });
-    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "22.0.0", type: SuspenseBoundary, isStandalone: true, selector: "mm-suspense", host: { properties: { "attr.aria-busy": "pending() ? true : null" } }, providers: [provideTransitionScope()], usesInheritance: true, ngImport: i0, template: "\n  @if (suspended()) {\n    <ng-content select=\"[placeholder]\"><span>Loading\u2026</span></ng-content>\n  } @else {\n    @if (pending()) {\n      <ng-content select=\"[busy]\" />\n    }\n    <ng-content />\n  }\n", isInline: true, styles: [":host{display:contents}\n"] });
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: SuspenseBoundary, deps: null, target: i0.ɵɵFactoryTarget.Component });
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "22.0.2", type: SuspenseBoundary, isStandalone: true, selector: "mm-suspense", host: { properties: { "attr.aria-busy": "pending() ? true : null" } }, providers: [provideTransitionScope()], usesInheritance: true, ngImport: i0, template: "\n  @if (suspended()) {\n    <ng-content select=\"[placeholder]\"><span>Loading\u2026</span></ng-content>\n  } @else {\n    @if (pending()) {\n      <ng-content select=\"[busy]\" />\n    }\n    <ng-content />\n  }\n", isInline: true, styles: [":host{display:contents}\n"] });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.0", ngImport: i0, type: SuspenseBoundary, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: SuspenseBoundary, decorators: [{
             type: Component,
             args: [{ selector: 'mm-suspense', template: SUSPENSE_TEMPLATE, host: SUSPENSE_HOST, providers: [provideTransitionScope()], styles: [":host{display:contents}\n"] }]
         }] });
@@ -698,10 +751,10 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.0", ngImpor
  * ancestor.
  */
 class UnscopedSuspenseBoundary extends SuspenseBoundaryBase {
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.0", ngImport: i0, type: UnscopedSuspenseBoundary, deps: null, target: i0.ɵɵFactoryTarget.Component });
-    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "22.0.0", type: UnscopedSuspenseBoundary, isStandalone: true, selector: "mm-unscoped-suspense", host: { properties: { "attr.aria-busy": "pending() ? true : null" } }, usesInheritance: true, ngImport: i0, template: "\n  @if (suspended()) {\n    <ng-content select=\"[placeholder]\"><span>Loading\u2026</span></ng-content>\n  } @else {\n    @if (pending()) {\n      <ng-content select=\"[busy]\" />\n    }\n    <ng-content />\n  }\n", isInline: true, styles: [":host{display:contents}\n"] });
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: UnscopedSuspenseBoundary, deps: null, target: i0.ɵɵFactoryTarget.Component });
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "22.0.2", type: UnscopedSuspenseBoundary, isStandalone: true, selector: "mm-unscoped-suspense", host: { properties: { "attr.aria-busy": "pending() ? true : null" } }, usesInheritance: true, ngImport: i0, template: "\n  @if (suspended()) {\n    <ng-content select=\"[placeholder]\"><span>Loading\u2026</span></ng-content>\n  } @else {\n    @if (pending()) {\n      <ng-content select=\"[busy]\" />\n    }\n    <ng-content />\n  }\n", isInline: true, styles: [":host{display:contents}\n"] });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.0", ngImport: i0, type: UnscopedSuspenseBoundary, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: UnscopedSuspenseBoundary, decorators: [{
             type: Component,
             args: [{ selector: 'mm-unscoped-suspense', template: SUSPENSE_TEMPLATE, host: SUSPENSE_HOST, styles: [":host{display:contents}\n"] }]
         }] });
@@ -758,6 +811,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 +853,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,
@@ -3970,10 +4030,10 @@ class MessageBus {
         this.channel.close();
         this.listeners.clear();
     }
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.0", ngImport: i0, type: MessageBus, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
-    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "22.0.0", ngImport: i0, type: MessageBus, providedIn: 'root' });
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: MessageBus, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: MessageBus, providedIn: 'root' });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.0", ngImport: i0, type: MessageBus, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: MessageBus, decorators: [{
             type: Injectable,
             args: [{
                     providedIn: 'root',
@@ -4278,5 +4338,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