HTML API: Report real and virtual nodes in the HTML Processor.

HTML is a kind of short-hand for a DOM structure. This means that there are
many cases in HTML where an element's opening tag or closing tag is missing (or
both). This is because many of the parsing rules imply creating elements in the
DOM which may not exist in the text of the HTML.

The HTML Processor, being the higher-level counterpart to the Tag Processor, is
already aware of these nodes, but since it's inception has not paused on them
when scanning through a document. Instead, these are visible when pausing on a
child of such an element, but otherwise not seen.

In this patch the HTML Processor starts exposing those implicitly-created nodes,
including opening tags, and closing tags, that aren't foudn in the text content
of the HTML input document.

Previously, the sequence of matched tokens when scanning with 
`WP_HTML_Processor::next_token()` would depend on how the HTML document was written,
but with this patch, all semantically equal HTML documents will parse and scan in
the same exact manner, presenting an idealized or "perfect" view of the document
the same way as would occur when traversing a DOM in a browser.

Developed in WordPress#6348
Discussed in https://core.trac.wordpress.org/ticket/61348

Props audrasjb, dmsnell, gziolo, jonsurrell.
Fixes #61348.


git-svn-id: https://develop.svn.wordpress.org/trunk@58304 602fd350-edb4-49c9-b593-d223f7449a82

src/wp-includes/html-api/class-wp-html-open-elements.php

@@ -51,6 +51,56 @@ class WP_HTML_Open_Elements {
 	 */
 	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
+	 */
+	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
+	 */
+	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 ) {
+		$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 ) {
+		$this->push_handler = $handler;
+	}
+
 	/**
 	 * Reports if a specific node is in the stack of open elements.
 	 *
@@ -429,6 +479,10 @@ public function after_element_push( $item ) {
 				$this->has_p_in_button_scope = true;
 				break;
 		}
+
+		if ( null !== $this->push_handler ) {
+			( $this->push_handler )( $item );
+		}
 	}
 
 	/**
@@ -458,5 +512,9 @@ public function after_element_pop( $item ) {
 				$this->has_p_in_button_scope = $this->has_element_in_button_scope( 'P' );
 				break;
 		}
+
+		if ( null !== $this->pop_handler ) {
+			( $this->pop_handler )( $item );
+		}
 	}
 }