@mmstack/primitives 19.3.4 → 19.3.6

package/lib/pipeable/operators.d.ts

@@ -1,4 +1,4 @@
-import { type CreateSignalOptions, type Signal } from '@angular/core';
+import { type CreateSignalOptions, type Injector, 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>;
@@ -11,4 +11,15 @@ 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>;
+export declare const tap: <T>(fn: (v: T) => void, injector?: Injector) => Operator<T, T>;
+/**
+ * Like {@link filter}, but emits `initial` until a value passes the predicate
+ * for the first time. Avoids the `T | undefined` return type.
+ */
+export declare const filterWith: <T>(predicate: (v: T) => boolean, initial: T) => Operator<T, T>;
+/** Emits `initial` first, then mirrors source. */
+export declare const startWith: <T, U>(initial: U) => Operator<T, T | U>;
+/** Emits `[prev, curr]` pairs. The first emission has prev = undefined. */
+export declare const pairwise: <T>() => Operator<T, [T | undefined, T]>;
+/** Reduce-like accumulator across emissions. */
+export declare const scan: <T, R>(reducer: (acc: R, curr: T) => R, seed: R) => Operator<T, R>;

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

@@ -0,0 +1,14 @@
+import { type Signal } from '@angular/core';
+export type BatteryStatus = {
+    readonly level: number;
+    readonly charging: boolean;
+    readonly chargingTime: number;
+    readonly dischargingTime: number;
+};
+/**
+ * Creates a read-only signal that tracks the system battery status using the
+ * Battery Status API. Returns `null` until the underlying `getBattery()`
+ * promise resolves, or permanently when the API is unsupported (Firefox /
+ * Safari at the time of writing). SSR-safe.
+ */
+export declare function batteryStatus(debugName?: string): Signal<BatteryStatus | null>;

package/lib/sensors/clipboard.d.ts

@@ -0,0 +1,22 @@
+import { type Signal } from '@angular/core';
+export type ClipboardSignal = Signal<string> & {
+    /**
+     * Writes `value` to the system clipboard. Resolves once the write completes;
+     * rejects if the Clipboard API rejects (denied permission, insecure context).
+     */
+    readonly copy: (value: string) => Promise<void>;
+    /** `true` iff the Clipboard API is available in this environment. */
+    readonly isSupported: Signal<boolean>;
+};
+/**
+ * Creates a read-only signal mirroring the system clipboard contents.
+ *
+ * The signal value starts empty and updates whenever a `copy` event fires on
+ * the document (or {@link ClipboardSignal.copy} is invoked from this app).
+ * SSR-safe — returns `''` and `isSupported: false` on the server.
+ *
+ * Note: read access requires the Clipboard API and an active permission grant
+ * in browsers that gate it. Errors from `navigator.clipboard.readText` are
+ * swallowed silently to keep the signal value stable.
+ */
+export declare function clipboard(debugName?: string): ClipboardSignal;

package/lib/sensors/focus-within.d.ts

@@ -0,0 +1,12 @@
+import { ElementRef, type Signal } from '@angular/core';
+type FocusWithinTarget = ElementRef<Element> | Element | Signal<ElementRef<Element> | Element | null>;
+/**
+ * Creates a read-only signal that tracks whether the focused element is the
+ * target or a descendant of it. Mirrors the CSS `:focus-within` pseudo-class.
+ *
+ * Defaults `target` to the current `ElementRef` so it can be used inline in a
+ * component's `class` field. SSR-safe — returns a constant `false` signal on
+ * the server.
+ */
+export declare function focusWithin(target?: FocusWithinTarget): Signal<boolean>;
+export {};

package/lib/sensors/geolocation.d.ts

@@ -0,0 +1,29 @@
+import { type Signal } from '@angular/core';
+export type GeolocationOptions = PositionOptions & {
+    /**
+     * If `true`, uses `navigator.geolocation.watchPosition` and updates the
+     * signal continuously. Otherwise a single `getCurrentPosition` call is made.
+     * @default false
+     */
+    watch?: boolean;
+    /** Optional debug name for the produced signal. */
+    debugName?: string;
+};
+export type GeolocationSignal = Signal<GeolocationPosition | null> & {
+    readonly error: Signal<GeolocationPositionError | null>;
+    readonly loading: Signal<boolean>;
+};
+/**
+ * Creates a read-only signal that exposes the current geolocation position.
+ *
+ * The returned signal carries `error` and `loading` sub-signals for permission
+ * failures and the in-flight initial fetch respectively. SSR-safe — on the
+ * server the position is `null`, loading is `false`, and no API calls are made.
+ *
+ * @example
+ * ```ts
+ * const where = geolocation({ watch: true, enableHighAccuracy: true });
+ * effect(() => console.log(where()?.coords, where.error()));
+ * ```
+ */
+export declare function geolocation(opt?: GeolocationOptions): GeolocationSignal;

package/lib/sensors/idle.d.ts

@@ -0,0 +1,27 @@
+import { type Signal } from '@angular/core';
+export type IdleOptions = {
+    /**
+     * Milliseconds of user inactivity before the signal flips to `true`.
+     * @default 60_000
+     */
+    ms?: number;
+    /**
+     * Activity events that reset the idle timer.
+     * @default ['mousemove','keydown','touchstart','scroll','visibilitychange']
+     */
+    events?: string[];
+    /** Optional debug name for the produced signal. */
+    debugName?: string;
+};
+export type IdleSignal = Signal<boolean> & {
+    /** Timestamp of the last idle/active transition. */
+    readonly since: Signal<Date>;
+};
+/**
+ * Creates a read-only signal that flips to `true` after a window of user
+ * inactivity. Any of the configured `events` (default: pointer/keyboard/scroll
+ * activity) resets the timer and flips the signal back to `false`.
+ *
+ * SSR-safe — always `false` with a frozen `since` date on the server.
+ */
+export declare function idle(opt?: IdleOptions): IdleSignal;

package/lib/sensors/index.d.ts

@@ -1,9 +1,16 @@
+export * from './battery-status';
+export * from './clipboard';
 export * from './element-size';
 export * from './element-visibility';
+export * from './focus-within';
+export * from './geolocation';
+export * from './idle';
 export * from './media-query';
 export * from './mouse-position';
 export * from './network-status';
+export * from './orientation';
 export * from './page-visibility';
 export * from './scroll-position';
 export * from './sensor';
+export * from './signal-from-event';
 export * from './window-size';

package/lib/sensors/orientation.d.ts

@@ -0,0 +1,14 @@
+import { type Signal } from '@angular/core';
+export type ScreenOrientation = {
+    /** Angle in degrees relative to the natural orientation. */
+    readonly angle: number;
+    /** One of the four `OrientationType` strings. */
+    readonly type: OrientationType;
+};
+/**
+ * Creates a read-only signal that tracks `screen.orientation`.
+ *
+ * SSR-safe — returns a constant `portrait-primary / 0°` signal on the server
+ * and in environments without `screen.orientation` support.
+ */
+export declare function orientation(debugName?: string): Signal<ScreenOrientation>;

package/lib/sensors/sensor.d.ts

@@ -1,8 +1,13 @@
 import { type ElementRef, type Signal } from '@angular/core';
+import { type BatteryStatus } from './battery-status';
+import { type ClipboardSignal } from './clipboard';
 import { type ElementSizeOptions as BaseElementSizeOptions, type ElementSizeSignal } from './element-size';
 import { type ElementVisibilityOptions as BaseElementVisibilityOptions, type ElementVisibilitySignal } from './element-visibility';
+import { type GeolocationOptions, type GeolocationSignal } from './geolocation';
+import { type IdleOptions, type IdleSignal } from './idle';
 import { type MousePositionOptions, type MousePositionSignal } from './mouse-position';
 import { type NetworkStatusSignal } from './network-status';
+import { type ScreenOrientation } from './orientation';
 import { type ScrollPositionOptions, type ScrollPositionSignal } from './scroll-position';
 import { type WindowSizeOptions, type WindowSizeSignal } from './window-size';
 type SensorTypedOptions = {
@@ -61,6 +66,39 @@ type SensorTypedOptions = {
         };
         returnType: Signal<boolean>;
     };
+    geolocation: {
+        opt: GeolocationOptions;
+        returnType: GeolocationSignal;
+    };
+    clipboard: {
+        opt: {
+            debugName?: string;
+        };
+        returnType: ClipboardSignal;
+    };
+    orientation: {
+        opt: {
+            debugName?: string;
+        };
+        returnType: Signal<ScreenOrientation>;
+    };
+    batteryStatus: {
+        opt: {
+            debugName?: string;
+        };
+        returnType: Signal<BatteryStatus | null>;
+    };
+    idle: {
+        opt: IdleOptions;
+        returnType: IdleSignal;
+    };
+    focusWithin: {
+        opt: {
+            debugName?: string;
+            target?: ElementRef<Element> | Element | Signal<ElementRef<Element> | Element | null>;
+        };
+        returnType: Signal<boolean>;
+    };
 };
 /**
  * Creates a sensor signal that the elements visiblity within the viewport
@@ -152,6 +190,36 @@ export declare function sensor(type: 'windowSize', options?: SensorTypedOptions[
  * @example const pageScroll = sensor('scrollPosition', { throttle: 150 });
  */
 export declare function sensor(type: 'scrollPosition', options?: SensorTypedOptions['scrollPosition']['opt']): ScrollPositionSignal;
