react-native-anchored-menu 0.0.1

package/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2025 Mahmoud Elfeky
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+

package/README.md

@@ -0,0 +1,207 @@
+# react-native-anchored-menu
+
+A **headless, anchor-based menu / popover system for React Native** designed to work reliably across:
+
+- iOS & Android
+- FlatList / SectionList
+- Complex layouts
+- New Architecture (Fabric)
+- Modal & non-modal contexts
+
+This library focuses on **correct measurement and positioning**, not UI.  
+You fully control how the menu looks and behaves.
+
+---
+
+## 🎬 Demo
+
+<table>
+  <tr>
+    <td>
+      <strong>View host (inside normal screens)</strong><br />
+      <img src="assets/demo1.gif" width="320" />
+    </td>
+    <td>
+      <strong>View host inside native <code>&lt;Modal&gt;</code> (and nested modals)</strong><br />
+      <img src="assets/demo2.gif" width="320" />
+    </td>
+  </tr>
+</table>
+
+---
+
+## ✨ Why this library exists
+
+Most React Native menu / popover libraries break in at least one of these cases:
+
+- Wrong position on Android
+- Unreliable measurement inside FlatList
+- Broken behavior with Fabric
+- Rendering behind or inside unexpected layers
+- Forced UI and styling
+
+**react-native-anchored-menu** solves these by:
+
+- Using **stable anchor measurement**
+- Separating **state (Provider)** from **rendering (Hosts)**
+- Supporting multiple rendering strategies (View / Modal)
+- Staying **100% headless**
+
+---
+
+## ✅ Features
+
+- 📍 Anchor menus to any component
+- 📐 Accurate positioning (`auto`, `top`, `bottom`)
+- 🧠 FlatList-safe measurement
+- 🪟 Works inside and outside native `<Modal>`
+- 🧩 Fully headless render API
+- 🧹 Tap outside to dismiss
+- 🔄 Auto-close on scroll (optional)
+- 🌍 RTL-aware positioning
+- 🧱 Multiple host strategies
+
+---
+
+## 📦 Installation
+
+```bash
+npm install react-native-anchored-menu
+# or
+yarn add react-native-anchored-menu
+```
+
+No native linking required.
+
+---
+
+## 🚀 Basic Usage
+
+### 1️⃣ Wrap your app
+
+```tsx
+import { AnchoredMenuProvider } from "react-native-anchored-menu";
+
+export default function Root() {
+  return (
+    <AnchoredMenuProvider>
+      <App />
+    </AnchoredMenuProvider>
+  );
+}
+```
+
+> ⚠️ You **do NOT need** to manually mount any host by default.  
+> Hosts are automatically mounted internally.
+
+---
+
+### 2️⃣ Add an anchor
+
+```tsx
+import { MenuAnchor } from "react-native-anchored-menu";
+
+<MenuAnchor id="profile-menu">
+  <Pressable>
+    <Text>Open menu</Text>
+  </Pressable>
+</MenuAnchor>
+```
+
+---
+
+### 3️⃣ Open the menu
+
+```tsx
+import { useAnchoredMenuActions } from "react-native-anchored-menu";
+
+const { open, close } = useAnchoredMenuActions();
+
+open({
+  id: "profile-menu",
+  render: ({ close }) => (
+    <View style={{ backgroundColor: "#111", padding: 12, borderRadius: 8 }}>
+      <Pressable onPress={close}>
+        <Text style={{ color: "#fff" }}>Logout</Text>
+      </Pressable>
+    </View>
+  ),
+});
+```
+
+---
+
+## 🧠 API
+
+### `useAnchoredMenuActions()`
+
+```ts
+const { open, close } = useAnchoredMenuActions();
+```
+
+### `useAnchoredMenuState(selector?)`
+
+```ts
+const isOpen = useAnchoredMenuState((s) => s.isOpen);
+```
+
+> `useAnchoredMenu()` is still available for backwards compatibility, but the split hooks are recommended
+> to reduce re-renders in large trees.
+
+---
+
+### `open(options)`
+
+```ts
+open({
+  id: string;
+
+  placement?: "auto" | "top" | "bottom";
+  align?: "start" | "center" | "end";
+  offset?: number;
+  margin?: number;
+  rtlAware?: boolean;
+
+  render?: ({ close, anchor }) => ReactNode;
+  content?: ReactNode;
+
+  host?: "view" | "modal";
+
+  animationType?: "fade" | "none";
+  statusBarTranslucent?: boolean;
+
+  /**
+   * Measurement strategy.
+   * - "stable" (default): waits for interactions and retries for correctness (best for FlatList/Android)
+   * - "fast": one-frame measure (lowest latency, less reliable on complex layouts)
+   */
+  measurement?: "stable" | "fast";
+
+  /**
+   * Only used when `measurement="stable"` (default: 8).
+   */
+  measurementTries?: number;
+});
+```
+
+---
+
+## 🧭 Placement Behavior
+
+- `auto` → below if space allows, otherwise above
+- `top` → prefer above, fallback below
+- `bottom` → prefer below, fallback above
+
+---
+
+## 🧱 Host System
+
+- Default host: **view**
+- Hosts are auto-mounted
+- `modal` host is disabled on Fabric and falls back to `view`
+
+---
+
+## 📄 License
+
+MIT © Mahmoud Elfeky

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "react-native-anchored-menu",
+  "version": "0.0.1",
+  "description": "Headless anchored menu/popover for React Native with stable measurement (view host by default).",
+  "main": "src/index.js",
+  "react-native": "src/index.js",
+  "files": [
+    "src",
+    "assets",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "react-native",
+    "context-menu",
+    "popover",
+    "menu",
+    "anchor"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "react": "*",
+    "react-native": "*"
+  }
+}

