@elementor/editor-variables 3.33.0-99 → 3.35.0-325

package/src/mcp/index.ts

@@ -0,0 +1,17 @@
+import { getMCPByDomain } from '@elementor/editor-mcp';
+
+import { initCreateVariableTool } from './create-variable-tool';
+import { initDeleteVariableTool } from './delete-variable-tool';
+import { initListVariablesTool } from './list-variables-tool';
+import { initUpdateVariableTool } from './update-variable-tool';
+import { initVariablesResource } from './variables-resource';
+
+export function initMcp() {
+	const { setMCPDescription } = getMCPByDomain( 'variables' );
+	setMCPDescription( `Elementor Editor Variables MCP` );
+	initListVariablesTool();
+	initCreateVariableTool();
+	initUpdateVariableTool();
+	initDeleteVariableTool();
+	initVariablesResource();
+}

package/src/mcp/list-variables-tool.ts

@@ -0,0 +1,58 @@
+import { getMCPByDomain } from '@elementor/editor-mcp';
+import { z } from '@elementor/schema';
+
+import { service } from '../service';
+import { type TVariable } from '../storage';
+
+const VariableSchema = {
+	type: z.string().describe( 'The type of the variable.' ),
+	label: z.string().describe( 'The label of the variable, displayed to the user' ),
+	value: z.string().describe( 'The value of the variable.' ),
+	id: z
+		.string()
+		.describe(
+			'The unique identifier of the variable. Used for internal reference, not to be exposed to end users'
+		),
+};
+const VariableListSchema = {
+	variables: z.array( z.object( VariableSchema ) ).describe( 'List of variables' ),
+};
+
+export const initListVariablesTool = () => {
+	getMCPByDomain( 'variables' ).addTool( {
+		name: 'list-global-variables',
+		description: `List editor global variables
+  
+  ## When to use this tool:
+  - When a user requests to see all available global variables in the Elementor editor.
+  - When you need to be exact on a variable label, to avoid any mistakes.
+  - When you want to see the most up-to-date list of global variables.
+  - Before using any other variables related tools that makes changes, such as deletion, creation, or updates. This ensures you have the latest information and there is no naming collision or mismatching.
+  
+  ## Example tool response (JSON format):
+  \`\`\`json
+  { variables: [
+   { type: 'global-color-variable', label: 'Cool', value: 'rgb(1,2,3)', id: 'some-unique-id' },
+   { type: 'global-font-variable', label: 'Headline', value: 'serif', id: 'some-other-unique-id' },
+  ] }
+  \`\`\`
+  
+  Once you get the response, please display the variables in a user-friendly way, unless explicitly requested otherwise.
+  Unless explicitly requested otherwise, response in HTML Format, prefer to use tables or unordered lists.
+  
+  Note: **The label is most improtant to be seen as-is without any changes.**
+  
+  <important>
+  **Do not omit the label**. This is important for the user to identify the variable.
+  **Do not change the label**, it must be displayed exactly as it is, in it's original characters as received from this tool.
+  </important>
+  `,
+		outputSchema: VariableListSchema,
+		handler: async () => {
+			const variables = service.variables() as Record< string, TVariable >;
+			return {
+				variables: Object.entries( variables ).map( ( [ id, varData ] ) => ( { id, ...varData } ) ),
+			};
+		},
+	} );
+};

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

