@ankhorage/surface 9.4.19 → 9.5.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @ankhorage/surface
 
+## 9.5.0
+
+### Minor Changes
+
+- 68db7bb: Add a browser-only Popover entrypoint that does not load React Native modules.
+
 ## 9.4.19
 
 ### Patch Changes

package/README.md

@@ -3,7 +3,7 @@
 
 # @ankhorage/surface
 
-![license: MIT](././paradox/badges/license.svg) ![npm: v9.4.19](././paradox/badges/npm.svg) ![runtime: bun](././paradox/badges/runtime.svg) ![typescript: strict](././paradox/badges/typescript.svg) ![eslint: checked](././paradox/badges/eslint.svg) ![prettier: checked](././paradox/badges/prettier.svg) ![build: checked](././paradox/badges/build.svg) ![tests: checked](././paradox/badges/tests.svg) ![paradox: warnings](././paradox/badges/docs.svg)
+![license: MIT](././paradox/badges/license.svg) ![npm: v9.5.0](././paradox/badges/npm.svg) ![runtime: bun](././paradox/badges/runtime.svg) ![typescript: strict](././paradox/badges/typescript.svg) ![eslint: checked](././paradox/badges/eslint.svg) ![prettier: checked](././paradox/badges/prettier.svg) ![build: checked](././paradox/badges/build.svg) ![tests: checked](././paradox/badges/tests.svg) ![paradox: warnings](././paradox/badges/docs.svg)
 
 Cross-platform UI foundation for React Native and React Native Web. Provides theming, layout primitives, and core building blocks for modern apps.
 

package/dist/features/popover/adapters/inbound/browser/BrowserPopover.d.ts

@@ -0,0 +1,5 @@
+import React from 'react';
+import type { PopoverProps } from '../../../../../types/popover';
+/*** Renders the browser-only Popover without loading React Native implementation modules. */
+export declare function BrowserPopover(props: PopoverProps): React.JSX.Element;
+//# sourceMappingURL=BrowserPopover.d.ts.map

package/dist/features/popover/adapters/inbound/browser/BrowserPopover.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BrowserPopover.d.ts","sourceRoot":"","sources":["../../../../../../src/features/popover/adapters/inbound/browser/BrowserPopover.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAI1B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAEjE,6FAA6F;AAC7F,wBAAgB,cAAc,CAAC,KAAK,EAAE,YAAY,qBAgCjD"}

package/dist/features/popover/adapters/inbound/browser/BrowserPopover.js

