@zargaryanvh/react-component-inspector 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,274 @@
+# React Component Inspector
+
+> **A powerful development tool for inspecting React components with AI-friendly metadata extraction. Fully designed by Cursor AI.**
+
+## 🎯 What is This?
+
+React Component Inspector is a development-only tool that helps you identify, inspect, and extract detailed metadata from React components in your application. It's designed to work seamlessly with AI coding assistants (like Cursor) by providing structured, copyable metadata about any component in your UI.
+
+## 🔍 What Problem Does It Solve?
+
+### The Challenge
+When working with AI assistants to fix or modify frontend code, you often need to:
+- Identify which component is responsible for a specific UI element
+- Understand the component's props, variants, and usage context
+- Get the exact file path and component structure
+- Extract CSS selectors and element identifiers for precise targeting
+
+**Without this tool**, you'd need to:
+- Manually inspect the DOM
+- Search through codebases
+- Guess component names and file locations
+- Manually extract element information
+
+### The Solution
+React Component Inspector provides:
+- **One-click component identification** - Just hold CTRL and hover
+- **Rich metadata extraction** - Component name, props, file path, usage context
+- **AI-optimized format** - Copy-paste ready metadata for AI assistants
+- **Zero production overhead** - Completely disabled in production builds
+
+## 📊 What Data Does It Provide?
+
+When you inspect a component, you get:
+
+### Element Identification
+- Element type (HTML tag)
+- Element text/label content
+- Element ID
+- CSS classes
+- CSS selector
+- Position and size
+- Role and accessibility attributes
+
+### Component Metadata
+- Component name
+- Component ID (unique instance identifier)
+- Variant (if applicable)
+- Usage path (component hierarchy)
+- Instance index
+- Props signature (key props affecting behavior)
+- Source file path
+
+### Example Output
+```
+=== ELEMENT IDENTIFICATION ===
+Element Type: button
+Element Text/Label: "Save Transaction"
+Element ID: save-button
+Element Classes: MuiButton-root, primary-button
+CSS Selector: button#save-button
+Position: (450, 320)
+Size: 120x36px
+
+=== COMPONENT METADATA ===
+Component Name: SaveButton
+Component ID: save-button-0
+Variant: primary
+Usage Path: ActivityPage > EditTransactionModal > TransactionForm
+Instance: 0
+Props: variant=primary, disabled=false
+Source File: src/components/buttons/SaveButton.tsx
+```
+
+## 🚀 How to Use This Data for AI-Powered Frontend Optimization
+
+### 1. **Precise Component Targeting**
+Copy the metadata and ask your AI assistant:
+```
+"I need to modify the SaveButton component. Here's the metadata:
+[paste metadata]
+
+Change the button color to green and add an icon."
+```
+
+### 2. **Context-Aware Refactoring**
+The usage path tells you exactly where the component is used:
+```
+"Refactor the TransactionCard component used in:
+ActivityPage > TransactionList > TransactionCard
+
+Make it accept a new 'priority' prop."
+```
+
+### 3. **CSS Selector Generation**
+Use the CSS selector for automated testing or styling:
+```javascript
+// The metadata provides: button#save-button
+const saveButton = document.querySelector('button#save-button');
+```
+
+### 4. **Component Discovery**
+Find all instances of a component:
+```
+"Find all instances of TransactionCard in the codebase.
+The component is defined in: src/components/transactions/TransactionCard.tsx"
+```
+
+### 5. **AI-Powered Debugging**
+Share component metadata with AI to debug issues:
+```
+"This button isn't working. Component metadata:
+[paste metadata]
+
+The onClick handler should be in: src/components/buttons/SaveButton.tsx"
+```
+
+## 📦 Installation
+
+```bash
+npm install react-component-inspector
+```
+
+## 🔧 Setup
+
+### 1. Wrap Your App
+
+```tsx
+import { InspectionProvider } from 'react-component-inspector';
+import { InspectionTooltip } from 'react-component-inspector';
+import { InspectionHighlight } from 'react-component-inspector';
+import { setupInterceptors } from 'react-component-inspector';
+
+function App() {
+  // Setup request interceptors (optional - blocks API calls when CTRL is held)
+  useEffect(() => {
+    setupInterceptors();
+  }, []);
+
+  return (
+    <InspectionProvider>
+      <YourApp />
+      <InspectionTooltip />
+      <InspectionHighlight />
+    </InspectionProvider>
+  );
+}
+```
+
+### 2. Add Metadata to Components
+
+#### Option A: Using the Hook (Recommended)
+
+```tsx
+import { useInspectionMetadata } from 'react-component-inspector';
+
+function MyButton({ variant, disabled, onClick }) {
+  const inspectionProps = useInspectionMetadata({
+    componentName: "MyButton",
+    variant: variant,
+    usagePath: "HomePage > ActionBar",
+    props: { variant, disabled },
+    sourceFile: "src/components/MyButton.tsx",
+  });
+
+  return (
+    <button {...inspectionProps} onClick={onClick}>
+      Click me
+    </button>
+  );
+}
+```
+
+#### Option B: Using the Wrapper Component
+
+```tsx
+import { InspectionWrapper } from 'react-component-inspector';
+
+function MyComponent({ variant, children }) {
+  return (
+    <InspectionWrapper
+      componentName="MyComponent"
+      variant={variant}
+      usagePath="HomePage > ContentArea"
+      props={{ variant }}
+      sourceFile="src/components/MyComponent.tsx"
+    >
+      <div>{children}</div>
+    </InspectionWrapper>
+  );
+}
+```
+
+#### Option C: Using Data Attributes (Manual)
+
+```tsx
+<div
+  data-inspection-name="MyComponent"
+  data-inspection-id="my-component-0"
+  data-inspection-variant="primary"
+  data-inspection-usage-path="HomePage > ContentArea"
+  data-inspection-instance="0"
+  data-inspection-props="variant=primary"
+  data-inspection-file="src/components/MyComponent.tsx"
+>
+  Content
+</div>
+```
+
+## 🎮 Usage
+
+1. **Activate**: Hold the `CTRL` key (or `Cmd` on Mac)
+2. **Inspect**: Hover over any component with inspection metadata
+3. **View**: A tooltip appears showing component metadata
+4. **Lock**: Press `CTRL+H` to lock the tooltip position
+5. **Copy**: Click the copy icon to copy metadata to clipboard
+6. **Deactivate**: Release `CTRL` to exit inspection mode
+
+## 🛡️ Safety Features
+
+- **Development Only**: Completely disabled in production (`NODE_ENV !== "development"`)
+- **Request Blocking**: When CTRL is held, all API/Firebase requests are blocked to prevent accidental mutations
+- **Zero Overhead**: No code included in production builds
+- **Non-Intrusive**: Doesn't modify your components or affect their behavior
+
+## 📚 Documentation
+
+- [Quick Start Guide](./docs/QUICK_START.md)
+- [API Reference](./docs/API.md)
+- [Advanced Usage](./docs/ADVANCED.md)
+- [AI Integration Guide](./docs/AI_INTEGRATION.md)
+
+## 🎨 Features
+
+- ✅ Visual component highlighting
+- ✅ Rich metadata extraction
+- ✅ Copy-to-clipboard functionality
+- ✅ Automatic component detection
+- ✅ CSS selector generation
+- ✅ Usage path tracking
+- ✅ Instance indexing
+- ✅ Props signature extraction
+- ✅ Request blocking during inspection
+- ✅ Production-safe (zero overhead)
+
+## 🤖 Designed by Cursor AI
+
+This tool was fully designed and developed using [Cursor](https://cursor.sh), an AI-powered code editor. The entire codebase, architecture, and documentation were created through AI-assisted development, demonstrating the power of AI in building developer tools.
+
+## 📄 License
+
+MIT
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## ⚠️ Important Notes
+
+- This tool is **development-only** and will not work in production
+- Requires Material-UI (MUI) for the tooltip UI components
+- Works best with TypeScript but supports JavaScript
+- Request interceptors are optional but recommended for safety
+
+## 💡 Tips for AI Integration
+
+1. **Always copy the full metadata** - It contains all context needed
+2. **Include the usage path** - Helps AI understand component hierarchy
+3. **Share the source file** - Directs AI to the exact location
+4. **Use CSS selectors** - For precise element targeting in AI prompts
+5. **Copy element text** - Helps AI understand component purpose
+
+---
+
+**Made with ❤️ using Cursor AI**

package/dist/InspectionContext.d.ts

@@ -0,0 +1,35 @@
+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 {};

package/dist/InspectionContext.js

@@ -0,0 +1,122 @@
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import React, { createContext, useContext, useState, useCallback, useEffect } 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);
+    // Track CTRL key state and CTRL+H for locking
+    React.useEffect(() => {
+        if (process.env.NODE_ENV !== "development") {
+            return; // Only in development
+        }
+        const handleKeyDown = (e) => {
+            // H key pressed (with or without CTRL) to lock tooltip position while hovering
+            if (e.key.toLowerCase() === "h") {
+                // Only lock if inspection is active, we have a hovered component, and it's not already locked
+                if (isInspectionActive && hoveredComponent && !isLocked) {
+                    e.preventDefault();
+                    setIsLocked(true);
+                    if (process.env.NODE_ENV === "development") {
+                        console.log("[Inspection] Tooltip locked - position fixed. Press H again or release CTRL to unlock.");
+                    }
+                }
+                // If already locked and H is pressed again, unlock (toggle behavior)
+                else if (isLocked && isInspectionActive) {
+                    e.preventDefault();
+                    setIsLocked(false);
+                    if (process.env.NODE_ENV === "development") {
+                        console.log("[Inspection] Tooltip unlocked - inspection continues while CTRL is held.");
+                    }
+                }
+                return;
+            }
+            // CTRL key pressed
+            if (e.key === "Control" || e.ctrlKey) {
+                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) => {
+            // CTRL key released - unlock and clear
+            if (e.key === "Control" || (!e.ctrlKey && e.key !== "h")) {
+                setIsInspectionActive(false);
+                setIsLocked(false);
+                setInspectionActive(false);
+                setHoveredComponentState(null);
+                setHoveredElement(null);
+                if (process.env.NODE_ENV === "development") {
+                    console.log("[Inspection] Deactivated");
+                }
+            }
+            // Note: H key release doesn't unlock anymore - use H key press to toggle lock state
+        };
+        window.addEventListener("keydown", handleKeyDown);
+        window.addEventListener("keyup", handleKeyUp);
+        return () => {
+            window.removeEventListener("keydown", handleKeyDown);
+            window.removeEventListener("keyup", handleKeyUp);
+        };
+    }, [isInspectionActive, hoveredComponent, isLocked]);
+    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;
+};

