@elementor/editor-canvas 3.35.0-340 → 3.35.0-341

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

@@ -7,9 +7,10 @@ import {
 	type V1Element,
 } from '@elementor/editor-elements';
 import { type MCPRegistryEntry } from '@elementor/editor-mcp';
-import { type PropValue } from '@elementor/editor-props';
 
+import { BEST_PRACTICES_URI, STYLE_SCHEMA_URI, WIDGET_SCHEMA_URI } from '../../resources/widgets-schema-resource';
 import { doUpdateElementProperty } from '../../utils/do-update-element-property';
+import { validateInput } from '../../utils/validate-input';
 import { generatePrompt } from './prompt';
 import { inputSchema as schema, outputSchema } from './schema';
 
@@ -20,6 +21,13 @@ export const initBuildCompositionsTool = ( reg: MCPRegistryEntry ) => {
 		name: 'build-compositions',
 		description: generatePrompt(),
 		schema,
+		requiredResources: [
+			{ description: 'Widgets schema', uri: WIDGET_SCHEMA_URI },
+			{ description: 'Global Classes', uri: 'elementor://global-classes' },
+			{ description: 'Styles schema', uri: STYLE_SCHEMA_URI },
+			{ description: 'Global Variables', uri: 'elementor://global-variables' },
+			{ description: 'Styles best practices', uri: BEST_PRACTICES_URI },
+		],
 		outputSchema,
 		handler: async ( params ) => {
 			let xml: Document | null = null;
@@ -70,30 +78,24 @@ export const initBuildCompositionsTool = ( reg: MCPRegistryEntry ) => {
 					try {
 						const configObject = elementConfig[ configId ] || {};
 						const styleObject = stylesConfig[ configId ] || {};
-						configObject._styles = styleObject;
+						const { errors: propsValidationErrors } = validateInput.validatePropSchema(
+							elementTag,
+							configObject
+						);
+						errors.push( ...( propsValidationErrors || [] ).map( ( msg ) => new Error( msg ) ) );
+						const { errors: stylesValidationErrors } = validateInput.validateStyles( styleObject );
+						errors.push( ...( stylesValidationErrors || [] ).map( ( msg ) => new Error( msg ) ) );
+
+						if ( propsValidationErrors?.length || stylesValidationErrors?.length ) {
+							return;
+						}
+						configObject._styles = styleObject || {};
 						for ( const [ propertyName, propertyValue ] of Object.entries( configObject ) ) {
-							// validate property existance
-							const widgetSchema = widgetsCache[ elementTag ];
-							if (
-								! widgetSchema?.atomic_props_schema?.[ propertyName ] &&
-								propertyName !== '_styles' &&
-								propertyName !== 'custom_css'
-							) {
-								softErrors.push(
-									new Error(
-										`Property "${ propertyName }" does not exist on element type "${ elementTag }".`
-									)
-								);
-								continue;
-							}
 							try {
 								doUpdateElementProperty( {
 									elementId: newElement.id,
 									propertyName,
-									propertyValue:
-										propertyName === 'custom_css'
-											? { _styles: propertyValue }
-											: ( propertyValue as unknown as PropValue ),
+									propertyValue,
 									elementType: elementTag,
 								} );
 							} catch ( error ) {
@@ -130,13 +132,10 @@ export const initBuildCompositionsTool = ( reg: MCPRegistryEntry ) => {
 						options: { useHistory: false },
 					} );
 				} );
-			}
-
-			if ( errors.length > 0 ) {
 				const errorText = `Failed to build composition with the following errors:\n\n
 ${ errors.map( ( e ) => ( typeof e === 'string' ? e : e.message ) ).join( '\n\n' ) }
 "Missing $$type" errors indicate that the configuration objects are invalid. Try again and apply **ALL** object entries with correct $$type.
-Now that you have these errors, fix them and try again. Errors regarding configuration objects, please check again the PropType schemas`;
+Now that you have these errors, fix them and try again. Errors regarding configuration objects, please check against the PropType schemas`;
 				throw new Error( errorText );
 			}
 			if ( ! xml ) {

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

@@ -5,10 +5,10 @@ export const configureElementToolPrompt = `Configure an existing element on the
 # **CRITICAL - REQUIRED INFORMATION (Must read before using this tool)**
 1. [${ WIDGET_SCHEMA_URI }]
    Required to understand which widgets are available, and what are their configuration schemas.
-   Every widgetType (i.e. e-heading, e-button) that is supported has it's own property schema, that you must follow in order to apply property values correctly.
+   Every widgetType (i.e. e-heading, e-button) that is supported has it's own property schema, that you must follow in order to apply parameter values correctly.
 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 "_styles" configuration property.
+   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.
 
 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}
@@ -16,16 +16,18 @@ All widgets share a common _style property for styling, which uses the common st
 Retreive 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
+- propertiesToChange: An object containing the properties to change, with their new values. MANDATORY. When updating a style only, provide an empty object.
+- stylePropertiesToChange: An object containing the style properties to change, with their new values. OPTIONAL
 - elementId: The ID of the element to configure. MANDATORY
 - elementType: The type of the element to configure (i.e. e-heading, e-button). MANDATORY
 
 # When to use this tool
 When a user requires to change anything in an element, such as updating text, colors, sizes, or other configurable properties.
 This tool handles elements of type "widget".
-This tool handles styling elements, using the _styles property in the configuration.
+This tool handles styling elements, using the "stylePropertiesToChange" parameter.
 
 The element's schema must be known before using this tool.
+The style schema must be known before using this tool.
 
 Attached resource link describing how PropType schema should be parsed as PropValue for this tool.
 
@@ -43,13 +45,13 @@ ALWAYS MAKE SURE you have the PropType schemas for the element you are configuri
 
 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.
-Nested properties, such as for the _styles, should include a "_styles" property with object containing the definitions to change.
 
 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.
 
 # 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 _styles, use the style schema provided, as it also uses the PropType format.
+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.
 
 Use the EXACT "PROP-TYPE" Schema given, and ALWAYS include the "key" property from the original configuration for every property you are changing.
@@ -67,23 +69,24 @@ Use the EXACT "PROP-TYPE" Schema given, and ALWAYS include the "key" property fr
       $$type: 'boolean',
       value: false
     },
-    _styles: {
-      // List of available keys available at the [${ STYLE_SCHEMA_URI }] dynamic resource
-      'line-height': {
-        $$type: 'size', // MANDATORY do not forget to include the correct $$type for every property
-        value: {
-          size: {
-            $$type: 'number',
-            value: 20
-          },
-          unit: {
-            $$type: 'string',
-            value: 'px'
-          }
+  },
+  stylePropertiesToChange: {
+    'line-height': {
+      $$type: 'size', // MANDATORY do not forget to include the correct $$type for every property
+      value: {
+        size: {
+          $$type: 'number',
+          value: 20
+        },
+        unit: {
+          $$type: 'string',
+          value: 'px'
         }
       }
     }
-  }
+  },
+  elementId: 'element-id',
+  elementType: 'element-type'
 };
 \`\`\`
 

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

@@ -1,17 +1,25 @@
 import { z } from '@elementor/schema';
 
+import { STYLE_SCHEMA_URI, WIDGET_SCHEMA_URI } from '../../resources/widgets-schema-resource';
+
 export const inputSchema = {
 	propertiesToChange: z
 		.record(
+			z.string().describe( 'The property name.' ),
 			z
-				.string()
-				.describe(
-					'The property name. If nested property, provide the root property name, and the object delta only.'
-				),
-			z.any().describe( "The property's value" )
+				.any()
+				.describe( `PropValue, refer to [${ WIDGET_SCHEMA_URI }] by correct type, as appears in elementType` ),
+			z.any()
+		)
+		.describe( 'An object record containing property names and their new values to be set on the element' ),
+	stylePropertiesToChange: z
+		.record(
+			z.string().describe( 'The style property name' ),
+			z.any().describe( `The style PropValue, refer to [${ STYLE_SCHEMA_URI }] how to generate values` ),
+			z.any()
 		)
-		.describe( 'An object record containing property names and their new values to be set on the element' )
-		.optional(),
+		.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' ),
 	elementId: z.string().describe( 'The unique id of the element to configure' ),
 };

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

@@ -1,7 +1,8 @@
 import { type MCPRegistryEntry } from '@elementor/editor-mcp';
 
-import { WIDGET_SCHEMA_URI } from '../../resources/widgets-schema-resource';
+import { STYLE_SCHEMA_URI, WIDGET_SCHEMA_URI } from '../../resources/widgets-schema-resource';
 import { doUpdateElementProperty } from '../../utils/do-update-element-property';
+import { validateInput } from '../../utils/validate-input';
 import { configureElementToolPrompt } from './prompt';
 import { inputSchema as schema, outputSchema } from './schema';
 
@@ -13,20 +14,29 @@ export const initConfigureElementTool = ( reg: MCPRegistryEntry ) => {
 		description: configureElementToolPrompt,
 		schema,
 		outputSchema,
-		handler: ( { elementId, propertiesToChange, elementType } ) => {
-			if ( ! propertiesToChange ) {
-				throw new Error(
-					'propertiesToChange is required to configure an element. Now that you have this information, ensure you have the schema and try again.'
-				);
-			}
+		requiredResources: [
+			{ description: 'Widgets schema', uri: WIDGET_SCHEMA_URI },
+			{ description: 'Styles schema', uri: STYLE_SCHEMA_URI },
+		],
+		handler: ( { elementId, propertiesToChange, elementType, stylePropertiesToChange } ) => {
 			const toUpdate = Object.entries( propertiesToChange );
+			const { valid, errors } = validateInput.validatePropSchema( elementType, propertiesToChange );
+			const { valid: stylesValid, errors: stylesErrors } = validateInput.validateStyles(
+				stylePropertiesToChange || {}
+			);
+			if ( ! valid ) {
+				const errorMessage = `Failed to configure element "${ elementId }" due to invalid properties: ${ errors?.join(
+					'\n- '
+				) }`;
+				throw new Error( errorMessage );
+			}
+			if ( ! stylesValid ) {
+				const errorMessage = `Failed to configure element "${ elementId }" due to invalid style properties: ${ stylesErrors?.join(
+					'\n- '
+				) }`;
+				throw new Error( errorMessage );
+			}
 			for ( const [ propertyName, propertyValue ] of toUpdate ) {
-				if ( ! propertyName && ! elementId && ! elementType ) {
-					throw new Error(
-						'propertyName, elementId, elementType are required to configure an element. If you want to retreive the schema, use the get-element-configuration-schema tool.'
-					);
-				}
-
 				try {
 					doUpdateElementProperty( {
 						elementId,
@@ -40,6 +50,28 @@ export const initConfigureElementTool = ( reg: MCPRegistryEntry ) => {
 						elementId,
 						elementType,
 						error: error as Error,
+						propertyType: 'prop',
+					} );
+					throw new Error( errorMessage );
+				}
+			}
+			for ( const [ stylePropertyName, stylePropertyValue ] of Object.entries( stylePropertiesToChange || {} ) ) {
+				try {
+					doUpdateElementProperty( {
+						elementId,
+						elementType,
+						propertyName: '_styles',
+						propertyValue: {
+							[ stylePropertyName ]: stylePropertyValue,
+						},
+					} );
+				} catch ( error ) {
+					const errorMessage = createUpdateErrorMessage( {
+						propertyName: `(style) ${ stylePropertyName }`,
+						elementId,
+						elementType,
+						propertyType: 'style',
+						error: error as Error,
 					} );
 					throw new Error( errorMessage );
 				}
@@ -56,12 +88,24 @@ function createUpdateErrorMessage( opts: {
 	elementId: string;
 	elementType: string;
 	error: Error;
+	propertyType: 'prop' | 'style';
 } ) {
-	const { propertyName, elementId, elementType, error } = opts;
+	const { propertyName, elementId, elementType, error, propertyType } = opts;
 	return `Failed to update property "${ propertyName }" on element "${ elementId }": ${ error.message }.
+${
+	propertyType === 'prop'
+		? `
 Check the element's PropType schema at the resource [${ WIDGET_SCHEMA_URI.replace(
-		'{widgetType}',
-		elementType
-	) }] for type "${ elementType }" to ensure the property exists and the value matches the expected PropType.
-Now that you have this information, ensure you have the schema and try again.`;
+				'{widgetType}',
+				elementType
+		  ) }] for type "${ elementType }" to ensure the property exists and the value matches the expected PropType.
+Now that you have this information, ensure you have the schema and try again.`
+		: `
+Check the styles schema at the resource [${ STYLE_SCHEMA_URI.replace(
+				'{category}',
+				propertyName
+		  ) }] at editor-canvas__elementor://styles/schema/{category} to ensure the style property exists and the value matches the expected PropType.
+`
+};
+}`;
 }

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

