@berenjena/react-dev-panel 2.4.2 → 2.5.0

package/dist/hooks/useDevPanel/index.js

@@ -1,52 +1,61 @@
-import { useRef as d, useEffect as s, createElement as v } from "react";
-import { createRoot as S } from "react-dom/client";
-import { DevPanelPortal as E } from "../../components/DevPanelPortal/index.js";
+"use client";
+import { useRef as d, useEffect as f } from "react";
 import { DevPanelManager as P } from "../../managers/DevPanelManager.js";
-import { controlPersistenceService as m } from "../../store/ControlPersistenceService.js";
-import { useDevPanelSections as w, useDevPanelSectionActions as D } from "../../store/SectionsStore.js";
-import { hasControlsChanged as R } from "../../utils/hasControlChanged/hasControlChanged.js";
-function j(t, o, i) {
-  const p = w(), { registerSection: g, unregisterSection: h } = D(), C = d(void 0), c = d(null), f = d(/* @__PURE__ */ new Set());
-  c.current || (c.current = P.getInstance()), s(() => {
-    Object.entries(o).forEach(([e, n]) => {
-      const r = `${t}-${e}`;
-      if (n.persist && !f.current.has(r)) {
-        const a = m.getPersistedValue(t, e);
-        a !== void 0 && "onChange" in n && typeof n.onChange == "function" && n.onChange(a), f.current.add(r);
+import { controlPersistenceService as C } from "../../store/ControlPersistenceService.js";
+import { useDevPanelSections as $, useDevPanelSectionActions as m } from "../../store/SectionsStore.js";
+import { hasControlsChanged as E } from "../../utils/hasControlChanged/hasControlChanged.js";
+import { isValidPersistedValue as V } from "../../utils/isValidPersistedValue/isValidPersistedValue.js";
+import { mountDevPanelPortal as b } from "./mountDevPanelPortal.js";
+function M(e, i, o) {
+  const v = $(), { registerSection: l, unregisterSection: a } = m(), p = d(void 0), c = d(null), h = d(/* @__PURE__ */ new Set()), s = o?.enabled ?? !0;
+  c.current || (c.current = P.getInstance()), f(() => {
+    s && Object.entries(i).forEach(([n, r]) => {
+      const t = `${e}-${n}`;
+      if (r.persist && !h.current.has(t)) {
+        const u = C.getPersistedValue(e, n);
+        u !== void 0 && "onChange" in r && typeof r.onChange == "function" && (V(r, u) ? r.onChange(u) : (console.warn(
+          `[DevPanel] Ignoring persisted value for "${e}.${n}": type does not match control "${r.type}". Dropping stored value.`
+        ), C.removePersistedValue(e, n))), h.current.add(t);
       }
     });
-  }, [t, o]);
-  const u = d({});
-  s(() => {
-    const e = {};
-    Object.entries(o).forEach(([n, r]) => {
-      if (r.persist && "onChange" in r && typeof r.onChange == "function") {
-        const a = r.onChange;
-        e[n] = {
-          ...r,
-          onChange: (l) => {
-            m.setPersistedValue(t, n, l), a(l);
+  }, [s, e, i]);
+  const g = d({});
+  f(() => {
+    const n = {};
+    Object.entries(i).forEach(([r, t]) => {
+      if (t.persist && "onChange" in t && typeof t.onChange == "function") {
+        const u = t.onChange;
+        n[r] = {
+          ...t,
+          onChange: (S) => {
+            C.setPersistedValue(e, r, S);
+            try {
+              u(S);
+            } catch (D) {
+              console.error(`[DevPanel] Error in onChange for "${e}.${r}":`, D);
+            }
           }
         };
       } else
-        e[n] = r;
-    }), u.current = e;
-  }, [t, o]), s(() => {
-    const e = c.current, n = p[t] !== void 0;
-    R(u.current, C.current) || !n ? (g(t, u.current), C.current = u.current, e.addSection(t, i)) : i && e.updateProps(i);
-  }, [t, o, i, p, g]), s(() => {
-    const e = f.current;
+        n[r] = t;
+    }), g.current = n;
+  }, [e, i]), f(() => {
+    const n = c.current, r = v[e] !== void 0;
+    if (!s) {
+      r && (a(e), n.removeSection(e), p.current = void 0);
+      return;
+    }
+    E(g.current, p.current) || !r ? (l(e, g.current), p.current = g.current, n.addSection(e, o)) : o && n.updateProps(o);
+  }, [s, e, i, o, v, l, a]), f(() => {
+    const n = h.current;
     return () => {
-      const n = c.current;
-      h(t), n.removeSection(t), e.clear();
+      const r = c.current;
+      a(e), r.removeSection(e), n.clear();
     };
-  }, [t, h]), s(() => {
-    if (window.__devPanelAutoMounted) return;
-    window.__devPanelAutoMounted = !0;
-    const e = document.createElement("div");
-    e.id = "dev-panel-portal-container", e.style.display = "none", document.body.appendChild(e), S(e).render(v(E));
-  }, []);
+  }, [e, a]), f(() => {
+    s && b();
+  }, [s]);
 }
 export {
-  j as useDevPanel
+  M as useDevPanel
 };

package/dist/hooks/useDevPanel/mountDevPanelPortal.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Mounts the DevPanelPortal into a dedicated, hidden container appended to
+ * `document.body`, creating a single React root for the whole app.
+ *
+ * Idempotent and safe to call from every `useDevPanel` call site:
+ * - No-op in non-browser environments (SSR) — guarded by `typeof document`.
+ * - No-op if already mounted in this runtime (the stored `root` acts as guard).
+ * - Self-heals across HMR/module reloads: a stale container left over from a
+ *   previous module instance is removed before creating a fresh root, so the
+ *   portal never duplicates and never leaks an orphaned container.
+ */
+export declare function mountDevPanelPortal(): void;
+/**
+ * Tears down the DevPanelPortal root and removes its container from the DOM.
+ * Intended for HMR resets and tests; the portal re-mounts on the next
+ * `mountDevPanelPortal` call.
+ */
+export declare function unmountDevPanelPortal(): void;

package/dist/hooks/useDevPanel/mountDevPanelPortal.js

@@ -0,0 +1,20 @@
+"use client";
+import { createElement as r } from "react";
+import { createRoot as l } from "react-dom/client";
+import { DevPanelPortal as i } from "../../components/DevPanelPortal/index.js";
+import { registerDevPanelConsoleApi as m, unregisterDevPanelConsoleApi as u } from "./consoleApi.js";
+const o = "dev-panel-portal-container";
+let n = null, e = null;
+function f() {
+  if (typeof document > "u" || n)
+    return;
+  const t = document.getElementById(o);
+  t && t.remove(), e = document.createElement("div"), e.id = o, e.style.display = "none", document.body.appendChild(e), n = l(e), n.render(r(i)), m();
+}
+function s() {
+  n?.unmount(), n = null, e?.remove(), e = null, u();
+}
+export {
+  f as mountDevPanelPortal,
+  s as unmountDevPanelPortal
+};

package/dist/hooks/useDragAndDrop/index.js

@@ -1,3 +1,4 @@
+"use client";
 import { useRef as g, useState as p, useCallback as u, useEffect as f } from "react";
 import { debounce as E } from "../../utils/debounce/debounce.js";
 import { getConstrainedPosition as D } from "../../utils/getConstrainedPosition/getConstrainedPosition.js";

package/dist/hooks/useHotKey/index.js

@@ -1,7 +1,8 @@
+"use client";
 import { useHotkeys as t } from "../useHotkeys/index.js";
-function s(o, e = {}) {
-  t([o], e);
+function u(e, o = {}) {
+  t([e], o);
 }
 export {
-  s as useHotkey
+  u as useHotkey
 };

package/dist/hooks/useHotkeys/index.js

@@ -1,3 +1,4 @@
+"use client";
 import { useRef as K, useCallback as y, useEffect as w } from "react";
 function M(h, p = {}) {
   const { enabled: a = !0, target: c = window, preventDefault: f = !1, stopPropagation: l = !1 } = p, u = K([]);

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 export { useDevPanel } from './hooks/useDevPanel';
+export type { DevPanelConsoleApi } from './hooks/useDevPanel/consoleApi';
 export type { DevPanelProps } from './components/DevPanel/types';
 export type { ControlsGroup } from './components/ControlRenderer/controls/types';

package/dist/index.js

@@ -1,4 +1,5 @@
-import { useDevPanel as r } from "./hooks/useDevPanel/index.js";
-import './assets/index.css';export {
-  r as useDevPanel
+"use client";
+import { useDevPanel as n } from "./hooks/useDevPanel/index.js";
+export {
+  n as useDevPanel
 };

package/dist/managers/DevPanelManager.js

@@ -1,3 +1,4 @@
+"use client";
 class e {
   static instance = null;
   currentProps = {};

package/dist/store/BaseStoreService.d.ts

@@ -1,13 +1,8 @@
-/**
- * Abstract base class for state management services using the useSyncExternalStore pattern.
- * Provides common functionality for subscription management, state updates, and persistence.
- *
- * @template TState - The type of the state object
- * @template TPersistedState - The type of the persisted state object (usually a subset of TState)
- */
 export declare abstract class BaseStoreService<TState, TPersistedState = TState> {
     /** Set of listeners subscribed to state changes */
     protected readonly listeners: Set<() => void>;
+    /** Whether a persistence failure has already been logged (avoids log spam). */
+    private persistenceWarned;
     /** The localStorage key for persisting state */
     protected readonly storageKey: string;
     /** Whether this store should persist state to localStorage */

package/dist/store/BaseStoreService.js

@@ -1,6 +1,10 @@
-class r {
+"use client";
+import { deepEqual as r } from "../utils/deepEqual/deepEqual.js";
+class n {
   /** Set of listeners subscribed to state changes */
   listeners = /* @__PURE__ */ new Set();
+  /** Whether a persistence failure has already been logged (avoids log spam). */
+  persistenceWarned = !1;
   /** The localStorage key for persisting state */
   storageKey;
   /** Whether this store should persist state to localStorage */
@@ -24,12 +28,15 @@ class r {
    * @protected
    */
   saveState() {
-    if (this.shouldPersist)
+    if (!(!this.shouldPersist || typeof localStorage > "u"))
       try {
         const t = this.toPersistableState(this.state);
         localStorage.setItem(this.storageKey, JSON.stringify(t));
-      } catch {
-        console.warn(`Failed to save ${this.getServiceName()} state to localStorage`);
+      } catch (t) {
+        if (!this.persistenceWarned) {
+          const e = t instanceof DOMException && t.name === "QuotaExceededError" ? "localStorage quota exceeded" : "localStorage unavailable";
+          console.warn(`[DevPanel] Failed to save ${this.getServiceName()} state (${e}).`), this.persistenceWarned = !0;
+        }
       }
   }
   /**
@@ -39,7 +46,7 @@ class r {
    * @protected
    */
   loadState() {
-    if (this.shouldPersist)
+    if (!(!this.shouldPersist || typeof localStorage > "u"))
       try {
         const t = localStorage.getItem(this.storageKey);
         if (t) {
@@ -67,7 +74,7 @@ class r {
    */
   setState(t) {
     const e = t(this.state);
-    JSON.stringify(e) !== JSON.stringify(this.state) && (this.state = e, this.saveState(), this.notifySubscribers());
+    r(e, this.state) || (this.state = e, this.saveState(), this.notifySubscribers());
   }
   /**
    * Returns the current state snapshot for useSyncExternalStore.
@@ -86,5 +93,5 @@ class r {
   });
 }
 export {
-  r as BaseStoreService
+  n as BaseStoreService
 };

package/dist/store/ControlPersistenceService.d.ts

@@ -3,6 +3,8 @@
  */
 declare class ControlPersistenceService {
     private readonly storageKey;
+    /** Whether a write failure has already been logged (avoids log spam). */
+    private writeWarned;
     /**
      * Gets persisted value for a control
      * @param sectionName - Name of the section

package/dist/store/ControlPersistenceService.js

@@ -1,5 +1,8 @@
+"use client";
 class a {
   storageKey = "dev-panel-controls-persistence";
+  /** Whether a write failure has already been logged (avoids log spam). */
+  writeWarned = !1;
   /**
    * Gets persisted value for a control
    * @param sectionName - Name of the section
@@ -7,12 +10,13 @@ class a {
    * @returns Persisted value or undefined if not found
    */
   getPersistedValue(e, s) {
-    try {
-      const t = localStorage.getItem(this.storageKey);
-      return t ? JSON.parse(t)[e]?.[s] : void 0;
-    } catch {
-      return;
-    }
+    if (!(typeof localStorage > "u"))
+      try {
+        const r = localStorage.getItem(this.storageKey);
+        return r ? JSON.parse(r)[e]?.[s] : void 0;
+      } catch {
+        return;
+      }
   }
   /**
    * Sets persisted value for a control
@@ -20,12 +24,14 @@ class a {
    * @param controlKey - Key of the control within the section
    * @param value - Value to persist
    */
-  setPersistedValue(e, s, t) {
-    try {
-      const r = localStorage.getItem(this.storageKey), o = r ? JSON.parse(r) : {};
-      o[e] || (o[e] = {}), o[e][s] = t, localStorage.setItem(this.storageKey, JSON.stringify(o));
-    } catch {
-    }
+  setPersistedValue(e, s, r) {
+    if (!(typeof localStorage > "u"))
+      try {
+        const t = localStorage.getItem(this.storageKey), o = t ? JSON.parse(t) : {};
+        o[e] || (o[e] = {}), o[e][s] = r, localStorage.setItem(this.storageKey, JSON.stringify(o));
+      } catch (t) {
+        this.writeWarned || (console.warn(`[DevPanel] Failed to persist "${e}.${s}" (quota exceeded or value not serializable).`, t), this.writeWarned = !0);
+      }
   }
   /**
    * Removes persisted value for a control
@@ -33,26 +39,28 @@ class a {
    * @param controlKey - Key of the control within the section
    */
   removePersistedValue(e, s) {
-    try {
-      const t = localStorage.getItem(this.storageKey);
-      if (!t) return;
-      const r = JSON.parse(t);
-      r[e] && (delete r[e][s], Object.keys(r[e]).length === 0 && delete r[e], localStorage.setItem(this.storageKey, JSON.stringify(r)));
-    } catch {
-    }
+    if (!(typeof localStorage > "u"))
+      try {
+        const r = localStorage.getItem(this.storageKey);
+        if (!r) return;
+        const t = JSON.parse(r);
+        t[e] && (delete t[e][s], Object.keys(t[e]).length === 0 && delete t[e], localStorage.setItem(this.storageKey, JSON.stringify(t)));
+      } catch {
+      }
   }
   /**
    * Removes all persisted values for a section
    * @param sectionName - Name of the section
    */
   removeSection(e) {
-    try {
-      const s = localStorage.getItem(this.storageKey);
-      if (!s) return;
-      const t = JSON.parse(s);
-      delete t[e], localStorage.setItem(this.storageKey, JSON.stringify(t));
-    } catch {
-    }
+    if (!(typeof localStorage > "u"))
+      try {
+        const s = localStorage.getItem(this.storageKey);
+        if (!s) return;
+        const r = JSON.parse(s);
+        delete r[e], localStorage.setItem(this.storageKey, JSON.stringify(r));
+      } catch {
+      }
   }
 }
 const l = new a();

package/dist/store/SectionsStore.js

@@ -1,7 +1,8 @@
+"use client";
 import { useSyncExternalStore as n } from "react";
 import { BaseStoreService as c } from "./BaseStoreService.js";
 const S = "dev-panel-sections-storage";
-class a extends c {
+class l extends c {
   /**
    * Creates a new DevPanelSectionsService instance.
    */
@@ -96,7 +97,7 @@ class a extends c {
     this.setState(() => ({}));
   };
 }
-const r = new a();
+const r = new l();
 function p() {
   return n(r.subscribe, r.getSnapshot);
 }

package/dist/store/UIStore.d.ts

@@ -1,4 +1,18 @@
 import { DevPanelUIState, Position } from '../components/DevPanel/types';
+/**
+ * Imperatively shows the dev panel. Usable outside React (e.g. the console API).
+ * The panel still only appears on screen if at least one section is registered.
+ */
+export declare function showDevPanel(): void;
+/**
+ * Imperatively hides the dev panel. Usable outside React (e.g. the console API).
+ */
+export declare function hideDevPanel(): void;
+/**
+ * Imperatively toggles the dev panel visibility — mirrors the keyboard hotkey.
+ * Usable outside React (e.g. the console API).
+ */
+export declare function toggleDevPanel(): void;
 /**
  * React hook that provides access to the complete dev panel UI state and actions.
  * Uses useSyncExternalStore for optimal performance and React 18 compatibility.

package/dist/store/UIStore.js

@@ -1,12 +1,13 @@
+"use client";
 import { useSyncExternalStore as r } from "react";
 import { BaseStoreService as o } from "./BaseStoreService.js";
-const u = "dev-panel-ui-storage", h = { x: 20, y: 20 }, n = {
+const u = "dev-panel-ui-storage", l = { x: 20, y: 20 }, n = {
   isVisible: !1,
   isCollapsed: !1,
-  position: h,
+  position: l,
   currentTheme: "auto"
 };
-class a extends o {
+class h extends o {
   /**
    * Creates a new DevPanelUIService instance and loads persisted state from localStorage.
    */
@@ -58,6 +59,8 @@ class a extends o {
    * @private
    */
   applyTheme(t) {
+    if (typeof document > "u")
+      return;
     const s = document.documentElement;
     t === "auto" || t === "" ? s.removeAttribute("data-dev-panel-theme") : s.setAttribute("data-dev-panel-theme", t);
   }
@@ -113,8 +116,17 @@ class a extends o {
     this.setState(() => ({ ...n })), this.applyTheme(n.currentTheme);
   };
 }
-const e = new a();
-function l() {
+const e = new h();
+function T() {
+  e.setVisible(!0);
+}
+function p() {
+  e.setVisible(!1);
+}
+function b() {
+  e.setVisible(!e.getSnapshot().isVisible);
+}
+function a() {
   return {
     ...r(e.subscribe, e.getSnapshot),
     setVisible: e.setVisible,
@@ -126,19 +138,19 @@ function l() {
     reset: e.reset
   };
 }
-function c() {
+function d() {
   return r(e.subscribe, () => e.getSnapshot().isVisible);
 }
-function p() {
+function S() {
   return r(e.subscribe, () => e.getSnapshot().isCollapsed);
 }
-function b() {
+function f() {
   return r(e.subscribe, () => e.getSnapshot().position);
 }
-function S() {
+function g() {
   return r(e.subscribe, () => e.getSnapshot().currentTheme);
 }
-function d() {
+function P() {
   return {
     currentTheme: r(e.subscribe, () => e.getSnapshot().currentTheme),
     setTheme: e.setTheme,
@@ -146,7 +158,7 @@ function d() {
     getCurrentTheme: e.getCurrentTheme
   };
 }
-function C() {
+function v() {
   return {
     setVisible: e.setVisible,
     setCollapsed: e.setCollapsed,
@@ -157,22 +169,25 @@ function C() {
     reset: e.reset
   };
 }
-function g() {
+function C() {
   return {
     setTheme: e.setTheme,
     resetTheme: e.resetTheme,
     getCurrentTheme: e.getCurrentTheme
   };
 }
-const P = l;
+const V = a;
 export {
-  S as useCurrentTheme,
-  p as useDevPanelCollapsed,
-  b as useDevPanelPosition,
-  P as useDevPanelStore,
-  d as useDevPanelTheme,
-  g as useDevPanelThemeActions,
-  l as useDevPanelUI,
-  C as useDevPanelUIActions,
-  c as useDevPanelVisible
+  p as hideDevPanel,
+  T as showDevPanel,
+  b as toggleDevPanel,
+  g as useCurrentTheme,
+  S as useDevPanelCollapsed,
+  f as useDevPanelPosition,
+  V as useDevPanelStore,
+  P as useDevPanelTheme,
+  C as useDevPanelThemeActions,
+  a as useDevPanelUI,
+  v as useDevPanelUIActions,
+  d as useDevPanelVisible
 };

package/dist/utils/className/className.js

@@ -1,15 +1,16 @@
-function f(...o) {
+"use client";
+function c(...t) {
   const s = [];
-  for (const e of o)
+  for (const e of t)
     if (e) {
       if (typeof e == "string")
         s.push(e);
       else if (typeof e == "object")
-        for (const [t, n] of Object.entries(e))
-          n && s.push(t);
+        for (const [o, n] of Object.entries(e))
+          n && s.push(o);
     }
   return { className: s.join(" ") };
 }
 export {
-  f as className
+  c as className
 };

package/dist/utils/className/index.js

@@ -1,4 +1,5 @@
-import { className as m } from "./className.js";
+"use client";
+import { className as a } from "./className.js";
 export {
-  m as className
+  a as className
 };

package/dist/utils/copyToClipboard/copyToClipboard.js

@@ -1,3 +1,4 @@
+"use client";
 async function t(o) {
   try {
     await navigator.clipboard.writeText(o);

package/dist/utils/copyToClipboard/index.js

@@ -1,4 +1,5 @@
-import { copyToClipboard as r } from "./copyToClipboard.js";
+"use client";
+import { copyToClipboard as p } from "./copyToClipboard.js";
 export {
-  r as copyToClipboard
+  p as copyToClipboard
 };

package/dist/utils/createHotkey/createHotkey.js

@@ -1,4 +1,5 @@
-function c(e, a, t = {}, y = {}) {
+"use client";
+function l(e, a, t = {}, c = {}) {
   return {
     key: e,
     action: a,
@@ -6,9 +7,9 @@ function c(e, a, t = {}, y = {}) {
     shiftKey: t.shift,
     altKey: t.alt,
     metaKey: t.meta,
-    ...y
+    ...c
   };
 }
 export {
-  c as createHotkey
+  l as createHotkey
 };

package/dist/utils/createHotkey/index.js

@@ -1,4 +1,5 @@
-import { createHotkey as r } from "./createHotkey.js";
+"use client";
+import { createHotkey as o } from "./createHotkey.js";
 export {
-  r as createHotkey
+  o as createHotkey
 };

package/dist/utils/debounce/debounce.js

@@ -1,7 +1,8 @@
-function i(t, o) {
+"use client";
+function i(t, u) {
   let e;
-  return (...u) => {
-    clearTimeout(e), e = setTimeout(() => t(...u), o);
+  return (...o) => {
+    clearTimeout(e), e = setTimeout(() => t(...o), u);
   };
 }
 export {

package/dist/utils/debounce/index.js

@@ -1,4 +1,5 @@
-import { debounce as r } from "./debounce.js";
+"use client";
+import { debounce as c } from "./debounce.js";
 export {
-  r as debounce
+  c as debounce
 };

package/dist/utils/deepEqual/deepEqual.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Structural deep-equality check used to skip redundant store updates and
+ * re-registrations.
+ *
+ * Preferable to comparing two `JSON.stringify` outputs because it:
+ * - does not allocate two full string copies on every call;
+ * - is insensitive to object key order;
+ * - compares functions by reference (`Object.is`) instead of silently dropping
+ *   them, so a control whose only change is a new `onChange` handler is still
+ *   detected as changed.
+ *
+ * Note: like `JSON.stringify`, it does not guard against circular references;
+ * the states compared here (UI state, control descriptors) are never circular.
+ *
+ * @param a - First value
+ * @param b - Second value
+ * @returns `true` when the two values are structurally equal
+ */
+export declare function deepEqual(a: unknown, b: unknown): boolean;