Add docs number class (#313)

php-forge · Feb 18, 2024 · 63b7d41 · 63b7d41
1 parent 7fae566
commit 63b7d41
Show file tree

Hide file tree

Showing 8 changed files with 240 additions and 54 deletions.
diff --git a/docs/README.md b/docs/README.md
@@ -62,6 +62,7 @@ This is particularly useful for creating forms and other interactive elements on
 - [hidden](/docs/form/input/Hidden.md)
 - [image](/docs/form/input/Image.md)
 - [month](/docs/form/input/Month.md)
+- [number](/docs/form/input/Number.md)
 - [radio](/docs/form/input/Radio.md)
 - [radio-list](/docs/form/input/RadioList.md)
 - [text](/docs/form/input/Text.md)

diff --git a/docs/form/input/Date.md b/docs/form/input/Date.md
@@ -79,7 +79,7 @@ Explore additional methods for setting various attributes such as `lang`, `name`
 
 ## Prefix and Suffix
 
-Use `prefix` and `suffix` methods to add text before and after the `datetime-local` tag, respectively.
+Use `prefix` and `suffix` methods to add text before and after the `datetime` tag, respectively.
 
 ```php
 // adding a prefix

diff --git a/docs/form/input/Month.md b/docs/form/input/Month.md
@@ -79,7 +79,7 @@ Explore additional methods for setting various attributes such as `lang`, `name`
 
 ## Prefix and Suffix
 
-Use `prefix` and `suffix` methods to add text before and after the `datetime-local` tag, respectively.
+Use `prefix` and `suffix` methods to add text before and after the `month` tag, respectively.
 
 ```php
 // adding a prefix
@@ -128,7 +128,6 @@ The following methods are available for setting attributes:
 | `lang()`           | Set the `lang` attribute.                                                                       |
 | `name()`           | Set the `name` attribute.                                                                       |
 | `readOnly()`       | Set the `readonly` attribute.                                                                   |
-| `step()`           | Set the `step` attribute.                                                                       |
 | `style()`          | Set the `style` attribute.                                                                      |
 | `tabIndex()`       | Set the `tabindex` attribute.                                                                   |
 | `title()`          | Set the `title` attribute.                                                                      |

diff --git a/docs/form/input/Number.md b/docs/form/input/Number.md
@@ -0,0 +1,171 @@
+# Number
+
+The input element with a type attribute whose value is `range` represents an imprecise control for setting the
+element’s value to a string representing a number.
+
+## Basic Usage
+
+Instantiate the `Number` class using `Number::widget()`.
+
+```php
+$number = Number::widget();
+```
+
+## Generate field id and name
+
+The `generateField` method is used to generate the field id and name for the `HTML` output.
+
+Allowed arguments are:
+
+- `modelName` - The name of the model.
+- `fieldName` - The name of the field.
+- `arrayable` - Whether the field is an array. For default, it is `false`.
+
+```php
+// generate field id and name
+$number->generateField('model', 'field');
+```
+
+## Setting Attributes
+
+Use the provided methods to set specific attributes for the a element.
+
+```php
+// setting class attribute
+$number->class('container');
+```
+
+Or, use the `attributes` method to set multiple attributes at once.
+
+```php
+$number->attributes(['class' => 'container', 'style' => 'background-color: #eee;']);
+```
+
+## Adding value
+
+If you want to include value in the `number` element, use the `value` method.
+
+```php
+$number->value('MyValue');
+```
+
+## Rendering
+
+Generate the `HTML` output using the `render` method, for simple instantiation. 
+
+```php
+$html = $number->render();
+```
+
+Or, use the magic `__toString` method.
+
+```php
+$html = (string) $number;
+```
+
+## Common use cases
+
+Below are examples of common use cases:
+
+```php
+// adding multiple attributes
+$number->class('external')->value('Myvalue');
+
+// using data attributes
+$number->dataAttributes(['analytics' => 'trackClick']);
+```
+
+Explore additional methods for setting various attributes such as `lang`, `name`, `style`, `title`, etc.
+
+## Prefix and Suffix
+
+Use `prefix` and `suffix` methods to add text before and after the `number` tag, respectively.
+
+```php
+// adding a prefix
+$html = $number->value('MyValue')->prefix('MyPrefix')->render();
+
+// adding a suffix
+$html = $number->value('MyValue')->suffix('MySuffix')->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
+$number->template('<div>{tag}</div>');
+```
+
+## Attributes
+
+Refer to the [Attribute Tests](https://github.com/php-forge/html/blob/main/tests/Input/Number/AttributeTest.php) for
+comprehensive examples.
+
+The following methods are available for setting attributes:
+
+| Method             | Description                                                                                     |
+| ------------------ | ----------------------------------------------------------------------------------------------- |
+| `ariaDescribedBy()`| Set the `aria-describedby` attribute.                                                           |
+| `ariaLabel()`      | Set the `aria-label` attribute.                                                                 |
+| `attributes()`     | Set multiple `attributes` at once.                                                              |
+| `autofocus()`      | Set the `autofocus` attribute.                                                                  |
+| `class()`          | Set the `class` attribute.                                                                      |
+| `dataAttributes()` | Set multiple `data-attributes` at once.                                                         |
+| `disabled()`       | Set the `disabled` attribute.                                                                   |
+| `form()`           | Set the `form` attribute.                                                                       |
+| `hidden()`         | Set the `hidden` attribute.                                                                     |
+| `id()`             | Set the `id` attribute.                                                                         |
+| `lang()`           | Set the `lang` attribute.                                                                       |
+| `name()`           | Set the `name` attribute.                                                                       |
+| `placeholder()`    | Set the `placeholder` attribute.                                                                |
+| `readOnly()`       | Set the `readonly` attribute.                                                                   |
+| `style()`          | Set the `style` attribute.                                                                      |
+| `tabIndex()`       | Set the `tabindex` attribute.                                                                   |
+| `title()`          | Set the `title` attribute.                                                                      |
+| `value()`          | Set the `value` attribute.                                                                      |
+
+## Custom methods
+
+Refer to the [Custom Methods Tests](https://github.com/php-forge/html/blob/main/tests/Input/Number/CustomMethodTest.php) 
+for comprehensive examples.
+
+The following methods are available for customizing the `HTML` output:
+
+| Method                       | Description                                                                           |
+| ---------------------------- | ------------------------------------------------------------------------------------- |
+| `generateField()`           | Generate the field id and name for the `HTML` output.                                  |
+| `prefix()`                   | Add text before the `textarea` 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 `label` 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 `HTML` output.                                               |
+| `widget()`                   | Instantiates the `Number::class`.                                                      |
+
+## Validate methods
+
+Refer to the [Validate Tests](https://github.com/php-forge/html/blob/main/tests/Input/Number/ValidateTest.php)
+for comprehensive examples.
+
+| Method      | Description                                                                                            |
+| ----------- | ------------------------------------------------------------------------------------------------------ |
+| `max()`     | Set the `max` attribute.                                                                               |
+| `min()`     | Set the `min` attribute.                                                                               |
+| `step()`    | Set the `step` attribute.                                                                              |
+| `required()`| Set the `required` attribute.                                                                          |
diff --git a/docs/form/input/Time.md b/docs/form/input/Time.md
@@ -79,7 +79,7 @@ Explore additional methods for setting various attributes such as `lang`, `name`
 
 ## Prefix and Suffix
 
-Use `prefix` and `suffix` methods to add text before and after the `week` tag, respectively.
+Use `prefix` and `suffix` methods to add text before and after the `time` tag, respectively.
 
 ```php
 // adding a prefix

diff --git a/tests/Input/Number/AttributeTest.php b/tests/Input/Number/AttributeTest.php
@@ -153,26 +153,6 @@ public function testLang(): void
         );
     }
 
-    public function testMax(): void
-    {
-        Assert::equalsWithoutLE(
-            <<<HTML
-            <input id="number-6582f2d099e8b" type="number" max="value">
-            HTML,
-            Number::widget()->id('number-6582f2d099e8b')->max('value')->render()
-        );
-    }
-
-    public function testMin(): void
-    {
-        Assert::equalsWithoutLE(
-            <<<HTML
-            <input id="number-6582f2d099e8b" type="number" min="value">
-            HTML,
-            Number::widget()->id('number-6582f2d099e8b')->min('value')->render()
-        );
-    }
-
     public function testName(): void
     {
         Assert::equalsWithoutLE(
@@ -203,36 +183,6 @@ public function testReadonly(): void
         );
     }
 
-    public function testRender(): void
-    {
-        Assert::equalsWithoutLE(
-            <<<HTML
-            <input id="number-6582f2d099e8b" type="number">
-            HTML,
-            Number::widget()->id('number-6582f2d099e8b')->render()
-        );
-    }
-
-    public function testRequired(): void
-    {
-        Assert::equalsWithoutLE(
-            <<<HTML
-            <input id="number-6582f2d099e8b" type="number" required>
-            HTML,
-            Number::widget()->id('number-6582f2d099e8b')->required()->render()
-        );
-    }
-
-    public function testStep(): void
-    {
-        Assert::equalsWithoutLE(
-            <<<HTML
-            <input id="number-6582f2d099e8b" type="number" step="1">
-            HTML,
-            Number::widget()->id('number-6582f2d099e8b')->step(1)->render()
-        );
-    }
-
     public function testStyle(): void
     {
         Assert::equalsWithoutLE(

diff --git a/tests/Input/Number/CustomMethodTest.php b/tests/Input/Number/CustomMethodTest.php
@@ -101,6 +101,16 @@ public function testPrefixContainerTag(): void
         );
     }
 
+    public function testRender(): void
+    {
+        Assert::equalsWithoutLE(
+            <<<HTML
+            <input id="number-6582f2d099e8b" type="number">
+            HTML,
+            Number::widget()->id('number-6582f2d099e8b')->render()
+        );
+    }
+
     public function testSuffix(): void
     {
         Assert::equalsWithoutLE(

diff --git a/tests/Input/Number/ValidatorTest.php b/tests/Input/Number/ValidatorTest.php
@@ -0,0 +1,55 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PHPForge\Html\Tests\Input\Number;
+
+use PHPForge\Html\Input\Number;
+use PHPForge\Support\Assert;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * @psalm-suppress PropertyNotSetInConstructor
+ */
+final class ValidatorTest extends TestCase
+{
+    public function testMax(): void
+    {
+        Assert::equalsWithoutLE(
+            <<<HTML
+            <input id="number-6582f2d099e8b" type="number" max="value">
+            HTML,
+            Number::widget()->id('number-6582f2d099e8b')->max('value')->render()
+        );
+    }
+
+    public function testMin(): void
+    {
+        Assert::equalsWithoutLE(
+            <<<HTML
+            <input id="number-6582f2d099e8b" type="number" min="value">
+            HTML,
+            Number::widget()->id('number-6582f2d099e8b')->min('value')->render()
+        );
+    }
+
+    public function testRequired(): void
+    {
+        Assert::equalsWithoutLE(
+            <<<HTML
+            <input id="number-6582f2d099e8b" type="number" required>
+            HTML,
+            Number::widget()->id('number-6582f2d099e8b')->required()->render()
+        );
+    }
+
+    public function testStep(): void
+    {
+        Assert::equalsWithoutLE(
+            <<<HTML
+            <input id="number-6582f2d099e8b" type="number" step="1">
+            HTML,
+            Number::widget()->id('number-6582f2d099e8b')->step(1)->render()
+        );
+    }
+}