@elementor/editor-audits 4.3.0-1036

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

@@ -0,0 +1,70 @@
+const RESERVED_SETTING_KEYS = new Set( [ '__globals__', '__dynamic__' ] );
+const REPEATER_ROW_ID_KEY = '_id';
+const FONT_FAMILY_KEY_PATTERN = /font_family/;
+
+export type HardcodedFont = {
+	path: string;
+	value: string;
+};
+
+function isGlobalFontReference( value: string ): boolean {
+	return value.startsWith( 'globals/' );
+}
+
+function isHardcodedFontCandidate( key: string, value: string ): boolean {
+	return FONT_FAMILY_KEY_PATTERN.test( key ) && value.trim().length > 0;
+}
+
+function formatPath( prefix: string, key: string ): string {
+	return prefix ? `${ prefix }.${ key }` : key;
+}
+
+function formatArrayPath( prefix: string, index: number ): string {
+	return `${ prefix }[${ index }]`;
+}
+
+export function collectHardcodedFonts( settings: Record< string, unknown >, pathPrefix = '' ): HardcodedFont[] {
+	const linkedGlobals = ( settings.__globals__ ?? {} ) as Record< string, string >;
+	const results: HardcodedFont[] = [];
+
+	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 ( ! isGlobalFontReference( value ) && isHardcodedFontCandidate( key, 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(
+						...collectHardcodedFonts(
+							item as Record< string, unknown >,
+							formatArrayPath( arrayPath, index )
+						)
+					);
+				}
+			} );
+			continue;
+		}
+
+		if ( value && typeof value === 'object' ) {
+			results.push(
+				...collectHardcodedFonts( value as Record< string, unknown >, formatPath( pathPrefix, key ) )
+			);
+		}
+	}
+
+	return results;
+}

package/src/utils/compute-report.ts

@@ -0,0 +1,51 @@
+import { ALL_CATEGORIES } from '../constants';
+import { type AuditRun, type PageAuditReport } from '../types';
+import { getPopulatedCategories } from './audit-status-summary';
+
+type CategoryAccumulator = { totalWeight: number; passedWeight: number; total: number; failed: number };
+
+export function computeReport( documentId: number, results: AuditRun[] ): PageAuditReport {
+	const accumulators = Object.fromEntries(
+		ALL_CATEGORIES.map( ( c ) => [ c, { totalWeight: 0, passedWeight: 0, total: 0, failed: 0 } ] )
+	) as Record< string, CategoryAccumulator >;
+
+	for ( const { audit, result } of results ) {
+		if ( result.status === 'skipped' ) {
+			continue;
+		}
+
+		for ( const category of audit.categories ) {
+			const acc = accumulators[ category ];
+			acc.total++;
+			acc.totalWeight += audit.weight;
+
+			if ( result.status === 'pass' ) {
+				acc.passedWeight += audit.weight;
+			} else {
+				acc.failed++;
+			}
+		}
+	}
+
+	const categories = Object.fromEntries(
+		ALL_CATEGORIES.map( ( c ) => {
+			const acc = accumulators[ c ];
+			const score = acc.totalWeight === 0 ? 0 : Math.round( ( acc.passedWeight / acc.totalWeight ) * 100 );
+			return [ c, { score, failed: acc.failed, total: acc.total } ];
+		} )
+	) as PageAuditReport[ 'categories' ];
+
+	const populated = getPopulatedCategories( categories, ALL_CATEGORIES );
+	const overall =
+		populated.length === 0
+			? 0
+			: Math.round( populated.reduce( ( sum, c ) => sum + categories[ c ].score, 0 ) / populated.length );
+
+	return {
+		documentId,
+		runAt: Date.now(),
+		overall,
+		categories,
+		auditResults: results,
+	};
+}

package/src/utils/find-audit-run.ts

@@ -0,0 +1,5 @@
+import { type AuditRun, type PageAuditReport } from '../types';
+
+export function findAuditRun( report: PageAuditReport, auditId: string ): AuditRun | undefined {
+	return report.auditResults.find( ( run ) => run.audit.id === auditId );
+}

