@mmstack/primitives 20.4.7 → 20.5.0

package/fesm2022/mmstack-primitives.mjs

@@ -1,8 +1,218 @@
 import * as i0 from '@angular/core';
-import { untracked, signal, inject, DestroyRef, computed, PLATFORM_ID, isSignal, effect, ElementRef, linkedSignal, isDevMode, Injector, Injectable, runInInjectionContext } from '@angular/core';
+import { isDevMode, inject, Injector, untracked, effect, DestroyRef, linkedSignal, computed, signal, isSignal, ElementRef, PLATFORM_ID, Injectable, runInInjectionContext } from '@angular/core';
 import { isPlatformServer } from '@angular/common';
 import { SIGNAL } from '@angular/core/primitives/signals';
 
+const frameStack = [];
+function currentFrame() {
+    return frameStack.at(-1) ?? null;
+}
+function clearFrame(frame, userCleanups) {
+    frame.parent = null;
+    for (const fn of userCleanups) {
+        try {
+            fn();
+        }
+        catch (e) {
+            if (isDevMode())
+                console.error('Error destroying nested effect:', e);
+        }
+    }
+    userCleanups.length = 0;
+    for (const child of frame.children) {
+        try {
+            child.destroy();
+        }
+        catch (e) {
+            if (isDevMode())
+                console.error('Error destroying nested effect:', e);
+        }
+    }
+    frame.children.clear();
+}
+function pushFrame(frame) {
+    return frameStack.push(frame);
+}
+function popFrame() {
+    return frameStack.pop();
+}
+
+/**
+ * Creates an effect that can be nested, similar to SolidJS's `createEffect`.
+ *
+ * This primitive enables true hierarchical reactivity. A `nestedEffect` created
+ * within another `nestedEffect` is automatically destroyed and recreated when
+ * the parent re-runs.
+ *
+ * It automatically handles injector propagation and lifetime management, allowing
+ * you to create fine-grained, conditional side-effects that only track
+ * dependencies when they are "live".
+ *
+ * @param effectFn The side-effect function, which receives a cleanup register function.
+ * @param options (Optional) Angular's `CreateEffectOptions`.
+ * @returns An `EffectRef` for the created effect.
+ *
+ * @example
+ * ```ts
+ * // Assume `coldGuard` changes rarely, but `hotSignal` changes often.
+ * const coldGuard = signal(false);
+ * const hotSignal = signal(0);
+ *
+ * nestedEffect(() => {
+ * // This outer effect only tracks `coldGuard`.
+ * if (coldGuard()) {
+ *
+ * // This inner effect is CREATED when coldGuard is true
+ * // and DESTROYED when it becomes false.
+ * nestedEffect(() => {
+ * // It only tracks `hotSignal` while it exists.
+ * console.log('Hot signal is:', hotSignal());
+ * });
+ * }
+ * // If `coldGuard` is false, this outer effect does not track `hotSignal`.
+ * });
+ * ```
+ * @example
+ * ```ts
+ * const users = signal([
+ *   { id: 1, name: 'Alice' },
+ *   { id: 2, name: 'Bob' }
+ * ]);
+ *
+ * // The fine-grained mapped list
+ * const mappedUsers = mapArray(
+ *   users,
+ *   (userSignal, index) => {
+ *     // 1. Create a fine-grained SIDE EFFECT for *this item*
+ *     // This effect's lifetime is now tied to this specific item. created once on init of this index.
+ *     const effectRef = nestedEffect(() => {
+ *       // This only runs if *this* userSignal changes,
+ *       // not if the whole list changes.
+ *       console.log(`User ${index} updated:`, userSignal().name);
+ *     });
+ *
+ *     // 2. Return the data AND the cleanup logic
+ *     return {
+ *       // The mapped data
+ *       label: computed(() => `User: ${userSignal().name}`),
+ *
+ *       // The cleanup function
+ *       destroyEffect: () => effectRef.destroy()
+ *     };
+ *   },
+ *   {
+ *     // 3. Tell mapArray 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();
+ *     }
+ *   }
+ * );
+ * ```
+ */
+function nestedEffect(effectFn, options) {
+    const bindToFrame = options?.bindToFrame ?? ((parent) => parent);
+    const parent = bindToFrame(currentFrame());
+    const injector = options?.injector ?? parent?.injector ?? inject(Injector);
+    let isDestroyed = false;
+    const srcRef = untracked(() => {
+        return effect((cleanup) => {
+            if (isDestroyed)
+                return;
+            const frame = {
+                injector,
+                parent,
+                children: new Set(),
+            };
+            const userCleanups = [];
+            pushFrame(frame);
+            try {
+                effectFn((fn) => userCleanups.push(fn));
+            }
+            finally {
+                popFrame();
+            }
+            return cleanup(() => clearFrame(frame, userCleanups));
+        }, {
+            ...options,
+            injector,
+            manualCleanup: options?.manualCleanup ?? !!parent,
+        });
+    });
+    const ref = {
+        destroy: () => {
+            if (isDestroyed)
+                return;
+            isDestroyed = true;
+            parent?.children.delete(ref);
+            srcRef.destroy();
+        },
+    };
+    parent?.children.add(ref);
+    injector.get(DestroyRef).onDestroy(() => ref.destroy());
+    return ref;
+}
+
+/**
+ * Creates a new `Signal` that processes an array of items in time-sliced chunks. This is useful for handling large lists without blocking the main thread.
+ *
+ * The returned signal will initially contain the first `chunkSize` items from the source array. It will then schedule updates to include additional chunks of items based on the specified `duration`.
+ *
+ * @template T The type of items in the array.
+ * @param source A `Signal` or a function that returns an array of items to be processed in chunks.
+ * @param options Configuration options for chunk size, delay duration, equality function, and injector.
+ * @returns A `Signal` that emits the current chunk of items being processed.
+ *
+ * @example
+ * const largeList = signal(Array.from({ length: 1000 }, (_, i) => i));
+ * const chunkedList = chunked(largeList, { chunkSize: 100, duration: 100 });
+ */
+function chunked(source, options) {
+    const { chunkSize = 50, delay = 'frame', equal, injector } = options || {};
+    let delayFn;
+    if (delay === 'frame') {
+        delayFn = (callback) => {
+            const num = requestAnimationFrame(callback);
+            return () => cancelAnimationFrame(num);
+        };
+    }
+    else if (delay === 'microtask') {
+        delayFn = (cb) => {
+            let isCancelled = false;
+            queueMicrotask(() => {
+                if (isCancelled)
+                    return;
+                cb();
+            });
+            return () => {
+                isCancelled = true;
+            };
+        };
+    }
+    else {
+        delayFn = (cb) => {
+            const num = setTimeout(cb, delay);
+            return () => clearTimeout(num);
+        };
+    }
+    const internal = linkedSignal(...(ngDevMode ? [{ debugName: "internal", source,
+            computation: (items) => items.slice(0, chunkSize),
+            equal }] : [{
+            source,
+            computation: (items) => items.slice(0, chunkSize),
+            equal,
+        }]));
+    nestedEffect((cleanup) => {
+        const fullList = source();
+        const current = internal();
+        if (current.length >= fullList.length)
+            return;
+        return cleanup(delayFn(() => untracked(() => internal.set(fullList.slice(0, current.length + chunkSize)))));
+    }, {
+        injector: injector,
+    });
+    return internal.asReadonly();
+}
+
 /**
  * Converts a read-only `Signal` into a `WritableSignal` by providing custom `set` and, optionally, `update` functions.
  * This can be useful for creating controlled write access to a signal that is otherwise read-only.
@@ -31,9 +241,9 @@ import { SIGNAL } from '@angular/core/primitives/signals';
  *
  * writableSignal.set(5); // sets value of originalValue.a to 5 & triggers all signals
  */
