@mmstack/primitives 20.4.6 → 20.5.0

package/index.d.ts

@@ -1,4 +1,40 @@
-import { CreateSignalOptions, DestroyRef, WritableSignal, Signal, ElementRef, EffectCleanupRegisterFn, CreateEffectOptions, Injector, ValueEqualityFn } from '@angular/core';
+import { ValueEqualityFn, Injector, Signal, CreateSignalOptions, DestroyRef, WritableSignal, EffectRef, EffectCleanupRegisterFn, CreateEffectOptions, ElementRef } from '@angular/core';
+
+type CreateChunkedOptions<T> = {
+    /**
+     * The number of items to process in each chunk.
+     * @default 50
+     */
+    chunkSize?: number;
+    /**
+     * The delay between processing each chunk. Can be a number (milliseconds) or 'frame' to use `requestAnimationFrame`.
+     * @default 'frame'
+     */
+    delay?: number | 'frame' | 'microtask';
+    /**
+     * A custom equality function to determine if the processed chunk has changed. This can help prevent unnecessary updates if the chunk content is the same as the previous one.
+     */
+    equal?: ValueEqualityFn<T[]>;
+    /**
+     * An optional `Injector` to use for the internal effect. This allows the effect to have access to dependency injection if needed.
+     */
+    injector?: Injector;
+};
+/**
+ * Creates a new `Signal` that processes an array of items in time-sliced chunks. This is useful for handling large lists without blocking the main thread.
+ *
+ * The returned signal will initially contain the first `chunkSize` items from the source array. It will then schedule updates to include additional chunks of items based on the specified `duration`.
+ *
+ * @template T The type of items in the array.
+ * @param source A `Signal` or a function that returns an array of items to be processed in chunks.
+ * @param options Configuration options for chunk size, delay duration, equality function, and injector.
+ * @returns A `Signal` that emits the current chunk of items being processed.
+ *
+ * @example
+ * const largeList = signal(Array.from({ length: 1000 }, (_, i) => i));
+ * const chunkedList = chunked(largeList, { chunkSize: 100, duration: 100 });
+ */
+declare function chunked<T>(source: Signal<T[]> | (() => T[]), options?: CreateChunkedOptions<T>): Signal<T[]>;
 
 /**
  * Options for creating a debounced writable signal.
@@ -271,31 +307,32 @@ declare function derived<T, U>(source: WritableSignal<T>, opt: CreateDerivedOpti
  * console.log(user().name); // Outputs: Jane
  * ```
  */
-declare function derived<T extends UnknownObject, TKey extends keyof T>(source: WritableSignal<T>, key: TKey, opt?: CreateSignalOptions<T[TKey]>): DerivedSignal<T, T[TKey]>;
+declare function derived<T extends UnknownObject, TKey extends keyof T>(source: MutableSignal<T>, key: TKey, opt?: CreateSignalOptions<T[TKey]>): DerivedSignal<T, T[TKey]> & MutableSignal<T[TKey]>;
 /**
- * Creates a `DerivedSignal` from an array, deriving an element by its index.
- * This overload is a convenient shorthand for accessing array elements.
+ * 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 array).
- * @param source The source `WritableSignal` (holding an array).
- * @param index The index of the element to derive.
+ * @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 numbers = signal([1, 2, 3]);
- * const secondNumber = derived(numbers, 1);
+ * const user = signal({ name: 'John', age: 30 });
+ * const name = derived(user, 'name');
  *
- * console.log(secondNumber()); // Outputs: 2
+ * console.log(name()); // Outputs: John
  *
  * // Update the derived signal, which also updates the source
- * secondNumber.set(5);
+ * name.set('Jane');
  *
- * console.log(numbers()); // Outputs: [1, 5, 3]
+ * console.log(user().name); // Outputs: Jane
  * ```
  */