@@ -0,0 +1,108 @@
+import React from 'react';
+import { createPortal } from 'react-dom';
+import { useControllableState } from '../../../../../internal/useControllableState';
+/*** Renders the browser-only Popover without loading React Native implementation modules. */
+export function BrowserPopover(props) {
+    const anchorRef = React.useRef(null);
+    const [contentElement, setContentElement] = React.useState(null);
+    const [open, setOpen] = useControllableState({
+        defaultValue: props.defaultOpen ?? false,
+        onChange: props.onOpenChange,
+        value: props.open,
+    });
+    const passive = props.interactionPolicy === 'passive';
+    const close = React.useCallback(() => {
+        if (!passive)
+            setOpen(false);
+    }, [passive, setOpen]);
+    const toggle = React.useCallback(() => {
+        if (!passive)
+            setOpen(!open);
+    }, [open, passive, setOpen]);
+    useBrowserPopoverDismissal(anchorRef, close, contentElement, open, props.closeOnOutsidePress);
+    const anchorRect = useBrowserPopoverAnchorRect(anchorRef, open);
+    const content = renderBrowserPopoverContent(props, anchorRect, setContentElement, open);
+    return (<>
+      <div ref={anchorRef} style={anchorStyle} data-testid={props.testID ? `${props.testID}-anchor` : undefined}>
+        {props.anchor({ close, open, toggle })}
+      </div>
+      {content === null || typeof document === 'undefined'
+            ? null
+            : createPortal(content, document.body)}
+    </>);
+}
+/*** Closes the open browser overlay for a true outside pointer press or Escape. */
+function useBrowserPopoverDismissal(anchorRef, close, contentElement, open, closeOnOutsidePress) {
+    React.useEffect(() => {
+        if (!open)
+            return;
+        const closeOnPointerDown = (event) => {
+            const { target } = event;
+            if (!(target instanceof Node))
+                return;
+            if (anchorRef.current?.contains(target) || contentElement?.contains(target))
+                return;
+            if (closeOnOutsidePress !== false)
+                close();
+        };
+        const closeOnEscape = (event) => {
+            if (event.key === 'Escape')
+                close();
+        };
+        document.addEventListener('pointerdown', closeOnPointerDown);
+        document.addEventListener('keydown', closeOnEscape);
+        return () => {
+            document.removeEventListener('pointerdown', closeOnPointerDown);
+            document.removeEventListener('keydown', closeOnEscape);
+        };
+    }, [anchorRef, close, closeOnOutsidePress, contentElement, open]);
+}
+/*** Create portal content only after the browser anchor has viewport coordinates. */
+function renderBrowserPopoverContent(props, anchorRect, setContentElement, open) {
+    if (!open || anchorRect === null)
+        return null;
+    return (<div ref={setContentElement} data-testid={props.testID ? `${props.testID}-content` : undefined} role="dialog" style={contentStyle(props, anchorRect)}>
+      {props.children}
+    </div>);
+}
+/*** Tracks the anchor in viewport coordinates while the browser overlay is visible. */
+function useBrowserPopoverAnchorRect(anchorRef, open) {
+    const [anchorRect, setAnchorRect] = React.useState(null);
+    React.useLayoutEffect(() => {
+        if (!open)
+            return;
+        const anchor = anchorRef.current;
+        if (anchor === null)
+            return;
+        const updateAnchorRect = () => setAnchorRect(anchor.getBoundingClientRect());
+        updateAnchorRect();
+        window.addEventListener('resize', updateAnchorRect);
+        window.addEventListener('scroll', updateAnchorRect, true);
+        return () => {
+            window.removeEventListener('resize', updateAnchorRect);
+            window.removeEventListener('scroll', updateAnchorRect, true);
+        };
+    }, [anchorRef, open]);
+    return anchorRect;
+}
+/*** Position browser content in the document overlay using the shared Popover placement contract. */
+function contentStyle(props, anchorRect) {
+    const offset = props.offset ?? 8;
+    const placement = props.placement ?? 'bottom-start';
+    const verticalPosition = placement.startsWith('top')
+        ? { bottom: window.innerHeight - anchorRect.top + offset }
+        : { top: anchorRect.bottom + offset };
+    const horizontalPosition = placement.endsWith('end')
+        ? { left: anchorRect.right, transform: 'translateX(-100%)' }
+        : placement.endsWith('start')
+            ? { left: anchorRect.left }
+            : { left: anchorRect.left + anchorRect.width / 2, transform: 'translateX(-50%)' };
+    return { ...baseContentStyle, ...verticalPosition, ...horizontalPosition };
+}
+const anchorStyle = { display: 'inline-block' };
+const baseContentStyle = {
+    pointerEvents: 'auto',
+    position: 'fixed',
+    zIndex: 1000,
+};
+//# sourceMappingURL=BrowserPopover.js.map

