HTML API: Add support for list elements.

From https://github.com/html5lib/html5lib-tests/blob/a9f44960a9fedf265093d22b2aa3c7ca123727b9/tree-construction/webkit01.dat#L468-L482

Co-authored-by: Jon Surrell <sirreal@users.noreply.github.com>

Add docblocks to tests, expand comments in class docblock.

Author: dmsnell

phpcs.xml.dist

@@ -250,6 +250,15 @@
 		<exclude-pattern>/wp-tests-config-sample\.php</exclude-pattern>
 	</rule>
 
+	<!-- Exclude forbidding goto in the HTML Processor, which mimics algorithms that are written
+	     this way in the HTML specification, and these particular algorithms are complex and
+	     highly imperative. Avoiding the goto introduces a number of risks that could make it
+	     more difficult to maintain the relationship to the standard, lead to subtle differences
+	     in the parsing, and distance the code from its standard. -->
+	<rule ref="Generic.PHP.DiscourageGoto.Found">
+		<exclude-pattern>/wp-includes/html-api/class-wp-html-processor\.php</exclude-pattern>
+	</rule>
+
 	<!-- Exclude sample config from modernization to prevent breaking CI workflows based on WP-CLI scaffold.
 		 See: https://core.trac.wordpress.org/ticket/48082#comment:16 -->
 	<rule ref="Modernize.FunctionCalls.Dirname.FileConstant">

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

@@ -129,7 +129,7 @@ public function has_element_in_specific_scope( $tag_name, $termination_list ) {
 			}
 
 			if ( in_array( $node->node_name, $termination_list, true ) ) {
-				return true;
+				return false;
 			}
 		}
 
