@elementor/editor-canvas 4.3.3 → 4.3.5

package/src/legacy/__tests__/create-pending-element.test.ts

@@ -0,0 +1,128 @@
+import { createMockElement } from 'test-utils';
+import { addModelToParent, findModelInDocument, type V1ElementModelProps } from '@elementor/editor-elements';
+
+import { createPendingElement } from '../create-pending-element';
+import { type ElementView } from '../types';
+
+jest.mock( '@elementor/editor-elements', () => ( {
+	...jest.requireActual( '@elementor/editor-elements' ),
+	addModelToParent: jest.fn(),
+	findModelInDocument: jest.fn(),
+	getContainer: jest.fn(),
+} ) );
+
+const mockAddModelToParent = jest.mocked( addModelToParent );
+const mockFindModelInDocument = jest.mocked( findModelInDocument );
+
+describe( 'createPendingElement', () => {
+	beforeEach( () => {
+		(
+			window as typeof window & {
+				elementorCommon?: { helpers?: { getUniqueId?: jest.Mock } };
+			}
+		 ).elementorCommon = {
+			helpers: {
+				getUniqueId: jest
+					.fn()
+					.mockReturnValueOnce( 'cloned-parent-id' )
+					.mockReturnValueOnce( 'cloned-child-id' ),
+			},
+		};
+
+		mockAddModelToParent.mockClear();
+		mockFindModelInDocument.mockClear();
+		mockAddModelToParent.mockReturnValue( true );
+		mockFindModelInDocument.mockReturnValue( createMockElement( {} ) as never );
+	} );
+
+	afterEach( () => {
+		delete ( window as typeof window & { elementorCommon?: unknown } ).elementorCommon;
+	} );
+
+	it( 'regenerates ids before pending clone insertion', () => {
+		// Arrange.
+		const wrapperView = {
+			getContainer: () => ( { id: 'parent-id' } ),
+			once: jest.fn(),
+			model: {
+				trigger: jest.fn(),
+			},
+		} as unknown as ElementView;
+
+		const source = {
+			id: 'original-parent-id',
+			elType: 'container',
+			settings: { _element_id: 'original-parent-element-id' },
+			elements: [
+				{
+					id: 'original-child-id',
+					elType: 'widget',
+					widgetType: 'button',
+					settings: { _element_id: 'original-child-element-id' },
+					elements: [],
+				},
+			],
+		} as unknown as Partial< V1ElementModelProps >;
+
+		// Act.
+		const pendingElement = createPendingElement( wrapperView, source, { clone: true } );
+
+		// Assert.
+		expect( pendingElement?.getContainer().id ).toBe( 'cloned-parent-id' );
+		expect( mockAddModelToParent ).toHaveBeenCalledWith(
+			'parent-id',
+			expect.objectContaining( {
+				id: 'cloned-parent-id',
+				settings: expect.objectContaining( { _element_id: '' } ),
+				elements: [
+					expect.objectContaining( {
+						id: 'cloned-child-id',
+						settings: expect.objectContaining( { _element_id: '' } ),
+					} ),
+				],
+			} ),
+			expect.objectContaining( {
+				clone: false,
+			} )
+		);
+		expect( mockFindModelInDocument ).toHaveBeenCalledWith( 'cloned-parent-id' );
+	} );
+
+	it( 'preserves the source id when clone is false', () => {
+		// Arrange.
+		const wrapperView = {
+			getContainer: () => ( { id: 'parent-id' } ),
+			once: jest.fn(),
+			model: {
+				trigger: jest.fn(),
+			},
+		} as unknown as ElementView;
+
+		const source = {
+			id: 'original-parent-id',
+			elType: 'widget',
+			widgetType: 'button',
+			settings: { _element_id: 'original-parent-element-id' },
+			elements: [],
+		};
+
+		// Act.
+		const pendingElement = createPendingElement( wrapperView, source, { clone: false } );
+
+		// Assert.
+		expect( pendingElement?.getContainer().id ).toBe( 'original-parent-id' );
+		expect( mockAddModelToParent ).toHaveBeenCalledWith(
+			'parent-id',
+			expect.objectContaining( {
+				id: 'original-parent-id',
+				settings: expect.objectContaining( {
+					_element_id: 'original-parent-element-id',
+				} ),
+			} ),
+			expect.objectContaining( {
+				clone: false,
+			} )
+		);
+		expect( mockFindModelInDocument ).toHaveBeenCalledWith( 'original-parent-id' );
+	} );
+} );

