fix: prevent user from exiting interactive mode while in Theme mode and hide sidebar breadcrumbs

packages/visual-editor/src/internal/components/InternalThemeEditor.tsx

@@ -19,6 +19,7 @@ import { v4 as uuidv4 } from "uuid";
 import { ThemeHistories, ThemeHistory } from "../types/themeData.ts";
 import * as lzstring from "lz-string";
 import { Metadata } from "../../editor/Editor.tsx";
+import { createPreviewFrameLinkBlocker } from "../utils/previewFrameLinkBlocker.ts";
 
 const devLogger = new DevLogger();
 // Used because we want the sidebar to be hidden
@@ -71,6 +72,11 @@ export const InternalThemeEditor = ({
     themeHistoriesRef.current = themeHistories;
   }, [themeHistories]);
 
+  useEffect(() => {
+    // In theme mode, links should still be hoverable but never navigate.
+    return createPreviewFrameLinkBlocker();
+  }, []);
+
   const handlePublishTheme = async () => {
     devLogger.logFunc("saveThemeData");
     if (!themeHistories) {

packages/visual-editor/src/internal/puck/components/ThemeHeader.tsx

@@ -6,7 +6,7 @@ import { ThemeConfig } from "../../../utils/themeResolver.ts";
 import { updateThemeInEditor } from "../../../utils/applyTheme.ts";
 import { UIButtonsToggle } from "../ui/UIButtonsToggle.tsx";
 import { ClearLocalChangesButton } from "../ui/ClearLocalChangesButton.tsx";
-import { InitialHistory, useGetPuck } from "@puckeditor/core";
+import { InitialHistory, createUsePuck, useGetPuck } from "@puckeditor/core";
 import { ThemeData, ThemeHistories } from "../../types/themeData.ts";
 import { RotateCcw, RotateCw } from "lucide-react";
 import { Separator } from "@radix-ui/react-separator";
@@ -21,6 +21,9 @@ import {
 } from "../ui/Tooltip.tsx";
 import { getPublishTooltipMessageFromHeadDeployStatus } from "../../utils/getPublishTooltipMessageFromHeadDeployStatus.ts";
 
+const SIDEBAR_HIDE_STYLE_ID = "yext-theme-hide-sidebar-breadcrumbs";
+const usePuck = createUsePuck();
+
 type ThemeHeaderProps = {
   onPublishTheme: () => Promise<void>;
   isDevMode: boolean;
@@ -53,8 +56,9 @@ export const ThemeHeader = (props: ThemeHeaderProps) => {
   } = props;
 
   const getPuck = useGetPuck();
-
+  const previewMode = usePuck((s) => s.appState.ui.previewMode);
   useEffect(() => {
+    // Initialize Puck history and set preview mode to "interactive" on mount
     const {
       dispatch,
       history: { setHistories },
@@ -70,34 +74,38 @@ export const ThemeHeader = (props: ThemeHeaderProps) => {
   }, [puckInitialHistory]);
 
   useEffect(() => {
-    // Hide the components list and fields list titles
-    const fieldListTitle = document.querySelector<HTMLElement>(
-      "[class*='PuckLayout-rightSideBar'] > div[class*='SidebarSection--noBorderTop'] > div[class*='SidebarSection-title']"
-    );
-    if (fieldListTitle) {
-      fieldListTitle.style.display = "none";
-    }
-    const puckPreview =
-      document.querySelector<HTMLIFrameElement>("#preview-frame");
-    if (
-      puckPreview?.contentDocument?.head &&
-      !puckPreview?.contentDocument.getElementById(
-        "yext-preview-disable-pointer-events"
-      )
-    ) {
-      // add this style to preview iFrame to prevent clicking or hover effects.
-      const style = puckPreview.contentDocument.createElement("style");
-      style.id = "yext-preview-disable-pointer-events";
+    // Prevents the "Page" / breadcrumb from appearing over the right sidebar
+    if (!document.getElementById(SIDEBAR_HIDE_STYLE_ID)) {
+      const style = document.createElement("style");
+      style.id = SIDEBAR_HIDE_STYLE_ID;
       style.innerHTML = `
-        * {
-          cursor: default !important;
-          pointer-events: none !important;
+        [class*='SidebarSection-breadcrumbs'] {
+          display: none !important;
+        }
+        [class*='SidebarSection-title'] {
+          display: none !important;
         }
       `;
-      puckPreview.contentDocument.head.appendChild(style);
+      document.head.appendChild(style);
     }
+
+    return () => {
+      document.getElementById(SIDEBAR_HIDE_STYLE_ID)?.remove();
+    };
   }, []);
 
+  useEffect(() => {
+    // Keep theme mode in interactive preview so links/buttons are hoverable
+    // and Puck component selection is disabled.
+    if (previewMode !== "interactive") {
+      const { dispatch } = getPuck();
+      dispatch({
+        type: "setUi",
+        ui: { previewMode: "interactive" },
+      });
+    }
+  }, [previewMode, getPuck]);
+
   const canUndo = (): boolean => {
     if (!themeHistories) {
       return false;

packages/visual-editor/src/internal/utils/previewFrameLinkBlocker.ts

@@ -0,0 +1,216 @@
+import { PUCK_PREVIEW_IFRAME_ID } from "../../utils/applyTheme.ts";
+
+// Selector for interactive elements that should have their default navigation behavior blocked in preview mode, while still allowing hover/focus styles to apply.
+const NON_ACTIONABLE_SELECTOR = [
+  "a",
+  "area",
+  "[role='link']",
+  "[role='menuitem']",
+  "[data-slot='dropdown-menu-trigger']",
+  "[data-slot='dropdown-menu-item']",
+].join(", ");
+
+/**
+ * Installs link-navigation blocking in a specific preview document while
+ * preserving hover and focus behavior.
+ *
+ * @param previewDocument - The iframe document that renders theme preview content.
+ * @returns A cleanup function that restores original link attributes and removes listeners/observers.
+ */
+export const createPreviewDocumentLinkBlocker = (previewDocument: Document) => {
+  const previewWindow = previewDocument.defaultView;
+
+  /**
+   * Returns true when the event target (or one of its ancestors) is a link-like
+   * element or a dropdown menu item/trigger that should not be actionable in preview.
+   */
+  const isBlockedTarget = (event: Event) => {
+    const targetElement = event.target;
+    if (
+      !targetElement ||
+      typeof (targetElement as Element).closest !== "function"
+    ) {
+      return false;
+    }
+
+    return !!(targetElement as Element).closest(NON_ACTIONABLE_SELECTOR);
+  };
+
+  /**
+   * Cancels action-triggering events for blocked interactive targets.
+   * Keyboard events are only blocked for activation keys.
+   */
+  const preventLinkNavigation = (event: Event) => {
+    if (!isBlockedTarget(event)) {
+      return;
+    }
+
+    if (event.type === "keydown") {
+      const key = (event as KeyboardEvent).key;
+      if (key !== "Enter" && key !== " ") {
+        return;
+      }
+    }
+
+    event.preventDefault();
+    event.stopPropagation();
+    event.stopImmediatePropagation();
+  };
+
+  /**
+   * Removes href/target from links so the browser cannot navigate by default.
+   * Original values are stored in data attributes for later restoration.
+   */
+  const disableAnchorNavigationAttributes = () => {
+    previewDocument.querySelectorAll("a[href], area[href]").forEach((el) => {
+      if (!el.hasAttribute("data-ve-original-href")) {
+        el.setAttribute("data-ve-original-href", el.getAttribute("href") ?? "");
+      }
+
+      el.removeAttribute("href");
+
+      if (el.hasAttribute("target")) {
+        el.setAttribute(
+          "data-ve-original-target",
+          el.getAttribute("target") ?? ""
+        );
+        el.removeAttribute("target");
+      }
+    });
+  };
+
+  disableAnchorNavigationAttributes();
+  const anchorObserver = new MutationObserver(() => {
+    disableAnchorNavigationAttributes();
+  });
+  anchorObserver.observe(previewDocument.documentElement, {
+    childList: true,
+    subtree: true,
+  });
+
+  const eventTypes = [
+    "click",
+    "auxclick",
+    "mousedown",
+    "mouseup",
+    "pointerdown",
+    "pointerup",
+    "touchstart",
+    "keydown",
+  ] as const;
+
+  eventTypes.forEach((eventType) => {
+    previewDocument.addEventListener(eventType, preventLinkNavigation, true);
+    previewWindow?.addEventListener(eventType, preventLinkNavigation, true);
+  });
+
+  return () => {
+    anchorObserver.disconnect();
+
+    previewDocument
+      .querySelectorAll("a[data-ve-original-href], area[data-ve-original-href]")
+      .forEach((el) => {
+        const originalHref = el.getAttribute("data-ve-original-href");
+        if (originalHref !== null) {
+          el.setAttribute("href", originalHref);
+        }
+        el.removeAttribute("data-ve-original-href");
+
+        if (el.hasAttribute("data-ve-original-target")) {
+          const originalTarget = el.getAttribute("data-ve-original-target");
+          if (originalTarget !== null) {
+            el.setAttribute("target", originalTarget);
+          }
+          el.removeAttribute("data-ve-original-target");
+        }
+      });
+
+    eventTypes.forEach((eventType) => {
+      previewDocument.removeEventListener(
+        eventType,
+        preventLinkNavigation,
+        true
+      );
+      previewWindow?.removeEventListener(
+        eventType,
+        preventLinkNavigation,
+        true
+      );
+    });
+  };
+};
+
+/**
+ * Watches the preview iframe lifecycle and applies link-navigation blocking
+ * to whichever preview document is currently active.
+ *
+ * @returns A cleanup function that detaches iframe observers and listeners.
+ */
+export const createPreviewFrameLinkBlocker = () => {
+  let detachLinkNavigationBlock: (() => void) | undefined;
+  let activeFrame: HTMLIFrameElement | null = null;
+
+  /**
+   * Rebinds document-level blockers when the iframe loads a new document.
+   */
+  const onPreviewFrameLoad = () => {
+    detachLinkNavigationBlock?.();
+    if (activeFrame?.contentDocument) {
+      detachLinkNavigationBlock = createPreviewDocumentLinkBlocker(
+        activeFrame.contentDocument
+      );
+    }
+  };
+
+  /**
+   * Attaches blocker behavior to a new iframe element and detaches from any
+   * previously tracked iframe.
+   */
+  const attachToPreviewFrame = (frame: HTMLIFrameElement) => {
+    if (activeFrame === frame) {
+      return;
+    }
+
+    activeFrame?.removeEventListener("load", onPreviewFrameLoad);
+    detachLinkNavigationBlock?.();
+
+    activeFrame = frame;
+    activeFrame.addEventListener("load", onPreviewFrameLoad);
+    if (activeFrame.contentDocument) {
+      detachLinkNavigationBlock = createPreviewDocumentLinkBlocker(
+        activeFrame.contentDocument
+      );
+    }
+  };
+
+  /**
+   * Locates the preview iframe and ensures blocker behavior is attached.
+   */
+  const syncPreviewFrame = () => {
+    const previewFrame = document.getElementById(
+      PUCK_PREVIEW_IFRAME_ID
+    ) as HTMLIFrameElement | null;
+    if (!previewFrame) {
+      return;
+    }
+
+    attachToPreviewFrame(previewFrame);
+  };
+
+  const iframeObserver = new MutationObserver(syncPreviewFrame);
+  iframeObserver.observe(document, {
+    childList: true,
+    subtree: true,
+    attributes: true,
+    attributeFilter: ["href", "target"],
+  });
+
+  syncPreviewFrame();
+
+  return () => {
+    iframeObserver.disconnect();
+    activeFrame?.removeEventListener("load", onPreviewFrameLoad);
+    detachLinkNavigationBlock?.();
+    activeFrame = null;
+  };
+};