Add docs Tag::class. (#285)

docs/README.md

@@ -40,33 +40,20 @@ In addition to basic `HTML` tags, the repository also supports the generation of
 
 This is particularly useful for creating forms and other interactive elements on a webpage.
 
-## Creating Custom Widgets
+## Creating Widgets
 
-One of the standout features of the `HTML` repository is its utilization of `PHP` traits.
+The HTML repository leverages the power of PHP traits to enable you to create custom widgets with ease.
 
-Traits serve as a mechanism for code reuse in single inheritance languages like `PHP`, enabling the grouping of specific
-functionalities in a coherent manner.
+Traits are a way of reusing code in single inheritance languages like PHP, allowing you to group related functionalities
+in a consistent way.
 
-The `HTML` repository provides traits that can be employed to assemble custom widgets, offering the flexibility to
-create `HTML` elements tailored to specific needs.
+The HTML repository provides a set of traits that you can use to compose custom widgets, giving you the flexibility to
+create HTML elements that suit your specific needs.
 
-To use the repository, you would typically import the necessary classes and traits into your `PHP` script.
+## Helper Classes
 
-Subsequently, you would invoke the appropriate methods to generate `HTML` code. The generated code can then be sent to
-the browser or used in other parts of your application.
+- [HtmlBuilder](/docs/helper/HtmlBuilder.md)
 
-It's important to note that the exact usage may vary depending on the specific classes and traits you are utilizing.
+## Generic tags
 
-Be sure to review the tests and traits in the repository for more detailed examples and usage instructions.
-
-Furthermore, the repository supplies various abstract classes that can be utilized to craft custom widgets.
-
-These classes provide a fundamental implementation of the `HTML` interface and can be extended to develop more
-intricate widgets.
-
-Additionally, the repository furnishes several interfaces that can be used to create personalized widgets.
-
-These interfaces offer a basic implementation of the `HTML` interface and can be extended to construct more complex
-widgets.
-
-This enhances the extensibility of the repository, empowering you to design personalized `HTML` elements efficiently.
+- [Tag](/docs/tag/Tag.md)

docs/helper/HtmlBuilder.md

@@ -0,0 +1,52 @@
+# HtmlBuilder helper
+
+The repository also provides a helper class called `HtmlBuilder` that you can use to generate `HTML` code.
+
+The `HtmlBuilder` class provides a wide range of methods for creating `HTML` elements, making it easy to generate
+`HTML` code programmatically using `PHP`.
+
+
+## Creating a new HTML element
+
+To create a new `HTML` element, you can use the `HtmlBuilder` with the `create` method.
+
+Allowed arguments are:
+
+- `tag` (string) - The tag name.
+- `content` (string) - The content of the tag.
+- `attributes` (array) - The attributes of the tag.
+
+```php
+<?php
+
+declare(strict_types=1);
+
+use Html\HtmlBuilder;
+?>
+
+<?= HtmlBuilder::create('div', 'Hello, World!', ['class' => 'container']) ?>
+```
+
+Or you can use the `HtmlBuilder` with the `begin` and `end` methods.
+
+Allowed arguments for `begin` method are:
+
+- `tag` (string) - The tag name.
+- `attributes` (array) - The attributes of the tag.
+
+Allowed arguments for `end` method are:
+
+- `tag` (string) - The tag name.
+
+```php
+<?php
+
+declare(strict_types=1);
+
+use Html\HtmlBuilder;
+?>
+
+<?= HtmlBuilder::begin('div', ['class' => 'container']) ?>
+    Hello, World!
+<?= HtmlBuilder::end('div') ?>
+```

docs/tag/Tag.md

@@ -0,0 +1,104 @@
+# Tag
+
+The `<tag>` `HTML` element represents a generic tag.
+
+You must specify the tag name in the setter `tagName()`.
+
+## Basic Usage
+
+Instantiate the `Tag` class using `Tag::widget()`.
+
+```php
+$tag = Tag::widget()->tagName('div');
+```
+
+> Note: The `Tag` class is a generic class that can be used to create any `HTML` tag. You must specify the tag name
+using the `tagName()` method.
+
+## Setting Attributes
+
+Use the provided methods to set specific attributes for the a element.
+
+```php
+// setting class attribute
+$tag->class('container');
+```
+
+Or, use the `attributes` method to set multiple attributes at once.
+
+```php
+$tag->attributes(['class' => 'container', 'style' => 'background-color: #eee;']);
+```
+
+## Adding Content
+
+If you want to include content within the `div` tag, use the `content` method.
+
+```php
+$tag->content('My content');
+```
+
+## Rendering
+
+Generate the `HTML` output using the `render` method, for simple instantiation. 
+
+```php
+$html = $tag->render();
+```
+
+Or, use the magic `__toString` method.
+
+```php
+$html = (string) $tag;
+```
+
+## Common Use Cases
+
+Below are examples of common use cases:
+
+```php
+// adding multiple attributes
+$tag->class('external')->content('My content');
+
+// using data attributes
+$tag->dataAttributes(['analytics' => 'trackClick']);
+```
+
+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/Tag/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 `div` 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.                                                                       |
+| `tabIndex()`      | Set the `tabindex` attribute.                                                                    |
+| `title()`         | Set the `title` attribute.                                                                       |
+| `type()`          | Set the `type` attribute.                                                                        |
+| `value()`         | Set the `value` attribute.                                                                       |
+
+## Custom methods
+
+Refer to the [Custom Methods Tests](https://github.com/php-forge/html/blob/main/tests/Tag/CustomMethodTest.php) for
+comprehensive examples.
+
+The following methods are available for customizing the `HTML` output:
+
+| Method         | Description                                                                                         |
+| -------------- | --------------------------------------------------------------------------------------------------- |
+| `render()`     | Generates the `HTML` output.                                                                        |
+| `tagName()`    | Set the tag name for the `HTML` output.                                                             |
+| `template()`   | Set the template for the `HTML` output.                                                             |
+| `tokenValues()`| Set the token values for the `HTML` output.                                                         |
+| `widget()`     | Instantiates the `Body::class`.                                                                     |

tests/Tag/AttributeTest.php

@@ -0,0 +1,135 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PHPForge\Html\Tests\Tag;
+
+use PHPForge\Html\Tag;
+use PHPForge\Support\Assert;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * @psalm-suppress PropertyNotSetInConstructor
+ */
+final class AttributeTest extends TestCase
+{
+    public function testAttributes(): void
+    {
+        Assert::equalsWithoutLE(
+            <<<HTML
+            <span id="value"></span>
+            HTML,
+            Tag::widget()->attributes(['id' => 'value'])->tagName('span')->render()
+        );
+    }
+
+    public function testClass(): void
+    {
+        Assert::equalsWithoutLE(
+            <<<HTML
+            <span class="value"></span>
+            HTML,
+            Tag::widget()->class('value')->tagName('span')->render()
+        );
+    }
+
+    public function testContent(): void
+    {
+        Assert::equalsWithoutLE(
+            <<<HTML
+            <span>content</span>
+            HTML,
+            Tag::widget()->content('content')->tagName('span')->render()
+        );
+    }
+
+    public function testDataAttributes(): void
+    {
+        Assert::equalsWithoutLE(
+            <<<HTML
+            <span data-value="value"></span>
+            HTML,
+            Tag::widget()->dataAttributes(['value' => 'value'])->tagName('span')->render()
+        );
+    }
+
+    public function testId(): void
+    {
+        Assert::equalsWithoutLE(
+            <<<HTML
+            <span id="value"></span>
+            HTML,
+            Tag::widget()->id('value')->tagName('span')->render()
+        );
+    }
+
+    public function testLang(): void
+    {
+        Assert::equalsWithoutLE(
+            <<<HTML
+            <span lang="value"></span>
+            HTML,
+            Tag::widget()->lang('value')->tagName('span')->render()
+        );
+    }
+
+    public function testName(): void
+    {
+        Assert::equalsWithoutLE(
+            <<<HTML
+            <span name="value"></span>
+            HTML,
+            Tag::widget()->name('value')->tagName('span')->render()
+        );
+    }
+
+    public function testStyle(): void
+    {
+        Assert::equalsWithoutLE(
+            <<<HTML
+            <span style="value"></span>
+            HTML,
+            Tag::widget()->style('value')->tagName('span')->render()
+        );
+    }
+
+    public function testTabindex(): void
+    {
+        Assert::equalsWithoutLE(
+            <<<HTML
+            <span tabindex="1"></span>
+            HTML,
+            Tag::widget()->tabindex(1)->tagName('span')->render()
+        );
+    }
+
+    public function testTitle(): void
+    {
+        Assert::equalsWithoutLE(
+            <<<HTML
+            <span title="value"></span>
+            HTML,
+            Tag::widget()->title('value')->tagName('span')->render()
+        );
+    }
+
+    public function testType(): void
+    {
+        Assert::equalsWithoutLE(
+            <<<HTML
+            <button type="button"></button>
+            HTML,
+            Tag::widget()->tagName('button')->type('button')->render()
+        );
+    }
+
+    public function testValue(): void
+    {
+        Assert::equalsWithoutLE(
+            <<<HTML
+            <input value="value">
+            HTML,
+            Tag::widget()->tagName('input')->value('value')->render()
+        );
+    }
+}