@zargaryanvh/react-component-inspector 1.0.0

package/dist/inspection.js

@@ -0,0 +1,140 @@
+/**
+ * Generate a unique component ID
+ */
+export const generateComponentId = (componentName, instanceIndex) => {
+    return `${componentName.toLowerCase().replace(/\s+/g, "-")}-${instanceIndex}`;
+};
+/**
+ * Format props signature for display
+ */
+export const formatPropsSignature = (props) => {
+    const keyProps = [];
+    // Include props that affect behavior/rendering
+    const importantProps = ["variant", "role", "type", "mode", "status", "disabled", "selected", "active"];
+    for (const key of importantProps) {
+        if (key in props && props[key] !== undefined && props[key] !== null) {
+            const value = props[key];
+            if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+                keyProps.push(`${key}=${String(value)}`);
+            }
+        }
+    }
+    return keyProps.length > 0 ? keyProps.join(", ") : "default";
+};
+/**
+ * Get component name from component type
+ */
+export const getComponentName = (component) => {
+    if (typeof component === "string") {
+        return component;
+    }
+    return component.displayName || component.name || "Unknown";
+};
+/**
+ * Build usage path from component hierarchy
+ */
+export const buildUsagePath = (hierarchy) => {
+    return hierarchy.join(" > ");
+};
+/**
+ * Format metadata for clipboard with full element details
+ */
+export const formatMetadataForClipboard = (metadata, element) => {
+    const lines = [];
+    // Element identification (most important for AI understanding)
+    lines.push(`=== ELEMENT IDENTIFICATION ===`);
+    lines.push(`Element Type: ${element.tagName.toLowerCase()}`);
+    // Get element text content (label/button text)
+    const textContent = element.textContent?.trim() || "";
+    const visibleText = textContent.substring(0, 100).replace(/\s+/g, " ");
+    if (visibleText) {
+        lines.push(`Element Text/Label: "${visibleText}"`);
+    }
+    // Element ID (if exists)
+    if (element.id) {
+        lines.push(`Element ID: ${element.id}`);
+    }
+    // Element classes (first few meaningful ones)
+    if (element.className) {
+        // Convert className to string - it can be a DOMTokenList or string
+        const classNameStr = typeof element.className === "string"
+            ? element.className
+            : String(element.className);
+        const classes = classNameStr.split(/\s+/).filter(c => c && !c.startsWith("Mui")).slice(0, 5);
+        if (classes.length > 0) {
+            lines.push(`Element Classes: ${classes.join(", ")}`);
+        }
+    }
+    // Data attributes that might help identify the element
+    const dataAttrs = [];
+    Array.from(element.attributes).forEach(attr => {
+        if (attr.name.startsWith("data-") && !attr.name.startsWith("data-inspection-")) {
+            dataAttrs.push(`${attr.name}="${attr.value}"`);
+        }
+    });
+    if (dataAttrs.length > 0) {
+        lines.push(`Data Attributes: ${dataAttrs.slice(0, 3).join(", ")}`);
+    }
+    // Role/aria-label for accessibility
+    const role = element.getAttribute("role") || metadata.role;
+    const ariaLabel = element.getAttribute("aria-label");
+    if (role) {
+        lines.push(`Role: ${role}`);
+    }
+    if (ariaLabel) {
+        lines.push(`Aria Label: "${ariaLabel}"`);
+    }
+    // Component metadata
+    lines.push(``);
+    lines.push(`=== COMPONENT METADATA ===`);
+    lines.push(`Component Name: ${metadata.componentName}`);
+    lines.push(`Component ID: ${metadata.componentId}`);
+    if (metadata.variant) {
+        lines.push(`Variant: ${metadata.variant}`);
+    }
+    lines.push(`Usage Path: ${metadata.usagePath}`);
+    lines.push(`Instance: ${metadata.instanceIndex}`);
+    lines.push(`Props: ${metadata.propsSignature}`);
+    lines.push(`Source File: ${metadata.sourceFile}`);
+    // CSS selector for direct targeting
+    lines.push(``);
+    lines.push(`=== CSS SELECTOR ===`);
+    let selector = element.tagName.toLowerCase();
+    if (element.id) {
+        selector = `#${element.id}`;
+    }
+    else if (element.className) {
+        // Convert className to string - it can be a DOMTokenList or string
+        const classNameStr = typeof element.className === "string"
+            ? element.className
+            : String(element.className);
+        const firstClass = classNameStr.split(/\s+/).find(c => c && !c.startsWith("Mui"));
+        if (firstClass) {
+            selector = `${element.tagName.toLowerCase()}.${firstClass}`;
+        }
+    }
+    lines.push(`Selector: ${selector}`);
+    // Visual description
+    const rect = element.getBoundingClientRect();
+    lines.push(`Position: (${Math.round(rect.left)}, ${Math.round(rect.top)})`);
+    lines.push(`Size: ${Math.round(rect.width)}x${Math.round(rect.height)}px`);
+    return lines.join("\n");
+};
+/**
+ * Track component instances for instance indexing
+ */
+const componentInstanceCounts = new Map();
+/**
+ * Get next instance index for a component
+ */
+export const getNextInstanceIndex = (componentName) => {
+    const current = componentInstanceCounts.get(componentName) || 0;
+    componentInstanceCounts.set(componentName, current + 1);
+    return current;
+};
+/**
+ * Reset instance counts (useful for testing or remounting)
+ */
+export const resetInstanceCounts = () => {
+    componentInstanceCounts.clear();
+};

