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

package/reactHooks/state/__tests__/useComponentScreenState.test.ts

@@ -0,0 +1,246 @@
+import { renderHook, act } from "@testing-library/react-native";
+import { useComponentScreenState } from "../useComponentScreenState";
+import { useScreenContextV2 } from "@applicaster/zapp-react-native-utils/reactHooks/screen/useScreenContext";
+
+import { create } from "zustand";
+
+const createMockStore = () => create(() => ({}));
+
+// Mock the external dependencies
+jest.mock(
+  "@applicaster/zapp-react-native-utils/reactHooks/screen/useScreenContext",
+  () => ({
+    useScreenContextV2: jest.fn(),
+  })
+);
+
+const mockUseScreenContextV2 = useScreenContextV2 as jest.MockedFunction<
+  typeof useScreenContextV2
+>;
+
+describe("useComponentScreenState", () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it("should return initial value when no state exists for componentId", () => {
+    const mockStore = createMockStore();
+
+    mockUseScreenContextV2.mockReturnValue({
+      _componentStateStore: mockStore,
+    } as any);
+
+    const initialValue = "default-value";
+    const componentId = "test-component";
+
+    const { result } = renderHook(() =>
+      useComponentScreenState(componentId, initialValue)
+    );
+
+    expect(result.current[0]).toBe(initialValue);
+  });
+
+  it("should return stored value when state exists for componentId", () => {
+    const mockStore = createMockStore();
+    mockStore.setState({ "existing-component": "stored-value" });
+
+    mockUseScreenContextV2.mockReturnValue({
+      _componentStateStore: mockStore,
+    } as any);
+
+    const { result } = renderHook(() =>
+      useComponentScreenState("existing-component", "default")
+    );
+
+    expect(result.current[0]).toBe("stored-value");
+  });
+
+  it("should update state when setter is called", () => {
+    const mockStore = createMockStore();
+
+    mockUseScreenContextV2.mockReturnValue({
+      _componentStateStore: mockStore,
+    } as any);
+
+    const { result } = renderHook(() =>
+      useComponentScreenState("update-test", "initial")
+    );
+
+    // Verify initial value
+    expect(result.current[0]).toBe("initial");
+
+    // Update the value
+    act(() => {
+      result.current[1]("updated-value");
+    });
+
+    // Verify updated value
+    expect(result.current[0]).toBe("updated-value");
+  });
+
+  it("should handle different data types correctly", () => {
+    const mockStore = createMockStore();
+
+    mockUseScreenContextV2.mockReturnValue({
+      _componentStateStore: mockStore,
+    } as any);
+
+    // Test with number
+    const { result: numberResult } = renderHook(() =>
+      useComponentScreenState<number>("number-test", 42)
+    );
+
+    expect(numberResult.current[0]).toBe(42);
+
+    // Test with boolean
+    const { result: boolResult } = renderHook(() =>
+      useComponentScreenState<boolean>("bool-test", true)
+    );
+
+    expect(boolResult.current[0]).toBe(true);
+
+    // Test with object
+    const testObj = { key: "value" };
+
+    const { result: objResult } = renderHook(() =>
+      useComponentScreenState<{ key: string }>("obj-test", testObj)
+    );
+
+    expect(objResult.current[0]).toEqual(testObj);
+  });
+
+  it("should maintain separate states for different componentIds", () => {
+    const mockStore = createMockStore();
+
+    mockUseScreenContextV2.mockReturnValue({
+      _componentStateStore: mockStore,
+    } as any);
+
+    const { result: firstResult } = renderHook(() =>
+      useComponentScreenState("first", "first-initial")
+    );
+
+    const { result: secondResult } = renderHook(() =>
+      useComponentScreenState("second", "second-initial")
+    );
+
+    // Verify initial values are separate
+    expect(firstResult.current[0]).toBe("first-initial");
+    expect(secondResult.current[0]).toBe("second-initial");
+
+    // Update first component's state
+    act(() => {
+      firstResult.current[1]("first-updated");
+    });
+
+    // Verify only first component's state changed
+    expect(firstResult.current[0]).toBe("first-updated");
+    expect(secondResult.current[0]).toBe("second-initial");
+  });
+
+  it("should return a memoized setter function", () => {
+    const mockStore = createMockStore();
+
+    mockUseScreenContextV2.mockReturnValue({
+      _componentStateStore: mockStore,
+    } as any);
+
+    const { result, rerender } = renderHook(
+      ({ id, initial }) => useComponentScreenState(id, initial),
+      {
+        initialProps: { id: "memo-test", initial: "initial" },
+      }
+    );
+
+    const firstSetter = result.current[1];
+
+    // Rerender with same props
+    rerender({ id: "memo-test", initial: "initial" });
+
+    const secondSetter = result.current[1];
+
+    // Setter should be the same instance due to useCallback
+    expect(firstSetter).toBe(secondSetter);
+  });
+
+  it("should update setter when componentId changes", () => {
+    const mockStore = createMockStore();
+
+    mockUseScreenContextV2.mockReturnValue({
+      _componentStateStore: mockStore,
+    } as any);
+
+    const { result, rerender } = renderHook(
+      ({ id, initial }) => useComponentScreenState(id, initial),
+      {
+        initialProps: { id: "old-id", initial: "initial" },
+      }
+    );
+
+    const firstSetter = result.current[1];
+
+    // Rerender with different componentId
+    rerender({ id: "new-id", initial: "initial" });
+
+    const secondSetter = result.current[1];
+
+    // Setter should be different because componentId changed
+    expect(firstSetter).not.toBe(secondSetter);
+  });
+
+  it("should call store.setState with correct parameters", () => {
+    const mockStore = createMockStore();
+    const setStateSpy = jest.spyOn(mockStore, "setState");
+
+    mockUseScreenContextV2.mockReturnValue({
+      _componentStateStore: mockStore,
+    } as any);
+
+    const { result } = renderHook(() =>
+      useComponentScreenState("state-test", "initial")
+    );
+
+    const newValue = "new-value";
+
+    act(() => {
+      result.current[1](newValue);
+    });
+
+    expect(setStateSpy).toHaveBeenCalledWith({
+      "state-test": newValue,
+    });
+  });
+
+  it("should handle falsy initial values correctly", () => {
+    const mockStore = createMockStore();
+
+    mockUseScreenContextV2.mockReturnValue({
+      _componentStateStore: mockStore,
+    } as any);
+
+    // Test with falsy values
+    const { result: nullResult } = renderHook(() =>
+      useComponentScreenState("null-test", null)
+    );
+
+    expect(nullResult.current[0]).toBeNull();
+
+    const { result: falseResult } = renderHook(() =>
+      useComponentScreenState("false-test", false)
+    );
+
+    expect(falseResult.current[0]).toBe(false);
+
+    const { result: zeroResult } = renderHook(() =>
+      useComponentScreenState("zero-test", 0)
+    );
+
+    expect(zeroResult.current[0]).toBe(0);
+
+    const { result: emptyStrResult } = renderHook(() =>
+      useComponentScreenState("empty-test", "")
+    );
+
+    expect(emptyStrResult.current[0]).toBe("");
+  });
+});

