Add HasContainerMenu trait for widgets with container menu methods. (#…

…148)

src/Attribute/Custom/HasContainerMenu.php

@@ -0,0 +1,82 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PHPForge\Html\Attribute\Custom;
+
+use InvalidArgumentException;
+use PHPForge\Html\Helper\CssClass;
+
+/**
+ * Is used by widgets that implement container menu methods.
+ */
+trait HasContainerMenu
+{
+    protected array $containerMenuAttributes = [];
+
+    /**
+     * Enable or disable the container menu tag.
+     *
+     * @param bool $value `true` to enable the container menu, `false` to disable.
+     *
+     * @return static A new instance of the current class with the specified container menu.
+     */
+    public function containerMenu(bool $value): static
+    {
+        $new = clone $this;
+        $new->containerMenu = $value;
+
+        return $new;
+    }
+
+    /**
+     * Set the `HTML` attributes for the container menu.
+     *
+     * @param array $values Attribute values indexed by attribute names.
+     *
+     * @return static A new instance of the current class with the specified container menu attributes.
+     */
+    public function containerMenuAttributes(array $values = []): static
+    {
+        $new = clone $this;
+        $new->containerMenuAttributes = $values;
+
+        return $new;
+    }
+
+    /**
+     * Set the `CSS` class for the container menu.
+     *
+     * @param string $value The CSS class name.
+     *
+     * @return static A new instance of the current class with the specified container menu class.
+     */
+    public function containerMenuClass(string $value): static
+    {
+        $new = clone $this;
+        CssClass::add($new->containerMenuAttributes, $value);
+
+        return $new;
+    }
+
+    /**
+     * Set the container menu tag name.
+     *
+     * @param string $value The tag name for the container menu element.
+     *
+     * @throws InvalidArgumentException If the container tag is an empty string.
+     *
+     * @return static A new instance of the current class with the specified container menu tag.
+     */
+    public function containerMenuTag(string $value): static
+    {
+        if ($value === '') {
+            throw new InvalidArgumentException('The container menu tag must be a non-empty string.');
+        }
+
+        $new = clone $this;
+        $new->containerMenuTag = $value;
+
+        return $new;
+    }
+}

tests/Attribute/Custom/HasContainerMenuTest.php

@@ -0,0 +1,66 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PHPForge\Html\Tests\Attribute\Custom;
+
+use InvalidArgumentException;
+use PHPForge\Html\Attribute\Custom\HasContainerMenu;
+use PHPUnit\Framework\TestCase;
+
+final class HasContainerMenuTest extends TestCase
+{
+    public function testClass(): void
+    {
+        $instance = new class () {
+            use HasContainerMenu;
+
+            protected bool $containerMenu = true;
+            protected string $containerMenuTag = 'div';
+
+            public function getContainerMenuClass(): string
+            {
+                return $this->containerMenuAttributes['class'] ?? '';
+            }
+        };
+
+        $this->assertEmpty($instance->getContainerMenuClass());
+
+        $instance = $instance->containerMenuClass('foo');
+
+        $this->assertSame('foo', $instance->getContainerMenuClass());
+
+        $instance = $instance->containerMenuClass('bar');
+
+        $this->assertSame('foo bar', $instance->getContainerMenuClass());
+    }
+
+    public function testException(): void
+    {
+        $instance = new class () {
+            use HasContainerMenu;
+
+            protected bool $containerMenu = true;
+            protected string $containerMenuTag = '';
+        };
+
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('The container menu tag must be a non-empty string.');
+
+        $instance->containerMenuTag('');
+    }
+
+    public function testImmutablity(): void
+    {
+        $instance = new class () {
+            use HasContainerMenu;
+
+            protected string $containerMenuTag = 'div';
+        };
+
+        $this->assertNotSame($instance, $instance->containerMenu(true));
+        $this->assertNotSame($instance, $instance->containerMenuAttributes([]));
+        $this->assertNotSame($instance, $instance->containerMenuClass(''));
+        $this->assertNotSame($instance, $instance->containerMenuTag('span'));
+    }
+}