@tamagui/popper 2.0.0-rc.9 → 2.0.0

package/src/Popper.tsx

@@ -1,20 +1,24 @@
 // adapted from radix-ui popper
+import { flushSync } from 'react-dom'
 import { useComposedRefs } from '@tamagui/compose-refs'
 import { isWeb, useIsomorphicLayoutEffect } from '@tamagui/constants'
-import type { SizeTokens, ViewProps, TamaguiElement } from '@tamagui/core'
+import type { SizeTokens, TamaguiElement, ViewProps } from '@tamagui/core'
 import {
   LayoutMeasurementController,
   View as TamaguiView,
   createStyledContext,
   getVariableValue,
+  registerLayoutNode,
   styled,
-  useProps,
 } from '@tamagui/core'
+import type { PopupTriggerMap } from '@tamagui/floating'
+import { FloatingOverrideContext } from '@tamagui/floating'
 import type {
   Coords,
   Middleware,
   OffsetOptions,
   Placement,
+  ReferenceType,
   Side,
   SizeOptions,
   Strategy,
@@ -22,8 +26,8 @@ import type {
 } from '@tamagui/floating'
 import {
   arrow,
-  autoUpdate,
   flip,
+  getOverflowAncestors,
   offset as offsetFn,
   platform,
   shift,
@@ -35,7 +39,7 @@ import type { SizableStackProps, YStackProps } from '@tamagui/stacks'
 import { YStack } from '@tamagui/stacks'
 import { startTransition } from '@tamagui/start-transition'
 import * as React from 'react'
-import { Keyboard, type View, useWindowDimensions } from 'react-native'
+import { Keyboard, useWindowDimensions } from 'react-native'
 
 type ShiftProps = typeof shift extends (options: infer Opts) => void ? Opts : never
 type FlipProps = typeof flip extends (options: infer Opts) => void ? Opts : never
@@ -70,15 +74,18 @@ export const PopperPositionContext = createStyledContext
 export const { useStyledContext: usePopperContext, Provider: PopperProviderFast } =
   PopperContextFast
 
-export type PopperContextSlowValue = PopperContextShared &
-  Pick<
-    UseFloatingReturn,
-    'context' | 'getReferenceProps' | 'getFloatingProps' | 'strategy' | 'update' | 'refs'
-  >
+export type PopperContextSlowValue = Pick<
+  UseFloatingReturn,
+  'getReferenceProps' | 'update' | 'refs'
+> & {
+  onHoverReference?: (event: any) => void
+  onLeaveReference?: () => void
+  triggerElements?: PopupTriggerMap
+}
 
 export const PopperContextSlow = createStyledContext<PopperContextSlowValue>(
   // since we always provide this we can avoid setting here
-  {} as PopperContextValue,
+  {} as PopperContextSlowValue,
   'PopperSlow__'
 )
 
@@ -91,7 +98,32 @@ export const PopperProvider = ({
   children,
   ...context
 }: PopperContextValue & { scope?: string; children?: React.ReactNode }) => {
-  const slowContext = getContextSlow(context)
+  // single ref holds all unstable functions — updated every render so the
+  // stable wrappers below always forward to the latest version
+  const fns = React.useRef(context)
+  fns.current = context
+
+  // stable wrappers that never change identity — objectIdentityKey in
+  // createStyledContext produces the same key across renders, so PopperAnchor
+  // instances never re-render from context changes (only from parent re-renders)
+  const [slowContext] = React.useState(
+    (): PopperContextSlowValue => ({
+      refs: context.refs,
+      triggerElements: context.triggerElements,
+      update(...a: []) {
+        fns.current.update(...a)
+      },
+      getReferenceProps(p?: any) {
+        return fns.current.getReferenceProps?.(p)
+      },
+      onHoverReference(e?: any) {
+        ;(fns.current as any).onHoverReference?.(e)
+      },
+      onLeaveReference() {
+        ;(fns.current as any).onLeaveReference?.()
+      },
+    })
+  )
 
   return (
     <PopperProviderFast scope={scope} {...context}>
@@ -102,24 +134,6 @@ export const PopperProvider = ({
   )
 }
 
-// avoid position based re-rendering
-function getContextSlow(context: PopperContextValue): PopperContextSlowValue {
-  return {
-    refs: context.refs,
-    size: context.size,
-    arrowRef: context.arrowRef,
-    arrowStyle: context.arrowStyle,
-    onArrowSize: context.onArrowSize,
-    hasFloating: context.hasFloating,
-    strategy: context.strategy,
-    update: context.update,
-    context: context.context,
-    getFloatingProps: context.getFloatingProps,
-    getReferenceProps: context.getReferenceProps,
-    open: context.open,
-  }
-}
-
 export type PopperProps = {
   /**
    * Popper is a component used by other components to create interfaces, so scope is required
@@ -141,7 +155,9 @@ export type PopperProps = {
   placement?: Placement
 
   /**
-   * Attempts to shift the content to stay within the windiw
+   * Shifts content horizontally to stay within viewport.
+   * Pass an object to override shift options (mainAxis, crossAxis, padding, etc).
+   * Defaults: { mainAxis: true, crossAxis: false, padding: 10 }
    * @see https://floating-ui.com/docs/shift
    */
   stayInFrame?: ShiftProps | boolean
@@ -246,6 +262,58 @@ const transformOriginMiddleware = (options: {
   },
 })
 
+// replaces floating-ui's autoUpdate with tamagui's batched IO measurement loop
+// keeps scroll/resize listeners for immediate response, but replaces per-element
+// ResizeObserver + IntersectionObserver with the shared layoutOnAnimationFrame loop
+function tamaguiAutoUpdate(
+  reference: ReferenceType,
+  floating: HTMLElement,
+  update: () => void
+): () => void {
+  // initial position
+  update()
+
+  // schedule a second update after layout/scroll events settle (e.g. focus-
+  // triggered scrolls that cause flip corrections)
+  let rafId = requestAnimationFrame(() => {
+    update()
+    rafId = 0
+  })
+
+  const cleanups: (() => void)[] = [
+    () => {
+      if (rafId) cancelAnimationFrame(rafId)
+    },
+  ]
+
+  // watch reference element via tamagui's IO measurement loop
+  // only watch reference, NOT floating — watching floating causes loops
+  // (computePosition sets position → rect changes → update → repeat)
+  if (reference instanceof HTMLElement) {
+    cleanups.push(registerLayoutNode(reference, update))
+  }
+
+  // scroll listeners for immediate response (only for real DOM elements)
+  const refAncestors = reference instanceof Element ? getOverflowAncestors(reference) : []
+  const ancestors = [...refAncestors, ...getOverflowAncestors(floating)]
+  const uniqueAncestors = [...new Set(ancestors)]
+  for (const ancestor of uniqueAncestors) {
+    ancestor.addEventListener('scroll', update, { passive: true })
+  }
+
+  // window resize
+  window.addEventListener('resize', update)
+
+  cleanups.push(() => {
+    for (const ancestor of uniqueAncestors) {
+      ancestor.removeEventListener('scroll', update)
+    }
+    window.removeEventListener('resize', update)
+  })
+
+  return () => cleanups.forEach((fn) => fn())
+}
+
 export function Popper(props: PopperProps) {
   const {
     children,
@@ -266,33 +334,35 @@ export function Popper(props: PopperProps) {
   const [arrowSize, setArrowSize] = React.useState(0)
   const offsetOptions = offset ?? arrowSize
   const floatingStyle = React.useRef({})
-  const isOpen = passThrough ? false : open || true
-
-  let floating = useFloating({
-    open: isOpen,
-    strategy,
-    placement,
-    sameScrollView: false, // this only takes effect on native
-    whileElementsMounted: !isOpen ? undefined : autoUpdate,
-    platform:
-      (disableRTL ?? setupOptions.disableRTL)
-        ? {
-            ...platform,
-            isRTL(element) {
-              return false
-            },
-          }
-        : platform,
-    middleware: [
+  const isOpen = passThrough ? false : (open ?? true)
+
+  // freeze middleware reference when closed so floating-ui's deepEqual trivially
+  // passes (same object) and skips computePosition on re-renders while closed.
+  // unlike swapping to [], this retains the last good middleware so cached
+  // position data (offset, arrow, transformOrigin) stays correct for reopen.
+  const middlewareRef = React.useRef<any[]>([])
+  if (isOpen) {
+    middlewareRef.current = [
+      // order matters: offset first, then flip, then shift, then arrow
+      typeof offsetOptions !== 'undefined' ? offsetFn(offsetOptions) : (null as any),
+      allowFlip ? flip(typeof allowFlip === 'boolean' ? {} : allowFlip) : (null as any),
+      // NOTE: shift's axis terminology is reversed vs flip/offset:
+      // for top/bottom placements: mainAxis = horizontal, crossAxis = vertical
+      // for left/right placements: mainAxis = vertical, crossAxis = horizontal
+      // default to horizontal shift only (mainAxis: true, crossAxis: false)
       stayInFrame
-        ? shift(typeof stayInFrame === 'boolean' ? {} : stayInFrame)
+        ? shift({
+            padding: 10,
+            mainAxis: true,
+            crossAxis: false,
+            ...(typeof stayInFrame === 'object' ? stayInFrame : null),
+          })
         : (null as any),
-      allowFlip ? flip(typeof allowFlip === 'boolean' ? {} : allowFlip) : (null as any),
       arrowEl ? arrow({ element: arrowEl }) : (null as any),
-      typeof offsetOptions !== 'undefined' ? offsetFn(offsetOptions) : (null as any),
       checkFloating,
       process.env.TAMAGUI_TARGET !== 'native' && resize
         ? sizeMiddleware({
+            padding: typeof stayInFrame === 'object' ? stayInFrame.padding : 10,
             apply({ availableHeight, availableWidth }) {
               if (passThrough) {
                 return
@@ -343,7 +413,25 @@ export function Popper(props: PopperProps) {
             arrowWidth: arrowSize,
           })
         : (null as any),
-    ].filter(Boolean),
+    ].filter(Boolean)
+  }
+
+  let floating = useFloating({
+    open: isOpen,
+    strategy,
+    placement,
+    sameScrollView: false, // this only takes effect on native
+    whileElementsMounted: !isOpen ? undefined : tamaguiAutoUpdate,
+    platform:
+      (disableRTL ?? setupOptions.disableRTL)
+        ? {
+            ...platform,
+            isRTL(element) {
+              return false
+            },
+          }
+        : platform,
+    middleware: middlewareRef.current,
   })
 
   if (process.env.TAMAGUI_TARGET !== 'native') {
@@ -399,8 +487,6 @@ export function Popper(props: PopperProps) {
     }, [passThrough, dimensions, keyboardOpen])
   }
 
-  // memoize since we round x/y, floating-ui doesn't by default which can cause tons of updates
-  // if the floating element is inside something animating with a spring
   const popperContext = React.useMemo(() => {
     return {
       size,
@@ -417,20 +503,20 @@ export function Popper(props: PopperProps) {
   }, [
     open,
     size,
-    floating.x,
-    floating.y,
-    floating.placement,
+    floating,
     JSON.stringify(middlewareData.arrow || null),
     JSON.stringify(middlewareData.transformOrigin || null),
-    floating.isPositioned,
   ])
 
   return (
-    <LayoutMeasurementController disable={!isOpen}>
-      <PopperProvider scope={scope} {...popperContext}>
+    <PopperProvider scope={scope} {...popperContext}>
+      {/* reset FloatingOverrideContext so it doesn't leak into nested Poppers —
+          each Popper consumes the override for its own useFloating, children
+          should not inherit it (e.g. a Menu inside a Tooltip's tree) */}
+      <FloatingOverrideContext.Provider value={null}>
         {children}
-      </PopperProvider>
-    </LayoutMeasurementController>
+      </FloatingOverrideContext.Provider>
+    </PopperProvider>
   )
 }
 
@@ -452,10 +538,25 @@ export const PopperAnchor = YStack.styleable<PopperAnchorExtraProps>(
     const context = usePopperContextSlow(scope)
     const { getReferenceProps, refs, update } = context
     const ref = React.useRef<PopperAnchorRef>(null)
+    const triggerId = React.useId()
+
+    // register this trigger element with the shared trigger map
+    // so useHover can detect cursor moves between sibling triggers
+    React.useEffect(() => {
+      if (!scope || !context.triggerElements || !ref.current) return
+      if (!(ref.current instanceof Element)) return
+      const el = ref.current as Element
+      context.triggerElements.add(triggerId, el)
+      return () => {
+        context.triggerElements?.delete(triggerId)
+      }
+    }, [scope, triggerId, context.triggerElements])
 
     React.useEffect(() => {
       if (virtualRef) {
         refs.setReference(virtualRef.current)
+        // recompute position after setting virtual reference
+        update()
       }
     }, [virtualRef])
 
@@ -472,7 +573,8 @@ export const PopperAnchor = YStack.styleable<PopperAnchorExtraProps>(
           refs.setReference(node)
         })
       },
-      [refs.setReference]
+      // it was refs.setRefernce but its stable and refs is undefined on server
+      [refs]
     )
 
     const shouldHandleInHover = isWeb && scope
@@ -489,22 +591,30 @@ export const PopperAnchor = YStack.styleable<PopperAnchorExtraProps>(
         {...refProps}
         ref={composedRefs}
         {...(shouldHandleInHover && {
-          // this helps us with handling scoped poppers with many different targets
-          // basically we wait for mouseEnter to ever set a reference and remove it on leave
-          // otherwise floating ui gets confused by having >1 reference
+          // scoped poppers with multiple triggers: set the reference on
+          // mouseEnter so floating-ui positions relative to the hovered
+          // trigger, not the last one rendered.
+          //
+          // flushSync is critical here: without it, setReference batches
+          // with React's async state updates and the arrow/content position
+          // computes against the OLD reference element. this causes the
+          // arrow to flash at x=0 (top-left) during trigger switches.
+          // flushSync forces synchronous commit so update() below reads
+          // the correct reference element immediately.
           onMouseEnter: (e) => {
-            if (ref.current instanceof HTMLElement) {
-              refs.setReference(ref.current)
+            const el = (e.currentTarget ?? ref.current) as HTMLElement | null
+            if (el instanceof HTMLElement) {
+              flushSync(() => refs.setReference(el))
+              update()
 
-              if (!refProps) {
-                return
-              }
+              if (!refProps) return
 
               refProps.onPointerEnter?.(e)
-              update()
+              context.onHoverReference?.(e.nativeEvent)
             }
           },
           onMouseLeave: (e) => {
+            context.onLeaveReference?.()
             refProps?.onMouseLeave?.(e)
           },
         })}
@@ -535,11 +645,7 @@ export const PopperContentFrame = styled(YStack, {
 
   variants: {
     unstyled: {
-      false: {
-        size: '$true',
-        backgroundColor: '$background',
-        alignItems: 'center',
-      },
+      true: {},
     },
 
     size: {
@@ -551,20 +657,25 @@ export const PopperContentFrame = styled(YStack, {
       },
     },
   } as const,
-
-  defaultVariants: {
-    unstyled: process.env.TAMAGUI_HEADLESS === '1',
-  },
 })
 
 export const PopperContent = React.forwardRef<PopperContentElement, PopperContentProps>(
   function PopperContent(props, forwardedRef) {
+    // detect controlled animatePosition before destructuring. when the user passes
+    // animatePosition (even with a currently-falsy value like undefined or false),
+    // toggling it later must not flip 'transition' presence on the inner View - that
+    // would change useComponentState's hasAnimationProp mid-life, conditionally calling
+    // useAnimations/usePresence and tripping React's "Should have a queue" invariant.
+    const isAnimatePosControlled =
+      'animatePosition' in props || 'enableAnimationForPositionChange' in props
+
     const {
       scope,
       animatePosition,
       enableAnimationForPositionChange,
       children,
       passThrough,
+      unstyled,
       ...rest
     } = props
     const animatePos = animatePosition ?? enableAnimationForPositionChange
@@ -580,19 +691,60 @@ export const PopperContent = React.forwardRef<PopperContentElement, PopperConten
       size,
       isPositioned,
       transformOrigin,
+      update,
     } = context
 
-    // Wrap setFloating in startTransition to avoid React #185 (setState during render)
-    // This can happen during rapid navigation when refs are set during render phase
+    // keep update() accessible inside safeSetFloating without adding it as a dep
+    const updateRef = React.useRef(update)
+    updateRef.current = update
+
+    // ref callback: call refs.setFloating directly (no startTransition) so floating-ui's
+    // state update runs synchronously and position is computed on mount.
+    // note: ref callbacks fire during the commit phase, not render, so calling setState
+    // here is safe - React batches it for the next commit.
+    //
+    // when animatePosition=true, disableAnimation state changes cycle the DOM node
+    // (null then re-mount). we block all null calls here to prevent floating-ui from
+    // losing its reference mid-cycle; genuine unmount is handled by the useEffect below.
+    // for same-node cycling (animateOnly prop change without remount), refs.setFloating
+    // is a no-op in floating-ui (same-node guard), so we call update() to force recompute.
+    const lastNodeRef = React.useRef<any>(null)
     const safeSetFloating = React.useCallback(
       (node: any) => {
-        startTransition(() => {
+        const isNewNode = node !== lastNodeRef.current
+        if (node) {
+          lastNodeRef.current = node
           refs.setFloating(node)
-        })
+          if (!isNewNode) {
+            // same node re-appeared (prop cycling without remount):
+            // refs.setFloating is a no-op, so force position recompute
+            updateRef.current?.()
+          }
+        }
+        // null calls are blocked: cycling nulls are transient, genuine unmount
+        // is handled by the useEffect cleanup below
       },
       [refs.setFloating]
     )
 
+    // clear floating-ui's reference when the component genuinely unmounts.
+    // IMPORTANT: useEffect cleanup is deferred — when PopperContent remounts
+    // (e.g. animation prop cycling), the new instance's ref callback fires
+    // BEFORE this cleanup runs. without the guard, we'd null out the ref that
+    // the new instance just set, causing all subsequent update() calls to
+    // early-return (the "stuck tooltip" bug).
+    React.useEffect(() => {
+      return () => {
+        const ourNode = lastNodeRef.current
+        // only clear if floating-ui still points to OUR node — if a new
+        // instance already set a different node, don't touch it
+        if (ourNode && refs.floating.current === ourNode) {
+          refs.setFloating(null)
+        }
+        lastNodeRef.current = null
+      }
+    }, [])
+
     const contentRefs = useComposedRefs<any>(safeSetFloating, forwardedRef)
 
     const [needsMeasure, setNeedsMeasure] = React.useState(animatePos)
@@ -603,28 +755,52 @@ export const PopperContent = React.forwardRef<PopperContentElement, PopperConten
       }
     }, [needsMeasure, animatePos, x, y])
 
-    // default to not showing if positioned at 0, 0
-    const hide = x === 0 && y === 0
+    // track whether we've ever been positioned. floating-ui resets isPositioned
+    // to false when open changes to false (e.g. hoverable safePolygon briefly
+    // closing). without this, the brief close disables animation and causes
+    // position jumps when the popover reopens at the new trigger.
+    const hasBeenPositioned = React.useRef(false)
+    const lastGoodPosition = React.useRef({ x: 0, y: 0 })
+    if (x !== 0 || y !== 0) {
+      // always track the latest computed position so that when a new reference
+      // is set while closed (e.g. content → gap → different trigger), the
+      // effectiveX/Y fallback uses the fresh position, not the stale one
+      lastGoodPosition.current = { x, y }
+      if (isPositioned) {
+        hasBeenPositioned.current = true
+      }
+    }
+
+    // use the last known good position when floating-ui provides 0,0.
+    // this happens in two cases:
+    // 1. close/reopen cycle: isPositioned resets to false
+    // 2. trigger switch: reference element changes, floating-ui briefly
+    //    provides x=0,y=0 while isPositioned is still true, causing the
+    //    animation driver to animate toward (0,0) for 2-3 frames
+    const brieflyZero = hasBeenPositioned.current && x === 0 && y === 0
+    const effectiveX = brieflyZero ? lastGoodPosition.current.x : x
+    const effectiveY = brieflyZero ? lastGoodPosition.current.y : y
+
+    // only hide before the very first positioning
+    const hide = !hasBeenPositioned.current && effectiveX === 0 && effectiveY === 0
 
     const disableAnimationProp =
       // if they want to animate also when re-positioning allow it
       animatePos === 'even-when-repositioning'
         ? needsMeasure
-        : !isPositioned || needsMeasure
+        : (!hasBeenPositioned.current && !isPositioned) || needsMeasure
 
     const [disableAnimation, setDisableAnimation] = React.useState(disableAnimationProp)
 
-    // we set this delayed because we need to pass to the animation driver the value and then update it
+    // set in an effect so we apply the css transition only after the element is positioned,
+    // not on the first render (which would animate from y=0 to the actual position)
     React.useEffect(() => {
       setDisableAnimation(disableAnimationProp)
     }, [disableAnimationProp])
 
-    // when position not calculated yet (hide=true means x===0 && y===0),
-    // don't pass x/y to avoid motion driver capturing 0,0 as starting position
-    // and then animating from 0,0 to the real position (causes visual jump)
     const positionProps = hide
-      ? {} // omit x/y when hiding - prevents motion from animating from origin
-      : { x: x || 0, y: y || 0 }
+      ? {} // omit x/y when hiding - prevents motion driver from animating from origin
+      : { x: effectiveX || 0, y: effectiveY || 0 }
 
     const frameProps = {
       ref: contentRefs,
@@ -632,17 +808,18 @@ export const PopperContent = React.forwardRef<PopperContentElement, PopperConten
       top: 0,
       left: 0,
       position: strategy,
-      opacity: 1,
-      ...(animatePos && {
-        transition: rest.transition,
-        animateOnly: disableAnimation ? [] : rest.animateOnly,
-        // apply animation but disable it on initial render to avoid animating from 0 to the first position
+      opacity: hide ? 0 : 1,
+      // when animatePosition is controlled by the user, always emit these keys with
+      // safe no-op values (transition: undefined, animateOnly: []) so the inner
+      // View's hook count stays stable across animatePos toggles. animatePresence
+      // must always be false here too, to short-circuit usePresence consistently.
+      ...(isAnimatePosControlled && {
+        transition: animatePos ? rest.transition : undefined,
+        // animateOnly: [] turns off transitions while keeping styles applied,
+        // letting the element move to its position silently before animations start
+        animateOnly: animatePos && !disableAnimation ? rest.animateOnly : [],
         animatePresence: false,
       }),
-      ...(hide && {
-        opacity: 0,
-        animateOnly: [],
-      }),
     }
 
     // outer frame because we explicitly don't want animation to apply to this
@@ -658,33 +835,34 @@ export const PopperContent = React.forwardRef<PopperContentElement, PopperConten
         : undefined
 
     return (
-      <TamaguiView
-        passThrough={passThrough}
-        ref={contentRefs}
-        contain="layout style"
-        {...(passThrough ? null : floatingProps)}
-        {...(!passThrough &&
-          animatePos && {
-            // marker for animation driver to know this is a popper element
-            // that needs special handling for position animation interruption
-            'data-popper-animate-position': 'true',
-          })}
-      >
-        <PopperContentFrame
-          key="popper-content-frame"
+      <LayoutMeasurementController disable={!context.open}>
+        <TamaguiView
           passThrough={passThrough}
-          {...(!passThrough && {
-            'data-placement': placement,
-            'data-strategy': strategy,
-            size,
-            ...style,
-            ...transformOriginStyle,
-            ...rest,
-          })}
+          ref={contentRefs}
+          direction={rest.direction}
+          {...(passThrough ? null : floatingProps)}
+          {...(!passThrough &&
+            animatePos && {
+              'data-popper-animate-position': 'true',
+            })}
         >
-          {children}
-        </PopperContentFrame>
-      </TamaguiView>
+          <PopperContentFrame
+            key="popper-content-frame"
+            passThrough={passThrough}
+            unstyled={unstyled}
+            {...(!passThrough && {
+              'data-placement': placement,
+              'data-strategy': strategy,
+              size,
+              ...style,
+              ...transformOriginStyle,
+              ...rest,
+            })}
+          >
+            {children}
+          </PopperContentFrame>
+        </TamaguiView>
+      </LayoutMeasurementController>
     )
   }
 )
@@ -755,11 +933,14 @@ type Sides = keyof typeof opposites
 
 export const PopperArrow = React.forwardRef<TamaguiElement, PopperArrowProps>(
   function PopperArrow(propsIn, forwardedRef) {
+    // see PopperContent for why we detect controlled animatePosition before destructuring
+    const isAnimatePosControlled = 'animatePosition' in propsIn
     const { scope, animatePosition, transition, ...rest } = propsIn
-    const props = useProps(rest)
-    const { offset, size: sizeProp, borderWidth = 0, ...arrowProps } = props
+    const { offset, size: sizeProp, borderWidth = 0, ...arrowProps } = rest
 
     const context = usePopperContext(scope)
+
+    // TODO: get rid! at the very least move up to Popover and simplify
     const sizeVal =
       typeof sizeProp === 'number'
         ? sizeProp
@@ -780,6 +961,10 @@ export const PopperArrow = React.forwardRef<TamaguiElement, PopperArrowProps>(
     const x = (context.arrowStyle?.x as number) || 0
     const y = (context.arrowStyle?.y as number) || 0
 
+    // hide arrow until floating-ui has computed its position to prevent
+    // flash at x=0 during initial render or trigger switches in hydration
+    const arrowPositioned = context.arrowStyle != null
+
     const primaryPlacement = (placement ? placement.split('-')[0] : 'top') as Sides
 
     const arrowStyle: ViewProps = { x, y, width: size, height: size }
@@ -813,9 +998,10 @@ export const PopperArrow = React.forwardRef<TamaguiElement, PopperArrowProps>(
       <PopperArrowOuterFrame
         ref={refs}
         {...arrowStyle}
-        {...(animatePosition && {
-          transition,
-          animateOnly: ['transform'],
+        {...(!arrowPositioned && { opacity: 0 })}
+        {...(isAnimatePosControlled && {
+          transition: animatePosition ? transition : undefined,
+          animateOnly: animatePosition ? ['transform'] : [],
           animatePresence: false,
         })}
       >