<?php

namespace NeurogenesisTheme\QuickSetup;

defined( 'ABSPATH' ) || exit;

/**
 * Base class for a Quick Setup checklist step.
 */
abstract class Step {

	/**
	 * Unique step identifier.
	 */
	abstract public function id(): string;

	/**
	 * Human-readable label shown in the dashboard UI.
	 */
	abstract public function label(): string;

	/**
	 * Admin URL the step links to when incomplete.
	 */
	abstract public function url(): string;

	/**
	 * Whether this step has been completed.
	 */
	abstract public function completed(): bool;

	/**
	 * Optional admin action key for in-dashboard handlers (e.g. AJAX install).
	 */
	public function action(): string {
		return '';
	}

	/**
	 * Whether the step should render as a clickable link in the UI.
	 */
	public function is_clickable(): bool {
		if ( $this->completed() ) {
			return false;
		}

		return '' !== $this->url() || '' !== $this->action();
	}

	/**
	 * @return array{id:string,label:string,completed:bool,url:string,action:string,clickable:bool}
	 */
	public function to_array(): array {
		return array(
			'id'        => $this->id(),
			'label'     => $this->label(),
			'completed' => $this->completed(),
			'url'       => $this->url(),
			'action'    => $this->action(),
			'clickable' => $this->is_clickable(),
		);
	}

	/**
	 * @param string $filter Filter hook; return non-null bool to override completion.
	 */
	protected function filtered_completed( string $filter ): ?bool {
		$filtered = apply_filters( $filter, null );

		return null !== $filtered ? (bool) $filtered : null;
	}
}
