<?php

/**

 * HTML API: WP_HTML_Open_Elements class

 *

 * @package WordPress

 * @subpackage HTML-API

 * @since 6.4.0

 */

/**

 * Core class used by the HTML processor during HTML parsing

 * for managing the stack of open elements.

 *

 * This class is designed for internal use by the HTML processor.

 *

 * > Initially, the stack of open elements is empty. The stack grows

 * > downwards; the topmost node on the stack is the first one added

 * > to the stack, and the bottommost node of the stack is the most

 * > recently added node in the stack (notwithstanding when the stack

 * > is manipulated in a random access fashion as part of the handling

 * > for misnested tags).

 *

 * @since 6.4.0

 *

 * @access private

 *

 * @see https://html.spec.whatwg.org/#stack-of-open-elements

 * @see WP_HTML_Processor

 */

class WP_HTML_Open_Elements {

	/**

	 * Holds the stack of open element references.

	 *

	 * @since 6.4.0

	 *

	 * @var WP_HTML_Token[]

	 */

	public $stack = array();

	/**

	 * Whether a P element is in button scope currently.

	 *

	 * This class optimizes scope lookup by pre-calculating

	 * this value when elements are added and removed to the

	 * stack of open elements which might change its value.

	 * This avoids frequent iteration over the stack.

	 *

	 * @since 6.4.0

	 *

	 * @var bool

	 */

	private $has_p_in_button_scope = false;

	/**

	 * A function that will be called when an item is popped off the stack of open elements.

	 *

	 * The function will be called with the popped item as its argument.

	 *

	 * @since 6.6.0

	 *

	 * @var Closure|null

	 */

	private $pop_handler = null;

	/**

	 * A function that will be called when an item is pushed onto the stack of open elements.

	 *

	 * The function will be called with the pushed item as its argument.

	 *

	 * @since 6.6.0

	 *

	 * @var Closure|null

	 */

	private $push_handler = null;

	/**

	 * Sets a pop handler that will be called when an item is popped off the stack of

	 * open elements.

	 *

	 * The function will be called with the pushed item as its argument.

	 *

	 * @since 6.6.0

	 *

	 * @param Closure $handler The handler function.

	 */

	public function set_pop_handler( Closure $handler ): void {

		$this->pop_handler = $handler;

	}

	/**

	 * Sets a push handler that will be called when an item is pushed onto the stack of

	 * open elements.

	 *

	 * The function will be called with the pushed item as its argument.

	 *

	 * @since 6.6.0

	 *

	 * @param Closure $handler The handler function.

	 */

	public function set_push_handler( Closure $handler ): void {

		$this->push_handler = $handler;

	}

	/**

	 * Returns the name of the node at the nth position on the stack

	 * of open elements, or `null` if no such position exists.

	 *

	 * Note that this uses a 1-based index, which represents the

	 * "nth item" on the stack, counting from the top, where the

	 * top-most element is the 1st, the second is the 2nd, etc...

	 *

	 * @since 6.7.0

	 *

	 * @param int $nth Retrieve the nth item on the stack, with 1 being

	 *                 the top element, 2 being the second, etc...

	 * @return WP_HTML_Token|null Name of the node on the stack at the given location,

	 *                            or `null` if the location isn't on the stack.

	 */

	public function at( int $nth ): ?WP_HTML_Token {

		foreach ( $this->walk_down() as $item ) {

			if ( 0 === --$nth ) {

				return $item;

			}

		}

		return null;

	}

	/**

	 * Reports if a node of a given name is in the stack of open elements.

	 *

	 * @since 6.7.0

	 *

	 * @param string $node_name Name of node for which to check.

	 * @return bool Whether a node of the given name is in the stack of open elements.

	 */

	public function contains( string $node_name ): bool {

		foreach ( $this->walk_up() as $item ) {

			if ( $node_name === $item->node_name ) {

				return true;

			}

		}

		return false;

	}

	/**

	 * Reports if a specific node is in the stack of open elements.

	 *

	 * @since 6.4.0

	 *

	 * @param WP_HTML_Token $token Look for this node in the stack.

	 * @return bool Whether the referenced node is in the stack of open elements.

	 */