package/src/utils/image-alt.ts

@@ -0,0 +1,19 @@
+import { type PageContextResponse } from '../types';
+import { type ImageLikeMedia } from './image-like-sources';
+
+export function hasMeaningfulAlt( media: ImageLikeMedia, pageContext: PageContextResponse ): boolean {
+	if ( ! media.id && ! media.url ) {
+		return true;
+	}
+
+	if ( media.id ) {
+		const alt = pageContext.image_sizes[ media.id ]?.alt ?? '';
+		return alt.trim().length > 0;
+	}
+
+	return ( media.alt ?? '' ).trim().length > 0;
+}
+
+export function isImageSourcePresent( media: ImageLikeMedia ): boolean {
+	return Boolean( media.id || media.url );
+}

package/src/utils/image-like-sources.ts

@@ -0,0 +1,70 @@
+import { type ElementSnapshotNode } from '../types';
+import { walkElements } from './walk';
+
+export const IMAGE_LIKE_WIDGETS = new Set( [ 'image', 'image-box', 'image-carousel', 'gallery', 'image-gallery' ] );
+
+export type ImageLikeMedia = {
+	id?: number;
+	url?: string;
+	alt?: string;
+};
+
+export type ImageLikeSourceVisit = {
+	node: ElementSnapshotNode;
+	media: ImageLikeMedia;
+};
+
+export function hasPageImages( tree: ElementSnapshotNode[] ): boolean {
+	let found = false;
+
+	walkImageLikeSources( tree, ( { media } ) => {
+		if ( media.id || media.url ) {
+			found = true;
+		}
+	} );
+
+	return found;
+}
+
+export function walkImageLikeSources(
+	tree: ElementSnapshotNode[],
+	visit: ( source: ImageLikeSourceVisit ) => void
+): void {
+	walkElements( tree, ( node ) => {
+		if ( node.elType !== 'widget' ) {
+			return;
+		}
+
+		if ( ! IMAGE_LIKE_WIDGETS.has( node.widgetType ?? '' ) ) {
+			return;
+		}
+
+		for ( const media of collectMediaFromNode( node ) ) {
+			visit( { node, media } );
+		}
+	} );
+}
+
+function collectMediaFromNode( node: ElementSnapshotNode ): ImageLikeMedia[] {
+	const sources: ImageLikeMedia[] = [];
+
+	const image = node.settings.image as ImageLikeMedia | undefined;
+
+	if ( image?.id || image?.url ) {
+		sources.push( image );
+	}
+
+	const gallery = ( node.settings.carousel ?? node.settings.gallery ?? node.settings.wp_gallery ) as
+		| ImageLikeMedia[]
+		| undefined;
+
+	if ( Array.isArray( gallery ) ) {
+		for ( const item of gallery ) {
+			if ( item?.id || item?.url ) {
+				sources.push( item );
+			}
+		}
+	}
+
+	return sources;
+}

package/src/utils/keyboard-click.ts

@@ -0,0 +1,10 @@
+import type * as React from 'react';
+
+export function onKeyboardClick( callback: () => void ) {
+	return ( event: React.KeyboardEvent ) => {
+		if ( event.key === 'Enter' || event.key === ' ' ) {
+			event.preventDefault();
+			callback();
+		}
+	};
+}

package/src/utils/match-global-by-value.ts

@@ -0,0 +1,5 @@
+export function findMatchingGlobalByValue< T extends { value: string } >( value: string, globals: T[] ): T | null {
+	const trimmed = value.trim();
+
+	return globals.find( ( global ) => global.value === trimmed ) ?? null;
+}

package/src/utils/page-attachments.ts

