[TASK] Add and implement CSSElement interface (#1231)

Also add tests to confirm that the supplanted types in the DocBlock actually
implement the new interface.

And correct a DocBlock type to also allow `string`,
which is currently possible.

cf. #1230

Author: JakeQZ

CHANGELOG.md

@@ -10,6 +10,7 @@ Please also have a look at our
 
 ### Added
 
+- Add Interface `CSSElement` (#1231)
 - Methods `getLineNumber` and `getColumnNumber` which return a nullable `int`
   for the following classes:
   `Comment`, `CSSList`, `SourceException`, `Charset`, `CSSNamespace`, `Import`,

README.md

@@ -624,6 +624,9 @@ classDiagram
 
     %% Start of the part originally generated from the PHP code using tasuku43/mermaid-class-diagram
 
+    class CSSElement {
+        <<interface>>
+    }
     class Renderable {
         <<interface>>
     }
@@ -721,9 +724,11 @@ classDiagram
     }
 
     RuleSet <|-- DeclarationBlock: inheritance
+    Renderable <|-- CSSElement: inheritance
     Renderable <|-- CSSListItem: inheritance
     Commentable <|-- CSSListItem: inheritance
     Positionable <|.. RuleSet: realization
+    CSSElement <|.. RuleSet: realization
     CSSListItem <|.. RuleSet: realization
     RuleSet <|-- AtRuleSet: inheritance
     AtRule <|.. AtRuleSet: realization
@@ -736,7 +741,7 @@ classDiagram
     AtRule <|.. Import: realization
     Positionable <|.. CSSNamespace: realization
     AtRule <|.. CSSNamespace: realization
-    Renderable <|.. Rule: realization
+    CSSElement <|.. Rule: realization
     Positionable <|.. Rule: realization
     Commentable <|.. Rule: realization
     SourceException <|-- OutputException: inheritance
@@ -746,6 +751,7 @@ classDiagram
     SourceException <|-- UnexpectedTokenException: inheritance
     CSSList <|-- CSSBlockList: inheritance
     CSSBlockList <|-- Document: inheritance
+    CSSElement <|.. CSSList: realization
     Positionable <|.. CSSList: realization
     CSSListItem <|.. CSSList: realization
     CSSList <|-- KeyFrame: inheritance
@@ -758,7 +764,7 @@ classDiagram
     Value <|-- ValueList: inheritance
     CSSFunction <|-- CalcFunction: inheritance
     ValueList <|-- LineName: inheritance
-    Renderable <|.. Value: realization
+    CSSElement <|.. Value: realization
     Positionable <|.. Value: realization
     PrimitiveValue <|-- Size: inheritance
     PrimitiveValue <|-- CSSString: inheritance

src/CSSElement.php

@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Sabberworm\CSS;
+
+/**
+ * Represents any entity in the CSS that is encapsulated by a class.
+ *
+ * Its primary purpose is to provide a type for use with `Document::getAllValues()`
+ * when a subset of values from a particular part of the document is required.
+ *
+ * Thus, elements which don't contain `Value`s (such as statement at-rules) don't need to implement this.
+ *
+ * It extends `Renderable` because every element is renderable.
+ */
+interface CSSElement extends Renderable {}

src/CSSList/CSSBlockList.php

@@ -4,6 +4,7 @@
 
 namespace Sabberworm\CSS\CSSList;
 
+use Sabberworm\CSS\CSSElement;
 use Sabberworm\CSS\Property\Selector;
 use Sabberworm\CSS\Rule\Rule;
 use Sabberworm\CSS\RuleSet\DeclarationBlock;
@@ -75,7 +76,7 @@ public function getAllRuleSets(): array
     }
 
     /**
-     * @param CSSList|Rule|RuleSet|Value $element
+     * @param CSSElement|string $element
      * @param list<Value> $result
      */
     protected function allValues(

src/CSSList/CSSList.php

@@ -5,6 +5,7 @@
 namespace Sabberworm\CSS\CSSList;
 
 use Sabberworm\CSS\Comment\CommentContainer;
+use Sabberworm\CSS\CSSElement;
 use Sabberworm\CSS\OutputFormat;
 use Sabberworm\CSS\Parsing\ParserState;
 use Sabberworm\CSS\Parsing\SourceException;
@@ -34,7 +35,7 @@
  * Note that `CSSListItem` extends both `Commentable` and `Renderable`,
  * so those interfaces must also be implemented by concrete subclasses.
  */
-abstract class CSSList implements CSSListItem, Positionable
+abstract class CSSList implements CSSElement, CSSListItem, Positionable
 {
     use CommentContainer;
     use Position;

src/CSSList/Document.php

@@ -4,6 +4,7 @@
 
 namespace Sabberworm\CSS\CSSList;
 
+use Sabberworm\CSS\CSSElement;
 use Sabberworm\CSS\OutputFormat;
 use Sabberworm\CSS\Parsing\ParserState;
 use Sabberworm\CSS\Parsing\SourceException;
@@ -33,7 +34,7 @@ public static function parse(ParserState $parserState): Document
     /**
      * Returns all `Value` objects found recursively in `Rule`s in the tree.
      *
-     * @param CSSList|RuleSet|string $element
+     * @param CSSElement|string $element
      *        the `CSSList` or `RuleSet` to start the search from (defaults to the whole document).
      *        If a string is given, it is used as rule name filter.
      * @param bool $searchInFunctionArguments whether to also return Value objects used as Function arguments.

src/Rule/Rule.php

@@ -7,13 +7,13 @@
 use Sabberworm\CSS\Comment\Comment;
 use Sabberworm\CSS\Comment\Commentable;
 use Sabberworm\CSS\Comment\CommentContainer;
+use Sabberworm\CSS\CSSElement;
 use Sabberworm\CSS\OutputFormat;
 use Sabberworm\CSS\Parsing\ParserState;
 use Sabberworm\CSS\Parsing\UnexpectedEOFException;
 use Sabberworm\CSS\Parsing\UnexpectedTokenException;
 use Sabberworm\CSS\Position\Position;
 use Sabberworm\CSS\Position\Positionable;
-use Sabberworm\CSS\Renderable;
 use Sabberworm\CSS\Value\RuleValueList;
 use Sabberworm\CSS\Value\Value;
 
@@ -22,7 +22,7 @@
  *
  * In CSS, `Rule`s are expressed as follows: “key: value[0][0] value[0][1], value[1][0] value[1][1];”
  */
-class Rule implements Commentable, Positionable, Renderable
+class Rule implements Commentable, CSSElement, Positionable
 {
     use CommentContainer;
     use Position;

src/RuleSet/RuleSet.php

@@ -5,6 +5,7 @@
 namespace Sabberworm\CSS\RuleSet;
 
 use Sabberworm\CSS\Comment\CommentContainer;
+use Sabberworm\CSS\CSSElement;
 use Sabberworm\CSS\CSSList\CSSListItem;
 use Sabberworm\CSS\OutputFormat;
 use Sabberworm\CSS\Parsing\ParserState;
@@ -26,7 +27,7 @@
  * Note that `CSSListItem` extends both `Commentable` and `Renderable`,
  * so those interfaces must also be implemented by concrete subclasses.
  */
-abstract class RuleSet implements CSSListItem, Positionable
+abstract class RuleSet implements CSSElement, CSSListItem, Positionable
 {
     use CommentContainer;
     use Position;

src/Value/Value.php

@@ -4,19 +4,19 @@
 
 namespace Sabberworm\CSS\Value;
 
+use Sabberworm\CSS\CSSElement;
 use Sabberworm\CSS\Parsing\ParserState;
 use Sabberworm\CSS\Parsing\SourceException;
 use Sabberworm\CSS\Parsing\UnexpectedEOFException;
 use Sabberworm\CSS\Parsing\UnexpectedTokenException;
 use Sabberworm\CSS\Position\Position;
 use Sabberworm\CSS\Position\Positionable;
-use Sabberworm\CSS\Renderable;
 
 /**
  * Abstract base class for specific classes of CSS values: `Size`, `Color`, `CSSString` and `URL`, and another
  * abstract subclass `ValueList`.
  */
-abstract class Value implements Positionable, Renderable
+abstract class Value implements CSSElement, Positionable
 {
     use Position;
 

tests/Unit/CSSList/CSSListTest.php

@@ -6,6 +6,7 @@
 
 use PHPUnit\Framework\TestCase;
 use Sabberworm\CSS\Comment\Commentable;
+use Sabberworm\CSS\CSSElement;
 use Sabberworm\CSS\Renderable;
 use Sabberworm\CSS\RuleSet\DeclarationBlock;
 use Sabberworm\CSS\Tests\Unit\CSSList\Fixtures\ConcreteCSSList;
@@ -15,6 +16,16 @@
  */
 final class CSSListTest extends TestCase
 {
+    /**
+     * @test
+     */
+    public function implementsCSSElement(): void
+    {
+        $subject = new ConcreteCSSList();
+
+        self::assertInstanceOf(CSSElement::class, $subject);
+    }
+
     /**
      * @test
      */

tests/Unit/Rule/RuleTest.php

@@ -5,6 +5,7 @@
 namespace Sabberworm\CSS\Tests\Unit\Rule;
 
 use PHPUnit\Framework\TestCase;
+use Sabberworm\CSS\CSSElement;
 use Sabberworm\CSS\Parsing\ParserState;
 use Sabberworm\CSS\Rule\Rule;
 use Sabberworm\CSS\Settings;
@@ -17,6 +18,16 @@
  */
 final class RuleTest extends TestCase
 {
+    /**
+     * @test
+     */
+    public function implementsCSSElement(): void
+    {
+        $subject = new Rule('beverage-container');
+
+        self::assertInstanceOf(CSSElement::class, $subject);
+    }
+
     /**
      * @return array<string, array{0: string, 1: list<class-string>}>
      */

tests/Unit/RuleSet/Fixtures/ConcreteRuleSet.php

@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Sabberworm\CSS\Tests\Unit\RuleSet\Fixtures;
+
+use Sabberworm\CSS\OutputFormat;
+use Sabberworm\CSS\RuleSet\RuleSet;
+
+final class ConcreteRuleSet extends RuleSet
+{
+    /**
+     * @return never
+     */
+    public function render(OutputFormat $outputFormat): string
+    {
+        throw new \BadMethodCallException('Nothing to see here :/', 1744067015);
+    }
+}

tests/Unit/RuleSet/RuleSetTest.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Sabberworm\CSS\Tests\Unit\RuleSet;
+
+use PHPUnit\Framework\TestCase;
+use Sabberworm\CSS\CSSElement;
+use Sabberworm\CSS\Tests\Unit\RuleSet\Fixtures\ConcreteRuleSet;
+
+/**
+ * @covers \Sabberworm\CSS\RuleSet\RuleSet
+ */
+final class RuleSetTest extends TestCase
+{
+    /**
+     * @test
+     */
+    public function implementsCSSElement(): void
+    {
+        $subject = new ConcreteRuleSet();
+
+        self::assertInstanceOf(CSSElement::class, $subject);
+    }
+}

tests/Unit/Value/Fixtures/ConcreteValue.php

@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Sabberworm\CSS\Tests\Unit\Value\Fixtures;
+
+use Sabberworm\CSS\OutputFormat;
+use Sabberworm\CSS\Value\Value;
+
+final class ConcreteValue extends Value
+{
+    /**
+     * @return never
+     */
+    public function render(OutputFormat $outputFormat): string
+    {
+        throw new \BadMethodCallException('Nothing to see here :/', 1744067951);
+    }
+}

tests/Unit/Value/ValueTest.php

@@ -5,9 +5,11 @@
 namespace Sabberworm\CSS\Tests\Unit\Value;
 
 use PHPUnit\Framework\TestCase;
+use Sabberworm\CSS\CSSElement;
 use Sabberworm\CSS\OutputFormat;
 use Sabberworm\CSS\Parsing\ParserState;
 use Sabberworm\CSS\Settings;
+use Sabberworm\CSS\Tests\Unit\Value\Fixtures\ConcreteValue;
 use Sabberworm\CSS\Value\CSSFunction;
 use Sabberworm\CSS\Value\Value;
 
@@ -25,6 +27,16 @@ final class ValueTest extends TestCase
      */
     private const DEFAULT_DELIMITERS = [',', ' ', '/'];
 
+    /**
+     * @test
+     */
+    public function implementsCSSElement(): void
+    {
+        $subject = new ConcreteValue();
+
+        self::assertInstanceOf(CSSElement::class, $subject);
+    }
+
     /**
      * @return array<string, array{0: string}>
      */