-declare function derived<T extends any[]>(source: WritableSignal<T>, index: number, opt?: CreateSignalOptions<T[number]>): DerivedSignal<T, T[number]>;
+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` that derives its value from another `MutableSignal`.
  * Use mutuable signals with caution, but very useful for deeply nested structures.
@@ -319,6 +356,30 @@ declare function derived<T extends any[]>(source: WritableSignal<T>, index: numb
  * ```
  */
 declare function derived<T, U>(source: MutableSignal<T>, optOrKey: CreateDerivedOptions<T, U> | keyof T, opt?: CreateSignalOptions<U>): DerivedSignal<T, U> & MutableSignal<U>;
+/**
+ * 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]
+ * ```
+ */
+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.
@@ -353,71 +414,87 @@ 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>;
+type Frame = {
+    injector: Injector;
+    parent: Frame | null;
+    children: Set<EffectRef>;
 };
+
 /**
- * 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.
+ * Creates an effect that can be nested, similar to SolidJS's `createEffect`.
  *
- * It can observe a static `ElementRef`/`Element` or a `Signal` that resolves to one,
- * allowing for dynamic targets.
+ * This primitive enables true hierarchical reactivity. A `nestedEffect` created
+ * within another `nestedEffect` is automatically destroyed and recreated when
+ * the parent re-runs.
  *
- * @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.
+ * It automatically handles injector propagation and lifetime management, allowing
+ * you to create fine-grained, conditional side-effects that only track
+ * dependencies when they are "live".
+ *
+ * @param effectFn The side-effect function, which receives a cleanup register function.
+ * @param options (Optional) Angular's `CreateEffectOptions`.
+ * @returns An `EffectRef` for the created effect.
  *
  * @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);
+ * // Assume `coldGuard` changes rarely, but `hotSignal` changes often.
+ * const coldGuard = signal(false);
+ * const hotSignal = signal(0);
  *
- * // Derive a simple boolean for visibility
- * readonly isVisible = computed(() => this.intersectionEntry()?.isIntersecting ?? false);
+ * nestedEffect(() => {
+ * // This outer effect only tracks `coldGuard`.
+ * if (coldGuard()) {
  *
- * constructor() {
- * effect(() => {
- * console.log('Intersection Entry:', this.intersectionEntry());
- * console.log('Is Visible:', this.isVisible());
+ * // This inner effect is CREATED when coldGuard is true
+ * // and DESTROYED when it becomes false.
+ * nestedEffect(() => {
+ * // It only tracks `hotSignal` while it exists.
+ * console.log('Hot signal is:', hotSignal());
  * });
  * }
- * }
+ * // If `coldGuard` is false, this outer effect does not track `hotSignal`.
+ * });
+ * ```
+ * @example
+ * ```ts
+ * const users = signal([
+ *   { id: 1, name: 'Alice' },
+ *   { id: 2, name: 'Bob' }
+ * ]);
+ *
+ * // The fine-grained mapped list
+ * const mappedUsers = mapArray(
+ *   users,
+ *   (userSignal, index) => {
+ *     // 1. Create a fine-grained SIDE EFFECT for *this item*
+ *     // This effect's lifetime is now tied to this specific item. created once on init of this index.
+ *     const effectRef = nestedEffect(() => {
+ *       // This only runs if *this* userSignal changes,
+ *       // not if the whole list changes.
+ *       console.log(`User ${index} updated:`, userSignal().name);
+ *     });
+ *
+ *     // 2. Return the data AND the cleanup logic
+ *     return {
+ *       // The mapped data
+ *       label: computed(() => `User: ${userSignal().name}`),
+ *
+ *       // The cleanup function
+ *       destroyEffect: () => effectRef.destroy()
+ *     };
+ *   },
+ *   {
+ *     // 3. Tell mapArray HOW to clean up when an item is removed, this needs to be manual as it's not a nestedEffect itself
+ *     onDestroy: (mappedItem) => {
+ *       mappedItem.destroyEffect();
+ *     }
+ *   }
+ * );
  * ```
  */
