@applicaster/zapp-react-native-utils 15.0.0-alpha.3634430569 → 15.0.0-alpha.3735433464

package/actionUtils/index.ts

@@ -0,0 +1,7 @@
+import { Image } from "react-native";
+import { isTV } from "../reactUtils";
+
+export const resolveDefaultAssetUri = (source: string | number): string =>
+  isTV()
+    ? (source as string)
+    : Image.resolveAssetSource(source as number)?.uri || "";

package/appUtils/focusManagerAux/utils/index.ts

@@ -142,6 +142,10 @@ export const isTabsScreenOnContentFocused = (node) => {
 };
 
 export const isCurrentFocusOnMenu = (node) => {
+  if (isNil(node)) {
+    return false;
+  }
+
   if (isRoot(node)) {
     return false;
   }
@@ -154,10 +158,14 @@ export const isCurrentFocusOnMenu = (node) => {
     return false;
   }
 
-  return isCurrentFocusOnMenu(node.parent);
+  return isCurrentFocusOnMenu(node?.parent);
 };
 
 export const isCurrentFocusOnContent = (node) => {
+  if (isNil(node)) {
+    return false;
+  }
+
   if (isRoot(node)) {
     return false;
   }
@@ -170,7 +178,7 @@ export const isCurrentFocusOnContent = (node) => {
     return true;
   }
 
-  return isCurrentFocusOnContent(node.parent);
+  return isCurrentFocusOnContent(node?.parent);
 };
 
 export const isCurrentFocusOn = (id, node) => {

package/cellUtils/__tests__/cellUtils.test.ts

@@ -3,6 +3,7 @@ import {
   ifEmptyUseFallback,
   textTransform,
   getKeyForLabel,
+  getDataTransformForLabel,
   getLabel,
   getAspectRatio,
   getCellWidth,
@@ -56,6 +57,44 @@ describe("getKeyForLabel", () => {
   });
 });
 
