• File: widget-context-helper.php
  • Full Path: /home/slvgwrnz/public_html/wp-content/plugins/elementor/modules/mcp/abilities/utils/widget-context-helper.php
  • Date Modified: 11/05/2026 9:17 AM
  • File size: 13.08 KB
  • MIME-type: text/x-php
  • Charset: utf-8
<?php

namespace Elementor\Modules\Mcp\Abilities\Utils;

use Elementor\Modules\AtomicWidgets\PropTypes\Base\Array_Prop_Type;
use Elementor\Modules\AtomicWidgets\PropTypes\Base\Object_Prop_Type;
use Elementor\Modules\AtomicWidgets\PropTypes\Contracts\Prop_Type;
use Elementor\Modules\AtomicWidgets\PropTypes\Escaped_Html_Prop_Type;
use Elementor\Modules\AtomicWidgets\PropTypes\Prop_Sensitivity;
use Elementor\Modules\AtomicWidgets\PropTypes\Utils\Plain_Llm_Schema_Converter;
use Elementor\Modules\GlobalClasses\Utils\Atomic_Elements_Utils;
use Elementor\Modules\Mcp\Abilities\Appliers\V3\Maps\V3_Widget_Map_Registry;
use Elementor\Plugin;
use Elementor\Utils;

if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

/**
 * Provides widget metadata for MCP abilities: eligibility checks, summaries, and JSON schemas
 * for LLM consumption. The schema output includes property types and LLM guidance.
 */
class Widget_Context_Helper {

	const NON_CONFIGURABLE_PROP_KEYS = [ '_cssid', 'classes', 'attributes', 'display-conditions' ];

	const EXCLUDED_WIDGET_TITLE = 'Component';

	const VERSION_V3 = 'v3';

	const VERSION_V4 = 'v4';

	const MCP_UNPROMOTED_ELEMENT_TYPES = [
		'e-flexbox',
	];

	const ALLOWED_HTML_TAGS_NOTE = 'May contain inline HTML written directly in the string (e.g. "Hello <strong>world</strong>"), limited to these tags: %s. Any other tag is stripped on save.';

	/**
	 * @return array<string, array> widget_type => config, filtered to widgets eligible for LLM use.
	 */
	public static function get_llm_eligible_widgets(): array {
		$eligible = [];

		foreach ( Plugin::$instance->widgets_manager->get_widget_types() as $type => $instance ) {
			$type = (string) $type;

			if ( self::is_type_unpromoted_in_widget_list( $type ) ) {
				continue;
			}

			if ( self::should_initialize_v3_controls_stack( $type ) && method_exists( $instance, 'get_stack' ) ) {
				$instance->get_stack( false );
			}

			$config = $instance->get_config();

			if ( self::is_widget_eligible_for_llm( $config ) ) {
				$eligible[ $type ] = $config;
			}
		}

		foreach ( Plugin::$instance->elements_manager->get_element_types() as $type => $instance ) {
			$type = (string) $type;

			if ( self::is_type_unpromoted_in_widget_list( $type ) ) {
				continue;
			}

			if ( self::should_initialize_v3_controls_stack( $type ) && method_exists( $instance, 'get_stack' ) ) {
				$instance->get_stack( false );
			}

			$config = $instance->get_config();

			if ( self::is_widget_eligible_for_llm( $config ) ) {
				$eligible[ $type ] = $config;
			}
		}

		return $eligible;
	}

	public static function get_widget_config( string $widget_type ): ?array {
		$instance = Atomic_Elements_Utils::get_element_instance( $widget_type );

		if ( ! $instance ) {
			return null;
		}

		if ( self::should_initialize_v3_controls_stack( $widget_type ) && method_exists( $instance, 'get_stack' ) ) {
			$instance->get_stack( false );
		}

		return $instance->get_config();
	}

	public static function is_widget_eligible_for_llm( array $config ): bool {
		if ( false === ( $config['meta']['llm_support'] ?? null ) ) {
			return false;
		}

		if ( self::EXCLUDED_WIDGET_TITLE === ( $config['title'] ?? null ) ) {
			return false;
		}

		if ( ! empty( $config['atomic_props_schema'] ) ) {
			return true;
		}

		return self::has_v3_controls( $config['controls'] ?? null );
	}

	private static function has_v3_controls( $controls ): bool {
		return is_array( $controls ) && ! empty( $controls );
	}

	public static function get_widget_version( array $config ): string {
		return empty( $config['atomic_props_schema'] ) ? self::VERSION_V3 : self::VERSION_V4;
	}

	public static function is_type_unpromoted_in_widget_list( string $widget_type ): bool {
		return in_array( $widget_type, self::MCP_UNPROMOTED_ELEMENT_TYPES, true );
	}

	public static function is_v3_supported( string $widget_type ): bool {
		return V3_Widget_Map_Registry::instance()->is_supported( $widget_type );
	}

