@elementor/editor-canvas 4.3.3 → 4.3.5

package/src/mcp/tools/find-icons/tool.ts

@@ -0,0 +1,153 @@
+import { type MCPRegistryEntry } from '@elementor/editor-mcp';
+import { type HttpResponse, httpService } from '@elementor/http-client';
+import { z } from '@elementor/schema';
+
+import { getMcpErrorMessage } from '../../utils/get-mcp-error-message';
+import { findIconsToolPrompt } from './prompt';
+
+const MCP_PROXY_URL = 'elementor/v1/mcp-proxy';
+
+const MAX_QUERIES = 10;
+
+const MAX_PER_PAGE = 25;
+
+type IconMatch = {
+	value: string;
+	library: string;
+	name: string;
+	label: string;
+	matched_on: 'name' | 'alias' | 'term' | 'category' | 'library';
+	license: 'free' | 'pro';
+};
+
+type IconQueryResult = {
+	query: string;
+	matches: IconMatch[];
+	total: number;
+	page: number;
+	per_page: number;
+	truncated: boolean;
+};
+
+// NOTE: shape defined by Find_Icons_Ability::execute() in modules/mcp/abilities/find-icons-ability.php
+type FindIconsResponse = {
+	results: IconQueryResult[];
+	libraries?: string[];
+	custom_libraries?: Record< string, string >;
+	categories?: string[];
+	truncated_custom_libraries?: string[];
+	font_awesome_version: string | null;
+	llm_instructions?: string;
+};
+
+export const initFindIconsTool = ( reg: MCPRegistryEntry ) => {
+	const { addTool } = reg;
+
+	addTool( {
+		name: 'find-icons',
+		description: findIconsToolPrompt.prompt(),
+		schema: {
+			queries: z
+				.array( z.string() )
+				.max( MAX_QUERIES )
+				.optional()
+				.describe(
+					'One plain-language phrase per icon you need, for example ["add to cart", "free shipping"]. Batch every icon a page needs into a single call.'
+				),
+			library: z
+				.string()
+				.optional()
+				.describe(
+					'Restrict results to one library key reported in "libraries", for example "fa-solid". Omit to search every library installed on the site.'
+				),
+			category: z
+				.string()
+				.optional()
+				.describe(
+					'Restrict results to one Font Awesome category reported in "categories", for example "shopping". May be used without a query to browse that category.'
+				),
+			page: z.number().int().min( 1 ).optional(),
+			perPage: z.number().int().min( 1 ).max( MAX_PER_PAGE ).optional(),
+		},
+		outputSchema: {
+			results: z
+				.array(
+					z.object( {
+						query: z.string(),
+						matches: z.array(
+							z.object( {
+								value: z.string(),
+								library: z.string(),
+								name: z.string(),
+								label: z.string(),
+								matched_on: z.enum( [ 'name', 'alias', 'term', 'category', 'library' ] ),
+								license: z.enum( [ 'free', 'pro' ] ),
+							} )
+						),
+						total: z.number(),
+						page: z.number(),
+						per_page: z.number(),
+						truncated: z.boolean(),
+					} )
+				)
+				.describe(
+					'One entry per query, each with ranked "matches". Every match carries the "value" and "library" pair to write on the e-svg icon prop, plus "matched_on" and "license".'
+				),
+			libraries: z
+				.array( z.string() )
+				.optional()
+				.describe(
+					'Icon library keys installed on this site. Only sent when nothing matched or when browsing.'
+				),
+			customLibraries: z
+				.record( z.string(), z.string() )
+				.optional()
+				.describe(
+					'Custom (uploaded) icon libraries keyed by library. Only sent when nothing matched or when browsing.'
+				),
+			categories: z
+				.array( z.string() )
+				.optional()
+				.describe(
+					'Icon categories for the "category" filter. Only sent when nothing matched or when browsing.'
+				),
+			truncatedCustomLibraries: z
+				.array( z.string() )
+				.optional()
+				.describe( 'Custom libraries with more than 250 icons; only their first 250 icons are searchable.' ),
+			fontAwesomeVersion: z.string().nullable().describe( 'Font Awesome version the site renders icons from.' ),
+			llmInstructions: z
+				.string()
+				.optional()
+				.describe( 'Present only when nothing matched, explaining what to do next.' ),
+		},
+		handler: async ( { queries, library, category, page, perPage } ) => {
+			try {
+				const { data } = await httpService().post< HttpResponse< FindIconsResponse > >( MCP_PROXY_URL, {
+					tool: 'find-icons',
+					input: {
+						...( queries ? { queries } : {} ),
+						...( library ? { library } : {} ),
+						...( category ? { category } : {} ),
+						...( page ? { page } : {} ),
+						...( perPage ? { per_page: perPage } : {} ),
+					},
+				} );
+
+				return {
+					results: data.data.results,
+					...( data.data.libraries ? { libraries: data.data.libraries } : {} ),
+					...( data.data.custom_libraries ? { customLibraries: data.data.custom_libraries } : {} ),
+					...( data.data.categories ? { categories: data.data.categories } : {} ),
+					...( data.data.truncated_custom_libraries
+						? { truncatedCustomLibraries: data.data.truncated_custom_libraries }
+						: {} ),
+					fontAwesomeVersion: data.data.font_awesome_version,
+					...( data.data.llm_instructions ? { llmInstructions: data.data.llm_instructions } : {} ),
+				};
+			} catch ( error ) {
+				throw new Error( getMcpErrorMessage( error, 'find-icons' ) );
+			}
+		},
+	} );
+};

