Rework structure of complex_selector class

src/wp-includes/html-api/class-wp-css-complex-selector.php

@@ -12,7 +12,7 @@ final class WP_CSS_Complex_Selector implements WP_CSS_HTML_Processor_Matcher {
 	const COMBINATOR_SUBSEQUENT_SIBLING = '~';
 
 	/**
-	 * This is the selector in the final position of the complex selector. This corresponds to the
+	 * The "self selector" is the last element in a complex selector, it corresponds to the
 	 * selected element.
 	 *
 	 * @example
@@ -27,12 +27,20 @@ final class WP_CSS_Complex_Selector implements WP_CSS_HTML_Processor_Matcher {
 	public $self_selector;
 
 	/**
-	 * This is the selector in the final position of the complex selector. This corresponds to the
-	 * selected element.
+	 * The "context selectors" are zero or more elements that provide additional constraints for
+	 * the "self selector."
+	 *
+	 * In this example selector, and element like `<el class="selected">` is selected iff:
+	 *   - it is a child of an `H1` element
+	 *   - *and* that `H1` element is a descendant of a `HEADING` element.
+	 *
+	 * The `H1` and `HEADING` parts of this selector are the "context selectors." Note that this
+	 * terminology is used for purposes of this class but does not correspond to language in the
+	 * CSS or selector specifications.
 	 *
 	 * @example
 	 *
-	 *     $relative_selectors
+	 *     $context_selectors
 	 *     ┏━━━━━━┻━━━━┓
 	 *     .heading h1 > el.selected
 	 *
@@ -52,20 +60,20 @@ final class WP_CSS_Complex_Selector implements WP_CSS_HTML_Processor_Matcher {
 	 *     )
 	 *
 	 * @readonly
-	 * @var array{WP_CSS_Type_Selector, string}[]
+	 * @var array{WP_CSS_Type_Selector, string}[]|null
 	 */
-	public $relative_selectors;
+	public $context_selectors;
 
 	/**
 	 * @param WP_CSS_Compound_Selector $self_selector
-	 * @param array{WP_CSS_Type_Selector, string}[] $selectors
+	 * @param array{WP_CSS_Type_Selector, string}[]|null $selectors
 	 */
 	public function __construct(
 		WP_CSS_Compound_Selector $self_selector,
-		?array $relative_selectors
+		?array $context_selectors
 	) {
-		$this->self_selector      = $self_selector;
-		$this->relative_selectors = $relative_selectors;
+		$this->self_selector     = $self_selector;
+		$this->context_selectors = $context_selectors;
 	}
 
 	public function matches( WP_HTML_Processor $processor ): bool {
@@ -74,13 +82,13 @@ public function matches( WP_HTML_Processor $processor ): bool {
 			return false;
 		}
 
-		if ( null === $this->relative_selectors || array() === $this->relative_selectors ) {
+		if ( null === $this->context_selectors || array() === $this->context_selectors ) {
 			return true;
 		}
 
 		/** @var string[] */
 		$breadcrumbs = array_slice( array_reverse( $processor->get_breadcrumbs() ), 1 );
-		return $this->explore_matches( $this->relative_selectors, $breadcrumbs );
+		return $this->explore_matches( $this->context_selectors, $breadcrumbs );
 	}
 
 	/**

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

@@ -36,14 +36,14 @@ public function test_parse_complex_selector() {
 		/** @var WP_CSS_Complex_Selector|null */
 		$sel = $this->test_class::test_parse_complex_selector( $input, $offset );
 
-		$this->assertSame( 2, count( $sel->relative_selectors ) );
+		$this->assertSame( 2, count( $sel->context_selectors ) );
 
 		// Relative selectors should be reverse ordered.
-		$this->assertSame( 'el2', $sel->relative_selectors[0][0]->ident );
-		$this->assertSame( WP_CSS_Complex_Selector::COMBINATOR_CHILD, $sel->relative_selectors[0][1] );
+		$this->assertSame( 'el2', $sel->context_selectors[0][0]->ident );
+		$this->assertSame( WP_CSS_Complex_Selector::COMBINATOR_CHILD, $sel->context_selectors[0][1] );
 
-		$this->assertSame( 'el1', $sel->relative_selectors[1][0]->ident );
-		$this->assertSame( WP_CSS_Complex_Selector::COMBINATOR_DESCENDANT, $sel->relative_selectors[1][1] );
+		$this->assertSame( 'el1', $sel->context_selectors[1][0]->ident );
+		$this->assertSame( WP_CSS_Complex_Selector::COMBINATOR_DESCENDANT, $sel->context_selectors[1][1] );
 
 		$this->assertSame( 3, count( $sel->self_selector->subclass_selectors ) );
 		$this->assertNull( $sel->self_selector->type_selector );