diff --git a/src/wp-includes/html-api/class-wp-css-complex-selector.php b/src/wp-includes/html-api/class-wp-css-complex-selector.php
index 9db2912d3ac16..1f03f133c8806 100644
--- a/src/wp-includes/html-api/class-wp-css-complex-selector.php
+++ b/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 `` 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 );
}
/**
diff --git a/tests/phpunit/tests/html-api/wpCssComplexSelectorList.php b/tests/phpunit/tests/html-api/wpCssComplexSelectorList.php
index 795e230033cdb..dc89869ea2e66 100644
--- a/tests/phpunit/tests/html-api/wpCssComplexSelectorList.php
+++ b/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 );