<?php
/**
 * Immutable value object representing a content phrase.
 *
 * @package Postlinkly
 * @since   1.0.0
 */

declare(strict_types=1);

namespace Postlinkly\Text;

/**
 * Immutable value object for a phrase extracted from post content.
 *
 * The suggestion engine slices content into sentences, then into phrases
 * (sub-sentence units). Each phrase carries its own text, the surrounding
 * sentence, and a lookup index of unique tokenised words.
 *
 * Properties are public for compactness; do not modify them after
 * construction.
 *
 * @since 1.0.0
 */
final class PhraseModel {

	/**
	 * Index of the phrase within its source content (zero-based).
	 *
	 * @var int
	 */
	public int $index;

	/**
	 * The phrase text as it appears in the source.
	 *
	 * @var string
	 */
	public string $text;

	/**
	 * The surrounding sentence text.
	 *
	 * @var string
	 */
	public string $sentence;

	/**
	 * Unique tokenised words present in the phrase.
	 *
	 * Keyed by stemmed word, value is the count of occurrences. Used for
	 * fast set-overlap checks during candidate matching.
	 *
	 * @var array<string, int>
	 */
	public array $unique_words;

	/**
	 * @since 1.0.0
	 *
	 * @param string             $text         The phrase text.
	 * @param string             $sentence     Optional. Surrounding sentence.
	 *                                         Default empty (treats phrase as its own sentence).
	 * @param int                $index        Optional. Position within source. Default 0.
	 * @param array<string, int> $unique_words Optional. Stemmed word counts. Default [].
	 */
	public function __construct(
		string $text,
		string $sentence = '',
		int $index = 0,
		array $unique_words = array()
	) {
		$this->text         = $text;
		$this->sentence     = '' !== $sentence ? $sentence : $text;
		$this->index        = $index;
		$this->unique_words = $unique_words;
	}

	/**
	 * Returns whether this phrase contains the given stemmed word.
	 *
	 * @since 1.0.0
	 *
	 * @param string $stemmed_word Already-stemmed word to look up.
	 *
	 * @return bool True when present.
	 */
	public function contains_word( string $stemmed_word ): bool {
		return isset( $this->unique_words[ $stemmed_word ] );
	}
}