package/src/components/AnchoredMenuLayer.js

@@ -0,0 +1,26 @@
+import React from "react";
+import { View } from "react-native";
+import { AnchoredMenuProvider } from "../core/provider";
+
+/**
+ * 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
+}) {
+  return (
+    <View style={[{ flex: 1, position: "relative" }, style]}>
+      <AnchoredMenuProvider defaultHost={defaultHost} {...providerProps}>
+        {children}
+      </AnchoredMenuProvider>
+    </View>
+  );
+}
+
+

package/src/components/MenuAnchor.js

@@ -0,0 +1,55 @@
+import React, { useContext, useEffect, useRef } from "react";
+import { StyleSheet, View } from "react-native";
+import { AnchoredMenuActionsContext } from "../core/context";
+
+function extractMarginsFromChild(children) {
+  try {
+    const child = React.Children.only(children);
+    const flat = StyleSheet.flatten(child?.props?.style) || {};
+    const mv =
+      typeof flat.marginVertical === "number" ? flat.marginVertical : undefined;
+    const mh =
+      typeof flat.marginHorizontal === "number"
+        ? flat.marginHorizontal
+        : undefined;
+    const m = typeof flat.margin === "number" ? flat.margin : 0;
+
+    const top = (typeof flat.marginTop === "number" ? flat.marginTop : mv) ?? m;
+    const bottom =
+      (typeof flat.marginBottom === "number" ? flat.marginBottom : mv) ?? m;
+    const left =
+      (typeof flat.marginLeft === "number" ? flat.marginLeft : mh) ?? m;
+    const right =
+      (typeof flat.marginRight === "number" ? flat.marginRight : mh) ?? m;
+
+    return { top, bottom, left, right };
+  } catch {
+    return { top: 0, bottom: 0, left: 0, right: 0 };
+  }
+}
+
+export function MenuAnchor({ id, children }) {
+  const actions = useContext(AnchoredMenuActionsContext);
+  if (!actions) throw new Error("AnchoredMenuProvider is missing");
+
+  const ref = useRef(null);
+
+  useEffect(() => {
+    // Store child margins on the ref object so measurement can exclude margins.
+    // This avoids offset differences when the anchored child uses e.g. marginBottom.
+    ref.__anchoredMenuMargins = extractMarginsFromChild(children);
+
+    actions.registerAnchor(id, ref);
+
+    return () => {
+      actions.unregisterAnchor(id);
+    };
+  }, [actions, id, children]);
+
+  // collapsable={false} is important for Android measurement reliability
+  return (
+    <View ref={ref} collapsable={false}>
+      {children}
+    </View>
+  );
+}

package/src/core/context.js

@@ -0,0 +1,10 @@
+import React, { createContext } from "react";
+
+/**
+ * Split contexts to avoid re-rendering all anchors when `request` changes.
+ *
+ * - Actions context: stable references (open/close/register/unregister/anchors map)
+ * - State context: request + derived values that change during open/close
+ */
+export const AnchoredMenuActionsContext = createContext(null);
+export const AnchoredMenuStateContext = createContext(null);

package/src/core/provider.js

