@mmstack/primitives 21.3.0 → 21.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmstack/primitives",
-  "version": "21.3.0",
+  "version": "21.4.1",
   "keywords": [
     "angular",
     "signals",

package/types/mmstack-primitives.d.ts

@@ -189,8 +189,9 @@ declare function providePaused(source: Signal<boolean>): Provider;
 declare function holdUntilReady<T>(target: Signal<T>, ready: () => boolean): Signal<T>;
 
 /**
- * Handle for an in-progress transition: a `pending` signal (true while the transition's
- * resources are in flight) and a `done` promise that resolves once they all settle.
+ * Handle for an in-progress transition: a `pending` signal (true while the transition's OWN
+ * resources are in flight — loads already in flight when it started are not attributed) and a
+ * `done` promise that resolves once they all settle.
  */
 type TransitionRef = {
     readonly pending: Signal<boolean>;
@@ -292,6 +293,15 @@ declare function createForwardingScope(): ForwardingTransitionScope;
 declare function provideForwardingTransitionScope(): Provider;
 /** Read the transition scope reachable from `injector`, or null if none is provided there. */
 declare function getTransitionScope(injector: Injector): TransitionScope | null;
+/**
+ * @internal Transaction-attributed pending for `startTransition`/`startTransaction`: like
+ * `scope.pending`, but loads already in flight when the tracker is created are NOT attributed —
+ * a pre-existing background load can neither settle the transaction early nor block its settle
+ * forever. A pre-existing flight is excluded only until it first settles; a later re-trigger of
+ * the same resource (e.g. the transaction's write changed its request) counts as the
+ * transaction's own work.
+ */
+declare function createAttributedPending(scope: TransitionScope): Signal<boolean>;
 /**
  * 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
@@ -342,8 +352,7 @@ declare class SuspenseBoundary extends SuspenseBoundaryBase {
 }
 /**
  * Unscoped suspense boundary — **reads the ambient scope** instead of providing one. For cases where
- * the resources to coordinate are registered *above* the boundary (e.g. an app-builder page whose
- * manifests/connectors register at a higher injector), so the boundary observes that outer scope
+ * the resources to coordinate are registered *above* the boundary so the boundary observes that outer scope
  * rather than opening a fresh one. Pair with a `provideTransitionScope()` (or another boundary) in an
  * ancestor.
  */
@@ -368,7 +377,8 @@ type Transaction = {
 declare function createTransaction(): Transaction;
 /** The transaction in effect right now, or `null`. Stateful actions consult this to record undo. */
 declare function activeTransaction(): Transaction | null;
-/** Handle for an in-progress transaction (Tier 3): the transition `pending`/`done`, plus `abort`. */
+/** Handle for an in-progress transaction (Tier 3): the transaction's own `pending`/`done`
+ * (loads already in flight at start are not attributed to it), plus `abort`. */
 type TransactionRef = {
     readonly pending: Signal<boolean>;
     readonly done: Promise<void>;
@@ -393,6 +403,67 @@ type TransactionRef = {
  */
 declare function injectStartTransaction(): (fn: () => void) => TransactionRef;
 
+type MmTransitionContext<T> = {
+    readonly $implicit: T;
+    readonly mmTransition: T;
+};
+/**
+ * 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.
+ */
+declare class MmTransition<T> {
+    private readonly tpl;
+    private readonly vcr;
+    private readonly parent;
+    private readonly onServer;
+    /** The value whose changes are transitioned. Each view keeps the value it was created with. */
+    readonly value: i0.InputSignal<T>;
+    /** Skip holding entirely — every change swaps at once (the plain re-render behavior). */
+    readonly immediate: i0.InputSignal<boolean>;
+    /** Wrap the swap in the View Transitions API for an animated cross-fade (feature detected). */
+    readonly viewTransition: i0.InputSignal<boolean>;
+    private current;
+    private incoming;
+    /** Bumped on every re-target/teardown so a superseded (possibly deferred) swap can't commit. */
+    private swapEpoch;
+    private readonly holding;
+    /** True while an incoming view is mounted hidden, waiting to settle. */
+    readonly pending: Signal<boolean>;
+    static ngTemplateContextGuard<T>(dir: MmTransition<T>, ctx: unknown): ctx is MmTransitionContext<T>;
+    constructor();
+    private onValue;
+    private commitSwap;
+    /** The actual swap: destroy the old view, reveal the new one. Always instant. */
+    private finishSwap;
+    private dropIncoming;
+    private createView;
+    private setHidden;
+    static ɵfac: i0.ɵɵFactoryDeclaration<MmTransition<any>, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<MmTransition<any>, "[mmTransition]", ["mmTransition"], { "value": { "alias": "mmTransition"; "required": true; "isSignal": true; }; "immediate": { "alias": "mmTransitionImmediate"; "required": false; "isSignal": true; }; "viewTransition": { "alias": "mmTransitionViewTransition"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
 /**
  * Options for creating a debounced writable signal.
  * Extends Angular's `CreateSignalOptions` with a debounce time setting.
@@ -1945,6 +2016,13 @@ type PointerDragState = {
      * otherwise the listener's element. `null` when idle.
      */
     origin: HTMLElement | null;
+    /**
+     * Whether the LAST gesture ended by being aborted (`pointercancel` /
+     * `lostpointercapture` / Escape / `cancel()`) rather than a normal `pointerup`.
+     * Only meaningful on the idle transition — consumers ending a drag branch on it
+     * to distinguish "drop here" from "abort". Sticky until the next `pointerdown`.
+     */
+    cancelled: boolean;
 };
 type PointerDragOptions = SensorRunOptions & {
     /**
@@ -3249,5 +3327,5 @@ type CreateHistoryOptions<T> = Omit<CreateSignalOptions<T[]>, 'equal'> & {
  */
 declare function withHistory<T>(sourceOrValue: WritableSignal<T> | T, opt?: CreateHistoryOptions<T>): SignalWithHistory<T>;
 
-export { MmActivity, PAUSABLE_OPTIONS, SuspenseBoundary, SuspenseBoundaryBase, UnscopedSuspenseBoundary, activeTransaction, batteryStatus, chunked, clipboard, combineWith, 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 type { BatteryStatus, ClipboardSignal, Computation, CreateChunkedOptions, CreateDebouncedOptions, CreateHistoryOptions, CreatePooledOptions, CreateProvidedPooledOptions, CreateStoredOptions, CreateThrottledOptions, DebouncedSignal, DerivedSignal, ElementSize, ElementSizeOptions, ElementSizeSignal, ElementVisibilityOptions, ElementVisibilitySignal, ExtendStoreOptions, Fork, ForkStoreOptions, ForkStrategy, ForwardingTransitionScope, Frame, GeolocationOptions, GeolocationSignal, IdleOptions, IdleSignal, MousePositionOptions, MousePositionSignal, MutableSignal, MutableSignalStore, NetworkStatusSignal, Opaque, PausableOptions, PauseOption, PipeableSignal, PointerDragOptions, PointerDragSignal, PointerDragState, PointerModifiers, PointerPoint, ReconcileFn, RegisterOptions, ScreenOrientation, ScreenOrientationState, ScrollPosition, ScrollPositionOptions, ScrollPositionSignal, SensorRunOptions, SignalFromEventOptions, SignalStore, SignalWithHistory, StoreOptions, StoredSignal, SuspendType, ThrottledSignal, Transaction, TransactionRef, TransitionRef, TransitionScope, UntilOptions, Vivify, WindowSize, WindowSizeOptions, WindowSizeSignal, WithVivify, WritableSignalStore, toStoreOptions };
+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 };
+export type { BatteryStatus, ClipboardSignal, Computation, CreateChunkedOptions, CreateDebouncedOptions, CreateHistoryOptions, CreatePooledOptions, CreateProvidedPooledOptions, CreateStoredOptions, CreateThrottledOptions, DebouncedSignal, DerivedSignal, ElementSize, ElementSizeOptions, ElementSizeSignal, ElementVisibilityOptions, ElementVisibilitySignal, ExtendStoreOptions, Fork, ForkStoreOptions, ForkStrategy, ForwardingTransitionScope, Frame, GeolocationOptions, GeolocationSignal, IdleOptions, IdleSignal, MmTransitionContext, MousePositionOptions, MousePositionSignal, MutableSignal, MutableSignalStore, NetworkStatusSignal, Opaque, PausableOptions, PauseOption, PipeableSignal, PointerDragOptions, PointerDragSignal, PointerDragState, PointerModifiers, PointerPoint, ReconcileFn, RegisterOptions, ScreenOrientation, ScreenOrientationState, ScrollPosition, ScrollPositionOptions, ScrollPositionSignal, SensorRunOptions, SignalFromEventOptions, SignalStore, SignalWithHistory, StoreOptions, StoredSignal, SuspendType, ThrottledSignal, Transaction, TransactionRef, TransitionRef, TransitionScope, UntilOptions, Vivify, WindowSize, WindowSizeOptions, WindowSizeSignal, WithVivify, WritableSignalStore, toStoreOptions };