+/**
+ * Creates a sensor signal exposing the device's current geolocation position.
+ * @see {geolocation}
+ */
+export declare function sensor(type: 'geolocation', options?: SensorTypedOptions['geolocation']['opt']): GeolocationSignal;
+/**
+ * Creates a sensor signal mirroring the system clipboard contents.
+ * @see {clipboard}
+ */
+export declare function sensor(type: 'clipboard', options?: SensorTypedOptions['clipboard']['opt']): ClipboardSignal;
+/**
+ * Creates a sensor signal tracking the screen orientation.
+ * @see {orientation}
+ */
+export declare function sensor(type: 'orientation', options?: SensorTypedOptions['orientation']['opt']): Signal<ScreenOrientation>;
+/**
+ * Creates a sensor signal tracking the system battery status.
+ * @see {batteryStatus}
+ */
+export declare function sensor(type: 'batteryStatus', options?: SensorTypedOptions['batteryStatus']['opt']): Signal<BatteryStatus | null>;
+/**
+ * Creates a sensor signal that flips to `true` after a window of user inactivity.
+ * @see {idle}
+ */
+export declare function sensor(type: 'idle', options?: SensorTypedOptions['idle']['opt']): IdleSignal;
+/**
+ * Creates a sensor signal tracking whether focus is within a target subtree.
+ * @see {focusWithin}
+ */
+export declare function sensor(type: 'focusWithin', options?: SensorTypedOptions['focusWithin']['opt']): Signal<boolean>;
 type SensorsOptions<TKey extends keyof SensorTypedOptions> = {
     [K in TKey]: SensorTypedOptions[K]['opt'];
 };

