@elementor/editor-global-classes 3.35.0-470 → 3.35.0-472

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elementor/editor-global-classes",
-  "version": "3.35.0-470",
+  "version": "3.35.0-472",
   "private": false,
   "author": "Elementor Team",
   "homepage": "https://elementor.com/",
@@ -39,28 +39,28 @@
     "dev": "tsup --config=../../tsup.dev.ts"
   },
   "dependencies": {
-    "@elementor/editor": "3.35.0-470",
-    "@elementor/editor-current-user": "3.35.0-470",
-    "@elementor/editor-documents": "3.35.0-470",
-    "@elementor/editor-editing-panel": "3.35.0-470",
-    "@elementor/editor-mcp": "3.35.0-470",
-    "@elementor/editor-panels": "3.35.0-470",
-    "@elementor/editor-props": "3.35.0-470",
-    "@elementor/editor-variables": "3.35.0-470",
-    "@elementor/editor-styles": "3.35.0-470",
-    "@elementor/editor-canvas": "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/http-client": "3.35.0-470",
+    "@elementor/editor": "3.35.0-472",
+    "@elementor/editor-current-user": "3.35.0-472",
+    "@elementor/editor-documents": "3.35.0-472",
+    "@elementor/editor-editing-panel": "3.35.0-472",
+    "@elementor/editor-mcp": "3.35.0-472",
+    "@elementor/editor-panels": "3.35.0-472",
+    "@elementor/editor-props": "3.35.0-472",
+    "@elementor/editor-variables": "3.35.0-472",
+    "@elementor/editor-styles": "3.35.0-472",
+    "@elementor/editor-canvas": "3.35.0-472",
+    "@elementor/editor-styles-repository": "3.35.0-472",
+    "@elementor/editor-ui": "3.35.0-472",
+    "@elementor/editor-v1-adapters": "3.35.0-472",
+    "@elementor/http-client": "3.35.0-472",
     "@elementor/icons": "^1.63.0",
-    "@elementor/query": "3.35.0-470",
-    "@elementor/schema": "3.35.0-470",
-    "@elementor/store": "3.35.0-470",
+    "@elementor/query": "3.35.0-472",
+    "@elementor/schema": "3.35.0-472",
+    "@elementor/store": "3.35.0-472",
     "@elementor/ui": "1.36.17",
-    "@elementor/utils": "3.35.0-470",
+    "@elementor/utils": "3.35.0-472",
     "@wordpress/i18n": "^5.13.0",
-    "@elementor/mixpanel": "3.35.0-470"
+    "@elementor/mixpanel": "3.35.0-472"
   },
   "peerDependencies": {
     "react": "^18.3.1",

package/src/mcp-integration/classes-resource.ts

@@ -5,24 +5,27 @@ import { globalClassesStylesProvider } from '../global-classes-styles-provider';
 export const GLOBAL_CLASSES_URI = 'elementor://global-classes';
 
 export const initClassesResource = () => {
-	const { mcpServer, resource, waitForReady } = getMCPByDomain( 'canvas' );
+	const canvasMcpEntry = getMCPByDomain( 'canvas' );
+	const classesMcpEntry = getMCPByDomain( 'classes' );
 
-	resource(
-		'global-classes',
-		GLOBAL_CLASSES_URI,
-		{
-			description: 'Global classes list.',
-		},
-		async () => {
-			return {
-				contents: [ { uri: GLOBAL_CLASSES_URI, text: localStorage[ 'elementor-global-classes' ] ?? {} } ],
-			};
-		}
-	);
-
-	waitForReady().then( () => {
-		globalClassesStylesProvider.subscribe( () => {
-			mcpServer.sendResourceListChanged();
+	[ canvasMcpEntry, classesMcpEntry ].forEach( ( entry ) => {
+		const { mcpServer, resource, waitForReady } = entry;
+		resource(
+			'global-classes',
+			GLOBAL_CLASSES_URI,
+			{
+				description: 'Global classes list.',
+			},
+			async () => {
+				return {
+					contents: [ { uri: GLOBAL_CLASSES_URI, text: localStorage[ 'elementor-global-classes' ] ?? '{}' } ],
+				};
+			}
+		);
+		waitForReady().then( () => {
+			globalClassesStylesProvider.subscribe( () => {
+				mcpServer.sendResourceListChanged();
+			} );
 		} );
 	} );
 };

package/src/mcp-integration/index.ts

@@ -2,15 +2,15 @@ import { getMCPByDomain } from '@elementor/editor-mcp';
 
 import { initClassesResource } from './classes-resource';
 import initMcpApplyUnapplyGlobalClasses from './mcp-apply-unapply-global-classes';
-import { initCreateGlobalClass } from './mcp-create-global-class';
 import initMcpApplyGetGlobalClassUsages from './mcp-get-global-class-usages';
-import { initModifyGlobalClass } from './mcp-modify-global-class';
+import { initManageGlobalClasses } from './mcp-manage-global-classes';
 
 export const initMcpIntegration = () => {
-	const reg = getMCPByDomain( 'canvas' );
+	const reg = getMCPByDomain( 'classes', {
+		instructions: 'MCP server for management of Elementor global classes',
+	} );
 	initMcpApplyUnapplyGlobalClasses( reg );
 	initMcpApplyGetGlobalClassUsages( reg );
-	initCreateGlobalClass( reg );
-	initModifyGlobalClass( reg );
+	initManageGlobalClasses( reg );
 	initClassesResource();
 };

package/src/mcp-integration/mcp-apply-unapply-global-classes.ts

@@ -16,16 +16,29 @@ export default function initMcpApplyUnapplyGlobalClasses( server: MCPRegistryEnt
 			intelligencePriority: 0.7,
 			speedPriority: 0.8,
 		},
-		description: `Apply a global class to the current element
+		description: `Apply a global class to an element, enabling consistent styling through your design system.
 
 ## When to use this tool:
-- When a user requests to apply a global class or a class to an element in the Elementor editor.
-- When you need to add a specific class to an element's applied classes.
+**ALWAYS use this IMMEDIATELY AFTER building compositions** to apply the global classes you created beforehand:
+- After using "build-compositions" tool, apply semantic classes to the created elements
+- When applying consistent typography styles (heading-primary, text-body, etc.)
+- When applying theme colors or brand styles (bg-brand, button-cta, etc.)
+- When ensuring spacing consistency (spacing-section-large, etc.)
+
+**DO NOT use this tool** for:
+- Elements that don't share styles with other elements (use inline styles instead)
+- Layout-specific properties (those should remain inline in stylesConfig)
 
 ## Prerequisites:
-- Ensure you have the most up-to-date list of classes applied to the element to avoid duplicates.
-  List available at always up-to-date resource 'elementor://global-classes'.
-- Make sure you have the correct class ID that you want to apply.`,
+- **REQUIRED**: Get the list of available global classes from 'elementor://global-classes' resource
+- **REQUIRED**: Get element IDs from the composition XML returned by "build-compositions" tool
+- Ensure you have the most up-to-date list of classes applied to the element to avoid duplicates
+- Make sure you have the correct class ID that you want to apply
+
+## Best Practices:
+1. Apply multiple classes to a single element if needed (typography + color + spacing)
+2. After applying, the tool will remind you to remove duplicate inline styles from elementConfig
+3. Classes should describe purpose, not implementation (e.g., "heading-primary" not "big-red-text")`,
 		handler: async ( params ) => {
 			const { classId, elementId } = params;
 			const appliedClasses = doGetAppliedClasses( elementId );

package/src/mcp-integration/mcp-manage-global-classes.ts

@@ -0,0 +1,282 @@
+import { BREAKPOINTS_SCHEMA_URI, STYLE_SCHEMA_URI } from '@elementor/editor-canvas';
+import { type MCPRegistryEntry } from '@elementor/editor-mcp';
+import { type Props, Schema } from '@elementor/editor-props';
+import { type BreakpointId } from '@elementor/editor-responsive';
+import { getStylesSchema } from '@elementor/editor-styles';
+import { type StylesProvider } from '@elementor/editor-styles-repository';
+import { type Utils as IUtils } from '@elementor/editor-variables';
+import { z } from '@elementor/schema';
+
+import { globalClassesStylesProvider } from '../global-classes-styles-provider';
+import { saveGlobalClasses } from '../save-global-classes';
+import { GLOBAL_CLASSES_URI } from './classes-resource';
+
+// TODO: see https://elementor.atlassian.net/browse/ED-22513 for better cross-module access
+type XElementor = z.infer< z.ZodAny >;
+
+const schema = {
+	action: z.enum( [ 'create', 'modify', 'delete' ] ).describe( 'Operation to perform' ),
+	classId: z
+		.string()
+		.optional()
+		.describe( 'Global class ID (required for modify). Get from elementor://global-classes resource.' ),
+	globalClassName: z.string().optional().describe( 'Global class name (required for create)' ),
+	props: z
+		.record( z.any() )
+		.describe(
+			'key-value of style-schema PropValues. Available properties at dynamic resource "elementor://styles/schema/{property-name}"'
+		),
+	breakpoint: z
+		.nullable( z.string().describe( 'Responsive breakpoint name for styles. Defaults to desktop (null).' ) )
+		.default( null )
+		.describe( 'Responsive breakpoint name for styles. Defaults to desktop (null).' ),
+};
+
+const outputSchema = {
+	status: z.enum( [ 'ok', 'error' ] ).describe( 'Operation status' ),
+	classId: z.string().optional().describe( 'Class ID (returned on create success)' ),
+	message: z.string().optional().describe( 'Error details if status is error' ),
+};
+
+type InputSchema = z.infer< ReturnType< typeof z.object< typeof schema > > >;
+type OutputSchema = z.infer< ReturnType< typeof z.object< typeof outputSchema > > >;
+
+const handler = async ( input: InputSchema ): Promise< OutputSchema > => {
+	const { action, classId, globalClassName, props, breakpoint } = input;
+
+	if ( action === 'create' && ! globalClassName ) {
+		return {
+			status: 'error',
+			message: 'Create requires globalClassName',
+		};
+	}
+
+	if ( action === 'modify' && ! classId ) {
+		return {
+			status: 'error',
+			message: 'Modify requires classId',
+		};
+	}
+
+	if ( action === 'delete' && ! classId ) {
+		return {
+			status: 'error',
+			message: 'Delete requires classId',
+		};
+	}
+
+	const { create, update, delete: deleteClass } = globalClassesStylesProvider.actions;
+	if ( ! create || ! update || ! deleteClass ) {
+		return {
+			status: 'error',
+			message: 'Required actions not available',
+		};
+	}
+
+	const errors: string[] = [];
+	const stylesSchema = getStylesSchema();
+	const validProps = Object.keys( stylesSchema );
+
+	Object.keys( props ).forEach( ( key ) => {
+		const propType = stylesSchema[ key ];
+		if ( ! propType ) {
+			errors.push( `Property "${ key }" does not exist in styles schema.` );
+			return;
+		}
+		const { valid, jsonSchema } = Schema.validatePropValue( propType, props[ key ] );
+		if ( ! valid ) {
+			errors.push( `- Property "${ key }" has invalid value\n  Expected schema: ${ jsonSchema }\n` );
+		}
+	} );
+
+	if ( errors.length > 0 ) {
+		return {
+			status: 'error',
+			message: `Validation errors:\n${ errors.join( '\n' ) }\nAvailable Properties: ${ validProps.join(
+				', '
+			) }\nUpdate your input and try again.`,
+		};
+	}
+
+	// TODO: see https://elementor.atlassian.net/browse/ED-22513 for better cross-module access
+	const Utils = ( ( ( window as XElementor ).elementorV2 as XElementor ).editorVariables as XElementor )
+		.Utils as typeof IUtils;
+	Object.keys( props ).forEach( ( key ) => {
+		props[ key ] = Schema.adjustLlmPropValueSchema( props[ key ], {
+			transformers: Utils.globalVariablesLLMResolvers,
+		} );
+	} );
+
+	const breakpointValue = breakpoint ?? 'desktop';
+
+	try {
+		switch ( action ) {
+			case 'create':
+				const newClassId = await attemptCreate( {
+					props,
+					className: globalClassName,
+					stylesProvider: globalClassesStylesProvider,
+					breakpoint: breakpointValue as BreakpointId,
+				} );
+				return newClassId
+					? {
+							status: 'ok',
+							message: `created global class with ID ${ newClassId }`,
+					  }
+					: {
+							status: 'error',
+							message: 'error creating class',
+					  };
+			case 'modify':
+				const updated = await attemptUpdate( {
+					classId,
+					props,
+					stylesProvider: globalClassesStylesProvider,
+					breakpoint: breakpointValue as BreakpointId,
+				} );
+				return updated
+					? { status: 'ok', classId }
+					: {
+							status: 'error',
+							message: 'error modifying class',
+					  };
+			case 'delete':
+				const deleted = await attemptDelete( {
+					classId,
+					stylesProvider: globalClassesStylesProvider,
+				} );
+				return deleted
+					? { status: 'ok', message: `deleted global class with ID ${ classId }` }
+					: {
+							status: 'error',
+							message: 'error deleting class',
+					  };
+		}
+	} catch ( error ) {
+		return {
+			status: 'error',
+			message: `${ action } failed: ${ ( error as Error ).message || 'Unknown error' }`,
+		};
+	}
+};
+
+export const initManageGlobalClasses = ( reg: MCPRegistryEntry ) => {
+	const { addTool } = reg;
+
+	addTool( {
+		name: 'manage-global-classes',
+		requiredResources: [
+			{ uri: GLOBAL_CLASSES_URI, description: 'Global classes list' },
+			{ uri: STYLE_SCHEMA_URI, description: 'Style schema resources' },
+			{ uri: BREAKPOINTS_SCHEMA_URI, description: 'Breakpoints list' },
+		],
+		modelPreferences: {
+			intelligencePriority: 0.85,
+			speedPriority: 0.6,
+		},
+		description: `Manages global classes (create/modify) in Elementor editor. Check [elementor://global-classes] and style schemas first.
+
+CREATE: Requires globalClassName, props. Use semantic naming (heading-primary, button-cta, text-muted). Check existing classes to avoid duplicates. ALWAYS create global classes BEFORE compositions for reusable styles.
+MODIFY: Requires classId, props. Get classId from [elementor://global-classes] resource.
+
+Naming pattern: [element-type]-[purpose/variant]-[modifier]
+DO NOT create global classes for: one-off styles, layout-specific properties.
+
+Use style schema at [elementor://styles/schema/{category}] for valid props. Errors include exact schema mismatch details.`,
+		schema,
+		outputSchema,
+		handler,
+	} );
+};
+
+type Opts = {
+	stylesProvider: StylesProvider;
+	className?: string;
+	classId?: string;
+	breakpoint: BreakpointId;
+	props: Props;
+};
+
+async function attemptCreate( opts: Opts ) {
+	const { props, breakpoint, className, stylesProvider } = opts;
+	const { create, delete: deleteClass } = stylesProvider.actions;
+	if ( ! className ) {
+		throw new Error( 'Global class name is a required for creation' );
+	}
+	if ( ! create || ! deleteClass ) {
+		throw new Error( 'User is unable to create global classes' );
+	}
+	const newClassId = create( className, [
+		{
+			meta: {
+				breakpoint,
+				state: null,
+			},
+			custom_css: null,
+			props,
+		},
+	] );
+	try {
+		await saveGlobalClasses( { context: 'frontend' } );
+		return newClassId;
+	} catch {
+		deleteClass( newClassId );
+		return null;
+	}
+}
+
+async function attemptUpdate( opts: Opts ) {
+	const { props, breakpoint, classId, stylesProvider } = opts;
+	const { updateProps, update } = stylesProvider.actions;
+	if ( ! classId ) {
+		throw new Error( 'Class ID is required for modification' );
+	}
+	if ( ! updateProps || ! update ) {
+		throw new Error( 'User is unable to update global classes' );
+	}
+	const snapshot = structuredClone( stylesProvider.actions.all() );
+	try {
+		updateProps( {
+			id: classId,
+			props,
+			meta: {
+				breakpoint,
+				state: null,
+			},
+		} );
+		await saveGlobalClasses( { context: 'frontend' } );
+		return true;
+	} catch {
+		snapshot.forEach( ( style ) => {
+			update( {
+				id: style.id,
+				variants: style.variants,
+			} );
+		} );
+		await saveGlobalClasses( { context: 'frontend' } );
+		return false;
+	}
+}
+
+async function attemptDelete( opts: Pick< Opts, 'classId' | 'stylesProvider' > ) {
+	const { classId, stylesProvider } = opts;
+	const { delete: deleteClass, create } = stylesProvider.actions;
+	if ( ! classId ) {
+		throw new Error( 'Class ID is required for deletion' );
+	}
+	if ( ! deleteClass || ! create ) {
+		throw new Error( 'User is unable to delete global classes' );
+	}
+	const snapshot = structuredClone( stylesProvider.actions.all() );
+	const targetClass = snapshot.find( ( style ) => style.id === classId );
+	if ( ! targetClass ) {
+		throw new Error( `Class with ID "${ classId }" not found` );
+	}
+	try {
+		deleteClass( classId );
+		await saveGlobalClasses( { context: 'frontend' } );
+		return true;
+	} catch {
+		return false;
+	}
+}

package/src/mcp-integration/design-system/design-system-tool.ts

@@ -1,121 +0,0 @@
-import { STYLE_SCHEMA_URI } from '@elementor/editor-canvas';
-import { type MCPRegistryEntry } from '@elementor/editor-mcp';
-import { GLOBAL_VARIABLES_URI, service } from '@elementor/editor-variables';
-import { z } from '@elementor/schema';
-
-import { GLOBAL_CLASSES_URI } from '../classes-resource';
-import { handler, inputSchema as globalClassInputSchema } from '../mcp-create-global-class';
-
-export const initDesignSystemTool = ( reg: MCPRegistryEntry ) => {
-	const { addTool } = reg;
-
-	const schema = {
-		globalVariables: z
-			.array(
-				z.object( {
-					variableName: z.string().describe( 'The name of the global variable.' ),
-					variableType: z
-						.enum( [ 'global-color-variable', 'global-font-variable' ] )
-						.describe( 'The type of the global variable.' ),
-					value: z
-						.string()
-						.describe(
-							'The value of the global variable. For colors, use css applicable format. For fonts, use the font family name.'
-						),
-				} )
-			)
-			.default( [] ),
-		globalClasses: z.array( z.object( globalClassInputSchema ) ).default( [] ),
-	};
-
-	addTool( {
-		name: 'design-system',
-		requiredResources: [
-			{ uri: STYLE_SCHEMA_URI, description: 'Style schema template resource' },
-			{ uri: GLOBAL_CLASSES_URI, description: 'Global classes list' },
-			{ uri: GLOBAL_VARIABLES_URI, description: 'Global variables list' },
-		],
-		description: `Manages or Creates a comprehensive design system based on user requirements.
-# CRITICAL PRE-REQUISITES:
-- Must read the style schema at dynamic resource list ${ STYLE_SCHEMA_URI } to understand the valid properties and values that can be assigned to global classes and variables.
-- Must get the existing global classes from always up-to-date resource ${ GLOBAL_CLASSES_URI } to avoid duplication when creating new global classes.
-- Must get the existing global variables from always up-to-date resource 'elementor://global-variables' to avoid duplication when creating new global variables.
-
-# IMPORTANT
-- DO NOT create variables if already existing variables can be re-used.
-- DO NOT create global classes if already existing global classes can be re-used.
-
-# When to use this tool:
-- When a user requests to create or manage a design system for their website.
-- When you need to generate a cohesive set of design tokens, styles, and global classes.
-
-# When NOT to use this tool:
-- For simple style adjustments or individual component styling, use the appropriate styling tools instead.
-- For modifications or creations of small amount of global classes, use the "create-global-class" or "modify-global-class" tools instead.
-- When you need to create or modify global variables only, use the "create-global-variable" or "modify-global-variable" tools instead.
-
-# Parameters:
-- \`globalClasses\` (array, optional): A list of global classes to be created or updated. Each class should include a name and a set of style-schema PropValues.
-- \`globalVariables\` (array, optional): A list of global variables to be created or updated. Each variable should include a name, type, and value.
-
-# You Goal
-Every design system has a set of global variables and global classes.
-Your goal is to make sure the user has enough global classes to re-use across the site, and that the global variables are defined to support these classes.
-Most sites would need classes for:
-- Headings (at least 3 levels)
-- Texts (default, emphasis, info, etc).
-- Buttons (primary, secondary, etc).
-- Containers (cards, sections, etc).
-- Banners (important messages, alerts, etc).
-- Hero sections (main site intro, etc).
-
-Global Classes SHOULD HAVE meaningful names that reflect their purpose and usage.
-Global Classes SHOULD HAVE PROPERTIES.
-
-DO NOT PROVIDE EMPTY OBJECTS
-
-Example partial design system input:
-\`\`\`json
-{
-  "globalVariables": [{variableName: 'secondary-text', variableType: 'global-color-variable', value: '#666666'}],
-  "globalClasses": [
-    {
-      "globalClassName": "info-text",
-      "props": {
-        "background": {
-          "$$type": "background",
-          "value": {
-            "color": {
-              "$$type": "global-color-variable",
-              "value": "secondary-text"
-            }
-          }
-        }
-      }
-  } ]
-}
-\`\`\`
-
-You are encouraged to create even more if required to cover user requirements.
-Before you create any class, make sure there is not already an existing class that supports the same purpose, by checking the resource at uri elementor://global-classes
-
-Before creating global variables, read the list, in many cases there are already existing variables that can be re-used. The list is available at resource uri elementor://global-variables
-`,
-		schema,
-		handler: async ( params ) => {
-			const { globalClasses, globalVariables } = params;
-			for ( const globalVariable of globalVariables ) {
-				const { variableName, variableType, value } = globalVariable;
-				service.create( {
-					label: variableName,
-					type: variableType,
-					value,
-				} );
-			}
-			for ( const globalClass of globalClasses ) {
-				await handler( globalClass );
-			}
-			return 'done';
-		},
-	} );
-};