package/src/transformers/shared/__tests__/icon-transformer.test.ts

@@ -1,3 +1,9 @@
+jest.mock( '@elementor/http-client', () => ( {
+	httpService: () => ( {
+		get: jest.fn().mockRejectedValue( new Error( 'no custom svg' ) ),
+	} ),
+} ) );
+
 import { resetFontAwesome7IconsCache } from '@elementor/editor-controls';
 import { iconPropTypeUtil, stringPropTypeUtil } from '@elementor/editor-props';
 
@@ -41,6 +47,7 @@ async function resolveSavedIcon( iconClass: string, library: string ) {
 
 describe( 'iconTransformer', () => {
 	const originalElementorCommon = window.elementorCommon;
+	const originalElementor = window.elementor;
 
 	beforeEach( () => {
 		jest.clearAllMocks();
@@ -63,6 +70,7 @@ describe( 'iconTransformer', () => {
 
 	afterEach( () => {
 		window.elementorCommon = originalElementorCommon;
+		window.elementor = originalElementor;
 		jest.restoreAllMocks();
 	} );
 
@@ -178,6 +186,37 @@ describe( 'iconTransformer', () => {
 		expect( result ).toEqual( { html: null, url: null } );
 	} );
 
+	it( 'falls back to the default svg when a custom library has been deleted', async () => {
+		// Arrange.
+		window.elementor = {
+			config: {
+				icons: {
+					libraries: [ { name: 'fa-solid', prefix: 'fa-', native: true } ],
+				},
+			},
+		} as typeof window.elementor;
+		const defaultSvg =
+			'<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 50 50"><path d="M24.9999 4.31543"></path></svg>';
+		global.fetch = jest.fn().mockResolvedValue( {
+			ok: true,
+			headers: new Headers( { 'content-type': 'image/svg+xml' } ),
+			text: () => Promise.resolve( defaultSvg ),
+		} );
+
+		// Act.
+		const result = await resolveSavedIcon( 'missing-set missing-set-ghost', 'missing-set' );
+
+		// Assert.
+		expect( global.fetch ).toHaveBeenCalledWith(
+			'https://example.com/assets/images/default-svg.svg',
+			expect.anything()
+		);
+		expect( result ).toEqual( {
+			html: expect.stringContaining( 'M24.9999 4.31543' ),
+			url: 'https://example.com/assets/images/default-svg.svg',
+		} );
+	} );
+
 	it( 'returns null html when value or library is missing', async () => {
 		// Act.
 		const resolve = createPropsResolver( {

package/src/transformers/shared/icon-transformer.ts

@@ -1,16 +1,20 @@
 import {
 	type FontAwesome7IconDefinition,
 	getFontAwesome7IconName,
+	isDeletedCustomIconLibrary,
+	resolveCustomIconSvg,
 	resolveFontAwesome7Icon,
 } from '@elementor/editor-controls';
 
 import { createTransformer } from '../create-transformer';
 import type { TransformerOptions } from '../types';
 import { processSvgContent } from './process-svg-content';
+import { svgSrcTransformer } from './svg-src-transformer';
 
 const EMPTY_ICON_RESULT = { html: null, url: null };
 const ICON_SVG_SIZE = '100%';
 const ICON_SVG_OVERFLOW = 'visible';
+const DEFAULT_SVG_RELATIVE_PATH = 'images/default-svg.svg';
 
 type IconValue = {
 	value?: unknown;
@@ -25,30 +29,70 @@ export const iconTransformer = createTransformer( async ( value: IconValue, { si
 		return EMPTY_ICON_RESULT;
 	}
 
-	const iconName = getFontAwesome7IconName( iconValue );
+	const fontAwesomeHtml = await resolveFontAwesomeSvg( library, iconValue, signal );
 
-	if ( ! iconName ) {
-		return EMPTY_ICON_RESULT;
+	if ( fontAwesomeHtml ) {
+		return { html: fontAwesomeHtml, url: null };
 	}
 
-	const iconData = await resolveFontAwesome7Icon( library, iconName, signal );
+	if ( isDeletedCustomIconLibrary( library, iconValue ) ) {
+		return resolveDefaultSvg( signal );
+	}
 
-	if ( ! iconData ) {
-		return EMPTY_ICON_RESULT;
+	const customHtml = await resolveCustomSvg( library, iconValue, signal );
+
+	if ( customHtml ) {
+		return { html: customHtml, url: null };
 	}
 
-	const svgText = buildFontAwesomeSvg( iconData );
+	return EMPTY_ICON_RESULT;
+} );
+
+async function resolveDefaultSvg( signal?: AbortSignal ) {
+	const assetsUrl = window.elementorCommon?.config?.urls?.assets;
 
-	if ( ! svgText ) {
+	if ( typeof assetsUrl !== 'string' || assetsUrl === '' ) {
 		return EMPTY_ICON_RESULT;
 	}
 
-	const html = processIconSvgContent( svgText );
+	return svgSrcTransformer(
+		{
+			id: null,
+			url: `${ assetsUrl }${ DEFAULT_SVG_RELATIVE_PATH }`,
+		},
+		{ key: 'svg', signal }
+	);
+}
 
-	return { html, url: null };
-} );
+async function resolveCustomSvg( library: string, iconValue: string, signal?: AbortSignal ): Promise< string | null > {
+	const markup = await resolveCustomIconSvg( library, iconValue, signal );
+
+	return markup ? processIconSvgContent( markup ) : null;
+}
+
+async function resolveFontAwesomeSvg(
+	library: string,
+	iconValue: string,
+	signal?: AbortSignal
+): Promise< string | null > {
+	const iconName = getFontAwesome7IconName( iconValue );
+
+	if ( ! iconName ) {
+		return null;
+	}
+
+	const iconData = await resolveFontAwesome7Icon( library, iconName, signal );
+
+	if ( ! iconData ) {
+		return null;
+	}
+
+	const svgText = buildPathSvg( iconData );
+
+	return svgText ? processIconSvgContent( svgText ) : null;
+}
 
-function buildFontAwesomeSvg( iconData: FontAwesome7IconDefinition ): string | null {
+function buildPathSvg( iconData: FontAwesome7IconDefinition ): string | null {
 	if ( iconData.paths.length === 0 ) {
 		return null;
 	}