@mmstack/primitives 19.1.1 → 19.2.0

package/lib/sensors/mouse-position.d.ts

@@ -0,0 +1,75 @@
+import { ElementRef, Signal } from '@angular/core';
+type MousePosition = {
+    x: number;
+    y: number;
+};
+/**
+ * Options for configuring the `mousePosition` sensor.
+ */
+export type MousePositionOptions = {
+    /**
+     * The target element to listen for mouse movements on.
+     * Can be `window`, `document`, an `HTMLElement`, or an `ElementRef<HTMLElement>`.
+     * @default window
+     */
+    target?: Window | Document | HTMLElement | ElementRef<HTMLElement>;
+    /**
+     * Defines the coordinate system for the reported position.
+     * - `'client'`: Coordinates relative to the viewport (`clientX`, `clientY`).
+     * - `'page'`: Coordinates relative to the entire document (`pageX`, `pageY`).
+     * @default 'client'
+     */
+    coordinateSpace?: 'client' | 'page';
+    /**
+     * If `true`, the sensor will also listen to `touchmove` events and report
+     * the coordinates of the first touch point.
+     * @default false
+     */
+    touch?: boolean;
+    /**
+     * Optional debug name for the internal signal.
+     */
+    debugName?: string;
+    /**
+     * Optional delay in milliseconds to throttle the updates.
+     * @default 100
+     */
+    throttle?: number;
+};
+export type MousePositionSignal = Signal<MousePosition> & {
+    readonly unthrottled: Signal<MousePosition>;
+};
+/**
+ * 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());
+ * });
+ * }
+ * }
+ * ```
+ */
+export declare function mousePosition(opt?: MousePositionOptions): MousePositionSignal;
+export {};

package/lib/sensors/network-status.d.ts

