Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
0.00% covered (danger)
0.00%
0 / 24
0.00% covered (danger)
0.00%
0 / 13
 CRAP
0.00% covered (danger)
0.00%
0 / 1
Label
0.00% covered (danger)
0.00%
0 / 24
0.00% covered (danger)
0.00%
0 / 13
 182
0.00% covered (danger)
0.00%
0 / 1
 __construct
0.00% covered (danger)
0.00%
0 / 12
0.00% covered (danger)
0.00%
0 / 1
 2
 getLabelText
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 getInputId
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 isOptional
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 isVisuallyHidden
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 isLegend
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 getDescription
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 getDescriptionId
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
 getIconClass
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
 getId
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 * Label.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 `Label` 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\LabelRenderer;
20
21/**
22 * Label
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 Label {
36
37    /**
38     * The text displayed inside the label.
39     */
40    protected string $labelText;
41
42    /**
43     * The ID of the input/control this label is associated with.
44     */
45    protected string $inputId;
46
47    /**
48     * Whether the associated input field is optional.
49     */
50    protected bool $optional;
51
52    /**
53     * Whether the label should be visually hidden but accessible to screen readers.
54     */
55    protected bool $visuallyHidden;
56
57    /**
58     * Whether the label should be rendered as a `<legend>` element, typically used within a `<fieldset>`.
59     */
60    protected bool $isLegend;
61
62    /**
63     * The description text that provides additional information about the input field.
64     */
65    protected string $description;
66
67    /**
68     * The ID of the description element, useful for the `aria-describedby` attribute.
69     */
70    protected ?string $descriptionId;
71
72    /**
73     * Whether the label is for a disabled field or input.
74     */
75    protected bool $disabled;
76
77    /**
78     * The CSS class for an icon displayed before the label text.
79     */
80    protected ?string $iconClass;
81
82    /**
83     * Additional HTML attributes for the label element.
84     */
85    protected array $attributes;
86
87    /**
88     * The ID attribute for the label.
89     */
90    protected ?string $id;
91
92    /**
93     * The renderer instance used to render the label.
94     */
95    protected LabelRenderer $renderer;
96
97    /**
98     * Constructor for the Label component.
99     *
100     * Initializes a Label instance with the specified properties.
101     *
102     * @param string $labelText The text displayed inside the label.
103     * @param string $inputId The ID of the input/control this label is associated with.
104     * @param bool $optional Indicates whether the associated input field is optional.
105     * @param bool $visuallyHidden Indicates whether the label should be visually hidden.
106     * @param bool $isLegend Indicates if the label should be rendered as a `<legend>` element.
107     * @param string $description The description text for the label.
108     * @param string|null $descriptionId The ID of the description element.
109     * @param bool $disabled Indicates whether the label is for a disabled input.
110     * @param string|null $iconClass The CSS class for an icon before the label text.
111     * @param array $attributes Additional HTML attributes for the label element.
112     * @param string|null $id The ID attribute for the label.
113     * @param LabelRenderer $renderer The renderer to use for rendering the label.
114     */
115    public function __construct(
116        string $labelText,
117        string $inputId,
118        bool $optional,
119        bool $visuallyHidden,
120        bool $isLegend,
121        string $description,
122        ?string $descriptionId,
123        bool $disabled,
124        ?string $iconClass,
125        array $attributes,
126        ?string $id,
127        LabelRenderer $renderer
128    ) {
129        $this->labelText = $labelText;
130        $this->inputId = $inputId;
131        $this->optional = $optional;
132        $this->visuallyHidden = $visuallyHidden;
133        $this->isLegend = $isLegend;
134        $this->description = $description;
135        $this->descriptionId = $descriptionId;
136        $this->disabled = $disabled;
137        $this->iconClass = $iconClass;
138        $this->attributes = $attributes;
139        $this->id = $id;
140        $this->renderer = $renderer;
141    }
142
143    /**
144     * Get the text displayed inside the label.
145     *
146     * This method returns the text that is displayed inside the label. The label text provides
147     * a descriptive title for the associated input field.
148     *
149     * @since 0.1.0
150     * @return string The text of the label.
151     */
152    public function getLabelText(): string {
153        return $this->labelText;
154    }
155
156    /**
157     * Get the ID of the input/control this label is associated with.
158     *
159     * This method returns the ID of the input element that this label is associated with. The ID
160     * is crucial for linking the label to its corresponding input, ensuring accessibility.
161     *
162     * @since 0.1.0
163     * @return string The ID of the input element.
164     */
165    public function getInputId(): string {
166        return $this->inputId;
167    }
168
169    /**
170     * Check if the associated input field is optional.
171     *
172     * This method returns a boolean indicating whether the associated input field is optional.
173     * If true, an "(optional)" flag is typically displayed next to the label text.
174     *
175     * @since 0.1.0
176     * @return bool True if the input field is optional, false otherwise.
177     */
178    public function isOptional(): bool {
179        return $this->optional;
180    }
181
182    /**
183     * Check if the label is visually hidden but accessible to screen readers.
184     *
185     * This method returns a boolean indicating whether the label is visually hidden
186     * while still being accessible to screen readers. This is useful for forms where
187     * labels need to be accessible but not displayed.
188     *
189     * @since 0.1.0
190     * @return bool True if the label is visually hidden, false otherwise.
191     */
192    public function isVisuallyHidden(): bool {
193        return $this->visuallyHidden;
194    }
195
196    /**
197     * Check if the label is rendered as a `<legend>` element.
198     *
199     * This method returns a boolean indicating whether the label is rendered as a `<legend>`
200     * element, typically used within a `<fieldset>` for grouping related inputs.
201     *
202     * @since 0.1.0
203     * @return bool True if the label is rendered as a `<legend>`, false otherwise.
204     */
205    public function isLegend(): bool {
206        return $this->isLegend;
207    }
208
209    /**
210     * Get the description text associated with the label.
211     *
212     * This method returns the description text that provides additional information about the
213     * input field. The description is linked to the input via the `aria-describedby` attribute.
214     *
215     * @since 0.1.0
216     * @return string The description text for the label.
217     */
218    public function getDescription(): string {
219        return $this->description;
220    }
221
222    /**
223     * Get the ID of the description element.
224     *
225     * This method returns the ID of the description element, which is useful for associating
226     * the description with an input via the `aria-describedby` attribute.
227     *
228     * @since 0.1.0
229     * @return string|null The ID for the description element, or null if not set.
230     */
231    public function getDescriptionId(): ?string {
232        return $this->descriptionId;
233    }
234
235    /**
236     * Check if the label is for a disabled field or input.
237     *
238     * This method returns a boolean indicating whether the label is associated with a disabled
239     * input field, applying the appropriate styles.
240     *
241     * @since 0.1.0
242     * @return bool True if the label is for a disabled input, false otherwise.
243     */
244    public function isDisabled(): bool {
245        return $this->disabled;
246    }
247
248    /**
249     * Get the icon class used before the label text.
250     *
251     * This method returns the CSS class for the icon displayed before the label text, if applicable.
252     * The icon enhances the visual appearance of the label.
253     *
254     * @since 0.1.0
255     * @return string|null The CSS class for the icon, or null if no icon is set.
256     */
257    public function getIconClass(): ?string {
258        return $this->iconClass;
259    }
260
261    /**
262     * Get the additional HTML attributes for the label element.
263     *
264     * This method returns an associative array of custom HTML attributes that are applied
265     * to the label element. These attributes can be used for customization or accessibility.
266     *
267     * @since 0.1.0
268     * @return array The additional attributes as an array.
269     */
270    public function getAttributes(): array {
271        return $this->attributes;
272    }
273
274    /**
275     * Get the ID of the label element.
276     *
277     * @since 0.1.0
278     * @return string|null The ID of the label, or null if not set.
279     */
280    public function getId(): ?string {
281        return $this->id;
282    }
283
284    /**
285     * Get the component's HTML representation.
286     *
287     * This method generates the HTML markup for the component, incorporating relevant properties
288     * and any additional attributes. The component is structured using appropriate HTML elements
289     * as defined by the implementation.
290     *
291     * @since 0.1.0
292     * @return string The generated HTML string for the component.
293     */
294    public function getHtml(): string {
295        return $this->renderer->render( $this );
296    }
297}