@rn-tools/navigation 3.0.1 → 3.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rn-tools/navigation",
-  "version": "3.0.1",
+  "version": "3.0.2",
   "main": "./src/index.ts",
   "license": "MIT",
   "files": [
@@ -34,6 +34,7 @@
     "react-native-screens": "*"
   },
   "dependencies": {
+    "@rn-tools/sheets": "*",
     "path-to-regexp": "^6.2.2",
     "zustand": "^4.5.2"
   }

package/readme.md

@@ -54,9 +54,12 @@ export default function App() {
 Push and pop screens imperatively:
 
 ```tsx
-navigation.pushScreen(<DetailScreen />, { id: "detail" });
-navigation.popScreen();
-navigation.setActiveTab(1);
+navigation.push(<DetailScreen />, { id: "detail" });
+navigation.pop();
+navigation.tab(1);
+navigation.present(<EditSheet />, { id: "edit", snapPoints: [320, 520] });
+navigation.dismiss();
+navigation.dismissAll();
 ```
 
 When no explicit target is provided, these methods automatically resolve the deepest active stack or tabs instance.

package/src/navigation-client.test.tsx

@@ -48,9 +48,13 @@ describe("createNavigation", () => {
     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");
+    expect(nav.sheetsStore).toBeDefined();
+    expect(typeof nav.push).toBe("function");
+    expect(typeof nav.pop).toBe("function");
+    expect(typeof nav.tab).toBe("function");
+    expect(typeof nav.present).toBe("function");
+    expect(typeof nav.dismiss).toBe("function");
+    expect(typeof nav.dismissAll).toBe("function");
   });
 
   it("initializes with empty state by default", () => {
@@ -71,6 +75,33 @@ describe("createNavigation", () => {
   });
 });
 
+describe("sheet methods", () => {
+  it("present returns a key", () => {
+    const nav = createNavigation();
+    const key = nav.present(<span>sheet</span>);
+
+    expect(typeof key).toBe("string");
+  });
+
+  it("present reuses key when id is reused", () => {
+    const nav = createNavigation();
+    const key1 = nav.present(<span>sheet-a</span>, { id: "edit" });
+    const key2 = nav.present(<span>sheet-b</span>, { id: "edit" });
+
+    expect(key2).toBe(key1);
+  });
+
+  it("dismiss and dismissAll are callable via public API", () => {
+    const nav = createNavigation();
+    nav.present(<span>a</span>);
+    nav.present(<span>b</span>);
+
+    expect(() => nav.dismiss()).not.toThrow();
+    nav.dismissAll();
+    expect(() => nav.dismissAll()).not.toThrow();
+  });
+});
+
 describe("loadNavigationState", () => {
   it("replaces the store state with normalized input", () => {
     const nav = createNavigation({
@@ -87,13 +118,13 @@ describe("loadNavigationState", () => {
   });
 });
 
-describe("pushScreen", () => {
+describe("push", () => {
   it("pushes a screen to the specified stack", () => {
     const nav = createNavigation({
       stacks: { "stack-a": [] },
     });
 
-    nav.pushScreen(<span>pushed</span>, { stackId: "stack-a" });
+    nav.push(<span>pushed</span>, { stack: "stack-a" });
 
     const screens = nav.store.getState().stacks.get("stack-a");
     expect(screens).toHaveLength(1);
@@ -102,7 +133,7 @@ describe("pushScreen", () => {
   it("creates the stack entry if it did not exist", () => {
     const nav = createNavigation();
 
-    nav.pushScreen(<span>pushed</span>, { stackId: "stack-new" });
+    nav.push(<span>pushed</span>, { stack: "stack-new" });
 
     const screens = nav.store.getState().stacks.get("stack-new");
     expect(screens).toHaveLength(1);
@@ -115,7 +146,7 @@ describe("pushScreen", () => {
       },
     });
 
-    nav.pushScreen(<span>dup</span>, { id: "screen-1", stackId: "stack-a" });
+    nav.push(<span>dup</span>, { id: "screen-1", stack: "stack-a" });
 
     expect(nav.store.getState().stacks.get("stack-a")).toHaveLength(1);
   });
@@ -127,22 +158,22 @@ describe("pushScreen", () => {
       },
     });
 
-    nav.popScreen({ stackId: "stack-a" });
+    nav.pop({ stack: "stack-a" });
     expect(nav.store.getState().stacks.get("stack-a")).toHaveLength(0);
 
-    nav.pushScreen(<span>new</span>, { id: "screen-1", stackId: "stack-a" });
+    nav.push(<span>new</span>, { id: "screen-1", stack: "stack-a" });
     expect(nav.store.getState().stacks.get("stack-a")).toHaveLength(1);
   });
 
-  it("throws when no stackId is provided and no stack is mounted", () => {
+  it("throws when no stack is provided and no stack is mounted", () => {
     const nav = createNavigation();
-    expect(() => nav.pushScreen(<span>x</span>)).toThrow(
-      "could not resolve stackId",
+    expect(() => nav.push(<span>x</span>)).toThrow(
+      "could not resolve stack",
     );
   });
 });
 
-describe("popScreen", () => {
+describe("pop", () => {
   it("removes the top screen from the specified stack", () => {
     const nav = createNavigation({
       stacks: {
@@ -153,7 +184,7 @@ describe("popScreen", () => {
       },
     });
 
-    nav.popScreen({ stackId: "stack-a" });
+    nav.pop({ stack: "stack-a" });
 
     expect(nav.store.getState().stacks.get("stack-a")).toHaveLength(1);
   });
@@ -164,25 +195,25 @@ describe("popScreen", () => {
     });
 
     const before = nav.store.getState();
-    nav.popScreen({ stackId: "stack-a" });
+    nav.pop({ stack: "stack-a" });
     const after = nav.store.getState();
 
     expect(before).toBe(after);
   });
 
-  it("throws when no stackId is provided and no stack is mounted", () => {
+  it("throws when no stack is provided and no stack is mounted", () => {
     const nav = createNavigation();
-    expect(() => nav.popScreen()).toThrow("could not resolve stackId");
+    expect(() => nav.pop()).toThrow("could not resolve stack");
   });
 });
 
-describe("setActiveTab", () => {
+describe("tab", () => {
   it("sets the active index for the specified tabs", () => {
     const nav = createNavigation({
       tabs: { "my-tabs": { activeIndex: 0 } },
     });
 
-    nav.setActiveTab(2, { tabsId: "my-tabs" });
+    nav.tab(2, { tabs: "my-tabs" });
 
     expect(nav.store.getState().tabs.get("my-tabs")).toEqual({
       activeIndex: 2,
@@ -192,15 +223,15 @@ describe("setActiveTab", () => {
   it("creates the tabs entry if it did not exist", () => {
     const nav = createNavigation();
 
-    nav.setActiveTab(1, { tabsId: "new-tabs" });
+    nav.tab(1, { tabs: "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", () => {
+  it("throws when no tabs is provided and no tabs are mounted", () => {
     const nav = createNavigation();
-    expect(() => nav.setActiveTab(0)).toThrow("could not resolve tabsId");
+    expect(() => nav.tab(0)).toThrow("could not resolve tabs");
   });
 });

package/src/navigation-client.tsx

@@ -7,16 +7,18 @@ import {
   getRenderNodeDepth,
 } from "@rn-tools/core";
 import type { Store, RenderTreeStore } from "@rn-tools/core";
+import { createSheets } from "@rn-tools/sheets";
+import type { SheetOptions, SheetsClient } from "@rn-tools/sheets";
 
-export type PushScreenOptions = {
+export type PushOptions = {
   id?: string;
-  stackId?: string;
+  stack?: string;
 };
 
 export type NavigationScreenEntry = {
   element: React.ReactElement;
   id?: string;
-  options?: PushScreenOptions;
+  options?: PushOptions;
 };
 
 export type TabState = {
@@ -61,9 +63,13 @@ export function loadNavigationState(
 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;
+  sheetsStore: SheetsClient;
+  push: (element: React.ReactElement, options?: PushOptions) => void;
+  pop: (options?: { stack?: string }) => void;
+  tab: (index: number, options?: { tabs?: string }) => void;
+  present: (element: React.ReactElement, options?: SheetOptions) => string;
+  dismiss: (id?: string) => void;
+  dismissAll: () => void;
 };
 
 export function createNavigation(
@@ -73,6 +79,7 @@ export function createNavigation(
     normalizeNavigationState(initialState ?? { stacks: new Map() }),
   );
   const renderTreeStore = createRenderTreeStore();
+  const sheetsStore = createSheets();
 
   function getDeepestActiveNodeId(type: string): string | null {
     const tree = renderTreeStore.getState();
@@ -93,14 +100,14 @@ export function createNavigation(
     return deepestId;
   }
 
-  function pushScreen(
+  function push(
     element: React.ReactElement,
-    options?: PushScreenOptions,
+    options?: PushOptions,
   ) {
-    const stackId = options?.stackId ?? getDeepestActiveNodeId("stack");
+    const stackId = options?.stack ?? getDeepestActiveNodeId("stack");
     if (!stackId) {
       throw new Error(
-        "pushScreen: could not resolve stackId. Pass { stackId } explicitly or ensure a Stack is mounted and active.",
+        "push: could not resolve stack. Pass { stack } explicitly or ensure a Stack is mounted and active.",
       );
     }
 
@@ -122,11 +129,11 @@ export function createNavigation(
     });
   }
 
-  function popScreen(options?: { stackId?: string }) {
-    const stackId = options?.stackId ?? getDeepestActiveNodeId("stack");
+  function pop(options?: { stack?: string }) {
+    const stackId = options?.stack ?? getDeepestActiveNodeId("stack");
     if (!stackId) {
       throw new Error(
-        "popScreen: could not resolve stackId. Pass { stackId } explicitly or ensure a Stack is mounted and active.",
+        "pop: could not resolve stack. Pass { stack } explicitly or ensure a Stack is mounted and active.",
       );
     }
 
@@ -139,11 +146,11 @@ export function createNavigation(
     });
   }
 
-  function setActiveTab(index: number, options?: { tabsId?: string }) {
-    const tabsId = options?.tabsId ?? getDeepestActiveNodeId("tabs");
+  function tab(index: number, options?: { tabs?: string }) {
+    const tabsId = options?.tabs ?? getDeepestActiveNodeId("tabs");
     if (!tabsId) {
       throw new Error(
-        "setActiveTab: could not resolve tabsId. Pass { tabsId } explicitly or ensure a Tabs is mounted and active.",
+        "tab: could not resolve tabs. Pass { tabs } explicitly or ensure a Tabs is mounted and active.",
       );
     }
 
@@ -154,7 +161,29 @@ export function createNavigation(
     });
   }
 
-  return { store: navStore, renderTreeStore, pushScreen, popScreen, setActiveTab };
+  function present(element: React.ReactElement, options?: SheetOptions): string {
+    return sheetsStore.present(element, options);
+  }
+
+  function dismiss(id?: string) {
+    sheetsStore.dismiss(id);
+  }
+
+  function dismissAll() {
+    sheetsStore.dismissAll();
+  }
+
+  return {
+    store: navStore,
+    renderTreeStore,
+    sheetsStore,
+    push,
+    pop,
+    tab,
+    present,
+    dismiss,
+    dismissAll,
+  };
 }
 
 export function useNavigation(): NavigationClient {

package/src/navigation.tsx

@@ -1,5 +1,6 @@
 import * as React from "react";
 import { RenderTree } from "@rn-tools/core";
+import { SheetsProvider } from "@rn-tools/sheets";
 import {
   NavigationContext,
   NavigationStoreContext,
@@ -30,11 +31,13 @@ export const Navigation = React.memo(function Navigation(
 ) {
   return (
     <RenderTree store={props.navigation.renderTreeStore}>
-      <NavigationContext.Provider value={props.navigation}>
-        <NavigationStoreContext.Provider value={props.navigation.store}>
-          <RootStack>{props.children}</RootStack>
-        </NavigationStoreContext.Provider>
-      </NavigationContext.Provider>
+      <SheetsProvider sheets={props.navigation.sheetsStore}>
+        <NavigationContext.Provider value={props.navigation}>
+          <NavigationStoreContext.Provider value={props.navigation.store}>
+            <RootStack>{props.children}</RootStack>
+          </NavigationStoreContext.Provider>
+        </NavigationContext.Provider>
+      </SheetsProvider>
     </RenderTree>
   );
 });

package/src/stack.test.tsx

@@ -110,7 +110,7 @@ describe("Stack", () => {
     expect(renderer.getByText("screen-b:true")).toBeTruthy();
   });
 
-  it("pushScreen adds a new active screen to the stack", async () => {
+  it("push adds a new active screen to the stack", async () => {
     const { navigation, renderer } = await renderWithProviders(
       <Stack id="stack-a" />,
       {
@@ -132,13 +132,13 @@ describe("Stack", () => {
     );
 
     act(() => {
-      navigation.pushScreen(
+      navigation.push(
         <RenderNodeProbe
           render={(data) => <span>{`screen-b:${String(data.active)}`}</span>}
         />,
         {
           id: "screen-b",
-          stackId: "stack-a",
+          stack: "stack-a",
         },
       );
     });
@@ -227,7 +227,7 @@ describe("Stack", () => {
     expect(renderer.getByText("a1:true")).toBeTruthy();
   });
 
-  it("pushScreen does not push a duplicate when a screen with the same id exists", async () => {
+  it("push does not push a duplicate when a screen with the same id exists", async () => {
     const { navigation, renderer } = await renderWithProviders(
       <Stack id="stack-a" />,
       {
@@ -243,9 +243,9 @@ describe("Stack", () => {
     );
 
     act(() => {
-      navigation.pushScreen(<span>screen-a-dup</span>, {
+      navigation.push(<span>screen-a-dup</span>, {
         id: "screen-a",
-        stackId: "stack-a",
+        stack: "stack-a",
       });
     });
 
@@ -253,16 +253,16 @@ describe("Stack", () => {
     expect(renderer.getByText("screen-a")).toBeTruthy();
 
     act(() => {
-      navigation.popScreen({ stackId: "stack-a" });
+      navigation.pop({ stack: "stack-a" });
     });
 
     expect(navigation.store.getState().stacks.get("stack-a")).toHaveLength(0);
     expect(renderer.queryByText("screen-a")).toBeNull();
 
     act(() => {
-      navigation.pushScreen(<span>screen-a-again</span>, {
+      navigation.push(<span>screen-a-again</span>, {
         id: "screen-a",
-        stackId: "stack-a",
+        stack: "stack-a",
       });
     });
 
@@ -270,30 +270,99 @@ describe("Stack", () => {
     renderer.getByText("screen-a-again");
   });
 
-  it("ref.pushScreen adds a screen and ref.popScreen removes it", async () => {
+  it("ref.push adds a screen and ref.pop removes it", async () => {
     const ref = React.createRef<StackHandle>();
-    const { renderer } = await renderWithProviders(
+    const { renderer, store } = await renderWithProviders(
       <Stack ref={ref} id="stack-a" rootScreen={<span>root</span>} />,
     );
 
     expect(renderer.getByText("root")).toBeTruthy();
 
     act(() => {
-      ref.current!.pushScreen(<span>pushed</span>, { id: "pushed-screen" });
+      ref.current!.push(<span>pushed</span>, { id: "pushed-screen" });
     });
 
     await waitFor(() => {
       expect(renderer.getByText("pushed")).toBeTruthy();
     });
 
+    expect(store.getState().stacks.get("stack-a")).toHaveLength(1);
+
     act(() => {
-      ref.current!.popScreen();
+      ref.current!.pop();
     });
 
     await waitFor(() => {
       expect(renderer.queryByText("pushed")).toBeNull();
       expect(renderer.getByText("root")).toBeTruthy();
     });
+
+    expect(store.getState().stacks.get("stack-a")).toHaveLength(0);
+  });
+
+  it("ref.push targets the correct stack when id is not provided", async () => {
+    const ref = React.createRef<StackHandle>();
+    const { renderer, store } = await renderWithProviders(
+      <Stack ref={ref} rootScreen={<span>root</span>} />,
+    );
+
+    expect(renderer.getByText("root")).toBeTruthy();
+
+    act(() => {
+      ref.current!.push(<span>pushed</span>, { id: "pushed-screen" });
+    });
+
+    await waitFor(() => {
+      expect(renderer.getByText("pushed")).toBeTruthy();
+    });
+
+    // The screen should be pushed to the auto-generated stack id
+    const state = store.getState();
+    expect(state.stacks.size).toBe(1);
+    const [stackId, screens] = [...state.stacks.entries()][0];
+    expect(typeof stackId).toBe("string");
+    expect(screens).toHaveLength(1);
+
+    act(() => {
+      ref.current!.pop();
+    });
+
+    await waitFor(() => {
+      expect(renderer.queryByText("pushed")).toBeNull();
+      expect(renderer.getByText("root")).toBeTruthy();
+    });
+
+    expect(store.getState().stacks.get(stackId)).toHaveLength(0);
+  });
+
+  it("ref.push targets the inner stack when nested without an explicit id", async () => {
+    const innerRef = React.createRef<StackHandle>();
+
+    function InnerStack() {
+      return <Stack ref={innerRef} rootScreen={<span>inner-root</span>} />;
+    }
+
+    const { renderer, store } = await renderWithProviders(
+      <Stack id="outer" rootScreen={<InnerStack />} />,
+    );
+
+    await waitFor(() => {
+      expect(renderer.getByText("inner-root")).toBeTruthy();
+    });
+
+    act(() => {
+      innerRef.current!.push(<span>inner-pushed</span>, {
+        id: "inner-screen",
+      });
+    });
+
+    await waitFor(() => {
+      expect(renderer.getByText("inner-pushed")).toBeTruthy();
+    });
+
+    // The screen was pushed to the inner stack's auto-generated id, not "outer"
+    const state = store.getState();
+    expect(state.stacks.has("outer")).toBe(false);
   });
 
   it("resolves the deepest active stack and falls back when a subtree becomes inactive", async () => {
@@ -314,9 +383,9 @@ describe("Stack", () => {
       expect(result.getByText("nested-root")).toBeTruthy();
     });
 
-    // pushScreen with no stackId should target the deepest active stack: right-nested
+    // push with no stack should target the deepest active stack: right-nested
     act(() => {
-      navigation.pushScreen(<span>first-push</span>);
+      navigation.push(<span>first-push</span>);
     });
 
     const stateAfterFirst = navigation.store.getState();
@@ -332,7 +401,7 @@ describe("Stack", () => {
     );
 
     act(() => {
-      navigation.pushScreen(<span>second-push</span>);
+      navigation.push(<span>second-push</span>);
     });
 
     const stateAfterSecond = navigation.store.getState();

package/src/stack.tsx

@@ -1,9 +1,13 @@
 import * as React from "react";
-import { RenderTreeNode, useRenderNode } from "@rn-tools/core";
+import {
+  RenderTreeNode,
+  useRenderNode,
+  nextRenderTreeIdForType,
+} from "@rn-tools/core";
 import {
   useStackScreens,
   useNavigation,
-  type PushScreenOptions,
+  type PushOptions,
 } from "./navigation-client";
 
 // TODO - replace with custom implementation
@@ -11,8 +15,11 @@ import * as RNScreens from "react-native-screens";
 import { StyleSheet } from "react-native";
 
 export type StackHandle = {
-  pushScreen: (element: React.ReactElement, options?: PushScreenOptions) => void;
-  popScreen: () => void;
+  push: (
+    element: React.ReactElement,
+    options?: PushOptions,
+  ) => void;
+  pop: () => void;
 };
 
 export type StackProps = {
@@ -22,16 +29,36 @@ export type StackProps = {
   children?: React.ReactNode;
 };
 
-const StackRoot = React.memo(function StackRoot(props: StackProps) {
-  return (
-    <RenderTreeNode type="stack" id={props.id} active={props.active}>
-      <RNScreens.ScreenStack style={StyleSheet.absoluteFill}>
-        {props.rootScreen && <StackScreen>{props.rootScreen}</StackScreen>}
-        {props.children}
-      </RNScreens.ScreenStack>
-    </RenderTreeNode>
-  );
-});
+const StackRoot = React.memo(
+  React.forwardRef<StackHandle, StackProps>(function StackRoot(props, ref) {
+    const stackId = React.useRef(
+      props.id ?? nextRenderTreeIdForType("stack"),
+    ).current;
+    const navigation = useNavigation();
+
+    React.useImperativeHandle(
+      ref,
+      () => ({
+        push(element: React.ReactElement, options?: PushOptions) {
+          navigation.push(element, { ...options, stack: stackId });
+        },
+        pop() {
+          navigation.pop({ stack: stackId });
+        },
+      }),
+      [stackId, navigation],
+    );
+
+    return (
+      <RenderTreeNode type="stack" id={stackId} active={props.active}>
+        <RNScreens.ScreenStack style={StyleSheet.absoluteFill}>
+          {props.rootScreen && <StackScreen>{props.rootScreen}</StackScreen>}
+          {props.children}
+        </RNScreens.ScreenStack>
+      </RenderTreeNode>
+    );
+  }),
+);
 
 export type StackScreenProps = {
   id?: string;
@@ -72,25 +99,8 @@ const StackSlot = React.memo(function StackSlot() {
 export const Stack = React.memo(
   React.forwardRef<StackHandle, Omit<StackProps, "children">>(
     function Stack(props, ref) {
-      const navigation = useNavigation();
-      const node = useRenderNode();
-      const stackId = props.id ?? node?.id ?? null;
-
-      React.useImperativeHandle(ref, () => ({
-        pushScreen(element: React.ReactElement, options?: PushScreenOptions) {
-          if (stackId) {
-            navigation.pushScreen(element, { ...options, stackId });
-          }
-        },
-        popScreen() {
-          if (stackId) {
-            navigation.popScreen({ stackId });
-          }
-        },
-      }), [stackId, navigation]);
-
       return (
-        <StackRoot {...props}>
+        <StackRoot ref={ref} {...props}>
           <StackSlot />
         </StackRoot>
       );

package/src/tabs.test.tsx

@@ -62,14 +62,14 @@ describe("Tabs", () => {
     expect(renderer.getByText("tab-2:tab-screen:false")).toBeTruthy();
   });
 
-  it("setActiveTab changes which screen is active", async () => {
+  it("tab changes which screen is active", async () => {
     const screens = makeScreens(3);
     const { navigation, renderer } = renderWithProviders(
       <Tabs id="my-tabs" screens={screens} />,
     );
 
     act(() => {
-      navigation.setActiveTab(2);
+      navigation.tab(2);
     });
 
     await waitFor(() => {
@@ -88,17 +88,39 @@ describe("Tabs", () => {
     expect(renderer.getByText("tab-0:tab-screen:false")).toBeTruthy();
   });
 
-  it("ref.setActiveIndex changes the active tab", async () => {
+  it("ref.setActive changes the active tab", async () => {
     const screens = makeScreens(3);
     const ref = React.createRef<TabsHandle>();
-    const { renderer } = renderWithProviders(
+    const { renderer, store } = renderWithProviders(
       <Tabs ref={ref} id="my-tabs" screens={screens} />,
     );
 
     expect(renderer.getByText("tab-0:tab-screen:true")).toBeTruthy();
 
     act(() => {
-      ref.current!.setActiveIndex(2);
+      ref.current!.setActive(2);
+    });
+
+    await waitFor(() => {
+      expect(renderer.getByText("tab-0:tab-screen:false")).toBeTruthy();
+      expect(renderer.getByText("tab-1:tab-screen:false")).toBeTruthy();
+      expect(renderer.getByText("tab-2:tab-screen:true")).toBeTruthy();
+    });
+
+    expect(store.getState().tabs.get("my-tabs")).toEqual({ activeIndex: 2 });
+  });
+
+  it("ref.setActive targets the correct tabs when id is not provided", async () => {
+    const screens = makeScreens(3);
+    const ref = React.createRef<TabsHandle>();
+    const { renderer, store } = renderWithProviders(
+      <Tabs ref={ref} screens={screens} />,
+    );
+
+    expect(renderer.getByText("tab-0:tab-screen:true")).toBeTruthy();
+
+    act(() => {
+      ref.current!.setActive(2);
     });
 
     await waitFor(() => {
@@ -106,6 +128,55 @@ describe("Tabs", () => {
       expect(renderer.getByText("tab-1:tab-screen:false")).toBeTruthy();
       expect(renderer.getByText("tab-2:tab-screen:true")).toBeTruthy();
     });
+
+    // The tab state should be set on the auto-generated tabs id
+    const state = store.getState();
+    expect(state.tabs.size).toBe(1);
+    const [, tabState] = [...state.tabs.entries()][0];
+    expect(tabState).toEqual({ activeIndex: 2 });
+  });
+
+  it("ref.setActive targets the inner tabs when nested inside a stack without an explicit id", async () => {
+    const ref = React.createRef<TabsHandle>();
+    const navigation = createNavigation();
+
+    const tabScreens: TabScreenOptions[] = [
+      {
+        id: "tab-a",
+        screen: <span>tab-a-content</span>,
+        tab: () => <span>tab-a</span>,
+      },
+      {
+        id: "tab-b",
+        screen: <span>tab-b-content</span>,
+        tab: () => <span>tab-b</span>,
+      },
+    ];
+
+    const result = render(
+      <Navigation navigation={navigation}>
+        <Stack
+          id="outer-stack"
+          rootScreen={<Tabs ref={ref} screens={tabScreens} />}
+        />
+      </Navigation>,
+    );
+
+    await waitFor(() => {
+      expect(result.getByText("tab-a-content")).toBeTruthy();
+    });
+
+    act(() => {
+      ref.current!.setActive(1);
+    });
+
+    // The tab switch should target the auto-generated tabs id, not "outer-stack"
+    const state = navigation.store.getState();
+    expect(state.tabs.has("outer-stack")).toBe(false);
+    expect(state.tabs.size).toBe(1);
+
+    const [, tabState] = [...state.tabs.entries()][0];
+    expect(tabState.activeIndex).toBe(1);
   });
 
   it("supports preloaded activeIndex from the navigation state", () => {
@@ -179,7 +250,7 @@ describe("TabBar", () => {
 });
 
 describe("Nested Stack + Tabs", () => {
-  it("pushScreen targets the stack inside the active tab", async () => {
+  it("push targets the stack inside the active tab", async () => {
     const navigation = createNavigation();
 
     const screens: TabScreenOptions[] = [
@@ -205,9 +276,9 @@ describe("Nested Stack + Tabs", () => {
       expect(result.getByText("stack-a-root")).toBeTruthy();
     });
 
-    // Tab 0 (stack-a) is active — pushScreen should target stack-a
+    // Tab 0 (stack-a) is active — push should target stack-a
     act(() => {
-      navigation.pushScreen(<span>pushed-to-a</span>);
+      navigation.push(<span>pushed-to-a</span>);
     });
 
     const stateAfterFirst = navigation.store.getState();
@@ -215,7 +286,7 @@ describe("Nested Stack + Tabs", () => {
     expect(stateAfterFirst.stacks.has("stack-b")).toBe(false);
   });
 
-  it("switching tabs redirects pushScreen to the newly active stack", async () => {
+  it("switching tabs redirects push to the newly active stack", async () => {
     const navigation = createNavigation();
 
     const screens: TabScreenOptions[] = [
@@ -239,11 +310,11 @@ describe("Nested Stack + Tabs", () => {
 
     // Switch to tab 1 (stack-b)
     act(() => {
-      navigation.setActiveTab(1);
+      navigation.tab(1);
     });
 
     act(() => {
-      navigation.pushScreen(<span>pushed-to-b</span>);
+      navigation.push(<span>pushed-to-b</span>);
     });
 
     const state = navigation.store.getState();
@@ -251,7 +322,7 @@ describe("Nested Stack + Tabs", () => {
     expect(state.stacks.has("stack-a")).toBe(false);
   });
 
-  it("setActiveTab resolves the correct tabs when a stack wraps tabs", async () => {
+  it("tab resolves the correct tabs when a stack wraps tabs", async () => {
     const navigation = createNavigation();
 
     const tabScreens: TabScreenOptions[] = [
@@ -277,9 +348,9 @@ describe("Nested Stack + Tabs", () => {
       expect(result.getByText("tab-a-content")).toBeTruthy();
     });
 
-    // setActiveTab with no explicit tabsId should resolve inner-tabs
+    // tab with no explicit tabs should resolve inner-tabs
     act(() => {
-      navigation.setActiveTab(1);
+      navigation.tab(1);
     });
 
     const state = navigation.store.getState();

package/src/tabs.tsx

@@ -3,8 +3,13 @@ import {
   RenderTreeNode,
   useRenderNode,
   useSafeAreaInsets,
+  nextRenderTreeIdForType,
 } from "@rn-tools/core";
-import { useTabActiveIndex, useNavigationStore, useNavigation } from "./navigation-client";
+import {
+  useTabActiveIndex,
+  useNavigationStore,
+  useNavigation,
+} from "./navigation-client";
 
 import * as RNScreens from "react-native-screens";
 import { StyleSheet, View, type ViewStyle } from "react-native";
@@ -20,7 +25,7 @@ export type TabScreenOptions = {
 };
 
 export type TabsHandle = {
-  setActiveIndex: (index: number) => void;
+  setActive: (index: number) => void;
 };
 
 export type TabsProps = {
@@ -32,13 +37,30 @@ export type TabsProps = {
   children?: React.ReactNode;
 };
 
-const TabsRoot = React.memo(function TabsRoot(props: TabsProps) {
-  return (
-    <RenderTreeNode type="tabs" id={props.id} active={props.active}>
-      {props.children}
-    </RenderTreeNode>
-  );
-});
+const TabsRoot = React.memo(
+  React.forwardRef<TabsHandle, TabsProps>(function TabsRoot(props, ref) {
+    const tabsId = React.useRef(
+      props.id ?? nextRenderTreeIdForType("tabs"),
+    ).current;
+    const navigation = useNavigation();
+
+    React.useImperativeHandle(
+      ref,
+      () => ({
+        setActive(index: number) {
+          navigation.tab(index, { tabs: tabsId });
+        },
+      }),
+      [tabsId, navigation],
+    );
+
+    return (
+      <RenderTreeNode type="tabs" id={tabsId} active={props.active}>
+        {props.children}
+      </RenderTreeNode>
+    );
+  }),
+);
 
 const TabBar = React.memo(function TabBar(props: {
   screens: TabScreenOptions[];
@@ -121,17 +143,6 @@ export const Tabs = React.memo(
   React.forwardRef<TabsHandle, Omit<TabsProps, "children">>(
     function Tabs(props, ref) {
       const position = props.tabbarPosition ?? "bottom";
-      const navigation = useNavigation();
-      const node = useRenderNode();
-      const tabsId = props.id ?? node?.id ?? null;
-
-      React.useImperativeHandle(ref, () => ({
-        setActiveIndex(index: number) {
-          if (tabsId) {
-            navigation.setActiveTab(index, { tabsId });
-          }
-        },
-      }), [tabsId, navigation]);
 
       const tabbar = React.useMemo(
         () => (
@@ -145,7 +156,7 @@ export const Tabs = React.memo(
       );
 
       return (
-        <TabsRoot {...props}>
+        <TabsRoot ref={ref} {...props}>
           {position === "top" && tabbar}
           <View style={styles.slotContainer}>
             <TabsSlot screens={props.screens} />