package/dist/features/popover/adapters/inbound/browser/BrowserPopover.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BrowserPopover.js","sourceRoot":"","sources":["../../../../../../src/features/popover/adapters/inbound/browser/BrowserPopover.tsx"],"names":[],"mappings":"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","sourcesContent":["import React from 'react';\nimport { createPortal } from 'react-dom';\n\nimport { useControllableState } from '../../../../../internal/useControllableState';\nimport type { PopoverProps } from '../../../../../types/popover';\n\n/*** Renders the browser-only Popover without loading React Native implementation modules. */\nexport function BrowserPopover(props: PopoverProps) {\n  const anchorRef = React.useRef<HTMLDivElement>(null);\n  const [contentElement, setContentElement] = React.useState<HTMLDivElement | null>(null);\n  const [open, setOpen] = useControllableState<boolean>({\n    defaultValue: props.defaultOpen ?? false,\n    onChange: props.onOpenChange,\n    value: props.open,\n  });\n  const passive = props.interactionPolicy === 'passive';\n  const close = React.useCallback(() => {\n    if (!passive) setOpen(false);\n  }, [passive, setOpen]);\n  const toggle = React.useCallback(() => {\n    if (!passive) setOpen(!open);\n  }, [open, passive, setOpen]);\n  useBrowserPopoverDismissal(anchorRef, close, contentElement, open, props.closeOnOutsidePress);\n  const anchorRect = useBrowserPopoverAnchorRect(anchorRef, open);\n  const content = renderBrowserPopoverContent(props, anchorRect, setContentElement, open);\n  return (\n    <>\n      <div\n        ref={anchorRef}\n        style={anchorStyle}\n        data-testid={props.testID ? `${props.testID}-anchor` : undefined}\n      >\n        {props.anchor({ close, open, toggle })}\n      </div>\n      {content === null || typeof document === 'undefined'\n        ? null\n        : createPortal(content, document.body)}\n    </>\n  );\n}\n\n/*** Closes the open browser overlay for a true outside pointer press or Escape. */\nfunction useBrowserPopoverDismissal(\n  anchorRef: React.RefObject<HTMLDivElement | null>,\n  close: () => void,\n  contentElement: HTMLDivElement | null,\n  open: boolean,\n  closeOnOutsidePress: boolean | undefined,\n): void {\n  React.useEffect(() => {\n    if (!open) return;\n    const closeOnPointerDown = (event: PointerEvent) => {\n      const { target } = event;\n      if (!(target instanceof Node)) return;\n      if (anchorRef.current?.contains(target) || contentElement?.contains(target)) return;\n      if (closeOnOutsidePress !== false) close();\n    };\n    const closeOnEscape = (event: KeyboardEvent) => {\n      if (event.key === 'Escape') close();\n    };\n    document.addEventListener('pointerdown', closeOnPointerDown);\n    document.addEventListener('keydown', closeOnEscape);\n    return () => {\n      document.removeEventListener('pointerdown', closeOnPointerDown);\n      document.removeEventListener('keydown', closeOnEscape);\n    };\n  }, [anchorRef, close, closeOnOutsidePress, contentElement, open]);\n}\n\n/*** Create portal content only after the browser anchor has viewport coordinates. */\nfunction renderBrowserPopoverContent(\n  props: PopoverProps,\n  anchorRect: DOMRect | null,\n  setContentElement: React.Dispatch<React.SetStateAction<HTMLDivElement | null>>,\n  open: boolean,\n): React.ReactNode {\n  if (!open || anchorRect === null) return null;\n  return (\n    <div\n      ref={setContentElement}\n      data-testid={props.testID ? `${props.testID}-content` : undefined}\n      role=\"dialog\"\n      style={contentStyle(props, anchorRect)}\n    >\n      {props.children}\n    </div>\n  );\n}\n\n/*** Tracks the anchor in viewport coordinates while the browser overlay is visible. */\nfunction useBrowserPopoverAnchorRect(\n  anchorRef: React.RefObject<HTMLDivElement | null>,\n  open: boolean,\n): DOMRect | null {\n  const [anchorRect, setAnchorRect] = React.useState<DOMRect | null>(null);\n  React.useLayoutEffect(() => {\n    if (!open) return;\n    const anchor = anchorRef.current;\n    if (anchor === null) return;\n    const updateAnchorRect = () => setAnchorRect(anchor.getBoundingClientRect());\n    updateAnchorRect();\n    window.addEventListener('resize', updateAnchorRect);\n    window.addEventListener('scroll', updateAnchorRect, true);\n    return () => {\n      window.removeEventListener('resize', updateAnchorRect);\n      window.removeEventListener('scroll', updateAnchorRect, true);\n    };\n  }, [anchorRef, open]);\n  return anchorRect;\n}\n\n/*** Position browser content in the document overlay using the shared Popover placement contract. */\nfunction contentStyle(props: PopoverProps, anchorRect: DOMRect): React.CSSProperties {\n  const offset = props.offset ?? 8;\n  const placement = props.placement ?? 'bottom-start';\n  const verticalPosition = placement.startsWith('top')\n    ? { bottom: window.innerHeight - anchorRect.top + offset }\n    : { top: anchorRect.bottom + offset };\n  const horizontalPosition = placement.endsWith('end')\n    ? { left: anchorRect.right, transform: 'translateX(-100%)' }\n    : placement.endsWith('start')\n      ? { left: anchorRect.left }\n      : { left: anchorRect.left + anchorRect.width / 2, transform: 'translateX(-50%)' };\n  return { ...baseContentStyle, ...verticalPosition, ...horizontalPosition };\n}\n\nconst anchorStyle: React.CSSProperties = { display: 'inline-block' };\nconst baseContentStyle: React.CSSProperties = {\n  pointerEvents: 'auto',\n  position: 'fixed',\n  zIndex: 1000,\n};\n"]}

