From 6c4065beea6eeb8dc1eb7e40f49fb24fd4b8b3e7 Mon Sep 17 00:00:00 2001
From: Jake Hotson <jake.github@qzdesign.co.uk>
Date: Sat, 10 May 2025 00:24:02 +0100
Subject: [PATCH] [TASK] Add interface `RuleContainer` for `RuleSet`

This covers the maniplation of `Rule`s within the container,
and may be implemented by other classes in future (e.g. #1194).

Note that the naming is consistent with the current codebase,
rather than what the CSS entities are now called:
- `Rule` represents what is now called a "declaration";
- `RuleSet` represents what is now called a "declaration block";
- `DeclarationBlock` represents what is now called a "style rule";
- `CSSListItem` (closely) represents what is now generically called a "rule".

Renaming things is part of a longer-term plan touched on in #1189.
---
 CHANGELOG.md                       |  1 +
 README.md                          |  4 ++++
 src/CSSList/CSSBlockList.php       |  3 ++-
 src/RuleSet/RuleContainer.php      | 36 ++++++++++++++++++++++++++++++
 src/RuleSet/RuleSet.php            |  2 +-
 tests/Unit/RuleSet/RuleSetTest.php |  9 ++++++++
 6 files changed, 53 insertions(+), 2 deletions(-)
 create mode 100644 src/RuleSet/RuleContainer.php

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 69831196..05c0f51d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,7 @@ Please also have a look at our
 
 ### Added
 
+- Interface `RuleContainer` for `RuleSet` `Rule` manipulation methods (#1256)
 - `RuleSet::removeMatchingRules()` method
   (for the implementing classes `AtRuleSet` and `DeclarationBlock`) (#1249)
 - `RuleSet::removeAllRules()` method
diff --git a/README.md b/README.md
index b69cb6d2..9ecdc3e7 100644
--- a/README.md
+++ b/README.md
@@ -636,6 +636,9 @@ classDiagram
     class CSSListItem {
         <<interface>>
     }
+    class RuleContainer {
+        <<interface>>
+    }
     class DeclarationBlock {
     }
     class RuleSet {
@@ -730,6 +733,7 @@ classDiagram
     Positionable <|.. RuleSet: realization
     CSSElement <|.. RuleSet: realization
     CSSListItem <|.. RuleSet: realization
+    RuleContainer <|.. RuleSet: realization
     RuleSet <|-- AtRuleSet: inheritance
     AtRule <|.. AtRuleSet: realization
     Renderable <|.. Selector: realization
diff --git a/src/CSSList/CSSBlockList.php b/src/CSSList/CSSBlockList.php
index 90643968..2dfd284f 100644
--- a/src/CSSList/CSSBlockList.php
+++ b/src/CSSList/CSSBlockList.php
@@ -8,6 +8,7 @@
 use Sabberworm\CSS\Property\Selector;
 use Sabberworm\CSS\Rule\Rule;
 use Sabberworm\CSS\RuleSet\DeclarationBlock;
+use Sabberworm\CSS\RuleSet\RuleContainer;
 use Sabberworm\CSS\RuleSet\RuleSet;
 use Sabberworm\CSS\Value\CSSFunction;
 use Sabberworm\CSS\Value\Value;
@@ -95,7 +96,7 @@ public function getAllValues(
                     );
                 }
             }
-        } elseif ($element instanceof RuleSet) {
+        } elseif ($element instanceof RuleContainer) {
             foreach ($element->getRules($ruleSearchPattern) as $rule) {
                 $result = \array_merge(
                     $result,
diff --git a/src/RuleSet/RuleContainer.php b/src/RuleSet/RuleContainer.php
new file mode 100644
index 00000000..0c6c5936
--- /dev/null
+++ b/src/RuleSet/RuleContainer.php
@@ -0,0 +1,36 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Sabberworm\CSS\RuleSet;
+
+use Sabberworm\CSS\Rule\Rule;
+
+/**
+ * Represents a CSS item that contains `Rules`, defining the methods to manipulate them.
+ */
+interface RuleContainer
+{
+    public function addRule(Rule $ruleToAdd, ?Rule $sibling = null): void;
+
+    public function removeRule(Rule $ruleToRemove): void;
+
+    public function removeMatchingRules(string $searchPattern): void;
+
+    public function removeAllRules(): void;
+
+    /**
+     * @param array<Rule> $rules
+     */
+    public function setRules(array $rules): void;
+
+    /**
+     * @return array<int<0, max>, Rule>
+     */
+    public function getRules(?string $searchPattern = null): array;
+
+    /**
+     * @return array<string, Rule>
+     */
+    public function getRulesAssoc(?string $searchPattern = null): array;
+}
diff --git a/src/RuleSet/RuleSet.php b/src/RuleSet/RuleSet.php
index e1a07f57..1fc1295e 100644
--- a/src/RuleSet/RuleSet.php
+++ b/src/RuleSet/RuleSet.php
@@ -27,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 CSSElement, CSSListItem, Positionable
+abstract class RuleSet implements CSSElement, CSSListItem, Positionable, RuleContainer
 {
     use CommentContainer;
     use Position;
diff --git a/tests/Unit/RuleSet/RuleSetTest.php b/tests/Unit/RuleSet/RuleSetTest.php
index 774f37e7..03783b8e 100644
--- a/tests/Unit/RuleSet/RuleSetTest.php
+++ b/tests/Unit/RuleSet/RuleSetTest.php
@@ -8,6 +8,7 @@
 use Sabberworm\CSS\CSSElement;
 use Sabberworm\CSS\CSSList\CSSListItem;
 use Sabberworm\CSS\Rule\Rule;
+use Sabberworm\CSS\RuleSet\RuleContainer;
 use Sabberworm\CSS\Tests\Unit\RuleSet\Fixtures\ConcreteRuleSet;
 
 /**
@@ -41,6 +42,14 @@ public function implementsCSSListItem(): void
         self::assertInstanceOf(CSSListItem::class, $this->subject);
     }
 
+    /**
+     * @test
+     */
+    public function implementsRuleContainer(): void
+    {
+        self::assertInstanceOf(RuleContainer::class, $this->subject);
+    }
+
     /**
      * @return array<string, array{0: list<Rule>, 1: string, 2: list<string>}>
      */