[CL-335][CL-336][CL-374] Announce toasts more consistently

apps/browser/src/popup/app.component.ts

@@ -35,9 +35,12 @@ import { DesktopSyncVerificationDialogComponent } from "./components/desktop-syn
   selector: "app-root",
   styles: [],
   animations: [routerTransition],
-  template: ` <div [@routerTransition]="getRouteElevation(outlet)">
-    <router-outlet #outlet="outlet"></router-outlet>
-  </div>`,
+  template: `
+    <div [@routerTransition]="getRouteElevation(outlet)">
+      <router-outlet #outlet="outlet"></router-outlet>
+    </div>
+    <bit-toast-container></bit-toast-container>
+  `,
 })
 export class AppComponent implements OnInit, OnDestroy {
   private viewCacheService = inject(PopupViewCacheService);

apps/desktop/src/app/app.component.ts

@@ -92,6 +92,8 @@
       </div>
       <router-outlet *ngIf="!loading"></router-outlet>
     </div>
+
+    <bit-toast-container></bit-toast-container>
   `,
 })
 export class AppComponent implements OnInit, OnDestroy {

apps/web/src/app/app.component.html

@@ -17,3 +17,5 @@
 <ng-container *ngIf="!loading; else loadingState">
   <router-outlet></router-outlet>
 </ng-container>
+
+<bit-toast-container></bit-toast-container>

libs/components/src/toast/toast-container.component.html

@@ -0,0 +1 @@
+<div role="status" aria-live="polite" aria-atomic="true" toastContainer></div>

libs/components/src/toast/toast-container.component.ts

@@ -0,0 +1,19 @@
+import { Component, OnInit, ViewChild } from "@angular/core";
+import { ToastContainerDirective, ToastrService } from "ngx-toastr";
+
+@Component({
+  selector: "bit-toast-container",
+  templateUrl: "toast-container.component.html",
+  standalone: true,
+  imports: [ToastContainerDirective],
+})
+export class ToastContainerComponent implements OnInit {
+  @ViewChild(ToastContainerDirective, { static: true })
+  toastContainer?: ToastContainerDirective;
+
+  constructor(private toastrService: ToastrService) {}
+
+  ngOnInit(): void {
+    this.toastrService.overlayContainer = this.toastContainer;
+  }
+}

libs/components/src/toast/toast.component.html

@@ -2,6 +2,7 @@
   class="tw-mb-1 tw-min-w-[--bit-toast-width] tw-text-main tw-flex tw-flex-col tw-justify-between tw-rounded-md tw-pointer-events-auto tw-cursor-default tw-overflow-hidden tw-shadow-lg {{
     bgColor
   }}"
+  [attr.role]="variant === 'error' ? 'alert' : null"
 >
   <div class="tw-flex tw-items-center tw-gap-4 tw-px-2 tw-pb-1 tw-pt-2">
     <i aria-hidden="true" class="bwi tw-text-xl tw-py-1.5 tw-px-2.5 {{ iconClass }}"></i>

libs/components/src/toast/toast.mdx

@@ -10,21 +10,57 @@ import { ToastService } from "@bitwarden/components";
 
 # Toast
 
-<Primary />
-<Controls />
+Toasts are used for error or confirmation messaging. The toast body content should accurately
+describe the warning, error, or successful event following best practices for UX Writing. Avoid
+using long messages in toasts.
 
-## Stories
+<Canvas of={stories.Default} />
 
-### Default
+<Canvas of={stories.LongContent} />
 
-<Canvas of={stories.Default} />
+## Displaying a toast
 
-### Long Content
+Toasts are triggered via the `toastService` from a frontend Angular context.
 
-Avoid using long messages in toasts.
+```
+toastService.showToast({
+  variant: 'success',
+  title: null,
+  message: 'Hi I'm a toast,
+});
+```
 
-<Canvas of={stories.LongContent} />
+The following options are accepted:
 
-### Service
+| Option    | Description                                   |
+| --------- | --------------------------------------------- |
+| `variant` | `"success" \| "error" \| "info" \| "warning"` |
+| `title`   | Optional title `string`                       |
+| `message` | Main toast content. Required `string`         |
 
 <Canvas of={stories.Service} />
+
+## Toast container
+
+Each web client uses the `bit-toast-container` component in its root `app` component to house the
+toasts. This container component provides aria attributes that make the toasts accessible to
+screenreader technology. Any new clients should do the same. Without the toast container, toasts
+will still display visually but will be more difficult for screenreader users to perceive.
+
+```
+<other app file html here>
+<bit-toast-container></bit-toast-container>
+```
+
+The `Service` story utilizes the `bit-toast-container` for more accurate screenreader testing.
+
+## Toast configuration
+
+Toast placement, auto dismiss, close button visibility, and max number of toasts to display are
+configured once at the shared module import level, but can be overridden in a client's module import
+file.
+
+## Accessibility
+
+In addition to the accessibility provided by the `bit-toast-container` component, the toast itself
+will apply `aria-alert="true"` if the toast is of type `error`.

libs/components/src/toast/toast.module.ts

@@ -1,11 +1,12 @@
 import { ModuleWithProviders, NgModule } from "@angular/core";
 import { DefaultNoComponentGlobalConfig, GlobalConfig, TOAST_CONFIG } from "ngx-toastr";
 
+import { ToastContainerComponent } from "./toast-container.component";
 import { BitwardenToastrComponent } from "./toastr.component";
 
 @NgModule({
-  imports: [BitwardenToastrComponent],
-  exports: [BitwardenToastrComponent],
+  imports: [BitwardenToastrComponent, ToastContainerComponent],
+  exports: [BitwardenToastrComponent, ToastContainerComponent],
 })
 export class ToastModule {
   static forRoot(config: Partial<GlobalConfig> = {}): ModuleWithProviders<ToastModule> {

libs/components/src/toast/toast.stories.ts

@@ -33,7 +33,7 @@ export default {
 
   decorators: [
     moduleMetadata({
-      imports: [CommonModule, BrowserAnimationsModule, ButtonModule],
+      imports: [CommonModule, BrowserAnimationsModule, ButtonModule, ToastModule],
       declarations: [ToastServiceExampleComponent],
     }),
     applicationConfig({
@@ -47,6 +47,7 @@ export default {
               success: "Success",
               error: "Error",
               warning: "Warning",
+              info: "Info",
             });
           },
         },
@@ -104,6 +105,7 @@ export const Service: Story = {
       toastOptions: args,
     },
     template: `
+    <bit-toast-container></bit-toast-container>
       <toast-service-example [toastOptions]="toastOptions"></toast-service-example>
     `,
   }),

libs/components/src/toast/toastr.component.ts

@@ -1,6 +1,6 @@
 import { animate, state, style, transition, trigger } from "@angular/animations";
 import { Component } from "@angular/core";
-import { Toast as BaseToastrComponent } from "ngx-toastr";
+import { Toast as BaseToastrComponent, ToastPackage, ToastrService } from "ngx-toastr";
 
 import { ToastComponent } from "./toast.component";
 
@@ -27,4 +27,8 @@
   standalone: true,
   imports: [ToastComponent],
 })
-export class BitwardenToastrComponent extends BaseToastrComponent {}
+export class BitwardenToastrComponent extends BaseToastrComponent {
+  constructor(toastrService: ToastrService, toastPackage: ToastPackage) {
+    super(toastrService, toastPackage);
+  }
+}