Add docs Ol::class. (#279)

docs/README.md

@@ -27,6 +27,7 @@ The following tags are currently supported:
 - [li](/docs/tag/Li.md)
 - [meta](/docs/tag/Meta.md)
 - [nav](/docs/tag/Nav.md)
+- [ol](/docs/tag/Ol.md)
 
 ## Input Tags
 

docs/tag/Ol.md

@@ -0,0 +1,94 @@
+# Ol
+
+The `<ol>` `HTML` element represents an ordered list of items, typically rendered as a numbered list.
+
+## Basic Usage
+
+Instantiate the `Ol` class using `Ol::widget()`.
+
+```php
+$ol = Ol::widget();
+```
+
+## Setting Attributes
+
+Use the provided methods to set specific attributes for the a element.
+
+```php
+// setting class attribute
+$ol->class('external');
+```
+
+Or, use the `attributes` method to set multiple attributes at once.
+
+```php
+$ol->attributes(['class' => 'external', 'title' => 'External Link']);
+```
+
+## Adding Content
+
+If you want to include content within the `ol` tag, use the `content` method.
+
+```php
+$ol->content('myContent');
+```
+
+## Rendering
+
+Generate the `HTML` output using the `render` method.
+
+```php
+$html = $ol->render();
+```
+
+Or, use the magic `__toString` method.
+
+```php
+$html = (string) $ol;
+```
+
+## Common Use Cases
+
+Below are examples of common use cases:
+
+```php
+// adding multiple attributes
+$ol->class('external')->content('myContent')->title('External Link');
+```
+
+Explore additional methods for setting various attributes such as `lang`, `tabindex`, `title`, `value` and more.
+
+## Attributes
+
+Refer to the [Attribute Tests](https://github.com/php-forge/html/blob/main/tests/Ol/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 `ol` element.                                                       |
+| `id()`            | Set the `id` attribute.                                                                          |
+| `lang()`          | Set the `lang` attribute.                                                                        |
+| `name()`          | Set the `name` attribute.                                                                        |
+| `reversed()`      | Set the `reversed` attribute.                                                                    |
+| `start()`         | Set the `start` 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 Method Test](https://github.com/php-forge/html/blob/main/tests/Ol/CustomMethodTest.php) for 
+comprehensive examples.
+
+The following methods are available for customizing the `HTML` output:
+
+| Method                       | Description                                                                           |
+| ---------------------------- | ------------------------------------------------------------------------------------- |
+| `render()`                   | Generates the `HTML` output.                                                          |
+| `widget()`                   | Instantiates the `Ol::class`.                                                         |

src/Attribute/Tag/HasReversed.php

@@ -0,0 +1,26 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PHPForge\Html\Attribute\Tag;
+
+/**
+ * Is used by widgets that implement the reversed method.
+ */
+trait HasReversed
+{
+    /**
+     * Set the reversed attribute.
+     *
+     * @return static A new instance of the current class with the specified reversed value.
+     *
+     * @link https://html.spec.whatwg.org/multipage/grouping-content.html#attr-ol-reversed
+     */
+    public function reversed(): static
+    {
+        $new = clone $this;
+        $new->attributes['reversed'] = true;
+
+        return $new;
+    }
+}

src/Attribute/Tag/HasStart.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PHPForge\Html\Attribute\Tag;
+
+/**
+ * Is used by widgets that implement the start method.
+ */
+trait HasStart
+{
+    /**
+     * The start attribute specifies the value of the first list item in an ordered list.
+     *
+     * @param int $value The value of the first list item in an ordered list.
+     *
+     * @return static A new instance of the current class with the specified start value.
+     *
+     * @link https://html.spec.whatwg.org/multipage/grouping-content.html#attr-ol-start
+     */
+    public function start(int $value): static
+    {
+        $new = clone $this;
+        $new->attributes['start'] = $value;
+
+        return $new;
+    }
+}

src/Ol.php

@@ -11,5 +11,8 @@
  */
 final class Ol extends Base\AbstractList
 {
+    use Attribute\Tag\HasReversed;
+    use Attribute\Tag\HasStart;
+
     protected string $tagName = 'ol';
 }

tests/Attribute/Tag/HasReversedTest.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PHPForge\Html\Tests\Attribute\Tag;
+
+use PHPForge\Html\Attribute\Tag\HasReversed;
+use PHPUnit\Framework\TestCase;
+
+final class HasReversedTest extends TestCase
+{
+    public function testImmutability(): void
+    {
+        $instance = new class () {
+            use HasReversed;
+
+            protected array $attributes = [];
+        };
+
+        $this->assertNotSame($instance, $instance->reversed());
+    }
+}

tests/Attribute/Tag/HasStartTest.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PHPForge\Html\Tests\Attribute\Tag;
+
+use PHPForge\Html\Attribute\Tag\HasStart;
+use PHPUnit\Framework\TestCase;
+
+final class HasStartTest extends TestCase
+{
+    public function testImmutability(): void
+    {
+        $instance = new class () {
+            use HasStart;
+
+            protected array $attributes = [];
+        };
+
+        $this->assertNotSame($instance, $instance->start(1));
+    }
+}

tests/Ol/RenderTest.php → tests/Ol/AttributeTest.php

@@ -12,31 +12,27 @@
 /**
  * @psalm-suppress PropertyNotSetInConstructor
  */
-final class RenderTest extends TestCase
+final class AttributeTest extends TestCase
 {
     public function testAttributes(): void
     {
         Assert::equalsWithoutLE(
             <<<HTML
-            <ol class="test-class">
+            <ol class="value">
             </ol>
             HTML,
-            Ol::widget()->attributes([
-                'class' => 'test-class',
-            ])->render(),
+            Ol::widget()->attributes(['class' => 'value'])->render()
         );
     }
 
     public function testClass(): void
     {
         Assert::equalsWithoutLE(
             <<<HTML
-            <ol class="test-class test-class-1">
+            <ol class="value">
             </ol>
             HTML,
-            Ol::widget()->attributes([
-                'class' => 'test-class',
-            ])->class('test-class-1')->render(),
+            Ol::widget()->attributes(['class' => 'value'])->render()
         );
     }
 
@@ -53,105 +49,73 @@ public function testContent(): void
             </li>
             </ol>
             HTML,
-            Ol::widget()
-                ->content(
-                    Li::widget()->content('Item 1'),
-                    Li::widget()->content('Item 2'),
-                )
-                ->render(),
+            Ol::widget()->content(Li::widget()->content('Item 1'), Li::widget()->content('Item 2'))->render()
         );
     }
 
-    public function testElement(): void
+    public function testId(): void
     {
         Assert::equalsWithoutLE(
             <<<HTML
-            <ol>
+            <ol id="value">
             </ol>
             HTML,
-            Ol::widget()->render(),
+            Ol::widget()->id('value')->render(),
         );
     }
 
-    public function testId(): void
+    public function testLang(): void
     {
         Assert::equalsWithoutLE(
             <<<HTML
-            <ol id="test-id">
+            <ol lang="value">
             </ol>
             HTML,
-            Ol::widget()->id('test-id')->render(),
+            Ol::widget()->lang('value')->render()
         );
     }
 
-    public function testLang(): void
+    public function testName(): void
     {
         Assert::equalsWithoutLE(
             <<<HTML
-            <ol lang="en">
+            <ol name="value">
             </ol>
             HTML,
-            Ol::widget()->lang('en')->render(),
+            Ol::widget()->name('value')->render(),
         );
     }
 
-    public function testName(): void
+    public function testReversed(): void
     {
         Assert::equalsWithoutLE(
             <<<HTML
-            <ol name="test-name">
+            <ol reversed>
             </ol>
             HTML,
-            Ol::widget()->name('test-name')->render(),
+            Ol::widget()->reversed()->render(),
         );
     }
 
-    public function testNested(): void
+    public function testStart(): void
     {
         Assert::equalsWithoutLE(
             <<<HTML
-            <ol>
-            <li>
-            Item 1
-            <ol>
-            <li>
-            Item 1.1
-            </li>
-            <li>
-            Item 1.2
-            </li>
-            </ol>
-            </li>
-            <li>
-            Item 2
-            </li>
+            <ol start="1">
             </ol>
             HTML,
-            Ol::widget()
-                ->content(
-                    Li::widget()
-                        ->content(
-                            'Item 1',
-                            Ol::widget()
-                                ->content(
-                                    Li::widget()->content('Item 1.1'),
-                                    Li::widget()->content('Item 1.2'),
-                                ),
-                        ),
-                    Li::widget()->content('Item 2'),
-                )
-                ->render(),
+            Ol::widget()->start(1)->render(),
         );
     }
 
     public function testStyle(): void
     {
         Assert::equalsWithoutLE(
             <<<HTML
-            <ol style="color:red;">
+            <ol style="value">
             </ol>
             HTML,
-            Ol::widget()->style('color:red;')->render(),
+            Ol::widget()->style('value')->render(),
         );
     }
 
@@ -170,10 +134,10 @@ public function testTitle(): void
     {
         Assert::equalsWithoutLE(
             <<<HTML
-            <ol title="test-title">
+            <ol title="value">
             </ol>
             HTML,
-            Ol::widget()->title('test-title')->render(),
+            Ol::widget()->title('value')->render(),
         );
     }