Add previous and next sibling functions (#815)

* Add previous and next sibling functions

* Remove unused import

* Style fixes

* Use snake case for method names

* Fix method names

Author: dustinpaluch

src/mantle/support/class-html.php

@@ -152,6 +152,36 @@ public function first_by_selector( string $selector ): static {
 		return $this->filter( $selector )->first();
 	}
 
+	/**
+	 * Get the nearest previous sibling element.
+	 *
+	 * @param string|null $selector Optional CSS selector to filter the previous siblings.
+	 * @throws \InvalidArgumentException If the current node list is empty.
+	 */
+	public function previous_sibling( ?string $selector = null ): static {
+		if ( ! $this->has_nodes() ) {
+			throw new \InvalidArgumentException( 'The current node list is empty.' );
+		}
+
+		$previous = $this->previousAll();
+		return (bool) $selector ? $previous->filter( $selector )->first() : $previous->first();
+	}
+
+	/**
+	 * Get the nearest next sibling element.
+	 *
+	 * @param string|null $selector Optional CSS selector to filter the next siblings.
+	 * @throws \InvalidArgumentException If the current node list is empty.
+	 */
+	public function next_sibling( ?string $selector = null ): static {
+		if ( ! $this->has_nodes() ) {
+			throw new \InvalidArgumentException( 'The current node list is empty.' );
+		}
+
+		$next = $this->nextAll();
+		return (bool) $selector ? $next->filter( $selector )->first() : $next->first();
+	}
+
 	/**
 	 * Retrieve all elements matching an XPath expression.
 	 *

tests/Support/HtmlTest.php

@@ -569,4 +569,42 @@ public function test_element_assertions(): void {
 			->assertElementExistsByTestId( 'test-item' )
 			->assertQuerySelectorMissing( '.non-existent-class' );
 	}
+
+	public function test_it_can_get_the_nearest_previous_sibling(): void {
+		$html = new HTML(self::TEST_CONTENT);
+		$previous = $html->filter('#test-id')->previous_sibling();
+		$this->assertInstanceOf(HTML::class, $previous);
+		$this->assertEquals('div', $previous->nodeName());
+		$this->assertEquals('test-class', $previous->attr('class'));
+		$this->assertEquals('Example Div By Class', $previous->text());
+	}
+
+	public function test_it_can_get_the_nearest_next_sibling(): void {
+		$html = new HTML(self::TEST_CONTENT);
+		$next = $html->filter('#test-id')->next_sibling();
+		$this->assertInstanceOf(HTML::class, $next);
+		$this->assertEquals('ul', $next->nodeName());
+	}
+
+	public function test_it_returns_empty_crawler_for_missing_next_sibling(): void {
+		$html = new HTML(self::TEST_CONTENT);
+		$next = $html->filter('ul')->next_sibling();
+		$this->assertInstanceOf(HTML::class, $next);
+		$this->assertEquals(0, $next->count());
+	}
+
+	public function test_it_can_get_the_nearest_previous_filtered_sibling(): void {
+		$html = new HTML(self::TEST_CONTENT);
+		$previous = $html->filter('#test-id')->previous_sibling('section');
+		$this->assertInstanceOf(HTML::class, $previous);
+		$this->assertEquals('section', $previous->nodeName());
+	}
+
+	public function test_it_can_get_the_nearest_next_filtered_sibling(): void {
+		$html = new HTML(self::TEST_CONTENT);
+		$next = $html->filter('section')->next_sibling('ul');
+		$this->assertInstanceOf(HTML::class, $next);
+		$this->assertEquals('ul', $next->nodeName());
+	}
+
 }