@elementor/editor-variables 4.2.0-876 → 4.2.0-877

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elementor/editor-variables",
-  "version": "4.2.0-876",
+  "version": "4.2.0-877",
   "private": false,
   "author": "Elementor Team",
   "homepage": "https://elementor.com/",
@@ -39,22 +39,22 @@
     "dev": "tsup --config=../../tsup.dev.ts"
   },
   "dependencies": {
-    "@elementor/editor": "4.2.0-876",
-    "@elementor/editor-canvas": "4.2.0-876",
-    "@elementor/editor-controls": "4.2.0-876",
-    "@elementor/editor-current-user": "4.2.0-876",
-    "@elementor/editor-mcp": "4.2.0-876",
-    "@elementor/editor-panels": "4.2.0-876",
-    "@elementor/editor-props": "4.2.0-876",
-    "@elementor/editor-ui": "4.2.0-876",
-    "@elementor/editor-v1-adapters": "4.2.0-876",
-    "@elementor/menus": "4.2.0-876",
-    "@elementor/http-client": "4.2.0-876",
+    "@elementor/editor": "4.2.0-877",
+    "@elementor/editor-canvas": "4.2.0-877",
+    "@elementor/editor-controls": "4.2.0-877",
+    "@elementor/editor-current-user": "4.2.0-877",
+    "@elementor/editor-mcp": "4.2.0-877",
+    "@elementor/editor-panels": "4.2.0-877",
+    "@elementor/editor-props": "4.2.0-877",
+    "@elementor/editor-ui": "4.2.0-877",
+    "@elementor/editor-v1-adapters": "4.2.0-877",
+    "@elementor/menus": "4.2.0-877",
+    "@elementor/http-client": "4.2.0-877",
     "@elementor/icons": "~1.75.1",
-    "@elementor/events": "4.2.0-876",
-    "@elementor/schema": "4.2.0-876",
+    "@elementor/events": "4.2.0-877",
+    "@elementor/schema": "4.2.0-877",
     "@elementor/ui": "1.37.5",
-    "@elementor/utils": "4.2.0-876",
+    "@elementor/utils": "4.2.0-877",
     "@wordpress/i18n": "^5.13.0"
   },
   "peerDependencies": {

package/src/mcp/manage-variable-tool.ts

@@ -1,30 +1,78 @@
 import { type MCPRegistryEntry } from '@elementor/editor-mcp';
 import { z } from '@elementor/schema';
+import { isProActive } from '@elementor/utils';
 
 import { service } from '../service';
 import { validateLabel } from '../utils/validations';
+import { generateVariablesPrompt, MANAGE_VARIABLES_GUIDE_URI } from './variable-tool-prompt';
 import { GLOBAL_VARIABLES_URI } from './variables-resource';
 
+const VARIABLE_TYPES = {
+	COLOR: 'global-color-variable',
+	FONT: 'global-font-variable',
+	SIZE: 'global-size-variable',
+	CUSTOM_SIZE: 'global-custom-size-variable',
+} as const;
+
+const LENGTH_UNIT_PATTERN = /^(auto|\d+(\.\d+)?(px|rem|em|vh|vw|%|ch|s|ms))$/i;
+const COLOR_PATTERN = /^(#[0-9a-f]{3,8}|rgba?\(|hsl)/i;
+
+function validateValueForType( type: string, value: string ): string | null {
+	if ( type === VARIABLE_TYPES.FONT && LENGTH_UNIT_PATTERN.test( value.trim() ) ) {
+		return `Font variable value must be a font family name (e.g. "Roboto"), not a size value like "${ value }". Use "global-size-variable" or "global-custom-size-variable" for spacing/size values.`;
+	}
+
+	if ( type === VARIABLE_TYPES.COLOR && ! COLOR_PATTERN.test( value.trim() ) ) {
+		return `Color variable value should be a CSS color (e.g. "#FF0000"), got "${ value }".`;
+	}
+
+	if ( type === VARIABLE_TYPES.SIZE && ! LENGTH_UNIT_PATTERN.test( value.trim() ) ) {
+		return `Size variable value should include a CSS unit (e.g. "16px") or be "auto", got "${ value }".`;
+	}
+
+	return null;
+}
+
 export const initManageVariableTool = ( reg: MCPRegistryEntry ) => {
-	const { addTool } = reg;
+	const { addTool, resource } = reg;
+
+	resource(
+		'manage-global-variable-guide',
+		MANAGE_VARIABLES_GUIDE_URI,
+		{
+			title: 'Manage Global Variable Guide',
+			description: 'Detailed guide for using the manage-global-variable tool',
+			mimeType: 'text/plain',
+		},
+		async ( uri: URL ) => ( {
+			contents: [ { uri: uri.href, mimeType: 'text/plain', text: generateVariablesPrompt() } ],
+		} )
+	);
+
 	addTool( {
 		name: 'manage-global-variable',
+		description: 'Manage V4 global variables (color, font, size). Read the guide resource before use.',
 		schema: {
 			action: z.enum( [ 'create', 'update', 'delete' ] ).describe( 'Operation to perform' ),
 			id: z
 				.string()
 				.optional()
-				.describe( 'Variable id (required for update/delete). Get from list-global-variables.' ),
+				.describe( 'Variable id — required for update/delete. Get from the global-variables resource.' ),
 			type: z
 				.string()
 				.optional()
-				.describe( 'Variable type: "global-color-variable" or "global-font-variable" (required for create)' ),
-			label: z.string().optional().describe( 'Variable label (required for create/update)' ),
+				.describe(
+					'Variable type — required for create. One of: "global-color-variable", "global-font-variable", "global-size-variable", "global-custom-size-variable" (size types require Elementor Pro). NEVER store px/rem values in a font variable.'
+				),
+			label: z
+				.string()
+				.optional()
+				.describe( 'Variable label (lowercase, dash-separated) — required for create/update.' ),
 			value: z
 				.string()
 				.optional()
 				.describe(
-					'The variable value (required for create/update). Provide a plain CSS value matching the variable type (font: family name; color: CSS color; size: value with unit). Never JSON.'
+					'Plain CSS value — required for create/update. Color: hex/rgba/hsl. Font: family name only, never px/rem. Size: value with unit e.g. "16px", or "auto" (Pro). Do NOT pass JSON.'
 				),
 		},
 		outputSchema: {
@@ -32,28 +80,22 @@ export const initManageVariableTool = ( reg: MCPRegistryEntry ) => {
 			message: z.string().optional().describe( 'Error details if status is error' ),
 		},
 		requiredResources: [
+			{ uri: MANAGE_VARIABLES_GUIDE_URI, description: 'Full guide for variable types, naming rules, and usage' },
 			{
 				uri: GLOBAL_VARIABLES_URI,
-				description: 'Global variables',
+				description: 'Current global variables — check before creating to avoid duplicates',
 			},
 		],
-		description: `Create, update, or delete V4 global variables (distinct from legacy "globals").
-- Values: any valid CSS value, inserted as-is (1:1 with \`--css-var: VALUE\`). Do NOT pass JSON or legacy-globals object structures.
-- Names: lowercase, dash-separated (e.g. "Headline Primary" → "headline-primary").
-- Update: when renaming, keep the existing value; when updating value, keep the exact label.
-- Delete: destructive — confirm with user first.`,
+		isDestructive: true,
 		handler: async ( params ) => {
 			const operations = getServiceActions( service );
 			const op = operations[ params.action ];
 			if ( op ) {
 				await op( params );
-				return {
-					status: 'ok',
-				};
+				return { status: 'ok' };
 			}
 			throw new Error( `Unknown action ${ params.action }` );
 		},
-		isDestructive: true, // Because delete is destructive
 	} );
 };
 
@@ -67,10 +109,17 @@ function getServiceActions( svc: typeof service ) {
 			if ( ! type || ! label || ! value ) {
 				throw new Error( 'Create requires type, label, and value' );
 			}
+			if ( ( type === VARIABLE_TYPES.SIZE || type === VARIABLE_TYPES.CUSTOM_SIZE ) && ! isProActive() ) {
+				throw new Error( 'Creating size variables requires Elementor Pro.' );
+			}
 			const labelError = validateLabel( label );
 			if ( labelError ) {
 				throw new Error( labelError );
 			}
+			const valueError = validateValueForType( type, value );
+			if ( valueError ) {
+				throw new Error( valueError );
+			}
 			return svc.create( { type, label, value } );
 		},
 		update( { id, label, value }: Opts< { id: string; label: string; value: string } > ) {
@@ -81,6 +130,13 @@ function getServiceActions( svc: typeof service ) {
 			if ( labelError ) {
 				throw new Error( labelError );
 			}
+			const existingVariable = svc.variables()[ id ];
+			if ( existingVariable ) {
+				const valueError = validateValueForType( existingVariable.type, value );
+				if ( valueError ) {
+					throw new Error( valueError );
+				}
+			}
 			return svc.update( id, { label, value } );
 		},
 		delete( { id }: Opts< { id: string } > ) {

package/src/mcp/variable-tool-prompt.ts

@@ -0,0 +1,85 @@
+import { toolPrompts } from '@elementor/editor-mcp';
+import { isProActive } from '@elementor/utils';
+
+export const MANAGE_VARIABLES_GUIDE_URI = 'elementor://variables/tools/manage-global-variable-guide';
+
+export const generateVariablesPrompt = () => {
+	const prompt = toolPrompts( 'manage-global-variable' );
+	const proIsActive = isProActive();
+
+	const sizeVariableSection = proIsActive
+		? `- **global-size-variable** — A simple CSS length with a unit (Elementor Pro). Use this for fixed spacing, font sizes, or layout values. Example: \`16px\`, \`1.5rem\`, \`2em\`, \`10vh\`
+- **global-custom-size-variable** — Any CSS size expression that goes beyond a simple number + unit (Elementor Pro). Use this when the value is a CSS function, a keyword, or a combination of units that \`global-size-variable\` cannot represent. Example: \`auto\`, \`clamp(1rem, 2vw, 2rem)\`, \`calc(100% - 32px)\`, \`min(50vw, 600px)\`, \`300ms\`, \`2ch\`. When in doubt: if the value contains a function call or a keyword, use \`global-custom-size-variable\`.`
+		: `- ~~global-size-variable~~ — requires Elementor Pro (not available on this site)
+- ~~global-custom-size-variable~~ — requires Elementor Pro (not available on this site)`;
+
+	prompt.description( `
+# Purpose
+Create, update, or delete V4 global CSS variables. These are distinct from legacy v3 globals and map 1:1 to \`--css-var: VALUE\`.
+
+# Available Types
+- **global-color-variable** — CSS color value. Example: \`#FF0000\`, \`rgba(255,0,0,1)\`, \`hsl(0,100%,50%)\`
+- **global-font-variable** — Font family name ONLY — NOT a size or px value. Example: \`Roboto\`, \`Open Sans\`. NEVER pass px/rem here.
+${ sizeVariableSection }
+
+# Naming Rules
+- Labels must be **lowercase**, using only letters (a-z), numbers, digits (0-9), dashes (-), or underscores (_)
+- No spaces, no special characters
+- Example: "Headline Primary" → \`headline-primary\`
+- Labels must be unique — always check [elementor://global-variables] first
+
+# Value Rules
+- Provide a **plain CSS value** only — do NOT pass JSON, legacy-globals object structures, or variable references
+- Values are inserted as-is: \`--css-var: <value>\`
+- NEVER store a px/rem value inside a \`global-font-variable\` — use \`global-size-variable\` (Pro) instead
+
+# Operations
+- **create** — requires \`type\`, \`label\`, \`value\`. Label must be unique.
+- **update** — requires \`id\`, \`label\`, \`value\`. Get \`id\` from [elementor://global-variables]. When renaming: keep existing value. When changing value: keep exact existing label.
+- **delete** — requires \`id\`. DESTRUCTIVE — always confirm with user before executing.
+` );
+
+	prompt.parameter( 'action', '"create", "update", or "delete".' );
+	prompt.parameter( 'type', 'Variable type. Required for create. See Available Types above.' );
+	prompt.parameter( 'label', 'Variable name (lowercase, dash-separated). Required for create/update.' );
+	prompt.parameter(
+		'value',
+		'Plain CSS value matching the variable type. Required for create/update. Do NOT pass JSON.'
+	);
+	prompt.parameter( 'id', 'Variable ID. Required for update/delete. Obtain from [elementor://global-variables].' );
+
+	prompt.example( `
+Create a brand color:
+{ "action": "create", "type": "global-color-variable", "label": "brand-primary", "value": "#1A73E8" }
+
+Create a heading font:
+{ "action": "create", "type": "global-font-variable", "label": "font-heading", "value": "Playfair Display" }
+
+Create a simple spacing size:
+{ "action": "create", "type": "global-size-variable", "label": "spacing-md", "value": "16px" }
+
+Create a fluid/responsive size using a CSS function (use global-custom-size-variable, NOT global-size-variable):
+{ "action": "create", "type": "global-custom-size-variable", "label": "spacing-fluid", "value": "clamp(1rem, 2vw, 2rem)" }
+
+Create a size that is a keyword:
+{ "action": "create", "type": "global-custom-size-variable", "label": "width-auto", "value": "auto" }
+
+Create a size using calc():
+{ "action": "create", "type": "global-custom-size-variable", "label": "sidebar-width", "value": "calc(100% - 32px)" }
+
+Update a variable's value (keep exact label):
+{ "action": "update", "id": "abc123", "label": "brand-primary", "value": "#0D47A1" }
+
+Rename a variable (keep existing value):
+{ "action": "update", "id": "abc123", "label": "brand-secondary", "value": "#1A73E8" }
+
+Delete a variable:
+{ "action": "delete", "id": "abc123" }
+` );
+
+	prompt.instruction(
+		'Always read [elementor://global-variables] before creating to check existing variables and avoid duplicate labels.'
+	);
+
+	return prompt.prompt();
+};