feat: add debug logging with xYextDebug

src/components/Editor.tsx

@@ -12,6 +12,7 @@ import {
 } from "../internal/hooks/useMessage.ts";
 import { SaveState } from "../internal/types/saveState.ts";
 import "@measured/puck/puck.css";
+import { DevLogger, DevLoggerPrefix } from "../utils/devLogger.ts";
 
 export const Role = {
   GLOBAL: "global",
@@ -38,6 +39,8 @@ export interface EditorProps {
   componentRegistry: Map<string, Config<any>>;
 }
 
+const devLogger = new DevLogger();
+
 export const Editor = ({ document, componentRegistry }: EditorProps) => {
   const [puckInitialHistory, setPuckInitialHistory] =
     useState<PuckInitialHistory>({
@@ -54,6 +57,10 @@ export const Editor = ({ document, componentRegistry }: EditorProps) => {
   const [puckConfig, setPuckConfig] = useState<Config>();
   const [parentLoaded, setParentLoaded] = useState<boolean>(false);
 
+  if (document) {
+    devLogger.logData("DOCUMENT", document);
+  }
+
   const buildLocalStorageKey = useCallback(() => {
     if (!templateMetadata) {
       return "";
@@ -88,7 +95,11 @@ export const Editor = ({ document, componentRegistry }: EditorProps) => {
   useReceiveMessage("getTemplateMetadata", TARGET_ORIGINS, (send, payload) => {
     const puckConfig = componentRegistry.get(payload.templateId);
     setPuckConfig(puckConfig);
+    const templateMetadata = payload as TemplateMetadata;
     setTemplateMetadata(payload as TemplateMetadata);
+    devLogger.enable(templateMetadata.isxYextDebug);
+    devLogger.logData("TEMPLATE_METADATA", templateMetadata);
+    devLogger.logData("PUCK_CONFIG", puckConfig);
     send({ status: "success", payload: { message: "payload received" } });
   });
 
@@ -108,13 +119,15 @@ export const Editor = ({ document, componentRegistry }: EditorProps) => {
    * Clears the user's localStorage and resets the current Puck history
    */
   const clearLocalStorage = () => {
+    devLogger.logFunc("clearLocalStorage");
     window.localStorage.removeItem(buildLocalStorageKey());
   };
 
   /**
    * Clears localStorage and resets the save data in the DB
    */
   const clearHistory = () => {
+    devLogger.logFunc("clearHistory");
     clearLocalStorage();
     deleteSaveState();
   };
@@ -148,6 +161,8 @@ export const Editor = ({ document, componentRegistry }: EditorProps) => {
       return;
     }
 
+    devLogger.logFunc("loadPuckInitialHistory");
+
     if (templateMetadata.isDevMode && !templateMetadata.devOverride) {
       // Check localStorage for existing Puck history
       const localHistoryArray = window.localStorage.getItem(
@@ -156,6 +171,7 @@ export const Editor = ({ document, componentRegistry }: EditorProps) => {
 
       // Use localStorage directly if it exists
       if (localHistoryArray) {
+        devLogger.log("Dev Mode - Using localStorage");
         const localHistories = JSON.parse(localHistoryArray);
         const localHistoryIndex = localHistories.length - 1;
         setPuckInitialHistory({
@@ -166,6 +182,7 @@ export const Editor = ({ document, componentRegistry }: EditorProps) => {
       }
 
       // Otherwise start fresh from Content
+      devLogger.log("Dev Mode - No localStorage. Using data from Content");
       setPuckInitialHistory({
         histories: visualConfigurationData
           ? [{ id: "root", data: { data: visualConfigurationData } }]
@@ -180,6 +197,7 @@ export const Editor = ({ document, componentRegistry }: EditorProps) => {
     if (!saveState) {
       clearLocalStorage();
 
+      devLogger.log("Prod Mode - No saveState. Using data from Content");
       setPuckInitialHistory({
         histories: visualConfigurationData
           ? [{ id: "root", data: { data: visualConfigurationData } }]
@@ -197,6 +215,7 @@ export const Editor = ({ document, componentRegistry }: EditorProps) => {
 
     // No localStorage, start from saveState
     if (!localHistoryArray) {
+      devLogger.log("Prod Mode - No localStorage. Using saveState");
       setPuckInitialHistory({
         histories: visualConfigurationData
           ? [
@@ -223,6 +242,7 @@ export const Editor = ({ document, componentRegistry }: EditorProps) => {
 
     // If local storage reset Puck history to it
     if (localHistoryIndex !== -1) {
+      devLogger.log("Prod Mode - Using localStorage");
       setPuckInitialHistory({
         histories: JSON.parse(localHistoryArray),
         index: localHistoryIndex,
@@ -234,6 +254,12 @@ export const Editor = ({ document, componentRegistry }: EditorProps) => {
     clearLocalStorage();
   }, [setPuckInitialHistory, clearLocalStorage, getLocalStorageKey]);
 
+  useEffect(() => {
+    if (puckInitialHistory) {
+      devLogger.logData("PUCK_INITIAL_HISTORY", puckInitialHistory);
+    }
+  }, [puckInitialHistory]);
+
   const { sendToParent: iFrameLoaded } = useSendMessageToParent(
     "iFrameLoaded",
     TARGET_ORIGINS
@@ -262,6 +288,7 @@ export const Editor = ({ document, componentRegistry }: EditorProps) => {
   }, [templateMetadata]);
 
   useReceiveMessage("getSaveState", TARGET_ORIGINS, (send, payload) => {
+    devLogger.logData("SAVE_STATE", payload);
     setSaveState(payload as SaveState);
     setSaveStateFetched(true);
     send({ status: "success", payload: { message: "saveState received" } });
@@ -271,9 +298,9 @@ export const Editor = ({ document, componentRegistry }: EditorProps) => {
     "getVisualConfigurationData",
     TARGET_ORIGINS,
     (send, payload) => {
-      setVisualConfigurationData(
-        jsonFromEscapedJsonString(payload.visualConfigurationData)
-      );
+      const vcd = jsonFromEscapedJsonString(payload.visualConfigurationData);
+      devLogger.logData("VISUAL_CONFIGURATION_DATA", vcd);
+      setVisualConfigurationData(vcd);
       setVisualConfigurationDataFetched(true);
       send({
         status: "success",
@@ -367,6 +394,7 @@ export const Editor = ({ document, componentRegistry }: EditorProps) => {
           sendDevSaveStateData={sendDevSaveStateData}
           visualConfigurationData={visualConfigurationData}
           buildLocalStorageKey={buildLocalStorageKey}
+          devLogger={devLogger}
         />
       ) : (
         parentLoaded && <LoadingScreen progress={progress} />

src/internal/components/InternalEditor.tsx

@@ -7,6 +7,7 @@ import { TemplateMetadata } from "../types/templateMetadata.ts";
 import { EntityFieldProvider } from "../../components/EntityField.tsx";
 import { SaveState } from "../types/saveState.ts";
 import { PuckInitialHistory } from "../../components/Editor.tsx";
+import { DevLogger } from "../../utils/devLogger.ts";
 
 interface InternalEditorProps {
   puckConfig: Config;
@@ -20,6 +21,7 @@ interface InternalEditorProps {
   sendDevSaveStateData: (data: any) => void;
   visualConfigurationData: any;
   buildLocalStorageKey: () => string;
+  devLogger: DevLogger;
 }
 
 // Render Puck editor
@@ -35,6 +37,7 @@ export const InternalEditor = ({
   sendDevSaveStateData,
   visualConfigurationData,
   buildLocalStorageKey,
+  devLogger,
 }: InternalEditorProps) => {
   const [canEdit, setCanEdit] = useState<boolean>(false);
   const historyIndex = useRef<number>(-1);
@@ -50,21 +53,27 @@ export const InternalEditor = ({
         historyIndex.current !== index &&
         histories.length > 0
       ) {
+        devLogger.logFunc("handleHistoryChange");
+        devLogger.logData("PUCK_INDEX", index);
+        devLogger.logData("PUCK_HISTORY", histories);
         historyIndex.current = index;
 
+        devLogger.logFunc("saveToLocalStorage");
         window.localStorage.setItem(
           buildLocalStorageKey(),
           JSON.stringify(histories)
         );
 
         if (saveState?.hash !== histories[index].id) {
           if (templateMetadata.isDevMode && !templateMetadata.devOverride) {
+            devLogger.logFunc("sendDevSaveStateData");
             sendDevSaveStateData({
               payload: {
                 devSaveStateData: JSON.stringify(histories[index].data?.data),
               },
             });
           } else {
+            devLogger.logFunc("saveSaveState");
             saveSaveState({
               payload: {
                 hash: histories[index].id,
@@ -84,6 +93,7 @@ export const InternalEditor = ({
   };
 
   const handleSave = async (data: Data) => {
+    devLogger.logFunc("saveVisualConfigData");
     saveVisualConfigData({
       payload: { visualConfigurationData: JSON.stringify(data) },
     });

src/internal/types/templateMetadata.ts

@@ -6,4 +6,5 @@ export type TemplateMetadata = {
   entityId?: number;
   isDevMode: boolean;
   devOverride: boolean;
+  isxYextDebug: boolean;
 };

src/utils/devLogger.ts

@@ -0,0 +1,53 @@
+export type DevLoggerPrefix =
+  | "TEMPLATE_METADATA"
+  | "PUCK_CONFIG"
+  | "SAVE_STATE"
+  | "VISUAL_CONFIGURATION_DATA"
+  | "DOCUMENT"
+  | "PUCK_INDEX"
+  | "PUCK_HISTORY"
+  | "PUCK_INITIAL_HISTORY";
+
+export class DevLogger {
+  constructor(private enabled: boolean = false) {
+    if (!this.enabled) {
+      return;
+    }
+
+    console.log("[DEBUG] xYextDebug enabled");
+  }
+
+  enable = (enabled: boolean) => {
+    this.enabled = enabled;
+
+    if (!this.enabled) {
+      return;
+    }
+
+    console.log("[DEBUG] xYextDebug enabled");
+  };
+
+  logData = (devLoggerPrefix: DevLoggerPrefix, payload: any) => {
+    if (!this.enabled) {
+      return;
+    }
+
+    console.log("[DEBUG]", devLoggerPrefix, "-", payload);
+  };
+
+  logFunc = (functionName: string) => {
+    if (!this.enabled) {
+      return;
+    }
+
+    console.log("[DEBUG] -->", functionName, "called");
+  };
+
+  log = (text: string) => {
+    if (!this.enabled) {
+      return;
+    }
+
+    console.log("[DEBUG]", text);
+  };
+}