-declare function elementVisibility(target?: ElementRef<Element> | Element | Signal<ElementRef<Element> | Element | null>, opt?: ElementVisibilityOptions): ElementVisibilitySignal;
+declare function nestedEffect(effectFn: (registerCleanup: EffectCleanupRegisterFn) => void, options?: CreateEffectOptions & {
+    bindToFrame?: (parent: Frame | null) => Frame | null;
+}): EffectRef;
 
 /**
  * Reactively maps items from a source array to a new array, creating stable signals for each item.
@@ -449,7 +526,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,91 +535,60 @@ 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 mapArray<T, U>(source: WritableSignal<T[]>, map: (value: WritableSignal<T>, index: number) => U, options?: CreateSignalOptions<T> & {
+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 mapArray<T, U>(source: Signal<T[]> | (() => T[]), map: (value: Signal<T>, index: number) => U, options?: CreateSignalOptions<T> & {
+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;
 
 /**
- * Creates an effect that can be nested, similar to SolidJS's `createEffect`.
+ * Reactively maps items from a source array to a new array by value (identity).
  *
- * This primitive enables true hierarchical reactivity. A `nestedEffect` created
- * within another `nestedEffect` is automatically destroyed and recreated when
- * the parent re-runs.
- *
- * It automatically handles injector propagation and lifetime management, allowing
- * you to create fine-grained, conditional side-effects that only track
- * dependencies when they are "live".
+ * similar to `Array.prototype.map`, but:
+ * 1. The `mapFn` receives the `index` as a Signal.
+ * 2. If an item in the `source` array moves to a new position, the *result* of the map function is reused and moved.
+ *    The `index` signal is updated to the new index.
+ * 3. The `mapFn` is only run for *new* items.
  *
- * @param effectFn The side-effect function, which receives a cleanup register function.
- * @param options (Optional) Angular's `CreateEffectOptions`.
- * @returns An `EffectRef` for the created effect.
+ * This is useful for building efficient lists where DOM nodes or heavy instances should be reused
+ * when the list is reordered.
  *
- * @example
- * ```ts
- * // Assume `coldGuard` changes rarely, but `hotSignal` changes often.
- * const coldGuard = signal(false);
- * const hotSignal = signal(0);
- *
- * nestedEffect(() => {
- * // This outer effect only tracks `coldGuard`.
- * if (coldGuard()) {
- *
- * // This inner effect is CREATED when coldGuard is true
- * // and DESTROYED when it becomes false.
- * nestedEffect(() => {
- * // It only tracks `hotSignal` while it exists.
- * console.log('Hot signal is:', hotSignal());
- * });
- * }
- * // If `coldGuard` is false, this outer effect does not track `hotSignal`.
- * });
- * ```
- * @example
- * ```ts
- * const users = signal([
-  { id: 1, name: 'Alice' },
-  { id: 2, name: 'Bob' }
-]);
-
-// The fine-grained mapped list
-const mappedUsers = mapArray(
-  users,
-  (userSignal, index) => {
-    // 1. Create a fine-grained SIDE EFFECT for *this item*
-    // This effect's lifetime is now tied to this specific item. created once on init of this index.
-    const effectRef = nestedEffect(() => {
-      // This only runs if *this* userSignal changes,
-      // not if the whole list changes.
-      console.log(`User ${index} updated:`, userSignal().name);
-    });
-
-    // 2. Return the data AND the cleanup logic
-    return {
-      // The mapped data
-      label: computed(() => `User: ${userSignal().name}`),
-      
-      // The cleanup function
-      destroyEffect: () => effectRef.destroy()
-    };
-  },
-  {
-    // 3. Tell mapArray HOW to clean up when an item is removed, this needs to be manual as it's not a nestedEffect itself
-    onDestroy: (mappedItem) => {
-      mappedItem.destroyEffect();
-    }
-  }
-);
- * ```
+ * @param source A `Signal<T[]>` or a function returning `T[]`.
+ * @param mapFn The mapping function. Receives the item and its index as a Signal.
+ * @param options Optional configuration:
+ *  - `onDestroy`: A callback invoked when a mapped item is removed from the array.
+ * @returns A `Signal<U[]>` containing the mapped array.
  */
