Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
0.00% covered (danger)
0.00%
0 / 22
0.00% covered (danger)
0.00%
0 / 12
 CRAP
0.00% covered (danger)
0.00%
0 / 1
Button
0.00% covered (danger)
0.00%
0 / 22
0.00% covered (danger)
0.00%
0 / 12
 182
0.00% covered (danger)
0.00%
0 / 1
 __construct
0.00% covered (danger)
0.00%
0 / 11
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
 getLabel
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 getAction
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 getWeight
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 getSize
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 getType
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 6
 getIconClass
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 isIconOnly
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
 getAttributes
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 * Button.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 `Button` 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\ButtonRenderer;
20
21/**
22 * Button
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 Button {
36
37    /**
38     * The ID for the button.
39     */
40    private string $id;
41
42    /**
43     * The text label displayed on the button.
44     */
45    private string $label;
46
47    /**
48     * The visual action style of the button (e.g., default, progressive, destructive).
49     */
50    private string $action;
51
52    /**
53     * The size of the button (e.g., medium, large).
54     */
55    private string $size;
56
57    /**
58     * The type of the button (e.g., button, submit, reset).
59     */
60    private string $type;
61
62    /**
63     * The visual prominence of the button (e.g., normal, primary, quiet).
64     */
65    private string $weight;
66
67    /**
68     * The CSS class for an icon, if the button includes one.
69     */
70    private ?string $iconClass;
71
72    /**
73     * Indicates if the button is icon-only (no text).
74     */
75    private bool $iconOnly;
76
77    /**
78     * Indicates if the button is disabled.
79     */
80    private bool $disabled;
81
82    /**
83     * Additional HTML attributes for the button element.
84     */
85    private array $attributes;
86
87    /**
88     * The renderer instance used to render the button.
89     */
90    private ButtonRenderer $renderer;
91
92    /**
93     * Constructor for the Button component.
94     *
95     * Initializes a Button instance with the specified properties.
96     *
97     * @param string $id The ID for the button.
98     * @param string $label The text label displayed on the button.
99     * @param string $action The visual action style of the button.
100     * @param string $size The size of the button.
101     * @param string $type The type of the button.
102     * @param string $weight The visual prominence of the button.
103     * @param string|null $iconClass The CSS class for an icon, if any.
104     * @param bool $iconOnly Indicates if the button is icon-only.
105     * @param bool $disabled Indicates if the button is disabled.
106     * @param array $attributes Additional HTML attributes for the button element.
107     * @param ButtonRenderer $renderer The renderer to use for rendering the button.
108     */
109    public function __construct(
110        string $id,
111        string $label,
112        string $action,
113        string $size,
114        string $type,
115        string $weight,
116        ?string $iconClass,
117        bool $iconOnly,
118        bool $disabled,
119        array $attributes,
120        ButtonRenderer $renderer
121    ) {
122        $this->id = $id;
123        $this->label = $label;
124        $this->action = $action;
125        $this->size = $size;
126        $this->type = $type;
127        $this->weight = $weight;
128        $this->iconClass = $iconClass;
129        $this->iconOnly = $iconOnly;
130        $this->disabled = $disabled;
131        $this->attributes = $attributes;
132        $this->renderer = $renderer;
133    }
134
135    /**
136     * Get the button's HTML ID attribute.
137     *
138     * This method returns the ID that is assigned to the button element.
139     * The ID is useful for targeting the button with JavaScript, CSS, or accessibility features.
140     *
141     * @since 0.1.0
142     * @return string The ID of the button element.
143     */
144    public function getId(): string {
145        return $this->id;
146    }
147
148    /**
149     * Get the label displayed on the button.
150     *
151     * This method returns the text label that is displayed on the button. The label provides context
152     * to users about the button's action, ensuring that it is understandable and accessible.
153     *
154     * @since 0.1.0
155     * @return string The label of the button.
156     */
157    public function getLabel(): string {
158        return $this->label;
159    }
160
161    /**
162     * Get the action style of the button.
163     *
164     * This method returns the action style of the button, indicating the visual style
165     * that reflects the nature of the action it represents (e.g., 'default', 'progressive', 'destructive').
166     *
167     * @since 0.1.0
168     * @return string The action style of the button.
169     */
170    public function getAction(): string {
171        return $this->action;
172    }
173
174    /**
175     * Get the weight style of the button.
176     *
177     * This method returns the weight style of the button, which indicates its visual prominence
178     * (e.g., 'normal', 'primary', 'quiet').
179     *
180     * @since 0.1.0
181     * @return string The weight style of the button.
182     */
183    public function getWeight(): string {
184        return $this->weight;
185    }
186
187    /**
188     * Get the size of the button.
189     *
190     * This method returns the size of the button, determining whether it is 'medium' or 'large'.
191     *
192     * @since 0.1.0
193     * @return string The size of the button.
194     */
195    public function getSize(): string {
196        return $this->size;
197    }
198
199    /**
200     * Get the type of the button.
201     *
202     * This method returns the type of the button, determining whether it is 'button', 'submit', or 'reset'.
203     *
204     * @since 0.1.0
205     * @return string The type of the button.
206     */
207    public function getType(): string {
208        return $this->type ?: 'button';
209    }
210
211    /**
212     * Get the icon class for the button.
213     *
214     * This method returns the CSS class used for the icon displayed inside the button.
215     * The icon is an additional visual element that can be included in the button to enhance usability.
216     *
217     * @since 0.1.0
218     * @return string|null The CSS class for the icon, or null if no icon is set.
219     */
220    public function getIconClass(): ?string {
221        return $this->iconClass;
222    }
223
224    /**
225     * Check if the button is icon-only.
226     *
227     * This method returns a boolean value indicating whether the button is icon-only (i.e., displays only an icon
228     * without any text). This is useful in scenarios where space is limited.
229     *
230     * @since 0.1.0
231     * @return bool True if the button is icon-only, false otherwise.
232     */
233    public function isIconOnly(): bool {
234        return $this->iconOnly;
235    }
236
237    /**
238     * Check if the button is disabled.
239     *
240     * This method returns a boolean value indicating whether the button is disabled.
241     *
242     * @since 0.1.0
243     * @return bool True if the button is disabled, false otherwise.
244     */
245    public function isDisabled(): bool {
246        return $this->disabled;
247    }
248
249    /**
250     * Retrieve additional HTML attributes for the button element.
251     *
252     * This method returns an associative array of additional HTML attributes that will be applied
253     * to the <button> element. These attributes can be used to enhance customization, improve accessibility,
254     * and facilitate JavaScript integration.
255     *
256     * @since 0.1.0
257     * @return array The additional attributes as an array.
258     */
259    public function getAttributes(): array {
260        return $this->attributes;
261    }
262
263    /**
264     * Get the component's HTML representation.
265     *
266     * This method generates the HTML markup for the component, incorporating relevant properties
267     * and any additional attributes. The component is structured using appropriate HTML elements
268     * as defined by the implementation.
269     *
270     * @since 0.1.0
271     * @return string The generated HTML string for the component.
272     */
273    public function getHtml(): string {
274        return $this->renderer->render( $this );
275    }
276}