Add doc H::class. (#268)

docs/README.md

@@ -17,6 +17,7 @@ The following tags are currently supported:
 - [div](/docs/tag/Div.md)
 - [footer](/docs/tag/Footer.md)
 - [form](/docs/tag/Form.md)
+- [h](/docs/tag/H.md)
 
 ## Input Tags
 

docs/tag/H.md

@@ -0,0 +1,124 @@
+# H
+
+The `<h1>` to `<h6>` `HTML` elements represent six levels of section headings.
+
+`<h1>` is the highest section level and `<h6>` is the lowest.
+
+## Basic Usage
+
+Instantiate the `H` class using `H::widget()`.
+
+```php
+$h = H::widget();
+```
+
+Or, block style instantiation.
+
+```php
+<?= H::begin() ?>
+    // ... content to be wrapped by `h` element
+<?= H::end() ?>
+```
+
+## Setting Attributes
+
+Use the provided methods to set specific attributes for the a element.
+
+```php
+// setting href attribute
+$h->class('container');
+```
+
+Or, use the `attributes` method to set multiple attributes at once.
+
+```php
+$h->attributes(['class' => 'container', 'style' => 'background-color: #eee;']);
+```
+
+## Adding Content
+
+If you want to include content within the `h` tag, use the `content` method.
+
+```php
+$h->content('My content');
+```
+
+Or, use `begin()` and `end()` methods to wrap content.
+
+```php
+<?= H::begin() ?>
+    My content
+<?= H::end() ?>
+```
+
+## Rendering
+
+Generate the `HTML` output using the `render` method, for simple instantiation. 
+
+```php
+$html = $h->render();
+```
+
+For block style instantiation, use the `end()` method, which returns the `HTML` output.
+
+```php
+$html = H::end();
+```
+
+Or, use the magic `__toString` method.
+
+```php
+$html = (string) $h;
+```
+
+## Common Use Cases
+
+Below are examples of common use cases:
+
+```php
+// adding multiple attributes
+$h->class('external')->content('My content');
+
+// using data attributes
+$h->dataAttributes(['analytics' => 'trackClick']);
+
+// specifying the tag name h2
+H::widget()->tagName('h2')->content('value')->render()
+```
+
+Explore additional methods for setting various attributes such as `lang`, `name`, `style`, `title`, etc.
+
+## Attributes
+
+Refer to the [Attribute Tests](https://github.com/php-forge/html/blob/main/tests/H/AttributeTest.php) for comprehensive
+examples.
+
+The following methods are available for setting attributes:
+
+| Method            | Description                                                                                      |
+| ----------------- | ------------------------------------------------------------------------------------------------ |
+| `attributes()`    | Set multiple `attributes` at once.                                                               |
+| `class()`         | Set the `class` attribute.                                                                       |
+| `content()`       | Set the `content` within the `h` element.                                                        |
+| `dataAttributes()`| Set multiple `data-attributes` at once.                                                          |
+| `id()`            | Set the `id` attribute.                                                                          |
+| `lang()`          | Set the `lang` attribute.                                                                        |
+| `name()`          | Set the `name` attribute.                                                                        |
+| `style()`         | Set the `style` attribute.                                                                       |
+| `title()`         | Set the `title` attribute.                                                                       |
+
+## Custom methods
+
+Refer to the [Custom Methods Tests](https://github.com/php-forge/html/blob/main/tests/H/CustomMethodTest.php) for
+comprehensive examples.
+
+The following methods are available for customizing the `HTML` output:
+
+| Method     | Description                                                                                              |
+| ---------- | -------------------------------------------------------------------------------------------------------- |
+| `begin()  `| Start the `h` element.                                                                                   |
+| `end()`    | End the `h` element, and generate the `HTML` output.                                                     |
+| `tagName()`| Set the `tag` name.                                                                                      |
+|            | Alowed values: `h1`, `h2`, `h3`, `h4`, `h5`, `h6`. For default value its `h1`.                           |
+| `render()` | Generates the `HTML` output.                                                                             |
+| `widget()` | Instantiates the `Body::class`.                                                                          |

src/H.php

@@ -4,10 +4,6 @@
 
 namespace PHPForge\Html;
 
-use InvalidArgumentException;
-
-use function in_array;
-
 /**
  * The `<h1>` to `<h6>` HTML elements represent six levels of section headings.
  * `<h1>` is the highest section level and `<h6>` is the lowest.
@@ -17,14 +13,13 @@
 final class H extends Base\AbstractBlockElement
 {
     use Attribute\Custom\HasTagName;
+    use Attribute\Custom\HasWidgetValidation;
 
     protected string $tagName = 'h1';
 
     protected function run(): string
     {
-        if (in_array($this->tagName, ['h1', 'h2', 'h3', 'h4', 'h5', 'h6'], true) === false) {
-            throw new InvalidArgumentException('Invalid tag name, only h1 to h6 are allowed.');
-        }
+        $this->validateTagName($this->tagName, 'h1', 'h2', 'h3', 'h4', 'h5', 'h6');
 
         return parent::run();
     }

tests/H/RenderTest.php → tests/H/AttributeTest.php

@@ -11,113 +11,105 @@
 /**
  * @psalm-suppress PropertyNotSetInConstructor
  */
-final class RenderTest extends TestCase
+final class AttributeTest extends TestCase
 {
     public function testAttributes(): void
     {
         Assert::equalsWithoutLE(
             <<<HTML
-            <h1 class="test-class">
+            <h1 class="value">
             </h1>
             HTML,
-            H::widget()->attributes([
-                'class' => 'test-class',
-            ])->render(),
+            H::widget()->attributes(['class' => 'value'])->render(),
         );
     }
 
     public function testClass(): void
     {
         Assert::equalsWithoutLE(
             <<<HTML
-            <h1 class="test-class">
+            <h1 class="value">
             </h1>
             HTML,
-            H::widget()->class('test-class')->render(),
+            H::widget()->class('value')->render(),
         );
     }
 
-    public function testBlockLevelElements(): void
-    {
-        $this->assertSame('<h1>test block</h1>', H::widget()->begin() . 'test block' . H::end());
-    }
-
-    public function testElement(): void
+    public function testContent(): void
     {
         Assert::equalsWithoutLE(
             <<<HTML
             <h1>
-            test element
+            value
             </h1>
             HTML,
-            H::widget()->content('test element')->render(),
+            H::widget()->content('value')->render(),
         );
     }
 
-    public function testId(): void
+    public function testDataAttributes(): void
     {
         Assert::equalsWithoutLE(
             <<<HTML
-            <h1 id="test-id">
+            <h1 data-value="value">
             </h1>
             HTML,
-            H::widget()->id('test-id')->render(),
+            H::widget()->dataAttributes(['value' => 'value'])->render(),
         );
     }
 
-    public function testLang(): void
+    public function testId(): void
     {
         Assert::equalsWithoutLE(
             <<<HTML
-            <h1 lang="en">
+            <h1 id="value">
             </h1>
             HTML,
-            H::widget()->lang('en')->render(),
+            H::widget()->id('value')->render(),
         );
     }
 
-    public function testName(): void
+    public function testLang(): void
     {
         Assert::equalsWithoutLE(
             <<<HTML
-            <h1 name="test-name">
+            <h1 lang="value">
             </h1>
             HTML,
-            H::widget()->name('test-name')->render(),
+            H::widget()->lang('value')->render(),
         );
     }
 
-    public function testStyle(): void
+    public function testName(): void
     {
         Assert::equalsWithoutLE(
             <<<HTML
-            <h1 style="color: red;">
+            <h1 name="value">
             </h1>
             HTML,
-            H::widget()->style('color: red;')->render(),
+            H::widget()->name('value')->render(),
         );
     }
 
-    public function testTagName(): void
+    public function testStyle(): void
     {
         Assert::equalsWithoutLE(
             <<<HTML
-            <h2>
-            test tag name
-            </h2>
+            <h1 style="value">
+            </h1>
             HTML,
-            H::widget()->tagName('h2')->content('test tag name')->render(),
+            H::widget()->style('value')->render(),
         );
     }
 
     public function testTitle(): void
     {
         Assert::equalsWithoutLE(
             <<<HTML
-            <h1 title="test-title">
+            <h1 title="value">
             </h1>
             HTML,
-            H::widget()->title('test-title')->render(),
+            H::widget()->title('value')->render(),
         );
     }
 

tests/H/CustomMethodTest.php

@@ -0,0 +1,43 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PHPForge\Html\Tests\H;
+
+use PHPForge\Html\H;
+use PHPForge\Support\Assert;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * @psalm-suppress PropertyNotSetInConstructor
+ */
+final class CustomMethodTest extends TestCase
+{
+    public function testBeginEnd(): void
+    {
+        $this->assertSame('<h1>value</h1>', H::widget()->begin() . 'value' . H::end());
+    }
+
+    public function testRender(): void
+    {
+        Assert::equalsWithoutLE(
+            <<<HTML
+            <h1>
+            </h1>
+            HTML,
+            H::widget()->render(),
+        );
+    }
+
+    public function testTagName(): void
+    {
+        Assert::equalsWithoutLE(
+            <<<HTML
+            <h2>
+            value
+            </h2>
+            HTML,
+            H::widget()->tagName('h2')->content('value')->render(),
+        );
+    }
+}

tests/H/ExceptionTest.php

@@ -13,7 +13,7 @@ final class ExceptionTest extends TestCase
     public function testBeginInlineElement(): void
     {
         $this->expectException(InvalidArgumentException::class);
-        $this->expectExceptionMessage('Invalid tag name, only h1 to h6 are allowed.');
+        $this->expectExceptionMessage('H::class widget must have a tag name of h1, h2, h3, h4, h5, h6.');
 
         H::widget()->tagName('span')->render();
     }