package/lib/sensors/signal-from-event.d.ts

@@ -0,0 +1,42 @@
+import { DestroyRef, ElementRef, Injector, type Signal } from '@angular/core';
+/**
+ * Options for {@link signalFromEvent}. Extends the native
+ * `AddEventListenerOptions` so callers can opt into `capture`, `passive`, etc.
+ */
+export type SignalFromEventOptions = AddEventListenerOptions & {
+    /** Optional debug name for the produced signal. */
+    debugName?: string;
+    /** Override the DestroyRef used to remove the listener on teardown. */
+    destroyRef?: DestroyRef;
+    /** Override the Injector used to inject dependencies. */
+    injector?: Injector;
+};
+type EventTargetLike = EventTarget | ElementRef<EventTarget>;
+type ResolvableTarget = EventTargetLike | Signal<EventTargetLike | null>;
+/**
+ * Creates a read-only signal that emits the latest event dispatched on a
+ * target. The target can be a static `EventTarget`, an `ElementRef`, or a
+ * `Signal` that resolves to one (or `null` to detach).
+ *
+ * SSR-safe: on the server the signal returns the provided `initial` value and
+ * no listener is registered.
+ *
+ * @example
+ * ```ts
+ * const click = signalFromEvent(document, 'click', null);
+ * ```
+ *
+ * @example
+ * ```ts
+ * // With a projection — store just the coordinates.
+ * const point = signalFromEvent<MouseEvent, { x: number; y: number }>(
+ *   document,
+ *   'mousemove',
+ *   { x: 0, y: 0 },
+ *   (e) => ({ x: e.clientX, y: e.clientY }),
+ * );
+ * ```
+ */
+export declare function signalFromEvent<TEvent extends Event>(target: ResolvableTarget, eventName: string, initial: TEvent | null, opt?: SignalFromEventOptions): Signal<TEvent | null>;
+export declare function signalFromEvent<TEvent extends Event, U>(target: ResolvableTarget, eventName: string, initial: U, project: (event: TEvent) => U, opt?: SignalFromEventOptions): Signal<U>;
+export {};

