[FEATURE] Represent Selector as Component objects

Part of #1325.

Author: JakeQZ

src/Property/Selector.php

@@ -11,18 +11,20 @@
 use Sabberworm\CSS\Property\Selector\Combinator;
 use Sabberworm\CSS\Property\Selector\Component;
 use Sabberworm\CSS\Property\Selector\CompoundSelector;
-use Sabberworm\CSS\Property\Selector\SpecificityCalculator;
 use Sabberworm\CSS\Renderable;
+use Sabberworm\CSS\Settings;
+use Sabberworm\CSS\ShortClassNameProvider;
 
 use function Safe\preg_match;
-use function Safe\preg_replace;
 
 /**
  * Class representing a single CSS selector. Selectors have to be split by the comma prior to being passed into this
  * class.
  */
 class Selector implements Renderable
 {
+    use ShortClassNameProvider;
+
     /**
      * @internal since 8.5.2
      */
@@ -54,9 +56,9 @@ class Selector implements Renderable
         /ux';
 
     /**
-     * @var string
+     * @var list<Component>
      */
-    private $selector;
+    private $components = [];
 
     /**
      * @internal since V8.8.0
@@ -72,9 +74,13 @@ public static function isValid(string $selector): bool
     /**
      * @throws \UnexpectedValueException if the selector is not valid
      */
-    final public function __construct(string $selector)
+    final public function __construct(string $selector = '')
     {
-        $this->setSelector($selector);
+        // Allow construction of empty object for content to be set via `setComponents()`.
+        // (`setSelector()` will throw an exception when provided with an empty string.)
+        if ($selector !== '') {
+            $this->setSelector($selector);
+        }
     }
 
     /**
@@ -137,52 +143,76 @@ public static function parse(ParserState $parserState, array &$comments = []): s
             );
         }
 
-        $selectorString = '';
-        foreach ($selectorParts as $selectorPart) {
-            $selectorPartValue = $selectorPart->getValue();
-            if (\in_array($selectorPartValue, ['>', '+', '~'], true)) {
-                $selectorString .= ' ' . $selectorPartValue . ' ';
-            } else {
-                $selectorString .= $selectorPartValue;
-            }
-        }
+        return (new static())->setComponents($selectorParts);
+    }
 
-        return new static($selectorString);
+    /**
+     * @return list<Component>
+     */
+    public function getComponents(): array
+    {
+        return $this->components;
+    }
+
+    /**
+     * @param list<Component> $components
+     *        This should be an alternating sequence of `CompoundSelector` and `Combinator`, starting and ending with a
+     *        `CompoundSelector`, and may be a single `CompoundSelector`.
+     */
+    public function setComponents(array $components): self
+    {
+        $this->components = $components;
+
+        return $this;
     }
 
     public function getSelector(): string
     {
-        return $this->selector;
+        return $this->render(new OutputFormat());
     }
 
     /**
      * @throws \UnexpectedValueException if the selector is not valid
      */
     public function setSelector(string $selector): void
     {
-        if (!self::isValid($selector)) {
-            throw new \UnexpectedValueException("Selector `$selector` is not valid.");
-        }
+        $parserState = new ParserState($selector, Settings::create());
 
-        $selector = \trim($selector);
+        $components = self::parseComponents($parserState);
 
-        $hasAttribute = \strpos($selector, '[') !== false;
+        // Check that the selector has been fully parsed:
+        if (!$parserState->isEnd()) {
+            throw new UnexpectedTokenException(
+                'EOF',
+                $parserState->peek(5),
+                'literal'
+            );
+        }
 
-        // Whitespace can't be adjusted within an attribute selector, as it would change its meaning
-        $this->selector = !$hasAttribute ? preg_replace('/\\s++/', ' ', $selector) : $selector;
+        $this->components = $components;
     }
 
     /**
      * @return int<0, max>
      */
     public function getSpecificity(): int
     {
-        return SpecificityCalculator::calculate($this->selector);
+        return \array_sum(\array_map(
+            static function (Component $component): int {
+                return $component->getSpecificity();
+            },
+            $this->components
+        ));
     }
 
     public function render(OutputFormat $outputFormat): string
     {
-        return $this->getSelector();
+        return \implode('', \array_map(
+            static function (Component $component) use ($outputFormat): string {
+                return $component->render($outputFormat);
+            },
+            $this->components
+        ));
     }
 
     /**
@@ -192,6 +222,14 @@ public function render(OutputFormat $outputFormat): string
      */
     public function getArrayRepresentation(): array
     {
-        throw new \BadMethodCallException('`getArrayRepresentation` is not yet implemented for `' . self::class . '`');
+        return [
+            'class' => $this->getShortClassName(),
+            'components' => \array_map(
+                static function (Component $component): array {
+                    return $component->getArrayRepresentation();
+                },
+                $this->components
+            ),
+        ];
     }
 }

