@elementor/editor-canvas 4.2.0-923 → 4.2.0-925

package/src/mcp/tools/build-composition/tool.ts

@@ -10,6 +10,7 @@ import { type MCPRegistryEntry } from '@elementor/editor-mcp';
 
 import { CompositionBuilder } from '../../../composition-builder/composition-builder';
 import { AVAILABLE_WIDGETS_URI_V4 } from '../../resources/available-widgets-resource';
+import { DYNAMIC_TAGS_URI } from '../../resources/dynamic-tags-resource';
 import { BEST_PRACTICES_URI, STYLE_SCHEMA_URI, WIDGET_SCHEMA_URI } from '../../resources/widgets-schema-resource';
 import { isWidgetAvailableForLLM } from '../../utils/element-data-util';
 import { getCompositionTargetContainer } from '../../utils/get-composition-target-container';
@@ -45,6 +46,7 @@ export const initBuildCompositionsTool = ( reg: MCPRegistryEntry ) => {
 			{ description: 'Global Variables', uri: 'elementor://global-variables' },
 			{ description: 'Styles best practices', uri: BEST_PRACTICES_URI },
 			{ description: 'Available widgets for this tool', uri: AVAILABLE_WIDGETS_URI_V4 },
+			{ description: 'Dynamic tags catalog', uri: DYNAMIC_TAGS_URI },
 		],
 		outputSchema,
 		handler: async ( rawParams ) => {

package/src/mcp/tools/configure-element/prompt.ts

@@ -1,5 +1,6 @@
 import { toolPrompts } from '@elementor/editor-mcp';
 
+import { DYNAMIC_TAGS_URI } from '../../resources/dynamic-tags-resource';
 import { STYLE_SCHEMA_URI, WIDGET_SCHEMA_URI } from '../../resources/widgets-schema-resource';
 
 export const CONFIGURE_ELEMENT_GUIDE_URI = 'elementor://canvas/tools/configure-element-guide';
@@ -59,6 +60,21 @@ For styleProperties, use the style schema provided, as it also uses the PropType
 For all non-primitive types, provide the key property as defined in the schema as $$type in the generated object, as it is MANDATORY for parsing.
 
 Use the EXACT "PROP-TYPE" Schema given, and ALWAYS include the "key" property from the original configuration for every property you are changing.
+
+# Dynamic tags
+A value can be made dynamic wherever its schema exposes a variant with "$$type": "dynamic". This may be the property root OR a NESTED field: for example an image is made dynamic on its "src" (the root stays "image"), NOT on the whole "image" value.
+Put the dynamic object EXACTLY at the node whose schema offers the "dynamic" variant, in place of the static variant. The variant's "name" enumerates the tags allowed at that node.
+1. Read the [${ DYNAMIC_TAGS_URI }] resource for each allowed tag's settings schema.
+2. Provide, at that node:
+{
+  "$$type": "dynamic",
+  "value": {
+    "name": "<allowed tag name>",
+    "settings": { /* strictly per the tag's settings schema */ }
+  }
+}
+Image example: { "$$type": "image", "value": { "src": { "$$type": "dynamic", "value": { "name": "<image tag>", "settings": { ... } } } } }
+Do NOT send "group" (it is resolved automatically). Use { "settings": {} } only when the tag has no settings.
 ` );
 
 	configureElementToolPrompt.parameter( 'elementId', 'The ID of the element to configure. MANDATORY.' );

package/src/mcp/tools/configure-element/tool.ts

@@ -1,6 +1,7 @@
 import { getWidgetsCache } from '@elementor/editor-elements';
 import { type MCPRegistryEntry } from '@elementor/editor-mcp';
 
+import { DYNAMIC_TAGS_URI } from '../../resources/dynamic-tags-resource';
 import { STYLE_SCHEMA_URI, WIDGET_SCHEMA_URI } from '../../resources/widgets-schema-resource';
 import { doUpdateElementProperty } from '../../utils/do-update-element-property';
 import { validateInput } from '../../utils/validate-input';
@@ -32,6 +33,7 @@ export const initConfigureElementTool = ( reg: MCPRegistryEntry ) => {
 			{ description: 'Widgets schema', uri: WIDGET_SCHEMA_URI },
 			{ description: 'Styles schema', uri: STYLE_SCHEMA_URI },
 			{ description: 'Configure element guide', uri: CONFIGURE_ELEMENT_GUIDE_URI },
+			{ description: 'Dynamic tags catalog', uri: DYNAMIC_TAGS_URI },
 		],
 		handler: ( { elementId, propertiesToChange, elementType, stylePropertiesToChange } ) => {
 			const widgetData = getWidgetsCache()?.[ elementType ];

package/src/mcp/utils/__tests__/resolve-dynamic-tag.test.ts

@@ -0,0 +1,102 @@
+import { getElementorConfig } from '@elementor/editor-v1-adapters';
+
+import { dynamicTagLLMResolver, getDynamicTagNamesByCategories } from '../resolve-dynamic-tag';
+
+jest.mock( '@elementor/editor-v1-adapters', () => ( {
+	getElementorConfig: jest.fn(),
+} ) );
+
+const mockedGetElementorConfig = getElementorConfig as jest.MockedFunction< typeof getElementorConfig >;
+
+const givenTags = () =>
+	mockedGetElementorConfig.mockReturnValue( {
+		atomicDynamicTags: {
+			tags: {
+				'post-custom-field': {
+					name: 'post-custom-field',
+					label: 'Post Custom Field',
+					group: 'post',
+					categories: [ 'text', 'url' ],
+					props_schema: {
+						key: { kind: 'plain', key: 'string', default: '' },
+						before: { kind: 'plain', key: 'string', default: 'prefix' },
+						fallback: { kind: 'plain', key: 'string', default: '' },
+					},
+				},
+				'site-title': {
+					name: 'site-title',
+					label: 'Site Title',
+					group: 'site',
+					categories: [ 'text' ],
+					props_schema: {},
+				},
+			},
+		},
+	} as never );
+
+describe( 'resolve-dynamic-tag', () => {
+	beforeEach( () => {
+		jest.clearAllMocks();
+		givenTags();
+	} );
+
+	describe( 'getDynamicTagNamesByCategories', () => {
+		it( 'returns only the tags whose categories intersect the prop categories', () => {
+			// Act
+			const names = getDynamicTagNamesByCategories( [ 'url' ] );
+
+			// Assert
+			expect( names ).toEqual( [ 'post-custom-field' ] );
+		} );
+
+		it( 'returns an empty list when no categories are requested', () => {
+			// Act & Assert
+			expect( getDynamicTagNamesByCategories( [] ) ).toEqual( [] );
+		} );
+	} );
+
+	describe( 'dynamicTagLLMResolver', () => {
+		it( 'fills the group from the registry and wraps provided scalar settings', () => {
+			// Act
+			const resolved = dynamicTagLLMResolver( {
+				name: 'post-custom-field',
+				settings: { key: 'price' },
+			} );
+
+			// Assert
+			expect( resolved ).toEqual( {
+				$$type: 'dynamic',
+				value: {
+					name: 'post-custom-field',
+					group: 'post',
+					settings: {
+						key: { $$type: 'string', value: 'price' },
+						before: { $$type: 'string', value: 'prefix' },
+					},
+				},
+			} );
+		} );
+
+		it( 'keeps already-wrapped settings values untouched', () => {
+			// Act
+			const resolved = dynamicTagLLMResolver( {
+				name: 'post-custom-field',
+				settings: { key: { $$type: 'string', value: 'price' } },
+			} ) as { value: { settings: Record< string, unknown > } };
+
+			// Assert
+			expect( resolved.value.settings.key ).toEqual( { $$type: 'string', value: 'price' } );
+		} );
+
+		it( 'returns a structurally complete value for unknown tags', () => {
+			// Act
+			const resolved = dynamicTagLLMResolver( { name: 'does-not-exist' } );
+
+			// Assert
+			expect( resolved ).toEqual( {
+				$$type: 'dynamic',
+				value: { name: 'does-not-exist', group: '', settings: {} },
+			} );
+		} );
+	} );
+} );

package/src/mcp/utils/do-update-element-property.ts

@@ -12,6 +12,7 @@ import { type Utils as IUtils } from '@elementor/editor-variables';
 import { type z } from '@elementor/schema';
 
 import { mergeCustomCssText, readStoredCustomCssText } from './merge-custom-css';
+import { DYNAMIC_PROP_TYPE_KEY, dynamicTagLLMResolver } from './resolve-dynamic-tag';
 
 // TODO: see https://elementor.atlassian.net/browse/ED-22513 for better cross-module access
 type XElementor = z.infer< z.ZodAny >;
@@ -34,7 +35,10 @@ export function resolvePropValue( value: unknown, forceKey?: string ): PropValue
 		.Utils as typeof IUtils;
 	return Schema.adjustLlmPropValueSchema( value as PropValue, {
 		forceKey,
-		transformers: Utils.globalVariablesLLMResolvers,
+		transformers: {
+			...Utils.globalVariablesLLMResolvers,
+			[ DYNAMIC_PROP_TYPE_KEY ]: dynamicTagLLMResolver,
+		},
 	} );
 }
 

package/src/mcp/utils/resolve-dynamic-tag.ts

@@ -0,0 +1,102 @@
+import { type PropType, type PropValue } from '@elementor/editor-props';
+import { getElementorConfig } from '@elementor/editor-v1-adapters';
+
+export const DYNAMIC_PROP_TYPE_KEY = 'dynamic';
+
+// `fallback` is a generic render-time default added to every tag; it is noise for configuration.
+export const OMITTED_DYNAMIC_SETTING_KEYS = [ 'fallback' ] as const;
+
+type SettingPropType = PropType & { key?: string };
+
+export type AtomicDynamicTag = {
+	name: string;
+	label: string;
+	group: string;
+	categories: string[];
+	props_schema: Record< string, SettingPropType >;
+};
+
+type LlmDynamicValue = {
+	name?: string;
+	settings?: Record< string, unknown >;
+};
+
+export const getAtomicDynamicTags = (): Record< string, AtomicDynamicTag > => {
+	const config = getElementorConfig() as { atomicDynamicTags?: { tags?: Record< string, AtomicDynamicTag > } };
+	return config.atomicDynamicTags?.tags ?? {};
+};
+
+export const getDynamicTagNamesByCategories = ( categories: string[] ): string[] => {
+	if ( ! categories.length ) {
+		return [];
+	}
+	const wanted = new Set( categories );
+	return Object.values( getAtomicDynamicTags() )
+		.filter( ( tag ) => tag.categories?.some( ( category ) => wanted.has( category ) ) )
+		.map( ( tag ) => tag.name );
+};
+
+// Reconstructs an intact dynamic PropValue from whatever the LLM produced: the authoritative `group`
+// is taken from the registry (never trusted from the model) and `settings` are rebuilt strictly from
+// the tag's props schema (provided values are wrapped, omitted ones fall back to their defaults).
+export const dynamicTagLLMResolver = ( value: unknown ): PropValue => {
+	const input = ( value ?? {} ) as LlmDynamicValue;
+	const tag = input.name ? getAtomicDynamicTags()[ input.name ] : undefined;
+
+	if ( ! tag ) {
+		return {
+			$$type: DYNAMIC_PROP_TYPE_KEY,
+			value: { name: input.name ?? '', group: '', settings: {} },
+		} as PropValue;
+	}
+
+	return {
+		$$type: DYNAMIC_PROP_TYPE_KEY,
+		value: {
+			name: tag.name,
+			group: tag.group,
+			settings: buildStrictSettings( tag.props_schema ?? {}, input.settings ?? {} ),
+		},
+	} as PropValue;
+};
+
+const buildStrictSettings = (
+	schema: Record< string, SettingPropType >,
+	provided: Record< string, unknown >
+): Record< string, unknown > => {
+	const settings: Record< string, unknown > = {};
+
+	for ( const [ key, propType ] of Object.entries( schema ) ) {
+		if ( ( OMITTED_DYNAMIC_SETTING_KEYS as readonly string[] ).includes( key ) ) {
+			continue;
+		}
+
+		const resolved =
+			provided[ key ] !== undefined
+				? wrapSettingValue( provided[ key ], propType )
+				: defaultSettingValue( propType );
+
+		if ( resolved !== undefined && resolved !== null ) {
+			settings[ key ] = resolved;
+		}
+	}
+
+	return settings;
+};
+
+const wrapSettingValue = ( raw: unknown, propType: SettingPropType ): unknown => {
+	if ( raw !== null && typeof raw === 'object' ) {
+		return raw;
+	}
+	return propType.key ? { $$type: propType.key, value: raw } : raw;
+};
+
+const defaultSettingValue = ( propType: SettingPropType ): unknown => {
+	if ( propType.initial_value !== null && propType.initial_value !== undefined ) {
+		return propType.initial_value;
+	}
+	if ( propType.default !== null && propType.default !== undefined ) {
+		return wrapSettingValue( propType.default, propType );
+	}
+	return undefined;
+};