@berenjena/react-dev-panel 1.0.3 → 1.0.4

package/README.md

@@ -1,9 +1,9 @@
 # React Dev Panel
 
-[![npm version](https://badge.fury.io/js/@berenjena%2Freact-dev-panel.svg)](https://badge.fury.io/js/@berenjena%2Freact-dev-panel)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Weekly Downloads](https://img.shields.io/npm/dw/@berenjena/react-dev-panel)](https://www.npmjs.com/package/@berenjena/react-dev-panel)
-![npm package minimized gzipped size](https://img.shields.io/bundlejs/size/%40berenjena%2Freact-dev-panel?label=gzipped)
+![NPM Version](https://badgen.net/npm/v/@berenjena/react-dev-panel)
+![npm package minimized gzipped size](<https://img.shields.io/bundlejs/size/%40berenjena%2Freact-dev-panel?label=Bundle%20size%20(gzip)>)
+[![License: MIT](https://badgen.net/npm/license/@berenjena/react-dev-panel)](https://opensource.org/licenses/MIT)
+[![Weekly Downloads](https://badgen.net/npm/dw/@berenjena/react-dev-panel)](https://www.npmjs.com/package/@berenjena/react-dev-panel)
 
 A powerful, type-safe React development panel that provides an intuitive interface for controlling component props, debugging state, and rapid prototyping during development.
 
@@ -11,27 +11,10 @@ A powerful, type-safe React development panel that provides an intuitive interfa
 
 -   🎛️ **Rich Control Types** - Boolean, Number, Text, Select, Color, Range, Date, Button, and Separator controls
 -   🎨 **Themeable** - Consistent design system with CSS custom properties
--   📱 **Responsive** - Adapts to different screen sizes and can be positioned anywhere
 -   ⌨️ **Keyboard Shortcuts** - Quick access with customizable hotkeys
--   🔄 **State Management** - Built-in state persistence
 -   📖 **TypeScript First** - Full type safety and IntelliSense support
 -   🚀 **Zero Dependencies** - Only requires React (peer dependency)
-
-## 📊 Package Stats
-
--   **Bundle Size**: ~35KB (minified)
--   **Total Files**: 142
--   **License**: MIT
-
-## 🆕 What's New
-
-### Recent Updates (v1.0.1+)
-
--   **🔄 Zero External Dependencies**: Replaced Zustand with React's built-in `useSyncExternalStore` for state management
--   **📊 Logger Component**: New floating, collapsible logger component for debugging object data in JSON format
--   **⚡ Performance Optimizations**: Selective subscriptions for better re-render performance
--   **🔧 Development Mode Improvements**: Removed development mode checks - panel now works in all environments
--   **📝 Enhanced Documentation**: Comprehensive code documentation and better TypeScript support
+-   📦 **Bundle Size**: ![npm package minimized gzipped size](<https://img.shields.io/bundlejs/size/%40berenjena%2Freact-dev-panel?label=Bundle%20size%20(gzip)>)
 
 ## 📦 Installation
 
@@ -106,6 +89,8 @@ function App() {
 
 ## 🎛️ Control Types
 
+React Dev Panel provides rich control types for different data types. Here are some quick examples:
+
 ### Text Control
 
 ```tsx
@@ -114,7 +99,6 @@ function App() {
   value: 'Hello World',
   label: 'Message',
   placeholder: 'Enter message...',
-  event: 'onBlur', // or 'onChange'
   onChange: (value: string) => setValue(value),
 }
 ```
@@ -128,7 +112,6 @@ function App() {
   label: 'Count',
   min: 0,
   max: 100,
-  step: 1,
   onChange: (value: number) => setValue(value),
 }
 ```
@@ -144,61 +127,6 @@ function App() {
 }
 ```
 
-### Select Control
-
-```tsx
-{
-  type: 'select',
-  value: 'option1',
-  label: 'Choose Option',
-  options: ['option1', 'option2', 'option3'],
-  // or with labels:
-  options: [
-    { label: 'Option 1', value: 'opt1' },
-    { label: 'Option 2', value: 'opt2' },
-  ],
-  onChange: (value: string) => setValue(value),
-}
-```
-
-### Color Control
-
-```tsx
-{
-  type: 'color',
-  value: '#ff6200',
-  label: 'Brand Color',
-  onChange: (value: string) => setValue(value),
-}
-```
-
-### Range Control
-
-```tsx
-{
-  type: 'range',
-  value: 50,
-  label: 'Volume',
-  min: 0,
-  max: 100,
-  step: 1,
-  onChange: (value: number) => setValue(value),
-}
-```
-
-### Date Control
-
-```tsx
-{
-  type: 'date',
-  value: '2025-07-26',
-  label: 'Start Date',
-  min: '2025-01-01',
-  max: '2025-12-31',
-  onChange: (value: string) => setValue(value),
-}
-```
-
 ### Button Control
 
 ```tsx
@@ -209,63 +137,22 @@ function App() {
 }
 ```
 
-### Button Group Control
-
-```tsx
-{
-  type: 'buttonGroup',
-  label: 'Actions',
-  buttons: [
-    { label: 'Save', onClick: handleSave },
-    { label: 'Load', onClick: handleLoad },
-    { label: 'Reset', onClick: handleReset, disabled: true },
-  ],
-}
-```
-
-### Separator Control
-
-```tsx
-// Line separator
-{ type: 'separator' }
-
-// Space separator
-{ type: 'separator', style: 'space' }
-
-// Label separator
-{ type: 'separator', style: 'label', label: 'Advanced Settings' }
-```
+**📖 [View all control types and detailed documentation →](./guides/CONTROLS.md)**
 
 ## 🎨 Styling and Theming
 
-The dev panel uses CSS custom properties for easy theming:
+The dev panel uses CSS custom properties for easy theming. Here's a quick example:
 
 ```css
 :root {
 	--dev-panel-background-color: #1a1a1a;
 	--dev-panel-text-color: #ffffff;
-	--dev-panel-text-color-highlight: #ffffff;
-	--dev-panel-text-color-muted: #888888;
 	--dev-panel-accent-color: #ff6200;
 	--dev-panel-border-color: #333333;
-	--dev-panel-input-background-color: #2a2a2a;
-	--dev-panel-highlight-color: #ff620020;
-	--dev-panel-font-size-xs: 11px;
-	--dev-panel-font-size-sm: 12px;
-	--dev-panel-spacing-xs: 4px;
-	--dev-panel-spacing-sm: 8px;
-	--dev-panel-spacing-md: 16px;
-	--dev-panel-border-radius: 4px;
-	--dev-panel-inputs-height: 24px;
-	--dev-panel-transition: all 0.2s ease;
 }
 ```
 
-### Custom Panel Positioning
-
-```tsx
-<DevPanel panelTitle="Custom Panel" position={{ x: 100, y: 100 }} defaultExpanded={true} />
-```
+**📖 [Complete theming guide and customization options →](./guides/STYLING.md)**
 
 ## ⌨️ Keyboard Shortcuts
 
@@ -312,32 +199,16 @@ function App() {
 }
 ```
 
-### Conditional Controls
-
-```tsx
-useDevPanel("Settings", {
-	mode: {
-		type: "select",
-		value: mode,
-		options: ["simple", "advanced"],
-		onChange: setMode,
-	},
-	// Only show advanced settings when mode is 'advanced'
-	...(mode === "advanced" && {
-		separator1: { type: "separator", style: "label", label: "Advanced" },
-		complexValue: {
-			type: "range",
-			value: complexValue,
-			min: 0,
-			max: 1000,
-			onChange: setComplexValue,
-		},
-	}),
-});
-```
+**📖 [Advanced patterns, state management, and optimization →](./guides/ADVANCED_USAGE.md)**
 
 ### Event Handling Options
 
+React Dev Panel supports two different event handling strategies for input controls:
+
+**onChange Event**: Provides real-time updates as the user types or interacts with the control. This is ideal for immediate feedback and live previews, but may trigger more frequent re-renders.
+
+**onBlur Event**: Updates the value only when the user finishes interacting with the control (loses focus). This approach is more performance-friendly for expensive operations and provides a better user experience when dealing with API calls or heavy computations.
+
 ```tsx
 {
   type: 'text',
@@ -354,6 +225,19 @@ useDevPanel("Settings", {
 }
 ```
 
+## 📚 Documentation
+
+### Core Guides
+
+-   **[Control Types](./guides/CONTROLS.md)** - Complete guide to all available controls
+-   **[Event Handling](./guides/EVENT_HANDLING.md)** - onChange vs onBlur strategies and best practices
+-   **[Styling & Theming](./guides/STYLING.md)** - Customization, themes, and responsive design
+-   **[Advanced Usage](./guides/ADVANCED_USAGE.md)** - Complex patterns, state management, and optimization
+
+### Development
+
+-   **[Development Guide](./guides/DEVELOPMENT.md)** - Setup, contributing, and project structure
+
 ## 📚 API Reference
 
 ### `useDevPanel(groupName: string, controls: ControlsGroup)`
@@ -385,28 +269,9 @@ Registers keyboard shortcuts.
 
 ## 🛠️ Development
 
-### Prerequisites
-
--   Node.js 18+
--   React 18+
+Want to contribute or set up the project locally?
 
-### Setup
-
-```bash
-git clone https://github.com/Berenjenas/react-dev-panel.git
-cd react-dev-panel
-npm install
-```
-
-### Available Scripts
-
-```bash
-npm run dev          # Start development server
-npm run build        # Build for production
-npm run storybook    # Start Storybook
-npm run test         # Run tests
-npm run lint         # Lint code
-```
+**📖 [Development setup, contributing guidelines, and project structure →](./guides/DEVELOPMENT.md)**
 
 ## 📖 Storybook
 
@@ -428,10 +293,6 @@ We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) f
 4. Push to the branch (`git push origin feature/amazing-feature`)
 5. Open a Pull Request
 
-## 📄 License
-
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
-
 ## 🔗 Links
 
 -   [NPM Package](https://www.npmjs.com/package/@berenjena/react-dev-panel)

package/dist/UIStore-CQdr4U-2.js

@@ -0,0 +1,227 @@
+import { useSyncExternalStore as n } from "react";
+import { BaseStoreService as c } from "./store/BaseStoreService.js";
+const S = "dev-panel-sections-storage";
+class p extends c {
+  /**
+   * Creates a new DevPanelSectionsService instance.
+   */
+  constructor() {
+    super(S, {}, !1, !1);
+  }
+  /**
+   * Transforms current sections state to persistable format.
+   * Since this store doesn't persist, this method returns a dummy value.
+   *
+   * @param _state - The current sections state (unused)
+   * @returns Empty persistable state
+   * @protected
+   */
+  toPersistableState(e) {
+    return { sectionCollapseState: {} };
+  }
+  /**
+   * Transforms persisted state back to current state format.
+   * Since this store doesn't persist, this method returns the default state.
+   *
+   * @param _persistedState - The persisted sections state (unused)
+   * @param defaultState - The default state to fall back to
+   * @returns The default state
+   * @protected
+   */
+  fromPersistedState(e, t) {
+    return t;
+  }
+  /**
+   * Gets the service name for error messages.
+   *
+   * @returns The service name
+   * @protected
+   */
+  getServiceName() {
+    return "sections";
+  }
+  /**
+   * Registers a new section with the dev panel.
+   * If a section with the same name already exists, it preserves the existing collapse state.
+   * New sections start in expanded state (isCollapsed: false).
+   *
+   * @param name - Unique name for the section
+   * @param controls - Array of control configurations for the section
+   */
+  registerSection = (e, t) => {
+    this.setState((i) => {
+      const u = i[e]?.isCollapsed ?? !1;
+      return {
+        ...i,
+        [e]: {
+          name: e,
+          controls: t,
+          isCollapsed: u
+        }
+      };
+    });
+  };
+  /**
+   * Removes a section from the dev panel.
+   *
+   * @param name - Name of the section to remove
+   */
+  unregisterSection = (e) => {
+    this.setState((t) => {
+      const { [e]: i, ...a } = t;
+      return a;
+    });
+  };
+  /**
+   * Toggles the collapsed state of a specific section.
+   *
+   * @param name - Name of the section to toggle
+   */
+  toggleSectionCollapse = (e) => {
+    this.setState((t) => {
+      const i = t[e];
+      return i ? {
+        ...t,
+        [e]: {
+          ...i,
+          isCollapsed: !i.isCollapsed
+        }
+      } : t;
+    });
+  };
+  /**
+   * Clears all sections.
+   */
+  reset = () => {
+    this.setState(() => ({}));
+  };
+}
+const o = new p();
+function C() {
+  return n(o.subscribe, o.getSnapshot);
+}
+function h() {
+  return {
+    registerSection: o.registerSection,
+    unregisterSection: o.unregisterSection,
+    toggleSectionCollapse: o.toggleSectionCollapse,
+    reset: o.reset
+  };
+}
+const g = "dev-panel-ui-storage", d = { x: 20, y: 20 }, l = {
+  isVisible: !1,
+  isCollapsed: !1,
+  position: d
+};
+class b extends c {
+  /**
+   * Creates a new DevPanelUIService instance and loads persisted state from localStorage.
+   */
+  constructor() {
+    super(g, l, !0, !0);
+  }
+  /**
+   * Transforms current state to persistable format.
+   *
+   * @param state - The current UI state
+   * @returns The state in persistable format
+   * @protected
+   */
+  toPersistableState(e) {
+    return {
+      ...e
+    };
+  }
+  /**
+   * Transforms persisted state back to current state format.
+   *
+   * @param persistedState - The persisted UI state
+   * @param defaultState - The default state to fall back to
+   * @returns The state in current format
+   * @protected
+   */
+  fromPersistedState(e, t) {
+    return {
+      ...t,
+      ...e
+    };
+  }
+  /**
+   * Gets the service name for error messages.
+   *
+   * @returns The service name
+   * @protected
+   */
+  getServiceName() {
+    return "UI";
+  }
+  /**
+   * Sets the visibility state of the dev panel.
+   *
+   * @param visible - Whether the panel should be visible
+   */
+  setVisible = (e) => {
+    this.setState((t) => ({ ...t, isVisible: e }));
+  };
+  /**
+   * Sets the collapsed state of the dev panel.
+   *
+   * @param collapsed - Whether the panel should be collapsed
+   */
+  setCollapsed = (e) => {
+    this.setState((t) => ({ ...t, isCollapsed: e }));
+  };
+  /**
+   * Updates the position of the dev panel.
+   *
+   * @param position - New position coordinates {x, y}
+   */
+  setPosition = (e) => {
+    this.setState((t) => ({ ...t, position: e }));
+  };
+  /**
+   * Resets the dev panel UI to its default state.
+   * Resets position and sets visibility and collapse to false.
+   */
+  reset = () => {
+    this.setState(() => ({ ...l }));
+  };
+}
+const s = new b();
+function P() {
+  return {
+    ...n(s.subscribe, s.getSnapshot),
+    setVisible: s.setVisible,
+    setCollapsed: s.setCollapsed,
+    setPosition: s.setPosition,
+    reset: s.reset
+  };
+}
+function D() {
+  return n(s.subscribe, () => s.getSnapshot().isVisible);
+}
+function V() {
+  return n(s.subscribe, () => s.getSnapshot().isCollapsed);
+}
+function x() {
+  return n(s.subscribe, () => s.getSnapshot().position);
+}
+function m() {
+  return {
+    setVisible: s.setVisible,
+    setCollapsed: s.setCollapsed,
+    setPosition: s.setPosition,
+    reset: s.reset
+  };
+}
+const I = P;
+export {
+  h as a,
+  P as b,
+  D as c,
+  V as d,
+  x as e,
+  m as f,
+  I as g,
+  C as u
+};

package/dist/components/ControlRenderer/controls/ColorControl/ColorControl.js

@@ -1,13 +1,17 @@
-import { jsxs as t, jsx as n } from "react/jsx-runtime";
-import { Input as l } from "../../../Input/Input.js";
-import '../../../../assets/ColorControl.css';const o = "_container_ds1no_1", r = {
-  container: o
+import { jsxs as r, jsx as n } from "react/jsx-runtime";
+import { Input as o } from "../../../Input/Input.js";
+import { useDebouncedCallback as d } from "../../../../hooks/useDebounceCallback/useDebounceCallback.js";
+import '../../../../assets/ColorControl.css';const s = "_container_ds1no_1", i = {
+  container: s
 };
-function d({ control: e }) {
-  return /* @__PURE__ */ t("div", { className: r.container, children: [
-    /* @__PURE__ */ n("label", { children: /* @__PURE__ */ n(l, { type: "color", value: e.value, disabled: e.disabled, onChange: (a) => e.onChange(a.target.value) }) }),
+function C({ control: e }) {
+  const l = d(e.onChange, 100), t = (a) => {
+    l(a.target.value);
+  };
+  return /* @__PURE__ */ r("div", { className: i.container, children: [
+    /* @__PURE__ */ n("label", { children: /* @__PURE__ */ n(o, { type: "color", value: e.value, disabled: e.disabled, onChange: t }) }),
     /* @__PURE__ */ n(
-      l,
+      o,
       {
         type: "text",
         value: e.value,
@@ -19,5 +23,5 @@ function d({ control: e }) {
   ] });
 }
 export {
-  d as ColorControl
+  C as ColorControl
 };

package/dist/components/DevPanel/DevPanel.js

@@ -1,67 +1,67 @@
-import { jsxs as r, jsx as e } from "react/jsx-runtime";
-import { useCallback as g } from "react";
-import { useDragAndDrop as _ } from "../../hooks/useDragAndDrop/useDragAndDrop.js";
-import { useHotkey as C } from "../../hooks/useHotkeys/useHotkey.js";
-import { useDevPanelStore as w } from "../../store/store.js";
-import { className as b } from "../../utils/className/className.js";
-import { EmptyContent as y } from "../EmptyContent/EmptyContent.js";
-import { Section as D } from "../Section/Section.js";
-import '../../assets/DevPanel.css';const P = "_devPanelContainer_1vath_1", x = "_header_1vath_12", K = "_title_1vath_21", N = "_button_1vath_31", k = "_collapsed_1vath_53", A = "_content_1vath_60", t = {
-  devPanelContainer: P,
-  header: x,
-  title: K,
-  button: N,
-  collapsed: k,
-  content: A
-}, j = {
+import { jsxs as c, jsx as e } from "react/jsx-runtime";
+import { useCallback as C } from "react";
+import { useDragAndDrop as w } from "../../hooks/useDragAndDrop/useDragAndDrop.js";
+import { useHotkey as b } from "../../hooks/useHotkeys/useHotkey.js";
+import { b as y, u as D } from "../../UIStore-CQdr4U-2.js";
+import { className as P } from "../../utils/className/className.js";
+import { EmptyContent as x } from "../EmptyContent/EmptyContent.js";
+import { Section as K } from "../Section/Section.js";
+import '../../assets/DevPanel.css';const N = "_devPanelContainer_1vath_1", k = "_header_1vath_12", A = "_title_1vath_21", j = "_button_1vath_31", E = "_collapsed_1vath_53", H = "_content_1vath_60", t = {
+  devPanelContainer: N,
+  header: k,
+  title: A,
+  button: j,
+  collapsed: E,
+  content: H
+}, M = {
   ctrlKey: !0,
   shiftKey: !0,
   key: "a",
   altKey: !1,
   metaKey: !1
 };
-function O({ panelTitle: c = "Dev panel", ...d }) {
-  const { isVisible: l, isCollapsed: o, position: a, sections: h, ...n } = w(), m = g(
-    (s) => {
-      n.setPosition(s);
+function U({ panelTitle: d = "Dev panel", ...h }) {
+  const { isVisible: s, isCollapsed: n, position: l, setVisible: a, setCollapsed: m, setPosition: i } = y(), p = D(), v = C(
+    (o) => {
+      i(o);
     },
-    [n]
-  ), { isDragging: p, elementRef: v, handleMouseDown: u } = _({
-    onPositionChange: m
+    [i]
+  ), { isDragging: u, elementRef: f, handleMouseDown: g } = w({
+    onPositionChange: v
   });
-  if (C({
+  if (b({
     description: "Show Dev Panel",
     preventDefault: !0,
-    action: () => n.setVisible(!l),
-    ...j,
-    ...d.hotKeyConfig,
+    action: () => a(!s),
+    ...M,
+    ...h.hotKeyConfig,
     target: window
-  }), !l)
+  }), !s)
     return null;
-  const i = Object.entries(h);
-  return /* @__PURE__ */ r(
+  const r = Object.entries(p);
+  return /* @__PURE__ */ c(
     "div",
     {
-      ref: v,
-      ...b(t.devPanelContainer, {
-        [t.dragging]: p
+      ref: f,
+      ...P(t.devPanelContainer, {
+        [t.dragging]: u
       }),
       style: {
-        left: a.x,
-        top: a.y,
-        height: o ? "auto" : void 0
+        left: l.x,
+        top: l.y,
+        height: n ? "auto" : void 0
       },
       children: [
-        /* @__PURE__ */ r("div", { className: t.header, onMouseDown: u, children: [
-          /* @__PURE__ */ e("button", { className: t.button, onClick: () => n.setCollapsed(!o), title: o ? "Expand" : "Collapse", children: /* @__PURE__ */ e("svg", { xmlns: "http://www.w3.org/2000/svg", viewBox: "0 0 24 24", className: o ? t.collapsed : void 0, children: /* @__PURE__ */ e("path", { d: "M16.843 10.211A.75.75 0 0 0 16.251 9H7.75a.75.75 0 0 0-.591 1.212l4.258 5.498a.746.746 0 0 0 1.183-.001l4.243-5.498z" }) }) }),
-          /* @__PURE__ */ e("div", { className: t.title, children: c }),
-          /* @__PURE__ */ e("button", { className: t.button, onClick: () => n.setVisible(!1), title: "Close", children: /* @__PURE__ */ e("svg", { xmlns: "http://www.w3.org/2000/svg", viewBox: "0 0 24 24", children: /* @__PURE__ */ e("path", { d: "m12 10.93 5.719-5.72a.749.749 0 1 1 1.062 1.062l-5.72 5.719 5.719 5.719a.75.75 0 1 1-1.061 1.062L12 13.053l-5.719 5.719A.75.75 0 0 1 5.22 17.71l5.719-5.719-5.72-5.719A.752.752 0 0 1 6.281 5.21z" }) }) })
+        /* @__PURE__ */ c("div", { className: t.header, onMouseDown: g, children: [
+          /* @__PURE__ */ e("button", { className: t.button, onClick: () => m(!n), title: n ? "Expand" : "Collapse", children: /* @__PURE__ */ e("svg", { xmlns: "http://www.w3.org/2000/svg", viewBox: "0 0 24 24", className: n ? t.collapsed : void 0, children: /* @__PURE__ */ e("path", { d: "M16.843 10.211A.75.75 0 0 0 16.251 9H7.75a.75.75 0 0 0-.591 1.212l4.258 5.498a.746.746 0 0 0 1.183-.001l4.243-5.498z" }) }) }),
+          /* @__PURE__ */ e("div", { className: t.title, children: d }),
+          /* @__PURE__ */ e("button", { className: t.button, onClick: () => a(!1), title: "Close", children: /* @__PURE__ */ e("svg", { xmlns: "http://www.w3.org/2000/svg", viewBox: "0 0 24 24", children: /* @__PURE__ */ e("path", { d: "m12 10.93 5.719-5.72a.749.749 0 1 1 1.062 1.062l-5.72 5.719 5.719 5.719a.75.75 0 1 1-1.061 1.062L12 13.053l-5.719 5.719A.75.75 0 0 1 5.22 17.71l5.719-5.719-5.72-5.719A.752.752 0 0 1 6.281 5.21z" }) }) })
         ] }),
-        !o && /* @__PURE__ */ e("div", { className: t.content, children: i.length ? i.map(([s, f]) => /* @__PURE__ */ e(D, { sectionName: s, section: f }, `section-${s}`)) : /* @__PURE__ */ e(y, {}) })
+        !n && /* @__PURE__ */ e("div", { className: t.content, children: r.length ? r.map(([o, _]) => /* @__PURE__ */ e(K, { sectionName: o, section: _ }, `section-${o}`)) : /* @__PURE__ */ e(x, {}) })
       ]
     }
   );
 }
 export {
-  O as DevPanel
+  U as DevPanel
 };

package/dist/components/DevPanel/types.d.ts

@@ -32,6 +32,8 @@ export interface DevPanelState {
 	position: Position;
 }
 
+export type DevPanelUIState = Omit<DevPanelState, "sections">;
+
 export interface DevPanelActions {
 	setVisible: (visible: boolean) => void;
 	setCollapsed: (collapsed: boolean) => void;