@xsolla/xui-notification-panel 0.149.1 → 0.151.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +71 -181
  2. package/package.json +5 -5
package/README.md CHANGED
@@ -1,265 +1,155 @@
1
1
  # NotificationPanel
2
2
 
3
- A full-width horizontal notification bar designed for persistent inline notifications within page layouts. Unlike the Notification component (designed for toast popups), NotificationPanel is intended for contextual feedback messages that should remain visible until dismissed.
3
+ A full-width horizontal notification bar for persistent inline notifications within page layouts. Cross-platform (web and React Native) via `@xsolla/xui-primitives`.
4
4
 
5
5
  ## Installation
6
6
 
7
7
  ```bash
8
8
  npm install @xsolla/xui-notification-panel
9
- # or
10
- yarn add @xsolla/xui-notification-panel
11
9
  ```
12
10
 
13
- ## Demo
11
+ ## Imports
14
12
 
15
- ### Basic NotificationPanel
13
+ ```tsx
14
+ import { NotificationPanel, type NotificationPanelProps } from '@xsolla/xui-notification-panel';
15
+ ```
16
+
17
+ ## Quick start
16
18
 
17
19
  ```tsx
18
20
  import * as React from 'react';
19
21
  import { NotificationPanel } from '@xsolla/xui-notification-panel';
20
22
 
21
- export default function BasicNotificationPanel() {
23
+ export default function Example() {
22
24
  return (
23
25
  <NotificationPanel
24
26
  type="success"
25
- title="Success!"
27
+ title="Success"
26
28
  description="Your changes have been saved."
29
+ onClose={() => console.log('dismissed')}
27
30
  />
28
31
  );
29
32
  }
30
33
  ```
31
34
 
32
- ### NotificationPanel Types
35
+ ## API Reference
36
+
37
+ ### `<NotificationPanel>`
38
+
39
+ | Prop | Type | Default | Description |
40
+ | --- | --- | --- | --- |
41
+ | `type` | `"alert" \| "warning" \| "success" \| "neutral" \| "brand"` | `"neutral"` | Visual variant. Drives panel background and default icon. |
42
+ | `title` | `string` | — | Title text. |
43
+ | `description` | `string` | — | Description text. |
44
+ | `showIcon` | `boolean` | `true` | Show or hide the icon frame. |
45
+ | `icon` | `ReactNode` | — | Custom icon override. Replaces the default type icon. |
46
+ | `actionButton` | `ReactElement` | — | A `Button` or `IconButton` element. `size: "xs"` and `variant: "secondary"` are auto-applied via `cloneElement`; all other props are preserved as written. |
47
+ | `showCloseButton` | `boolean` | `true` | Show or hide the close button. |
48
+ | `onClose` | `() => void` | — | Close button click handler. |
49
+ | `closeButtonAlign` | `"top" \| "center"` | `"top"` | Vertical alignment of the trailing button column. |
50
+ | `testID` | `string` | — | Test identifier. |
51
+
52
+ Inherits `ThemeOverrideProps` (`themeMode`, `themeProductContext`).
53
+
54
+ ### Type values
55
+
56
+ | Type | Use case |
57
+ | --- | --- |
58
+ | `neutral` | General information, default state. |
59
+ | `success` | Positive outcomes, confirmations. |
60
+ | `warning` | Caution, requires attention. |
61
+ | `alert` | Errors, critical issues. |
62
+ | `brand` | Branded messages, promotions. |
63
+
64
+ ## Examples
65
+
66
+ ### All types
33
67
 
34
68
  ```tsx
35
69
  import * as React from 'react';
36
70
  import { NotificationPanel } from '@xsolla/xui-notification-panel';
37
71
 
38
- export default function NotificationPanelTypes() {
72
+ export default function Types() {
39
73
  return (
40
74
  <div style={{ display: 'flex', flexDirection: 'column', gap: 16 }}>
41
- <NotificationPanel type="neutral" title="Info" description="This is an informational message." />
42
- <NotificationPanel type="success" title="Success" description="Operation completed successfully." />
43
- <NotificationPanel type="warning" title="Warning" description="Please review before proceeding." />
75
+ <NotificationPanel type="neutral" title="Info" description="Informational message." />
76
+ <NotificationPanel type="success" title="Success" description="Operation completed." />
77
+ <NotificationPanel type="warning" title="Warning" description="Review before proceeding." />
44
78
  <NotificationPanel type="alert" title="Error" description="Something went wrong." />
45
- <NotificationPanel type="brand" title="Brand" description="A branded notification message." />
79
+ <NotificationPanel type="brand" title="Brand" description="A branded notification." />
46
80
  </div>
47
81
  );
48
82
  }
49
83
  ```
50
84
 
51
- ### With Action Button
85
+ ### With action button
52
86
 
