Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
0.00% covered (danger)
0.00%
0 / 23
0.00% covered (danger)
0.00%
0 / 14
 CRAP
0.00% covered (danger)
0.00%
0 / 1
Message
0.00% covered (danger)
0.00%
0 / 23
0.00% covered (danger)
0.00%
0 / 14
 272
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
 getContent
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
 2
 isInline
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 getHeading
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
 setId
0.00% covered (danger)
0.00%
0 / 2
0.00% covered (danger)
0.00%
0 / 1
 2
 setContent
0.00% covered (danger)
0.00%
0 / 2
0.00% covered (danger)
0.00%
0 / 1
 2
 setType
0.00% covered (danger)
0.00%
0 / 4
0.00% covered (danger)
0.00%
0 / 1
 6
 setInline
0.00% covered (danger)
0.00%
0 / 2
0.00% covered (danger)
0.00%
0 / 1
 2
 setHeading
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 * Message.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 `Message` 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 InvalidArgumentException;
22use Wikimedia\Codex\Contract\Component;
23use Wikimedia\Codex\Renderer\MessageRenderer;
24use Wikimedia\Codex\Traits\ContentSetter;
25
26/**
27 * Message
28 *
29 * @category Component
30 * @package  Codex\Component
31 * @since    0.1.0
32 * @author   Doğu Abaris <abaris@null.net>
33 * @license  https://www.gnu.org/copyleft/gpl.html GPL-2.0-or-later
34 * @link     https://doc.wikimedia.org/codex/main/ Codex Documentation
35 */
36class Message extends Component {
37    use ContentSetter;
38
39    private string $id = '';
40
41    /**
42     * The valid status types for messages.
43     */
44    public const STATUS_TYPES = [
45        'notice',
46        'warning',
47        'error',
48        'success',
49    ];
50
51    public function __construct(
52        MessageRenderer $renderer,
53        private string|HtmlSnippet $content,
54        private string $type,
55        private bool $inline,
56        private string|HtmlSnippet $heading,
57        private string $iconClass,
58        private array $attributes
59    ) {
60        parent::__construct( $renderer );
61    }
62
63    /**
64     * Get the Message's HTML ID attribute.
65     *
66     * This method returns the ID assigned to the Message element.
67     * The ID can be used for targeting the message with JavaScript, CSS, or for accessibility purposes.
68     *
69     * @since 0.1.0
70     * @return string The ID of the Message element.
71     */
72    public function getId(): string {
73        return $this->id;
74    }
75
76    /**
77     * Get the content of the message box.
78     *
79     * This method returns the text or HTML content displayed inside the message box.
80     * The content provides the primary feedback or information that the message conveys to the user.
81     *
82     * @since 0.1.0
83     * @return string|HtmlSnippet The content of the message box.
84     */
85    public function getContent(): string|HtmlSnippet {
86        return $this->content;
87    }
88
89    /**
90     * Get the type of the message box.
91     *
92     * This method returns the type of the message, which determines its visual style.
93     * The type can be one of the following: 'notice', 'warning', 'error', 'success'.
94     *
95     * @since 0.1.0
96     * @return string The type of the message box.
97     */
98    public function getType(): string {
99        return $this->type;
100    }
101
102    /**
103     * Check if the message box is displayed inline.
104     *
105     * This method returns a boolean indicating whether the message box is displayed inline,
106     * without additional padding, background color, or border.
107     *
108     * @since 0.1.0
109     * @return bool True if the message box is displayed inline, false otherwise.
110     */
111    public function isInline(): bool {
112        return $this->inline;
113    }
114
115    /**
116     * Get the heading of the message box.
117     *
118     * This method returns the heading text prominently displayed at the top of the message content.
119     * The heading helps to quickly convey the primary purpose or topic of the message.
120     *
121     * @since 0.1.0
122     * @return string|HtmlSnippet The heading text of the message box.
123     */
124    public function getHeading(): string|HtmlSnippet {
125        return $this->heading;
126    }
127
128    /**
129     * Get the CSS class name for the icon.
130     *
131     * This method returns the CSS class name for the icon displayed in the message box,
132     * enhancing the visual representation of the message.
133     *
134     * @since 0.1.0
135     * @return string The CSS class name for the icon.
136     */
137    public function getIconClass(): string {
138        return $this->iconClass;
139    }
140
141    /**
142     * Get the additional HTML attributes for the message box.
143     *
144     * This method returns an associative array of additional HTML attributes that are applied
145     * to the outer `<div>` element of the message box. These attributes can be used to enhance
146     * accessibility or integrate with JavaScript.
147     *
148     * @since 0.1.0
149     * @return array The additional attributes as an array.
150     */
151    public function getAttributes(): array {
152        return $this->attributes;
153    }
154
155    /**
156     * Set the Message's HTML ID attribute.
157     *
158     * @deprecated Use setAttributes() to set the ID
159     * @since 0.1.0
160     * @param string $id The ID for the Message element.
161     * @return $this
162     */
163    public function setId( string $id ): self {
164        $this->id = $id;
165
166        return $this;
167    }
168
169    /**
170     * Set the content of the message.
171     *
172     * @param string|HtmlSnippet $content Text or HTML to be displayed inside the message box.
173     * @return $this Returns the Message instance for method chaining.
174     */
175    public function setContent( string|HtmlSnippet $content ): self {
176        $this->content = $content;
177
178        return $this;
179    }
180
181    /**
182     * Set the type of the message box.
183     *
184     * This method sets the visual style of the message box based on its type.
185     * The type can be one of the following:
186     * - 'notice': For general information.
187     * - 'warning': For cautionary information.
188     * - 'error': For error messages.
189     * - 'success': For success messages.
190     *
191     * The type is applied as a CSS class (`cdx-message--{type}`) to the message element.
192     *
193     * @since 0.1.0
194     * @param string $type The type of message (e.g., 'notice', 'warning', 'error', 'success').
195     * @return $this Returns the Message instance for method chaining.
196     */
197    public function setType( string $type ): self {
198        if ( !in_array( $type, self::STATUS_TYPES, true ) ) {
199            throw new InvalidArgumentException( "Invalid message type: $type" );
200        }
201        $this->type = $type;
202
203        return $this;
204    }
205
206    /**
207     * Set the inline display of the message box.
208     *
209     * This method determines whether the message box should be displayed inline,
210     * without padding, background color, or border. Inline messages are typically used for
211     * validation feedback or brief notifications within the flow of content.
212     *
213     * @since 0.1.0
214     * @param bool $inline Whether the message box should be displayed inline.
215     * @return $this Returns the Message instance for method chaining.
216     */
217    public function setInline( bool $inline ): self {
218        $this->inline = $inline;
219
220        return $this;
221    }
222
223    /**
224     * Set the heading of the message box.
225     *
226     * This method sets a heading for the message box, which will be displayed prominently at the top of the message
227     * content. The heading helps to quickly convey the primary purpose or topic of the message.
228     *
229     * Example usage:
230     *
231     *     $message->setHeading('Error: Invalid Input');
232     *
233     * @since 0.1.0
234     * @param string|HtmlSnippet $heading The heading text to be displayed inside the message box.
235     * @return $this Returns the Message instance for method chaining.
236     */
237    public function setHeading( string|HtmlSnippet $heading ): self {
238        $this->heading = $heading;
239
240        return $this;
241    }
242
243    /**
244     * Set additional HTML attributes for the message box.
245     *
246     * This method allows custom HTML attributes to be added to the outer `<div>` element of the message box,
247     * such as `id`, `data-*`, `aria-*`, or any other valid attributes. These attributes can be used to
248     * enhance accessibility or integrate with JavaScript.
249     *
250     * The values of these attributes are automatically escaped to prevent XSS vulnerabilities.
251     *
252     * Example usage:
253     *
254     *     $message->setAttributes([
255     *         'id' => 'error-message',
256     *         'data-type' => 'error',
257     *     ]);
258     *
259     * @since 0.1.0
260     * @param array $attributes An associative array of HTML attributes.
261     * @return $this Returns the Message instance for method chaining.
262     */
263    public function setAttributes( array $attributes ): self {
264        foreach ( $attributes as $key => $value ) {
265            $this->attributes[$key] = $value;
266        }
267        return $this;
268    }
269}