@mmstack/primitives 20.4.7 → 21.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmstack/primitives",
-  "version": "20.4.7",
+  "version": "21.0.1",
   "keywords": [
     "angular",
     "signals",
@@ -15,18 +15,18 @@
   },
   "homepage": "https://github.com/mihajm/mmstack/blob/master/packages/primitives",
   "peerDependencies": {
-    "@angular/core": ">=20 <21",
-    "@angular/common": ">=20 <21"
+    "@angular/core": ">=21 <22",
+    "@angular/common": ">=21 <22"
   },
   "sideEffects": false,
   "module": "fesm2022/mmstack-primitives.mjs",
-  "typings": "index.d.ts",
+  "typings": "types/mmstack-primitives.d.ts",
   "exports": {
     "./package.json": {
       "default": "./package.json"
     },
     ".": {
-      "types": "./index.d.ts",
+      "types": "./types/mmstack-primitives.d.ts",
       "default": "./fesm2022/mmstack-primitives.mjs"
     }
   },

package/{index.d.ts → types/mmstack-primitives.d.ts}

@@ -1,4 +1,4 @@
-import { CreateSignalOptions, DestroyRef, WritableSignal, Signal, ElementRef, EffectCleanupRegisterFn, CreateEffectOptions, Injector, ValueEqualityFn } from '@angular/core';
+import { CreateSignalOptions, DestroyRef, WritableSignal, Signal, EffectCleanupRegisterFn, CreateEffectOptions, ElementRef, Injector, ValueEqualityFn } from '@angular/core';
 
 /**
  * Options for creating a debounced writable signal.
@@ -353,72 +353,6 @@ declare function toFakeSignalDerivation<T, U>(initial: WritableSignal<U>): Deriv
  */
 declare function isDerivation<T, U>(sig: WritableSignal<U>): sig is DerivedSignal<T, U>;
 
