<?php
/**
 * Favorites button helper (free tier).
 *
 * Free favorites are anonymous: stored in the visitor's localStorage,
 * never logged on the server (per ADR-29). The button this class emits
 * is a placeholder that frontend.js wires up via the existing
 * `.trx-ad-card__action--favorite` event delegation.
 *
 * Pro tier promotes favorites to per-user post meta with REST CRUD.
 * That extension hooks `trx_ad_favorites_button` to override this render.
 *
 * @package ThemeREX\AutoDealer
 * @version 1.0.0
 */

declare(strict_types=1);

namespace ThemeREX\AutoDealer\Frontend;

/**
 * Stateless favorite-button renderer + page hydrator.
 */
final class FavoritesHandler {

	public const SHORTCODE = 'trx_ad_favorites';

	/**
	 * Hook registration. Adds the `[trx_ad_favorites]` shortcode so the
	 * Activator-generated /favorites page renders the grid instead of
	 * leaking shortcode source as plain text.
	 */
	public function register(): void {
		add_shortcode( self::SHORTCODE, array( $this, 'renderShortcode' ) );
	}

	/**
	 * Shortcode entry — wraps the static renderer.
	 *
	 * @param array<string,mixed>|string $atts    Shortcode attributes (unused).
	 * @param string|null                $content Inner content (unused).
	 * @return string
	 */
	public function renderShortcode( $atts = array(), ?string $content = null ): string {
		unset( $atts, $content );
		// Escaped at the callback's return boundary -- WP outputs shortcode
		// return values directly (wp.org 2026-08 review round 4).
		return wp_kses( self::renderPage(), \ThemeREX\AutoDealer\allowedHtml() );
	}

	/**
	 * Render a heart toggle button. Pro can override the markup via filter.
	 *
	 * @param int $post_id Vehicle ID.
	 * @return string
	 */
	public static function renderButton( int $post_id ): string {
		$markup = sprintf(
			'<button type="button"
				class="trx-ad-btn trx-ad-btn--icon trx-ad-card__action--favorite"
				data-vehicle-id="%1$d"
				aria-label="%2$s">
				<svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true">
					<path d="M20.84 4.61a5.5 5.5 0 00-7.78 0L12 5.67l-1.06-1.06a5.5 5.5 0 00-7.78 7.78l1.06 1.06L12 21.23l7.78-7.78 1.06-1.06a5.5 5.5 0 000-7.78z"/>
				</svg>
				<span>%3$s</span>
			</button>',
			(int) $post_id,
			esc_attr__( 'Add to favorites', 'trx-auto-dealer' ),
			esc_html__( 'Save', 'trx-auto-dealer' )
		);

		/**
		 * Filter the rendered favorites button. Pro replaces this with a
		 * REST-powered toggle that persists to user meta.
		 *
		 * @param string $markup  Default button HTML.
		 * @param int    $post_id Vehicle ID.
		 */
		return (string) apply_filters( 'trx_ad_favorites_button', $markup, $post_id );
	}

	/**
	 * Render the public favorites page shell. JS hydrates it from
	 * localStorage by fetching /vehicles/{id} for each saved ID.
	 *
	 * @return string
	 */
	public static function renderPage(): string {
		ob_start();
		?>
		<section class="trx-ad-favorites-page" data-trx-ad-favorites-page>
			<h2 class="trx-ad-favorites-page__heading">
				<?php esc_html_e( 'Your Favorites', 'trx-auto-dealer' ); ?>
			</h2>
			<p class="trx-ad-favorites-page__empty" data-trx-ad-favorites-empty hidden>
				<?php esc_html_e( "You haven't saved any vehicles yet.", 'trx-auto-dealer' ); ?>
			</p>
			<div class="trx-ad-favorites-page__grid" data-trx-ad-favorites-grid></div>
		</section>
		<?php
		return (string) ob_get_clean();
	}
}
