@tamagui/create-menu 2.0.0-rc.8 → 2.0.0

package/src/createBaseMenu.tsx

@@ -15,16 +15,18 @@ import type { RovingFocusGroupProps } from '@tamagui/roving-focus'
 import { RovingFocusGroup } from '@tamagui/roving-focus'
 import { useCallbackRef } from '@tamagui/use-callback-ref'
 import { useDirection } from '@tamagui/use-direction'
-import type { TamaguiComponent, TextProps } from '@tamagui/web'
+import type { TextProps } from '@tamagui/web'
 import {
   type ViewProps,
   composeEventHandlers,
   composeRefs,
   createStyledContext,
   isWeb,
+  styled,
   Text,
   Theme,
   useComposedRefs,
+  useIsTouchDevice,
   useThemeName,
   View,
   withStaticProperties,
@@ -215,6 +217,11 @@ type MenuItemElement = MenuItemImplElement
 interface MenuItemProps extends Omit<MenuItemImplProps, 'onSelect'> {
   onSelect?: (event: Event) => void
   unstyled?: boolean
+  /**
+   * Prevents the menu from closing when this item is selected.
+   * Useful for toggle items or multi-select scenarios.
+   */
+  preventCloseOnSelect?: boolean
 }
 
 type MenuItemImplElement = TamaguiElement
@@ -369,15 +376,15 @@ const { Provider: MenuRootProvider, useStyledContext: useMenuRootContext } =
 const MENU_CONTEXT = 'MenuContext'
 
 export type CreateBaseMenuProps = {
-  Item?: TamaguiComponent
-  MenuGroup?: TamaguiComponent
-  Title?: TamaguiComponent
-  SubTitle?: TamaguiComponent
+  Item?: typeof MenuPredefined.MenuItem
+  MenuGroup?: typeof MenuPredefined.MenuGroup
+  Title?: typeof MenuPredefined.Title
+  SubTitle?: typeof MenuPredefined.SubTitle
   Image?: React.ElementType
-  Icon?: TamaguiComponent
-  Indicator?: TamaguiComponent
-  Separator?: TamaguiComponent
-  Label?: TamaguiComponent
+  Icon?: typeof MenuPredefined.MenuIcon
+  Indicator?: typeof MenuPredefined.MenuIndicator
+  Separator?: typeof MenuPredefined.MenuSeparator
+  Label?: typeof MenuPredefined.MenuLabel
 }
 
 export function createBaseMenu({
@@ -392,6 +399,9 @@ export function createBaseMenu({
   Label: _Label = MenuPredefined.MenuLabel,
 }: CreateBaseMenuProps) {
   const MenuComp = (props: ScopedProps<MenuBaseProps>) => {
+    const direction = useDirection(props.dir)
+    // default placement: bottom-start for LTR, bottom-end for RTL
+    const defaultPlacement = direction === 'rtl' ? 'bottom-end' : 'bottom-start'
     const {
       scope = MENU_CONTEXT,
       open = false,
@@ -401,12 +411,14 @@ export function createBaseMenu({
       modal = true,
       allowFlip = { padding: 10 },
       stayInFrame = { padding: 10 },
+      placement = defaultPlacement,
+      resize = true,
+      offset = 10,
       ...rest
     } = props
     const [content, setContent] = React.useState<MenuContentElement | null>(null)
     const isUsingKeyboardRef = React.useRef(false)
     const handleOpenChange = useCallbackRef(onOpenChange)
-    const direction = useDirection(dir)
 
     if (isWeb) {
       React.useEffect(() => {
@@ -437,8 +449,12 @@ export function createBaseMenu({
     return (
       <PopperPrimitive.Popper
         scope={scope}
+        open={open}
+        placement={placement}
         allowFlip={allowFlip}
         stayInFrame={stayInFrame}
+        resize={resize}
+        offset={offset}
         {...rest}
       >
         <MenuProvider
@@ -556,7 +572,7 @@ export function createBaseMenu({
 
     return (
       <Animate type="presence" present={isPresent}>
-        <PortalPrimitive>
+        <PortalPrimitive stackZIndex>
           <>
             <PortalProvider scope={scope} forceMount={forceMount}>
               <View zIndex={zIndex || 100} inset={0} position="absolute">
@@ -587,7 +603,11 @@ export function createBaseMenu({
   const { Provider: MenuContentProvider, useStyledContext: useMenuContentContext } =
     createStyledContext<MenuContentContextValue>()
 
-  const MenuContent = React.forwardRef<MenuContentElement, ScopedProps<MenuContentProps>>(
+  const MenuContentFrame = styled(PopperPrimitive.PopperContentFrame, {
+    name: CONTENT_NAME,
+  })
+
+  const MenuContent = MenuContentFrame.styleable<ScopedProps<MenuContentProps>>(
     (props, forwardedRef) => {
       const scope = props.scope || MENU_CONTEXT
       const portalContext = usePortalContext(scope)
@@ -694,9 +714,13 @@ export function createBaseMenu({
 
     const context = useMenuContext(scope)
     const rootContext = useMenuRootContext(scope)
+    const popperContext = PopperPrimitive.usePopperContext(scope)
     const getItems = useCollection(scope)
     const [currentItemId, setCurrentItemId] = React.useState<string | null>(null)
     const contentRef = React.useRef<TamaguiElement>(null)
+    // the actual focusable content element (PopperContentFrame) differs from contentRef
+    // due to PopperContent's wrapper structure, so we capture it on mount
+    const focusableContentRef = React.useRef<HTMLElement | null>(null)
     const composedRefs = useComposedRefs(
       forwardedRef,
       contentRef,
@@ -740,17 +764,54 @@ export function createBaseMenu({
       return () => clearTimeout(timerRef.current)
     }, [])
 
-    // dismiss on scroll (web only)
+    // capture the actual focusable content element on mount
+    // PopperContent has a wrapper structure where the ref points to the outer
+    // TamaguiView but props like tabIndex go to the inner PopperContentFrame
+    React.useEffect(() => {
+      if (!isWeb || !context.open) return
+      // use requestAnimationFrame to ensure DOM is ready
+      const frame = requestAnimationFrame(() => {
+        // scope the query to within this menu's content to avoid grabbing a submenu's element
+        const container = contentRef.current as unknown as HTMLElement
+        const el = container?.querySelector('[data-tamagui-menu-content]') as HTMLElement
+        if (el) focusableContentRef.current = el
+      })
+      return () => cancelAnimationFrame(frame)
+    }, [context.open])
+
+    // dismiss on scroll (web only) - only when the scroll actually moves the
+    // menu's anchor. a scroll in an unrelated subtree leaves the menu's
+    // position unchanged, so it should not dismiss.
     React.useEffect(() => {
       if (!isWeb || disableDismissOnScroll || !context.open) return
-      const handleScroll = () => {
+      const handleScroll = (event: Event) => {
+        const scrolled = event.target as Node | null
+        if (!scrolled) return
+        // never dismiss when scrolling within the menu's own content
+        const content = contentRef.current as unknown as HTMLElement | null
+        if (content?.contains(scrolled)) return
+        // resolve the menu's anchor element (the trigger). a virtual reference
+        // (e.g. a context menu pinned to a point) may expose its DOM origin
+        // via `contextElement`.
+        const reference = popperContext.refs?.reference?.current as
+          | Element
+          | { contextElement?: Element | null }
+          | null
+          | undefined
+        const anchor =
+          reference instanceof Element ? reference : (reference?.contextElement ?? null)
+        // when we can see the anchor element, only dismiss if the scrolled
+        // container actually contains it - i.e. this scroll moved the menu
+        // relative to the viewport. window/document scrolls have `document`
+        // as the target, which contains the anchor, so those still dismiss.
+        if (anchor && !scrolled.contains(anchor)) return
         onDismiss?.()
       }
       window.addEventListener('scroll', handleScroll, { capture: true, passive: true })
       return () => {
         window.removeEventListener('scroll', handleScroll, { capture: true })
       }
-    }, [disableDismissOnScroll, context.open, onDismiss])
+    }, [disableDismissOnScroll, context.open, onDismiss, popperContext.refs])
 
     // Make sure the whole tree has focus guards as our `MenuContent` may be
     // the last element in the DOM (beacuse of the `Portal`)
@@ -768,8 +829,11 @@ export function createBaseMenu({
     const content = (
       <PopperPrimitive.PopperContent
         role="menu"
+        // tabIndex allows the content to be focusable so that onItemLeave can
+        // focus the content frame and properly blur the previously focused item
+        tabIndex={-1}
+        unstyled={unstyled}
         {...(!unstyled && {
-          padding: 4,
           backgroundColor: '$background',
           borderWidth: 1,
           borderColor: '$borderColor',
@@ -858,7 +922,7 @@ export function createBaseMenu({
         onItemLeave={React.useCallback(
           (event) => {
             if (isPointerMovingToSubmenu(event)) return
-            contentRef.current?.focus()
+            focusableContentRef.current?.focus()
             setCurrentItemId(null)
           },
           [isPointerMovingToSubmenu]
@@ -888,7 +952,7 @@ export function createBaseMenu({
               const content = document.querySelector(
                 '[data-tamagui-menu-content]'
               ) as HTMLElement | null
-              content?.focus()
+              content?.focus({ preventScroll: true })
             })}
             onUnmountAutoFocus={onCloseAutoFocus}
           >
@@ -935,106 +999,109 @@ export function createBaseMenu({
   const ITEM_NAME = 'MenuItem'
   const ITEM_SELECT = 'menu.itemSelect'
 
-  const MenuItem = React.forwardRef<TamaguiElement, ScopedProps<MenuItemProps>>(
-    (props, forwardedRef) => {
-      const {
-        disabled = false,
-        onSelect,
-        children,
-        scope = MENU_CONTEXT,
-        // filter out native-only props that shouldn't reach the DOM
-        // @ts-ignore
-        destructive,
-        // @ts-ignore
-        hidden,
-        // @ts-ignore
-        androidIconName,
-        // @ts-ignore
-        iosIconName,
-        ...itemProps
-      } = props
-      const ref = React.useRef<TamaguiElement>(null)
-      const rootContext = useMenuRootContext(scope)
-      const contentContext = useMenuContentContext(scope)
-      const composedRefs = useComposedRefs(forwardedRef, ref)
-      const isPointerDownRef = React.useRef(false)
-
-      const handleSelect = () => {
-        const menuItem = ref.current
-        if (!disabled && menuItem) {
-          if (isWeb) {
-            const menuItemEl = menuItem as HTMLElement
-            const itemSelectEvent = new CustomEvent(ITEM_SELECT, {
-              bubbles: true,
-              cancelable: true,
-            })
-            menuItemEl.addEventListener(ITEM_SELECT, (event) => onSelect?.(event), {
-              once: true,
-            })
-            dispatchDiscreteCustomEvent(menuItemEl, itemSelectEvent)
-            if (itemSelectEvent.defaultPrevented) {
-              isPointerDownRef.current = false
-            } else {
-              rootContext.onClose()
-            }
-          } else {
-            // TODO: find a better way to handle this on native
-            onSelect?.({ target: menuItem } as unknown as Event)
+  // use styleable so styled(Menu.Item, { focusStyle }) passes pseudo styles through correctly
+  const MenuItem = _Item.styleable<ScopedProps<MenuItemProps>>((props, forwardedRef) => {
+    const {
+      disabled = false,
+      onSelect,
+      preventCloseOnSelect,
+      children,
+      scope = MENU_CONTEXT,
+      // filter out native-only props that shouldn't reach the DOM
+      // @ts-ignore
+      destructive,
+      // @ts-ignore
+      hidden,
+      // @ts-ignore
+      androidIconName,
+      // @ts-ignore
+      iosIconName,
+      ...itemProps
+    } = props
+    const ref = React.useRef<TamaguiElement>(null)
+    const rootContext = useMenuRootContext(scope)
+    const contentContext = useMenuContentContext(scope)
+    const composedRefs = useComposedRefs(forwardedRef, ref)
+    const isPointerDownRef = React.useRef(false)
+
+    const handleSelect = () => {
+      const menuItem = ref.current
+      if (!disabled && menuItem) {
+        if (isWeb) {
+          const menuItemEl = menuItem as HTMLElement
+          const itemSelectEvent = new CustomEvent(ITEM_SELECT, {
+            bubbles: true,
+            cancelable: true,
+          })
+          menuItemEl.addEventListener(ITEM_SELECT, (event) => onSelect?.(event), {
+            once: true,
+          })
+          dispatchDiscreteCustomEvent(menuItemEl, itemSelectEvent)
+          // close the menu unless preventCloseOnSelect is set or event.preventDefault() was called
+          if (itemSelectEvent.defaultPrevented || preventCloseOnSelect) {
             isPointerDownRef.current = false
+          } else {
+            rootContext.onClose()
+          }
+        } else {
+          // TODO: find a better way to handle this on native
+          onSelect?.({ target: menuItem } as unknown as Event)
+          isPointerDownRef.current = false
+          if (!preventCloseOnSelect) {
             rootContext.onClose()
           }
         }
       }
+    }
 
-      const content = typeof children === 'string' ? <Text>{children}</Text> : children
+    const content = typeof children === 'string' ? <Text>{children}</Text> : children
 
-      return (
-        <MenuItemImpl
-          outlineStyle="none"
-          {...itemProps}
-          scope={scope}
-          // @ts-ignore
-          ref={composedRefs}
-          disabled={disabled}
-          onPress={composeEventHandlers(props.onPress, handleSelect)}
-          onPointerDown={(event) => {
-            props.onPointerDown?.(event)
-            isPointerDownRef.current = true
-          }}
-          onPointerUp={composeEventHandlers(props.onPointerUp, (event) => {
-            // Pointer down can move to a different menu item which should activate it on pointer up.
-            // We dispatch a click for selection to allow composition with click based triggers and to
-            // prevent Firefox from getting stuck in text selection mode when the menu closes.
-            if (isWeb) {
-              // @ts-ignore
-              if (!isPointerDownRef.current) event.currentTarget?.click()
+    return (
+      <MenuItemImpl
+        outlineStyle="none"
+        {...itemProps}
+        scope={scope}
+        // @ts-ignore
+        ref={composedRefs}
+        disabled={disabled}
+        onPress={composeEventHandlers(props.onPress, handleSelect)}
+        onPointerDown={(event) => {
+          props.onPointerDown?.(event)
+          isPointerDownRef.current = true
+        }}
+        onPointerUp={composeEventHandlers(props.onPointerUp, (event) => {
+          // Pointer down can move to a different menu item which should activate it on pointer up.
+          // We dispatch a click for selection to allow composition with click based triggers and to
+          // prevent Firefox from getting stuck in text selection mode when the menu closes.
+          if (isWeb) {
+            // @ts-ignore
+            if (!isPointerDownRef.current) event.currentTarget?.click()
+          }
+        })}
+        {...(isWeb
+          ? {
+              onKeyDown: composeEventHandlers(props.onKeyDown, (event) => {
+                const isTypingAhead = contentContext.searchRef.current !== ''
+                if (disabled || (isTypingAhead && event.key === ' ')) return
+                if (SELECTION_KEYS.includes(event.key)) {
+                  // @ts-ignore
+                  event.currentTarget?.click()
+                  /**
+                   * We prevent default browser behaviour for selection keys as they should trigger
+                   * a selection only:
+                   * - prevents space from scrolling the page.
+                   * - if keydown causes focus to move, prevents keydown from firing on the new target.
+                   */
+                  event.preventDefault()
+                }
+              }),
             }
-          })}
-          {...(isWeb
-            ? {
-                onKeyDown: composeEventHandlers(props.onKeyDown, (event) => {
-                  const isTypingAhead = contentContext.searchRef.current !== ''
-                  if (disabled || (isTypingAhead && event.key === ' ')) return
-                  if (SELECTION_KEYS.includes(event.key)) {
-                    // @ts-ignore
-                    event.currentTarget?.click()
-                    /**
-                     * We prevent default browser behaviour for selection keys as they should trigger
-                     * a selection only:
-                     * - prevents space from scrolling the page.
-                     * - if keydown causes focus to move, prevents keydown from firing on the new target.
-                     */
-                    event.preventDefault()
-                  }
-                }),
-              }
-            : {})}
-        >
-          {content}
-        </MenuItemImpl>
-      )
-    }
-  )
+          : {})}
+      >
+        {content}
+      </MenuItemImpl>
+    )
+  })
 
   const MenuItemImpl = React.forwardRef<
     MenuItemImplElement,
@@ -1074,13 +1141,9 @@ export function createBaseMenu({
           asChild
           __scopeRovingFocusGroup={scope}
           focusable={!disabled}
-          {...(!unstyled && {
-            flexDirection: 'row',
-            alignItems: 'center',
-          })}
-          {...itemProps}
         >
           <_Item
+            unstyled={unstyled}
             componentName={ITEM_NAME}
             role="menuitem"
             data-highlighted={isFocused ? '' : undefined}
@@ -1206,40 +1269,39 @@ export function createBaseMenu({
 
   const CHECKBOX_ITEM_NAME = 'MenuCheckboxItem'
 
-  const MenuCheckboxItem = React.forwardRef<
-    TamaguiElement,
-    ScopedProps<MenuCheckboxItemProps>
-  >((props, forwardedRef) => {
-    const {
-      checked = false,
-      onCheckedChange,
-      scope = MENU_CONTEXT,
-      // filter out native-only props
-      // @ts-ignore - native menu value state
-      value,
-      // @ts-ignore - native menu value change handler
-      onValueChange,
-      ...checkboxItemProps
-    } = props
-    return (
-      <ItemIndicatorProvider scope={scope} checked={checked}>
-        <MenuItem
-          componentName={CHECKBOX_ITEM_NAME}
-          role={(isWeb ? 'menuitemcheckbox' : 'menuitem') as 'menuitem'}
-          aria-checked={isIndeterminate(checked) ? 'mixed' : checked}
-          {...checkboxItemProps}
-          scope={scope}
-          ref={forwardedRef}
-          data-state={getCheckedState(checked)}
-          onSelect={composeEventHandlers(
-            checkboxItemProps.onSelect,
-            () => onCheckedChange?.(isIndeterminate(checked) ? true : !checked),
-            { checkDefaultPrevented: false }
-          )}
-        />
-      </ItemIndicatorProvider>
-    )
-  })
+  const MenuCheckboxItem = _Item.styleable<ScopedProps<MenuCheckboxItemProps>>(
+    (props, forwardedRef) => {
+      const {
+        checked = false,
+        onCheckedChange,
+        scope = MENU_CONTEXT,
+        // filter out native-only props
+        // @ts-ignore - native menu value state
+        value,
+        // @ts-ignore - native menu value change handler
+        onValueChange,
+        ...checkboxItemProps
+      } = props
+      return (
+        <ItemIndicatorProvider scope={scope} checked={checked}>
+          <MenuItem
+            componentName={CHECKBOX_ITEM_NAME}
+            role={(isWeb ? 'menuitemcheckbox' : 'menuitem') as 'menuitem'}
+            aria-checked={isIndeterminate(checked) ? 'mixed' : checked}
+            {...checkboxItemProps}
+            scope={scope}
+            ref={forwardedRef}
+            data-state={getCheckedState(checked)}
+            onSelect={composeEventHandlers(
+              checkboxItemProps.onSelect,
+              () => onCheckedChange?.(isIndeterminate(checked) ? true : !checked),
+              { checkDefaultPrevented: false }
+            )}
+          />
+        </ItemIndicatorProvider>
+      )
+    }
+  )
 
   MenuCheckboxItem.displayName = CHECKBOX_ITEM_NAME
   /* -------------------------------------------------------------------------------------------------
@@ -1274,7 +1336,7 @@ export function createBaseMenu({
 
   const RADIO_ITEM_NAME = 'MenuRadioItem'
 
-  const MenuRadioItem = React.forwardRef<TamaguiElement, ScopedProps<MenuRadioItemProps>>(
+  const MenuRadioItem = _Item.styleable<ScopedProps<MenuRadioItemProps>>(
     (props, forwardedRef) => {
       const { value, scope = MENU_CONTEXT, ...radioItemProps } = props
       const context = useRadioGroupContext(scope)
@@ -1351,6 +1413,7 @@ export function createBaseMenu({
         <PopperPrimitive.PopperArrow
           scope={scope}
           componentName="PopperArrow"
+          unstyled={unstyled}
           {...(!unstyled && {
             backgroundColor: '$background',
           })}
@@ -1371,15 +1434,58 @@ export function createBaseMenu({
     createStyledContext<MenuSubContextValue>()
 
   const MenuSub: React.FC<ScopedProps<MenuSubProps>> = (props) => {
+    const isTouchDevice = useIsTouchDevice()
+    const { scope = MENU_CONTEXT } = props
+    const rootContext = useMenuRootContext(scope)
+
+    // detect if this sub is nested inside another sub that opened to a side
+    const parentPopperContext = PopperPrimitive.usePopperContext(scope)
+    const parentSide = parentPopperContext.placement?.split('-')[0]
+    const isNestedSubmenu = parentSide === 'left' || parentSide === 'right'
+
+    // nested submenus inherit the parent's direction so they cascade
+    // rather than flipping back on top of the grandparent
+    const defaultPlacement = isTouchDevice
+      ? 'bottom'
+      : isNestedSubmenu
+        ? (`${parentSide}-start` as any)
+        : rootContext.dir === 'rtl'
+          ? 'left-start'
+          : 'right-start'
     const {
-      scope = MENU_CONTEXT,
       children,
       open = false,
       onOpenChange,
-      allowFlip = { padding: 10 },
+      allowFlip: allowFlipProp = { padding: 10 },
       stayInFrame = { padding: 10 },
+      placement = defaultPlacement,
       ...rest
     } = props
+
+    // for nested submenus, flip to opposite side (never top/bottom which overlap parent)
+    const allowFlip = React.useMemo(() => {
+      if (!isNestedSubmenu || typeof allowFlipProp === 'boolean') return allowFlipProp
+      if ((allowFlipProp as any).fallbackPlacements) return allowFlipProp
+
+      const side = placement.split('-')[0]
+      const align = placement.split('-')[1] || 'start'
+      const otherAlign = align === 'start' ? 'end' : 'start'
+
+      if (side === 'left' || side === 'right') {
+        const oppositeSide = side === 'right' ? 'left' : 'right'
+        return {
+          ...(typeof allowFlipProp === 'object' ? allowFlipProp : {}),
+          fallbackPlacements: [
+            `${side}-${otherAlign}`,
+            `${oppositeSide}-${align}`,
+            `${oppositeSide}-${otherAlign}`,
+          ] as any,
+        }
+      }
+
+      return allowFlipProp
+    }, [isNestedSubmenu, allowFlipProp, placement])
+
     const parentMenuContext = useMenuContext(scope)
     const [trigger, setTrigger] = React.useState<MenuSubTriggerElement | null>(null)
     const [content, setContent] = React.useState<MenuContentElement | null>(null)
@@ -1393,6 +1499,8 @@ export function createBaseMenu({
 
     return (
       <PopperPrimitive.Popper
+        open={open}
+        placement={placement}
         allowFlip={allowFlip}
         stayInFrame={stayInFrame}
         {...rest}
@@ -1439,15 +1547,9 @@ export function createBaseMenu({
     const openTimerRef = React.useRef<number | null>(null)
     const { pointerGraceTimerRef, onPointerGraceIntentChange } = contentContext
 
-    // determine effective direction for keyboard navigation based on placement
-    // if submenu opens to the left, arrow keys should be flipped
-    const placementSide = popperContext.placement?.split('-')[0]
-    const effectiveDir: Direction =
-      placementSide === 'left'
-        ? 'rtl'
-        : placementSide === 'right'
-          ? 'ltr'
-          : rootContext.dir
+    // keyboard navigation follows text direction, not placement side
+    // ArrowRight always opens, ArrowLeft always closes (flipped only for RTL)
+    const effectiveDir: Direction = rootContext.dir
 
     const clearOpenTimer = React.useCallback(() => {
       if (openTimerRef.current) window.clearTimeout(openTimerRef.current)
@@ -1673,114 +1775,113 @@ export function createBaseMenu({
 
   const SUB_CONTENT_NAME = 'MenuSubContent'
 
-  const MenuSubContent = React.forwardRef<
-    MenuSubContentElement,
-    ScopedProps<MenuSubContentProps>
-  >((props, forwardedRef) => {
-    const scope = props.scope || MENU_CONTEXT
-    const portalContext = usePortalContext(scope)
-    const { forceMount = portalContext.forceMount, ...subContentProps } = props
-    const context = useMenuContext(scope)
-    const rootContext = useMenuRootContext(scope)
-    const subContext = useMenuSubContext(scope)
-    const popperContext = PopperPrimitive.usePopperContext(scope)
-    const ref = React.useRef<MenuSubContentElement>(null)
-    const composedRefs = useComposedRefs(forwardedRef, ref)
+  const MenuSubContentFrame = styled(PopperPrimitive.PopperContentFrame, {
+    name: SUB_CONTENT_NAME,
+  })
 
-    // determine side from actual placement, not just RTL direction
-    // placement like "left-start" or "right-end" - extract the side
-    const placementSide = popperContext.placement?.split('-')[0] as
-      | 'left'
-      | 'right'
-      | 'top'
-      | 'bottom'
-      | undefined
-    // for submenus, we care about horizontal placement (left/right)
-    // default to 'right' for LTR, 'left' for RTL
-    const dataSide: Side =
-      placementSide === 'left' || placementSide === 'right'
-        ? placementSide
-        : rootContext.dir === 'rtl'
-          ? 'left'
-          : 'right'
+  const MenuSubContent = MenuSubContentFrame.styleable<ScopedProps<MenuSubContentProps>>(
+    (props, forwardedRef) => {
+      const scope = props.scope || MENU_CONTEXT
+      const portalContext = usePortalContext(scope)
+      const { forceMount = portalContext.forceMount, ...subContentProps } = props
+      const context = useMenuContext(scope)
+      const rootContext = useMenuRootContext(scope)
+      const subContext = useMenuSubContext(scope)
+      const popperContext = PopperPrimitive.usePopperContext(scope)
+      const ref = React.useRef<MenuSubContentElement>(null)
+      const composedRefs = useComposedRefs(forwardedRef, ref)
 
-    // effective direction for keyboard navigation - if submenu is on left, flip arrow keys
-    const effectiveDir: Direction =
-      placementSide === 'left'
-        ? 'rtl'
-        : placementSide === 'right'
-          ? 'ltr'
-          : rootContext.dir
+      // determine side from actual placement, not just RTL direction
+      // placement like "left-start" or "right-end" - extract the side
+      const placementSide = popperContext.placement?.split('-')[0] as
+        | 'left'
+        | 'right'
+        | 'top'
+        | 'bottom'
+        | undefined
+      // for submenus, we care about horizontal placement (left/right)
+      // default to 'right' for LTR, 'left' for RTL
+      const dataSide: Side =
+        placementSide === 'left' || placementSide === 'right'
+          ? placementSide
+          : rootContext.dir === 'rtl'
+            ? 'left'
+            : 'right'
+
+      // keyboard navigation follows text direction, not placement side
+      const effectiveDir: Direction = rootContext.dir
 
-    return (
-      <Collection.Provider scope={scope}>
-        <Collection.Slot scope={scope}>
-          <MenuContentImpl
-            id={subContext.contentId}
-            aria-labelledby={subContext.triggerId}
-            {...subContentProps}
-            ref={composedRefs}
-            data-side={dataSide}
-            disableOutsidePointerEvents={false}
-            disableOutsideScroll={false}
-            trapFocus={false}
-            onOpenAutoFocus={(event) => {
-              // when opening a submenu, focus content for keyboard users only
-              if (rootContext.isUsingKeyboardRef.current) {
-                // ref.current doesn't reliably point to the focusable DOM element,
-                // so we query for the submenu content directly
-                const content = document.querySelector(
-                  '[data-tamagui-menu-content][data-side]'
-                ) as HTMLElement | null
-                content?.focus()
-              }
-              event.preventDefault()
-            }}
-            // The menu might close because of focusing another menu item in the parent menu. We
-            // don't want it to refocus the trigger in that case so we handle trigger focus ourselves.
-            onCloseAutoFocus={(event) => event.preventDefault()}
-            onFocusOutside={composeEventHandlers(props.onFocusOutside, (event) => {
-              // We prevent closing when the trigger is focused to avoid triggering a re-open animation
-              // on pointer interaction.
-              if (event.target !== subContext.trigger) context.onOpenChange(false)
-            })}
-            onEscapeKeyDown={composeEventHandlers(props.onEscapeKeyDown, (event) => {
-              // close only this submenu, not the root menu
-              context.onOpenChange(false)
-              // return focus to the submenu trigger with focusVisible since this is keyboard navigation
-              // @ts-ignore focusVisible is a newer API
-              subContext.trigger?.focus({ focusVisible: true })
-              // ensure pressing escape in submenu doesn't escape full screen mode
-              event.preventDefault()
-            })}
-            {...(isWeb
-              ? {
-                  onKeyDown: composeEventHandlers(props.onKeyDown, (event) => {
-                    // Submenu key events bubble through portals. We only care about keys in this menu.
-                    // @ts-ignore
-                    const isKeyDownInside = event.currentTarget.contains(
-                      event.target as HTMLElement
-                    )
-                    // use effectiveDir so arrow keys match the submenu's actual position
-                    // (e.g., ArrowRight closes a left-side submenu)
-                    const isCloseKey = SUB_CLOSE_KEYS[effectiveDir].includes(event.key)
-                    if (isKeyDownInside && isCloseKey) {
-                      context.onOpenChange(false)
-                      // We focus manually because we prevented it in `onCloseAutoFocus`
-                      // use focusVisible: true since this is keyboard navigation
-                      // @ts-ignore focusVisible is a newer API
-                      subContext.trigger?.focus({ focusVisible: true })
-                      // prevent window from scrolling
-                      event.preventDefault()
-                    }
-                  }),
+      return (
+        <Collection.Provider scope={scope}>
+          <Collection.Slot scope={scope}>
+            <MenuContentImpl
+              id={subContext.contentId}
+              aria-labelledby={subContext.triggerId}
+              {...subContentProps}
+              ref={composedRefs}
+              data-side={dataSide}
+              disableOutsidePointerEvents={false}
+              disableOutsideScroll={false}
+              trapFocus={false}
+              onOpenAutoFocus={(event) => {
+                // when opening a submenu, focus content for keyboard users only
+                if (rootContext.isUsingKeyboardRef.current) {
+                  // scope query to this submenu's subtree so nested submenus
+                  // don't accidentally focus a sibling/parent submenu content
+                  const root = ref.current as unknown as HTMLElement
+                  const content = root?.querySelector?.(
+                    '[data-tamagui-menu-content]'
+                  ) as HTMLElement | null
+                  ;(content || root)?.focus({ preventScroll: true })
                 }
-              : null)}
-          />
-        </Collection.Slot>
-      </Collection.Provider>
-    )
-  })
+                event.preventDefault()
+              }}
+              // The menu might close because of focusing another menu item in the parent menu. We
+              // don't want it to refocus the trigger in that case so we handle trigger focus ourselves.
+              onCloseAutoFocus={(event) => event.preventDefault()}
+              onFocusOutside={composeEventHandlers(props.onFocusOutside, (event) => {
+                // We prevent closing when the trigger is focused to avoid triggering a re-open animation
+                // on pointer interaction.
+                if (event.target !== subContext.trigger) context.onOpenChange(false)
+              })}
+              onEscapeKeyDown={composeEventHandlers(props.onEscapeKeyDown, (event) => {
+                // close only this submenu, not the root menu
+                context.onOpenChange(false)
+                // return focus to the submenu trigger with focusVisible since this is keyboard navigation
+                // @ts-ignore focusVisible is a newer API
+                subContext.trigger?.focus({ focusVisible: true })
+                // ensure pressing escape in submenu doesn't escape full screen mode
+                event.preventDefault()
+              })}
+              {...(isWeb
+                ? {
+                    onKeyDown: composeEventHandlers(props.onKeyDown, (event) => {
+                      // Submenu key events bubble through portals. We only care about keys in this menu.
+                      // @ts-ignore
+                      const isKeyDownInside = event.currentTarget.contains(
+                        event.target as HTMLElement
+                      )
+                      // use effectiveDir so arrow keys match the submenu's actual position
+                      // (e.g., ArrowRight closes a left-side submenu)
+                      const isCloseKey = SUB_CLOSE_KEYS[effectiveDir].includes(event.key)
+                      if (isKeyDownInside && isCloseKey) {
+                        context.onOpenChange(false)
+                        // We focus manually because we prevented it in `onCloseAutoFocus`
+                        // use focusVisible: true since this is keyboard navigation
+                        // @ts-ignore focusVisible is a newer API
+                        subContext.trigger?.focus({ focusVisible: true })
+                        // prevent window from scrolling
+                        event.preventDefault()
+                      }
+                    }),
+                  }
+                : null)}
+            />
+          </Collection.Slot>
+        </Collection.Provider>
+      )
+    }
+  )
 
   MenuSubContent.displayName = SUB_CONTENT_NAME
 
@@ -1860,7 +1961,7 @@ function focusFirst(candidates: HTMLElement[], options?: { focusVisible?: boolea
     // if focus is already where we want to go, we don't want to keep going through the candidates
     if (candidate === PREVIOUSLY_FOCUSED_ELEMENT) return
     // @ts-ignore focusVisible is a newer API not yet in all TS libs
-    candidate.focus({ focusVisible: options?.focusVisible })
+    candidate.focus({ preventScroll: true, focusVisible: options?.focusVisible })
     if (document.activeElement !== PREVIOUSLY_FOCUSED_ELEMENT) return
   }
 }