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