@mmstack/primitives 19.2.3 → 19.3.1

package/index.d.ts

@@ -1,10 +1,14 @@
+export * from './lib/chunked';
 export * from './lib/debounced';
 export * from './lib/derived';
-export * from './lib/element-visibility';
-export * from './lib/map-array';
+export { nestedEffect } from './lib/effect';
+export * from './lib/mappers';
 export * from './lib/mutable';
+export * from './lib/pipeable/public_api';
 export * from './lib/sensors';
+export * from './lib/store';
 export * from './lib/stored';
+export { tabSync } from './lib/tabSync';
 export * from './lib/throttled';
 export * from './lib/to-writable';
 export * from './lib/until';

package/lib/chunked.d.ts

@@ -0,0 +1,36 @@
+import { type Injector, type Signal, type ValueEqualityFn } from '@angular/core';
+export 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 });
+ */
+export declare function chunked<T>(source: Signal<T[]> | (() => T[]), options?: CreateChunkedOptions<T>): Signal<T[]>;

package/lib/derived.d.ts

@@ -1,5 +1,5 @@
-import { CreateSignalOptions, type WritableSignal } from '@angular/core';
-import type { UnknownObject } from '@mmstack/object';
+import { type CreateSignalOptions, type WritableSignal } from '@angular/core';
+import { type MutableSignal } from './mutable';
 /**
  * Options for creating a derived signal using the full `derived` function signature.
  * @typeParam T - The type of the source signal's value (parent).
@@ -78,7 +78,55 @@ export declare function derived<T, U>(source: WritableSignal<T>, opt: CreateDeri
  * 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]>;
+export declare function derived<T extends object, TKey extends keyof T>(source: MutableSignal<T>, key: TKey, opt?: CreateSignalOptions<T[TKey]>): DerivedSignal<T, T[TKey]> & MutableSignal<T[TKey]>;
+/**
+ * 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 object, 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.
+ *
+ * @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 & MutableSignal` 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: 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.

package/lib/effect/frame-stack.d.ts

@@ -0,0 +1,10 @@
+import { type EffectRef, type Injector } from '@angular/core';
+export type Frame = {
+    injector: Injector;
+    parent: Frame | null;
+    children: Set<EffectRef>;
+};
+export declare function currentFrame(): Frame | null;
+export declare function clearFrame(frame: Frame, userCleanups: (() => void)[]): void;
+export declare function pushFrame(frame: Frame): number;
+export declare function popFrame(): Frame | undefined;

package/lib/effect/index.d.ts

@@ -0,0 +1 @@
+export * from './nested-effect';

package/lib/effect/nested-effect.d.ts

@@ -0,0 +1,77 @@
+import { type CreateEffectOptions, type EffectCleanupRegisterFn, type EffectRef } from '@angular/core';
+import { type Frame } from './frame-stack';
+/**
+ * Creates an effect that can be nested, similar to SolidJS's `createEffect`.
+ *
+ * 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".
+ *
+ * @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
+ * // 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();
+ *     }
+ *   }
+ * );
+ * ```
+ */
+export declare function nestedEffect(effectFn: (registerCleanup: EffectCleanupRegisterFn) => void, options?: CreateEffectOptions & {
+    bindToFrame?: (parent: Frame | null) => Frame | null;
+}): EffectRef;

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

@@ -1,4 +1,4 @@
-import { Signal, ValueEqualityFn } from '@angular/core';
+import { type Signal, type ValueEqualityFn } from '@angular/core';
 /**
  * @interal
  */

package/lib/mappers/index-array.d.ts

