@rn-tools/navigation 2.2.6 → 3.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rn-tools/navigation",
-  "version": "2.2.6",
+  "version": "3.0.1",
   "main": "./src/index.ts",
   "license": "MIT",
   "files": [
@@ -8,13 +8,12 @@
   ],
   "scripts": {
     "build": "tsc",
-    "test": "jest .",
+    "test": "NODE_OPTIONS='--no-experimental-detect-module' vitest",
     "lint": "eslint -c ./.eslintrc.js ."
   },
   "devDependencies": {
     "@rn-tools/eslint-config": "*",
-    "@testing-library/react-native": "^12.5.1",
-    "@types/jest": "^27.0.3",
+    "@testing-library/react": "^14.2.1",
     "@types/react": "~18.2.79",
     "@types/react-native": "^0.72.8",
     "@types/react-test-renderer": "^18",
@@ -22,28 +21,20 @@
     "@typescript-eslint/parser": "^6.8.0",
     "babel-preset-expo": "~11.0.0",
     "eslint": "^8.56.0",
-    "expo": "^51.0.8",
-    "jest": "^29.7.0",
-    "jest-expo": "^51.0.2",
+    "expo": "~52.0.0",
     "lint-staged": "^15.2.0",
     "prettier": "^3.2.1",
     "react-test-renderer": "18.2.0",
-    "typescript": "~5.3.3"
+    "typescript": "~5.3.3",
+    "vitest": "^1.6.0"
   },
   "peerDependencies": {
     "react": "*",
     "react-native": "*",
-    "react-native-safe-area-context": "*",
     "react-native-screens": "*"
   },
   "dependencies": {
     "path-to-regexp": "^6.2.2",
     "zustand": "^4.5.2"
-  },
-  "jest": {
-    "preset": "jest-expo",
-    "transformIgnorePatterns": [
-      "node_modules/(?!((jest-)?react-native|@react-native(-community)?)|expo(nent)?|@expo(nent)?/.*|@expo-google-fonts/.*|react-navigation|@react-navigation/.*|@unimodules/.*|unimodules|sentry-expo|native-base|react-native-svg)"
-    ]
   }
 }

package/readme.md

@@ -0,0 +1,68 @@
+# @rn-tools/navigation
+
+Navigation primitives for React Native. Built on `react-native-screens`.
+
+## Installation
+
+```bash
+yarn expo install @rn-tools/navigation react-native-screens
+```
+
+## Quick Start
+
+```tsx
+import {
+  createNavigation,
+  Navigation,
+  Stack,
+  Tabs,
+  type TabScreenOptions,
+} from "@rn-tools/navigation";
+
+const navigation = createNavigation();
+
+const tabScreens: TabScreenOptions[] = [
+  {
+    id: "home",
+    screen: <Stack id="home" rootScreen={<HomeScreen />} />,
+    tab: ({ isActive, onPress }) => (
+      <Pressable onPress={onPress}>
+        <Text style={{ fontWeight: isActive ? "bold" : "normal" }}>Home</Text>
+      </Pressable>
+    ),
+  },
+  {
+    id: "settings",
+    screen: <SettingsScreen />,
+    tab: ({ isActive, onPress }) => (
+      <Pressable onPress={onPress}>
+        <Text style={{ fontWeight: isActive ? "bold" : "normal" }}>Settings</Text>
+      </Pressable>
+    ),
+  },
+];
+
+export default function App() {
+  return (
+    <Navigation navigation={navigation}>
+      <Tabs id="main-tabs" screens={tabScreens} />
+    </Navigation>
+  );
+}
+```
+
+Push and pop screens imperatively:
+
+```tsx
+navigation.pushScreen(<DetailScreen />, { id: "detail" });
+navigation.popScreen();
+navigation.setActiveTab(1);
+```
+
+When no explicit target is provided, these methods automatically resolve the deepest active stack or tabs instance.
+
+## Docs
+
+- [Navigation](docs/navigation.md) — setup, `createNavigation`, `NavigationClient` API, hooks
+- [Stack](docs/stack.md) — stack navigation, pushing/popping, refs, preloading, nesting
+- [Tabs](docs/tabs.md) — tab navigation, tab bar, refs, preloading, nesting with stacks

package/src/index.ts

@@ -1,4 +1,4 @@
-export * from "./navigation";
 export * from "./stack";
+export * from "./navigation-client";
+export { Navigation, type NavigationProps } from "./navigation";
 export * from "./tabs";
-export * from './deep-links'

package/src/navigation-client.test.tsx

