HTML API: Add support for list elements.

Author: dmsnell

phpcs.xml.dist

@@ -224,7 +224,7 @@
 	#############################################################################
 	SELECTIVE EXCLUSIONS
 	Exclude specific files for specific sniffs and/or exclude sub-groups in sniffs.
-	
+
 	These exclusions are listed ordered by alphabetic sniff name.
 	#############################################################################
 	-->
@@ -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

@@ -106,7 +106,7 @@ public function current_node() {
 	 *
 	 * @see https://html.spec.whatwg.org/#has-an-element-in-the-specific-scope
 	 *
-	 * @param string   $tag_name         Name of tag check.
+	 * @param string   $tag_name         Name of tag check, or the class constant HEADING_ELEMENTS to specify H1-H6.
 	 * @param string[] $termination_list List of elements that terminate the search.
 	 * @return bool Whether the element was found in a specific scope.
 	 */
@@ -169,15 +169,18 @@ public function has_element_in_scope( $tag_name ) {
 	 *
 	 * @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',
+			)
+		);
 	}
 
 	/**
@@ -270,7 +273,8 @@ public function pop() {
 	 *
 	 * @see WP_HTML_Open_Elements::pop
 	 *
-	 * @param string $tag_name Name of tag that needs to be popped off of the stack of open elements.
+	 * @param string $tag_name Name of tag that needs to be popped off of the stack of open elements,
+	 *                         or the class constant HEADING_ELEMENTS to specify any of H1-H6.
 	 * @return bool Whether a tag of the given name was found and popped off of the stack of open elements.
 	 */
 	public function pop_until( $tag_name ) {
@@ -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;
 		}
 	}
 
@@ -443,4 +459,15 @@ public function after_element_pop( $item ) {
 				break;
 		}
 	}
+
+	/**
+	 * Represents the collection of H1-H6 elements.
+	 *
+	 * @since 6.5.0
+	 *
+	 * @see has_element_in_scope()
+	 *
+	 * @var string
+	 */
+	const HEADING_ELEMENTS = 'heading-elements';
 }

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

@@ -644,10 +644,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();
 				}
@@ -681,9 +683,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.
@@ -733,7 +737,11 @@ private function step_in_body() {
 			case '-H4':
 			case '-H5':
 			case '-H6':
-				if ( ! $this->state->stack_of_open_elements->has_element_in_scope( '(internal: H1 through H6 - do not use)' ) ) {
+				if (
+					! $this->state->stack_of_open_elements->has_element_in_scope(
+						'(internal: H1 through H6 - do not use)'
+					)
+				) {
 					/*
 					 * This is a parse error; ignore the token.
 					 *
@@ -751,6 +759,92 @@ 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();
+
+				in_body_list_loop:
+				if ( $tag_name === $node->node_name ) {
+					$this->generate_implied_end_tags();
+					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 );
+					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 (
+					(
+						'LI' === $tag_name &&
+						! $this->state->stack_of_open_elements->has_element_in_list_item_scope( 'LI' )
+					) ||
+					(
+						'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"
 			 */
@@ -1128,6 +1222,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',
 		);
 
@@ -1153,6 +1250,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',
 		);