@@ -8,11 +8,12 @@ const schema = {
 };
 
 const outputSchema = {
-	propValues: z
+	properties: z
 		.record( z.string(), z.any() )
-		.describe(
-			'A record mapping PropTypes to their corresponding PropValues, with _styles record for style-related PropValues'
-		),
+		.describe( 'A record mapping PropTypes to their corresponding PropValues' ),
+	style: z
+		.record( z.string(), z.any() )
+		.describe( 'A record mapping StyleSchema properties to their corresponding PropValues' ),
 };
 
 export const initGetElementConfigTool = ( reg: MCPRegistryEntry ) => {
@@ -29,7 +30,9 @@ export const initGetElementConfigTool = ( reg: MCPRegistryEntry ) => {
 				throw new Error( `Element with ID ${ elementId } not found.` );
 			}
 			const elementRawSettings = element.settings;
-			const propSchema = getWidgetsCache()?.[ element.model.get( 'widgetType' ) || '' ]?.atomic_props_schema;
+			const propSchema =
+				getWidgetsCache()?.[ element.model.get( 'widgetType' ) || element.model.get( 'elType' ) || '' ]
+					?.atomic_props_schema;
 
 			if ( ! elementRawSettings || ! propSchema ) {
 				throw new Error( `No settings or prop schema found for element ID: ${ elementId }` );
@@ -55,13 +58,18 @@ export const initGetElementConfigTool = ( reg: MCPRegistryEntry ) => {
 							stylePropValues[ stylePropName ] = structuredClone( styleProps[ stylePropName ] );
 						}
 					} );
