From fd615cbeef9ab149f8f86831f47b1447c8a71d4b Mon Sep 17 00:00:00 2001 From: Jake Hotson Date: Fri, 23 Jan 2026 23:12:05 +0000 Subject: [PATCH 1/3] [TASK] Add `SelectorComponent` interface This will be implemented by `CompoundSelector` and `Combinator` to break up the components of a selector. Part of #1325. --- src/Property/Selector/SelectorComponent.php | 23 +++++++++++++++++++++ 1 file changed, 23 insertions(+) create mode 100644 src/Property/Selector/SelectorComponent.php diff --git a/src/Property/Selector/SelectorComponent.php b/src/Property/Selector/SelectorComponent.php new file mode 100644 index 000000000..6ff9d3a47 --- /dev/null +++ b/src/Property/Selector/SelectorComponent.php @@ -0,0 +1,23 @@ + + */ + public function getSpecificity(): int; +} From 2eb97348b3196a71f8e01169d6ed2cd7d397ef5d Mon Sep 17 00:00:00 2001 From: Jake Hotson Date: Sun, 25 Jan 2026 19:13:19 +0000 Subject: [PATCH 2/3] Add description for interface. Change `getStringValue()` to `getValue()` (and also for `setValue()`). --- src/Property/Selector/SelectorComponent.php | 24 +++++++++++++++++++-- 1 file changed, 22 insertions(+), 2 deletions(-) diff --git a/src/Property/Selector/SelectorComponent.php b/src/Property/Selector/SelectorComponent.php index 6ff9d3a47..f3ce0e2ed 100644 --- a/src/Property/Selector/SelectorComponent.php +++ b/src/Property/Selector/SelectorComponent.php @@ -4,17 +4,37 @@ namespace Sabberworm\CSS\Property\Selector; +/** + * @see https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Selectors/Selector_structure + * + * A complex selector is a sequence of one or more simple and/or compound selectors that are separated by combinators, + * including the white space descendant combinator. + * + * This is essentially a 'selector', as a 'selector list' is a list of comma-separated selectors. + * + * A compound selector is a superset that includes a simple selector: + * - `li` is a simple selector (but can be treated as a compound selector); + * - `li:last-child` is a compound selector; + * - `ul li:last-child` is a complex selector as it has a combinator (the whitespace descendent combinator). + * + * A (complex) selector can be decomposed thus: + * selector = compound-selector [combinator, compound-selector]* + * + * It's a list of alternating types. + * + * This interface covers both types, so they can be put into an array of the interface type. + */ interface SelectorComponent { /** * @return non-empty-string */ - public function getStringValue(): string; + public function getValue(): string; /** * @param non-empty-string $value */ - public function setStringValue(string $value): void; + public function setValue(string $value): void; /** * @return int<0, max> From 37c13b83000a28d332c6eec854c2ab0f353f1767 Mon Sep 17 00:00:00 2001 From: Jake Hotson Date: Tue, 27 Jan 2026 23:55:42 +0000 Subject: [PATCH 3/3] Reword DocBlock --- src/Property/Selector/SelectorComponent.php | 24 +++++++++------------ 1 file changed, 10 insertions(+), 14 deletions(-) diff --git a/src/Property/Selector/SelectorComponent.php b/src/Property/Selector/SelectorComponent.php index f3ce0e2ed..2e105cf11 100644 --- a/src/Property/Selector/SelectorComponent.php +++ b/src/Property/Selector/SelectorComponent.php @@ -5,24 +5,20 @@ namespace Sabberworm\CSS\Property\Selector; /** - * @see https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Selectors/Selector_structure - * - * A complex selector is a sequence of one or more simple and/or compound selectors that are separated by combinators, - * including the white space descendant combinator. - * - * This is essentially a 'selector', as a 'selector list' is a list of comma-separated selectors. + * This interface is for a class that represents a part of a selector which is either a compound selector (or a simple + * selector, which is effectively a compound selector without any compounding) or a selector combinator. * - * A compound selector is a superset that includes a simple selector: - * - `li` is a simple selector (but can be treated as a compound selector); - * - `li:last-child` is a compound selector; - * - `ul li:last-child` is a complex selector as it has a combinator (the whitespace descendent combinator). - * - * A (complex) selector can be decomposed thus: + * It allows a selector to be represented as an array of objects that implement this interface. + * This is the formal definition: * selector = compound-selector [combinator, compound-selector]* * - * It's a list of alternating types. + * The selector is comprised of an array of alternating types that can't be easily represented in a type-safe manner + * without this. + * + * 'Selector component' is not a known grammar in the spec, but a convenience for the implementation. * - * This interface covers both types, so they can be put into an array of the interface type. + * @see https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Selectors/Selector_structure + * @see https://www.w3.org/TR/selectors-4/#structure */ interface SelectorComponent {