@elementor/editor-interactions 4.0.0-manual → 4.0.0

package/src/mcp/constants.ts

@@ -1 +1,59 @@
 export const MAX_INTERACTIONS_PER_ELEMENT = 5;
+export const EDITOR_INTERACTIONS_MCP_INSTRUCTIONS = `MCP server for managing element interactions and animations. Use this to add, modify, or remove animations and motion effects triggered by user events such as page load or scroll-into-view.
+		** IMPORTANT **
+		Use the "interactions-schema" resource to get the schema of the interactions.
+		Actions:
+		- get: Read the current interactions on the element.
+		- add: Add a new interaction (max ${ MAX_INTERACTIONS_PER_ELEMENT } per element).
+		- update: Update an existing interaction by its interactionId.
+		- delete: Remove a specific interaction by its interactionId.
+		- clear: Remove all interactions from the element.
+		
+		For add/update, provide: trigger, effect, effectType, direction (required for slide effect), duration, delay, easing.
+		Use excludedBreakpoints to disable the animation on specific responsive breakpoints (e.g. ["mobile", "tablet"]).
+		Example Get Request:
+		{
+			"elementId": "123",
+			"action": "get",
+			"interactionId": "123",
+			"animationData": {
+				"trigger": "click",
+				"effect": "fade",
+			}
+		}
+		Example Add Request:
+		{
+			"elementId": "123",
+			"action": "add",
+			"animationData": {
+				"effectType": "in",
+				"direction": "top",
+				"trigger": "click",
+				"effect": "fade",
+				"duration": 1000,
+				"delay": 0,
+				"easing": "easeIn",
+				"excludedBreakpoints": ["mobile", "tablet"],
+			}
+		}
+		Example Update Request:
+		{
+			"elementId": "123",
+			"action": "update",
+			"interactionId": "123",
+			"animationData": {
+				"trigger": "click",
+				"effect": "fade",
+			}
+		}
+		Example Delete Request:
+		{
+			"elementId": "123",
+			"action": "delete",
+			"interactionId": "123",
+		}
+		Example Clear Request:
+		{
+			"elementId": "123",
+			"action": "clear",
+		}`;

package/src/mcp/index.ts

@@ -1,74 +1,20 @@
-import { getMCPByDomain } from '@elementor/editor-mcp';
+import { type MCPRegistryEntry } from '@elementor/editor-mcp';
 
-import { MAX_INTERACTIONS_PER_ELEMENT } from './constants';
 import { initInteractionsSchemaResource } from './resources/interactions-schema-resource';
 import { initManageElementInteractionTool } from './tools/manage-element-interaction-tool';
 