@@ -0,0 +1,20 @@
+import { Signal } from '@angular/core';
+/**
+ * A specialized Signal that tracks network status.
+ * It's a boolean signal with an attached `since` signal.
+ */
+export type NetworkStatusSignal = Signal<boolean> & {
+    /** A signal tracking the timestamp of the last status change. */
+    readonly since: Signal<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.
+ */
+export declare function networkStatus(debugName?: string): NetworkStatusSignal;

package/lib/sensors/page-visibility.d.ts

@@ -0,0 +1,38 @@
+import { Signal } from '@angular/core';
+/**
+ * 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.');
+ * }
+ * });
+ * }
+ * }
+ * ```
+ */
+export declare function pageVisibility(debugName?: string): Signal<DocumentVisibilityState>;

package/lib/sensors/sensor.d.ts

@@ -0,0 +1,56 @@
+import { Signal } from '@angular/core';
+import { MousePositionOptions, MousePositionSignal } from './mouse-position';
+import { NetworkStatusSignal } from './network-status';
+/**
+ * Creates a sensor signal that tracks the mouse cursor's position.
+ * @param type Must be `'mousePosition'`.
+ * @param options Optional configuration for the mouse position sensor.
+ * @returns A `MousePositionSignal` that tracks mouse coordinates and provides an unthrottled version.
+ * @see {mousePosition} for detailed documentation and examples.
+ * @example const pos = sensor('mousePosition', { coordinateSpace: 'page', throttle: 50 });
+ */
+export declare function sensor(type: 'mousePosition', options?: MousePositionOptions): MousePositionSignal;
+/**
+ * Creates a sensor signal that tracks the browser's online/offline status.
+ * @param type Must be `'networkStatus'`.
+ * @param options Optional configuration, currently only `debugName`.
+ * @returns A `NetworkStatusSignal` which is a boolean indicating online status, with an attached `since` signal.
+ * @see {networkStatus} for detailed documentation and examples.
+ * @example const onlineStatus = sensor('networkStatus');
+ */
+export declare function sensor(type: 'networkStatus', options?: {
+    debugName?: string;
+}): NetworkStatusSignal;
+/**
+ * Creates a sensor signal that tracks the page's visibility state (e.g., 'visible', 'hidden').
+ * @param type Must be `'pageVisibility'`.
+ * @param options Optional configuration, currently only `debugName`.
+ * @returns A `Signal<DocumentVisibilityState>` indicating the page's current visibility.
+ * @see {pageVisibility} for detailed documentation and examples.
+ * @example const visibility = sensor('pageVisibility');
+ */
+export declare function sensor(type: 'pageVisibility', options?: {
+    debugName?: string;
+}): Signal<DocumentVisibilityState>;
+/**
+ * Creates a sensor signal that tracks the user's OS/browser preference for a dark color scheme.
+ * @param type Must be `'dark-mode'`.
+ * @param options Optional configuration, currently only `debugName`.
+ * @returns A `Signal<boolean>` which is `true` if a dark theme is preferred.
+ * @see {prefersDarkMode} for detailed documentation and examples.
+ * @example const isDarkMode = sensor('dark-mode');
+ */
+export declare function sensor(type: 'dark-mode', options?: {
+    debugName?: string;
+}): Signal<boolean>;
+/**
+ * Creates a sensor signal that tracks the user's OS/browser preference for reduced motion.
+ * @param type Must be `'reduced-motion'`.
+ * @param options Optional configuration, currently only `debugName`.
+ * @returns A `Signal<boolean>` which is `true` if reduced motion is preferred.
+ * @see {prefersReducedMotion} for detailed documentation and examples.
+ * @example const wantsReducedMotion = sensor('reduced-motion');
+ */
+export declare function sensor(type: 'reduced-motion', options?: {
+    debugName?: string;
+}): Signal<boolean>;

package/lib/stored.d.ts

@@ -51,6 +51,16 @@ export type CreateStoredOptions<T> = CreateSignalOptions<T> & {
      * Requires a browser environment. Defaults to `false`.
      */
     syncTabs?: boolean;
+    /**
+     * Optional parameter to specify how key changes should be handled, load is the default.
+     * - `load`: The signal will load the value from storage when the key changes & replace the signal's value.
+     * - `store`: The signal will store the current value to the new key when the key changes.
+     */
+    onKeyChange?: 'load' | 'store';
+    /**
+     * If 'true', the signal will remove the old key from storage when the key changes, defaults to `false`.
+     */
+    cleanupOldKey?: boolean;
 };
 /**
  * A specialized `WritableSignal` returned by the `stored()` function.
@@ -122,5 +132,5 @@ export type StoredSignal<T> = WritableSignal<T> & {
  * }
  * ```
  */
-export declare function stored<T>(fallback: T, { key, store: providedStore, serialize, deserialize, syncTabs, equal, ...rest }: CreateStoredOptions<T>): StoredSignal<T>;
+export declare function stored<T>(fallback: T, { key, store: providedStore, serialize, deserialize, syncTabs, equal, onKeyChange, cleanupOldKey, ...rest }: CreateStoredOptions<T>): StoredSignal<T>;
 export {};

package/lib/throttled.d.ts

@@ -0,0 +1,75 @@
+import { type CreateSignalOptions, DestroyRef, type WritableSignal } from '@angular/core';
+import { DebouncedSignal } from './debounced';
+/**
+ * Options for creating a throttled writable signal.
+ * Extends Angular's `CreateSignalOptions` with a throttle time setting.
+ *
+ * @template T The type of value held by the signal.
+ */
+export type CreateThrottledOptions<T> = CreateSignalOptions<T> & {
+    /**
+     * The throttle delay in milliseconds. The minimum time
+     * in milliseconds that must pass between updates to the throttled signal's value.
+     */
+    ms?: number;
+    /**
+     * Optional `DestroyRef` to clean up the throttle timer when the signal is destroyed.
+     * If provided, the timer will be cleared when the signal is destroyed.
+     * If the signal is called within a reactive context a DestroyRef is injected automatically.
+     * If it is not provided or injected, the timer will not be cleared automatically...which is usually fine :)
+     */
+    destroyRef?: DestroyRef;
+};
+/**
+ * A specialized `WritableSignal` whose publicly readable value updates are throttled.
+ *
+ * It provides access to the underlying, non-throttled signal via the `original` property.
+ *
+ * @template T The type of value held by the signal.
+ * @see {DebouncedSignal} as the output type has the same structure.
+ */
+export type ThrottledSignal<T> = DebouncedSignal<T>;
+/**
+ * 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.
+ */
+export declare function throttled<T>(initial: T, opt?: CreateThrottledOptions<T>): DebouncedSignal<T>;
+/**
+ * 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.
+ */
+export declare function throttle<T>(source: WritableSignal<T>, opt?: CreateThrottledOptions<T>): ThrottledSignal<T>;

package/lib/until.d.ts

@@ -0,0 +1,50 @@
+import { DestroyRef, Signal } from '@angular/core';
+export type UntilOptions = {
+    /**
+     * Optional timeout in milliseconds. If the condition is not met
+     * within this period, the promise will reject.
+     */
+    timeout?: number;
+    /**
+     * Optional DestroyRef. If provided and the component/context is destroyed
+     * before the condition is met or timeout occurs, the promise will reject.
+     * If not provided, it will attempt to inject one if called in an injection context.
+     */
+    destroyRef?: DestroyRef;
+};
+/**
+ * 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();
+ * ```
+ */
+export declare function until<T>(sourceSignal: Signal<T>, predicate: (value: T) => boolean, options?: UntilOptions): Promise<T>;

package/lib/with-history.d.ts

@@ -1,14 +1,94 @@
-import { type CreateSignalOptions, type Signal, type WritableSignal } from '@angular/core';
+import { type CreateSignalOptions, type Signal, type ValueEqualityFn, type WritableSignal } from '@angular/core';
+/**
+ * A WritableSignal enhanced with undo/redo capabilities and history tracking.
+ *
+ * @template T The type of value held by the signal.
+ */
 export type SignalWithHistory<T> = WritableSignal<T> & {
+    /** A read-only signal of the undo history stack. The oldest changes are at the start of the array. */
     history: Signal<T[]>;
+    /** Reverts the signal to its most recent previous state in the history. */
     undo: () => void;
+    /** Re-applies the last state that was undone. */
     redo: () => void;
+    /** A signal that is `true` if there are states in the redo stack. */
     canRedo: Signal<boolean>;
+    /** A signal that is `true` if there are states in the undo history. */
     canUndo: Signal<boolean>;
+    /** Clears both the undo and redo history stacks. */
     clear: () => void;
+    /** A signal that is `true` if there is any history that can be cleared. */
     canClear: Signal<boolean>;
 };
+/**
+ * Options for creating a signal with history tracking.
+ *
+ * @template T The type of value held by the signal.
+ */
 export type CreateHistoryOptions<T> = Omit<CreateSignalOptions<T[]>, 'equal'> & {
+    /**
+     * Optional custom equality function to determine if a value has changed before
+     * adding it to history. Defaults to the source signal's equality function or `Object.is`.
+     */
+    equal?: ValueEqualityFn<T>;
+    /**
+     * The maximum number of undo states to keep in the history.
+     * @default Infinity
+     */
     maxSize?: number;
+    /**
+     * The strategy for trimming the history when `maxSize` is reached.
+     * - `shift`: Removes the single oldest entry from the history.
+     * - `halve`: Removes the oldest half of the history stack.
+     * @default 'halve'
+     */
+    cleanupStrategy?: 'shift' | 'halve';
 };
+/**
+ * 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
+ * ```
+ */
 export declare function withHistory<T>(source: WritableSignal<T>, opt?: CreateHistoryOptions<T>): SignalWithHistory<T>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmstack/primitives",
-  "version": "19.1.1",
+  "version": "19.2.0",
   "keywords": [
     "angular",
     "signals",