@@ -0,0 +1,206 @@
+import * as React from "react";
+import { describe, expect, it } from "vitest";
+import {
+  createNavigation,
+  createNavigationState,
+  loadNavigationState,
+} from "./navigation-client";
+
+describe("createNavigationState", () => {
+  it("returns empty maps by default", () => {
+    const state = createNavigationState();
+    expect(state.stacks).toBeInstanceOf(Map);
+    expect(state.tabs).toBeInstanceOf(Map);
+    expect(state.stacks.size).toBe(0);
+    expect(state.tabs.size).toBe(0);
+  });
+
+  it("normalizes Record inputs into Maps", () => {
+    const state = createNavigationState({
+      stacks: {
+        "stack-a": [{ element: <span>a</span> }],
+      },
+      tabs: {
+        "my-tabs": { activeIndex: 2 },
+      },
+    });
+
+    expect(state.stacks).toBeInstanceOf(Map);
+    expect(state.stacks.get("stack-a")).toHaveLength(1);
+    expect(state.tabs).toBeInstanceOf(Map);
+    expect(state.tabs.get("my-tabs")).toEqual({ activeIndex: 2 });
+  });
+
+  it("accepts Map inputs directly", () => {
+    const stacks = new Map([
+      ["stack-a", [{ element: <span>a</span> }]],
+    ]);
+    const tabs = new Map([["my-tabs", { activeIndex: 1 }]]);
+    const state = createNavigationState({ stacks, tabs });
+
+    expect(state.stacks.get("stack-a")).toHaveLength(1);
+    expect(state.tabs.get("my-tabs")).toEqual({ activeIndex: 1 });
+  });
+});
+
+describe("createNavigation", () => {
+  it("returns a client with the expected shape", () => {
+    const nav = createNavigation();
+    expect(nav.store).toBeDefined();
+    expect(nav.renderTreeStore).toBeDefined();
+    expect(typeof nav.pushScreen).toBe("function");
+    expect(typeof nav.popScreen).toBe("function");
+    expect(typeof nav.setActiveTab).toBe("function");
+  });
+
+  it("initializes with empty state by default", () => {
+    const nav = createNavigation();
+    const state = nav.store.getState();
+    expect(state.stacks.size).toBe(0);
+    expect(state.tabs.size).toBe(0);
+  });
+
+  it("initializes with the provided state", () => {
+    const nav = createNavigation({
+      stacks: { "stack-a": [{ element: <span>a</span> }] },
+      tabs: { "my-tabs": { activeIndex: 1 } },
+    });
+    const state = nav.store.getState();
+    expect(state.stacks.get("stack-a")).toHaveLength(1);
+    expect(state.tabs.get("my-tabs")).toEqual({ activeIndex: 1 });
+  });
+});
+
+describe("loadNavigationState", () => {
+  it("replaces the store state with normalized input", () => {
+    const nav = createNavigation({
+      stacks: { "stack-a": [{ element: <span>old</span> }] },
+    });
+
+    loadNavigationState(nav.store, {
+      stacks: { "stack-b": [{ element: <span>new</span> }] },
+    });
+
+    const state = nav.store.getState();
+    expect(state.stacks.has("stack-a")).toBe(false);
+    expect(state.stacks.get("stack-b")).toHaveLength(1);
+  });
+});
+
+describe("pushScreen", () => {
+  it("pushes a screen to the specified stack", () => {
+    const nav = createNavigation({
+      stacks: { "stack-a": [] },
+    });
+
+    nav.pushScreen(<span>pushed</span>, { stackId: "stack-a" });
+
+    const screens = nav.store.getState().stacks.get("stack-a");
+    expect(screens).toHaveLength(1);
+  });
+
+  it("creates the stack entry if it did not exist", () => {
+    const nav = createNavigation();
+
+    nav.pushScreen(<span>pushed</span>, { stackId: "stack-new" });
+
+    const screens = nav.store.getState().stacks.get("stack-new");
+    expect(screens).toHaveLength(1);
+  });
+
+  it("does not push a duplicate screen with the same id", () => {
+    const nav = createNavigation({
+      stacks: {
+        "stack-a": [{ element: <span>a</span>, options: { id: "screen-1" } }],
+      },
+    });
+
+    nav.pushScreen(<span>dup</span>, { id: "screen-1", stackId: "stack-a" });
+
+    expect(nav.store.getState().stacks.get("stack-a")).toHaveLength(1);
+  });
+
+  it("allows pushing after a screen with the same id was popped", () => {
+    const nav = createNavigation({
+      stacks: {
+        "stack-a": [{ element: <span>a</span>, options: { id: "screen-1" } }],
+      },
+    });
+
+    nav.popScreen({ stackId: "stack-a" });
+    expect(nav.store.getState().stacks.get("stack-a")).toHaveLength(0);
+
+    nav.pushScreen(<span>new</span>, { id: "screen-1", stackId: "stack-a" });
+    expect(nav.store.getState().stacks.get("stack-a")).toHaveLength(1);
+  });
+
+  it("throws when no stackId is provided and no stack is mounted", () => {
+    const nav = createNavigation();
+    expect(() => nav.pushScreen(<span>x</span>)).toThrow(
+      "could not resolve stackId",
+    );
+  });
+});
+
+describe("popScreen", () => {
+  it("removes the top screen from the specified stack", () => {
+    const nav = createNavigation({
+      stacks: {
+        "stack-a": [
+          { element: <span>a</span> },
+          { element: <span>b</span> },
+        ],
+      },
+    });
+
+    nav.popScreen({ stackId: "stack-a" });
+
+    expect(nav.store.getState().stacks.get("stack-a")).toHaveLength(1);
+  });
+
+  it("is a no-op when the stack is empty", () => {
+    const nav = createNavigation({
+      stacks: { "stack-a": [] },
+    });
+
+    const before = nav.store.getState();
+    nav.popScreen({ stackId: "stack-a" });
+    const after = nav.store.getState();
+
+    expect(before).toBe(after);
+  });
+
+  it("throws when no stackId is provided and no stack is mounted", () => {
+    const nav = createNavigation();
+    expect(() => nav.popScreen()).toThrow("could not resolve stackId");
+  });
+});
+
+describe("setActiveTab", () => {
+  it("sets the active index for the specified tabs", () => {
+    const nav = createNavigation({
+      tabs: { "my-tabs": { activeIndex: 0 } },
+    });
+
+    nav.setActiveTab(2, { tabsId: "my-tabs" });
+
+    expect(nav.store.getState().tabs.get("my-tabs")).toEqual({
+      activeIndex: 2,
+    });
+  });
+
+  it("creates the tabs entry if it did not exist", () => {
+    const nav = createNavigation();
+
+    nav.setActiveTab(1, { tabsId: "new-tabs" });
+
+    expect(nav.store.getState().tabs.get("new-tabs")).toEqual({
+      activeIndex: 1,
+    });
+  });
+
+  it("throws when no tabsId is provided and no tabs are mounted", () => {
+    const nav = createNavigation();
+    expect(() => nav.setActiveTab(0)).toThrow("could not resolve tabsId");
+  });
+});