@@ -166,18 +166,22 @@ public function has_element_in_scope( $tag_name ) {
 	 * Returns whether a particular element is in list item scope.
 	 *
 	 * @since 6.4.0
+	 * @since 6.5.0 Implemented: no longer throws on every invocation.
 	 *
 	 * @see https://html.spec.whatwg.org/#has-an-element-in-list-item-scope
 	 *
-	 * @throws WP_HTML_Unsupported_Exception Always until this function is implemented.
-	 *
 	 * @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( $tag_name ) {
-		throw new WP_HTML_Unsupported_Exception( 'Cannot process elements depending on list item scope.' );
-
-		return false; // The linter requires this unreachable code until the function is implemented and can return.
+		return $this->has_element_in_specific_scope(
+			$tag_name,
+			array(
+				// There are more elements that belong here which aren't currently supported.
+				'OL',
+				'UL',
+			)
+		);
 	}
 
 	/**
@@ -375,10 +379,22 @@ public function walk_down() {
 	 * see WP_HTML_Open_Elements::walk_down().
 	 *
 	 * @since 6.4.0
+	 * @since 6.5.0 Accepts $above_this_node to start traversal above a given node, if it exists.
+	 *
+	 * @param ?WP_HTML_Token $above_this_node Start traversing above this node, if provided and if the node exists.
 	 */
-	public function walk_up() {
+	public function walk_up( $above_this_node = null ) {
+		$has_found_node = null === $above_this_node;
+
 		for ( $i = count( $this->stack ) - 1; $i >= 0; $i-- ) {
-			yield $this->stack[ $i ];
+			$node = $this->stack[ $i ];
+
+			if ( ! $has_found_node ) {
+				$has_found_node = $node === $above_this_node;
+				continue;
+			}
+
+			yield $node;
 		}
 	}
 

src/wp-includes/html-api/class-wp-html-processor.php

@@ -105,7 +105,7 @@
  *  - Formatting elements: B, BIG, CODE, EM, FONT, I, SMALL, STRIKE, STRONG, TT, U.
  *  - Heading elements: H1, H2, H3, H4, H5, H6, HGROUP.
  *  - Links: A.
- *  - Lists: DL.
+ *  - Lists: DD, DL, DT, LI, OL, LI.
  *  - Media elements: AUDIO, CANVAS, FIGCAPTION, FIGURE, IMG, MAP, PICTURE, VIDEO.
  *  - Paragraph: P.
  *  - Phrasing elements: ABBR, BDI, BDO, CITE, DATA, DEL, DFN, INS, MARK, OUTPUT, Q, SAMP, SUB, SUP, TIME, VAR.
@@ -648,10 +648,12 @@ private function step_in_body() {
 			case '+MAIN':
 			case '+MENU':
 			case '+NAV':
+			case '+OL':
 			case '+P':
 			case '+SEARCH':
 			case '+SECTION':
 			case '+SUMMARY':
+			case '+UL':
 				if ( $this->state->stack_of_open_elements->has_p_in_button_scope() ) {
 					$this->close_a_p_element();
 				}
@@ -685,9 +687,11 @@ private function step_in_body() {
 			case '-MAIN':
 			case '-MENU':
 			case '-NAV':
+			case '-OL':
 			case '-SEARCH':
 			case '-SECTION':
 			case '-SUMMARY':
+			case '-UL':
 				if ( ! $this->state->stack_of_open_elements->has_element_in_scope( $tag_name ) ) {
 					// @todo Report parse error.
 					// Ignore the token.
@@ -755,6 +759,109 @@ private function step_in_body() {
 				$this->state->stack_of_open_elements->pop_until( '(internal: H1 through H6 - do not use)' );
 				return true;
 
+			/*
+			 * > A start tag whose tag name is "li"
+			 * > A start tag whose tag name is one of: "dd", "dt"
+			 */
+			case '+DD':
+			case '+DT':
+			case '+LI':
+				$this->state->frameset_ok = false;
+				$node                     = $this->state->stack_of_open_elements->current_node();
+				$is_li                    = 'LI' === $tag_name;
+
+				in_body_list_loop:
+				/*
+				 * The logic for LI and DT/DD is the same except for one point: LI elements _only_
+				 * close other LI elements, but a DT or DD element closes _any_ open DT or DD element.
+				 */
+				if ( $is_li ? 'LI' === $node->node_name : ( 'DD' === $node->node_name || 'DT' === $node->node_name ) ) {
+					$node_name = $is_li ? 'LI' : $node->node_name;
+					$this->generate_implied_end_tags( $node_name );
+					if ( $node_name !== $this->state->stack_of_open_elements->current_node()->node_name ) {
+						// @todo Indicate a parse error once it's possible. This error does not impact the logic here.
+					}
+
+					$this->state->stack_of_open_elements->pop_until( $node_name );
+					goto in_body_list_done;
+				}
+
+				if (
+					'ADDRESS' !== $node->node_name &&
+					'DIV' !== $node->node_name &&
+					'P' !== $node->node_name &&
+					$this->is_special( $node->node_name )
+				) {
+					/*
+					 * > If node is in the special category, but is not an address, div,
+					 * > or p element, then jump to the step labeled done below.
+					 */
+					goto in_body_list_done;
+				} else {
+					/*
+					 * > Otherwise, set node to the previous entry in the stack of open elements
+					 * > and return to the step labeled loop.
+					 */
+					foreach ( $this->state->stack_of_open_elements->walk_up( $node ) as $item ) {
+						$node = $item;
+						break;
+					}
+					goto in_body_list_loop;
+				}
+
+				in_body_list_done:
+				if ( $this->state->stack_of_open_elements->has_p_in_button_scope() ) {
+					$this->close_a_p_element();
+				}
+
+				$this->insert_html_element( $this->state->current_token );
+				return true;
+
+			/*
+			 * > An end tag whose tag name is "li"
+			 * > An end tag whose tag name is one of: "dd", "dt"
+			 */
+			case '-DD':
+			case '-DT':
+			case '-LI':
+				if (
+					/*
+					 * An end tag whose tag name is "li":
+					 * If the stack of open elements does not have an li element in list item scope,
+					 * then this is a parse error; ignore the token.
+					 */
+					(
+						'LI' === $tag_name &&
+						! $this->state->stack_of_open_elements->has_element_in_list_item_scope( 'LI' )
+					) ||
+					/*
+					 * An end tag whose tag name is one of: "dd", "dt":
+					 * If the stack of open elements does not have an element in scope that is an
+					 * HTML element with the same tag name as that of the token, then this is a
+					 * parse error; ignore the token.
+					 */
+					(
+						'LI' !== $tag_name &&
+						! $this->state->stack_of_open_elements->has_element_in_scope( $tag_name )
+					)
+				) {
+					/*
+					 * This is a parse error, ignore the token.
+					 *
+					 * @todo Indicate a parse error once it's possible.
+					 */
+					return $this->step();
+				}
+
+				$this->generate_implied_end_tags( $tag_name );
+
+				if ( $tag_name !== $this->state->stack_of_open_elements->current_node()->node_name ) {
+					// @todo Indicate a parse error once it's possible. This error does not impact the logic here.
+				}
+
+				$this->state->stack_of_open_elements->pop_until( $tag_name );
+				return true;
+
 			/*
 			 * > An end tag whose tag name is "p"
 			 */
@@ -1223,6 +1330,9 @@ private function close_a_p_element() {
 	 */
 	private function generate_implied_end_tags( $except_for_this_element = null ) {
 		$elements_with_implied_end_tags = array(
+			'DD',
+			'DT',
+			'LI',
 			'P',
 		);
 
@@ -1248,6 +1358,9 @@ private function generate_implied_end_tags( $except_for_this_element = null ) {
 	 */
 	private function generate_implied_end_tags_thoroughly() {
 		$elements_with_implied_end_tags = array(
+			'DD',
+			'DT',
+			'LI',
 			'P',
 		);
 

tests/phpunit/tests/html-api/wpHtmlProcessor.php

@@ -168,8 +168,6 @@ public function data_unsupported_special_in_body_tags() {
 			'CAPTION'   => array( 'CAPTION' ),
 			'COL'       => array( 'COL' ),
 			'COLGROUP'  => array( 'COLGROUP' ),
-			'DD'        => array( 'DD' ),
-			'DT'        => array( 'DT' ),
 			'EMBED'     => array( 'EMBED' ),
 			'FORM'      => array( 'FORM' ),
 			'FRAME'     => array( 'FRAME' ),
@@ -180,7 +178,6 @@ public function data_unsupported_special_in_body_tags() {
 			'IFRAME'    => array( 'IFRAME' ),
 			'INPUT'     => array( 'INPUT' ),
 			'KEYGEN'    => array( 'KEYGEN' ),
-			'LI'        => array( 'LI' ),
 			'LINK'      => array( 'LINK' ),
 			'LISTING'   => array( 'LISTING' ),
 			'MARQUEE'   => array( 'MARQUEE' ),
@@ -191,7 +188,6 @@ public function data_unsupported_special_in_body_tags() {
 			'NOFRAMES'  => array( 'NOFRAMES' ),
 			'NOSCRIPT'  => array( 'NOSCRIPT' ),
 			'OBJECT'    => array( 'OBJECT' ),
-			'OL'        => array( 'OL' ),
 			'OPTGROUP'  => array( 'OPTGROUP' ),
 			'OPTION'    => array( 'OPTION' ),
 			'PARAM'     => array( 'PARAM' ),
@@ -218,7 +214,6 @@ public function data_unsupported_special_in_body_tags() {
 			'TITLE'     => array( 'TITLE' ),
 			'TR'        => array( 'TR' ),
 			'TRACK'     => array( 'TRACK' ),
-			'UL'        => array( 'UL' ),
 			'WBR'       => array( 'WBR' ),
 			'XMP'       => array( 'XMP' ),
 		);