@@ -0,0 +1,81 @@
+import { getMCPByDomain } from '@elementor/editor-mcp';
+import { z } from '@elementor/schema';
+
+import { service } from '../service';
+
+export const initUpdateVariableTool = () => {
+	getMCPByDomain( 'variables' ).addTool( {
+		schema: {
+			id: z.string().describe( 'The unique identifier of the variable to be updated or renamed.' ),
+			label: z
+				.string()
+				.describe(
+					'The label of the variable to be stored after the change. If the user only wishes to update the value, this must be strictly equal to the current label.'
+				),
+			value: z
+				.string()
+				.describe(
+					"The new value for the variable. For color variables, this should be a valid CSS color (e.g., 'rgb(255,0,0)', '#ff0000', 'red'). For font variables, this should be a valid font family (e.g., 'Arial', 'serif'). If the user wishes to rename only, make sure you provide the existing value."
+				),
+		},
+		outputSchema: {
+			status: z.enum( [ 'ok', 'error' ] ).describe( 'The status of the operation' ),
+			message: z
+				.string()
+				.optional()
+				.describe( 'Optional message providing additional information about the operation' ),
+		},
+		name: 'update-global-variable',
+		description: `Update an existing global variable
+
+## When to use this tool:
+- When a user requests to update an existing global variable in the Elementor editor.
+- When you need to modify the value of an existing variable.
+- When you want to rename an existing variable (change its label).
+- When you want to both rename and modify the value of an existing variable.
+
+## Prerequisites:
+- Ensure you have the most up-to-date list of existing global variables to avoid label duplication. You can use the "list-global-variables" tool to fetch the current variables.
+- Make sure when updating a variable, the new label is unique and not already in use by another variable.
+- Make sure you understand whether you are updating a value, renaming, or both.
+- Reference the variable by the "id" property, given from the "list-global-variables" tool.
+- If the user wishes to rename, make sure you have the existing value.
+- If the user wishes to update the value, make sure you have to **correct label**.
+- You must have the unique identifier, the current label, the current value, and the new value or label or both, before using this tool.
+
+## Required parameters:
+- id: The unique identifier of the variable to be updated or renamed.
+- label: The label of the variable to be stored after the change. If the user only wishes to update the value, this must be strictly equal to the current label.
+- value: The new value for the variable. For color variables, this should be a valid CSS color (e.g., 'rgb(255,0,0)', '#ff0000', 'red'). For font variables, this should be a valid font family (e.g., 'Arial', 'serif'). If the user wishes to rename only, make sure you provide the existing value.
+
+## Example tool call (JSON format):
+\`\`\`json
+{ "id": "some-unique-id", "label": "Cool", "value": "rgb(0,140,250)" }
+\`\`\`
+
+## Example responses (JSON format):
+Successful update:
+\`\`\`json
+{ "status": "ok" }
+\`\`\`
+
+Failed update, which must be displayed to the end user. If the error message is not plain, attempt to find the most useful part of the message and display it.
+\`\`\`json
+{ "status": "error", "message": "Label 'Cool' is already in use by another variable." }
+\`\`\`
+`,
+		handler: async ( params ) => {
+			const { id, label, value } = params;
+			try {
+				await service.update( id, { label, value } );
+				return { status: 'ok' };
+			} catch ( error ) {
+				const message: string = ( error as Error ).message || 'Unknown server error';
+				return {
+					status: 'error',
+					message: `There was an error creating the variable: ${ message }`,
+				};
+			}
+		},
+	} );
+};

package/src/mcp/variables-resource.ts

@@ -0,0 +1,28 @@
+import { getMCPByDomain } from '@elementor/editor-mcp';
+
+export const GLOBAL_VARIABLES_URI = 'elementor://variables';
+
+export const initVariablesResource = () => {
+	const { mcpServer } = getMCPByDomain( 'variables' );
+
+	mcpServer.resource(
+		'global-variables',
+		GLOBAL_VARIABLES_URI,
+		{
+			description:
+				'Global variables list. Variables are being used in this way: If it is directly in the schema, you need to put the ID which is the key inside the object.',
+		},
+		async () => {
+			return {
+				contents: [ { uri: GLOBAL_VARIABLES_URI, text: localStorage[ 'elementor-global-variables' ] } ],
+			};
+		}
+	);
+
+	window.addEventListener( 'variables:updated', () => {
+		mcpServer.server.sendResourceUpdated( {
+			uri: GLOBAL_VARIABLES_URI,
+			contents: [ { uri: GLOBAL_VARIABLES_URI, text: localStorage[ 'elementor-global-variables' ] } ],
+		} );
+	} );
+};

package/src/register-variable-types.tsx