@@ -0,0 +1,192 @@
+import React, { useCallback, useEffect, useMemo, useRef } from "react";
+import { Platform } from "react-native";
+import {
+  AnchoredMenuActionsContext,
+  AnchoredMenuStateContext,
+} from "./context";
+import { ModalHost } from "../hosts/ModalHost";
+import { ViewHost } from "../hosts/ViewHost";
+import { isFabricEnabled } from "../utils/runtime";
+import {
+  findAllProvidersForAnchorId,
+  findProviderForAnchorId,
+  registerProvider,
+} from "./providerRegistry";
+
+/**
+ * Provider config
+ * - defaultHost: which host to use when `open()` doesn't specify one (default: "view")
+ * - autoHost: automatically mounts the host implementation (default: true)
+ *
+ * request shape (open payload)
+ * Modal/View host:
+ *  {
+ *    id,
+ *    host?: "modal" | "view",
+ *    placement?, offset?, margin?, align?, rtlAware?,
+ *    animationType?,
+ *    statusBarTranslucent?, // Android-only, for modal host
+ *    render?: fn,
+ *    content?: node
+ *  }
+ */
+export function AnchoredMenuProvider({
+  children,
+  // backwards compatible alias
+  host,
+  defaultHost = host ?? "view",
+  autoHost = true,
+}) {
+  const anchorsRef = useRef(new Map()); // id -> ref
+  const pendingOpenRafRef = useRef(null);
+  const defaultHostRef = useRef(defaultHost);
+  defaultHostRef.current = defaultHost;
+
+  // Tiny external store so open/close doesn't re-render the whole provider subtree.
+  const storeRef = useRef(null);
+  if (!storeRef.current) {
+    const listeners = new Set();
+    let snapshot = { request: null, activeHost: defaultHost, isOpen: false };
+    storeRef.current = {
+      getSnapshot: () => snapshot,
+      subscribe: (listener) => {
+        listeners.add(listener);
+        return () => listeners.delete(listener);
+      },
+      _setSnapshot: (next) => {
+        snapshot = next;
+        listeners.forEach((l) => l());
+      },
+    };
+  }
+
+  const setRequest = useCallback((payload) => {
+    const defaultH = defaultHostRef.current ?? "view";
+    let nextActiveHost = payload?.host ?? defaultH;
+
+    // Guard: unknown host -> view
+    if (nextActiveHost !== "view" && nextActiveHost !== "modal") {
+      if (__DEV__) {
+        // eslint-disable-next-line no-console
+        console.warn(
+          `[react-native-anchored-menu] Unknown host="${String(
+            nextActiveHost
+          )}". Falling back to host="view".`
+        );
+      }
+      nextActiveHost = "view";
+    }
+
+    // Defensive: ModalHost can trigger internal React/Fabric issues in some environments.
+    if (
+      nextActiveHost === "modal" &&
+      isFabricEnabled() &&
+      Platform.OS !== "web"
+    ) {
+      nextActiveHost = "view";
+      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".'
+        );
+      }
+    }
+
+    storeRef.current._setSnapshot({
+      request: payload ?? null,
+      activeHost: payload ? nextActiveHost : defaultH,
+      isOpen: !!payload,
+    });
+  }, []);
+
+  const registerAnchor = useCallback((id, ref) => {
+    anchorsRef.current.set(id, ref);
+  }, []);
+
+  const unregisterAnchor = useCallback((id) => {
+    anchorsRef.current.delete(id);
+  }, []);
+
+  // Register this provider globally so parents can route `open({ id })` to the correct layer.
+  useEffect(() => {
+    const entry = { anchors: anchorsRef.current, setRequest };
+    return registerProvider(entry);
+  }, []);
+
+  const open = useCallback((payload) => {
+    // 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;
+    }
+
+    const commit = () => {
+      if (!payload) return setRequest(null);
+
+      // If the anchor isn't registered in this provider, route to a nested provider that has it.
+      const anchorId = payload.id;
+      const hasLocalAnchor = anchorsRef.current?.has?.(anchorId);
+
+      if (!hasLocalAnchor) {
+        const matches = findAllProvidersForAnchorId(anchorId);
+        if (matches.length > 1) {
+          // 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."
+          );
+        }
+        const target = findProviderForAnchorId(anchorId);
+        if (target && target.setRequest) return target.setRequest(payload);
+      }
+
+      setRequest(payload);
+    };
+
+    if (payload?.immediate) commit();
+    else {
+      pendingOpenRafRef.current = requestAnimationFrame(() => {
+        pendingOpenRafRef.current = null;
+        commit();
+      });
+    }
+  }, []);
+
+  const close = useCallback(() => {
+    if (pendingOpenRafRef.current) {
+      cancelAnimationFrame(pendingOpenRafRef.current);
+      pendingOpenRafRef.current = null;
+    }
+    setRequest(null);
+  }, []);
+
+  const actionsValue = useMemo(
+    () => ({
+      anchors: anchorsRef.current,
+      registerAnchor,
+      unregisterAnchor,
+      open,
+      close,
+      // provider config
+      defaultHost,
+    }),
+    [registerAnchor, unregisterAnchor, open, close, defaultHost]
+  );
+
+  const stateStore = storeRef.current;
+
+  return (
+    <AnchoredMenuActionsContext.Provider value={actionsValue}>
+      <AnchoredMenuStateContext.Provider value={stateStore}>
+        {children}
+        {autoHost ? (
+          <>
+            <ModalHost />
+            <ViewHost />
+          </>
+        ) : null}
+      </AnchoredMenuStateContext.Provider>
+    </AnchoredMenuActionsContext.Provider>
+  );
+}