+					if ( defaultVariant.custom_css ) {
+						stylePropValues.custom_css = atob( defaultVariant.custom_css.raw );
+					}
 				}
 			}
 
 			return {
-				propValues: {
+				properties: {
 					...propValues,
-					_styles: stylePropValues,
+				},
+				style: {
+					...stylePropValues,
 				},
 			};
 		},

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

@@ -5,13 +5,7 @@ import {
 	updateElementSettings,
 	updateElementStyle,
 } from '@elementor/editor-elements';
-import {
-	getPropSchemaFromCache,
-	type PropValue,
-	Schema,
-	stringPropTypeUtil,
-	type TransformablePropValue,
-} from '@elementor/editor-props';
+import { getPropSchemaFromCache, type PropValue, Schema, type TransformablePropValue } from '@elementor/editor-props';
 import { type CustomCss, getStylesSchema } from '@elementor/editor-styles';
 
 type OwnParams = {
@@ -22,9 +16,13 @@ type OwnParams = {
 };
 
 function resolvePropValue( value: unknown, forceKey?: string ): PropValue {
-	return Schema.adjustLlmPropValueSchema( value as PropValue, forceKey );
+	return Schema.adjustLlmPropValueSchema( value as PropValue, { forceKey } );
 }
 
+/*
+ * This function expects a PropValue bag for updaing 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 ) => {
 	const { elementId, propertyName, propertyValue, elementType } = params;
 
@@ -48,12 +46,12 @@ export const doUpdateElementProperty = ( params: OwnParams ) => {
 		Object.keys( propertyMapValue as Record< string, unknown > ).forEach( ( stylePropName ) => {
 			const propertyRawSchema = styleSchema[ stylePropName ];
 			if ( stylePropName === 'custom_css' ) {
-				let customCssValue = propertyMapValue[ stylePropName ] as object | string;
-				if ( typeof customCssValue === 'object' ) {
-					customCssValue =
-						stringPropTypeUtil.extract( customCssValue ) ||
-						( customCssValue as { value: unknown } )?.value ||
-						'';
+				let customCssValue = propertyMapValue[ stylePropName ] as Record< string, unknown > | string;
+				if ( typeof customCssValue === 'object' && customCssValue && customCssValue.value ) {
+					customCssValue = String( customCssValue.value );
+				}
+				if ( ! customCssValue ) {
+					customCssValue = '';
 				}
 				customCss = {
 					raw: btoa( customCssValue as string ),
@@ -62,7 +60,7 @@ export const doUpdateElementProperty = ( params: OwnParams ) => {
 			}
 			const isSupported = !! propertyRawSchema;
 			if ( ! isSupported ) {
-				throw new Error( `_styles property ${ stylePropName } is not supported.` );
+				throw new Error( `Style property ${ stylePropName } is not supported.` );
 			}
 			if ( propertyRawSchema.kind === 'plain' ) {
 				if ( typeof ( propertyMapValue as Record< string, unknown > )[ stylePropName ] !== 'object' ) {
@@ -74,6 +72,7 @@ export const doUpdateElementProperty = ( params: OwnParams ) => {
 				}
 			}
 		} );
+		delete transformedStyleValues.custom_css;
 		const localStyle = Object.values( elementStyles ).find( ( style ) => style.label === 'local' );
 		if ( ! localStyle ) {
 			createElementStyle( {
@@ -118,7 +117,8 @@ export const doUpdateElementProperty = ( params: OwnParams ) => {
 			) }`
 		);
 	}
-	const value = resolvePropValue( propertyValue );
+	const propKey = elementPropSchema[ propertyName ].key;
+	const value = resolvePropValue( propertyValue, propKey );
 	updateElementSettings( {
 		id: elementId,
 		props: {

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

@@ -0,0 +1,100 @@
+import { getWidgetsCache } from '@elementor/editor-elements';
+import { type PropsSchema, type PropValue, Schema } from '@elementor/editor-props';
+import { getStylesSchema } from '@elementor/editor-styles';
+
+let _widgetsSchema: Record< string, PropsSchema > | null = null;
+
+type ValidationResult = {
+	valid: boolean;
+	errors?: string[];
+};
+
+export const validateInput = {
+	get widgetsSchema(): Record< string, PropsSchema > {
+		if ( ! _widgetsSchema ) {
+			const schema: Record< string, PropsSchema > = {};
+			const cache = getWidgetsCache();
+			if ( ! cache ) {
+				return {};
+			}
+			Object.entries( cache ).forEach( ( [ widgetType, widgetData ] ) => {
+				if ( widgetData.atomic_props_schema ) {
+					schema[ widgetType ] = structuredClone( widgetData.atomic_props_schema );
+				}
+			} );
+			_widgetsSchema = schema;
+		}
+		return _widgetsSchema;
+	},
+
+	validateProps(
+		schema: PropsSchema | undefined | null,
+		values: Record< string, unknown >,
+		ignore: string[] = []
+	): ValidationResult {
+		if ( ! schema ) {
+			throw new Error( 'No schema provided for validation.' );
+		}
+		const errors: string[] = [];
+		let hasInvalidKey = false;
+		Object.entries( values ).forEach( ( [ propName, propValue ] ) => {
+			if ( ignore.includes( propName ) ) {
+				return;
+			}
+			const propSchema = schema[ propName ];
+			if ( ! propSchema ) {
+				errors.push( `Property "${ propName }" is not defined in the schema.` );
+				hasInvalidKey = true;
+			} else if ( ! Schema.isPropKeyConfigurable( propName ) ) {
+				errors.push( `Property "${ propName }" is not configurable.` );
+			} else {
+				const { valid, errorMessages } = Schema.validatePropValue( propSchema, propValue as PropValue );
+				if ( ! valid ) {
+					errors.push( `Invalid property "${ propName }": ${ errorMessages }` );
+				}
+			}
+		} );
+		if ( hasInvalidKey ) {
+			errors.push( 'Available properties: ' + Object.keys( schema ).join( ', ' ) );
+		}
+		return {
+			errors,
+			valid: errors.length === 0,
+		};
+	},
+
+	validateStyles( values: Record< string, unknown > ): ValidationResult {
+		const styleSchema = getStylesSchema();
+		const customCssValue = values.custom_css;
+		const result = this.validateProps( styleSchema, values, [ 'custom_css' ] );
+		const appendInvalidCustomCssErr = () => {
+			result.valid = false;
+			result.errors = result.errors || [];
+			result.errors.push( 'Invalid property "custom_css". Expected a string value.' );
+		};
+		if ( customCssValue && typeof customCssValue === 'object' ) {
+			if ( typeof ( customCssValue as Record< string, unknown > ).value !== 'string' ) {
+				appendInvalidCustomCssErr();
+			}
+		} else if (
+			typeof customCssValue !== 'string' &&
+			typeof customCssValue !== 'undefined' &&
+			customCssValue !== null
+		) {
+			appendInvalidCustomCssErr();
+		}
+		return result;
+	},
+
+	validatePropSchema(
+		widgetType: string,
+		values: Record< string, unknown >,
+		ignore: string[] = []
+	): ValidationResult {
+		const schema = this.widgetsSchema[ widgetType ];
+		if ( ! schema ) {
+			return { valid: false, errors: [ `No schema found for widget type "${ widgetType }".` ] };
+		}
+		return this.validateProps( schema, values, ignore );
+	},
+};