@elementor/editor-canvas 3.35.0-470 → 3.35.0-471

package/package.json

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

package/src/composition-builder/composition-builder.ts

@@ -0,0 +1,233 @@
+import {
+	createElement,
+	generateElementId,
+	getContainer,
+	getWidgetsCache,
+	type V1Element,
+} from '@elementor/editor-elements';
+import { type z } from '@elementor/schema';
+
+import { doUpdateElementProperty } from '../mcp/utils/do-update-element-property';
+import { validateInput } from '../mcp/utils/validate-input';
+
+type AnyValue = z.infer< z.ZodTypeAny >;
+type AnyConfig = Record< string, Record< string, AnyValue > >;
+
+type API = {
+	createElement: typeof createElement;
+	getWidgetsCache: typeof getWidgetsCache;
+	generateElementId: typeof generateElementId;
+	getContainer: typeof getContainer;
+	doUpdateElementProperty: typeof doUpdateElementProperty;
+};
+
+type CtorOptions = {
+	xml: Document;
+	api?: Partial< API >;
+	elementConfig?: AnyConfig;
+	stylesConfig?: AnyConfig;
+};
+
+export class CompositionBuilder {
+	private elementConfig: Record< string, Record< string, AnyValue > > = {};
+	private elementStylesConfig: Record< string, Record< string, AnyValue > > = {};
+	private rootContainers: V1Element[] = [];
+	private containerElements: string[] = [];
+	private api: API = {
+		createElement,
+		getWidgetsCache,
+		generateElementId,
+		getContainer,
+		doUpdateElementProperty,
+	};
+	private xml: Document;
+
+	public static fromXMLString( xmlString: string, api: Partial< API > = {} ): CompositionBuilder {
+		const parser = new DOMParser();
+		const xmlDoc = parser.parseFromString( xmlString, 'application/xml' );
+		const errorNode = xmlDoc.querySelector( 'parsererror' );
+		if ( errorNode ) {
+			throw new Error( 'Failed to parse XML string: ' + errorNode.textContent );
+		}
+		return new CompositionBuilder( {
+			xml: xmlDoc,
+			api,
+		} );
+	}
+
+	constructor( opts: CtorOptions ) {
+		const { api = {}, elementConfig = {}, stylesConfig = {}, xml } = opts;
+		this.xml = xml;
+		Object.assign( this.api, api );
+		this.setElementConfig( elementConfig );
+		this.setStylesConfig( stylesConfig );
+	}
+
+	setElementConfig( config: Record< string, Record< string, AnyValue > > ) {
+		this.elementConfig = config;
+	}
+
+	setStylesConfig( config: Record< string, Record< string, AnyValue > > ) {
+		this.elementStylesConfig = config;
+	}
+
+	getXML() {
+		return this.xml;
+	}
+
+	private iterateBuild( node: Element, containerElement: V1Element, childIndex: number ) {
+		const elementTag = node.tagName;
+		const isContainer = this.containerElements.includes( elementTag );
+		const parentElType = containerElement.model.get( 'elType' );
+		let targetContainerId =
+			parentElType === 'e-tabs'
+				? containerElement.children?.[ 1 ].children?.[ childIndex ]?.id || containerElement.children?.[ 1 ].id
+				: containerElement.id;
+		if ( ! targetContainerId ) {
+			targetContainerId = containerElement.id;
+		}
+		const newElement = isContainer
+			? this.api.createElement( {
+					containerId: targetContainerId,
+					model: {
+						elType: elementTag,
+						id: generateElementId(),
+					},
+					options: { useHistory: false },
+			  } )
+			: this.api.createElement( {
+					containerId: targetContainerId,
+					model: {
+						elType: 'widget',
+						widgetType: elementTag,
+						id: generateElementId(),
+					},
+					options: { useHistory: false },
+			  } );
+		if ( containerElement.id === 'document' ) {
+			this.rootContainers.push( newElement );
+		}
+		node.setAttribute( 'id', newElement.id );
+		let currentChild = 0;
+		for ( const childNode of Array.from( node.children ) ) {
+			this.iterateBuild( childNode, newElement, currentChild );
+			currentChild++;
+		}
+	}
+
+	private findSchemaForNode( node: Element ) {
+		const widgetsCache = this.api.getWidgetsCache() || {};
+		const widgetType = node.tagName;
+		const widgetData = widgetsCache[ widgetType ]?.atomic_props_schema;
+		return widgetData || null;
+	}
+
+	private matchNodeByConfigId( configId: string ) {
+		const node = this.xml.querySelector( `[configuration-id="${ configId }"]` );
+		if ( ! node ) {
+			throw new Error( `Configuration id "${ configId }" does not have target node.` );
+		}
+		const id = node.getAttribute( 'id' );
+		if ( ! id ) {
+			throw new Error( `Node with configuration id "${ configId }" does not have element id.` );
+		}
+		const element = this.api.getContainer( id );
+		if ( ! element ) {
+			throw new Error( `Element with id "${ id }" not found but should exist.` );
+		}
+		return {
+			element,
+			node,
+		};
+	}
+
+	applyStyles() {
+		const errors: string[] = [];
+		const invalidStyles: Record< string, string[] > = {};
+		const validStylesPropValues: Record< string, AnyValue > = {};
+		for ( const [ styleId, styleConfig ] of Object.entries( this.elementStylesConfig ) ) {
+			const { element, node } = this.matchNodeByConfigId( styleId );
+			for ( const [ styleName, stylePropValue ] of Object.entries( styleConfig ) ) {
+				const { valid, errors: validationErrors } = validateInput.validateStyles( {
+					[ styleName ]: stylePropValue,
+				} );
+				if ( ! valid ) {
+					if ( styleConfig.$intention ) {
+						invalidStyles[ element.id ] = invalidStyles[ element.id ] || [];
+						invalidStyles[ element.id ].push( styleName );
+					}
+					errors.push( ...( validationErrors || [] ) );
+				} else {
+					validStylesPropValues[ styleName ] = stylePropValue;
+				}
+				this.api.doUpdateElementProperty( {
+					elementId: element.id,
+					propertyName: '_styles',
+					propertyValue: validStylesPropValues,
+					elementType: node.tagName,
+				} );
+			}
+		}
+		return {
+			errors,
+			invalidStyles,
+		};
+	}
+
+	applyConfigs() {
+		const errors: string[] = [];
+		for ( const [ configId, config ] of Object.entries( this.elementConfig ) ) {
+			const { element, node } = this.matchNodeByConfigId( configId );
+			const propSchema = this.findSchemaForNode( node );
+			const result = validateInput.validateProps( propSchema, config );
+			if ( ! result.valid && result.errors?.length ) {
+				errors.push( ...result.errors );
+			} else {
+				for ( const [ propertyName, propertyValue ] of Object.entries( config ) ) {
+					try {
+						this.api.doUpdateElementProperty( {
+							elementId: element.id,
+							propertyName,
+							propertyValue,
+							elementType: node.tagName,
+						} );
+					} catch ( error ) {
+						errors.push( ( error as Error ).message );
+					}
+				}
+			}
+		}
+		return errors;
+	}
+
+	build( rootContainer: V1Element ) {
+		const widgetsCache = this.api.getWidgetsCache() || {};
+		const CONTAINER_ELEMENTS = Object.values( widgetsCache )
+			.filter( ( widget ) => widget.meta?.is_container )
+			.map( ( widget ) => widget.elType )
+			.filter( ( x ) => typeof x === 'string' );
+		this.containerElements = CONTAINER_ELEMENTS;
+		new Set( this.xml.querySelectorAll( '*' ) ).forEach( ( node ) => {
+			if ( ! widgetsCache[ node.tagName ] ) {
+				throw new Error( `Unknown widget type: ${ node.tagName }` );
+			}
+		} );
+
+		const children = Array.from( this.xml.children );
+		let currentChild = 0;
+		for ( const childNode of children ) {
+			this.iterateBuild( childNode, rootContainer, currentChild );
+			currentChild++;
+		}
+
+		const { errors: styleErrors, invalidStyles } = this.applyStyles();
+		const configErrors = this.applyConfigs();
+
+		return {
+			configErrors,
+			styleErrors,
+			invalidStyles,
+			rootContainers: [ ...this.rootContainers ],
+		};
+	}
+}