package/src/core/providerRegistry.js

@@ -0,0 +1,47 @@
+/**
+ * Minimal global provider registry.
+ *
+ * Purpose: allow `open({ id })` called from a parent provider to route to a nested provider
+ * that owns the requested anchor id (e.g. inside RN <Modal>).
+ *
+ * This avoids requiring consumers to call `useAnchoredMenu()` inside the nested subtree.
+ */
+
+const providers = []; // stack order by mount time
+
+export function registerProvider(entry) {
+  providers.push(entry);
+  return () => unregisterProvider(entry);
+}
+
+export function unregisterProvider(entry) {
+  const idx = providers.indexOf(entry);
+  if (idx >= 0) providers.splice(idx, 1);
+}
+
+export function findProviderForAnchorId(anchorId) {
+  if (!anchorId) return null;
+
+  // Prefer most recently mounted provider that has the anchor id.
+  for (let i = providers.length - 1; i >= 0; i--) {
+    const p = providers[i];
+    try {
+      if (p?.anchors?.has(anchorId)) return p;
+    } catch {}
+  }
+  return null;
+}
+
+export function findAllProvidersForAnchorId(anchorId) {
+  const matches = [];
+  if (!anchorId) return matches;
+  for (let i = 0; i < providers.length; i++) {
+    const p = providers[i];
+    try {
+      if (p?.anchors?.has(anchorId)) matches.push(p);
+    } catch {}
+  }
+  return matches;
+}
+
+

package/src/hooks/useAnchoredMenu.js

@@ -0,0 +1,20 @@
+import { useContext, useMemo } from "react";
+import {
+  AnchoredMenuActionsContext,
+  AnchoredMenuStateContext,
+} from "../core/context";
+
+export function useAnchoredMenu() {
+  const actions = useContext(AnchoredMenuActionsContext);
+  const state = useContext(AnchoredMenuStateContext);
+  if (!actions || !state) throw new Error("AnchoredMenuProvider is missing");
+
+  return useMemo(
+    () => ({
+      open: actions.open,
+      close: actions.close,
+      isOpen: state.isOpen,
+    }),
+    [actions.open, actions.close, state.isOpen]
+  );
+}

package/src/hooks/useAnchoredMenuActions.js

@@ -0,0 +1,19 @@
+import { useContext, useMemo } from "react";
+import { AnchoredMenuActionsContext } from "../core/context";
+
+/**
+ * Stable actions-only hook.
+ * Components using this won't re-render when menu state changes.
+ */
+export function useAnchoredMenuActions() {
+  const actions = useContext(AnchoredMenuActionsContext);
+  if (!actions) throw new Error("AnchoredMenuProvider is missing");
+
+  return useMemo(
+    () => ({
+      open: actions.open,
+      close: actions.close,
+    }),
+    [actions.open, actions.close]
+  );
+}

package/src/hooks/useAnchoredMenuState.js

@@ -0,0 +1,20 @@
+import { useContext, useSyncExternalStore } from "react";
+import { AnchoredMenuStateContext } from "../core/context";
+
+/**
+ * State selector hook.
+ *
+ * Usage:
+ *   const isOpen = useAnchoredMenuState(s => s.isOpen)
+ */
+export function useAnchoredMenuState(selector = (s) => s) {
+  const store = useContext(AnchoredMenuStateContext);
+  if (!store) throw new Error("AnchoredMenuProvider is missing");
+
+  const getSelectedSnapshot = () => selector(store.getSnapshot());
+  return useSyncExternalStore(
+    store.subscribe,
+    getSelectedSnapshot,
+    getSelectedSnapshot
+  );
+}

package/src/hosts/ModalHost.js

