@elementor/editor-variables 4.1.0-838 → 4.1.0-beta2

package/package.json

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

package/src/components/global-styles-import-listener.tsx

@@ -2,28 +2,17 @@ import { useEffect } from 'react';
 import { GLOBAL_STYLES_IMPORTED_EVENT } from '@elementor/editor-canvas';
 
 import { service } from '../service';
-import { styleVariablesRepository } from '../style-variables-repository';
 
 export function GlobalStylesImportListener() {
 	useEffect( () => {
-		const handleGlobalStylesImported = ( event: CustomEvent ) => {
-			const importedVars = event.detail?.global_variables;
-
-			if ( ! importedVars ) {
-				return;
-			}
-
-			if ( importedVars.data && typeof importedVars.data === 'object' ) {
-				styleVariablesRepository.update( importedVars.data );
-			}
-
+		const handleGlobalStylesImported = () => {
 			service.load();
 		};
 
-		window.addEventListener( GLOBAL_STYLES_IMPORTED_EVENT, handleGlobalStylesImported as EventListener );
+		window.addEventListener( GLOBAL_STYLES_IMPORTED_EVENT, handleGlobalStylesImported );
 
 		return () => {
-			window.removeEventListener( GLOBAL_STYLES_IMPORTED_EVENT, handleGlobalStylesImported as EventListener );
+			window.removeEventListener( GLOBAL_STYLES_IMPORTED_EVENT, handleGlobalStylesImported );
 		};
 	}, [] );
 

package/src/components/variables-manager/hooks/use-variables-manager-state.ts

@@ -1,9 +1,9 @@
-import { useCallback, useState } from 'react';
+import { useCallback, useEffect, useState } from 'react';
 
 import { generateTempId } from '../../../batch-operations';
 import { getVariables } from '../../../hooks/use-prop-variables';
 import { service } from '../../../service';
-import { type TVariablesList } from '../../../storage';
+import { STORAGE_UPDATED_EVENT, type TVariablesList } from '../../../storage';
 import { generateDuplicateLabel } from '../../../utils/duplicate-label';
 import { filterBySearch } from '../../../utils/filter-by-search';
 import { applySelectionFilters, variablesToList } from '../../../utils/variables-to-list';
@@ -17,10 +17,40 @@ export const useVariablesManagerState = () => {
 	const [ isSaving, setIsSaving ] = useState( false );
 	const [ searchValue, setSearchValue ] = useState( '' );
 
+	useEffect( () => {
+		const handleStorageUpdated = () => {
+			setVariables( getVariables( false ) );
+			setDeletedVariables( [] );
+			setIsDirty( false );
+		};
+
+		window.addEventListener( STORAGE_UPDATED_EVENT, handleStorageUpdated );
+
+		return () => {
+			window.removeEventListener( STORAGE_UPDATED_EVENT, handleStorageUpdated );
+		};
+	}, [] );
+
 	const handleOnChange = useCallback(
 		( newVariables: TVariablesList ) => {
-			setVariables( { ...variables, ...newVariables } );
-			setIsDirty( true );
+			const hasChanges = Object.entries( newVariables ).some( ( [ id, newVar ] ) => {
+				const existingVar = variables[ id ];
+				if ( ! existingVar ) {
+					return true;
+				}
+				return (
+					existingVar.label !== newVar.label ||
+					existingVar.value !== newVar.value ||
+					existingVar.order !== newVar.order ||
+					existingVar.type !== newVar.type ||
+					( existingVar.sync_to_v3 ?? false ) !== ( newVar.sync_to_v3 ?? false )
+				);
+			} );
+
+			if ( hasChanges ) {
+				setVariables( { ...variables, ...newVariables } );
+				setIsDirty( true );
+			}
 		},
 		[ variables ]
 	);

package/src/components/variables-manager/ui/variable-table-row.tsx

@@ -162,7 +162,7 @@ export const VariableRow = (
 							value,
 							onChange,
 							onPropTypeKeyChange: ( type ) => {
-								if ( ! isDisabled ) {
+								if ( ! isDisabled && type !== row.type ) {
 									handleOnChange( {
 										...variables,
 										[ row.id ]: { ...variables[ row.id ], type },

package/src/components/variables-manager/variables-manager-panel.tsx

@@ -512,7 +512,6 @@ function VariablesManagerPanelRoot( {
 					flexDirection: 'column',
 					flex: 1,
 					minHeight: 0,
-					overflow: 'hidden',
 				} }
 			>
 				{ bodyInner }

package/src/init.ts

@@ -47,7 +47,15 @@ export function init() {
 	} );
 
 	variablesService.init().then( () => {
-		initMcp( getMCPByDomain( 'variables' ), getMCPByDomain( 'canvas' ) );
+		const variablesMcpRegistry = getMCPByDomain( 'variables', {
+			instructions: `Everything related to V4 ( Atomic ) variables.
+# Global variables
+- Create/update/delete global variables
+- Get list of global variables
+- Get details of a global variable
+`,
+		} );
+		initMcp( variablesMcpRegistry, getMCPByDomain( 'canvas' ) );
 	} );
 
 	injectIntoTop( {

package/src/mcp/index.ts

@@ -4,15 +4,6 @@ import { initManageVariableTool } from './manage-variable-tool';
 import { initVariablesResource } from './variables-resource';
 
 export function initMcp( reg: MCPRegistryEntry, canvasMcpEntry: MCPRegistryEntry ) {
-	const { setMCPDescription } = reg;
-	setMCPDescription(
-		`Everything related to V4 ( Atomic ) variables.
-# Global variables
-- Create/update/delete global variables
-- Get list of global variables
-- Get details of a global variable
-`
-	);
 	initManageVariableTool( reg );
 	initVariablesResource( reg, canvasMcpEntry );
 }

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

@@ -1,26 +1,79 @@
 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)' ),
-			value: z.string().optional().describe( 'Variable value (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(
+					'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: {
 			status: z.enum( [ 'ok' ] ).describe( 'Operation status' ),
@@ -31,31 +84,22 @@ export const initManageVariableTool = ( reg: MCPRegistryEntry ) => {
 			speedPriority: 0.75,
 		},
 		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: `Manages global variables (create/update/delete). Existing variables available in resources.
-CREATE: requires type, label, value. Ensure label is unique.
-UPDATE: requires id, label, value. When renaming: keep existing value. When updating value: keep exact label.
-DELETE: requires id. DESTRUCTIVE - confirm with user first.
-
-# NAMING - IMPORTANT
-the variables names should ALWAYS be lowercased and dashed spaced. example: "Headline Primary" should be "headline-primary"
-`,
+		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
 	} );
 };
 
@@ -69,10 +113,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 } > ) {
@@ -83,6 +134,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();
+};

package/src/mcp/variables-resource.ts

@@ -2,7 +2,7 @@ import { type MCPRegistryEntry } from '@elementor/editor-mcp';
 import { __privateListenTo as listenTo, commandEndEvent } from '@elementor/editor-v1-adapters';
 
 import { service } from '../service';
-import { type TVariable } from '../storage';
+import { STORAGE_UPDATED_EVENT, type TVariable } from '../storage';
 
 export const GLOBAL_VARIABLES_URI = 'elementor://global-variables';
 
@@ -47,7 +47,7 @@ export const initVariablesResource = ( variablesMcpEntry: MCPRegistryEntry, canv
 			}
 		);
 
-		window.addEventListener( 'variables:updated', notifyGlobalVariablesUpdated );
+		window.addEventListener( STORAGE_UPDATED_EVENT, notifyGlobalVariablesUpdated );
 
 		listenTo( commandEndEvent( 'document/save/update' ), notifyGlobalVariablesUpdated );
 	} );

package/src/storage.ts

@@ -13,6 +13,8 @@ export type TVariablesList = Record< string, TVariable >;
 const STORAGE_KEY = 'elementor-global-variables';
 const STORAGE_WATERMARK_KEY = 'elementor-global-variables-watermark';
 
+export const STORAGE_UPDATED_EVENT = 'variables:updated';
+
 export const OP_RW = 'RW';
 const OP_RO = 'RO';
 
@@ -23,7 +25,7 @@ export class Storage {
 	};
 
 	notifyChange() {
-		window.dispatchEvent( new Event( 'variables:updated' ) );
+		window.dispatchEvent( new Event( STORAGE_UPDATED_EVENT ) );
 	}
 
 	constructor() {