Better naming. (#127)

src/Attribute/Component/HasList.php

@@ -0,0 +1,115 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PHPForge\Html\Attribute\Component;
+
+use InvalidArgumentException;
+use PHPForge\Html\Helper\CssClass;
+
+use function in_array;
+use function sprintf;
+
+/**
+ * Is used by widgets that implement list methods.
+ */
+trait HasList
+{
+    protected array $listAttributes = [];
+    protected bool $listContainer = false;
+    protected array $listContainerAttributes = [];
+
+    /**
+     * Set the `HTML` attributes for the `<ul>` or `<ol>` tag.
+     *
+     * @param array $values Attribute values indexed by attribute names.
+     *
+     * @return static A new instance of the current class with the specified `<ul>` or `<ol>` attributes.
+     */
+    public function listAttributes(array $values): static
+    {
+        $new = clone $this;
+        $new->listAttributes = $values;
+
+        return $new;
+    }
+
+    /**
+     * Set the `CSS` class for the `<ul>` or `<ol>` tag.
+     *
+     * @param string $value The CSS class name.
+     *
+     * @return static A new instance of the current class with the specified `<ul>` or `<ol>` class.
+     */
+    public function listClass(string $value): static
+    {
+        $new = clone $this;
+        CssClass::add($new->listAttributes, $value);
+
+        return $new;
+    }
+
+    /**
+     * Enable or disable the container tag for tag `<ul>` or `<ol>`.
+     *
+     * @param bool $value `true` to enable the container, `false` to disable.
+     *
+     * @return static A new instance of the current class with the specified container for tag `<ul>` or `<ol>`.
+     */
+    public function listContainer(bool $value): static
+    {
+        $new = clone $this;
+        $new->listContainer = $value;
+
+        return $new;
+    }
+
+    /**
+     * Set the `HTML` attributes for the container for tag `<ul>` or `<ol>`.
+     *
+     * @param array $values Attribute values indexed by attribute names.
+     *
+     * @return static A new instance of the current class with the specified container attributes for tag `<ul>` or `<ol>`.
+     */
+    public function listContainerAttributes(array $values): static
+    {
+        $new = clone $this;
+        $new->listContainerAttributes = $values;
+
+        return $new;
+    }
+
+    /**
+     * Set the `CSS` class for the container for tag `<ul>` or `<ol>`.
+     *
+     * @param string $value The CSS class name.
+     *
+     * @return static A new instance of the current class with the specified container class for tag `<ul>` or `<ol>`.
+     */
+    public function listContainerClass(string $value): static
+    {
+        $new = clone $this;
+        CssClass::add($new->listContainerAttributes, $value);
+
+        return $new;
+    }
+
+    /**
+     * Set list type for tag `<ul>` or `<ol>`.
+     *
+     * @param string $value The list type.
+     *
+     * @return static A new instance of the current class with the specified list type for tag `<ul>` or `<ol>`.
+     */
+    public function listType(string $value): static
+    {
+        if (in_array($value, ['ul', 'ol'], true) === false) {
+            throw new InvalidArgumentException(sprintf('Invalid list type "%s".', $value));
+        }
+
+        $new = clone $this;
+        $new->listAttributes['type'] = $value;
+
+        return $new;
+    }
+}

tests/Attribute/Component/HasListTest.php

@@ -0,0 +1,82 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PHPForge\Html\Tests\Attribute\Component;
+
+use InvalidArgumentException;
+use PHPForge\Html\Attribute\Component\HasList;
+use PHPUnit\Framework\TestCase;
+
+final class HasListTest extends TestCase
+{
+    public function testClass(): void
+    {
+        $instance = new class() {
+            use HasList;
+
+            public function getListClass(): string
+            {
+                return $this->listAttributes['class'] ?? '';
+            }
+        };
+
+        $this->assertEmpty($instance->getListClass());
+
+        $instance = $instance->listClass('foo');
+
+        $this->assertSame('foo', $instance->getListClass());
+
+        $instance = $instance->listClass('bar');
+
+        $this->assertSame('foo bar', $instance->getListClass());
+    }
+
+    public function testContainerClass(): void
+    {
+        $instance = new class() {
+            use HasList;
+
+            public function getListContainerClass(): string
+            {
+                return $this->listContainerAttributes['class'] ?? '';
+            }
+        };
+
+        $this->assertEmpty($instance->getListContainerClass());
+
+        $instance = $instance->listContainerClass('foo');
+
+        $this->assertSame('foo', $instance->getListContainerClass());
+
+        $instance = $instance->listContainerClass('bar');
+
+        $this->assertSame('foo bar', $instance->getListContainerClass());
+    }
+
+    public function testException(): void
+    {
+        $instance = new class() {
+            use HasList;
+        };
+
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('Invalid list type "foo".');
+
+        $instance->listType('foo');
+    }
+
+    public function testImmutablity(): void
+    {
+        $instance = new class() {
+            use HasList;
+        };
+
+        $this->assertNotSame($instance, $instance->listAttributes([]));
+        $this->assertNotSame($instance, $instance->listClass(''));
+        $this->assertNotSame($instance, $instance->listContainer(true));
+        $this->assertNotSame($instance, $instance->listContainerAttributes([]));
+        $this->assertNotSame($instance, $instance->listContainerClass(''));
+        $this->assertNotSame($instance, $instance->listType('ul'));
+    }
+}