<?php
/**
 * First-run onboarding status.
 *
 * @package PRECO
 */

namespace PRECO\Includes\Admin;

defined( 'ABSPATH' ) || exit;

/**
 * Tracks whether the site-wide first-run onboarding tour has been completed
 * or skipped. There is no per-user tracking: whichever admin finishes or
 * skips the tour first locks it out for everyone else.
 */
class Onboarding {

	/**
	 * Option name.
	 */
	const OPTION_STATUS = 'preco_onboarding_status';

	/**
	 * Statuses that permanently dismiss onboarding.
	 *
	 * @var array<int,string>
	 */
	const DISMISS_STATUSES = array( 'completed', 'skipped' );

	/**
	 * Seed the onboarding option on a fresh activation only. Never
	 * overwrites an existing value, so reactivating the plugin (or updating
	 * it on an already-active install) never resets or retroactively shows
	 * onboarding.
	 *
	 * @return void
	 */
	public static function maybe_bootstrap() {
		if ( false === get_option( self::OPTION_STATUS ) ) {
			update_option( self::OPTION_STATUS, 'pending', false );
		}
	}

	/**
	 * Current onboarding status. Empty string means the option was never
	 * bootstrapped (existing install predating this feature) — treated the
	 * same as dismissed.
	 *
	 * @return string
	 */
	public static function get_status() {
		$status = get_option( self::OPTION_STATUS, '' );
		return is_string( $status ) ? $status : '';
	}

	/**
	 * Whether the onboarding tour should currently be shown.
	 *
	 * @return bool
	 */
	public static function should_show() {
		return 'pending' === self::get_status();
	}

	/**
	 * Mark onboarding as completed or skipped.
	 *
	 * @param string $status 'completed' or 'skipped'.
	 * @return bool True if the status was valid and saved.
	 */
	public static function mark( $status ) {
		if ( ! in_array( $status, self::DISMISS_STATUSES, true ) ) {
			return false;
		}

		update_option( self::OPTION_STATUS, $status, false );
		return true;
	}
}
