@mmstack/primitives 19.3.5 → 19.3.7

package/fesm2022/mmstack-primitives.mjs

@@ -1,5 +1,5 @@
 import * as i0 from '@angular/core';
-import { isDevMode, inject, Injector, untracked, effect, DestroyRef, linkedSignal, computed, signal, isSignal, ElementRef, PLATFORM_ID, Injectable, runInInjectionContext } from '@angular/core';
+import { isDevMode, inject, Injector, untracked, effect, DestroyRef, linkedSignal, computed, signal, isSignal, PLATFORM_ID, ElementRef, Injectable, runInInjectionContext } from '@angular/core';
 import { isPlatformServer } from '@angular/common';
 import { SIGNAL } from '@angular/core/primitives/signals';
 
@@ -351,9 +351,9 @@ function debounce(source, opt) {
 const { is } = Object;
 function mutable(initial, opt) {
     const baseEqual = opt?.equal ?? is;
-    let trigger = false;
+    let cnt = 0;
     const equal = (a, b) => {
-        if (trigger)
+        if (cnt > 0)
             return false;
         return baseEqual(a, b);
     };
@@ -363,9 +363,9 @@ function mutable(initial, opt) {
     });
     const internalUpdate = sig.update;
     sig.mutate = (updater) => {
-        trigger = true;
+        cnt++;
         internalUpdate(updater);
-        trigger = false;
+        cnt--;
     };
     sig.inline = (updater) => {
         sig.mutate((prev) => {
@@ -432,10 +432,10 @@ function derived(source, optOrKey, opt) {
                 };
     const rest = typeof optOrKey === 'object' ? { ...optOrKey, ...opt } : opt;
     const baseEqual = rest?.equal ?? Object.is;
-    let trigger = false;
+    let cnt = 0;
     const equal = isMutable(source)
         ? (a, b) => {
-            if (trigger)
+            if (cnt > 0)
                 return false;
             return baseEqual(a, b);
         }
@@ -444,9 +444,9 @@ function derived(source, optOrKey, opt) {
     sig.from = from;
     if (isMutable(source)) {
         sig.mutate = (updater) => {
-            trigger = true;
+            cnt++;
             sig.update(updater);
-            trigger = false;
+            cnt--;
         };
         sig.inline = (updater) => {
             sig.mutate((prev) => {
@@ -551,9 +551,11 @@ function indexArray(source, map, opt = {}) {
         });
     if (isWritableSignal(data) && isMutable(data) && !opt.equal) {
         opt.equal = (a, b) => {
-            if (a !== b)
-                return false; // actually check primitives and references
-            return false; // opt out for same refs
+            if (typeof a !== typeof b)
+                return false;
+            if (typeof a === 'object' || typeof a === 'function')
+                return false;
+            return a === b;
         };
     }
     return linkedSignal({
@@ -600,7 +602,30 @@ const mapArray = indexArray;
  * @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.
+ *  - `key`: A custom key extractor for identity matching (e.g. `(item) => item.id`)
+ *    when item references change but conceptual identity is preserved.
  * @returns A `Signal<U[]>` containing the mapped array.
+ *
+ * @example
+ * ```ts
+ * const users = signal([
+ *   { id: 1, name: 'Alice' },
+ *   { id: 2, name: 'Bob' },
+ * ]);
+ *
+ * const rows = keyArray(
+ *   users,
+ *   (user, index) => ({
+ *     label: computed(() => `#${index()} ${user.name}`),
+ *     id: user.id,
+ *   }),
+ *   { key: (u) => u.id },
+ * );
+ *
+ * // Reordering users() rebuilds index signals only — `rows` entries
+ * // are matched by id and reused, not re-created.
+ * users.set([users()[1], users()[0]]);
+ * ```
  */
 function keyArray(source, mapFn, options = {}) {
     const sourceSignal = isSignal(source) ? source : computed(source);
@@ -757,15 +782,69 @@ function mapObject(source, mapFn, options = {}) {
     }).asReadonly();
 }
 
-/** Project with optional equality. Pure & sync. */
+/**
+ * Synchronous projection of a signal value with optional `CreateSignalOptions`
+ * (custom `equal`, `debugName`, etc.). Equivalent to `map` plus the ability to
+ * pass signal options through to the underlying `computed()`.
+ *
+ * @example
+ * ```ts
+ * const user = piped({ id: 1, name: 'Alice' });
+ * const name = user.pipe(select((u) => u.name));
+ * name(); // 'Alice'
+ * ```
+ */
 const select = (projector, opt) => (src) => computed(() => projector(src()), opt);
-/** Combine with another signal using a projector. */
+/**
+ * Combine the piped signal with another `Signal` using a projector. The result
+ * recomputes whenever either source changes.
+ *
+ * @example
+ * ```ts
+ * const price = piped(10);
+ * const quantity = signal(3);
+ * const total = price.pipe(combineWith(quantity, (p, q) => p * q));
+ * total(); // 30
+ * ```
+ */
 const combineWith = (other, project, opt) => (src) => computed(() => project(src(), other()), opt);
-/** Only re-emit when equal(prev, next) is false. */
+/**
+ * Suppress emissions while consecutive values are considered equal. The
+ * comparator defaults to `Object.is`; pass a custom one for structural or
+ * key-based equality (e.g. compare by `id` only).
+ *
+ * @example
+ * ```ts
+ * const user = piped({ id: 1, lastSeen: Date.now() });
+ * const byId = user.pipe(distinct((a, b) => a.id === b.id));
+ * // byId only re-emits when `id` changes, not on every `lastSeen` update
+ * ```
+ */
 const distinct = (equal = Object.is) => (src) => computed(() => src(), { equal });
-/** map to new value */
+/**
+ * Pure synchronous transform from input to output. Equivalent to a `computed()`
+ * that reads the source and returns `fn(value)`.
+ *
+ * @example
+ * ```ts
+ * const count = piped(2);
+ * const doubled = count.pipe(map((n) => n * 2));
+ * doubled(); // 4
+ * ```
+ */
 const map = (fn) => (src) => computed(() => fn(src()));
-/** filter values, keeping the last value if it was ever available, if first value is filtered will return undefined */
+/**
+ * Keep only values that pass the predicate. The result holds the last passing
+ * value across emissions; before any value passes, the result is `undefined` —
+ * see {@link filterWith} when you need a non-`undefined` seed.
+ *
+ * @example
+ * ```ts
+ * const event = piped<MouseEvent | null>(null);
+ * const clicks = event.pipe(filter((e): e is MouseEvent => e?.type === 'click'));
+ * clicks(); // undefined until a click happens, then the last MouseEvent
+ * ```
+ */
 const filter = (predicate) => (src) => linkedSignal({
     source: src,
     computation: (next, prev) => {
@@ -774,11 +853,90 @@ const filter = (predicate) => (src) => linkedSignal({
         return prev?.source;
     },
 });
-/** tap into the value */
-const tap = (fn) => (src) => {
-    effect(() => fn(src()));
+/**
+ * Run a side effect on every emission without altering the signal value. Wraps
+ * Angular's `effect()`, so it must run in an injection context or receive an
+ * explicit `injector`. Use for logging / analytics — not for setting other
+ * signals (that's what regular `effect()` is for).
+ *
+ * @example
+ * ```ts
+ * const count = piped(0);
+ * count.pipe(tap((n) => console.log('count:', n)));
+ * count.set(1); // logs 'count: 1'
+ * ```
+ */
+const tap = (fn, injector) => (src) => {
+    effect(() => fn(src()), {
+        injector,
+    });
     return src;
 };
+/**
+ * Like {@link filter}, but emits `initial` until a value first passes the
+ * predicate. Eliminates the `T | undefined` return type at the cost of an
+ * explicit seed value.
+ *
+ * @example
+ * ```ts
+ * const event = piped<MouseEvent | null>(null);
+ * const lastClick = event.pipe(filterWith((e) => e?.type === 'click', null));
+ * lastClick(); // null until the first click, then the most recent click event
+ * ```
+ */
+const filterWith = (predicate, initial) => (src) => linkedSignal({
+    source: src,
+    computation: (next, prev) => predicate(next) ? next : (prev?.value ?? initial),
+});
+/**
+ * Emit `initial` on the first read, then mirror the source on every subsequent
+ * read. Useful for giving a pipeline a sensible seed value before the source
+ * is ready (e.g. loading state).
+ *
+ * @example
+ * ```ts
+ * const data = piped<User | null>(null);
+ * const view = data.pipe(startWith<User | null, 'loading'>('loading'));
+ * view(); // 'loading' on first read, then User | null afterward
+ * ```
+ */
+const startWith = (initial) => (src) => linkedSignal({
+    source: src,
+    computation: (next, prev) => (prev === undefined ? initial : next),
+});
+/**
+ * Emit `[prev, curr]` tuples so consumers can react to transitions instead of
+ * raw values. On the first emission `prev` is `undefined`.
+ *
+ * @example
+ * ```ts
+ * const count = piped(0);
+ * const delta = count.pipe(pairwise(), map(([prev, curr]) => curr - (prev ?? 0)));
+ * count.set(5);
+ * delta(); // 5
+ * ```
+ */
+const pairwise = () => (src) => linkedSignal({
+    source: src,
+    computation: (next, prev) => [prev?.source, next],
+});
+/**
+ * Reduce-like accumulator that folds each emission into a running result.
+ * Behaves like `Array.prototype.reduce` but applied over time, with the
+ * accumulator persisted across emissions.
+ *
+ * @example
+ * ```ts
+ * const delta = piped(0);
+ * const total = delta.pipe(scan((acc, n) => acc + n, 0));
+ * delta.set(5); // total() === 5
+ * delta.set(3); // total() === 8
+ * ```
+ */
+const scan = (reducer, seed) => (src) => linkedSignal({
+    source: src,
+    computation: (next, prev) => reducer(prev?.value ?? seed, next),
+});
 
 /**
  * Decorate any `Signal<T>` with a chainable `.pipe(...)` method.
@@ -882,12 +1040,10 @@ function pooled({ create, reset, computation, ...opt }) {
         const next = other ?? untracked(() => create());
         if (current !== undefined) {
             if (currentFresh) {
-                // never-mutated buffer leaving the active slot; nothing to clean
                 other = current;
             }
             else {
-                // reset on release: clean the dirty buffer as it goes back into the pool
-                // (also threads the swap-return correctly into the pool's spare slot)
+                // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- guarded by the `current !== undefined` check above
                 other = untracked(() => reset(current)) ?? current;
             }
         }
@@ -934,6 +1090,96 @@ function pooledMap(optOrComputation, signalOpt) {
     return pooled(toPooledOptions(optOrComputation, createEmptyMap, resetClearable, signalOpt));
 }
 
+const EVENTS = [
+    'chargingchange',
+    'levelchange',
+    'chargingtimechange',
+    'dischargingtimechange',
+];
+/**
+ * Creates a read-only signal that tracks the system battery status using the
+ * Battery Status API. Returns `null` until the underlying `getBattery()`
+ * promise resolves, or permanently when the API is unsupported (Firefox /
+ * Safari at the time of writing). SSR-safe.
+ *
+ * @example
+ * ```ts
+ * const battery = batteryStatus();
+ * effect(() => {
+ *   const b = battery();
+ *   if (b) console.log(`${Math.round(b.level * 100)}% • charging: ${b.charging}`);
+ * });
+ * ```
+ */
+function batteryStatus(debugName = 'batteryStatus') {
+    if (isPlatformServer(inject(PLATFORM_ID)) ||
+        typeof navigator === 'undefined' ||
+        typeof navigator.getBattery !== 'function') {
+        return computed(() => null, { debugName });
+    }
+    const state = signal(null, { debugName });
+    const abortController = new AbortController();
+    inject(DestroyRef).onDestroy(() => abortController.abort());
+    navigator.getBattery().then((battery) => {
+        if (abortController.signal.aborted)
+            return;
+        const read = () => ({
+            level: battery.level,
+            charging: battery.charging,
+            chargingTime: battery.chargingTime,
+            dischargingTime: battery.dischargingTime,
+        });
+        const onChange = () => state.set(read());
+        state.set(read());
+        for (const ev of EVENTS) {
+            battery.addEventListener(ev, onChange, {
+                signal: abortController.signal,
+            });
+        }
+    });
+    return state.asReadonly();
+}
+
+/**
+ * Creates a read-only signal mirroring the system clipboard contents.
+ *
+ * The signal value starts empty and updates whenever a `copy` event fires on
+ * the document (or {@link ClipboardSignal.copy} is invoked from this app).
+ * SSR-safe — returns `''` and `isSupported: false` on the server.
+ *
+ * Note: read access requires the Clipboard API and an active permission grant
+ * in browsers that gate it. Errors from `navigator.clipboard.readText` are
+ * swallowed silently to keep the signal value stable.
+ */
+function clipboard(debugName = 'clipboard') {
+    if (isPlatformServer(inject(PLATFORM_ID)) ||
+        typeof navigator === 'undefined' ||
+        !navigator.clipboard) {
+        const sig = computed(() => '', { debugName });
+        sig.copy = () => Promise.resolve();
+        sig.isSupported = computed(() => false);
+        return sig;
+    }
+    const state = signal('', { debugName });
+    const refresh = () => {
+        navigator.clipboard.readText().then((value) => state.set(value), () => {
+            // permission denied / focus required — ignore
+        });
+    };
+    const abortController = new AbortController();
+    const onCopy = () => refresh();
+    document.addEventListener('copy', onCopy, { signal: abortController.signal });
+    document.addEventListener('cut', onCopy, { signal: abortController.signal });
+    inject(DestroyRef).onDestroy(() => abortController.abort());
+    const sig = state.asReadonly();
+    sig.copy = async (value) => {
+        await navigator.clipboard.writeText(value);
+        state.set(value);
+    };
+    sig.isSupported = computed(() => true);
+    return sig;
+}
+
 function observerSupported$1() {
     return typeof ResizeObserver !== 'undefined';
 }
@@ -1134,6 +1380,184 @@ function elementVisibility(target = inject(ElementRef), opt) {
     return base;
 }
 
+function unwrap$1(target) {
+    if (!target)
+        return null;
+    return target instanceof ElementRef ? target.nativeElement : target;
+}
+/**
+ * Creates a read-only signal that tracks whether the focused element is the
+ * target or a descendant of it. Mirrors the CSS `:focus-within` pseudo-class.
+ *
+ * Defaults `target` to the current `ElementRef` so it can be used inline in a
+ * component's `class` field. SSR-safe — returns a constant `false` signal on
+ * the server.
+ *
+ * @example
+ * ```ts
+ * @Component({ ... })
+ * class MenuComponent {
+ *   // Defaults to the host element — flips true when focus is inside.
+ *   readonly hasFocus = focusWithin();
+ * }
+ * ```
+ */
+function focusWithin(target = inject(ElementRef)) {
+    if (isPlatformServer(inject(PLATFORM_ID))) {
+        return computed(() => false, { debugName: 'focusWithin' });
+    }
+    const state = signal(false, { debugName: 'focusWithin' });
+    const attach = (el) => {
+        state.set(el.contains(document.activeElement));
+        const abortController = new AbortController();
+        el.addEventListener('focusin', () => state.set(true), {
+            signal: abortController.signal,
+        });
+        el.addEventListener('focusout', () => {
+            // Defer so `document.activeElement` reflects the focus move.
+            queueMicrotask(() => state.set(el.contains(document.activeElement)));
+        }, { signal: abortController.signal });
+        return () => abortController.abort();
+    };
+    if (isSignal(target)) {
+        const targetSig = target;
+        effect((cleanup) => {
+            const el = unwrap$1(targetSig());
+            if (!el) {
+                state.set(false);
+                return;
+            }
+            cleanup(attach(el));
+        });
+    }
+    else {
+        const el = unwrap$1(target);
+        if (el) {
+            const detach = attach(el);
+            inject(DestroyRef).onDestroy(detach);
+        }
+    }
+    return state.asReadonly();
+}
+
+/**
+ * Creates a read-only signal that exposes the current geolocation position.
+ *
+ * The returned signal carries `error` and `loading` sub-signals for permission
+ * failures and the in-flight initial fetch respectively. SSR-safe — on the
+ * server the position is `null`, loading is `false`, and no API calls are made.
+ *
+ * @example
+ * ```ts
+ * const where = geolocation({ watch: true, enableHighAccuracy: true });
+ * effect(() => console.log(where()?.coords, where.error()));
+ * ```
+ */
+function geolocation(opt) {
+    if (isPlatformServer(inject(PLATFORM_ID)) || typeof navigator === 'undefined' || !navigator.geolocation) {
+        const sig = computed(() => null, {
+            debugName: opt?.debugName ?? 'geolocation',
+        });
+        sig.error = computed(() => null);
+        sig.loading = computed(() => false);
+        return sig;
+    }
+    const position = signal(null, {
+        debugName: opt?.debugName ?? 'geolocation',
+    });
+    const error = signal(null);
+    const loading = signal(true);
+    const onSuccess = (p) => {
+        position.set(p);
+        error.set(null);
+        loading.set(false);
+    };
+    const onError = (e) => {
+        error.set(e);
+        loading.set(false);
+    };
+    if (opt?.watch) {
+        const watchId = navigator.geolocation.watchPosition(onSuccess, onError, opt);
+        inject(DestroyRef).onDestroy(() => navigator.geolocation.clearWatch(watchId));
+    }
+    else {
+        navigator.geolocation.getCurrentPosition(onSuccess, onError, opt);
+    }
+    const sig = position.asReadonly();
+    sig.error = error.asReadonly();
+    sig.loading = loading.asReadonly();
+    return sig;
+}
+
+const DEFAULT_EVENTS = [
+    'mousemove',
+    'keydown',
+    'touchstart',
+    'scroll',
+    'visibilitychange',
+];
+const serverDate$1 = new Date();
+/**
+ * Creates a read-only signal that flips to `true` after a window of user
+ * inactivity. Any of the configured `events` (default: pointer/keyboard/scroll
+ * activity) resets the timer and flips the signal back to `false`.
+ *
+ * SSR-safe — always `false` with a frozen `since` date on the server.
+ *
+ * @example
+ * ```ts
+ * const isAway = idle({ ms: 30_000 });
+ * effect(() => {
+ *   if (isAway()) console.log('idle since', isAway.since());
+ * });
+ * ```
+ */
+function idle(opt) {
+    if (isPlatformServer(inject(PLATFORM_ID))) {
+        const sig = computed(() => false, {
+            debugName: opt?.debugName ?? 'idle',
+        });
+        sig.since = computed(() => serverDate$1);
+        return sig;
+    }
+    const ms = opt?.ms ?? 60_000;
+    const events = opt?.events ?? DEFAULT_EVENTS;
+    const state = signal(false, { debugName: opt?.debugName ?? 'idle' });
+    const since = signal(new Date());
+    let timer;
+    const goIdle = () => {
+        if (state())
+            return;
+        state.set(true);
+        since.set(new Date());
+    };
+    const reset = () => {
+        if (timer)
+            clearTimeout(timer);
+        if (state()) {
+            state.set(false);
+            since.set(new Date());
+        }
+        timer = setTimeout(goIdle, ms);
+    };
+    const abortController = new AbortController();
+    for (const ev of events) {
+        window.addEventListener(ev, reset, {
+            passive: true,
+            signal: abortController.signal,
+        });
+    }
+    timer = setTimeout(goIdle, ms);
+    inject(DestroyRef).onDestroy(() => {
+        if (timer)
+            clearTimeout(timer);
+        abortController.abort();
+    });
+    const sig = state.asReadonly();
+    sig.since = since.asReadonly();
+    return sig;
+}
+
 /**
  * Creates a read-only signal that reactively tracks whether a CSS media query
  * string currently matches.
@@ -1295,26 +1719,41 @@ function throttled(initial, opt) {
  */
 function throttle(source, opt) {
     const ms = opt?.ms ?? 0;
+    const leading = opt?.leading ?? false;
+    const trailing = opt?.trailing ?? true;
     const trigger = signal(false);
+    const fire = () => trigger.update((c) => !c);
     let timeout;
+    let pendingTrailing = false;
     try {
         const destroyRef = opt?.destroyRef ?? inject(DestroyRef, { optional: true });
         destroyRef?.onDestroy(() => {
             if (timeout)
                 clearTimeout(timeout);
             timeout = undefined;
+            pendingTrailing = false;
         });
     }
     catch {
         // not in injection context & no destroyRef provided opting out of cleanup
     }
     const tick = () => {
-        if (timeout)
+        if (!timeout) {
+            if (leading)
+                fire();
+            else
+                pendingTrailing = trailing;
+            timeout = setTimeout(() => {
+                timeout = undefined;
+                if (trailing && pendingTrailing) {
+                    pendingTrailing = false;
+                    fire();
+                }
+            }, ms);
             return;
-        timeout = setTimeout(() => {
-            trigger.update((c) => !c);
-            timeout = undefined;
-        }, ms);
+        }
+        if (trailing)
+            pendingTrailing = true;
     };
     const set = (value) => {
         source.set(value);
@@ -1435,6 +1874,14 @@ const serverDate = new Date();
  *
  * @param debugName Optional debug name for the signal.
  * @returns A `NetworkStatusSignal` instance.
+ *
+ * @example
+ * ```ts
+ * const online = networkStatus();
+ * effect(() => {
+ *   if (!online()) console.log('offline since', online.since());
+ * });
+ * ```
  */
 function networkStatus(debugName = 'networkStatus') {
     if (isPlatformServer(inject(PLATFORM_ID))) {
@@ -1467,6 +1914,46 @@ function networkStatus(debugName = 'networkStatus') {
     return sig;
 }
 
+const SSR_FALLBACK = {
+    angle: 0,
+    type: 'portrait-primary',
+};
+/**
+ * Creates a read-only signal that tracks `screen.orientation`.
+ *
+ * SSR-safe — returns a constant `portrait-primary / 0°` signal on the server
+ * and in environments without `screen.orientation` support.
+ *
+ * @example
+ * ```ts
+ * const screenOrientation = orientation();
+ * effect(() => {
+ *   const { type, angle } = screenOrientation();
+ *   console.log(`${type} at ${angle}°`);
+ * });
+ * ```
+ */
+function orientation(debugName = 'orientation') {
+    if (isPlatformServer(inject(PLATFORM_ID)) ||
+        typeof screen === 'undefined' ||
+        !screen.orientation) {
+        return computed(() => SSR_FALLBACK, { debugName });
+    }
+    const so = screen.orientation;
+    const read = () => ({
+        angle: so.angle,
+        type: so.type,
+    });
+    const state = signal(read(), {
+        debugName,
+        equal: (a, b) => a.angle === b.angle && a.type === b.type,
+    });
+    const onChange = () => state.set(read());
+    so.addEventListener('change', onChange);
+    inject(DestroyRef).onDestroy(() => so.removeEventListener('change', onChange));
+    return state.asReadonly();
+}
+
 /**
  * Creates a read-only signal that tracks the page's visibility state.
  *
@@ -1683,39 +2170,67 @@ function windowSize(opt) {
  * @internal
  */
 function sensor(type, options) {
+    const opts = options;
     switch (type) {
         case 'mousePosition':
-            return mousePosition(options);
+            return mousePosition(opts);
         case 'networkStatus':
-            return networkStatus(options?.debugName);
+            return networkStatus(opts?.debugName);
         case 'pageVisibility':
-            return pageVisibility(options?.debugName);
+            return pageVisibility(opts?.debugName);
         case 'darkMode':
         case 'dark-mode':
-            return prefersDarkMode(options?.debugName);
+            return prefersDarkMode(opts?.debugName);
         case 'reducedMotion':
         case 'reduced-motion':
-            return prefersReducedMotion(options?.debugName);
-        case 'mediaQuery': {
-            const opt = options;
-            return mediaQuery(opt.query, opt.debugName);
-        }
+            return prefersReducedMotion(opts?.debugName);
+        case 'mediaQuery':
+            return mediaQuery(opts.query, opts.debugName);
         case 'windowSize':
-            return windowSize(options);
+            return windowSize(opts);
         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);
-        }
+            return scrollPosition(opts);
+        case 'elementVisibility':
+            return elementVisibility(opts?.target, opts);
+        case 'elementSize':
+            return elementSize(opts?.target, opts);
+        case 'geolocation':
+            return geolocation(opts);
+        case 'clipboard':
+            return clipboard(opts?.debugName);
+        case 'orientation':
+            return orientation(opts?.debugName);
+        case 'batteryStatus':
+            return batteryStatus(opts?.debugName);
+        case 'idle':
+            return idle(opts);
+        case 'focusWithin':
+            return focusWithin(opts?.target);
         default:
             throw new Error(`Unknown sensor type: ${type}`);
     }
 }
+/**
+ * Bulk sensor factory — creates several sensor signals at once and returns
+ * them keyed by sensor type. Convenient when a single consumer needs to react
+ * to multiple browser signals; for a single sensor prefer {@link sensor}
+ * directly.
+ *
+ * @typeParam TType The union of sensor keys being requested.
+ * @param track Array of sensor type keys to create.
+ * @param opt Optional per-sensor options keyed by sensor type.
+ * @returns A record `{ [key]: <SensorReturnType> }` for each requested key.
+ *
+ * @example
+ * ```ts
+ * const { windowSize, networkStatus } = sensors(
+ *   ['windowSize', 'networkStatus'],
+ *   { windowSize: { throttle: 200 } },
+ * );
+ *
+ * effect(() => console.log(windowSize(), networkStatus()));
+ * ```
+ */
 function sensors(track, opt) {
     return track.reduce((result, key) => {
         result[key] = sensor(key, opt?.[key]);
@@ -1723,6 +2238,49 @@ function sensors(track, opt) {
     }, {});
 }
 
+function unwrap(t) {
+    if (!t)
+        return null;
+    return t instanceof ElementRef ? t.nativeElement : t;
+}
+function signalFromEvent(target, eventName, initial, projectOrOpt, maybeOpt) {
+    const project = typeof projectOrOpt === 'function' ? projectOrOpt : undefined;
+    const opt = typeof projectOrOpt === 'function' ? maybeOpt : projectOrOpt;
+    const injector = opt?.injector ?? inject(Injector);
+    if (isPlatformServer(injector.get(PLATFORM_ID))) {
+        return computed(() => initial, { debugName: opt?.debugName });
+    }
+    const state = signal(initial, {
+        debugName: opt?.debugName,
+    });
+    const handler = (event) => {
+        if (project)
+            state.set(project(event));
+        else
+            state.set(event);
+    };
+    const { destroyRef: providedDestroyRef, ...listenerOpts } = opt ?? {};
+    if (isSignal(target)) {
+        const targetSig = target;
+        effect((cleanup) => {
+            const resolved = unwrap(targetSig());
+            if (!resolved)
+                return;
+            resolved.addEventListener(eventName, handler, listenerOpts);
+            cleanup(() => resolved.removeEventListener(eventName, handler, listenerOpts));
+        }, { injector });
+    }
+    else {
+        const resolved = unwrap(target);
+        if (resolved) {
+            resolved.addEventListener(eventName, handler, listenerOpts);
+            const destroyRef = providedDestroyRef ?? injector.get(DestroyRef);
+            destroyRef.onDestroy(() => resolved.removeEventListener(eventName, handler, listenerOpts));
+        }
+    }
+    return untracked(() => state.asReadonly());
+}
+
 const IS_STORE = Symbol('MMSTACK::IS_STORE');
 const PROXY_CACHE = new WeakMap();
 const SIGNAL_FN_PROP = new Set([
@@ -2215,14 +2773,11 @@ function generateDeterministicID() {
  *
  * @template T - The type of the WritableSignal
  * @param sig - The WritableSignal to synchronize across tabs
- * @param opt - Optional configuration object
- * @param opt.id - Explicit channel ID for synchronization. If not provided,
- *                 a deterministic ID is generated based on the call site.
- *                 Use explicit IDs in production for reliability.
+ * @param opt - configuration object
+ * @param opt.id - Explicit channel ID for synchronization.
  *
  * @returns The same WritableSignal instance, now synchronized across tabs
  *
- * @throws {Error} When deterministic ID generation fails and no explicit ID is provided
  *
  * @example
  * ```typescript
@@ -2246,7 +2801,7 @@ function generateDeterministicID() {
 function tabSync(sig, opt) {
     if (isPlatformServer(inject(PLATFORM_ID)))
         return sig;
-    const id = opt?.id || generateDeterministicID();
+    const id = typeof opt === 'string' ? opt : (opt?.id ?? generateDeterministicID());
     const bus = inject(MessageBus);
     const { unsub, post } = bus.subscribe(id, (next) => sig.set(next));
     let first = false;
@@ -2378,8 +2933,13 @@ function getSignalEquality(sig) {
  * console.log('Can undo:', name.canUndo()); // false
  * ```
  */
-function withHistory(source, opt) {
-    const equal = opt?.equal ?? getSignalEquality(source);
+function withHistory(sourceOrValue, opt) {
+    const equal = (opt?.equal ?? isSignal(sourceOrValue))
+        ? getSignalEquality(sourceOrValue)
+        : Object.is;
+    const source = isSignal(sourceOrValue)
+        ? sourceOrValue
+        : signal(sourceOrValue);
     const maxSize = opt?.maxSize ?? Infinity;
     const history = mutable([], {
         ...opt,
@@ -2387,20 +2947,22 @@ function withHistory(source, opt) {
     });
     const redoArray = mutable([]);
     const originalSet = source.set;
+    const trim = (arr) => {
+        if (arr.length < maxSize)
+            return arr;
+        if (opt?.cleanupStrategy === 'shift') {
+            arr.shift();
+            return arr;
+        }
+        return arr.slice(Math.floor(maxSize / 2));
+    };
     const set = (value) => {
         const current = untracked(source);
         if (equal(value, current))
             return;
         source.set(value);
         history.mutate((c) => {
-            if (c.length >= maxSize) {
-                if (opt?.cleanupStrategy === 'shift') {
-                    c.shift();
-                }
-                else {
-                    c = c.slice(Math.floor(maxSize / 2));
-                }
-            }
+            c = trim(c);
             c.push(current);
             return c;
         });
@@ -2424,7 +2986,11 @@ function withHistory(source, opt) {
             return;
         originalSet.call(source, valueToRestore);
         history.inline((h) => h.pop());
-        redoArray.inline((r) => r.push(valueForRedo));
+        redoArray.mutate((r) => {
+            r = trim(r);
+            r.push(valueForRedo);
+            return r;
+        });
     };
     internal.redo = () => {
         const redoStack = untracked(redoArray);
@@ -2437,14 +3003,7 @@ function withHistory(source, opt) {
         originalSet.call(source, valueToRestore);
         redoArray.inline((r) => r.pop());
         history.mutate((h) => {
-            if (h.length >= maxSize) {
-                if (opt?.cleanupStrategy === 'shift') {
-                    h.shift();
-                }
-                else {
-                    h = h.slice(Math.floor(maxSize / 2));
-                }
-            }
+            h = trim(h);
             h.push(valueForUndo);
             return h;
         });
@@ -2463,5 +3022,5 @@ function withHistory(source, opt) {
  * Generated bundle index. Do not edit.
  */
 
-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, pooled, pooledArray, pooledMap, pooledSet, prefersDarkMode, prefersReducedMotion, scrollPosition, select, sensor, sensors, store, stored, tabSync, tap, throttle, throttled, toFakeDerivation, toFakeSignalDerivation, toStore, toWritable, until, windowSize, withHistory };
+export { batteryStatus, chunked, clipboard, combineWith, debounce, debounced, derived, distinct, elementSize, elementVisibility, filter, filterWith, focusWithin, geolocation, idle, indexArray, isDerivation, isMutable, isStore, keyArray, map, mapArray, mapObject, mediaQuery, mousePosition, mutable, mutableStore, nestedEffect, networkStatus, orientation, pageVisibility, pairwise, pipeable, piped, pooled, pooledArray, pooledMap, pooledSet, prefersDarkMode, prefersReducedMotion, 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