@applicaster/zapp-react-native-utils 15.0.0-rc.99 → 16.0.0-rc.1

package/refreshUtils/RefreshCoordinator/index.ts

@@ -0,0 +1,245 @@
+import { noop } from "@applicaster/zapp-react-native-utils/functionUtils";
+import { interval, Subject, Subscription } from "rxjs";
+import { map, filter, throttleTime } from "rxjs/operators";
+
+import { getDataRefreshConfig } from "./utils";
+
+export { getDataRefreshConfig, type RefreshConfig } from "./utils";
+
+const THROTTLE_TIMEOUT = 500; // ms
+
+type ComponentToRefresh = {
+  component: ZappUIComponent;
+  screenId: string;
+};
+
+/**
+ * Public contract for refresh coordination.
+ *
+ * The coordinator serves as an event bus for component refresh events.
+ * It supports two types of producers and any number of consumers:
+ *
+ * Producers (push events into refresh$):
+ *   register()        → starts a periodic timer that emits refresh events
+ *   triggerRefresh()   → imperatively emits refresh events (e.g. pull-to-refresh)
+ *
+ * Consumers (react to refresh events):
+ *   subscribeTo()     → listen to refresh events for a specific component/screen
+ *   subscribeToAny()  → listen to all refresh events with throttling
+ *
+ * Note: subscribeTo() works independently of register(). A component can
+ * subscribe to refresh events without having auto-refresh enabled.
+ * This is how pull-to-refresh works — triggerRefresh() pushes events that
+ * are picked up by existing subscribeTo() listeners in UrlFeedResolver,
+ * even for components that don't have periodic auto-refresh timers.
+ */
+interface IRefreshCoordinator {
+  register(component: ZappUIComponent, screenId: string): () => void;
+  triggerRefresh(components: ZappUIComponent[], screenId: string): void;
+  subscribeTo(
+    component: ZappUIComponent,
+    screenId: string,
+    listener: () => void
+  ): Subscription;
+  subscribeToAny(
+    listener: (componentToRefresh: ComponentToRefresh) => void
+  ): Subscription;
+}
+
+/**
+ * Singleton implementation of RefreshCoordinator.
+ *
+ * Design goals:
+ * - One shared coordinator across the app
+ * - Central refresh$ event bus for all refresh events
+ * - Multiple producers: periodic timers (register) and imperative triggers (triggerRefresh)
+ * - Multiple consumers: per-component (subscribeTo) and global (subscribeToAny)
+ * - Producers and consumers are independent — subscribeTo works without register
+ * - Safe cleanup of timers and subscriptions
+ */
+class RefreshCoordinator implements IRefreshCoordinator {
+  private static instance: RefreshCoordinator;
+
+  /**
+   * Active timers per component/screen pair ((componentId, screenId) → RxJS Subscription).
+   * Each entry is keyed by a composite of componentId and screenId (via getKey),
+   * and gets its own interval stream for periodic refresh.
+   */
+  private timers: Map<string, Subscription> = new Map();
+
+  /**
+   * Central event stream emitting components that need refresh.
+   * All component interval streams push into this Subject.
+   * Multiple listeners can subscribe to receive refresh events for specific components.
+   * This is the core stream that coordinates all refresh operations.
+   */
+  private refresh$ = new Subject<ComponentToRefresh>();
+
+  // Store the current single subscriber for subscribeToAny
+  private anyListenerSubscription?: Subscription;
+
+  private constructor() {}
+
+  public static getInstance(): RefreshCoordinator {
+    if (!RefreshCoordinator.instance) {
+      RefreshCoordinator.instance = new RefreshCoordinator();
+    }
+
+    return RefreshCoordinator.instance;
+  }
+
+  /**
+   * Registers a component for periodic refresh.
+   *
+   * Behavior:
+   * - If the component was previously registered, its timer is replaced.
+   * - If refreshing is disabled, nothing is scheduled.
+   * - Returns an unregister function for manual cleanup.
+   * - Each component gets its own interval stream for periodic refresh.
+   */
+  public register(component: ZappUIComponent, screenId: string): () => void {
+    const componentId: ZappUIComponent["id"] = component.id;
+
+    // Ensure no duplicate timer exists for this component
+    this.unregister(componentId, screenId);
+
+    const refreshConfig = getDataRefreshConfig(component);
+
+    // If refreshing disabled → do nothing
+    if (!refreshConfig.isRefreshingEnabled) {
+      return noop;
+    }
+
+    /**
+     * Create interval stream:
+     * - Emits every refreshIntervalMs
+     * - Maps emission to the ComponentToRefresh object
+     * - Pushes component into central refresh$ stream
+     */
+    const subscription: Subscription = interval(refreshConfig.refreshIntervalMs)
+      .pipe(
+        map(() => ({
+          component,
+          screenId,
+        }))
+      )
+      .subscribe(this.refresh$);
+
+    this.timers.set(this.getKey(componentId, screenId), subscription);
+
+    return (): void => this.unregister(componentId, screenId);
+  }
+
+  /**
+   * Imperatively triggers refresh for the given components on a screen.
+   *
+   * Pushes each component into the central refresh$ stream so that
+   * existing subscribers (e.g. UrlFeedResolver's reloadData) react
+   * to the event. Used by pull-to-refresh and programmatic refresh.
+   */
+  public triggerRefresh(components: ZappUIComponent[], screenId: string): void {
+    components.forEach((component) => {
+      this.refresh$.next({ component, screenId });
+    });
+  }
+
+  /**
+   * Stops and removes timer for a specific component.
+   * Cleans up the RxJS subscription for that component's interval stream.
+   */
+  private unregister(
+    componentId: ZappUIComponent["id"],
+    screenId: string
+  ): void {
+    const key = this.getKey(componentId, screenId);
+    const subscription: Subscription | undefined = this.timers.get(key);
+
+    if (subscription) {
+      subscription.unsubscribe();
+      this.timers.delete(key);
+    }
+  }
+
+  private getKey(componentId: ZappUIComponent["id"], screenId: string): string {
+    return `componentId:${componentId}___screenId:${screenId}`;
+  }
+
+  /**
+   * Subscribes to refresh events for a specific component.
+   *
+   * Each subscription is independent - multiple listeners can subscribe
+   * to the same component's refresh events.
+   */
+  public subscribeTo(
+    component: ZappUIComponent,
+    screenId: string,
+    listener: () => void
+  ): Subscription {
+    return this.refresh$
+      .pipe(
+        filter(
+          (componentToRefresh: ComponentToRefresh) =>
+            componentToRefresh.component.id === component.id &&
+            componentToRefresh.screenId === screenId
+        )
+      )
+      .subscribe(listener);
+  }
+
+  /**
+   * Subscribes a single global listener to all refresh events.
+   *
+   * Behavior:
+   * - Only one active listener exists at a time.
+   *   - If a previous listener was already subscribed, it is automatically unsubscribed.
+   * - Throttles refresh events to emit at most once per THROTTLE_TIMEOUT interval.
+   * - Useful for scenarios where you want a single handler to react
+   *   to any component refresh without having multiple active callbacks.
+   *
+   * @param listener - Callback to invoke whenever any component triggers a refresh
+   * @returns The RxJS Subscription object for this listener
+   */
+  public subscribeToAny(
+    listener: (componentToRefresh: ComponentToRefresh) => void
+  ): Subscription {
+    // Unsubscribe previous listener if present to enforce "single active listener" policy
+    if (this.anyListenerSubscription) {
+      this.anyListenerSubscription.unsubscribe();
+    }
+
+    // Create a new throttled subscription
+    this.anyListenerSubscription = this.refresh$
+      .pipe(throttleTime(THROTTLE_TIMEOUT))
+      .subscribe(listener);
+
+    return this.anyListenerSubscription;
+  }
+
+  /**
+   * Fully resets coordinator state.
+   *
+   * Clears:
+   * - All component timers
+   * - Any active "subscribeToAny" listener
+   * - Recreates internal Subject to allow fresh subscriptions
+   */
+  public clear(): void {
+    // Stop and remove all active timers
+    this.timers.forEach((sub: Subscription) => sub.unsubscribe());
+    this.timers.clear();
+
+    // Stop any active "subscribeToAny" subscription
+    if (this.anyListenerSubscription) {
+      this.anyListenerSubscription.unsubscribe();
+      this.anyListenerSubscription = undefined;
+    }
+
+    // Complete old Subject to release subscribers
+    this.refresh$.complete();
+
+    // Recreate Subject so coordinator can be reused
+    this.refresh$ = new Subject<ComponentToRefresh>();
+  }
+}
+
+export const refreshCoordinator = RefreshCoordinator.getInstance();

