npm package: @promakeai/inspector
Description: Visual element inspector React component with AI prompt support
Author: Promake
Latest version: 1.7.5

# @promakeai/inspector

Visual element inspector React component with AI prompt support.

## Features

- 🎯 Visual element selection
- ✏️ Text editing
- 🖼️ Image URL editing
- 🎨 Style editing (colors, spacing, typography, display, borders)
- 🔍 Element stack navigation (select overlapping elements)
- 🌐 i18n support via labels
- 🎨 Customizable theme
- 📱 Responsive design
- ⚡ **React version independent** - Works with React 18, 19, and any future versions
- 🎨 **No external UI dependencies** - All components built in-house for maximum compatibility

## Installation

```bash
npm install @promakeai/inspector
# or
yarn add @promakeai/inspector
# or
pnpm add @promakeai/inspector
# or
bun add @promakeai/inspector
```

## Peer Dependencies

Only React is required:

```json
{
  "react": ">=18.0.0"
}
```

**That's it!** No need for:

- ❌ React version matching
- ❌ Dependency deduplication
- ❌ Version resolution conflicts
- ❌ Additional UI library installations

## Usage

### 1. Add Vite Plugin (Optional - for component tracking)

```typescript
// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { inspectorDebugger } from "@promakeai/inspector/plugin";

export default defineConfig({
  plugins: [
    inspectorDebugger({ enabled: true }), // Must be BEFORE react() plugin
    react(),
  ],
});
```

**⚠️ Important:** `inspectorDebugger` must be placed **before** the `react()` plugin to properly track components.

**Note:** The Vite plugin is optional but recommended for better component tracking.

### 2. Use Inspector Component

```tsx
import { Inspector } from "@promakeai/inspector";
import "@promakeai/inspector/style.css";

function App() {
  return (
    <>
      <YourApp />
      <Inspector />
    </>
  );
}
```

The Inspector will inspect the current page and allow you to edit elements visually.

**Customization (Optional):**

You can customize labels and theme via the inspector store or by listening to inspector events. See the Hook API section below for programmatic control.

### 3. Programmatic Control (Advanced)

Access the inspector store for programmatic control:

```tsx
import { Inspector } from "@promakeai/inspector";
import { useInspectorStore } from "@promakeai/inspector";

function App() {
  const { setTheme, setLabels } = useInspectorStore();

  useEffect(() => {
    // Customize theme
    setTheme({
      primaryColor: "rgb(58, 18, 189)",
      backgroundColor: "#ffffff",
      textColor: "#000000",
    });

    // Customize labels
    setLabels({
      editText: "Edit Text",
      editImage: "Edit Image",
      editStyle: "Edit Style",
    });
  }, []);

  return (
    <>
      <YourApp />
      <Inspector />
    </>
  );
}
```

## Configuration

### Inspector Store

The Inspector component uses Zustand for state management. All configuration is done through the store:

```tsx
import { useInspectorStore } from "@promakeai/inspector";

const { theme, labels, setTheme, setLabels } = useInspectorStore();
```

**Note:** The `<Inspector />` component accepts no props. All customization is done via the store.

### Theme Options

```typescript
interface InspectorTheme {
  primaryColor?: string;
  backgroundColor?: string;
  textColor?: string;
  borderColor?: string;
  buttonColor?: string;
  buttonTextColor?: string;
  inputBackgroundColor?: string;
  // ... and more
}
```

### Label Options

All UI text can be customized via the `labels` prop. See TypeScript types for complete list.

## Browser Support

- Chrome/Edge 90+
- Firefox 88+
- Safari 14+

## Troubleshooting

### Styles not working?

Make sure to import the CSS:

```tsx
import "@promakeai/inspector/style.css";
```

### Inspector not appearing?

1. Check that the inspector root element is rendered
2. Open browser console for any errors
3. Clear Vite cache: `rm -rf node_modules/.vite`

### Elements not selectable?

1. Make sure elements don't have `pointer-events: none`
2. Check z-index conflicts with your app (inspector uses z-index 2147483640+)
3. Verify elements are not inside shadow DOM

## React Version Compatibility

This package is built with **zero external UI dependencies**, making it compatible with:

- ✅ React 18.x
- ✅ React 19.x
- ✅ React 19 Canary
- ✅ Future React versions

**No version conflicts, ever!** All UI components are custom-built pure React components.

## Migration from v1.0.6

If you're upgrading from v1.0.6 or earlier:

1. **Remove old Vite config workarounds:**

   ```diff
   - resolve: {
   -   dedupe: ["react", "react-dom"],
   - },
   - optimizeDeps: {
   -   exclude: ["@promakeai/inspector"],
   -   needsInterop: [],
   - },
   ```

2. **That's it!** The package now works out of the box with any React version.

## Changelog

### v1.1.0

- ✨ Removed all Radix UI dependencies
- ✨ Built custom Select and ColorPicker components
- ✨ React version independent (18+)
- ✨ Fixed dropdown positioning issues
- ✨ Improved Select label display
- ✨ Smaller bundle size
- 🐛 Fixed ControlBox overflow issues
- 🐛 Fixed color picker positioning

### v1.0.7

- Previous version with Radix UI dependencies