Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
0.00% covered (danger)
0.00%
0 / 14
0.00% covered (danger)
0.00%
0 / 8
 CRAP
0.00% covered (danger)
0.00%
0 / 1
Select
0.00% covered (danger)
0.00%
0 / 14
0.00% covered (danger)
0.00%
0 / 8
 72
0.00% covered (danger)
0.00%
0 / 1
 __construct
0.00% covered (danger)
0.00%
0 / 7
0.00% covered (danger)
0.00%
0 / 1
 2
 getId
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 getOptions
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 getOptGroups
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 getAttributes
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 getSelectedOption
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 isDisabled
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 getHtml
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
1<?php
2/**
3 * Select.php
4 *
5 * This file is part of the Codex design system, the official design system for Wikimedia projects.
6 * It contains the definition and implementation of the `Select` class, responsible for managing
7 * the behavior and properties of the corresponding component.
8 *
9 * @category Component
10 * @package  Codex\Component
11 * @since    0.1.0
12 * @author   Doğu Abaris <abaris@null.net>
13 * @license  https://www.gnu.org/copyleft/gpl.html GPL-2.0-or-later
14 * @link     https://doc.wikimedia.org/codex/main/ Codex Documentation
15 */
16
17namespace Wikimedia\Codex\Component;
18
19use Wikimedia\Codex\Renderer\SelectRenderer;
20
21/**
22 * Select
23 *
24 * This class is part of the Codex PHP library and is responsible for
25 * representing an immutable object. It is primarily intended for use
26 * with a builder class to construct its instances.
27 *
28 * @category Component
29 * @package  Codex\Component
30 * @since    0.1.0
31 * @author   Doğu Abaris <abaris@null.net>
32 * @license  https://www.gnu.org/copyleft/gpl.html GPL-2.0-or-later
33 * @link     https://doc.wikimedia.org/codex/main/ Codex Documentation
34 */
35class Select {
36
37    /**
38     * The ID for the select element.
39     */
40    private string $id;
41
42    /**
43     * The options available in the select dropdown.
44     */
45    private array $options;
46
47    /**
48     * The optGroups that group options under labels in the select dropdown.
49     */
50    private array $optGroups;
51
52    /**
53     * The selected option value.
54     */
55    private ?string $selectedOption;
56
57    /**
58     * Additional HTML attributes for the `<select>` element.
59     */
60    private array $attributes;
61
62    /**
63     * Indicates if the select element is disabled.
64     */
65    private bool $disabled;
66
67    /**
68     * The renderer instance used to render the select.
69     */
70    private SelectRenderer $renderer;
71
72    /**
73     * Constructor for the Select component.
74     *
75     * @param string $id The ID for the select element.
76     * @param array $options An array of options for the select element.
77     * @param array $optGroups An array of optGroups for grouping options.
78     * @param string|null $selectedOption The value of the selected option, if any.
79     * @param array $attributes Additional HTML attributes for the select element.
80     * @param bool $disabled Indicates whether the select element is disabled.
81     * @param SelectRenderer $renderer The renderer to use for rendering the select element.
82     */
83    public function __construct(
84        string $id,
85        array $options,
86        array $optGroups,
87        ?string $selectedOption,
88        array $attributes,
89        bool $disabled,
90        SelectRenderer $renderer
91    ) {
92        $this->id = $id;
93        $this->options = $options;
94        $this->optGroups = $optGroups;
95        $this->selectedOption = $selectedOption;
96        $this->attributes = $attributes;
97        $this->disabled = $disabled;
98        $this->renderer = $renderer;
99    }
100
101    /**
102     * Get the Select's HTML ID attribute.
103     *
104     * This method returns the ID assigned to the select element, which is used
105     * for identifying the select component in the HTML document.
106     *
107     * @since 0.1.0
108     * @return string The ID of the Select element.
109     */
110    public function getId(): string {
111        return $this->id;
112    }
113
114    /**
115     * Get the options for the select element.
116     *
117     * This method returns an associative array where the keys are the option values
118     * and the values are the display text shown to the user.
119     *
120     * @since 0.1.0
121     * @return array The associative array of options for the select element.
122     */
123    public function getOptions(): array {
124        return $this->options;
125    }
126
127    /**
128     * Get the optGroups for the select element.
129     *
130     * This method returns an associative array of optGroups, where each key is a label for a group
131     * and the value is an array of options within that group.
132     *
133     * @since 0.1.0
134     * @return array The associative array of optGroups for the select element.
135     */
136    public function getOptGroups(): array {
137        return $this->optGroups;
138    }
139
140    /**
141     * Get the additional HTML attributes for the `<select>` element.
142     *
143     * This method returns an associative array of custom HTML attributes that are applied to the `<select>` element,
144     * such as `id`, `data-*`, `aria-*`, or any other valid attributes.
145     *
146     * @since 0.1.0
147     * @return array The additional attributes as an array.
148     */
149    public function getAttributes(): array {
150        return $this->attributes;
151    }
152
153    /**
154     * Get the currently selected option value.
155     *
156     * This method returns the value of the currently selected option in the select element.
157     *
158     * @since 0.1.0
159     * @return string|null The value of the currently selected option, or null if no option is selected.
160     */
161    public function getSelectedOption(): ?string {
162        return $this->selectedOption;
163    }
164
165    /**
166     * Check if the select element is disabled.
167     *
168     * This method returns a boolean value indicating whether the select element is disabled.
169     * If true, the `disabled` attribute is present on the `<select>` element.
170     *
171     * @since 0.1.0
172     * @return bool True if the select element is disabled, false otherwise.
173     */
174    public function isDisabled(): bool {
175        return $this->disabled;
176    }
177
178    /**
179     * Get the component's HTML representation.
180     *
181     * This method generates the HTML markup for the component, incorporating relevant properties
182     * and any additional attributes. The component is structured using appropriate HTML elements
183     * as defined by the implementation.
184     *
185     * @since 0.1.0
186     * @return string The generated HTML string for the component.
187     */
188    public function getHtml(): string {
189        return $this->renderer->render( $this );
190    }
191}