HTML API: Add method to report depth of currently-matched element.

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

@@ -1263,6 +1263,17 @@ public function get_tag() {
 		}
 	}
 
+	/**
+	 * Return how deep the currently-matched element is in the HTML document.
+	 *
+	 * @since 6.6.0
+	 *
+	 * @return int
+	 */
+	public function get_current_depth() {
+		return $this->state->stack_of_open_elements->count();
+	}
+
 	/**
 	 * Removes a bookmark that is no longer needed.
 	 *

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

@@ -334,4 +334,49 @@ public static function data_unsupported_special_in_body_tags() {
 			'XMP'       => array( 'XMP' ),
 		);
 	}
+
+	/**
+	 * Ensures that the HTML Processor properly reports the depth of a given element.
+	 *
+	 * @ticket 61255
+	 *
+	 * @dataProvider data_html_with_target_element_and_depth_in_body
+	 *
+	 * @param string $html_with_target_element HTML containing element with `target` class.
+	 * @param int    $depth_at_element         Depth into document at target node.
+	 */
+	public function test_reports_proper_element_depth_in_body( $html_with_target_element, $depth_at_element ) {
+		$processor = WP_HTML_Processor::create_fragment( $html_with_target_element );
+
+		while ( $processor->next_tag() ) {
+			if ( $processor->has_class( 'target' ) ) {
+				break;
+			}
+		}
+
+		$this->assertSame(
+			'#tag',
+			$processor->get_token_type(),
+			'Failed to find target element: check test data provider.'
+		);
+
+		$this->assertSame(
+			$depth_at_element,
+			$processor->get_current_depth(),
+			'HTML Processor reported the wrong depth at the matched element.'
+		);
+	}
+
+	/**
+	 * Data provider.
+	 *
+	 * @return array[].
+	 */
+	public static function data_html_with_target_element_and_depth_in_body() {
+		return array(
+			'Single element'                    => array( '<div class="target">', 3 ),
+			'Basic layout and formatting stack' => array( '<div><span><p><b><em class="target">', 7 ),
+			'Adjacent elements'                 => array( '<div><span></span><span class="target"></div>', 4 ),
+		);
+	}
 }