@zargaryanvh/react-component-inspector 1.0.7 → 1.0.8

package/dist/InspectionTooltip.js

@@ -5,6 +5,24 @@ import ContentCopyIcon from "@mui/icons-material/ContentCopy";
 import { useInspection } from "./InspectionContext";
 import { formatMetadataForClipboard, getParentWithGap, getTooltipHowToFindInfo } from "./inspection";
 import { parseInspectionMetadata } from "./autoInspection";
+/**
+ * Helper: Clamp a tooltip rect to the viewport so it's always fully visible
+ */
+const clampToViewport = (x, y, w, h, padding = 10) => {
+    const vw = window.innerWidth;
+    const vh = window.innerHeight;
+    let cx = x;
+    let cy = y;
+    if (cx + w > vw - padding)
+        cx = vw - w - padding;
+    if (cy + h > vh - padding)
+        cy = vh - h - padding;
+    if (cx < padding)
+        cx = padding;
+    if (cy < padding)
+        cy = padding;
+    return { x: cx, y: cy };
+};
 /**
  * Helper: Get element text content (first 100 chars)
  */
@@ -84,49 +102,31 @@ const ComponentMetadataSection = ({ metadata }) => {
  */
 export const InspectionTooltip = () => {
     const { isInspectionActive, isLocked, isMobile, isMarginPaddingMode, hoveredComponent, hoveredElement } = useInspection();
-    const [position, setPosition] = useState({ x: 0, y: 0 });
     const [stablePosition, setStablePosition] = useState(null);
     const [copied, setCopied] = useState(null);
+    const [tooltipSize, setTooltipSize] = useState({ w: 400, h: 300 });
     const tooltipRef = useRef(null);
-    // Update position based on cursor, but keep it stable when locked or mouse is near tooltip
+    // Measure tooltip size so we can clamp it to the viewport precisely
     useEffect(() => {
-        if (!isInspectionActive || !hoveredElement) {
-            setStablePosition(null);
-            return;
-        }
-        // If locked, don't update position at all - keep it completely fixed
-        if (isLocked) {
+        if (!tooltipRef.current || typeof ResizeObserver === "undefined")
             return;
-        }
-        const updatePosition = (e) => {
-            // If we have a stable position, check if mouse is near tooltip
-            if (stablePosition && tooltipRef.current) {
-                const tooltipRect = tooltipRef.current.getBoundingClientRect();
-                const mouseX = e.clientX;
-                const mouseY = e.clientY;
-                // Create a "dead zone" around tooltip (80px padding for easier clicking)
-                const deadZone = {
-                    left: tooltipRect.left - 80,
-                    right: tooltipRect.right + 80,
-                    top: tooltipRect.top - 80,
-                    bottom: tooltipRect.bottom + 80,
-                };
-                // If mouse is in dead zone, keep position stable (don't update)
-                if (mouseX >= deadZone.left &&
-                    mouseX <= deadZone.right &&
-                    mouseY >= deadZone.top &&
-                    mouseY <= deadZone.bottom) {
-                    return; // Don't update position - keep it stable
-                }
+        const el = tooltipRef.current;
+        const observer = new ResizeObserver(() => {
+            const r = el.getBoundingClientRect();
+            if (r.width > 0 && r.height > 0) {
+                setTooltipSize((prev) => prev.w === r.width && prev.h === r.height ? prev : { w: r.width, h: r.height });
             }
-            // Mouse moved far from tooltip - update position
-            setPosition({ x: e.clientX, y: e.clientY });
-            // Clear stable position so it recalculates
+        });
+        observer.observe(el);
+        return () => observer.disconnect();
+    }, [isInspectionActive, hoveredComponent]);
+    // Reset stored cursor position when inspection turns off so we don't reuse
+    // a stale value on the next activation.
+    useEffect(() => {
+        if (!isInspectionActive || !hoveredElement) {
             setStablePosition(null);
-        };
-        window.addEventListener("mousemove", updatePosition);
-        return () => window.removeEventListener("mousemove", updatePosition);
-    }, [isInspectionActive, isLocked, hoveredElement, stablePosition]);
+        }
+    }, [isInspectionActive, hoveredElement]);
     // If no component metadata but we have an element, create basic metadata
     const displayComponent = hoveredComponent || (hoveredElement ? {
         componentName: hoveredElement.tagName.toLowerCase(),
@@ -136,84 +136,78 @@ export const InspectionTooltip = () => {
         propsSignature: "default",
         sourceFile: "DOM",
     } : null);
-    // On mobile (or when locking) there is no cursor; position tooltip over/near the inspected element
-    const positionFromElement = useMemo(() => {
-        if (!hoveredElement || !document.body.contains(hoveredElement))
-            return null;
+    // Compute anchor position once per element change. The value is intentionally
+    // NOT recomputed when tooltipSize updates (ResizeObserver may fire several
+    // times as the tooltip's content renders) — recomputing on every size update
+    // makes the tooltip visibly slide and shrink as it settles. Pin location is
+    // chosen as: below the element if there's room, otherwise above, right, left,
+    // and finally a fixed corner for elements that fill the viewport.
+    const tooltipSizeRef = useRef(tooltipSize);
+    tooltipSizeRef.current = tooltipSize;
+    const [anchoredPosition, setAnchoredPosition] = useState(null);
+    useEffect(() => {
+        if (!hoveredElement || !document.body.contains(hoveredElement)) {
+            setAnchoredPosition(null);
+            return;
+        }
         const padding = 10;
-        const estimatedWidth = 400;
-        const estimatedHeight = 200;
+        const gap = 8;
+        const { w, h } = tooltipSizeRef.current;
+        const vw = window.innerWidth;
+        const vh = window.innerHeight;
         const rect = hoveredElement.getBoundingClientRect();
-        // Prefer below and to the right of the element, clamped to viewport
-        let x = rect.left + 15;
-        let y = rect.bottom + 10;
-        if (x + estimatedWidth > window.innerWidth - padding)
-            x = window.innerWidth - estimatedWidth - padding;
-        if (x < padding)
-            x = padding;
-        if (y + estimatedHeight > window.innerHeight - padding)
-            y = rect.top - estimatedHeight - 10;
-        if (y < padding)
-            y = padding;
-        return { x, y };
-    }, [hoveredElement]);
-    // Calculate adjusted position to avoid going off-screen
-    // Use stable position if available; on mobile or when locked use element-based position so tooltip appears over inspected area
-    const adjustedPosition = useMemo(() => {
-        if (!displayComponent) {
-            return { x: position.x + 15, y: position.y + 15 };
-        }
-        // If we have a stable position, use it (don't recalculate)
-        if (stablePosition) {
-            return stablePosition;
-        }
-        // Mobile or just locked: place tooltip near the inspected element (not cursor)
-        if ((isMobile || isLocked) && positionFromElement) {
-            return positionFromElement;
+        const spaceBelow = vh - rect.bottom;
+        const spaceAbove = rect.top;
+        const spaceRight = vw - rect.right;
+        const spaceLeft = rect.left;
+        let x;
+        let y;
+        if (spaceBelow >= h + gap + padding) {
+            y = rect.bottom + gap;
+            x = Math.min(Math.max(rect.left, padding), vw - w - padding);
         }
-        // Desktop: calculate from cursor position
-        const padding = 10;
-        let x = position.x + 15;
-        let y = position.y + 15;
-        // Adjust if tooltip would go off right edge (estimate width)
-        const estimatedWidth = 400; // Approximate tooltip width
-        if (x + estimatedWidth > window.innerWidth - padding) {
-            x = position.x - estimatedWidth - 15;
+        else if (spaceAbove >= h + gap + padding) {
+            y = rect.top - h - gap;
+            x = Math.min(Math.max(rect.left, padding), vw - w - padding);
         }
-        // Adjust if tooltip would go off bottom edge (estimate height)
-        const estimatedHeight = 200; // Approximate tooltip height
-        if (y + estimatedHeight > window.innerHeight - padding) {
-            y = position.y - estimatedHeight - 15;
+        else if (spaceRight >= w + gap + padding) {
+            x = rect.right + gap;
+            y = Math.min(Math.max(rect.top, padding), vh - h - padding);
         }
-        // Adjust if tooltip would go off left edge
-        if (x < padding) {
-            x = padding;
+        else if (spaceLeft >= w + gap + padding) {
+            x = rect.left - w - gap;
+            y = Math.min(Math.max(rect.top, padding), vh - h - padding);
         }
-        // Adjust if tooltip would go off top edge
-        if (y < padding) {
-            y = padding;
+        else {
+            const cx = (rect.left + rect.right) / 2;
+            const cy = (rect.top + rect.bottom) / 2;
+            x = cx < vw / 2 ? vw - w - padding : padding;
+            y = cy < vh / 2 ? vh - h - padding : padding;
         }
-        return { x, y };
-    }, [position, displayComponent, stablePosition, isMobile, isLocked, positionFromElement]);
-    // Set stable position once when tooltip first appears for a new element, or when locked
-    const lastComponentIdRef = useRef(null);
+        setAnchoredPosition(clampToViewport(x, y, w, h));
+    }, [hoveredElement]);
+    const positionFromElement = anchoredPosition;
+    // Position is anchored to the hovered element's rect, not the cursor. This
+    // keeps the tooltip static while the cursor moves around inside one element
+    // (e.g. when inspecting a large container) and only repositions when the
+    // hovered element changes.
+    const adjustedPosition = useMemo(() => {
+        const w = tooltipSize.w;
+        const h = tooltipSize.h;
+        if (positionFromElement)
+            return positionFromElement;
+        return clampToViewport(15, 15, w, h);
+    }, [positionFromElement, tooltipSize]);
+    // When the lock is engaged we freeze whatever position was being shown at
+    // that moment so it doesn't follow subsequent element changes.
     useEffect(() => {
-        const currentComponentId = displayComponent?.componentId || null;
-        // When locked, ensure we have a stable position
-        if (isLocked && !stablePosition && displayComponent && adjustedPosition.x > 0 && adjustedPosition.y > 0) {
+        if (isLocked && !stablePosition && adjustedPosition.x > 0 && adjustedPosition.y > 0) {
             setStablePosition(adjustedPosition);
-            return;
         }
-        // Only set stable position when component changes or when we don't have one yet
-        if (currentComponentId !== lastComponentIdRef.current && !stablePosition && displayComponent && adjustedPosition.x > 0 && adjustedPosition.y > 0) {
-            lastComponentIdRef.current = currentComponentId;
-            // Set stable position after a small delay to ensure tooltip is rendered
-            const timer = setTimeout(() => {
-                setStablePosition(adjustedPosition);
-            }, 50);
-            return () => clearTimeout(timer);
+        if (!isLocked && stablePosition) {
+            setStablePosition(null);
         }
-    }, [displayComponent?.componentId, adjustedPosition, stablePosition, displayComponent, isLocked]);
+    }, [isLocked, adjustedPosition, stablePosition]);
     const fallbackCopy = (text) => {
         const textarea = document.createElement("textarea");
         textarea.value = text;
@@ -334,7 +328,7 @@ export const InspectionTooltip = () => {
             backgroundColor: "rgba(18, 18, 18, 0.95)",
             backdropFilter: "blur(8px)",
             border: "1px solid rgba(255, 255, 255, 0.1)",
-            transition: stablePosition ? "none" : "left 0.1s ease-out, top 0.1s ease-out",
+            transition: "none",
         }, children: [_jsxs(Box, { sx: { display: "flex", justifyContent: "space-between", alignItems: "flex-start", mb: 1 }, children: [_jsxs(Box, { sx: { display: "flex", alignItems: "center", gap: 1 }, children: [_jsx(Typography, { variant: "subtitle2", sx: { color: "#fff", fontWeight: 600, fontSize: "0.875rem" }, children: "Component Inspector" }), isMarginPaddingMode && (_jsx(Typography, { variant: "caption", sx: { color: "#ff9800", fontSize: "0.65rem" }, children: "M/P mode" })), isLocked && (_jsx(Typography, { variant: "caption", sx: { color: "#4caf50", fontSize: "0.7rem", fontStyle: "italic" }, children: "(Locked - Release H to unlock)" }))] }), _jsxs(Box, { sx: { display: "flex", alignItems: "center", gap: 0.75 }, children: [_jsx(MuiTooltip, { title: copied === "component" ? "Copied!" : "Copy component", children: _jsx(IconButton, { size: "small", onClick: (e) => { e.preventDefault(); handleCopy("component"); }, onPointerDown: (e) => { e.preventDefault(); handleCopy("component"); }, sx: {
                                         color: copied === "component" ? "#4caf50" : "#fff",
                                         "&:hover": { backgroundColor: "rgba(255, 255, 255, 0.1)" },

package/dist/InspectionWrapper.js

@@ -1,92 +1,33 @@
 import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
 import React from "react";
-import { useInspection } from "./InspectionContext";
 import { generateComponentId, formatPropsSignature, getComponentName, getNextInstanceIndex, } from "./inspection";
 /**
  * Wrapper component that adds inspection metadata to a component
  */
 export const InspectionWrapper = ({ componentName, variant, role, usagePath, props, sourceFile, children, }) => {
-    const { isInspectionActive, setHoveredComponent } = useInspection();
     const instanceIndex = React.useMemo(() => getNextInstanceIndex(componentName), [componentName]);
-    const handleMouseEnter = (e) => {
-        if (!isInspectionActive)
-            return;
-        const target = e.currentTarget;
-        const metadata = {
-            componentName,
-            componentId: generateComponentId(componentName, instanceIndex),
-            variant,
-            role,
-            usagePath,
-            instanceIndex,
-            propsSignature: formatPropsSignature(props),
-            sourceFile,
-        };
-        setHoveredComponent(metadata, target);
-    };
-    const handleMouseLeave = () => {
-        if (!isInspectionActive)
-            return;
-        setHoveredComponent(null, null);
-    };
-    // Touch handlers for mobile
-    const handleTouchStart = (e) => {
-        if (!isInspectionActive)
-            return;
-        const target = e.currentTarget;
-        const metadata = {
-            componentName,
-            componentId: generateComponentId(componentName, instanceIndex),
-            variant,
-            role,
-            usagePath,
-            instanceIndex,
-            propsSignature: formatPropsSignature(props),
-            sourceFile,
-        };
-        setHoveredComponent(metadata, target);
-    };
-    const handleTouchEnd = () => {
-        // Don't clear on touch end - let autoInspection handle it
-    };
-    // Clone the child element and add inspection handlers
+    // Attach data-inspection-* attributes only; the global autoInspection mousemove
+    // handler is the single source of truth for hover tracking. This avoids the
+    // border flicker caused by competing mouseEnter/mouseLeave handlers firing
+    // back and forth when the cursor sits on the edge between two components.
     if (!React.isValidElement(children)) {
         return _jsx(_Fragment, { children: children });
     }
-    const existingProps = (children.props || {});
-    const existingOnMouseEnter = existingProps.onMouseEnter;
-    const existingOnMouseLeave = existingProps.onMouseLeave;
-    const existingOnTouchStart = existingProps.onTouchStart;
-    const existingOnTouchEnd = existingProps.onTouchEnd;
-    const childWithProps = React.cloneElement(children, {
-        onMouseEnter: (e) => {
-            handleMouseEnter(e);
-            if (existingOnMouseEnter) {
-                existingOnMouseEnter(e);
-            }
-        },
-        onMouseLeave: (e) => {
-            handleMouseLeave();
-            if (existingOnMouseLeave) {
-                existingOnMouseLeave(e);
-            }
-        },
-        onTouchStart: (e) => {
-            handleTouchStart(e);
-            if (existingOnTouchStart) {
-                existingOnTouchStart(e);
-            }
-        },
-        onTouchEnd: (e) => {
-            handleTouchEnd();
-            if (existingOnTouchEnd) {
-                existingOnTouchEnd(e);
-            }
-        },
-        "data-inspection-id": generateComponentId(componentName, instanceIndex),
+    const componentId = generateComponentId(componentName, instanceIndex);
+    const propsSignature = formatPropsSignature(props);
+    const dataAttrs = {
+        "data-inspection-id": componentId,
         "data-inspection-name": componentName,
-    });
-    return _jsx(_Fragment, { children: childWithProps });
+        "data-inspection-usage-path": usagePath,
+        "data-inspection-instance": String(instanceIndex),
+        "data-inspection-props": propsSignature,
+        "data-inspection-file": sourceFile,
+    };
+    if (variant)
+        dataAttrs["data-inspection-variant"] = variant;
+    if (role)
+        dataAttrs["data-inspection-role"] = role;
+    return _jsx(_Fragment, { children: React.cloneElement(children, dataAttrs) });
 };
 /**
  * HOC to wrap a component with inspection capabilities

package/dist/autoInspection.js

@@ -259,16 +259,52 @@ export const setupAutoInspection = (setHoveredComponent, isInspectionActive, isL
     const isTouchDevice = 'ontouchstart' in window ||
         navigator.maxTouchPoints > 0 ||
         /Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(navigator.userAgent);
+    // De-dupe: if mousemove resolves to the same DOM element as last time, skip
+    // the state update. Combined with the throttle below this is what prevents
+    // the tooltip from flickering when the cursor sits on a border between two
+    // wrapped components and rapid mouseenter/leave events would otherwise toggle
+    // the hovered element back and forth.
+    let lastInspectedElement = null;
+    const dedupedSetHoveredComponent = (metadata, element) => {
+        if (element === lastInspectedElement)
+            return;
+        lastInspectedElement = element;
+        setHoveredComponent(metadata, element);
+    };
+    // Throttle mousemove processing to ~30 fps. DOM walking on every pixel of
+    // movement (the previous behavior) is wasted work and amplifies any border
+    // jitter into visible flicker.
+    let pendingTarget = null;
+    let throttleHandle = null;
+    const flushPendingTarget = () => {
+        throttleHandle = null;
+        const t = pendingTarget;
+        pendingTarget = null;
+        if (t)
+            inspectElement(t, isInspectionActive, isLocked, dedupedSetHoveredComponent);
+    };
     const handleMouseMove = (e) => {
-        if (!isInspectionActive) {
+        if (!isInspectionActive)
             return;
-        }
-        // If locked, don't update on mouse move - keep current tooltip fixed
-        if (isLocked) {
+        if (isLocked)
             return;
+        // Sticky: while the cursor is still within the bounds of the element we
+        // last anchored the tooltip to, do nothing. This stops the tooltip from
+        // sliding around as the deepest DOM element under the cursor changes
+        // pixel-by-pixel inside a large container.
+        if (lastInspectedElement && document.body.contains(lastInspectedElement)) {
+            const rect = lastInspectedElement.getBoundingClientRect();
+            if (e.clientX >= rect.left &&
+                e.clientX <= rect.right &&
+                e.clientY >= rect.top &&
+                e.clientY <= rect.bottom) {
+                return;
+            }
         }
-        const target = e.target;
-        inspectElement(target, isInspectionActive, isLocked, setHoveredComponent);
+        pendingTarget = e.target;
+        if (throttleHandle !== null)
+            return;
+        throttleHandle = window.setTimeout(flushPendingTarget, 32);
     };
     // Touch move handler for mobile devices
     const handleTouchMove = (e) => {
@@ -280,7 +316,7 @@ export const setupAutoInspection = (setHoveredComponent, isInspectionActive, isL
         const touch = e.touches[0];
         const target = document.elementFromPoint(touch.clientX, touch.clientY);
         if (target) {
-            inspectElement(target, isInspectionActive, isLocked, setHoveredComponent);
+            inspectElement(target, isInspectionActive, isLocked, dedupedSetHoveredComponent);
         }
     };
     // Touch start handler for mobile - inspect on touch
@@ -294,17 +330,19 @@ export const setupAutoInspection = (setHoveredComponent, isInspectionActive, isL
         const touch = e.touches[0];
         const target = document.elementFromPoint(touch.clientX, touch.clientY);
         if (target) {
-            inspectElement(target, isInspectionActive, isLocked, setHoveredComponent);
+            inspectElement(target, isInspectionActive, isLocked, dedupedSetHoveredComponent);
         }
     };
     const handleMouseLeave = () => {
         if (isInspectionActive && !isLocked) {
+            lastInspectedElement = null;
             setHoveredComponent(null, null);
         }
     };
     const handleTouchEnd = () => {
         // Clear inspection on touch end (unless locked)
         if (isInspectionActive && !isLocked) {
+            lastInspectedElement = null;
             setHoveredComponent(null, null);
         }
     };
@@ -320,6 +358,10 @@ export const setupAutoInspection = (setHoveredComponent, isInspectionActive, isL
     return () => {
         window.removeEventListener("mousemove", handleMouseMove);
         document.removeEventListener("mouseleave", handleMouseLeave);
+        if (throttleHandle !== null) {
+            clearTimeout(throttleHandle);
+            throttleHandle = null;
+        }
         if (isTouchDevice) {
             window.removeEventListener("touchmove", handleTouchMove);
             window.removeEventListener("touchstart", handleTouchStart);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zargaryanvh/react-component-inspector",
-  "version": "1.0.7",
+  "version": "1.0.8",
   "description": "A development tool for inspecting React components with AI-friendly metadata extraction",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",