From 2a1e2f90728b9508923080a5c337e6dc16073e1e Mon Sep 17 00:00:00 2001
From: Wilmer Arambula <42547589+terabytesoftw@users.noreply.github.com>
Date: Tue, 6 Feb 2024 11:32:36 -0300
Subject: [PATCH] Add docs `Img::class`. (#274)

---
 docs/README.md                 |   1 +
 docs/tag/Img.md                | 141 +++++++++++++++++++++++++
 src/A.php                      |   3 +-
 src/Base/AbstractElement.php   |   6 +-
 src/I.php                      |   4 +-
 src/Label.php                  |   3 +-
 src/Span.php                   |   4 +-
 src/Tag.php                    |   3 +-
 src/TextArea.php               |   3 +-
 tests/Img/AttributeTest.php    | 185 +++++++++++++++++++++++++++++++++
 tests/Img/CustomMethodTest.php | 167 +++++++++++++++++++++++++++++
 tests/Img/RenderTest.php       |  19 ----
 12 files changed, 511 insertions(+), 28 deletions(-)
 create mode 100644 docs/tag/Img.md
 create mode 100644 tests/Img/AttributeTest.php
 create mode 100644 tests/Img/CustomMethodTest.php
 delete mode 100644 tests/Img/RenderTest.php

diff --git a/docs/README.md b/docs/README.md
index 16dd8ca1..eb2ed70c 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -22,6 +22,7 @@ The following tags are currently supported:
 - [header](/docs/tag/Header.md)
 - [html](/docs/tag/Html.md)
 - [i](/docs/tag/I.md)
+- [img](/docs/tag/Img.md)
 
 ## Input Tags
 
diff --git a/docs/tag/Img.md b/docs/tag/Img.md
new file mode 100644
index 00000000..bf4861ac
--- /dev/null
+++ b/docs/tag/Img.md
@@ -0,0 +1,141 @@
+# Img
+
+The `<img>` `HTML` element embeds an image into the document.
+
+## Basic Usage
+
+Instantiate the `Img` class using `Img::widget()`.
+
+```php
+$img = Img::widget();
+```
+
+## Setting Attributes
+
+Use the provided methods to set specific attributes for the a element.
+
+```php
+// setting class attribute
+$img->class('external');
+```
+
+Or, use the `attributes` method to set multiple attributes at once.
+
+```php
+$img->attributes(['class' => 'external', 'title' => 'External Link']);
+```
+
+## Adding source
+
+If you want to include an image, use the `src` method.
+
+```php
+$img->src('https://example.com/image.jpg');
+```
+
+## Rendering
+
+Generate the `HTML` output using the `render` method.
+
+```php
+$html = $img->render();
+```
+
+Or, use the magic `__toString` method.
+
+```php
+$html = (string) $img;
+```
+
+## Common Use Cases
+
+Below are examples of common use cases:
+
+```php
+// adding multiple attributes
+$img->class('external')->title('External Link');
+
+// using data attributes
+$img->dataAttributes(['bs-toggle' => 'modal', 'bs-target' => '#exampleModal', 'analytics' => 'trackClick']);
+```
+
+Explore additional methods for setting various attributes such as `crossorigin`, `ismap`, `lang`, `loading`, `tabindex`,
+`title`, and more.
+
+## Prefix and Suffix
+
+Use `prefix` and `suffix` methods to add text before and after the `img` tag, respectively.
+
+```php
+// adding a prefix
+$html = $img->src('https://example.com/image.jpg')->prefix('prev')->render();
+
+// adding a suffix
+$html = $img->src('https://example.com/image.jpg')->suffix('Next')->render();
+```
+
+## Template
+
+The `template` method allows you to customize the `HTML` output of the a element.
+
+The following template tags are available:
+
+| Tag        | Description      |
+| ---------- | ---------------- |
+| `{prefix}` | The prefix text. |
+| `{tag}`    | The a element.   |
+| `{suffix}` | The suffix text. |
+
+```php
+// using a custom template
+$img->template('<span>{tag}</span>');
+```
+
+## Attributes
+
+Refer to the [Attribute Tests](https://github.com/php-forge/html/blob/main/tests/Img/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.                                                                       |
+| `crossorigin()`   | Set the `crossorigin` attribute.                                                                 |
+| `dataAttributes()`| Set multiple `data-attributes` at once.                                                          |
+| `height()`        | Set the `height` attribute.                                                                      |
+| `id()`            | Set the `id` attribute.                                                                          |
+| `ismap()`         | Set the `ismap` attribute.                                                                       |
+| `lang()`          | Set the `lang` attribute.                                                                        |
+| `loading()`       | Set the `loading` attribute.                                                                     |
+| `name()`          | Set the `name` attribute.                                                                        |
+| `sizes()`         | Set the `sizes` attribute.                                                                       |
+| `src()`           | Set the `src` attribute.                                                                         |
+| `srcset()`        | Set the `srcset` attribute.                                                                      |
+| `style()`         | Set the `style` attribute.                                                                       |
+| `title()`         | Set the `title` attribute.                                                                       |
+| `width()`         | Set the `width` attribute.                                                                       |
+
+## Custom methods
+
+Refer to the [Custom Method Test](https://github.com/php-forge/html/blob/main/tests/Img/CustomMethodTest.php) for 
+comprehensive examples.
+
+The following methods are available for customizing the `HTML` output:
+
+| Method                       | Description                                                                           |
+| ---------------------------- | ------------------------------------------------------------------------------------- |
+| `prefix()`                   | Add text before the `img` 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 `img` 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.                                     |
+| `template()`                 | Set the `template` for the `img` element.                                             |
+| `widget()`                   | Instantiates the `Img::class`.                                                        |
diff --git a/src/A.php b/src/A.php
index df15c7f3..d95727bf 100644
--- a/src/A.php
+++ b/src/A.php
@@ -19,6 +19,7 @@ final class A extends Base\AbstractElement
     use Attribute\Aria\HasRole;
     use Attribute\CanBeAutofocus;
     use Attribute\CanBeHidden;
+    use Attribute\Custom\HasContent;
     use Attribute\HasTabindex;
     use Attribute\Input\HasType;
     use Attribute\Tag\HasDownload;
@@ -31,6 +32,6 @@ final class A extends Base\AbstractElement
 
     protected function run(): string
     {
-        return $this->buildElement('a');
+        return $this->buildElement('a', $this->content);
     }
 }
diff --git a/src/Base/AbstractElement.php b/src/Base/AbstractElement.php
index 0e257ac9..bea582bf 100644
--- a/src/Base/AbstractElement.php
+++ b/src/Base/AbstractElement.php
@@ -14,7 +14,6 @@
 abstract class AbstractElement extends Element
 {
     use Attribute\Custom\HasAttributes;
-    use Attribute\Custom\HasContent;
     use Attribute\Custom\HasPrefixAndSuffix;
     use Attribute\Custom\HasTemplate;
     use Attribute\HasClass;
@@ -41,18 +40,19 @@ protected function loadDefaultDefinitions(): array
      * Generate the HTML representation of the element.
      *
      * @param string $tagName The tag name of the element.
+     * @param string $content The content of the element.
      * @param array $tokenValues The token values to be used in the template.
      *
      * @return string The HTML representation of the element.
      */
-    protected function buildElement(string $tagName, array $tokenValues = []): string
+    protected function buildElement(string $tagName, string $content = '', array $tokenValues = []): string
     {
         $attributes = $this->attributes;
         $attributes['id'] ??= $this->id;
 
         $tokenTemplateValues = [
             '{prefix}' => $this->renderPrefixTag(),
-            '{tag}' => HtmlBuilder::create($tagName, $this->content, $attributes),
+            '{tag}' => HtmlBuilder::create($tagName, $content, $attributes),
             '{suffix}' => $this->renderSuffixTag(),
         ];
         $tokenTemplateValues += $tokenValues;
diff --git a/src/I.php b/src/I.php
index 81e28f94..336091b1 100644
--- a/src/I.php
+++ b/src/I.php
@@ -12,8 +12,10 @@
  */
 final class I extends Base\AbstractElement
 {
+    use Attribute\Custom\HasContent;
+
     protected function run(): string
     {
-        return $this->buildElement('i');
+        return $this->buildElement('i', $this->content);
     }
 }
diff --git a/src/Label.php b/src/Label.php
index f45fff92..05f72c69 100644
--- a/src/Label.php
+++ b/src/Label.php
@@ -11,11 +11,12 @@
  */
 final class Label extends Base\AbstractElement
 {
+    use Attribute\Custom\HasContent;
     use Attribute\Input\HasForm;
     use Attribute\Tag\HasFor;
 
     protected function run(): string
     {
-        return $this->buildElement('label');
+        return $this->buildElement('label', $this->content);
     }
 }
diff --git a/src/Span.php b/src/Span.php
index 66867946..3799794b 100644
--- a/src/Span.php
+++ b/src/Span.php
@@ -16,8 +16,10 @@
  */
 final class Span extends Base\AbstractElement
 {
+    use Attribute\Custom\HasContent;
+
     protected function run(): string
     {
-        return $this->buildElement('span');
+        return $this->buildElement('span', $this->content);
     }
 }
diff --git a/src/Tag.php b/src/Tag.php
index 0d8fc9a0..0310b996 100644
--- a/src/Tag.php
+++ b/src/Tag.php
@@ -18,6 +18,7 @@
  */
 final class Tag extends Base\AbstractElement
 {
+    use Attribute\Custom\HasContent;
     use Attribute\Custom\HasTagName;
     use Attribute\Custom\HasTokenValues;
     use Attribute\HasTabindex;
@@ -26,6 +27,6 @@ final class Tag extends Base\AbstractElement
 
     protected function run(): string
     {
-        return $this->buildElement($this->tagName, $this->tokenValues);
+        return $this->buildElement($this->tagName, $this->content, $this->tokenValues);
     }
 }
diff --git a/src/TextArea.php b/src/TextArea.php
index ce80fc84..af1f671f 100644
--- a/src/TextArea.php
+++ b/src/TextArea.php
@@ -20,6 +20,7 @@ final class TextArea extends Base\AbstractElement implements
     Contract\RequiredInterface
 {
     use Attribute\CanBeAutofocus;
+    use Attribute\Custom\HasContent;
     use Attribute\HasTabindex;
     use Attribute\Input\CanBeDisabled;
     use Attribute\Input\CanBeReadonly;
@@ -47,6 +48,6 @@ protected function loadDefaultDefinitions(): array
 
     protected function run(): string
     {
-        return $this->buildElement('textarea');
+        return $this->buildElement('textarea', $this->content);
     }
 }
diff --git a/tests/Img/AttributeTest.php b/tests/Img/AttributeTest.php
new file mode 100644
index 00000000..2495da17
--- /dev/null
+++ b/tests/Img/AttributeTest.php
@@ -0,0 +1,185 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PHPForge\Html\Tests\Img;
+
+use PHPForge\Html\Img;
+use PHPForge\Support\Assert;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * @psalm-suppress PropertyNotSetInConstructor
+ */
+final class AttributeTest extends TestCase
+{
+    public function testAlt(): void
+    {
+        Assert::equalsWithoutLE(
+            <<<HTML
+            <img alt="value">
+            HTML,
+            Img::widget()->alt('value')->render()
+        );
+    }
+
+    public function testAttributes(): void
+    {
+        Assert::equalsWithoutLE(
+            <<<HTML
+            <img class="value">
+            HTML,
+            Img::widget()->attributes(['class' => 'value'])->render()
+        );
+    }
+
+    public function testClass(): void
+    {
+        Assert::equalsWithoutLE(
+            <<<HTML
+            <img class="value">
+            HTML,
+            Img::widget()->class('value')->render()
+        );
+    }
+
+    public function testCrossOrigin(): void
+    {
+        Assert::equalsWithoutLE(
+            <<<HTML
+            <img crossorigin="anonymous">
+            HTML,
+            Img::widget()->crossOrigin('anonymous')->render()
+        );
+    }
+
+    public function testDataAttributes(): void
+    {
+        Assert::equalsWithoutLE(
+            <<<HTML
+            <img data-value="value">
+            HTML,
+            Img::widget()->dataAttributes(['value' => 'value'])->render()
+        );
+    }
+
+    public function testHeight(): void
+    {
+        Assert::equalsWithoutLE(
+            <<<HTML
+            <img height="1">
+            HTML,
+            Img::widget()->height(1)->render()
+        );
+    }
+
+    public function testId(): void
+    {
+        Assert::equalsWithoutLE(
+            <<<HTML
+            <img id="value">
+            HTML,
+            Img::widget()->id('value')->render()
+        );
+    }
+
+    public function testIsMap(): void
+    {
+        Assert::equalsWithoutLE(
+            <<<HTML
+            <img ismap>
+            HTML,
+            Img::widget()->isMap()->render()
+        );
+    }
+
+    public function testLang(): void
+    {
+        Assert::equalsWithoutLE(
+            <<<HTML
+            <img lang="value">
+            HTML,
+            Img::widget()->lang('value')->render()
+        );
+    }
+
+    public function testLoading(): void
+    {
+        Assert::equalsWithoutLE(
+            <<<HTML
+            <img loading="lazy">
+            HTML,
+            Img::widget()->loading('lazy')->render()
+        );
+    }
+
+    public function testName(): void
+    {
+        Assert::equalsWithoutLE(
+            <<<HTML
+            <img name="value">
+            HTML,
+            Img::widget()->name('value')->render()
+        );
+    }
+
+    public function testSizes(): void
+    {
+        Assert::equalsWithoutLE(
+            <<<HTML
+            <img sizes="value">
+            HTML,
+            Img::widget()->sizes('value')->render()
+        );
+    }
+
+    public function testSrc(): void
+    {
+        Assert::equalsWithoutLE(
+            <<<HTML
+            <img src="value">
+            HTML,
+            Img::widget()->src('value')->render()
+        );
+    }
+
+    public function testSrcSet(): void
+    {
+        Assert::equalsWithoutLE(
+            <<<HTML
+            <img srcset="value">
+            HTML,
+            Img::widget()->srcSet('value')->render()
+        );
+    }
+
+    public function testStyle(): void
+    {
+        Assert::equalsWithoutLE(
+            <<<HTML
+            <img style="value">
+            HTML,
+            Img::widget()->style('value')->render()
+        );
+    }
+
+    public function testTitle(): void
+    {
+        Assert::equalsWithoutLE(
+            <<<HTML
+            <img title="value">
+            HTML,
+            Img::widget()->title('value')->render()
+        );
+    }
+
+    public function testWidth(): void
+    {
+        Assert::equalsWithoutLE(
+            <<<HTML
+            <img width="1">
+            HTML,
+            Img::widget()->width(1)->render()
+        );
+    }
+}
diff --git a/tests/Img/CustomMethodTest.php b/tests/Img/CustomMethodTest.php
new file mode 100644
index 00000000..1097b7fe
--- /dev/null
+++ b/tests/Img/CustomMethodTest.php
@@ -0,0 +1,167 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PHPForge\Html\Tests\Img;
+
+use PHPForge\Html\Img;
+use PHPForge\Support\Assert;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * @psalm-suppress PropertyNotSetInConstructor
+ */
+final class CustomMethodTest extends TestCase
+{
+    public function testPrefix(): void
+    {
+        Assert::equalsWithoutLE(
+            <<<HTML
+            value
+            <img>
+            HTML,
+            Img::widget()->prefix('value')->render(),
+        );
+    }
+
+    public function testPrefixContainer(): void
+    {
+        Assert::equalsWithoutLE(
+            <<<HTML
+            <div>
+            value
+            </div>
+            <img>
+            HTML,
+            Img::widget()->prefixContainer(true)->prefix('value')->render(),
+        );
+    }
+
+    public function testPrefixContainerAttributes(): void
+    {
+        Assert::equalsWithoutLE(
+            <<<HTML
+            <div class="value">
+            value
+            </div>
+            <img>
+            HTML,
+            Img::widget()
+                ->prefixContainer(true)
+                ->prefix('value')
+                ->prefixContainerAttributes(['class' => 'value'])
+                ->render(),
+        );
+    }
+
+    public function testPrefixContainerClass(): void
+    {
+        Assert::equalsWithoutLE(
+            <<<HTML
+            <div class="value">
+            value
+            </div>
+            <img>
+            HTML,
+            Img::widget()->prefixContainer(true)->prefix('value')->prefixContainerClass('value')->render(),
+        );
+    }
+
+    public function testPrefixContainerTag(): void
+    {
+        Assert::equalsWithoutLE(
+            <<<HTML
+            <span>value</span>
+            <img>
+            HTML,
+            Img::widget()->prefixContainer(true)->prefix('value')->prefixContainerTag('span')->render(),
+        );
+    }
+
+    public function testRender(): void
+    {
+        Assert::equalsWithoutLE(
+            <<<HTML
+            <img>
+            HTML,
+            Img::widget()->render(),
+        );
+    }
+
+    public function testSuffix(): void
+    {
+        Assert::equalsWithoutLE(
+            <<<HTML
+            <img>
+            value
+            HTML,
+            Img::widget()->suffix('value')->render(),
+        );
+    }
+
+    public function testSuffixContainer(): void
+    {
+        Assert::equalsWithoutLE(
+            <<<HTML
+            <img>
+            <div>
+            value
+            </div>
+            HTML,
+            Img::widget()->suffixContainer(true)->suffix('value')->render(),
+        );
+    }
+
+    public function testSuffixContainerAttributes(): void
+    {
+        Assert::equalsWithoutLE(
+            <<<HTML
+            <img>
+            <div class="value">
+            value
+            </div>
+            HTML,
+            Img::widget()
+                ->suffixContainer(true)
+                ->suffix('value')
+                ->suffixContainerAttributes(['class' => 'value'])
+                ->render(),
+        );
+    }
+
+    public function testSuffixContainerClass(): void
+    {
+        Assert::equalsWithoutLE(
+            <<<HTML
+            <img>
+            <div class="value">
+            value
+            </div>
+            HTML,
+            Img::widget()->suffixContainer(true)->suffix('value')->suffixContainerClass('value')->render(),
+        );
+    }
+
+    public function testSuffixContainerTag(): void
+    {
+        Assert::equalsWithoutLE(
+            <<<HTML
+            <img>
+            <span>value</span>
+            HTML,
+            Img::widget()->suffixContainer(true)->suffix('value')->suffixContainerTag('span')->render(),
+        );
+    }
+
+    public function testTemplate(): void
+    {
+        Assert::equalsWithoutLE(
+            <<<HTML
+            <div>
+            <img src="value">
+            </div>
+            HTML,
+            Img::widget()->src('value')->template('<div>\n{tag}\n</div>')->render(),
+        );
+    }
+}
diff --git a/tests/Img/RenderTest.php b/tests/Img/RenderTest.php
deleted file mode 100644
index ba35336e..00000000
--- a/tests/Img/RenderTest.php
+++ /dev/null
@@ -1,19 +0,0 @@
-<?php
-
-declare(strict_types=1);
-
-namespace PHPForge\Html\Tests\Img;
-
-use PHPForge\Html\Img;
-use PHPUnit\Framework\TestCase;
-
-/**
- * @psalm-suppress PropertyNotSetInConstructor
- */
-final class RenderTest extends TestCase
-{
-    public function testElement(): void
-    {
-        $this->assertSame('<img>', Img::widget()->render());
-    }
-}