@linhey/react-debug-inspector 1.0.0

package/README.md

@@ -0,0 +1,59 @@
+# @linhey/react-debug-inspector 🎯
+
+一个轻量级的 React 调试辅助工具，让你在浏览器中直接识别组件、标签及其对应的源码行号。
+
+## 特性
+
+- 🚀 **零配置注入**：通过 Babel 插件自动为每个 JSX 元素添加 `data-debug` 属性。
+- 🎯 **瞄准模式**：悬浮显示元素标识，单击一键复制。
+- 🌳 **零污染**：生产环境构建时自动剔除，不增加包体积。
+- ⌨️ **快捷键支持**：支持 Esc 退出及 Alt+右键 快速复制。
+
+## 安装
+
+```bash
+npm install @linhey/react-debug-inspector --save-dev
+```
+
+## 使用方法
+
+### 1. 配置 Vite (vite.config.ts)
+
+```typescript
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import debugInspector from '@linhey/react-debug-inspector';
+
+export default defineConfig({
+  plugins: [
+    react({
+      babel: {
+        // 仅在开发环境下启用注入
+        plugins: process.env.NODE_ENV === 'development' ? [debugInspector] : []
+      }
+    }),
+  ],
+});
+```
+
+### 2. 初始化交互界面 (main.tsx)
+
+```typescript
+import { initInspector } from '@linhey/react-debug-inspector';
+
+if (import.meta.env.DEV) {
+  initInspector();
+}
+```
+
+## 交互说明
+
+- **🎯 按钮**：位于右下角，点击进入/退出审查模式。
+- **悬浮模式**：进入模式后，鼠标指向的元素将被高亮，并显示 `组件:标签:行号`。
+- **单击左键**：复制标识到剪贴板并退出。
+- **Esc**：退出模式。
+- **Alt + 右键**：非模式下亦可直接复制标识。
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,13 @@
+declare function babelPluginDebugLabel(): {
+    visitor: {
+        FunctionDeclaration(path: any): void;
+        VariableDeclarator(path: any): void;
+    };
+};
+
+/**
+ * 初始化浏览器端的元素定位器交互界面
+ */
+declare function initInspector(): void;
+
+export { babelPluginDebugLabel as default, initInspector };

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+declare function babelPluginDebugLabel(): {
+    visitor: {
+        FunctionDeclaration(path: any): void;
+        VariableDeclarator(path: any): void;
+    };
+};
+
+/**
+ * 初始化浏览器端的元素定位器交互界面
+ */
+declare function initInspector(): void;
+
+export { babelPluginDebugLabel as default, initInspector };

package/dist/index.js

