@zargaryanvh/react-component-inspector 1.0.2 → 1.0.3

package/dist/InspectionContext.d.ts

@@ -1,35 +1,37 @@
-import React, { ReactNode } from "react";
-/**
- * Component inspection metadata
- */
-export interface ComponentMetadata {
-    componentName: string;
-    componentId: string;
-    variant?: string;
-    role?: string;
-    usagePath: string;
-    instanceIndex: number;
-    propsSignature: string;
-    sourceFile: string;
-}
-/**
- * Inspection context state
- */
-interface InspectionState {
-    isInspectionActive: boolean;
-    isLocked: boolean;
-    hoveredComponent: ComponentMetadata | null;
-    hoveredElement: HTMLElement | null;
-    setHoveredComponent: (component: ComponentMetadata | null, element: HTMLElement | null) => void;
-}
-/**
- * Inspection Provider - Only active in development
- */
-export declare const InspectionProvider: React.FC<{
-    children: ReactNode;
-}>;
-/**
- * Hook to access inspection context
- */
-export declare const useInspection: () => InspectionState;
-export {};
+import React, { ReactNode } from "react";
+/**
+ * Component inspection metadata
+ */
+export interface ComponentMetadata {
+    componentName: string;
+    componentId: string;
+    variant?: string;
+    role?: string;
+    usagePath: string;
+    instanceIndex: number;
+    propsSignature: string;
+    sourceFile: string;
+}
+/**
+ * Inspection context state
+ */
+interface InspectionState {
+    isInspectionActive: boolean;
+    isLocked: boolean;
+    isMobile: boolean;
+    isMarginPaddingMode: boolean;
+    hoveredComponent: ComponentMetadata | null;
+    hoveredElement: HTMLElement | null;
+    setHoveredComponent: (component: ComponentMetadata | null, element: HTMLElement | null) => void;
+}
+/**
+ * Inspection Provider - Only active in development
+ */
+export declare const InspectionProvider: React.FC<{
+    children: ReactNode;
+}>;
+/**
+ * Hook to access inspection context
+ */
+export declare const useInspection: () => InspectionState;
+export {};

package/dist/InspectionContext.js