@@ -0,0 +1,54 @@
+import { type CreateSignalOptions, type Signal, type WritableSignal } from '@angular/core';
+import { type MutableSignal } from '../mutable';
+/**
+ * Reactively maps items from a source array to a new array, creating stable signals for each item.
+ *
+ * This function is highly optimized for performance, similar to SolidJS's `mapArray`.
+ * For each item in the source array, it creates a stable signal that is passed to the mapping function.
+ * This ensures that downstream consumers only re-evaluate for items that have actually changed,
+ * or when items are added or removed from the list.
+ *
+ * The type of signal passed to the `map` function depends on the source:
+ * - **Readonly `Signal`**: `map` receives a readonly `Signal<T>`.
+ * - **`WritableSignal`**: `map` receives a `WritableSignal<T>`, allowing two-way binding.
+ * - **`MutableSignal`**: `map` receives a `MutableSignal<T>`, allowing in-place mutation for performance.
+ *
+ * @template T The type of items in the source array.
+ * @template U The type of items in the resulting mapped array.
+ *
+ * @param source A `Signal<T[]>` or a function returning `T[]`.
+ * @param map The mapping function. It receives a stable signal for the item and its index.
+ * @param options Optional configuration, including `CreateSignalOptions` for the item signals
+ * (e.g., a custom `equal` function) and an `onDestroy` callback for cleanup.
+ * @returns A `Signal<U[]>` containing the mapped array.
+ *
+ * @example
+ * // Writable example
+ * const sourceItems = signal([
+ * { id: 1, name: 'Apple' },
+ * { id: 2, name: 'Banana' }
+ * ]);
+ *
+ * // The `itemSignal` is writable because `sourceItems` is a WritableSignal.
+ * const mappedItems = indexArray(sourceItems, (itemSignal, index) => ({
+ * label: computed(() => `${index}: ${itemSignal().name.toUpperCase()}`),
+ * setName: (newName: string) => itemSignal.update(item => ({ ...item, name: newName }))
+ * }));
+ *
+ * // This will update the original source signal.
+ * mappedItems()[0].setName('Avocado');
+ * // sourceItems() is now: [{ id: 1, name: 'Avocado' }, { id: 2, name: 'Banana' }]
+ */
+export declare function indexArray<T, U>(source: MutableSignal<T[]>, map: (value: MutableSignal<T>, index: number) => U, options?: CreateSignalOptions<T> & {
+    onDestroy?: (value: U) => void;
+}): Signal<U[]>;
+export declare function indexArray<T, U>(source: WritableSignal<T[]>, map: (value: WritableSignal<T>, index: number) => U, options?: CreateSignalOptions<T> & {
+    onDestroy?: (value: U) => void;
+}): Signal<U[]>;
+export 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
+ */
+export declare const mapArray: typeof indexArray;

package/lib/mappers/index.d.ts

@@ -0,0 +1,3 @@
+export * from './index-array';
+export * from './key-array';
+export * from './map-object';

package/lib/mappers/key-array.d.ts

@@ -0,0 +1,28 @@
+import { type Signal } from '@angular/core';
+/**
+ * Reactively maps items from a source array to a new array by value (identity).
+ *
+ * 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.
+ *
+ * This is useful for building efficient lists where DOM nodes or heavy instances should be reused
+ * when the list is reordered.
+ *
+ * @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.
+ */
+export 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[]>;

package/lib/mappers/map-object.d.ts

@@ -0,0 +1,15 @@
+import { type Signal, type WritableSignal } from '@angular/core';
+import { type MutableSignal } from '../mutable';
+type MappedObject<T extends object, U> = {
+    [K in keyof T]: U;
+};
+export declare function mapObject<T extends object, 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>>;
+export declare function mapObject<T extends object, 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>>;
+export declare function mapObject<T extends object, 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>>;
+export {};

package/lib/mappers/util.d.ts

@@ -0,0 +1,9 @@
+import { type Signal, type WritableSignal } from '@angular/core';
+export declare function isWritableSignal<T>(value: Signal<T>): value is WritableSignal<T>;
+/**
+ * @internal
+ * Creates a setter function for a source signal of type `Signal<T[]>` or a function returning `T[]`.
+ * @param source The source signal of type `Signal<T[]>` or a function returning `T[]`.
+ * @returns
+ */
+export declare function createSetter<T>(source: Signal<T[]>): (value: T, index: number) => void;