package/lib/tabSync.d.ts

@@ -12,45 +12,19 @@ export declare class MessageBus {
     static ɵprov: i0.ɵɵInjectableDeclaration<MessageBus>;
 }
 export declare function generateDeterministicID(): string;
-type SyncSignalOptions = {
+type LegacySyncSignalOptions = {
     id?: string;
 };
+export type SyncSignalOptions = {
+    id: string;
+};
+/**
+ * @example tabSync(signal('dark), {id: 'theme})
+ */
+export declare function tabSync<T extends WritableSignal<any>>(sig: T, opt: SyncSignalOptions | string): T;
 /**
- * Synchronizes a WritableSignal across browser tabs using BroadcastChannel API.
- *
- * Creates a shared signal that automatically syncs its value between all tabs
- * of the same application. When the signal is updated in one tab, all other
- * tabs will receive the new value automatically.
- *
- * @template T - The type of the WritableSignal
- * @param sig - The WritableSignal to synchronize across tabs
- * @param opt - Optional configuration object
- * @param opt.id - Explicit channel ID for synchronization. If not provided,
- *                 a deterministic ID is generated based on the call site.
- *                 Use explicit IDs in production for reliability.
- *
- * @returns The same WritableSignal instance, now synchronized across tabs
- *
+ * @deprecated Use `tabSync` with `SyncSignalOptions` instead and pass the options as the second argument
  * @throws {Error} When deterministic ID generation fails and no explicit ID is provided
- *
- * @example
- * ```typescript
- * // Basic usage - auto-generates channel ID from call site
- * const theme = tabSync(signal('dark'));
- *
- * // With explicit ID (recommended for production)
- * const userPrefs = tabSync(signal({ lang: 'en' }), { id: 'user-preferences' });
- *
- * // Changes in one tab will sync to all other tabs
- * theme.set('light'); // All tabs will update to 'light'
- * ```
- *
- * @remarks
- * - Only works in browser environments (returns original signal on server)
- * - Uses a single BroadcastChannel for all synchronized signals
- * - Automatically cleans up listeners when the injection context is destroyed
- * - Initial signal value after sync setup is not broadcasted to prevent loops
- *
  */
-export declare function tabSync<T extends WritableSignal<any>>(sig: T, opt?: SyncSignalOptions): T;
+export declare function tabSync<T extends WritableSignal<any>>(sig: T, opt?: LegacySyncSignalOptions): T;
 export {};

package/lib/throttled.d.ts

@@ -19,6 +19,18 @@ export type CreateThrottledOptions<T> = CreateSignalOptions<T> & {
      * If it is not provided or injected, the timer will not be cleared automatically...which is usually fine :)
      */
     destroyRef?: DestroyRef;
+    /**
+     * If `true`, the throttled signal emits the first value immediately when a
+     * burst starts, then enforces the cooldown window before the next emission.
+     * @default false
+     */
+    leading?: boolean;
+    /**
+     * If `true`, the throttled signal emits the latest pending value at the end
+     * of each cooldown window (only when at least one write occurred during it).
+     * @default true
+     */
+    trailing?: boolean;
 };
 /**
  * A specialized `WritableSignal` whose publicly readable value updates are throttled.

package/lib/with-history.d.ts

@@ -91,4 +91,4 @@ export type CreateHistoryOptions<T> = Omit<CreateSignalOptions<T[]>, 'equal'> &
  * console.log('Can undo:', name.canUndo()); // false
  * ```
  */
-export declare function withHistory<T>(source: WritableSignal<T>, opt?: CreateHistoryOptions<T>): SignalWithHistory<T>;
+export declare function withHistory<T>(sourceOrValue: WritableSignal<T> | T, opt?: CreateHistoryOptions<T>): SignalWithHistory<T>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmstack/primitives",
-  "version": "19.3.4",
+  "version": "19.3.6",
   "keywords": [
     "angular",
     "signals",