package/refreshUtils/RefreshCoordinator/utils/__tests__/getDataRefreshConfig.test.ts

@@ -0,0 +1,104 @@
+import {
+  getDataRefreshConfig,
+  MINIMUM_REFRESHING_INTERVAL_IN_SECONDS,
+  DEFAULT_REFRESHING_INTERVAL_IN_SECONDS,
+} from "..";
+
+describe("getDataRefreshConfig", () => {
+  it("returns correct values when rules are defined", () => {
+    const component = {
+      rules: {
+        enable_data_refreshing: true,
+        refreshing_interval: 30,
+      },
+    } as any;
+
+    const result = getDataRefreshConfig(component);
+
+    expect(result).toEqual({
+      isRefreshingEnabled: true,
+      refreshIntervalMs: 30 * 1000,
+    });
+  });
+
+  it("returns false for isRefreshingEnabled if rules flag is false", () => {
+    const component = {
+      rules: {
+        enable_data_refreshing: false,
+        refreshing_interval: 45,
+      },
+    } as any;
+
+    const result = getDataRefreshConfig(component);
+
+    expect(result).toEqual({
+      isRefreshingEnabled: false,
+      refreshIntervalMs: 45 * 1000,
+    });
+  });
+
+  it("applies minimum interval if given interval is too low", () => {
+    const component = {
+      rules: {
+        enable_data_refreshing: true,
+        refreshing_interval: 2,
+      },
+    } as any;
+
+    const result = getDataRefreshConfig(component);
+
+    expect(result.refreshIntervalMs).toBe(
+      MINIMUM_REFRESHING_INTERVAL_IN_SECONDS * 1000
+    );
+  });
+
+  it("uses default interval when rules.refreshing_interval is undefined", () => {
+    const component = {
+      rules: {
+        enable_data_refreshing: true,
+      },
+    } as any;
+
+    const result = getDataRefreshConfig(component);
+
+    expect(result.refreshIntervalMs).toBe(
+      DEFAULT_REFRESHING_INTERVAL_IN_SECONDS * 1000
+    );
+  });
+
+  it("handles missing rules gracefully", () => {
+    const component = {} as any;
+
+    const result = getDataRefreshConfig(component);
+
+    expect(result).toEqual({
+      isRefreshingEnabled: false,
+      refreshIntervalMs: DEFAULT_REFRESHING_INTERVAL_IN_SECONDS * 1000,
+    });
+  });
+
+  it("handles null component gracefully", () => {
+    const result = getDataRefreshConfig(null as any);
+
+    expect(result).toEqual({
+      isRefreshingEnabled: false,
+      refreshIntervalMs: DEFAULT_REFRESHING_INTERVAL_IN_SECONDS * 1000,
+    });
+  });
+
+  it("handles string values for rules correctly", () => {
+    const component = {
+      rules: {
+        enable_data_refreshing: "true",
+        refreshing_interval: "25",
+      },
+    } as any;
+
+    const result = getDataRefreshConfig(component);
+
+    expect(result).toEqual({
+      isRefreshingEnabled: true,
+      refreshIntervalMs: 25 * 1000,
+    });
+  });
+});

