@xsolla/xui-b2b-toast 0.150.0-pr271.1778106166

package/README.md

@@ -0,0 +1,103 @@
+# B2B Toast
+
+Floating, transient feedback for B2B page layouts. Toasts slide in from a fixed corner of the viewport, auto-dismiss after a few seconds, and stack vertically. Use for brief confirmations and non-blocking status messages.
+
+> **See also:** [`@xsolla/xui-b2b-notification-panel`](../notification-panel/README.md) for inline (non-floating) feedback that stays in place until dismissed.
+
+## Installation
+
+```bash
+yarn add @xsolla/xui-b2b-toast
+```
+
+## Quick start
+
+Wrap your app with `ToastProvider` once, then call `useToast()` from anywhere inside.
+
+```tsx
+import { ToastProvider, useToast } from "@xsolla/xui-b2b-toast";
+import { Button } from "@xsolla/xui-button";
+
+function App() {
+  return (
+    <ToastProvider position="top-right" limit={3}>
+      <Page />
+    </ToastProvider>
+  );
+}
+
+function Page() {
+  const toast = useToast();
+  return (
+    <Button
+      onPress={() =>
+        toast.success({
+          title: "Saved",
+          description: "Your changes have been saved.",
+          action: <Button onPress={() => undo()}>Undo</Button>,
+        })
+      }
+    >
+      Save
+    </Button>
+  );
+}
+```
+
+## API
+
+### `<ToastProvider>`
+
+| Prop        | Type             | Default        | Description                                   |
+| ----------- | ---------------- | -------------- | --------------------------------------------- |
+| `position`  | `ToastPosition`  | `"top-right"`  | Viewport corner to anchor toasts to.          |
+| `limit`     | `number`         | `3`            | Max simultaneously visible toasts.            |
+| `container` | `HTMLElement`    | `document.body`| Portal target.                                |
+
+`ToastPosition` = `"top-right" \| "top-left" \| "top-center" \| "bottom-right" \| "bottom-left" \| "bottom-center"`
+
+### `useToast()`
+
+```ts
+const toast = useToast();
+toast.alert(options);    // role=alert, default 9000ms
+toast.success(options);  // default 4500ms
+toast.warning(options);  // default 6500ms
+toast.info(options);     // default 6500ms
+toast.show(type, options);
+toast.dismiss(id);
+toast.dismissAll();
+```
+
+`ToastOptions`:
+
+| Field             | Type                  | Description                                              |
+| ----------------- | --------------------- | -------------------------------------------------------- |
+| `title`           | `string`              | Title (bodyMd accent).                                    |
+| `description`     | `string`              | Optional description (bodySm).                           |
+| `action`          | `ReactElement`        | Button/IconButton; tone & size are auto-applied.         |
+| `showCloseButton` | `boolean`             | Default `true`.                                          |
+| `duration`        | `number`              | Auto-dismiss in ms. `0` disables.                        |
+| `id`              | `string`              | Stable id; reusing replaces the existing toast.          |
+| `onDismiss`       | `() => void`          | Fires when toast is removed (auto, manual, or replaced). |
+
+### `<Toast>`
+
+The visual component, used internally by the provider but exported for advanced cases (custom rendering, snapshot stories, etc.).
+
+```tsx
+<Toast
+  type="alert"
+  title="Project deleted"
+  description='Project "Project Name" deleted'
+  action={<Button>Undo</Button>}
+  onClose={() => {}}
+/>
+```
+
+## Behavior
+
+- **Auto-dismiss** — success 4.5s, info/warning 6.5s, alert 9s. Pass `duration={0}` to make a toast sticky.
+- **Pause on hover/focus** — auto-dismiss timer pauses while the toast is hovered or focused, and resumes on leave/blur.
+- **Stacking** — newest toast appears closest to the screen edge. When `limit` is exceeded, the oldest toast is dropped.
+- **Accessibility** — `alert` toasts use `role="alert"` / `aria-live="assertive"`; the rest use `role="status"` / `aria-live="polite"`.

package/native/index.d.mts