@@ -0,0 +1,14 @@
+import { type ElementSnapshotNode } from '../types';
+import { walkImageLikeSources } from './image-like-sources';
+
+export function extractAttachmentIds( tree: ElementSnapshotNode[] ): number[] {
+	const ids = new Set< number >();
+
+	walkImageLikeSources( tree, ( { media } ) => {
+		if ( media.id ) {
+			ids.add( media.id );
+		}
+	} );
+
+	return Array.from( ids ).sort( ( a, b ) => a - b );
+}

package/src/utils/read-kit-snapshot.ts

@@ -0,0 +1,149 @@
+import { type KitSnapshot } from '../types';
+
+type GlobalColorApiItem = {
+	id: string;
+	title?: string;
+	value?: string;
+};
+
+type GlobalTypographyApiItem = {
+	id: string;
+	title?: string;
+	value?: {
+		typography_font_family?: string;
+	};
+};
+
+type KitColorRow = {
+	_id: string;
+	color: string;
+	title?: string;
+};
+
+type KitTypographyRow = {
+	_id: string;
+	title: string;
+	typography_font_family?: string;
+};
+
+type AuditWindow = Window & {
+	elementor?: {
+		documents?: {
+			get: ( id: number ) => { config?: { settings?: { settings?: KitDocumentSettings } } } | undefined;
+		};
+	};
+	$e?: {
+		data?: {
+			get: (
+				command: string
+			) => Promise< { data?: Record< string, GlobalColorApiItem | GlobalTypographyApiItem > } >;
+		};
+	};
+};
+
+type KitDocumentSettings = {
+	system_colors?: KitColorRow[];
+	custom_colors?: KitColorRow[];
+	system_typography?: KitTypographyRow[];
+	custom_typography?: KitTypographyRow[];
+};
+
+type GlobalWithValue = { value: string };
+
+function hasNonEmptyGlobalValue< T extends GlobalWithValue >( item: T ): boolean {
+	return item.value.length > 0;
+}
+
+export async function readKitSnapshot( kitId: number ): Promise< KitSnapshot > {
+	const [ colorsFromApi, fontsFromApi ] = await Promise.all( [
+		readGlobalsFromApi( 'globals/colors', mapApiColor, hasNonEmptyGlobalValue ),
+		readGlobalsFromApi( 'globals/typography', mapApiTypography, hasNonEmptyGlobalValue ),
+	] );
+
+	const documentSettings =
+		colorsFromApi.length === 0 || fontsFromApi.length === 0 ? getKitDocumentSettings( kitId ) : null;
+
+	const colors = colorsFromApi.length > 0 ? colorsFromApi : readColorsFromKitDocumentSettings( documentSettings );
+	const fonts = fontsFromApi.length > 0 ? fontsFromApi : readFontsFromKitDocumentSettings( documentSettings );
+
+	return { id: kitId, globals: { colors, fonts } };
+}
+
+async function readGlobalsFromApi< TApiItem, TGlobal extends GlobalWithValue >(
+	command: string,
+	mapItem: ( item: TApiItem ) => TGlobal,
+	hasValue: ( item: TGlobal ) => boolean
+): Promise< TGlobal[] > {
+	const $e = ( window as AuditWindow ).$e;
+
+	if ( ! $e?.data?.get ) {
+		return [];
+	}
+
+	try {
+		const result = await $e.data.get( command );
+		const data = result?.data ?? {};
+
+		return Object.values( data )
+			.map( ( item ) => mapItem( item as TApiItem ) )
+			.filter( hasValue );
+	} catch {
+		return [];
+	}
+}
+
+function mapApiColor( item: GlobalColorApiItem ): KitSnapshot[ 'globals' ][ 'colors' ][ number ] {
+	return {
+		id: item.id,
+		value: item.value ?? '',
+		title: item.title ?? item.id,
+	};
+}
+
+function mapApiTypography( item: GlobalTypographyApiItem ): KitSnapshot[ 'globals' ][ 'fonts' ][ number ] {
+	return {
+		id: item.id,
+		value: item.value?.typography_font_family ?? '',
+		title: item.title ?? item.id,
+	};
+}
+
+function readColorsFromKitDocumentSettings(
+	settings: KitDocumentSettings | null
+): KitSnapshot[ 'globals' ][ 'colors' ] {
+	if ( ! settings ) {
+		return [];
+	}
+
+	const rows = [ ...( settings.system_colors ?? [] ), ...( settings.custom_colors ?? [] ) ];
+
+	return rows
+		.map( ( row ) => ( {
+			id: row._id,
+			value: row.color,
+			title: row.title ?? row._id,
+		} ) )
+		.filter( hasNonEmptyGlobalValue );
+}
+
+function readFontsFromKitDocumentSettings( settings: KitDocumentSettings | null ): KitSnapshot[ 'globals' ][ 'fonts' ] {
+	if ( ! settings ) {
+		return [];
+	}
+
+	const rows = [ ...( settings.system_typography ?? [] ), ...( settings.custom_typography ?? [] ) ];
+
+	return rows
+		.map( ( row ) => ( {
+			id: row._id,
+			value: row.typography_font_family ?? '',
+			title: row.title ?? row._id,
+		} ) )
+		.filter( hasNonEmptyGlobalValue );
+}
+
+function getKitDocumentSettings( kitId: number ): KitDocumentSettings | null {
+	const document = ( window as AuditWindow ).elementor?.documents?.get?.( kitId );
+
+	return document?.config?.settings?.settings ?? null;
+}

