<?php
/**
 * @package Hafenstudios\Core
 */

namespace Hafenstudios\Core\Hans;

defined( 'ABSPATH' ) || exit;

/**
 * Wiederverwendbare Wizard-Huelle fuer die Onboarding-Lotsen der Plugins.
 *
 * Liefert nur die Schale (Fortschritts-Punkte, Schritt-Container, Ueberspringen-
 * Link, optionales Hans-Motiv). Die konkreten Schritte fuellt das Plugin. Der
 * Wizard ist immer ueberspringbar (UX-KONZEPT Abschnitt 6 und Ziel 5).
 */
final class Wizard {

	private string $id;

	/**
	 * @var array<int, array{title:string,body:string}>
	 */
	private array $steps = array();

	private string $skip_url = '';

	private int $current = 0;

	private int $motif = 30;

	/**
	 * @param string $id Eindeutige Wizard-ID.
	 */
	public function __construct( string $id ) {
		$this->id = sanitize_key( $id );
	}

	/**
	 * Fuegt einen Schritt hinzu.
	 *
	 * @param string $title Titel.
	 * @param string $body  HTML-Inhalt (bereits escaped).
	 * @return Wizard
	 */
	public function add_step( string $title, string $body ): Wizard {
		$this->steps[] = array(
			'title' => $title,
			'body'  => $body,
		);
		return $this;
	}

	/**
	 * Setzt die Ueberspringen-Ziel-URL.
	 *
	 * @param string $url URL.
	 * @return Wizard
	 */
	public function skip_url( string $url ): Wizard {
		$this->skip_url = $url;
		return $this;
	}

	/**
	 * Setzt den aktuellen Schritt (0-basiert).
	 *
	 * @param int $index Index.
	 * @return Wizard
	 */
	public function current( int $index ): Wizard {
		$this->current = max( 0, $index );
		return $this;
	}

	/**
	 * Setzt das Hans-Motiv fuer den Kopfbereich.
	 *
	 * @param int $motif Motiv-Nummer.
	 * @return Wizard
	 */
	public function motif( int $motif ): Wizard {
		$this->motif = $motif;
		return $this;
	}

	/**
	 * Rendert die Wizard-Huelle mit dem aktuellen Schritt.
	 *
	 * @param Hans $hans Hans-Instanz fuer das Motivbild.
	 * @return string HTML.
	 */
	public function render( Hans $hans ): string {
		if ( empty( $this->steps ) ) {
			return '';
		}
		$total = count( $this->steps );
		$index = min( $this->current, $total - 1 );
		$step  = $this->steps[ $index ];
		$image = $hans->image_url( $this->motif );

		ob_start();
		?>
		<div class="hs-wizard" id="hs-wizard-<?php echo esc_attr( $this->id ); ?>">
			<div class="hs-wizard__head">
				<?php if ( '' !== $image ) : ?>
					<img class="hs-wizard__img" src="<?php echo esc_url( $image ); ?>" alt="" width="96" height="96" />
				<?php endif; ?>
				<ol class="hs-wizard__dots" aria-label="<?php esc_attr_e( 'Fortschritt', 'hafenstudios-core' ); ?>">
					<?php for ( $i = 0; $i < $total; $i++ ) : ?>
						<li class="hs-wizard__dot<?php echo $i <= $index ? ' is-active' : ''; ?>" aria-current="<?php echo $i === $index ? 'step' : 'false'; ?>"></li>
					<?php endfor; ?>
				</ol>
			</div>
			<div class="hs-wizard__step">
				<h2 class="hs-wizard__title"><?php echo esc_html( $step['title'] ); ?></h2>
				<div class="hs-wizard__body"><?php echo $step['body']; // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped -- Aufrufer liefert bereits escaped. ?></div>
			</div>
			<?php if ( '' !== $this->skip_url ) : ?>
				<p class="hs-wizard__skip">
					<a href="<?php echo esc_url( $this->skip_url ); ?>"><?php esc_html_e( 'Einrichtung ueberspringen', 'hafenstudios-core' ); ?></a>
				</p>
			<?php endif; ?>
		</div>
		<?php
		return (string) ob_get_clean();
	}
}