package/dist/InspectionHighlight.d.ts

@@ -0,0 +1,6 @@
+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;

package/dist/InspectionHighlight.js

@@ -0,0 +1,65 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useState } from "react";
+import { Box } from "@mui/material";
+import { useInspection } from "./InspectionContext";
+/**
+ * Highlight overlay that shows the boundary of the hovered component
+ * Only visible when CTRL is held and a component is hovered
+ */
+export const InspectionHighlight = () => {
+    const { isInspectionActive, hoveredElement } = useInspection();
+    const [highlightStyle, setHighlightStyle] = useState(null);
+    useEffect(() => {
+        // Show highlight for any element when CTRL is held, even without metadata
+        if (!isInspectionActive) {
+            setHighlightStyle(null);
+            return;
+        }
+        // If no hoveredElement but inspection is active, don't show highlight
+        if (!hoveredElement) {
+            setHighlightStyle(null);
+            return;
+        }
+        const updateHighlight = () => {
+            // Check if element is still in the DOM
+            if (!document.body.contains(hoveredElement)) {
+                setHighlightStyle(null);
+                return;
+            }
+            try {
+                const rect = hoveredElement.getBoundingClientRect();
+                setHighlightStyle({
+                    position: "fixed",
+                    left: `${rect.left + window.scrollX}px`,
+                    top: `${rect.top + window.scrollY}px`,
+                    width: `${rect.width}px`,
+                    height: `${rect.height}px`,
+                    pointerEvents: "none",
+                    zIndex: 999998,
+                    border: "2px solid #2196f3",
+                    backgroundColor: "rgba(33, 150, 243, 0.1)",
+                    boxShadow: "0 0 0 1px rgba(33, 150, 243, 0.3), 0 0 8px rgba(33, 150, 243, 0.2)",
+                    borderRadius: "2px",
+                    transition: "all 0.1s ease-out",
+                });
+            }
+            catch (error) {
+                // Element might have been removed, clear highlight
+                setHighlightStyle(null);
+            }
+        };
+        updateHighlight();
+        // Update on scroll/resize
+        const handleUpdate = () => updateHighlight();
+        window.addEventListener("scroll", handleUpdate, true);
+        window.addEventListener("resize", handleUpdate);
+        return () => {
+            window.removeEventListener("scroll", handleUpdate, true);
+            window.removeEventListener("resize", handleUpdate);
+        };
+    }, [isInspectionActive, hoveredElement]);
+    if (!isInspectionActive || !highlightStyle) {
+        return null;
+    }
+    return _jsx(Box, { sx: highlightStyle });
+};

package/dist/InspectionTooltip.d.ts

@@ -0,0 +1,6 @@
+import React from "react";
+/**
+ * Inspection tooltip that shows component metadata
+ * Only visible when CTRL is held and a component is hovered
+ */
+export declare const InspectionTooltip: React.FC;