@elementor/editor-canvas 4.1.0 → 4.2.0-840

package/src/mcp/tools/build-composition/prompt.ts

@@ -1,5 +1,7 @@
 import { toolPrompts } from '@elementor/editor-mcp';
 
+import { AVAILABLE_WIDGETS_URI } from '../../resources/available-widgets-resource';
+
 export const generatePrompt = () => {
 	const buildCompositionsToolPrompt = toolPrompts( 'build-compositions' );
 
@@ -7,6 +9,10 @@ export const generatePrompt = () => {
 # RESOURCES (Read before use)
 - [elementor://global-classes] - Check FIRST for reusable classes
 - [elementor://global-variables] - ONLY use variables defined here
+- [${ AVAILABLE_WIDGETS_URI }/v4]
+
+# TOOL SUPPORT
+This tool support v4 elements only
 
 # WORKFLOW
 1. Check/create global classes via "create-global-class" tool

package/src/mcp/tools/build-composition/tool.ts

@@ -9,6 +9,7 @@ import {
 import { type MCPRegistryEntry } from '@elementor/editor-mcp';
 
 import { CompositionBuilder } from '../../../composition-builder/composition-builder';
+import { AVAILABLE_WIDGETS_URI_V4 } from '../../resources/available-widgets-resource';
 import { BEST_PRACTICES_URI, STYLE_SCHEMA_URI, WIDGET_SCHEMA_URI } from '../../resources/widgets-schema-resource';
 import { doUpdateElementProperty } from '../../utils/do-update-element-property';
 import { getCompositionTargetContainer } from '../../utils/get-composition-target-container';
@@ -28,12 +29,14 @@ export const initBuildCompositionsTool = ( reg: MCPRegistryEntry ) => {
 			{ description: 'Global Classes', uri: 'elementor://global-classes' },
 			{ description: 'Global Variables', uri: 'elementor://global-variables' },
 			{ description: 'Styles best practices', uri: BEST_PRACTICES_URI },
+			{ description: 'Available widgets for this tool', uri: AVAILABLE_WIDGETS_URI_V4 },
 		],
 		outputSchema,
 		modelPreferences: {
 			hints: [ { name: 'claude-sonnet-4-5' } ],
 		},
 		handler: async ( params ) => {
+			assertCompositionXmlUsesV4WidgetsOnly( params.xmlStructure );
 			const { xmlStructure, elementConfig, stylesConfig, customCSS } = params;
 			let generatedXML: string = '';
 			const errors: Error[] = [];
@@ -132,3 +135,26 @@ Remember: Global classes ensure design consistency and reusability. Don't skip a
 		},
 	} );
 };
+
+function assertCompositionXmlUsesV4WidgetsOnly( xmlStructure: string ) {
+	const doc = new DOMParser().parseFromString( xmlStructure, 'application/xml' );
+	if ( doc.querySelector( 'parsererror' ) ) {
+		throw new Error( 'Failed to parse XML string: ' + doc );
+	}
+	const widgetsCache = getWidgetsCache() ?? {};
+	for ( const node of doc.querySelectorAll( '*' ) ) {
+		const type = node.tagName;
+		const widgetData = widgetsCache[ type ];
+		if ( ! widgetData ) {
+			continue;
+		}
+		if ( widgetData.elType !== 'widget' ) {
+			continue;
+		}
+		if ( ! widgetData.atomic_props_schema ) {
+			throw new Error(
+				`This tool does not support V3 elements. Please use the elementor-v3-mcp tools instead for element type: ${ type }`
+			);
+		}
+	}
+}

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

@@ -9,11 +9,11 @@ export const configureElementToolPrompt = `Configure an existing element on the
 2. [${ STYLE_SCHEMA_URI }]
    Required to understand the styles schema for the widgets. All widgets share the same styles schema, grouped by categories.
    Use this resource to understand which style properties are available for each element, and how to structure the "stylePropertiesToChange" parameter.
-3. If not sure about the PropValues schema, you can use the "get-element-configuration-values" tool to retreive the current PropValues configuration of the element.
+3. If not sure about the PropValues schema, you can use the "get-element-configuration-values" tool to retrieve the current PropValues configuration of the element.
 
 Before using this tool, check the definitions of the elements PropTypes at the resource "widget-schema-by-type" at editor-canvas__elementor://widgets/schema/{widgetType}
 All widgets share a common _style property for styling, which uses the common styles schema.
-Retreive and check the common styles schema at the resource list "styles-schema" at editor-canvas__elementor://styles/schema/{category}
+Retrieve and check the common styles schema at the resource list "styles-schema" at editor-canvas__elementor://styles/schema/{category}
 
 # Parameters
 - propertiesToChange: An object containing the properties to change, with their new values. MANDATORY. When updating a style only, provide an empty object.
@@ -42,19 +42,19 @@ PropValue structure:
 }
 
 <IMPORTANT>
-ALWAYS MAKE SURE you have the PropType schemas for the element you are configuring, and the common-styles schema for styling. If you are not sure, retreive the schema from the resources mentioned above.
+ALWAYS MAKE SURE you have the PropType schemas for the element you are configuring, and the common-styles schema for styling. If you are not sure, retrieve the schema from the resources mentioned above.
 </IMPORTANT>
 
 You can use multiple property changes at once by providing multiple entries in the propertiesToChange object, including _style alongside non-style props.
 Some properties are nested, use the root property name, then objects with nested values inside, as the complete schema suggests.
 
-Make sure you have the "widget-schema-by-type" resource available to retreive the PropType schema for the element type you are configuring.
-Make sure you have to "styles-schema" resources available to retreive the common styles schema.
+Make sure you have the "widget-schema-by-type" resource available to retrieve the PropType schema for the element type you are configuring.
+Make sure you have to "styles-schema" resources available to retrieve the common styles schema.
 
 # How to configure elements
 We use a dedicated PropType Schema for configuring elements, including styles. When you configure an element, you must use the EXACT PropType Value as defined in the schema.
 For styleProperties, use the style schema provided, as it also uses the PropType format.
-For all non-primitive types, provide the key property as defined in the schema as $$type in the generated objecct, as it is MANDATORY for parsing.
+For all non-primitive types, provide the key property as defined in the schema as $$type in the generated object, as it is MANDATORY for parsing.
 
 Use the EXACT "PROP-TYPE" Schema given, and ALWAYS include the "key" property from the original configuration for every property you are changing.
 

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

@@ -20,7 +20,7 @@ export const inputSchema = {
 		)
 		.describe( 'An object record containing style property names and their new values to be set on the element' )
 		.default( {} ),
-	elementType: z.string().describe( 'The type of the element to retreive the schema' ),
+	elementType: z.string().describe( 'The type of the element to retrieve the schema' ),
 	elementId: z.string().describe( 'The unique id of the element to configure' ),
 };
 

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

@@ -1,3 +1,4 @@
+import { getWidgetsCache } from '@elementor/editor-elements';
 import { type MCPRegistryEntry } from '@elementor/editor-mcp';
 
 import { STYLE_SCHEMA_URI, WIDGET_SCHEMA_URI } from '../../resources/widgets-schema-resource';
@@ -24,6 +25,17 @@ export const initConfigureElementTool = ( reg: MCPRegistryEntry ) => {
 			speedPriority: 0.7,
 		},
 		handler: ( { elementId, propertiesToChange, elementType, stylePropertiesToChange } ) => {
+			const widgetData = getWidgetsCache()?.[ elementType ];
+			if ( ! widgetData ) {
+				throw new Error(
+					`Unknown element type: ${ elementType }. Check the available-widgets resource for valid types.`
+				);
+			}
+			if ( ! widgetData.atomic_props_schema ) {
+				throw new Error(
+					`This tool does not support V3 elements. Please use the elementor-v3-mcp tools instead for element type: ${ elementType }`
+				);
+			}
 			const toUpdate = Object.entries( propertiesToChange );
 			const { valid, errors } = validateInput.validatePropSchema( elementType, propertiesToChange );
 			const { valid: stylesValid, errors: stylesErrors } = validateInput.validateStyles(

package/src/mcp/tools/get-element-config/tool.ts

@@ -59,10 +59,20 @@ export const initGetElementConfigTool = ( reg: MCPRegistryEntry ) => {
 			if ( ! element ) {
 				throw new Error( `Element with ID ${ elementId } not found.` );
 			}
+			const elementType = element.model.get( 'widgetType' ) || element.model.get( 'elType' ) || '';
+			const widgetData = getWidgetsCache()?.[ elementType ];
+			if ( ! widgetData ) {
+				throw new Error(
+					`Unknown element type: ${ elementType }. Check the available-widgets resource for valid types.`
+				);
+			}
+			if ( ! widgetData.atomic_props_schema ) {
+				throw new Error(
+					`This tool does not support V3 elements. Please use the elementor-v3-mcp tools instead for element type: ${ elementType }`
+				);
+			}
 			const elementRawSettings = element.settings;
-			const propSchema =
-				getWidgetsCache()?.[ element.model.get( 'widgetType' ) || element.model.get( 'elType' ) || '' ]
-					?.atomic_props_schema;
+			const propSchema = getWidgetsCache()?.[ elementType ]?.atomic_props_schema;
 
 			if ( ! elementRawSettings || ! propSchema ) {
 				throw new Error( `No settings or prop schema found for element ID: ${ elementId }` );

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

@@ -30,7 +30,7 @@ export function resolvePropValue( value: unknown, forceKey?: string ): PropValue
 }
 
 /*
- * This function expects a PropValue bag for updaing an element.
+ * This function expects a PropValue bag for updating an element.
  * Also, it supports updating styles "on-the-way" by checking for "_styles" property with PropValue bag that fits the common style schema.
  */
 export const doUpdateElementProperty = ( params: OwnParams ) => {

package/src/mcp/utils/element-data-util.ts

@@ -0,0 +1,46 @@
+import { getWidgetsCache, type V1ElementConfig } from '@elementor/editor-elements';
+
+export type AvailableWidget = {
+	type: string;
+	version: string;
+	description?: string;
+};
+
+export function hasV3Controls( controls: unknown ): boolean {
+	return typeof controls === 'object' && controls !== null && Object.keys( controls ).length > 0;
+}
+
+export function isWidgetAvailableForLLM( config: V1ElementConfig | undefined ): boolean {
+	if ( ! config ) {
+		return false;
+	}
+	if ( config.meta?.llm_support === false ) {
+		return false;
+	}
+	if ( config.atomic_props_schema ) {
+		return true;
+	}
+	return hasV3Controls( config.controls );
+}
+
+export function getWidgetVersion( config: V1ElementConfig | undefined ): string {
+	return config?.atomic_props_schema ? 'v4' : 'v3';
+}
+
+export function getAvailableWidgets(): AvailableWidget[] {
+	const cache = getWidgetsCache() ?? {};
+
+	return Object.keys( cache )
+		.filter( ( widgetType ) => isWidgetAvailableForLLM( cache[ widgetType ] ) )
+		.sort()
+		.map( ( widgetType ) => {
+			const config = cache[ widgetType ];
+			const description = typeof config?.meta?.description === 'string' ? config.meta.description : undefined;
+
+			return {
+				type: widgetType,
+				version: getWidgetVersion( config ),
+				...( description && { description } ),
+			};
+		} );
+}

package/src/mcp/utils/validate-input.ts

@@ -47,7 +47,7 @@ export const validateInput = {
 			if ( ! propSchema ) {
 				errors.push( `Property "${ propName }" is not defined in the schema.` );
 				hasInvalidKey = true;
-			} else if ( ! Schema.isPropKeyConfigurable( propName ) ) {
+			} else if ( ! Schema.isPropKeyConfigurable( propName, propSchema ) ) {
 				errors.push( `Property "${ propName }" is not configurable.` );
 			} else {
 				const { valid } = Schema.validatePropValue( propSchema, propValue as PropValue );

package/src/sync/global-styles-imported-event.ts

@@ -0,0 +1,8 @@
+import { type StyleDefinitionID, type StyleDefinitionsMap, type StyleVariables } from '@elementor/editor-styles';
+
+export const GLOBAL_STYLES_IMPORTED_EVENT = 'elementor/global-styles/imported';
+
+export type ImportedGlobalStylesPayload = {
+	global_variables?: { data: StyleVariables };
+	global_classes?: { items: StyleDefinitionsMap; order: StyleDefinitionID[] };
+};

package/src/transformers/settings/date-range-transformer.ts

@@ -0,0 +1,12 @@
+import { createTransformer } from '../create-transformer';
+
+export const dateRangeTransformer = createTransformer< { min?: string | null; max?: string | null } >( ( value ) => {
+	if ( ! value || Object.keys( value ).length === 0 ) {
+		return null;
+	}
+
+	return {
+		min: value.min || null,
+		max: value.max || null,
+	};
+} );

package/src/transformers/settings/time-range-transformer.ts

@@ -0,0 +1,12 @@
+import { createTransformer } from '../create-transformer';
+
+export const timeRangeTransformer = createTransformer< { min?: string | null; max?: string | null } >( ( value ) => {
+	if ( ! value || Object.keys( value ).length === 0 ) {
+		return null;
+	}
+
+	return {
+		min: value.min || null,
+		max: value.max || null,
+	};
+} );

package/src/transformers/shared/image-src-transformer.ts

@@ -3,9 +3,11 @@ import { createTransformer } from '../create-transformer';
 type ImageSrc = {
 	id?: unknown;
 	url?: unknown;
+	alt?: unknown;
 };
 
 export const imageSrcTransformer = createTransformer( ( value: ImageSrc ) => ( {
 	id: value.id ?? null,
 	url: value.url ?? null,
+	alt: value.alt ?? null,
 } ) );

package/src/transformers/shared/image-transformer.ts

@@ -6,6 +6,7 @@ type Image = {
 	src?: {
 		id: number | null;
 		url: string | null;
+		alt?: string | null;
 	};
 	size?: string;
 };
@@ -14,7 +15,7 @@ export const imageTransformer = createTransformer( async ( value: Image ) => {
 	const { src, size } = value;
 
 	if ( ! src?.id ) {
-		return src?.url ? { src: src.url } : null;
+		return src?.url ? { src: src.url, alt: src.alt ?? '' } : null;
 	}
 
 	const attachment = await getMediaAttachment( { id: src.id } );
@@ -26,6 +27,7 @@ export const imageTransformer = createTransformer( async ( value: Image ) => {
 			src: sizedAttachment.url,
 			height: sizedAttachment.height,
 			width: sizedAttachment.width,
+			alt: attachment.alt,
 		};
 	}
 
@@ -34,6 +36,7 @@ export const imageTransformer = createTransformer( async ( value: Image ) => {
 			src: attachment.url,
 			height: attachment.height,
 			width: attachment.width,
+			alt: attachment.alt,
 		};
 	}
 

package/src/transformers/styles/span-transformer.ts

@@ -0,0 +1,5 @@
+import { createTransformer } from '../create-transformer';
+
+export const spanTransformer = createTransformer( ( value: number ) => {
+	return value || 0 === value ? 'span ' + value : null;
+} );

package/src/utils/after-render.ts

@@ -0,0 +1,26 @@
+import { getContainer } from '@elementor/editor-elements';
+
+import { type TemplatedElementView } from '../legacy/types';
+
+export function doAfterRender( elementIds: string[], callback: ( elementIds: string[] ) => void ): void {
+	const pending = elementIds
+		.map( ( elementId ) => {
+			const view = getContainer( elementId )?.view;
+			if ( ! view || ! hasDoAfterRender( view ) ) {
+				return undefined;
+			}
+
+			return new Promise< void >( ( resolve ) => view._doAfterRender( resolve ) );
+		} )
+		.filter( Boolean );
+
+	if ( pending.length > 0 ) {
+		Promise.all( pending ).then( () => callback( elementIds ) );
+	} else {
+		callback( elementIds );
+	}
+}
+
+function hasDoAfterRender( view: unknown ): view is TemplatedElementView {
+	return typeof ( view as TemplatedElementView )?._doAfterRender === 'function';
+}

package/src/mcp/utils/generate-available-tags.ts

@@ -1,23 +0,0 @@
-import { getWidgetsCache, type V1ElementConfig } from '@elementor/editor-elements';
-
-type ElTypedElementConfig = V1ElementConfig< {
-	elType?: string;
-} >;
-
-export const generateAvailableTags = () => {
-	const cache = getWidgetsCache< ElTypedElementConfig >();
-	if ( ! cache ) {
-		return [];
-	}
-	const customTags = Object.entries( cache )
-		.filter( ( [ , widgetData ] ) => !! widgetData.atomic_controls )
-		.map( ( [ widgetType, widgetData ] ) => {
-			const configurationSchema = widgetData; //getElementSchemaAsJsonSchema( widgetType );
-			return {
-				tag: `${ widgetType }`,
-				description: widgetData.title || widgetData.elType || `A ${ widgetType } element`,
-				configurationSchema: JSON.stringify( configurationSchema ),
-			};
-		} );
-	return customTags;
-};