<?php
/**
 * A single visibility-controlled block found during a scan.
 *
 * @package BlockSieve
 */

namespace BlockSieve\Monitor;

/**
 * Immutable record of one block that carries a visibility model.
 *
 * Produced by BlockScanner (which knows only about content strings) and then
 * decorated with its source by ContentSources. Warnings and preview verdicts
 * are attached by UsageAnalyzer rather than computed here, keeping this a plain
 * value object.
 */
final class Occurrence {

	/**
	 * Source kind: an entry in the posts table (post, page, CPT).
	 */
	public const SOURCE_POST = 'post';

	/**
	 * Source kind: a synced pattern (wp_block).
	 */
	public const SOURCE_PATTERN = 'pattern';

	/**
	 * Source kind: a site-editor template.
	 */
	public const SOURCE_TEMPLATE = 'template';

	/**
	 * Source kind: a site-editor template part.
	 */
	public const SOURCE_TEMPLATE_PART = 'template_part';

	/**
	 * Source kind: a block widget in a sidebar.
	 */
	public const SOURCE_WIDGET = 'widget';

	/**
	 * Source kind: a navigation menu (`wp_navigation`).
	 */
	public const SOURCE_NAVIGATION = 'navigation';

	/**
	 * Block type name, e.g. "core/paragraph".
	 *
	 * @var string
	 * @readonly
	 */
	public string $block_name;

	/**
	 * Dot-separated index path within the document, e.g. "2.1.0".
	 *
	 * @var string
	 * @readonly
	 */
	public string $path;

	/**
	 * The stored visibility model.
	 *
	 * @var array
	 * @readonly
	 */
	public array $model;

	/**
	 * One of the SOURCE_* constants.
	 *
	 * @var string
	 * @readonly
	 */
	public string $source_kind;

	/**
	 * Identifier within the source kind (post id, template id, widget id).
	 *
	 * @var string
	 * @readonly
	 */
	public string $source_id;

	/**
	 * Human-readable location title.
	 *
	 * @var string
	 * @readonly
	 */
	public string $source_title;

	/**
	 * Translated label for the source kind, e.g. "Page".
	 *
	 * @var string
	 * @readonly
	 */
	public string $source_label;

	/**
	 * Admin URL that opens the location for editing ('' when unavailable).
	 *
	 * @var string
	 * @readonly
	 */
	public string $edit_url;

	/**
	 * Post id when the source is a post, otherwise 0.
	 *
	 * @var int
	 * @readonly
	 */
	public int $post_id;

	/**
	 * Post type when the source is a post, otherwise ''.
	 *
	 * @var string
	 * @readonly
	 */
	public string $post_type;

	/**
	 * Warning messages attached by the analyzer.
	 *
	 * @var string[]
	 * @readonly
	 */
	public array $warnings;

	/**
	 * Preview verdicts attached by the analyzer.
	 *
	 * @var array
	 * @readonly
	 */
	public array $preview;

	/**
	 * Constructor.
	 *
	 * @param string   $block_name   Block type name, e.g. "core/paragraph".
	 * @param string   $path         Dot-separated index path within the document, e.g. "2.1.0".
	 * @param array    $model        The stored visibility model.
	 * @param string   $source_kind  One of the SOURCE_* constants.
	 * @param string   $source_id    Identifier within the source kind (post id, template id, widget id).
	 * @param string   $source_title Human-readable location title.
	 * @param string   $source_label Translated label for the source kind, e.g. "Page".
	 * @param string   $edit_url     Admin URL that opens the location for editing ('' when unavailable).
	 * @param int      $post_id      Post id when the source is a post, otherwise 0.
	 * @param string   $post_type    Post type when the source is a post, otherwise ''.
	 * @param string[] $warnings     Warning messages attached by the analyzer.
	 * @param array    $preview      Preview verdicts attached by the analyzer.
	 */
	public function __construct(
		string $block_name,
		string $path,
		array $model,
		string $source_kind = self::SOURCE_POST,
		string $source_id = '',
		string $source_title = '',
		string $source_label = '',
		string $edit_url = '',
		int $post_id = 0,
		string $post_type = '',
		array $warnings = array(),
		array $preview = array()
	) {
		$this->block_name   = $block_name;
		$this->path         = $path;
		$this->model        = $model;
		$this->source_kind  = $source_kind;
		$this->source_id    = $source_id;
		$this->source_title = $source_title;
		$this->source_label = $source_label;
		$this->edit_url     = $edit_url;
		$this->post_id      = $post_id;
		$this->post_type    = $post_type;
		$this->warnings     = $warnings;
		$this->preview      = $preview;
	}

	/**
	 * Returns a copy carrying the given source information.
	 *
	 * @param string $kind     Source kind (a SOURCE_* constant).
	 * @param string $id       Identifier within the source kind.
	 * @param string $title    Human-readable location title.
	 * @param string $label    Translated label for the source kind.
	 * @param string $edit_url Admin edit URL.
	 * @param int    $post_id  Post id, when applicable.
	 * @param string $type     Post type, when applicable.
	 * @return self
	 */
	public function with_source(
		string $kind,
		string $id,
		string $title,
		string $label,
		string $edit_url = '',
		int $post_id = 0,
		string $type = ''
	): self {
		return new self(
			$this->block_name,
			$this->path,
			$this->model,
			$kind,
			$id,
			$title,
			$label,
			$edit_url,
			$post_id,
			$type,
			$this->warnings,
			$this->preview
		);
	}

	/**
	 * Returns a copy carrying analyzer output.
	 *
	 * @param string[] $warnings Warning messages.
	 * @param array    $preview  Preview verdicts.
	 * @return self
	 */
	public function with_analysis( array $warnings, array $preview ): self {
		return new self(
			$this->block_name,
			$this->path,
			$this->model,
			$this->source_kind,
			$this->source_id,
			$this->source_title,
			$this->source_label,
			$this->edit_url,
			$this->post_id,
			$this->post_type,
			$warnings,
			$preview
		);
	}

	/**
	 * Reports whether the visibility model is switched on.
	 *
	 * @return bool
	 */
	public function is_enabled(): bool {
		return ! empty( $this->model['enabled'] );
	}

	/**
	 * Returns the combinator used to join the conditions ('all' or 'any').
	 *
	 * @return string
	 */
	public function relation(): string {
		return isset( $this->model['relation'] ) && 'any' === $this->model['relation'] ? 'any' : 'all';
	}

	/**
	 * Returns the stored conditions, filtered to well-formed entries.
	 *
	 * @return array<int, array>
	 */
	public function conditions(): array {
		$conditions = $this->model['conditions'] ?? array();

		if ( ! is_array( $conditions ) ) {
			return array();
		}

		return array_values( array_filter( $conditions, 'is_array' ) );
	}

	/**
	 * Returns the condition type ids used by this block.
	 *
	 * @return string[]
	 */
	public function condition_types(): array {
		$types = array();

		foreach ( $this->conditions() as $condition ) {
			if ( isset( $condition['type'] ) && is_string( $condition['type'] ) ) {
				$types[] = $condition['type'];
			}
		}

		return $types;
	}

	/**
	 * Reports whether the analyzer attached any warnings.
	 *
	 * @return bool
	 */
	public function has_warnings(): bool {
		return array() !== $this->warnings;
	}

	/**
	 * Returns a stable identifier for this occurrence.
	 *
	 * @return string
	 */
	public function key(): string {
		return $this->source_kind . ':' . $this->source_id . ':' . $this->path;
	}
}