<?php
/**
 * File Path: includes/metaboxes/class-mbs-metabox-book-discovery.php
 *
 * Book Discovery Section Facade — My Book Showroom
 *
 * Facade handler for the "Discovery" sub-section of the Book Details tab.
 * Contains zero domain logic. Its sole responsibility is composing and
 * sequencing three single-responsibility sub-handlers in a fixed visual order,
 * with group headings separating each cluster of fields.
 *
 * Visual groups rendered in order:
 *   "Part of"           — MBS_Metabox_Series_Collections (Series, Position, Reading Order, Collections)
 *                         MBS_Metabox_Universe           (Universes)
 *   "Themes & Keywords" — MBS_Metabox_Categorization     (Genre, Tags, Themes)
 *
 * Each sub-handler owns its own nonce field and verification. The Facade
 * outputs no nonce of its own.
 *
 * Conforms to: WordPress Plugin Handbook, OOP Single Responsibility Principle,
 * GoF Facade pattern. Extracted during Book Details tab restructure (Sprint 178).
 *
 * @package    My_Book_Showroom
 * @subpackage Includes/Metaboxes
 * @since      1.0.0
 */

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

class MBS_Metabox_Book_Discovery extends MBS_Metabox_Base { // phpcs:ignore WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedClassFound -- mbs_/MBS_ prefix is correct; scanner not configured with plugin prefix

	/** @var MBS_Metabox_Series_Collections */
	private MBS_Metabox_Series_Collections $series_collections;

	/** @var MBS_Metabox_Universe */
	private MBS_Metabox_Universe $universe;

	/** @var MBS_Metabox_Categorization */
	private MBS_Metabox_Categorization $categorization;

	/**
	 * Instantiate sub-handlers.
	 *
	 * Sub-handlers are plain handler classes — not singletons — and carry no
	 * hook-registration side effects in their constructors, so direct
	 * instantiation here is safe and conventional for this codebase.
	 */
	public function __construct() {
		$this->series_collections = new MBS_Metabox_Series_Collections();
		$this->universe           = new MBS_Metabox_Universe();
		$this->categorization     = new MBS_Metabox_Categorization();
	}

	// -------------------------------------------------------------------------
	// Editor shell interface
	// -------------------------------------------------------------------------

	/**
	 * Render the Discovery section by delegating to sub-handlers in sequence.
	 *
	 * Outputs three group headings as visual separators. All field HTML,
	 * nonce fields, and inline scripts are produced by the sub-handlers.
	 *
	 * @param string  $section_key Section key passed by the editor shell (unused).
	 * @param WP_Post $post        Current post object.
	 * @return void
	 */
	public function render_section( string $section_key, WP_Post $post ): void {

		// ── "Themes & Keywords" ────────────────────────────────────────────────────────────────────────
		echo '<h3 class="mbs-discovery-group-heading">' . esc_html__( 'Themes & Keywords', 'my-book-showroom' ) . '</h3>';
		$this->categorization->render_section( $section_key, $post );

		// ── "Part of" ────────────────────────────────────────────────────────────────────
		echo '<h3 class="mbs-discovery-group-heading">' . esc_html__( 'Part of', 'my-book-showroom' ) . '</h3>';
		$this->series_collections->render_section( $section_key, $post );
		$this->universe->render_section( $section_key, $post );

	}

	/**
	 * Save the Discovery section by delegating to sub-handlers in sequence.
	 *
	 * Each sub-handler independently verifies its own nonce before saving.
	 * The Facade imposes no additional nonce check.
	 *
	 * @param string  $section_key Section key passed by the editor shell (unused).
	 * @param int     $post_id     Post ID.
	 * @param WP_Post $post        Post object.
	 * @return void
	 */
	public function save_section( string $section_key, int $post_id, WP_Post $post ): void {
		$this->series_collections->save_section( $section_key, $post_id, $post );
		$this->universe->save_section( $section_key, $post_id, $post );
		$this->categorization->save_section( $section_key, $post_id, $post );
	}

}
