From 18c16611fbdf70f8bc61335863918ddd0c2fafcd Mon Sep 17 00:00:00 2001
From: Wilmer Arambula <terabytesoftw@gmail.com>
Date: Wed, 6 Mar 2024 12:55:14 -0300
Subject: [PATCH] Add helper `HTMLBuilder::class`.

---
 CHANGELOG.md                       |   1 +
 README.md                          |  46 +++++++
 src/Base/AbstractHTMLBuilder.php   | 203 +++++++++++++++++++++++++++++
 src/HTMLBuilder.php                |  12 ++
 tests/HTMLBuilderExceptionTest.php |  34 +++++
 tests/HTMLBuilderTest.php          |  35 +++++
 tests/Provider/TagProvider.php     |  42 ++++++
 7 files changed, 373 insertions(+)
 create mode 100644 src/Base/AbstractHTMLBuilder.php
 create mode 100644 src/HTMLBuilder.php
 create mode 100644 tests/HTMLBuilderExceptionTest.php
 create mode 100644 tests/HTMLBuilderTest.php
 create mode 100644 tests/Provider/TagProvider.php

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 89728d3..f7e653b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,3 +7,4 @@
 - Initial release
 - Enh #2: Add helper `Template::class` (@terabytesoftw)
 - Bug #3: Fix `README.md` (@terabytesoftw)
+- Enh #4: Add helper `HTMLBuilder::class` (@terabytesoftw)
diff --git a/README.md b/README.md
index 46cac3e..9b6ce5a 100644
--- a/README.md
+++ b/README.md
@@ -87,6 +87,52 @@ private array $attributes = ['class' => 'btn'];
 $classes = CssClasses::add($this->attributes, ['btn-primary', 'btn-lg'], true);
 ```
 
+### Create a new `HTML` element
+
+To create a new `HTML` element, you can use the `HTMLBuilder::class` with the `createTag()` 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 UIAwesome\Html\Helper\HTMLBuilder;
+?>
+
+<?= HTMLBuilder::createTag('div', 'Hello, World!', ['class' => 'container']) ?>
+```
+
+### Create a new `HTML` block element
+
+To create a new `HTML` block element, you can use the `HTMLBuilder::class` with the `beginTag()` and `endTag()` methods.
+
+Allowed arguments for `beginTag()` method are:
+
+- `tag` (string) - The tag name.
+- `attributes` (array) - The attributes of the tag.
+
+Allowed arguments for `endTag()` method are:
+
+- `tag` (string) - The tag name.
+
+```php
+<?php
+
+declare(strict_types=1);
+
+use UIAwesome\Html\Helper\HTMLBuilder;
+
+<?= HTMLBuilder::beginTag('div', ['class' => 'container']) ?>
+    Hello, World!
+<?= HTMLBuilder::endTag('div') ?>
+```
+
 ### Convert regular expression to pattern
 
 The `Utils::class` helper can be used to normalize a regular expression.
