react-boxmodel-inspector 1.0.0

package/README.md

@@ -0,0 +1,114 @@
+# react-boxmodel-inspector
+
+A zero-dependency React developer tool that wraps any element and visually debugs its CSS box model — margin, border, padding, and content — with live overlays and a draggable floating panel.
+
+> ⚠️ This is a **developer tool**. Don't ship it to production.
+
+---
+
+## Features
+
+- 🔍 **Long-press any element** to inspect it
+- 📦 **Live layered overlays** — dashed rectangles for margin (orange), padding (green), and content (purple), each with pixel edge labels
+- 🪟 **Draggable floating panel** showing T·R·B·L values for margin, border, padding, and content size
+- 🔄 **Live updates** via `ResizeObserver`, `MutationObserver`, and scroll/resize listeners
+- ⌨️ **Keyboard shortcuts** — press backtick (`` ` ``) to toggle, `ESC` to close
+- ⚡ **Zero overhead when disabled** — renders only `children` when not in use
+- 🎨 **Expandable CSS property groups** — typography, layout, flex/grid, color, transform, and more
+
+---
+
+## Installation
+
+```bash
+npm install react-boxmodel-inspector
+```
+
+---
+
+## Basic Usage
+
+Wrap your app (or any subtree) with `BoxModelInspector`:
+
+```jsx
+import BoxModelInspector from 'react-boxmodel-inspector';
+
+function App() {
+  return (
+    <BoxModelInspector>
+      <YourApp />
+    </BoxModelInspector>
+  );
+}
+```
+
+Then in the browser:
+- Press `` ` `` (backtick) to activate the inspector
+- **Long-press** any element to inspect it
+- Press `ESC` or click `✕` to close the panel
+- **Drag** the panel anywhere
+
+---
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `ReactNode` | — | The component tree to wrap |
+| `longPressDuration` | `number` | `500` | How long (ms) to hold before inspection triggers |
+| `toggleKey` | `string` | `` "`" `` | Key to toggle the inspector on/off |
+
+---
+
+## Usage with entry point (main.jsx / index.jsx)
+
+```jsx
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import App from './App.jsx';
+import BoxModelInspector from 'react-boxmodel-inspector';
+
+createRoot(document.getElementById('root')).render(
+  <StrictMode>
+    <BoxModelInspector>
+      <App />
+    </BoxModelInspector>
+  </StrictMode>
+);
+```
+
+---
+
+## Custom toggle key and duration
+
+```jsx
+<BoxModelInspector toggleKey="F2" longPressDuration={300}>
+  <App />
+</BoxModelInspector>
+```
+
+---
+
+## How it works
+
+1. Press the toggle key to activate inspector mode — a blue banner appears at the top of the screen.
+2. Long-press any element in the page. A circular ripple indicates the progress.
+3. On trigger, three dashed overlays appear directly on the element:
+   - **Orange** — margin box with T/R/B/L labels
+   - **Green** — padding box with T/R/B/L labels
+   - **Purple** — content box with width × height
+4. A dark floating panel also appears to the right, showing numeric T·R·B·L values for margin, border, padding, and content size.
+5. Expand "All properties" in the panel to see grouped CSS values (typography, layout, flex, color, etc).
+
+---
+
+## Requirements
+
+- React **17+** or **18+**
+- Works in any browser with `ResizeObserver` and `MutationObserver` support (all modern browsers)
+
+---
+
+## License
+
+MIT