@@ -11,19 +11,23 @@ import { registerVariableType } from './variables-registry/variable-type-registr
 
 export function registerVariableTypes() {
 	registerVariableType( {
+		key: colorVariablePropTypeUtil.key,
 		valueField: ColorField,
 		icon: BrushIcon,
 		propTypeUtil: colorVariablePropTypeUtil,
 		fallbackPropTypeUtil: colorPropTypeUtil,
 		variableType: 'color',
 		startIcon: ( { value } ) => <ColorIndicator size="inherit" component="span" value={ value } />,
+		defaultValue: '#ffffff',
 	} );
 
 	registerVariableType( {
+		key: fontVariablePropTypeUtil.key,
 		valueField: FontField,
 		icon: TextIcon,
 		propTypeUtil: fontVariablePropTypeUtil,
 		fallbackPropTypeUtil: stringPropTypeUtil,
 		variableType: 'font',
+		defaultValue: 'Roboto',
 	} );
 }

package/src/service.ts

@@ -1,6 +1,7 @@
 import { __ } from '@wordpress/i18n';
 
 import { apiClient } from './api';
+import { buildOperationsArray, type OperationResult } from './batch-operations';
 import { OP_RW, Storage, type TVariablesList } from './storage';
 import { styleVariablesRepository } from './style-variables-repository';
 import { type Variable } from './types';
@@ -12,8 +13,12 @@ export const service = {
 		return storage.load();
 	},
 
+	getWatermark: (): number => {
+		return storage.state.watermark;
+	},
+
 	init: () => {
-		service.load();
+		return service.load();
 	},
 
 	load: () => {
@@ -168,6 +173,60 @@ export const service = {
 				};
 			} );
 	},