-declare function nestedEffect(effectFn: (registerCleanup: EffectCleanupRegisterFn) => void, options?: CreateEffectOptions): {
-    destroy: () => void;
+declare function keyArray<T, U, K>(source: Signal<T[]> | (() => T[]), mapFn: (v: T, i: Signal<number>) => U, options?: {
+    onDestroy?: (value: U) => void;
+    /**
+     * Optional function to use a custom key for item comparison.
+     * Use this if you want to reuse mapped items based on a property (like an ID)
+     * even if the item reference changes.
+     */
+    key?: (item: T) => K;
+}): Signal<U[]>;
+
+type MappedObject<T extends Record<string, any>, U> = {
+    [K in keyof T]: U;
 };
+declare function mapObject<T extends Record<string, any>, U>(source: MutableSignal<T>, mapFn: <K extends keyof T>(key: K, value: MutableSignal<T[K]>) => U, options?: {
+    onDestroy?: (value: U) => void;
+}): Signal<MappedObject<T, U>>;
+declare function mapObject<T extends Record<string, any>, U>(source: WritableSignal<T>, mapFn: <K extends keyof T>(key: K, value: WritableSignal<T[K]>) => U, options?: {
+    onDestroy?: (value: U) => void;
+}): Signal<MappedObject<T, U>>;
+declare function mapObject<T extends Record<string, any>, U>(source: (() => T) | Signal<T>, mapFn: <K extends keyof T>(key: K, value: Signal<T[K]>) => U, options?: {
+    onDestroy?: (value: U) => void;
+}): Signal<MappedObject<T, U>>;
 
 /**
  * A pure, synchronous transform from I -> O.
@@ -640,6 +686,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 +1176,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 +1259,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 +1268,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 +1277,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 +1313,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 +1322,70 @@ 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>;
+
+type BaseType = string | number | boolean | symbol | undefined | null | Function | Date | RegExp;
+type Key = string | number;
+type AnyRecord = Record<Key, any>;
+/**
+ * @internal
+ * Validates whether a value is a Signal Store.
+ */
+declare function isStore<T>(value: unknown): value is SignalStore<T>;
+type SignalArrayStore<T extends any[]> = Signal<T> & {
+    readonly [index: number]: SignalStore<T[number]>;
+    readonly length: Signal<number>;
+    [Symbol.iterator](): Iterator<SignalStore<T[number]>>;
+};
+type WritableArrayStore<T extends any[]> = WritableSignal<T> & {
+    readonly asReadonlyStore: () => SignalArrayStore<T>;
+    readonly [index: number]: WritableSignalStore<T[number]>;
+    readonly length: Signal<number>;
+    [Symbol.iterator](): Iterator<WritableSignalStore<T[number]>>;
+};
+type MutableArrayStore<T extends any[]> = MutableSignal<T> & {
+    readonly asReadonlyStore: () => SignalArrayStore<T>;
+    readonly [index: number]: MutableSignalStore<T[number]>;
+    readonly length: Signal<number>;
+    [Symbol.iterator](): Iterator<MutableSignalStore<T[number]>>;
+};
+type SignalStore<T> = Signal<T> & (NonNullable<T> extends BaseType ? unknown : NonNullable<T> extends Array<any> ? SignalArrayStore<NonNullable<T>> : Readonly<{
+    [K in keyof Required<T>]: SignalStore<NonNullable<T>[K]>;
+}>);
+type WritableSignalStore<T> = WritableSignal<T> & {
+    readonly asReadonlyStore: () => SignalStore<T>;
+} & (NonNullable<T> extends BaseType ? unknown : NonNullable<T> extends Array<any> ? WritableArrayStore<NonNullable<T>> : Readonly<{
+    [K in keyof Required<T>]: WritableSignalStore<NonNullable<T>[K]>;
+}>);
+type MutableSignalStore<T> = MutableSignal<T> & {
+    readonly asReadonlyStore: () => SignalStore<T>;
+} & (NonNullable<T> extends BaseType ? unknown : NonNullable<T> extends Array<any> ? MutableArrayStore<NonNullable<T>> : Readonly<{
+    [K in keyof Required<T>]: MutableSignalStore<NonNullable<T>[K]>;
+}>);
+declare function toStore<T extends AnyRecord>(source: MutableSignal<T>, injector?: Injector): MutableSignalStore<T>;
+declare function toStore<T extends AnyRecord>(source: WritableSignal<T>, injector?: Injector): WritableSignalStore<T>;
+declare function toStore<T extends AnyRecord>(source: Signal<T>, injector?: Injector): SignalStore<T>;
+/**
+ * Creates a WritableSignalStore from a value.
+ * @see {@link toStore}
+ */
+declare function store<T extends AnyRecord>(value: T, opt?: CreateSignalOptions<T> & {
+    injector?: Injector;
+}): WritableSignalStore<T>;
+/**
+ * Creates a MutableSignalStore from a value.
+ * @see {@link toStore}
+ */
+declare function mutableStore<T extends AnyRecord>(value: T, opt?: CreateSignalOptions<T> & {
+    injector?: Injector;
+}): MutableSignalStore<T>;
 
 /**
  * Interface for storage mechanisms compatible with the `stored` signal.
@@ -1163,6 +1449,10 @@ type CreateStoredOptions<T> = CreateSignalOptions<T> & {
      * If 'true', the signal will remove the old key from storage when the key changes, defaults to `false`.
      */
     cleanupOldKey?: boolean;
+    /**
+     * Optional validator, which is called on load of value. Store will be set to fallback if value is false
+     */
+    validate?: (value: T) => boolean;
 };
 /**
  * A specialized `WritableSignal` returned by the `stored()` function.
@@ -1234,7 +1524,7 @@ type StoredSignal<T> = WritableSignal<T> & {
  * }
  * ```
  */
