@mmstack/primitives 19.2.3 → 20.0.1

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

@@ -1,20 +0,0 @@
-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

@@ -1,38 +0,0 @@
-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/scroll-position.d.ts

@@ -1,84 +0,0 @@
-import { ElementRef, // Used for SSR fallback
-type Signal } from '@angular/core';
-/**
- * Represents the scroll position.
- */
-export type ScrollPosition = {
-    /** The horizontal scroll position (pixels from the left). */
-    readonly x: number;
-    /** The vertical scroll position (pixels from the top). */
-    readonly y: number;
-};
-/**
- * Options for configuring the `scrollPosition` sensor.
- */
-export type ScrollPositionOptions = {
-    /**
-     * The target to listen for scroll events on.
-     * Can be `window` (for page scroll) or an `HTMLElement`/`ElementRef<HTMLElement>`.
-     * @default window
-     */
-    target?: Window | HTMLElement | ElementRef<HTMLElement>;
-    /**
-     * Optional delay in milliseconds to throttle the updates.
-     * Scroll events can fire very rapidly.
-     * @default 100 // A common default for scroll throttling
-     */
-    throttle?: number;
-    /** Optional debug name for the internal signal. */
-    debugName?: string;
-};
-/**
- * A specialized Signal that tracks scroll position.
- * It's a throttled signal of the scroll coordinates with an attached `unthrottled` signal.
- */
-export type ScrollPositionSignal = Signal<ScrollPosition> & {
-    /** A signal providing the raw, unthrottled scroll position. */
-    readonly unthrottled: Signal<ScrollPosition>;
-};
-/**
- * Creates a read-only signal that tracks the scroll position (x, y) of the window
- * or a specified HTML element.
- *
- * Updates are throttled by default to optimize performance. An `unthrottled`
- * property is available on the returned signal for direct access to raw updates.
- * The primitive is SSR-safe and automatically cleans up its event listeners.
- *
- * @param options Optional configuration for the scroll sensor.
- * @returns A `ScrollPositionSignal`. On the server, it returns a static
- * signal with `{ x: 0, y: 0 }`.
- *
- * @example
- * ```ts
- * import { Component, effect, ElementRef, viewChild } from '@angular/core';
- * import { scrollPosition } from '@mmstack/primitives';
- *
- * @Component({
- * selector: 'app-scroll-tracker',
- * template: `
- * <p>Window Scroll: X: {{ windowScroll().x }}, Y: {{ windowScroll().y }}</p>
- * <div #scrollableDiv style="height: 200px; width: 200px; overflow: auto; border: 1px solid black;">
- * <div style="height: 400px; width: 400px;">Scroll me!</div>
- * </div>
- * @if (divScroll()) {
- * <p>Div Scroll: X: {{ divScroll().x }}, Y: {{ divScroll().y }}</p>
- * }
- * `
- * })
- * export class ScrollTrackerComponent {
- * readonly windowScroll = scrollPosition(); // Defaults to window
- * readonly scrollableDiv = viewChild<ElementRef<HTMLDivElement>>('scrollableDiv');
- * readonly divScroll = scrollPosition({ target: this.scrollableDiv() }); // Example with element target
- *
- * constructor() {
- * effect(() => {
- * console.log('Window scrolled to:', this.windowScroll());
- * if (this.divScroll()) {
- * console.log('Div scrolled to:', this.divScroll());
- * }
- * });
- * }
- * }
- * ```
- */
-export declare function scrollPosition(opt?: ScrollPositionOptions): ScrollPositionSignal;

package/lib/sensors/sensor.d.ts

@@ -1,76 +0,0 @@
-import { Signal } from '@angular/core';
-import { MousePositionOptions, MousePositionSignal } from './mouse-position';
-import { NetworkStatusSignal } from './network-status';
-import { ScrollPositionOptions, ScrollPositionSignal } from './scroll-position';
-import { WindowSizeOptions, WindowSizeSignal } from './window-size';
-/**
- * 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>;
-/**
- * Creates a sensor signal that tracks the browser window's inner dimensions (width and height).
- * @param type Must be `'windowSize'`.
- * @param options Optional configuration for the window size sensor, including `throttle` and `debugName`.
- * @returns A `WindowSizeSignal` that tracks window dimensions and provides an unthrottled version.
- * @see {windowSize} for detailed documentation and examples.
- * @example const size = sensor('windowSize', { throttle: 200 });
- */
-export declare function sensor(type: 'windowSize', options?: WindowSizeOptions): WindowSizeSignal;
-/**
- * Creates a sensor signal that tracks the scroll position (x, y) of the window or a specified element.
- * @param type Must be `'scrollPosition'`.
- * @param options Optional configuration for the scroll position sensor, including `target`, `throttle`, and `debugName`.
- * @returns A `ScrollPositionSignal` that tracks scroll coordinates and provides an unthrottled version.
- * @see {scrollPosition} for detailed documentation and examples.
- * @example const pageScroll = sensor('scrollPosition', { throttle: 150 });
- */
-export declare function sensor(type: 'scrollPosition', options?: ScrollPositionOptions): ScrollPositionSignal;