@@ -0,0 +1,183 @@
+import React, { useContext, useEffect, useMemo, useRef, useState } from "react";
+import { Modal, Platform, Pressable, View } from "react-native";
+import {
+  AnchoredMenuActionsContext,
+  AnchoredMenuStateContext,
+} from "../core/context";
+import { useAnchoredMenuState } from "../hooks/useAnchoredMenuState";
+import {
+  applyAnchorMargins,
+  measureInWindowFast,
+  measureInWindowStable,
+} from "../utils/measure";
+import { computeMenuPosition } from "../utils/position";
+import { isFabricEnabled } from "../utils/runtime";
+
+export function ModalHost() {
+  const actions = useContext(AnchoredMenuActionsContext);
+  const store = useContext(AnchoredMenuStateContext);
+  if (!actions || !store) throw new Error("AnchoredMenuProvider is missing");
+
+  const activeHost = useAnchoredMenuState((s) => s.activeHost);
+  if (activeHost !== "modal") return null;
+  if (isFabricEnabled() && Platform.OS !== "web") return null;
+
+  const req = useAnchoredMenuState((s) => s.request);
+  const visible = !!req;
+
+  const hostRef = useRef(null);
+  const [hostSize, setHostSize] = useState({ width: 0, height: 0 });
+
+  const [anchorWin, setAnchorWin] = useState(null);
+  const [hostWin, setHostWin] = useState(null);
+  const [menuSize, setMenuSize] = useState({ width: 0, height: 0 });
+  const measureCacheRef = useRef(new Map()); // id -> { t, anchorWin, hostWin }
+
+  useEffect(() => {
+    if (!req) {
+      setAnchorWin(null);
+      setHostWin(null);
+      setMenuSize({ width: 0, height: 0 });
+      return;
+    }
+    // reset on open / anchor change
+    setAnchorWin(null);
+    setHostWin(null);
+    setMenuSize({ width: 0, height: 0 });
+
+    // Warm start: if we recently measured this anchor, seed state so the menu can appear faster.
+    const cached = measureCacheRef.current.get(req.id);
+    if (cached && Date.now() - cached.t < 300) {
+      setAnchorWin(cached.anchorWin);
+      setHostWin(cached.hostWin);
+    }
+  }, [req?.id, req]);
+
+  // Measure after Modal is visible (hostRef exists only then)
+  useEffect(() => {
+    let cancelled = false;
+
+    async function run() {
+      if (!req) return;
+      await new Promise((r) => requestAnimationFrame(r));
+      await new Promise((r) => requestAnimationFrame(r));
+
+      const refObj = actions.anchors.get(req.id); // ref object
+      if (!refObj || !hostRef.current) return;
+
+      const strategy = req?.measurement ?? "stable"; // "stable" | "fast"
+      const tries =
+        typeof req?.measurementTries === "number" ? req.measurementTries : 8;
+      const measure =
+        strategy === "fast" ? measureInWindowFast : measureInWindowStable;
+
+      const [a, h] = await Promise.all([
+        measure(refObj, strategy === "stable" ? { tries } : undefined),
+        measure(hostRef, strategy === "stable" ? { tries } : undefined),
+      ]);
+
+      if (cancelled) return;
+      const nextAnchorWin = applyAnchorMargins(a, refObj);
+      setAnchorWin(nextAnchorWin);
+      setHostWin(h);
+      measureCacheRef.current.set(req.id, {
+        t: Date.now(),
+        anchorWin: nextAnchorWin,
+        hostWin: h,
+      });
+    }
+
+    run();
+    return () => {
+      cancelled = true;
+    };
+  }, [req?.id, req, actions.anchors]);
+
+  // window coords -> host coords (avoids status bar / inset mismatches)
+  const anchorInHost = useMemo(() => {
+    if (!anchorWin || !hostWin) return null;
+    return {
+      ...anchorWin,
+      pageX: anchorWin.pageX - hostWin.pageX,
+      pageY: anchorWin.pageY - hostWin.pageY,
+    };
+  }, [anchorWin, hostWin]);
+
+  const position = useMemo(() => {
+    if (!req || !anchorInHost) return null;
+    const viewport =
+      hostSize.width && hostSize.height
+        ? { width: hostSize.width, height: hostSize.height }
+        : undefined;
+    return computeMenuPosition({
+      anchor: anchorInHost,
+      menuSize,
+      viewport,
+      placement: req.placement ?? "auto",
+      offset: req.offset ?? 8,
+      margin: req.margin ?? 8,
+      align: req.align ?? "start",
+      rtlAware: req.rtlAware ?? true,
+    });
+  }, [req, anchorInHost, menuSize, hostSize]);
+
+  const needsInitialMeasure = menuSize.width === 0 || menuSize.height === 0;
+
+  const statusBarTranslucent =
+    req?.statusBarTranslucent ?? (Platform.OS === "android" ? false : true);
+
+  if (!visible) return null;
+
+  return (
+    <Modal
+      visible={visible}
+      transparent
+      animationType={req.animationType ?? "fade"}
+      statusBarTranslucent={statusBarTranslucent}
+      onRequestClose={actions.close}
+    >
+      <View
+        ref={hostRef}
+        collapsable={false}
+        style={{ flex: 1 }}
+        onLayout={(e) => {
+          const { width, height } = e.nativeEvent.layout;
+          if (width !== hostSize.width || height !== hostSize.height) {
+            setHostSize({ width, height });
+          }
+        }}
+      >
+        {/* Tap outside to dismiss */}
+        <Pressable style={{ flex: 1 }} onPress={actions.close}>
+          {visible && !!anchorInHost && !!position ? (
+            <View
+              style={{
+                position: "absolute",
+                // Keep in-place so layout runs on iOS; hide visually until measured to avoid flicker.
+                top: position.top,
+                left: position.left,
+                opacity: needsInitialMeasure ? 0 : 1,
+              }}
+              pointerEvents={needsInitialMeasure ? "none" : "auto"}
+              onStartShouldSetResponder={() => true}
+              onLayout={(e) => {
+                const { width, height } = e.nativeEvent.layout;
+                if (width !== menuSize.width || height !== menuSize.height) {
+                  setMenuSize({ width, height });
+                }
+              }}
+            >
+              {typeof req.render === "function"
+                ? req.render({
+                    close: actions.close,
+                    anchor: anchorWin,
+                    anchorInHost,
+                  })
+                : req.content}
+            </View>
+          ) : null}
+        </Pressable>
+      </View>
+    </Modal>
+  );
+}