@@ -0,0 +1,209 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  default: () => index_default,
+  initInspector: () => initInspector
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/babel-plugin.ts
+function babelPluginDebugLabel() {
+  return {
+    visitor: {
+      FunctionDeclaration(path) {
+        const name = path.node.id?.name;
+        if (!name || name[0] !== name[0].toUpperCase()) return;
+        injectAllJSX(path, name);
+      },
+      VariableDeclarator(path) {
+        const name = path.node.id?.name;
+        if (!name || name[0] !== name[0].toUpperCase()) return;
+        const init = path.node.init;
+        if (init && (init.type === "ArrowFunctionExpression" || init.type === "FunctionExpression")) {
+          injectAllJSX(path.get("init"), name);
+        }
+      }
+    }
+  };
+  function injectAllJSX(path, componentName) {
+    path.traverse({
+      JSXElement(jsxPath) {
+        const { openingElement } = jsxPath.node;
+        const tagName = getTagName(openingElement.name);
+        const line = openingElement.loc?.start.line || "0";
+        const debugId = `${componentName}:${tagName}:${line}`;
+        const alreadyHas = openingElement.attributes.some(
+          (attr) => attr.type === "JSXAttribute" && attr.name?.name === "data-debug"
+        );
+        if (alreadyHas) return;
+        openingElement.attributes.push({
+          type: "JSXAttribute",
+          name: { type: "JSXIdentifier", name: "data-debug" },
+          value: { type: "StringLiteral", value: debugId }
+        });
+      }
+    });
+  }
+  function getTagName(node) {
+    if (node.type === "JSXIdentifier") return node.name;
+    if (node.type === "JSXMemberExpression") {
+      return `${getTagName(node.object)}.${node.property.name}`;
+    }
+    return "unknown";
+  }
+}
+
+// src/runtime.ts
+function initInspector() {
+  if (typeof window === "undefined") return;
+  let isInspecting = false;
+  const toggleBtn = document.createElement("button");
+  toggleBtn.innerHTML = "\u{1F3AF}";
+  toggleBtn.title = "\u5F00\u542F\u7EC4\u4EF6\u5B9A\u4F4D\u5668";
+  toggleBtn.style.cssText = `
+    position: fixed;
+    bottom: 24px;
+    right: 24px;
+    width: 44px;
+    height: 44px;
+    border-radius: 22px;
+    background: #0ea5e9;
+    color: white;
+    border: 2px solid white;
+    box-shadow: 0 4px 12px rgba(0,0,0,0.15);
+    cursor: pointer;
+    z-index: 9999999;
+    font-size: 20px;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    transition: all 0.2s cubic-bezier(0.4, 0, 0.2, 1);
+  `;
+  document.body.appendChild(toggleBtn);
+  const overlay = document.createElement("div");
+  overlay.style.cssText = `
+    position: fixed;
+    pointer-events: none;
+    z-index: 9999998;
+    background: rgba(14, 165, 233, 0.15);
+    border: 2px dashed #0ea5e9;
+    display: none;
+    transition: all 0.1s ease-out;
+  `;
+  document.body.appendChild(overlay);
+  const tooltip = document.createElement("div");
+  tooltip.style.cssText = `
+    position: fixed;
+    pointer-events: none;
+    z-index: 9999999;
+    background: #1e293b;
+    color: #38bdf8;
+    padding: 4px 10px;
+    border-radius: 6px;
+    font-size: 11px;
+    font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+    font-weight: 700;
+    box-shadow: 0 4px 6px rgba(0,0,0,0.2);
+    display: none;
+    white-space: nowrap;
+    transition: all 0.1s ease-out;
+  `;
+  document.body.appendChild(tooltip);
+  const stopInspecting = () => {
+    isInspecting = false;
+    toggleBtn.style.transform = "scale(1)";
+    toggleBtn.style.background = "#0ea5e9";
+    document.body.style.cursor = "";
+    overlay.style.display = "none";
+    tooltip.style.display = "none";
+  };
+  toggleBtn.onclick = () => {
+    isInspecting = !isInspecting;
+    if (isInspecting) {
+      toggleBtn.style.transform = "scale(0.9)";
+      toggleBtn.style.background = "#ef4444";
+      document.body.style.cursor = "crosshair";
+    } else {
+      stopInspecting();
+    }
+  };
+  window.addEventListener("mousemove", (e) => {
+    if (!isInspecting) return;
+    const target = e.target;
+    if (target === toggleBtn || target === overlay || target === tooltip) return;
+    const debugEl = target.closest("[data-debug]");
+    if (debugEl) {
+      const debugId = debugEl.getAttribute("data-debug") || "";
+      const rect = debugEl.getBoundingClientRect();
+      overlay.style.display = "block";
+      overlay.style.top = rect.top + "px";
+      overlay.style.left = rect.left + "px";
+      overlay.style.width = rect.width + "px";
+      overlay.style.height = rect.height + "px";
+      tooltip.style.display = "block";
+      tooltip.textContent = debugId;
+      tooltip.style.color = "#38bdf8";
+      const tooltipY = rect.top < 30 ? rect.bottom + 4 : rect.top - 28;
+      tooltip.style.top = tooltipY + "px";
+      tooltip.style.left = rect.left + "px";
+    } else {
+      overlay.style.display = "none";
+      tooltip.style.display = "none";
+    }
+  });
+  window.addEventListener(
+    "click",
+    (e) => {
+      if (!isInspecting) return;
+      const target = e.target;
+      if (target === toggleBtn) return;
+      e.preventDefault();
+      e.stopPropagation();
+      const debugEl = target.closest("[data-debug]");
+      if (debugEl) {
+        const debugId = debugEl.getAttribute("data-debug");
+        if (debugId) {
+          navigator.clipboard.writeText(debugId).then(() => {
+            tooltip.textContent = "\u2705 Copied!";
+            tooltip.style.color = "#10b981";
+            overlay.style.background = "rgba(16, 185, 129, 0.2)";
+            overlay.style.borderColor = "#10b981";
+            setTimeout(stopInspecting, 600);
+          });
+        }
+      } else {
+        stopInspecting();
+      }
+    },
+    { capture: true }
+  );
+  window.addEventListener("keydown", (e) => {
+    if (e.key === "Escape" && isInspecting) stopInspecting();
+  });
+}
+
+// src/index.ts
+var index_default = babelPluginDebugLabel;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  initInspector
+});