package/lib/pipeable/operators.d.ts

@@ -0,0 +1,14 @@
+import { type CreateSignalOptions, type Signal } from '@angular/core';
+import { type Operator } from './types';
+/** Project with optional equality. Pure & sync. */
+export declare const select: <I, O>(projector: (v: I) => O, opt?: CreateSignalOptions<O>) => Operator<I, O>;
+/** Combine with another signal using a projector. */
+export declare const combineWith: <A, B, R>(other: Signal<B>, project: (a: A, b: B) => R, opt?: CreateSignalOptions<R>) => Operator<A, R>;
+/** Only re-emit when equal(prev, next) is false. */
+export declare const distinct: <T>(equal?: (a: T, b: T) => boolean) => Operator<T, T>;
+/** map to new value */
+export declare const map: <I, O>(fn: (v: I) => O) => Operator<I, O>;
+/** filter values, keeping the last value if it was ever available, if first value is filtered will return undefined */
+export declare const filter: <T>(predicate: (v: T) => boolean) => Operator<T, T | undefined>;
+/** tap into the value */
+export declare const tap: <T>(fn: (v: T) => void) => Operator<T, T>;

package/lib/pipeable/pipeble.d.ts

@@ -0,0 +1,23 @@
+import { type CreateSignalOptions, type Signal, type WritableSignal } from '@angular/core';
+import type { PipeableSignal, SignalValue } from './types';
+/**
+ * Decorate any `Signal<T>` with a chainable `.pipe(...)` method.
+ *
+ * @example
+ * const s = pipeable(signal(1)); // WritableSignal<number> (+ pipe)
+ * const label = s.pipe(n => n * 2, n => `#${n}`); // Signal<string> (+ pipe)
+ * label(); // "#2"
+ */
+export declare function pipeable<TSig extends Signal<any>>(signal: TSig): PipeableSignal<SignalValue<TSig>, TSig>;
+/**
+ * Create a new **writable** signal and return it as a `PipableSignal`.
+ *
+ * The returned value is a `WritableSignal<T>` with `.set`, `.update`, `.asReadonly`
+ * still available (via intersection type), plus a chainable `.pipe(...)`.
+ *
+ * @example
+ * const count = piped(1); // WritableSignal<number> (+ pipe)
+ * const even = count.pipe(n => n % 2 === 0); // Signal<boolean> (+ pipe)
+ * count.update(n => n + 1);
+ */
+export declare function piped<T>(initial: T, opt?: CreateSignalOptions<T>): PipeableSignal<T, WritableSignal<T>>;

package/lib/pipeable/public_api.d.ts

@@ -0,0 +1,3 @@
+export * from './operators';
+export * from './pipeble';
+export { type PipeableSignal } from './types';

package/lib/pipeable/types.d.ts