package/dist/features/popover/browser.d.ts

@@ -0,0 +1,3 @@
+export type { PopoverAnchorRenderProps, PopoverPlacement, PopoverProps } from '../../types/popover';
+export { BrowserPopover as Popover } from './adapters/inbound/browser/BrowserPopover';
+//# sourceMappingURL=browser.d.ts.map

package/dist/features/popover/browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../../../src/features/popover/browser.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,wBAAwB,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACpG,OAAO,EAAE,cAAc,IAAI,OAAO,EAAE,MAAM,2CAA2C,CAAC"}

package/dist/features/popover/browser.js

@@ -0,0 +1,2 @@
+export { BrowserPopover as Popover } from './adapters/inbound/browser/BrowserPopover';
+//# sourceMappingURL=browser.js.map

package/dist/features/popover/browser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.js","sourceRoot":"","sources":["../../../src/features/popover/browser.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,IAAI,OAAO,EAAE,MAAM,2CAA2C,CAAC","sourcesContent":["export type { PopoverAnchorRenderProps, PopoverPlacement, PopoverProps } from '../../types/popover';\nexport { BrowserPopover as Popover } from './adapters/inbound/browser/BrowserPopover';\n"]}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ankhorage/surface",
   "type": "module",
-  "version": "9.4.19",
+  "version": "9.5.0",
   "description": "Stable UI foundation for React Native and React Native Web.",
   "homepage": "https://github.com/ankhorage/surface#readme",
   "bugs": {
@@ -34,6 +34,7 @@
     "@react-native-vector-icons/ionicons": "^13.1.3",
     "@react-native-vector-icons/material-design-icons": "^13.1.3",
     "react": "19.2.3 || 19.3.0",
+    "react-dom": "19.2.3 || 19.3.0",
     "react-native": "0.86.x || 0.87.x",
     "react-native-gesture-handler": "~2.32.0 || ~3.3.0",
     "react-native-reanimated": "4.5.1 || 4.7.0 || 4.7",
@@ -70,6 +71,11 @@
       "import": "./dist/features/bottom-sheet/public.js",
       "default": "./dist/features/bottom-sheet/public.js"
     },
+    "./browser": {
+      "types": "./dist/features/popover/browser.d.ts",
+      "import": "./dist/features/popover/browser.js",
+      "default": "./dist/features/popover/browser.js"
+    },
     "./color": {
       "bun": "./src/constants/surfaceColor.ts",
       "react-native": "./src/constants/surfaceColor.ts",
@@ -108,6 +114,7 @@
     "format:check": "ankhorage-prettier --check .",
     "prepack": "bun run build",
     "test": "bun test src",
+    "test:browser": "bun test ./test/browser/browserPopover.ts",
     "typecheck": "bun x tsc --noEmit -p tsconfig.json",
     "version-packages": "ankhorage-changeset version"
   },
