Remove attribute from widgets. (#44)

src/Attribute/Aria/HasAriaDescribedBy.php

@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PHPForge\Html\Attribute\Aria;
+
+/**
+ * Is used by widgets which have an aria-describedby attribute.
+ */
+trait HasAriaDescribedBy
+{
+    /**
+     * Returns a new instance specifying the element (or elements) that describes the element on which the attribute is
+     * set.
+     *
+     * @param string $value The value of the aria-describedby attribute.
+     *
+     * @link https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-describedby
+     */
+    public function ariaDescribedBy(string $value): static
+    {
+        $new = clone $this;
+        $new->attributes['aria-describedby'] = $value;
+
+        return $new;
+    }
+}

src/Attribute/Aria/HasAriaLabel.php

@@ -0,0 +1,26 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PHPForge\Html\Attribute\Aria;
+
+/**
+ * Is used by widgets which have an aria-label attribute.
+ */
+trait HasAriaLabel
+{
+    /**
+     * Returns a new instance specifying a string value that labels an interactive element.
+     *
+     * @param string $value The value of the aria-label attribute.
+     *
+     * @link https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label
+     */
+    public function ariaLabel(string $value): static
+    {
+        $new = clone $this;
+        $new->attributes['aria-label'] = $value;
+
+        return $new;
+    }
+}

src/Attribute/CanBeAutofocus.php

@@ -0,0 +1,26 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PHPForge\Html\Attribute;
+
+/**
+ * Is used by widgets which have an autofocus attribute.
+ */
+trait CanBeAutofocus
+{
+    /**
+     * Returns a new instance specifying the focus on the control (put cursor into it) when the page loads.
+     *
+     * Only one form element could be in focus at the same time.
+     *
+     * @link https://www.w3.org/TR/html52/sec-forms.html#autofocusing-a-form-control-the-autofocus-attribute
+     */
+    public function autofocus(): static
+    {
+        $new = clone $this;
+        $new->attributes['autofocus'] = true;
+
+        return $new;
+    }
+}

src/Attribute/Custom/HasAttributes.php

@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PHPForge\Html\Attribute\Custom;
+
+use function array_merge;
+
+/**
+ * Is used by widgets which have an attributes.
+ *
+ * @link https://www.w3.org/TR/html52/dom.html#global-attributes
+ * @link https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes
+ */
+trait HasAttributes
+{
+    /**
+     * Returns a new instance specifying the `HTML` attributes.
+     *
+     * @param array $values Attribute values indexed by attribute names.
+     */
+    public function attributes(array $values): static
+    {
+        $new = clone $this;
+        $new->attributes = array_merge($this->attributes, $values);
+
+        return $new;
+    }
+}

src/Attribute/Custom/HasContainer.php

@@ -0,0 +1,73 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PHPForge\Html\Attribute\Custom;
+
+use InvalidArgumentException;
+use PHPForge\Html\Helper\CssClass;
+
+/**
+ * Provides methods to configure the HTML container.
+ */
+trait HasContainer
+{
+    protected bool $container = true;
+    protected array $containerAttributes = [];
+
+    /**
+     * Return new instance specifying when the container its enabled or disabled.
+     *
+     * @param bool $value `true` to enable container, `false` to disable.
+     */
+    public function container(bool $value): static
+    {
+        $new = clone $this;
+        $new->container = $value;
+
+        return $new;
+    }
+
+    /**
+     * Returns a new instance specifying the `HTML` container attributes.
+     *
+     * @param array $values Attribute values indexed by attribute names.
+     */
+    public function containerAttributes(array $values = []): static
+    {
+        $new = clone $this;
+        $new->containerAttributes = $values;
+
+        return $new;
+    }
+
+    /**
+     * Returns a new instance specifying the `CSS` HTML container class name.
+     *
+     * @param string $value The css class name.
+     */
+    public function containerClass(string $value): static
+    {
+        $new = clone $this;
+        CssClass::add($new->containerAttributes, $value);
+
+        return $new;
+    }
+
+    /**
+     * Return new instance specified the tag name for the container element.
+     *
+     * @param string $value The tag name for the container element.
+     */
+    public function containerTag(string $value): static
+    {
+        if ($value === '') {
+            throw new InvalidArgumentException('The container tag must be a non-empty string.');
+        }
+
+        $new = clone $this;
+        $new->containerTag = $value;
+
+        return $new;
+    }
+}

src/Attribute/Custom/HasContent.php

@@ -0,0 +1,34 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PHPForge\Html\Attribute\Custom;
+
+use PHPForge\Html\Helper\Encode;
+use Stringable;
+
+/**
+ * Is used by widgets which have content value.
+ */
+trait HasContent
+{
+    protected string $content = '';
+
+    /**
+     * Returns a new instance specifying the content value of the widget.
+     *
+     * @param string|Stringable $value The content value.
+     * @param bool $encode Whether to encode the content value.
+     */
+    public function content(string|Stringable $value, bool $encode = true): static
+    {
+        if ($encode) {
+            $value = Encode::content($value);
+        }
+
+        $new = clone $this;
+        $new->content = (string) $value;
+
+        return $new;
+    }
+}

src/Attribute/Custom/HasItems.php

@@ -0,0 +1,74 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PHPForge\Html\Attribute\Custom;
+
+/**
+ * Provides methods to configure the data items for the widget.
+ */
+trait HasItems
+{
+    protected array $items = [];
+    protected array $itemsAttributes = [];
+
+    /**
+     * Returns a new instances specifying the data items for the widget.
+     *
+     * The array keys are option values, and the array values are the corresponding option labels. The array can also
+     * be nested (for example, some array values are arrays too). For each sub-array, an option group will be generated
+     * whose label is the key associated with the sub-array.
+     *
+     * Example:
+     * ```php
+     * [
+     *     '1' => 'Santiago',
+     *     '2' => 'Concepcion',
+     *     '3' => 'Chillan',
+     *     '4' => 'Moscu'
+     *     '5' => 'San Petersburg',
+     *     '6' => 'Novosibirsk',
+     *     '7' => 'Ekaterinburgo'
+     * ];
+     * ```
+     *
+     * Example with options groups:
+     * ```php
+     * [
+     *     '1' => [
+     *         '1' => 'Santiago',
+     *         '2' => 'Concepcion',
+     *         '3' => 'Chillan',
+     *     ],
+     *     '2' => [
+     *         '4' => 'Moscu',
+     *         '5' => 'San Petersburg',
+     *         '6' => 'Novosibirsk',
+     *         '7' => 'Ekaterinburgo'
+     *     ],
+     * ];
+     * ```
+     *
+     * @param array $value The option data items.
+     */
+    public function items(array $value = []): static
+    {
+        $new = clone $this;
+        $new->items = $value;
+
+        return $new;
+    }
+
+    /**
+     * Returns a new instances specifying the `HTML` attributes for items.
+     *
+     * @param array $values Attribute values indexed by attribute names.
+     */
+    public function itemsAttributes(array $values = []): static
+    {
+        $new = clone $this;
+        $new->itemsAttributes = $values;
+
+        return $new;
+    }
+}