HTML API: Introduce wp_split_class_names().

This patch introduces a new CSS helper module containing a new function,
`wp_split_class_names()`. This function wraps some code to rely on the
HTML API to take an HTML `class` attribute value and return a
`Generator` to iterate over the classes in that value.

Many existing functions perform ad-hoc parsing of CSS class names,
usually by splitting on a space character. However, there are issues
with this approach:

 - There is no decoding of HTML character references, which is normative
   inside HTML attributes.
 - There is no handling of null bytes.
 - Class names can be split by more than just the space character.
 - There is no handling of duplicates, and while mostly benign, code
   forgetting to account for duplicates can lead to defects.

The new function handles the nuances to let developers focus on reading
CSS class names, adding new class names, and removing class names. This
serves a middleground between legacy code interacting with CSS class
names in isolation and code processing full HTML documents.

Author: dmsnell

src/wp-includes/html-api/css-helpers.php

@@ -0,0 +1,58 @@
+<?php
+/**
+ * HTML API: Utility functions for working with CSS and CSS-adjacent content.
+ *
+ * @package WordPress
+ * @subpackage HTML-API
+ * @since 6.9.0
+ */
+
+/**
+ * Iterates over the class names represented by an HTML `class` attribute value.
+ *
+ * Because this is aware of the HTML and CSS semantics, duplicate values will be
+ * skipped and classes will be properly split according to the whitespace rules.
+ * Because this comes without a parent document, it will be parsed as NO QUIRKS
+ * mode and therefore treats class names as byte-identical names rather than as
+ * case-insensitive names.
+ *
+ * Example:
+ *
+ *     foreach ( wp_split_css_class_list( 'alignleft wide alignleft' ) as $name ) {
+ *         echo $name . ' ';
+ *     }
+ *     // "alignleft wide "
+ *
+ *     // The missing semicolon demonstrates one way this follows HTML semantics.
+ *     foreach ( wp_split_css_class_list( "One one ONE &#x80" ) as $name ) {
+ *         echo $name . ' ';
+ *     }
+ *     // "One one ONE € "
+ *
+ *     // It can also be converted into an array.
+ *     $names = iterator_to_array( wp_split_css_class_list( "one &#x61nd two ze&#x00;\x00ro" ) );
+ *     $names === array( 'one', 'and', 'two', 'ze��ro' );
+ *
+ *     // Can be used to join classes uniquely.
+ *     $combined = wp_split_css_class_list( "{$existing} {$new}" );
+ *     $combined = implode( ' ', iterator_to_array( $combined ) );
+ *
+ * @since 6.9.0
+ *
+ * @param string $class_attribute_string Class names as found in an HTML `class` attribute.
+ * @return Generator<non-empty-string> Use this in a foreach loop to iterate over the class names.
+ */
+function wp_split_css_class_list( $class_attribute_string ): Generator {
+	if ( '' === $class_attribute_string || ! is_string( $class_attribute_string ) ) {
+		return;
+	}
+
+	// Get these from the HTML API to avoid ad-hoc parsing HTML or CSS class names.
+	$processor = new WP_HTML_Tag_Processor( '<wp-noop>' );
+	$processor->next_token();
+	$processor->set_attribute( 'class', $class_attribute_string );
+
+	foreach ( $processor->class_list() as $class_name ) {
+		yield $class_name;
+	}
+}

src/wp-settings.php

@@ -268,6 +268,7 @@
 require ABSPATH . WPINC . '/html-api/class-wp-html-stack-event.php';
 require ABSPATH . WPINC . '/html-api/class-wp-html-processor-state.php';
 require ABSPATH . WPINC . '/html-api/class-wp-html-processor.php';
+require ABSPATH . WPINC . '/html-api/css-helpers.php';
 require ABSPATH . WPINC . '/class-wp-block-processor.php';
 require ABSPATH . WPINC . '/class-wp-http.php';
 require ABSPATH . WPINC . '/class-wp-http-streams.php';