@mmstack/primitives 19.2.0 → 19.2.2

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

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

package/lib/sensors/sensor.d.ts

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

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

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

package/lib/until.d.ts

@@ -1,4 +1,4 @@
-import { DestroyRef, Signal } from '@angular/core';
+import { DestroyRef, Injector, Signal } from '@angular/core';
 export type UntilOptions = {
     /**
      * Optional timeout in milliseconds. If the condition is not met
@@ -11,6 +11,7 @@ export type UntilOptions = {
      * If not provided, it will attempt to inject one if called in an injection context.
      */
     destroyRef?: DestroyRef;
+    injector?: Injector;
 };
 /**
  * Creates a Promise that resolves when a signal's value satisfies a given predicate.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmstack/primitives",
-  "version": "19.2.0",
+  "version": "19.2.2",
   "keywords": [
     "angular",
     "signals",
@@ -15,7 +15,7 @@
   },
   "homepage": "https://github.com/mihajm/mmstack/blob/master/packages/primitives",
   "dependencies": {
-    "@mmstack/object": "^19.1.0",
+    "@mmstack/object": "^19.2.0",
     "tslib": "^2.3.0"
   },
   "peerDependencies": {