Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
0.00% covered (danger)
0.00%
0 / 17
0.00% covered (danger)
0.00%
0 / 11
 CRAP
0.00% covered (danger)
0.00%
0 / 1
ProgressBar
0.00% covered (danger)
0.00%
0 / 17
0.00% covered (danger)
0.00%
0 / 11
 156
0.00% covered (danger)
0.00%
0 / 1
 __construct
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
 getLabel
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 isInline
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
 setId
0.00% covered (danger)
0.00%
0 / 2
0.00% covered (danger)
0.00%
0 / 1
 2
 setLabel
0.00% covered (danger)
0.00%
0 / 2
0.00% covered (danger)
0.00%
0 / 1
 2
 setInline
0.00% covered (danger)
0.00%
0 / 2
0.00% covered (danger)
0.00%
0 / 1
 2
 setDisabled
0.00% covered (danger)
0.00%
0 / 2
0.00% covered (danger)
0.00%
0 / 1
 2
 setAttributes
0.00% covered (danger)
0.00%
0 / 3
0.00% covered (danger)
0.00%
0 / 1
 6
1<?php
2declare( strict_types = 1 );
3
4/**
5 * ProgressBar.php
6 *
7 * This file is part of the Codex design system, the official design system for Wikimedia projects.
8 * It contains the definition and implementation of the `ProgressBar` class, responsible for managing
9 * the behavior and properties of the corresponding component.
10 *
11 * @category Component
12 * @package  Codex\Component
13 * @since    0.1.0
14 * @author   Doğu Abaris <abaris@null.net>
15 * @license  https://www.gnu.org/copyleft/gpl.html GPL-2.0-or-later
16 * @link     https://doc.wikimedia.org/codex/main/ Codex Documentation
17 */
18
19namespace Wikimedia\Codex\Component;
20
21use Wikimedia\Codex\Contract\Component;
22use Wikimedia\Codex\Renderer\ProgressBarRenderer;
23
24/**
25 * ProgressBar
26 *
27 * @category Component
28 * @package  Codex\Component
29 * @since    0.1.0
30 * @author   Doğu Abaris <abaris@null.net>
31 * @license  https://www.gnu.org/copyleft/gpl.html GPL-2.0-or-later
32 * @link     https://doc.wikimedia.org/codex/main/ Codex Documentation
33 */
34class ProgressBar extends Component {
35    private string $id = '';
36
37    public function __construct(
38        ProgressBarRenderer $renderer,
39        private string $label,
40        private bool $inline,
41        private bool $disabled,
42        private array $attributes
43    ) {
44        parent::__construct( $renderer );
45    }
46
47    /**
48     * Get the ProgressBar's HTML ID attribute.
49     *
50     * This method returns the ID assigned to the progress bar element, which is used
51     * for identifying the progress bar in the HTML document.
52     *
53     * @since 0.1.0
54     * @return string The ID of the ProgressBar.
55     */
56    public function getId(): string {
57        return $this->id;
58    }
59
60    /**
61     * Get the ARIA label for the progress bar.
62     *
63     * This method returns the ARIA label used for the progress bar, which is important for accessibility.
64     * The label provides a descriptive name for the progress bar, helping users with assistive technologies
65     * to understand its purpose.
66     *
67     * @since 0.1.0
68     * @return string The ARIA label for the progress bar.
69     */
70    public function getLabel(): string {
71        return $this->label;
72    }
73
74    /**
75     * Get whether the progress bar is inline.
76     *
77     * This method returns a boolean value indicating whether the progress bar is the smaller, inline variant.
78     *
79     * @since 0.1.0
80     * @return bool True if the progress bar is inline, false otherwise.
81     */
82    public function isInline(): bool {
83        return $this->inline;
84    }
85
86    /**
87     * Get whether the progress bar is disabled.
88     *
89     * This method returns a boolean value indicating whether the progress bar is disabled.
90     *
91     * @since 0.1.0
92     * @return bool True if the progress bar is disabled, false otherwise.
93     */
94    public function isDisabled(): bool {
95        return $this->disabled;
96    }
97
98    /**
99     * Get the additional HTML attributes for the outer `<div>` element.
100     *
101     * This method returns an associative array of HTML attributes that are applied to the outer `<div>` element of the
102     * progress bar. These attributes can include `id`, `data-*`, `aria-*`, or any other valid HTML attributes.
103     *
104     * @since 0.1.0
105     * @return array The additional attributes as an array.
106     */
107    public function getAttributes(): array {
108        return $this->attributes;
109    }
110
111    /**
112     * Set the ProgressBar's HTML ID attribute.
113     *
114     * @deprecated Use setAttributes() to set the ID
115     * @since 0.1.0
116     * @param string $id The ID for the ProgressBar element.
117     * @return $this
118     */
119    public function setId( string $id ): self {
120        $this->id = $id;
121
122        return $this;
123    }
124
125    /**
126     * Set the ARIA label for the progress bar.
127     *
128     * This method sets the ARIA label for the progress bar, which is important for accessibility.
129     * The label provides a descriptive name for the progress bar, helping users with assistive technologies
130     * to understand its purpose.
131     *
132     * Example usage:
133     *
134     *     $progressBar->setLabel('File upload progress');
135     *
136     * @since 0.1.0
137     * @param string $label The ARIA label for the progress bar.
138     * @return $this Returns the ProgressBar instance for method chaining.
139     */
140    public function setLabel( string $label ): self {
141        $this->label = $label;
142
143        return $this;
144    }
145
146    /**
147     * Set whether the progress bar should be displayed inline.
148     *
149     * This method sets the `inline` property, which controls whether the progress bar should be
150     * displayed as a smaller, inline variant. The inline variant is typically used in compact spaces.
151     *
152     * Example usage:
153     *
154     *     $progressBar->setInline(true);
155     *
156     * @since 0.1.0
157     * @param bool $inline Whether the progress bar should be displayed inline.
158     * @return $this Returns the ProgressBar instance for method chaining.
159     */
160    public function setInline( bool $inline ): self {
161        $this->inline = $inline;
162
163        return $this;
164    }
165
166    /**
167     * Set whether the progress bar is disabled.
168     *
169     * This method sets the `disabled` property, which controls whether the progress bar is disabled.
170     * A disabled progress bar may be visually different and indicate to the user that it is inactive.
171     *
172     * Example usage:
173     *
174     *     $progressBar->setDisabled(true);
175     *
176     * @since 0.1.0
177     * @param bool $disabled Whether the progress bar is disabled.
178     * @return $this Returns the ProgressBar instance for method chaining.
179     */
180    public function setDisabled( bool $disabled ): self {
181        $this->disabled = $disabled;
182
183        return $this;
184    }
185
186    /**
187     * Set additional HTML attributes for the outer `<div>` element.
188     *
189     * This method allows custom HTML attributes to be added to the outer `<div>` element of the progress bar,
190     * such as `id`, `data-*`, `aria-*`, or any other valid attributes. These attributes can be used to
191     * enhance accessibility or integrate with JavaScript.
192     *
193     * The values of these attributes are automatically escaped to prevent XSS vulnerabilities.
194     *
195     * Example usage:
196     *
197     *     $progressBar->setAttributes([
198     *         'id' => 'file-upload-progress',
199     *         'data-upload' => 'true',
200     *     ]);
201     *
202     * @since 0.1.0
203     * @param array $attributes An associative array of HTML attributes.
204     * @return $this Returns the ProgressBar instance for method chaining.
205     */
206    public function setAttributes( array $attributes ): self {
207        foreach ( $attributes as $key => $value ) {
208            $this->attributes[$key] = $value;
209        }
210        return $this;
211    }
212}