@@ -135,6 +142,7 @@
     "react-native-svg": "15.15.5",
     "react-native-web": "~0.21.4",
     "react-native-worklets": "0.13.0",
+    "playwright-core": "^1.58.2",
     "typescript": "~6.0.3"
   },
   "packageManager": "bun@1.4.2",

package/src/features/popover/adapters/inbound/browser/BrowserPopover.test.tsx

@@ -0,0 +1,111 @@
+import { expect, test } from 'bun:test';
+import { Window } from 'happy-dom';
+import React, { act } from 'react';
+
+import { BrowserPopover } from './BrowserPopover';
+
+test('BrowserPopover opens, uses browser placement, and closes on outside press', async () => {
+  const { browserWindow, container, root } = await renderBrowserPopover();
+  try {
+    const button = container.querySelector('button');
+    if (button === null) throw new Error('BrowserPopover anchor did not render.');
+    await act(async () => {
+      button.click();
+      await Promise.resolve();
+    });
+
+    const content = browserWindow.document.querySelector(
+      '[data-testid="popover-content"]',
+    ) as HTMLElement | null;
+    expect(content?.textContent).toBe('Content');
+    expect(content?.style.position).toBe('fixed');
+    expect(Number.parseInt(content?.style.bottom ?? '', 10)).toBeGreaterThan(0);
+    expect(content?.style.left).toBe('0px');
+    expect(content?.style.transform).toBe('translateX(-100%)');
+
+    await act(async () => {
+      browserWindow.document.body.dispatchEvent(
+        new browserWindow.PointerEvent('pointerdown', { bubbles: true }),
+      );
+      await Promise.resolve();
+    });
+    expect(browserWindow.document.querySelector('[data-testid="popover-content"]')).toBeNull();
+    act(() => root.unmount());
+  } finally {
+    resetBrowserGlobals(browserWindow);
+  }
+});
+
+test('BrowserPopover closes on Escape and removes browser listeners after unmount', async () => {
+  const { browserWindow, container, root } = await renderBrowserPopover();
+  try {
+    const button = container.querySelector('button');
+    if (button === null) throw new Error('BrowserPopover anchor did not render.');
+    await act(async () => {
+      button.click();
+      await Promise.resolve();
+    });
+
+    await act(async () => {
+      browserWindow.document.dispatchEvent(
+        new browserWindow.KeyboardEvent('keydown', { bubbles: true, key: 'Escape' }),
+      );
+      await Promise.resolve();
+    });
+    expect(browserWindow.document.querySelector('[data-testid="popover-content"]')).toBeNull();
+
+    act(() => root.unmount());
+    browserWindow.dispatchEvent(new browserWindow.Event('resize'));
+    browserWindow.document.body.dispatchEvent(
+      new browserWindow.PointerEvent('pointerdown', { bubbles: true }),
+    );
+    expect(browserWindow.document.querySelector('[data-testid="popover-content"]')).toBeNull();
+  } finally {
+    resetBrowserGlobals(browserWindow);
+  }
+});
+
+/*** Mount the browser-only Popover in a DOM isolated from the Bun test process. */
+async function renderBrowserPopover() {
+  const browserWindow = new Window();
+  Object.assign(globalThis, {
+    IS_REACT_ACT_ENVIRONMENT: true,
+    document: browserWindow.document,
+    Node: browserWindow.Node,
+    PointerEvent: browserWindow.PointerEvent,
+    window: browserWindow,
+  });
+  try {
+    const container = browserWindow.document.createElement('div');
+    browserWindow.document.body.append(container);
+    const { createRoot } = await import('react-dom/client');
+    const root = createRoot(container as unknown as Element);
+
+    act(() => {
+      root.render(
+        <BrowserPopover
+          closeOnOutsidePress
+          placement="top-end"
+          testID="popover"
+          anchor={({ toggle }) => <button onClick={toggle}>Open</button>}
+        >
+          <span>Content</span>
+        </BrowserPopover>,
+      );
+    });
+    return { browserWindow, container, root };
+  } catch (error) {
+    resetBrowserGlobals(browserWindow);
+    throw error;
+  }
+}
+
+/*** Remove the temporary DOM globals so other tests retain their own environment. */
+function resetBrowserGlobals(browserWindow: Window): void {
+  browserWindow.close();
+  Reflect.deleteProperty(globalThis, 'IS_REACT_ACT_ENVIRONMENT');
+  Reflect.deleteProperty(globalThis, 'Node');
+  Reflect.deleteProperty(globalThis, 'PointerEvent');
+  Reflect.deleteProperty(globalThis, 'document');
+  Reflect.deleteProperty(globalThis, 'window');
+}