53
87
  ```tsx
54
88
  import * as React from 'react';
55
89
  import { NotificationPanel } from '@xsolla/xui-notification-panel';
56
90
  import { Button } from '@xsolla/xui-button';
57
91
 
58
- export default function ActionNotificationPanel() {
92
+ export default function WithAction() {
59
93
  return (
60
94
  <NotificationPanel
61
95
  type="warning"
62
- title="Session Expiring"
96
+ title="Session expiring"
63
97
  description="Your session will expire in 5 minutes."
64
98
  actionButton={
65
- <Button onPress={() => console.log('Session extended')}>
66
- Extend Session
67
- </Button>
68
- }
69
- onClose={() => console.log('Dismissed')}
70
- />
71
- );
72
- }
73
- ```
74
-
75
- ### With Button Icon Right
76
-
77
- ```tsx
78
- import * as React from 'react';
79
- import { NotificationPanel } from '@xsolla/xui-notification-panel';
80
- import { Button } from '@xsolla/xui-button';
81
- import { ArrowRight } from '@xsolla/xui-icons';
82
-
83
- export default function IconButtonNotificationPanel() {
84
- return (
85
- <NotificationPanel
86
- type="neutral"
87
- description="Check our guide to view all webhooks"
88
- actionButton={
89
- <Button
90
- iconRight={<ArrowRight />}
91
- onPress={() => console.log('Open docs')}
92
- >
93
- Open documentation
94
- </Button>
99
+ <Button onPress={() => console.log('extended')}>Extend session</Button>
95
100
  }
101
+ onClose={() => console.log('dismissed')}
96
102
  />
97
103
  );
98
104
  }
99
105
  ```
100
106
 
101
- ### With IconButton
107
+ ### With IconButton action
102
108
 
103
109
  ```tsx
104
110
  import * as React from 'react';
105
111
  import { NotificationPanel } from '@xsolla/xui-notification-panel';
106
112
  import { IconButton } from '@xsolla/xui-button';
107
- import { ArrowRight } from '@xsolla/xui-icons';
113
+ import { ArrowRight } from '@xsolla/xui-icons-base';
108
114
 
109
- export default function IconButtonNotificationPanel() {
115
+ export default function WithIconAction() {
110
116
  return (
111
117
  <NotificationPanel
112
118
  type="neutral"
113
119
  title="Quick action available"
114
- description="Click the arrow to view more details"
115
- actionButton={
116
- <IconButton
117
- icon={<ArrowRight />}
118
- onPress={() => console.log('Navigate')}
119
- />
120
- }
120
+ description="Click the arrow to view more details."
121
+ actionButton={<IconButton icon={<ArrowRight />} aria-label="Open" onPress={() => {}} />}
121
122
  showCloseButton={false}
122
123
  />
123
124
  );
124
125
  }
125
126
  ```
126
127
 
127
- ### Title Only
128
-
129
- ```tsx
130
- import * as React from 'react';
131
- import { NotificationPanel } from '@xsolla/xui-notification-panel';
132
-
133
- export default function TitleOnlyNotificationPanel() {
134
- return (
135
- <NotificationPanel
136
- type="success"
137
- title="Your payment was successful!"
138
- />
139
- );
140
- }
141
- ```
142
-
143
- ### Description Only
144
-
145
- ```tsx
146
- import * as React from 'react';
147
- import { NotificationPanel } from '@xsolla/xui-notification-panel';
148
-
149
- export default function DescriptionOnlyNotificationPanel() {
150
- return (
151
- <NotificationPanel
152
- type="warning"
153
- description="Please verify your email address to continue using all features."
154
- />
155
- );
156
- }
157
- ```
158
-
159
- ### Without Icon
160
-
161
- ```tsx
162
- import * as React from 'react';
163
- import { NotificationPanel } from '@xsolla/xui-notification-panel';
164
-
165
- export default function NoIconNotificationPanel() {
166
- return (
167
- <NotificationPanel
168
- type="neutral"
169
- title="Notice"
170
- description="This notification has no icon."
171
- showIcon={false}
172
- />
173
- );
174
- }
175
- ```
176
-
177
- ### Without Close Button
128
+ ### Title only / description only / no icon
178
129
 
179
130
  ```tsx
180
131
  import * as React from 'react';
181
132
  import { NotificationPanel } from '@xsolla/xui-notification-panel';
182
133
 
183
- export default function PersistentNotificationPanel() {
134
+ export default function Variants() {
184
135
  return (
185
- <NotificationPanel
186
- type="alert"
187
- title="Critical"
188
- description="This notification cannot be dismissed."
189
- showCloseButton={false}
190
- />
136
+ <div style={{ display: 'flex', flexDirection: 'column', gap: 16 }}>
137
+ <NotificationPanel type="success" title="Your payment was successful." />
138
+ <NotificationPanel type="warning" description="Verify your email to continue." />
139
+ <NotificationPanel type="neutral" title="Notice" description="No icon." showIcon={false} />
140
+ <NotificationPanel type="alert" title="Critical" description="Cannot be dismissed." showCloseButton={false} />
141
+ </div>
191
142
  );
192
143
  }
193
144
  ```