	public function contains_node( WP_HTML_Token $token ): bool {

		foreach ( $this->walk_up() as $item ) {

			if ( $token === $item ) {

				return true;

			}

		}

		return false;

	}

	/**

	 * Returns how many nodes are currently in the stack of open elements.

	 *

	 * @since 6.4.0

	 *

	 * @return int How many node are in the stack of open elements.

	 */

	public function count(): int {

		return count( $this->stack );

	}

	/**

	 * Returns the node at the end of the stack of open elements,

	 * if one exists. If the stack is empty, returns null.

	 *

	 * @since 6.4.0

	 *

	 * @return WP_HTML_Token|null Last node in the stack of open elements, if one exists, otherwise null.

	 */

	public function current_node(): ?WP_HTML_Token {

		$current_node = end( $this->stack );

		return $current_node ? $current_node : null;

	}

	/**

	 * Indicates if the current node is of a given type or name.

	 *

	 * It's possible to pass either a node type or a node name to this function.

	 * In the case there is no current element it will always return `false`.

	 *

	 * Example:

	 *

	 *     // Is the current node a text node?

	 *     $stack->current_node_is( '#text' );

	 *

	 *     // Is the current node a DIV element?

	 *     $stack->current_node_is( 'DIV' );

	 *

	 *     // Is the current node any element/tag?

	 *     $stack->current_node_is( '#tag' );

	 *

	 * @see WP_HTML_Tag_Processor::get_token_type

	 * @see WP_HTML_Tag_Processor::get_token_name

	 *

	 * @since 6.7.0

	 *

	 * @access private

	 *

	 * @param string $identity Check if the current node has this name or type (depending on what is provided).

	 * @return bool Whether there is a current element that matches the given identity, whether a token name or type.

	 */

	public function current_node_is( string $identity ): bool {

		$current_node = end( $this->stack );

		if ( false === $current_node ) {

			return false;

		}

		$current_node_name = $current_node->node_name;

		return (

			$current_node_name === $identity ||

			( '#doctype' === $identity && 'html' === $current_node_name ) ||

			( '#tag' === $identity && ctype_upper( $current_node_name ) )

		);

	}

	/**

	 * Returns whether an element is in a specific scope.

	 *

	 * @since 6.4.0

	 *

	 * @see https://html.spec.whatwg.org/#has-an-element-in-the-specific-scope

	 *

	 * @param string   $tag_name         Name of tag check.

	 * @param string[] $termination_list List of elements that terminate the search.

	 * @return bool Whether the element was found in a specific scope.

	 */

	public function has_element_in_specific_scope( string $tag_name, $termination_list ): bool {

		foreach ( $this->walk_up() as $node ) {

			$namespaced_name = 'html' === $node->namespace

				? $node->node_name

				: "{$node->namespace} {$node->node_name}";

			if ( $namespaced_name === $tag_name ) {

				return true;

			}

			if (

				'(internal: H1 through H6 - do not use)' === $tag_name &&

				in_array( $namespaced_name, array( 'H1', 'H2', 'H3', 'H4', 'H5', 'H6' ), true )

			) {

				return true;

			}

			if ( in_array( $namespaced_name, $termination_list, true ) ) {

				return false;

			}

		}

		return false;

	}

	/**

	 * Returns whether a particular element is in scope.

	 *

	 * > The stack of open elements is said to have a particular element in

	 * > scope when it has that element in the specific scope consisting of

	 * > the following element types:

	 * >

	 * >   - applet

	 * >   - caption

	 * >   - html

	 * >   - table

	 * >   - td

	 * >   - th

	 * >   - marquee

	 * >   - object

	 * >   - template

	 * >   - MathML mi

	 * >   - MathML mo

	 * >   - MathML mn

	 * >   - MathML ms

	 * >   - MathML mtext

	 * >   - MathML annotation-xml

	 * >   - SVG foreignObject

	 * >   - SVG desc

	 * >   - SVG title

	 *

	 * @since 6.4.0

	 * @since 6.7.0 Full support.

	 *

	 * @see https://html.spec.whatwg.org/#has-an-element-in-scope

	 *

	 * @param string $tag_name Name of tag to check.

	 * @return bool Whether given element is in scope.

	 */