@@ -0,0 +1,62 @@
+import type { CreateSignalOptions, Signal } from '@angular/core';
+/**
+ * A pure, synchronous transform from I -> O.
+ * Prefer transforms without side effects to keep derivations predictable.
+ */
+export type UnaryFunction<I, O> = (a: I) => O;
+/** An Operator transforms a source Signal<I> into a derived Signal<O>. */
+export type Operator<I, O> = (src: Signal<I>) => Signal<O>;
+type SignalMap<In> = {
+    (): PipeableSignal<In>;
+    <A>(fn1: UnaryFunction<In, A>, opt?: CreateSignalOptions<A>): PipeableSignal<A>;
+    <A, B>(fn1: UnaryFunction<In, A>, fn2: UnaryFunction<A, B>, opt?: CreateSignalOptions<B>): PipeableSignal<B>;
+    <A, B, C>(fn1: UnaryFunction<In, A>, fn2: UnaryFunction<A, B>, fn3: UnaryFunction<B, C>, opt?: CreateSignalOptions<C>): PipeableSignal<C>;
+    <A, B, C, D>(fn1: UnaryFunction<In, A>, fn2: UnaryFunction<A, B>, fn3: UnaryFunction<B, C>, fn4: UnaryFunction<C, D>, opt?: CreateSignalOptions<D>): PipeableSignal<D>;
+    <A, B, C, D, E>(fn1: UnaryFunction<In, A>, fn2: UnaryFunction<A, B>, fn3: UnaryFunction<B, C>, fn4: UnaryFunction<C, D>, fn5: UnaryFunction<D, E>, opt?: CreateSignalOptions<E>): PipeableSignal<E>;
+    <A, B, C, D, E, F>(fn1: UnaryFunction<In, A>, fn2: UnaryFunction<A, B>, fn3: UnaryFunction<B, C>, fn4: UnaryFunction<C, D>, fn5: UnaryFunction<D, E>, fn6: UnaryFunction<E, F>, opt?: CreateSignalOptions<F>): PipeableSignal<F>;
+    <A, B, C, D, E, F, G>(fn1: UnaryFunction<In, A>, fn2: UnaryFunction<A, B>, fn3: UnaryFunction<B, C>, fn4: UnaryFunction<C, D>, fn5: UnaryFunction<D, E>, fn6: UnaryFunction<E, F>, fn7: UnaryFunction<F, G>, opt?: CreateSignalOptions<G>): PipeableSignal<G>;
+    <A, B, C, D, E, F, G, H>(fn1: UnaryFunction<In, A>, fn2: UnaryFunction<A, B>, fn3: UnaryFunction<B, C>, fn4: UnaryFunction<C, D>, fn5: UnaryFunction<D, E>, fn6: UnaryFunction<E, F>, fn7: UnaryFunction<F, G>, fn8: UnaryFunction<G, H>, opt?: CreateSignalOptions<H>): PipeableSignal<H>;
+    <A, B, C, D, E, F, G, H, I>(fn1: UnaryFunction<In, A>, fn2: UnaryFunction<A, B>, fn3: UnaryFunction<B, C>, fn4: UnaryFunction<C, D>, fn5: UnaryFunction<D, E>, fn6: UnaryFunction<E, F>, fn7: UnaryFunction<F, G>, fn8: UnaryFunction<G, H>, fn9: UnaryFunction<H, I>, ...rest: UnaryFunction<any, any>[]): PipeableSignal<unknown>;
+};
+/** `.pipe(...)` — compose operators (Signal -> Signal). */
+type SignalPipe<In> = {
+    (): PipeableSignal<In>;
+    <A>(op1: Operator<In, A>): PipeableSignal<A>;
+    <A, B>(op1: Operator<In, A>, op2: Operator<A, B>): PipeableSignal<B>;
+    <A, B, C>(op1: Operator<In, A>, op2: Operator<A, B>, op3: Operator<B, C>): PipeableSignal<C>;
+    <A, B, C, D>(op1: Operator<In, A>, op2: Operator<A, B>, op3: Operator<B, C>, op4: Operator<C, D>): PipeableSignal<D>;
+    <A, B, C, D, E>(op1: Operator<In, A>, op2: Operator<A, B>, op3: Operator<B, C>, op4: Operator<C, D>, op5: Operator<D, E>): PipeableSignal<E>;
+    <A, B, C, D, E, F>(op1: Operator<In, A>, op2: Operator<A, B>, op3: Operator<B, C>, op4: Operator<C, D>, op5: Operator<D, E>, op6: Operator<E, F>): PipeableSignal<F>;
+    <A, B, C, D, E, F, G>(op1: Operator<In, A>, op2: Operator<A, B>, op3: Operator<B, C>, op4: Operator<C, D>, op5: Operator<D, E>, op6: Operator<E, F>, op7: Operator<F, G>): PipeableSignal<G>;
+    <A, B, C, D, E, F, G, H>(op1: Operator<In, A>, op2: Operator<A, B>, op3: Operator<B, C>, op4: Operator<C, D>, op5: Operator<D, E>, op6: Operator<E, F>, op7: Operator<F, G>, op8: Operator<G, H>): PipeableSignal<H>;
+    <A, B, C, D, E, F, G, H, I>(op1: Operator<In, A>, op2: Operator<A, B>, op3: Operator<B, C>, op4: Operator<C, D>, op5: Operator<D, E>, op6: Operator<E, F>, op7: Operator<F, G>, op8: Operator<G, H>, op9: Operator<H, I>, ...rest: Operator<any, any>[]): PipeableSignal<unknown>;
+};
+/**
+ * A `Signal<T>` augmented with a chainable `.pipe(...)` method.
+ *
+ * The `.pipe(...)` returns **computed** signals wrapped with the same method,
+ * allowing fluent, strongly-typed pipelines.
+ * @see {@link SignalPipe}
+ * @example
+ * ```ts
+ * import { piped } from '@ngrx/signals';
+ *
+ * const count = piped(1);
+ *
+ * const doubled = count.pipe(x => x * 2); // PipeableSignal<number>
+ * // doubled() === 2
+ * const toString = doubled.pipe(String); // PipeableSignal<string>
+ * // toString() === '2'
+ * ```
+ */
+export type PipeableSignal<T, TSig extends Signal<T> = Signal<T>> = TSig & {
+    pipe: SignalPipe<T>;
+    /** Chain pure transforms to derive new signals. See {@link SignalMap}. */
+    map: SignalMap<T>;
+};
+/**
+ * Helper type to infer the value type of a signal.
+ * @internal
+ */
+export type SignalValue<TSig extends Signal<any>> = TSig extends Signal<infer V> ? V : never;
+export {};

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