package/lib/sensors/window-size.d.ts

@@ -1,75 +0,0 @@
-import { Signal } from '@angular/core';
-/**
- * Represents the dimensions of the window.
- */
-export type WindowSize = {
-    /** The current inner width of the window in pixels. */
-    readonly width: number;
-    /** The current inner height of the window in pixels. */
-    readonly height: number;
-};
-/**
- * Options for configuring the `mousePosition` sensor.
- */
-export type WindowSizeOptions = {
-    /**
-     * Optional debug name for the internal signal.
-     */
-    debugName?: string;
-    /**
-     * Optional delay in milliseconds to throttle the updates.
-     * @default 100
-     */
-    throttle?: number;
-};
-/**
- * A specialized Signal that tracks window size.
- * It's a throttled signal of the window.innerHeight/innerWidth properties
- * with an attached `unthrottled` signal.
- */
-export type WindowSizeSignal = Signal<WindowSize> & {
-    /** A signal providing the raw, unthrottled window size. */
-    readonly unthrottled: Signal<WindowSize>;
-};
-/**
- * Creates a read-only signal that tracks the browser window's inner dimensions (width and height).
- *
- * Updates are throttled by default (100ms) to optimize performance during resize events.
- * An `unthrottled` property is available on the returned signal for direct access to raw updates.
- * The primitive is SSR-safe (returns a default size on the server) and automatically
- * cleans up its event listeners.
- *
- * @param opt Optional configuration, including `throttle` (ms) and `debugName`.
- * @returns A `WindowSizeSignal` (a `Signal<WindowSize>` with an `unthrottled` property).
- *
- * @example
- * ```ts
- * import { Component, effect } from '@angular/core';
- * import { windowSize } from '@mmstack/primitives';
- *
- * @Component({
- * selector: 'app-responsive-header',
- * template: `
- * <header>
- * Current Window Size: {{ size().width }}px x {{ size().height }}px
- * @if (isMobile()) {
- * <p>Mobile Menu</p>
- * } @else {
- * <p>Desktop Menu</p>
- * }
- * </header>
- * `
- * })
- * export class ResponsiveHeaderComponent {
- * readonly size = windowSize();
- * readonly isMobile = computed(() => this.size().width < 768);
- *
- * constructor() {
- * effect(() => {
- * console.log('Window resized to:', this.size());
- * });
- * }
- * }
- * ```
- */
-export declare function windowSize(opt?: WindowSizeOptions): WindowSizeSignal;

package/lib/stored.d.ts

