From f756b2c31fd30da02c550d58845ccf08a7302c2d Mon Sep 17 00:00:00 2001
From: Dennis Snell <dmsnell@git.wordpress.org>
Date: Fri, 24 May 2024 01:21:10 +0000
Subject: [PATCH] HTML API: Add `expects_closer()` method to HTML Processor

This patch adds a new method, `WP_HTML_Processor->expects_closer()` to indicate
if the currently-matched node expects to find a closing token. For example, a
`DIV` element expects a closing `</div>` tag, but an `<img>` expects none, because
it's a void element. Similarly, `#text` nodes and HTML comments only appear as
unitary nodes on the stack of open elements. Once proceeding further in the
document they are immediately removed without any closing tag.

This new method serves as a helper to indicate whether or not to expect the
closer, as this can be more complicated than it seems, and calling code
shouldn't have to build custom interpretations and implementations. Instead,
the HTML Processor ought to export its internal knowledge to make it easy for
consuming code and projects.

Developed in https://github.com/WordPress/wordpress-develop/pull/6600
Discussed in https://core.trac.wordpress.org/ticket/61257

Fixes #61257.
Props dmsnell, jonsurrell.


Built from https://develop.svn.wordpress.org/trunk@58192


git-svn-id: https://core.svn.wordpress.org/trunk@57655 1a063a9b-81f0-0310-95a4-ce76da25c4cd
---
 .../html-api/class-wp-html-processor.php      | 38 +++++++++++++++++++
 wp-includes/version.php                       |  2 +-
 2 files changed, 39 insertions(+), 1 deletion(-)

diff --git a/wp-includes/html-api/class-wp-html-processor.php b/wp-includes/html-api/class-wp-html-processor.php
index e3100abc69..c2349d8a28 100644
--- a/wp-includes/html-api/class-wp-html-processor.php
+++ b/wp-includes/html-api/class-wp-html-processor.php
@@ -508,6 +508,44 @@ public function matches_breadcrumbs( $breadcrumbs ) {
 		return false;
 	}
 
+	/**
+	 * Indicates if the currently-matched node expects a closing
+	 * token, or if it will self-close on the next step.
+	 *
+	 * Most HTML elements expect a closer, such as a P element or
+	 * a DIV element. Others, like an IMG element are void and don't
+	 * have a closing tag. Special elements, such as SCRIPT and STYLE,
+	 * are treated just like void tags. Text nodes and self-closing
+	 * foreign content will also act just like a void tag, immediately
+	 * closing as soon as the processor advances to the next token.
+	 *
+	 * @since 6.6.0
+	 *
+	 * @todo When adding support for foreign content, ensure that
+	 *       this returns false for self-closing elements in the
+	 *       SVG and MathML namespace.
+	 *
+	 * @return bool Whether to expect a closer for the currently-matched node,
+	 *              or `null` if not matched on any token.
+	 */
+	public function expects_closer() {
+		$token_name = $this->get_token_name();
+		if ( ! isset( $token_name ) ) {
+			return null;
+		}
+
+		return ! (
+			// Comments, text nodes, and other atomic tokens.
+			'#' === $token_name[0] ||
+			// Doctype declarations.
+			'html' === $token_name ||
+			// Void elements.
+			self::is_void( $token_name ) ||
+			// Special atomic elements.
+			in_array( $token_name, array( 'IFRAME', 'NOEMBED', 'NOFRAMES', 'SCRIPT', 'STYLE', 'TEXTAREA', 'TITLE', 'XMP' ), true )
+		);
+	}
+
 	/**
 	 * Steps through the HTML document and stop at the next tag, if any.
 	 *
diff --git a/wp-includes/version.php b/wp-includes/version.php
index 1cfc031679..da5ee3053b 100644
--- a/wp-includes/version.php
+++ b/wp-includes/version.php
@@ -16,7 +16,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '6.6-alpha-58191';
+$wp_version = '6.6-alpha-58192';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.