Merge pull request #32542 from backstage/bui-toast

feat: Introduce ToastApi for rich notifications in the new frontend system

.changeset/deep-crabs-dig.md

@@ -0,0 +1,5 @@
+---
+'@backstage/ui': patch
+---
+
+Fixed --bui-fg-success token in light mode to be more accessible.

.changeset/deprecate-alert-api-core-app.md

@@ -0,0 +1,5 @@
+---
+'@backstage/core-app-api': patch
+---
+
+Deprecated `AlertApiForwarder` in favor of the new `ToastApi`. The `AlertApiForwarder` now emits a console warning on first use, guiding developers to migrate to `ToastApi` from `@backstage/frontend-plugin-api`.

.changeset/deprecate-alert-api-core-plugin.md

@@ -0,0 +1,5 @@
+---
+'@backstage/core-plugin-api': patch
+---
+
+Deprecated `AlertApi`, `AlertMessage`, and `alertApiRef` in favor of the new `ToastApi` from `@backstage/frontend-plugin-api`.

.changeset/deprecate-alert-api.md

@@ -0,0 +1,55 @@
+---
+'@backstage/frontend-plugin-api': patch
+---
+
+Deprecated `AlertApi` in favor of the new `ToastApi`.
+
+`AlertApi` is now deprecated and will be removed in a future release. Please migrate to `ToastApi` which provides richer notification features.
+
+**Why migrate?**
+
+`ToastApi` offers enhanced capabilities over `AlertApi`:
+
+- **Title and Description**: Display a prominent title with optional description text
+- **Action Links**: Include clickable links within notifications
+- **Status Variants**: Support for neutral, info, success, warning, and danger statuses
+- **Per-toast Timeout**: Control auto-dismiss timing for each notification individually
+- **Programmatic Dismiss**: Close notifications via the `close()` handle returned from `post()`
+
+**Migration Guide**
+
+| AlertApi                                     | ToastApi                                   |
+| -------------------------------------------- | ------------------------------------------ |
+| `message: string`                            | `title: ReactNode`                         |
+| `severity: 'error'`                          | `status: 'danger'`                         |
+| `severity: 'success' \| 'info' \| 'warning'` | `status: 'success' \| 'info' \| 'warning'` |
+| `display: 'transient'`                       | `timeout: 5000` (or custom ms)             |
+| `display: 'permanent'`                       | omit `timeout`                             |
+| `post()` returns `void`                      | `post()` returns `{ close(): void }`       |
+
+**Example Migration**
+
+```typescript
+// Before (AlertApi)
+import { alertApiRef, useApi } from '@backstage/core-plugin-api';
+
+const alertApi = useApi(alertApiRef);
+alertApi.post({
+  message: 'Entity saved successfully',
+  severity: 'success',
+  display: 'transient',
+});
+
+// After (ToastApi)
+import { toastApiRef, useApi } from '@backstage/frontend-plugin-api';
+
+const toastApi = useApi(toastApiRef);
+const toast = toastApi.post({
+  title: 'Entity saved successfully',
+  status: 'success',
+  timeout: 5000,
+});
+// Later: toast.close() to dismiss programmatically
+```
+
+**Note**: During the migration period, both APIs work simultaneously. The `ToastDisplay` component subscribes to both `AlertApi` and `ToastApi`, so existing code continues to work while you migrate incrementally.

.changeset/toast-api-introduction.md

@@ -0,0 +1,38 @@
+---
+'@backstage/frontend-plugin-api': patch
+'@backstage/plugin-app': patch
+---
+
+Introduced a new `ToastApi` for displaying rich toast notifications in the new frontend system.
+
+The new `ToastApi` provides enhanced notification capabilities compared to the existing `AlertApi`:
+
+- **Title and Description**: Toasts support both a title and an optional description
+- **Custom Timeouts**: Each toast can specify its own timeout duration
+- **Links**: Toasts can include action links
+- **Status Variants**: Support for neutral, info, success, warning, and danger statuses
+- **Programmatic Dismiss**: Toasts can be dismissed programmatically using the `close()` handle returned from `post()`
+
+**Usage:**
+
+```typescript
+import { toastApiRef, useApi } from '@backstage/frontend-plugin-api';
+
+const toastApi = useApi(toastApiRef);
+
+// Full-featured toast
+toastApi.post({
+  title: 'Entity saved',
+  description: 'Your changes have been saved successfully.',
+  status: 'success',
+  timeout: 5000,
+  links: [{ label: 'View entity', href: '/catalog/entity' }],
+});
+
+// Programmatic dismiss
+const { close } = toastApi.post({ title: 'Uploading...', status: 'info' });
+// Later...
+close();
+```
+
+The `ToastDisplay` component subscribes to both `ToastApi` and `AlertApi`, providing a migration path where both systems work side by side until `AlertApi` is fully deprecated.