Skip to content

Commit d8c0900

Browse files
JonasBanatemoo-re
JonasBa
and
natemoo-re
authored
ref(core): refactor alerts documentation (#95186)
Refactor to use new mdx format. --------- Co-authored-by: Nate Moore <natemoo-re@users.noreply.github.com>
1 parent 8f8aa12 commit d8c0900

File tree

2 files changed

+297
-190
lines changed

2 files changed

+297
-190
lines changed

‎static/app/components/core/alert/index.mdx

Lines changed: 297 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,297 @@
1+
---
2+
title: Alert
3+
description: Alerts provide contextual feedback messages to users with different severity levels and optional interactive elements.
4+
source: 'sentry/components/core/alert'
5+
resources:
6+
js: https://github.com/getsentry/sentry/blob/master/static/app/components/core/alert/index.tsx
7+
figma: https://www.figma.com/design/eTJz6aPgudMY9E6mzyZU0B/ChonkUI--App-Components--WIP-?node-id=3040-309&p=f&t=waV9nlkQ95W3UZtu-0
8+
a11y:
9+
WCAG 1.4.3: https://www.w3.org/TR/WCAG22/#contrast-minimum
10+
WCAG 2.1.1: https://www.w3.org/TR/WCAG22/#keyboard
11+
WCAG 2.4.7: https://www.w3.org/TR/WCAG22/#focus-visible
12+
WAI-ARIA Alert Pattern: https://www.w3.org/WAI/ARIA/apg/patterns/alert/
13+
---
14+
15+
import {Alert} from 'sentry/components/core/alert';
16+
import {Button} from 'sentry/components/core/button';
17+
import {IconAdd, IconDelete, IconEdit} from 'sentry/icons';
18+
import * as Storybook from 'sentry/stories';
19+
20+
import types from '!!type-loader!sentry/components/core/alert/index';
21+
22+
export {types};
23+
24+
To create a basic alert, wrap your message in an `<Alert>` component and specify the appropriate type.
25+
26+
```jsx
27+
<Alert type="info" showIcon>
28+
This is an informational message
29+
</Alert>
30+
```
31+
32+
### Types
33+
34+
Alerts come in five different types to convey different levels of importance and meaning: `muted`, `info`, `warning`, `success`, and `error`.
35+
36+
<Storybook.Demo>
37+
<Alert.Container>
38+
<Alert type="muted" showIcon>
39+
This is a muted alert for neutral information
40+
</Alert>
41+
<Alert type="info" showIcon>
42+
This is an info alert for general information
43+
</Alert>
44+
<Alert type="warning" showIcon>
45+
This is a warning alert for important notices
46+
</Alert>
47+
<Alert type="success" showIcon>
48+
This is a success alert for positive feedback
49+
</Alert>
50+
<Alert type="error" showIcon>
51+
This is an error alert for critical issues
52+
</Alert>
53+
</Alert.Container>
54+
</Storybook.Demo>
55+
```jsx
56+
<Alert.Container>
57+
<Alert type="muted" showIcon>
58+
This is a muted alert for neutral information
59+
</Alert>
60+
<Alert type="info" showIcon>
61+
This is an info alert for general information
62+
</Alert>
63+
<Alert type="warning" showIcon>
64+
This is a warning alert for important notices
65+
</Alert>
66+
<Alert type="success" showIcon>
67+
This is a success alert for positive feedback
68+
</Alert>
69+
<Alert type="error" showIcon>
70+
This is an error alert for critical issues
71+
</Alert>
72+
</Alert.Container>
73+
```
74+
75+
### Icons
76+
77+
By default, alerts display appropriate icons based on their type. You can hide icons by setting `showIcon={false}` or provide custom icons.
78+
79+
<Storybook.Demo>
80+
<Alert.Container>
81+
<Alert type="info" showIcon>
82+
Default info icon
83+
</Alert>
84+
<Alert type="warning" showIcon={false}>
85+
No icon
86+
</Alert>
87+
<Alert type="success" showIcon icon={<IconAdd />}>
88+
Custom add icon
89+
</Alert>
90+
</Alert.Container>
91+
</Storybook.Demo>
92+
```jsx
93+
<Alert.Container>
94+
<Alert type="info" showIcon>
95+
Default info icon
96+
</Alert>
97+
<Alert type="warning" showIcon={false}>
98+
No icon
99+
</Alert>
100+
<Alert type="success" showIcon icon={<IconAdd />}>
101+
Custom add icon
102+
</Alert>
103+
</Alert.Container>
104+
```
105+
106+
### Expandable Content
107+
108+
Alerts can contain expandable content to provide additional details without overwhelming the initial view.
109+
110+
<Storybook.Demo>
111+
<Alert
112+
type="warning"
113+
showIcon
114+
expand={
115+
<div>
116+
<p>This is additional content that was hidden by default.</p>
117+
<p>
118+
You can include any React elements here, including lists, links, or other
119+
components.
120+
</p>
121+
</div>
122+
}
123+
>
124+
Click to expand this alert for more details
125+
</Alert>
126+
</Storybook.Demo>
127+
```jsx
128+
<Alert
129+
type="warning"
130+
showIcon
131+
expand={
132+
<div>
133+
<p>This is additional content that was hidden by default.</p>
134+
<p>
135+
You can include any React elements here, including lists, links, or other
136+
components.
137+
</p>
138+
</div>
139+
}
140+
>
141+
Click to expand this alert for more details
142+
</Alert>
143+
```
144+
145+
### Trailing Items
146+
147+
Add interactive elements like buttons or links to the right side of alerts using the `trailingItems` prop.
148+
149+
<Storybook.Demo>
150+
<Alert.Container>
151+
<Alert
152+
type="info"
153+
showIcon
154+
trailingItems={
155+
<Button size="xs" priority="primary">
156+
Take Action
157+
</Button>
158+
}
159+
>
160+
This alert has a trailing action button
161+
</Alert>
162+
<Alert
163+
type="error"
164+
showIcon
165+
trailingItems={
166+
<div>
167+
<Button size="xs" priority="danger" icon={<IconDelete />}>
168+
Delete
169+
</Button>
170+
<Button size="xs" priority="muted" icon={<IconEdit />}>
171+
Edit
172+
</Button>
173+
</div>
174+
}
175+
>
176+
This alert has multiple trailing actions
177+
</Alert>
178+
</Alert.Container>
179+
</Storybook.Demo>
180+
```jsx
181+
<Alert.Container>
182+
<Alert
183+
type="info"
184+
showIcon
185+
trailingItems={
186+
<Button size="xs" priority="primary">
187+
Take Action
188+
</Button>
189+
}
190+
>
191+
This alert has a trailing action button
192+
</Alert>
193+
<Alert
194+
type="error"
195+
showIcon
196+
trailingItems={
197+
<div>
198+
<Button size="xs" priority="danger" icon={<IconDelete />}>
199+
Delete
200+
</Button>
201+
<Button size="xs" priority="muted" icon={<IconEdit />}>
202+
Edit
203+
</Button>
204+
</div>
205+
}
206+
>
207+
This alert has multiple trailing actions
208+
</Alert>
209+
</Alert.Container>
210+
```
211+
212+
### System Alerts
213+
214+
System alerts are full-width variants typically used for application-level notifications or banners.
215+
216+
<Storybook.Demo>
217+
<Alert type="warning" showIcon system>
218+
This is a system-wide alert that spans the full width of its container
219+
</Alert>
220+
</Storybook.Demo>
221+
```jsx
222+
<Alert type="warning" showIcon system>
223+
This is a system-wide alert that spans the full width of its container
224+
</Alert>
225+
```
226+
227+
### Expanded by Default
228+
229+
You can control the initial expansion state of alerts with expandable content.
230+
231+
<Storybook.Demo>
232+
<Alert
233+
type="info"
234+
showIcon
235+
defaultExpanded
236+
expand={
237+
<div>
238+
<p>This alert starts in an expanded state.</p>
239+
<p>Users can still collapse it by clicking the chevron.</p>
240+
</div>
241+
}
242+
>
243+
This alert is expanded by default
244+
</Alert>
245+
</Storybook.Demo>
246+
```jsx
247+
<Alert
248+
type="info"
249+
showIcon
250+
defaultExpanded
251+
expand={
252+
<div>
253+
<p>This alert starts in an expanded state.</p>
254+
<p>Users can still collapse it by clicking the chevron.</p>
255+
</div>
256+
}
257+
>
258+
This alert is expanded by default
259+
</Alert>
260+
```
261+
262+
### Container
263+
264+
Use `Alert.Container` to properly manage spacing between multiple alerts.
265+
266+
<Storybook.Demo>
267+
<Alert.Container>
268+
<Alert type="info" showIcon>
269+
First alert in a container
270+
</Alert>
271+
<Alert type="warning" showIcon>
272+
Second alert in a container
273+
</Alert>
274+
<Alert type="success" showIcon>
275+
Third alert in a container
276+
</Alert>
277+
</Alert.Container>
278+
</Storybook.Demo>
279+
```jsx
280+
<Alert.Container>
281+
<Alert type="info" showIcon>
282+
First alert in a container
283+
</Alert>
284+
<Alert type="warning" showIcon>
285+
Second alert in a container
286+
</Alert>
287+
<Alert type="success" showIcon>
288+
Third alert in a container
289+
</Alert>
290+
</Alert.Container>
291+
```
292+
293+
### Accessibility
294+
295+
To meet WCAG 2.2 AA compliance, `<Alert>` automatically meets the [WCAG 1.4.3](https://www.w3.org/TR/WCAG22/#contrast-minimum), [WCAG 2.1.1](https://www.w3.org/TR/WCAG22/#keyboard), and [WCAG 2.4.7](https://www.w3.org/TR/WCAG22/#focus-visible) success criteria.
296+
297+
Developers should take care to ensure that their implementations additionally follow the [WAI-ARIA Alert Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/alert/) and consider using appropriate ARIA attributes for dynamic content updates.

0 commit comments

Comments
 (0)