@@ -0,0 +1,81 @@
+import React from 'react';
+import { ThemeOverrideProps } from '@xsolla/xui-core';
+import { ButtonProps, IconButtonProps } from '@xsolla/xui-button';
+
+type ToastType = "alert" | "success" | "warning" | "info";
+type ToastActionElement = React.ReactElement<ButtonProps | IconButtonProps>;
+interface ToastProps extends ThemeOverrideProps {
+    /** Visual variant/tone of the toast */
+    type?: ToastType;
+    /** Title text (required for accessibility) */
+    title?: string;
+    /** Optional description text shown beneath the title */
+    description?: string;
+    /**
+     * Action element (Button/IconButton). The toast will inject
+     * `size="xs"`, `variant="tertiary"`, and a tone matching the toast type.
+     */
+    action?: React.ReactElement;
+    /** Show/hide close button */
+    showCloseButton?: boolean;
+    /** Close button click handler */
+    onClose?: () => void;
+    /** Test ID for testing frameworks */
+    testID?: string;
+}
+declare const Toast: React.FC<ToastProps>;
+
+type ToastPosition = "top-right" | "top-left" | "top-center" | "bottom-right" | "bottom-left" | "bottom-center";
+type ToastVariant = "default" | "sonner";
+interface ToastOptions extends Omit<ToastProps, "type" | "onClose" | "testID"> {
+    /**
+     * Auto-dismiss duration in ms. Pass 0 to disable auto-dismiss.
+     * Defaults derived from `type`: success 4500, info/warning 6500, alert 9000.
+     */
+    duration?: number;
+    /** Stable id — if provided and a toast with that id already exists, it's replaced. */
+    id?: string;
+    /** Called when the toast is dismissed (auto or manual). */
+    onDismiss?: () => void;
+}
+interface ToastQueueItem extends ToastOptions {
+    id: string;
+    type: ToastType;
+    createdAt: number;
+}
+interface ToastApi {
+    alert: (options: ToastOptions) => string;
+    success: (options: ToastOptions) => string;
+    warning: (options: ToastOptions) => string;
+    info: (options: ToastOptions) => string;
+    show: (type: ToastType, options: ToastOptions) => string;
+    dismiss: (id: string) => void;
+    dismissAll: () => void;
+}
+interface ToastProviderProps {
+    children: React.ReactNode;
+    /** Where toasts appear on screen. Defaults to top-right. */
+    position?: ToastPosition;
+    /** Maximum number of simultaneously visible toasts. Defaults to 3. */
+    limit?: number;
+    /** DOM node to portal the viewport into. Defaults to document.body. */
+    container?: HTMLElement | null;
+    /**
+     * Enable enter & exit animations. Defaults to `true`.
+     * When `false`, toasts appear and disappear instantly.
+     */
+    animated?: boolean;
+    /** Animation duration in ms. Defaults to 220 (default variant) / 400 (sonner). */
+    animationDuration?: number;
+    /**
+     * Visual variant.
+     * - `"default"` — toasts slide in from the edge and stack vertically.
+     * - `"sonner"` — shadcn/sonner-style stacked-cards: toasts overlap as a deck
+     *   with back cards scaled & peeking; hovering the stack expands it.
+     */
+    variant?: ToastVariant;
+}
+declare const ToastProvider: React.FC<ToastProviderProps>;
+declare const useToast: () => ToastApi;
+
+export { Toast, type ToastActionElement, type ToastApi, type ToastOptions, type ToastPosition, type ToastProps, ToastProvider, type ToastProviderProps, type ToastQueueItem, type ToastType, type ToastVariant, useToast };

package/native/index.d.ts

@@ -0,0 +1,81 @@
+import React from 'react';
+import { ThemeOverrideProps } from '@xsolla/xui-core';
+import { ButtonProps, IconButtonProps } from '@xsolla/xui-button';
+
+type ToastType = "alert" | "success" | "warning" | "info";
+type ToastActionElement = React.ReactElement<ButtonProps | IconButtonProps>;
+interface ToastProps extends ThemeOverrideProps {
+    /** Visual variant/tone of the toast */
+    type?: ToastType;
+    /** Title text (required for accessibility) */
+    title?: string;
+    /** Optional description text shown beneath the title */
+    description?: string;
+    /**
+     * Action element (Button/IconButton). The toast will inject
+     * `size="xs"`, `variant="tertiary"`, and a tone matching the toast type.
+     */
+    action?: React.ReactElement;
+    /** Show/hide close button */
+    showCloseButton?: boolean;
+    /** Close button click handler */
+    onClose?: () => void;
+    /** Test ID for testing frameworks */
+    testID?: string;
+}
+declare const Toast: React.FC<ToastProps>;
+
+type ToastPosition = "top-right" | "top-left" | "top-center" | "bottom-right" | "bottom-left" | "bottom-center";
+type ToastVariant = "default" | "sonner";
+interface ToastOptions extends Omit<ToastProps, "type" | "onClose" | "testID"> {
+    /**
+     * Auto-dismiss duration in ms. Pass 0 to disable auto-dismiss.
+     * Defaults derived from `type`: success 4500, info/warning 6500, alert 9000.
+     */
+    duration?: number;
+    /** Stable id — if provided and a toast with that id already exists, it's replaced. */
+    id?: string;
+    /** Called when the toast is dismissed (auto or manual). */
+    onDismiss?: () => void;
+}
+interface ToastQueueItem extends ToastOptions {
+    id: string;
+    type: ToastType;
+    createdAt: number;
+}
+interface ToastApi {
+    alert: (options: ToastOptions) => string;
+    success: (options: ToastOptions) => string;
+    warning: (options: ToastOptions) => string;
+    info: (options: ToastOptions) => string;
+    show: (type: ToastType, options: ToastOptions) => string;
+    dismiss: (id: string) => void;
+    dismissAll: () => void;
+}
+interface ToastProviderProps {
+    children: React.ReactNode;
+    /** Where toasts appear on screen. Defaults to top-right. */
+    position?: ToastPosition;
+    /** Maximum number of simultaneously visible toasts. Defaults to 3. */
+    limit?: number;
+    /** DOM node to portal the viewport into. Defaults to document.body. */
+    container?: HTMLElement | null;
+    /**
+     * Enable enter & exit animations. Defaults to `true`.
+     * When `false`, toasts appear and disappear instantly.
+     */
+    animated?: boolean;
+    /** Animation duration in ms. Defaults to 220 (default variant) / 400 (sonner). */
+    animationDuration?: number;
+    /**
+     * Visual variant.
+     * - `"default"` — toasts slide in from the edge and stack vertically.
+     * - `"sonner"` — shadcn/sonner-style stacked-cards: toasts overlap as a deck
+     *   with back cards scaled & peeking; hovering the stack expands it.
+     */
+    variant?: ToastVariant;
+}
+declare const ToastProvider: React.FC<ToastProviderProps>;
+declare const useToast: () => ToastApi;
+
+export { Toast, type ToastActionElement, type ToastApi, type ToastOptions, type ToastPosition, type ToastProps, ToastProvider, type ToastProviderProps, type ToastQueueItem, type ToastType, type ToastVariant, useToast };