package/dist/inspectionInterceptors.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Interceptors to block API and Firebase requests when CTRL is pressed
+ * Only active in development
+ */
+/**
+ * Set inspection active state (called from InspectionContext)
+ */
+export declare const setInspectionActive: (active: boolean) => void;
+/**
+ * Check if inspection is active and requests should be blocked
+ */
+export declare const shouldBlockRequest: () => boolean;
+/**
+ * Intercept fetch requests (for API calls)
+ */
+export declare const setupFetchInterceptor: () => void;
+/**
+ * Intercept Firebase Firestore operations
+ * Note: Firestore operations are harder to intercept at the SDK level
+ * We'll rely on blocking at the fetch level (which Firestore uses internally)
+ * and also provide a wrapper utility for direct Firestore calls
+ */
+export declare const setupFirestoreInterceptor: () => void;
+/**
+ * Setup all interceptors
+ */
+export declare const setupInterceptors: () => void;

package/dist/inspectionInterceptors.js

@@ -0,0 +1,64 @@
+/**
+ * Interceptors to block API and Firebase requests when CTRL is pressed
+ * Only active in development
+ */
+let isInspectionActive = false;
+/**
+ * Set inspection active state (called from InspectionContext)
+ */
+export const setInspectionActive = (active) => {
+    if (process.env.NODE_ENV !== "development") {
+        return;
+    }
+    isInspectionActive = active;
+};
+/**
+ * Check if inspection is active and requests should be blocked
+ */
+export const shouldBlockRequest = () => {
+    if (process.env.NODE_ENV !== "development") {
+        return false;
+    }
+    return isInspectionActive;
+};
+/**
+ * Intercept fetch requests (for API calls)
+ */
+export const setupFetchInterceptor = () => {
+    if (process.env.NODE_ENV !== "development") {
+        return;
+    }
+    const originalFetch = window.fetch;
+    window.fetch = async (...args) => {
+        if (shouldBlockRequest()) {
+            console.warn("[Inspection] Blocked API request (CTRL held):", args[0]);
+            // Return a rejected promise to prevent the request
+            return Promise.reject(new Error("Request blocked: Inspection mode active (CTRL held)"));
+        }
+        return originalFetch(...args);
+    };
+};
+/**
+ * Intercept Firebase Firestore operations
+ * Note: Firestore operations are harder to intercept at the SDK level
+ * We'll rely on blocking at the fetch level (which Firestore uses internally)
+ * and also provide a wrapper utility for direct Firestore calls
+ */
+export const setupFirestoreInterceptor = () => {
+    if (process.env.NODE_ENV !== "development") {
+        return;
+    }
+    // Firestore uses fetch internally, so the fetch interceptor will catch most operations
+    // For direct Firestore SDK calls, we'll need to wrap them manually
+    // This is a limitation of the Firestore SDK architecture
+};
+/**
+ * Setup all interceptors
+ */
+export const setupInterceptors = () => {
+    if (process.env.NODE_ENV !== "development") {
+        return;
+    }
+    setupFetchInterceptor();
+    setupFirestoreInterceptor();
+};

