@mmstack/primitives 19.1.2 → 19.2.0

package/fesm2022/mmstack-primitives.mjs

@@ -1,4 +1,4 @@
-import { untracked, signal, inject, DestroyRef, computed, isSignal, linkedSignal, PLATFORM_ID, isDevMode, effect } from '@angular/core';
+import { untracked, signal, inject, DestroyRef, computed, isSignal, linkedSignal, PLATFORM_ID, ElementRef, isDevMode, effect } from '@angular/core';
 import { isPlatformServer } from '@angular/common';
 import { SIGNAL } from '@angular/core/primitives/signals';
 
@@ -336,6 +336,404 @@ function isMutable(value) {
     return 'mutate' in value && typeof value.mutate === 'function';
 }
 
+/**
+ * Creates a read-only signal that reactively tracks whether a CSS media query
+ * string currently matches.
+ *
+ * It uses `window.matchMedia` to evaluate the query and listen for changes.
+ * The primitive is SSR-safe (defaults to `false` on the server) and automatically
+ * cleans up its event listeners when the creating context is destroyed.
+ *
+ * @param query The CSS media query string to evaluate (e.g., `'(min-width: 768px)'`, `'(prefers-color-scheme: dark)'`).
+ * @param debugName Optional debug name for the signal.
+ * @returns A read-only `Signal<boolean>` which is `true` if the media query
+ * currently matches, and `false` otherwise.
+ *
+ * @remarks
+ * - On the server, this signal will always return `false` by default.
+ * - It automatically updates if the match status of the media query changes in the browser.
+ * - Event listeners are cleaned up automatically via `DestroyRef` if created in an injection context.
+ *
+ * @example
+ * ```ts
+ * import { Component, effect } from '@angular/core';
+ * import { mediaQuery } from '@mmstack/primitives';
+ *
+ * @Component({
+ * selector: 'app-responsive-layout',
+ * template: `
+ * @if (isDesktop()) {
+ * <p>Showing desktop layout.</p>
+ * } @else {
+ * <p>Showing mobile layout.</p>
+ * }
+ * `
+ * })
+ * export class ResponsiveLayoutComponent {
+ * readonly isDesktop = mediaQuery('(min-width: 1024px)');
+ *
+ * constructor() {
+ * effect(() => {
+ * console.log('Is desktop view:', this.isDesktop());
+ * });
+ * }
+ * }
+ * ```
+ */
+function mediaQuery(query, debugName) {
+    if (isPlatformServer(inject(PLATFORM_ID)))
+        return computed(() => false, { debugName });
+    const mediaQueryList = window.matchMedia(query);
+    const state = signal(mediaQueryList.matches, { debugName });
+    const handleChange = (event) => {
+        state.set(event.matches);
+    };
+    mediaQueryList.addEventListener('change', handleChange);
+    inject(DestroyRef).onDestroy(() => {
+        mediaQueryList.removeEventListener('change', handleChange);
+    });
+    return state.asReadonly();
+}
+/**
+ * Creates a read-only signal that tracks the user's OS/browser preference
+ * for a dark color scheme using the `(prefers-color-scheme: dark)` media query.
+ *
+ * This is a convenience wrapper around the generic `mediaQuery` primitive.
+ * It's SSR-safe (defaults to `false` on the server) and automatically
+ * cleans up its event listeners.
+ *
+ * @param debugName Optional debug name for the signal.
+ * @returns A read-only `Signal<boolean>` which is `true` if a dark theme
+ * is preferred, and `false` otherwise.
+ * @see {mediaQuery} for the underlying implementation.
+ *
+ * @example
+ * ```ts
+ * const isDarkMode = prefersDarkMode();
+ * effect(() => {
+ * document.body.classList.toggle('dark-theme', isDarkMode());
+ * });
+ * ```
+ */
+function prefersDarkMode(debugName) {
+    return mediaQuery('(prefers-color-scheme: dark)', debugName);
+}
+/**
+ * Creates a read-only signal that tracks the user's OS/browser preference
+ * for reduced motion using the `(prefers-reduced-motion: reduce)` media query.
+ *
+ * This is a convenience wrapper around the generic `mediaQuery` primitive.
+ * It's SSR-safe (defaults to `false` on the server) and automatically
+ * cleans up its event listeners.
+ *
+ * @param debugName Optional debug name for the signal.
+ * @returns A read-only `Signal<boolean>` which is `true` if reduced motion
+ * is preferred, and `false` otherwise.
+ * @see {mediaQuery} for the underlying implementation.
+ *
+ * @example
+ * ```ts
+ * const reduceMotion = prefersReducedMotion();
+ * effect(() => {
+ * if (reduceMotion()) {
+ * // Apply simplified animations or disable them
+ * } else {
+ * // Apply full animations
+ * }
+ * });
+ * ```
+ */
+function prefersReducedMotion(debugName) {
+    return mediaQuery('(prefers-reduced-motion: reduce)', debugName);
+}
+
+/**
+ * A convenience function that creates and throttles a new `WritableSignal` in one step.
+ *
+ * @see {throttle} for the core implementation details.
+ *
+ * @template T The type of value the signal holds.
+ * @param initial The initial value of the signal.
+ * @param opt Options for signal creation, including throttle time `ms`.
+ * @returns A `ThrottledSignal<T>` instance.
+ *
+ * @example
+ * const query = throttled('', { ms: 500 });
+ * effect(() => console.log('Throttled Query:', query()));
+ *
+ * query.set('a');
+ * query.set('b');
+ * query.set('c');
+ * // With a trailing-edge throttle, the final value 'c' would be set
+ * // after the 500ms cooldown.
+ */
+function throttled(initial, opt) {
+    return throttle(signal(initial, opt), opt);
+}
+/**
+ * Wraps an existing `WritableSignal` to create a new one whose readable value is throttled.
+ *
+ * This implementation avoids using `effect` by pairing a trigger signal with an `untracked`
+ * read of the source signal to control when the throttled value is re-evaluated.
+ *
+ * @template T The type of value the signal holds.
+ * @param source The source `WritableSignal` to wrap. Writes are applied to this signal immediately.
+ * @param opt Options for throttling, including throttle time `ms` and an optional `DestroyRef`.
+ * @returns A new `ThrottledSignal<T>` whose read value is throttled. The `.original` property
+ * of the returned signal is a reference back to the provided `source` signal.
+ *
+ * @example
+ * const query = throttled('', { ms: 500 });
+ * effect(() => console.log('Throttled Query:', query()));
+ *
+ * query.set('a');
+ * query.set('b');
+ * query.set('c');
+ * // With a trailing-edge throttle, the final value 'c' would be set
+ * // after the 500ms cooldown.
+ */
+function throttle(source, opt) {
+    const ms = opt?.ms ?? 0;
+    const trigger = signal(false);
+    let timeout;
+    try {
+        const destroyRef = opt?.destroyRef ?? inject(DestroyRef, { optional: true });
+        destroyRef?.onDestroy(() => {
+            if (timeout)
+                clearTimeout(timeout);
+            timeout = undefined;
+        });
+    }
+    catch {
+        // not in injection context & no destroyRef provided opting out of cleanup
+    }
+    const triggerFn = (updateSourceAction) => {
+        updateSourceAction();
+        if (timeout)
+            return;
+        timeout = setTimeout(() => {
+            trigger.update((c) => !c);
+            timeout = undefined;
+        }, ms);
+    };
+    const set = (value) => {
+        triggerFn(() => source.set(value));
+    };
+    const update = (fn) => {
+        triggerFn(() => source.update(fn));
+    };
+    const writable = toWritable(computed(() => {
+        trigger();
+        return untracked(source);
+    }, opt), set, update);
+    writable.original = source;
+    return writable;
+}
+
+/**
+ * Creates a read-only signal that tracks the mouse cursor's position.
+ *
+ * It can track mouse movements on a specific target (window, document, or element)
+ * and optionally include touch movements. The coordinate space ('client' or 'page')
+ * can also be configured.
+ * The primitive is SSR-safe and automatically cleans up its event listeners.
+ *
+ * @param options Optional configuration for the sensor.
+ * @returns A read-only `Signal<MousePosition>`. On the server, it returns a static
+ * signal with `{ x: 0, y: 0 }`.
+ *
+ * @example
+ * ```ts
+ * import { Component, effect } from '@angular/core';
+ * import { mousePosition } from '@mmstack/primitives';
+ *
+ * @Component({
+ * selector: 'app-mouse-tracker',
+ * template: `<p>Mouse Position: X: {{ pos().x }}, Y: {{ pos().y }}</p>`
+ * })
+ * export class MouseTrackerComponent {
+ * readonly pos = mousePosition({ coordinateSpace: 'page' });
+ *
+ * constructor() {
+ * effect(() => {
+ * console.log('Mouse moved to:', this.pos());
+ * });
+ * }
+ * }
+ * ```
+ */
+function mousePosition(opt) {
+    if (isPlatformServer(inject(PLATFORM_ID))) {
+        const base = computed(() => ({
+            x: 0,
+            y: 0,
+        }), {
+            debugName: opt?.debugName,
+        });
+        base.unthrottled = base;
+        return base;
+    }
+    const { target = window, coordinateSpace = 'client', touch = false, debugName, throttle = 100, } = opt ?? {};
+    const eventTarget = target instanceof ElementRef ? target.nativeElement : target;
+    if (!eventTarget) {
+        if (isDevMode())
+            console.warn('mousePosition: Target element not found.');
+        const base = computed(() => ({
+            x: 0,
+            y: 0,
+        }), {
+            debugName,
+        });
+        base.unthrottled = base;
+        return base;
+    }
+    const pos = throttled({ x: 0, y: 0 }, {
+        ms: throttle,
+        equal: (a, b) => a.x === b.x && a.y === b.y,
+        debugName,
+    });
+    const updatePosition = (event) => {
+        let x, y;
+        if (event instanceof MouseEvent) {
+            x = coordinateSpace === 'page' ? event.pageX : event.clientX;
+            y = coordinateSpace === 'page' ? event.pageY : event.clientY;
+        }
+        else if (event.touches.length > 0) {
+            const firstTouch = event.touches[0];
+            x = coordinateSpace === 'page' ? firstTouch.pageX : firstTouch.clientX;
+            y = coordinateSpace === 'page' ? firstTouch.pageY : firstTouch.clientY;
+        }
+        else {
+            return;
+        }
+        pos.set({ x, y });
+    };
+    eventTarget.addEventListener('mousemove', updatePosition);
+    if (touch) {
+        eventTarget.addEventListener('touchmove', updatePosition);
+    }
+    inject(DestroyRef).onDestroy(() => {
+        eventTarget.removeEventListener('mousemove', updatePosition);
+        if (touch) {
+            eventTarget.removeEventListener('touchmove', updatePosition);
+        }
+    });
+    const base = pos.asReadonly();
+    base.unthrottled = pos.original;
+    return base;
+}
+
+const serverDate = new Date();
+/**
+ * Creates a read-only signal that tracks the browser's online status.
+ *
+ * The main signal returns a boolean (`true` for online, `false` for offline).
+ * An additional `since` signal is attached, tracking when the status last changed.
+ * It's SSR-safe and automatically cleans up its event listeners.
+ *
+ * @param debugName Optional debug name for the signal.
+ * @returns A `NetworkStatusSignal` instance.
+ */
+function networkStatus(debugName) {
+    if (isPlatformServer(inject(PLATFORM_ID))) {
+        const sig = computed(() => true, {
+            debugName,
+        });
+        sig.since = computed(() => serverDate);
+        return sig;
+    }
+    const state = signal(navigator.onLine, {
+        debugName,
+    });
+    const since = signal(new Date());
+    const goOnline = () => {
+        state.set(true);
+        since.set(new Date());
+    };
+    const goOffline = () => {
+        state.set(false);
+        since.set(new Date());
+    };
+    window.addEventListener('online', goOnline);
+    window.addEventListener('offline', goOffline);
+    inject(DestroyRef).onDestroy(() => {
+        window.removeEventListener('online', goOnline);
+        window.removeEventListener('offline', goOffline);
+    });
+    const sig = state.asReadonly();
+    sig.since = since.asReadonly();
+    return sig;
+}
+
+/**
+ * Creates a read-only signal that tracks the page's visibility state.
+ *
+ * It uses the browser's Page Visibility API to reactively report if the
+ * current document is `'visible'`, `'hidden'`, or in another state.
+ * The primitive is SSR-safe and automatically cleans up its event listeners
+ * when the creating context is destroyed.
+ *
+ * @param debugName Optional debug name for the signal.
+ * @returns A read-only `Signal<DocumentVisibilityState>`. On the server,
+ * it returns a static signal with a value of `'visible'`.
+ *
+ * @example
+ * ```ts
+ * import { Component, effect } from '@angular/core';
+ * import { pageVisibility } from '@mmstack/primitives';
+ *
+ * @Component({
+ * selector: 'app-visibility-tracker',
+ * template: `<p>Page is currently: {{ visibilityState() }}</p>`
+ * })
+ * export class VisibilityTrackerComponent {
+ * readonly visibilityState = pageVisibility();
+ *
+ * constructor() {
+ * effect(() => {
+ * if (this.visibilityState() === 'hidden') {
+ * console.log('Page is hidden, pausing expensive animations...');
+ * } else {
+ * console.log('Page is visible, resuming activity.');
+ * }
+ * });
+ * }
+ * }
+ * ```
+ */
+function pageVisibility(debugName) {
+    if (isPlatformServer(inject(PLATFORM_ID))) {
+        return computed(() => 'visible', { debugName });
+    }
+    const visibility = signal(document.visibilityState, { debugName });
+    const onVisibilityChange = () => visibility.set(document.visibilityState);
+    document.addEventListener('visibilitychange', onVisibilityChange);
+    inject(DestroyRef).onDestroy(() => document.removeEventListener('visibilitychange', onVisibilityChange));
+    return visibility.asReadonly();
+}
+
+/**
+ * Implementation for sensor overloads.
+ * Users should refer to the specific overloads for detailed documentation.
+ * @internal
+ */
+function sensor(type, options) {
+    switch (type) {
+        case 'mousePosition':
+            return mousePosition(options);
+        case 'networkStatus':
+            return networkStatus(options?.debugName);
+        case 'pageVisibility':
+            return pageVisibility(options?.debugName);
+        case 'dark-mode':
+            return prefersDarkMode(options?.debugName);
+        case 'reduced-motion':
+            return prefersReducedMotion(options?.debugName);
+        default:
+            throw new Error(`Unknown sensor type: ${type}`);
+    }
+}
+
 // Internal dummy store for server-side rendering
 const noopStore = {
     getItem: () => null,
@@ -494,11 +892,160 @@ function stored(fallback, { key, store: providedStore, serialize = JSON.stringif
     return writable;
 }
 
+/**
+ * Creates a Promise that resolves when a signal's value satisfies a given predicate.
+ *
+ * This is useful for imperatively waiting for a reactive state to change,
+ * for example, in tests or to orchestrate complex asynchronous operations.
+ *
+ * @template T The type of the signal's value.
+ * @param sourceSignal The signal to observe.
+ * @param predicate A function that takes the signal's value and returns `true` if the condition is met.
+ * @param options Optional configuration for timeout and explicit destruction.
+ * @returns A Promise that resolves with the signal's value when the predicate is true,
+ * or rejects on timeout or context destruction.
+ *
+ * @example
+ * ```ts
+ * const count = signal(0);
+ *
+ * async function waitForCount() {
+ * console.log('Waiting for count to be >= 3...');
+ * try {
+ * const finalCount = await until(count, c => c >= 3, { timeout: 5000 });
+ * console.log(`Count reached: ${finalCount}`);
+ * } catch (e: any) { // Ensure 'e' is typed if you access properties like e.message
+ * console.error(e.message); // e.g., "until: Timeout after 5000ms."
+ * }
+ * }
+ *
+ * // Simulate updates
+ * setTimeout(() => count.set(1), 500);
+ * setTimeout(() => count.set(2), 1000);
+ * setTimeout(() => count.set(3), 1500);
+ *
+ * waitForCount();
+ * ```
+ */
+function until(sourceSignal, predicate, options = {}) {
+    return new Promise((resolve, reject) => {
+        let effectRef;
+        let timeoutId;
+        let settled = false;
+        const cleanupAndReject = (reason) => {
+            if (!settled) {
+                settled = true;
+                if (timeoutId)
+                    clearTimeout(timeoutId);
+                effectRef?.destroy();
+                reject(new Error(reason));
+            }
+        };
+        const cleanupAndResolve = (value) => {
+            if (!settled) {
+                settled = true;
+                if (timeoutId)
+                    clearTimeout(timeoutId);
+                effectRef?.destroy();
+                resolve(value);
+            }
+        };
+        try {
+            const destroyRef = options.destroyRef ?? inject(DestroyRef, { optional: true });
+            destroyRef?.onDestroy(() => {
+                cleanupAndReject('until: Operation cancelled due to context destruction.');
+            });
+        }
+        catch {
+            // noop
+        }
+        const initialValue = untracked(sourceSignal);
+        if (predicate(initialValue)) {
+            cleanupAndResolve(initialValue);
+            return;
+        }
+        if (options?.timeout !== undefined) {
+            timeoutId = setTimeout(() => cleanupAndReject(`until: Timeout after ${options.timeout}ms.`), options.timeout);
+        }
+        effectRef = effect(() => {
+            if (settled) {
+                return effectRef?.destroy();
+            }
+            const currentValue = sourceSignal();
+            if (predicate(currentValue)) {
+                cleanupAndResolve(currentValue);
+            }
+        });
+    });
+}
+
+/**
+ * @interal
+ */
+function getSignalEquality(sig) {
+    const internal = sig[SIGNAL];
+    if (internal && typeof internal.equal === 'function') {
+        return internal.equal;
+    }
+    return Object.is; // Default equality check
+}
+
+/**
+ * Enhances an existing `WritableSignal` by adding a complete undo/redo history
+ * stack and an API to control it.
+ *
+ * @template T The type of value held by the signal.
+ * @param source The source `WritableSignal` to add history tracking to.
+ * @param options Optional configuration for the history behavior.
+ * @returns A `SignalWithHistory<T>` instance, augmenting the source signal with history APIs.
+ *
+ * @remarks
+ * - Any new `.set()` or `.update()` call on the signal will clear the entire redo stack.
+ * - The primitive attempts to automatically use the source signal's own `equal` function,
+ * but this relies on an internal Angular API. For maximum stability across Angular
+ * versions, it is recommended to provide an explicit `equal` function in the options.
+ *
+ * @example
+ * ```ts
+ * import { signal } from '@angular/core';
+ * import { withHistory } from '@mmstack/primitives';
+ *
+ * const name = withHistory(signal('John'), { maxSize: 5 });
+ *
+ * console.log('Initial value:', name()); // "John"
+ *
+ * name.set('John Doe');
+ * name.set('Jane Doe');
+ *
+ * console.log('Current value:', name()); // "Jane Doe"
+ * console.log('History:', name.history()); // ["John", "John Doe"]
+ * console.log('Can undo:', name.canUndo()); // true
+ * console.log('Can redo:', name.canRedo()); // false
+ *
+ * name.undo();
+ * console.log('After undo:', name()); // "John Doe"
+ * console.log('Can redo:', name.canRedo()); // true
+ *
+ * name.redo();
+ * console.log('After redo:', name()); // "Jane Doe"
+ *
+ * // A new change will clear the redo history
+ * name.set('Janine Doe');
+ * console.log('Can redo:', name.canRedo()); // false
+ *
+ * name.clear();
+ * console.log('Can undo:', name.canUndo()); // false
+ * ```
+ */
 function withHistory(source, opt) {
-    const { equal = Object.is, debugName } = source[SIGNAL];
+    const equal = opt?.equal ?? getSignalEquality(source);
     const maxSize = opt?.maxSize ?? Infinity;
-    const history = mutable([], opt);
+    const history = mutable([], {
+        ...opt,
+        equal: undefined,
+    });
     const redoArray = mutable([]);
+    const originalSet = source.set;
     const set = (value) => {
         const current = untracked(source);
         if (equal(value, current))
@@ -506,7 +1053,12 @@ function withHistory(source, opt) {
         source.set(value);
         history.mutate((c) => {
             if (c.length >= maxSize) {
-                c = c.slice(Math.floor(maxSize / 2));
+                if (opt?.cleanupStrategy === 'shift') {
+                    c.shift();
+                }
+                else {
+                    c = c.slice(Math.floor(maxSize / 2));
+                }
             }
             c.push(current);
             return c;
@@ -518,26 +1070,39 @@ function withHistory(source, opt) {
     };
     const internal = toWritable(computed(() => source(), {
         equal,
-        debugName,
+        debugName: opt?.debugName,
     }), set, update);
     internal.history = history;
     internal.undo = () => {
-        const last = untracked(history);
-        if (last.length === 0)
+        const historyStack = untracked(history);
+        if (historyStack.length === 0)
             return;
-        const prev = last.at(-1);
-        const cur = untracked(source);
-        history.inline((c) => c.pop());
-        redoArray.inline((c) => c.push(cur));
-        source.set(prev);
+        const valueForRedo = untracked(source);
+        const valueToRestore = historyStack.at(-1);
+        originalSet.call(source, valueToRestore);
+        history.inline((h) => h.pop());
+        redoArray.inline((r) => r.push(valueForRedo));
     };
     internal.redo = () => {
-        const last = untracked(redoArray);
-        if (last.length === 0)
+        const redoStack = untracked(redoArray);
+        if (redoStack.length === 0)
             return;
-        const prev = last.at(-1);
-        redoArray.inline((c) => c.pop());
-        set(prev);
+        const valueForUndo = untracked(source);
+        const valueToRestore = redoStack.at(-1);
+        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.push(valueForUndo);
+            return h;
+        });
     };
     internal.clear = () => {
         history.set([]);
@@ -553,5 +1118,5 @@ function withHistory(source, opt) {
  * Generated bundle index. Do not edit.
  */
 
-export { debounce, debounced, derived, isDerivation, isMutable, mapArray, mutable, stored, toFakeDerivation, toFakeSignalDerivation, toWritable, withHistory };
+export { debounce, debounced, derived, isDerivation, isMutable, mapArray, mediaQuery, mousePosition, mutable, networkStatus, pageVisibility, prefersDarkMode, prefersReducedMotion, sensor, stored, throttle, throttled, toFakeDerivation, toFakeSignalDerivation, toWritable, until, withHistory };
 //# sourceMappingURL=mmstack-primitives.mjs.map