package/src/features/popover/adapters/inbound/browser/BrowserPopover.tsx

@@ -0,0 +1,132 @@
+import React from 'react';
+import { createPortal } from 'react-dom';
+
+import { useControllableState } from '../../../../../internal/useControllableState';
+import type { PopoverProps } from '../../../../../types/popover';
+
+/*** Renders the browser-only Popover without loading React Native implementation modules. */
+export function BrowserPopover(props: PopoverProps) {
+  const anchorRef = React.useRef<HTMLDivElement>(null);
+  const [contentElement, setContentElement] = React.useState<HTMLDivElement | null>(null);
+  const [open, setOpen] = useControllableState<boolean>({
+    defaultValue: props.defaultOpen ?? false,
+    onChange: props.onOpenChange,
+    value: props.open,
+  });
+  const passive = props.interactionPolicy === 'passive';
+  const close = React.useCallback(() => {
+    if (!passive) setOpen(false);
+  }, [passive, setOpen]);
+  const toggle = React.useCallback(() => {
+    if (!passive) setOpen(!open);
+  }, [open, passive, setOpen]);
+  useBrowserPopoverDismissal(anchorRef, close, contentElement, open, props.closeOnOutsidePress);
+  const anchorRect = useBrowserPopoverAnchorRect(anchorRef, open);
+  const content = renderBrowserPopoverContent(props, anchorRect, setContentElement, open);
+  return (
+    <>
+      <div
+        ref={anchorRef}
+        style={anchorStyle}
+        data-testid={props.testID ? `${props.testID}-anchor` : undefined}
+      >
+        {props.anchor({ close, open, toggle })}
+      </div>
+      {content === null || typeof document === 'undefined'
+        ? null
+        : createPortal(content, document.body)}
+    </>
+  );
+}
+
+/*** Closes the open browser overlay for a true outside pointer press or Escape. */
+function useBrowserPopoverDismissal(
+  anchorRef: React.RefObject<HTMLDivElement | null>,
+  close: () => void,
+  contentElement: HTMLDivElement | null,
+  open: boolean,
+  closeOnOutsidePress: boolean | undefined,
+): void {
+  React.useEffect(() => {
+    if (!open) return;
+    const closeOnPointerDown = (event: PointerEvent) => {
+      const { target } = event;
+      if (!(target instanceof Node)) return;
+      if (anchorRef.current?.contains(target) || contentElement?.contains(target)) return;
+      if (closeOnOutsidePress !== false) close();
+    };
+    const closeOnEscape = (event: KeyboardEvent) => {
+      if (event.key === 'Escape') close();
+    };
+    document.addEventListener('pointerdown', closeOnPointerDown);
+    document.addEventListener('keydown', closeOnEscape);
+    return () => {
+      document.removeEventListener('pointerdown', closeOnPointerDown);
+      document.removeEventListener('keydown', closeOnEscape);
+    };
+  }, [anchorRef, close, closeOnOutsidePress, contentElement, open]);
+}
+
+/*** Create portal content only after the browser anchor has viewport coordinates. */
+function renderBrowserPopoverContent(
+  props: PopoverProps,
+  anchorRect: DOMRect | null,
+  setContentElement: React.Dispatch<React.SetStateAction<HTMLDivElement | null>>,
+  open: boolean,
+): React.ReactNode {
+  if (!open || anchorRect === null) return null;
+  return (
+    <div
+      ref={setContentElement}
+      data-testid={props.testID ? `${props.testID}-content` : undefined}
+      role="dialog"
+      style={contentStyle(props, anchorRect)}
+    >
+      {props.children}
+    </div>
+  );
+}
+
+/*** Tracks the anchor in viewport coordinates while the browser overlay is visible. */
+function useBrowserPopoverAnchorRect(
+  anchorRef: React.RefObject<HTMLDivElement | null>,
+  open: boolean,
+): DOMRect | null {
+  const [anchorRect, setAnchorRect] = React.useState<DOMRect | null>(null);
+  React.useLayoutEffect(() => {
+    if (!open) return;
+    const anchor = anchorRef.current;
+    if (anchor === null) return;
+    const updateAnchorRect = () => setAnchorRect(anchor.getBoundingClientRect());
+    updateAnchorRect();
+    window.addEventListener('resize', updateAnchorRect);
+    window.addEventListener('scroll', updateAnchorRect, true);
+    return () => {
+      window.removeEventListener('resize', updateAnchorRect);
+      window.removeEventListener('scroll', updateAnchorRect, true);
+    };
+  }, [anchorRef, open]);
+  return anchorRect;
+}
+
+/*** Position browser content in the document overlay using the shared Popover placement contract. */
+function contentStyle(props: PopoverProps, anchorRect: DOMRect): React.CSSProperties {
+  const offset = props.offset ?? 8;
+  const placement = props.placement ?? 'bottom-start';
+  const verticalPosition = placement.startsWith('top')
+    ? { bottom: window.innerHeight - anchorRect.top + offset }
+    : { top: anchorRect.bottom + offset };
+  const horizontalPosition = placement.endsWith('end')
+    ? { left: anchorRect.right, transform: 'translateX(-100%)' }
+    : placement.endsWith('start')
+      ? { left: anchorRect.left }
+      : { left: anchorRect.left + anchorRect.width / 2, transform: 'translateX(-50%)' };
+  return { ...baseContentStyle, ...verticalPosition, ...horizontalPosition };
+}
+
+const anchorStyle: React.CSSProperties = { display: 'inline-block' };
+const baseContentStyle: React.CSSProperties = {
+  pointerEvents: 'auto',
+  position: 'fixed',
+  zIndex: 1000,
+};