	public function has_element_in_scope( string $tag_name ): bool {

		return $this->has_element_in_specific_scope(

			$tag_name,

			array(

				'APPLET',

				'CAPTION',

				'HTML',

				'TABLE',

				'TD',

				'TH',

				'MARQUEE',

				'OBJECT',

				'TEMPLATE',

				'math MI',

				'math MO',

				'math MN',

				'math MS',

				'math MTEXT',

				'math ANNOTATION-XML',

				'svg FOREIGNOBJECT',

				'svg DESC',

				'svg TITLE',

			)

		);

	}

	/**

	 * Returns whether a particular element is in list item scope.

	 *

	 * > The stack of open elements is said to have a particular element

	 * > in list item scope when it has that element in the specific scope

	 * > consisting of the following element types:

	 * >

	 * >   - All the element types listed above for the has an element in scope algorithm.

	 * >   - ol in the HTML namespace

	 * >   - ul in the HTML namespace

	 *

	 * @since 6.4.0

	 * @since 6.5.0 Implemented: no longer throws on every invocation.

	 * @since 6.7.0 Supports all required HTML elements.

	 *

	 * @see https://html.spec.whatwg.org/#has-an-element-in-list-item-scope

	 *

	 * @param string $tag_name Name of tag to check.

	 * @return bool Whether given element is in scope.

	 */

	public function has_element_in_list_item_scope( string $tag_name ): bool {

		return $this->has_element_in_specific_scope(

			$tag_name,

			array(

				'APPLET',

				'BUTTON',

				'CAPTION',

				'HTML',

				'TABLE',

				'TD',

				'TH',

				'MARQUEE',

				'OBJECT',

				'OL',

				'TEMPLATE',

				'UL',

				'math MI',

				'math MO',

				'math MN',

				'math MS',

				'math MTEXT',

				'math ANNOTATION-XML',

				'svg FOREIGNOBJECT',

				'svg DESC',

				'svg TITLE',

			)

		);

	}

	/**

	 * Returns whether a particular element is in button scope.

	 *

	 * > The stack of open elements is said to have a particular element

	 * > in button scope when it has that element in the specific scope

	 * > consisting of the following element types:

	 * >

	 * >   - All the element types listed above for the has an element in scope algorithm.

	 * >   - button in the HTML namespace

	 *

	 * @since 6.4.0

	 * @since 6.7.0 Supports all required HTML elements.

	 *

	 * @see https://html.spec.whatwg.org/#has-an-element-in-button-scope

	 *

	 * @param string $tag_name Name of tag to check.

	 * @return bool Whether given element is in scope.

	 */

	public function has_element_in_button_scope( string $tag_name ): bool {

		return $this->has_element_in_specific_scope(

			$tag_name,

			array(

				'APPLET',

				'BUTTON',

				'CAPTION',

				'HTML',

				'TABLE',

				'TD',

				'TH',

				'MARQUEE',

				'OBJECT',

				'TEMPLATE',

				'math MI',

				'math MO',

				'math MN',

				'math MS',

				'math MTEXT',

				'math ANNOTATION-XML',

				'svg FOREIGNOBJECT',

				'svg DESC',

				'svg TITLE',

			)

		);

	}

	/**

	 * Returns whether a particular element is in table scope.

	 *

	 * > The stack of open elements is said to have a particular element

	 * > in table scope when it has that element in the specific scope

	 * > consisting of the following element types:

	 * >

	 * >   - html in the HTML namespace

	 * >   - table in the HTML namespace

	 * >   - template in the HTML namespace

	 *

	 * @since 6.4.0

	 * @since 6.7.0 Full implementation.

	 *

	 * @see https://html.spec.whatwg.org/#has-an-element-in-table-scope

	 *

	 * @param string $tag_name Name of tag to check.

	 * @return bool Whether given element is in scope.

	 */

	public function has_element_in_table_scope( string $tag_name ): bool {

		return $this->has_element_in_specific_scope(

			$tag_name,

			array(

				'HTML',

				'TABLE',

				'TEMPLATE',