-export const initMcpInteractions = () => {
-	const reg = getMCPByDomain( 'interactions', {
-		instructions: `
-		MCP server for managing element interactions and animations. Use this to add, modify, or remove animations and motion effects triggered by user events such as page load or scroll-into-view.
-		** IMPORTANT **
-		Use the "interactions-schema" resource to get the schema of the interactions.
-		Actions:
-		- get: Read the current interactions on the element.
-		- add: Add a new interaction (max ${ MAX_INTERACTIONS_PER_ELEMENT } per element).
-		- update: Update an existing interaction by its interactionId.
-		- delete: Remove a specific interaction by its interactionId.
-		- clear: Remove all interactions from the element.
-		
-		For add/update, provide: trigger, effect, effectType, direction (required for slide effect), duration, delay, easing.
-		Use excludedBreakpoints to disable the animation on specific responsive breakpoints (e.g. ["mobile", "tablet"]).
-		Example Get Request:
-		{
-			"elementId": "123",
-			"action": "get",
-			"interactionId": "123",
-			"animationData": {
-				"trigger": "click",
-				"effect": "fade",
-			}
-		}
-		Example Add Request:
-		{
-			"elementId": "123",
-			"action": "add",
-			"animationData": {
-				"effectType": "in",
-				"direction": "top",
-				"trigger": "click",
-				"effect": "fade",
-				"duration": 1000,
-				"delay": 0,
-				"easing": "easeIn",
-				"excludedBreakpoints": ["mobile", "tablet"],
-			}
-		}
-		Example Update Request:
-		{
-			"elementId": "123",
-			"action": "update",
-			"interactionId": "123",
-			"animationData": {
-				"trigger": "click",
-				"effect": "fade",
-			}
-		}
-		Example Delete Request:
-		{
-			"elementId": "123",
-			"action": "delete",
-			"interactionId": "123",
-		}
-		Example Clear Request:
-		{
-			"elementId": "123",
-			"action": "clear",
-		}
-		`,
-	} );
-	reg.waitForReady().then( () => {
-		initInteractionsSchemaResource( reg );
-		initManageElementInteractionTool( reg );
-	} );
+export * from './constants';
+
+export const initMcpInteractions = ( reg: MCPRegistryEntry ) => {
+	const { setMCPDescription } = reg;
+	setMCPDescription(
+		`Everything related to V4 ( Atomic ) interactions.
+# Interactions
+- Create/update/delete interactions
+- Get list of interactions
+- Get details of an interaction
+`
+	);
+	initInteractionsSchemaResource( reg );
+	initManageElementInteractionTool( reg );
 };

package/src/mcp/tools/manage-element-interaction-tool.ts

@@ -5,7 +5,12 @@ import { isProActive } from '@elementor/utils';
 
 import { interactionsRepository } from '../../interactions-repository';
 import { type ElementInteractions } from '../../types';
-import { createInteractionItem, extractString } from '../../utils/prop-value-utils';
+import {
+	createInteractionItem,
+	extractExcludedBreakpoints,
+	extractSize,
+	extractString,
+} from '../../utils/prop-value-utils';
 import { generateTempInteractionId } from '../../utils/temp-id-utils';
 import { MAX_INTERACTIONS_PER_ELEMENT } from '../constants';
 import { INTERACTIONS_SCHEMA_URI } from '../resources/interactions-schema-resource';
@@ -16,6 +21,8 @@ const EMPTY_INTERACTIONS: ElementInteractions = {
 	items: [],
 };
 
+const EFFECTS_WITHOUT_TYPE = [ 'custom' ];
+
 export const initManageElementInteractionTool = ( reg: MCPRegistryEntry ) => {
 	const { addTool } = reg;
 	const extendedSchema = isProActive() ? { ...baseSchema, ...proSchema } : baseSchema;
@@ -55,18 +62,44 @@ export const initManageElementInteractionTool = ( reg: MCPRegistryEntry ) => {
 			[ key: string ]: unknown;
 		} ) => {
 			const { elementId, action, interactionId, ...animationData } = input;
+			const { effectType, ...restAnimationData } = animationData as {
+				effectType?: string;
+				[ key: string ]: unknown;
+			};
+			const effect = restAnimationData.effect as string | undefined;
+			const resolvedType =
+				effectType ?? ( effect && ! EFFECTS_WITHOUT_TYPE.includes( effect ) ? 'in' : undefined );
 
 			const allInteractions = interactionsRepository.all();
 			const elementData = allInteractions.find( ( data ) => data.elementId === elementId );
 			const currentInteractions: ElementInteractions = elementData?.interactions ?? EMPTY_INTERACTIONS;
 
 			if ( action === 'get' ) {
+				const summary = currentInteractions.items.map( ( item ) => {
+					const { value } = item;
+					const animValue = value.animation.value;
+					const timingValue = animValue.timing_config.value;
+					const configValue = animValue.config.value;
+
+					return {
+						id: extractString( value.interaction_id ),
+						trigger: extractString( value.trigger ),
+						effect: extractString( animValue.effect ),
+						effectType: extractString( animValue.type ),
+						direction: extractString( animValue.direction ),
+						duration: extractSize( timingValue.duration ),
+						delay: extractSize( timingValue.delay ),
+						easing: extractString( configValue.easing ),
+						excludedBreakpoints: extractExcludedBreakpoints( value.breakpoints ),
+					};
+				} );
+
 				return {
 					success: true,
 					elementId,
 					action,
-					interactions: currentInteractions.items,
-					count: currentInteractions.items.length,
+					interactions: summary,
+					count: summary.length,
 				};
 			}
 
@@ -82,7 +115,8 @@ export const initManageElementInteractionTool = ( reg: MCPRegistryEntry ) => {
 
 					const newItem = createInteractionItem( {
 						interactionId: generateTempInteractionId(),
-						...animationData,
+						...restAnimationData,
+						type: resolvedType,
 					} );
 
 					updatedItems = [ ...updatedItems, newItem ];
@@ -106,7 +140,8 @@ export const initManageElementInteractionTool = ( reg: MCPRegistryEntry ) => {
 
 					const updatedItem = createInteractionItem( {
 						interactionId,
-						...animationData,
+						...restAnimationData,
+						type: resolvedType,
 					} );
 
 					updatedItems = [

package/src/mcp/tools/schema.ts

@@ -25,7 +25,7 @@ export const proSchema = {
 		.optional()
 		.describe( 'Event that triggers the animation' ),
 	effect: z.enum( [ 'fade', 'slide', 'scale', 'custom' ] ).optional().describe( 'Animation effect type' ),
-	customEffect: z
+	customEffects: z
 		.object( {
 			keyframes: z
 				.array(

package/src/types.ts

@@ -31,7 +31,10 @@ export type InteractionConstants = {
 	defaultDelay: number;
 	slideDistance: number;
 	scaleStart: number;
-	easing: string;
+	defaultEasing: string;
+	relativeTo: string;
+	start: number;
+	end: number;
 };
 
 export type InteractionsConfig = {
@@ -47,6 +50,8 @@ export type FieldProps< T = string > = {
 };
 
 export type ReplayFieldProps = FieldProps< boolean >;
+export type RepeatFieldProps = FieldProps< string >;
+export type TimesFieldProps = FieldProps< number >;
 export type DirectionFieldProps = FieldProps< string > & {
 	interactionType: string;
 };

package/src/ui/interactions-promotion-chip.tsx

@@ -1,5 +1,6 @@
 import * as React from 'react';
-import { forwardRef, type MouseEvent, type RefObject, useImperativeHandle, useState } from 'react';
+import { forwardRef, type MouseEvent, type RefObject, useCallback, useImperativeHandle, useState } from 'react';
+import { type PromotionTrackingData, trackUpgradePromotionClick, trackViewPromotion } from '@elementor/editor-controls';
 import { PromotionChip, PromotionPopover, useCanvasClickHandler } from '@elementor/editor-ui';
 import { Box } from '@elementor/ui';
 import { __ } from '@wordpress/i18n';
@@ -8,6 +9,7 @@ export type InteractionsPromotionChipProps = {
 	content: string;
 	upgradeUrl: string;
 	anchorRef?: RefObject< HTMLElement | null >;
+	trackingData: PromotionTrackingData;
 };
 
 export type InteractionsPromotionChipRef = {
@@ -15,14 +17,21 @@ export type InteractionsPromotionChipRef = {
 };
 
 export const InteractionsPromotionChip = forwardRef< InteractionsPromotionChipRef, InteractionsPromotionChipProps >(
-	( { content, upgradeUrl, anchorRef }, ref ) => {
+	( { content, upgradeUrl, anchorRef, trackingData }, ref ) => {
 		const [ isOpen, setIsOpen ] = useState( false );
 
 		useCanvasClickHandler( isOpen, () => setIsOpen( false ) );
 
-		const toggle = () => setIsOpen( ( prev ) => ! prev );
+		const toggle = useCallback( () => {
+			setIsOpen( ( prev ) => {
+				if ( ! prev ) {
+					trackViewPromotion( trackingData );
+				}
+				return ! prev;
+			} );
+		}, [ trackingData ] );
 
-		useImperativeHandle( ref, () => ( { toggle } ), [] );
+		useImperativeHandle( ref, () => ( { toggle } ), [ toggle ] );
 
 		const handleToggle = ( e: MouseEvent ) => {
 			e.stopPropagation();
@@ -42,6 +51,7 @@ export const InteractionsPromotionChip = forwardRef< InteractionsPromotionChipRe
 					e.stopPropagation();
 					setIsOpen( false );
 				} }
+				onCtaClick={ () => trackUpgradePromotionClick( trackingData ) }
 			>
 				<Box
 					onMouseDown={ ( e: MouseEvent ) => e.stopPropagation() }
@@ -54,5 +64,3 @@ export const InteractionsPromotionChip = forwardRef< InteractionsPromotionChipRe
 		);
 	}
 );
-
-InteractionsPromotionChip.displayName = 'InteractionsPromotionChip';

package/src/ui/promotion-overlay-layout.tsx

@@ -0,0 +1,22 @@
+import * as React from 'react';
+import { forwardRef, type ReactNode } from 'react';
+import { Box } from '@elementor/ui';
+
+const OVERLAY_GRID = '1 / 1';
+const CHIP_OFFSET = '50%';
+
+type PromotionOverlayLayoutProps = {
+	children: ReactNode;
+	promotionChip: ReactNode;
+};
+
+export const PromotionOverlayLayout = forwardRef< HTMLDivElement, PromotionOverlayLayoutProps >(
+	( { children, promotionChip }, ref ) => (
+		<Box ref={ ref } sx={ { display: 'grid', alignItems: 'center' } }>
+			<Box sx={ { gridArea: OVERLAY_GRID } }>{ children }</Box>
+			<Box sx={ { gridArea: OVERLAY_GRID, marginInlineEnd: CHIP_OFFSET, justifySelf: 'end' } }>
+				{ promotionChip }
+			</Box>
+		</Box>
+	)
+);

package/src/ui/promotion-select.tsx

@@ -1,5 +1,6 @@
 import * as React from 'react';
 import { type MouseEvent, useRef } from 'react';
+import { type PromotionTrackingData } from '@elementor/editor-controls';
 import { MenuListItem } from '@elementor/editor-ui';
 import { MenuSubheader, Select, type SelectChangeEvent } from '@elementor/ui';
 import { __ } from '@wordpress/i18n';
@@ -14,6 +15,7 @@ type PromotionSelectProps = {
 	promotionLabel?: string;
 	promotionContent: string;
 	upgradeUrl: string;
+	trackingData: PromotionTrackingData;
 };
 
 export function PromotionSelect( {
@@ -24,6 +26,7 @@ export function PromotionSelect( {
 	promotionLabel,
 	promotionContent,
 	upgradeUrl,
+	trackingData,
 }: PromotionSelectProps ) {
 	const promotionRef = useRef< InteractionsPromotionChipRef >( null );
 	const anchorRef = useRef< HTMLElement >( null );
@@ -63,6 +66,7 @@ export function PromotionSelect( {
 					upgradeUrl={ upgradeUrl }
 					ref={ promotionRef }
 					anchorRef={ anchorRef }
+					trackingData={ trackingData }
 				/>
 			</MenuSubheader>
 

package/src/utils/custom-effect-to-prop-value.ts

@@ -0,0 +1,145 @@
+import { type PropValue } from '@elementor/editor-props';
+
+const CUSTOM_EFFECT_TYPE = 'custom-effect';
+const KEYFRAMES_TYPE = 'keyframes';
+const KEYFRAME_STOP_TYPE = 'keyframe-stop';
+const KEYFRAME_STOP_SETTINGS_TYPE = 'keyframe-stop-settings';
+const SIZE_TYPE = 'size';
+const NUMBER_TYPE = 'number';
+const TRANSFORM_SCALE_TYPE = 'transform-scale';
+const TRANSFORM_ROTATE_TYPE = 'transform-rotate';
+const TRANSFORM_MOVE_TYPE = 'transform-move';
+const TRANSFORM_SKEW_TYPE = 'transform-skew';
+const UNIT_PERCENT = '%';
+const UNIT_DEG = 'deg';
+const UNIT_PX = 'px';
+
+export type PlainKeyframeValue = {
+	opacity?: number;
+	scale?: { x: number; y: number };
+	rotate?: { x: number; y: number; z: number };
+	move?: { x: number; y: number; z: number };
+	skew?: { x: number; y: number };
+};
+
+export type PlainKeyframe = { stop: number; value: PlainKeyframeValue };
+
+export type PlainCustomEffect = { keyframes: PlainKeyframe[] };
+
+const isPlainCustomEffect = ( v: unknown ): v is PlainCustomEffect =>
+	typeof v === 'object' &&
+	v !== null &&
+	'keyframes' in v &&
+	Array.isArray( ( v as PlainCustomEffect ).keyframes ) &&
+	! ( '$$type' in v );
+
+const toSizePropValue = ( size: number, unit: string = UNIT_PERCENT ): PropValue => ( {
+	$$type: SIZE_TYPE,
+	value: { size, unit },
+} );
+
+const toNumberPropValue = ( n: number ): PropValue => ( {
+	$$type: NUMBER_TYPE,
+	value: n,
+} );
+
+const toDimensionalNumberPropValue = (
+	type: string,
+	plain: { x?: number; y?: number; z?: number },
+	defaults: { x: number; y: number; z: number }
+): PropValue => ( {
+	$$type: type,
+	value: {
+		x: toNumberPropValue( plain.x ?? defaults.x ),
+		y: toNumberPropValue( plain.y ?? defaults.y ),
+		z: toNumberPropValue( plain.z ?? defaults.z ),
+	},
+} );
+
+const toDimensionalSizePropValue = (
+	type: string,
+	plain: { x?: number; y?: number; z?: number },
+	defaults: { x: number; y: number; z: number },
+	unit: string
+): PropValue => ( {
+	$$type: type,
+	value: {
+		x: toSizePropValue( plain.x ?? defaults.x, unit ),
+		y: toSizePropValue( plain.y ?? defaults.y, unit ),
+		z: toSizePropValue( plain.z ?? defaults.z, unit ),
+	},
+} );
+
+const toSkewPropValue = ( plain: { x?: number; y?: number } ): PropValue => ( {
+	$$type: TRANSFORM_SKEW_TYPE,
+	value: {
+		x: toSizePropValue( plain.x ?? 0, UNIT_DEG ),
+		y: toSizePropValue( plain.y ?? 0, UNIT_DEG ),
+	},
+} );
+
+const toKeyframeStopSettingsPropValue = ( plain: PlainKeyframeValue ): PropValue => {
+	const value: Record< string, PropValue > = {};
+	if ( plain.opacity !== undefined ) {
+		const percent = plain.opacity <= 1 ? Math.round( plain.opacity * 100 ) : plain.opacity;
+		value.opacity = toSizePropValue( percent );
+	}
+	if ( plain.scale !== undefined ) {
+		value.scale = toDimensionalNumberPropValue( TRANSFORM_SCALE_TYPE, plain.scale, { x: 1, y: 1, z: 1 } );
+	}
+	if ( plain.rotate !== undefined ) {
+		value.rotate = toDimensionalSizePropValue(
+			TRANSFORM_ROTATE_TYPE,
+			plain.rotate,
+			{ x: 0, y: 0, z: 0 },
+			UNIT_DEG
+		);
+	}
+	if ( plain.move !== undefined ) {
+		value.move = toDimensionalSizePropValue( TRANSFORM_MOVE_TYPE, plain.move, { x: 0, y: 0, z: 0 }, UNIT_PX );
+	}
+	if ( plain.skew !== undefined ) {
+		value.skew = toSkewPropValue( plain.skew );
+	}
+	return { $$type: KEYFRAME_STOP_SETTINGS_TYPE, value };
+};
+
+const isPlainKeyframe = ( v: unknown ): v is PlainKeyframe =>
+	typeof v === 'object' && v !== null && 'stop' in v && 'value' in v && ! ( '$$type' in v );
+
+const toKeyframeStopPropValue = ( item: PlainKeyframe | PropValue ): PropValue => {
+	if ( ! isPlainKeyframe( item ) ) {
+		return item as PropValue;
+	}
+	return {
+		$$type: KEYFRAME_STOP_TYPE,
+		value: {
+			stop: toSizePropValue( item.stop ),
+			settings: toKeyframeStopSettingsPropValue( item.value ),
+		},
+	};
+};
+
+const toKeyframesPropValue = ( keyframes: ( PlainKeyframe | PropValue )[] ): PropValue => ( {
+	$$type: KEYFRAMES_TYPE,
+	value: keyframes.map( toKeyframeStopPropValue ),
+} );
+
+const plainCustomEffectToPropValue = ( plain: PlainCustomEffect ): PropValue => ( {
+	$$type: CUSTOM_EFFECT_TYPE,
+	value: {
+		keyframes: toKeyframesPropValue( plain.keyframes as ( PlainKeyframe | PropValue )[] ),
+	},
+} );
+
+export const toCustomEffectPropValue = (
+	customEffects: PropValue | PlainCustomEffect | undefined
+): PropValue | undefined => {
+	if ( customEffects === undefined ) {
+		return undefined;
+	}
+	if ( isPlainCustomEffect( customEffects ) ) {
+		return plainCustomEffectToPropValue( customEffects );
+	}
+	return customEffects as PropValue;
+};

package/src/utils/filter-interactions.ts

@@ -0,0 +1,9 @@
+import { type InteractionItemPropValue } from '@elementor/editor-elements';
+
+import { isSupportedInteractionItem } from './is-supported-interaction-item';
+
+export const filterInteractions = ( interactions: InteractionItemPropValue[] ) => {
+	return interactions.filter( ( interaction ) => {
+		return isSupportedInteractionItem( interaction );
+	} );
+};

package/src/utils/get-interactions-config.ts

@@ -1,15 +1,5 @@
 import { type InteractionsConfig } from '../types';
 
-const DEFAULT_CONFIG: InteractionsConfig = {
-	constants: {
-		defaultDuration: 300,
-		defaultDelay: 0,
-		slideDistance: 100,
-		scaleStart: 0.5,
-		easing: 'linear',
-	},
-};
-
 export function getInteractionsConfig(): InteractionsConfig {
-	return window.ElementorInteractionsConfig || DEFAULT_CONFIG;
+	return window.ElementorInteractionsConfig ?? ( {} as InteractionsConfig );
 }

package/src/utils/is-supported-interaction-item.ts

@@ -0,0 +1,39 @@
+import { getInteractionsControlOptions, type InteractionsControlType } from '../interactions-controls-registry';
+import { type InteractionItemPropValue } from '../types';
+import { extractBoolean, extractString } from '../utils/prop-value-utils';
+
+export function isSupportedInteractionItem( interaction: InteractionItemPropValue ): boolean {
+	const value = interaction.value;
+
+	const replay = extractBoolean( value.animation.value.config?.value.replay );
+	if ( true === replay ) {
+		return hasSupport( 'replay', 'yes' );
+	}
+
+	const trigger = extractString( value.trigger );
+	const easing = extractString( value.animation.value.config?.value.easing );
+	const effect = extractString( value.animation.value.effect );
+
+	const checks: Array< [ string, string ] > = [
+		[ 'trigger', trigger ],
+		[ 'easing', easing ],
+		[ 'effect', effect ],
+	];
+
+	return checks.every( ( [ controlType, controlValue ] ) => {
+		if ( controlValue === '' || controlValue === null ) {
+			return true;
+		}
+		return hasSupport( controlType, controlValue );
+	} );
+}
+
+function hasSupport( controlType: string, controlValue: string ) {
+	const supportedOptions = getInteractionsControlOptions( controlType as InteractionsControlType );
+
+	if ( 1 > supportedOptions.length ) {
+		return true;
+	}
+
+	return supportedOptions.includes( controlValue );
+}