-/**
- * Options for configuring the `elementVisibility` sensor, extending
- * standard `IntersectionObserverInit` options.
- */
-type ElementVisibilityOptions = IntersectionObserverInit & {
-    /** Optional debug name for the internal signal. */
-    debugName?: string;
-};
-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());
- * });
- * }
- * }
- * ```
- */
-declare function elementVisibility(target?: ElementRef<Element> | Element | Signal<ElementRef<Element> | Element | null>, opt?: ElementVisibilityOptions): ElementVisibilitySignal;
-
 /**
  * Reactively maps items from a source array to a new array, creating stable signals for each item.
  *
@@ -449,7 +383,7 @@ declare function elementVisibility(target?: ElementRef<Element> | Element | Sign
  * ]);
  *
  * // The `itemSignal` is writable because `sourceItems` is a WritableSignal.
- * const mappedItems = mapArray(sourceItems, (itemSignal, index) => ({
+ * const mappedItems = indexArray(sourceItems, (itemSignal, index) => ({
  * label: computed(() => `${index}: ${itemSignal().name.toUpperCase()}`),
  * setName: (newName: string) => itemSignal.update(item => ({ ...item, name: newName }))
  * }));
@@ -458,13 +392,43 @@ declare function elementVisibility(target?: ElementRef<Element> | Element | Sign
  * mappedItems()[0].setName('Avocado');
  * // sourceItems() is now: [{ id: 1, name: 'Avocado' }, { id: 2, name: 'Banana' }]
  */
-declare function mapArray<T, U>(source: MutableSignal<T[]>, map: (value: MutableSignal<T>, index: number) => U, options?: CreateSignalOptions<T> & {
+declare function indexArray<T, U>(source: MutableSignal<T[]>, map: (value: MutableSignal<T>, index: number) => U, options?: CreateSignalOptions<T> & {
+    onDestroy?: (value: U) => void;
+}): Signal<U[]>;
+declare function indexArray<T, U>(source: WritableSignal<T[]>, map: (value: WritableSignal<T>, index: number) => U, options?: CreateSignalOptions<T> & {
+    onDestroy?: (value: U) => void;
+}): Signal<U[]>;
+declare function indexArray<T, U>(source: Signal<T[]> | (() => T[]), map: (value: Signal<T>, index: number) => U, options?: CreateSignalOptions<T> & {
+    onDestroy?: (value: U) => void;
+}): Signal<U[]>;
+/**
+ * @deprecated use indexArray instead
+ */
+declare const mapArray: typeof indexArray;
+
+/**
+ * Reactively maps items from a source array to a new array using a key function to maintain stability.
+ *
+ * This function preserves the `mapped` signals for items even if they move within the array,
+ * as long as their key remains the same. This is equivalent to SolidJS's `mapArray` or Angular's `@for (item of items; track item.id)`.
+ *
+ * @template T The type of items in the source array.
+ * @template U The type of items in the resulting mapped array.
+ * @template K The type of the key.
+ *
+ * @param source A `Signal<T[]>` or a function returning `T[]`.
+ * @param keyFn A function to extract a unique key for each item.
+ * @param map The mapping function. It receives a stable signal for the item and a signal for its index.
+ * @param options Optional configuration, including `CreateSignalOptions` and an `onDestroy` callback.
+ * @returns A `Signal<U[]>` containing the mapped array.
+ */
+declare function keyArray<T, U>(source: MutableSignal<T[]>, keyFn: (item: T) => string | number, map: (value: MutableSignal<T>, index: Signal<number>) => U, options?: CreateSignalOptions<T> & {
     onDestroy?: (value: U) => void;
 }): Signal<U[]>;
-declare function mapArray<T, U>(source: WritableSignal<T[]>, map: (value: WritableSignal<T>, index: number) => U, options?: CreateSignalOptions<T> & {
+declare function keyArray<T, U>(source: WritableSignal<T[]>, keyFn: (item: T) => string | number, map: (value: WritableSignal<T>, index: Signal<number>) => U, options?: CreateSignalOptions<T> & {
     onDestroy?: (value: U) => void;
 }): Signal<U[]>;
-declare function mapArray<T, U>(source: Signal<T[]> | (() => T[]), map: (value: Signal<T>, index: number) => U, options?: CreateSignalOptions<T> & {
+declare function keyArray<T, U>(source: Signal<T[]> | (() => T[]), keyFn: (item: T) => string | number, map: (value: Signal<T>, index: Signal<number>) => U, options?: CreateSignalOptions<T> & {
     onDestroy?: (value: U) => void;
 }): Signal<U[]>;
 
@@ -640,6 +604,107 @@ declare function pipeable<TSig extends Signal<any>>(signal: TSig): PipeableSigna
  */
 declare function piped<T>(initial: T, opt?: CreateSignalOptions<T>): PipeableSignal<T, WritableSignal<T>>;
 
+/**
+ * Represents the size of an element.
+ */
+interface ElementSize {
+    width: number;
+    height: number;
+}
+/**
+ * Options for configuring the `elementSize` sensor.
+ */
+type ElementSizeOptions = ResizeObserverOptions & {
+    /** Optional debug name for the internal signal. */
+    debugName?: string;
+};
+type ElementSizeSignal = Signal<ElementSize | undefined>;
+/**
+ * Creates a read-only signal that tracks the size of a target DOM element.
+ *
+ * By default, it observes the `border-box` size to align with `getBoundingClientRect()`,
+ * which is used to provide a synchronous initial value if possible.
+ *
+ * @param target The DOM element (or `ElementRef`, or a `Signal` resolving to one) to observe.
+ * @param options Optional configuration including `box` (defaults to 'border-box') and `debugName`.
+ * @returns A `Signal<ElementSize | undefined>`.
+ *
+ * @example
+ * ```ts
+ * const size = elementSize(elementRef);
+ * effect(() => {
+ *   console.log('Size:', size()?.width, size()?.height);
+ * });
+ * ```
+ */
+declare function elementSize(target?: ElementRef<Element> | Element | Signal<ElementRef<Element> | Element | null>, opt?: ElementSizeOptions): ElementSizeSignal;
+
+/**
+ * Options for configuring the `elementVisibility` sensor, extending
+ * standard `IntersectionObserverInit` options.
+ */
+type ElementVisibilityOptions = IntersectionObserverInit & {
+    /** Optional debug name for the internal signal. */
+    debugName?: string;
+};
+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());
+ * });
+ * }
+ * }
+ * ```
+ */
+declare function elementVisibility(target?: ElementRef<Element> | Element | Signal<ElementRef<Element> | Element | null>, opt?: ElementVisibilityOptions): ElementVisibilitySignal;
+
 /**
  * Creates a read-only signal that reactively tracks whether a CSS media query
  * string currently matches.
@@ -1029,6 +1094,81 @@ type WindowSizeSignal = Signal<WindowSize> & {
  */
 declare function windowSize(opt?: WindowSizeOptions): WindowSizeSignal;
 
