@elementor/editor-audits 4.3.0-1036

package/src/hooks/use-audit-report.ts

@@ -0,0 +1,43 @@
+import { useEffect } from 'react';
+import { getCurrentDocumentId } from '@elementor/editor-elements';
+import { __useDispatch as useDispatch, __useSelector as useSelector } from '@elementor/store';
+
+import { runPageAudit } from '../runner';
+import { type GlobalState, selectError, selectReport, selectStatus, slice } from '../store';
+import { getPersistedReport, persistReport } from '../utils/report-storage';
+
+export function useAuditReport() {
+	const status = useSelector( ( state: GlobalState ) => selectStatus( state ) );
+	const report = useSelector( ( state: GlobalState ) => selectReport( state ) );
+	const error = useSelector( ( state: GlobalState ) => selectError( state ) );
+	const dispatch = useDispatch();
+	const documentId = getCurrentDocumentId() ?? 0;
+
+	useEffect( () => {
+		if ( ! documentId || report?.documentId === documentId ) {
+			return;
+		}
+
+		const persisted = getPersistedReport( documentId );
+
+		if ( persisted ) {
+			dispatch( slice.actions.reportRestored( persisted ) );
+		} else if ( report ) {
+			dispatch( slice.actions.reportCleared() );
+		}
+	}, [ documentId, report, dispatch ] );
+
+	const run = async ( documentIdToRun: number ) => {
+		dispatch( slice.actions.runStarted() );
+
+		try {
+			const nextReport = await runPageAudit( documentIdToRun );
+			dispatch( slice.actions.runSucceeded( nextReport ) );
+			persistReport( documentIdToRun, nextReport );
+		} catch ( e ) {
+			dispatch( slice.actions.runFailed( e instanceof Error ? e.message : 'Unknown error' ) );
+		}
+	};
+
+	return { status, report, error, run };
+}

package/src/hooks/use-audit-toggle-props.ts

