<?php
/**
 * Schema Module.
 *
 * HowTo + FAQ structured data for posts, edited in a panel on the post and
 * emitted as JSON-LD — no third-party plugin, no per-article code. On first
 * run it seeds a neutral example so the editor panel shows populated and
 * demonstrates valid output immediately.
 *
 * @package Platform\Helm\Modules\Schema
 */

declare( strict_types = 1 );

namespace Platform\Helm\Modules\Schema;

use Platform\Helm\Contracts\ModuleInterface;
use Platform\Helm\Core\Assets;

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

final class SchemaModule implements ModuleInterface {

	private const SEED_OPTION = 'platform_helm_schema_seeded';

	private SchemaMetaBox $meta_box;
	private SchemaInjector $injector;

	public function __construct( Assets $assets ) {
		$this->meta_box = new SchemaMetaBox( $assets );
		$this->injector = new SchemaInjector();
	}

	public function id(): string {
		return 'schema';
	}

	public function name(): string {
		return __( 'Structured Data (Schema)', 'platform-helm' );
	}

	public function description(): string {
		return __( 'Add HowTo and FAQ schema to posts from an editor panel — emitted as clean JSON-LD, no third-party plugin or code snippets. Helps articles win rich results and AI answer citations.', 'platform-helm' );
	}

	public function default_enabled(): bool {
		return true;
	}

	public function boot(): void {
		$this->meta_box->register_hooks();
		$this->injector->register_hooks();
		if ( is_admin() && ! get_option( self::SEED_OPTION ) ) {
			$this->seed();
		}
	}

	/**
	 * One-time seed of a neutral example HowTo + FAQ, so the editor panel is
	 * shown populated on first run. Applied to the most recent published post
	 * that has no schema yet — never overwrites anything already set.
	 */
	private function seed(): void {
		update_option( self::SEED_OPTION, 1, false ); // Set first so a failure never loops.

		$posts = get_posts( [
			'post_type'      => 'post',
			'post_status'    => 'publish',
			'posts_per_page' => 1,
			'orderby'        => 'date',
			'order'          => 'DESC',
			'fields'         => 'ids',
			'no_found_rows'  => true,
		] );
		if ( empty( $posts ) ) {
			return;
		}
		$post_id = (int) $posts[0];
		if ( get_post_meta( $post_id, SchemaInjector::META_HOWTO, true ) || get_post_meta( $post_id, SchemaInjector::META_FAQ, true ) ) {
			return; // Respect anything already set.
		}

		// A neutral, universally-applicable example so the panel shows populated.
		update_post_meta( $post_id, SchemaInjector::META_HOWTO, [
			'name'        => 'How to Add Structured Data to a Post',
			'description' => 'A simple example showing how HowTo structured data appears. Edit or clear these fields in the Structured Data panel on this post.',
			'total_time'  => 'PT10M',
			'cost'        => '',
			'steps'       => [
				[ 'name' => 'Open the post editor', 'text' => 'Edit any published post and scroll to the Structured Data panel added by this module.' ],
				[ 'name' => 'Fill in the HowTo or FAQ fields', 'text' => 'Add a name, a short description, and one step or question per row. Leave a section empty to omit it.' ],
				[ 'name' => 'Update the post', 'text' => 'Save the post. The module emits valid JSON-LD into the page head automatically — no code or third-party plugin needed.' ],
			],
		] );

		update_post_meta( $post_id, SchemaInjector::META_FAQ, [
			[ 'q' => 'What is structured data?', 'a' => 'Structured data is a standardised format (JSON-LD) that describes your content to search engines and AI answer engines, helping you win rich results and citations.' ],
			[ 'q' => 'Will this conflict with my SEO plugin?', 'a' => 'This module only adds HowTo and FAQ schema from the fields you fill in. If your SEO plugin already outputs the same schema type for a post, set it in only one place to avoid duplicates.' ],
			[ 'q' => 'How do I remove this example?', 'a' => 'Open this post, clear the fields in the Structured Data panel, and update the post. The example is only seeded once.' ],
		] );
	}
}