+type SensorTypedOptions = {
+    elementVisibility: {
+        opt: ElementVisibilityOptions & {
+            target?: ElementRef<Element> | Element | Signal<ElementRef<Element> | Element | null>;
+        };
+        returnType: ElementVisibilitySignal;
+    };
+    elementSize: {
+        opt: ElementSizeOptions & {
+            target?: ElementRef<Element> | Element | Signal<ElementRef<Element> | Element | null>;
+        };
+        returnType: ElementSizeSignal;
+    };
+    mousePosition: {
+        opt: MousePositionOptions;
+        returnType: MousePositionSignal;
+    };
+    networkStatus: {
+        opt: {
+            debugName?: string;
+        };
+        returnType: NetworkStatusSignal;
+    };
+    pageVisibility: {
+        opt: {
+            debugName?: string;
+        };
+        returnType: Signal<DocumentVisibilityState>;
+    };
+    darkMode: {
+        opt: {
+            debugName?: string;
+        };
+        returnType: Signal<boolean>;
+    };
+    reducedMotion: {
+        opt: {
+            debugName?: string;
+        };
+        returnType: Signal<boolean>;
+    };
+    scrollPosition: {
+        opt: ScrollPositionOptions;
+        returnType: ScrollPositionSignal;
+    };
+    windowSize: {
+        opt: WindowSizeOptions;
+        returnType: WindowSizeSignal;
+    };
+    mediaQuery: {
+        opt: {
+            query: string;
+            debugName?: string;
+        };
+        returnType: Signal<boolean>;
+    };
+};
+/**
+ * Creates a sensor signal that the elements visiblity within the viewport
+ * @param type Must be `'elementVisibility'`.
+ * @param options Optional configuration IntersectionObserver & target.
+ * @returns A `ElementVisibilitySignal` that tracks whether the Element is intersected.
+ * @see {elementVisibility} for detailed documentation and examples.
+ * @example const pos = sensor('elementVisibility');
+ */
+declare function sensor(type: 'elementVisibility', options?: SensorTypedOptions['elementVisibility']['opt']): ElementVisibilitySignal;
+/**
+ * Creates a sensor signal that tracks the element's size dimensions.
+ * @param type Must be `'elementSize'`.
+ * @param options Optional configuration ResizeObserver & target.
+ * @returns A `ElementSizeSignal` that tracks the element's size ({ width, height }).
+ * @see {elementSize} for detailed documentation and examples.
+ * @example const size = sensor('elementSize');
+ */
+declare function sensor(type: 'elementSize', options?: SensorTypedOptions['elementSize']['opt']): ElementSizeSignal;
 /**
  * Creates a sensor signal that tracks the mouse cursor's position.
  * @param type Must be `'mousePosition'`.
@@ -1037,7 +1177,7 @@ declare function windowSize(opt?: WindowSizeOptions): WindowSizeSignal;
  * @see {mousePosition} for detailed documentation and examples.
  * @example const pos = sensor('mousePosition', { coordinateSpace: 'page', throttle: 50 });
  */
