@elementor/editor-canvas 4.2.0-883 → 4.2.0-885

package/dist/index.d.mts

@@ -4,6 +4,7 @@ import { Root } from 'react-dom/client';
 import * as _elementor_editor_props from '@elementor/editor-props';
 import { Props, PropValue, PropType, PropTypeKey, PropsSchema, AnyTransformable } from '@elementor/editor-props';
 import { StyleVariables, StyleDefinitionsMap, StyleDefinitionID, StyleDefinitionState } from '@elementor/editor-styles';
+import * as React$1 from 'react';
 import * as _elementor_utils from '@elementor/utils';
 
 declare const BREAKPOINTS_SCHEMA_URI = "elementor://breakpoints/list";
@@ -292,6 +293,8 @@ type ResolvedProps = Record<string, unknown>;
 type PropsResolver = ReturnType<typeof createPropsResolver>;
 declare function createPropsResolver({ transformers, schema: initialSchema, onPropResolve }: CreatePropResolverArgs): ({ props, schema, signal, renderContext }: ResolveArgs) => Promise<ResolvedProps>;
 
+declare function waitForChildrenToComplete(view: Pick<ElementView, 'children'>): Promise<void>;
+
 declare const settingsTransformersRegistry: {
     register(type: _elementor_editor_props.PropTypeKey, transformer: AnyTransformer): /*elided*/ any;
     registerFallback(transformer: AnyTransformer): /*elided*/ any;
@@ -326,6 +329,14 @@ type ImportedGlobalStylesPayload = {
 
 declare const DOCUMENT_STRUCTURE_URI = "elementor://document/structure";
 
+type SpotlightBackdropProps = {
+    canvas: Document;
+    element: HTMLElement | null;
+    onExit: () => void;
+    ariaLabel: string;
+};
+declare function SpotlightBackdrop({ canvas, element, onExit, ariaLabel }: SpotlightBackdropProps): React$1.JSX.Element;
+
 declare function createTransformer<TValue = never>(cb: TValue extends AnyTransformable ? 'Transformable values are invalid, use the actual value instead.' : UnbrandedTransformer<TValue>): Transformer<NoInfer<TValue>>;
 
 declare const isGridTrackProperty: (cssProperty: string) => boolean;
@@ -364,6 +375,10 @@ declare const UnknownStyleStateError: {
     isError(error: unknown): error is Error;
 };
 
+declare function useCanvasDocument(): Document | null | undefined;
+
+declare function useEscapeOnCanvas(canvasDocument: Document | null | undefined, onEscape: () => void): void;
+
 declare function doAfterRender(elementIds: string[], callback: (elementIds: string[]) => void): void;
 
-export { type AnyTransformer, BREAKPOINTS_SCHEMA_URI, type BackboneModel, type BackboneModelConstructor, type ContextMenuAction, type ContextMenuEventData, type CreateNestedTemplatedElementTypeOptions, type CreateTemplatedElementTypeOptions, DOCUMENT_STRUCTURE_URI, type ElementModel, ElementType, ElementView, GLOBAL_STYLES_IMPORTED_EVENT, type ImportedGlobalStylesPayload, type LegacyWindow, type NamespacedRenderContext, type NestedTemplatedElementConfig, type PropsResolver, type RenderContext, type ReplacementSettings, STYLE_SCHEMA_URI, TemplatedElementView, type TransformerOptions, UnknownStyleStateError, UnknownStyleTypeError, WIDGET_SCHEMA_URI, canBeNestedTemplated, createNestedTemplatedElementType, createNestedTemplatedElementView, createPropsResolver, createTemplatedElementView, createTransformer, createTransformersRegistry, doAfterRender, endDragElementFromPanel, formatGridTrackRepeat, init, isAtomicWidget, isGridTrackProperty, registerElementType, registerModelExtensions, settingsTransformersRegistry, startDragElementFromPanel, styleTransformersRegistry, stylesInheritanceTransformersRegistry };
+export { type AnyTransformer, BREAKPOINTS_SCHEMA_URI, type BackboneModel, type BackboneModelConstructor, type ContextMenuAction, type ContextMenuEventData, type CreateNestedTemplatedElementTypeOptions, type CreateTemplatedElementTypeOptions, DOCUMENT_STRUCTURE_URI, type ElementModel, ElementType, ElementView, GLOBAL_STYLES_IMPORTED_EVENT, type ImportedGlobalStylesPayload, type LegacyWindow, type NamespacedRenderContext, type NestedTemplatedElementConfig, type PropsResolver, type RenderContext, type ReplacementSettings, STYLE_SCHEMA_URI, SpotlightBackdrop, TemplatedElementView, type TransformerOptions, UnknownStyleStateError, UnknownStyleTypeError, WIDGET_SCHEMA_URI, canBeNestedTemplated, createNestedTemplatedElementType, createNestedTemplatedElementView, createPropsResolver, createTemplatedElementView, createTransformer, createTransformersRegistry, doAfterRender, endDragElementFromPanel, formatGridTrackRepeat, init, isAtomicWidget, isGridTrackProperty, registerElementType, registerModelExtensions, settingsTransformersRegistry, startDragElementFromPanel, styleTransformersRegistry, stylesInheritanceTransformersRegistry, useCanvasDocument, useEscapeOnCanvas, waitForChildrenToComplete };

package/dist/index.d.ts

@@ -4,6 +4,7 @@ import { Root } from 'react-dom/client';
 import * as _elementor_editor_props from '@elementor/editor-props';
 import { Props, PropValue, PropType, PropTypeKey, PropsSchema, AnyTransformable } from '@elementor/editor-props';
 import { StyleVariables, StyleDefinitionsMap, StyleDefinitionID, StyleDefinitionState } from '@elementor/editor-styles';
+import * as React$1 from 'react';
 import * as _elementor_utils from '@elementor/utils';
 
 declare const BREAKPOINTS_SCHEMA_URI = "elementor://breakpoints/list";
@@ -292,6 +293,8 @@ type ResolvedProps = Record<string, unknown>;
 type PropsResolver = ReturnType<typeof createPropsResolver>;
 declare function createPropsResolver({ transformers, schema: initialSchema, onPropResolve }: CreatePropResolverArgs): ({ props, schema, signal, renderContext }: ResolveArgs) => Promise<ResolvedProps>;
 
+declare function waitForChildrenToComplete(view: Pick<ElementView, 'children'>): Promise<void>;
+
 declare const settingsTransformersRegistry: {
     register(type: _elementor_editor_props.PropTypeKey, transformer: AnyTransformer): /*elided*/ any;
     registerFallback(transformer: AnyTransformer): /*elided*/ any;
@@ -326,6 +329,14 @@ type ImportedGlobalStylesPayload = {
 
 declare const DOCUMENT_STRUCTURE_URI = "elementor://document/structure";
 
+type SpotlightBackdropProps = {
+    canvas: Document;
+    element: HTMLElement | null;
+    onExit: () => void;
+    ariaLabel: string;
+};
+declare function SpotlightBackdrop({ canvas, element, onExit, ariaLabel }: SpotlightBackdropProps): React$1.JSX.Element;
+
 declare function createTransformer<TValue = never>(cb: TValue extends AnyTransformable ? 'Transformable values are invalid, use the actual value instead.' : UnbrandedTransformer<TValue>): Transformer<NoInfer<TValue>>;
 
 declare const isGridTrackProperty: (cssProperty: string) => boolean;
@@ -364,6 +375,10 @@ declare const UnknownStyleStateError: {
     isError(error: unknown): error is Error;
 };
 
+declare function useCanvasDocument(): Document | null | undefined;
+
+declare function useEscapeOnCanvas(canvasDocument: Document | null | undefined, onEscape: () => void): void;
+
 declare function doAfterRender(elementIds: string[], callback: (elementIds: string[]) => void): void;
 
-export { type AnyTransformer, BREAKPOINTS_SCHEMA_URI, type BackboneModel, type BackboneModelConstructor, type ContextMenuAction, type ContextMenuEventData, type CreateNestedTemplatedElementTypeOptions, type CreateTemplatedElementTypeOptions, DOCUMENT_STRUCTURE_URI, type ElementModel, ElementType, ElementView, GLOBAL_STYLES_IMPORTED_EVENT, type ImportedGlobalStylesPayload, type LegacyWindow, type NamespacedRenderContext, type NestedTemplatedElementConfig, type PropsResolver, type RenderContext, type ReplacementSettings, STYLE_SCHEMA_URI, TemplatedElementView, type TransformerOptions, UnknownStyleStateError, UnknownStyleTypeError, WIDGET_SCHEMA_URI, canBeNestedTemplated, createNestedTemplatedElementType, createNestedTemplatedElementView, createPropsResolver, createTemplatedElementView, createTransformer, createTransformersRegistry, doAfterRender, endDragElementFromPanel, formatGridTrackRepeat, init, isAtomicWidget, isGridTrackProperty, registerElementType, registerModelExtensions, settingsTransformersRegistry, startDragElementFromPanel, styleTransformersRegistry, stylesInheritanceTransformersRegistry };
+export { type AnyTransformer, BREAKPOINTS_SCHEMA_URI, type BackboneModel, type BackboneModelConstructor, type ContextMenuAction, type ContextMenuEventData, type CreateNestedTemplatedElementTypeOptions, type CreateTemplatedElementTypeOptions, DOCUMENT_STRUCTURE_URI, type ElementModel, ElementType, ElementView, GLOBAL_STYLES_IMPORTED_EVENT, type ImportedGlobalStylesPayload, type LegacyWindow, type NamespacedRenderContext, type NestedTemplatedElementConfig, type PropsResolver, type RenderContext, type ReplacementSettings, STYLE_SCHEMA_URI, SpotlightBackdrop, TemplatedElementView, type TransformerOptions, UnknownStyleStateError, UnknownStyleTypeError, WIDGET_SCHEMA_URI, canBeNestedTemplated, createNestedTemplatedElementType, createNestedTemplatedElementView, createPropsResolver, createTemplatedElementView, createTransformer, createTransformersRegistry, doAfterRender, endDragElementFromPanel, formatGridTrackRepeat, init, isAtomicWidget, isGridTrackProperty, registerElementType, registerModelExtensions, settingsTransformersRegistry, startDragElementFromPanel, styleTransformersRegistry, stylesInheritanceTransformersRegistry, useCanvasDocument, useEscapeOnCanvas, waitForChildrenToComplete };

package/dist/index.js

@@ -34,6 +34,7 @@ __export(index_exports, {
   DOCUMENT_STRUCTURE_URI: () => DOCUMENT_STRUCTURE_URI,
   GLOBAL_STYLES_IMPORTED_EVENT: () => GLOBAL_STYLES_IMPORTED_EVENT,
   STYLE_SCHEMA_URI: () => STYLE_SCHEMA_URI,
+  SpotlightBackdrop: () => SpotlightBackdrop,
   UnknownStyleStateError: () => UnknownStyleStateError,
   UnknownStyleTypeError: () => UnknownStyleTypeError,
   WIDGET_SCHEMA_URI: () => WIDGET_SCHEMA_URI,
@@ -55,7 +56,10 @@ __export(index_exports, {
   settingsTransformersRegistry: () => settingsTransformersRegistry,
   startDragElementFromPanel: () => startDragElementFromPanel,
   styleTransformersRegistry: () => styleTransformersRegistry,
-  stylesInheritanceTransformersRegistry: () => stylesInheritanceTransformersRegistry
+  stylesInheritanceTransformersRegistry: () => stylesInheritanceTransformersRegistry,
+  useCanvasDocument: () => useCanvasDocument,
+  useEscapeOnCanvas: () => useEscapeOnCanvas,
+  waitForChildrenToComplete: () => waitForChildrenToComplete
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -5672,6 +5676,137 @@ var getLegacyPanelElementView = ({ settings, ...rest }) => {
 // src/sync/global-styles-imported-event.ts
 var GLOBAL_STYLES_IMPORTED_EVENT = "elementor/global-styles/imported";
 
+// src/components/spotlight-backdrop.tsx
+var React7 = __toESM(require("react"));
+
+// src/hooks/use-element-rect.ts
+var import_react14 = require("react");
+var import_utils6 = require("@elementor/utils");
+function useElementRect(element) {
+  const [rect, setRect] = (0, import_react14.useState)(new DOMRect(0, 0, 0, 0));
+  const onChange = (0, import_utils6.throttle)(
+    () => {
+      setRect(element?.getBoundingClientRect() ?? new DOMRect(0, 0, 0, 0));
+    },
+    20,
+    true
+  );
+  useScrollListener({ element, onChange });
+  useResizeListener({ element, onChange });
+  useMutationsListener({ element, onChange });
+  (0, import_react14.useEffect)(
+    () => () => {
+      onChange.cancel();
+    },
+    [onChange]
+  );
+  return rect;
+}
+function useScrollListener({ element, onChange }) {
+  (0, import_react14.useEffect)(() => {
+    if (!element) {
+      return;
+    }
+    const win = element.ownerDocument?.defaultView;
+    win?.addEventListener("scroll", onChange, { passive: true });
+    return () => {
+      win?.removeEventListener("scroll", onChange);
+    };
+  }, [element, onChange]);
+}
+function useResizeListener({ element, onChange }) {
+  (0, import_react14.useEffect)(() => {
+    if (!element) {
+      return;
+    }
+    const resizeObserver = new ResizeObserver(onChange);
+    resizeObserver.observe(element);
+    const win = element.ownerDocument?.defaultView;
+    win?.addEventListener("resize", onChange, { passive: true });
+    return () => {
+      resizeObserver.disconnect();
+      win?.removeEventListener("resize", onChange);
+    };
+  }, [element, onChange]);
+}
+function useMutationsListener({ element, onChange }) {
+  (0, import_react14.useEffect)(() => {
+    if (!element) {
+      return;
+    }
+    const mutationObserver = new MutationObserver(onChange);
+    mutationObserver.observe(element, { childList: true, subtree: true });
+    return () => {
+      mutationObserver.disconnect();
+    };
+  }, [element, onChange]);
+}
+
+// src/components/spotlight-backdrop.tsx
+function SpotlightBackdrop({ canvas, element, onExit, ariaLabel }) {
+  const rect = useElementRect(element);
+  const clipPath = element ? getRectClipPath(rect, canvas.defaultView) : void 0;
+  const backdropStyle = {
+    position: "fixed",
+    top: 0,
+    left: 0,
+    width: "100vw",
+    height: "100vh",
+    backgroundColor: "rgba(0, 0, 0, 0.5)",
+    zIndex: 999,
+    pointerEvents: "painted",
+    cursor: "pointer",
+    clipPath
+  };
+  const handleKeyDown = (event) => {
+    if (event.key === "Enter" || event.key === " ") {
+      event.preventDefault();
+      onExit();
+    }
+  };
+  return /* @__PURE__ */ React7.createElement(
+    "div",
+    {
+      style: backdropStyle,
+      onClick: onExit,
+      onKeyDown: handleKeyDown,
+      role: "button",
+      tabIndex: 0,
+      "aria-label": ariaLabel
+    }
+  );
+}
+function getRectClipPath(rect, viewport) {
+  const { x, y, width, height } = rect;
+  const { innerWidth: vw, innerHeight: vh } = viewport;
+  return `path(evenodd, 'M 0 0 L ${vw} 0 L ${vw} ${vh} L 0 ${vh} Z M ${x} ${y} L ${x + width} ${y} L ${x + width} ${y + height} L ${x} ${y + height} L ${x} ${y} Z')`;
+}
+
+// src/hooks/use-canvas-document.ts
+var import_editor_v1_adapters25 = require("@elementor/editor-v1-adapters");
+function useCanvasDocument() {
+  return (0, import_editor_v1_adapters25.__privateUseListenTo)((0, import_editor_v1_adapters25.commandEndEvent)("editor/documents/attach-preview"), () => (0, import_editor_v1_adapters25.getCanvasIframeDocument)());
+}
+
+// src/hooks/use-escape-on-canvas.ts
+var import_react15 = require("react");
+function useEscapeOnCanvas(canvasDocument, onEscape) {
+  (0, import_react15.useEffect)(() => {
+    if (!canvasDocument) {
+      return;
+    }
+    const handleEsc = (event) => {
+      if (event.key === "Escape") {
+        onEscape();
+      }
+    };
+    canvasDocument.body.addEventListener("keydown", handleEsc);
+    return () => {
+      canvasDocument.body.removeEventListener("keydown", handleEsc);
+    };
+  }, [canvasDocument, onEscape]);
+}
+
 // src/utils/after-render.ts
 var import_editor_elements22 = require("@elementor/editor-elements");
 function doAfterRender(elementIds, callback) {
@@ -5697,6 +5832,7 @@ function hasDoAfterRender(view) {
   DOCUMENT_STRUCTURE_URI,
   GLOBAL_STYLES_IMPORTED_EVENT,
   STYLE_SCHEMA_URI,
+  SpotlightBackdrop,
   UnknownStyleStateError,
   UnknownStyleTypeError,
   WIDGET_SCHEMA_URI,
@@ -5718,6 +5854,9 @@ function hasDoAfterRender(view) {
   settingsTransformersRegistry,
   startDragElementFromPanel,
   styleTransformersRegistry,
-  stylesInheritanceTransformersRegistry
+  stylesInheritanceTransformersRegistry,
+  useCanvasDocument,
+  useEscapeOnCanvas,
+  waitForChildrenToComplete
 });
 //# sourceMappingURL=index.js.map

package/dist/index.mjs

@@ -5682,6 +5682,141 @@ var getLegacyPanelElementView = ({ settings, ...rest }) => {
 // src/sync/global-styles-imported-event.ts
 var GLOBAL_STYLES_IMPORTED_EVENT = "elementor/global-styles/imported";
 
+// src/components/spotlight-backdrop.tsx
+import * as React7 from "react";
+
+// src/hooks/use-element-rect.ts
+import { useEffect as useEffect9, useState as useState6 } from "react";
+import { throttle } from "@elementor/utils";
+function useElementRect(element) {
+  const [rect, setRect] = useState6(new DOMRect(0, 0, 0, 0));
+  const onChange = throttle(
+    () => {
+      setRect(element?.getBoundingClientRect() ?? new DOMRect(0, 0, 0, 0));
+    },
+    20,
+    true
+  );
+  useScrollListener({ element, onChange });
+  useResizeListener({ element, onChange });
+  useMutationsListener({ element, onChange });
+  useEffect9(
+    () => () => {
+      onChange.cancel();
+    },
+    [onChange]
+  );
+  return rect;
+}
+function useScrollListener({ element, onChange }) {
+  useEffect9(() => {
+    if (!element) {
+      return;
+    }
+    const win = element.ownerDocument?.defaultView;
+    win?.addEventListener("scroll", onChange, { passive: true });
+    return () => {
+      win?.removeEventListener("scroll", onChange);
+    };
+  }, [element, onChange]);
+}
+function useResizeListener({ element, onChange }) {
+  useEffect9(() => {
+    if (!element) {
+      return;
+    }
+    const resizeObserver = new ResizeObserver(onChange);
+    resizeObserver.observe(element);
+    const win = element.ownerDocument?.defaultView;
+    win?.addEventListener("resize", onChange, { passive: true });
+    return () => {
+      resizeObserver.disconnect();
+      win?.removeEventListener("resize", onChange);
+    };
+  }, [element, onChange]);
+}
+function useMutationsListener({ element, onChange }) {
+  useEffect9(() => {
+    if (!element) {
+      return;
+    }
+    const mutationObserver = new MutationObserver(onChange);
+    mutationObserver.observe(element, { childList: true, subtree: true });
+    return () => {
+      mutationObserver.disconnect();
+    };
+  }, [element, onChange]);
+}
+
+// src/components/spotlight-backdrop.tsx
+function SpotlightBackdrop({ canvas, element, onExit, ariaLabel }) {
+  const rect = useElementRect(element);
+  const clipPath = element ? getRectClipPath(rect, canvas.defaultView) : void 0;
+  const backdropStyle = {
+    position: "fixed",
+    top: 0,
+    left: 0,
+    width: "100vw",
+    height: "100vh",
+    backgroundColor: "rgba(0, 0, 0, 0.5)",
+    zIndex: 999,
+    pointerEvents: "painted",
+    cursor: "pointer",
+    clipPath
+  };
+  const handleKeyDown = (event) => {
+    if (event.key === "Enter" || event.key === " ") {
+      event.preventDefault();
+      onExit();
+    }
+  };
+  return /* @__PURE__ */ React7.createElement(
+    "div",
+    {
+      style: backdropStyle,
+      onClick: onExit,
+      onKeyDown: handleKeyDown,
+      role: "button",
+      tabIndex: 0,
+      "aria-label": ariaLabel
+    }
+  );
+}
+function getRectClipPath(rect, viewport) {
+  const { x, y, width, height } = rect;
+  const { innerWidth: vw, innerHeight: vh } = viewport;
+  return `path(evenodd, 'M 0 0 L ${vw} 0 L ${vw} ${vh} L 0 ${vh} Z M ${x} ${y} L ${x + width} ${y} L ${x + width} ${y + height} L ${x} ${y + height} L ${x} ${y} Z')`;
+}
+
+// src/hooks/use-canvas-document.ts
+import {
+  __privateUseListenTo as useListenTo5,
+  commandEndEvent as commandEndEvent8,
+  getCanvasIframeDocument as getCanvasIframeDocument5
+} from "@elementor/editor-v1-adapters";
+function useCanvasDocument() {
+  return useListenTo5(commandEndEvent8("editor/documents/attach-preview"), () => getCanvasIframeDocument5());
+}
+
+// src/hooks/use-escape-on-canvas.ts
+import { useEffect as useEffect10 } from "react";
+function useEscapeOnCanvas(canvasDocument, onEscape) {
+  useEffect10(() => {
+    if (!canvasDocument) {
+      return;
+    }
+    const handleEsc = (event) => {
+      if (event.key === "Escape") {
+        onEscape();
+      }
+    };
+    canvasDocument.body.addEventListener("keydown", handleEsc);
+    return () => {
+      canvasDocument.body.removeEventListener("keydown", handleEsc);
+    };
+  }, [canvasDocument, onEscape]);
+}
+
 // src/utils/after-render.ts
 import { getContainer as getContainer8 } from "@elementor/editor-elements";
 function doAfterRender(elementIds, callback) {
@@ -5706,6 +5841,7 @@ export {
   DOCUMENT_STRUCTURE_URI,
   GLOBAL_STYLES_IMPORTED_EVENT,
   STYLE_SCHEMA_URI,
+  SpotlightBackdrop,
   UnknownStyleStateError,
   UnknownStyleTypeError,
   WIDGET_SCHEMA_URI,
@@ -5727,6 +5863,9 @@ export {
   settingsTransformersRegistry,
   startDragElementFromPanel,
   styleTransformersRegistry,
-  stylesInheritanceTransformersRegistry
+  stylesInheritanceTransformersRegistry,
+  useCanvasDocument,
+  useEscapeOnCanvas,
+  waitForChildrenToComplete
 };
 //# sourceMappingURL=index.mjs.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@elementor/editor-canvas",
   "description": "Elementor Editor Canvas",
-  "version": "4.2.0-883",
+  "version": "4.2.0-885",
   "private": false,
   "author": "Elementor Team",
   "homepage": "https://elementor.com/",
@@ -37,25 +37,25 @@
     "react-dom": "^18.3.1"
   },
   "dependencies": {
-    "@elementor/editor": "4.2.0-883",
+    "@elementor/editor": "4.2.0-885",
     "dompurify": "^3.2.6",
-    "@elementor/editor-controls": "4.2.0-883",
-    "@elementor/editor-documents": "4.2.0-883",
-    "@elementor/editor-elements": "4.2.0-883",
-    "@elementor/editor-interactions": "4.2.0-883",
-    "@elementor/editor-mcp": "4.2.0-883",
-    "@elementor/editor-notifications": "4.2.0-883",
-    "@elementor/editor-props": "4.2.0-883",
-    "@elementor/editor-responsive": "4.2.0-883",
-    "@elementor/editor-styles": "4.2.0-883",
-    "@elementor/editor-styles-repository": "4.2.0-883",
-    "@elementor/editor-ui": "4.2.0-883",
-    "@elementor/editor-v1-adapters": "4.2.0-883",
-    "@elementor/schema": "4.2.0-883",
-    "@elementor/twing": "4.2.0-883",
+    "@elementor/editor-controls": "4.2.0-885",
+    "@elementor/editor-documents": "4.2.0-885",
+    "@elementor/editor-elements": "4.2.0-885",
+    "@elementor/editor-interactions": "4.2.0-885",
+    "@elementor/editor-mcp": "4.2.0-885",
+    "@elementor/editor-notifications": "4.2.0-885",
+    "@elementor/editor-props": "4.2.0-885",
+    "@elementor/editor-responsive": "4.2.0-885",
+    "@elementor/editor-styles": "4.2.0-885",
+    "@elementor/editor-styles-repository": "4.2.0-885",
+    "@elementor/editor-ui": "4.2.0-885",
+    "@elementor/editor-v1-adapters": "4.2.0-885",
+    "@elementor/schema": "4.2.0-885",
+    "@elementor/twing": "4.2.0-885",
     "@elementor/ui": "1.37.5",
-    "@elementor/utils": "4.2.0-883",
-    "@elementor/wp-media": "4.2.0-883",
+    "@elementor/utils": "4.2.0-885",
+    "@elementor/wp-media": "4.2.0-885",
     "@floating-ui/react": "^0.27.5",
     "@wordpress/i18n": "^5.13.0"
   },

package/src/components/__tests__/spotlight-backdrop.test.tsx

@@ -0,0 +1,53 @@
+import * as React from 'react';
+import { renderWithTheme } from 'test-utils';
+import { fireEvent, screen } from '@testing-library/react';
+
+import { SpotlightBackdrop } from '../spotlight-backdrop';
+
+describe( '<SpotlightBackdrop />', () => {
+	it( 'renders a button-role backdrop with the given aria label', () => {
+		const onExit = jest.fn();
+
+		renderWithTheme(
+			<SpotlightBackdrop canvas={ document } element={ null } onExit={ onExit } ariaLabel="Exit" />
+		);
+
+		expect( screen.getByRole( 'button', { name: 'Exit' } ) ).toBeInTheDocument();
+	} );
+
+	it( 'calls onExit when clicking the backdrop', () => {
+		const onExit = jest.fn();
+		renderWithTheme(
+			<SpotlightBackdrop canvas={ document } element={ null } onExit={ onExit } ariaLabel="Exit" />
+		);
+
+		fireEvent.click( screen.getByRole( 'button', { name: 'Exit' } ) );
+
+		expect( onExit ).toHaveBeenCalledTimes( 1 );
+	} );
+
+	it( 'calls onExit when pressing Enter or Space on the backdrop', () => {
+		const onExit = jest.fn();
+		renderWithTheme(
+			<SpotlightBackdrop canvas={ document } element={ null } onExit={ onExit } ariaLabel="Exit" />
+		);
+		const backdrop = screen.getByRole( 'button', { name: 'Exit' } );
+
+		fireEvent.keyDown( backdrop, { key: 'Enter' } );
+		fireEvent.keyDown( backdrop, { key: ' ' } );
+
+		expect( onExit ).toHaveBeenCalledTimes( 2 );
+	} );
+
+	it( 'does not apply a clip-path when no element is provided', () => {
+		const onExit = jest.fn();
+
+		renderWithTheme(
+			<SpotlightBackdrop canvas={ document } element={ null } onExit={ onExit } ariaLabel="Exit" />
+		);
+
+		expect( screen.getByRole( 'button', { name: 'Exit' } ) ).not.toHaveStyle( {
+			clipPath: expect.stringContaining( 'path' ),
+		} );
+	} );
+} );

package/src/components/spotlight-backdrop.tsx

@@ -0,0 +1,56 @@
+import * as React from 'react';
+import { type CSSProperties } from 'react';
+
+import { useElementRect } from '../hooks/use-element-rect';
+
+type SpotlightBackdropProps = {
+	canvas: Document;
+	element: HTMLElement | null;
+	onExit: () => void;
+	ariaLabel: string;
+};
+
+export function SpotlightBackdrop( { canvas, element, onExit, ariaLabel }: SpotlightBackdropProps ) {
+	const rect = useElementRect( element );
+	const clipPath = element ? getRectClipPath( rect, canvas.defaultView as Window ) : undefined;
+
+	const backdropStyle: CSSProperties = {
+		position: 'fixed',
+		top: 0,
+		left: 0,
+		width: '100vw',
+		height: '100vh',
+		backgroundColor: 'rgba(0, 0, 0, 0.5)',
+		zIndex: 999,
+		pointerEvents: 'painted',
+		cursor: 'pointer',
+		clipPath,
+	};
+
+	const handleKeyDown = ( event: React.KeyboardEvent ) => {
+		if ( event.key === 'Enter' || event.key === ' ' ) {
+			event.preventDefault();
+			onExit();
+		}
+	};
+
+	return (
+		<div
+			style={ backdropStyle }
+			onClick={ onExit }
+			onKeyDown={ handleKeyDown }
+			role="button"
+			tabIndex={ 0 }
+			aria-label={ ariaLabel }
+		/>
+	);
+}
+
+function getRectClipPath( rect: DOMRect, viewport: Window ) {
+	const { x, y, width, height } = rect;
+	const { innerWidth: vw, innerHeight: vh } = viewport;
+
+	return `path(evenodd, 'M 0 0 L ${ vw } 0 L ${ vw } ${ vh } L 0 ${ vh } Z M ${ x } ${ y } L ${
+		x + width
+	} ${ y } L ${ x + width } ${ y + height } L ${ x } ${ y + height } L ${ x } ${ y } Z')`;
+}

package/src/hooks/use-canvas-document.ts

@@ -0,0 +1,9 @@
+import {
+	__privateUseListenTo as useListenTo,
+	commandEndEvent,
+	getCanvasIframeDocument,
+} from '@elementor/editor-v1-adapters';
+
+export function useCanvasDocument() {
+	return useListenTo( commandEndEvent( 'editor/documents/attach-preview' ), () => getCanvasIframeDocument() );
+}

package/src/hooks/use-element-rect.ts

@@ -0,0 +1,81 @@
+import { useEffect, useState } from 'react';
+import { throttle } from '@elementor/utils';
+
+export function useElementRect( element: HTMLElement | null ) {
+	const [ rect, setRect ] = useState< DOMRect >( new DOMRect( 0, 0, 0, 0 ) );
+
+	const onChange = throttle(
+		() => {
+			setRect( element?.getBoundingClientRect() ?? new DOMRect( 0, 0, 0, 0 ) );
+		},
+		20,
+		true
+	);
+
+	useScrollListener( { element, onChange } );
+	useResizeListener( { element, onChange } );
+	useMutationsListener( { element, onChange } );
+
+	useEffect(
+		() => () => {
+			onChange.cancel();
+		},
+		[ onChange ]
+	);
+
+	return rect;
+}
+
+type ListenerProps = {
+	element: HTMLElement | null;
+	onChange: () => void;
+};
+
+function useScrollListener( { element, onChange }: ListenerProps ) {
+	useEffect( () => {
+		if ( ! element ) {
+			return;
+		}
+
+		const win = element.ownerDocument?.defaultView;
+		win?.addEventListener( 'scroll', onChange, { passive: true } );
+
+		return () => {
+			win?.removeEventListener( 'scroll', onChange );
+		};
+	}, [ element, onChange ] );
+}
+
+function useResizeListener( { element, onChange }: ListenerProps ) {
+	useEffect( () => {
+		if ( ! element ) {
+			return;
+		}
+
+		const resizeObserver = new ResizeObserver( onChange );
+		resizeObserver.observe( element );
+
+		const win = element.ownerDocument?.defaultView;
+		win?.addEventListener( 'resize', onChange, { passive: true } );
+
+		return () => {
+			resizeObserver.disconnect();
+			win?.removeEventListener( 'resize', onChange );
+		};
+	}, [ element, onChange ] );
+}
+
+function useMutationsListener( { element, onChange }: ListenerProps ) {
+	useEffect( () => {
+		if ( ! element ) {
+			return;
+		}
+
+		const mutationObserver = new MutationObserver( onChange );
+		mutationObserver.observe( element, { childList: true, subtree: true } );
+
+		return () => {
+			mutationObserver.disconnect();
+		};
+	}, [ element, onChange ] );
+}

package/src/hooks/use-escape-on-canvas.ts

@@ -0,0 +1,21 @@
+import { useEffect } from 'react';
+
+export function useEscapeOnCanvas( canvasDocument: Document | null | undefined, onEscape: () => void ) {
+	useEffect( () => {
+		if ( ! canvasDocument ) {
+			return;
+		}
+
+		const handleEsc = ( event: KeyboardEvent ) => {
+			if ( event.key === 'Escape' ) {
+				onEscape();
+			}
+		};
+
+		canvasDocument.body.addEventListener( 'keydown', handleEsc );
+
+		return () => {
+			canvasDocument.body.removeEventListener( 'keydown', handleEsc );
+		};
+	}, [ canvasDocument, onEscape ] );
+}

package/src/index.ts

@@ -16,6 +16,7 @@ export {
 	type NestedTemplatedElementConfig,
 } from './legacy/create-nested-templated-element-type';
 export { registerElementType, registerModelExtensions } from './legacy/init-legacy-views';
+export { waitForChildrenToComplete } from './legacy/twig-rendering-utils';
 export * from './legacy/types';
 export { createPropsResolver, type PropsResolver } from './renderers/create-props-resolver';
 export { settingsTransformersRegistry } from './settings-transformers-registry';
@@ -25,6 +26,7 @@ export { GLOBAL_STYLES_IMPORTED_EVENT, type ImportedGlobalStylesPayload } from '
 export { DOCUMENT_STRUCTURE_URI } from './mcp/resources/document-structure-resource';
 export { WIDGET_SCHEMA_URI } from './mcp/resources/widgets-schema-resource';
 export * from './legacy/types';
+export { SpotlightBackdrop } from './components/spotlight-backdrop';
 export { createTransformer } from './transformers/create-transformer';
 export { formatGridTrackRepeat, isGridTrackProperty } from './transformers/styles/grid-track-renderer';
 export {
@@ -33,4 +35,6 @@ export {
 } from './transformers/create-transformers-registry';
 export { type AnyTransformer, type TransformerOptions } from './transformers/types';
 export { UnknownStyleTypeError, UnknownStyleStateError } from './renderers/errors';
+export { useCanvasDocument } from './hooks/use-canvas-document';
+export { useEscapeOnCanvas } from './hooks/use-escape-on-canvas';
 export { doAfterRender } from './utils/after-render';