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 );