@@ -0,0 +1,17 @@
+import { type ToggleActionProps } from '@elementor/editor-app-bar';
+import { ShieldCheckIcon } from '@elementor/icons';
+import { __ } from '@wordpress/i18n';
+
+import { auditPanel } from '../editor-panel';
+
+export function useAuditToggleProps(): ToggleActionProps {
+	const { isOpen } = auditPanel.useFloatingPanelStatus();
+	const { toggle } = auditPanel.useFloatingPanelActions();
+
+	return {
+		title: __( 'Audit Page', 'elementor' ),
+		icon: ShieldCheckIcon,
+		selected: isOpen,
+		onClick: () => toggle(),
+	};
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+export { init } from './init';
+export { registerAudit } from './registry';
+export { runPageAudit } from './runner';
+export type {
+	Audit,
+	AuditCategory,
+	AuditContext,
+	AuditMeta,
+	AuditResult,
+	AuditRun,
+	AuditSeverity,
+	AuditViolation,
+	PageAuditReport,
+} from './types';

package/src/init.ts

@@ -0,0 +1,14 @@
+import { registerFloatingPanel } from '@elementor/editor-floating-panels';
+import { __registerSlice as registerSlice } from '@elementor/store';
+
+import { registerAppBarAuditsToggle } from './editor-app-bar';
+import { auditPanel } from './editor-panel';
+import { registerAllAudits } from './register-audits';
+import { slice } from './store/slice';
+
+export function init(): void {
+	registerSlice( slice );
+	registerAllAudits();
+	registerFloatingPanel( auditPanel.panel );
+	registerAppBarAuditsToggle();
+}

package/src/register-audits.ts

@@ -0,0 +1,56 @@
+import * as accessibilityPolicy from './audits/accessibility-policy';
+import * as cookiePolicy from './audits/cookie-policy';
+import * as deepNesting from './audits/deep-nesting';
+import * as defaultDesignSystem from './audits/default-design-system';
+import * as deprecatedWidgets from './audits/deprecated-widgets';
+import * as headingStructure from './audits/heading-structure';
+import * as hiddenElements from './audits/hidden-elements';
+import * as imagesAltText from './audits/images-alt-text';
+import * as imagesTooLarge from './audits/images-too-large';
+import * as nestedBoxedContainers from './audits/nested-boxed-containers';
+import * as pageExcerpt from './audits/page-excerpt';
+import * as pageFeaturedImage from './audits/page-featured-image';
+import * as pageTitle from './audits/page-title';
+import * as preferGlobalColors from './audits/prefer-global-colors';
+import * as preferGlobalFonts from './audits/prefer-global-fonts';
+import * as privacyPolicy from './audits/privacy-policy';
+import * as robotsNoindex from './audits/robots-noindex';
+import * as sectionsAndColumns from './audits/sections-and-columns';
+import * as siteIdentity from './audits/site-identity';
+import * as tooManyWidgets from './audits/too-many-widgets';
+import { registerAudit } from './registry';
+import { type Audit } from './types';
+
+const AUDITS: Audit[] = [
+	pageTitle.audit,
+	pageExcerpt.audit,
+	pageFeaturedImage.audit,
+
+	hiddenElements.audit,
+	deprecatedWidgets.audit,
+	tooManyWidgets.audit,
+	sectionsAndColumns.audit,
+	deepNesting.audit,
+	nestedBoxedContainers.audit,
+
+	defaultDesignSystem.audit,
+	siteIdentity.audit,
+	preferGlobalColors.audit,
+	preferGlobalFonts.audit,
+
+	headingStructure.audit,
+	imagesAltText.audit,
+	imagesTooLarge.audit,
+
+	robotsNoindex.audit,
+
+	privacyPolicy.audit,
+	accessibilityPolicy.audit,
+	cookiePolicy.audit,
+];
+
+export function registerAllAudits(): void {
+	for ( const audit of AUDITS ) {
+		registerAudit( audit );
+	}
+}

package/src/register-promotions.ts

@@ -0,0 +1,75 @@
+import { ElementorCookieIcon, PhotoIcon, ShieldHalfFilledIcon } from '@elementor/icons';
+import { __, _n, sprintf } from '@wordpress/i18n';
+
+import { type AuditRun } from './types';
+
+export type PromotionIcon = typeof PhotoIcon;
+
+export type PromotionConfig = {
+	auditId: string;
+	icon: PromotionIcon;
+	ctaLabel: string;
+	formatSubtitle: ( run: AuditRun ) => string | null;
+	getCtaUrl: ( run: AuditRun ) => string | undefined;
+};
+
+function firstFailExternalUrl( run: AuditRun ): string | undefined {
+	return run.result.status === 'fail' ? run.result.violations[ 0 ]?.externalUrl : undefined;
+}
+
+export const PROMOTIONS: PromotionConfig[] = [
+	{
+		auditId: 'audits/images-alt-text',
+		icon: PhotoIcon,
+		ctaLabel: __( 'Fix with Ally', 'elementor' ),
+		formatSubtitle: ( run ) => {
+			if ( run.result.status !== 'fail' ) {
+				return null;
+			}
+
+			const count = run.result.metadata?.missingAltImageCount ?? 0;
+
+			if ( count === 0 ) {
+				return null;
+			}
+
+			return sprintf(
+				/* translators: %d: number of images missing alt text. */
+				_n( '%d image', '%d images', count, 'elementor' ),
+				count
+			);
+		},
+		getCtaUrl: firstFailExternalUrl,
+	},
+	{
+		auditId: 'audits/cookie-policy',
+		icon: ElementorCookieIcon,
+		ctaLabel: __( 'Fix with Cookiez', 'elementor' ),
+		formatSubtitle: ( run ) =>
+			run.result.status === 'fail' ? __( 'Generate cookie policy', 'elementor' ) : null,
+		getCtaUrl: firstFailExternalUrl,
+	},
+	{
+		auditId: 'audits/images-too-large',
+		icon: ShieldHalfFilledIcon,
+		ctaLabel: __( 'Optimize all', 'elementor' ),
+		formatSubtitle: ( run ) => {
+			if ( run.result.status !== 'fail' ) {
+				return null;
+			}
+
+			const count = run.result.metadata?.oversizedImageCount ?? 0;
+
+			if ( count === 0 ) {
+				return null;
+			}
+
+			return sprintf(
+				/* translators: %d: number of oversized images. */
+				_n( '%d image', '%d images', count, 'elementor' ),
+				count
+			);
+		},
+		getCtaUrl: firstFailExternalUrl,
+	},
+];

package/src/registry.ts

@@ -0,0 +1,19 @@
+import { type Audit } from './types';
+
+const registry = new Map< string, Audit >();
+
+export function registerAudit( audit: Audit ): void {
+	registry.set( audit.id, audit );
+}
+
+export function getRegisteredAudits(): Audit[] {
+	return Array.from( registry.values() );
+}
+
+export function hasAudit( id: string ): boolean {
+	return registry.has( id );
+}
+
+export function clearAuditRegistry(): void {
+	registry.clear();
+}

package/src/runner.ts

@@ -0,0 +1,44 @@
+import { getElements } from '@elementor/editor-elements';
+
+import { fetchPageContext } from './api/page-context-client';
+import { getRegisteredAudits } from './registry';
+import {
+	type Audit,
+	type AuditContext,
+	type AuditMeta,
+	type AuditRun,
+	type ElementsModelSnapshot,
+	type KitSnapshot,
+	type PageAuditReport,
+} from './types';
+import { computeReport } from './utils/compute-report';
+import { extractAttachmentIds } from './utils/page-attachments';
+import { readKitSnapshot } from './utils/read-kit-snapshot';
+import { buildSnapshotTree } from './utils/v1-snapshot';
+
+export async function runPageAudit( documentId: number ): Promise< PageAuditReport > {
+	const tree = buildSnapshotTree( getElements() );
+	const attachmentIds = extractAttachmentIds( tree );
+	const pageContext = await fetchPageContext( documentId, attachmentIds );
+
+	const elements: ElementsModelSnapshot = { documentId, tree };
+	const kit: KitSnapshot = await readKitSnapshot( pageContext.kit_id );
+
+	const ctx: AuditContext = { documentId, elements, pageContext, kit };
+	const registered = getRegisteredAudits();
+
+	const auditResults: AuditRun[] = await Promise.all(
+		registered.map( async ( audit ) => {
+			const { evaluate: _evaluate, ...meta }: AuditMeta & Pick< Audit, 'evaluate' > = audit;
+			try {
+				const result = await audit.evaluate( ctx );
+				return { audit: meta, result };
+			} catch ( error ) {
+				const reason = error instanceof Error ? error.message : 'unknown-error';
+				return { audit: meta, result: { status: 'skipped' as const, reason } };
+			}
+		} )
+	);
+
+	return computeReport( documentId, auditResults );
+}

package/src/store/index.ts

@@ -0,0 +1,2 @@
+export { slice, type AuditsSliceState } from './slice';
+export * from './selectors';

package/src/store/selectors.ts

@@ -0,0 +1,15 @@
+import { type AuditsSliceState } from './slice';
+
+export type GlobalState = { audits: AuditsSliceState };
+
+export function selectStatus( state: GlobalState ) {
+	return state.audits.status;
+}
+
+export function selectReport( state: GlobalState ) {
+	return state.audits.report;
+}
+
+export function selectError( state: GlobalState ) {
+	return state.audits.error;
+}

package/src/store/slice.ts

@@ -0,0 +1,42 @@
+import { __createSlice, type PayloadAction } from '@elementor/store';
+
+import { type PageAuditReport } from '../types';
+
+type SliceState = {
+	status: 'idle' | 'loading' | 'error' | 'ready';
+	report: PageAuditReport | null;
+	error: string | null;
+};
+
+const initialState: SliceState = { status: 'idle', report: null, error: null };
+
+export const slice = __createSlice( {
+	name: 'audits',
+	initialState,
+	reducers: {
+		runStarted( state ) {
+			state.status = 'loading';
+			state.error = null;
+		},
+		runSucceeded( state, action: PayloadAction< PageAuditReport > ) {
+			state.status = 'ready';
+			state.report = action.payload;
+		},
+		runFailed( state, action: PayloadAction< string > ) {
+			state.status = 'error';
+			state.error = action.payload;
+		},
+		reportRestored( state, action: PayloadAction< PageAuditReport > ) {
+			state.status = 'ready';
+			state.report = action.payload;
+			state.error = null;
+		},
+		reportCleared( state ) {
+			state.status = 'idle';
+			state.report = null;
+			state.error = null;
+		},
+	},
+} );
+
+export type AuditsSliceState = SliceState;

package/src/types.ts

@@ -0,0 +1,112 @@
+export type Audit = {
+	id: string;
+	title: string;
+	description: string;
+	fixHint: string;
+	categories: AuditCategory[];
+	severity: AuditSeverity;
+	weight: number;
+	evaluate: ( ctx: AuditContext ) => AuditResult | Promise< AuditResult >;
+};
+
+export type AuditCategory = 'best-practices' | 'seo' | 'accessibility' | 'performance' | 'compliance';
+
+export type AuditSeverity = 'error' | 'warning' | 'info';
+
+export type AuditMeta = Omit< Audit, 'evaluate' >;
+
+export type AuditRun = {
+	audit: AuditMeta;
+	result: AuditResult;
+};
+
+export type AuditFailMetadata = {
+	missingAltImageCount?: number;
+	oversizedImageCount?: number;
+};
+
+export type AuditResult =
+	| { status: 'pass' }
+	| { status: 'fail'; violations: AuditViolation[]; metadata?: AuditFailMetadata }
+	| { status: 'skipped'; reason: string };
+
+export type AuditViolation = {
+	auditId: string;
+	elementId?: string;
+	targetHint?: 'page-settings' | 'site-settings' | 'site-identity-settings' | 'element-settings';
+	externalUrl?: string;
+	label: string;
+	detail?: string;
+	angieFix?: boolean;
+};
+
+export type PageContextResponse = {
+	post_title: string | null;
+	post_excerpt: string | null;
+	featured_image_id: number | null;
+	image_sizes: Record<
+		number,
+		{
+			width: number;
+			height: number;
+			filesize_bytes: number;
+			mime: string;
+			src: string;
+			alt: string;
+		}
+	>;
+	kit_id: number;
+	kit_is_default_unchanged: boolean;
+	is_noindex: boolean;
+	reading_settings_url: string;
+	privacy_policy_url: string | null;
+	privacy_settings_url: string;
+	ally_plugin_active: boolean;
+	ally_plugin_url: string;
+	cookiez_plugin_active: boolean;
+	cookiez_plugin_url: string;
+	image_optimization_plugin_active: boolean;
+	image_optimization_plugin_url: string;
+	site_identity: {
+		site_name_set: boolean;
+		site_description_set: boolean;
+		site_logo_set: boolean;
+		site_favicon_set: boolean;
+	};
+};
+
+export type ElementSnapshotNode = {
+	id: string;
+	elType: string;
+	widgetType?: string;
+	settings: Record< string, unknown >;
+	elements: ElementSnapshotNode[];
+};
+
+export type ElementsModelSnapshot = {
+	documentId: number;
+	tree: ElementSnapshotNode[];
+};
+
+export type KitSnapshot = {
+	id: number;
+	globals: {
+		colors: Array< { id: string; value: string; title: string } >;
+		fonts: Array< { id: string; value: string; title: string } >;
+	};
+};
+
+export type AuditContext = {
+	documentId: number;
+	elements: ElementsModelSnapshot;
+	pageContext: PageContextResponse;
+	kit: KitSnapshot;
+};
+
+export type PageAuditReport = {
+	documentId: number;
+	runAt: number;
+	overall: number;
+	categories: Record< AuditCategory, { score: number; failed: number; total: number } >;
+	auditResults: AuditRun[];
+};

package/src/utils/audit-status-summary.ts

@@ -0,0 +1,112 @@
+import { type ChipProps } from '@elementor/ui';
+import { __ } from '@wordpress/i18n';
+
+import { type AuditCategory, type AuditResult, type AuditRun, type PageAuditReport } from '../types';
+import { sortFailedAuditResults } from './sort-failed-audits';
+
+export type AuditStatusGroup = 'fail' | 'pass' | 'skipped';
+
+export type PartitionedAuditResults = {
+	failed: Array< AuditRun & { result: Extract< AuditResult, { status: 'fail' } > } >;
+	passed: Array< AuditRun & { result: Extract< AuditResult, { status: 'pass' } > } >;
+	skipped: Array< AuditRun & { result: Extract< AuditResult, { status: 'skipped' } > } >;
+	totalViolations: number;
+};
+
+type PartitionOptions = {
+	category?: AuditCategory;
+	sortFailed?: boolean;
+};
+
+export function partitionAuditResults(
+	report: PageAuditReport,
+	options: PartitionOptions = {}
+): PartitionedAuditResults {
+	const { category, sortFailed = true } = options;
+	const failed: PartitionedAuditResults[ 'failed' ] = [];
+	const passed: PartitionedAuditResults[ 'passed' ] = [];
+	const skipped: PartitionedAuditResults[ 'skipped' ] = [];
+
+	let totalViolations = 0;
+
+	for ( const run of report.auditResults ) {
+		if ( category && ! run.audit.categories.includes( category ) ) {
+			continue;
+		}
+
+		switch ( run.result.status ) {
+			case 'fail':
+				failed.push( { ...run, result: run.result } );
+				totalViolations += run.result.violations.length;
+				break;
+			case 'pass':
+				passed.push( { ...run, result: run.result } );
+				break;
+			case 'skipped':
+				skipped.push( { ...run, result: run.result } );
+				break;
+		}
+	}
+
+	return {
+		failed: sortFailed ? sortFailedAuditResults( failed ) : failed,
+		passed,
+		skipped,
+		totalViolations,
+	};
+}
+
+export function auditStatusDisplayCounts( report: PageAuditReport ): Record< AuditStatusGroup, number > {
+	let pass = 0;
+	let skipped = 0;
+	let totalViolations = 0;
+
+	for ( const { result } of report.auditResults ) {
+		switch ( result.status ) {
+			case 'fail':
+				totalViolations += result.violations.length;
+				break;
+			case 'pass':
+				pass++;
+				break;
+			case 'skipped':
+				skipped++;
+				break;
+		}
+	}
+
+	return {
+		fail: totalViolations,
+		pass,
+		skipped,
+	};
+}
+
+export function auditStatusColor( status: AuditStatusGroup ): ChipProps[ 'color' ] {
+	switch ( status ) {
+		case 'fail':
+			return 'error';
+		case 'pass':
+			return 'success';
+		case 'skipped':
+			return 'default';
+	}
+}
+
+export function auditStatusLabel( status: AuditStatusGroup ): string {
+	switch ( status ) {
+		case 'fail':
+			return __( 'Failed audits', 'elementor' );
+		case 'pass':
+			return __( 'Passed audits', 'elementor' );
+		case 'skipped':
+			return __( 'Skipped audits', 'elementor' );
+	}
+}
+
+export function getPopulatedCategories(
+	categoryTotals: PageAuditReport[ 'categories' ],
+	categories: readonly AuditCategory[]
+): AuditCategory[] {
+	return categories.filter( ( category ) => categoryTotals[ category ].total > 0 );
+}

package/src/utils/build-angie-prompt.ts

@@ -0,0 +1,9 @@
+import { __, sprintf } from '@wordpress/i18n';
+
+export function buildAngiePrompt( violationText: string ): string {
+	return sprintf(
+		/* translators: %s: audit violation description. */
+		__( 'Help me fix: %s', 'elementor' ),
+		violationText
+	);
+}

package/src/utils/collect-hardcoded-colors.ts

@@ -0,0 +1,74 @@
+const RESERVED_SETTING_KEYS = new Set( [ '__globals__', '__dynamic__' ] );
+const REPEATER_ROW_ID_KEY = '_id';
+
+const HEX_COLOR_PATTERN = /^#[0-9a-f]{3,8}$/i;
+const RGB_COLOR_PATTERN = /^rgba?\(/i;
+
+export type HardcodedColor = {
+	path: string;
+	value: string;
+};
+
+function isGlobalColorReference( value: string ): boolean {
+	return value.startsWith( 'globals/' );
+}
+
+function isHardcodedColorCandidate( value: string ): boolean {
+	const trimmed = value.trim();
+
+	return HEX_COLOR_PATTERN.test( trimmed ) || RGB_COLOR_PATTERN.test( trimmed );
+}
+
+function formatPath( prefix: string, key: string ): string {
+	return prefix ? `${ prefix }.${ key }` : key;
+}
+
+function formatArrayPath( prefix: string, index: number ): string {
+	return `${ prefix }[${ index }]`;
+}
+
+export function collectHardcodedColors( settings: Record< string, unknown >, pathPrefix = '' ): HardcodedColor[] {
+	const linkedGlobals = ( settings.__globals__ ?? {} ) as Record< string, string >;
+	const results: HardcodedColor[] = [];
+
+	for ( const [ key, value ] of Object.entries( settings ) ) {
+		if ( RESERVED_SETTING_KEYS.has( key ) || key === REPEATER_ROW_ID_KEY ) {
+			continue;
+		}
+
+		if ( linkedGlobals[ key ] ) {
+			continue;
+		}
+
+		if ( typeof value === 'string' ) {
+			if ( ! isGlobalColorReference( value ) && isHardcodedColorCandidate( value ) ) {
+				results.push( { path: formatPath( pathPrefix, key ), value } );
+			}
+			continue;
+		}
+
+		if ( Array.isArray( value ) ) {
+			const arrayPath = formatPath( pathPrefix, key );
+
+			value.forEach( ( item, index ) => {
+				if ( item && typeof item === 'object' && ! Array.isArray( item ) ) {
+					results.push(
+						...collectHardcodedColors(
+							item as Record< string, unknown >,
+							formatArrayPath( arrayPath, index )
+						)
+					);
+				}
+			} );
+			continue;
+		}
+
+		if ( value && typeof value === 'object' ) {
+			results.push(
+				...collectHardcodedColors( value as Record< string, unknown >, formatPath( pathPrefix, key ) )
+			);
+		}
+	}
+
+	return results;
+}