-declare function sensor(type: 'mousePosition', options?: MousePositionOptions): MousePositionSignal;
+declare function sensor(type: 'mousePosition', options?: SensorTypedOptions['mousePosition']['opt']): MousePositionSignal;
 /**
  * Creates a sensor signal that tracks the browser's online/offline status.
  * @param type Must be `'networkStatus'`.
@@ -1046,9 +1186,7 @@ declare function sensor(type: 'mousePosition', options?: MousePositionOptions):
  * @see {networkStatus} for detailed documentation and examples.
  * @example const onlineStatus = sensor('networkStatus');
  */
-declare function sensor(type: 'networkStatus', options?: {
-    debugName?: string;
-}): NetworkStatusSignal;
+declare function sensor(type: 'networkStatus', options?: SensorTypedOptions['networkStatus']['opt']): NetworkStatusSignal;
 /**
  * Creates a sensor signal that tracks the page's visibility state (e.g., 'visible', 'hidden').
  * @param type Must be `'pageVisibility'`.
@@ -1057,31 +1195,34 @@ declare function sensor(type: 'networkStatus', options?: {
  * @see {pageVisibility} for detailed documentation and examples.
  * @example const visibility = sensor('pageVisibility');
  */
-declare function sensor(type: 'pageVisibility', options?: {
-    debugName?: string;
-}): Signal<DocumentVisibilityState>;
+declare function sensor(type: 'pageVisibility', options?: SensorTypedOptions['pageVisibility']['opt']): 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 type Must be `'darkMode'`.
  * @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');
  */
-declare function sensor(type: 'dark-mode', options?: {
-    debugName?: string;
-}): Signal<boolean>;
+declare function sensor(type: 'darkMode' | 'dark-mode', options?: SensorTypedOptions['darkMode']['opt']): Signal<boolean>;
 /**
  * Creates a sensor signal that tracks the user's OS/browser preference for reduced motion.
- * @param type Must be `'reduced-motion'`.
+ * @param type Must be `'reducedMotion'`.
  * @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');
  */
-declare function sensor(type: 'reduced-motion', options?: {
-    debugName?: string;
-}): Signal<boolean>;
+declare function sensor(type: 'reducedMotion' | 'reduced-motion', options?: SensorTypedOptions['reducedMotion']['opt']): Signal<boolean>;
+/**
+ * Creates a sensor signal that tracks the provided media query.
+ * @param type Must be `'mediaQuery'`.
+ * @param options Optional configuration for the media query sensor, including `query` and `debugName`.
+ * @returns A `Signal<boolean>` which is `true` if the media query currently matches.
+ * @see {mediaQuery} for detailed documentation and examples.
+ * @example const isDesktop = sensor('mediaQuery', { query: '(min-width: 1024px)' });
+ */
+declare function sensor(type: 'mediaQuery', options?: SensorTypedOptions['mediaQuery']['opt']): Signal<boolean>;
 /**
  * Creates a sensor signal that tracks the browser window's inner dimensions (width and height).
  * @param type Must be `'windowSize'`.
@@ -1090,7 +1231,7 @@ declare function sensor(type: 'reduced-motion', options?: {
  * @see {windowSize} for detailed documentation and examples.
  * @example const size = sensor('windowSize', { throttle: 200 });
  */
-declare function sensor(type: 'windowSize', options?: WindowSizeOptions): WindowSizeSignal;
+declare function sensor(type: 'windowSize', options?: SensorTypedOptions['windowSize']['opt']): WindowSizeSignal;
 /**
  * Creates a sensor signal that tracks the scroll position (x, y) of the window or a specified element.
  * @param type Must be `'scrollPosition'`.
@@ -1099,7 +1240,14 @@ declare function sensor(type: 'windowSize', options?: WindowSizeOptions): Window
  * @see {scrollPosition} for detailed documentation and examples.
  * @example const pageScroll = sensor('scrollPosition', { throttle: 150 });
  */
