@elementor/editor-global-classes 3.33.0-99 → 3.34.2

package/src/components/search-and-filter/context.tsx

@@ -17,7 +17,7 @@ type SearchContextType = {
 type FilterAndSortContextType = {
 	filters: CheckedFilters;
 	setFilters: React.Dispatch< React.SetStateAction< CheckedFilters > >;
-	onClearFilter: () => void;
+	onClearFilter: ( type?: 'menu' | 'header' ) => void;
 };
 
 export type SearchAndFilterContextType = {
@@ -35,9 +35,19 @@ const INIT_CHECKED_FILTERS: CheckedFilters = {
 
 export const SearchAndFilterProvider = ( { children }: React.PropsWithChildren ) => {
 	const [ filters, setFilters ] = React.useState< CheckedFilters >( INIT_CHECKED_FILTERS );
+
+	const getInitialSearchValue = () => {
+		const storedValue = localStorage.getItem( 'elementor-global-classes-search' );
+		if ( storedValue ) {
+			localStorage.removeItem( 'elementor-global-classes-search' );
+			return storedValue;
+		}
+		return '';
+	};
+
 	const { debouncedValue, inputValue, handleChange } = useDebounceState( {
 		delay: 300,
-		initialValue: '',
+		initialValue: getInitialSearchValue(),
 	} );
 
 	const onClearSearch = () => {

package/src/errors.ts

@@ -9,3 +9,8 @@ export const GlobalClassLabelAlreadyExistsError = createError< { label: string }
 	code: 'global_class_label_already_exists',
 	message: 'Class with this name already exists.',
 } );
+
+export const GlobalClassTrackingError = createError< { cause: string } >( {
+	code: 'global_class_tracking_error',
+	message: 'Error tracking global classes event.',
+} );

package/src/global-classes-styles-provider.ts

@@ -8,7 +8,7 @@ import {
 import { __ } from '@wordpress/i18n';
 
 import { getCapabilities } from './capabilities';
-import { GlobalClassLabelAlreadyExistsError } from './errors';
+import { GlobalClassLabelAlreadyExistsError, GlobalClassTrackingError } from './errors';
 import {
 	selectClass,
 	selectData,
@@ -17,8 +17,9 @@ import {
 	slice,
 	type StateWithGlobalClasses,
 } from './store';
+import { trackGlobalClasses, type TrackingEvent } from './utils/tracking';
 
-const MAX_CLASSES = 50;
+const MAX_CLASSES = 100;
 
 export const GLOBAL_CLASSES_PROVIDER_KEY = 'global-classes';
 
@@ -33,7 +34,11 @@ export const globalClassesStylesProvider = createStylesProvider( {
 	subscribe: ( cb ) => subscribeWithStates( cb ),
 	capabilities: getCapabilities(),
 	actions: {
-		all: () => selectOrderedClasses( getState() ),
+		all: () => {
+			const selectAllClasses = selectOrderedClasses( getState() );
+			localStorage.setItem( 'elementor-global-classes', JSON.stringify( selectAllClasses ) );
+			return selectAllClasses;
+		},
 		get: ( id ) => selectClass( getState(), id ),
 		resolveCssName: ( id: string ) => {
 			return selectClass( getState(), id )?.label ?? id;
@@ -90,6 +95,11 @@ export const globalClassesStylesProvider = createStylesProvider( {
 				} )
 			);
 		},
+		tracking: ( data: { event: string; [ key: string ]: unknown } ) => {
+			trackGlobalClasses( data as TrackingEvent ).catch( ( error ) => {
+				throw new GlobalClassTrackingError( { cause: error } );
+			} );
+		},
 	},
 } );
 

package/src/hooks/use-css-class-by-id.ts

@@ -0,0 +1,8 @@
+import { type StyleDefinitionID } from '@elementor/editor-styles';
+import { __useSelector as useSelector, type SliceState } from '@elementor/store';
+
+import { selectClass, type slice } from '../store';
+
+export const useCssClassById = ( id: StyleDefinitionID ) => {
+	return useSelector( ( state: SliceState< typeof slice > ) => selectClass( state, id ) );
+};

package/src/hooks/use-prefetch-css-class-usage.ts

@@ -14,3 +14,9 @@ export function usePrefetchCssClassUsage() {
 
 	return { prefetchClassesUsage };
 }
+
+export const PrefetchCssClassUsage = () => {
+	const { prefetchClassesUsage } = usePrefetchCssClassUsage();
+	prefetchClassesUsage();
+	return null;
+};

package/src/init.ts

@@ -6,7 +6,6 @@ import {
 } from '@elementor/editor-editing-panel';
 import { __registerPanel as registerPanel } from '@elementor/editor-panels';
 import { stylesRepository } from '@elementor/editor-styles-repository';
-import { __privateListenTo as listenTo, v1ReadyEvent } from '@elementor/editor-v1-adapters';
 import { __registerSlice as registerSlice } from '@elementor/store';
 
 import { ClassManagerButton } from './components/class-manager/class-manager-button';
@@ -14,8 +13,10 @@ import { panel } from './components/class-manager/class-manager-panel';
 import { ConvertLocalClassToGlobalClass } from './components/convert-local-class-to-global-class';
 import { PopulateStore } from './components/populate-store';
 import { GLOBAL_CLASSES_PROVIDER_KEY, globalClassesStylesProvider } from './global-classes-styles-provider';
+import { PrefetchCssClassUsage } from './hooks/use-prefetch-css-class-usage';
+import { initMcpIntegration } from './mcp-integration';
 import { slice } from './store';
-import { syncWithDocumentSave } from './sync-with-document-save';
+import { SyncWithDocumentSave } from './sync-with-document';
 
 export function init() {
 	registerSlice( slice );
@@ -28,6 +29,16 @@ export function init() {
 		component: PopulateStore,
 	} );
 
+	injectIntoLogic( {
+		id: 'global-classes-sync-with-document',
+		component: SyncWithDocumentSave,
+	} );
+
+	injectIntoLogic( {
+		id: 'global-classes-prefetch-css-class-usage',
+		component: PrefetchCssClassUsage,
+	} );
+
 	injectIntoCssClassConvert( {
 		id: 'global-classes-convert-from-local-class',
 		component: ConvertLocalClassToGlobalClass,
@@ -43,7 +54,5 @@ export function init() {
 		getThemeColor: ( theme ) => theme.palette.global.dark,
 	} );
 
-	listenTo( v1ReadyEvent(), () => {
-		syncWithDocumentSave();
-	} );
+	initMcpIntegration();
 }

package/src/mcp-integration/classes-resource.ts

@@ -0,0 +1,20 @@
+import { getMCPByDomain } from '@elementor/editor-mcp';
+
+export const GLOBAL_CLASSES_URI = 'elementor://classes';
+
+export const initClassesResource = () => {
+	const { mcpServer } = getMCPByDomain( 'classes' );
+
+	mcpServer.resource(
+		'global-classes',
+		GLOBAL_CLASSES_URI,
+		{
+			description: 'Global classes list.',
+		},
+		async () => {
+			return {
+				contents: [ { uri: GLOBAL_CLASSES_URI, text: localStorage[ 'elementor-global-classes' ] ?? {} } ],
+			};
+		}
+	);
+};

package/src/mcp-integration/index.ts

@@ -0,0 +1,15 @@
+import { getMCPByDomain } from '@elementor/editor-mcp';
+
+import { initClassesResource } from './classes-resource';
+import initMcpApplyUnapplyGlobalClasses from './mcp-apply-unapply-global-classes';
+import initMcpApplyGetGlobalClassUsages from './mcp-get-global-class-usages';
+
+export const initMcpIntegration = () => {
+	const reg = getMCPByDomain( 'classes' );
+	reg.setMCPDescription(
+		'Tools for managing and applying Global CSS classes to elements within the Elementor editor.'
+	);
+	initMcpApplyUnapplyGlobalClasses( reg );
+	initMcpApplyGetGlobalClassUsages( reg );
+	initClassesResource();
+};

package/src/mcp-integration/mcp-apply-unapply-global-classes.ts

@@ -0,0 +1,117 @@
+import { doApplyClasses, doGetAppliedClasses, doUnapplyClass } from '@elementor/editor-editing-panel';
+import { type MCPRegistryEntry } from '@elementor/editor-mcp';
+import { stylesRepository } from '@elementor/editor-styles-repository';
+import { z } from '@elementor/schema';
+
+export default function initMcpApplyUnapplyGlobalClasses( server: MCPRegistryEntry ) {
+	server.addTool( {
+		name: 'list-all-global-classes',
+		description: `List all classes applied to a specific element
+
+## When to use this tool:
+- When a user requests to see which classes or global classes exists.
+- When you need the list of global classes to allow the user to select from.
+- At least once before applying or unapplying a class, to ensure the class ID is correct.
+
+`,
+		outputSchema: {
+			appliedClasses: z.array(
+				z.object( {
+					id: z.string().describe( 'The ID of the class' ),
+					label: z.string().describe( 'The label of the class' ),
+					variants: z.array(
+						z.object( {
+							meta: z.object( {
+								breakpoint: z.string().optional(),
+								state: z.string().optional(),
+							} ),
+							props: z.record( z.any() ),
+						} )
+					),
+				} )
+			),
+		},
+		handler: async () => {
+			const globalClassesProvider = stylesRepository.getProviderByKey( 'global-classes' );
+			if ( ! globalClassesProvider ) {
+				throw new Error( 'Global classes provider not found' );
+			}
+			const result: {
+				id: string;
+				label: string;
+				variants: {
+					meta: { breakpoint?: string | undefined; state?: string | undefined };
+					props: Record< string, unknown >;
+				}[];
+			}[] = [];
+			globalClassesProvider.actions.all().forEach( ( style ) => {
+				const { id, label, variants } = style;
+				result.push( {
+					id,
+					label,
+					variants: variants.map( ( variant ) => ( {
+						meta: {
+							breakpoint: variant.meta.breakpoint as string | undefined,
+							state: variant.meta.state as string | undefined,
+						},
+						props: variant.props as Record< string, unknown >,
+					} ) ),
+				} );
+			} );
+			return { appliedClasses: result };
+		},
+	} );
+
+	server.addTool( {
+		schema: {
+			classId: z.string().describe( 'The ID of the class to apply' ),
+			elementId: z.string().describe( 'The ID of the element to which the class will be applied' ),
+		},
+		name: 'apply-global-class',
+		description: `Apply a global class to the current element
+
+## When to use this tool:
+- When a user requests to apply a global class or a class to an element in the Elementor editor.
+- When you need to add a specific class to an element's applied classes.
+
+## Prerequisites:
+- Ensure you have the most up-to-date list of classes applied to the element to avoid duplicates. You can use the "list-applied-classes" tool to fetch the current classes.
+- Make sure you have the correct class ID that you want to apply.`,
+		handler: async ( params ) => {
+			const { classId, elementId } = params;
+			const appliedClasses = doGetAppliedClasses( elementId );
+			doApplyClasses( elementId, [ ...appliedClasses, classId ] );
+			return `Class ${ classId } applied to element ${ elementId } successfully.`;
+		},
+	} );
+
+	server.addTool( {
+		name: 'unapply-global-class',
+		schema: {
+			classId: z.string().describe( 'The ID of the class to unapply' ),
+			elementId: z.string().describe( 'The ID of the element from which the class will be unapplied' ),
+		},
+		description: `Unapply a (global) class from the current element
+
+## When to use this tool:
+- When a user requests to unapply a global class or a class from an element in the Elementor editor.
+- When you need to remove a specific class from an element's applied classes.
+
+## Prerequisites:
+- Ensure you have the most up-to-date list of classes applied to the element to avoid errors. You can use the "list-global-classes" tool to fetch the all classes applied to all elements.
+- Make sure you have the correct class ID that you want to unapply.
+
+<note>
+If the user want to unapply a class by it's name and not ID, please use the "list-global-classes" tool to get the class ID from the name first.
+</note>
+`,
+		handler: async ( params ) => {
+			const { classId, elementId } = params;
+			const ok = doUnapplyClass( elementId, classId );
+			if ( ! ok ) {
+				throw new Error( `Class ${ classId } is not applied to element ${ elementId }, cannot unapply it.` );
+			}
+			return `Class ${ classId } unapplied from element ${ elementId } successfully.`;
+		},
+	} );
+}

package/src/mcp-integration/mcp-get-global-class-usages.ts

@@ -0,0 +1,72 @@
+import { type MCPRegistryEntry } from '@elementor/editor-mcp';
+import { z } from '@elementor/schema';
+
+import { fetchCssClassUsage } from '../../service/css-class-usage-service';
+import { type CssClassUsageContent, type EnhancedCssClassUsageContent } from '../components/css-class-usage/types';
+
+export default function initMcpApplyGetGlobalClassUsages( reg: MCPRegistryEntry ) {
+	const { addTool } = reg;
+	const globalClassesUsageSchema = {
+		usages: z.array(
+			z.object( {
+				classId: z
+					.string()
+					.describe(
+						'The ID of the class, not visible to the user. To retreive the name of the class, use the "list-global-classes" tool'
+					),
+				usages: z.array(
+					z.object( {
+						pageId: z.string().describe( 'The ID of the page where the class is used' ),
+						title: z.string().describe( 'The title of the page where the class is used' ),
+						total: z.number().describe( 'The number of times the class is used on this page' ),
+						elements: z.array( z.string() ).describe( 'List of element IDs using this class on the page' ),
+					} )
+				),
+			} )
+		),
+	};
+
+	addTool( {
+		name: 'get-global-class-usages',
+		description: `Retreive the usage details of global classes within the Elementor editor, accross all pages.
+
+## Prequisites:
+- Use "list-global-classes" tool to be able to match class IDs to class names/labels.
+
+## When to use this tool:
+- When a user requests to see where a specific global class is being used accross the site.
+- When you need to manage or clean up unused global classes.
+- Before deleting a global class, to ensure it is not in use in any other pages.
+`,
+		outputSchema: globalClassesUsageSchema,
+		handler: async () => {
+			const data = await fetchCssClassUsage();
+			const result = {
+				usages: [] as z.infer< ( typeof globalClassesUsageSchema )[ 'usages' ] >,
+			};
+
+			Object.entries( data as unknown as EnhancedCssClassUsageContent ).forEach(
+				( [ classId, usageDetails ] ) => {
+					const newEntry: ( typeof result )[ 'usages' ][ 0 ] = {
+						classId,
+						usages: [],
+					};
+					if ( typeof usageDetails !== 'number' ) {
+						const { content } = usageDetails as unknown as { content: CssClassUsageContent[] };
+						content.forEach( ( detail ) => {
+							newEntry.usages.push( {
+								pageId: String( detail.pageId ),
+								title: detail.title,
+								total: detail.total,
+								elements: detail.elements,
+							} );
+						} );
+						result.usages.push( newEntry );
+					}
+				}
+			);
+
+			return result;
+		},
+	} );
+}

package/src/save-global-classes.tsx

@@ -0,0 +1,55 @@
+import * as React from 'react';
+import { openDialog } from '@elementor/editor-ui';
+import { __dispatch as dispatch, __getState as getState } from '@elementor/store';
+import { hash } from '@elementor/utils';
+
+import { API_ERROR_CODES, apiClient, type ApiContext } from './api';
+import { DuplicateLabelDialog } from './components/class-manager/duplicate-label-dialog';
+import { type GlobalClasses, selectData, selectFrontendInitialData, selectPreviewInitialData, slice } from './store';
+import { trackGlobalClasses } from './utils/tracking';
+
+type Options = {
+	context: ApiContext;
+	onApprove?: () => void;
+};
+
+export async function saveGlobalClasses( { context, onApprove }: Options ) {
+	const state = selectData( getState() );
+	const apiAction = context === 'preview' ? apiClient.saveDraft : apiClient.publish;
+	const currentContext = context === 'preview' ? selectPreviewInitialData : selectFrontendInitialData;
+	const response = await apiAction( {
+		items: state.items,
+		order: state.order,
+		changes: calculateChanges( state, currentContext( getState() ) ),
+	} );
+
+	dispatch( slice.actions.reset( { context } ) );
+	if ( response?.data?.data?.code === API_ERROR_CODES.DUPLICATED_LABEL ) {
+		dispatch( slice.actions.updateMultiple( response.data.data.modifiedLabels ) );
+		trackGlobalClasses( {
+			event: 'classPublishConflict',
+			numOfConflicts: Object.keys( response.data.data.modifiedLabels ).length,
+		} );
+		openDialog( {
+			component: (
+				<DuplicateLabelDialog
+					modifiedLabels={ response.data.data.modifiedLabels || [] }
+					onApprove={ onApprove }
+				/>
+			),
+		} );
+	}
+}
+
+function calculateChanges( state: GlobalClasses, initialData: GlobalClasses ) {
+	const stateIds = Object.keys( state.items );
+	const initialDataIds = Object.keys( initialData.items );
+
+	return {
+		added: stateIds.filter( ( id ) => ! initialDataIds.includes( id ) ),
+		deleted: initialDataIds.filter( ( id ) => ! stateIds.includes( id ) ),
+		modified: stateIds.filter( ( id ) => {
+			return id in initialData.items && hash( state.items[ id ] ) !== hash( initialData.items[ id ] );
+		} ),
+	};
+}

package/src/store.ts

@@ -1,4 +1,4 @@
-import { mergeProps, type Props } from '@elementor/editor-props';
+import { type Props } from '@elementor/editor-props';
 import {
 	type CustomCss,
 	getVariantByMeta,
@@ -32,6 +32,13 @@ type GlobalClassesState = {
 	isDirty: boolean;
 };
 
+export type ModifiedLabels = {
+	[ id: string ]: {
+		original: string;
+		modified: string;
+	};
+};
+
 const localHistory = SnapshotHistory.get< GlobalClasses >( 'global-classes' );
 
 const initialState: GlobalClassesState = {
@@ -108,6 +115,14 @@ export const slice = createSlice( {
 			state.isDirty = true;
 		},
 
+		updateMultiple( state, { payload }: PayloadAction< ModifiedLabels > ) {
+			localHistory.next( state.data );
+			Object.entries( payload ).forEach( ( [ id, { modified } ] ) => {
+				state.data.items[ id ].label = modified;
+			} );
+
+			state.isDirty = false;
+		},
 		updateProps(
 			state,
 			{
@@ -186,6 +201,22 @@ export const slice = createSlice( {
 	},
 } );
 
+const mergeProps = ( current: Props, updates: Props ): Props => {
+	// edge case, the server returns an array instead of an object when empty props because of PHP array / object conversion
+	const props = Array.isArray( current ) ? {} : current;
+
+	Object.entries( updates ).forEach( ( [ key, value ] ) => {
+		if ( value === null || value === undefined ) {
+			// eslint-disable-next-line @typescript-eslint/no-dynamic-delete
+			delete props[ key ];
+		} else {
+			props[ key ] = value;
+		}
+	} );
+
+	return props;
+};
+
 const getNonEmptyVariants = ( style: StyleDefinition ) => {
 	return style.variants.filter(
 		( { props, custom_css: customCss }: StyleDefinitionVariant ) => Object.keys( props ).length || customCss?.raw

package/src/sync-with-document-save.ts

@@ -7,10 +7,10 @@ import { UPDATE_CLASS_CAPABILITY_KEY } from './capabilities';
 import { saveGlobalClasses } from './save-global-classes';
 import { selectIsDirty } from './store';
 
-export function syncWithDocumentSave() {
+export function syncWithDocumentSave( panelActions?: { open: () => void } ) {
 	const unsubscribe = syncDirtyState();
 
-	bindSaveAction();
+	bindSaveAction( panelActions );
 
 	return unsubscribe;
 }
@@ -25,19 +25,22 @@ function syncDirtyState() {
 	} );
 }
 
-function bindSaveAction() {
-	registerDataHook( 'after', 'document/save/save', ( args ) => {
+function bindSaveAction( panelActions?: { open: () => void } ) {
+	registerDataHook( 'dependency', 'document/save/save', ( args ) => {
 		const user = getCurrentUser();
 
 		const canEdit = user?.capabilities.includes( UPDATE_CLASS_CAPABILITY_KEY );
 
 		if ( ! canEdit ) {
-			return;
+			return true;
 		}
 
-		return saveGlobalClasses( {
+		saveGlobalClasses( {
 			context: args.status === 'publish' ? 'frontend' : 'preview',
+			onApprove: panelActions?.open,
 		} );
+
+		return true;
 	} );
 }
 

package/src/sync-with-document.tsx

@@ -0,0 +1,19 @@
+import { useEffect } from 'react';
+import { __privateListenTo as listenTo, v1ReadyEvent } from '@elementor/editor-v1-adapters';
+
+import { usePanelActions } from './components/class-manager/class-manager-panel';
+import { syncWithDocumentSave } from './sync-with-document-save';
+
+export function SyncWithDocumentSave() {
+	const panelActions = usePanelActions();
+
+	useEffect( () => {
+		listenTo( v1ReadyEvent(), () => {
+			syncWithDocumentSave( panelActions );
+		} );
+
+		// eslint-disable-next-line react-hooks/exhaustive-deps
+	}, [] );
+
+	return null;
+}