@xsolla/xui-toast 0.174.2 → 0.175.0

package/README.md

@@ -2,6 +2,54 @@
 
 A cross-platform toast notification system matching the base Figma toast. Use it for short, non-blocking feedback with a title, optional description, optional action, and automatic or manual dismissal.
 
+<!-- BEGIN:xui-mcp-instructions:toast -->
+A toast is a short, non-blocking message that appears temporarily to inform the user about the result of an action or a change in system state. It appears as a compact bar that slides in from the top of the screen, stays briefly, then dismisses automatically — or can be dismissed manually.
+
+### When to use
+
+- To confirm that an action was completed successfully (e.g. *"Profile updated"*)
+- To notify the user of a background event they didn't directly trigger (e.g. *"New rewards available"*)
+- To surface a non-critical warning that doesn't block the user from continuing
+- To inform about an error that occurred in the background (e.g. *"Connection lost"*)
+
+### When not to use
+
+For critical errors that require the user to take action before continuing — use a modal or inline error instead
+
+For information that the user needs to refer back to — toasts disappear and can't be recalled
+- For complex messages with multiple actions — keep it to one optional CTA at most
+- As a substitute for form validation errors — those belong inline next to the relevant field
+
+### Content guidelines
+
+Title should be short and specific — 1 to 5 words: *"Profile saved"*, *"Connection lost"*, *"Reward claimed"*
+
+Subtitle is optional — use it to add one line of supporting context, not to repeat the title
+
+Button label should be a clear verb: *"Undo"*, *"Retry"*, *"View"* — not *"OK"* or *"Click here"*
+- Avoid exclamation marks or dramatic language — keep the tone calm and factual
+- Match the type to the message: use Alert only for errors, Warning for caution, Success for positive outcomes, Neutral for informational messages
+
+### Behaviour guidelines
+
+Toasts appear at the top of the viewport, offset from the status bar or navigation
+
+They auto-dismiss after a set duration (typically 3–5 seconds) — the exact timing is set at the product layer
+
+When Button=False, a close (×) icon is shown — tapping it dismisses the toast immediately
+
+When Button=True, the action button replaces the close icon — the toast can be dismissed by tapping the button or waiting for auto-dismiss
+- Multiple toasts stack in a ToastGroup — see below
+- Toasts do not block interaction with the rest of the screen
+
+### Accessibility
+
+Use role=*"status"* for Neutral and Success toasts — screen readers announce them without interrupting the user
+- Use role=*"alert"* for Warning and Alert toasts — these are announced immediately
+- The close button must have aria-label=*"Dismiss notification"*
+- Do not rely on color alone to convey the type — the icon and text must also communicate it
+<!-- END:xui-mcp-instructions:toast -->
+
 ## Installation
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xsolla/xui-toast",
-  "version": "0.174.2",
+  "version": "0.175.0",
   "main": "./web/index.js",
   "module": "./web/index.mjs",
   "types": "./web/index.d.ts",
@@ -14,10 +14,10 @@
     "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
-    "@xsolla/xui-core": "0.174.2",
-    "@xsolla/xui-icons": "0.174.2",
-    "@xsolla/xui-icons-base": "0.174.2",
-    "@xsolla/xui-primitives-core": "0.174.2"
+    "@xsolla/xui-core": "0.175.0",
+    "@xsolla/xui-icons": "0.175.0",
+    "@xsolla/xui-icons-base": "0.175.0",
+    "@xsolla/xui-primitives-core": "0.175.0"
   },
   "peerDependencies": {
     "react": ">=16.8.0",