react-state-inspector-devtools 0.1.0 → 0.1.1

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,410 @@
+# react-state-inspector-devtools
+
+A lightweight, runtime state inspector for React.  
+**Inspect and edit component state live — directly from your app.**
+
+[![npm version](https://img.shields.io/npm/v/react-state-inspector-devtools.svg)](https://www.npmjs.com/package/react-state-inspector-devtools)
+[![license](https://img.shields.io/npm/l/react-state-inspector-devtools.svg)](https://github.com/yourusername/react-state-inspector-devtools/blob/main/LICENSE)
+
+---
+
+## ✨ What is this?
+
+`react-state-inspector-devtools` is a **dev-only** React tool that lets you:
+
+- 👀 See which components are currently mounted
+- 🔍 Inspect their internal state (`useState`)
+- ✏️ Edit state values live from a floating UI panel
+- ⚡ Observe UI updates instantly
+
+**No browser extensions.**  
+**No React DevTools dependency.**  
+**Just drop it into your app.**
+
+---
+
+## 🧠 Why?
+
+React DevTools are great — but sometimes you want:
+
+- 🖥️ State inspection **inside the app**
+- 🧪 A tool that works in **embedded environments**, previews, sandboxes
+- 🎨 A way to poke state values quickly while **designing UI**
+- ⚙️ **Zero setup**, zero configuration
+
+> This tool is optimized for **developer experience**, not production analytics.
+
+---
+
+## 📦 Installation
+
+```bash
+npm install react-state-inspector-devtools
+```
+
+or
+
+```bash
+pnpm add react-state-inspector-devtools
+```
+
+or
+
+```bash
+yarn add react-state-inspector-devtools
+```
+
+---
+
+## 🚀 Quick Start
+
+### 1️⃣ Wrap your app with the provider (dev-only)
+
+```tsx
+import {
+  StateInspectorProvider,
+  StateInspectorUI,
+} from "react-state-inspector-devtools";
+
+export function AppRoot() {
+  return (
+    <StateInspectorProvider enabled={import.meta.env.DEV}>
+      <App />
+      {import.meta.env.DEV && <StateInspectorUI />}
+    </StateInspectorProvider>
+  );
+}
+```
+
+> ⚠️ **Important:**  
+> This tool is intended for **development only**.  
+> Always gate it behind `DEV` / `NODE_ENV !== "production"`.
+
+### 2️⃣ Opt-in to state inspection
+
+Replace `useState` with `useInspectableState`:
+
+```tsx
+import {
+  useInspectorComponent,
+  useInspectableState,
+} from "react-state-inspector-devtools";
+
+export function CounterCard() {
+  const inspector = useInspectorComponent("CounterCard");
+
+  const [count, setCount] = useInspectableState(
+    inspector,
+    "count",
+    0,
+    { type: "number", min: 0, max: 999, step: 1 }
+  );
+
+  return (
+    <div>
+      <button onClick={() => setCount((c) => c - 1)}>-</button>
+      <span>{count}</span>
+      <button onClick={() => setCount((c) => c + 1)}>+</button>
+    </div>
+  );
+}
+```
+
+**That's it.**  
+The component and its state will appear in the inspector UI.
+
+---
+
+## 🪟 The Inspector UI
+
+- Appears as a **floating button** in the bottom-right corner
+- Opens a panel with:
+  - **Left:** Mounted components list
+  - **Right:** Editable state values
+- State changes update the UI **immediately**
+
+### Supported Editors
+
+| Type | Editor |
+|------|--------|
+| `boolean` | ✅ Checkbox |
+| `number` | ✅ Number input (min / max / step) |
+| `text` | ✅ Text input (with placeholder) |
+| `select` | ✅ Dropdown |
+| `json` | ✅ JSON editor |
+
+---
+
+## 🧩 API Reference
+
+### `StateInspectorProvider`
+
+Wraps your app and controls whether the inspector is active.
+
+```tsx
+<StateInspectorProvider enabled={boolean}>
+  {children}
+</StateInspectorProvider>
+```
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `enabled` | `boolean` | Controls whether the inspector is active |
+| `children` | `ReactNode` | Your application |
+
+---
+
+### `StateInspectorUI`
+
+Renders the floating inspector overlay.
+
+```tsx
+<StateInspectorUI />
+```
+
+---
+
+### `useInspectorComponent(label?: string)`
+
+Registers a component instance with the inspector.
+
+```tsx
+const inspector = useInspectorComponent("ProfileForm");
+```
+
+- Creates a **stable component identity**
+- Must be called **once per component**
+- The `label` appears in the component list
+
+---
+
+### `useInspectableState<T>(inspector, key, initialValue, meta?)`
+
+Drop-in replacement for `useState` that registers state with the inspector.
+
+```tsx
+const [value, setValue] = useInspectableState(
+  inspector,
+  key,
+  initialValue,
+  meta?
+);
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `inspector` | `InspectorComponentRef` | Returned from `useInspectorComponent` |
+| `key` | `string` | State name shown in the UI |
+| `initialValue` | `T` | Initial state value (same as `useState`) |
+| `meta` | `InspectableMeta` | Optional UI hints for the editor |
+
+---
+
+## 📝 Meta Options
+
+The `meta` parameter controls how the state is rendered in the inspector UI:
+
+### Boolean
+
+```tsx
+{ type: "boolean" }
+```
+
+### Number
+
+```tsx
+{ type: "number", min: 0, max: 100, step: 5 }
+```
+
+### Text
+
+```tsx
+{ type: "text", placeholder: "Enter name..." }
+```
+
+### Select (Dropdown)
+
+```tsx
+{
+  type: "select",
+  options: ["small", "medium", "large"],
+}
+
+// Or with labels
+{
+  type: "select",
+  options: [
+    { label: "Small", value: "sm" },
+    { label: "Medium", value: "md" },
+    { label: "Large", value: "lg" },
+  ],
+}
+```
+
+### JSON
+
+```tsx
+{ type: "json" }
+```
+
+> 💡 **Tip:** If you don't provide `meta`, the type is **automatically inferred** from the initial value.
+
+---
+
+## 🧪 Examples
+
+### Boolean Flags
+
+```tsx
+export function FlagsPanel() {
+  const inspector = useInspectorComponent("FlagsPanel");
+
+  const [isAdmin, setIsAdmin] = useInspectableState(
+    inspector,
+    "isAdmin",
+    false,
+    { type: "boolean" }
+  );
+
+  const [betaUser, setBetaUser] = useInspectableState(
+    inspector,
+    "betaUser",
+    true,
+    { type: "boolean" }
+  );
+
+  return (
+    <div>
+      <label>
+        <input
+          type="checkbox"
+          checked={isAdmin}
+          onChange={(e) => setIsAdmin(e.target.checked)}
+        />
+        Is Admin
+      </label>
+      <label>
+        <input
+          type="checkbox"
+          checked={betaUser}
+          onChange={(e) => setBetaUser(e.target.checked)}
+        />
+        Beta User
+      </label>
+    </div>
+  );
+}
+```
+
+### Select Dropdown
+
+```tsx
+export function VariantPicker() {
+  const inspector = useInspectorComponent("VariantPicker");
+
+  const [variant, setVariant] = useInspectableState(
+    inspector,
+    "variant",
+    "M",
+    {
+      type: "select",
+      options: ["S", "M", "L", "XL"],
+    }
+  );
+
+  return (
+    <select value={variant} onChange={(e) => setVariant(e.target.value)}>
+      {["S", "M", "L", "XL"].map((v) => (
+        <option key={v} value={v}>{v}</option>
+      ))}
+    </select>
+  );
+}
+```
+
+### Text Inputs
+
+```tsx
+export function ProfileForm() {
+  const inspector = useInspectorComponent("ProfileForm");
+
+  const [name, setName] = useInspectableState(
+    inspector,
+    "name",
+    "",
+    { type: "text", placeholder: "Name" }
+  );
+
+  const [email, setEmail] = useInspectableState(
+    inspector,
+    "email",
+    "",
+    { type: "text", placeholder: "Email" }
+  );
+
+  return (
+    <div>
+      <input
+        value={name}
+        onChange={(e) => setName(e.target.value)}
+        placeholder="Name"
+      />
+      <input
+        value={email}
+        onChange={(e) => setEmail(e.target.value)}
+        placeholder="Email"
+      />
+    </div>
+  );
+}
+```
+
+---
+
+## 🔒 Production Safety
+
+- ✅ The inspector does **nothing** when `enabled={false}`
+- ✅ No side effects, no global patches
+- ✅ No state is tracked unless you **opt in**
+
+> ⚠️ Still, **do not ship it enabled in production.**
+
+---
+
+## 🛠️ Use Cases
+
+- 🎨 UI development & tweaking
+- 📐 Design system work
+- 📚 Component libraries
+- 🖼️ Embedded previews
+- 🔧 Internal tools
+- 🎤 Demos & presentations
+
+---
+
+## 🧩 Inspired by
+
+- [React DevTools](https://react.dev/learn/react-developer-tools)
+- [Redux DevTools](https://github.com/reduxjs/redux-devtools)
+- In-app debug overlays
+
+…but intentionally **simpler** and **runtime-focused**.
+
+---
+
+## 📄 License
+
+MIT
+
+---
+
+## ⭐ Feedback
+
+This is a V1 devtool built for real-world usage.  
+Ideas, issues, and PRs are welcome!
+
+---
+
+## 🔗 Links
+
+- [npm](https://www.npmjs.com/package/react-state-inspector-devtools)

package/package.json

@@ -1,6 +1,7 @@
 {
     "name": "react-state-inspector-devtools",
-    "version": "0.1.0",
+    "version": "0.1.1",
+    "license": "MIT",
     "publishConfig": {
         "access": "public"
     },
@@ -29,4 +30,4 @@
         "lint": "eslint .",
         "format": "prettier . --check"
     }
-}
+}