<?php
/**
 * Post entity field registration for WP Data Optimizer (v2.9.1).
 *
 * Registers three post entity groups designed to absorb the bulk of
 * wp_postmeta rows that previously bypassed any flat-table strategy.
 * All groups use TMDO_Entity_Registry → flat tables instead of wp_postmeta EAV.
 *
 * Groups → flat tables (post_type targets):
 *   wp_core         → wp_wpdo_post_wp_core         (cross post_type)
 *   attachment      → wp_wpdo_post_attachment      (attachment)
 *   nav_menu_item   → wp_wpdo_post_nav_menu_item   (nav_menu_item)
 *
 * Pattern mirrors TMDO_Member_Fields::register(). Called from
 * TMDO_Core::run() before the wpdo_register_entity_fields action fires;
 * Schema_Manager materializes the three flat tables in init:1
 * via process_pending_migrations() (idempotent via schema_hash compare).
 *
 * Keys not registered here (HivePress dynamic attrs, WPCS legacy keys,
 * etc.) pass through to wp_postmeta unchanged — same fall-back behavior
 * as user entity bridge.
 *
 * The HivePress groups (hp_listing_core / hp_request_core / hp_vendor_core)
 * are registered by the HivePress AddOn (TMDO_HivePress_Entity_Groups).
 *
 * 🔒 v2.9.x frozen contract: this class must NEVER call register_group()
 * with entity_type='user'. User entity registration is owned exclusively
 * by TMDO_Member_Fields.
 *
 * @package WP_Data_Optimizer
 * @since   2.9.1
 */

declare(strict_types=1);

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

/**
 * Registers three post entity groups. WooCommerce product meta is not one of
 * them (1.2.0): WooCommerce reads it directly and writes stock by SQL, so
 * native meta stays its only copy. Existing wp_wpdo_post_wc_product tables
 * are left alone (see `wp tmdo bridge-restore-native post --group=wc_product --retire`).
 */
final class TMDO_Post_Fields {

	/**
	 * Post type of each core group that is not scoped to post types in the
	 * registry (wp_core spans every post type and is absent on purpose).
	 */
	private const GROUP_POST_TYPES = array(
		'attachment'    => 'attachment',
		'nav_menu_item' => 'nav_menu_item',
	);

	/**
	 * Primary post type of a post group: the registry scope for scoped groups
	 * (e.g. the HivePress AddOn's), the core mapping otherwise.
	 *
	 * @param string $group Entity group name.
	 * @return string|null Null for cross-post-type groups such as wp_core.
	 */
	public static function post_type_for_group( string $group ): ?string {
		$scoped = class_exists( 'TMDO_Entity_Registry' ) ? TMDO_Entity_Registry::get_group_post_types( 'post', $group ) : array();
		return $scoped[0] ?? ( self::GROUP_POST_TYPES[ $group ] ?? null );
	}

	/**
	 * Post groups dedicated to a post type (wp_core excluded).
	 *
	 * @param string $post_type Post type slug.
	 * @return string[]
	 */
	public static function groups_for_post_type( string $post_type ): array {
		$groups = array_keys( self::GROUP_POST_TYPES, $post_type, true );
		if ( class_exists( 'TMDO_Entity_Registry' ) ) {
			foreach ( TMDO_Entity_Registry::get_groups_for_type( 'post' ) as $group ) {
				if ( in_array( $post_type, TMDO_Entity_Registry::get_group_post_types( 'post', $group ), true ) ) {
					$groups[] = $group;
				}
			}
		}
		return array_values( array_unique( $groups ) );
	}

	/**
	 * Hook into WPDO entity field registration.
	 *
	 * @return void
	 */
	public static function register(): void {
		add_action( 'wpdo_register_entity_fields', array( __CLASS__, 'register_entity_fields' ) );
	}

	/**
	 * Register all post entity groups.
	 *
	 * @return void
	 */
	public static function register_entity_fields(): void {
		if ( ! class_exists( 'TMDO_Entity_Registry' ) ) {
			return;
		}

		self::register_wp_core_group();
		self::register_attachment_group();
		self::register_nav_menu_item_group();
	}

	// ── Group definitions ────────────────────────────────────────────────────

	/**
	 * WP core post meta keys present across post_types.
	 *
	 * @return void
	 */
	private static function register_wp_core_group(): void {
		TMDO_Entity_Registry::register_group(
			'post',
			'wp_core',
			array(
				array(
					'key'        => '_thumbnail_id',
					'type'       => 'integer',
					'searchable' => true,
					'label'      => 'Featured image attachment ID',
				),
				array(
					'key'   => '_wp_page_template',
					'type'  => 'text',
					'label' => 'Page template slug',
				),
				array(
					'key'        => '_edit_last',
					'type'       => 'integer',
					'searchable' => true,
					'label'      => 'Last editor user ID',
				),
			)
		);
	}

	/**
	 * Attachment-specific meta keys (post_type=attachment).
	 *
	 * @return void
	 */
	private static function register_attachment_group(): void {
		TMDO_Entity_Registry::register_group(
			'post',
			'attachment',
			array(
				array(
					'key'        => '_wp_attached_file',
					'type'       => 'text',
					'searchable' => true,
					'label'      => 'Relative path of the attached file',
				),
				array(
					'key'   => '_wp_attachment_metadata',
					'type'  => 'json',
					'label' => 'Image dimensions / EXIF / sizes array',
				),
				array(
					'key'   => '_wp_attachment_image_alt',
					'type'  => 'textarea',
					'label' => 'Alt text for accessibility',
				),
				array(
					'key'   => '_wp_attachment_caption',
					'type'  => 'textarea',
					'label' => 'Attachment caption',
				),
			)
		);
	}

	/**
	 * Nav menu item meta keys (post_type=nav_menu_item).
	 *
	 * @return void
	 */
	private static function register_nav_menu_item_group(): void {
		TMDO_Entity_Registry::register_group(
			'post',
			'nav_menu_item',
			array(
				array(
					'key'     => '_menu_item_type',
					'type'    => 'enum',
					'options' => array( 'post_type', 'taxonomy', 'custom', 'post_type_archive' ),
					'label'   => 'Menu item linking type',
				),
				array(
					'key'   => '_menu_item_menu_item_parent',
					'type'  => 'integer',
					'label' => 'Parent menu item ID',
				),
				array(
					'key'        => '_menu_item_object_id',
					'type'       => 'integer',
					'searchable' => true,
					'label'      => 'Linked object ID',
				),
				array(
					'key'   => '_menu_item_object',
					'type'  => 'text',
					'label' => 'Linked object slug (post_type/taxonomy)',
				),
				array(
					'key'   => '_menu_item_target',
					'type'  => 'text',
					'label' => 'Link target attribute',
				),
				array(
					'key'   => '_menu_item_classes',
					'type'  => 'json',
					'label' => 'CSS classes array',
				),
				array(
					'key'   => '_menu_item_xfn',
					'type'  => 'text',
					'label' => 'XFN relationship',
				),
				array(
					'key'   => '_menu_item_url',
					'type'  => 'textarea',
					'label' => 'Custom URL (for type=custom)',
				),
			)
		);
	}
}