@elementor/editor-interactions 4.0.0-manual → 4.0.0

package/src/components/interaction-details.tsx

@@ -1,8 +1,8 @@
 import * as React from 'react';
-import { type ComponentType, useMemo, useRef } from 'react';
+import { type ComponentType, useMemo } from 'react';
 import { PopoverContent } from '@elementor/editor-controls';
 import { type PropValue } from '@elementor/editor-props';
-import { Box, Divider, Grid } from '@elementor/ui';
+import { Divider, Grid } from '@elementor/ui';
 import { __ } from '@wordpress/i18n';
 
 import { getInteractionsControl } from '../interactions-controls-registry';
@@ -35,6 +35,8 @@ export const DEFAULT_VALUES = {
 	replay: false,
 	easing: 'easeIn',
 	relativeTo: 'viewport',
+	repeat: '',
+	times: 1,
 	start: 85,
 	end: 15,
 };
@@ -53,7 +55,9 @@ type InteractionsControlType =
 	| 'relativeTo'
 	| 'start'
 	| 'end'
-	| 'customEffects';
+	| 'customEffects'
+	| 'repeat'
+	| 'times';
 
 type InteractionValues = {
 	trigger: string;
@@ -68,6 +72,8 @@ type InteractionValues = {
 	start: SizeStringValue;
 	end: SizeStringValue;
 	customEffects?: PropValue;
+	repeat: string;
+	times: number;
 };
 
 type ControlVisibilityConfig = {
@@ -82,6 +88,8 @@ const controlVisibilityConfig: ControlVisibilityConfig = {
 	relativeTo: ( values ) => values.trigger === 'scrollOn',
 	start: ( values ) => values.trigger === 'scrollOn',
 	end: ( values ) => values.trigger === 'scrollOn',
+	repeat: ( values ) => values.trigger !== 'scrollOn',
+	times: ( values ) => values.trigger !== 'scrollOn' && values.repeat === 'times',
 
 	duration: ( values ) => {
 		const isRelativeToVisible = values.trigger === 'scrollOn';
@@ -93,6 +101,14 @@ const controlVisibilityConfig: ControlVisibilityConfig = {
 	},
 };
 
+function normalizeTimesValue( value: unknown, fallback: number ): number {
+	const numericValue = Number( value );
+	if ( ! Number.isFinite( numericValue ) ) {
+		return fallback;
+	}
+	return Math.max( 1, Math.floor( numericValue ) );
+}
+
 function useControlComponent( controlName: InteractionsControlType, isVisible: boolean = true ) {
 	return useMemo( () => {
 		if ( ! isVisible ) {
@@ -113,6 +129,9 @@ export const InteractionDetails = ( { interaction, onChange, onPlayInteraction }
 	const replay = extractBoolean( interaction.animation.value.config?.value.replay, DEFAULT_VALUES.replay );
 	const easing = extractString( interaction.animation.value.config?.value.easing, DEFAULT_VALUES.easing );
 	const relativeTo = extractString( interaction.animation.value.config?.value.relativeTo, DEFAULT_VALUES.relativeTo );
+	const configValue = interaction.animation.value.config?.value;
+	const repeat = extractString( configValue?.repeat, DEFAULT_VALUES.repeat );
+	const times = normalizeTimesValue( configValue?.times?.value, DEFAULT_VALUES.times );
 
 	const start = extractSize( interaction.animation.value.config?.value.start, DEFAULT_VALUES.start );
 	const end = extractSize( interaction.animation.value.config?.value.end, DEFAULT_VALUES.end );
@@ -127,6 +146,8 @@ export const InteractionDetails = ( { interaction, onChange, onPlayInteraction }
 		easing,
 		replay,
 		relativeTo,
+		repeat,
+		times,
 		start,
 		end,
 		customEffects,
@@ -151,10 +172,16 @@ export const InteractionDetails = ( { interaction, onChange, onPlayInteraction }
 		controlVisibilityConfig.effectType( interactionValues )
 	);
 	const DirectionControl = useControlComponent( 'direction', controlVisibilityConfig.direction( interactionValues ) );
+	const RepeatControl = useControlComponent(
+		'repeat',
+		controlVisibilityConfig.repeat( interactionValues )
+	) as ComponentType< FieldProps< string > >;
+	const TimesControl = useControlComponent(
+		'times',
+		controlVisibilityConfig.times( interactionValues )
+	) as ComponentType< FieldProps< number > >;
 	const EasingControl = useControlComponent( 'easing' );
 
-	const containerRef = useRef< HTMLDivElement >( null );
-
 	const updateInteraction = (
 		updates: Partial< {
 			trigger: string;
@@ -166,6 +193,8 @@ export const InteractionDetails = ( { interaction, onChange, onPlayInteraction }
 			replay: boolean;
 			easing?: string;
 			relativeTo: string;
+			repeat: string;
+			times?: number;
 			start: SizeStringValue;
 			end: SizeStringValue;
 			customEffects?: PropValue;
@@ -192,6 +221,8 @@ export const InteractionDetails = ( { interaction, onChange, onPlayInteraction }
 				replay: updates.replay ?? replay,
 				easing: updates.easing ?? easing,
 				relativeTo: updates.relativeTo ?? relativeTo,
+				repeat: updates.repeat ?? repeat,
+				times: updates.times ?? times,
 				start: updates.start ?? start,
 				end: updates.end ?? end,
 				customEffects: updates.customEffects ?? customEffects,
@@ -208,131 +239,142 @@ export const InteractionDetails = ( { interaction, onChange, onPlayInteraction }
 	};
 
 	return (
-		<Box ref={ containerRef }>
-			<PopoverContent p={ 1.5 }>
-				<Grid container spacing={ 1.5 }>
-					{ TriggerControl && (
-						<Field label={ __( 'Trigger', 'elementor' ) }>
-							<TriggerControl
-								value={ trigger }
-								onChange={ ( v ) => updateInteraction( { trigger: v } ) }
-							/>
-						</Field>
-					) }
-
-					{ ReplayControl && (
-						<Field label={ __( 'Replay', 'elementor' ) }>
-							<ReplayControl
-								value={ replay }
-								onChange={ ( v ) => updateInteraction( { replay: v } ) }
-								disabled={ true }
-								anchorRef={ containerRef }
-							/>
-						</Field>
-					) }
-				</Grid>
+		<PopoverContent p={ 1.5 }>
+			<Grid container spacing={ 1.5 }>
+				{ TriggerControl && (
+					<Field label={ __( 'Trigger', 'elementor' ) }>
+						<TriggerControl value={ trigger } onChange={ ( v ) => updateInteraction( { trigger: v } ) } />
+					</Field>
+				) }
 
-				<Divider />
+				{ ReplayControl && (
+					<Field label={ __( 'Replay', 'elementor' ) }>
+						<ReplayControl
+							value={ replay }
+							onChange={ ( v ) => updateInteraction( { replay: v } ) }
+							disabled={ true }
+						/>
+					</Field>
+				) }
+			</Grid>
 
-				<Grid container spacing={ 1.5 }>
-					{ EffectControl && (
-						<Field label={ __( 'Effect', 'elementor' ) }>
-							<EffectControl value={ effect } onChange={ ( v ) => updateInteraction( { effect: v } ) } />
-						</Field>
-					) }
+			<Divider />
 
-					{ CustomEffectControl && (
-						<Field label={ __( 'Custom Effect', 'elementor' ) }>
-							<CustomEffectControl
-								value={ customEffects }
-								onChange={ ( v: PropValue ) => updateInteraction( { customEffects: v } ) }
-							/>
-						</Field>
-					) }
+			<Grid container spacing={ 1.5 }>
+				{ EffectControl && (
+					<Field label={ __( 'Effect', 'elementor' ) }>
+						<EffectControl value={ effect } onChange={ ( v ) => updateInteraction( { effect: v } ) } />
+					</Field>
+				) }
 
-					{ EffectTypeControl && (
-						<Field label={ __( 'Type', 'elementor' ) }>
-							<EffectTypeControl value={ type } onChange={ ( v ) => updateInteraction( { type: v } ) } />
-						</Field>
-					) }
-
-					{ DirectionControl && (
-						<Field label={ __( 'Direction', 'elementor' ) }>
-							<DirectionControl
-								value={ direction }
-								onChange={ ( v ) => updateInteraction( { direction: v } ) }
-								interactionType={ type }
-							/>
-						</Field>
-					) }
-
-					{ controlVisibilityConfig.duration( interactionValues ) && (
-						<Field label={ __( 'Duration', 'elementor' ) }>
-							<TimeFrameIndicator
-								value={ String( duration ) }
-								onChange={ ( v ) => updateInteraction( { duration: v as SizeStringValue } ) }
-								defaultValue={ DEFAULT_VALUES.duration as SizeStringValue }
-							/>
-						</Field>
-					) }
-
-					{ controlVisibilityConfig.delay( interactionValues ) && (
-						<Field label={ __( 'Delay', 'elementor' ) }>
-							<TimeFrameIndicator
-								value={ String( delay ) }
-								onChange={ ( v ) => updateInteraction( { delay: v as SizeStringValue } ) }
-								defaultValue={ DEFAULT_VALUES.delay as SizeStringValue }
-							/>
-						</Field>
-					) }
-				</Grid>
+				{ CustomEffectControl && (
+					<Field label={ __( 'Custom Effect', 'elementor' ) }>
+						<CustomEffectControl
+							value={ customEffects }
+							onChange={ ( v: PropValue ) => updateInteraction( { customEffects: v } ) }
+						/>
+					</Field>
+				) }
 
-				{ controlVisibilityConfig.relativeTo( interactionValues ) && RelativeToControl && (
-					<>
-						<Divider />
-						<Grid container spacing={ 1.5 }>
-							{ StartControl && (
-								<Field label={ __( 'Start', 'elementor' ) }>
-									<StartControl
-										value={ parseSizeValue( start, [ '%' ] ).size?.toString() ?? '' }
-										onChange={ ( v: string ) =>
-											updateInteraction( { start: v as SizeStringValue } )
-										}
-									/>
-								</Field>
-							) }
-							{ EndControl && (
-								<Field label={ __( 'End', 'elementor' ) }>
-									<EndControl
-										value={ parseSizeValue( end, [ '%' ] ).size?.toString() ?? '' }
-										onChange={ ( v: string ) => updateInteraction( { end: v as SizeStringValue } ) }
-									/>
-								</Field>
-							) }
-							<Field label={ __( 'Relative To', 'elementor' ) }>
-								<RelativeToControl
-									value={ relativeTo }
-									onChange={ ( v ) => updateInteraction( { relativeTo: v } ) }
-								/>
-							</Field>
-						</Grid>
-						<Divider />
-					</>
+				{ EffectTypeControl && (
+					<Field label={ __( 'Type', 'elementor' ) }>
+						<EffectTypeControl value={ type } onChange={ ( v ) => updateInteraction( { type: v } ) } />
+					</Field>
+				) }
+
+				{ DirectionControl && (
+					<Field label={ __( 'Direction', 'elementor' ) }>
+						<DirectionControl
+							value={ direction }
+							onChange={ ( v ) => updateInteraction( { direction: v } ) }
+							interactionType={ type }
+						/>
+					</Field>
+				) }
+
+				{ RepeatControl && (
+					<Field label={ __( 'Repeat', 'elementor' ) }>
+						<RepeatControl value={ repeat } onChange={ ( v ) => updateInteraction( { repeat: v } ) } />
+					</Field>
+				) }
+
+				{ TimesControl && (
+					<Field label={ __( 'Times', 'elementor' ) }>
+						<TimesControl
+							value={ times }
+							onChange={ ( v ) =>
+								updateInteraction( {
+									times: normalizeTimesValue( v, DEFAULT_VALUES.times ),
+								} )
+							}
+						/>
+					</Field>
+				) }
+
+				{ controlVisibilityConfig.duration( interactionValues ) && (
+					<Field label={ __( 'Duration', 'elementor' ) }>
+						<TimeFrameIndicator
+							value={ String( duration ) }
+							onChange={ ( v ) => updateInteraction( { duration: v as SizeStringValue } ) }
+							defaultValue={ DEFAULT_VALUES.duration as SizeStringValue }
+						/>
+					</Field>
+				) }
+
+				{ controlVisibilityConfig.delay( interactionValues ) && (
+					<Field label={ __( 'Delay', 'elementor' ) }>
+						<TimeFrameIndicator
+							value={ String( delay ) }
+							onChange={ ( v ) => updateInteraction( { delay: v as SizeStringValue } ) }
+							defaultValue={ DEFAULT_VALUES.delay as SizeStringValue }
+						/>
+					</Field>
 				) }
+			</Grid>
 
-				{ EasingControl && (
+			{ controlVisibilityConfig.relativeTo( interactionValues ) && RelativeToControl && (
+				<>
+					<Divider />
 					<Grid container spacing={ 1.5 }>
-						<Field label={ __( 'Easing', 'elementor' ) }>
-							<EasingControl
-								value={ easing }
-								onChange={ ( v ) => {
-									updateInteraction( { easing: v } );
-								} }
+						{ StartControl && (
+							<Field label={ __( 'Start', 'elementor' ) }>
+								<StartControl
+									value={ parseSizeValue( start, [ '%' ] ).size?.toString() ?? '' }
+									onChange={ ( v: string ) => updateInteraction( { start: v as SizeStringValue } ) }
+								/>
+							</Field>
+						) }
+						{ EndControl && (
+							<Field label={ __( 'End', 'elementor' ) }>
+								<EndControl
+									value={ parseSizeValue( end, [ '%' ] ).size?.toString() ?? '' }
+									onChange={ ( v: string ) => updateInteraction( { end: v as SizeStringValue } ) }
+								/>
+							</Field>
+						) }
+						<Field label={ __( 'Relative To', 'elementor' ) }>
+							<RelativeToControl
+								value={ relativeTo }
+								onChange={ ( v ) => updateInteraction( { relativeTo: v } ) }
 							/>
 						</Field>
 					</Grid>
-				) }
-			</PopoverContent>
-		</Box>
+					<Divider />
+				</>
+			) }
+
+			{ EasingControl && (
+				<Grid container spacing={ 1.5 }>
+					<Field label={ __( 'Easing', 'elementor' ) }>
+						<EasingControl
+							value={ easing }
+							onChange={ ( v ) => {
+								updateInteraction( { easing: v } );
+							} }
+						/>
+					</Field>
+				</Grid>
+			) }
+		</PopoverContent>
 	);
 };

package/src/components/interactions-list.tsx

@@ -1,13 +1,15 @@
 import * as React from 'react';
 import { useCallback, useEffect, useMemo, useRef } from 'react';
-import { Repeater } from '@elementor/editor-controls';
+import { Repeater, type SetRepeaterValuesMeta } from '@elementor/editor-controls';
 import { InfoCircleFilledIcon, PlayerPlayIcon } from '@elementor/icons';
 import { Alert, AlertTitle, Box, IconButton, Tooltip } from '@elementor/ui';
 import { __ } from '@wordpress/i18n';
 
+import { useInteractionsContext } from '../contexts/interactions-context';
 import { InteractionItemContextProvider } from '../contexts/interactions-item-context';
 import type { ElementInteractions, InteractionItemPropValue, InteractionItemValue } from '../types';
 import { buildDisplayLabel, createDefaultInteractionItem, extractString } from '../utils/prop-value-utils';
+import { trackInteractionCreated } from '../utils/tracking';
 import { InteractionsListItem } from './interactions-list-item';
 export const MAX_NUMBER_OF_INTERACTIONS = 5;
 
@@ -20,6 +22,7 @@ export type InteractionListProps = {
 
 export function InteractionsList( props: InteractionListProps ) {
 	const { interactions, onSelectInteractions, onPlayInteraction, triggerCreateOnShowEmpty } = props;
+	const { elementId } = useInteractionsContext();
 
 	const hasInitializedRef = useRef( false );
 
@@ -62,13 +65,23 @@ export function InteractionsList( props: InteractionListProps ) {
 	) : undefined;
 
 	const handleRepeaterChange = useCallback(
-		( newItems: ElementInteractions[ 'items' ] ) => {
+		(
+			newItems: ElementInteractions[ 'items' ],
+			_: unknown,
+			meta?: SetRepeaterValuesMeta< InteractionItemPropValue >
+		) => {
 			handleUpdateInteractions( {
 				...interactions,
 				items: newItems,
 			} );
+			if ( meta?.action?.type === 'add' ) {
+				const addedItem = meta.action.payload[ 0 ]?.item;
+				if ( addedItem ) {
+					trackInteractionCreated( elementId, addedItem );
+				}
+			}
 		},
-		[ interactions, handleUpdateInteractions ]
+		[ interactions, handleUpdateInteractions, elementId ]
 	);
 
 	const handleInteractionChange = useCallback(

package/src/components/interactions-tab.tsx

@@ -1,12 +1,14 @@
 import * as React from 'react';
 import { useCallback, useState } from 'react';
-import { useElementInteractions } from '@elementor/editor-elements';
 import { SessionStorageProvider } from '@elementor/session';
 import { Stack } from '@elementor/ui';
 
 import { InteractionsProvider, useInteractionsContext } from '../contexts/interactions-context';
 import { PopupStateProvider } from '../contexts/popup-state-context';
+import { useElementInteractions } from '../hooks/use-element-interactions';
 import type { ElementInteractions } from '../types';
+import { createDefaultInteractionItem } from '../utils/prop-value-utils';
+import { trackInteractionCreated } from '../utils/tracking';
 import { EmptyState } from './empty-state';
 import { InteractionsList } from './interactions-list';
 
@@ -33,6 +35,7 @@ function InteractionsTabContent( { elementId }: { elementId: string } ) {
 				<EmptyState
 					onCreateInteraction={ () => {
 						firstInteractionState[ 1 ]( true );
+						trackInteractionCreated( elementId, createDefaultInteractionItem() );
 					} }
 				/>
 			) }

package/src/contexts/interactions-context.tsx

@@ -4,10 +4,12 @@ import {
 	type ElementInteractions,
 	playElementInteractions,
 	updateElementInteractions,
-	useElementInteractions,
 } from '@elementor/editor-elements';
 
+import { useElementInteractions } from '../hooks/use-element-interactions';
+
 type InteractionsContextValue = {
+	elementId: string;
 	interactions: ElementInteractions;
 	setInteractions: ( value: ElementInteractions | undefined ) => void;
 	playInteractions: ( interactionId: string ) => void;
@@ -44,6 +46,7 @@ export const InteractionsProvider = ( { children, elementId }: { children: React
 	};
 
 	const contextValue: InteractionsContextValue = {
+		elementId,
 		interactions,
 		setInteractions,
 		playInteractions,

package/src/hooks/use-element-interactions.ts

@@ -0,0 +1,26 @@
+import { useState } from 'react';
+import { type ElementID, type ElementInteractions, getElementInteractions } from '@elementor/editor-elements';
+import { __privateUseListenTo as useListenTo, windowEvent } from '@elementor/editor-v1-adapters';
+
+import { filterInteractions } from '../utils/filter-interactions';
+
+export const useElementInteractions = ( elementId: ElementID ) => {
+	const [ interactions, setInteractions ] = useState< ElementInteractions >( () => {
+		const initial = getElementInteractions( elementId );
+		const filteredInteractions = filterInteractions( initial?.items ?? [] );
+
+		return { version: initial?.version ?? 1, items: filteredInteractions };
+	} );
+
+	useListenTo(
+		windowEvent( 'elementor/element/update_interactions' ),
+		() => {
+			const newInteractions = getElementInteractions( elementId );
+			const filteredInteractions = filterInteractions( newInteractions?.items ?? [] );
+			setInteractions( { version: newInteractions?.version ?? 1, items: filteredInteractions } );
+		},
+		[ elementId ]
+	);
+
+	return interactions;
+};

package/src/index.ts

@@ -16,3 +16,29 @@ export { TRIGGER_OPTIONS, BASE_TRIGGERS } from './components/controls/trigger';
 export { EASING_OPTIONS, BASE_EASINGS } from './components/controls/easing';
 export { REPLAY_OPTIONS, BASE_REPLAY } from './components/controls/replay';
 export { EFFECT_OPTIONS, BASE_EFFECTS } from './components/controls/effect';
+export { REPEAT_OPTIONS, REPEAT_TOOLTIPS } from './components/controls/repeat';
+
+export {
+	createString,
+	createNumber,
+	createBoolean,
+	createTimingConfig,
+	createConfig,
+	createExcludedBreakpoints,
+	createInteractionBreakpoints,
+	createAnimationPreset,
+	createInteractionItem,
+	createDefaultInteractionItem,
+	createDefaultInteractions,
+	extractString,
+	extractBoolean,
+	extractSize,
+	extractExcludedBreakpoints,
+	buildDisplayLabel,
+} from './utils/prop-value-utils';
+
+export { generateTempInteractionId, isTempId } from './utils/temp-id-utils';
+export { resolveDirection } from './utils/resolve-direction';
+export { convertTimeUnit } from './utils/time-conversion';
+export { parseSizeValue, formatSizeValue } from './utils/size-transform-utils';
+export { useElementInteractions } from './hooks/use-element-interactions';

package/src/init.ts

@@ -1,13 +1,17 @@
+import { getMCPByDomain } from '@elementor/editor-mcp';
+
+import { initPasteInteractionsCommand } from './commands/paste-interactions';
 import { Direction } from './components/controls/direction';
 import { Easing } from './components/controls/easing';
 import { Effect } from './components/controls/effect';
 import { EffectType } from './components/controls/effect-type';
+import { Repeat } from './components/controls/repeat';
 import { Replay } from './components/controls/replay';
 import { Trigger } from './components/controls/trigger';
 import { initCleanInteractionIdsOnDuplicate } from './hooks/on-duplicate';
 import { registerInteractionsControl } from './interactions-controls-registry';
 import { interactionsRepository } from './interactions-repository';
-import { initMcpInteractions } from './mcp';
+import { EDITOR_INTERACTIONS_MCP_INSTRUCTIONS, initMcpInteractions } from './mcp';
 import { documentElementsInteractionsProvider } from './providers/document-elements-interactions-provider';
 
 export function init() {
@@ -15,6 +19,7 @@ export function init() {
 		interactionsRepository.register( documentElementsInteractionsProvider );
 
 		initCleanInteractionIdsOnDuplicate();
+		initPasteInteractionsCommand();
 
 		registerInteractionsControl( {
 			type: 'trigger',
@@ -31,7 +36,7 @@ export function init() {
 		registerInteractionsControl( {
 			type: 'replay',
 			component: Replay,
-			options: [ 'true', 'false' ],
+			options: [ 'no' ],
 		} );
 
 		registerInteractionsControl( {
@@ -52,7 +57,12 @@ export function init() {
 			options: [ 'fade', 'slide', 'scale' ],
 		} );
 
-		initMcpInteractions();
+		registerInteractionsControl( {
+			type: 'repeat',
+			component: Repeat,
+		} );
+
+		initMcpInteractions( getMCPByDomain( 'interactions', { instructions: EDITOR_INTERACTIONS_MCP_INSTRUCTIONS } ) );
 	} catch ( error ) {
 		throw error;
 	}

package/src/interactions-controls-registry.ts

@@ -1,9 +1,15 @@
 import { type ComponentType } from 'react';
 import { type PropValue } from '@elementor/editor-props';
 
-import { type DirectionFieldProps, type FieldProps, type ReplayFieldProps } from './types';
+import {
+	type DirectionFieldProps,
+	type FieldProps,
+	type RepeatFieldProps,
+	type ReplayFieldProps,
+	type TimesFieldProps,
+} from './types';
 
-type InteractionsControlType =
+export type InteractionsControlType =
 	| 'trigger'
 	| 'effect'
 	| 'effectType'
@@ -11,6 +17,8 @@ type InteractionsControlType =
 	| 'duration'
 	| 'delay'
 	| 'replay'
+	| 'repeat'
+	| 'times'
 	| 'easing'
 	| 'relativeTo'
 	| 'start'
@@ -26,6 +34,8 @@ type InteractionsControlPropsMap = {
 	duration: FieldProps;
 	delay: FieldProps;
 	replay: ReplayFieldProps;
+	repeat: RepeatFieldProps;
+	times: TimesFieldProps;
 	easing: FieldProps;
 	relativeTo: FieldProps;
 	start: FieldProps;
@@ -40,7 +50,9 @@ type ControlOptions< T extends InteractionsControlType > = {
 
 type StoredControlOptions = {
 	type: InteractionsControlType;
-	component: ComponentType< FieldProps | DirectionFieldProps | ReplayFieldProps >;
+	component: ComponentType<
+		FieldProps | DirectionFieldProps | ReplayFieldProps | RepeatFieldProps | TimesFieldProps
+	>;
 	options?: string[];
 };