+
+	batchSave: ( originalVariables: TVariablesList, currentVariables: TVariablesList ) => {
+		const operations = buildOperationsArray( originalVariables, currentVariables );
+		const batchPayload = { operations, watermark: storage.state.watermark };
+
+		if ( operations.length === 0 ) {
+			return Promise.resolve( {
+				success: true,
+				watermark: storage.state.watermark,
+				operations: 0,
+			} );
+		}
+
+		return apiClient
+			.batch( batchPayload )
+			.then( ( response ) => {
+				const { success, data: payload } = response.data;
+
+				if ( ! success ) {
+					throw new Error( 'Unexpected response from server' );
+				}
+
+				return payload;
+			} )
+			.then( ( data ) => {
+				const { results, watermark } = data;
+
+				handleWatermark( OP_RW, watermark );
+
+				if ( results ) {
+					results.forEach( ( result: OperationResult ) => {
+						if ( result.variable ) {
+							const { id: variableId, ...variableData } = result.variable;
+
+							if ( result.type === 'create' ) {
+								storage.add( variableId, variableData );
+							} else {
+								storage.update( variableId, variableData );
+							}
+
+							styleVariablesRepository.update( {
+								[ variableId ]: variableData,
+							} );
+						}
+					} );
+				}
+
+				return {
+					success: true,
+					watermark,
+					operations: operations.length,
+				};
+			} );
+	},
 };
 
 const handleWatermark = ( operation: string, newWatermark: number ) => {

package/src/storage.ts

@@ -2,6 +2,7 @@ export type TVariable = {
 	type: string;
 	label: string;
 	value: string;
+	order?: number;
 	deleted?: boolean;
 	deleted_at?: string;
 };
@@ -20,6 +21,10 @@ export class Storage {
 		variables: TVariablesList;
 	};
 
+	notifyChange() {
+		window.dispatchEvent( new Event( 'variables:updated' ) );
+	}
+
 	constructor() {
 		this.state = {
 			watermark: -1,
@@ -43,18 +48,21 @@ export class Storage {
 
 		localStorage.setItem( STORAGE_WATERMARK_KEY, this.state.watermark.toString() );
 		localStorage.setItem( STORAGE_KEY, JSON.stringify( this.state.variables ) );
+		this.notifyChange();
 	}
 
 	add( id: string, variable: TVariable ) {
 		this.load();
 		this.state.variables[ id ] = variable;
 		localStorage.setItem( STORAGE_KEY, JSON.stringify( this.state.variables ) );
+		this.notifyChange();
 	}
 
 	update( id: string, variable: TVariable ) {
 		this.load();
 		this.state.variables[ id ] = variable;
 		localStorage.setItem( STORAGE_KEY, JSON.stringify( this.state.variables ) );
+		this.notifyChange();
 	}
 
 	watermark( watermark: number ) {

package/src/types.ts

@@ -22,4 +22,5 @@ export type NormalizedVariable = {
 	key: string;
 	label: string;
 	value: string;
+	order?: number;
 };

package/src/utils/filter-by-search.ts

@@ -0,0 +1,5 @@
+export function filterBySearch< T extends { label: string } >( variables: T[], searchValue: string ): T[] {
+	const lowerSearchValue = searchValue.toLowerCase();
+
+	return variables.filter( ( variable ) => variable.label.toLowerCase().includes( lowerSearchValue ) );
+}

package/src/utils/tracking.ts

@@ -1,3 +1,5 @@
+import { getMixpanel } from '@elementor/mixpanel';
+
 type VariableEventData = {
 	varType: string;
 	controlPath: string;
@@ -5,35 +7,48 @@ type VariableEventData = {
 };
 
 export const trackVariableEvent = ( { varType, controlPath, action }: VariableEventData ) => {
-	const extendedWindow = window as unknown as Window & {
-		elementorCommon?: {
-			eventsManager?: {
-				dispatchEvent: ( name: string, data: Record< string, string > ) => void;
-				config?: {
-					locations: Record< string, string >;
-					secondaryLocations: Record< string, string >;
-					names: {
-						variables?: Record< string, string >;
-					};
-					triggers: Record< string, string >;
-					elements?: Record< string, string >;
-				};
-			};
-		};
-	};
-
-	const config = extendedWindow?.elementorCommon?.eventsManager?.config;
+	const { dispatchEvent, config } = getMixpanel();
 	if ( ! config?.names?.variables?.[ action ] ) {
 		return;
 	}
 
 	const name = config.names.variables[ action ];
-	extendedWindow.elementorCommon?.eventsManager?.dispatchEvent( name, {
-		location: config.locations.variables,
-		secondaryLocation: config.secondaryLocations.variablesPopover,
-		trigger: config.triggers.click,
+	dispatchEvent?.( name, {
+		location: config?.locations?.variables || '',
+		secondaryLocation: config?.secondaryLocations?.variablesPopover || '',
+		trigger: config?.triggers?.click || '',
 		var_type: varType,
 		control_path: controlPath,
 		action_type: name,
 	} );
 };
+
+type VariablesManagerEventData = {
+	action: 'openManager' | 'add' | 'saveChanges' | 'delete';
+	varType?: string;
+	controlPath?: string;
+};
+
+export const trackVariablesManagerEvent = ( { action, varType, controlPath }: VariablesManagerEventData ) => {
+	const { dispatchEvent, config } = getMixpanel();
+	if ( ! config?.names?.variables?.[ action ] ) {
+		return;
+	}
+
+	const name = config.names.variables[ action ];
+	const eventData: Record< string, string > = {
+		location: config?.locations?.variablesManager || '',
+		trigger: config?.triggers?.click || '',
+		action_type: name,
+	};
+
+	if ( varType ) {
+		eventData.var_type = varType;
+	}
+
+	if ( controlPath ) {
+		eventData.style_control_path = controlPath;
+	}
+
+	dispatchEvent?.( name, eventData );
+};

package/src/utils/unlink-variable.ts

@@ -7,7 +7,7 @@ export function transformValueBeforeUnlink( variable: Variable, propTypeKey: str
 	const { valueTransformer } = getVariableType( propTypeKey );
 
 	if ( valueTransformer ) {
-		return valueTransformer( variable.value );
+		return valueTransformer( variable );
 	}
 
 	return variable.value;

package/src/utils/validations.ts

@@ -1,4 +1,8 @@
-import { __ } from '@wordpress/i18n';
+import type * as React from 'react';
+import { AlertTriangleFilledIcon, InfoCircleFilledIcon } from '@elementor/icons';
+import { __, sprintf } from '@wordpress/i18n';
+
+import { type TVariable, type TVariablesList } from '../storage';
 
 export const ERROR_MESSAGES = {
 	MISSING_VARIABLE_NAME: __( 'Give your variable a name.', 'elementor' ),
@@ -8,21 +12,49 @@ export const ERROR_MESSAGES = {
 	VARIABLE_LABEL_MAX_LENGTH: __( 'Keep names up to 50 characters.', 'elementor' ),
 	DUPLICATED_LABEL: __( 'This variable name already exists. Please choose a unique name.', 'elementor' ),
 	UNEXPECTED_ERROR: __( 'There was a glitch. Try saving your variable again.', 'elementor' ),
+	BATCH: {
+		DUPLICATED_LABELS: ( count: number, name: string ) =>
+			// eslint-disable-next-line @wordpress/i18n-translator-comments
+			sprintf( __( 'We found %1$d duplicated %2$s.', 'elementor' ), count, name ),
+		UNEXPECTED_ERROR: __( 'There was a glitch.', 'elementor' ),
+		DUPLICATED_LABEL_ACTION: __( 'Take me there', 'elementor' ),
+		DUPLICATED_LABEL_ACTION_MESSAGE: __( 'Please rename the variables.', 'elementor' ),
+		UNEXPECTED_ERROR_ACTION_MESSAGE: __( 'Try saving your variables again.', 'elementor' ),
+	},
 } as const;
 
 export const VARIABLE_LABEL_MAX_LENGTH = 50;
 
-type ErrorResponse = {
+type BatchErrorData = {
+	[ id: string ]: {
+		status?: number;
+		message?: string;
+	};
+};
+export type ErrorResponse = {
 	response?: {
 		data?: {
 			code?: string;
+			data?: BatchErrorData;
 		};
 	};
 };
 
+export type ErrorAction = {
+	label?: string;
+	message?: string;
+	callback?: () => void;
+	data?: {
+		duplicatedIds?: string[];
+	};
+};
+
 export type MappedError = {
 	field: string;
 	message: string;
+	action?: ErrorAction;
+	severity?: 'error' | 'secondary';
+	IconComponent?: React.ElementType;
 };
 
 export const mapServerError = ( error: ErrorResponse ): MappedError | undefined => {
@@ -33,10 +65,43 @@ export const mapServerError = ( error: ErrorResponse ): MappedError | undefined
 		};
 	}
 
+	if ( error?.response?.data?.code === 'batch_duplicated_label' ) {
+		const errorData = error?.response?.data?.data ?? {};
+		const count = Object.keys( errorData ).length;
+		const name = count === 1 ? 'name' : 'names';
+		const duplicatedIds = Object.keys( errorData );
+
+		return {
+			field: 'label',
+			message: ERROR_MESSAGES.BATCH.DUPLICATED_LABELS( count, name ),
+			severity: 'error',
+			IconComponent: AlertTriangleFilledIcon,
+			action: {
+				label: ERROR_MESSAGES.BATCH.DUPLICATED_LABEL_ACTION,
+				message: ERROR_MESSAGES.BATCH.DUPLICATED_LABEL_ACTION_MESSAGE,
+				data: {
+					duplicatedIds,
+				},
+			},
+		};
+	}
+
+	if ( error?.response?.data?.code === 'batch_operation_failed' ) {
+		return {
+			field: 'label',
+			message: ERROR_MESSAGES.BATCH.UNEXPECTED_ERROR,
+			severity: 'secondary',
+			IconComponent: InfoCircleFilledIcon,
+			action: {
+				message: ERROR_MESSAGES.BATCH.UNEXPECTED_ERROR_ACTION_MESSAGE,
+			},
+		};
+	}
+
 	return undefined;
 };
 
-export const validateLabel = ( name: string ): string => {
+export const validateLabel = ( name: string, variables?: TVariablesList ): string => {
 	if ( ! name.trim() ) {
 		return ERROR_MESSAGES.MISSING_VARIABLE_NAME;
 	}
@@ -55,6 +120,10 @@ export const validateLabel = ( name: string ): string => {
 		return ERROR_MESSAGES.VARIABLE_LABEL_MAX_LENGTH;
 	}
 
+	if ( Object.values( variables ?? {} ).some( ( variable: TVariable ) => variable.label === name ) ) {
+		return ERROR_MESSAGES.DUPLICATED_LABEL;
+	}
+
 	return '';
 };
 

package/src/variables-registry/create-variable-type-registry.ts

@@ -1,4 +1,4 @@
-import { type ForwardRefExoticComponent, type JSX, type RefAttributes } from 'react';
+import { type ForwardRefExoticComponent, type JSX, type RefAttributes, type RefObject } from 'react';
 import { styleTransformersRegistry } from '@elementor/editor-canvas';
 import { stylesInheritanceTransformersRegistry } from '@elementor/editor-editing-panel';
 import {
@@ -17,8 +17,12 @@ import { type NormalizedVariable, type Variable } from '../types';
 export type ValueFieldProps = {
 	value: string;
 	onChange: ( value: string ) => void;
+	onPropTypeKeyChange?: ( key: string ) => void;
+	propTypeKey?: string;
 	onValidationChange?: ( value: string ) => void;
 	propType?: PropType;
+	error?: { value: string; message: string };
+	ref?: RefObject< HTMLElement | null >;
 };
 
 type FallbackPropTypeUtil = ReturnType< typeof createPropUtils >;
@@ -26,34 +30,36 @@ type FallbackPropTypeUtil = ReturnType< typeof createPropUtils >;
 type VariableTypeOptions = {
 	icon: ForwardRefExoticComponent< Omit< SvgIconProps, 'ref' > & RefAttributes< SVGSVGElement > >;
 	startIcon?: ( { value }: { value: string } ) => JSX.Element;
-	valueField: ( { value, onChange, onValidationChange, propType }: ValueFieldProps ) => JSX.Element;
+	valueField: ( props: ValueFieldProps ) => JSX.Element;
 	variableType: string;
+	key?: string;
+	defaultValue?: string;
 	fallbackPropTypeUtil: FallbackPropTypeUtil;
 	propTypeUtil: PropTypeUtil< string, string >;
 	selectionFilter?: ( variables: NormalizedVariable[], propType: PropType ) => NormalizedVariable[];
-	valueTransformer?: ( value: string ) => PropValue;
+	valueTransformer?: ( variable: Variable ) => PropValue;
 	isCompatible?: ( propType: PropType, variable: Variable ) => boolean;
 };
 
-export type VariableTypesMap = Record< string, VariableTypeOptions >;
+export type VariableTypesMap = Record< string, Omit< VariableTypeOptions, 'key' > >;
 
 export function createVariableTypeRegistry() {
 	const variableTypes: VariableTypesMap = {};
 
 	const registerVariableType = ( {
+		key,
 		icon,
 		startIcon,
 		valueField,
 		propTypeUtil,
 		variableType,
+		defaultValue,
 		selectionFilter,
 		valueTransformer,
 		fallbackPropTypeUtil,
 		isCompatible,
 	}: VariableTypeOptions ) => {
-		if ( variableTypes[ propTypeUtil.key ] ) {
-			throw new Error( `Variable with key "${ propTypeUtil.key }" is already registered.` );
-		}
+		const variableTypeKey = key ?? propTypeUtil.key;
 
 		if ( ! isCompatible ) {
 			isCompatible = ( propType, variable: Variable ) => {
@@ -66,12 +72,13 @@ export function createVariableTypeRegistry() {
 			};
 		}
 
-		variableTypes[ propTypeUtil.key ] = {
+		variableTypes[ variableTypeKey ] = {
 			icon,
 			startIcon,
 			valueField,
 			propTypeUtil,
 			variableType,
+			defaultValue,
 			selectionFilter,
 			valueTransformer,
 			fallbackPropTypeUtil,
@@ -94,6 +101,10 @@ export function createVariableTypeRegistry() {
 		return variableTypes[ key ];
 	};
 
+	const getVariableTypes = () => {
+		return variableTypes;
+	};
+
 	const hasVariableType = ( key: string ) => {
 		return key in variableTypes;
 	};
@@ -101,6 +112,7 @@ export function createVariableTypeRegistry() {
 	return {
 		registerVariableType,
 		getVariableType,
+		getVariableTypes,
 		hasVariableType,
 	};
 }

package/src/variables-registry/variable-type-registry.ts

@@ -1,3 +1,4 @@
 import { createVariableTypeRegistry } from './create-variable-type-registry';
 
-export const { registerVariableType, getVariableType, hasVariableType } = createVariableTypeRegistry();
+export const { registerVariableType, getVariableType, getVariableTypes, hasVariableType } =
+	createVariableTypeRegistry();