package/src/utils/report-storage.ts

@@ -0,0 +1,16 @@
+import { getSessionStorageItem, setSessionStorageItem } from '@elementor/session';
+
+import { REPORT_STORAGE_KEY_PREFIX } from '../constants';
+import { type PageAuditReport } from '../types';
+
+function getStorageKey( documentId: number ): string {
+	return `${ REPORT_STORAGE_KEY_PREFIX }/${ documentId }`;
+}
+
+export function getPersistedReport( documentId: number ): PageAuditReport | null {
+	return getSessionStorageItem< PageAuditReport >( getStorageKey( documentId ) ) ?? null;
+}
+
+export function persistReport( documentId: number, report: PageAuditReport ): void {
+	setSessionStorageItem( getStorageKey( documentId ), report );
+}

package/src/utils/score-thresholds.ts

@@ -0,0 +1,23 @@
+import { __ } from '@wordpress/i18n';
+
+export const GOOD_THRESHOLD = 90;
+export const OK_THRESHOLD = 50;
+
+export type ScoreColor = 'success' | 'warning' | 'error';
+
+export type ScoreTier = {
+	color: ScoreColor;
+	label: string;
+};
+
+export function getScoreTier( score: number ): ScoreTier {
+	if ( score >= GOOD_THRESHOLD ) {
+		return { color: 'success', label: __( 'Good', 'elementor' ) };
+	}
+
+	if ( score >= OK_THRESHOLD ) {
+		return { color: 'warning', label: __( 'Needs work', 'elementor' ) };
+	}
+
+	return { color: 'error', label: __( 'At risk', 'elementor' ) };
+}

package/src/utils/severity-counts.ts

@@ -0,0 +1,59 @@
+import { __, sprintf } from '@wordpress/i18n';
+
+import { type AuditCategory, type AuditSeverity, type PageAuditReport } from '../types';
+
+export type SeverityCounts = Record< AuditSeverity, number >;
+
+export const ALL_SEVERITIES = [ 'error', 'warning', 'info' ] as const;
+
+export function countSeverities( report: PageAuditReport, category?: AuditCategory ): SeverityCounts {
+	const counts: SeverityCounts = { error: 0, warning: 0, info: 0 };
+
+	for ( const { audit, result } of report.auditResults ) {
+		if ( result.status !== 'fail' ) {
+			continue;
+		}
+
+		if ( category && ! audit.categories.includes( category ) ) {
+			continue;
+		}
+
+		counts[ audit.severity ] += result.violations.length;
+	}
+
+	return counts;
+}
+
+export function severityPluralLabel( severity: AuditSeverity ): string {
+	switch ( severity ) {
+		case 'error':
+			return __( 'Errors', 'elementor' );
+		case 'warning':
+			return __( 'Warnings', 'elementor' );
+		case 'info':
+			return __( 'Info', 'elementor' );
+	}
+}
+
+export function severityRemainingCountLabel( severity: AuditSeverity, count: number ): string {
+	switch ( severity ) {
+		case 'error':
+			return sprintf(
+				/* translators: %d: number of remaining error violations. */
+				__( '%d errors', 'elementor' ),
+				count
+			);
+		case 'warning':
+			return sprintf(
+				/* translators: %d: number of remaining warning violations. */
+				__( '%d warnings', 'elementor' ),
+				count
+			);
+		case 'info':
+			return sprintf(
+				/* translators: %d: number of remaining info violations. */
+				__( '%d info', 'elementor' ),
+				count
+			);
+	}
+}