package/src/navigation-client.tsx

@@ -0,0 +1,216 @@
+import * as React from "react";
+import {
+  createStore,
+  useStore,
+  createRenderTreeStore,
+  getRenderNodeActive,
+  getRenderNodeDepth,
+} from "@rn-tools/core";
+import type { Store, RenderTreeStore } from "@rn-tools/core";
+
+export type PushScreenOptions = {
+  id?: string;
+  stackId?: string;
+};
+
+export type NavigationScreenEntry = {
+  element: React.ReactElement;
+  id?: string;
+  options?: PushScreenOptions;
+};
+
+export type TabState = {
+  activeIndex: number;
+};
+
+export type NavigationState = {
+  stacks: Map<string, NavigationScreenEntry[]>;
+  tabs: Map<string, TabState>;
+};
+
+export type NavigationStore = Store<NavigationState>;
+
+export const NavigationContext = React.createContext<NavigationClient | null>(null);
+
+export const NavigationStoreContext = React.createContext<NavigationStore | null>(
+  null,
+);
+
+export type NavigationStateInput = {
+  stacks?:
+    | Map<string, NavigationScreenEntry[]>
+    | Record<string, NavigationScreenEntry[]>;
+  tabs?:
+    | Map<string, TabState>
+    | Record<string, TabState>;
+};
+
+export function createNavigationState(
+  input: NavigationStateInput = {},
+): NavigationState {
+  return normalizeNavigationState(input);
+}
+
+export function loadNavigationState(
+  store: NavigationStore,
+  input: NavigationState | NavigationStateInput,
+) {
+  store.setState(normalizeNavigationState(input));
+}
+
+export type NavigationClient = {
+  store: NavigationStore;
+  renderTreeStore: RenderTreeStore;
+  pushScreen: (element: React.ReactElement, options?: PushScreenOptions) => void;
+  popScreen: (options?: { stackId?: string }) => void;
+  setActiveTab: (index: number, options?: { tabsId?: string }) => void;
+};
+
+export function createNavigation(
+  initialState?: NavigationStateInput,
+): NavigationClient {
+  const navStore = createStore(
+    normalizeNavigationState(initialState ?? { stacks: new Map() }),
+  );
+  const renderTreeStore = createRenderTreeStore();
+
+  function getDeepestActiveNodeId(type: string): string | null {
+    const tree = renderTreeStore.getState();
+    let deepestId: string | null = null;
+    let deepestDepth = -1;
+
+    for (const [id, node] of tree.nodes) {
+      if (node.type !== type) continue;
+      if (!getRenderNodeActive(tree, id)) continue;
+
+      const depth = getRenderNodeDepth(tree, id);
+      if (depth > deepestDepth) {
+        deepestDepth = depth;
+        deepestId = id;
+      }
+    }
+
+    return deepestId;
+  }
+
+  function pushScreen(
+    element: React.ReactElement,
+    options?: PushScreenOptions,
+  ) {
+    const stackId = options?.stackId ?? getDeepestActiveNodeId("stack");
+    if (!stackId) {
+      throw new Error(
+        "pushScreen: could not resolve stackId. Pass { stackId } explicitly or ensure a Stack is mounted and active.",
+      );
+    }
+
+    navStore.setState((prev) => {
+      const stacks = new Map(prev.stacks);
+      const existing = stacks.get(stackId) ?? [];
+
+      if (
+        options?.id &&
+        existing.some(
+          (s) => s.id === options.id || s.options?.id === options.id,
+        )
+      ) {
+        return prev;
+      }
+
+      stacks.set(stackId, [...existing, { element, id: options?.id, options }]);
+      return { ...prev, stacks };
+    });
+  }
+
+  function popScreen(options?: { stackId?: string }) {
+    const stackId = options?.stackId ?? getDeepestActiveNodeId("stack");
+    if (!stackId) {
+      throw new Error(
+        "popScreen: could not resolve stackId. Pass { stackId } explicitly or ensure a Stack is mounted and active.",
+      );
+    }
+
+    navStore.setState((prev) => {
+      const stacks = new Map(prev.stacks);
+      const screens = stacks.get(stackId);
+      if (!screens || screens.length === 0) return prev;
+      stacks.set(stackId, screens.slice(0, -1));
+      return { ...prev, stacks };
+    });
+  }
+
+  function setActiveTab(index: number, options?: { tabsId?: string }) {
+    const tabsId = options?.tabsId ?? getDeepestActiveNodeId("tabs");
+    if (!tabsId) {
+      throw new Error(
+        "setActiveTab: could not resolve tabsId. Pass { tabsId } explicitly or ensure a Tabs is mounted and active.",
+      );
+    }
+
+    navStore.setState((prev) => {
+      const tabs = new Map(prev.tabs);
+      tabs.set(tabsId, { activeIndex: index });
+      return { ...prev, tabs };
+    });
+  }
+
+  return { store: navStore, renderTreeStore, pushScreen, popScreen, setActiveTab };
+}
+
+export function useNavigation(): NavigationClient {
+  const navigation = React.useContext(NavigationContext);
+  if (!navigation) {
+    throw new Error("NavigationProvider is missing from the component tree.");
+  }
+  return navigation;
+}
+
+export function useNavigationStore(): NavigationStore {
+  const store = React.useContext(NavigationStoreContext);
+  if (!store) {
+    throw new Error("NavigationProvider is missing from the component tree.");
+  }
+  return store;
+}
+
+export function useTabActiveIndex(tabsId: string | null): number {
+  const store = useNavigationStore();
+  return useStore(store, (state) =>
+    tabsId ? state.tabs.get(tabsId)?.activeIndex ?? 0 : 0,
+  );
+}
+
+export function useStackScreens(
+  stackKey: string | null,
+): NavigationScreenEntry[] {
+  const store = useNavigationStore();
+  return useStore(store, (state) =>
+    stackKey ? state.stacks.get(stackKey) ?? [] : [],
+  );
+}
+
+function normalizeNavigationState(
+  input: NavigationState | NavigationStateInput,
+): NavigationState {
+  const stacksInput =
+    (input as NavigationState).stacks ??
+    (input as NavigationStateInput).stacks ??
+    new Map();
+
+  const stacks =
+    stacksInput instanceof Map
+      ? new Map(stacksInput)
+      : new Map(Object.entries(stacksInput));
+
+  const tabsInput =
+    (input as NavigationState).tabs ??
+    (input as NavigationStateInput).tabs ??
+    new Map();
+
+  const tabs =
+    tabsInput instanceof Map
+      ? new Map(tabsInput)
+      : new Map(Object.entries(tabsInput));
+
+  return { stacks, tabs };
+}