@@ -0,0 +1,35 @@
+import { ElementRef, type Signal } from '@angular/core';
+/**
+ * Represents the size of an element.
+ */
+export interface ElementSize {
+    width: number;
+    height: number;
+}
+/**
+ * Options for configuring the `elementSize` sensor.
+ */
+export type ElementSizeOptions = ResizeObserverOptions & {
+    /** Optional debug name for the internal signal. */
+    debugName?: string;
+};
+export 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);
+ * });
+ * ```
+ */
+export declare function elementSize(target?: ElementRef<Element> | Element | Signal<ElementRef<Element> | Element | null>, opt?: ElementSizeOptions): ElementSizeSignal;

package/lib/{element-visibility.d.ts → sensors/element-visibility.d.ts}

@@ -1,4 +1,4 @@
-import { ElementRef, Signal } from '@angular/core';
+import { ElementRef, type Signal } from '@angular/core';
 /**
  * Options for configuring the `elementVisibility` sensor, extending
  * standard `IntersectionObserverInit` options.

package/lib/sensors/index.d.ts

@@ -1,3 +1,5 @@
+export * from './element-size';
+export * from './element-visibility';
 export * from './media-query';
 export * from './mouse-position';
 export * from './network-status';

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

@@ -1,4 +1,4 @@
-import { Signal } from '@angular/core';
+import { type Signal } from '@angular/core';
 /**
  * Creates a read-only signal that reactively tracks whether a CSS media query
  * string currently matches.

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

@@ -1,4 +1,4 @@
-import { ElementRef, Signal } from '@angular/core';
+import { ElementRef, type Signal } from '@angular/core';
 type MousePosition = {
     x: number;
     y: number;

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

@@ -1,4 +1,4 @@
-import { Signal } from '@angular/core';
+import { type Signal } from '@angular/core';
 /**
  * A specialized Signal that tracks network status.
  * It's a boolean signal with an attached `since` signal.

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

@@ -1,4 +1,4 @@
-import { Signal } from '@angular/core';
+import { type Signal } from '@angular/core';
 /**
  * Creates a read-only signal that tracks the page's visibility state.
  *