package/src/hosts/ViewHost.js

@@ -0,0 +1,187 @@
+import React, { useContext, useEffect, useMemo, useRef, useState } from "react";
+import { Pressable, View } from "react-native";
+import {
+  AnchoredMenuActionsContext,
+  AnchoredMenuStateContext,
+} from "../core/context";
+import { useAnchoredMenuState } from "../hooks/useAnchoredMenuState";
+import {
+  applyAnchorMargins,
+  measureInWindowFast,
+  measureInWindowStable,
+} from "../utils/measure";
+import { computeMenuPosition } from "../utils/position";
+
+/**
+ * ViewHost (non-native-modal host)
+ *
+ * Renders the menu as an absolutely-positioned overlay View, without presenting
+ * a native <Modal>. This is safe to use inside an existing RN <Modal>.
+ *
+ * NOTE: Must be mounted inside a parent that can cover the intended area
+ * (usually at the app root, or inside your RN Modal content).
+ */
+export function ViewHost() {
+  const actions = useContext(AnchoredMenuActionsContext);
+  const store = useContext(AnchoredMenuStateContext);
+  if (!actions || !store) throw new Error("AnchoredMenuProvider is missing");
+
+  const activeHost = useAnchoredMenuState((s) => s.activeHost);
+  if (activeHost !== "view") return null;
+
+  const req = useAnchoredMenuState((s) => s.request);
+  const visible = !!req;
+
+  const hostRef = useRef(null);
+  const [hostSize, setHostSize] = useState({ width: 0, height: 0 });
+
+  const [anchorWin, setAnchorWin] = useState(null);
+  const [hostWin, setHostWin] = useState(null);
+  const [menuSize, setMenuSize] = useState({ width: 0, height: 0 });
+  const measureCacheRef = useRef(new Map()); // id -> { t, anchorWin, hostWin }
+
+  useEffect(() => {
+    if (!req) {
+      setAnchorWin(null);
+      setHostWin(null);
+      setMenuSize({ width: 0, height: 0 });
+      return;
+    }
+    // reset on open / anchor change
+    setAnchorWin(null);
+    setHostWin(null);
+    setMenuSize({ width: 0, height: 0 });
+
+    // Warm start: if we recently measured this anchor, seed state so the menu can appear faster.
+    const cached = measureCacheRef.current.get(req.id);
+    if (cached && Date.now() - cached.t < 300) {
+      setAnchorWin(cached.anchorWin);
+      setHostWin(cached.hostWin);
+    }
+  }, [req?.id, req]);
+
+  useEffect(() => {
+    let cancelled = false;
+
+    async function run() {
+      if (!req || !hostRef.current) return;
+      await new Promise((r) => requestAnimationFrame(r));
+
+      const refObj = actions.anchors.get(req.id); // ref object
+      if (!refObj) return;
+
+      const strategy = req?.measurement ?? "stable"; // "stable" | "fast"
+      const tries =
+        typeof req?.measurementTries === "number" ? req.measurementTries : 8;
+      const measure =
+        strategy === "fast" ? measureInWindowFast : measureInWindowStable;
+
+      const [a, h] = await Promise.all([
+        measure(refObj, strategy === "stable" ? { tries } : undefined),
+        measure(hostRef, strategy === "stable" ? { tries } : undefined),
+      ]);
+
+      if (cancelled) return;
+      const nextAnchorWin = applyAnchorMargins(a, refObj);
+      setAnchorWin(nextAnchorWin);
+      setHostWin(h);
+      measureCacheRef.current.set(req.id, {
+        t: Date.now(),
+        anchorWin: nextAnchorWin,
+        hostWin: h,
+      });
+    }
+
+    run();
+    return () => {
+      cancelled = true;
+    };
+  }, [req?.id, req, actions.anchors]);
+
+  const anchorInHost = useMemo(() => {
+    if (!anchorWin || !hostWin) return null;
+    return {
+      ...anchorWin,
+      pageX: anchorWin.pageX - hostWin.pageX,
+      pageY: anchorWin.pageY - hostWin.pageY,
+    };
+  }, [anchorWin, hostWin]);
+
+  const position = useMemo(() => {
+    if (!req || !anchorInHost) return null;
+    const viewport =
+      hostSize.width && hostSize.height
+        ? { width: hostSize.width, height: hostSize.height }
+        : undefined;
+
+    return computeMenuPosition({
+      anchor: anchorInHost,
+      menuSize,
+      viewport,
+      placement: req.placement ?? "auto",
+      offset: req.offset ?? 8,
+      margin: req.margin ?? 8,
+      align: req.align ?? "start",
+      rtlAware: req.rtlAware ?? true,
+    });
+  }, [req, anchorInHost, menuSize, hostSize]);
+
+  const needsInitialMeasure = menuSize.width === 0 || menuSize.height === 0;
+  if (!visible) return null;
+
+  return (
+    <View
+      ref={hostRef}
+      collapsable={false}
+      style={{
+        position: "absolute",
+        top: 0,
+        right: 0,
+        bottom: 0,
+        left: 0,
+        zIndex: 9999,
+        elevation: 9999,
+      }}
+      pointerEvents="box-none"
+      onLayout={(e) => {
+        const { width, height } = e.nativeEvent.layout;
+        if (width !== hostSize.width || height !== hostSize.height) {
+          setHostSize({ width, height });
+        }
+      }}
+    >
+      {/* Tap outside to dismiss */}
+      <Pressable style={{ flex: 1 }} onPress={actions.close}>
+        {visible && !!anchorInHost && !!position ? (
+          <View
+            style={{
+              position: "absolute",
+              // Keep in-place so layout runs on iOS; hide visually until measured to avoid flicker.
+              top: position.top,
+              left: position.left,
+              zIndex: 10000,
+              elevation: 10000,
+              opacity: needsInitialMeasure ? 0 : 1,
+            }}
+            pointerEvents={needsInitialMeasure ? "none" : "auto"}
+            onStartShouldSetResponder={() => true}
+            onLayout={(e) => {
+              const { width, height } = e.nativeEvent.layout;
+              if (width !== menuSize.width || height !== menuSize.height) {
+                setMenuSize({ width, height });
+              }
+            }}
+          >
+            {typeof req.render === "function"
+              ? req.render({
+                  close: actions.close,
+                  anchor: anchorWin,
+                  anchorInHost,
+                })
+              : req.content}
+          </View>
+        ) : null}
+      </Pressable>
+    </View>
+  );
+}

