@momo-kits/animated-tooltip 0.154.2-beta.1 → 0.154.2-beta.2

package/PORTAL_SETUP.md

@@ -0,0 +1,52 @@
+# Tooltip Portal Setup
+
+## Important: Required Setup
+
+The Tooltip component now uses a **Portal system** to render above all other content, solving zIndex limitations. This requires a one-time setup in your app.
+
+### Setup Instructions
+
+Wrap your app with `TooltipPortalProvider` and add `TooltipPortalHost` at the root level:
+
+```typescript
+import React from 'react';
+import { TooltipPortalProvider, TooltipPortalHost } from '@momo-kits/tooltip';
+import YourApp from './YourApp';
+
+function App() {
+  return (
+    <TooltipPortalProvider>
+      <YourApp />
+      {/* TooltipPortalHost renders all tooltips at this level */}
+      <TooltipPortalHost />
+    </TooltipPortalProvider>
+  );
+}
+
+export default App;
+```
+
+### Usage
+
+After setup, use Tooltip as normal - **no changes required**:
+
+```typescript
+import { Tooltip } from '@momo-kits/tooltip';
+
+<Tooltip title="Help" description="This is helpful info" placement="top">
+  <Button>Press me</Button>
+</Tooltip>
+```
+
+## What Changed
+
+### For Developers
+- **No API changes** - Tooltip props remain the same
+- **One-time setup** required (Provider + Host)
+- **Better zIndex handling** - Tooltips now render above everything
+
+### Technical Details
+- Uses `measureInWindow` for absolute positioning
+- Portal renders tooltips at root level (outside component hierarchy)
+- No ref required from consumer - uses internal ref
+- Backward compatible API

package/TooltipPortal.tsx

@@ -0,0 +1,125 @@
+import React, {
+  createContext,
+  useContext,
+  useCallback,
+  ReactNode,
+  useMemo,
+  useReducer,
+  useRef,
+  RefObject,
+} from 'react';
+import { View, StyleSheet } from 'react-native';
+
+interface TooltipPortalContextValue {
+  register: (id: string, content: ReactNode) => void;
+  unregister: (id: string, immediate?: boolean) => void;
+  portals: Map<string, ReactNode>;
+  hostRef: RefObject<View | null>;
+}
+
+const TooltipPortalContext = createContext<TooltipPortalContextValue | null>(
+  null,
+);
+
+export const TooltipPortalProvider: React.FC<{ children: ReactNode }> = ({
+  children,
+}) => {
+  // Use ref for synchronous updates + reducer for manual re-renders
+  const portalsRef = useRef<Map<string, ReactNode>>(new Map());
+  const hostRef = useRef<View>(null);
+  const [updateCounter, forceUpdate] = useReducer((x: number) => x + 1, 0);
+  const pendingUpdateRef = useRef<NodeJS.Timeout | null>(null);
+
+  const register = useCallback((id: string, content: ReactNode) => {
+    portalsRef.current.set(id, content);
+    forceUpdate(); // Trigger re-render to show new content
+  }, []);
+
+  const unregister = useCallback((id: string, immediate = false) => {
+    const hasItem = portalsRef.current.has(id);
+    if (!hasItem) return; // Already removed
+
+    portalsRef.current.delete(id);
+
+    // Clear any pending updates
+    if (pendingUpdateRef.current) {
+      clearTimeout(pendingUpdateRef.current);
+      pendingUpdateRef.current = null;
+    }
+
+    if (immediate) {
+      forceUpdate();
+    } else {
+      // Debounce normal updates to avoid excessive re-renders
+      pendingUpdateRef.current = setTimeout(() => {
+        forceUpdate();
+        pendingUpdateRef.current = null;
+      }, 0) as unknown as NodeJS.Timeout;
+    }
+  }, []);
+
+  const value = useMemo(
+    () => ({ register, unregister, portals: portalsRef.current, hostRef }),
+    [register, unregister, updateCounter], // Include updateCounter to refresh context
+  );
+
+  return (
+    <TooltipPortalContext.Provider value={value}>
+      {children}
+    </TooltipPortalContext.Provider>
+  );
+};
+
+export const TooltipPortalHost: React.FC = () => {
+  const context = useContext(TooltipPortalContext);
+
+  if (!context) {
+    if (__DEV__) {
+      console.warn(
+        'TooltipPortalHost must be used within TooltipPortalProvider',
+      );
+    }
+    return null;
+  }
+
+  const { portals, hostRef } = context;
+
+  return (
+    <View ref={hostRef} style={styles.hostContainer} pointerEvents="box-none">
+      {Array.from(portals.entries()).map(([id, content]) => (
+        <React.Fragment key={id}>{content}</React.Fragment>
+      ))}
+    </View>
+  );
+};
+
+export const useTooltipPortal = () => {
+  const context = useContext(TooltipPortalContext);
+
+  if (!context) {
+    if (__DEV__) {
+      console.warn(
+        'useTooltipPortal must be used within TooltipPortalProvider. Tooltips may not appear correctly.',
+      );
+    }
+    // Return no-op functions if context is missing
+    return {
+      register: () => {},
+      unregister: () => {},
+      hostRef: null,
+    };
+  }
+
+  return context;
+};
+
+const styles = StyleSheet.create({
+  hostContainer: {
+    position: 'absolute',
+    top: 0,
+    left: 0,
+    right: 0,
+    bottom: 0,
+    zIndex: 9999,
+  },
+});

