@applicaster/quick-brick-core 16.0.0-rc.113 → 16.0.0-rc.114

package/App/NavigationProvider/NavigationProvider.tsx

@@ -13,6 +13,8 @@ import {
   useGetScreenOrientation,
 } from "@applicaster/zapp-react-native-utils/appUtils/orientationHelper";
 import { focusManager } from "@applicaster/zapp-react-native-utils/focusManager/FocusManager";
+import { setXrayNavigator } from "@applicaster/zapp-react-native-utils/navigationUtils/xrayNavigator";
+import { registerNavToolbox } from "./navToolbox";
 
 import reducer, {
   ACTIONS,
@@ -760,11 +762,11 @@ export function NavigationProvider({ children }: Props) {
   const getStackForPathname = (
     pathname: string
   ): NavigationScreenState | undefined => {
-    const stack = [...state?.stack?.mainStack];
-
-    const currentStack = stack.find(({ route }) => route === pathname);
-
-    return currentStack;
+    // Topmost match: the active screen if a route is on the stack twice.
+    return R.findLast(
+      ({ route }) => route === pathname,
+      state?.stack?.mainStack ?? []
+    );
   };
 
   const navigator: QuickBrickAppNavigator = React.useMemo(
@@ -829,6 +831,13 @@ export function NavigationProvider({ children }: Props) {
     navigator.state = state;
   }
 
+  React.useLayoutEffect(() => {
+    setXrayNavigator(navigator);
+    registerNavToolbox();
+
+    return () => setXrayNavigator(undefined);
+  }, [navigator]);
+
   React.useLayoutEffect(() => {
     if (pathname === "/" && appLaunched) {
       goHome(true);

package/App/NavigationProvider/__tests__/navToolbox.test.ts

@@ -0,0 +1,227 @@
+const mockRegister = jest.fn().mockResolvedValue(undefined);
+
+// The X-Ray mock (__mocks__/@applicaster/quick-brick-xray) has no toolbox API: give it one.
+require("@applicaster/quick-brick-xray").registerReactToolbox = mockRegister;
+
+// Required after the toolbox API is in place: loading them can register the player toolbox.
+const {
+  modalStore,
+} = require("@applicaster/zapp-react-native-utils/modalState");
+
+const {
+  setXrayNavigator,
+} = require("@applicaster/zapp-react-native-utils/navigationUtils/xrayNavigator");
+
+const {
+  playerManager,
+} = require("@applicaster/zapp-react-native-utils/appUtils/playerManager");
+
+const { registerNavToolbox } = require("../navToolbox");
+
+const navigator = (overrides = {}) => {
+  const nav = {
+    getPathname: () => "/river/a/river/b",
+    getStack: () => [{ route: "/river/a" }, { route: "/river/a/river/b" }],
+    canGoBack: () => true,
+    goBack: jest.fn(),
+    goHome: jest.fn(),
+    getPlayNextOverlay: () => null,
+    getModalState: () => modalStore.getState().modalState,
+    dismissModal: jest.fn(),
+    videoModalState: { visible: false },
+    minimiseVideoModal: jest.fn(),
+    maximiseVideoModal: jest.fn(),
+    closeVideoModal: jest.fn(),
+    ...overrides,
+  };
+
+  setXrayNavigator(nav as unknown as QuickBrickAppNavigator);
+
+  return nav;
+};
+
+const videoModal = (mode: string) => ({
+  videoModalState: { visible: true, mode, item: { id: "v1", title: "V" } },
+});
+
+const call = (name: string) => {
+  // Other toolboxes (player) may register first.
+  const { tools } = mockRegister.mock.calls.find(
+    ([toolbox]) => toolbox.name === "nav"
+  )[0];
+
+  return tools.find((tool) => tool.name === name).handler({});
+};
+
+describe("navToolbox", () => {
+  beforeAll(() => registerNavToolbox());
+
+  afterEach(() => {
+    modalStore.getState().setModalState({ visible: false, screen: null });
+    jest.restoreAllMocks();
+  });
+
+  it("throws until the NavigationProvider sets the navigator", () => {
+    setXrayNavigator(undefined);
+
+    expect(() => call("stack")).toThrow("Navigation is not available yet");
+  });
+
+  it("goes back one screen", () => {
+    const nav = navigator();
+
+    expect(call("back")).toEqual({ from: "/river/a/river/b", wentBack: true });
+    expect(nav.goBack).toHaveBeenCalledWith(false);
+  });
+
+  it("does not go back from the root", () => {
+    const nav = navigator({ canGoBack: () => false });
+
+    expect(call("back")).toMatchObject({ wentBack: false });
+    expect(nav.goBack).not.toHaveBeenCalled();
+  });
+
+  it("does not pop the screen under a modal or the video modal", () => {
+    const nav = navigator(videoModal("MAXIMIZED"));
+
+    expect(call("back")).toEqual({
+      from: "video-modal/v1",
+      wentBack: false,
+      blockedBy: "video-modal",
+    });
+
+    modalStore.getState().openModal({ item: { id: "m" } });
+
+    expect(call("back")).toMatchObject({ blockedBy: "modal" });
+    expect(nav.goBack).not.toHaveBeenCalled();
+  });
+
+  it("only dismisses Play Next when it shows", () => {
+    const nav = navigator({ getPlayNextOverlay: () => ({}) });
+
+    expect(call("back")).toMatchObject({
+      wentBack: false,
+      dismissed: "playNext",
+    });
+
+    expect(nav.goBack).toHaveBeenCalledWith(false);
+  });
+
+  it("leaves a hook screen to cancel itself", () => {
+    const nav = navigator({ getPathname: () => "/river/a/hooks/login" });
+
+    expect(call("back")).toMatchObject({ wentBack: false, blockedBy: "hook" });
+    expect(nav.goBack).not.toHaveBeenCalled();
+  });
+
+  it("goes home", () => {
+    const nav = navigator();
+
+    expect(call("home")).toEqual({ from: "/river/a/river/b", wentHome: true });
+    expect(nav.goHome).toHaveBeenCalled();
+  });
+
+  it("does not go home under a modal or the video modal", () => {
+    const nav = navigator(videoModal("MAXIMIZED"));
+
+    expect(call("home")).toEqual({
+      from: "video-modal/v1",
+      wentHome: false,
+      blockedBy: "video-modal",
+    });
+
+    modalStore.getState().openModal({ item: { id: "m" } });
+
+    expect(call("home")).toMatchObject({ blockedBy: "modal" });
+    expect(nav.goHome).not.toHaveBeenCalled();
+  });
+
+  it("goes home with the mini player docked", () => {
+    const nav = navigator(videoModal("MINIMIZED"));
+
+    expect(call("home")).toMatchObject({ wentHome: true });
+    expect(nav.goHome).toHaveBeenCalled();
+  });
+
+  it("dismisses the modal store's modal, not the video modal", () => {
+    const nav = navigator(videoModal("MAXIMIZED"));
+
+    expect(() => call("dismissModal")).toThrow("No modal is open");
+
+    modalStore.getState().openModal({ item: { id: "m" } });
+
+    expect(call("dismissModal")).toBe("OK");
+    expect(nav.dismissModal).toHaveBeenCalled();
+  });
+
+  it("minimises only a maximised video modal", () => {
+    const fullscreen = navigator(videoModal("FULLSCREEN"));
+
+    expect(() => call("minimizeVideoModal")).toThrow("mode is FULLSCREEN");
+    expect(fullscreen.minimiseVideoModal).not.toHaveBeenCalled();
+
+    const maximized = navigator(videoModal("MAXIMIZED"));
+
+    call("minimizeVideoModal");
+
+    expect(maximized.minimiseVideoModal).toHaveBeenCalled();
+  });
+
+  it("enters and leaves fullscreen through the player, which also rotates the phone", () => {
+    const invoke = jest.spyOn(playerManager, "invokeHandler");
+    const playerContainer = jest.fn();
+
+    playerManager.on("toggleFullscreen", playerContainer);
+
+    navigator(videoModal("MAXIMIZED"));
+    call("fullscreenVideoModal");
+
+    expect(invoke).toHaveBeenCalledWith("toggleFullscreen", {
+      fullscreen: true,
+    });
+
+    const fullscreen = navigator(videoModal("FULLSCREEN"));
+
+    call("maximizeVideoModal");
+
+    expect(invoke).toHaveBeenCalledWith("toggleFullscreen", {
+      fullscreen: false,
+    });
+
+    expect(fullscreen.maximiseVideoModal).not.toHaveBeenCalled();
+
+    playerManager.removeHandler("toggleFullscreen", playerContainer);
+  });
+
+  it("does not claim fullscreen without a player, or from the mini player", () => {
+    navigator(videoModal("MAXIMIZED"));
+
+    expect(() => call("fullscreenVideoModal")).toThrow("shows no player");
+
+    navigator(videoModal("MINIMIZED"));
+
+    expect(() => call("fullscreenVideoModal")).toThrow("mode is MINIMIZED");
+  });
+
+  it("expands the mini player", () => {
+    const nav = navigator(videoModal("MINIMIZED"));
+
+    call("maximizeVideoModal");
+
+    expect(nav.maximiseVideoModal).toHaveBeenCalled();
+  });
+
+  it("reports the video modal", () => {
+    navigator(videoModal("MINIMIZED"));
+
+    expect(call("videoModal")).toMatchObject({
+      visible: true,
+      mode: "MINIMIZED",
+      entry: { id: "v1", title: "V" },
+    });
+
+    navigator();
+
+    expect(call("videoModal")).toMatchObject({ visible: false });
+  });
+});

package/App/NavigationProvider/navToolbox.ts

@@ -0,0 +1,224 @@
+import { Dimensions } from "react-native";
+import {
+  registerXrayToolbox,
+  XrayToolSpec,
+} from "@applicaster/zapp-react-native-utils/logger/xrayToolbox";
+import { getXrayNavigator } from "@applicaster/zapp-react-native-utils/navigationUtils/xrayNavigator";
+import { playerManager } from "@applicaster/zapp-react-native-utils/appUtils/playerManager";
+import { getTopPathname } from "@applicaster/zapp-react-native-ui-components/Decorators/ZappPipesDataConnector/screenToolbox";
+
+/**
+ * X-Ray `nav.*` toolbox: lets an agent navigate by intent and read or drive the video modal,
+ * which is navigation state. The swipes behind some of these (minimising the player, dragging a
+ * sheet) are react-native-gesture-handler recognisers that no public API can feed touches to, so
+ * the outcome is offered instead. Pairs with `screen.current` to check where an action landed.
+ *
+ * Registered by the NavigationProvider, which keeps the navigator in a plain module variable
+ * (xrayNavigator), so updating it never renders anything.
+ */
+
+const requireNavigator = (): QuickBrickAppNavigator => {
+  const navigator = getXrayNavigator();
+
+  if (!navigator) throw new Error("Navigation is not available yet");
+
+  return navigator;
+};
+
+/** The player's own fullscreen switch: it also rotates the phone, as the fullscreen button does. */
+const toggleFullscreen = (fullscreen: boolean) => {
+  // Only a mounted PlayerContainer handles it: not while the video modal runs its hooks or casts.
+  if (!playerManager.hasHandler("toggleFullscreen")) {
+    throw new Error(
+      "The video modal shows no player (hooks running or casting)"
+    );
+  }
+
+  playerManager.invokeHandler("toggleFullscreen", { fullscreen });
+
+  return "OK: the player switches on its next tick, check with videoModal";
+};
+
+const requireVideoModal = () => {
+  const nav = requireNavigator();
+
+  if (!nav.videoModalState?.visible) {
+    throw new Error("No video modal is open");
+  }
+
+  return nav;
+};
+
+const tools: XrayToolSpec[] = [
+  {
+    name: "stack",
+    description: "Routes on the navigation stack, root first.",
+    handler: () => ({
+      routes: requireNavigator()
+        .getStack()
+        .map(({ route }) => route),
+    }),
+  },
+  {
+    name: "back",
+    description:
+      "Go back one screen, as the nav bar back button does: it pops the stack and does not run " +
+      "hardware back listeners (Android back key), so a screen plugin's own back handling is skipped. " +
+      "Not while a modal, the video modal (unless docked) or a hook screen is on top: blockedBy says " +
+      "which; close it first, or cancel a hook with the device back key. With Play Next showing it " +
+      "only dismisses that. Check with screen.current.",
+    handler: () => {
+      const nav = requireNavigator();
+      const from = getTopPathname() ?? nav.getPathname();
+
+      // A presented layer (hooks-modal/, modal/, video-modal/) is on top: popping the stack would
+      // change the screen underneath it, which the user's back never does.
+      if (!from.startsWith("/")) {
+        return { from, wentBack: false, blockedBy: from.split("/")[0] };
+      }
+
+      if (nav.getPlayNextOverlay()) {
+        nav.goBack(false);
+
+        return { from, wentBack: false, dismissed: "playNext" };
+      }
+
+      // The hook screen answers the user's back itself (cancels its flow); a pop would skip that.
+      if (from.split("/").slice(-2)[0] === "hooks") {
+        return { from, wentBack: false, blockedBy: "hook" };
+      }
+
+      if (!nav.canGoBack()) return { from, wentBack: false };
+
+      nav.goBack(false);
+
+      return { from, wentBack: true };
+    },
+  },
+  {
+    name: "home",
+    description:
+      "Go to the home screen. Not while a modal, the video modal (unless docked) or the hooks modal is " +
+      "on top: blockedBy says which; close it first. On TV it does not move focus to the top menu as " +
+      "the remote's home does.",
+    handler: () => {
+      const nav = requireNavigator();
+      const from = getTopPathname() ?? nav.getPathname();
+
+      // goHome only replaces the stack: a presented layer would stay on top of the home screen,
+      // and it covers the menu the user would press home in.
+      if (!from.startsWith("/")) {
+        return { from, wentHome: false, blockedBy: from.split("/")[0] };
+      }
+
+      nav.goHome();
+
+      return { from, wentHome: true };
+    },
+  },
+  {
+    name: "dismissModal",
+    description:
+      "Close the open modal screen or bottom sheet, as dragging it down does. Not the video modal: use closeVideoModal.",
+    handler: () => {
+      const nav = requireNavigator();
+
+      if (!nav.getModalState()?.visible) throw new Error("No modal is open");
+
+      nav.dismissModal();
+
+      return "OK";
+    },
+  },
+  {
+    name: "videoModal",
+    description:
+      "The video modal: visible, mode (MAXIMIZED, MINIMIZED = mini player, FULLSCREEN, PIP), its entry, " +
+      "and the screen orientation.",
+    handler: () => {
+      const videoModal = requireNavigator().videoModalState;
+      const { width, height } = Dimensions.get("window");
+      const orientation = width > height ? "landscape" : "portrait";
+
+      if (!videoModal?.visible) return { visible: false, orientation };
+
+      return {
+        visible: true,
+        mode: videoModal.mode,
+        entry: videoModal.item
+          ? { id: videoModal.item.id, title: videoModal.item.title }
+          : null,
+        orientation,
+      };
+    },
+  },
+  {
+    name: "minimizeVideoModal",
+    description:
+      "Minimise the maximised video modal to the mini player, as swiping it down does.",
+    handler: () => {
+      const nav = requireVideoModal();
+      const { mode } = nav.videoModalState;
+
+      // The swipe exists only on the maximised modal; other modes have no way to the mini player.
+      if (mode !== "MAXIMIZED") {
+        throw new Error(
+          `Only a maximised video modal minimises (mode is ${mode})`
+        );
+      }
+
+      nav.minimiseVideoModal();
+
+      return "OK";
+    },
+  },
+  {
+    name: "maximizeVideoModal",
+    description: "Expand the mini player or leave fullscreen.",
+    handler: () => {
+      const nav = requireVideoModal();
+
+      if (nav.videoModalState.mode === "FULLSCREEN") {
+        return toggleFullscreen(false);
+      }
+
+      nav.maximiseVideoModal();
+
+      return "OK";
+    },
+  },
+  {
+    name: "fullscreenVideoModal",
+    description:
+      "Put the video modal in fullscreen, as the player's fullscreen button does.",
+    handler: () => {
+      const { mode } = requireVideoModal().videoModalState;
+
+      // The fullscreen button is on the maximised player, not on the mini player.
+      if (mode !== "MAXIMIZED") {
+        throw new Error(
+          `Only a maximised video modal goes fullscreen (mode is ${mode})`
+        );
+      }
+
+      return toggleFullscreen(true);
+    },
+  },
+  {
+    name: "closeVideoModal",
+    description: "Close the video modal and its player.",
+    handler: () => {
+      requireVideoModal().closeVideoModal();
+
+      return "OK";
+    },
+  },
+];
+
+export const registerNavToolbox = () =>
+  registerXrayToolbox({
+    name: "nav",
+    description:
+      "Navigate the app (stack, back, home, modals) and drive the video modal.",
+    tools,
+  });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@applicaster/quick-brick-core",
-  "version": "16.0.0-rc.113",
+  "version": "16.0.0-rc.114",
   "description": "Core package for Applicaster's Quick Brick App",
   "main": "index.js",
   "types": "index.d.ts",
@@ -28,13 +28,13 @@
   },
   "homepage": "https://github.com/applicaster/quickbrick#readme",
   "dependencies": {
-    "@applicaster/applicaster-types": "16.0.0-rc.113",
-    "@applicaster/quick-brick-core-plugins": "16.0.0-rc.113",
-    "@applicaster/zapp-pipes-v2-client": "16.0.0-rc.113",
-    "@applicaster/zapp-react-native-bridge": "16.0.0-rc.113",
-    "@applicaster/zapp-react-native-redux": "16.0.0-rc.113",
-    "@applicaster/zapp-react-native-ui-components": "16.0.0-rc.113",
-    "@applicaster/zapp-react-native-utils": "16.0.0-rc.113",
+    "@applicaster/applicaster-types": "16.0.0-rc.114",
+    "@applicaster/quick-brick-core-plugins": "16.0.0-rc.114",
+    "@applicaster/zapp-pipes-v2-client": "16.0.0-rc.114",
+    "@applicaster/zapp-react-native-bridge": "16.0.0-rc.114",
+    "@applicaster/zapp-react-native-redux": "16.0.0-rc.114",
+    "@applicaster/zapp-react-native-ui-components": "16.0.0-rc.114",
+    "@applicaster/zapp-react-native-utils": "16.0.0-rc.114",
     "atob": "^2.1.2",
     "axios": "^0.28.0",
     "btoa": "^1.2.1",