package/dist/index.mjs

@@ -0,0 +1,182 @@
+// src/babel-plugin.ts
+function babelPluginDebugLabel() {
+  return {
+    visitor: {
+      FunctionDeclaration(path) {
+        const name = path.node.id?.name;
+        if (!name || name[0] !== name[0].toUpperCase()) return;
+        injectAllJSX(path, name);
+      },
+      VariableDeclarator(path) {
+        const name = path.node.id?.name;
+        if (!name || name[0] !== name[0].toUpperCase()) return;
+        const init = path.node.init;
+        if (init && (init.type === "ArrowFunctionExpression" || init.type === "FunctionExpression")) {
+          injectAllJSX(path.get("init"), name);
+        }
+      }
+    }
+  };
+  function injectAllJSX(path, componentName) {
+    path.traverse({
+      JSXElement(jsxPath) {
+        const { openingElement } = jsxPath.node;
+        const tagName = getTagName(openingElement.name);
+        const line = openingElement.loc?.start.line || "0";
+        const debugId = `${componentName}:${tagName}:${line}`;
+        const alreadyHas = openingElement.attributes.some(
+          (attr) => attr.type === "JSXAttribute" && attr.name?.name === "data-debug"
+        );
+        if (alreadyHas) return;
+        openingElement.attributes.push({
+          type: "JSXAttribute",
+          name: { type: "JSXIdentifier", name: "data-debug" },
+          value: { type: "StringLiteral", value: debugId }
+        });
+      }
+    });
+  }
+  function getTagName(node) {
+    if (node.type === "JSXIdentifier") return node.name;
+    if (node.type === "JSXMemberExpression") {
+      return `${getTagName(node.object)}.${node.property.name}`;
+    }
+    return "unknown";
+  }
+}
+
+// src/runtime.ts
+function initInspector() {
+  if (typeof window === "undefined") return;
+  let isInspecting = false;
+  const toggleBtn = document.createElement("button");
+  toggleBtn.innerHTML = "\u{1F3AF}";
+  toggleBtn.title = "\u5F00\u542F\u7EC4\u4EF6\u5B9A\u4F4D\u5668";
+  toggleBtn.style.cssText = `
+    position: fixed;
+    bottom: 24px;
+    right: 24px;
+    width: 44px;
+    height: 44px;
+    border-radius: 22px;
+    background: #0ea5e9;
+    color: white;
+    border: 2px solid white;
+    box-shadow: 0 4px 12px rgba(0,0,0,0.15);
+    cursor: pointer;
+    z-index: 9999999;
+    font-size: 20px;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    transition: all 0.2s cubic-bezier(0.4, 0, 0.2, 1);
+  `;
+  document.body.appendChild(toggleBtn);
+  const overlay = document.createElement("div");
+  overlay.style.cssText = `
+    position: fixed;
+    pointer-events: none;
+    z-index: 9999998;
+    background: rgba(14, 165, 233, 0.15);
+    border: 2px dashed #0ea5e9;
+    display: none;
+    transition: all 0.1s ease-out;
+  `;
+  document.body.appendChild(overlay);
+  const tooltip = document.createElement("div");
+  tooltip.style.cssText = `
+    position: fixed;
+    pointer-events: none;
+    z-index: 9999999;
+    background: #1e293b;
+    color: #38bdf8;
+    padding: 4px 10px;
+    border-radius: 6px;
+    font-size: 11px;
+    font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+    font-weight: 700;
+    box-shadow: 0 4px 6px rgba(0,0,0,0.2);
+    display: none;
+    white-space: nowrap;
+    transition: all 0.1s ease-out;
+  `;
+  document.body.appendChild(tooltip);
+  const stopInspecting = () => {
+    isInspecting = false;
+    toggleBtn.style.transform = "scale(1)";
+    toggleBtn.style.background = "#0ea5e9";
+    document.body.style.cursor = "";
+    overlay.style.display = "none";
+    tooltip.style.display = "none";
+  };
+  toggleBtn.onclick = () => {
+    isInspecting = !isInspecting;
+    if (isInspecting) {
+      toggleBtn.style.transform = "scale(0.9)";
+      toggleBtn.style.background = "#ef4444";
+      document.body.style.cursor = "crosshair";
+    } else {
+      stopInspecting();
+    }
+  };
+  window.addEventListener("mousemove", (e) => {
+    if (!isInspecting) return;
+    const target = e.target;
+    if (target === toggleBtn || target === overlay || target === tooltip) return;
+    const debugEl = target.closest("[data-debug]");
+    if (debugEl) {
+      const debugId = debugEl.getAttribute("data-debug") || "";
+      const rect = debugEl.getBoundingClientRect();
+      overlay.style.display = "block";
+      overlay.style.top = rect.top + "px";
+      overlay.style.left = rect.left + "px";
+      overlay.style.width = rect.width + "px";
+      overlay.style.height = rect.height + "px";
+      tooltip.style.display = "block";
+      tooltip.textContent = debugId;
+      tooltip.style.color = "#38bdf8";
+      const tooltipY = rect.top < 30 ? rect.bottom + 4 : rect.top - 28;
+      tooltip.style.top = tooltipY + "px";
+      tooltip.style.left = rect.left + "px";
+    } else {
+      overlay.style.display = "none";
+      tooltip.style.display = "none";
+    }
+  });
+  window.addEventListener(
+    "click",
+    (e) => {
+      if (!isInspecting) return;
+      const target = e.target;
+      if (target === toggleBtn) return;
+      e.preventDefault();
+      e.stopPropagation();
+      const debugEl = target.closest("[data-debug]");
+      if (debugEl) {
+        const debugId = debugEl.getAttribute("data-debug");
+        if (debugId) {
+          navigator.clipboard.writeText(debugId).then(() => {
+            tooltip.textContent = "\u2705 Copied!";
+            tooltip.style.color = "#10b981";
+            overlay.style.background = "rgba(16, 185, 129, 0.2)";
+            overlay.style.borderColor = "#10b981";
+            setTimeout(stopInspecting, 600);
+          });
+        }
+      } else {
+        stopInspecting();
+      }
+    },
+    { capture: true }
+  );
+  window.addEventListener("keydown", (e) => {
+    if (e.key === "Escape" && isInspecting) stopInspecting();
+  });
+}
+
+// src/index.ts
+var index_default = babelPluginDebugLabel;
+export {
+  index_default as default,
+  initInspector
+};

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@linhey/react-debug-inspector",
+  "version": "1.0.0",
+  "description": "A developer tool to inspect React components in browser and jump to source code.",
+  "author": "linhey",
+  "license": "MIT",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "dev": "tsup src/index.ts --format cjs,esm --watch --dts",
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.24.0",
+    "tsup": "^8.0.2",
+    "typescript": "^5.4.2"
+  },
+  "peerDependencies": {
+    "react": ">=16.8.0"
+  },
+  "keywords": [
+    "react",
+    "debug",
+    "inspector",
+    "vite",
+    "babel-plugin"
+  ]
+}