Add WP_HTML_Processor

[ockham]

What?

Part of #44410.

Add WP_HTML_Processor, a subclass of WP_Tag_HTML_Processor, which allows "broader" access to the parsed HTML, by providing the get_content_inside_balanced_tags() method, and some related helper methods, such as balanced_next().

Why?

This is a requirement for the Block Interactivity API (see WordPress/block-interactivity-experiments#120). Furthermore, balanced_next() is also a prerequisite for set_content_inside_balanced_tags() (see #47036).

How?

The code is copy-pasted from @dmsnell's #46345 (which has a much wider scope). I've only applied some formatting, fixed some lint errors, and added some PHPDoc.

Testing Instructions

See unit tests!

TODO

• Separate file for WP_HTML_Processor_Scan_State
• PHPDoc
• Add/update @since
• PHPDoc for tests?

[github-actions]

Flaky tests detected in 35bd051.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/4053307533
📝 Reported issues:

• [Flaky Test] should select and deselect with shift and arrow keys #44382 in specs/editor/various/multi-block-selection.test.js

[ockham]

Opening for review. As stated in the PR desc, this is pretty much copy-pasted from @dmsnell's #46345.

Not sure if you'd rather make any changes to the API and/or test coverage -- I wanted to open this early to get the ball rolling for get_content_inside_balanced_tags 😊

[ockham]

Closing. Per recent discussions, we're going to unblock the work in the BHE repo by implementing missing features in a subclass of WP_HTML_Tag_Processor right there (e.g.).

Development of the HTML Processor API is expected to progress more cautiously/slowly, to take into account more exotic HTML constructs; it will happen in (forks of) the wordpress-develop repo (e.g.).