feat(VB-2055): add isVisualEditorEditing helper

src/index.ts

@@ -5,7 +5,6 @@ import LightLivePreviewHoC from "./light-sdk";
 
 export type IStackSdk = ExternalStackSdkType;
 
-
 const ContentstackLivePreview =
     typeof process !== "undefined" &&
     (process?.env?.PURGE_PREVIEW_SDK === "true" ||
@@ -14,4 +13,7 @@ const ContentstackLivePreview =
         : ContentstackLivePreviewHOC;
 
 export const VB_EmptyBlockParentClass = "visual-builder__empty-block-parent";
+
+export { isVisualEditorEditing } from "./visualBuilder/utils/editingState";
+
 export default ContentstackLivePreview;

src/visualBuilder/utils/__test__/editingState.test.ts

@@ -0,0 +1,60 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { isVisualEditorEditing } from "../editingState";
+
+const ATTR = "data-cslp-field-type";
+
+describe("isVisualEditorEditing", () => {
+    let el: HTMLElement;
+
+    beforeEach(() => {
+        document.body.innerHTML = "";
+        el = document.createElement("div");
+        document.body.appendChild(el);
+    });
+
+    it("returns false when nothing is being edited", () => {
+        expect(isVisualEditorEditing()).toBe(false);
+        expect(isVisualEditorEditing(el)).toBe(false);
+    });
+
+    it("returns true when a descendant of the element is being edited", () => {
+        const child = document.createElement("span");
+        el.appendChild(child);
+        child.setAttribute(ATTR, "singleline");
+
+        expect(isVisualEditorEditing(el)).toBe(true);
+    });
+
+    it("returns true when the element itself carries the attribute", () => {
+        el.setAttribute(ATTR, "singleline");
+        expect(isVisualEditorEditing(el)).toBe(true);
+    });
+
+    it("scopes the check to the given element", () => {
+        const other = document.createElement("div");
+        document.body.appendChild(other);
+        const child = document.createElement("span");
+        other.appendChild(child);
+        child.setAttribute(ATTR, "singleline");
+
+        expect(isVisualEditorEditing(el)).toBe(false);
+        expect(isVisualEditorEditing(other)).toBe(true);
+    });
+
+    it("checks the whole document when no element is passed", () => {
+        expect(isVisualEditorEditing()).toBe(false);
+        el.setAttribute(ATTR, "singleline");
+        expect(isVisualEditorEditing()).toBe(true);
+    });
+
+    describe("without a DOM (SSR)", () => {
+        afterEach(() => {
+            vi.unstubAllGlobals();
+        });
+
+        it("returns false", () => {
+            vi.stubGlobal("document", undefined);
+            expect(isVisualEditorEditing()).toBe(false);
+        });
+    });
+});

src/visualBuilder/utils/editingState.ts

@@ -0,0 +1,22 @@
+import { VISUAL_BUILDER_FIELD_TYPE_ATTRIBUTE_KEY } from "./constants";
+
+const EDITING_SELECTOR = `[${VISUAL_BUILDER_FIELD_TYPE_ATTRIBUTE_KEY}]`;
+
+/**
+ * Returns whether a field inside `element` is being edited in Visual Editor.
+ * Pass the element wrapping your self-updating content to pause it while true.
+ * Omit `element` to check the whole document. Returns `false` during SSR.
+ */
+export function isVisualEditorEditing(element?: HTMLElement | null): boolean {
+    if (typeof document === "undefined") return false;
+
+    if (element) {
+        return (
+            (typeof element.matches === "function" &&
+                element.matches(EDITING_SELECTOR)) ||
+            element.querySelector(EDITING_SELECTOR) !== null
+        );
+    }
+
+    return document.querySelector(EDITING_SELECTOR) !== null;
+}