<?php
/**
 * Abstract Wizard Step
 *
 * Base class for all setup wizard steps.  Each step is responsible for its
 * own render output and optional data handling on form submission.
 *
 * @package AmbassadorHub\Admin\Wizard
 */

namespace AmbassadorHub\Admin\Wizard;

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

/**
 * Base class for setup wizard steps.
 */
abstract class AbstractWizardStep {

	/**
	 * Unique string identifier for this step (used in CSS classes, etc.).
	 *
	 * @return string
	 */
	abstract public function get_id(): string;

	/**
	 * Human-readable title displayed in the wizard header and progress dots.
	 *
	 * @return string
	 */
	abstract public function get_title(): string;

	/**
	 * Render the step's body HTML (form fields, descriptions, status widgets).
	 *
	 * Called inside a <form> that already contains the action/nonce fields.
	 * The step should output field markup only — no <form> wrapper needed.
	 *
	 * @return void
	 */
	abstract public function render(): void;

	/**
	 * Handle form submission for this step.
	 *
	 * Called when the user clicks "Next" (ambh_wizard_action=next) on this step.
	 * Returns null to auto-advance to the next step, or a redirect URL string
	 * to stay on the current step with extra query parameters (e.g. show
	 * a confirmation message).
	 *
	 * @param array<string,mixed> $post_data Sanitised $_POST data.
	 * @return string|null Redirect URL, or null to auto-advance.
	 */
	public function handle( array $post_data ): ?string { // phpcs:ignore Generic.CodeAnalysis.UnusedFunctionParameter.Found -- default no-op implementation; subclasses use $post_data to process form submissions.
		return null; // Default: no-op, auto-advance.
	}

	/**
	 * Whether this step can be individually skipped by the user.
	 *
	 * @return bool
	 */
	public function is_skippable(): bool {
		return true;
	}

	/**
	 * Whether this step is already fulfilled (e.g. pages already created,
	 * PSP already configured).  Used to determine the button label and
	 * whether to show a completion checkmark.
	 *
	 * @return bool
	 */
	public function is_done(): bool {
		return false;
	}

	/**
	 * Whether this step should contribute to the setup-incomplete admin notice.
	 *
	 * Steps that perform real configuration (pages, PSP, first fundraiser) return
	 * true so that admins are alerted when the step remains undone after the
	 * wizard has been closed or skipped.  Informational or diagnostic steps
	 * (Welcome, email test) return false.
	 *
	 * @return bool
	 */
	public function is_alertable(): bool {
		return false;
	}
}