package/refreshUtils/RefreshCoordinator/utils/index.ts

@@ -0,0 +1,29 @@
+import { isTrue } from "@applicaster/zapp-react-native-utils/booleanUtils";
+import { toNumberWithDefault } from "@applicaster/zapp-react-native-utils/numberUtils";
+
+export const MINIMUM_REFRESHING_INTERVAL_IN_SECONDS = 5; // 5 seconds
+
+export const DEFAULT_REFRESHING_INTERVAL_IN_SECONDS = 60; // 1 minute
+
+export type RefreshConfig = {
+  isRefreshingEnabled: boolean;
+  refreshIntervalMs: number;
+};
+
+export const getDataRefreshConfig = (
+  component: ZappUIComponent
+): RefreshConfig => {
+  const isRefreshingEnabled = isTrue(component?.rules?.enable_data_refreshing);
+
+  const refreshing_interval = toNumberWithDefault(
+    DEFAULT_REFRESHING_INTERVAL_IN_SECONDS,
+    component?.rules?.refreshing_interval
+  );
+
+  return {
+    isRefreshingEnabled,
+    refreshIntervalMs:
+      Math.max(refreshing_interval, MINIMUM_REFRESHING_INTERVAL_IN_SECONDS) *
+      1000,
+  };
+};

package/screenPickerUtils/index.ts

@@ -1,3 +1,5 @@
+import { endsWith } from "@applicaster/zapp-react-native-utils/utils";
+
 export const getFocusableId = (id) => `PickerItem.${id}`;
 
 export const getPickerSelectorId = (id) => `PickerSelector.${id}`;