@@ -1,136 +0,0 @@
-import { Signal, type CreateSignalOptions, type WritableSignal } from '@angular/core';
-/**
- * Interface for storage mechanisms compatible with the `stored` signal.
- * Matches the essential parts of the `Storage` interface (`localStorage`, `sessionStorage`).
- */
-type Store = {
-    /** Retrieves an item from storage for a given key. */
-    getItem: (key: string) => string | null;
-    /** Sets an item in storage for a given key. */
-    setItem: (key: string, value: string) => void;
-    /** Removes an item from storage for a given key. */
-    removeItem: (key: string) => void;
-};
-/**
- * Options for creating a signal synchronized with persistent storage using `stored()`.
- * Extends Angular's `CreateSignalOptions`.
- *
- * @template T The type of value held by the signal.
- */
-export type CreateStoredOptions<T> = CreateSignalOptions<T> & {
-    /**
-     * The key used to identify the item in storage.
-     * Can be a static string or a function/signal returning a string for dynamic keys
-     * (e.g., based on user ID or other application state).
-     */
-    key: string | (() => string);
-    /**
-     * Optional custom storage implementation (e.g., `sessionStorage` or a custom adapter).
-     * Must conform to the `Store` interface (`getItem`, `setItem`, `removeItem`).
-     * Defaults to `localStorage` in browser environments and a no-op store on the server.
-     */
-    store?: Store;
-    /**
-     * Optional function to serialize the value (type `T`) into a string before storing.
-     * Defaults to `JSON.stringify`.
-     * @param {T} value The value to serialize.
-     * @returns {string} The serialized string representation.
-     */
-    serialize?: (value: T) => string;
-    /**
-     * Optional function to deserialize the string retrieved from storage back into the value (type `T`).
-     * Defaults to `JSON.parse`.
-     * @param {string} value The string retrieved from storage.
-     * @returns {T} The deserialized value.
-     */
-    deserialize?: (value: string) => T;
-    /**
-     * If `true`, the signal will attempt to synchronize its state across multiple browser tabs
-     * using the `storage` event. Changes made in one tab (set, update, clear) will be
-     * reflected in other tabs using the same storage key.
-     * 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.
- * It synchronizes its value with persistent storage and provides additional methods.
- *
- * @template T The type of value held by the signal (matches the fallback type).
- */
-export type StoredSignal<T> = WritableSignal<T> & {
-    /**
-     * Removes the item associated with the signal's key from the configured storage.
-     * After clearing, reading the signal will return the fallback value until it's set again.
-     */
-    clear: () => void;
-    /**
-     * A `Signal<string>` containing the current storage key being used by this stored signal.
-     * This is particularly useful if the key was configured dynamically. You can read or react
-     * to this signal to know the active key.
-     */
-    key: Signal<string>;
-};
-/**
- * Creates a `WritableSignal` whose state is automatically synchronized with persistent storage
- * (like `localStorage` or `sessionStorage`).
- *
- * It handles Server-Side Rendering (SSR) gracefully, allows dynamic storage keys,
- * custom serialization/deserialization, custom storage providers, and optional
- * synchronization across browser tabs.
- *
- * @template T The type of value held by the signal and stored (after serialization).
- * @param fallback The default value of type `T` to use when no value is found in storage
- * or when deserialization fails. The signal's value will never be `null` or `undefined`
- * publicly, it will always revert to this fallback.
- * @param options Configuration options (`CreateStoredOptions<T>`). Requires at least the `key`.
- * @returns A `StoredSignal<T>` instance. This signal behaves like a standard `WritableSignal<T>`,
- * but its value is persisted. It includes a `.clear()` method to remove the item from storage
- * and a `.key` signal providing the current storage key.
- *
- * @remarks
- * - **Persistence:** The signal automatically saves its value to storage whenever the signal's
- * value or its configured `key` changes. This is managed internally using `effect`.
- * - **SSR Safety:** Detects server environments and uses a no-op storage, preventing errors.
- * - **Error Handling:** Catches and logs errors during serialization/deserialization in dev mode.
- * - **Tab Sync:** If `syncTabs` is true, listens to `storage` events to keep the signal value
- * consistent across browser tabs using the same key. Cleanup is handled automatically
- * using `DestroyRef`.
- * - **Removal:** Use the `.clear()` method on the returned signal to remove the item from storage.
- * Setting the signal to the fallback value will store the fallback value, not remove the item.
- *
- * @example
- * ```ts
- * import { Component, effect, signal } from '@angular/core';
- * import { stored } from '@mmstack/primitives'; // Adjust import path
- *
- * @Component({
- * selector: 'app-settings',
- * standalone: true,
- * template: `
- * Theme:
- * <select [ngModel]="theme()" (ngModelChange)="theme.set($event)">
- * <option value="light">Light</option>
- * <option value="dark">Dark</option>
- * </select>
- * <button (click)="theme.clear()">Clear Theme Setting</button>
- * <p>Storage Key Used: {{ theme.key() }}</p>
- * ` // Requires FormsModule for ngModel
- * })
- * export class SettingsComponent {
- *  theme = stored<'light' | 'dark'>('light', { key: 'app-theme', syncTabs: true });
- * }
- * ```
- */
-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

@@ -1,75 +0,0 @@
-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/to-writable.d.ts

@@ -1,30 +0,0 @@
-import { Signal, WritableSignal } from '@angular/core';
-/**
- * Converts a read-only `Signal` into a `WritableSignal` by providing custom `set` and, optionally, `update` functions.
- * This can be useful for creating controlled write access to a signal that is otherwise read-only.
- *
- * @typeParam T - The type of value held by the signal.
- *
- * @param signal - The read-only `Signal` to be made writable.
- * @param set - A function that will be used to set the signal's value.  This function *must* handle
- *              the actual update mechanism (e.g., updating a backing store, emitting an event, etc.).
- * @param update - (Optional) A function that will be used to update the signal's value based on its
- *                 previous value.  If not provided, a default `update` implementation is used that
- *                 calls the provided `set` function with the result of the updater function. The
- *                 default implementation uses `untracked` to avoid creating unnecessary dependencies
- *                 within the updater function.
- *
- * @returns A `WritableSignal` that uses the provided `set` and `update` functions.  The `asReadonly`
- *          method of the returned signal will still return the original read-only signal.
- *
- * @example
- * // Basic usage: Making a read-only signal writable with a custom set function.
- * const originalValue = signal({a: 0});
- * const readOnlySignal = computed(() => originalValue().a);
- * const writableSignal = toWritable(readOnlySignal, (newValue) => {
- *  originalValue.update((prev) => { ...prev, a: newValue });
- * });
- *
- * writableSignal.set(5); // sets value of originalValue.a to 5 & triggers all signals
- */
-export declare function toWritable<T>(signal: Signal<T>, set: (value: T) => void, update?: (updater: (value: T) => T) => void): WritableSignal<T>;

package/lib/until.d.ts

@@ -1,51 +0,0 @@
-import { DestroyRef, Injector, 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;
-    injector?: Injector;
-};
-/**
- * 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>;