package/src/mcp/mcp-description.ts

@@ -2,121 +2,112 @@ import { STYLE_SCHEMA_URI, WIDGET_SCHEMA_URI } from './resources/widgets-schema-
 
 const ELEMENT_SCHEMA_URI = WIDGET_SCHEMA_URI.replace( '{widgetType}', 'element-schema' );
 
-export const mcpDescription = `Canvas MCP
-This MCP enables everything related to creation, configuration, and styling of elements on the Elementor canvas.
+export const mcpDescription = `Elementor Canvas MCP
+This MCP enables creation, configuration, and styling of elements on the Elementor canvas using the build_composition tool.
 
-# Design Systems in Elementor
-- Elementor presents global classes. Each global class is a a set of styles that can be applied to multiple elements. This allows for consistent styling across the design.
-- Elementor also presents global variables, which can be colors, sizes or fonts. These variables can be used in any element's styles, or global classes, allowing for easy updates and consistency across the design.
-- All data is stored in a PropValue structure, which is a wrapper for elementor values. The PropValues are derived from an internal "PropType" schema, which defines the structure and types of the values.
+# Core Concepts
 
-# PropValues structure and usage
+## PropValues Structure
+All data in Elementor uses PropValues - a typed wrapper for values:
 \`\`\`json
 {
-  $$type: 'the-prop-type-schema-kind',
-  value: 'the-actual-value-as-defined-for-the-propType'
+  "$$type": "the-prop-type-schema-kind",
+  "value": "the-actual-value-as-defined-for-the-propType"
 }
 \`\`\`
-The "value" property can be an object, string, number, boolean, array, etc. The $$type defines the kind of value, and the value is the actual value.
-It is critical to provide the correct $$type for each value, as it defines how Elementor will interpret the value or reject it.
-
-All widgets properties and configuration is built from sets of PropValues, which can be retreived from the resource [${ WIDGET_SCHEMA_URI }].
-All styles are SHARED ACCROSS widgets, containers and components, and are defined in a common styles schema, retreivable from the resource [${ STYLE_SCHEMA_URI }].
-The style schema also defines the global classes.
-
-To understand the configuration options for an element, refer to the PropType schema for that specific element. For example: "e-heading" configuration schema is available at the resource [${ WIDGET_SCHEMA_URI }/e-heading]
-
-# Modifying elements and styles
-When configuring an element, elementor does a MERGE PROPERTIES operation, which means that only the properties you provide will be updated, and the rest will remain as is.
-For deleting a property, the value must be set to null, instead of a PropValue. When adding a configuration, no need to provide the full configuration, only the properties you want to add or update.
-The same rule applies to styles as well and modifications to global classes.
-
-# Building full compositions
-The "build-composition" tool allows creating multiple elements in a single operation.
-The tool accepts both the structure, the styling and the configuration of each element to be created.
-
-- First step: Retreive the available widgets by listing the [${ WIDGET_SCHEMA_URI }] dynamic resource.
-- Second step: decide which elements to create, and their configuration and styles.
-  Retrieve the used elements configuration schema from the resource [${ ELEMENT_SCHEMA_URI }]
-- Third step: define the styles for each element, using the common styles schema from the resource [${ STYLE_SCHEMA_URI }]. List the resource to see all available style properties.
-
-## Workflow for build-compositions tool
-1. **Parse user requirements** - Undestand what needs to be built (structure, content, styling).
-2. ** Check global resources FIRST** - Always check before building:
-   - List \`elementor://global-classes\` to see if the needed global classes already exist.
-   - List \`elementor://global-variables\` to see if the needed global variables already exist.
-   - **Preference**: Use existing global classes and variables over creating new inline styles.
-3. **Retreive widget schemas** - For each widget you will use:
-   - List [${ WIDGET_SCHEMA_URI }] to see available widgets.
-   - Retrieve configuration schema from [${ ELEMENT_SCHEMA_URI }] for each widget to understand required properties.
-   - Understand if a widget is a container (can have children) by checking the "llm_guidance" property in the widget's schema.
-4. **Build XML structure** - Create valid XML width configuration-ids:
-   - Every element has unique configuration-id attribute
-   - No text nodes, classes, IDs in XML.
-   
-5. **Create elementConfig** - For each configuration-id:
-   - Use PropValues with corrent \`$$type\` matching the schema.
-   - **Use global variables** in PropValues where applicable
-
-6. **Create stylesConfig** - For each configuration-id:
-   - Use style schema PropValues from [${ STYLE_SCHEMA_URI }]
-   - **Use global variables** for colors, sizes, fonts where applicable
-   - **Important**: Global classes are applied AFTER building the composition. Once built, apply classes using the "apply-global-class" tool - after completion of building the composition.
-
-7. **Validate** - Ensure:
-   - XML structure is valid
-   - All PropValues have corrent \`$$type\`
-   - After building a composition, you can retreive each element configuration using the "get-element-configuration-values" tool to verify correctness, using the IDs returned from the build-composition tool.
-
-## Key relationships:
-- **XML structure**: Defines the hierarchy of elements/widgets
-- **elementConfig**: Maps configuration-id to widget PropValues
-- **stylesConfig**: Maps configuration-id to style PropValues
-
-## Using global variables example:
-Existing global variables can be used during composition
+The \`$$type\` defines how Elementor interprets the value. Providing the correct \`$$type\` is critical - incorrect types will be rejected.
+
+## Design System Resources
+- **Global Variables**: Reusable colors, sizes, and fonts (\`elementor://global-variables\`)
+- **Global Classes**: Reusable style sets that can be applied to elements (\`elementor://global-classes\`)
+- **Widget Schemas**: Configuration options for each widget type (\`${ WIDGET_SCHEMA_URI }\`)
+- **Style Schema**: Common styles shared across all widgets and containers (\`${ STYLE_SCHEMA_URI }\`)
+
+# Building Compositions with build_composition
+
+The \`build_composition\` tool is the primary way to create elements. It accepts structure (XML), configuration, and styling in a single operation.
+
+## Complete Workflow
+
+### 1. Parse User Requirements
+Understand what needs to be built: structure, content, and styling.
+
+### 2. Check Global Resources FIRST
+Always check existing resources before building:
+- List \`elementor://global-variables\` for available variables (colors, sizes, fonts)
+- List \`elementor://global-classes\` for available style sets
+- **Always prefer using existing global resources over creating inline styles**
+
+### 3. Retrieve Widget Schemas
+For each widget you'll use:
+- List \`${ WIDGET_SCHEMA_URI }\` to see available widgets
+- Retrieve configuration schema from \`${ ELEMENT_SCHEMA_URI }\` for each widget
+- Check the \`llm_guidance\` property to understand if a widget is a container (can have children)
+
+### 4. Build XML Structure
+Create valid XML with configuration-ids:
+- Each element must have a unique \`configuration-id\` attribute
+- No text nodes, classes, or IDs in XML - structure only
+- Example:
+\`\`\`xml
+<e-container configuration-id="container-1">
+  <e-heading configuration-id="heading-1" />
+  <e-text configuration-id="text-1" />
+</e-container>
+\`\`\`
+
+### 5. Create elementConfig
+Map each configuration-id to its widget properties using PropValues:
+- Use correct \`$$type\` matching the widget's schema
+- Use global variables in PropValues where applicable
+- Example:
+\`\`\`json
+{
+  "heading-1": {
+    "text": { "$$type": "string", "value": "Welcome" },
+    "tag": { "$$type": "string", "value": "h1" }
+  }
+}
+\`\`\`
+
+### 6. Create stylesConfig
+Map each configuration-id to style PropValues from \`${ STYLE_SCHEMA_URI }\`:
+- Use global variables for colors, sizes, and fonts
+- Example using global variable:
 \`\`\`json
-{ "color": { "$$type": "global-color-variable", "value": "global-variable-id" } }
+{
+  "heading-1": {
+    "color": { "$$type": "global-color-variable", "value": "primary-color-id" },
+    "font-size": { "$$type": "size", "value": "2rem" }
+  }
+}
 \`\`\`
 
-# Configuring Elements / Adding Style to Elements
-An element configuration can be retrieved using the "get-element-configuration-values" tool.
-Updating an element requires only the UPDATED properties (including in the styles), as Elementor does a MERGE/PATCH operation.
-
-<note>
-for PropValue with array as value:
-All array types that can receive union types, are typed as mixed array.
-</note>
-
-# Styling best practices
-Prefer using "em" and "rem" values for text-related sizes, padding and spacing. Use percentages for dynamic sizing relative to parent containers.
-This flexboxes are by default "flex" with "stretch" alignment. To ensure proper layout, define the "justify-content" and "align-items" as in the schema.
-
-# Examples:
-
-## e-image PropValue structure:
-{$$type:'image',value:{src:{$$type:'image-src',value:{url:{$$type:'url',value:'https://example.com/image.jpg'}}},size:{$$type:'string',value:'full'}}}
-
-Widgets' sizes MUST be defined using the style schema. Images, for example, have a "size" property, but it DOES NOT AFFECT THE VISUAL size, but rather the image size/resolution to load.
-
-# Working with Global Classes and Variables
-- To get the list of available global classes, use the resource at uri elementor://global-classes
-- To get the list of available global variables, use the resource at uri elementor://global-variables
-- Before creating a global variable or class, refer to the list and see if it already exists.
-- Naming conventions:
-  - Global classes and global variables should have meaningful names that reflect their purpose and usage.
-  - Avoid generic names like "style1" or "classA"; instead, use descriptive names like "primary-button" or "heading-level-1".
-  - Avoid names that reflect colors or values, use only purpose-based names.
-
-# Advanced operations
-You are encouraged to run multiple times multiple tools to achieve the desired result.
-
-An Example scenario of creating fully styled composition:
-1. Get the list of availble widgets using dynamic resource [${ WIDGET_SCHEMA_URI }]
-2. For each element to create, retreive its configuration schema from [${ WIDGET_SCHEMA_URI }/element-name]
-3. Get the list of available global classes using the always up-to-date resource 
-4. Get the list of available global variables using the dynamic resource
-5. Build a composition using the "build-composition" tool, providing the structure, configuration and styles for each element. You may want to style the elements later.
-6. Check you work: as you have the created IDs from the build-composition response, you can retreive each element configuration using the "get-element-configuration-values" tool.
-7. If needed, update styles using the "configure-element" tool, providing only the styles or widget's properties to update.
+### 7. Execute build_composition
+Call the tool with your XML structure, elementConfig, and stylesConfig. The response will contain the created element IDs.
+At the response you will also find llm_instructions for you to do afterwards, read and follow them!
+
+## Key Points
+
+- **PropValue Types**: Arrays that accept union types are typed as mixed arrays
+- **Visual Sizing**: Widget sizes MUST be defined in stylesConfig. Widget properties like image "size" control resolution, not visual appearance
+- **Global Variables**: Reference by ID in PropValues (e.g., \`{ "$$type": "global-color-variable", "value": "variable-id" }\`)
+- **Naming Conventions**: Use meaningful, purpose-based names (e.g., "primary-button", "heading-large"), not value-based names (e.g., "blue-style", "20px-padding")
+
+## Example: e-image PropValue Structure
+\`\`\`json
+{
+  "$$type": "image",
+  "value": {
+    "src": {
+      "$$type": "image-src",
+      "value": {
+        "url": { "$$type": "url", "value": "https://example.com/image.jpg" }
+      }
+    },
+    "size": { "$$type": "string", "value": "full" }
+  }
+}
+\`\`\`
+Note: The "size" property controls image resolution/loading, not visual size. Set visual dimensions in stylesConfig.
 `;

package/src/mcp/resources/widgets-schema-resource.ts

@@ -38,7 +38,7 @@ The css string must follow standard CSS syntax, with properties and values separ
 		'styles-schema',
 		new ResourceTemplate( STYLE_SCHEMA_URI, {
 			list: () => {
-				const categories = [ ...Object.keys( getStylesSchema() ) ];
+				const categories = [ ...Object.keys( getStylesSchema() ) ].filter( ( category ) => category !== 'all' );
 				return {
 					resources: categories.map( ( category ) => ( {
 						uri: `elementor://styles/schema/${ category }`,