-declare function sensor(type: 'scrollPosition', options?: ScrollPositionOptions): ScrollPositionSignal;
+declare function sensor(type: 'scrollPosition', options?: SensorTypedOptions['scrollPosition']['opt']): ScrollPositionSignal;
+type SensorsOptions<TKey extends keyof SensorTypedOptions> = {
+    [K in TKey]: SensorTypedOptions[K]['opt'];
+};
+type Sensors<TKey extends keyof SensorTypedOptions> = {
+    [K in TKey]: SensorTypedOptions[K]['returnType'];
+};
+declare function sensors<const TType extends keyof SensorTypedOptions>(track: TType[], opt?: SensorsOptions<TType>): Sensors<TType>;
 
 /**
  * Interface for storage mechanisms compatible with the `stored` signal.
@@ -1380,7 +1528,9 @@ declare function throttle<T>(source: WritableSignal<T>, opt?: CreateThrottledOpt
  *
  * writableSignal.set(5); // sets value of originalValue.a to 5 & triggers all signals
  */
-declare function toWritable<T>(signal: Signal<T>, set: (value: T) => void, update?: (updater: (value: T) => T) => void): WritableSignal<T>;
+declare function toWritable<T>(source: Signal<T>, set: (value: T) => void, update?: (updater: (value: T) => T) => void, opt?: CreateSignalOptions<T> & {
+    pure?: boolean;
+}): WritableSignal<T>;
 
 type UntilOptions = {
     /**
@@ -1532,5 +1682,5 @@ type CreateHistoryOptions<T> = Omit<CreateSignalOptions<T[]>, 'equal'> & {
  */
 declare function withHistory<T>(source: WritableSignal<T>, opt?: CreateHistoryOptions<T>): SignalWithHistory<T>;
 
-export { combineWith, debounce, debounced, derived, distinct, elementVisibility, filter, isDerivation, isMutable, map, mapArray, mediaQuery, mousePosition, mutable, nestedEffect, networkStatus, pageVisibility, pipeable, piped, prefersDarkMode, prefersReducedMotion, scrollPosition, select, sensor, stored, tabSync, tap, throttle, throttled, toFakeDerivation, toFakeSignalDerivation, toWritable, until, windowSize, withHistory };
-export type { CreateDebouncedOptions, CreateHistoryOptions, CreateStoredOptions, CreateThrottledOptions, DebouncedSignal, DerivedSignal, ElementVisibilityOptions, ElementVisibilitySignal, MousePositionOptions, MousePositionSignal, MutableSignal, NetworkStatusSignal, PipeableSignal, ScrollPosition, ScrollPositionOptions, ScrollPositionSignal, SignalWithHistory, StoredSignal, ThrottledSignal, UntilOptions, WindowSize, WindowSizeOptions, WindowSizeSignal };
+export { combineWith, debounce, debounced, derived, distinct, elementSize, elementVisibility, filter, indexArray, isDerivation, isMutable, keyArray, map, mapArray, mediaQuery, mousePosition, mutable, nestedEffect, networkStatus, pageVisibility, pipeable, piped, prefersDarkMode, prefersReducedMotion, scrollPosition, select, sensor, sensors, stored, tabSync, tap, throttle, throttled, toFakeDerivation, toFakeSignalDerivation, toWritable, until, windowSize, withHistory };
+export type { CreateDebouncedOptions, CreateHistoryOptions, CreateStoredOptions, CreateThrottledOptions, DebouncedSignal, DerivedSignal, ElementSize, ElementSizeOptions, ElementSizeSignal, ElementVisibilityOptions, ElementVisibilitySignal, MousePositionOptions, MousePositionSignal, MutableSignal, NetworkStatusSignal, PipeableSignal, ScrollPosition, ScrollPositionOptions, ScrollPositionSignal, SignalWithHistory, StoredSignal, ThrottledSignal, UntilOptions, WindowSize, WindowSizeOptions, WindowSizeSignal };