Add Main::class widget. (#323)

php-forge · Feb 20, 2024 · e8b0f8a · e8b0f8a
1 parent 7570dde
commit e8b0f8a
Show file tree

Hide file tree

Showing 4 changed files with 289 additions and 0 deletions.
diff --git a/docs/layout/Main.md b/docs/layout/Main.md
@@ -0,0 +1,119 @@
+# Main
+
+The `<main>` `HTML` element represents the dominant content of the <body> of a document. The main content area consists
+of content that is directly related to or expands upon the central topic of a document, or the central functionality of
+an application.
+
+## Basic Usage
+
+Instantiate the `Main` class using `Main::widget()`.
+
+```php
+$main = Main::widget();
+```
+
+Or, block style instantiation.
+
+```php
+<?= Main::begin() ?>
+    // ... content to be wrapped by `main` element
+<?= Main::end() ?>
+```
+
+## Setting Attributes
+
+Use the provided methods to set specific attributes for the a element.
+
+```php
+// setting class attribute
+$main->class('container');
+```
+
+Or, use the `attributes` method to set multiple attributes at once.
+
+```php
+$main->attributes(['class' => 'container', 'style' => 'background-color: #eee;']);
+```
+
+## Adding Content
+
+If you want to include content within the `main` tag, use the `content` method.
+
+```php
+$main->content('MyContent');
+```
+
+Or, use `begin()` and `end()` methods to wrap content.
+
+```php
+<?= Main::begin() ?>
+    My content
+<?= Main::end() ?>
+```
+
+## Rendering
+
+Generate the `HTML` output using the `render` method, for simple instantiation. 
+
+```php
+$html = $main->render();
+```
+
+For block style instantiation, use the `end()` method, which returns the `HTML` output.
+
+```php
+$html = Main::end();
+```
+
+Or, use the magic `__toString` method.
+
+```php
+$html = (string) $main;
+```
+
+## Common Use Cases
+
+Below are examples of common use cases:
+
+```php
+// adding multiple attributes
+$main->class('external')->content('MyContent');
+
+// using data attributes
+$main->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/Layout/Main/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 `main` 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/Layout/Main/CustomMethodTest.php)
+for comprehensive examples.
+
+The following methods are available for customizing the `HTML` output:
+
+| Method    | Description                                                                                              |
+| --------- | -------------------------------------------------------------------------------------------------------- |
+| `begin() `| Start the `main` element.                                                                                |
+| `end()`   | End the `main` element, and generate the `HTML` output.                                                  |
+| `render()`| Generates the `HTML` output.                                                                             |
+| `widget()`| Instantiates the `Main::class`.                                                                          |
diff --git a/src/Layout/Main.php b/src/Layout/Main.php
@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PHPForge\Html\Layout;
+
+use PHPForge\Html\Base\AbstractBlockElement;
+
+/**
+ * The `<main>` HTML element represents the dominant content of the <body> of a document. The main content area consists
+ * of content that is directly related to or expands upon the central topic of a document, or the central functionality
+ * of an application.
+ *
+ * @link https://html.spec.whatwg.org/multipage/grouping-content.html#the-main-element
+ */
+final class Main extends AbstractBlockElement
+{
+    protected string $tagName = 'main';
+}
diff --git a/tests/Layout/Main/AttributeTest.php b/tests/Layout/Main/AttributeTest.php
@@ -0,0 +1,115 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PHPForge\Html\Tests\Layout\Main;
+
+use PHPForge\Html\Layout\Main;
+use PHPForge\Support\Assert;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * @psalm-suppress PropertyNotSetInConstructor
+ */
+final class AttributeTest extends TestCase
+{
+    public function testAttributes(): void
+    {
+        Assert::equalsWithoutLE(
+            <<<HTML
+            <main class="value">
+            </main>
+            HTML,
+            Main::widget()->attributes(['class' => 'value'])->render()
+        );
+    }
+
+    public function testClass(): void
+    {
+        Assert::equalsWithoutLE(
+            <<<HTML
+            <main class="value">
+            </main>
+            HTML,
+            Main::widget()->class('value')->render()
+        );
+    }
+
+    public function testContent(): void
+    {
+        Assert::equalsWithoutLE(
+            <<<HTML
+            <main>
+            value
+            </main>
+            HTML,
+            Main::widget()->content('value')->render()
+        );
+    }
+
+    public function testDataAttributes(): void
+    {
+        Assert::equalsWithoutLE(
+            <<<HTML
+            <main data-value="value">
+            </main>
+            HTML,
+            Main::widget()->dataAttributes(['value' => 'value'])->render()
+        );
+    }
+
+    public function testId(): void
+    {
+        Assert::equalsWithoutLE(
+            <<<HTML
+            <main id="value">
+            </main>
+            HTML,
+            Main::widget()->id('value')->render()
+        );
+    }
+
+    public function testLang(): void
+    {
+        Assert::equalsWithoutLE(
+            <<<HTML
+            <main lang="value">
+            </main>
+            HTML,
+            Main::widget()->lang('value')->render()
+        );
+    }
+
+    public function testName(): void
+    {
+        Assert::equalsWithoutLE(
+            <<<HTML
+            <main name="value">
+            </main>
+            HTML,
+            Main::widget()->name('value')->render()
+        );
+    }
+
+    public function testStyle(): void
+    {
+        Assert::equalsWithoutLE(
+            <<<HTML
+            <main style="value">
+            </main>
+            HTML,
+            Main::widget()->style('value')->render()
+        );
+    }
+
+    public function testTitle(): void
+    {
+        Assert::equalsWithoutLE(
+            <<<HTML
+            <main title="value">
+            </main>
+            HTML,
+            Main::widget()->title('value')->render()
+        );
+    }
+}
diff --git a/tests/Layout/Main/CustomMethodTest.php b/tests/Layout/Main/CustomMethodTest.php
@@ -0,0 +1,36 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PHPForge\Html\Tests\Layout\Main;
+
+use PHPForge\Html\Layout\Main;
+use PHPForge\Support\Assert;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * @psalm-suppress PropertyNotSetInConstructor
+ */
+final class CustomMethodTest extends TestCase
+{
+    public function testBeginEnd(): void
+    {
+        Assert::equalsWithoutLE(
+            <<<HTML
+            <main>value</main>
+            HTML,
+            Main::widget()->begin() . 'value' . Main::end()
+        );
+    }
+
+    public function testRender(): void
+    {
+        Assert::equalsWithoutLE(
+            <<<HTML
+            <main>
+            </main>
+            HTML,
+            Main::widget()->render()
+        );
+    }
+}