@mmstack/primitives 19.2.3 → 20.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmstack/primitives",
-  "version": "19.2.3",
+  "version": "20.0.0",
   "keywords": [
     "angular",
     "signals",
@@ -15,12 +15,12 @@
   },
   "homepage": "https://github.com/mihajm/mmstack/blob/master/packages/primitives",
   "dependencies": {
-    "@mmstack/object": "^19.2.0",
+    "@mmstack/object": "^20.0.0",
     "tslib": "^2.3.0"
   },
   "peerDependencies": {
-    "@angular/core": "~19.2.3",
-    "@angular/common": "~19.2.3"
+    "@angular/core": "~20.0.3",
+    "@angular/common": "~20.0.3"
   },
   "sideEffects": false,
   "module": "fesm2022/mmstack-primitives.mjs",

package/lib/debounced.d.ts

@@ -1,97 +0,0 @@
-import { type CreateSignalOptions, DestroyRef, type Signal, type WritableSignal } from '@angular/core';
-/**
- * Options for creating a debounced writable signal.
- * Extends Angular's `CreateSignalOptions` with a debounce time setting.
- *
- * @template T The type of value held by the signal.
- */
-export type CreateDebouncedOptions<T> = CreateSignalOptions<T> & {
-    /**
-     * The debounce delay in milliseconds. Specifies how long to wait after the
-     * last `set` or `update` call before the debounced signal reflects the new value.
-     */
-    ms?: number;
-    /**
-     * Optional `DestroyRef` to clean up the debounce 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 debounced.
- *
- * It provides access to the underlying, non-debounced signal via the `original` property.
- *
- * @template T The type of value held by the signal.
- */
-export type DebouncedSignal<T> = WritableSignal<T> & {
-    /**
-     * A reference to the original, inner `WritableSignal`.
-     * This signal's value is updated *immediately* upon calls to `set` or `update`
-     * on the parent `DebouncedSignal`. Useful for accessing the latest value
-     * without the debounce delay.
-     */
-    original: Signal<T>;
-};
-/**
- * A convenience function that creates and debounces a new `WritableSignal` in one step.
- *
- * @see {debounce} 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 debounce time `ms`.
- * @returns A `DebouncedSignal<T>` instance.
- *
- * @example
- * // The existing example remains perfect here.
- * const query = debounced('', { ms: 500 });
- * effect(() => console.log('Debounced Query:', query()));
- * query.set('abc');
- * // ...500ms later...
- * // Output: Debounced Query: abc
- */
-export declare function debounced<T>(initial: T, opt?: CreateDebouncedOptions<T>): DebouncedSignal<T>;
-/**
- * Wraps an existing `WritableSignal` to create a new one whose readable value is debounced.
- *
- * This implementation avoids using `effect` by pairing a trigger signal with an `untracked`
- * read of the source signal to control when the debounced 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 debouncing, including debounce time `ms` and an optional `DestroyRef`.
- * @returns A new `DebouncedSignal<T>` whose read value is debounced. The `.original` property
- * of the returned signal is a reference back to the provided `source` signal.
- *
- * @example
- * ```ts
- * import { signal, effect } from '@angular/core';
- *
- * // 1. Create a standard source signal.
- * const sourceQuery = signal('');
- *
- * // 2. Create a debounced version of it.
- * const debouncedQuery = debounce(sourceQuery, { ms: 500 });
- *
- * // This effect tracks the original signal and runs immediately.
- * effect(() => {
- * console.log('Original Query:', debouncedQuery.original());
- * });
- *
- * // This effect tracks the debounced signal and runs after the delay.
- * effect(() => {
- * console.log('Debounced Query:', debouncedQuery());
- * });
- *
- * console.log('Setting query to "a"');
- * debouncedQuery.set('a');
- * // Output: Original Query: a
- *
- * // ...500ms later...
- * // Output: Debounced Query: a
- * ```
- */
-export declare function debounce<T>(source: WritableSignal<T>, opt?: CreateDebouncedOptions<T>): DebouncedSignal<T>;

package/lib/derived.d.ts

@@ -1,139 +0,0 @@
-import { CreateSignalOptions, type WritableSignal } from '@angular/core';
-import type { UnknownObject } from '@mmstack/object';
-/**
- * Options for creating a derived signal using the full `derived` function signature.
- * @typeParam T - The type of the source signal's value (parent).
- * @typeParam U - The type of the derived signal's value (child).
- */
-type CreateDerivedOptions<T, U> = CreateSignalOptions<U> & {
-    /**
-     * A function that extracts the derived value (`U`) from the source signal's value (`T`).
-     */
-    from: (v: T) => U;
-    /**
-     * A function that updates the source signal's value (`T`) when the derived signal's value (`U`) changes.
-     * This establishes the two-way binding.
-     */
-    onChange: (newValue: U) => void;
-};
-/**
- * A `WritableSignal` that derives its value from another `WritableSignal` (the "source" signal).
- * It provides two-way binding: changes to the source signal update the derived signal, and
- * changes to the derived signal update the source signal.
- *
- * @typeParam T - The type of the source signal's value (parent).
- * @typeParam U - The type of the derived signal's value (child).
- */
-export type DerivedSignal<T, U> = WritableSignal<U> & {
-    /**
-     * The function used to derive the derived signal's value from the source signal's value.
-     * This is primarily for internal use and introspection.
-     */
-    from: (v: T) => U;
-};
-/**
- * Creates a `DerivedSignal` that derives its value from another `WritableSignal`.
- * This overload provides the most flexibility, allowing you to specify custom `from` and `onChange` functions.
- *
- * @typeParam T The type of the source signal's value.
- * @typeParam U The type of the derived signal's value.
- * @param source The source `WritableSignal`.
- * @param options An object containing the `from` and `onChange` functions, and optional signal options.
- * @returns A `DerivedSignal` instance.
- *
- * @example
- * ```ts
- * const user = signal({ name: 'John', age: 30 });
- * const name = derived(user, {
- * from: (u) => u.name,
- * onChange: (newName) => user.update((u) => ({ ...u, name: newName })),
- * });
- *
- * name.set('Jane'); // Updates the original signal
- * console.log(user().name); // Outputs: Jane
- * ```
- */
-export declare function derived<T, U>(source: WritableSignal<T>, opt: CreateDerivedOptions<T, U>): DerivedSignal<T, U>;
-/**
- * Creates a `DerivedSignal` that derives a property from an object held by the source signal.
- * This overload is a convenient shorthand for accessing object properties.
- *
- * @typeParam T The type of the source signal's value (must be an object).
- * @typeParam TKey The key of the property to derive.
- * @param source The source `WritableSignal` (holding an object).
- * @param key The key of the property to derive.
- * @param options Optional signal options for the derived signal.
- * @returns A `DerivedSignal` instance.
- *
- * @example
- * ```ts
- * const user = signal({ name: 'John', age: 30 });
- * const name = derived(user, 'name');
- *
- * console.log(name()); // Outputs: John
- *
- * // Update the derived signal, which also updates the source
- * name.set('Jane');
- *
- * console.log(user().name); // Outputs: Jane
- * ```
- */
-export declare function derived<T extends UnknownObject, TKey extends keyof T>(source: WritableSignal<T>, key: TKey, opt?: CreateSignalOptions<T[TKey]>): DerivedSignal<T, T[TKey]>;
-/**
- * Creates a `DerivedSignal` from an array, deriving an element by its index.
- * This overload is a convenient shorthand for accessing array elements.
- *
- * @typeParam T The type of the source signal's value (must be an array).
- * @param source The source `WritableSignal` (holding an array).
- * @param index The index of the element to derive.
- * @param options Optional signal options for the derived signal.
- * @returns A `DerivedSignal` instance.
- *
- * @example
- * ```ts
- * const numbers = signal([1, 2, 3]);
- * const secondNumber = derived(numbers, 1);
- *
- * console.log(secondNumber()); // Outputs: 2
- *
- * // Update the derived signal, which also updates the source
- * secondNumber.set(5);
- *
- * console.log(numbers()); // Outputs: [1, 5, 3]
- * ```
- */
-export declare function derived<T extends any[]>(source: WritableSignal<T>, index: number, opt?: CreateSignalOptions<T[number]>): DerivedSignal<T, T[number]>;
-/**
- * Creates a "fake" `DerivedSignal` from a simple value. This is useful for creating
- * `FormControlSignal` instances that are not directly derived from another signal.
- * The returned signal's `from` function will always return the initial value.
- *
- * @typeParam T -  This type parameter is not used in the implementation but is kept for type compatibility with `DerivedSignal`.
- * @typeParam U - The type of the signal's value.
- * @param initial - The initial value of the signal.
- * @returns A `DerivedSignal` instance.
- * @internal
- */
-export declare function toFakeDerivation<T, U>(initial: U): DerivedSignal<T, U>;
-/**
- * Creates a "fake" `DerivedSignal` from an existing `WritableSignal`. This is useful
- * for treating a regular `WritableSignal` as a `DerivedSignal` without changing its behavior.
- *  The returned signal's `from` function returns the current value of signal, using `untracked`.
- *
- * @typeParam T - This type parameter is not used in the implementation but is kept for type compatibility with `DerivedSignal`.
- * @typeParam U - The type of the signal's value.
- * @param initial - The existing `WritableSignal`.
- * @returns A `DerivedSignal` instance.
- * @internal
- */
-export declare function toFakeSignalDerivation<T, U>(initial: WritableSignal<U>): DerivedSignal<T, U>;
-/**
- * Type guard function to check if a given `WritableSignal` is a `DerivedSignal`.
- *
- * @typeParam T - The type of the source signal's value (optional, defaults to `any`).
- * @typeParam U - The type of the derived signal's value (optional, defaults to `any`).
- * @param sig - The `WritableSignal` to check.
- * @returns `true` if the signal is a `DerivedSignal`, `false` otherwise.
- */
-export declare function isDerivation<T, U>(sig: WritableSignal<U>): sig is DerivedSignal<T, U>;
-export {};

package/lib/element-visibility.d.ts

@@ -1,66 +0,0 @@
-import { ElementRef, Signal } from '@angular/core';
-/**
- * Options for configuring the `elementVisibility` sensor, extending
- * standard `IntersectionObserverInit` options.
- */
-export type ElementVisibilityOptions = IntersectionObserverInit & {
-    /** Optional debug name for the internal signal. */
-    debugName?: string;
-};
-export type ElementVisibilitySignal = Signal<IntersectionObserverEntry | undefined> & {
-    readonly visible: Signal<boolean>;
-};
-/**
- * Creates a read-only signal that tracks the intersection status of a target DOM element
- * with the viewport or a specified root element, using the `IntersectionObserver` API.
- *
- * It can observe a static `ElementRef`/`Element` or a `Signal` that resolves to one,
- * allowing for dynamic targets.
- *
- * @param target The DOM element (or `ElementRef`, or a `Signal` resolving to one) to observe.
- * If the signal resolves to `null`, observation stops.
- * @param options Optional `IntersectionObserverInit` options (e.g., `root`, `rootMargin`, `threshold`)
- * and an optional `debugName`.
- * @returns A `Signal<IntersectionObserverEntry | undefined>`. It emits `undefined` initially,
- * on the server, or if the target is `null`. Otherwise, it emits the latest
- * `IntersectionObserverEntry`. Consumers can derive a boolean `isVisible` from
- * this entry's `isIntersecting` property.
- *
- * @example
- * ```ts
- * import { Component, effect, ElementRef, viewChild } from '@angular/core';
- * import { elementVisibility } from '@mmstack/primitives';
- * import { computed } from '@angular/core'; // For derived boolean
- *
- * @Component({
- * selector: 'app-lazy-image',
- * template: `
- * <div #imageContainer style="height: 200px; border: 1px dashed grey;">
- * @if (isVisible()) {
- * <img src="your-image-url.jpg" alt="Lazy loaded image" />
- * <p>Image is VISIBLE!</p>
- * } @else {
- * <p>Scroll down to see the image...</p>
- * }
- * </div>
- * `
- * })
- * export class LazyImageComponent {
- * readonly imageContainer = viewChild.required<ElementRef<HTMLDivElement>>('imageContainer');
- *
- * // Observe the element, get the full IntersectionObserverEntry
- * readonly intersectionEntry = elementVisibility(this.imageContainer);
- *
- * // Derive a simple boolean for visibility
- * readonly isVisible = computed(() => this.intersectionEntry()?.isIntersecting ?? false);
- *
- * constructor() {
- * effect(() => {
- * console.log('Intersection Entry:', this.intersectionEntry());
- * console.log('Is Visible:', this.isVisible());
- * });
- * }
- * }
- * ```
- */
-export declare function elementVisibility(target?: ElementRef<Element> | Element | Signal<ElementRef<Element> | Element | null>, opt?: ElementVisibilityOptions): ElementVisibilitySignal;

package/lib/get-signal-equality.d.ts

@@ -1,5 +0,0 @@
-import { Signal, ValueEqualityFn } from '@angular/core';
-/**
- * @interal
- */
-export declare function getSignalEquality<T>(sig: Signal<T>): ValueEqualityFn<T>;

package/lib/map-array.d.ts

@@ -1,61 +0,0 @@
-import { type CreateSignalOptions, type Signal } from '@angular/core';
-/**
- * Reactively maps items from a source array (or signal of an array) using a provided mapping function.
- *
- * This function serves a similar purpose to SolidJS's `mapArray` by providing stability
- * for mapped items. It receives a source function returning an array (or a Signal<T[]>)
- * and a mapping function.
- *
- * For each item in the source array, it creates a stable `computed` signal representing
- * that item's value at its current index. This stable signal (`Signal<T>`) is passed
- * to the mapping function. This ensures that downstream computations or components
- * depending on the mapped result only re-render or re-calculate for the specific items
- * that have changed, or when items are added/removed, rather than re-evaluating everything
- * when the source array reference changes but items remain the same.
- *
- * It efficiently handles changes in the source array's length by reusing existing mapped
- * results when possible, slicing when the array shrinks, and appending new mapped items
- * when it grows.
- *
- * @template T The type of items in the source array.
- * @template U The type of items in the resulting mapped array.
- *
- * @param source A function returning the source array `T[]`, or a `Signal<T[]>` itself.
- * The `mapArray` function will reactively update based on changes to this source.
- * @param map The mapping function. It is called for each item in the source array.
- * It receives:
- * - `value`: A stable `Signal<T>` representing the item at the current index.
- * Use this signal within your mapping logic if you need reactivity
- * tied to the specific item's value changes.
- * - `index`: The number index of the item in the array.
- * It should return the mapped value `U`.
- * @param [opt] Optional `CreateSignalOptions<T>`. These options are passed directly
- * to the `computed` signal created for each individual item (`Signal<T>`).
- * This allows specifying options like a custom `equal` function for item comparison.
- *
- * @returns A `Signal<U[]>` containing the mapped array. This signal updates whenever
- * the source array changes (either length or the values of its items).
- *
- * @example
- * ```ts
- * const sourceItems = signal([
- * { id: 1, name: 'Apple' },
- * { id: 2, name: 'Banana' }
- * ]);
- *
- * const mappedItems = mapArray(
- * sourceItems,
- * (itemSignal, index) => {
- * // itemSignal is stable for a given item based on its index.
- * // We create a computed here to react to changes in the item's name.
- *  return computed(() => `${index}: ${itemSignal().name.toUpperCase()}`);
- * },
- * // Example optional options (e.g., custom equality for item signals)
- * { equal: (a, b) => a.id === b.id && a.name === b.name }
- * );
- * ```
- * @remarks
- * This function achieves its high performance by leveraging the new `linkedSignal`
- * API from Angular, which allows for efficient memoization and reuse of array items.
- */
-export declare function mapArray<T, U>(source: () => T[], map: (value: Signal<T>, index: number) => U, opt?: CreateSignalOptions<T>): Signal<U[]>;

package/lib/mutable.d.ts

@@ -1,95 +0,0 @@
-import { type CreateSignalOptions, type WritableSignal } from '@angular/core';
-/**
- * A `MutableSignal` is a special type of `WritableSignal` that allows for in-place mutation of its value.
- * In addition to the standard `set` and `update` methods, it provides a `mutate` method.  This is useful
- * for performance optimization when dealing with complex objects or arrays, as it avoids unnecessary
- * object copying.
- *
- * @typeParam T - The type of value held by the signal.
- */
-export type MutableSignal<T> = WritableSignal<T> & {
-    /**
-     * Mutates the signal's value in-place.  This is similar to `update`, but it's optimized for
-     * scenarios where you want to modify the existing object directly rather than creating a new one.
-     *
-     * @param updater - A function that takes the current value as input and modifies it directly.
-     *
-     * @example
-     * const myArray = mutable([1, 2, 3]);
-     * myArray.mutate((arr) => {
-     *  arr.push(4);
-     *  return arr;
-     * }); // myArray() now returns [1, 2, 3, 4]
-     */
-    mutate: WritableSignal<T>['update'];
-    /**
-     * Mutates the signal's value in-place, similar to `mutate`, but with a void-returning value in updater
-     * function. This further emphasizes that the mutation is happening inline, improving readability
-     * in some cases.
-     * @param updater - Function to change to the current value
-     * @example
-     * const myObject = mutable({ a: 1, b: 2 });
-     * myObject.inline((obj) => (obj.a = 3)); // myObject() now returns { a: 3, b: 2 }
-     */
-    inline: (updater: (value: T) => void) => void;
-};
-/**
- * Creates a `MutableSignal`. This function overloads the standard `signal` function to provide
- * the additional `mutate` and `inline` methods.
- *
- * @typeParam T The type of value held by the signal.
- * @param initial The initial value of the signal.
- * @param options Optional signal options, including a custom `equal` function.
- * @returns A `MutableSignal` instance.
- *
- * ### Important Note on `computed` Signals
- *
- * When creating a `computed` signal that derives a non-primitive value (e.g., an object or array)
- * from a `mutable` signal, you **must** provide the `{ equal: false }` option to the `computed`
- * function.
- *
- * This is because a `.mutate()` call notifies its dependents that it has changed, but if the
- * reference to a derived object hasn't changed, the `computed` signal will not trigger its
- * own dependents by default.
- *
- * @example
- * ```ts
- * const state = mutable({ user: { name: 'John' }, lastUpdated: new Date() });
- *
- * // ✅ CORRECT: Deriving a primitive value works as expected.
- * const name = computed(() => state().user.name);
- *
- * // ❌ INCORRECT: This will not update reliably after the first change.
- * const userObject = computed(() => state().user);
- *
- * // ✅ CORRECT: For object derivations, `equal: false` is required.
- * const userObjectFixed = computed(() => state().user, { equal: false });
- *
- * // This mutation will now correctly trigger effects depending on `userObjectFixed`.
- * state.mutate(s => s.lastUpdated = new Date());
- * ```
- */
-export declare function mutable<T>(): MutableSignal<T | undefined>;
-export declare function mutable<T>(initial: T): MutableSignal<T>;
-export declare function mutable<T>(initial: T, opt?: CreateSignalOptions<T>): MutableSignal<T>;
-/**
- * Type guard function to check if a given `WritableSignal` is a `MutableSignal`.  This is useful
- * for situations where you need to conditionally use the `mutate` or `inline` methods.
- *
- * @typeParam T - The type of the signal's value (optional, defaults to `any`).
- * @param value - The `WritableSignal` to check.
- * @returns `true` if the signal is a `MutableSignal`, `false` otherwise.
- *
- * @example
- * const mySignal = signal(0);
- * const myMutableSignal = mutable(0);
- *
- * if (isMutable(mySignal)) {
- *   mySignal.mutate(x => x + 1); // This would cause a type error, as mySignal is not a MutableSignal.
- * }
- *
- * if (isMutable(myMutableSignal)) {
- *   myMutableSignal.mutate(x => x + 1); // This is safe.
- * }
- */
-export declare function isMutable<T = any>(value: WritableSignal<T>): value is MutableSignal<T>;

package/lib/sensors/index.d.ts

@@ -1,7 +0,0 @@
-export * from './media-query';
-export * from './mouse-position';
-export * from './network-status';
-export * from './page-visibility';
-export * from './scroll-position';
-export * from './sensor';
-export * from './window-size';

package/lib/sensors/media-query.d.ts

@@ -1,94 +0,0 @@
-import { Signal } from '@angular/core';
-/**
- * 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());
- * });
- * }
- * }
- * ```
- */
-export declare function mediaQuery(query: string, debugName?: string): Signal<boolean>;
-/**
- * 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());
- * });
- * ```
- */
-export declare function prefersDarkMode(debugName?: string): Signal<boolean>;
-/**
- * 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
- * }
- * });
- * ```
- */
-export declare function prefersReducedMotion(debugName?: string): Signal<boolean>;

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

@@ -1,80 +0,0 @@
-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;
-};
-/**
- * A specialized Signal that tracks mouse position within an element.
- * It's a throttled signal of the mouse coordinates with an attached `unthrottled` signal.
- */
-export type MousePositionSignal = Signal<MousePosition> & {
-    /** A signal providing the raw, unthrottled mouse position. */
-    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 {};