@@ -11,3 +13,6 @@ export const getScreenPickerSelectorContainerId = (id) =>
 
 export const getScreenPickerContentContainerId = (id) =>
   `${getScreenPickerId(id)}-screen-container`;
+
+export const isTabsScreenContentContainerId = (id) =>
+  endsWith("-screen-container", id);

package/screenUtils/index.ts

@@ -0,0 +1,3 @@
+export const TV_SCREEN_HEIGHT = 1080;
+
+export const TV_SCREEN_WIDTH = 1920;

package/utils/__tests__/clone.test.ts

@@ -0,0 +1,158 @@
+import { clone } from "../clone";
+
+describe("clone", () => {
+  const originalStructuredClone = global.structuredClone;
+
+  afterEach(() => {
+    // Restore the original structuredClone after each test
+    global.structuredClone = originalStructuredClone;
+  });
+
+  describe("when structuredClone is available", () => {
+    beforeEach(() => {
+      // Mock structuredClone if it's not available
+      if (typeof global.structuredClone === "undefined") {
+        global.structuredClone = jest.fn((value) =>
+          JSON.parse(JSON.stringify(value))
+        );
+      }
+    });
+
+    test("clones primitive values", () => {
+      expect(clone(42)).toBe(42);
+      expect(clone("test")).toBe("test");
+      expect(clone(true)).toBe(true);
+      expect(clone(null)).toBe(null);
+    });
+
+    test("clones simple objects", () => {
+      const original = { a: 1, b: 2 };
+      const cloned = clone(original);
+
+      expect(cloned).toEqual(original);
+      expect(cloned).not.toBe(original);
+    });
+
+    test("clones nested objects", () => {
+      const original = { a: { b: { c: 1 } } };
+      const cloned = clone(original);
+
+      expect(cloned).toEqual(original);
+      expect(cloned).not.toBe(original);
+      expect(cloned.a).not.toBe(original.a);
+      expect(cloned.a.b).not.toBe(original.a.b);
+    });
+
+    test("clones arrays", () => {
+      const original = [1, 2, 3];
+      const cloned = clone(original);
+
+      expect(cloned).toEqual(original);
+      expect(cloned).not.toBe(original);
+    });
+
+    test("clones arrays with nested objects", () => {
+      const original = [{ a: 1 }, { b: 2 }];
+      const cloned = clone(original);
+
+      expect(cloned).toEqual(original);
+      expect(cloned).not.toBe(original);
+      expect(cloned[0]).not.toBe(original[0]);
+      expect(cloned[1]).not.toBe(original[1]);
+    });
+
+    test("does not mutate the original value", () => {
+      const original = { a: 1, b: { c: 2 } };
+      const cloned = clone(original);
+
+      cloned.a = 99;
+      cloned.b.c = 99;
+
+      expect(original.a).toBe(1);
+      expect(original.b.c).toBe(2);
+    });
+  });
+
+  describe("when structuredClone is not available (fallback to cloneDeep)", () => {
+    beforeEach(() => {
+      // Delete structuredClone to force fallback to cloneDeep
+      delete (global as any).structuredClone;
+    });
+
+    test("clones primitive values using cloneDeep", () => {
+      expect(clone(42)).toBe(42);
+      expect(clone("test")).toBe("test");
+      expect(clone(true)).toBe(true);
+      expect(clone(null)).toBe(null);
+    });
+
+    test("clones simple objects using cloneDeep", () => {
+      const original = { a: 1, b: 2 };
+      const cloned = clone(original);
+
+      expect(cloned).toEqual(original);
+      expect(cloned).not.toBe(original);
+    });
+
+    test("clones nested objects using cloneDeep", () => {
+      const original = { a: { b: { c: 1 } } };
+      const cloned = clone(original);
+
+      expect(cloned).toEqual(original);
+      expect(cloned).not.toBe(original);
+      expect(cloned.a).not.toBe(original.a);
+      expect(cloned.a.b).not.toBe(original.a.b);
+    });
+
+    test("clones arrays using cloneDeep", () => {
+      const original = [1, 2, 3];
+      const cloned = clone(original);
+
+      expect(cloned).toEqual(original);
+      expect(cloned).not.toBe(original);
+    });
+
+    test("clones arrays with nested objects using cloneDeep", () => {
+      const original = [{ a: 1 }, { b: 2 }];
+      const cloned = clone(original);
+
+      expect(cloned).toEqual(original);
+      expect(cloned).not.toBe(original);
+      expect(cloned[0]).not.toBe(original[0]);
+      expect(cloned[1]).not.toBe(original[1]);
+    });
+
+    test("does not mutate the original value when using cloneDeep", () => {
+      const original = { a: 1, b: { c: 2 } };
+      const cloned = clone(original);
+
+      cloned.a = 99;
+      cloned.b.c = 99;
+
+      expect(original.a).toBe(1);
+      expect(original.b.c).toBe(2);
+    });
+
+    test("handles complex objects with multiple levels", () => {
+      const original = {
+        name: "test",
+        data: {
+          items: [
+            { id: 1, value: "a" },
+            { id: 2, value: "b" },
+          ],
+          meta: { count: 2 },
+        },
+      };
+
+      const cloned = clone(original);
+
+      expect(cloned).toEqual(original);
+      expect(cloned).not.toBe(original);
+      expect(cloned.data).not.toBe(original.data);
+      expect(cloned.data.items).not.toBe(original.data.items);
+      expect(cloned.data.items[0]).not.toBe(original.data.items[0]);
+      expect(cloned.data.meta).not.toBe(original.data.meta);
+    });
+  });
+});