@@ -1,253 +1,236 @@
-import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
-import React, { createContext, useContext, useState, useCallback, useEffect, useRef } from "react";
-import { setInspectionActive } from "./inspectionInterceptors";
-import { setupAutoInspection } from "./autoInspection";
-const InspectionContext = createContext(undefined);
-/**
- * Inspection Provider - Only active in development
- */
-export const InspectionProvider = ({ children }) => {
-    const [isInspectionActive, setIsInspectionActive] = useState(false);
-    const [isLocked, setIsLocked] = useState(false);
-    const [hoveredComponent, setHoveredComponentState] = useState(null);
-    const [hoveredElement, setHoveredElement] = useState(null);
-    // Use refs to always access latest state values in event handlers
-    const isInspectionActiveRef = useRef(isInspectionActive);
-    const isLockedRef = useRef(isLocked);
-    const hoveredComponentRef = useRef(hoveredComponent);
-    const hKeyPressedRef = useRef(false); // Track if H key is currently being held
-    // Mobile touch support
-    const longPressTimerRef = useRef(null);
-    const touchStartTimeRef = useRef(0);
-    const lastTapRef = useRef(0);
-    const isMobileRef = useRef(false);
-    // Detect mobile device
-    useEffect(() => {
-        const checkMobile = () => {
-            if (typeof window === 'undefined')
-                return false;
-            return 'ontouchstart' in window ||
-                navigator.maxTouchPoints > 0 ||
-                /Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(navigator.userAgent);
-        };
-        isMobileRef.current = checkMobile();
-    }, []);
-    // Keep refs in sync with state
-    useEffect(() => {
-        isInspectionActiveRef.current = isInspectionActive;
-    }, [isInspectionActive]);
-    useEffect(() => {
-        isLockedRef.current = isLocked;
-    }, [isLocked]);
-    useEffect(() => {
-        hoveredComponentRef.current = hoveredComponent;
-    }, [hoveredComponent]);
-    // Mobile touch handlers for activation and locking
-    React.useEffect(() => {
-        if (process.env.NODE_ENV !== "development") {
-            return; // Only in development
-        }
-        // Long-press to activate inspection mode (mobile)
-        const handleTouchStart = (e) => {
-            if (!isMobileRef.current)
-                return;
-            // Only activate if touching with 3 fingers (to avoid accidental activation)
-            if (e.touches.length === 3) {
-                touchStartTimeRef.current = Date.now();
-                longPressTimerRef.current = setTimeout(() => {
-                    setIsInspectionActive(true);
-                    setInspectionActive(true);
-                    if (process.env.NODE_ENV === "development") {
-                        console.log("[Inspection] Activated (mobile) - Long-press with 3 fingers. Double-tap tooltip to lock.");
-                    }
-                }, 800); // 800ms long-press
-            }
-        };
-        const handleTouchEnd = (e) => {
-            if (!isMobileRef.current)
-                return;
-            // Clear long-press timer
-            if (longPressTimerRef.current) {
-                clearTimeout(longPressTimerRef.current);
-                longPressTimerRef.current = null;
-            }
-            // Double-tap detection for locking (on tooltip or component)
-            const now = Date.now();
-            const timeSinceLastTap = now - lastTapRef.current;
-            if (timeSinceLastTap < 300 && timeSinceLastTap > 0) {
-                // Double-tap detected
-                if (isInspectionActiveRef.current && hoveredComponentRef.current && !isLockedRef.current) {
-                    setIsLocked(true);
-                    if (process.env.NODE_ENV === "development") {
-                        console.log("[Inspection] Tooltip LOCKED (mobile) - Double-tap again to unlock.");
-                    }
-                }
-                else if (isLockedRef.current) {
-                    // Unlock on double-tap when locked
-                    setIsLocked(false);
-                    if (process.env.NODE_ENV === "development") {
-                        console.log("[Inspection] Tooltip UNLOCKED (mobile) - inspection continues.");
-                    }
-                }
-                lastTapRef.current = 0; // Reset
-            }
-            else {
-                lastTapRef.current = now;
-            }
-            // Deactivate if 3-finger touch ends and inspection was active
-            if (e.touches.length === 0 && isInspectionActiveRef.current) {
-                const touchDuration = Date.now() - touchStartTimeRef.current;
-                // Only deactivate if it was a quick tap (not a long-press that activated)
-                if (touchDuration < 800) {
-                    setIsInspectionActive(false);
-                    setIsLocked(false);
-                    hKeyPressedRef.current = false;
-                    setInspectionActive(false);
-                    setHoveredComponentState(null);
-                    setHoveredElement(null);
-                    if (process.env.NODE_ENV === "development") {
-                        console.log("[Inspection] Deactivated (mobile)");
-                    }
-                }
-            }
-        };
-        const handleTouchCancel = () => {
-            if (!isMobileRef.current)
-                return;
-            if (longPressTimerRef.current) {
-                clearTimeout(longPressTimerRef.current);
-                longPressTimerRef.current = null;
-            }
-        };
-        // Track CTRL key state and CTRL+H for locking (desktop)
-        const handleKeyDown = (e) => {
-            // H key pressed while CTRL is held - lock tooltip position
-            if (e.key.toLowerCase() === "h" && e.ctrlKey) {
-                e.preventDefault();
-                e.stopPropagation();
-                // Ignore repeated keydown events (when key is held down)
-                if (e.repeat) {
-                    return;
-                }
-                // Only lock if inspection is active, we have a hovered component, and H is not already being held
-                if (isInspectionActiveRef.current && hoveredComponentRef.current && !hKeyPressedRef.current) {
-                    hKeyPressedRef.current = true;
-                    setIsLocked(true);
-                    if (process.env.NODE_ENV === "development") {
-                        console.log("[Inspection] Tooltip LOCKED - Hold H to keep locked. Release H to unlock.");
-                    }
-                }
-                return;
-            }
-            // CTRL key pressed
-            if (e.key === "Control" && !e.repeat) {
-                setIsInspectionActive(true);
-                setInspectionActive(true);
-                if (process.env.NODE_ENV === "development") {
-                    console.log("[Inspection] Activated - Hold CTRL and hover over components. Press H to lock tooltip position.");
-                }
-            }
-        };
-        const handleKeyUp = (e) => {
-            // H key released - unlock tooltip but keep inspection active if CTRL is still held
-            if (e.key.toLowerCase() === "h") {
-                e.preventDefault();
-                e.stopPropagation();
-                // Only process if H was actually being held
-                if (hKeyPressedRef.current) {
-                    const wasLocked = isLockedRef.current;
-                    hKeyPressedRef.current = false;
-                    // Only unlock if we were locked and CTRL is still held
-                    if (wasLocked && e.ctrlKey && isInspectionActiveRef.current) {
-                        setIsLocked(false);
-                        if (process.env.NODE_ENV === "development") {
-                            console.log("[Inspection] Tooltip UNLOCKED - inspection continues while CTRL is held.");
-                        }
-                    }
-                }
-                return;
-            }
-            // CTRL key released - unlock and clear
-            if (e.key === "Control") {
-                setIsInspectionActive(false);
-                setIsLocked(false);
-                hKeyPressedRef.current = false;
-                setInspectionActive(false);
-                setHoveredComponentState(null);
-                setHoveredElement(null);
-                if (process.env.NODE_ENV === "development") {
-                    console.log("[Inspection] Deactivated");
-                }
-            }
-        };
-        window.addEventListener("keydown", handleKeyDown);
-        window.addEventListener("keyup", handleKeyUp);
-        // Mobile touch events
-        window.addEventListener("touchstart", handleTouchStart, { passive: true });
-        window.addEventListener("touchend", handleTouchEnd, { passive: true });
-        window.addEventListener("touchcancel", handleTouchCancel, { passive: true });
-        return () => {
-            window.removeEventListener("keydown", handleKeyDown);
-            window.removeEventListener("keyup", handleKeyUp);
-            window.removeEventListener("touchstart", handleTouchStart);
-            window.removeEventListener("touchend", handleTouchEnd);
-            window.removeEventListener("touchcancel", handleTouchCancel);
-            // Cleanup timers
-            if (longPressTimerRef.current) {
-                clearTimeout(longPressTimerRef.current);
-            }
-        };
-    }, []); // Empty deps - refs handle state access
-    const setHoveredComponent = useCallback((component, element) => {
-        if (process.env.NODE_ENV !== "development") {
-            return; // Only in development
-        }
-        // Validate element is still in DOM before setting
-        if (element && !document.body.contains(element)) {
-            setHoveredComponentState(null);
-            setHoveredElement(null);
-            return;
-        }
-        setHoveredComponentState(component);
-        setHoveredElement(element);
-    }, []);
-    // Setup automatic inspection detection via data attributes
-    useEffect(() => {
-        if (process.env.NODE_ENV !== "development") {
-            return;
-        }
-        const cleanup = setupAutoInspection(setHoveredComponent, isInspectionActive, isLocked);
-        return cleanup;
-    }, [isInspectionActive, isLocked, setHoveredComponent]);
-    // Don't render provider in production
-    if (process.env.NODE_ENV !== "development") {
-        return _jsx(_Fragment, { children: children });
-    }
-    return (_jsx(InspectionContext.Provider, { value: {
-            isInspectionActive,
-            isLocked,
-            hoveredComponent,
-            hoveredElement,
-            setHoveredComponent,
-        }, children: children }));
-};
-/**
- * Hook to access inspection context
- */
-export const useInspection = () => {
-    const context = useContext(InspectionContext);
-    if (process.env.NODE_ENV !== "development") {
-        // Return dummy state in production
-        return {
-            isInspectionActive: false,
-            isLocked: false,
-            hoveredComponent: null,
-            hoveredElement: null,
-            setHoveredComponent: () => { },
-        };
-    }
-    if (!context) {
-        throw new Error("useInspection must be used within InspectionProvider");
-    }
-    return context;
-};
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import React, { createContext, useContext, useState, useCallback, useEffect, useRef } from "react";
+import { setInspectionActive } from "./inspectionInterceptors";
+import { setupAutoInspection } from "./autoInspection";
+const InspectionContext = createContext(undefined);
+/**
+ * Inspection Provider - Only active in development
+ */
+export const InspectionProvider = ({ children }) => {
+    const [ctrlHeld, setCtrlHeld] = useState(false);
+    const [isStickyInspection, setIsStickyInspection] = useState(false);
+    const isInspectionActive = ctrlHeld || isStickyInspection;
+    const [isLocked, setIsLocked] = useState(false);
+    const [isMarginPaddingMode, setIsMarginPaddingMode] = useState(false);
+    const [hoveredComponent, setHoveredComponentState] = useState(null);
+    const [hoveredElement, setHoveredElement] = useState(null);
+    // Use refs to always access latest state values in event handlers
+    const isInspectionActiveRef = useRef(isInspectionActive);
+    const isLockedRef = useRef(isLocked);
+    const isStickyInspectionRef = useRef(isStickyInspection);
+    const hoveredComponentRef = useRef(hoveredComponent);
+    const hKeyPressedRef = useRef(false);
+    // Touch support for locking only (3/4 finger activation removed - use Ctrl+Shift+R on laptop)
+    const lastTapRef = useRef(0);
+    const [isMobile, setIsMobile] = useState(false);
+    useEffect(() => {
+        const checkMobile = () => {
+            if (typeof window === 'undefined')
+                return false;
+            return 'ontouchstart' in window ||
+                navigator.maxTouchPoints > 0 ||
+                /Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(navigator.userAgent);
+        };
+        setIsMobile(checkMobile());
+    }, []);
+    // Keep refs in sync with state
+    useEffect(() => {
+        isInspectionActiveRef.current = isInspectionActive;
+    }, [isInspectionActive]);
+    useEffect(() => {
+        isLockedRef.current = isLocked;
+    }, [isLocked]);
+    useEffect(() => {
+        hoveredComponentRef.current = hoveredComponent;
+    }, [hoveredComponent]);
+    useEffect(() => {
+        isStickyInspectionRef.current = isStickyInspection;
+    }, [isStickyInspection]);
+    // Only block API/fetch when CTRL is physically held (not when sticky inspection is on)
+    useEffect(() => {
+        setInspectionActive(ctrlHeld);
+    }, [ctrlHeld]);
+    // Mobile touch handlers for activation and locking
+    React.useEffect(() => {
+        if (process.env.NODE_ENV !== "development") {
+            return; // Only in development
+        }
+        // Double-tap for locking tooltip (touch devices)
+        const handleTouchEnd = (e) => {
+            if (!('ontouchstart' in window) && navigator.maxTouchPoints === 0)
+                return;
+            const now = Date.now();
+            const timeSinceLastTap = now - lastTapRef.current;
+            if (timeSinceLastTap < 300 && timeSinceLastTap > 0) {
+                if (isInspectionActiveRef.current && hoveredComponentRef.current && !isLockedRef.current) {
+                    setIsLocked(true);
+                }
+                else if (isLockedRef.current) {
+                    setIsLocked(false);
+                }
+                lastTapRef.current = 0;
+            }
+            else {
+                lastTapRef.current = now;
+            }
+        };
+        // Keyboard: CTRL, CTRL+Shift+R (toggle inspection), CTRL+M (margin/padding), CTRL+H (lock)
+        const handleKeyDown = (e) => {
+            // R key with CTRL+Shift - toggle inspection on/off (sticky, for mobile viewport on laptop)
+            if (e.key && e.key.toLowerCase() === "r" && e.ctrlKey && e.shiftKey) {
+                e.preventDefault();
+                e.stopPropagation();
+                if (!e.repeat) {
+                    setIsStickyInspection(prev => {
+                        const next = !prev;
+                        if (!next) {
+                            setHoveredComponentState(null);
+                            setHoveredElement(null);
+                            setIsLocked(false);
+                        }
+                        if (process.env.NODE_ENV === "development") {
+                            console.log("[Inspection] Inspection toggled (Ctrl+Shift+R):", next ? "ON" : "OFF");
+                        }
+                        return next;
+                    });
+                }
+                return;
+            }
+            // M key with CTRL (hold) - margin/padding mode while held, inspect on mouse move
+            if (e.key && e.key.toLowerCase() === "m" && e.ctrlKey && !e.shiftKey && !e.altKey) {
+                e.preventDefault();
+                e.stopPropagation();
+                if (!e.repeat) {
+                    setIsMarginPaddingMode(true);
+                    setCtrlHeld(true);
+                }
+                return;
+            }
+            // H key pressed while CTRL is held - lock tooltip position
+            if (e.key && e.key.toLowerCase() === "h" && e.ctrlKey) {
+                e.preventDefault();
+                e.stopPropagation();
+                // Ignore repeated keydown events (when key is held down)
+                if (e.repeat) {
+                    return;
+                }
+                // Only lock if inspection is active, we have a hovered component, and H is not already being held
+                if (isInspectionActiveRef.current && hoveredComponentRef.current && !hKeyPressedRef.current) {
+                    hKeyPressedRef.current = true;
+                    setIsLocked(true);
+                    if (process.env.NODE_ENV === "development") {
+                        console.log("[Inspection] Tooltip LOCKED - Hold H to keep locked. Release H to unlock.");
+                    }
+                }
+                return;
+            }
+            // CTRL key pressed
+            if (e.key === "Control" && !e.repeat) {
+                setCtrlHeld(true);
+            }
+        };
+        const handleKeyUp = (e) => {
+            // H key released - unlock tooltip but keep inspection active if CTRL is still held
+            if (e.key && e.key.toLowerCase() === "h") {
+                e.preventDefault();
+                e.stopPropagation();
+                // Only process if H was actually being held
+                if (hKeyPressedRef.current) {
+                    const wasLocked = isLockedRef.current;
+                    hKeyPressedRef.current = false;
+                    // Only unlock if we were locked and CTRL is still held
+                    if (wasLocked && e.ctrlKey && isInspectionActiveRef.current) {
+                        setIsLocked(false);
+                        if (process.env.NODE_ENV === "development") {
+                            console.log("[Inspection] Tooltip UNLOCKED - inspection continues while CTRL is held.");
+                        }
+                    }
+                }
+                return;
+            }
+            // M key released - turn off margin/padding mode (hold-to-use, no toggle)
+            if (e.key && e.key.toLowerCase() === "m") {
+                setIsMarginPaddingMode(false);
+            }
+            // CTRL key released - clear only if not in sticky mode
+            if (e.key === "Control") {
+                setCtrlHeld(false);
+                hKeyPressedRef.current = false;
+                if (!isStickyInspectionRef.current) {
+                    setIsMarginPaddingMode(false);
+                    setIsLocked(false);
+                    setHoveredComponentState(null);
+                    setHoveredElement(null);
+                }
+            }
+        };
+        window.addEventListener("keydown", handleKeyDown);
+        window.addEventListener("keyup", handleKeyUp);
+        if ('ontouchstart' in window || navigator.maxTouchPoints > 0) {
+            window.addEventListener("touchend", handleTouchEnd, { passive: true });
+        }
+        return () => {
+            window.removeEventListener("keydown", handleKeyDown);
+            window.removeEventListener("keyup", handleKeyUp);
+            window.removeEventListener("touchend", handleTouchEnd);
+        };
+    }, []); // Empty deps - refs handle state access
+    const setHoveredComponentRef = useRef(() => { });
+    const setHoveredComponent = useCallback((component, element) => {
+        if (process.env.NODE_ENV !== "development") {
+            return; // Only in development
+        }
+        // Validate element is still in DOM before setting
+        if (element && !document.body.contains(element)) {
+            setHoveredComponentState(null);
+            setHoveredElement(null);
+            return;
+        }
+        setHoveredComponentState(component);
+        setHoveredElement(element);
+    }, []);
+    setHoveredComponentRef.current = setHoveredComponent;
+    // Setup automatic inspection detection via data attributes
+    useEffect(() => {
+        if (process.env.NODE_ENV !== "development") {
+            return;
+        }
+        const cleanup = setupAutoInspection(setHoveredComponent, isInspectionActive, isLocked);
+        return cleanup;
+    }, [isInspectionActive, isLocked, setHoveredComponent]);
+    // Don't render provider in production
+    if (process.env.NODE_ENV !== "development") {
+        return _jsx(_Fragment, { children: children });
+    }
+    return (_jsx(InspectionContext.Provider, { value: {
+            isInspectionActive,
+            isLocked,
+            isMobile,
+            isMarginPaddingMode,
+            hoveredComponent,
+            hoveredElement,
+            setHoveredComponent,
+        }, children: children }));
+};
+/**
+ * Hook to access inspection context
+ */
+export const useInspection = () => {
+    const context = useContext(InspectionContext);
+    if (process.env.NODE_ENV !== "development") {
+        // Return dummy state in production
+        return {
+            isInspectionActive: false,
+            isLocked: false,
+            isMobile: false,
+            isMarginPaddingMode: false,
+            hoveredComponent: null,
+            hoveredElement: null,
+            setHoveredComponent: () => { },
+        };
+    }
+    if (!context) {
+        throw new Error("useInspection must be used within InspectionProvider");
+    }
+    return context;
+};

package/dist/InspectionHighlight.d.ts

@@ -1,6 +1,2 @@
-import React from "react";
-/**
- * Highlight overlay that shows the boundary of the hovered component
- * Only visible when CTRL is held and a component is hovered
- */
-export declare const InspectionHighlight: React.FC;
+import React from "react";
+export declare const InspectionHighlight: React.FC;