Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
86.36% covered (warning)
86.36%
19 / 22
71.43% covered (warning)
71.43%
5 / 7
 CRAP
0.00% covered (danger)
0.00%
0 / 1
InfoChipBuilder
86.36% covered (warning)
86.36%
19 / 22
71.43% covered (warning)
71.43%
5 / 7
 9.21
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
 setText
75.00% covered (warning)
75.00%
3 / 4
0.00% covered (danger)
0.00%
0 / 1
 2.06
 setStatus
100.00% covered (success)
100.00%
2 / 2
100.00% covered (success)
100.00%
1 / 1
 1
 setIcon
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 * InfoChipBuilder.php
4 *
5 * This file is part of the Codex design system, the official design system
6 * for Wikimedia projects. It provides the `InfoChip` class, a builder for constructing
7 * non-interactive information chip components using the Codex design system.
8 *
9 * An InfoChip is a non-interactive item that provides information.
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 InvalidArgumentException;
22use Wikimedia\Codex\Component\InfoChip;
23use Wikimedia\Codex\Renderer\InfoChipRenderer;
24
25/**
26 * InfoChipBuilder
27 *
28 * This class implements the builder pattern to construct instances of InfoChip.
29 * It provides a fluent interface for setting various properties and building the
30 * final immutable object with predefined configurations and immutability.
31 *
32 * @category Builder
33 * @package  Codex\Builder
34 * @since    0.1.0
35 * @author   Doğu Abaris <abaris@null.net>
36 * @license  https://www.gnu.org/copyleft/gpl.html GPL-2.0-or-later
37 * @link     https://doc.wikimedia.org/codex/main/ Codex Documentation
38 */
39class InfoChipBuilder {
40
41    /**
42     * The ID for the InfoChip.
43     */
44    protected string $id = '';
45
46    /**
47     * The text displayed inside the InfoChip.
48     */
49    protected string $text = '';
50
51    /**
52     * The status type, determines chip's visual style. Options include 'notice', 'warning', 'error', and 'success'.
53     */
54    protected string $status = '';
55
56    /**
57     * The CSS class for a custom icon used in the InfoChip, applicable only for the 'notice' status.
58     */
59    protected ?string $icon = null;
60
61    /**
62     * Additional HTML attributes for the outer `<div>` element of the InfoChip.
63     */
64    protected array $attributes = [];
65
66    /**
67     * The renderer instance used to render the infoChip.
68     */
69    protected InfoChipRenderer $renderer;
70
71    /**
72     * Constructor for the InfoChipBuilder class.
73     *
74     * @param InfoChipRenderer $renderer The renderer to use for rendering the info chip.
75     */
76    public function __construct( InfoChipRenderer $renderer ) {
77        $this->renderer = $renderer;
78    }
79
80    /**
81     * Set the InfoChip's HTML ID attribute.
82     *
83     * @since 0.1.0
84     * @param string $id The ID for the InfoChip element.
85     * @return $this
86     */
87    public function setId( string $id ): self {
88        $this->id = $id;
89
90        return $this;
91    }
92
93    /**
94     * Set the text content for the info chip.
95     *
96     * This method specifies the text that will be displayed inside the info chip.
97     * The text provides the primary information that the chip conveys.
98     *
99     * @since 0.1.0
100     * @param string $text The text to be displayed inside the info chip.
101     * @return $this Returns the InfoChip instance for method chaining.
102     */
103    public function setText( string $text ): self {
104        if ( trim( $text ) === '' ) {
105            throw new InvalidArgumentException( 'InfoChip text cannot be empty.' );
106        }
107        $this->text = $text;
108
109        return $this;
110    }
111
112    /**
113     * Set the status type for the info chip.
114     *
115     * This method sets the visual style of the info chip based on its status.
116     * The status can be one of the following:
117     * - 'notice': For general information.
118     * - 'warning': For cautionary information.
119     * - 'error': For error messages.
120     * - 'success': For success messages.
121     *
122     * The status type is applied as a CSS class (`cdx-info-chip--{status}`) to the chip element.
123     *
124     * @since 0.1.0
125     * @param string $status The status type (e.g., 'notice', 'warning', 'error', 'success').
126     * @return $this Returns the InfoChip instance for method chaining.
127     */
128    public function setStatus( string $status ): self {
129        $this->status = $status;
130
131        return $this;
132    }
133
134    /**
135     * Set a custom icon for the "notice" status chip.
136     *
137     * This method specifies a CSS class for a custom icon to be displayed inside the chip.
138     * This option is applicable only for chips with the "notice" status.
139     * Chips with other status types (warning, error, success) do not support custom icons and will ignore this setting.
140     *
141     * @since 0.1.0
142     * @param string|null $icon The CSS class for the custom icon, or null to remove the icon.
143     * @return $this Returns the InfoChip instance for method chaining.
144     */
145    public function setIcon( ?string $icon ): self {
146        $this->icon = $icon;
147
148        return $this;
149    }
150
151    /**
152     * Set additional HTML attributes for the outer `<div>` element.
153     *
154     * This method allows custom HTML attributes to be added to the outer `<div>` element of the info chip,
155     * such as `id`, `data-*`, `aria-*`, or any other valid attributes. These attributes can be used to
156     * enhance accessibility or integrate with JavaScript.
157     *
158     * The values of these attributes are automatically escaped to prevent XSS vulnerabilities.
159     *
160     * Example usage:
161     *
162     *     $infoChip->setAttributes([
163     *         'id' => 'info-chip-example',
164     *         'data-category' => 'info',
165     *     ]);
166     *
167     * @since 0.1.0
168     * @param array $attributes An associative array of HTML attributes.
169     * @return $this Returns the InfoChip instance for method chaining.
170     */
171    public function setAttributes( array $attributes ): self {
172        foreach ( $attributes as $key => $value ) {
173            $this->attributes[$key] = $value;
174        }
175        return $this;
176    }
177
178    /**
179     * Build and return the InfoChip component object.
180     * This method constructs the immutable InfoChip object with all the properties set via the builder.
181     *
182     * @since 0.1.0
183     * @return InfoChip The constructed InfoChip.
184     */
185    public function build(): InfoChip {
186        return new InfoChip(
187            $this->id,
188            $this->text,
189            $this->status,
190            $this->icon,
191            $this->attributes,
192            $this->renderer
193        );
194    }
195}