@mmstack/primitives 19.6.0 → 19.7.0

package/README.md

@@ -119,6 +119,10 @@ Top-level array support isn't exposed yet — use `indexArray` / `keyArray` for
 
 **Union leaves (perf opt-in).** `noUnionLeaves: true` promises no node ever flips between a leaf and a sub-store, so each node's leaf-ness is resolved once on first access and cached instead of staying reactive. Off by default — leave it off if a value can switch between a primitive and an object/array.
 
+**Unions are fully supported by default.** A node may flip between array ↔ record ↔ primitive ↔ `null` freely: routing (`keys`/iteration/prototype) follows the live kind, and a child signal you grabbed **before** a flip stays correct after it — reads resolve against the new shape (`undefined` through a `null` parent, no throw) and writes copy by the container's live shape, so writing through a pre-flip child never turns an array into a plain object.
+
+> Reserved keys: `set`, `update`, `mutate`, `inline`, `asReadonly` (and `extend`, until its removal next minor) resolve to the signal's own methods, so record keys with those names aren't reachable as child stores — read them off the value (`s().set`) instead.
+
 ### `extendStore` (scoped overlay)
 
 `extendStore(store, seed)` (on any store kind) creates a **scoped overlay** — a child store that **shares** the parent's signals for inherited keys (the same `WritableSignal`: writes go through to the parent and parent changes flow down) while keeping the seed and any new keys in a **local layer** that never propagates upward. No diffing, no syncing — local keys simply aren't wired to the parent.
@@ -461,6 +465,15 @@ const t = startTransaction(() => applyBulkEdit()); // live state updates; the di
 await t.done; // committed, display revealed in one frame
 ```
 
+Every exit settles: a throwing body rolls back, and if the calling context is **destroyed
+mid-flight** the hold is released (writes kept) and `done` resolves — a transaction can never
+leave a surviving ancestor scope frozen.
+
+Attribution is **per transaction**: a load already in flight when it starts is not adopted —
+it can neither commit the transaction early nor block its settle. (The same applies to
+`startTransition`.) A pre-existing flight re-triggered by the transaction's own writes counts
+once it restarts.
+
 ### `holdUntilReady`
 
 The **structural** counterpart to `keepPrevious`: where that holds a _value_ through a reload, this holds a _structure_ through a swap. Given a `target` signal and a `ready` predicate, it keeps yielding the previous value until `ready()` is true, then swaps to the current target. Mount the incoming structure off to the side so its resources can settle and flip `ready`, keep showing the held one meanwhile, and let the old one go once `ready` releases the swap. (`@mmstack/router-core`'s `<mm-transition-outlet>` is this pattern applied to routes.)
@@ -677,6 +690,11 @@ outer one on the same tree (e.g. a nested sortable). Reads are throttled
 (`throttle`, default 16ms); `drag.unthrottled()` exposes the un-throttled view
 for logic that needs the exact release position.
 
+The idle state carries the **end reason**: `cancelled` is `true` when the gesture
+was aborted (Escape, `pointercancel`, `.cancel()`) rather than released, and stays
+set until the next `pointerdown` — so a drag consumer can tell "drop here" from
+"abort" (`@mmstack/dnd` uses this to cancel instead of committing).
+
 ```typescript
 import { sensor } from '@mmstack/primitives';
 

package/fesm2022/mmstack-primitives.mjs