package/src/legacy/__tests__/create-templated-element-type.test.ts

@@ -121,20 +121,7 @@ describe( 'createTemplatedElementView', () => {
 	} );
 
 	describe( 'render context', () => {
-		it( 'should inject computed tag into the twig render context', async () => {
-			// Arrange
-			const utils = createMockRenderer();
-			const ViewClass = createTemplatedElementView( {
-				type: MOCK_ELEMENT_TYPE,
-				renderer: utils,
-				element: {
-					...createMockElementConfig(),
-					twig_templates: {
-						main: '<{{ tag | e("html_tag") }}></{{ tag | e("html_tag") }}>',
-					},
-				},
-			} );
-
+		const createRenderableView = ( ViewClass: ReturnType< typeof createTemplatedElementView > ) => {
 			const view = new ViewClass() as unknown as ElementView & {
 				_abortController: AbortController;
 			};
@@ -159,12 +146,61 @@ describe( 'createTemplatedElementView', () => {
 			view._ensureViewIsIntact = jest.fn();
 			view.resetChildViewContainer = jest.fn();
 
+			return view;
+		};
+
+		it( 'should inject computed tag into the twig render context', async () => {
+			// Arrange
+			const utils = createMockRenderer();
+			const ViewClass = createTemplatedElementView( {
+				type: MOCK_ELEMENT_TYPE,
+				renderer: utils,
+				element: {
+					...createMockElementConfig(),
+					twig_templates: {
+						main: '<{{ tag | e("html_tag") }}></{{ tag | e("html_tag") }}>',
+					},
+				},
+			} );
+
+			const view = createRenderableView( ViewClass );
+
 			// Act
 			await view._renderTemplate();
 
 			// Assert
 			expect( utils.render ).toHaveBeenCalledWith( 'main', expect.objectContaining( { tag: 'div' } ) );
 		} );
+
+		it( 'should merge element template_context into the twig render context without overriding core keys', async () => {
+			// Arrange
+			const utils = createMockRenderer();
+			const ViewClass = createTemplatedElementView( {
+				type: MOCK_ELEMENT_TYPE,
+				renderer: utils,
+				element: {
+					...createMockElementConfig(),
+					template_context: {
+						provider: { key: 'google', api_key: 'test-key' },
+						id: 'should-not-override',
+					},
+				},
+			} );
+
+			const view = createRenderableView( ViewClass );
+
+			// Act
+			await view._renderTemplate();
+
+			// Assert
+			expect( utils.render ).toHaveBeenCalledWith(
+				'main',
+				expect.objectContaining( {
+					id: 'test-id',
+					provider: { key: 'google', api_key: 'test-key' },
+				} )
+			);
+		} );
 	} );
 } );
 

package/src/legacy/create-nested-templated-element-type.ts

@@ -71,15 +71,17 @@ export function createNestedTemplatedElementType( {
 	};
 }
 
-function buildEditorAttributes( model: ElementView[ 'model' ] ): string {
+export function buildEditorAttributes( model: ElementView[ 'model' ] ): string {
 	const id = model.get( 'id' );
 	const originId = model.get( 'originId' );
 	const cid = model.cid ?? '';
+	const isDecorative = model.get( 'editor_settings' )?.decorative === true;
 
 	const attrs: Record< string, string > = {
 		'data-model-cid': cid,
 		'data-interaction-id': originId ?? id,
 		'x-ignore': 'true',
+		...( isDecorative ? { 'data-e-decorative': 'true' } : {} ),
 	};
 
 	return Object.entries( attrs )
@@ -420,7 +422,7 @@ export function createNestedTemplatedElementView( {
 			this._doAfterRender( () => parentOpenEditingPanel.call( this, options ) );
 		},
 
-		addElement( data: Partial< V1ElementModelProps >, options?: { edit?: boolean; at?: number } ) {
+		addElement( data: Partial< V1ElementModelProps >, options?: { edit?: boolean; at?: number; clone?: boolean } ) {
 			if ( this.isRendered ) {
 				return parentAddElement.call( this, data, options );
 			}

package/src/legacy/create-pending-element.ts

@@ -1,5 +1,6 @@
 import {
 	addModelToParent,
+	cloneElementTree,
 	findModelInDocument,
 	generateElementId,
 	getContainer,
@@ -12,12 +13,12 @@ import { type ElementView } from './types';
 export function createPendingElement(
 	wrapperView: ElementView,
 	data: Partial< V1ElementModelProps >,
-	options: { edit?: boolean; at?: number } = {}
+	options: { edit?: boolean; at?: number; clone?: boolean } = {}
 ): { getContainer: () => V1Element } | undefined {
 	const parentContainer = wrapperView.getContainer();
-	const model: Partial< V1ElementModelProps > = { ...data };
+	const model: Partial< V1ElementModelProps > = options.clone ? cloneElementTree( data ) : { ...data };
 
-	if ( ! model.id ) {
+	if ( ! options.clone && ! model.id ) {
 		model.id = generateElementId();
 	}
 
@@ -25,13 +26,16 @@ export function createPendingElement(
 		model.elements = [];
 	}
 
-	const added = addModelToParent( parentContainer.id, model as V1ElementModelProps, options );
+	const added = addModelToParent( parentContainer.id, model as V1ElementModelProps, {
+		...options,
+		clone: false,
+	} );
 
 	if ( ! added ) {
 		return undefined;
 	}
 
-	const childId = model.id;
+	const childId = model.id as string;
 	const childModel = findModelInDocument( childId );
 
 	if ( ! childModel ) {

package/src/legacy/create-templated-element-type.ts

@@ -29,7 +29,7 @@ export type CreateTemplatedElementTypeOptions = {
 export type TemplatedElementConfig = Required<
 	Pick< V1ElementConfig, 'twig_templates' | 'twig_main_template' | 'atomic_props_schema' | 'base_styles_dictionary' >
 > &
-	Pick< V1ElementConfig, 'default_html_tag' | 'html_tag_follows_link' >;
+	Pick< V1ElementConfig, 'default_html_tag' | 'html_tag_follows_link' | 'template_context' >;
 
 export function createTemplatedElementType( {
 	type,
@@ -163,6 +163,7 @@ export function createTemplatedElementView( {
 					this._lastResolvedSettingsHash = settingsHash;
 
 					const context = {
+						...( element.template_context ?? {} ),
 						id: this.model.get( 'id' ),
 						interaction_id: this.getInteractionId(),
 						type,

package/src/mcp/canvas-mcp.ts

@@ -1,6 +1,7 @@
 import { type MCPRegistryEntry } from '@elementor/editor-mcp';
 import { Schema } from '@elementor/editor-props';
 
+import { isIconLibraryActive } from './icon-library-experiment';
 import { initAvailableWidgetsResource } from './resources/available-widgets-resource';
 import { initBestPracticesResource } from './resources/best-practices-resource';
 import { initBreakpointsResource } from './resources/breakpoints-resource';
@@ -11,6 +12,7 @@ import { initGeneralContextResource } from './resources/general-context-resource
 import { initSelectedElementResource } from './resources/selected-element-resource';
 import { initWidgetsSchemaResource } from './resources/widgets-schema-resource';
 import { initConfigureElementTool } from './tools/configure-element/tool';
+import { initFindIconsTool } from './tools/find-icons/tool';
 import { initGetPageStructureTool } from './tools/get-page-structure/tool';
 import { getDynamicTagNamesByCategories } from './utils/resolve-dynamic-tag';
 
@@ -28,6 +30,9 @@ export const initCanvasMcp = ( reg: MCPRegistryEntry ) => {
 	initGeneralContextResource( reg );
 	initBestPracticesResource( reg );
 	initConfigureElementTool( reg );
+	if ( isIconLibraryActive() ) {
+		initFindIconsTool( reg );
+	}
 	initGetPageStructureTool( reg );
 	initBreakpointsResource( reg );
 };

package/src/mcp/icon-library-experiment.ts

@@ -0,0 +1,5 @@
+import { isExperimentActive } from '@elementor/editor-v1-adapters';
+
+const ICON_LIBRARY_EXPERIMENT = 'e_svg_library';
+
+export const isIconLibraryActive = () => isExperimentActive( ICON_LIBRARY_EXPERIMENT );

package/src/mcp/tools/configure-element/prompt.ts

@@ -1,11 +1,52 @@
 import { toolPrompts } from '@elementor/editor-mcp';
 
+import { isIconLibraryActive } from '../../icon-library-experiment';
 import { DYNAMIC_TAGS_URI } from '../../resources/dynamic-tags-resource';
 import { WIDGET_SCHEMA_URI } from '../../resources/widgets-schema-resource';
 
+const ICONS_SECTION = `# Icons (the \`svg\` property on e-svg)
+The \`svg\` property accepts two variants. Prefer a library icon for iconography (carts, arrows, social marks, check marks) — it needs no upload and inherits \`color\` via \`currentColor\`. Use an uploaded file only for custom artwork such as a brand logo.
+
+Resolve the icon with the \`find-icons\` tool FIRST, then copy its \`value\` and \`library\` verbatim. Never assemble those strings yourself: Font Awesome renamed many icons between major versions (\`shopping-cart\` became \`cart-shopping\`), so a plausible guess renders nothing. \`find-icons\` matches on names, aliases, human search terms, and categories, so describe the intent — "add to cart" finds \`cart-shopping\`. It takes a batch of \`queries\`, so resolve every icon you need in one call.
+
+Library icon (note the nested PropValues — \`value\` and \`library\` are each a \`string\` PropValue):
+{ "$$type": "icon", "value": { "value": { "$$type": "string", "value": "fa-solid fa-cart-shopping" }, "library": { "$$type": "string", "value": "fa-solid" } } }
+
+Uploaded SVG file:
+{ "$$type": "svg-src", "value": { "id": { "$$type": "image-attachment-id", "value": 123 } } }
+
+Size and colour an e-svg through \`style\` (\`width\`, \`height\`, \`color\`), never through \`propertiesToChange\`.
+`;
+
+const ICON_EXAMPLE = `
+Setting a Font Awesome icon on an e-svg, after resolving it with \`find-icons\`:
+
+\`\`\`json
+{
+  propertiesToChange: {
+    svg: {
+      $$type: 'icon',
+      value: {
+        value: { $$type: 'string', value: 'fa-solid fa-cart-shopping' },
+        library: { $$type: 'string', value: 'fa-solid' }
+      }
+    }
+  },
+  style: {
+    'width': '1.25rem',
+    'height': '1.25rem',
+    'color': '#1a1a1a'
+  },
+  elementId: 'element-id',
+  elementType: 'e-svg'
+};
+\`\`\`
+`;
+
 export const CONFIGURE_ELEMENT_GUIDE_URI = 'elementor://canvas/tools/configure-element-guide';
 
 export const generatePrompt = () => {
+	const iconLibraryActive = isIconLibraryActive();
 	const configureElementToolPrompt = toolPrompts( 'configure-element' );
 
 	configureElementToolPrompt.description( `
@@ -64,7 +105,8 @@ Put the dynamic object EXACTLY at the node whose schema offers the "dynamic" var
 }
 Image example: { "$$type": "image", "value": { "src": { "$$type": "dynamic", "value": { "name": "<image tag>", "settings": { ... } } } } }
 Do NOT send "group" (it is resolved automatically). Use { "settings": {} } only when the tag has no settings.
-` );
+
+${ iconLibraryActive ? ICONS_SECTION : '' }` );
 
 	configureElementToolPrompt.parameter( 'elementId', 'The ID of the element to configure. MANDATORY.' );
 
@@ -107,6 +149,10 @@ Do NOT send "group" (it is resolved automatically). Use { "settings": {} } only
 \`\`\`
 ` );
 
+	if ( iconLibraryActive ) {
+		configureElementToolPrompt.example( ICON_EXAMPLE );
+	}
+
 	configureElementToolPrompt.instruction(
 		'The $$type property is MANDATORY for every value in propertiesToChange; it is not used in the style parameter (raw CSS only).'
 	);

package/src/mcp/tools/find-icons/__tests__/tool.test.ts

@@ -0,0 +1,143 @@
+import { httpService } from '@elementor/http-client';
+
+import { initFindIconsTool } from '../tool';
+
+jest.mock( '@elementor/http-client', () => ( {
+	httpService: jest.fn(),
+	AxiosError: class AxiosError extends Error {},
+} ) );
+
+const mockedHttpService = httpService as jest.MockedFunction< typeof httpService >;
+
+type ToolConfig = {
+	name: string;
+	description: string;
+	schema: Record< string, unknown >;
+	handler: ( input: Record< string, unknown > ) => Promise< Record< string, unknown > >;
+};
+
+const captureTool = (): ToolConfig => {
+	const addTool = jest.fn();
+	initFindIconsTool( { addTool } as never );
+	return addTool.mock.calls[ 0 ][ 0 ] as ToolConfig;
+};
+
+const serverResponse = {
+	results: [
+		{
+			query: 'add to cart',
+			matches: [
+				{
+					value: 'fa-solid fa-cart-plus',
+					library: 'fa-solid',
+					name: 'cart-plus',
+					label: 'Cart Plus',
+					matched_on: 'term',
+					license: 'free',
+				},
+			],
+			total: 1,
+			page: 1,
+			per_page: 10,
+			truncated: false,
+		},
+	],
+	libraries: [ 'fa-brands', 'fa-regular', 'fa-solid' ],
+	categories: [ 'shopping' ],
+	font_awesome_version: '7.3.1',
+};
+
+const givenServerResponse = ( data: Record< string, unknown > ) => {
+	const post = jest.fn().mockResolvedValue( { data: { data } } );
+	mockedHttpService.mockReturnValue( { post } as never );
+	return post;
+};
+
+describe( 'find-icons tool', () => {
+	beforeEach( () => {
+		jest.clearAllMocks();
+	} );
+
+	it( 'proxies a batch of queries to the php ability', async () => {
+		// Arrange
+		const post = givenServerResponse( serverResponse );
+		const { handler } = captureTool();
+
+		// Act
+		await handler( { queries: [ 'add to cart', 'free shipping' ] } );
+
+		// Assert
+		expect( post ).toHaveBeenCalledWith( 'elementor/v1/mcp-proxy', {
+			tool: 'find-icons',
+			input: { queries: [ 'add to cart', 'free shipping' ] },
+		} );
+	} );
+
+	it( 'maps per-page to the snake-cased ability input', async () => {
+		// Arrange
+		const post = givenServerResponse( serverResponse );
+		const { handler } = captureTool();
+
+		// Act
+		await handler( {
+			queries: [ 'cart' ],
+			library: 'fa-solid',
+			category: 'shopping',
+			page: 2,
+			perPage: 25,
+		} );
+
+		// Assert
+		expect( post ).toHaveBeenCalledWith( 'elementor/v1/mcp-proxy', {
+			tool: 'find-icons',
+			input: {
+				queries: [ 'cart' ],
+				library: 'fa-solid',
+				category: 'shopping',
+				page: 2,
+				per_page: 25,
+			},
+		} );
+	} );
+
+	it( 'returns the writable icon pair and the site catalog facets', async () => {
+		// Arrange
+		givenServerResponse( serverResponse );
+		const { handler } = captureTool();
+
+		// Act
+		const result = await handler( { queries: [ 'add to cart' ] } );
+
+		// Assert
+		expect( result.results ).toEqual( serverResponse.results );
+		expect( result.libraries ).toEqual( serverResponse.libraries );
+		expect( result.categories ).toEqual( serverResponse.categories );
+		expect( result.fontAwesomeVersion ).toBe( '7.3.1' );
+	} );
+
+	it( 'omits facets the server did not send', async () => {
+		// Arrange
+		givenServerResponse( { results: serverResponse.results, font_awesome_version: '7.3.1' } );
+		const { handler } = captureTool();
+
+		// Act
+		const result = await handler( { queries: [ 'add to cart' ] } );
+
+		// Assert
+		expect( result ).not.toHaveProperty( 'libraries' );
+		expect( result ).not.toHaveProperty( 'customLibraries' );
+		expect( result ).not.toHaveProperty( 'categories' );
+	} );
+
+	it( 'surfaces a server failure as a tool error', async () => {
+		// Arrange
+		const post = jest.fn().mockRejectedValue( new Error( 'The icon catalog is missing on this site.' ) );
+		mockedHttpService.mockReturnValue( { post } as never );
+		const { handler } = captureTool();
+
+		// Act & Assert
+		await expect( handler( { queries: [ 'cart' ] } ) ).rejects.toThrow(
+			'The icon catalog is missing on this site.'
+		);
+	} );
+} );

package/src/mcp/tools/find-icons/prompt.ts

@@ -0,0 +1,43 @@
+import { toolPrompts } from '@elementor/editor-mcp';
+
+export const findIconsToolPrompt = toolPrompts( 'find-icons' );
+
+findIconsToolPrompt.description(
+	'Finds icons for the `svg` property of an `e-svg` element, across Font Awesome and any icon packs uploaded to this site. ' +
+		'Returns the exact `value` and `library` pair to write - never assemble those strings yourself, and never guess an icon name. ' +
+		'Call this before placing or configuring an `e-svg`. Nothing has to be uploaded to the Media Library for an icon to work.'
+);
+
+findIconsToolPrompt.instruction(
+	'Call it when the user names an icon ("use the cart-shopping icon") and take the first exact `name` match, ' +
+		'and also when the user describes a page and you decide icons belong in it ("create a product page") - ' +
+		'in that case pass one query per icon you intend to place, in a single call.'
+);
+
+findIconsToolPrompt.instruction(
+	'Write queries the way a person would describe the icon ("shopping cart", "credit card", "phone"). Icons are matched on ' +
+		'their name, aliases, Font Awesome search terms and category, so plain language works better than guessed icon names.'
+);
+
+findIconsToolPrompt.instruction(
+	'Results are ordered best first; `matched_on: "name"` is a stronger signal than `matched_on: "term"`. ' +
+		"Check each result's `license` and only use `free` icons; skip any `pro` entry. " +
+		'Prefer `fa-solid` for UI iconography and keep one style across a page; brand marks only exist in `fa-brands`. ' +
+		'An empty `matches` array means no match was found: broaden the phrase instead of inventing a value.'
+);
+
+findIconsToolPrompt.instruction(
+	'Pass the chosen pair to `configure-element` as the `svg` property: ' +
+		'{ "$$type": "icon", "value": { "value": { "$$type": "string", "value": "fa-solid fa-cart-shopping" }, ' +
+		'"library": { "$$type": "string", "value": "fa-solid" } } }. ' +
+		'An `e-svg` has no colour or size of its own, so set `width`, `height` and `color` in the same `configure-element` call.'
+);
+
+findIconsToolPrompt.example( `Icon named by the user:
+{ "queries": ["cart-shopping"] }` );
+
+findIconsToolPrompt.example( `Every icon a product page needs, in one call:
+{ "queries": ["add to cart", "free shipping", "secure payment", "instagram"] }` );
+
+findIconsToolPrompt.example( `Browse a category, one style only:
+{ "category": "shopping", "library": "fa-solid", "perPage": 25 }` );