package/src/index.js

@@ -0,0 +1,13 @@
+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";
+
+export { ModalHost } from "./hosts/ModalHost";
+export { ViewHost } from "./hosts/ViewHost";
+
+// Backwards-compat / convenience: allow default import
+//   import AnchoredMenuProvider from 'react-native-anchored-menu'
+export { AnchoredMenuProvider as default } from "./core/provider";

package/src/utils/measure.js

@@ -0,0 +1,87 @@
+import { InteractionManager, UIManager, findNodeHandle } from "react-native";
+
+const raf = () => new Promise((r) => requestAnimationFrame(r));
+
+async function measureInWindowOnce(target) {
+  const node = findNodeHandle(target?.current ?? target);
+  if (!node) return null;
+  return await new Promise((resolve) => {
+    UIManager.measureInWindow(node, (x, y, width, height) => {
+      resolve({ pageX: x, pageY: y, width, height });
+    });
+  });
+}
+
+/**
+ * Faster (less stable) measurement: one RAF + single measureInWindow call.
+ * Useful for very simple layouts where Android/FlatList flakiness isn't a concern.
+ */
+export async function measureInWindowFast(target) {
+  await raf();
+  return await measureInWindowOnce(target);
+}
+
+/**
+ * More reliable measurement for Android/FlatList: waits for interactions + next frame(s)
+ * and retries until values stabilize.
+ */
+export async function measureInWindowStable(target, { tries = 8 } = {}) {
+  await new Promise((r) => InteractionManager.runAfterInteractions(r));
+
+  const node = findNodeHandle(target?.current ?? target);
+  if (!node) return null;
+
+  let last = null;
+
+  for (let i = 0; i < tries; i++) {
+    await raf();
+
+    const m = await measureInWindowOnce({ current: node });
+
+    const looksInvalid = m.pageX === 0 && m.pageY === 0 && i < tries - 1;
+    const stable =
+      last &&
+      Math.abs(m.pageX - last.pageX) < 1 &&
+      Math.abs(m.pageY - last.pageY) < 1;
+
+    if (!looksInvalid && (stable || i >= 1)) return m;
+
+    last = m;
+  }
+
+  return last;
+}
+
+/**
+ * FlatList-safe: waits for interactions and next frame before measuring.
+ * Uses measureInWindow so coords match overlay/Modal window coordinates.
+ */
+export async function measureAnchorInWindow(ref) {
+  return await measureInWindowStable(ref, { tries: 8 });
+}
+
+/**
+ * Adjust measured rect to ignore margins applied on the anchored child.
+ * `MenuAnchor` stores margins on the ref object as `__anchoredMenuMargins`.
+ */
+export function applyAnchorMargins(measured, refObj) {
+  if (!measured) return measured;
+  const m = refObj?.__anchoredMenuMargins;
+  if (!m) return measured;
+
+  const top = typeof m.top === "number" ? m.top : 0;
+  const bottom = typeof m.bottom === "number" ? m.bottom : 0;
+  const left = typeof m.left === "number" ? m.left : 0;
+  const right = typeof m.right === "number" ? m.right : 0;
+
+  const width = Math.max(0, measured.width - left - right);
+  const height = Math.max(0, measured.height - top - bottom);
+
+  return {
+    ...measured,
+    pageX: measured.pageX + left,
+    pageY: measured.pageY + top,
+    width,
+    height,
+  };
+}

