@mmstack/primitives 21.0.0 → 21.0.1

package/fesm2022/mmstack-primitives.mjs

@@ -1,5 +1,5 @@
 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 { computed, untracked, signal, inject, DestroyRef, isWritableSignal as isWritableSignal$1, isSignal, linkedSignal, isDevMode, Injector, effect, ElementRef, PLATFORM_ID, Injectable, runInInjectionContext } from '@angular/core';
 import { isPlatformServer } from '@angular/common';
 import { SIGNAL } from '@angular/core/primitives/signals';
 
@@ -31,9 +31,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;
@@ -289,117 +289,10 @@ 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;
+function isWritableSignal(value) {
+    return isWritableSignal$1(value);
 }
 
-/**
- * @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;
-}
 /**
  * @internal
  * Creates a setter function for a source signal of type `Signal<T[]>` or a function returning `T[]`.
@@ -407,31 +300,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,41 +349,92 @@ 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]);
-                    }
-                }
-                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;
+                if (opt.onDestroy)
+                    prev.value.forEach((v) => opt.onDestroy?.(v));
+                return prev.value.slice(0, len);
             }
+            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;
+
+function keyArray(source, keyFn, map, opt = {}) {
+    const data = isSignal(source) ? source : computed(source);
+    const setter = createSetter(data);
+    const writableData = isWritableSignal(data)
+        ? data
+        : toWritable(data, () => {
+            // noop
+        });
+    if (isWritableSignal(data) && isMutable(data) && !opt.equal) {
+        opt.equal = (a, b) => {
+            if (a !== b)
+                return false;
+            return false; // opt out for same refs
+        };
+    }
+    let freeMap = new Map();
+    const createRecord = (i) => {
+        const idx = signal(i, ...(ngDevMode ? [{ debugName: "idx" }] : []));
+        const value = derived(writableData, {
+            from: (v) => v[idx()],
+            onChange: (next) => setter(next, untracked(idx)),
+        }, opt);
+        return {
+            source: {
+                idx,
+                value,
+            },
+            computation: map(value, idx),
+        };
+    };
+    const internal = linkedSignal({ ...(ngDevMode ? { debugName: "internal" } : {}), source: () => writableData(),
+        computation: (src, prev) => {
+            const prevCache = prev?.value.cache ?? new Map();
+            const nextCache = freeMap;
+            const nextValues = [];
+            let changed = false;
+            for (let i = 0; i < src.length; i++) {
+                const k = untracked(() => keyFn(src[i]));
+                let record = prevCache.get(k);
+                if (!record) {
+                    changed = true;
+                    record = createRecord(i);
+                }
+                prevCache.delete(k);
+                nextCache.set(k, record);
+                nextValues.push(record.computation);
+                if (untracked(record.source.idx) !== i) {
+                    record.source.idx.set(i);
+                    changed = true;
+                }
+            }
+            if (prevCache.size > 0)
+                changed = true;
+            if (opt.onDestroy)
+                prevCache.values().forEach((v) => opt.onDestroy?.(v.computation));
+            // clear for next run
+            prevCache.clear();
+            freeMap = prevCache;
+            return {
+                cache: nextCache,
+                values: changed ? nextValues : (prev?.value.values ?? []),
+            };
+        } });
+    return computed(() => internal().values);
+}
 
 const frameStack = [];
 function current() {
@@ -698,6 +656,205 @@ 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.
@@ -1004,9 +1161,7 @@ function networkStatus(debugName = 'networkStatus') {
         sig.since = computed(() => serverDate, ...(ngDevMode ? [{ debugName: "since" }] : []));
         return sig;
     }
-    const state = signal(navigator.onLine, ...(ngDevMode ? [{ debugName: "state", debugName }] : [{
-            debugName,
-        }]));
+    const state = signal(navigator.onLine, { ...(ngDevMode ? { debugName: "state" } : {}), debugName });
     const since = signal(new Date(), ...(ngDevMode ? [{ debugName: "since" }] : []));
     const goOnline = () => {
         state.set(true);
@@ -1067,7 +1222,7 @@ function pageVisibility(debugName = 'pageVisibility') {
     if (isPlatformServer(inject(PLATFORM_ID))) {
         return computed(() => 'visible', { debugName });
     }
-    const visibility = signal(document.visibilityState, ...(ngDevMode ? [{ debugName: "visibility", debugName }] : [{ debugName }]));
+    const visibility = signal(document.visibilityState, { ...(ngDevMode ? { debugName: "visibility" } : {}), debugName });
     const onVisibilityChange = () => visibility.set(document.visibilityState);
     document.addEventListener('visibilitychange', onVisibilityChange);
     inject(DestroyRef).onDestroy(() => document.removeEventListener('visibilitychange', onVisibilityChange));
@@ -1250,18 +1405,38 @@ 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;
+    }, {});
+}
 
 // Internal dummy store for server-side rendering
 const noopStore = {
@@ -1363,23 +1538,14 @@ function stored(fallback, { key, store: providedStore, serialize = JSON.stringif
         equal,
     };
     const initialKey = untracked(keySig);
-    const internal = signal(getValue(initialKey), ...(ngDevMode ? [{ debugName: "internal", ...opt,
-            equal: (a, b) => {
-                if (a === null && b === null)
-                    return true;
-                if (a === null || b === null)
-                    return false;
-                return equal(a, b);
-            } }] : [{
-            ...opt,
-            equal: (a, b) => {
-                if (a === null && b === null)
-                    return true;
-                if (a === null || b === null)
-                    return false;
-                return equal(a, b);
-            },
-        }]));
+    const internal = signal(getValue(initialKey), { ...(ngDevMode ? { debugName: "internal" } : {}), ...opt,
+        equal: (a, b) => {
+            if (a === null && b === null)
+                return true;
+            if (a === null || b === null)
+                return false;
+            return equal(a, b);
+        } });
     let prevKey = initialKey;
     if (onKeyChange === 'store') {
         effect(() => {
@@ -1457,10 +1623,10 @@ class MessageBus {
         this.channel.removeEventListener('message', listener);
         this.listeners.delete(id);
     }
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.0.0", ngImport: i0, type: MessageBus, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
-    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.0.0", ngImport: i0, type: MessageBus, providedIn: 'root' });
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.0.8", ngImport: i0, type: MessageBus, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.0.8", ngImport: i0, type: MessageBus, providedIn: 'root' });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.0.0", ngImport: i0, type: MessageBus, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.0.8", ngImport: i0, type: MessageBus, decorators: [{
             type: Injectable,
             args: [{
                     providedIn: 'root',
@@ -1743,5 +1909,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 { combineWith, debounce, debounced, derived, distinct, elementSize, elementVisibility, filter, indexArray, isDerivation, isMutable, keyArray, map, mapArray, mediaQuery, mousePosition, mutable, nestedEffect, networkStatus, pageVisibility, pipeable, piped, prefersDarkMode, prefersReducedMotion, scrollPosition, select, sensor, sensors, stored, tabSync, tap, throttle, throttled, toFakeDerivation, toFakeSignalDerivation, toWritable, until, windowSize, withHistory };
 //# sourceMappingURL=mmstack-primitives.mjs.map