@@ -634,6 +634,38 @@ function provideForwardingTransitionScope() {
 function getTransitionScope(injector) {
     return injector.get(TRANSITION_SCOPE, 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.
+ */
+function createAttributedPending(scope) {
+    const isInFlight = (ref) => {
+        const s = untracked(ref.status);
+        return s === ResourceStatus.Loading || s === ResourceStatus.Reloading;
+    };
+    const preexisting = new Set(untracked(scope.resources).filter(isInFlight));
+    return computed(() => {
+        let pending = false;
+        for (const ref of scope.resources()) {
+            const s = ref.status();
+            const loading = s === ResourceStatus.Loading || s === ResourceStatus.Reloading;
+            if (preexisting.has(ref)) {
+                // deletes are monotonic, so this stays sound under re-computation
+                if (loading)
+                    continue;
+                preexisting.delete(ref);
+                continue;
+            }
+            if (loading)
+                pending = true;
+        }
+        return pending;
+    });
+}
 /**
  * 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
@@ -671,38 +703,43 @@ function registerResource(res, opt) {
 function injectStartTransition() {
     const scope = injectTransitionScope();
     const injector = inject(Injector);
+    const destroyRef = inject(DestroyRef);
     const onServer = isPlatformServer(inject(PLATFORM_ID, { optional: true }) ?? 'browser');
     return (fn) => {
+        // attributed: loads already in flight when the transition starts are not ours —
+        // they can neither settle this transition early nor block it forever
+        const pending = createAttributedPending(scope);
         untracked(fn);
         let sawPending = false;
         const done = new Promise((resolve) => {
+            const settle = () => {
+                releaseDestroy();
+                watcher.destroy();
+                resolve();
+            };
             const watcher = effect(() => {
-                const p = scope.pending();
+                const p = pending();
                 if (p)
                     sawPending = true;
                 // settle: requests went in flight and then drained
-                if (sawPending && !p) {
-                    watcher.destroy();
-                    resolve();
-                }
+                if (sawPending && !p)
+                    settle();
             }, { injector });
+            // a destroy mid-flight kills the watcher — resolve so awaiters never hang
+            const releaseDestroy = destroyRef.onDestroy(settle);
             if (onServer) {
-                if (!untracked(scope.pending)) {
-                    watcher.destroy();
-                    resolve();
-                }
+                if (!untracked(pending))
+                    settle();
                 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(() => {
-                if (!sawPending && !untracked(scope.pending)) {
-                    watcher.destroy();
-                    resolve();
-                }
+                if (!sawPending && !untracked(pending))
+                    settle();
             }, { injector });
         });
-        return { pending: scope.pending, done };
+        return { pending, done };
     };
 }
 
@@ -773,8 +810,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "19.2.19", ngImpo
         }] });
 /**
  * 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.
  */
@@ -839,9 +875,13 @@ function runInTransaction(txn, fn) {
 function injectStartTransaction() {
     const scope = injectTransitionScope();
     const injector = inject(Injector);
+    const destroyRef = inject(DestroyRef);
     const onServer = isPlatformServer(inject(PLATFORM_ID, { optional: true }) ?? 'browser');
     return (fn) => {
         const txn = createTransaction();
+        // attributed: loads already in flight when the transaction starts are not ours —
+        // they can neither commit this transaction early nor block its settle forever
+        const pending = createAttributedPending(scope);
         // Hold BEFORE the writes, so the display freezes at pre-transaction values.
         scope.beginHold();
         let finished = false;
@@ -858,6 +898,7 @@ function injectStartTransaction() {
             if (finished)
                 return;
             finished = true;
+            releaseDestroy();
             watcher?.destroy();
             if (restore)
                 txn.restore();
@@ -866,6 +907,10 @@ function injectStartTransaction() {
             scope.endHold();
             resolveDone();
         };
+        // The scope may outlive the calling context (a component transacting on an ancestor
+        // boundary): a destroy mid-flight kills the settle watcher, so without this the hold
+        // would leak and freeze the surviving scope forever. Keep the writes — they landed live.
+        const releaseDestroy = destroyRef.onDestroy(() => finish(false));
         try {
             runInTransaction(txn, fn);
         }
@@ -875,25 +920,25 @@ function injectStartTransaction() {
         }
         let sawPending = false;
         watcher = effect(() => {
-            const p = scope.pending();
+            const p = pending();
             if (p)
                 sawPending = true;
             if (sawPending && !p)
                 finish(false);
         }, { injector });
         if (onServer) {
-            if (!untracked(scope.pending))
+            if (!untracked(pending))
                 finish(false);
         }
         else {
             // no-async fallback: if nothing ever went in flight, settle once the writes are processed.
             afterNextRender(() => {
-                if (!sawPending && !untracked(scope.pending))
+                if (!sawPending && !untracked(pending))
                     finish(false);
             }, { injector });
         }
         return {
-            pending: scope.pending,
+            pending,
             done,
             abort: () => finish(true),
         };
@@ -2907,9 +2952,13 @@ const IDLE = {
     button: -1,
     pointerType: '',
     origin: null,
+    cancelled: false,
 };
+/** Terminal state of an aborted gesture — same idle shape, `cancelled: true`. */
+const CANCELLED = { ...IDLE, cancelled: true };
 function stateEqual(a, b) {
     return (a.active === b.active &&
+        a.cancelled === b.cancelled &&
         a.pointerId === b.pointerId &&
         a.current.x === b.current.x &&
         a.current.y === b.current.y &&
@@ -2987,7 +3036,7 @@ function createPointerDrag(opt) {
         ctrl: e.ctrlKey,
         meta: e.metaKey,
     });
-    const end = () => {
+    const end = (cancelled = false) => {
         gesture?.abort();
         gesture = null;
         activePointerId = null;
@@ -2995,8 +3044,8 @@ function createPointerDrag(opt) {
         activePointerType = '';
         activeOrigin = null;
         activated = false;
-        state.set(IDLE);
-        state.flush(); // terminal transition: reflect IDLE now, not on the trailing edge
+        state.set(cancelled ? CANCELLED : IDLE);
+        state.flush(); // terminal transition: reflect idle now, not on the trailing edge
     };
     const onMove = (e) => {
         if (e.pointerId !== activePointerId)
@@ -3016,6 +3065,7 @@ function createPointerDrag(opt) {
             button: activeButton, // pointermove button is -1; keep the down-button
             pointerType: activePointerType,
             origin: activeOrigin,
+            cancelled: false,
         });
     };
     const onUp = (e) => {
@@ -3024,11 +3074,11 @@ function createPointerDrag(opt) {
     };
     const onCancel = (e) => {
         if (e.pointerId === activePointerId)
-            end();
+            end(true);
     };
     const onKey = (e) => {
         if (e.key === 'Escape' && activePointerId !== null)
-            end();
+            end(true);
     };
     const onDown = (el) => (e) => {
         if (activePointerId !== null)
@@ -3073,6 +3123,7 @@ function createPointerDrag(opt) {
             button: e.button,
             pointerType: activePointerType,
             origin: activeOrigin,
+            cancelled: false,
         });
     };
     const attach = (el) => {
@@ -3082,7 +3133,7 @@ function createPointerDrag(opt) {
         });
         return () => {
             controller.abort();
-            end();
+            end(true); // teardown mid-gesture is an abort, not a drop
         };
     };
     if (isSignal(target)) {
@@ -3100,7 +3151,7 @@ function createPointerDrag(opt) {
     }
     const base = state.asReadonly();
     base.unthrottled = state.original;
-    base.cancel = end;
+    base.cancel = () => end(true);
     return base;
 }
 
@@ -3693,30 +3744,35 @@ function getCachedChild(target, prop, build, cache, cleanupRegistry) {
     cleanupRegistry.register(proxy, { target, prop }, ref);
     return proxy;
 }
+/**
+ * @internal Whether a mutable parent's child value must always re-notify: in-place mutation
+ * keeps an object child's reference stable, so `Object.is` would swallow the change. Decided
+ * per-VALUE (not snapshotted at build) so a union child that becomes an object later still
+ * propagates parent-level mutations.
+ */
+function mutableChildEqual(a, b) {
+    if (typeof a === 'object' && a !== null)
+        return false;
+    return Object.is(a, b);
+}
 /**
  * @internal Builds the derived child signal for `prop` and wraps it as an array/object substore.
- * A record parent reads the key directly; any other container goes through the fallback `from`/
- * `onChange` path. Shared verbatim by the array and object proxies — the only place a child node
- * is constructed.
+ * Both the read (`v?.[prop]`) and the write (`createFallbackOnChange` copies by the container's
+ * LIVE shape) are shape-adaptive, so a child cached before an array↔record↔null union flip stays
+ * correct after it. The only place a child node is constructed — shared by every container kind.
  */
 function buildChildNode(target, prop, isMutableSource, options) {
     const value = untracked(target);
-    const valueIsRecord = isRecord(value);
-    const valueIsArray = Array.isArray(value);
     const nodeVivify = resolveVivify(value, options.vivify);
     const vivifyFn = createVivify(nodeVivify);
-    const equalFn = (valueIsRecord || valueIsArray) &&
-        isMutableSource &&
-        typeof value[prop] === 'object'
-        ? () => false
+    const equalFn = isMutableSource && (isRecord(value) || Array.isArray(value))
+        ? mutableChildEqual
         : undefined;
-    const computation = valueIsRecord
-        ? derived(target, prop, { equal: equalFn, vivify: nodeVivify })
-        : derived(target, {
-            from: (v) => v?.[prop],
-            onChange: createFallbackOnChange(target, prop, vivifyFn, isMutableSource),
-            equal: equalFn,
-        });
+    const computation = derived(target, {
+        from: (v) => v?.[prop],
+        onChange: createFallbackOnChange(target, prop, vivifyFn, isMutableSource),
+        equal: equalFn,
+    });
     const childSample = untracked(computation);
     const childVivify = resolveVivify(childSample, options.vivify);
     const proxy = toStore(computation, options);
@@ -4605,5 +4661,5 @@ function withHistory(sourceOrValue, opt) {
  * Generated bundle index. Do not edit.
  */
 
-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 { 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 };
 //# sourceMappingURL=mmstack-primitives.mjs.map