package/src/features/popover/browser.ts

@@ -0,0 +1,2 @@
+export type { PopoverAnchorRenderProps, PopoverPlacement, PopoverProps } from '../../types/popover';
+export { BrowserPopover as Popover } from './adapters/inbound/browser/BrowserPopover';

package/src/index.test.ts

@@ -137,6 +137,11 @@ describe('public package metadata contract', () => {
         import: './dist/features/bottom-sheet/public.js',
         types: './dist/features/bottom-sheet/public.d.ts',
       },
+      './browser': {
+        default: './dist/features/popover/browser.js',
+        import: './dist/features/popover/browser.js',
+        types: './dist/features/popover/browser.d.ts',
+      },
       './color': {
         bun: './src/constants/surfaceColor.ts',
         'react-native': './src/constants/surfaceColor.ts',
@@ -162,6 +167,7 @@ describe('public package metadata contract', () => {
 describe('native peer compatibility contract', () => {
   it('preserves the independently tested Expo 57 and current native peer tuples', () => {
     expect(packageJson.peerDependencies.react).toBe('19.2.3 || 19.3.0');
+    expect(packageJson.peerDependencies['react-dom']).toBe('19.2.3 || 19.3.0');
     expect(packageJson.peerDependencies['react-native']).toBe('0.86.x || 0.87.x');
     expect(packageJson.peerDependencies['react-native-web']).toBe('~0.21.0');
     expect(packageJson.peerDependencies['react-native-safe-area-context']).toBe(