package/src/utils/sort-failed-audits.ts

@@ -0,0 +1,19 @@
+import { type AuditMeta, type AuditSeverity } from '../types';
+
+const SEVERITY_SORTING_RANK: Record< AuditSeverity, number > = {
+	error: 0,
+	warning: 1,
+	info: 2,
+};
+
+export function sortFailedAuditResults< T extends { audit: AuditMeta } >( results: T[] ): T[] {
+	return [ ...results ].sort( ( a, b ) => {
+		const rankDiff = SEVERITY_SORTING_RANK[ a.audit.severity ] - SEVERITY_SORTING_RANK[ b.audit.severity ];
+
+		if ( rankDiff !== 0 ) {
+			return rankDiff;
+		}
+
+		return a.audit.title.localeCompare( b.audit.title );
+	} );
+}

package/src/utils/v1-snapshot.ts

@@ -0,0 +1,27 @@
+import { type V1Element } from '@elementor/editor-elements';
+
+import { type ElementSnapshotNode } from '../types';
+
+export function buildSnapshotTree( elements: V1Element[] ): ElementSnapshotNode[] {
+	if ( elements.length === 0 ) {
+		return [];
+	}
+
+	const root = elements[ 0 ];
+	const children = root.children ?? [];
+
+	return children.map( toSnapshot );
+}
+
+function toSnapshot( element: V1Element ): ElementSnapshotNode {
+	const model = element.model;
+	const settings = element.settings?.toJSON?.() ?? {};
+
+	return {
+		id: element.id,
+		elType: ( model.get( 'elType' ) as string ) ?? '',
+		widgetType: model.get( 'widgetType' ) as string | undefined,
+		settings: settings as Record< string, unknown >,
+		elements: ( element.children ?? [] ).map( toSnapshot ),
+	};
+}

package/src/utils/walk.ts

@@ -0,0 +1,17 @@
+import { type ElementSnapshotNode } from '../types';
+
+export type WalkVisitor = ( node: ElementSnapshotNode, parents: readonly ElementSnapshotNode[] ) => void;
+
+export function walkElements( tree: ElementSnapshotNode[], visit: WalkVisitor ): void {
+	const parents: ElementSnapshotNode[] = [];
+	recurse( tree, parents, visit );
+}
+
+function recurse( nodes: ElementSnapshotNode[], parents: ElementSnapshotNode[], visit: WalkVisitor ): void {
+	for ( const node of nodes ) {
+		visit( node, parents );
+		parents.push( node );
+		recurse( node.elements, parents, visit );
+		parents.pop();
+	}
+}

package/src/utils/window-config.ts

@@ -0,0 +1,20 @@
+type WindowConfig = {
+	restNamespace: string;
+	nonce: string;
+};
+
+declare global {
+	interface Window {
+		elementorAudits?: WindowConfig;
+	}
+}
+
+export function getWindowConfig(): WindowConfig {
+	const config = window.elementorAudits;
+
+	if ( ! config ) {
+		return { restNamespace: 'elementor/v1', nonce: '' };
+	}
+
+	return config;
+}