@mmstack/primitives 20.4.4 → 20.4.5

package/index.d.ts

@@ -1160,6 +1160,48 @@ 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>;
 
+type SyncSignalOptions = {
+    id?: string;
+};
+/**
+ * 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
+ *
+ * @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
+ *
+ */
+declare function tabSync<T extends WritableSignal<any>>(sig: T, opt?: SyncSignalOptions): T;
+
 /**
  * Options for creating a throttled writable signal.
  * Extends Angular's `CreateSignalOptions` with a throttle time setting.
@@ -1414,5 +1456,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, networkStatus, pageVisibility, pipeable, piped, prefersDarkMode, prefersReducedMotion, scrollPosition, select, sensor, stored, tap, throttle, throttled, toFakeDerivation, toFakeSignalDerivation, toWritable, until, windowSize, withHistory };
+export { combineWith, debounce, debounced, derived, distinct, elementVisibility, filter, isDerivation, isMutable, map, mapArray, mediaQuery, mousePosition, mutable, 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 };

package/package.json

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