Add docs select (#282)

.vscode/Method.php

@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PHPForge\Html\Tests;
+
+use PHPForge\Html\Select;
+
+final class Method extends \PHPUnit\Framework\TestCase
+{
+    public function test(): void
+    {
+        $methods = get_class_methods(Select::class);
+
+        sort($methods);
+        var_dump(implode("\n", $methods));
+        die;
+    }
+}

docs/README.md

@@ -30,6 +30,7 @@ The following tags are currently supported:
 - [ol](/docs/tag/Ol.md)
 - [p](/docs/tag/P.md)
 - [section](/docs/tag/Section.md)
+- [select](/docs/tag/Select.md)
 
 ## Input Tags
 

docs/tag/Select.md

@@ -0,0 +1,234 @@
+# Select
+
+The `<select>` `HTML` element represents a control that provides a menu of options.
+
+## Basic Usage
+
+Instantiate the `Select` class using `Select::widget()`.
+
+```php
+$select = Select::widget();
+```
+
+## Setting Attributes
+
+Use the provided methods to set specific attributes for the a element.
+
+```php
+// setting class attribute
+$select->class('myClass');
+```
+
+Or, use the `attributes` method to set multiple attributes at once.
+
+```php
+$select->attributes(['class' => 'myClass', 'id' => 'myId']);
+```
+
+## Add items
+
+use the `item` method to add items to the `select` element.
+
+```php
+<?= 
+    Select::widget()
+        ->items(
+            [
+                1 => 'Moscu',
+                2 => 'Paris',
+            ]
+        )
+?>
+```
+
+## Add items with groups
+
+use the `groups` method to add items to the `select` element.
+
+```php
+<?php
+
+declare(strict_types=1);
+
+private array $cities = [
+    1 => [
+        2 => ' Moscu',
+        3 => ' San Petersburgo',
+        4 => ' Novosibirsk',
+        5 => ' Ekaterinburgo',
+    ],
+    2 => [
+        6 => 'Santiago',
+        7 => 'Concepcion',
+        8 => 'Chillan',
+    ],
+];
+private array $groups = [
+    1 => [
+        'label' => 'Russia',
+    ],
+    2 => [
+        'label' => 'Chile',
+    ],
+];
+?>
+
+<?= Select::widget()->groups($this->groups)->items($this->cities) ?>
+```
+
+use the `itemsAttributes` method to add attributes to the `option` element.
+
+```php
+<?php
+
+declare(strict_types=1);
+
+private array $cities = [
+    1 => [
+        2 => ' Moscu',
+        3 => ' San Petersburgo',
+        4 => ' Novosibirsk',
+        5 => ' Ekaterinburgo',
+    ],
+    2 => [
+        6 => 'Santiago',
+        7 => 'Concepcion',
+        8 => 'Chillan',
+    ],
+];
+private array $groups = [
+    1 => [
+        'label' => 'Russia',
+    ],
+    2 => [
+        'label' => 'Chile',
+    ],
+];
+?>
+
+<?= Select::widget()->groups($this->groups)->items($this->cities)->itemsAttributes([2 => ['disabled' => true]]) ?>
+```
+
+## Add prompt
+
+use the `prompt` method to add a prompt to the `select` element.
+
+For default the `prompt` value is `Select an option`.
+
+```php
+<?php
+
+declare(strict_types=1);
+
+private array $cities = [
+    '1' => 'Moscu',
+    '2' => 'San Petersburgo',
+    '3' => 'Novosibirsk',
+    '4' => 'Ekaterinburgo',
+];
+?>
+
+<?= Select::widget()->items($this->cities)->prompt('Select City Birth') ?>
+```
+
+## Rendering
+
+Generate the `HTML` output using the `render` method.
+
+```php
+$html = $select->render();
+```
+
+Or, use the magic `__toString` method.
+
+```php
+$html = (string) $select;
+```
+
+## Common Use Cases
+
+Below are examples of common use cases:
+
+```php
+// adding multiple attributes
+$select->class('myClass')->required();
+```
+
+```php
+// setting the `multiple` attribute
+$select->multiple();
+```
+
+```php
+// setting the `size` attribute
+$select->size(5);
+```
+
+Explore additional methods for setting various attributes such as `lang`, `multiple`, `size`, `tabindex`, `title`, and
+more.
+
+## Prefix and Suffix
+
+Use `prefix` and `suffix` methods to add text before and after the `select` tag, respectively.
+
+```php
+// adding a prefix
+$html = $select->prefix('myPrefix')->render();
+
+// adding a suffix
+$html = $select->suffix('mySuffix')->render();
+```
+
+## Attributes
+
+Refer to the [Attribute Tests](https://github.com/php-forge/html/blob/main/tests/Select/AttributeTest.php) for
+comprehensive examples.
+
+The following methods are available for setting attributes:
+
+| Method            | Description                                                                                      |
+| ----------------- | ------------------------------------------------------------------------------------------------ |
+| `ariaLabel()`     | Set the `aria-label` attribute.                                                                  |
+| `attributes()`    | Set multiple `attributes` at once.                                                               |
+| `autofocus()`     | Set the `autofocus` attribute.                                                                   |
+| `class()`         | Set the `class` attribute.                                                                       |
+| `disabled()`      | Set the `disabled` attribute.                                                                    |
+| `dataAttributes()`| Set multiple `data-attributes` at once.                                                          |
+| `id()`            | Set the `id` attribute.                                                                          |
+| `name()`          | Set the `name` attribute.                                                                        |
+| `prompt()`        | Set the `prompt` attribute.                                                                      |
+| `required()`      | Set the `required` attribute.                                                                    |
+| `size()`          | Set the `size` attribute.                                                                        |
+| `style()`         | Set the `style` attribute.                                                                       |
+| `tabindex()`      | Set the `tabindex` attribute.                                                                    |
+| `value()`         | Set the `value` attribute.                                                                       |
+
+## Custom methods
+
+Refer to the [Custom Method Test](https://github.com/php-forge/html/blob/main/tests/Select/CustomMethodTest.php) for 
+comprehensive examples.
+
+The following methods are available for customizing the `HTML` output:
+
+| Method                       | Description                                                                           |
+| ---------------------------- | ------------------------------------------------------------------------------------- |
+| `items()`                    | Add `items` to the `select` element.                                                  |
+| `itemsAttributes()`          | Add `attributes` to the `items` element.                                              |
+| `groups()`                   | Add `groups` to the `select` element.                                                 |
+| `labelAttributes()`          | Set `attributes` for the `label` element.                                             |
+| `labelClass()`               | Set the `class` attribute for the `label` element.                                    |
+| `labelContent()`             | Set the `content` for the `label` element.                                            |
+| `labelFor()`                 | Set the `for` attribute for the `label` element.                                      |
+| `notLabel()`                 | Set enabled or disabled for the `label` element.                                      |
+| `prefix()`                   | Add text before the `select` element.                                                 |
+| `prefixContainer()`          | Set enabled or disabled for the `prefix-container` element.                           |
+| `prefixContainerAttributes()`| Set `attributes` for the `prefix-container` element.                                  |                                            
+| `prefixContainerClass()`     | Set the `class` attribute for the `prefix-container` element.                         |
+| `prefixContainerTag()`       | Set the `tag` for the `prefix-container` element.                                     |
+| `render()`                   | Generates the `HTML` output.                                                          |
+| `suffix()`                   | Add text after the `select` element.                                                  |
+| `suffixContainer()`          | Set enabled or disabled for the `suffix-container` element.                           |
+| `suffixContainerAttributes()`| Set `attributes` for the `suffix-container` element.                                  |
+| `suffixContainerClass()`     | Set the `class` attribute for the `suffix-container` element.                         |
+| `suffixContainerTag()`       | Set the `tag` for the `suffix-container` element.                                     |
+| `widget()`                   | Instantiates the `Select::class`.                                                     |

src/Attribute/Tag/HasItemsAttributes.php

@@ -4,8 +4,6 @@
 
 namespace PHPForge\Html\Attribute\Tag;
 
-use PHPForge\Html\Helper\CssClass;
-
 /**
  * Is used by widgets that implement the items attributes methods.
  */
@@ -27,20 +25,4 @@ public function itemsAttributes(array $values = []): static
 
         return $new;
     }
-
-    /**
-     * Set the `CSS` `HTML` class attribute for the items.
-     *
-     * @param string $value The `CSS` attribute for the items.
-     * @param bool $override If `true` the value will be overridden.
-     *
-     * @return static A new instance of the current class with the specified class value for the items.
-     */
-    public function itemsClass(string $value, bool $override = false): static
-    {
-        $new = clone $this;
-        CssClass::add($new->itemsAttributes, $value, $override);
-
-        return $new;
-    }
 }

src/Base/AbstractSelect.php

@@ -31,6 +31,7 @@ abstract class AbstractSelect extends Element implements InputInterface, Require
     use Attribute\Custom\HasPrefixAndSuffix;
     use Attribute\HasClass;
     use Attribute\HasId;
+    use Attribute\HasStyle;
     use Attribute\HasTabindex;
     use Attribute\Input\CanBeDisabled;
     use Attribute\Input\CanBeMultiple;
@@ -54,7 +55,11 @@ protected function run(): string
 
         $items = match ($this->prompt) {
             '' => PHP_EOL . Tag::widget()->content('Select an option')->tagName('option')->render(),
-            default => PHP_EOL . Tag::widget()->content($this->prompt)->tagName('option')->value($this->promptValue)->render(),
+            default => PHP_EOL . Tag::widget()
+                ->content($this->prompt)
+                ->tagName('option')
+                ->value($this->promptValue)
+                ->render(),
         };
 
         if (is_object($value)) {
@@ -80,16 +85,24 @@ protected function run(): string
             ->content($items)
             ->id($this->id)
             ->prefix($this->prefix)
+            ->prefixContainer($this->prefixContainer)
+            ->prefixContainerAttributes($this->prefixContainerAttributes)
+            ->prefixContainerTag($this->prefixContainerTag)
             ->suffix($this->suffix)
+            ->suffixContainer($this->suffixContainer)
+            ->suffixContainerAttributes($this->suffixContainerAttributes)
+            ->suffixContainerTag($this->suffixContainerTag)
             ->tagName('select');
 
-        return match ($this->labelContent) {
-            '' => $selectTag->render(),
-            default => Label::widget()
-                ->attributes($this->labelAttributes)
-                ->content($this->labelContent, PHP_EOL, $selectTag, PHP_EOL)
-                ->render(),
-        };
+        if ($this->notLabel === true || $this->labelContent === '') {
+            return $selectTag->render();
+        }
+
+        return Label::widget()
+            ->attributes($this->labelAttributes)
+            ->content($this->labelContent, PHP_EOL, $selectTag, PHP_EOL)
+            ->for($this->labelFor)
+            ->render();
     }
 
     /**

tests/Attribute/Tag/HasItemsAttributesTest.php

@@ -9,41 +9,12 @@
 
 final class HasItemsAttributesTest extends TestCase
 {
-    public function testClass(): void
-    {
-        $instance = new class () {
-            use HasItemsAttributes;
-
-            protected array $attributes = [];
-
-            public function getItemsClass(): string
-            {
-                return $this->itemsAttributes['class'] ?? '';
-            }
-        };
-
-        $this->assertEmpty($instance->getItemsClass());
-
-        $instance = $instance->itemsClass('test-class');
-
-        $this->assertSame('test-class', $instance->getItemsClass());
-
-        $instance = $instance->itemsClass('test-class-1');
-
-        $this->assertSame('test-class test-class-1', $instance->getItemsClass());
-
-        $instance = $instance->itemsClass('test-override-class', true);
-
-        $this->assertSame('test-override-class', $instance->getItemsClass());
-    }
-
     public function testImmutability(): void
     {
         $instance = new class () {
             use HasItemsAttributes;
         };
 
         $this->assertNotSame($instance, $instance->itemsAttributes([]));
-        $this->assertNotSame($instance, $instance->itemsClass(''));
     }
 }