package/reactHooks/state/index.ts

@@ -3,3 +3,5 @@ export { useRivers } from "./useRivers";
 export { useHomeRiver, getHomeRiver } from "./useHomeRiver";
 
 export { ZStoreProvider, useZStore } from "./ZStoreProvider";
+
+export { useComponentScreenState } from "./useComponentScreenState";

package/reactHooks/state/useComponentScreenState.ts

@@ -0,0 +1,45 @@
+import * as React from "react";
+import { useScreenContextV2 } from "@applicaster/zapp-react-native-utils/reactHooks/screen/useScreenContext";
+import { useStore } from "zustand";
+
+/**
+ * A custom hook that provides persistent state storage across component re-mounts
+ * using the screen's component state store.
+ *
+ * @see {@link DOCS/adr/0010-useComponentScreenState.md} - ADR explaining why useComponentScreenState is used for List/Hero/Grid/Gallery components
+ *
+ * The state is shared across all components using the same componentId within the same screen context.
+ * If no value exists for the componentId, the initial value is returned as a fallback but is not persisted in the store.
+ * The initial value must be explicitly set using the returned setter function to persist it.
+ *
+ * @template T - The type of value being stored
+ * @param componentId - Unique identifier for this state in the component state store
+ * @param initialValue - The default value if no value exists for the componentId
+ * @returns A tuple containing the current value and a memoized setter function
+ *
+ * @example
+ * ```tsx
+ * const [count, setCount] = useComponentScreenState<number>('counter', 0);
+ * const [name, setName] = useComponentScreenState<string>('username', 'Anonymous');
+ * ```
+ */
+export const useComponentScreenState = <T = unknown>(
+  componentId: string,
+  initialValue: T
+): [T, (value: T) => void] => {
+  const store = useScreenContextV2()._componentStateStore;
+
+  const value = useStore(
+    store,
+    (state) => (state[componentId] as T | undefined) ?? initialValue
+  );
+
+  const setValue = React.useCallback(
+    (nextValue: T) => {
+      store.setState({ [componentId]: nextValue });
+    },
+    [componentId, store]
+  );
+
+  return [value, setValue] as const;
+};