	public static function build_widget_summary( string $widget_type, array $config ): array {
		return self::filter_nulls( [
			'type' => $widget_type,
			'version' => self::get_widget_version( $config ),
			'description' => self::get_description( $config, $widget_type ),
		] );
	}

	/**
	 * Builds a parents index for efficient allowed_parents lookup.
	 *
	 * @param array<string, array> $all_configs All widget configs keyed by type.
	 * @return array<string, string[]> child_type => parent_types[].
	 */
	public static function build_parents_index( array $all_configs ): array {
		$index = [];

		foreach ( $all_configs as $parent_type => $parent_config ) {
			foreach ( $parent_config['allowed_child_types'] ?? [] as $child_type ) {
				$index[ $child_type ][] = $parent_type;
			}
		}

		return $index;
	}

	/**
	 * Builds the JSON Schema for a widget's props.
	 * Returns null for widgets that can't be schematized at all (no atomic props and no V3 controls).
	 *
	 * @param string $widget_type   Widget type to build the schema for.
	 * @param array  $config        The widget's own config, from `get_config()`.
	 * @param array  $parents_index Precomputed child_type => parent_types[] index for nesting guidance.
	 */
	public static function build_widget_schema( string $widget_type, array $config, array $parents_index = [] ): ?array {
		$props_schema = $config['atomic_props_schema'] ?? null;

		if ( ! $props_schema ) {
			if ( ! self::has_v3_controls( $config['controls'] ?? null ) ) {
				return null;
			}

			return self::build_standardized_v3_widget_schema( $widget_type, $config );
		}

		return self::filter_nulls( [
			'type' => 'object',
			'properties' => self::build_configurable_properties_schema( $props_schema, $widget_type ),
			'editor_settings' => Editor_Settings::get_schema( $widget_type ),
			'description' => self::get_description( $config, $widget_type ),
			'llm_guidance' => Llm_Guidance_Builder::build( $config, $widget_type, $parents_index ),
		] );
	}

	/**
	 * @param array<string, Prop_Type> $props_schema
	 */
	private static function build_configurable_properties_schema( array $props_schema, string $widget_type ): array {
		$properties = [];

		foreach ( $props_schema as $key => $prop_type ) {
			$schema = $prop_type instanceof Prop_Type ? self::build_published_property_schema( $key, $prop_type, $widget_type ) : null;

			if ( null !== $schema ) {
				$properties[ $key ] = $schema;
			}
		}

		return $properties;
	}

	/**
	 * @return array<string, mixed>|null The property schema `get-widget-schemas` publishes, or null when the key is not configurable.
	 */
	public static function build_published_property_schema( string $key, Prop_Type $prop_type, string $widget_type ): ?array {
		if ( ! self::is_prop_key_configurable( $key, $prop_type ) ) {
			return null;
		}

		$schema = self::to_plain_llm_schema_from_json( $prop_type->to_json_schema() );
		$allowed_html_tags = Escaped_Html_Prop_Type::get_allowed_html_tags_for_prop( $widget_type, $key );

		return null === $allowed_html_tags ? $schema : self::describe_allowed_html_tags( $schema, $allowed_html_tags );
	}

	/**
	 * Keeps the machine-readable tag list while spelling out in the description that the string
	 * itself may carry that markup — a bare `allowed_html_tags` key is non-standard JSON Schema
	 * and reads as ambiguous next to `type: string`.
	 */
	private static function describe_allowed_html_tags( array $schema, array $allowed_html_tags ): array {
		$schema['allowed_html_tags'] = $allowed_html_tags;

		$tag_list = implode( ', ', array_map( fn( $tag ) => "<{$tag}>", $allowed_html_tags ) );
		$note = sprintf( self::ALLOWED_HTML_TAGS_NOTE, $tag_list );

		if ( ! isset( $schema['anyOf'] ) || ! is_array( $schema['anyOf'] ) ) {
			return self::append_description( $schema, $note );
		}

		// The markup rule belongs on the static string variant only — a dynamic-tag branch
		// resolves its own value and never carries inline HTML from the caller.
		$schema['anyOf'] = array_map(
			fn( $branch ) => is_array( $branch ) && 'string' === ( $branch['type'] ?? null )
				? self::append_description( $branch, $note )
				: $branch,
			$schema['anyOf']
		);

		return $schema;
	}

	private static function append_description( array $schema, string $note ): array {
		$schema['description'] = isset( $schema['description'] )
			? $schema['description'] . ' ' . $note
			: $note;

		return $schema;
	}

	public static function to_plain_llm_schema( Prop_Type $prop_type ): array {
		$schema = self::to_plain_llm_schema_from_json( $prop_type->to_json_schema() );

		return self::refine_from_prop_type( $schema, $prop_type, Utils::has_pro() );
	}

	private static function to_plain_llm_schema_from_json( array $schema ): array {
		$filtered = apply_filters( 'elementor/atomic-widgets/llm-json-schema', $schema );

		return Plain_Llm_Schema_Converter::convert( $filtered );
	}