-declare function stored<T>(fallback: T, { key, store: providedStore, serialize, deserialize, syncTabs, equal, onKeyChange, cleanupOldKey, ...rest }: CreateStoredOptions<T>): StoredSignal<T>;
+declare function stored<T>(fallback: T, { key, store: providedStore, serialize, deserialize, syncTabs, equal, onKeyChange, cleanupOldKey, validate, ...rest }: CreateStoredOptions<T>): StoredSignal<T>;
 
 type SyncSignalOptions = {
     id?: string;
@@ -1380,7 +1670,14 @@ 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> & {
+    /**
+     * If `true` (the default), the returned signal will be a computed signal that depends on the source signal.
+     * If `false`, the returned signal will be a direct wrapper around the source signal without creating a new computed signal.
+     * @default true
+     */
+    pure?: boolean;
+}): WritableSignal<T>;
 
 type UntilOptions = {
     /**
@@ -1532,5 +1829,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 { chunked, combineWith, debounce, debounced, derived, distinct, elementSize, elementVisibility, filter, indexArray, isDerivation, isMutable, isStore, keyArray, map, mapArray, mapObject, mediaQuery, mousePosition, mutable, mutableStore, nestedEffect, networkStatus, pageVisibility, pipeable, piped, prefersDarkMode, prefersReducedMotion, scrollPosition, select, sensor, sensors, store, stored, tabSync, tap, throttle, throttled, toFakeDerivation, toFakeSignalDerivation, toStore, toWritable, until, windowSize, withHistory };
+export type { CreateChunkedOptions, CreateDebouncedOptions, CreateHistoryOptions, CreateStoredOptions, CreateThrottledOptions, DebouncedSignal, DerivedSignal, ElementSize, ElementSizeOptions, ElementSizeSignal, ElementVisibilityOptions, ElementVisibilitySignal, MousePositionOptions, MousePositionSignal, MutableSignal, MutableSignalStore, NetworkStatusSignal, PipeableSignal, ScrollPosition, ScrollPositionOptions, ScrollPositionSignal, SignalStore, SignalWithHistory, StoredSignal, ThrottledSignal, UntilOptions, WindowSize, WindowSizeOptions, WindowSizeSignal, WritableSignalStore };