package/refreshUtils/RefreshCoordinator/__tests__/refreshCoordinator.test.ts

@@ -0,0 +1,206 @@
+import { refreshCoordinator } from "..";
+import { getDataRefreshConfig } from "../utils";
+import { Subscription } from "rxjs";
+
+jest.mock("../utils", () => ({
+  getDataRefreshConfig: jest.fn(),
+}));
+
+describe("RefreshCoordinator", () => {
+  const component = { id: "c1" } as ZappUIComponent;
+  const screenId = "screen-1";
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    refreshCoordinator.clear();
+    jest.useFakeTimers();
+  });
+
+  afterEach(() => {
+    jest.runOnlyPendingTimers();
+    jest.useRealTimers();
+  });
+
+  // ----------------------------------------
+  // Singleton
+  // ----------------------------------------
+  it("returns the same instance via getInstance", () => {
+    const instance1 = refreshCoordinator;
+    const instance2 = (refreshCoordinator as any).constructor.getInstance();
+    expect(instance1).toBe(instance2);
+  });
+
+  // ----------------------------------------
+  // register & unregister
+  // ----------------------------------------
+  it("register starts a timer and returns an unregister function", () => {
+    (getDataRefreshConfig as jest.Mock).mockReturnValue({
+      refreshIntervalMs: 1000,
+      isRefreshingEnabled: true,
+    });
+
+    const unregister = refreshCoordinator.register(component, screenId);
+
+    expect(typeof unregister).toBe("function");
+    expect((refreshCoordinator as any).timers.size).toBe(1);
+
+    // Calling unregister should remove timer
+    unregister();
+    expect((refreshCoordinator as any).timers.size).toBe(0);
+  });
+
+  it("does not register if refreshing is disabled", () => {
+    (getDataRefreshConfig as jest.Mock).mockReturnValue({
+      refreshIntervalMs: 1000,
+      isRefreshingEnabled: false,
+    });
+
+    const unregister = refreshCoordinator.register(component, screenId);
+
+    expect(unregister).toBeInstanceOf(Function);
+    expect((refreshCoordinator as any).timers.size).toBe(0);
+  });
+
+  it("replaces existing timer if component is re-registered", () => {
+    (getDataRefreshConfig as jest.Mock).mockReturnValue({
+      refreshIntervalMs: 1000,
+      isRefreshingEnabled: true,
+    });
+
+    const unregister1 = refreshCoordinator.register(component, screenId);
+    const unregister2 = refreshCoordinator.register(component, screenId);
+
+    expect((refreshCoordinator as any).timers.size).toBe(1);
+    expect(unregister1).toBeInstanceOf(Function);
+    expect(unregister2).toBeInstanceOf(Function);
+  });
+
+  // ----------------------------------------
+  // subscribeTo
+  // ----------------------------------------
+  it("subscribeTo only triggers listener for matching component & screen", () => {
+    (getDataRefreshConfig as jest.Mock).mockReturnValue({
+      refreshIntervalMs: 1000,
+      isRefreshingEnabled: true,
+    });
+
+    const listener = jest.fn();
+    refreshCoordinator.register(component, screenId);
+    const sub = refreshCoordinator.subscribeTo(component, screenId, listener);
+
+    // Emit a refresh manually via private Subject
+    (refreshCoordinator as any).refresh$.next({ component, screenId });
+    expect(listener).toHaveBeenCalledTimes(1);
+
+    // Non-matching component should not call listener
+    (refreshCoordinator as any).refresh$.next({
+      component: { id: "other" } as ZappUIComponent,
+      screenId,
+    });
+
+    expect(listener).toHaveBeenCalledTimes(1);
+
+    sub.unsubscribe();
+  });
+
+  // ----------------------------------------
+  // subscribeToAny
+  // ----------------------------------------
+  it("subscribeToAny triggers listener with throttling and replaces previous listener", () => {
+    const listener1 = jest.fn();
+    const listener2 = jest.fn();
+
+    // First subscription
+    const sub1: Subscription = refreshCoordinator.subscribeToAny(listener1);
+    expect(sub1).toBeInstanceOf(Subscription);
+
+    // Second subscription replaces first
+    const sub2: Subscription = refreshCoordinator.subscribeToAny(listener2);
+    expect(sub2).toBeInstanceOf(Subscription);
+
+    // Emit multiple events quickly
+    (refreshCoordinator as any).refresh$.next({ component, screenId });
+    (refreshCoordinator as any).refresh$.next({ component, screenId });
+
+    // Because of throttleTime(500ms), fast events are ignored
+    jest.advanceTimersByTime(500);
+    expect(listener1).not.toHaveBeenCalled();
+    expect(listener2).toHaveBeenCalledTimes(1);
+
+    sub2.unsubscribe();
+  });
+
+  // ----------------------------------------
+  // triggerRefresh
+  // ----------------------------------------
+  it("triggerRefresh emits refresh events for each component", () => {
+    const component1 = { id: "c1" } as ZappUIComponent;
+    const component2 = { id: "c2" } as ZappUIComponent;
+    const listener = jest.fn();
+
+    // Subscribe to all events
+    (refreshCoordinator as any).refresh$.subscribe(listener);
+
+    refreshCoordinator.triggerRefresh([component1, component2], screenId);
+
+    expect(listener).toHaveBeenCalledTimes(2);
+
+    expect(listener).toHaveBeenCalledWith({
+      component: component1,
+      screenId,
+    });
+
+    expect(listener).toHaveBeenCalledWith({
+      component: component2,
+      screenId,
+    });
+  });
+
+  it("triggerRefresh with empty components does nothing", () => {
+    const listener = jest.fn();
+
+    (refreshCoordinator as any).refresh$.subscribe(listener);
+
+    refreshCoordinator.triggerRefresh([], screenId);
+
+    expect(listener).not.toHaveBeenCalled();
+  });
+
+  it("triggerRefresh events are picked up by subscribeTo", () => {
+    const listener = jest.fn();
+
+    refreshCoordinator.subscribeTo(component, screenId, listener);
+    refreshCoordinator.triggerRefresh([component], screenId);
+
+    expect(listener).toHaveBeenCalledTimes(1);
+  });
+
+  // ----------------------------------------
+  // clear
+  // ----------------------------------------
+  it("clear stops all timers, anyListener, and recreates subject", () => {
+    (getDataRefreshConfig as jest.Mock).mockReturnValue({
+      refreshIntervalMs: 1000,
+      isRefreshingEnabled: true,
+    });
+
+    const listener = jest.fn();
+    refreshCoordinator.register(component, screenId);
+    refreshCoordinator.subscribeToAny(listener);
+
+    expect((refreshCoordinator as any).timers.size).toBe(1);
+    expect((refreshCoordinator as any).anyListenerSubscription).toBeDefined();
+
+    refreshCoordinator.clear();
+
+    expect((refreshCoordinator as any).timers.size).toBe(0);
+    expect((refreshCoordinator as any).anyListenerSubscription).toBeUndefined();
+
+    // New events on new Subject still work
+    const newListener = jest.fn();
+    refreshCoordinator.subscribeToAny(newListener);
+    (refreshCoordinator as any).refresh$.next({ component, screenId });
+    jest.advanceTimersByTime(500);
+    expect(newListener).toHaveBeenCalled();
+  });
+});