diff --git a/src/Base/AbstractHTMLBuilder.php b/src/Base/AbstractHTMLBuilder.php
new file mode 100644
index 0000000..056416c
--- /dev/null
+++ b/src/Base/AbstractHTMLBuilder.php
@@ -0,0 +1,203 @@
+<?php
+
+declare(strict_types=1);
+
+namespace UIAwesome\Html\Helper\Base;
+
+use UIAwesome\Html\Helper\Attributes;
+
+use function in_array;
+use function strtolower;
+
+/**
+ * Provides common functionality for generate HTML code fragments programmatically.
+ *
+ * Concrete classes should extend this class to implement specific HTML elements and their generation logic.
+ */
+abstract class AbstractHTMLBuilder
+{
+    /**
+     * @psalm-var string[]
+     */
+    private const INLINE_ELEMENTS = [
+        'a',
+        'abbr',
+        'acronym',
+        'audio',
+        'b',
+        'bdi',
+        'bdo',
+        'big',
+        'br',
+        'button',
+        'canvas',
+        'cite',
+        'code',
+        'data',
+        'datalist',
+        'del',
+        'dfn',
+        'em',
+        'embed',
+        'i',
+        'iframe',
+        'img',
+        'input',
+        'ins',
+        'kbd',
+        'label',
+        'map',
+        'mark',
+        'meter',
+        'noscript',
+        'object',
+        'option',
+        'output',
+        'picture',
+        'progress',
+        'q',
+        'ruby',
+        's',
+        'samp',
+        'script',
+        'select',
+        'slot',
+        'small',
+        'span',
+        'strong',
+        'sub',
+        'sup',
+        'svg',
+        'template',
+        'textarea',
+        'time',
+        'u',
+        'td',
+        'th',
+        'tt',
+        'var',
+        'video',
+        'wbr',
+    ];
+
+    /**
+     * @psalm-var string[]
+     */
+    private const VOID_ELEMENT = [
+        'area',
+        'base',
+        'br',
+        'col',
+        'command',
+        'embed',
+        'hr',
+        'img',
+        'input',
+        'keygen',
+        'link',
+        'meta',
+        'param',
+        'source',
+        'track',
+        'wbr',
+    ];
+
+    /**
+     * This method creates a new HTML begin tag with the specified tag name and attributes.
+     *
+     * @param string $tag The tag name.
+     * @param array $attributes The tag attributes.
+     *
+     * @return string The begin tag.
+     */
+    public static function beginTag(string $tag, array $attributes = []): string
+    {
+        $helperAttributes = new Attributes();
+        $tag = self::validateTag($tag);
+
+        if (self::inlinedElements($tag)) {
+            throw new \InvalidArgumentException('Inline elements cannot be used with begin/end syntax.');
+        }
+
+        return '<' . $tag . $helperAttributes->render($attributes) . '>';
+    }
+
+    /**
+     * This method creates a new HTML tag with the specified tag name, content, and attributes.
+     *
+     * @param string $tag The tag name.
+     * @param string $content The content of the tag.
+     * @param array $attributes The attributes of the tag.
+     *
+     * @return string The tag.
+     */
+    public static function createTag(string $tag, string $content = '', array $attributes = []): string
+    {
+        $tag = self::validateTag($tag);
+        $voidElement = "<$tag" . Attributes::render($attributes) . '>';
+
+        if (self::voidElements($tag)) {
+            return $voidElement;
+        }
+
+        if (self::inlinedElements($tag)) {
+            return "$voidElement$content</$tag>";
+        }
+
+        $content = $content === '' ? '' : $content . PHP_EOL;
+
+        return "$voidElement\n$content</$tag>";
+    }
+
+    /**
+     * This method creates a new HTML end tag with the specified tag name.
+     *
+     * @param string $tag The tag name.
+     *
+     * @return string The closing tag.
+     */
+    public static function endTag(string $tag): string
+    {
+        if (self::inlinedElements($tag)) {
+            throw new \InvalidArgumentException('Inline elements cannot be used with begin/end syntax.');
+        }
+
+        $tag = self::validateTag($tag);
+
+        return "</$tag>";
+    }
+
+    /**
+     * @return bool True if tag is inlined element.
+     *
+     * @link https://developer.mozilla.org/en-US/docs/Web/HTML/Inline_elements
+     */
+    private static function inlinedElements(string $tag): bool
+    {
+        return in_array($tag, self::INLINE_ELEMENTS, true);
+    }
+
+    /**
+     * @return bool True if tag is void element.
+     *
+     * @link http://www.w3.org/TR/html-markup/syntax.html#void-element
+     */
+    private static function voidElements(string $tag): bool
+    {
+        return in_array($tag, self::VOID_ELEMENT, true);
+    }
+
+    /**
+     * @throws \InvalidArgumentException
+     */
+    private static function validateTag(string $tag): string
+    {
+        $tag = strtolower($tag);
+
+        if ($tag === '') {
+            throw new \InvalidArgumentException('Tag name cannot be empty.');
+        }
+
+        return $tag;
+    }
+}
diff --git a/src/HTMLBuilder.php b/src/HTMLBuilder.php
new file mode 100644
index 0000000..7a45f90
--- /dev/null
+++ b/src/HTMLBuilder.php
@@ -0,0 +1,12 @@
+<?php
+
+declare(strict_types=1);
+
+namespace UIAwesome\Html\Helper;
+
+/**
+ * This class provides methods to generate `HTML` code fragments programmatically.
+ *
+ * @link https://developer.mozilla.org/en-US/docs/Glossary/Element
+ */
+final class HTMLBuilder extends Base\AbstractHTMLBuilder {}
diff --git a/tests/HTMLBuilderExceptionTest.php b/tests/HTMLBuilderExceptionTest.php
new file mode 100644
index 0000000..0ddfd94
--- /dev/null
+++ b/tests/HTMLBuilderExceptionTest.php
@@ -0,0 +1,34 @@
+<?php
+
+declare(strict_types=1);
+
+namespace UIAwesome\Html\Tests\Helper;
+
+use UIAwesome\Html\Helper\HTMLBuilder;
+
+final class HTMLBuilderExceptionTest extends \PHPUnit\Framework\TestCase
+{
+    public function testBeginInlineElement(): void
+    {
+        $this->expectException(\InvalidArgumentException::class);
+        $this->expectExceptionMessage('Inline elements cannot be used with begin/end syntax.');
+
+        HTMLBuilder::beginTag('br');
+    }
+
+    public function testEndInlineElement(): void
+    {
+        $this->expectException(\InvalidArgumentException::class);
+        $this->expectExceptionMessage('Inline elements cannot be used with begin/end syntax.');
+
+        HTMLBuilder::endTag('br');
+    }
+
+    public function testTagEmpty(): void
+    {
+        $this->expectException(\InvalidArgumentException::class);
+        $this->expectExceptionMessage('Tag name cannot be empty.');
+
+        HTMLBuilder::createTag('');
+    }
+}
diff --git a/tests/HTMLBuilderTest.php b/tests/HTMLBuilderTest.php
new file mode 100644
index 0000000..c82c647
--- /dev/null
+++ b/tests/HTMLBuilderTest.php
@@ -0,0 +1,35 @@
+<?php
+
+declare(strict_types=1);
+
+namespace UIAwesome\Html\Tests;
+
+use PHPForge\Support\Assert;
+use UIAwesome\Html\Helper\HTMLBuilder;
+
+final class HTMLBuilderTest extends \PHPUnit\Framework\TestCase
+{
+    public function testBegin(): void
+    {
+        $this->assertSame('<div>', HTMLBuilder::beginTag('div'));
+        $this->assertSame('<div class="class">', HTMLBuilder::beginTag('div', ['class' => 'class']));
+    }
+
+    /**
+     * @dataProvider UIAwesome\Html\Helper\Tests\Provider\TagProvider::create
+     *
+     * @param string $tagName Tag name.
+     * @param string $content Tag content.
+     * @param array $attributes Tag attributes.
+     * @param string $expected Expected result.
+     */
+    public function testCreate(string $tagName, string $content, array $attributes, string $expected): void
+    {
+        Assert::equalsWithoutLE($expected, HTMLBuilder::createTag($tagName, $content, $attributes));
+    }
+
+    public function testEnd(): void
+    {
+        $this->assertSame('</div>', HTMLBuilder::endTag('div'));
+    }
+}
diff --git a/tests/Provider/TagProvider.php b/tests/Provider/TagProvider.php
new file mode 100644
index 0000000..0a7f440
--- /dev/null
+++ b/tests/Provider/TagProvider.php
@@ -0,0 +1,42 @@
+<?php
+
+declare(strict_types=1);
+
+namespace UIAwesome\Html\Helper\Tests\Provider;
+
+final class TagProvider
+{
+    public static function create(): array
+    {
+        return [
+            [
+                'article',
+                '',
+                [
+                    'id' => 'id-1',
+                    'class' => 'class',
+                ],
+                '<article class="class" id="id-1">' . PHP_EOL . '</article>',
+            ],
+            ['br', '', [], '<br>'],
+            ['BR', '', [], '<br>'],
+            ['hr', '', [], '<hr>'],
+            ['HR', '', [], '<hr>'],
+            ['div', 'Content', [], '<div>' . PHP_EOL . 'Content' . PHP_EOL . '</div>'],
+            [
+                'input',
+                '',
+                [
+                    'type' => 'text',
+                    'name' => 'test',
+                    'value' => '<>',
+                ],
+                '<input name="test" type="text" value="&lt;&gt;">',
+            ],
+            ['span', '', [], '<span></span>'],
+            ['span', '', [
+                'disabled' => true,
+            ], '<span disabled></span>'],
+        ];
+    }
+}