tests/Unit/Property/KeyframeSelectorTest.php

@@ -6,6 +6,7 @@
 
 use PHPUnit\Framework\TestCase;
 use Sabberworm\CSS\Property\KeyframeSelector;
+use Sabberworm\CSS\Property\Selector\CompoundSelector;
 
 /**
  * @covers \Sabberworm\CSS\Property\KeyframeSelector
@@ -16,12 +17,24 @@ final class KeyframeSelectorTest extends TestCase
     /**
      * @test
      */
-    public function getArrayRepresentationThrowsException(): void
+    public function getArrayRepresentationIncludesClassName(): void
     {
-        $this->expectException(\BadMethodCallException::class);
+        $subject = new KeyframeSelector('');
 
-        $subject = new KeyframeSelector('a');
+        $result = $subject->getArrayRepresentation();
 
-        $subject->getArrayRepresentation();
+        self::assertSame('KeyframeSelector', $result['class']);
+    }
+
+    /**
+     * @test
+     */
+    public function getArrayRepresentationIncludesComponent(): void
+    {
+        $subject = (new KeyframeSelector(''))->setComponents([new CompoundSelector('50%')]);
+
+        $result = $subject->getArrayRepresentation();
+
+        self::assertSame('50%', $result['components'][0]['value']);
     }
 }

tests/Unit/Property/SelectorTest.php

@@ -9,6 +9,7 @@
 use Sabberworm\CSS\Parsing\ParserState;
 use Sabberworm\CSS\Parsing\UnexpectedTokenException;
 use Sabberworm\CSS\Property\Selector;
+use Sabberworm\CSS\Property\Selector\CompoundSelector;
 use Sabberworm\CSS\Renderable;
 use Sabberworm\CSS\Settings;
 use TRegx\PhpUnit\DataProviders\DataProvider;
@@ -329,10 +330,17 @@ public function canConstructObjectWithEmptyState(): void
      * @test
      *
      * @dataProvider provideInvalidSelectors
+     * @dataProvider provideInvalidSelectorsForParse
      */
     public function constructorThrowsExceptionWithInvalidSelector(string $selector): void
     {
-        $this->expectException(\UnexpectedValueException::class);
+        // An empty string is allowed to construct an empty object
+        if ($selector === '') {
+            self::expectNotToPerformAssertions();
+            return;
+        }
+
+        $this->expectException(UnexpectedTokenException::class);
 
         new Selector($selector);
     }
@@ -341,10 +349,11 @@ public function constructorThrowsExceptionWithInvalidSelector(string $selector):
      * @test
      *
      * @dataProvider provideInvalidSelectors
+     * @dataProvider provideInvalidSelectorsForParse
      */
     public function setSelectorThrowsExceptionWithInvalidSelector(string $selector): void
     {
-        $this->expectException(\UnexpectedValueException::class);
+        $this->expectException(UnexpectedTokenException::class);
 
         $subject = new Selector('a');
 
@@ -458,12 +467,24 @@ public function doesNotCleanupSpacesWithinAttributeSelector(): void
     /**
      * @test
      */
-    public function getArrayRepresentationThrowsException(): void
+    public function getArrayRepresentationIncludesClassName(): void
     {
-        $this->expectException(\BadMethodCallException::class);
+        $subject = new Selector('');
 
-        $subject = new Selector('a');
+        $result = $subject->getArrayRepresentation();
+
+        self::assertSame('Selector', $result['class']);
+    }
+
+    /**
+     * @test
+     */
+    public function getArrayRepresentationIncludesComponent(): void
+    {
+        $subject = (new Selector(''))->setComponents([new CompoundSelector('p.test')]);
+
+        $result = $subject->getArrayRepresentation();
 
-        $subject->getArrayRepresentation();
+        self::assertSame('p.test', $result['components'][0]['value']);
     }
 }