added DomQuery::closest()

Author: dg

src/Framework/DomQuery.php

@@ -112,6 +112,19 @@ public function matches(string $selector): bool
 	}
 
 
+	/**
+	 * Returns closest ancestor matching CSS selector.
+	 */
+	public function closest(string $selector): ?self
+	{
+		if (PHP_VERSION_ID < 80400) {
+			throw new \LogicException('Requires PHP 8.4 or newer.');
+		}
+		$el = Dom\import_simplexml($this)->closest($selector);
+		return $el ? simplexml_import_dom($el, self::class) : null;
+	}
+
+
 	/**
 	 * Converts a CSS selector into an XPath expression.
 	 */

tests/Framework/DomQuery.fromHtml.84.phpt

@@ -97,6 +97,24 @@ test('matches() checks if element matches selector', function () {
 	Assert::false($para->matches('.test'));
 });
 
+test('closest() finds nearest matching ancestor', function () {
+	$dom = DomQuery::fromHtml('
+        <div class="outer">
+            <div class="middle">
+                <div class="inner">
+                    <p>Test</p>
+                </div>
+            </div>
+        </div>
+    ');
+
+	$p = $dom->find('p')[0];
+	Assert::type(DomQuery::class, $p->closest('div'));
+	Assert::true($p->closest('div')->matches('.inner'));
+	Assert::true($p->closest('.outer')->matches('.outer'));
+	Assert::null($p->closest('span'));
+});
+
 test('find() returns empty array for no matches', function () {
 	$dom = DomQuery::fromHtml('<div></div>');
 	Assert::same([], $dom->find('nonexistent'));