@ankhorage/surface 4.4.1 → 5.0.0

package/dist/types/bottomSheet.d.ts

@@ -1,9 +1,12 @@
 import type React from 'react';
+export type BottomSheetContentMode = 'view' | 'direct';
 export interface BottomSheetPresentOptions {
     content: React.ReactNode;
+    contentMode?: BottomSheetContentMode;
     snapPoints?: readonly (number | string)[];
     initialIndex?: number;
     enableDynamicSizing?: boolean;
+    maxDynamicContentSize?: number;
     enablePanDownToClose?: boolean;
     dismissOnBackdropPress?: boolean;
     keyboardBehavior?: 'extend' | 'fillParent' | 'interactive';

package/dist/types/bottomSheet.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bottomSheet.d.ts","sourceRoot":"","sources":["../../src/types/bottomSheet.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,MAAM,WAAW,yBAAyB;IACxC,OAAO,EAAE,KAAK,CAAC,SAAS,CAAC;IACzB,UAAU,CAAC,EAAE,SAAS,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;IAC1C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC,gBAAgB,CAAC,EAAE,QAAQ,GAAG,YAAY,GAAG,aAAa,CAAC;IAC3D,oBAAoB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;CACxB;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,CAAC,OAAO,EAAE,yBAAyB,KAAK,IAAI,CAAC;IACtD,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB"}
+{"version":3,"file":"bottomSheet.d.ts","sourceRoot":"","sources":["../../src/types/bottomSheet.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,MAAM,MAAM,sBAAsB,GAAG,MAAM,GAAG,QAAQ,CAAC;AAEvD,MAAM,WAAW,yBAAyB;IACxC,OAAO,EAAE,KAAK,CAAC,SAAS,CAAC;IACzB,WAAW,CAAC,EAAE,sBAAsB,CAAC;IACrC,UAAU,CAAC,EAAE,SAAS,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;IAC1C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC,gBAAgB,CAAC,EAAE,QAAQ,GAAG,YAAY,GAAG,aAAa,CAAC;IAC3D,oBAAoB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;CACxB;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,CAAC,OAAO,EAAE,yBAAyB,KAAK,IAAI,CAAC;IACtD,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB"}

package/dist/types/bottomSheet.js.map

@@ -1 +1 @@
-{"version":3,"file":"bottomSheet.js","sourceRoot":"","sources":["../../src/types/bottomSheet.ts"],"names":[],"mappings":"","sourcesContent":["import type React from 'react';\n\nexport interface BottomSheetPresentOptions {\n  content: React.ReactNode;\n  snapPoints?: readonly (number | string)[];\n  initialIndex?: number;\n  enableDynamicSizing?: boolean;\n  enablePanDownToClose?: boolean;\n  dismissOnBackdropPress?: boolean;\n  keyboardBehavior?: 'extend' | 'fillParent' | 'interactive';\n  keyboardBlurBehavior?: 'none' | 'restore';\n  onIndexChange?: (index: number) => void;\n  onDismiss?: () => void;\n}\n\nexport interface BottomSheetController {\n  present: (options: BottomSheetPresentOptions) => void;\n  dismiss: () => void;\n}\n"]}
+{"version":3,"file":"bottomSheet.js","sourceRoot":"","sources":["../../src/types/bottomSheet.ts"],"names":[],"mappings":"","sourcesContent":["import type React from 'react';\n\nexport type BottomSheetContentMode = 'view' | 'direct';\n\nexport interface BottomSheetPresentOptions {\n  content: React.ReactNode;\n  contentMode?: BottomSheetContentMode;\n  snapPoints?: readonly (number | string)[];\n  initialIndex?: number;\n  enableDynamicSizing?: boolean;\n  maxDynamicContentSize?: number;\n  enablePanDownToClose?: boolean;\n  dismissOnBackdropPress?: boolean;\n  keyboardBehavior?: 'extend' | 'fillParent' | 'interactive';\n  keyboardBlurBehavior?: 'none' | 'restore';\n  onIndexChange?: (index: number) => void;\n  onDismiss?: () => void;\n}\n\nexport interface BottomSheetController {\n  present: (options: BottomSheetPresentOptions) => void;\n  dismiss: () => void;\n}\n"]}

package/dist/types/popoverMenu.d.ts

@@ -0,0 +1,24 @@
+import type React from 'react';
+import type { InteractionPolicy } from '../interactionPolicy';
+import type { PopoverAnchorRenderProps } from './popover';
+export type PopoverMenuActionIntent = 'default' | 'danger';
+export interface PopoverMenuAction {
+    id: string;
+    title: React.ReactNode;
+    description?: React.ReactNode;
+    leading?: React.ReactNode;
+    trailing?: React.ReactNode;
+    intent?: PopoverMenuActionIntent;
+    disabled?: boolean;
+    selected?: boolean;
+    activate?: () => void;
+}
+export interface PopoverMenuProps {
+    trigger: (controls: PopoverAnchorRenderProps) => React.ReactNode;
+    actions: readonly PopoverMenuAction[];
+    dismiss?: () => void;
+    closeOnSelect?: boolean;
+    interactionPolicy?: InteractionPolicy;
+    testID?: string;
+}
+//# sourceMappingURL=popoverMenu.d.ts.map

package/dist/types/popoverMenu.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"popoverMenu.d.ts","sourceRoot":"","sources":["../../src/types/popoverMenu.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,WAAW,CAAC;AAE1D,MAAM,MAAM,uBAAuB,GAAG,SAAS,GAAG,QAAQ,CAAC;AAE3D,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,KAAK,CAAC,SAAS,CAAC;IACvB,WAAW,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC9B,OAAO,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC3B,MAAM,CAAC,EAAE,uBAAuB,CAAC;IACjC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;CACvB;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,CAAC,QAAQ,EAAE,wBAAwB,KAAK,KAAK,CAAC,SAAS,CAAC;IACjE,OAAO,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACtC,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IACtC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB"}

package/dist/types/popoverMenu.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=popoverMenu.js.map

package/dist/types/popoverMenu.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"popoverMenu.js","sourceRoot":"","sources":["../../src/types/popoverMenu.ts"],"names":[],"mappings":"","sourcesContent":["import type React from 'react';\n\nimport type { InteractionPolicy } from '../interactionPolicy';\nimport type { PopoverAnchorRenderProps } from './popover';\n\nexport type PopoverMenuActionIntent = 'default' | 'danger';\n\nexport interface PopoverMenuAction {\n  id: string;\n  title: React.ReactNode;\n  description?: React.ReactNode;\n  leading?: React.ReactNode;\n  trailing?: React.ReactNode;\n  intent?: PopoverMenuActionIntent;\n  disabled?: boolean;\n  selected?: boolean;\n  activate?: () => void;\n}\n\nexport interface PopoverMenuProps {\n  trigger: (controls: PopoverAnchorRenderProps) => React.ReactNode;\n  actions: readonly PopoverMenuAction[];\n  dismiss?: () => void;\n  closeOnSelect?: boolean;\n  interactionPolicy?: InteractionPolicy;\n  testID?: string;\n}\n"]}

package/dist/{components/tooltip/types.d.ts → types/tooltip.d.ts}

@@ -1,5 +1,5 @@
 import type React from 'react';
-import type { InteractionPolicy } from '../../interactionPolicy';
+import type { InteractionPolicy } from '../interactionPolicy';
 export interface TooltipProps {
     children?: React.ReactNode;
     content?: React.ReactNode;
@@ -8,4 +8,4 @@ export interface TooltipProps {
     placement?: 'top' | 'bottom';
     testID?: string;
 }
-//# sourceMappingURL=types.d.ts.map
+//# sourceMappingURL=tooltip.d.ts.map

package/dist/types/tooltip.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tooltip.d.ts","sourceRoot":"","sources":["../../src/types/tooltip.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAE9D,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC3B,OAAO,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IACtC,SAAS,CAAC,EAAE,KAAK,GAAG,QAAQ,CAAC;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB"}

package/dist/types/tooltip.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=tooltip.js.map

package/dist/types/tooltip.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tooltip.js","sourceRoot":"","sources":["../../src/types/tooltip.ts"],"names":[],"mappings":"","sourcesContent":["import type React from 'react';\n\nimport type { InteractionPolicy } from '../interactionPolicy';\n\nexport interface TooltipProps {\n  children?: React.ReactNode;\n  content?: React.ReactNode;\n  delay?: number;\n  interactionPolicy?: InteractionPolicy;\n  placement?: 'top' | 'bottom';\n  testID?: string;\n}\n"]}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ankhorage/surface",
   "type": "module",
-  "version": "4.4.1",
+  "version": "5.0.0",
   "description": "Stable UI foundation for React Native and React Native Web.",
   "homepage": "https://github.com/ankhorage/surface#readme",
   "bugs": {

package/src/features/bottom-sheet/BottomSheetProvider.tsx

@@ -77,10 +77,7 @@ function BottomSheetHost({
   presentedRef,
 }: BottomSheetHostProps) {
   React.useEffect(() => {
-    if (!activeRequest || presentedRef.current) {
-      return;
-    }
-
+    if (!activeRequest || presentedRef.current) return;
     presentedRef.current = true;
     modalRef.current?.present();
   }, [activeRequest, modalRef, presentedRef]);
@@ -91,9 +88,7 @@ function BottomSheetHost({
     [activeRequest?.snapPoints],
   );
 
-  if (!activeRequest) {
-    return null;
-  }
+  if (!activeRequest) return null;
 
   return (
     <BottomSheetModal
@@ -104,15 +99,25 @@ function BottomSheetHost({
       index={activeRequest.initialIndex ?? 0}
       keyboardBehavior={activeRequest.keyboardBehavior ?? 'interactive'}
       keyboardBlurBehavior={activeRequest.keyboardBlurBehavior ?? 'restore'}
+      maxDynamicContentSize={activeRequest.maxDynamicContentSize}
       onChange={activeRequest.onIndexChange}
       onDismiss={handleDismiss}
       snapPoints={snapPoints}
     >
-      <BottomSheetView>{activeRequest.content}</BottomSheetView>
+      {renderBottomSheetContent(activeRequest)}
     </BottomSheetModal>
   );
 }
 
+/*** Renders default content in BottomSheetView and direct content without an extra wrapper. */
+function renderBottomSheetContent(activeRequest: BottomSheetPresentOptions): React.ReactNode {
+  return activeRequest.contentMode === 'direct' ? (
+    activeRequest.content
+  ) : (
+    <BottomSheetView>{activeRequest.content}</BottomSheetView>
+  );
+}
+
 /*** Creates the backdrop renderer for the active bottom-sheet request. */
 function useBottomSheetBackdrop(dismissOnBackdropPress: boolean | undefined) {
   return React.useCallback(

package/src/features/bottom-sheet/public.test.ts

@@ -0,0 +1,23 @@
+import { expect, test } from 'bun:test';
+
+test('bottom-sheet boundary exposes Gorhom integrated scrollables and direct content mode', async () => {
+  const [publicSource, providerSource, typeSource] = await Promise.all([
+    Bun.file('src/features/bottom-sheet/public.ts').text(),
+    Bun.file('src/features/bottom-sheet/BottomSheetProvider.tsx').text(),
+    Bun.file('src/types/bottomSheet.ts').text(),
+  ]);
+
+  for (const name of [
+    'BottomSheetFlatList',
+    'BottomSheetScrollView',
+    'BottomSheetSectionList',
+    'BottomSheetView',
+    'BottomSheetVirtualizedList',
+  ]) {
+    expect(publicSource).toContain(name);
+  }
+
+  expect(typeSource).toContain("export type BottomSheetContentMode = 'view' | 'direct';");
+  expect(providerSource).toContain("activeRequest.contentMode === 'direct'");
+  expect(providerSource).toContain('maxDynamicContentSize={activeRequest.maxDynamicContentSize}');
+});

package/src/features/bottom-sheet/public.ts

@@ -1,3 +1,14 @@
-export type { BottomSheetController, BottomSheetPresentOptions } from '../../types/bottomSheet';
+export type {
+  BottomSheetContentMode,
+  BottomSheetController,
+  BottomSheetPresentOptions,
+} from '../../types/bottomSheet';
 export { BottomSheetProvider } from './BottomSheetProvider';
 export { useBottomSheet } from './useBottomSheet';
+export {
+  BottomSheetFlatList,
+  BottomSheetScrollView,
+  BottomSheetSectionList,
+  BottomSheetView,
+  BottomSheetVirtualizedList,
+} from '@gorhom/bottom-sheet';

package/src/features/popover-menu/adapters/inbound/PopoverMenu.tsx

@@ -0,0 +1,201 @@
+import React from 'react';
+import { Pressable } from 'react-native';
+
+import { FocusScope } from '../../../../internal/focus/FocusScope';
+import { useFocusManager } from '../../../../internal/focus/useFocusManager';
+import { Inline } from '../../../../layout';
+import { useTheme } from '../../../../theme/ThemeContext';
+import type { PopoverMenuAction, PopoverMenuProps } from '../../../../types/popoverMenu';
+import { Box, Stack } from '../../../layout/public';
+import { Popover } from '../../../popover/public';
+import { Surface } from '../../../surface/public';
+import { Text } from '../../../typography/public';
+import { usePopoverMenuController } from '../../composition/usePopoverMenuController';
+import { resolveNextMenuIndex } from '../../utils/resolveNextMenuIndex';
+
+/*** Presents an anchored action menu using the shared Popover capability. */
+export function PopoverMenu({
+  trigger,
+  actions,
+  dismiss,
+  closeOnSelect = true,
+  interactionPolicy = 'enabled',
+  testID,
+}: PopoverMenuProps) {
+  const passive = interactionPolicy === 'passive';
+  const controller = usePopoverMenuController({ actions, closeOnSelect, dismiss, passive });
+
+  return (
+    <Popover
+      anchor={trigger}
+      closeOnOutsidePress
+      interactionPolicy={interactionPolicy}
+      onOpenChange={controller.handleOpenChange}
+      open={controller.open}
+      placement="bottom-start"
+      testID={testID}
+    >
+      <PopoverMenuContent
+        actions={actions}
+        activeIndex={controller.activeIndex}
+        activateAction={controller.activateAction}
+        close={controller.close}
+        passive={passive}
+        setActiveIndex={controller.setActiveIndex}
+        testID={testID}
+      />
+    </Popover>
+  );
+}
+
+interface PopoverMenuContentProps {
+  actions: readonly PopoverMenuAction[];
+  activeIndex: number;
+  activateAction: (action: PopoverMenuAction) => void;
+  close: () => void;
+  passive: boolean;
+  setActiveIndex: React.Dispatch<React.SetStateAction<number>>;
+  testID?: string;
+}
+
+/*** Renders menu semantics and keyboard navigation inside an open Popover. */
+function PopoverMenuContent({
+  actions,
+  activeIndex,
+  activateAction,
+  close,
+  passive,
+  setActiveIndex,
+  testID,
+}: PopoverMenuContentProps) {
+  usePopoverMenuKeyboard({ actions, activeIndex, activateAction, close, passive, setActiveIndex });
+
+  return (
+    <FocusScope active onEscape={passive ? undefined : close}>
+      <Surface accessibilityRole="menu" p="xs" testID={testID} variant="raised">
+        {actions.map((action, index) => (
+          <PopoverMenuItem
+            action={action}
+            active={index === activeIndex}
+            activateAction={activateAction}
+            key={action.id}
+            passive={passive}
+            testID={testID}
+          />
+        ))}
+      </Surface>
+    </FocusScope>
+  );
+}
+
+/*** Subscribes an open PopoverMenu to standard menu keyboard controls. */
+function usePopoverMenuKeyboard({
+  actions,
+  activeIndex,
+  activateAction,
+  close,
+  passive,
+  setActiveIndex,
+}: Omit<PopoverMenuContentProps, 'testID'>) {
+  const { bindKeydown } = useFocusManager();
+
+  React.useEffect(
+    () =>
+      bindKeydown((event) => {
+        if (passive) return;
+
+        const { key } = event;
+        if (key === undefined) return;
+
+        if (['ArrowDown', 'ArrowUp', 'Home', 'End'].includes(key)) {
+          event.preventDefault();
+          setActiveIndex((current) => resolveNextMenuIndex(actions, current, key));
+          return;
+        }
+        if (key === 'Enter') {
+          event.preventDefault();
+          const action = actions.at(activeIndex);
+          if (action) activateAction(action);
+          return;
+        }
+        if (key === 'Escape') {
+          event.preventDefault();
+          close();
+        }
+      }),
+    [actions, activeIndex, activateAction, bindKeydown, close, passive, setActiveIndex],
+  );
+}
+
+/*** Renders one accessible PopoverMenu action row. */
+function PopoverMenuItem({
+  action,
+  active,
+  activateAction,
+  passive,
+  testID,
+}: {
+  action: PopoverMenuAction;
+  active: boolean;
+  activateAction: (action: PopoverMenuAction) => void;
+  passive: boolean;
+  testID?: string;
+}) {
+  const { theme } = useTheme();
+  const selected = action.selected ?? active;
+
+  return (
+    <Pressable
+      accessibilityRole="menuitem"
+      accessibilityState={{ disabled: action.disabled, selected }}
+      disabled={action.disabled}
+      onPress={passive ? undefined : () => activateAction(action)}
+      testID={testID ? `${testID}-item-${action.id}` : undefined}
+    >
+      <Box
+        bg={selected ? theme.semantics.action.neutral.softBg : 'transparent'}
+        opacity={action.disabled ? 0.56 : 1}
+        px="m"
+        py="s"
+        radius="s"
+      >
+        <PopoverMenuItemContent action={action} active={active} />
+      </Box>
+    </Pressable>
+  );
+}
+
+/*** Renders the leading, textual, and trailing content of one menu action. */
+function PopoverMenuItemContent({
+  action,
+  active,
+}: {
+  action: PopoverMenuAction;
+  active: boolean;
+}) {
+  const titleColor =
+    action.intent === 'danger' ? 'danger' : active || action.selected ? 'neutral' : undefined;
+
+  return (
+    <Inline align="center" gap="s" justify="space-between" wrap="nowrap">
+      {action.leading ? <Box>{action.leading}</Box> : null}
+      <Box flex={1}>
+        <Stack gap="xxs">
+          <Text
+            color={titleColor}
+            variant="bodySmall"
+            weight={action.selected ? 'semiBold' : 'medium'}
+          >
+            {action.title}
+          </Text>
+          {action.description ? (
+            <Text emphasis="muted" variant="caption">
+              {action.description}
+            </Text>
+          ) : null}
+        </Stack>
+      </Box>
+      {action.trailing ? <Box>{action.trailing}</Box> : null}
+    </Inline>
+  );
+}

package/src/features/popover-menu/composition/usePopoverMenuController.ts

@@ -0,0 +1,55 @@
+import React from 'react';
+
+import type { PopoverMenuAction } from '../../../types/popoverMenu';
+
+interface PopoverMenuControllerOptions {
+  actions: readonly PopoverMenuAction[];
+  closeOnSelect: boolean;
+  dismiss?: () => void;
+  passive: boolean;
+}
+
+/*** Owns PopoverMenu visibility, active action state, and selection behavior. */
+export function usePopoverMenuController({
+  actions,
+  closeOnSelect,
+  dismiss,
+  passive,
+}: PopoverMenuControllerOptions) {
+  const [open, setOpen] = React.useState(false);
+  const [activeIndex, setActiveIndex] = React.useState(0);
+
+  const handleOpenChange = React.useCallback(
+    (nextOpen: boolean) => {
+      if (nextOpen) setActiveIndex(resolveInitialIndex(actions));
+      if (open && !nextOpen) dismiss?.();
+      setOpen(nextOpen);
+    },
+    [actions, dismiss, open],
+  );
+
+  const close = React.useCallback(() => handleOpenChange(false), [handleOpenChange]);
+  const activateAction = React.useCallback(
+    (action: PopoverMenuAction) => {
+      if (action.disabled || passive) return;
+      action.activate?.();
+      if (closeOnSelect) close();
+    },
+    [close, closeOnSelect, passive],
+  );
+
+  return {
+    activeIndex,
+    activateAction,
+    close,
+    handleOpenChange,
+    open,
+    setActiveIndex,
+  } as const;
+}
+
+/*** Returns the first enabled action index for a newly opened menu. */
+function resolveInitialIndex(actions: readonly PopoverMenuAction[]): number {
+  const index = actions.findIndex((action) => !action.disabled);
+  return index === -1 ? 0 : index;
+}

package/src/features/popover-menu/public.test.ts

@@ -0,0 +1,13 @@
+import { expect, test } from 'bun:test';
+
+test('PopoverMenu composes Popover instead of owning anchor and portal mechanics', async () => {
+  const source = await Bun.file(
+    'src/features/popover-menu/adapters/inbound/PopoverMenu.tsx',
+  ).text();
+
+  expect(source).toContain("import { Popover } from '../../../popover/public';");
+  expect(source).toContain('<Popover');
+  expect(source).not.toContain('measureInWindow');
+  expect(source).not.toContain('internal/overlay');
+  expect(source).not.toContain('<Portal');
+});

package/src/features/popover-menu/public.ts

@@ -0,0 +1,6 @@
+export type {
+  PopoverMenuAction,
+  PopoverMenuActionIntent,
+  PopoverMenuProps,
+} from '../../types/popoverMenu';
+export { PopoverMenu } from './adapters/inbound/PopoverMenu';

package/src/{components/menu/navigation.test.ts → features/popover-menu/utils/resolveNextMenuIndex.test.ts}

@@ -1,11 +1,11 @@
 import { describe, expect, it } from 'bun:test';
 
-import { resolveNextMenuIndex } from './navigation';
+import { resolveNextMenuIndex } from './resolveNextMenuIndex';
 
 describe('resolveNextMenuIndex', () => {
-  const items = [{}, { disabled: true }, {}, {}];
+  const items = [{}, { disabled: true }, {}, {}] as const;
 
-  it('cycles down and up through the menu items', () => {
+  it('cycles down and up through enabled actions', () => {
     expect(resolveNextMenuIndex(items, 0, 'ArrowDown')).toBe(2);
     expect(resolveNextMenuIndex(items, 0, 'ArrowUp')).toBe(3);
   });
@@ -15,7 +15,7 @@ describe('resolveNextMenuIndex', () => {
     expect(resolveNextMenuIndex(items, 0, 'End')).toBe(3);
   });
 
-  it('returns -1 when all items are disabled', () => {
+  it('returns -1 when all actions are disabled', () => {
     expect(resolveNextMenuIndex([{ disabled: true }], 0, 'ArrowDown')).toBe(-1);
   });
 });

package/src/features/popover-menu/utils/resolveNextMenuIndex.ts

@@ -0,0 +1,21 @@
+/*** Resolves the next enabled action index for standard menu keyboard navigation. */
+export function resolveNextMenuIndex(
+  items: readonly { disabled?: boolean }[],
+  currentIndex: number,
+  key: string,
+): number {
+  const enabledIndexes = items.flatMap((item, index) => (item.disabled ? [] : [index]));
+  if (enabledIndexes.length === 0) return -1;
+  if (key === 'Home') return enabledIndexes.at(0) ?? -1;
+  if (key === 'End') return enabledIndexes.at(-1) ?? -1;
+
+  const activeEnabledIndex = enabledIndexes.indexOf(currentIndex);
+  const nextEnabledIndex =
+    activeEnabledIndex === -1
+      ? 0
+      : key === 'ArrowUp'
+        ? (activeEnabledIndex - 1 + enabledIndexes.length) % enabledIndexes.length
+        : (activeEnabledIndex + 1) % enabledIndexes.length;
+
+  return enabledIndexes.at(nextEnabledIndex) ?? -1;
+}

package/src/features/tooltip/adapters/inbound/Tooltip.tsx

@@ -0,0 +1,56 @@
+import React from 'react';
+import { Platform, Pressable, View } from 'react-native';
+
+import { useTheme } from '../../../../theme/ThemeContext';
+import type { TooltipProps } from '../../../../types/tooltip';
+import { Popover } from '../../../popover/public';
+import { Surface } from '../../../surface/public';
+import { Text } from '../../../typography/public';
+import { useTooltipVisibility } from '../../composition/useTooltipVisibility';
+
+/*** Presents delayed hover/focus help through the shared Popover foundation. */
+export function Tooltip({
+  children,
+  content,
+  delay = 150,
+  interactionPolicy = 'enabled',
+  placement = 'top',
+  testID,
+}: TooltipProps) {
+  const { theme } = useTheme();
+  const passive = interactionPolicy === 'passive';
+  const { hide, setVisible, show, visible } = useTooltipVisibility(delay, passive);
+
+  return (
+    <Popover
+      closeOnOutsidePress={false}
+      interactionPolicy={interactionPolicy}
+      onOpenChange={setVisible}
+      open={visible}
+      placement={placement}
+      testID={testID}
+      anchor={() => (
+        <Pressable
+          onBlur={passive ? undefined : hide}
+          onFocus={passive ? undefined : show}
+          onHoverIn={Platform.OS === 'web' && !passive ? show : undefined}
+          onHoverOut={Platform.OS === 'web' && !passive ? hide : undefined}
+        >
+          {children}
+        </Pressable>
+      )}
+    >
+      <View pointerEvents="none">
+        <Surface
+          p="s"
+          style={{ backgroundColor: theme.semantics.surface.inverse }}
+          variant="raised"
+        >
+          <Text emphasis="inverse" variant="caption">
+            {content}
+          </Text>
+        </Surface>
+      </View>
+    </Popover>
+  );
+}

package/src/features/tooltip/composition/useTooltipVisibility.ts

@@ -0,0 +1,29 @@
+import React from 'react';
+
+/*** Manages delayed tooltip visibility and timer cleanup. */
+export function useTooltipVisibility(delay: number, passive: boolean) {
+  const timeoutRef = React.useRef<ReturnType<typeof setTimeout> | null>(null);
+  const [visible, setVisible] = React.useState(false);
+
+  const clearTimer = React.useCallback(() => {
+    if (timeoutRef.current) {
+      clearTimeout(timeoutRef.current);
+      timeoutRef.current = null;
+    }
+  }, []);
+
+  const show = React.useCallback(() => {
+    if (passive) return;
+    clearTimer();
+    timeoutRef.current = setTimeout(() => setVisible(true), delay);
+  }, [clearTimer, delay, passive]);
+
+  const hide = React.useCallback(() => {
+    clearTimer();
+    setVisible(false);
+  }, [clearTimer]);
+
+  React.useEffect(() => clearTimer, [clearTimer]);
+
+  return { hide, setVisible, show, visible } as const;
+}

package/src/features/tooltip/public.test.ts

@@ -0,0 +1,11 @@
+import { expect, test } from 'bun:test';
+
+test('Tooltip delegates anchored positioning and portal ownership to Popover', async () => {
+  const source = await Bun.file('src/features/tooltip/adapters/inbound/Tooltip.tsx').text();
+
+  expect(source).toContain("import { Popover } from '../../../popover/public';");
+  expect(source).toContain('<Popover');
+  expect(source).not.toContain('measureInWindow');
+  expect(source).not.toContain('internal/overlay');
+  expect(source).not.toContain('<Portal');
+});

package/src/features/tooltip/public.ts

@@ -0,0 +1,2 @@
+export type { TooltipProps } from '../../types/tooltip';
+export { Tooltip } from './adapters/inbound/Tooltip';