package/index.tsx

@@ -26,6 +26,7 @@ import {
 import styles from './styles';
 import { TooltipPlacement, TooltipProps, TooltipRef } from './types';
 import { IconButton, PrimaryButton, SecondaryButton } from './TooltipButtons';
+import { useTooltipPortal } from './TooltipPortal';
 
 const Tooltip = forwardRef<TooltipRef, TooltipProps>(function Tooltip(
   {
@@ -53,6 +54,32 @@ const Tooltip = forwardRef<TooltipRef, TooltipProps>(function Tooltip(
   const arrowSize = 6;
   const [tooltipSize, setTooltipSize] = useState({ width: 0, height: 0 });
 
+  // Portal integration
+  const portal = useTooltipPortal();
+  const portalId = useRef(
+    `tooltip-${Math.random().toString(36).substr(2, 9)}`,
+  ).current;
+
+  // DEBUG: Check if portal is available
+  console.log('[Tooltip] Portal context available:', !!portal, portalId);
+
+  // Internal ref for anchor - no ref required from consumer
+  const anchorRef = useRef<View>(null);
+
+  // Anchor position from measureInWindow
+  const [anchorPosition, setAnchorPosition] = useState({
+    x: 0,
+    y: 0,
+    width: 0,
+    height: 0,
+  });
+
+  // Portal host position for relative calculation
+  const [hostPosition, setHostPosition] = useState({
+    x: 0,
+    y: 0,
+  });
+
   const componentName = 'Tooltip';
   const componentId = useMemo(() => {
     if (accessibilityLabel) {
@@ -69,10 +96,17 @@ const Tooltip = forwardRef<TooltipRef, TooltipProps>(function Tooltip(
   ).current;
   const showTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
   const hideTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
-  const [anchorSize, setAnchorSize] = useState({ width: 0, height: 0 });
 
   const currentVisible = isControlled ? !!visible : internalVisible;
 
+  // DEBUG: Log visibility state
+  console.log('[Tooltip] Visibility state:', { 
+    isControlled, 
+    visible, 
+    internalVisible, 
+    currentVisible 
+  });
+
   const clearTimers = () => {
     if (showTimer.current) {
       clearTimeout(showTimer.current);
@@ -102,6 +136,100 @@ const Tooltip = forwardRef<TooltipRef, TooltipProps>(function Tooltip(
     animate(currentVisible);
   }, [currentVisible, animationDuration]);
 
+  // Preload anchor measurement on mount for faster initial display
+  useEffect(() => {
+    // Measure immediately on mount to have position ready
+    const timer = setTimeout(() => {
+      // Measure host position first
+      if (portal.hostRef?.current) {
+        portal.hostRef.current.measureInWindow((hostX, hostY) => {
+          setHostPosition({ x: hostX, y: hostY });
+        });
+      }
+      
+      anchorRef.current?.measureInWindow((x, y, width, height) => {
+        if (x !== 0 || y !== 0 || width !== 0 || height !== 0) {
+          setAnchorPosition({ x, y, width, height });
+        }
+      });
+    }, 0);
+
+    return () => clearTimeout(timer);
+  }, []);
+
+  // Continuously measure anchor position when tooltip is visible
+  // This handles scroll events and dynamic layout changes
+  useEffect(() => {
+    if (!currentVisible) {
+      // Reset position immediately when hiding
+      setAnchorPosition({ x: 0, y: 0, width: 0, height: 0 });
+      setHostPosition({ x: 0, y: 0 });
+      return;
+    }
+
+    let rafId: number | null = null;
+    let lastPosition = { x: 0, y: 0, width: 0, height: 0 };
+    let lastHostPosition = { x: 0, y: 0 };
+    let isMounted = true; // Track mounted state
+    let isActive = true; // Track active state for early cancellation
+
+    const measureAnchor = () => {
+      // Check flags before any work
+      if (!isMounted || !isActive || !anchorRef.current) {
+        return;
+      }
+
+      // Measure portal host position first
+      if (portal.hostRef?.current) {
+        portal.hostRef.current.measureInWindow((hostX, hostY) => {
+          if (!isMounted || !isActive) return;
+          
+          if (hostX !== lastHostPosition.x || hostY !== lastHostPosition.y) {
+            lastHostPosition = { x: hostX, y: hostY };
+            setHostPosition({ x: hostX, y: hostY });
+          }
+        });
+      }
+
+      anchorRef.current.measureInWindow((x, y, width, height) => {
+        // Double-check flags in callback
+        if (!isMounted || !isActive) return;
+
+        // Only update if position changed (to avoid unnecessary re-renders)
+        if (
+          x !== lastPosition.x ||
+          y !== lastPosition.y ||
+          width !== lastPosition.width ||
+          height !== lastPosition.height
+        ) {
+          console.log('[Tooltip] Position updated:', { x, y, width, height });
+          lastPosition = { x, y, width, height };
+          setAnchorPosition({ x, y, width, height });
+        }
+      });
+
+      // Continue polling while visible, mounted, and active
+      if (currentVisible && isMounted && isActive) {
+        rafId = requestAnimationFrame(measureAnchor);
+      }
+    };
+
+    // Start polling
+    rafId = requestAnimationFrame(measureAnchor);
+
+    return () => {
+      // Set flags immediately to stop all pending work
+      isMounted = false;
+      isActive = false;
+
+      // Cancel any pending animation frame
+      if (rafId !== null) {
+        cancelAnimationFrame(rafId);
+        rafId = null;
+      }
+    };
+  }, [currentVisible]);
+
   useEffect(() => {
     return () => {
       clearTimers();
@@ -111,7 +239,20 @@ const Tooltip = forwardRef<TooltipRef, TooltipProps>(function Tooltip(
 
   const handleShow = () => {
     clearTimers();
-    showTimer.current = setTimeout(() => setVisibility(true), showDelay);
+    showTimer.current = setTimeout(() => {
+      // Measure host position first
+      if (portal.hostRef?.current) {
+        portal.hostRef.current.measureInWindow((hostX, hostY) => {
+          setHostPosition({ x: hostX, y: hostY });
+        });
+      }
+      
+      // Measure anchor position before showing tooltip
+      anchorRef.current?.measureInWindow((x, y, width, height) => {
+        setAnchorPosition({ x, y, width, height });
+        setVisibility(true);
+      });
+    }, showDelay);
   };
 
   const handleHide = () => {
@@ -166,32 +307,73 @@ const Tooltip = forwardRef<TooltipRef, TooltipProps>(function Tooltip(
           }),
         };
 
-  const placementStyle: {
-    [key: string]: any;
-  } =
-    placement === 'top'
-      ? { bottom: (anchorSize.height || 0) + offset }
-      : placement === 'bottom'
-      ? { top: (anchorSize.height || 0) + offset }
-      : placement === 'left'
-      ? { right: (anchorSize.width || 0) + offset }
-      : { left: (anchorSize.width || 0) + offset };
+  // Calculate absolute position based on window coordinates
+  // Subtract host position to make it relative to the portal host container
+  const getTooltipPosition = useMemo((): {
+    top?: number;
+    left?: number;
+    right?: number;
+    bottom?: number;
+  } => {
+    const { x, y, width, height } = anchorPosition;
+    const { width: tooltipWidth, height: tooltipHeight } = tooltipSize;
+
+    let position: { top?: number; left?: number; right?: number } = {};
+
+    // Vertical positioning (relative to portal host)
+    if (placement === 'top') {
+      position.top = y - tooltipHeight - offset - hostPosition.y;
+    } else if (placement === 'bottom') {
+      position.top = y + height + offset - hostPosition.y;
+    } else {
+      // For left/right placement, calculate vertical center alignment
+      if (align === 'start') {
+        position.top = y - hostPosition.y;
+      } else if (align === 'end') {
+        position.top = y + height - tooltipHeight - hostPosition.y;
+      } else {
+        // center
+        position.top = y + height / 2 - tooltipHeight / 2 - hostPosition.y;
+      }
+    }
+
+    // Horizontal positioning (relative to portal host)
+    if (placement === 'left') {
+      position.left = x - tooltipWidth - offset - hostPosition.x;
+    } else if (placement === 'right') {
+      position.left = x + width + offset - hostPosition.x;
+    } else {
+      // For top/bottom placement, calculate horizontal alignment
+      if (align === 'start') {
+        position.left = x - hostPosition.x;
+      } else if (align === 'end') {
+        position.left = x + width - tooltipWidth - hostPosition.x;
+      } else {
+        // center
+        position.left = x + width / 2 - tooltipWidth / 2 - hostPosition.x;
+      }
+    }
+
+    return position;
+  }, [anchorPosition, tooltipSize, placement, align, offset, hostPosition]);
+
+  const placementStyle = getTooltipPosition; // This IS the memoized position object!
+
+  // DEBUG: Log values to troubleshoot positioning
+  if (__DEV__ && currentVisible) {
+    console.log('[Tooltip Debug]', {
+      anchorPosition,
+      tooltipSize,
+      placement,
+      align,
+      placementStyle,
+    });
+  }
 
   const centerVerticalOffset =
-    (anchorSize.height || 0) / 2 - (tooltipSize.height || 0) / 2;
-
-  const alignStyle: ViewStyle =
-    placement === 'top' || placement === 'bottom'
-      ? align === 'start'
-        ? { left: 0 }
-        : align === 'end'
-        ? { right: 0 }
-        : { alignSelf: 'center' }
-      : align === 'start'
-      ? { top: 0 }
-      : align === 'end'
-      ? { bottom: 0 }
-      : { top: centerVerticalOffset };
+    (anchorPosition.height || 0) / 2 - (tooltipSize.height || 0) / 2;
+
+  const alignStyle: ViewStyle = {}; // No longer needed - position calculated in getTooltipPosition
 
   const resolvedTextColor = Colors.black_01;
 
@@ -391,28 +573,67 @@ const Tooltip = forwardRef<TooltipRef, TooltipProps>(function Tooltip(
     }
   };
 
-  const tooltipNode = (
-    <Animated.View
-      pointerEvents="auto"
-      style={[
-        {
-          maxWidth: SCREEN_WIDTH - Spacing.M * 2,
-        },
-        containerStyle,
-        styles.tooltip,
-        placementStyle,
-        alignStyle,
-        {
-          opacity: animatedValue,
-          transform: [translate],
-        },
-      ]}
-      onLayout={event => setTooltipSize(event.nativeEvent.layout)}
-    >
-      {renderContent()}
-      <View style={getArrowStyle()} />
-    </Animated.View>
-  );
+  // Register tooltip with portal when visible
+  // Note: content is created fresh each time to ensure up-to-date styles/props
+  useEffect(() => {
+    let isActive = true; // Track if effect is still active
+
+    if (!currentVisible) {
+      portal.unregister(portalId, true); // Immediate cleanup when hiding
+      return;
+    }
+
+    // Only render tooltip if anchor has been measured (not initial 0,0,0,0)
+    const hasMeasurement =
+      anchorPosition.x !== 0 ||
+      anchorPosition.y !== 0 ||
+      anchorPosition.width !== 0 ||
+      anchorPosition.height !== 0;
+
+    if (!hasMeasurement) {
+      console.log('[Tooltip] Waiting for anchor measurement...');
+      return;
+    }
+
+    console.log('[Tooltip] Registering with portal, position:', placementStyle);
+
+    const content = (
+      <Animated.View
+        pointerEvents="auto"
+        style={[
+          {
+            maxWidth: SCREEN_WIDTH - Spacing.M * 2,
+          },
+          containerStyle,
+          styles.tooltip,
+          placementStyle,
+          alignStyle,
+          {
+            opacity: animatedValue,
+            transform: [translate],
+          },
+        ]}
+        onLayout={event => {
+          if (isActive) {
+            setTooltipSize(event.nativeEvent.layout);
+          }
+        }}
+      >
+        {renderContent()}
+        <View style={getArrowStyle()} />
+      </Animated.View>
+    );
+
+    portal.register(portalId, content);
+
+    return () => {
+      isActive = false; // Mark as inactive immediately
+      portal.unregister(portalId, true); // Always use immediate cleanup on unmount
+    };
+    // Only depend on position-affecting values
+    // Content (title, description, buttons) updates via React reconciliation automatically
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [currentVisible, anchorPosition, placement, align]);
 
   return (
     <View
@@ -420,13 +641,17 @@ const Tooltip = forwardRef<TooltipRef, TooltipProps>(function Tooltip(
       style={styles.container}
       accessibilityLabel={componentId}
     >
-      <View onLayout={event => setAnchorSize(event.nativeEvent.layout)}>
+      <View ref={anchorRef} style={{ alignSelf: 'flex-start' }}>
         {children}
       </View>
-      {tooltipNode}
     </View>
   );
 });
 
 export { Tooltip };
 export type { TooltipProps, TooltipPlacement, TooltipRef };
+export {
+  TooltipPortalProvider,
+  TooltipPortalHost,
+  useTooltipPortal,
+} from './TooltipPortal';

package/package.json

@@ -1,16 +1,16 @@
 {
-    "name": "@momo-kits/animated-tooltip",
-    "version": "0.154.2-beta.1",
-    "private": false,
-    "main": "index.tsx",
-    "dependencies": {},
-    "peerDependencies": {
-        "@momo-kits/foundation": "latest",
-        "react": "*",
-        "react-native": "*"
-    },
-    "license": "MoMo",
-    "publishConfig": {
-        "registry": "https://registry.npmjs.org/"
-    }
-}
+  "name": "@momo-kits/animated-tooltip",
+  "version": "0.154.2-beta.2",
+  "private": false,
+  "main": "index.tsx",
+  "dependencies": {},
+  "peerDependencies": {
+    "@momo-kits/foundation": "latest",
+    "react": "*",
+    "react-native": "*"
+  },
+  "license": "MoMo",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/styles.ts

@@ -7,7 +7,6 @@ export default StyleSheet.create({
   },
   tooltip: {
     position: 'absolute',
-    zIndex: 10,
     padding: Spacing.M,
     backgroundColor: Colors.black_17,
     borderRadius: Radius.S,