<?php
/**
 * The one place the plugin says what its advice is and is not.
 *
 * AI-O Optimiser proposes changes on several screens: schema entity types,
 * metadata, content opportunities, NAP corrections. Every one of those is a
 * suggestion drawn from evidence the plugin can see, and none of them can
 * promise an outcome, because search engines and AI systems decide
 * independently what they index, rank or cite.
 *
 * That was previously said well in some places, partially in others and not at
 * all in a few. Keeping the wording here means it is written once, translated
 * once, and reads the same wherever it appears.
 *
 * @package AI_O_Vis_Op
 */

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

final class AI_O_Optimiser_Advisory_Disclaimers {

	/**
	 * Screens that carry the standing footer line.
	 *
	 * Mirrors the primary navigation's own page map: if a page is part of the
	 * AI-O workspace it gets the line, and if it is not, nothing is emitted into
	 * somebody else's admin screen.
	 */
	const PAGES = array(
		'ai-o-optimiser-dashboard',
		'ai-o-optimiser-optimise',
		'ai-o-optimiser-metadata-workflow',
		'ai-o-optimiser-content-opportunities',
		'ai-o-optimiser-schema-review',
		'ai-o-optimiser-local-discovery',
		'ai-o-optimiser-system-check',
		'ai-o-optimiser-guidance',
		'ai-o-optimiser-environment-check',
		'ai-o-optimiser-logs',
		'ai-o-optimiser-deep-review-prompt',
		'ai-o-optimiser-settings',
		'ai-o-optimiser-notifications',
	);

	/** Register the footer line and its styles. */
	public static function boot() {
		add_action( 'admin_enqueue_scripts', array( __CLASS__, 'enqueue_assets' ) );
		add_action( 'admin_footer', array( __CLASS__, 'render_footer' ) );
	}

	/**
	 * The canonical wording, keyed by where it is used.
	 *
	 * Each string states two things: the suggestion is yours to accept or
	 * reject, and applying it guarantees nothing. Callers pick the key that
	 * matches the decision in front of the administrator rather than writing
	 * their own variant.
	 *
	 * @param string $key Advisory key.
	 * @return string Translated sentence, or '' for an unknown key.
	 */
	public static function text( $key ) {
		$texts = array(
			// Schema entity types: the judgement genuinely belongs to the administrator.
			'schema_type'     => __( 'Suggested entity types are suggestions. AI-O Optimiser checks every one against the bundled Schema.org registry, but only you know what a page or post actually is — review each suggestion and apply it only where it genuinely describes that content. Structured data does not guarantee rich results, rankings or inclusion in AI answers.', 'ai-o-optimiser' ),

			// The audit table, where rows carry a recommended reconciliation.
			'schema_audit'    => __( 'Audit findings and recommended fixes are advisory. Review the recommendation against the page it belongs to before applying it, and expect no guaranteed change in rankings, rich results or AI citation as a result.', 'ai-o-optimiser' ),

			// Generated titles, descriptions and keywords.
			'metadata'        => __( 'Generated metadata is a draft for your review, not finished copy. Check that each title and description is accurate for the page before applying it. Nothing here guarantees rankings, click-through or traffic.', 'ai-o-optimiser' ),

			// Search-evidence-led content suggestions.
			'opportunities'   => __( 'Opportunities are drawn from search evidence and are directional only. Whether a topic is worth writing, and how, remains an editorial decision. No opportunity guarantees ranking, traffic or AI citation.', 'ai-o-optimiser' ),

			// NAP and external listings.
			'nap'             => __( 'Listing and consistency findings are evidence to review, not instructions. Confirm each correction against the real business facts before acting on it. Consistent NAP data supports entity clarity; it does not guarantee local rankings, listings or AI inclusion.', 'ai-o-optimiser' ),

			// Site model / operating model guidance.
			'site_model'      => __( 'These are suggestions based on the site’s own published content. You decide whether they describe the site correctly, and nothing is saved until you confirm it.', 'ai-o-optimiser' ),

			// The standing line on every AI-O screen.
			'results'         => __( 'AI-O Optimiser reports the evidence it observes and suggests changes for you to review. Search engines and AI systems decide independently what they crawl, index, rank and cite, so no result here is guaranteed.', 'ai-o-optimiser' ),
		);

		return isset( $texts[ $key ] ) ? $texts[ $key ] : '';
	}

	/**
	 * Inline advisory note, for placing beside the thing being suggested.
	 *
	 * Returns markup rather than echoing so callers inside larger echo/printf
	 * expressions can compose with it. Already escaped: print with
	 * wp_kses_post() at the call site so the intent is visible in review.
	 *
	 * @param string $key   Advisory key.
	 * @param string $extra Optional extra class on the wrapper.
	 * @return string Markup, or '' for an unknown key.
	 */
	public static function markup( $key, $extra = '' ) {
		$text = self::text( $key );
		if ( '' === $text ) {
			return '';
		}

		$class = 'ai-o-optimiser-advisory';
		if ( '' !== $extra ) {
			$class .= ' ' . sanitize_html_class( $extra );
		}

		return '<p class="' . esc_attr( $class ) . '"><span class="dashicons dashicons-info-outline" aria-hidden="true"></span><span>'
			. esc_html( $text ) . '</span></p>';
	}

	/**
	 * Echo an inline advisory note.
	 *
	 * @param string $key   Advisory key.
	 * @param string $extra Optional extra class on the wrapper.
	 */
	public static function note( $key, $extra = '' ) {
		echo wp_kses_post( self::markup( $key, $extra ) );
	}

	/** The standing line, once per AI-O screen. */
	public static function render_footer() {
		if ( ! self::is_workspace_screen() ) {
			return;
		}
		?>
		<div class="ai-o-optimiser-advisory-footer">
			<p><strong><?php esc_html_e( 'About AI-O Optimiser’s findings', 'ai-o-optimiser' ); ?></strong> <?php echo esc_html( self::text( 'results' ) ); ?></p>
		</div>
		<?php
	}

	/** Styles for both the inline note and the footer line. */
	public static function enqueue_assets() {
		if ( ! self::is_workspace_screen() ) {
			return;
		}
		wp_enqueue_style(
			'ai-o-optimiser-advisory',
			AI_O_Optimiser_PLUGIN_URL . 'assets/advisory.css',
			array(),
			AI_O_Optimiser_VERSION
		);
	}

	/** True on an AI-O workspace screen. */
	private static function is_workspace_screen() {
		// phpcs:ignore WordPress.Security.NonceVerification.Recommended -- Read-only screen routing. Nothing is written here, so there is no form submission to carry a nonce.
		$page = isset( $_GET['page'] ) ? sanitize_key( wp_unslash( $_GET['page'] ) ) : '';

		return in_array( $page, self::PAGES, true );
	}
}