@elementor/editor-components 3.35.0-356 → 3.35.0-358

package/src/mcp/save-as-component-tool.ts

@@ -1,8 +1,14 @@
-import { getContainer, type V1ElementData } from '@elementor/editor-elements';
-import { getMCPByDomain } from '@elementor/editor-mcp';
+import { DOCUMENT_STRUCTURE_URI, WIDGET_SCHEMA_URI } from '@elementor/editor-canvas';
+import { getContainer, getElementType, getWidgetsCache, type V1ElementData } from '@elementor/editor-elements';
+import { getMCPByDomain, toolPrompts } from '@elementor/editor-mcp';
+import { type PropValue } from '@elementor/editor-props';
+import { AxiosError } from '@elementor/http-client';
 import { z } from '@elementor/schema';
+import { generateUniqueId } from '@elementor/utils';
 
+import { apiClient } from '../api';
 import { createUnpublishedComponent } from '../store/actions/create-unpublished-component';
+import { type OverridableProps } from '../types';
 
 const InputSchema = {
 	element_id: z
@@ -14,6 +20,26 @@ const InputSchema = {
 	component_name: z
 		.string()
 		.describe( 'The name for the new component. Should be descriptive and unique among existing components.' ),
+	overridable_props: z
+		.object( {
+			props: z.record(
+				z.object( {
+					elementId: z
+						.string()
+						.describe( 'The id of the child element that you want to override its settings' ),
+					propKey: z
+						.string()
+						.describe(
+							'The property key of the child element that you want to override its settings (e.g., "text", "url", "tag"). To get the available propKeys for an element, use the "get-element-type-config" tool.'
+						),
+				} )
+			),
+		} )
+		.optional()
+		.describe(
+			'Overridable properties configuration. Specify which CHILD element properties can be customized. ' +
+				'Only elementId and propKey are required; To get the available propKeys for a child element you must use the "get-element-type-config" tool.'
+		),
 };
 
 const OutputSchema = {
@@ -24,16 +50,16 @@ const OutputSchema = {
 		.describe( 'The unique identifier of the newly created component (only present on success)' ),
 };
 
-export const VALID_ELEMENT_TYPES = [ 'e-div-block', 'e-flexbox', 'e-tabs' ];
 export const ERROR_MESSAGES = {
 	ELEMENT_NOT_FOUND: "Element not found. Use 'list-elements' to get valid element IDs.",
-	ELEMENT_NOT_ONE_OF_TYPES: `Element is not one of the following types: ${ VALID_ELEMENT_TYPES.join( ', ' ) }`,
+	ELEMENT_NOT_ONE_OF_TYPES: ( validTypes: string[] ) =>
+		`Element is not one of the following types: ${ validTypes.join( ', ' ) }`,
 	ELEMENT_IS_LOCKED: 'Cannot save a locked element as a component.',
 };
 
 export const handleSaveAsComponent = async ( params: z.infer< z.ZodObject< typeof InputSchema > > ) => {
-	const { element_id: elementId, component_name: componentName } = params;
-
+	const { element_id: elementId, component_name: componentName, overridable_props: overridablePropsInput } = params;
+	const validElementTypes = getValidElementTypes();
 	const container = getContainer( elementId );
 
 	if ( ! container ) {
@@ -42,8 +68,8 @@ export const handleSaveAsComponent = async ( params: z.infer< z.ZodObject< typeo
 
 	const elType = container.model.get( 'elType' );
 
-	if ( ! VALID_ELEMENT_TYPES.includes( elType ) ) {
-		throw new Error( ERROR_MESSAGES.ELEMENT_NOT_ONE_OF_TYPES );
+	if ( ! validElementTypes.includes( elType ) ) {
+		throw new Error( ERROR_MESSAGES.ELEMENT_NOT_ONE_OF_TYPES( validElementTypes ) );
 	}
 
 	const element = container.model.toJSON( { remove: [ 'default' ] } ) as V1ElementData;
@@ -52,7 +78,30 @@ export const handleSaveAsComponent = async ( params: z.infer< z.ZodObject< typeo
 		throw new Error( ERROR_MESSAGES.ELEMENT_IS_LOCKED );
 	}
 
-	const uid = createUnpublishedComponent( componentName, element, null );
+	const overridableProps = overridablePropsInput
+		? enrichOverridableProps( overridablePropsInput, element )
+		: undefined;
+
+	if ( overridableProps ) {
+		updateElementDataWithOverridableProps( element, overridableProps );
+	}
+
+	const uid = generateUniqueId( 'component' );
+
+	try {
+		await apiClient.validate( {
+			items: [
+				{ uid, title: componentName, elements: [ element ], settings: { overridable_props: overridableProps } },
+			],
+		} );
+	} catch ( error: unknown ) {
+		if ( error instanceof AxiosError ) {
+			throw new Error( error.response?.data.messge );
+		}
+		throw new Error( 'Unknown error' );
+	}
+
+	createUnpublishedComponent( componentName, element, null, overridableProps, uid );
 
 	return {
 		status: 'ok' as const,
@@ -61,32 +110,287 @@ export const handleSaveAsComponent = async ( params: z.infer< z.ZodObject< typeo
 	};
 };
 
-export const initSaveAsComponentTool = () => {
-	return getMCPByDomain( 'components' ).addTool( {
-		name: 'save-as-component',
-		schema: InputSchema,
-		outputSchema: OutputSchema,
-		description: `Save an existing element as a reusable component in the Elementor editor.
+function enrichOverridableProps(
+	input: { props: Record< string, { elementId: string; propKey: string } > },
+	rootElement: V1ElementData
+): OverridableProps {
+	const enrichedProps: OverridableProps[ 'props' ] = {};
+	const defaultGroupId = generateUniqueId( 'group' );
+
+	Object.entries( input.props ).forEach( ( [ , prop ] ) => {
+		const { elementId, propKey } = prop;
+		const element = findElementById( rootElement, elementId );
+
+		if ( ! element ) {
+			throw new Error( `Element with ID "${ elementId }" not found in component` );
+		}
+
+		const elType = element.elType;
+		const widgetType = element.widgetType || element.elType;
+
+		// Validate that the propKey exists in the element's schema
+		const elementType = getElementType( widgetType );
 
-## When NOT to use this tool:
-- Do not use for elements that are already components (widgetType: 'e-component').
-- Do not use for locked elements.
-- Do not guess element IDs. Always use "list-elements" first to get valid IDs.
+		if ( ! elementType ) {
+			throw new Error(
+				`Element type "${ widgetType }" is not atomic or does not have a settings schema. ` +
+					`Cannot expose property "${ propKey }" for element "${ elementId }".`
+			);
+		}
 
-## Prerequisites:
-- **Verify element type**: Ensure the element is not already a component (widgetType should not be 'e-component').
-- **Check if element is unlocked**: Locked elements cannot be saved as components.
-- **Check that the element is one of the following types**: ${ VALID_ELEMENT_TYPES.join( ', ' ) }
+		if ( ! elementType.propsSchema[ propKey ] ) {
+			const availableProps = Object.keys( elementType.propsSchema ).join( ', ' );
+			throw new Error(
+				`Property "${ propKey }" does not exist in element "${ elementId }" (type: ${ widgetType }). ` +
+					`Available properties: ${ availableProps }`
+			);
+		}
 
-## Required parameters:
-- **element_id**: The unique ID of the element to save.
-- **component_name**: A descriptive name for the component (2-50 characters).
+		const overrideKey = generateUniqueId( 'prop' );
+		const originValue = element.settings?.[ propKey ]
+			? ( element.settings[ propKey ] as PropValue )
+			: elementType.propsSchema[ propKey ].default ?? null;
 
-## Example tool call:
+		const label = generateLabel( propKey );
+
+		enrichedProps[ overrideKey ] = {
+			overrideKey,
+			label,
+			elementId,
+			propKey,
+			elType,
+			widgetType,
+			originValue,
+			groupId: defaultGroupId,
+		};
+	} );
+
+	return {
+		props: enrichedProps,
+		groups: {
+			items: {
+				[ defaultGroupId ]: {
+					id: defaultGroupId,
+					label: 'Default',
+					props: Object.keys( enrichedProps ),
+				},
+			},
+			order: [ defaultGroupId ],
+		},
+	};
+}
+
+function updateElementDataWithOverridableProps( rootElement: V1ElementData, overridableProps: OverridableProps ) {
+	Object.values( overridableProps.props ).forEach( ( prop ) => {
+		const element = findElementById( rootElement, prop.elementId );
+
+		if ( ! element || ! element.settings ) {
+			return;
+		}
+
+		element.settings[ prop.propKey ] = {
+			$$type: 'overridable',
+			value: {
+				override_key: prop.overrideKey,
+				origin_value: prop.originValue,
+			},
+		};
+	} );
+}
+
+function findElementById( root: V1ElementData, targetId: string ): V1ElementData | null {
+	if ( root.id === targetId ) {
+		return root;
+	}
+
+	if ( root.elements ) {
+		for ( const child of root.elements ) {
+			const found = findElementById( child, targetId );
+			if ( found ) {
+				return found;
+			}
+		}
+	}
+
+	return null;
+}
+
+function generateLabel( propKey: string ): string {
+	const uniqueId = generateUniqueId( 'prop' );
+	return `${ uniqueId } - ${ propKey }`;
+}
+
+function getValidElementTypes(): string[] {
+	const types = getWidgetsCache();
+
+	if ( ! types ) {
+		return [];
+	}
+
+	return Object.entries( types ).reduce( ( acc, [ type, value ] ) => {
+		if ( ! value.atomic_props_schema || ! value.show_in_panel || value.elType === 'widget' ) {
+			return acc;
+		}
+
+		acc.push( type );
+		return acc;
+	}, [] as string[] );
+}
+
+const generatePrompt = () => {
+	const saveAsComponentPrompt = toolPrompts( 'save-as-component' );
+
+	saveAsComponentPrompt.description( `
+Save an existing element as a reusable component in the Elementor editor.
+
+# When to use this tool
+Use this tool when the user wants to:
+- Create a reusable component from an existing element structure
+- Make specific child element properties customizable in component instances
+- Build a library of reusable design patterns
+
+# When NOT to use this tool
+- Element is already a component (widgetType: 'e-component')
+- Element is locked
+- Element is not an atomic element (atomic_props_schema is not defined)
+- Element elType is a 'widget'
+
+# **CRITICAL - REQUIRED RESOURCES (Must read before using this tool)**
+1. [${ DOCUMENT_STRUCTURE_URI }]
+   **MANDATORY** - Required to understand the document structure and identify child elements for overridable properties.
+   Use this resource to find element IDs and understand the element hierarchy.
+
+2. [${ WIDGET_SCHEMA_URI }]
+   **MANDATORY** - Required to understand which properties are available for each widget type.
+   Use this to identify available propKeys in the atomic_props_schema for child elements.
+
+# Instructions - MUST FOLLOW IN ORDER
+## Step 1: Identify the Target Element
+1. Read the [${ DOCUMENT_STRUCTURE_URI }] resource to understand the document structure
+2. Locate the element you want to save as a component by its element_id
+3. Verify the element type is a valid element type
+4. Ensure the element is not locked and is not already a component
+
+## Step 2: Define Overridable Properties
+Do this step to make child element properties customizable.
+Skip that step ONLY if the user explicitly requests to not make any properties customizable.
+
+1. **Identify Child Elements**
+   - Use the [${ DOCUMENT_STRUCTURE_URI }] resource to find all child elements
+   - Note the elementId and widgetType/elType of each child element you want to customize
+
+2. **Find Available Properties**
+   - Use the [${ WIDGET_SCHEMA_URI }] resource to find the child element's widget type schema
+   - Review the atomic_props_schema to find available propKeys (ONLY use top-level props)
+   - Common propKeys include: "text", "url", "tag", "size", etc.
+   - Use only the top level properties, do not use nested properties.
+
+3. **Build the overridable_props Object**
+   - For each property you want to make overridable, add an entry:
+     \`{ "elementId": "<child-element-id>", "propKey": "<property-key>" }\`
+   - Group all entries under the "props" object
+
+## Step 3: Execute the Tool
+Call the tool with:
+- element_id: The ID of the parent element to save as component
+- component_name: A descriptive name for the component
+- overridable_props: (Optional) The properties configuration from Step 2
+
+# CONSTRAINTS
+- NEVER try to override properties of the parent element itself - ONLY child elements
+- NEVER use invalid propKeys - always verify against the widget's atomic_props_schema in [${ WIDGET_SCHEMA_URI }]
+- Property keys must exist in the child element's atomic_props_schema
+- Element IDs must exist within the target element's children
+- When tool execution fails, read the error message and adjust accordingly
+- The element being saved must not be inside another component
+` );
+
+	saveAsComponentPrompt.parameter(
+		'element_id',
+		`**MANDATORY** The unique identifier of the element to save as a component.
+Use the [${ DOCUMENT_STRUCTURE_URI }] resource to find available element IDs.`
+	);
+
+	saveAsComponentPrompt.parameter(
+		'component_name',
+		`**MANDATORY** A descriptive name for the new component.
+Should be unique and clearly describe the component's purpose (e.g., "Hero Section", "Feature Card").`
+	);
+
+	saveAsComponentPrompt.parameter(
+		'overridable_props',
+		`**OPTIONAL** Configuration for which child element properties can be customized in component instances.
+
+Structure:
+\`\`\`json
+{
+  "props": {
+    "<unique-key>": {
+      "elementId": "<child-element-id>",
+      "propKey": "<property-key>"
+    }
+  }
+}
+\`\`\`
+
+To populate this correctly:
+1. Use [${ DOCUMENT_STRUCTURE_URI }] to find child element IDs and their widgetType
+2. Use [${ WIDGET_SCHEMA_URI }] to find the atomic_props_schema for each child element's widgetType
+3. Only include properties you want to be customizable in component instances
+4. Common propKeys: "text", "url", "tag", "size", "align", etc.`
+	);
+
+	saveAsComponentPrompt.example( `
+Basic component without overridable properties:
 \`\`\`json
-{ "element_id": "abc123", "component_name": "Hero Section" }
+{
+  "element_id": "abc123",
+  "component_name": "Hero Section"
+}
 \`\`\`
-`,
+
+Component with overridable properties:
+\`\`\`json
+{
+  "element_id": "abc123",
+  "component_name": "Feature Card",
+  "overridable_props": {
+    "props": {
+      "heading-text": {
+        "elementId": "heading-123",
+        "propKey": "text"
+      },
+      "button-text": {
+        "elementId": "button-456",
+        "propKey": "text"
+      },
+      "button-link": {
+        "elementId": "button-456",
+        "propKey": "url"
+      }
+    }
+  }
+}
+\`\`\`
+` );
+
+	saveAsComponentPrompt.instruction(
+		`After successful creation, the component will be available in the components library and can be inserted into any page or template.`
+	);
+
+	saveAsComponentPrompt.instruction(
+		`When overridable properties are defined, component instances will show customization controls for those specific properties in the editing panel.`
+	);
+
+	return saveAsComponentPrompt.prompt();
+};
+
+export const initSaveAsComponentTool = () => {
+	return getMCPByDomain( 'components' ).addTool( {
+		name: 'save-as-component',
+		schema: InputSchema,
+		outputSchema: OutputSchema,
+		description: generatePrompt(),
 		handler: handleSaveAsComponent,
 	} );
 };

package/src/store/actions/create-unpublished-component.ts

@@ -5,16 +5,19 @@ import { generateUniqueId } from '@elementor/utils';
 
 import { type ComponentEventData } from '../../components/create-component-form/utils/get-component-event-data';
 import { replaceElementWithComponent } from '../../components/create-component-form/utils/replace-element-with-component';
+import { type OverridableProps } from '../../types';
 import { trackComponentEvent } from '../../utils/tracking';
 import { slice } from '../store';
 
 export function createUnpublishedComponent(
 	name: string,
 	element: V1ElementData,
-	eventData: ComponentEventData | null
+	eventData: ComponentEventData | null,
+	overridableProps?: OverridableProps,
+	uid?: string | null
 ) {
-	const uid = generateUniqueId( 'component' );
-	const componentBase = { uid, name };
+	const generatedUid = uid ?? generateUniqueId( 'component' );
+	const componentBase = { uid: generatedUid, name, overridableProps };
 
 	dispatch(
 		slice.actions.addUnpublished( {
@@ -23,18 +26,18 @@ export function createUnpublishedComponent(
 		} )
 	);
 
-	dispatch( slice.actions.addCreatedThisSession( uid ) );
+	dispatch( slice.actions.addCreatedThisSession( generatedUid ) );
 
 	replaceElementWithComponent( element, componentBase );
 
 	trackComponentEvent( {
 		action: 'created',
-		component_uid: uid,
+		component_uid: generatedUid,
 		component_name: name,
 		...eventData,
 	} );
 
 	runCommand( 'document/save/auto' );
 
-	return uid;
+	return generatedUid;
 }

package/src/store/store.ts

@@ -140,7 +140,11 @@ export const selectComponents = createSelector(
 	selectData,
 	selectUnpublishedData,
 	( data: PublishedComponent[], unpublishedData: UnpublishedComponent[] ) => [
-		...unpublishedData.map( ( item ) => ( { uid: item.uid, name: item.name } ) ),
+		...unpublishedData.map( ( item ) => ( {
+			uid: item.uid,
+			name: item.name,
+			overridableProps: item.overridableProps,
+		} ) ),
 		...data,
 	]
 );

package/src/sync/create-components-before-save.ts

@@ -29,6 +29,7 @@ export async function createComponentsBeforeSave( {
 					id: uidToComponentId.get( component.uid ) as number,
 					name: component.name,
 					uid: component.uid,
+					overridableProps: component.overridableProps ? component.overridableProps : undefined,
 				} ) )
 			)
 		);
@@ -48,6 +49,7 @@ async function createComponents(
 			uid: component.uid,
 			title: component.name,
 			elements: component.elements,
+			settings: component.overridableProps ? { overridable_props: component.overridableProps } : undefined,
 		} ) ),
 	} );
 

package/src/types.ts

@@ -79,7 +79,7 @@ type ComponentOverrides = TransformablePropValue< 'overrides', ComponentOverride
 
 type ComponentOverride = TransformablePropValue< 'override', ComponentOverridePropValue >;
 
-type ComponentOverridePropValue = {
+export type ComponentOverridePropValue = {
 	override_key: string;
 	override_value: TransformablePropValue< string >;
 	schema_source: {