	/**
	 * Walks a plain LLM schema alongside its PropType tree to:
	 *   - Enrich primitive enums from `meta('enum')` when the JSON schema lacks them.
	 *   - Strip fields marked `meta('pro') === true` and enum values listed in `meta('pro')`
	 *     when Pro is inactive.
	 */
	private static function refine_from_prop_type( array $schema, Prop_Type $prop_type, bool $is_pro_active ): array {
		if ( $prop_type instanceof Object_Prop_Type ) {
			return self::refine_object( $schema, $prop_type, $is_pro_active );
		}

		if ( $prop_type instanceof Array_Prop_Type ) {
			return self::refine_array( $schema, $prop_type, $is_pro_active );
		}

		return self::refine_primitive( $schema, $prop_type, $is_pro_active );
	}

	private static function refine_object( array $schema, Object_Prop_Type $prop_type, bool $is_pro_active ): array {
		if ( ! isset( $schema['properties'] ) || ! is_array( $schema['properties'] ) ) {
			return $schema;
		}

		$properties = $schema['properties'];

		foreach ( $prop_type->get_shape() as $key => $child_prop_type ) {
			if ( ! isset( $properties[ $key ] ) ) {
				continue;
			}

			if ( ! $is_pro_active && self::is_pro_only_field( $child_prop_type ) ) {
				unset( $properties[ $key ] );
				continue;
			}

			$properties[ $key ] = self::refine_from_prop_type( $properties[ $key ], $child_prop_type, $is_pro_active );
		}

		$schema['properties'] = $properties;

		return $schema;
	}

	private static function refine_array( array $schema, Array_Prop_Type $prop_type, bool $is_pro_active ): array {
		if ( isset( $schema['items'] ) && is_array( $schema['items'] ) ) {
			$schema['items'] = self::refine_from_prop_type( $schema['items'], $prop_type->get_item_type(), $is_pro_active );
		}

		return $schema;
	}

	private static function refine_primitive( array $schema, Prop_Type $prop_type, bool $is_pro_active ): array {
		$enum_values = $prop_type->get_meta_item( 'enum' );

		if ( is_array( $enum_values ) ) {
			$schema['enum'] = $is_pro_active
				? array_values( $enum_values )
				: self::filter_pro_enum_values( $enum_values, $prop_type );
		}

		return $schema;
	}

	private static function filter_pro_enum_values( array $enum_values, Prop_Type $prop_type ): array {
		if ( self::is_pro_only_field( $prop_type ) ) {
			return [];
		}

		$pro_values = $prop_type->get_meta_item( 'pro' );

		if ( ! is_array( $pro_values ) ) {
			return array_values( $enum_values );
		}

		return array_values( array_diff( $enum_values, $pro_values ) );
	}

	private static function is_pro_only_field( Prop_Type $prop_type ): bool {
		return true === $prop_type->get_meta_item( 'pro' );
	}

	private static function is_prop_key_configurable( string $key, Prop_Type $prop_type ): bool {
		if ( Prop_Sensitivity::is_sensitive( $prop_type ) ) {
			return false;
		}

		if ( ! in_array( $key, self::NON_CONFIGURABLE_PROP_KEYS, true ) ) {
			return true;
		}

		return (bool) $prop_type->get_meta_item( 'llm_configurable', false );
	}

	private static function get_description( array $config, ?string $widget_type = null ): ?string {
		$description = $config['meta']['description'] ?? null;

		if ( is_string( $description ) && '' !== $description ) {
			return $description;
		}

		if ( null !== $widget_type && self::is_v3_supported( $widget_type ) ) {
			$map = V3_Widget_Map_Registry::instance()->get_map( $widget_type );

			if ( null !== $map && '' !== $map->get_description() ) {
				return $map->get_description();
			}
		}

		return null;
	}

	private static function filter_nulls( array $data ): array {
		return array_filter( $data, fn( $value ) => null !== $value );
	}

	private static function should_initialize_v3_controls_stack( string $widget_type ): bool {
		return V3_Widget_Map_Registry::instance()->has_registered_map( $widget_type );
	}

	private static function build_standardized_v3_widget_schema( string $widget_type, array $config ): ?array {
		$contract = V3_Widget_Map_Registry::instance()->get_llm_contract( $widget_type );

		if ( null === $contract ) {
			return null;
		}

		$description = '' !== $contract['description']
			? $contract['description']
			: self::get_description( $config, $widget_type );

		return self::filter_nulls( [
			'type' => 'object',
			'widget_version' => self::VERSION_V3,
			'description' => $description,
			'properties' => $contract['properties'],
			'editor_settings' => Editor_Settings::get_schema( $widget_type ),
			'additionalProperties' => false,
			'default_style_target' => $contract['default_style_target'],
			'style_targets' => $contract['style_targets'],
		] );
	}
}