Add docs Span::class. (#283)

docs/README.md

@@ -31,6 +31,7 @@ The following tags are currently supported:
 - [p](/docs/tag/P.md)
 - [section](/docs/tag/Section.md)
 - [select](/docs/tag/Select.md)
+- [span](/docs/tag/Span.md)
 
 ## Input Tags
 

docs/tag/Span.md

@@ -0,0 +1,116 @@
+# Span
+
+ The `<span>` `HTML` element represents a generic inline container for phrasing content, which doesn't inherently
+ represent anything. It can be used to group elements for styling purposes (using the class or id attributes), or
+ because they share attribute values, such as lang. It should be used only when no other semantic element is
+ appropriate.
+
+`<span>` is very much like a `<div>` element, but `<div>` is a block-level element whereas a `<span>` is an inline 
+element.
+
+## Basic Usage
+
+Instantiate the `Span` class using `Span::widget()`.
+
+```php
+$span = Span::widget();
+```
+
+Or, block style instantiation.
+
+```php
+<?= Span::begin() ?>
+    // ... content to be wrapped by `div` element
+<?= Span::end() ?>
+```
+
+## Setting Attributes
+
+Use the provided methods to set specific attributes for the a element.
+
+```php
+// setting class attribute
+$span->class('container');
+```
+
+Or, use the `attributes` method to set multiple attributes at once.
+
+```php
+$span->attributes(['class' => 'container', 'style' => 'background-color: #eee;']);
+```
+
+## Adding Content
+
+If you want to include content within the `div` tag, use the `content` method.
+
+```php
+$span->content('My content');
+```
+
+Or, use `begin()` and `end()` methods to wrap content.
+
+```php
+<?= Span::begin() ?>
+    My content
+<?= Span::end() ?>
+```
+
+## Rendering
+
+Generate the `HTML` output using the `render` method, for simple instantiation. 
+
+```php
+$html = $span->render();
+```
+
+Or, use the magic `__toString` method.
+
+```php
+$html = (string) $span;
+```
+
+## Common Use Cases
+
+Below are examples of common use cases:
+
+```php
+// adding multiple attributes
+$span->class('external')->content('My content');
+
+// using data attributes
+$span->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/Span/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.                                                                       |
+| `title()`         | Set the `title` attribute.                                                                       |
+
+## Custom methods
+
+Refer to the [Custom Methods Tests](https://github.com/php-forge/html/blob/main/tests/Span/CustomMethodTest.php) for
+comprehensive examples.
+
+The following methods are available for customizing the `HTML` output:
+
+| Method      | Description                                                                                            |
+| ----------- | ------------------------------------------------------------------------------------------------------ |
+| `render()`  | Generates the `HTML` output.                                                                           |
+| `template()`| Set the template for the `HTML` output.                                                                |
+| `widget()`  | Instantiates the `Body::class`.                                                                        |

src/Span.php

@@ -5,9 +5,10 @@
 namespace PHPForge\Html;
 
 /**
- * The `<span>` HTML element represents a generic inline container for phrasing content, which doesn't inherently represent
- * anything. It can be used to group elements for styling purposes (using the class or id attributes), or because they
- * share attribute values, such as lang. It should be used only when no other semantic element is appropriate.
+ * The `<span>` HTML element represents a generic inline container for phrasing content, which doesn't inherently
+ * represent anything. It can be used to group elements for styling purposes (using the class or id attributes), or
+ * because they share attribute values, such as lang. It should be used only when no other semantic element is
+ * appropriate.
  *
  * `<span>` is very much like a `<div>` element, but `<div>` is a block-level element whereas a `<span>` is an inline
  * element.

tests/Span/AttributeTest.php

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

tests/Span/CustomMethodTest.php

@@ -0,0 +1,93 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PHPForge\Html\Tests\Span;
+
+use PHPForge\Html\Span;
+use PHPForge\Support\Assert;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * @psalm-suppress PropertyNotSetInConstructor
+ */
+final class CustomMethodTest extends TestCase
+{
+    public function testPrefixContainer(): void
+    {
+        Assert::equalsWithoutLE(
+            <<<HTML
+            <div>
+            value
+            </div>
+            <span></span>
+            HTML,
+            Span::widget()->prefix('value')->prefixContainer(true)->render()
+        );
+    }
+
+    public function testPrefixContainerAttributes(): void
+    {
+        Assert::equalsWithoutLE(
+            <<<HTML
+            <div class="value">
+            value
+            </div>
+            <span></span>
+            HTML,
+            Span::widget()
+                ->prefix('value')
+                ->prefixContainer(true)
+                ->prefixContainerAttributes(['class' => 'value'])
+                ->render()
+        );
+    }
+
+    public function testPrefixContainerClass(): void
+    {
+        Assert::equalsWithoutLE(
+            <<<HTML
+            <div class="value">
+            value
+            </div>
+            <span></span>
+            HTML,
+            Span::widget()->prefix('value')->prefixContainer(true)->prefixContainerClass('value')->render()
+        );
+    }
+
+    public function testPrefixContainerTag(): void
+    {
+        Assert::equalsWithoutLE(
+            <<<HTML
+            <div>
+            value
+            </div>
+            <span></span>
+            HTML,
+            Span::widget()->prefix('value')->prefixContainer(true)->prefixContainerTag('div')->render()
+        );
+    }
+
+    public function testRender(): void
+    {
+        Assert::equalsWithoutLE(
+            <<<HTML
+            <span></span>
+            HTML,
+            Span::widget()->render(),
+        );
+    }
+
+    public function testTemplate(): void
+    {
+        Assert::equalsWithoutLE(
+            <<<HTML
+            <div>
+            <span>value</span>
+            </div>
+            HTML,
+            Span::widget()->content('value')->template('<div>\n{tag}\n</div>')->render()
+        );
+    }
+}