Add docs Section::class. (#281)

docs/README.md

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

docs/tag/Section.md

@@ -0,0 +1,118 @@
+# Section
+
+The `<section>` `HTML` element represents a generic standalone section of a document, which doesn't have a more specific
+semantic element to represent it. Sections should always have a heading, with very few exceptions.
+
+## Basic Usage
+
+Instantiate the `Section` class using `Section::widget()`.
+
+```php
+$section = Section::widget();
+```
+
+Or, block style instantiation.
+
+```php
+<?= Section::begin() ?>
+    // ... content to be wrapped by `section` element
+<?= Section::end() ?>
+```
+
+## Setting Attributes
+
+Use the provided methods to set specific attributes for the a element.
+
+```php
+// setting class attribute
+$section->class('container');
+```
+
+Or, use the `attributes` method to set multiple attributes at once.
+
+```php
+$section->attributes(['class' => 'container', 'style' => 'background-color: #eee;']);
+```
+
+## Adding Content
+
+If you want to include content within the `section` tag, use the `content` method.
+
+```php
+$section->content('My content');
+```
+
+Or, use `begin()` and `end()` methods to wrap content.
+
+```php
+<?= Section::begin() ?>
+    My content
+<?= Section::end() ?>
+```
+
+## Rendering
+
+Generate the `HTML` output using the `render` method, for simple instantiation. 
+
+```php
+$html = $section->render();
+```
+
+For block style instantiation, use the `end()` method, which returns the `HTML` output.
+
+```php
+$html = Section::end();
+```
+
+Or, use the magic `__toString` method.
+
+```php
+$html = (string) $section;
+```
+
+## Common Use Cases
+
+Below are examples of common use cases:
+
+```php
+// adding multiple attributes
+$section->class('external')->content('My content');
+
+// using data attributes
+$section->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/Section/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 `section` 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/Section/CustomMethodTest.php) for
+comprehensive examples.
+
+The following methods are available for customizing the `HTML` output:
+
+| Method    | Description                                                                                              |
+| --------- | -------------------------------------------------------------------------------------------------------- |
+| `begin() `| Start the `section` element.                                                                             |
+| `end()`   | End the `section` element, and generate the `HTML` output.                                               |
+| `render()`| Generates the `HTML` output.                                                                             |
+| `widget()`| Instantiates the `Body::class`.                                                                          |

tests/Section/AttributeTest.php

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

tests/Section/RenderTest.php → tests/Section/CustomMethodTest.php

@@ -11,22 +11,26 @@
 /**
  * @psalm-suppress PropertyNotSetInConstructor
  */
-final class RenderTest extends TestCase
+final class CustomMethodTest extends TestCase
 {
-    public function testBlockLevelElements(): void
+    public function testBeginEnd(): void
     {
-        $this->assertSame('<section>test block</section>', Section::widget()->begin() . 'test block' . Section::end());
+        Assert::equalsWithoutLE(
+            <<<HTML
+            <section>value</section>
+            HTML,
+            Section::widget()->begin() . 'value' . Section::end()
+        );
     }
 
-    public function testElement(): void
+    public function testRender(): void
     {
         Assert::equalsWithoutLE(
             <<<HTML
             <section>
-            test element
             </section>
             HTML,
-            Section::widget()->content('test element')->render(),
+            Section::widget()->render(),
         );
     }
 }