<?php
/**
 * File Path: includes/shortcodes/class-mbs-shortcode-universe.php
 *
 * [mbs_universe slug="x"] Shortcode -- SHC-2
 *
 * Renders a single universe description, optional PRO banner, and book grid
 * inline, without calling get_header() / get_footer(). Feature-for-feature
 * equivalent of taxonomy-mbs-universe.php.
 *
 * Sprint BACK-SC-001: Universe is entirely PRO-gated (client spec). FREE users
 * receive an HTML comment. PRO users must also have Universe enabled via
 * Settings -> Advanced (mbs_setting_advanced_universe_enabled). Rendering
 * delegated to MBS_Archive_Reader::render_ordered() with merge_missing: true.
 *
 * Extends MBS_Shortcode_Taxonomy_Base (D-010, Session 117) which handles
 * the shared scaffold: license gate, atts normalisation, slug + term
 * lookup, and the outer div/header HTML.
 *
 * Attributes:
 *   slug     (string, required) -- term slug for mbs_universe
 *   per_page (int, default 20)  -- reserved; ignored by render_ordered().
 *
 * @package MyBookShowroom
 * @since   1.0.0
 */

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

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

	protected static function get_taxonomy(): string {
		return MBS_TAX_UNIVERSE;
	}

	protected static function get_shortcode_tag(): string {
		return 'mbs_universe';
	}

	/**
	 * PRO gate + universe-enabled guard.
	 *
	 * Universe is entirely PRO-gated (client spec). FREE users receive an HTML
	 * comment. PRO users must have Universe enabled via Settings -> Advanced
	 * (mbs_setting_advanced_universe_enabled) before content renders.
	 *
	 * {@inheritdoc}
	 *
	 * @param array $atts Raw shortcode attributes.
	 * @return string HTML or HTML comment.
	 */
	public static function render( array $atts = array() ): string {
		if ( ! mbs_is_pro() && ! mbs_is_pub() ) {
			return '<!-- MBS: universe requires PRO license -->';
		}
		if ( ! (bool) get_option( 'mbs_setting_advanced_universe_enabled', false ) ) {
			return '<!-- MBS: universe feature is disabled in Settings → Advanced -->';
		}
		return parent::render( $atts );
	}

	/**
	 * F-BNR-U: Render the universe banner image after the archive header.
	 *
	 * PRO is guaranteed by the render() override above.
	 *
	 * @param WP_Term $term The resolved mbs_universe term.
	 * @return void
	 */
	protected static function render_after_header( WP_Term $term ): void {
		$banner_id = (int) get_term_meta( (int) $term->term_id, 'mbs_universe_banner_id', true );
		if ( ! $banner_id ) {
			return;
		}
		?>
		<div class="mbs-universe-banner">
			<?php echo wp_get_attachment_image( // R5-exempt: universe banner image, not book cover
				$banner_id,
				'full',
				false,
				array(
					'class' => 'mbs-universe-banner-img',
					'alt'   => $term->name,
				)
			); ?>
		</div>
		<?php
	}

	/**
	 * Render the book grid for the universe term.
	 *
	 * Sprint BACK-SC-001: Delegates to MBS_Archive_Reader::render_ordered().
	 * merge_missing: true handles stale junction-table rows (D-16).
	 * CE-3 removed: PRO is guaranteed by the render() override above.
	 *
	 * @param WP_Term $term     The resolved mbs_universe term.
	 * @param int     $per_page Reserved; ignored by render_ordered().
	 * @return void
	 */
	protected static function render_body( WP_Term $term, int $per_page ): void {
		$term_id = (int) $term->term_id;

		$display_mode = MBS_Archive_Reader::resolve_display_mode(
			$term_id,
			'mbs_universe_archive_display_mode',
			'mbs_setting_universe_archive_display_mode',
			'mbs_setting_show_universe_reading_order'
		);

		$layout_slug = MBS_Layout_Registry::resolve_slug_for_term( $term_id, 'grid' );
		$layout_obj  = MBS_Layout_Registry::get_layout( $layout_slug );

		$html = MBS_Archive_Reader::render_ordered(
			MBS_Universe_Reading_Order_DAO::class,
			$term_id,
			$layout_obj,
			$layout_slug,
			array(
				'display_mode'  => $display_mode,
				'merge_missing' => true,
				'context'       => 'universe',
			)
		);

		if ( '' === $html ) {
			echo '<p>' . esc_html__( 'No books found in this universe.', 'my-book-showroom' ) . '</p>';
			return;
		}

		// phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped
		echo $html;
	}
}
