react-native-anchored-menu 0.0.17 → 0.0.18

package/README.md

@@ -127,13 +127,36 @@ open({
 
 ---
 
+## 📱 Example App
+
+Want to see the library in action? Check out the comprehensive example app that demonstrates all features:
+
+```bash
+cd example
+npm install
+npm start      # Opens Expo Developer Tools
+# Then press 'i' for iOS or 'a' for Android
+```
+
+The example includes:
+
+- **Basic Usage** - Simple menus and fundamentals
+- **FlatList Integration** - Context menus in scrolling lists  
+- **Modal Usage** - Menus inside React Native modals
+- **Placement Options** - All positioning and alignment combinations
+- **Custom Styling** - Themes, animations, and advanced patterns
+
+Each example includes live code samples and explanations to help you understand the implementation.
+
+---
+
 ## 🪟 Using inside React Native `<Modal>`
 
 React Native `<Modal>` is rendered in a separate native layer. To ensure the menu appears **above** the modal content, mount a provider/layer **inside** the modal tree.
 
 **Sheets & overlays**:
 
-- **Native-layer overlays** (RN `<Modal>`, `react-native-navigation` modals/overlays, etc.): mount `AnchoredMenuLayer` inside that overlay’s content tree.
+- **Native-layer overlays** (RN `<Modal>`, `react-native-navigation` modals/overlays, etc.): mount `AnchoredMenuProvider` inside that overlay’s content tree.
 - **JS-only sheets** (rendered as normal React views in the same tree): you can keep a single provider at the app root.
 
 Recommended:
@@ -142,7 +165,7 @@ Recommended:
 import React, { useState } from "react";
 import { Modal, Pressable, Text, View } from "react-native";
 import {
-  AnchoredMenuLayer,
+  AnchoredMenuProvider,
   MenuAnchor,
   useAnchoredMenuActions,
 } from "react-native-anchored-menu";
@@ -158,8 +181,9 @@ export function ExampleModalMenu() {
       </Pressable>
 
       <Modal transparent visible={visible} onRequestClose={() => setVisible(false)}>
-        <AnchoredMenuLayer>
-          <View style={{ flex: 1, justifyContent: "center", alignItems: "center" }}>
+        <View style={{ flex: 1, position: "relative" }}>
+          <AnchoredMenuProvider>
+            <View style={{ flex: 1, justifyContent: "center", alignItems: "center" }}>
             <MenuAnchor id="modal-menu">
       <Pressable
                 onPress={() =>
@@ -183,8 +207,9 @@ export function ExampleModalMenu() {
             <Pressable onPress={() => setVisible(false)}>
               <Text>Close modal</Text>
             </Pressable>
-          </View>
-        </AnchoredMenuLayer>
+            </View>
+          </AnchoredMenuProvider>
+        </View>
       </Modal>
     </>
   );
@@ -198,7 +223,6 @@ export function ExampleModalMenu() {
 The following exports are considered **stable public API**:
 
 - `AnchoredMenuProvider` (with props: `defaultHost`, `autoHost`, `autoCloseOnBackground`, `host`)
-- `AnchoredMenuLayer`
 - `MenuAnchor`
 - `useAnchoredMenuActions`
 - `useAnchoredMenuState`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-anchored-menu",
-  "version": "0.0.17",
+  "version": "0.0.18",
   "description": "Headless anchored context menu / popover for React Native (iOS/Android) with stable measurement (default view host).",
   "repository": {
     "type": "git",
@@ -15,7 +15,6 @@
   "types": "src/index.ts",
   "files": [
     "src",
-    "assets",
     "docs",
     "README.md",
     "LICENSE"
@@ -41,5 +40,5 @@
     "react": "*",
     "react-native": "*"
   },
-  "readme": "# react-native-anchored-menu\n\nA **headless, anchor-based menu / popover system for React Native** designed to work reliably across:\n\n- iOS & Android\n- FlatList / SectionList\n- Complex layouts\n- New Architecture (Fabric)\n- Modal & non-modal contexts\n\nThis library focuses on **correct measurement and positioning**, not UI.  \nYou fully control how the menu looks and behaves.\n\n---\n\n## 🎬 Demo\n\n| View host (normal screens) | View host inside native `<Modal>` |\n| --- | --- |\n| ![View host demo](https://raw.githubusercontent.com/mahmoudelfekygithub/react-native-anchored-menu/main/assets/demo1.gif) | ![Modal demo](https://raw.githubusercontent.com/mahmoudelfekygithub/react-native-anchored-menu/main/assets/demo2.gif) |\n\n---\n\n## ✨ Why this library exists\n\nMost React Native menu / popover libraries break in at least one of these cases:\n\n- Wrong position on Android\n- Unreliable measurement inside FlatList\n- Broken behavior with Fabric\n- Rendering behind or inside unexpected layers\n- Forced UI and styling\n\n**react-native-anchored-menu** solves these by:\n\n- Using **stable anchor measurement**\n- Separating **state (Provider)** from **rendering (Hosts)**\n- Supporting multiple rendering strategies (View / Modal)\n- Staying **100% headless**\n\n---\n\n## ✅ Features\n\n- 📍 Anchor menus to any component\n- 📐 Accurate positioning (`auto`, `top`, `bottom`)\n- 🧠 FlatList-safe measurement\n- 🪟 Works inside and outside native `<Modal>`\n- 🧩 Fully headless render API\n- 🧹 Tap outside to dismiss\n- 🔄 Auto-close on scroll (optional)\n- 🌍 RTL-aware positioning\n- 🧱 Multiple host strategies\n\n---\n\n## 📦 Installation\n\n```bash\nnpm install react-native-anchored-menu\n# or\nyarn add react-native-anchored-menu\n```\n\nNo native linking required.\n\n---\n\n## 🚀 Basic Usage\n\n### 1️⃣ Wrap your app\n\n```tsx\nimport { AnchoredMenuProvider } from \"react-native-anchored-menu\";\n\nexport default function Root() {\n  return (\n    <AnchoredMenuProvider>\n      <App />\n    </AnchoredMenuProvider>\n  );\n}\n```\n\n> ⚠️ You **do NOT need** to manually mount any host by default.  \n> Hosts are automatically mounted internally.\n\n---\n\n### 2️⃣ Add an anchor\n\n```tsx\nimport { MenuAnchor } from \"react-native-anchored-menu\";\n\n<MenuAnchor id=\"profile-menu\">\n  <Pressable>\n    <Text>Open menu</Text>\n  </Pressable>\n</MenuAnchor>\n```\n\n---\n\n### 3️⃣ Open the menu\n\n```tsx\nimport { useAnchoredMenuActions } from \"react-native-anchored-menu\";\n\nconst { open, close } = useAnchoredMenuActions();\n\nopen({\n  id: \"profile-menu\",\n  render: ({ close }) => (\n    <View style={{ backgroundColor: \"#111\", padding: 12, borderRadius: 8 }}>\n      <Pressable onPress={close}>\n        <Text style={{ color: \"#fff\" }}>Logout</Text>\n      </Pressable>\n    </View>\n  ),\n});\n```\n\n---\n\n## 🪟 Using inside React Native `<Modal>`\n\nReact Native `<Modal>` is rendered in a separate native layer. To ensure the menu appears **above** the modal content, mount a provider/layer **inside** the modal tree.\n\n**Sheets & overlays**:\n\n- **Native-layer overlays** (RN `<Modal>`, `react-native-navigation` modals/overlays, etc.): mount `AnchoredMenuLayer` inside that overlay’s content tree.\n- **JS-only sheets** (rendered as normal React views in the same tree): you can keep a single provider at the app root.\n\nRecommended:\n\n```tsx\nimport React, { useState } from \"react\";\nimport { Modal, Pressable, Text, View } from \"react-native\";\nimport {\n  AnchoredMenuLayer,\n  MenuAnchor,\n  useAnchoredMenuActions,\n} from \"react-native-anchored-menu\";\n\nexport function ExampleModalMenu() {\n  const [visible, setVisible] = useState(false);\n  const { open } = useAnchoredMenuActions();\n\n  return (\n    <>\n      <Pressable onPress={() => setVisible(true)}>\n        <Text>Open modal</Text>\n      </Pressable>\n\n      <Modal transparent visible={visible} onRequestClose={() => setVisible(false)}>\n        <AnchoredMenuLayer>\n          <View style={{ flex: 1, justifyContent: \"center\", alignItems: \"center\" }}>\n            <MenuAnchor id=\"modal-menu\">\n              <Pressable\n                onPress={() =>\n                  open({\n                    id: \"modal-menu\",\n                    host: \"view\",\n                    render: ({ close }) => (\n                      <View style={{ backgroundColor: \"#111\", padding: 12, borderRadius: 8 }}>\n                        <Pressable onPress={close}>\n                          <Text style={{ color: \"#fff\" }}>Action</Text>\n                        </Pressable>\n                      </View>\n                    ),\n                  })\n                }\n              >\n                <Text>Open menu</Text>\n              </Pressable>\n            </MenuAnchor>\n\n            <Pressable onPress={() => setVisible(false)}>\n              <Text>Close modal</Text>\n            </Pressable>\n          </View>\n        </AnchoredMenuLayer>\n      </Modal>\n    </>\n  );\n}\n```\n\n## 🧠 API\n\n### `useAnchoredMenuActions()`\n\n```ts\nconst { open, close } = useAnchoredMenuActions();\n```\n\n### `useAnchoredMenuState(selector?)`\n\n```ts\nconst isOpen = useAnchoredMenuState((s) => s.isOpen);\n```\n\n**Recommended (performance)**: prefer split hooks in large trees to reduce re-renders:\n\n```ts\nconst isOpen = useAnchoredMenuState((s) => s.isOpen);\nconst { open } = useAnchoredMenuActions();\n```\n\n> `useAnchoredMenu()` is still available for backwards compatibility, but the split hooks are recommended\n> to reduce re-renders in large trees.\n\n---\n\n### `open(options)`\n\n```ts\nopen({\n  id: string;\n\n  placement?: \"auto\" | \"top\" | \"bottom\";\n  align?: \"start\" | \"center\" | \"end\";\n  offset?: number;\n  margin?: number;\n  rtlAware?: boolean;\n\n  render?: ({ close, anchor }) => ReactNode;\n  content?: ReactNode;\n\n  host?: \"view\" | \"modal\";\n\n  animationType?: \"fade\" | \"none\";\n  statusBarTranslucent?: boolean;\n\n  /**\n   * Measurement strategy.\n   * - \"stable\" (default): waits for interactions and retries for correctness (best for FlatList/Android)\n   * - \"fast\": one-frame measure (lowest latency, less reliable on complex layouts)\n   */\n  measurement?: \"stable\" | \"fast\";\n\n  /**\n   * Only used when `measurement=\"stable\"` (default: 8).\n   */\n  measurementTries?: number;\n});\n```\n\n---\n\n## 🧭 Placement Behavior\n\n- `auto` → below if space allows, otherwise above\n- `top` → prefer above, fallback below\n- `bottom` → prefer below, fallback above\n\n---\n\n## 🧱 Host System\n\n- Default host: **view**\n- Hosts are auto-mounted\n- `modal` host is disabled on Fabric and falls back to `view`\n\n---\n\n## 📄 License\n\nMIT © Mahmoud Elfeky\n"
+  "readme": "# react-native-anchored-menu\n\nA **headless, anchor-based menu / popover system for React Native** designed to work reliably across:\n\n- iOS & Android\n- FlatList / SectionList\n- Complex layouts\n- New Architecture (Fabric)\n- Modal & non-modal contexts\n\nThis library focuses on **correct measurement and positioning**, not UI.  \nYou fully control how the menu looks and behaves.\n\n---\n\n## 🎬 Demo\n\n| View host (normal screens) | View host inside native `<Modal>` |\n| --- | --- |\n| ![View host demo](https://raw.githubusercontent.com/mahmoudelfekygithub/react-native-anchored-menu/main/assets/demo1.gif) | ![Modal demo](https://raw.githubusercontent.com/mahmoudelfekygithub/react-native-anchored-menu/main/assets/demo2.gif) |\n\n---\n\n## ✨ Why this library exists\n\nMost React Native menu / popover libraries break in at least one of these cases:\n\n- Wrong position on Android\n- Unreliable measurement inside FlatList\n- Broken behavior with Fabric\n- Rendering behind or inside unexpected layers\n- Forced UI and styling\n\n**react-native-anchored-menu** solves these by:\n\n- Using **stable anchor measurement**\n- Separating **state (Provider)** from **rendering (Hosts)**\n- Supporting multiple rendering strategies (View / Modal)\n- Staying **100% headless**\n\n---\n\n## ✅ Features\n\n- 📍 Anchor menus to any component\n- 📐 Accurate positioning (`auto`, `top`, `bottom`)\n- 🧠 FlatList-safe measurement\n- 🪟 Works inside and outside native `<Modal>`\n- 🧩 Fully headless render API\n- 🧹 Tap outside to dismiss\n- 🔄 Auto-close on scroll (optional)\n- 🌍 RTL-aware positioning\n- 🧱 Multiple host strategies\n\n---\n\n## 📦 Installation\n\n```bash\nnpm install react-native-anchored-menu\n# or\nyarn add react-native-anchored-menu\n```\n\nNo native linking required.\n\n---\n\n## 🚀 Basic Usage\n\n### 1️⃣ Wrap your app\n\n```tsx\nimport { AnchoredMenuProvider } from \"react-native-anchored-menu\";\n\nexport default function Root() {\n  return (\n    <AnchoredMenuProvider>\n      <App />\n    </AnchoredMenuProvider>\n  );\n}\n```\n\n> ⚠️ You **do NOT need** to manually mount any host by default.  \n> Hosts are automatically mounted internally.\n\n---\n\n### 2️⃣ Add an anchor\n\n```tsx\nimport { MenuAnchor } from \"react-native-anchored-menu\";\n\n<MenuAnchor id=\"profile-menu\">\n  <Pressable>\n    <Text>Open menu</Text>\n  </Pressable>\n</MenuAnchor>\n```\n\n---\n\n### 3️⃣ Open the menu\n\n```tsx\nimport { useAnchoredMenuActions } from \"react-native-anchored-menu\";\n\nconst { open, close } = useAnchoredMenuActions();\n\nopen({\n  id: \"profile-menu\",\n  render: ({ close }) => (\n    <View style={{ backgroundColor: \"#111\", padding: 12, borderRadius: 8 }}>\n      <Pressable onPress={close}>\n        <Text style={{ color: \"#fff\" }}>Logout</Text>\n      </Pressable>\n    </View>\n  ),\n});\n```\n\n---\n\n## 🪟 Using inside React Native `<Modal>`\n\nReact Native `<Modal>` is rendered in a separate native layer. To ensure the menu appears **above** the modal content, mount a provider/layer **inside** the modal tree.\n\n**Sheets & overlays**:\n\n- **Native-layer overlays** (RN `<Modal>`, `react-native-navigation` modals/overlays, etc.): mount `AnchoredMenuProvider` inside that overlay’s content tree.\n- **JS-only sheets** (rendered as normal React views in the same tree): you can keep a single provider at the app root.\n\nRecommended:\n\n```tsx\nimport React, { useState } from \"react\";\nimport { Modal, Pressable, Text, View } from \"react-native\";\nimport {\n  AnchoredMenuProvider,\n  MenuAnchor,\n  useAnchoredMenuActions,\n} from \"react-native-anchored-menu\";\n\nexport function ExampleModalMenu() {\n  const [visible, setVisible] = useState(false);\n  const { open } = useAnchoredMenuActions();\n\n  return (\n    <>\n      <Pressable onPress={() => setVisible(true)}>\n        <Text>Open modal</Text>\n      </Pressable>\n\n      <Modal transparent visible={visible} onRequestClose={() => setVisible(false)}>\n        <AnchoredMenuProvider>\n          <View style={{ flex: 1, justifyContent: \"center\", alignItems: \"center\" }}>\n            <MenuAnchor id=\"modal-menu\">\n              <Pressable\n                onPress={() =>\n                  open({\n                    id: \"modal-menu\",\n                    host: \"view\",\n                    render: ({ close }) => (\n                      <View style={{ backgroundColor: \"#111\", padding: 12, borderRadius: 8 }}>\n                        <Pressable onPress={close}>\n                          <Text style={{ color: \"#fff\" }}>Action</Text>\n                        </Pressable>\n                      </View>\n                    ),\n                  })\n                }\n              >\n                <Text>Open menu</Text>\n              </Pressable>\n            </MenuAnchor>\n\n            <Pressable onPress={() => setVisible(false)}>\n              <Text>Close modal</Text>\n            </Pressable>\n          </View>\n        </AnchoredMenuProvider>\n      </Modal>\n    </>\n  );\n}\n```\n\n## 🧠 API\n\n### `useAnchoredMenuActions()`\n\n```ts\nconst { open, close } = useAnchoredMenuActions();\n```\n\n### `useAnchoredMenuState(selector?)`\n\n```ts\nconst isOpen = useAnchoredMenuState((s) => s.isOpen);\n```\n\n**Recommended (performance)**: prefer split hooks in large trees to reduce re-renders:\n\n```ts\nconst isOpen = useAnchoredMenuState((s) => s.isOpen);\nconst { open } = useAnchoredMenuActions();\n```\n\n> `useAnchoredMenu()` is still available for backwards compatibility, but the split hooks are recommended\n> to reduce re-renders in large trees.\n\n---\n\n### `open(options)`\n\n```ts\nopen({\n  id: string;\n\n  placement?: \"auto\" | \"top\" | \"bottom\";\n  align?: \"start\" | \"center\" | \"end\";\n  offset?: number;\n  margin?: number;\n  rtlAware?: boolean;\n\n  render?: ({ close, anchor }) => ReactNode;\n  content?: ReactNode;\n\n  host?: \"view\" | \"modal\";\n\n  animationType?: \"fade\" | \"none\";\n  statusBarTranslucent?: boolean;\n\n  /**\n   * Measurement strategy.\n   * - \"stable\" (default): waits for interactions and retries for correctness (best for FlatList/Android)\n   * - \"fast\": one-frame measure (lowest latency, less reliable on complex layouts)\n   */\n  measurement?: \"stable\" | \"fast\";\n\n  /**\n   * Only used when `measurement=\"stable\"` (default: 8).\n   */\n  measurementTries?: number;\n});\n```\n\n---\n\n## 🧭 Placement Behavior\n\n- `auto` → below if space allows, otherwise above\n- `top` → prefer above, fallback below\n- `bottom` → prefer below, fallback above\n\n---\n\n## 🧱 Host System\n\n- Default host: **view**\n- Hosts are auto-mounted\n- `modal` host is disabled on Fabric and falls back to `view`\n\n---\n\n## 📄 License\n\nMIT © Mahmoud Elfeky\n"
 }

package/src/components/MenuAnchor.tsx

@@ -29,12 +29,12 @@ function extractMarginsFromChild(children: React.ReactNode): AnchorMargins {
   }
 }
 
-export function MenuAnchor({ id, children }: MenuAnchorProps) {
+export function MenuAnchor({ id, children, style }: MenuAnchorProps) {
   const actions = useContext(AnchoredMenuActionsContext);
   if (!actions) {
     throw new Error(
       "[react-native-anchored-menu] MenuAnchor must be used within an AnchoredMenuProvider. " +
-        "Make sure to wrap your component tree with <AnchoredMenuProvider> or <AnchoredMenuLayer>."
+        "Make sure to wrap your component tree with <AnchoredMenuProvider>."
     );
   }
 
@@ -54,7 +54,7 @@ export function MenuAnchor({ id, children }: MenuAnchorProps) {
 
   // collapsable={false} is important for Android measurement reliability
   return (
-    <View ref={ref} collapsable={false}>
+    <View ref={ref} collapsable={false} style={style}>
       {children}
     </View>
   );

package/src/core/provider.tsx

@@ -21,6 +21,31 @@ import type {
   OpenMenuOptions,
 } from "../types";
 
+/**
+ * Creates a new MenuStore instance with its own state and listeners.
+ * Each provider instance needs its own store to maintain independent state.
+ */
+function createMenuStore(defaultHost: HostType): MenuStore {
+  const listeners = new Set<() => void>();
+  let snapshot: MenuState = {
+    request: null,
+    activeHost: defaultHost,
+    isOpen: false,
+  };
+
+  return {
+    getSnapshot: () => snapshot,
+    subscribe: (listener: () => void) => {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    _setSnapshot: (next: MenuState) => {
+      snapshot = next;
+      listeners.forEach((l) => l());
+    },
+  };
+}
+
 /**
  * Provider config
  * - defaultHost: which host to use when `open()` doesn't specify one (default: "view")
@@ -38,30 +63,24 @@ export function AnchoredMenuProvider({
   const anchorsRef = useRef(new Map<string, any>()); // id -> ref
   const pendingOpenRafRef = useRef<number | null>(null);
   const defaultHostRef = useRef(defaultHost);
-  defaultHostRef.current = defaultHost;
+  defaultHostRef.current = defaultHost; //this is to update the defaultHostRef.current when the defaultHost prop changes
 
-  // Tiny external store so open/close doesn't re-render the whole provider subtree.
+  // External store pattern: state lives outside React to prevent re-renders.
+  // When menu opens/closes, only components subscribed via useSyncExternalStore re-render,
+  // not the entire provider subtree. Each provider instance maintains its own independent store.
   const storeRef = useRef<MenuStore | null>(null);
   if (!storeRef.current) {
-    const listeners = new Set<() => void>();
-    let snapshot: MenuState = {
-      request: null,
-      activeHost: defaultHost,
-      isOpen: false,
-    };
-    storeRef.current = {
-      getSnapshot: () => snapshot,
-      subscribe: (listener: () => void) => {
-        listeners.add(listener);
-        return () => listeners.delete(listener);
-      },
-      _setSnapshot: (next: MenuState) => {
-        snapshot = next;
-        listeners.forEach((l) => l());
-      },
-    };
+    storeRef.current = createMenuStore(defaultHost);
   }
 
+  // Helper to cancel any pending open operation (used in both open and close)
+  const cancelPendingOpen = useCallback(() => {
+    if (pendingOpenRafRef.current) {
+      cancelAnimationFrame(pendingOpenRafRef.current);
+      pendingOpenRafRef.current = null;
+    }
+  }, []);
+
   const setRequest = useCallback((payload: MenuRequest | null) => {
     const defaultH = defaultHostRef.current ?? "view";
     let nextActiveHost: HostType = (payload?.host ?? defaultH) as HostType;
@@ -72,8 +91,8 @@ export function AnchoredMenuProvider({
         // eslint-disable-next-line no-console
         console.warn(
           `[react-native-anchored-menu] Unknown host="${String(
-            nextActiveHost
-          )}". Falling back to host="view".`
+            nextActiveHost,
+          )}". Falling back to host="view".`,
         );
       }
       nextActiveHost = "view";
@@ -89,7 +108,7 @@ export function AnchoredMenuProvider({
       if (__DEV__) {
         // eslint-disable-next-line no-console
         console.warn(
-          '[react-native-anchored-menu] host="modal" is disabled when Fabric is enabled; falling back to host="view".'
+          '[react-native-anchored-menu] host="modal" is disabled when Fabric is enabled; falling back to host="view".',
         );
       }
     }
@@ -126,13 +145,16 @@ export function AnchoredMenuProvider({
   useEffect(() => {
     if (!autoCloseOnBackground) return;
 
-    const subscription = AppState.addEventListener("change", (nextAppState: string) => {
-      if (nextAppState === "background" || nextAppState === "inactive") {
-        if (storeRef.current?.getSnapshot().isOpen) {
-          setRequest(null);
+    const subscription = AppState.addEventListener(
+      "change",
+      (nextAppState: string) => {
+        if (nextAppState === "background" || nextAppState === "inactive") {
+          if (storeRef.current?.getSnapshot().isOpen) {
+            setRequest(null);
+          }
         }
-      }
-    });
+      },
+    );
 
     return () => {
       subscription.remove();
@@ -140,17 +162,20 @@ export function AnchoredMenuProvider({
   }, [setRequest, autoCloseOnBackground]);
 
   const open = useCallback((payload: OpenMenuOptions) => {
-    // Defer by default to avoid "open tap" being interpreted as an outside press
-    // when a host mounts a Pressable backdrop during the active gesture.
-    if (pendingOpenRafRef.current) {
-      cancelAnimationFrame(pendingOpenRafRef.current);
-      pendingOpenRafRef.current = null;
-    }
+    // Defer opening by default to avoid the tap that opens the menu being interpreted
+    // as an outside press when the host mounts a Pressable backdrop during the same gesture.
+    // Cancel any pending open operation if a new open() call happens before it executes.
+    cancelPendingOpen();
 
     const commit = () => {
+      // Handle close case: if payload is null/undefined, close the menu by clearing the request.
+      // This allows open(null) to be used as an alternative to close().
       if (!payload) return setRequest(null);
 
-      // If the anchor isn't registered in this provider, route to a nested provider that has it.
+      // Cross-provider routing: If the anchor isn't registered in this provider, search for it
+      // in nested providers (e.g., a provider inside a Modal). This allows menus to work across
+      // provider boundaries, which is essential when anchors exist in separate React trees
+      // (like React Native Modals that render in a different native layer).
       const anchorId = payload.id;
       const hasLocalAnchor = anchorsRef.current?.has?.(anchorId);
 
@@ -160,7 +185,7 @@ export function AnchoredMenuProvider({
           // eslint-disable-next-line no-console
           console.warn(
             `[react-native-anchored-menu] Multiple MenuAnchors registered with id="${anchorId}". ` +
-              "Using the most recently mounted provider. Consider unique ids per screen/modal."
+              "Using the most recently mounted provider. Consider unique ids per screen/modal.",
           );
         }
         const target = findProviderForAnchorId(anchorId);
@@ -172,18 +197,24 @@ export function AnchoredMenuProvider({
           // eslint-disable-next-line no-console
           console.warn(
             `[react-native-anchored-menu] Anchor with id="${anchorId}" not found in any provider. ` +
-              "Make sure the MenuAnchor is mounted and the id matches."
+              "Make sure the MenuAnchor is mounted and the id matches.",
           );
         }
         return; // Don't open menu if anchor doesn't exist
       }
 
+      // Anchor is registered in this provider (hasLocalAnchor === true).
+      // Set the request to open the menu in this provider's context.
       setRequest(payload as MenuRequest);
     };
 
+    // Handle immediate case: if payload.immediate is true, commit the request immediately.
+    // Otherwise, defer the opening by using requestAnimationFrame to avoid conflicts with
+    // the tap that opens the menu.
     if (payload?.immediate) commit();
     else {
       pendingOpenRafRef.current = requestAnimationFrame(() => {
+        // Clear the pending reference after the frame executes to avoid stale references.
         pendingOpenRafRef.current = null;
         commit();
       });
@@ -191,12 +222,10 @@ export function AnchoredMenuProvider({
   }, []);
 
   const close = useCallback(() => {
-    if (pendingOpenRafRef.current) {
-      cancelAnimationFrame(pendingOpenRafRef.current);
-      pendingOpenRafRef.current = null;
-    }
+    // Cancel any pending open operation to prevent opening the menu again.
+    cancelPendingOpen();
     setRequest(null);
-  }, []);
+  }, [cancelPendingOpen]);
 
   const actionsValue = useMemo(
     () => ({
@@ -208,7 +237,7 @@ export function AnchoredMenuProvider({
       // provider config
       defaultHost,
     }),
-    [registerAnchor, unregisterAnchor, open, close, defaultHost]
+    [registerAnchor, unregisterAnchor, open, close, defaultHost],
   );
 
   const stateStore = storeRef.current;

package/src/hooks/useAnchoredMenu.ts

@@ -11,7 +11,7 @@ export function useAnchoredMenu() {
   if (!actions || !state) {
     throw new Error(
       "[react-native-anchored-menu] useAnchoredMenu must be used within an AnchoredMenuProvider. " +
-        "Make sure to wrap your component tree with <AnchoredMenuProvider> or <AnchoredMenuLayer>."
+        "Make sure to wrap your component tree with <AnchoredMenuProvider>."
     );
   }
 

package/src/hooks/useAnchoredMenuActions.ts

@@ -3,8 +3,14 @@ import { AnchoredMenuActionsContext } from "../core/context";
 import type { OpenMenuOptions } from "../types";
 
 /**
- * Stable actions-only hook.
- * Components using this won't re-render when menu state changes.
+ * Actions-only hook that provides open/close functions without subscribing to menu state.
+ * 
+ * Use this hook when you only need to trigger menu actions and don't need to know if the menu
+ * is currently open. Components using this hook will NOT re-render when menu state changes,
+ * making it ideal for performance-sensitive components like buttons or list items.
+ * 
+ * If you need to track menu state (e.g., show loading indicator when menu is open), use
+ * `useAnchoredMenu()` or combine `useAnchoredMenuActions()` with `useAnchoredMenuState()`.
  */
 export function useAnchoredMenuActions(): {
   open: (options: OpenMenuOptions) => void;
@@ -14,7 +20,7 @@ export function useAnchoredMenuActions(): {
   if (!actions) {
     throw new Error(
       "[react-native-anchored-menu] useAnchoredMenuActions must be used within an AnchoredMenuProvider. " +
-        "Make sure to wrap your component tree with <AnchoredMenuProvider> or <AnchoredMenuLayer>."
+        "Make sure to wrap your component tree with <AnchoredMenuProvider>."
     );
   }
 

package/src/hooks/useAnchoredMenuState.ts

@@ -15,7 +15,10 @@ try {
   }
 } catch {
   // Fallback for older React versions - use useState + useEffect
-  useSyncExternalStore = (subscribe: (onStoreChange: () => void) => () => void, getSnapshot: () => any) => {
+  useSyncExternalStore = (
+    subscribe: (onStoreChange: () => void) => () => void,
+    getSnapshot: () => any,
+  ) => {
     const [state, setState] = useState(() => getSnapshot());
     useEffect(() => {
       const unsubscribe = subscribe(() => {
@@ -34,13 +37,15 @@ try {
  *   const isOpen = useAnchoredMenuState(s => s.isOpen)
  */
 export function useAnchoredMenuState<T = MenuState>(
-  selector: (state: MenuState) => T = ((s: MenuState) => s) as (state: MenuState) => T
+  selector: (state: MenuState) => T = ((s: MenuState) => s) as (
+    state: MenuState,
+  ) => T,
 ): T {
   const store = useContext(AnchoredMenuStateContext);
   if (!store) {
     throw new Error(
       "[react-native-anchored-menu] useAnchoredMenuState must be used within an AnchoredMenuProvider. " +
-        "Make sure to wrap your component tree with <AnchoredMenuProvider> or <AnchoredMenuLayer>."
+        "Make sure to wrap your component tree with <AnchoredMenuProvider>.",
     );
   }
 
@@ -48,7 +53,6 @@ export function useAnchoredMenuState<T = MenuState>(
   return useSyncExternalStore(
     store.subscribe,
     getSelectedSnapshot,
-    getSelectedSnapshot
+    getSelectedSnapshot,
   );
 }
-

package/src/index.ts

@@ -1,7 +1,6 @@
 // Public, stable API
 export { AnchoredMenuProvider } from "./core/provider";
 export { MenuAnchor } from "./components/MenuAnchor";
-export { AnchoredMenuLayer } from "./components/AnchoredMenuLayer";
 export { useAnchoredMenu } from "./hooks/useAnchoredMenu";
 export { useAnchoredMenuActions } from "./hooks/useAnchoredMenuActions";
 export { useAnchoredMenuState } from "./hooks/useAnchoredMenuState";
@@ -28,7 +27,6 @@ export type {
   MenuState,
   AnchoredMenuProviderProps,
   MenuAnchorProps,
-  AnchoredMenuLayerProps,
   MenuPosition,
 } from "./types";
 export type { ComputeMenuPositionOptions } from "./utils/position";

package/src/types.ts

@@ -95,10 +95,9 @@ export interface OpenMenuOptions {
 
 /**
  * Menu request (internal state)
+ * Extends OpenMenuOptions - represents a validated menu request after processing.
  */
-export interface MenuRequest extends OpenMenuOptions {
-  id: string;
-}
+export interface MenuRequest extends OpenMenuOptions {}
 
 /**
  * Menu state snapshot
@@ -163,16 +162,11 @@ export interface AnchoredMenuProviderProps {
 export interface MenuAnchorProps {
   id: string;
   children: ReactNode;
-}
-
-/**
- * AnchoredMenuLayer props
- */
-export interface AnchoredMenuLayerProps extends Omit<AnchoredMenuProviderProps, "children"> {
-  children: ReactNode;
+  /** Optional style for the anchor wrapper View */
   style?: ViewStyle;
 }
 
+
 /**
  * Position calculation result
  */

package/src/components/AnchoredMenuLayer.tsx

@@ -1,26 +0,0 @@
-import React from "react";
-import { View } from "react-native";
-import { AnchoredMenuProvider } from "../core/provider";
-import type { AnchoredMenuLayerProps } from "../types";
-
-/**
- * AnchoredMenuLayer
- *
- * A convenience wrapper that ensures the "view" host has a stable layout box to fill.
- * Use it at app root and inside RN <Modal> (wrap the full-screen modal container).
- */
-export function AnchoredMenuLayer({
-  children,
-  style,
-  defaultHost = "view",
-  ...providerProps
-}: AnchoredMenuLayerProps) {
-  return (
-    <View style={[{ flex: 1, position: "relative" }, style]}>
-      <AnchoredMenuProvider defaultHost={defaultHost} {...providerProps}>
-        {children}
-      </AnchoredMenuProvider>
-    </View>
-  );
-}
-