-function toWritable(signal, set, update) {
-    const internal = signal;
-    internal.asReadonly = () => signal;
+function toWritable(source, set, update, opt) {
+    const internal = (opt?.pure !== false ? computed(source) : source);
+    internal.asReadonly = () => source;
     internal.set = set;
     internal.update = update ?? ((updater) => set(updater(untracked(internal))));
     return internal;
@@ -115,19 +325,19 @@ function debounce(source, opt) {
     catch {
         // not in injection context & no destroyRef provided opting out of cleanup
     }
-    const triggerFn = (afterClean) => {
+    const triggerFn = (next) => {
         if (timeout)
             clearTimeout(timeout);
-        afterClean();
+        source.set(next);
         timeout = setTimeout(() => {
             trigger.update((c) => !c);
         }, ms);
     };
     const set = (value) => {
-        triggerFn(() => source.set(value));
+        triggerFn(value);
     };
     const update = (fn) => {
-        triggerFn(() => source.update(fn));
+        triggerFn(fn(untracked(source)));
     };
     const writable = toWritable(computed(() => {
         trigger();
@@ -218,7 +428,7 @@ function derived(source, optOrKey, opt) {
                 : (next) => {
                     source.update((cur) => ({ ...cur, [optOrKey]: next }));
                 };
-    const rest = typeof optOrKey === 'object' ? optOrKey : opt;
+    const rest = typeof optOrKey === 'object' ? { ...optOrKey, ...opt } : opt;
     const baseEqual = rest?.equal ?? Object.is;
     let trigger = false;
     const equal = isMutable(source)
@@ -228,7 +438,7 @@ function derived(source, optOrKey, opt) {
             return baseEqual(a, b);
         }
         : baseEqual;
-    const sig = toWritable(computed(() => from(source()), { ...rest, equal }), (newVal) => onChange(newVal));
+    const sig = toWritable(computed(() => from(source()), { ...rest, equal }), (newVal) => onChange(newVal), undefined, { pure: false });
     sig.from = from;
     if (isMutable(source)) {
         sig.mutate = (updater) => {
@@ -289,116 +499,8 @@ function isDerivation(sig) {
     return 'from' in sig;
 }
 
-function observerSupported() {
-    return typeof IntersectionObserver !== 'undefined';
-}
-/**
- * Creates a read-only signal that tracks the intersection status of a target DOM element
- * with the viewport or a specified root element, using the `IntersectionObserver` API.
- *
- * It can observe a static `ElementRef`/`Element` or a `Signal` that resolves to one,
- * allowing for dynamic targets.
- *
- * @param target The DOM element (or `ElementRef`, or a `Signal` resolving to one) to observe.
- * If the signal resolves to `null`, observation stops.
- * @param options Optional `IntersectionObserverInit` options (e.g., `root`, `rootMargin`, `threshold`)
- * and an optional `debugName`.
- * @returns A `Signal<IntersectionObserverEntry | undefined>`. It emits `undefined` initially,
- * on the server, or if the target is `null`. Otherwise, it emits the latest
- * `IntersectionObserverEntry`. Consumers can derive a boolean `isVisible` from
- * this entry's `isIntersecting` property.
- *
- * @example
- * ```ts
- * import { Component, effect, ElementRef, viewChild } from '@angular/core';
- * import { elementVisibility } from '@mmstack/primitives';
- * import { computed } from '@angular/core'; // For derived boolean
- *
- * @Component({
- * selector: 'app-lazy-image',
- * template: `
- * <div #imageContainer style="height: 200px; border: 1px dashed grey;">
- * @if (isVisible()) {
- * <img src="your-image-url.jpg" alt="Lazy loaded image" />
- * <p>Image is VISIBLE!</p>
- * } @else {
- * <p>Scroll down to see the image...</p>
- * }
- * </div>
- * `
- * })
- * export class LazyImageComponent {
- * readonly imageContainer = viewChild.required<ElementRef<HTMLDivElement>>('imageContainer');
- *
- * // Observe the element, get the full IntersectionObserverEntry
- * readonly intersectionEntry = elementVisibility(this.imageContainer);
- *
- * // Derive a simple boolean for visibility
- * readonly isVisible = computed(() => this.intersectionEntry()?.isIntersecting ?? false);
- *
- * constructor() {
- * effect(() => {
- * console.log('Intersection Entry:', this.intersectionEntry());
- * console.log('Is Visible:', this.isVisible());
- * });
- * }
- * }
- * ```
- */
-function elementVisibility(target = inject(ElementRef), opt) {
-    if (isPlatformServer(inject(PLATFORM_ID)) || !observerSupported()) {
-        const base = computed(() => undefined, {
-            debugName: opt?.debugName,
-        });
-        base.visible = computed(() => false, ...(ngDevMode ? [{ debugName: "visible" }] : []));
-        return base;
-    }
-    const state = signal(undefined, {
-        debugName: opt?.debugName,
-        equal: (a, b) => {
-            if (!a && !b)
-                return true;
-            if (!a || !b)
-                return false;
-            return (a.target === b.target &&
-                a.isIntersecting === b.isIntersecting &&
-                a.intersectionRatio === b.intersectionRatio &&
-                a.boundingClientRect.top === b.boundingClientRect.top &&
-                a.boundingClientRect.left === b.boundingClientRect.left &&
-                a.boundingClientRect.width === b.boundingClientRect.width &&
-                a.boundingClientRect.height === b.boundingClientRect.height);
-        },
-    });
-    const targetSignal = isSignal(target) ? target : computed(() => target);
-    effect((cleanup) => {
-        const el = targetSignal();
-        if (!el)
-            return state.set(undefined);
-        let observer = null;
-        observer = new IntersectionObserver(([entry]) => state.set(entry), opt);
-        observer.observe(el instanceof ElementRef ? el.nativeElement : el);
-        cleanup(() => {
-            observer?.disconnect();
-        });
-    });
-    const base = state.asReadonly();
-    base.visible = computed(() => {
-        const s = state();
-        if (!s)
-            return false;
-        return s.isIntersecting;
-    }, ...(ngDevMode ? [{ debugName: "visible" }] : []));
-    return base;
-}
-
-/**
- * @internal
- * Checks if a signal is a WritableSignal.
- * @param sig The signal to check.
- */
-function isWritable(sig) {
-    // We just need to check for the presence of a 'set' method.
-    return 'set' in sig;
+function isWritableSignal(value) {
+    return 'set' in value && typeof value.set === 'function';
 }
 /**
  * @internal
@@ -407,31 +509,45 @@ function isWritable(sig) {
  * @returns
  */
 function createSetter(source) {
-    if (!isWritable(source))
+    if (!isWritableSignal(source))
         return () => {
             // noop;
         };
     if (isMutable(source))
         return (value, index) => {
-            source.inline((arr) => {
+            source.mutate((arr) => {
                 arr[index] = value;
+                return arr;
             });
         };
     return (value, index) => {
         source.update((arr) => arr.map((v, i) => (i === index ? value : v)));
     };
 }
-function mapArray(source, map, options) {
+
+/**
+ * Helper to create the derived signal for a specific index.
+ * Extracts the cast logic to keep the main loop clean.
+ */
+function createItemSignal(source, index, setter, opt) {
+    return derived(
+    // We cast to any/Mutable to satisfy the overload signature,
+    // but 'derived' internally checks isMutable() for safety.
+    source, {
+        from: (src) => src[index],
+        onChange: (value) => setter(value, index),
+    }, opt);
+}
+function indexArray(source, map, opt = {}) {
     const data = isSignal(source) ? source : computed(source);
     const len = computed(() => data().length, ...(ngDevMode ? [{ debugName: "len" }] : []));
     const setter = createSetter(data);
-    const opt = { ...options };
-    const writableData = isWritable(data)
+    const writableData = isWritableSignal(data)
         ? data
         : toWritable(data, () => {
             // noop
         });
-    if (isWritable(data) && isMutable(data) && !opt.equal) {
+    if (isWritableSignal(data) && isMutable(data) && !opt.equal) {
         opt.equal = (a, b) => {
             if (a !== b)
                 return false; // actually check primitives and references
@@ -442,175 +558,201 @@ function mapArray(source, map, options) {
         source: () => len(),
         computation: (len, prev) => {
             if (!prev)
-                return Array.from({ length: len }, (_, i) => {
-                    const derivation = derived(writableData, // typcase to largest type
-                    {
-                        from: (src) => src[i],
-                        onChange: (value) => setter(value, i),
-                    }, opt);
-                    return map(derivation, i);
-                });
+                return Array.from({ length: len }, (_, i) => map(createItemSignal(writableData, i, setter, opt), i));
             if (len === prev.value.length)
                 return prev.value;
             if (len < prev.value.length) {
-                const slice = prev.value.slice(0, len);
                 if (opt.onDestroy) {
                     for (let i = len; i < prev.value.length; i++) {
-                        opt.onDestroy?.(prev.value[i]);
+                        opt.onDestroy(prev.value[i]);
                     }
                 }
-                return slice;
-            }
-            else {
-                const next = [...prev.value];
-                for (let i = prev.value.length; i < len; i++) {
-                    const derivation = derived(writableData, // typcase to largest type
-                    {
-                        from: (src) => src[i],
-                        onChange: (value) => setter(value, i),
-                    }, opt);
-                    next[i] = map(derivation, i);
-                }
-                return next;
+                return prev.value.slice(0, len);
             }
-        },
-        equal: (a, b) => a.length === b.length,
-    });
-}
-
-const frameStack = [];
-function current() {
-    return frameStack.at(-1) ?? null;
-}
-function clearFrame(frame, userCleanups) {
-    for (const child of frame.children) {
-        try {
-            child.destroy();
-        }
-        catch (e) {
-            if (isDevMode())
-                console.error('Error destroying nested effect:', e);
-        }
-    }
-    frame.children.clear();
-    for (const fn of userCleanups) {
-        try {
-            fn();
-        }
-        catch (e) {
-            if (isDevMode())
-                console.error('Error destroying nested effect:', e);
-        }
-    }
-    userCleanups.length = 0;
-}
-/**
- * Creates an effect that can be nested, similar to SolidJS's `createEffect`.
- *
- * This primitive enables true hierarchical reactivity. A `nestedEffect` created
- * within another `nestedEffect` is automatically destroyed and recreated when
- * the parent re-runs.
- *
- * It automatically handles injector propagation and lifetime management, allowing
- * you to create fine-grained, conditional side-effects that only track
- * dependencies when they are "live".
- *
- * @param effectFn The side-effect function, which receives a cleanup register function.
- * @param options (Optional) Angular's `CreateEffectOptions`.
- * @returns An `EffectRef` for the created effect.
- *
- * @example
- * ```ts
- * // Assume `coldGuard` changes rarely, but `hotSignal` changes often.
- * const coldGuard = signal(false);
- * const hotSignal = signal(0);
- *
- * nestedEffect(() => {
- * // This outer effect only tracks `coldGuard`.
- * if (coldGuard()) {
- *
- * // This inner effect is CREATED when coldGuard is true
- * // and DESTROYED when it becomes false.
- * nestedEffect(() => {
- * // It only tracks `hotSignal` while it exists.
- * console.log('Hot signal is:', hotSignal());
- * });
- * }
- * // If `coldGuard` is false, this outer effect does not track `hotSignal`.
- * });
- * ```
- * @example
- * ```ts
- * const users = signal([
-  { id: 1, name: 'Alice' },
-  { id: 2, name: 'Bob' }
-]);
-
-// The fine-grained mapped list
-const mappedUsers = mapArray(
-  users,
-  (userSignal, index) => {
-    // 1. Create a fine-grained SIDE EFFECT for *this item*
-    // This effect's lifetime is now tied to this specific item. created once on init of this index.
-    const effectRef = nestedEffect(() => {
-      // This only runs if *this* userSignal changes,
-      // not if the whole list changes.
-      console.log(`User ${index} updated:`, userSignal().name);
-    });
-
-    // 2. Return the data AND the cleanup logic
-    return {
-      // The mapped data
-      label: computed(() => `User: ${userSignal().name}`),
-      
-      // The cleanup function
-      destroyEffect: () => effectRef.destroy()
-    };
-  },
-  {
-    // 3. Tell mapArray 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();
-    }
-  }
-);
- * ```
- */
-function nestedEffect(effectFn, options) {
-    const parent = current();
-    const injector = options?.injector ?? parent?.injector ?? inject(Injector);
-    const srcRef = untracked(() => {
-        return effect((cleanup) => {
-            const frame = {
-                injector,
-                children: new Set(),
-            };
-            const userCleanups = [];
-            frameStack.push(frame);
-            try {
-                effectFn((fn) => {
-                    userCleanups.push(fn);
-                });
+            const next = prev.value.slice();
+            for (let i = prev.value.length; i < len; i++)
+                next[i] = map(createItemSignal(writableData, i, setter, opt), i);
+            return next;
+        },
+        equal: (a, b) => a.length === b.length,
+    });
+}
+/**
+ * @deprecated use indexArray instead
+ */
+const mapArray = indexArray;
+
+/**
+ * Reactively maps items from a source array to a new array by value (identity).
+ *
+ * similar to `Array.prototype.map`, but:
+ * 1. The `mapFn` receives the `index` as a Signal.
+ * 2. If an item in the `source` array moves to a new position, the *result* of the map function is reused and moved.
+ *    The `index` signal is updated to the new index.
+ * 3. The `mapFn` is only run for *new* items.
+ *
+ * This is useful for building efficient lists where DOM nodes or heavy instances should be reused
+ * when the list is reordered.
+ *
+ * @param source A `Signal<T[]>` or a function returning `T[]`.
+ * @param mapFn The mapping function. Receives the item and its index as a Signal.
+ * @param options Optional configuration:
+ *  - `onDestroy`: A callback invoked when a mapped item is removed from the array.
+ * @returns A `Signal<U[]>` containing the mapped array.
+ */
+function keyArray(source, mapFn, options = {}) {
+    const sourceSignal = isSignal(source) ? source : computed(source);
+    const items = [];
+    let mapped = [];
+    const indexes = [];
+    const getKey = options.key || ((v) => v);
+    const newIndices = new Map();
+    const temp = [];
+    const tempIndexes = [];
+    const newIndicesNext = [];
+    const newIndexesCache = new Array();
+    return computed(() => {
+        const newItems = sourceSignal() || [];
+        return untracked(() => {
+            let i;
+            let j;
+            const newLen = newItems.length;
+            const len = items.length;
+            const newMapped = new Array(newLen);
+            const newIndexes = newIndexesCache;
+            newIndexes.length = 0;
+            newIndexes.length = newLen;
+            let start;
+            let end;
+            let newEnd;
+            let item;
+            let key;
+            if (newLen === 0) {
+                if (len !== 0) {
+                    if (options.onDestroy) {
+                        for (let k = 0; k < len; k++)
+                            options.onDestroy(mapped[k]);
+                    }
+                    items.length = 0;
+                    mapped = [];
+                    indexes.length = 0;
+                }
+                return mapped;
             }
-            finally {
-                frameStack.pop();
+            if (len === 0) {
+                for (j = 0; j < newLen; j++) {
+                    item = newItems[j];
+                    items[j] = item;
+                    const indexSignal = signal(j, ...(ngDevMode ? [{ debugName: "indexSignal" }] : []));
+                    newIndexes[j] = indexSignal;
+                    newMapped[j] = mapFn(item, indexSignal);
+                }
             }
-            return cleanup(() => clearFrame(frame, userCleanups));
-        }, {
-            ...options,
-            injector,
-            manualCleanup: !!parent,
+            else {
+                newIndices.clear();
+                temp.length = 0;
+                tempIndexes.length = 0;
+                newIndicesNext.length = 0;
+                for (start = 0, end = Math.min(len, newLen); start < end && getKey(items[start]) === getKey(newItems[start]); start++) {
+                    newMapped[start] = mapped[start];
+                    newIndexes[start] = indexes[start];
+                }
+                for (end = len - 1, newEnd = newLen - 1; end >= start &&
+                    newEnd >= start &&
+                    getKey(items[end]) === getKey(newItems[newEnd]); end--, newEnd--) {
+                    temp[newEnd] = mapped[end];
+                    tempIndexes[newEnd] = indexes[end];
+                }
+                for (j = newEnd; j >= start; j--) {
+                    item = newItems[j];
+                    key = getKey(item);
+                    i = newIndices.get(key);
+                    newIndicesNext[j] = i === undefined ? -1 : i;
+                    newIndices.set(key, j);
+                }
+                for (i = start; i <= end; i++) {
+                    item = items[i];
+                    key = getKey(item);
+                    j = newIndices.get(key);
+                    if (j !== undefined && j !== -1) {
+                        temp[j] = mapped[i];
+                        tempIndexes[j] = indexes[i];
+                        j = newIndicesNext[j];
+                        newIndices.set(key, j);
+                    }
+                    else {
+                        if (options.onDestroy)
+                            options.onDestroy(mapped[i]);
+                    }
+                }
+                // 2) Set all new values
+                for (j = start; j < newLen; j++) {
+                    if (temp[j] !== undefined) {
+                        newMapped[j] = temp[j];
+                        newIndexes[j] = tempIndexes[j];
+                        newIndexes[j].set(j);
+                    }
+                    else {
+                        const indexSignal = signal(j, ...(ngDevMode ? [{ debugName: "indexSignal" }] : []));
+                        newIndexes[j] = indexSignal;
+                        newMapped[j] = mapFn(newItems[j], indexSignal);
+                    }
+                }
+                items.length = newLen;
+                for (let k = 0; k < newLen; k++)
+                    items[k] = newItems[k];
+            }
+            mapped = newMapped;
+            indexes.length = newLen;
+            for (let k = 0; k < newLen; k++)
+                indexes[k] = newIndexes[k];
+            return mapped;
         });
     });
-    const ref = {
-        ...srcRef,
-        destroy: () => {
-            parent?.children.delete(ref);
-            srcRef.destroy();
+}
+
+function pooledKeys(src) {
+    const aBuf = new Set();
+    const bBuf = new Set();
+    let active = aBuf;
+    let spare = bBuf;
+    return computed(() => {
+        const val = src();
+        spare.clear();
+        for (const k in val)
+            if (Object.prototype.hasOwnProperty.call(val, k))
+                spare.add(k);
+        if (active.size === spare.size && active.isSubsetOf(spare))
+            return active;
+        const temp = active;
+        active = spare;
+        spare = temp;
+        return active;
+    });
+}
+function mapObject(source, mapFn, options = {}) {
+    const src = isSignal(source) ? source : computed(source);
+    const writable = (isWritableSignal(src)
+        ? src
+        : toWritable(src, () => {
+            // noop
+        })); // maximal overload internally
+    return linkedSignal({
+        source: pooledKeys(src),
+        computation: (next, prev) => {
+            const nextObj = {};
+            for (const k of next)
+                nextObj[k] =
+                    prev && prev.source.has(k)
+                        ? prev.value[k]
+                        : mapFn(k, derived(writable, k));
+            if (options.onDestroy && prev && prev.source.size)
+                for (const k of prev.source)
+                    if (!next.has(k))
+                        options.onDestroy(prev.value[k]);
+            return nextObj;
         },
-    };
-    parent?.children.add(ref);
-    return ref;
+    }).asReadonly();
 }
 
 /** Project with optional equality. Pure & sync. */
@@ -698,6 +840,206 @@ function piped(initial, opt) {
     return pipeable(signal(initial, opt));
 }
 
+function observerSupported$1() {
+    return typeof ResizeObserver !== 'undefined';
+}
+/**
+ * Creates a read-only signal that tracks the size of a target DOM element.
+ *
+ * By default, it observes the `border-box` size to align with `getBoundingClientRect()`,
+ * which is used to provide a synchronous initial value if possible.
+ *
+ * @param target The DOM element (or `ElementRef`, or a `Signal` resolving to one) to observe.
+ * @param options Optional configuration including `box` (defaults to 'border-box') and `debugName`.
+ * @returns A `Signal<ElementSize | undefined>`.
+ *
+ * @example
+ * ```ts
+ * const size = elementSize(elementRef);
+ * effect(() => {
+ *   console.log('Size:', size()?.width, size()?.height);
+ * });
+ * ```
+ */
+function elementSize(target = inject(ElementRef), opt) {
+    const getElement = () => {
+        if (isSignal(target)) {
+            try {
+                const val = target();
+                return val instanceof ElementRef ? val.nativeElement : val;
+            }
+            catch {
+                return null;
+            }
+        }
+        return target instanceof ElementRef ? target.nativeElement : target;
+    };
+    const resolveInitialValue = () => {
+        if (!observerSupported$1())
+            return undefined;
+        const el = getElement();
+        if (el && el.getBoundingClientRect) {
+            const rect = el.getBoundingClientRect();
+            return { width: rect.width, height: rect.height };
+        }
+        return undefined;
+    };
+    if (isPlatformServer(inject(PLATFORM_ID))) {
+        return computed(() => untracked(resolveInitialValue), {
+            debugName: opt?.debugName,
+        });
+    }
+    const state = signal(untracked(resolveInitialValue), {
+        debugName: opt?.debugName,
+        equal: (a, b) => a?.width === b?.width && a?.height === b?.height,
+    });
+    const targetSignal = isSignal(target) ? target : computed(() => target);
+    effect((cleanup) => {
+        const el = targetSignal();
+        if (el) {
+            const nativeEl = el instanceof ElementRef ? el.nativeElement : el;
+            const rect = nativeEl.getBoundingClientRect();
+            untracked(() => state.set({ width: rect.width, height: rect.height }));
+        }
+        else {
+            untracked(() => state.set(undefined));
+            return;
+        }
+        if (!observerSupported$1())
+            return;
+        let observer = null;
+        observer = new ResizeObserver(([entry]) => {
+            let width = 0;
+            let height = 0;
+            const boxOption = opt?.box ?? 'border-box';
+            if (boxOption === 'border-box' && entry.borderBoxSize?.length > 0) {
+                const size = entry.borderBoxSize[0];
+                width = size.inlineSize;
+                height = size.blockSize;
+            }
+            else if (boxOption === 'content-box' &&
+                entry.contentBoxSize?.length > 0) {
+                width = entry.contentBoxSize[0].inlineSize;
+                height = entry.contentBoxSize[0].blockSize;
+            }
+            else {
+                width = entry.contentRect.width;
+                height = entry.contentRect.height;
+            }
+            state.set({ width, height });
+        });
+        observer.observe(el instanceof ElementRef ? el.nativeElement : el, {
+            box: opt?.box ?? 'border-box',
+        });
+        cleanup(() => {
+            observer?.disconnect();
+        });
+    });
+    return state.asReadonly();
+}
+
+function observerSupported() {
+    return typeof IntersectionObserver !== 'undefined';
+}
+/**
+ * Creates a read-only signal that tracks the intersection status of a target DOM element
+ * with the viewport or a specified root element, using the `IntersectionObserver` API.
+ *
+ * It can observe a static `ElementRef`/`Element` or a `Signal` that resolves to one,
+ * allowing for dynamic targets.
+ *
+ * @param target The DOM element (or `ElementRef`, or a `Signal` resolving to one) to observe.
+ * If the signal resolves to `null`, observation stops.
+ * @param options Optional `IntersectionObserverInit` options (e.g., `root`, `rootMargin`, `threshold`)
+ * and an optional `debugName`.
+ * @returns A `Signal<IntersectionObserverEntry | undefined>`. It emits `undefined` initially,
+ * on the server, or if the target is `null`. Otherwise, it emits the latest
+ * `IntersectionObserverEntry`. Consumers can derive a boolean `isVisible` from
+ * this entry's `isIntersecting` property.
+ *
+ * @example
+ * ```ts
+ * import { Component, effect, ElementRef, viewChild } from '@angular/core';
+ * import { elementVisibility } from '@mmstack/primitives';
+ * import { computed } from '@angular/core'; // For derived boolean
+ *
+ * @Component({
+ * selector: 'app-lazy-image',
+ * template: `
+ * <div #imageContainer style="height: 200px; border: 1px dashed grey;">
+ * @if (isVisible()) {
+ * <img src="your-image-url.jpg" alt="Lazy loaded image" />
+ * <p>Image is VISIBLE!</p>
+ * } @else {
+ * <p>Scroll down to see the image...</p>
+ * }
+ * </div>
+ * `
+ * })
+ * export class LazyImageComponent {
+ * readonly imageContainer = viewChild.required<ElementRef<HTMLDivElement>>('imageContainer');
+ *
+ * // Observe the element, get the full IntersectionObserverEntry
+ * readonly intersectionEntry = elementVisibility(this.imageContainer);
+ *
+ * // Derive a simple boolean for visibility
+ * readonly isVisible = computed(() => this.intersectionEntry()?.isIntersecting ?? false);
+ *
+ * constructor() {
+ * effect(() => {
+ * console.log('Intersection Entry:', this.intersectionEntry());
+ * console.log('Is Visible:', this.isVisible());
+ * });
+ * }
+ * }
+ * ```
+ */
+function elementVisibility(target = inject(ElementRef), opt) {
+    if (isPlatformServer(inject(PLATFORM_ID)) || !observerSupported()) {
+        const base = computed(() => undefined, {
+            debugName: opt?.debugName,
+        });
+        base.visible = computed(() => false, ...(ngDevMode ? [{ debugName: "visible" }] : []));
+        return base;
+    }
+    const state = signal(undefined, {
+        debugName: opt?.debugName,
+        equal: (a, b) => {
+            if (!a && !b)
+                return true;
+            if (!a || !b)
+                return false;
+            return (a.target === b.target &&
+                a.isIntersecting === b.isIntersecting &&
+                a.intersectionRatio === b.intersectionRatio &&
+                a.boundingClientRect.top === b.boundingClientRect.top &&
+                a.boundingClientRect.left === b.boundingClientRect.left &&
+                a.boundingClientRect.width === b.boundingClientRect.width &&
+                a.boundingClientRect.height === b.boundingClientRect.height);
+        },
+    });
+    const targetSignal = isSignal(target) ? target : computed(() => target);
+    effect((cleanup) => {
+        const el = targetSignal();
+        if (!el)
+            return state.set(undefined);
+        let observer = null;
+        observer = new IntersectionObserver(([entry]) => state.set(entry), opt);
+        observer.observe(el instanceof ElementRef ? el.nativeElement : el);
+        cleanup(() => {
+            observer?.disconnect();
+        });
+    });
+    const base = state.asReadonly();
+    base.visible = computed(() => {
+        const s = state();
+        if (!s)
+            return false;
+        return s.isIntersecting;
+    }, ...(ngDevMode ? [{ debugName: "visible" }] : []));
+    return base;
+}
+
 /**
  * Creates a read-only signal that reactively tracks whether a CSS media query
  * string currently matches.
@@ -869,8 +1211,7 @@ function throttle(source, opt) {
     catch {
         // not in injection context & no destroyRef provided opting out of cleanup
     }
-    const triggerFn = (updateSourceAction) => {
-        updateSourceAction();
+    const tick = () => {
         if (timeout)
             return;
         timeout = setTimeout(() => {
@@ -879,10 +1220,12 @@ function throttle(source, opt) {
         }, ms);
     };
     const set = (value) => {
-        triggerFn(() => source.set(value));
+        source.set(value);
+        tick();
     };
     const update = (fn) => {
-        triggerFn(() => source.update(fn));
+        source.update(fn);
+        tick();
     };
     const writable = toWritable(computed(() => {
         trigger();
@@ -1250,18 +1593,303 @@ function sensor(type, options) {
             return networkStatus(options?.debugName);
         case 'pageVisibility':
             return pageVisibility(options?.debugName);
+        case 'darkMode':
         case 'dark-mode':
             return prefersDarkMode(options?.debugName);
+        case 'reducedMotion':
         case 'reduced-motion':
             return prefersReducedMotion(options?.debugName);
+        case 'mediaQuery': {
+            const opt = options;
+            return mediaQuery(opt.query, opt.debugName);
+        }
         case 'windowSize':
             return windowSize(options);
         case 'scrollPosition':
             return scrollPosition(options);
+        case 'elementVisibility': {
+            const opt = options;
+            return elementVisibility(opt.target, opt);
+        }
+        case 'elementSize': {
+            const opt = options;
+            return elementSize(opt.target, opt);
+        }
         default:
             throw new Error(`Unknown sensor type: ${type}`);
     }
 }
+function sensors(track, opt) {
+    return track.reduce((result, key) => {
+        result[key] = sensor(key, opt?.[key]);
+        return result;
+    }, {});
+}
+
+const IS_STORE = Symbol('MMSTACK::IS_STORE');
+const PROXY_CACHE = new WeakMap();
+const SIGNAL_FN_PROP = new Set([
+    'set',
+    'update',
+    'mutate',
+    'inline',
+    'asReadonly',
+]);
+const PROXY_CLEANUP = new FinalizationRegistry(({ target, prop }) => {
+    const storeCache = PROXY_CACHE.get(target);
+    if (storeCache)
+        storeCache.delete(prop);
+});
+/**
+ * @internal
+ * Validates whether a value is a Signal Store.
+ */
+function isStore(value) {
+    return (typeof value === 'function' &&
+        value !== null &&
+        value[IS_STORE] === true);
+}
+function isIndexProp(prop) {
+    return typeof prop === 'string' && prop.trim() !== '' && !isNaN(+prop);
+}
+function isRecord(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+/**
+ * @internal
+ * Makes an array store
+ */
+function toArrayStore(source, injector) {
+    if (isStore(source))
+        return source;
+    const isMutableSource = isMutable(source);
+    const lengthSignal = computed(() => {
+        const v = source();
+        if (!Array.isArray(v))
+            return 0;
+        return v.length;
+    }, ...(ngDevMode ? [{ debugName: "lengthSignal" }] : []));
+    return new Proxy(source, {
+        has(_, prop) {
+            if (prop === 'length')
+                return true;
+            if (isIndexProp(prop)) {
+                const idx = +prop;
+                return idx >= 0 && idx < untracked(lengthSignal);
+            }
+            return Reflect.has(untracked(source), prop);
+        },
+        ownKeys() {
+            const v = untracked(source);
+            if (!Array.isArray(v))
+                return [];
+            const len = v.length;
+            const arr = new Array(len + 1);
+            for (let i = 0; i < len; i++) {
+                arr[i] = String(i);
+            }
+            arr[len] = 'length';
+            return arr;
+        },
+        getPrototypeOf() {
+            return Array.prototype;
+        },
+        getOwnPropertyDescriptor(_, prop) {
+            const v = untracked(source);
+            if (!Array.isArray(v))
+                return;
+            if (prop === 'length' ||
+                (typeof prop === 'string' && !isNaN(+prop) && +prop < v.length)) {
+                return {
+                    enumerable: true,
+                    configurable: true, // Required for proxies to dynamic targets
+                };
+            }
+            return;
+        },
+        get(target, prop, receiver) {
+            if (prop === IS_STORE)
+                return true;
+            if (prop === 'length')
+                return lengthSignal;
+            if (prop === Symbol.iterator) {
+                return function* () {
+                    for (let i = 0; i < untracked(lengthSignal); i++) {
+                        yield receiver[i];
+                    }
+                };
+            }
+            if (typeof prop === 'symbol' || SIGNAL_FN_PROP.has(prop))
+                return target[prop];
+            if (isIndexProp(prop)) {
+                const idx = +prop;
+                let storeCache = PROXY_CACHE.get(target);
+                if (!storeCache) {
+                    storeCache = new Map();
+                    PROXY_CACHE.set(target, storeCache);
+                }
+                const cachedRef = storeCache.get(idx);
+                if (cachedRef) {
+                    const cached = cachedRef.deref();
+                    if (cached)
+                        return cached;
+                    storeCache.delete(idx);
+                    PROXY_CLEANUP.unregister(cachedRef);
+                }
+                const value = untracked(target);
+                const valueIsArray = Array.isArray(value);
+                const valueIsRecord = isRecord(value);
+                const equalFn = (valueIsRecord || valueIsArray) &&
+                    isMutableSource &&
+                    typeof value[idx] === 'object'
+                    ? () => false
+                    : undefined;
+                const computation = valueIsRecord
+                    ? derived(target, idx, { equal: equalFn })
+                    : derived(target, {
+                        from: (v) => v?.[idx],
+                        onChange: (newValue) => target.update((v) => {
+                            if (v === null || v === undefined)
+                                return v;
+                            try {
+                                v[idx] = newValue;
+                            }
+                            catch (e) {
+                                if (isDevMode())
+                                    console.error(`[store] Failed to set property "${String(idx)}"`, e);
+                            }
+                            return v;
+                        }),
+                    });
+                const proxy = Array.isArray(untracked(computation))
+                    ? toArrayStore(computation, injector)
+                    : toStore(computation, injector);
+                const ref = new WeakRef(proxy);
+                storeCache.set(idx, ref);
+                PROXY_CLEANUP.register(proxy, { target, prop: idx }, ref);
+                return proxy;
+            }
+            return Reflect.get(target, prop, receiver);
+        },
+    });
+}
+/**
+ * Converts a Signal into a deep-observable Store.
+ * Accessing nested properties returns a derived Signal of that path.
+ * @example
+ * const state = store({ user: { name: 'John' } });
+ * const nameSignal = state.user.name; // WritableSignal<string>
+ */
+function toStore(source, injector) {
+    if (isStore(source))
+        return source;
+    if (!injector)
+        injector = inject(Injector);
+    const writableSource = isWritableSignal(source)
+        ? source
+        : toWritable(source, () => {
+            // noop
+        });
+    const isMutableSource = isMutable(writableSource);
+    const s = new Proxy(writableSource, {
+        has(_, prop) {
+            return Reflect.has(untracked(source), prop);
+        },
+        ownKeys() {
+            const v = untracked(source);
+            if (!isRecord(v))
+                return [];
+            return Reflect.ownKeys(v);
+        },
+        getPrototypeOf() {
+            return Object.getPrototypeOf(untracked(source));
+        },
+        getOwnPropertyDescriptor(_, prop) {
+            const value = untracked(source);
+            if (!isRecord(value) || !(prop in value))
+                return;
+            return {
+                enumerable: true,
+                configurable: true,
+            };
+        },
+        get(target, prop) {
+            if (prop === IS_STORE)
+                return true;
+            if (prop === 'asReadonlyStore')
+                return () => {
+                    if (!isWritableSignal(source))
+                        return s;
+                    return untracked(() => toStore(source.asReadonly(), injector));
+                };
+            if (typeof prop === 'symbol' || SIGNAL_FN_PROP.has(prop))
+                return target[prop];
+            let storeCache = PROXY_CACHE.get(target);
+            if (!storeCache) {
+                storeCache = new Map();
+                PROXY_CACHE.set(target, storeCache);
+            }
+            const cachedRef = storeCache.get(prop);
+            if (cachedRef) {
+                const cached = cachedRef.deref();
+                if (cached)
+                    return cached;
+                storeCache.delete(prop);
+                PROXY_CLEANUP.unregister(cachedRef);
+            }
+            const value = untracked(target);
+            const valueIsRecord = isRecord(value);
+            const valueIsArray = Array.isArray(value);
+            const equalFn = (valueIsRecord || valueIsArray) &&
+                isMutableSource &&
+                typeof value[prop] === 'object'
+                ? () => false
+                : undefined;
+            const computation = valueIsRecord
+                ? derived(target, prop, { equal: equalFn })
+                : derived(target, {
+                    from: (v) => v?.[prop],
+                    onChange: (newValue) => target.update((v) => {
+                        if (v === null || v === undefined)
+                            return v;
+                        try {
+                            v[prop] = newValue;
+                        }
+                        catch (e) {
+                            if (isDevMode())
+                                console.error(`[store] Failed to set property "${String(prop)}"`, e);
+                        }
+                        return v;
+                    }),
+                });
+            const proxy = Array.isArray(untracked(computation))
+                ? toArrayStore(computation, injector)
+                : toStore(computation, injector);
+            const ref = new WeakRef(proxy);
+            storeCache.set(prop, ref);
+            PROXY_CLEANUP.register(proxy, { target, prop }, ref);
+            return proxy;
+        },
+    });
+    return s;
+}
+/**
+ * Creates a WritableSignalStore from a value.
+ * @see {@link toStore}
+ */
+function store(value, opt) {
+    return toStore(signal(value, opt), opt?.injector);
+}
+/**
+ * Creates a MutableSignalStore from a value.
+ * @see {@link toStore}
+ */
+function mutableStore(value, opt) {
+    return toStore(mutable(value, opt), opt?.injector);
+}
 
 // Internal dummy store for server-side rendering
 const noopStore = {
@@ -1324,7 +1952,7 @@ const noopStore = {
  * }
  * ```
  */
-function stored(fallback, { key, store: providedStore, serialize = JSON.stringify, deserialize = JSON.parse, syncTabs = false, equal = Object.is, onKeyChange = 'load', cleanupOldKey = false, ...rest }) {
+function stored(fallback, { key, store: providedStore, serialize = JSON.stringify, deserialize = JSON.parse, syncTabs = false, equal = Object.is, onKeyChange = 'load', cleanupOldKey = false, validate = () => true, ...rest }) {
     const isServer = isPlatformServer(inject(PLATFORM_ID));
     const fallbackStore = isServer ? noopStore : localStorage;
     const store = providedStore ?? fallbackStore;
@@ -1338,7 +1966,10 @@ function stored(fallback, { key, store: providedStore, serialize = JSON.stringif
         if (found === null)
             return null;
         try {
-            return deserialize(found);
+            const deserialized = deserialize(found);
+            if (!validate(deserialized))
+                return null;
+            return deserialized;
         }
         catch (err) {
             if (isDevMode())
@@ -1457,10 +2088,10 @@ class MessageBus {
         this.channel.removeEventListener('message', listener);
         this.listeners.delete(id);
     }
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.1", ngImport: i0, type: MessageBus, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
-    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "20.3.1", ngImport: i0, type: MessageBus, providedIn: 'root' });
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.17", ngImport: i0, type: MessageBus, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "20.3.17", ngImport: i0, type: MessageBus, providedIn: 'root' });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.1", ngImport: i0, type: MessageBus, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.17", ngImport: i0, type: MessageBus, decorators: [{
             type: Injectable,
             args: [{
                     providedIn: 'root',
@@ -1743,5 +2374,5 @@ function withHistory(source, opt) {
  * Generated bundle index. Do not edit.
  */
 
-export { combineWith, debounce, debounced, derived, distinct, elementVisibility, filter, isDerivation, isMutable, map, mapArray, mediaQuery, mousePosition, mutable, nestedEffect, networkStatus, pageVisibility, pipeable, piped, prefersDarkMode, prefersReducedMotion, scrollPosition, select, sensor, stored, tabSync, tap, throttle, throttled, toFakeDerivation, toFakeSignalDerivation, toWritable, until, windowSize, withHistory };
+export { chunked, combineWith, debounce, debounced, derived, distinct, elementSize, elementVisibility, filter, indexArray, isDerivation, isMutable, isStore, keyArray, map, mapArray, mapObject, mediaQuery, mousePosition, mutable, mutableStore, nestedEffect, networkStatus, pageVisibility, pipeable, piped, prefersDarkMode, prefersReducedMotion, scrollPosition, select, sensor, sensors, store, stored, tabSync, tap, throttle, throttled, toFakeDerivation, toFakeSignalDerivation, toStore, toWritable, until, windowSize, withHistory };
 //# sourceMappingURL=mmstack-primitives.mjs.map