@mmstack/primitives 19.2.0 → 19.2.2

package/README.md

@@ -23,8 +23,10 @@ This library provides the following primitives:
 - `mapArray` - Maps a reactive array efficently into an array of stable derivations.
 - `toWritable` - Converts a read-only signal to writable using custom write logic.
 - `derived` - Creates a signal with two-way binding to a source signal.
-- `sensor` - A facade function to create various reactive sensor signals (e.g., mouse position, network status, page visibility, dark mode preference)." (This makes it flow a bit better and more accurately lists what the facade produces.)
+- `sensor` - A facade function to create various reactive sensor signals (e.g., mouse position, network status, page visibility, dark mode preference)." (This was the suggestion from before; it just reads a little smoother and more accurately reflects what the facade creates directly).
 - `until` - Creates a Promise that resolves when a signal's value meets a specific condition.
+- `mediaQuery` - A generic primitive that tracks a CSS media query (forms the basis for `prefersDarkMode` and `prefersReducedMotion`).
+- `elementVisibility` - Tracks if an element is intersecting the viewport using IntersectionObserver.
 
 ---
 
@@ -289,6 +291,8 @@ Enhances any WritableSignal with a complete undo/redo history stack. This is use
 ```typescript
 import { FormsModule } from '@angular/forms';
 import { JsonPipe } from '@angular/common';
+import { withHistory } from '@mmstack/primitives';
+import { Component, signal, effect } from '@angular/core';
 
 @Component({
   selector: 'app-history-demo',
@@ -321,9 +325,13 @@ export class HistoryDemoComponent {
 
 ### sensor
 
-The sensor() facade provides a unified way to create various reactive sensor signals that track browser events, states, and user preferences. You specify the type of sensor you want, and it returns the corresponding signal, often with specific properties or methods. These primitives are generally SSR-safe and handle their own event listener cleanup.
+### sensor
+
+The `sensor()` facade provides a unified way to create various reactive sensor signals that track browser events, states, and user preferences. You specify the type of sensor you want (e.g., `'mousePosition'`, `'networkStatus'`, `'windowSize'`, `'dark-mode'`), and it returns the corresponding signal, often with specific properties or methods. These primitives are generally SSR-safe and handle their own event listener cleanup.
+
+You can either use the `sensor('sensorType', options)` facade or import the specific sensor functions directly if you prefer.
 
-You can either use the sensor('sensorType', options) facade or import the specific sensor functions directly.
+**Facade Usage Example:**
 
 ```typescript
 import { sensor } from '@mmstack/primitives';
@@ -331,10 +339,12 @@ import { effect } from '@angular/core';
 
 const network = sensor('networkStatus');
 const mouse = sensor('mousePosition', { throttle: 50, coordinateSpace: 'page' });
+const winSize = sensor('windowSize', { throttle: 150 });
 const isDark = sensor('dark-mode');
 
 effect(() => console.log('Online:', network().isOnline));
 effect(() => console.log('Mouse X:', mouse().x));
+effect(() => console.log('Window Width:', winSize().width));
 effect(() => console.log('Dark Mode Preferred:', isDark()));
 ```
 
@@ -439,6 +449,73 @@ export class VisibilityLoggerComponent {
 }
 ```
 