package/src/utils/position.js

@@ -0,0 +1,63 @@
+import { Dimensions, I18nManager } from "react-native";
+
+const clamp = (n, min, max) => Math.max(min, Math.min(max, n));
+
+/**
+ * Computes menu top/left with optional flip + clamping.
+ * If menuSize is unknown (0), it still places, but clamping/flip is limited.
+ */
+export function computeMenuPosition({
+  anchor,
+  menuSize,
+  viewport,
+  placement = "auto", // 'auto' | 'top' | 'bottom'
+  offset = 8,
+  margin = 8,
+  align = "start", // 'start' | 'center' | 'end'
+  rtlAware = true,
+}) {
+  const { width: SW, height: SH } = viewport ?? Dimensions.get("window");
+  const mW = menuSize?.width || 0;
+  const mH = menuSize?.height || 0;
+
+  // X alignment
+  let left = anchor.pageX;
+  if (align === "center" && mW) left = anchor.pageX + anchor.width / 2 - mW / 2;
+  if (align === "end" && mW) left = anchor.pageX + anchor.width - mW;
+
+  // Optional RTL hook (kept as no-op unless you customize)
+  if (rtlAware && I18nManager.isRTL) {
+    // no-op by default
+  }
+
+  if (mW) left = clamp(left, margin, SW - mW - margin);
+  else left = Math.max(margin, left);
+
+  // Candidate vertical positions
+  const belowTop = anchor.pageY + anchor.height + offset;
+  const aboveTop = anchor.pageY - mH - offset;
+
+  // Fit checks (meaningful when menu height is known)
+  const fitsAbove = mH ? aboveTop >= margin : true;
+  const fitsBelow = mH ? belowTop + mH <= SH - margin : true;
+
+  let top;
+
+  // Placement policy:
+  // - "top": prefer above, fallback below if it doesn't fit
+  // - "bottom": prefer below, fallback above if it doesn't fit
+  // - "auto": prefer below if it fits, else above
+  if (placement === "top") {
+    top = fitsAbove ? aboveTop : belowTop;
+  } else if (placement === "bottom") {
+    top = fitsBelow ? belowTop : aboveTop;
+  } else {
+    top = fitsBelow ? belowTop : aboveTop;
+  }
+
+  // Final clamp
+  if (mH) top = clamp(top, margin, SH - mH - margin);
+  else top = Math.max(margin, top);
+
+  return { top, left };
+}

package/src/utils/runtime.js

@@ -0,0 +1,13 @@
+/**
+ * Best-effort detection of Fabric/New Architecture.
+ * Used only to avoid known-crashy code paths (e.g. nesting RN <Modal> in some setups).
+ */
+export function isFabricEnabled() {
+  try {
+    // In Fabric, nativeFabricUIManager is typically defined.
+    // (Heuristic; varies by RN version)
+    return !!global?.nativeFabricUIManager;
+  } catch {
+    return false;
+  }
+}