package/utils/__tests__/path.test.ts

@@ -31,3 +31,10 @@ test("example 4", () => {
 
   expect(path(route, xs)).toBeUndefined();
 });
+
+test("example 5", () => {
+  const route = ["a", "b", 0];
+  const xs = { a: { b: [1, 2, 3] } };
+
+  expect(path(route, xs)).toBe(1);
+});

package/utils/clone.ts

@@ -0,0 +1,7 @@
+import { cloneDeep } from "lodash";
+
+export const clone = (value) => {
+  return typeof structuredClone !== "undefined"
+    ? structuredClone(value) // no support for hermes, fallback to cloneDeep
+    : cloneDeep(value);
+};

package/utils/index.ts

@@ -20,8 +20,9 @@ export { mapAccum } from "./mapAccum";
 
 export { mergeRight } from "./mergeRight";
 
+export { clone } from "./clone";
+
 export {
-  cloneDeep as clone,
   flatten,
   drop,
   size,

package/reactHooks/feed/__tests__/useFeedRefresh.test.tsx

@@ -1,75 +0,0 @@
-import { renderHook } from "@testing-library/react-native";
-
-jest.useFakeTimers();
-
-jest.mock("@applicaster/zapp-react-native-utils/reactHooks/navigation", () => ({
-  useIsScreenActive: () => true,
-}));
-
-const { useFeedRefresh, feedRefreshLogger } = require("..");
-
-describe("useFeedRefresh", () => {
-  const reloadData = jest.fn();
-
-  const component = {
-    id: "foo",
-    rules: { enable_data_refreshing: true, refreshing_interval: 61 },
-  };
-
-  it("Calls reloadData after passed time lapses", () => {
-    renderHook(() => useFeedRefresh({ reloadData, component }));
-
-    expect(reloadData).not.toBeCalled();
-    jest.runOnlyPendingTimers();
-    expect(reloadData).toBeCalled();
-  });
-
-  it("Logs warning message if refresh time set below minimum value", () => {
-    const loggerSpy = jest.spyOn(feedRefreshLogger, "warning");
-
-    renderHook(() =>
-      useFeedRefresh({
-        reloadData,
-        component: {
-          ...component,
-          rules: { enable_data_refreshing: true, refreshing_interval: 2 },
-        },
-      })
-    );
-
-    expect(loggerSpy).toBeCalled();
-  });
-
-  it("Calls reloadData on a Component that had a timer setup and was re-mounted", () => {
-    reloadData.mockReset();
-
-    // it is not called before rendering hook"
-    expect(reloadData).not.toBeCalled();
-
-    // it is not called when rendering new component (Not previously rendered)
-    renderHook(() =>
-      useFeedRefresh({ reloadData, component: { ...component, id: "bar" } })
-    );
-
-    expect(reloadData).not.toBeCalled();
-
-    // it is called when rendering previously rendered component",
-    renderHook(() => useFeedRefresh({ reloadData, component }));
-    expect(reloadData).toBeCalled();
-  });
-
-  it("Doesn't refresh data when enable_data_refreshing if false", () => {
-    reloadData.mockReset();
-
-    renderHook(() =>
-      useFeedRefresh({
-        reloadData,
-        component: { ...component, rules: { enable_data_refreshing: false } },
-      })
-    );
-
-    jest.runOnlyPendingTimers();
-
-    expect(reloadData).not.toBeCalled();
-  });
-});