+#### windowSize
+
+Tracks the browser window's inner dimensions (width and height). Updates are throttled by default (100ms). It provides the main throttled signal and an .unthrottled property to access raw updates.
+
+```typescript
+import { Component, effect, computed } from '@angular/core';
+import { sensor } from '@mmstack/primitives'; // Or import { windowSize }
+
+@Component({
+  selector: 'app-responsive-display',
+  standalone: true,
+  template: `
+    <p>Current Window Size: {{ winSize().width }}px x {{ winSize().height }}px</p>
+    <p>Unthrottled: W: {{ winSize.unthrottled().width }} H: {{ winSize.unthrottled().height }}</p>
+    @if (isMobileDisplay()) {
+      <p>Displaying mobile layout.</p>
+    } @else {
+      <p>Displaying desktop layout.</p>
+    }
+  `,
+})
+export class ResponsiveDisplayComponent {
+  readonly winSize = sensor('windowSize', { throttle: 150 });
+  // Or: readonly winSize = windowSize({ throttle: 150 });
+
+  readonly isMobileDisplay = computed(() => this.winSize().width < 768);
+
+  constructor() {
+    effect(() => console.log('Window Size (Throttled):', this.winSize()));
+  }
+}
+```
+
+#### scrollPosition
+
+Tracks the scroll position (x, y) of the window or a specified HTML element. Updates are throttled by default (100ms). It provides the main throttled signal and an .unthrottled property to access raw updates.
+
+```typescript
+import { Component, effect, ElementRef, viewChild } from '@angular/core';
+import { sensor } from '@mmstack/primitives'; // Or import { scrollPosition }
+import { JsonPipe } from '@angular/common';
+
+@Component({
+  selector: 'app-scroll-indicator',
+  standalone: true,
+  imports: [JsonPipe],
+  template: `
+    <div style="height: 100px; border-bottom: 2px solid red; position: fixed; top: 0; left: 0; width: 100%; background: white; z-index: 10;">
+      Page Scroll Y: {{ pageScroll().y }}px
+      <p>Unthrottled Y: {{ pageScroll.unthrottled().y }}</p>
+    </div>
+    <div #scrollableContent style="height: 2000px; padding-top: 120px;">Scroll down...</div>
+  `,
+})
+export class ScrollIndicatorComponent {
+  readonly pageScroll = sensor('scrollPosition', { throttle: 50 });
+  // Or: readonly pageScroll = scrollPosition({ throttle: 50 });
+
+  constructor() {
+    effect(() => {
+      // Example: Change header style based on scroll
+      console.log('Page scroll Y (Throttled):', this.pageScroll().y);
+    });
+  }
+}
+```
+
 #### mediaQuery, prefersDarkMode() & prefersReducedMotion()
 
 A generic mediaQuery primitive, you can use directly for any CSS media query. Two specific versions have been created for `prefersDarkMode()` & `prefersReducedMotion()`.