194
145
 
195
- ## API Reference
196
-
197
- ### NotificationPanel
198
-
199
- **NotificationPanel Props:**
200
-
201
- | Prop | Type | Default | Description |
202
- | :--- | :--- | :------ | :---------- |
203
- | type | `"alert" \| "warning" \| "success" \| "neutral" \| "brand"` | `"neutral"` | Visual variant/tone of the notification. |
204
- | title | `string` | - | Title text (optional). |
205
- | description | `string` | - | Description text (optional). |
206
- | showIcon | `boolean` | `true` | Show/hide the icon frame. |
207
- | icon | `React.ReactNode` | - | Custom icon override (optional). |
208
- | actionButton | `React.ReactElement` | - | Action button (Button or IconButton). `tone`, `size`, and `variant` are auto-applied. |
209
- | showCloseButton | `boolean` | `true` | Show/hide close button. |
210
- | onClose | `() => void` | - | Close button click handler. |
211
- | closeButtonAlign | `"top" \| "center"` | `"top"` | Vertical alignment of the close button. Use `"center"` for single-line notifications where centered alignment is preferred. |
212
- | testID | `string` | - | Test ID for testing frameworks. |
213
-
214
- ### Auto-Applied Button Props
215
-
216
- When passing a `Button` or `IconButton` to `actionButton`, the following props are automatically injected:
217
-
218
- | Prop | Value | Description |
219
- | :--- | :---- | :---------- |
220
- | tone | Based on `type` | Matches notification type (see table below). |
221
- | size | `"xs"` | Extra small size for compact appearance. |
222
- | variant | `"secondary"` | Secondary button variant. |
223
-
224
- ### Type Values
225
-
226
- | Type | Use Case | Button Tone |
227
- | :--- | :------- | :---------- |
228
- | `neutral` | General information, default state | mono |
229
- | `success` | Positive outcomes, confirmations | brandExtra |
230
- | `warning` | Caution, requires attention | mono |
231
- | `alert` | Errors, critical issues | alert |
232
- | `brand` | Branded messages, promotions | brand |
233
-
234
- ## Theming
235
-
236
- ```typescript
237
- // Type-specific colors accessed via theme
238
- theme.colors.overlay.alert // Alert background
239
- theme.colors.overlay.warning // Warning background
240
- theme.colors.overlay.success // Success background
241
- theme.colors.overlay.mono // Neutral background
242
- theme.colors.overlay.brand // Brand background
243
-
244
- // Icon frame backgrounds
245
- theme.colors.background.warning.primary // Warning icon frame
246
- theme.colors.background.success.primary // Success icon frame
247
- ```
248
-
249
146
  ## Accessibility
250
147
 
251
- - Uses `role="status"` for screen reader announcements
252
- - Includes `aria-label` with notification type
253
- - Close button has `aria-label="Close notification"`
254
- - Action buttons are keyboard accessible and focusable
255
- - Icons are decorative and hidden from screen readers
148
+ - Renders with `role="status"` and an `aria-label` derived from `type`.
149
+ - The close button uses `aria-label="Close notification"`.
150
+ - Action buttons remain keyboard-focusable; the default icon is decorative.
256
151
 
257
- ## Comparison with Notification
152
+ ## Related
258
153
 
259
- | Feature | Notification | NotificationPanel |
260
- | :------ | :----------- | :---------------- |
261
- | Use case | Toast popups, temporary messages | Inline banners, persistent messages |
262
- | Display | Floating overlay | Full-width inline |
263
- | Layout | Compact, stacked | Horizontal bar |
264
- | Icon | Inline with text | Separate colored frame |
265
- | Types | 4 tones (neutral, success, warning, alert) | 5 types (+ brand) |
154
+ - [Notification](./notification.md) — toast/inline message component.
155
+ - [Toast](./toast.md) — programmatic toast notifications via provider.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@xsolla/xui-notification-panel",
3
- "version": "0.149.1",
3
+ "version": "0.151.0",
4
4
  "main": "./web/index.js",
5
5
  "module": "./web/index.mjs",
6
6
  "types": "./web/index.d.ts",
@@ -13,10 +13,10 @@
13
13
  "test:coverage": "vitest run --coverage"
14
14
  },
15
15
  "dependencies": {
16
- "@xsolla/xui-button": "0.149.1",
17
- "@xsolla/xui-core": "0.149.1",
18
- "@xsolla/xui-icons-base": "0.149.1",
19
- "@xsolla/xui-primitives-core": "0.149.1"
16
+ "@xsolla/xui-button": "0.151.0",
17
+ "@xsolla/xui-core": "0.151.0",
18
+ "@xsolla/xui-icons-base": "0.151.0",
19
+ "@xsolla/xui-primitives-core": "0.151.0"
20
20
  },
21
21
  "peerDependencies": {
22
22
  "react": ">=16.8.0",