+describe("getDataTransformForLabel", () => {
+  it("returns dataKey when dataKey is not other", () => {
+    expect(getDataTransformForLabel(VAL.dataKey, VAL.customKey)).toEqual(
+      VAL.dataKey
+    );
+  });
+
+  it("returns customKey when dataKey is other", () => {
+    expect(getDataTransformForLabel(VAL.other, VAL.customKey)).toEqual(
+      VAL.customKey
+    );
+  });
+
+  it("preserves full date formats containing dots", () => {
+    expect(getDataTransformForLabel(VAL.other, "DD.MM.YYYY")).toEqual(
+      "DD.MM.YYYY"
+    );
+  });
+
+  it("returns default date format when selected key is null or undefined", () => {
+    expect(getDataTransformForLabel(EMPTY.nulls, VAL.customKey)).toEqual(
+      "DD/MM/YYYY"
+    );
+
+    expect(getDataTransformForLabel(EMPTY.undef, VAL.customKey)).toEqual(
+      "DD/MM/YYYY"
+    );
+
+    expect(getDataTransformForLabel(VAL.other, EMPTY.nulls)).toEqual(
+      "DD/MM/YYYY"
+    );
+
+    expect(getDataTransformForLabel(VAL.other, EMPTY.undef)).toEqual(
+      "DD/MM/YYYY"
+    );
+  });
+});
+
 describe("getLabel", () => {
   it("returns a string from dataKey's path", () => {
     expect(getLabel(VAL.dataKey, VAL.customKey)(entry)).toEqual(entry.id);

package/cellUtils/index.ts

@@ -1,5 +1,5 @@
 import * as R from "ramda";
-import dayjs from "dayjs";
+import { dayjs } from "../dateUtils";
 import validateColor from "validate-color";
 
 import { transformColorCode as fixColorHexCode } from "@applicaster/zapp-react-native-utils/transform";
@@ -31,6 +31,16 @@ export const getKeyForLabel = (dataKey, customKey) => {
   return keyToUse.split(".");
 };
 
+/**
+ * Provides `format` for date formatting. Returns customKey if dataKey is "other", otherwise it returns dataKey.
+ * Should consist of valid dayjs tokens - https://day.js.org/docs/en/parse/string-format#list-of-all-available-parsing-tokens
+ */
+export const getDataTransformForLabel = (dataKey, customKey) => {
+  const keyToUse = dataKey === CUSTOM_KEY ? customKey : dataKey;
+
+  return keyToUse ?? "DD/MM/YYYY";
+};
+
 /**
  * This method will return true if the argument passed to it is either empty or nil
  * The method prevents zero from being evaluated as falsey in an || condition

package/componentsUtils/index.ts

@@ -1,3 +1,5 @@
+import { last } from "@applicaster/zapp-react-native-utils/utils";
+
 const GROUP = "group-qb";
 const GROUP_INFO = "group-info-qb";
 const GROUP_INFO_OLD = "group-info";
@@ -29,6 +31,12 @@ export const isFirstComponentGallery = (
   return isGallery(components?.[0]);
 };
 
+export const isLastComponentGallery = (
+  components: ZappUIComponent[]
+): boolean => {
+  return isGallery(last(components));
+};
+
 export const isGroup = (item): boolean => item?.component_type === GROUP;
 
 export const isEmptyGroup = (item): boolean =>

package/dateUtils/__tests__/dayjs.test.ts

@@ -1,7 +1,4 @@
 import { dayjs } from "../index";
-import customParseFormat from "dayjs/plugin/customParseFormat";
-
-dayjs.extend(customParseFormat);
 
 describe("dayjs", () => {
   describe("basic functionality", () => {

package/dateUtils/index.ts

@@ -4,12 +4,14 @@ import timezone from "dayjs/plugin/timezone";
 import isoWeek from "dayjs/plugin/isoWeek";
 import duration from "dayjs/plugin/duration";
 import relativeTime from "dayjs/plugin/relativeTime";
+import customParseFormat from "dayjs/plugin/customParseFormat";
 
 // Extend dayjs with plugins
 dayjs.extend(utc);
 dayjs.extend(timezone);
 dayjs.extend(isoWeek);
 dayjs.extend(duration);
+dayjs.extend(customParseFormat);
 
 dayjs.extend(relativeTime, {
   thresholds: [

package/manifestUtils/keys.js

@@ -541,8 +541,8 @@ const MOBILE_ACTION_BUTTON_FIELDS = [
   },
   {
     type: ZAPPIFEST_FIELDS.select,
-    suffix: "action asset flavor",
-    options: ["flavor_1", "flavor_2"],
+    suffix: "action asset flavour",
+    options: ["flavour_1", "flavour_2"],
   },
   {
     type: ZAPPIFEST_FIELDS.select,

package/manifestUtils/mobileAction/button/__tests__/mobileActionButton.test.js

@@ -18,7 +18,7 @@ describe("mobileActionButton", () => {
     paddingBottom: 14,
     paddingLeft: 16,
     assetEnabled: true,
-    actionAssetFlavor: "flavor_1",
+    actionAssetFlavour: "flavour_1",
     assetAlignment: "left",
     assetHeight: 24,
     assetWidth: 24,
@@ -99,13 +99,13 @@ describe("mobileActionButton", () => {
       },
     ]);
 
-    const actionAssetFlavorField = result.fields.find(
-      (field) => field.key === "mobile_button_2_action_asset_flavor"
+    const actionAssetFlavourField = result.fields.find(
+      (field) => field.key === "mobile_button_2_action_asset_flavour"
     );
 
-    expect(actionAssetFlavorField.rules).toBe("all_conditions");
+    expect(actionAssetFlavourField.rules).toBe("all_conditions");
 
-    expect(actionAssetFlavorField.conditional_fields).toEqual([
+    expect(actionAssetFlavourField.conditional_fields).toEqual([
       {
         key: "styles/mobile_button_2_button_enabled",
         condition_value: true,

package/manifestUtils/mobileAction/button/index.js

@@ -94,7 +94,7 @@ function mobileActionButton({ label, description, defaults, isFirstButton }) {
     if (
       isKeyHasAnyOfSuffixes(
         [
-          "action_asset_flavor",
+          "action_asset_flavour",
           "asset_alignment",
           "asset_height",
           "asset_width",

package/manifestUtils/mobileAction/groups/defaults.js

@@ -1,5 +1,6 @@
 const DEFAULT_MOBILE_ACTION_BUTTONS_CONTAINER_DEFAULTS = {
   buttonsEnabled: false,
+
   align: "left",
   overImagePosition: "bottom_left",
   marginTop: 0,
@@ -27,7 +28,7 @@ const DEFAULT_MOBILE_ACTION_BUTTON_SHARED_DEFAULTS = {
   paddingBottom: 14,
   paddingLeft: 16,
   assetEnabled: true,
-  actionAssetFlavor: "flavor_1",
+  actionAssetFlavour: "flavour_1",
   assetAlignment: "left",
   assetHeight: 24,
   assetWidth: 24,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@applicaster/zapp-react-native-utils",
-  "version": "15.0.0-alpha.3634430569",
+  "version": "15.0.0-alpha.3735433464",
   "description": "Applicaster Zapp React Native utilities package",
   "main": "index.js",
   "types": "index.d.ts",
@@ -27,7 +27,7 @@
   },
   "homepage": "https://github.com/applicaster/quickbrick#readme",
   "dependencies": {
-    "@applicaster/applicaster-types": "15.0.0-alpha.3634430569",
+    "@applicaster/applicaster-types": "15.0.0-alpha.3735433464",
     "buffer": "^5.2.1",
     "camelize": "^1.0.0",
     "dayjs": "^1.11.10",

package/pluginUtils/index.ts

@@ -30,10 +30,7 @@ export function getComponentModule({
   components: ComponentsMap;
   plugins: Plugin[] | QuickBrickPlugin[];
 }) {
-  const component = R.compose(
-    R.prop(R.__, components),
-    toPascalCase
-  )(componentType);
+  const component = components[toPascalCase(componentType)];
 
   if (component) {
     return component;
@@ -60,7 +57,9 @@ export function findComponentByType({
     ? R.compose(...R.reverse(decorators))
     : decorators;
 
-  const component = getComponentModule({ componentType, components, plugins });
+  const module = getComponentModule({ componentType, components, plugins });
+
+  const component = module?.Component || module;
 
   return R.unless(R.isNil, applyDecorators)(component);
 }

package/reactHooks/casting/index.ts

@@ -0,0 +1 @@
+export { useIsCasting } from "./useIsCasting";

package/reactHooks/casting/useIsCasting.tsx

@@ -0,0 +1,57 @@
+import React from "react";
+import { useActions } from "@applicaster/zapp-react-native-utils/reactHooks/actions";
+import { useAppState } from "@applicaster/zapp-react-native-utils/reactHooks/app";
+import { isApplePlatform } from "@applicaster/zapp-react-native-utils/reactUtils";
+
+const CHROMECAST_IDENTIFIER = "quick-brick-chromecast-action";
+
+const fakeEntry: any = {
+  title: "Chromecast use is casting fake entry",
+  id: "quick-brick-use-is-casting-fake-entry",
+};
+
+/**
+ * Returns the cast action state connection status, does not update when app is in background on Apple platforms
+ * On other platforms, it continues to check the cast action state even when the app is in background
+ */
+export const useIsCasting = () => {
+  const actionContext = useActions(CHROMECAST_IDENTIFIER);
+  const appState = useAppState();
+  const isAppInForeground = appState === "active";
+  const shouldOnlyUpdateInForeground = isApplePlatform();
+
+  const [castActionState, setCastActionState] = React.useState(
+    !actionContext ? null : actionContext.initialEntryState(fakeEntry)
+  );
+
+  React.useEffect(() => {
+    if (!shouldOnlyUpdateInForeground || isAppInForeground) {
+      if (actionContext && castActionState === null) {
+        setCastActionState(actionContext.initialEntryState(fakeEntry));
+      }
+    }
+  }, [
+    actionContext,
+    setCastActionState,
+    isAppInForeground,
+    shouldOnlyUpdateInForeground,
+  ]);
+
+  React.useEffect(() => {
+    if (typeof actionContext?.addListener === "function") {
+      return actionContext?.addListener(String(fakeEntry.id), (state) => {
+        // Only check foreground state on Apple platforms
+        if (!shouldOnlyUpdateInForeground || isAppInForeground) {
+          setCastActionState(state);
+        }
+      });
+    }
+  }, [
+    setCastActionState,
+    actionContext,
+    isAppInForeground,
+    shouldOnlyUpdateInForeground,
+  ]);
+
+  return !!castActionState?.connected;
+};

package/reactHooks/resolvers/useComponentResolver.ts

@@ -5,9 +5,9 @@ import { coreLogger } from "@applicaster/zapp-react-native-utils/logger";
 
 import { findComponentByType } from "@applicaster/zapp-react-native-utils/pluginUtils";
 import {
-  usePlugins,
-  useAppSelector,
   selectComponents,
+  useAppSelector,
+  usePlugins,
 } from "@applicaster/zapp-react-native-redux";
 
 type Decorator = (component: React.Component<any>) => React.Component<any>;

package/reactHooks/screen/__tests__/useCurrentScreenIsHook.test.ts

@@ -0,0 +1,103 @@
+import { renderHook } from "@testing-library/react-native";
+import { useCurrentScreenIsHook } from "../useCurrentScreenIsHook";
+
+import { useNavigation } from "@applicaster/zapp-react-native-utils/reactHooks";
+import { last } from "@applicaster/zapp-react-native-utils/utils";
+import { toBooleanWithDefaultFalse } from "@applicaster/zapp-react-native-utils/booleanUtils";
+
+jest.mock("@applicaster/zapp-react-native-utils/reactHooks");
+jest.mock("@applicaster/zapp-react-native-utils/utils");
+jest.mock("@applicaster/zapp-react-native-utils/booleanUtils");
+
+const mockUseNavigation = useNavigation as jest.Mock;
+const mockLast = last as jest.Mock;
+const mockToBoolean = toBooleanWithDefaultFalse as jest.Mock;
+
+describe("useCurrentScreenIsHook", () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+
+    // sensible defaults
+    mockUseNavigation.mockReturnValue({ mainStack: [] });
+    mockLast.mockReturnValue(undefined);
+    mockToBoolean.mockReturnValue(false);
+  });
+
+  it("returns true when last route includes 'hook'", () => {
+    const stack = [{ route: "some-hook-screen" }];
+
+    mockUseNavigation.mockReturnValue({ mainStack: stack });
+    mockLast.mockReturnValue(stack[0]);
+    mockToBoolean.mockReturnValue(true);
+
+    const { result } = renderHook(() => useCurrentScreenIsHook());
+
+    expect(mockLast).toHaveBeenCalledWith(stack);
+    expect(mockToBoolean).toHaveBeenCalledWith(true);
+    expect(result.current).toBe(true);
+  });
+
+  it("returns false when last route does not include 'hook'", () => {
+    const stack = [{ route: "home-screen" }];
+
+    mockUseNavigation.mockReturnValue({ mainStack: stack });
+    mockLast.mockReturnValue(stack[0]);
+    mockToBoolean.mockReturnValue(false);
+
+    const { result } = renderHook(() => useCurrentScreenIsHook());
+
+    expect(mockToBoolean).toHaveBeenCalledWith(false);
+    expect(result.current).toBe(false);
+  });
+
+  it("returns false when route is undefined", () => {
+    const stack = [{}];
+
+    mockUseNavigation.mockReturnValue({ mainStack: stack });
+    mockLast.mockReturnValue(stack[0]);
+    mockToBoolean.mockReturnValue(false);
+
+    const { result } = renderHook(() => useCurrentScreenIsHook());
+
+    expect(mockToBoolean).toHaveBeenCalledWith(undefined);
+    expect(result.current).toBe(false);
+  });
+
+  it("returns false when last(mainStack) is undefined (empty stack)", () => {
+    mockUseNavigation.mockReturnValue({ mainStack: [] });
+    mockLast.mockReturnValue(undefined);
+    mockToBoolean.mockReturnValue(false);
+
+    const { result } = renderHook(() => useCurrentScreenIsHook());
+
+    expect(mockLast).toHaveBeenCalledWith([]);
+    expect(mockToBoolean).toHaveBeenCalledWith(undefined);
+    expect(result.current).toBe(false);
+  });
+
+  it("uses default empty array when mainStack is undefined", () => {
+    mockUseNavigation.mockReturnValue({});
+    mockLast.mockReturnValue(undefined);
+    mockToBoolean.mockReturnValue(false);
+
+    const { result } = renderHook(() => useCurrentScreenIsHook());
+
+    expect(mockLast).toHaveBeenCalledWith([]);
+    expect(result.current).toBe(false);
+  });
+
+  it("passes correct boolean result from includes('hook')", () => {
+    const stack = [{ route: "hook" }];
+
+    mockUseNavigation.mockReturnValue({ mainStack: stack });
+    mockLast.mockReturnValue(stack[0]);
+
+    // simulate actual includes result flowing through
+    mockToBoolean.mockImplementation((val) => Boolean(val));
+
+    const { result } = renderHook(() => useCurrentScreenIsHook());
+
+    expect(mockToBoolean).toHaveBeenCalledWith(true);
+    expect(result.current).toBe(true);
+  });
+});

package/reactHooks/screen/__tests__/useCurrentScreenIsStartupHook.test.ts

@@ -0,0 +1,94 @@
+import { renderHook } from "@testing-library/react-native";
+import { useCurrentScreenIsStartupHook } from "../useCurrentScreenIsStartupHook";
+
+import { useNavigation } from "@applicaster/zapp-react-native-utils/reactHooks";
+import { isFilledArray } from "@applicaster/zapp-react-native-utils/arrayUtils";
+
+jest.mock("@applicaster/zapp-react-native-utils/reactHooks");
+jest.mock("@applicaster/zapp-react-native-utils/arrayUtils");
+
+const mockUseNavigation = useNavigation as jest.Mock;
+const mockIsFilledArray = isFilledArray as jest.Mock;
+
+describe("useCurrentScreenIsStartupHook", () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it("returns true when startUpHooks is a filled array", () => {
+    mockUseNavigation.mockReturnValue({
+      startUpHooks: ["hook1"],
+    });
+
+    mockIsFilledArray.mockReturnValue(true);
+
+    const { result } = renderHook(() => useCurrentScreenIsStartupHook());
+
+    expect(result.current).toBe(true);
+    expect(mockIsFilledArray).toHaveBeenCalledWith(["hook1"]);
+  });
+
+  it('returns true when startUpHooks is "in_process"', () => {
+    mockUseNavigation.mockReturnValue({
+      startUpHooks: "in_process",
+    });
+
+    mockIsFilledArray.mockReturnValue(false);
+
+    const { result } = renderHook(() => useCurrentScreenIsStartupHook());
+
+    expect(result.current).toBe(true);
+    expect(mockIsFilledArray).toHaveBeenCalledWith("in_process");
+  });
+
+  it("returns false when startUpHooks is empty array", () => {
+    mockUseNavigation.mockReturnValue({
+      startUpHooks: [],
+    });
+
+    mockIsFilledArray.mockReturnValue(false);
+
+    const { result } = renderHook(() => useCurrentScreenIsStartupHook());
+
+    expect(result.current).toBe(false);
+    expect(mockIsFilledArray).toHaveBeenCalledWith([]);
+  });
+
+  it("returns false when startUpHooks is undefined", () => {
+    mockUseNavigation.mockReturnValue({
+      startUpHooks: undefined,
+    });
+
+    mockIsFilledArray.mockReturnValue(false);
+
+    const { result } = renderHook(() => useCurrentScreenIsStartupHook());
+
+    expect(result.current).toBe(false);
+    expect(mockIsFilledArray).toHaveBeenCalledWith(undefined);
+  });
+
+  it("returns false when startUpHooks is null", () => {
+    mockUseNavigation.mockReturnValue({
+      startUpHooks: null,
+    });
+
+    mockIsFilledArray.mockReturnValue(false);
+
+    const { result } = renderHook(() => useCurrentScreenIsStartupHook());
+
+    expect(result.current).toBe(false);
+    expect(mockIsFilledArray).toHaveBeenCalledWith(null);
+  });
+
+  it("prioritizes filled array over string comparison", () => {
+    mockUseNavigation.mockReturnValue({
+      startUpHooks: ["hook1"],
+    });
+
+    mockIsFilledArray.mockReturnValue(true);
+
+    const { result } = renderHook(() => useCurrentScreenIsStartupHook());
+
+    expect(result.current).toBe(true);
+  });
+});