@@ -499,3 +576,44 @@ it('should reject on timeout if the condition is not met in time', async () => {
   await expect(untilPromise).toThrow(`until: Timeout after ${timeoutDuration}ms.`);
 });
 ```
+
+### elementVisibility
+
+Tracks if a target DOM element is intersecting with the viewport (or a specified root element) using the `IntersectionObserver` API. This is highly performant for use cases like lazy-loading content or triggering animations when elements scroll into view.
+
+It can observe a static `ElementRef`/`Element` or a `Signal` that resolves to one, allowing for dynamic targets. The returned signal emits the full `IntersectionObserverEntry` object (or `undefined`) & exposes a sub-signal `.visible` which is just a boolean signal for ease of use
+
+```typescript
+import { Component, effect, ElementRef, viewChild, computed } from '@angular/core';
+import { elementVisibility } from '@mmstack/primitives';
+
+@Component({
+  selector: 'app-lazy-load-item',
+  standalone: true,
+  template: `
+    <div #itemToObserve style="height: 300px; margin-top: 100vh; border: 2px solid green;">
+      @if (intersectionEntry.isVisible()) {
+        <p>This content was lazy-loaded because it became visible!</p>
+      } @else {
+        <p>Item is off-screen. Scroll down to load it.</p>
+      }
+    </div>
+  `,
+})
+export class LazyLoadItemComponent {
+  readonly itemRef = viewChild.required<ElementRef<HTMLDivElement>>('itemToObserve');
+
+  // Observe the element, get the full IntersectionObserverEntry
+  readonly intersectionEntry = elementVisibility(this.itemRef);
+
+  constructor() {
+    effect(() => {
+      if (this.isVisible()) {
+        console.log('Item is now visible!', this.intersectionEntry());
+      } else {
+        console.log('Item is no longer visible or not yet visible.');
+      }
+    });
+  }
+}
+```

package/fesm2022/mmstack-primitives.mjs

@@ -1,4 +1,4 @@
-import { untracked, signal, inject, DestroyRef, computed, isSignal, linkedSignal, PLATFORM_ID, ElementRef, isDevMode, effect } from '@angular/core';
+import { untracked, signal, inject, DestroyRef, computed, PLATFORM_ID, isSignal, effect, ElementRef, linkedSignal, isDevMode, Injector, runInInjectionContext } from '@angular/core';
 import { isPlatformServer } from '@angular/common';
 import { SIGNAL } from '@angular/core/primitives/signals';
 
@@ -201,6 +201,108 @@ function isDerivation(sig) {
     return 'from' in sig;
 }
 
+function observerSupported() {
+    return typeof IntersectionObserver !== 'undefined';
+}
+/**
+ * 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());
+ * });
+ * }
+ * }
+ * ```
+ */
+function elementVisibility(target, opt) {
+    if (isPlatformServer(inject(PLATFORM_ID)) || !observerSupported()) {
+        const base = computed(() => undefined, {
+            debugName: opt?.debugName,
+        });
+        base.visible = computed(() => false);
+        return base;
+    }
+    const state = signal(undefined, {
+        debugName: opt?.debugName,
+        equal: (a, b) => {
+            if (!a && !b)
+                return true;
+            if (!a || !b)
+                return false;
+            return (a.target === b.target &&
+                a.isIntersecting === b.isIntersecting &&
+                a.intersectionRatio === b.intersectionRatio &&
+                a.boundingClientRect.top === b.boundingClientRect.top &&
+                a.boundingClientRect.left === b.boundingClientRect.left &&
+                a.boundingClientRect.width === b.boundingClientRect.width &&
+                a.boundingClientRect.height === b.boundingClientRect.height);
+        },
+    });
+    const targetSignal = isSignal(target) ? target : computed(() => target);
+    effect((cleanup) => {
+        const el = targetSignal();
+        if (!el)
+            return state.set(undefined);
+        let observer = null;
+        observer = new IntersectionObserver(([entry]) => state.set(entry), opt);
+        observer.observe(el instanceof ElementRef ? el.nativeElement : el);
+        cleanup(() => {
+            observer?.disconnect();
+        });
+    });
+    const base = state.asReadonly();
+    base.visible = computed(() => {
+        const s = state();
+        if (!s)
+            return false;
+        return s.isIntersecting;
+    });
+    return base;
+}
+
 /**
  * Reactively maps items from a source array (or signal of an array) using a provided mapping function.
  *
@@ -712,6 +814,169 @@ function pageVisibility(debugName) {
     return visibility.asReadonly();
 }
 
+/**
+ * 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());
+ * }
+ * });
+ * }
+ * }
+ * ```
+ */
+function scrollPosition(opt) {
+    if (isPlatformServer(inject(PLATFORM_ID))) {
+        const base = computed(() => ({
+            x: 0,
+            y: 0,
+        }), {
+            debugName: opt?.debugName,
+        });
+        base.unthrottled = base;
+        return base;
+    }
+    const { target = window, throttle = 100, debugName } = opt || {};
+    let element;
+    let getScrollPosition;
+    if (target instanceof Window) {
+        element = target;
+        getScrollPosition = () => {
+            return { x: target.scrollX, y: target.scrollY };
+        };
+    }
+    else if (target instanceof ElementRef) {
+        element = target.nativeElement;
+        getScrollPosition = () => {
+            return {
+                x: target.nativeElement.scrollLeft,
+                y: target.nativeElement.scrollTop,
+            };
+        };
+    }
+    else {
+        element = target;
+        getScrollPosition = () => {
+            return {
+                x: target.scrollLeft,
+                y: target.scrollTop,
+            };
+        };
+    }
+    const state = throttled(getScrollPosition(), {
+        debugName,
+        equal: (a, b) => a.x === b.x && a.y === b.y,
+        ms: throttle,
+    });
+    const onScroll = () => state.set(getScrollPosition());
+    element.addEventListener('scroll', onScroll, { passive: true });
+    inject(DestroyRef).onDestroy(() => element.removeEventListener('scroll', onScroll));
+    const base = state.asReadonly();
+    base.unthrottled = state.original;
+    return base;
+}
+
+/**
+ * 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());
+ * });
+ * }
+ * }
+ * ```
+ */
+function windowSize(opt) {
+    if (isPlatformServer(inject(PLATFORM_ID))) {
+        const base = computed(() => ({
+            width: 1024,
+            height: 768,
+        }), { debugName: opt?.debugName });
+        base.unthrottled = base;
+        return base;
+    }
+    const sizeSignal = throttled({ width: window.innerWidth, height: window.innerHeight }, {
+        debugName: opt?.debugName,
+        equal: (a, b) => a.width === b.width && a.height === b.height,
+        ms: opt?.throttle ?? 100,
+    });
+    const onResize = () => {
+        sizeSignal.set({ width: window.innerWidth, height: window.innerHeight });
+    };
+    window.addEventListener('resize', onResize);
+    inject(DestroyRef).onDestroy(() => {
+        window.removeEventListener('resize', onResize);
+    });
+    const base = sizeSignal.asReadonly();
+    base.unthrottled = sizeSignal.original;
+    return base;
+}
+
 /**
  * Implementation for sensor overloads.
  * Users should refer to the specific overloads for detailed documentation.
@@ -729,6 +994,10 @@ function sensor(type, options) {
             return prefersDarkMode(options?.debugName);
         case 'reduced-motion':
             return prefersReducedMotion(options?.debugName);
+        case 'windowSize':
+            return windowSize(options);
+        case 'scrollPosition':
+            return scrollPosition(options);
         default:
             throw new Error(`Unknown sensor type: ${type}`);
     }
@@ -928,6 +1197,7 @@ function stored(fallback, { key, store: providedStore, serialize = JSON.stringif
  * ```
  */
 function until(sourceSignal, predicate, options = {}) {
+    const injector = options.injector ?? inject(Injector);
     return new Promise((resolve, reject) => {
         let effectRef;
         let timeoutId;
@@ -967,14 +1237,16 @@ function until(sourceSignal, predicate, options = {}) {
         if (options?.timeout !== undefined) {
             timeoutId = setTimeout(() => cleanupAndReject(`until: Timeout after ${options.timeout}ms.`), options.timeout);
         }
-        effectRef = effect(() => {
-            if (settled) {
-                return effectRef?.destroy();
-            }
-            const currentValue = sourceSignal();
-            if (predicate(currentValue)) {
-                cleanupAndResolve(currentValue);
-            }
+        runInInjectionContext(injector, () => {
+            effectRef = effect(() => {
+                if (settled) {
+                    return effectRef?.destroy();
+                }
+                const currentValue = sourceSignal();
+                if (predicate(currentValue)) {
+                    cleanupAndResolve(currentValue);
+                }
+            });
         });
     });
 }
@@ -1118,5 +1390,5 @@ function withHistory(source, opt) {
  * Generated bundle index. Do not edit.
  */
 
-export { debounce, debounced, derived, isDerivation, isMutable, mapArray, mediaQuery, mousePosition, mutable, networkStatus, pageVisibility, prefersDarkMode, prefersReducedMotion, sensor, stored, throttle, throttled, toFakeDerivation, toFakeSignalDerivation, toWritable, until, withHistory };
+export { debounce, debounced, derived, elementVisibility, isDerivation, isMutable, mapArray, mediaQuery, mousePosition, mutable, networkStatus, pageVisibility, prefersDarkMode, prefersReducedMotion, scrollPosition, sensor, stored, throttle, throttled, toFakeDerivation, toFakeSignalDerivation, toWritable, until, windowSize, withHistory };
 //# sourceMappingURL=mmstack-primitives.mjs.map