package/dist/useInspectionMetadata.d.ts

@@ -0,0 +1,32 @@
+import React from "react";
+/**
+ * Hook to add inspection metadata to a component
+ *
+ * Usage:
+ * ```tsx
+ * const MyComponent = (props) => {
+ *   const inspectionProps = useInspectionMetadata({
+ *     componentName: "MyComponent",
+ *     variant: props.variant,
+ *     usagePath: "ActivityPage > TransactionList",
+ *     props,
+ *     sourceFile: "src/components/MyComponent.tsx",
+ *   });
+ *
+ *   return <Box {...inspectionProps}>...</Box>;
+ * };
+ * ```
+ */
+export declare const useInspectionMetadata: (config: {
+    componentName: string;
+    variant?: string;
+    role?: string;
+    usagePath: string;
+    props: Record<string, any>;
+    sourceFile: string;
+}) => {
+    onMouseEnter: (e: React.MouseEvent) => void;
+    onMouseLeave: () => void;
+    "data-inspection-id": string;
+    "data-inspection-name": string;
+};

package/dist/useInspectionMetadata.js

@@ -0,0 +1,52 @@
+import { useMemo } from "react";
+import { useInspection } from "./InspectionContext";
+import { generateComponentId, formatPropsSignature, getNextInstanceIndex, } from "./inspection";
+/**
+ * Hook to add inspection metadata to a component
+ *
+ * Usage:
+ * ```tsx
+ * const MyComponent = (props) => {
+ *   const inspectionProps = useInspectionMetadata({
+ *     componentName: "MyComponent",
+ *     variant: props.variant,
+ *     usagePath: "ActivityPage > TransactionList",
+ *     props,
+ *     sourceFile: "src/components/MyComponent.tsx",
+ *   });
+ *
+ *   return <Box {...inspectionProps}>...</Box>;
+ * };
+ * ```
+ */
+export const useInspectionMetadata = (config) => {
+    const { isInspectionActive, setHoveredComponent } = useInspection();
+    const instanceIndex = useMemo(() => getNextInstanceIndex(config.componentName), [config.componentName]);
+    const metadata = useMemo(() => ({
+        componentName: config.componentName,
+        componentId: generateComponentId(config.componentName, instanceIndex),
+        variant: config.variant,
+        role: config.role,
+        usagePath: config.usagePath,
+        instanceIndex,
+        propsSignature: formatPropsSignature(config.props),
+        sourceFile: config.sourceFile,
+    }), [config, instanceIndex]);
+    const handleMouseEnter = (e) => {
+        if (!isInspectionActive)
+            return;
+        const target = e.currentTarget;
+        setHoveredComponent(metadata, target);
+    };
+    const handleMouseLeave = () => {
+        if (!isInspectionActive)
+            return;
+        setHoveredComponent(null, null);
+    };
+    return {
+        onMouseEnter: handleMouseEnter,
+        onMouseLeave: handleMouseLeave,
+        "data-inspection-id": metadata.componentId,
+        "data-inspection-name": config.componentName,
+    };
+};

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@zargaryanvh/react-component-inspector",
+  "version": "1.0.0",
+  "description": "A development tool for inspecting React components with AI-friendly metadata extraction",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist/**/*",
+    "README.md",
+    "LICENSE",
+    "package.json"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "react",
+    "component",
+    "inspection",
+    "development",
+    "debugging",
+    "ai",
+    "metadata",
+    "tool",
+    "cursor",
+    "cursor-ai"
+  ],
+  "author": "zargaryanvh",
+  "license": "MIT",
+  "peerDependencies": {
+    "react": ">=16.8.0",
+    "react-dom": ">=16.8.0",
+    "@mui/material": ">=5.0.0",
+    "@mui/icons-material": ">=5.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.0.0",
+    "@types/react-dom": "^18.0.0",
+    "typescript": "^5.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zargaryanvh/react-component-inspector.git"
+  }
+}