@elementor/editor-canvas 4.3.0-999 → 4.3.0-beta2

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

@@ -6,7 +6,7 @@ import { type PropValue, Schema } from '@elementor/editor-props';
 import { DYNAMIC_TAGS_URI } from '../../resources/dynamic-tags-resource';
 import { WIDGET_SCHEMA_URI } from '../../resources/widgets-schema-resource';
 import { convertCssToAtomic } from '../../utils/convert-css-to-atomic';
-import { doUpdateElementProperty } from '../../utils/do-update-element-property';
+import { doUpdateElementProperty, UnsupportedPropertyError } from '../../utils/do-update-element-property';
 import { resolveCanonicalPropKeys } from '../../utils/resolve-canonical-prop-name';
 import { CONFIGURE_ELEMENT_GUIDE_URI, generatePrompt } from './prompt';
 import { inputSchema as schema, outputSchema } from './schema';
@@ -61,6 +61,7 @@ export const initConfigureElementTool = ( reg: MCPRegistryEntry ) => {
 			}
 			const propertiesToUpdate = resolveCanonicalPropKeys( elementType, propertiesToChange );
 			const toUpdate = Object.entries( propertiesToUpdate );
+			const skippedProps: string[] = [];
 			for ( const [ propertyName, propertyValue ] of toUpdate as [ string, PropValue ][] ) {
 				if ( ! Schema.isPropKeyConfigurable( propertyName ) ) {
 					throw new Error( `Not allowed to update ${ propertyName }` );
@@ -73,6 +74,10 @@ export const initConfigureElementTool = ( reg: MCPRegistryEntry ) => {
 						propertyValue,
 					} );
 				} catch ( error ) {
+					if ( error instanceof UnsupportedPropertyError ) {
+						skippedProps.push( error.propertyName );
+						continue;
+					}
 					const errorMessage = createUpdateErrorMessage( {
 						propertyName,
 						elementId,
@@ -86,6 +91,11 @@ export const initConfigureElementTool = ( reg: MCPRegistryEntry ) => {
 			await applyStyleFromCss( { elementId, elementType, style } );
 			return {
 				success: true,
+				warnings: skippedProps.length
+					? `Skipped unsupported props (not in the "${ elementType }" schema; other changes were applied): ${ skippedProps.join(
+							', '
+					  ) }.`
+					: undefined,
 			};
 		},
 	} );

package/src/mcp/tools/get-page-structure/tool.ts

@@ -0,0 +1,73 @@
+import { getCurrentDocument } from '@elementor/editor-documents';
+import { type MCPRegistryEntry } from '@elementor/editor-mcp';
+import { type HttpResponse, httpService } from '@elementor/http-client';
+import { z } from '@elementor/schema';
+
+import { getMcpErrorMessage } from '../../utils/get-mcp-error-message';
+
+const MCP_PROXY_URL = 'elementor/v1/mcp-proxy';
+
+type GetPageStructureResponse = {
+	elements: Array< Record< string, unknown > >;
+};
+
+export const initGetPageStructureTool = ( reg: MCPRegistryEntry ) => {
+	const { addTool } = reg;
+
+	addTool( {
+		name: 'get-page-structure',
+		description:
+			'Returns a lean Elementor element tree skeleton (id, elType, widgetType, title, nested elements) for a post or page. ' +
+			'If no postId is provided, uses the currently open document. Optionally scope to a subtree with elementId. ' +
+			"Set includeContent=true (requires elementId) to also return each node's settings and styles.",
+		schema: {
+			postId: z
+				.number()
+				.optional()
+				.describe(
+					'WordPress post ID of the Elementor document. If omitted, uses the currently open document.'
+				),
+			elementId: z
+				.string()
+				.optional()
+				.describe( 'If provided, returns only the subtree rooted at that element id.' ),
+			includeContent: z
+				.boolean()
+				.optional()
+				.describe(
+					"If true, includes each node's settings and styles (same shape build-composition accepts as input). Requires elementId."
+				),
+		},
+		outputSchema: {
+			elements: z
+				.array( z.any() )
+				.describe(
+					'Skeleton of Elementor elements (id, elType, widgetType, title, nested elements). When includeContent is true, each node also includes settings and styles.'
+				),
+		},
+		handler: async ( { postId, elementId, includeContent } ) => {
+			const resolvedPostId = postId ?? getCurrentDocument()?.id;
+
+			if ( ! resolvedPostId ) {
+				throw new Error( 'No post ID provided and no active document found.' );
+			}
+
+			try {
+				const { data } = await httpService().post< HttpResponse< GetPageStructureResponse > >( MCP_PROXY_URL, {
+					tool: 'get-page-structure',
+					input: {
+						post_id: resolvedPostId,
+						...( elementId ? { element_id: elementId } : {} ),
+						...( includeContent ? { include_content: true } : {} ),
+					},
+				} );
+
+				return {
+					elements: data.data.elements,
+				};
+			} catch ( error ) {
+				throw new Error( getMcpErrorMessage( error, 'get-page-structure' ) );
+			}
+		},
+	} );
+};

package/src/mcp/utils/__tests__/do-update-element-property.test.ts

@@ -8,7 +8,7 @@ import { Schema } from '@elementor/editor-props';
 import { getStylesSchema, getVariantByMeta } from '@elementor/editor-styles';
 import { __privateRunCommandSync } from '@elementor/editor-v1-adapters';
 
-import { doUpdateElementProperty } from '../do-update-element-property';
+import { doUpdateElementProperty, UnsupportedPropertyError } from '../do-update-element-property';
 
 jest.mock( '@elementor/editor-elements', () => ( {
 	createElementStyle: jest.fn(),
@@ -108,6 +108,32 @@ describe( 'doUpdateElementProperty', () => {
 		expect( __privateRunCommandSync ).not.toHaveBeenCalled();
 	} );
 
+	it( 'throws UnsupportedPropertyError when the property is not in the element schema', () => {
+		// Arrange
+		const propertyName = 'link';
+
+		// Act
+		let thrown: unknown;
+		try {
+			doUpdateElementProperty( {
+				elementId: ELEMENT_ID,
+				elementType: ELEMENT_TYPE,
+				propertyName,
+				propertyValue: { $$type: 'link', value: {} },
+			} );
+		} catch ( error ) {
+			thrown = error;
+		}
+
+		// Assert
+		expect( thrown ).toBeInstanceOf( UnsupportedPropertyError );
+		expect( ( thrown as UnsupportedPropertyError ).propertyName ).toBe( propertyName );
+		expect( ( thrown as UnsupportedPropertyError ).elementType ).toBe( ELEMENT_TYPE );
+		expect( ( thrown as Error ).message ).toContain( 'does not exist on element type' );
+		expect( Schema.validatePropValue ).not.toHaveBeenCalled();
+		expect( updateElementSettings ).not.toHaveBeenCalled();
+	} );
+
 	it( 'updates settings when Schema.validatePropValue reports valid PropValue', () => {
 		// Arrange
 		const propertyValue = 'resolved-title';

package/src/mcp/utils/do-update-element-property.ts

@@ -21,6 +21,23 @@ const LOCAL_STYLE_META = {
 	breakpoint: 'desktop',
 	state: null,
 } as const;
+
+export class UnsupportedPropertyError extends Error {
+	public readonly elementType: string;
+	public readonly propertyName: string;
+
+	constructor( elementType: string, propertyName: string, availableProperties: string[] ) {
+		super(
+			`Property "${ propertyName }" does not exist on element type "${ elementType }". Available properties are: ${ availableProperties.join(
+				', '
+			) }`
+		);
+		this.name = 'UnsupportedPropertyError';
+		this.elementType = elementType;
+		this.propertyName = propertyName;
+	}
+}
+
 type CustomCssWriteMode = 'replace' | 'merge-with-stored';
 type OwnParams = {
 	elementId: string;
@@ -151,12 +168,7 @@ export const doUpdateElementProperty = ( params: OwnParams ) => {
 		throw new Error( `No prop schema found for element type: ${ elementType }` );
 	}
 	if ( ! elementPropSchema[ propertyName ] ) {
-		const propertyNames = Object.keys( elementPropSchema );
-		throw new Error(
-			`Property "${ propertyName }" does not exist on element type "${ elementType }". Available properties are: ${ propertyNames.join(
-				', '
-			) }`
-		);
+		throw new UnsupportedPropertyError( elementType, propertyName, Object.keys( elementPropSchema ) );
 	}
 	const propKey = elementPropSchema[ propertyName ].key;
 	const value = resolvePropValue( propertyValue, propKey );

package/src/mcp/utils/get-mcp-error-message.ts

@@ -0,0 +1,16 @@
+import { AxiosError } from '@elementor/http-client';
+
+export function getMcpErrorMessage( error: unknown, toolName: string ): string {
+	if ( error instanceof AxiosError ) {
+		const data = error.response?.data as { message?: string; code?: string } | undefined;
+		if ( data?.message ) {
+			return data.code ? `${ data.code }: ${ data.message }` : data.message;
+		}
+	}
+
+	if ( error instanceof Error ) {
+		return error.message;
+	}
+
+	return `${ toolName } failed with an unknown error.`;
+}

package/src/renderers/__tests__/compute-html-tag.test.ts

@@ -0,0 +1,55 @@
+import { readFileSync } from 'fs';
+import { join } from 'path';
+
+import { computeHtmlTag } from '../compute-html-tag';
+
+type HtmlTagComputerCase = {
+	settings: Record< string, unknown >;
+	default: string;
+	followLink: boolean;
+	expected: string;
+};
+
+const contractCases: HtmlTagComputerCase[] = JSON.parse(
+	readFileSync( join( __dirname, 'fixtures/html-tag-computer-cases.json' ), 'utf8' )
+);
+
+describe( 'computeHtmlTag', () => {
+	it.each( contractCases )(
+		'contract case: default=$default followLink=$followLink expected=$expected',
+		( { settings, default: defaultTag, followLink, expected } ) => {
+			expect( computeHtmlTag( settings, defaultTag, { followLink } ) ).toBe( expected );
+		}
+	);
+
+	it( 'uses link tag when href is present', () => {
+		expect(
+			computeHtmlTag(
+				{
+					tag: 'div',
+					link: {
+						href: 'https://example.com',
+						tag: 'a',
+					},
+				},
+				'div'
+			)
+		).toBe( 'a' );
+	} );
+
+	it( 'ignores link when followLink is false', () => {
+		expect(
+			computeHtmlTag(
+				{
+					tag: 'h4',
+					link: {
+						href: 'https://example.com',
+						tag: 'a',
+					},
+				},
+				'h2',
+				{ followLink: false }
+			)
+		).toBe( 'h4' );
+	} );
+} );

package/src/renderers/__tests__/create-dom-renderer.test.ts

@@ -1,7 +1,21 @@
 /* eslint-disable testing-library/render-result-naming-convention */
 import { createDomRenderer } from '../create-dom-renderer';
 
+const TEST_ALLOWED_HTML_WRAPPER_TAGS = [ 'a', 'div', 'form', 'span' ];
+
 describe( 'createDomRenderer', () => {
+	beforeEach( () => {
+		window.elementorCommon = {
+			config: {
+				allowedHTMLWrapperTags: TEST_ALLOWED_HTML_WRAPPER_TAGS,
+			},
+		};
+	} );
+
+	afterEach( () => {
+		delete window.elementorCommon;
+	} );
+
 	it.each( [
 		{
 			title: 'basic string',
@@ -15,12 +29,24 @@ describe( 'createDomRenderer', () => {
 			context: { tag: 'a' },
 			expected: '<a></a>',
 		},
+		{
+			title: 'allowed form html tag',
+			template: `<{{ tag | e( 'html_tag' ) }}></{{ tag | e( 'html_tag' ) }}>`,
+			context: { tag: 'form' },
+			expected: '<form></form>',
+		},
 		{
 			title: 'disallowed html tags',
 			template: `<{{ tag | e( 'html_tag' ) }}></{{ tag | e( 'html_tag' ) }}>`,
 			context: { tag: 'script' },
 			expected: '<div></div>',
 		},
+		{
+			title: 'allowed html tag with uppercase casing',
+			template: `<{{ tag | e( 'html_tag' ) }}></{{ tag | e( 'html_tag' ) }}>`,
+			context: { tag: 'DIV' },
+			expected: '<DIV></DIV>',
+		},
 		{
 			title: 'allowed url (http)',
 			template: `{{ url | e( 'full_url' ) }}`,
@@ -63,4 +89,38 @@ describe( 'createDomRenderer', () => {
 		// Assert.
 		expect( result ).toBe( expected );
 	} );
+
+	it( 'should validate a tag added via localized config', async () => {
+		// Arrange.
+		window.elementorCommon = {
+			config: {
+				allowedHTMLWrapperTags: [ ...TEST_ALLOWED_HTML_WRAPPER_TAGS, 'custom-tag' ],
+			},
+		};
+		const domRenderer = createDomRenderer();
+		const template = `<{{ tag | e( 'html_tag' ) }}></{{ tag | e( 'html_tag' ) }}>`;
+
+		domRenderer.register( 'test-template', template );
+
+		// Act.
+		const result = await domRenderer.render( 'test-template', { tag: 'custom-tag' } );
+
+		// Assert.
+		expect( result ).toBe( '<custom-tag></custom-tag>' );
+	} );
+
+	it( 'should fail closed to div when the localized config is missing, even for an otherwise-safe tag', async () => {
+		// Arrange.
+		delete window.elementorCommon;
+		const domRenderer = createDomRenderer();
+		const template = `<{{ tag | e( 'html_tag' ) }}></{{ tag | e( 'html_tag' ) }}>`;
+
+		domRenderer.register( 'test-template', template );
+
+		// Act.
+		const result = await domRenderer.render( 'test-template', { tag: 'a' } );
+
+		// Assert.
+		expect( result ).toBe( '<div></div>' );
+	} );
 } );

package/src/renderers/__tests__/fixtures/html-tag-computer-cases.json

@@ -0,0 +1,87 @@
+[
+	{
+		"settings": {},
+		"default": "div",
+		"followLink": true,
+		"expected": "div"
+	},
+	{
+		"settings": { "tag": "header" },
+		"default": "div",
+		"followLink": true,
+		"expected": "header"
+	},
+	{
+		"settings": { "tag": "" },
+		"default": "div",
+		"followLink": true,
+		"expected": "div"
+	},
+	{
+		"settings": {
+			"link": {
+				"href": "https://example.com",
+				"tag": "a"
+			}
+		},
+		"default": "div",
+		"followLink": true,
+		"expected": "a"
+	},
+	{
+		"settings": {
+			"link": {
+				"tag": "a"
+			}
+		},
+		"default": "button",
+		"followLink": true,
+		"expected": "button"
+	},
+	{
+		"settings": {
+			"link": {
+				"tag": "a",
+				"attributes": "href=\"https://example.com\""
+			}
+		},
+		"default": "div",
+		"followLink": true,
+		"expected": "a"
+	},
+	{
+		"settings": {
+			"tag": "div",
+			"link": {
+				"href": "https://example.com",
+				"tag": "a"
+			}
+		},
+		"default": "div",
+		"followLink": true,
+		"expected": "a"
+	},
+	{
+		"settings": {
+			"tag": "div",
+			"link": {
+				"href": "https://example.com",
+				"tag": "a"
+			}
+		},
+		"default": "div",
+		"followLink": false,
+		"expected": "div"
+	},
+	{
+		"settings": {
+			"tag": {
+				"$$type": "string",
+				"value": "h3"
+			}
+		},
+		"default": "h2",
+		"followLink": true,
+		"expected": "h3"
+	}
+]

package/src/renderers/compute-html-tag.ts

@@ -0,0 +1,73 @@
+export type ComputeHtmlTagOptions = {
+	followLink?: boolean;
+};
+
+export const DEFAULT_LINK_TAG = 'a';
+
+type LinkSettings = Record< string, unknown >;
+
+export function computeHtmlTag(
+	settings: Record< string, unknown >,
+	defaultTag: string,
+	options: ComputeHtmlTagOptions = {}
+): string {
+	const followLink = options.followLink ?? true;
+
+	if ( followLink && settingsHaveActiveLink( settings ) ) {
+		const link = settings.link;
+
+		return extractLinkHtmlTag( isRecord( link ) ? link : {} );
+	}
+
+	const settingsTag = extractHtmlTagValue( settings.tag );
+
+	if ( null !== settingsTag && '' !== settingsTag ) {
+		return settingsTag;
+	}
+
+	return defaultTag;
+}
+
+function settingsHaveActiveLink( settings: Record< string, unknown > ): boolean {
+	const link = settings.link;
+
+	if ( ! isRecord( link ) ) {
+		return false;
+	}
+
+	const href = extractHtmlTagValue( link.href );
+
+	if ( null !== href && '' !== href ) {
+		return true;
+	}
+
+	const attributes = link.attributes;
+
+	return typeof attributes === 'string' && '' !== attributes;
+}
+
+function extractLinkHtmlTag( link: LinkSettings ): string {
+	const tag = extractHtmlTagValue( link.tag );
+
+	if ( null !== tag && '' !== tag ) {
+		return tag;
+	}
+
+	return DEFAULT_LINK_TAG;
+}
+
+function extractHtmlTagValue( value: unknown ): string | null {
+	if ( isRecord( value ) && typeof value.value === 'string' ) {
+		return value.value;
+	}
+
+	if ( typeof value === 'string' ) {
+		return value;
+	}
+
+	return null;
+}
+
+function isRecord( value: unknown ): value is Record< string, unknown > {
+	return typeof value === 'object' && null !== value && ! Array.isArray( value );
+}

package/src/renderers/create-dom-renderer.ts

@@ -18,29 +18,20 @@ export function createDomRenderer(): DomRenderer {
 	};
 }
 
+/**
+ * PHP (`Utils::get_allowed_html_wrapper_tags()`) is the single source of truth for this
+ * list; it's localized via `elementorCommon.config`. If it's ever missing, fail closed
+ * (no tags allowed) rather than fall back to a second hardcoded copy that could drift.
+ */
+function getAllowedHtmlWrapperTags(): readonly string[] {
+	return window.elementorCommon?.config?.allowedHTMLWrapperTags ?? [];
+}
+
 function escapeHtmlTag( value: string ) {
-	const allowedTags = [
-		'a',
-		'article',
-		'aside',
-		'button',
-		'div',
-		'footer',
-		'h1',
-		'h2',
-		'h3',
-		'h4',
-		'h5',
-		'h6',
-		'header',
-		'main',
-		'nav',
-		'p',
-		'section',
-		'span',
-	];
-
-	return allowedTags.includes( value ) ? value : 'div';
+	const allowedTags = getAllowedHtmlWrapperTags();
+	const normalizedTag = value?.toLowerCase?.() ?? '';
+
+	return allowedTags.includes( normalizedTag ) ? value : 'div';
 }
 
 function escapeURL( value: string ) {

package/src/transformers/settings/escaped-html-transformer.ts

@@ -0,0 +1,6 @@
+import { sanitizeEscapedHtml } from '../../utils/sanitize-escaped-html';
+import { createTransformer } from '../create-transformer';
+
+export const escapedHtmlTransformer = createTransformer( ( value: string | null ) => {
+	return sanitizeEscapedHtml( value );
+} );