package/reactHooks/screen/index.ts

@@ -12,3 +12,7 @@ export {
 } from "./useScreenContext";
 
 export { useScreenBackgroundColor } from "./useScreenBackgroundColor";
+
+export { useCurrentScreenIsHook } from "./useCurrentScreenIsHook";
+
+export { useCurrentScreenIsStartupHook } from "./useCurrentScreenIsStartupHook";

package/reactHooks/screen/useCurrentScreenIsHook.ts

@@ -0,0 +1,9 @@
+import { useNavigation } from "@applicaster/zapp-react-native-utils/reactHooks";
+import { last } from "@applicaster/zapp-react-native-utils/utils";
+import { toBooleanWithDefaultFalse } from "@applicaster/zapp-react-native-utils/booleanUtils";
+
+export const useCurrentScreenIsHook = (): boolean => {
+  const { mainStack = [] } = useNavigation();
+
+  return toBooleanWithDefaultFalse(last(mainStack)?.route?.includes("hook"));
+};

package/reactHooks/screen/useCurrentScreenIsStartupHook.ts

@@ -0,0 +1,8 @@
+import { useNavigation } from "@applicaster/zapp-react-native-utils/reactHooks";
+import { isFilledArray } from "@applicaster/zapp-react-native-utils/arrayUtils";
+
+export const useCurrentScreenIsStartupHook = (): boolean => {
+  const { startUpHooks } = useNavigation();
+
+  return isFilledArray(startUpHooks) || startUpHooks === "in_process";
+};

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

@@ -130,6 +130,51 @@ describe("RefreshCoordinator", () => {
     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
   // ----------------------------------------

package/refreshUtils/RefreshCoordinator/index.ts

@@ -16,12 +16,26 @@ type ComponentToRefresh = {
 /**
  * Public contract for refresh coordination.
  *
- * register() → starts refresh timer for a component with screen context
- * subscribeTo() → listen to refresh events for a specific component and screen
- * subscribeToAny() → listen to all refresh events with throttling
+ * 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,
@@ -37,8 +51,10 @@ interface IRefreshCoordinator {
  *
  * Design goals:
  * - One shared coordinator across the app
- * - Multiple components can register refresh timers with screen context
- * - Multiple listeners can subscribe to refresh events
+ * - 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 {
@@ -114,6 +130,19 @@ class RefreshCoordinator implements IRefreshCoordinator {
     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.