fix(alert): properly form a queue of alerts

packages/calcite-components/src/components.d.ts

@@ -15,7 +15,7 @@ import { ActionBarMessages } from "./components/action-bar/assets/action-bar/t9n
 import { Columns } from "./components/action-group/interfaces";
 import { ActionGroupMessages } from "./components/action-group/assets/action-group/t9n";
 import { ActionPadMessages } from "./components/action-pad/assets/action-pad/t9n";
-import { AlertDuration, AlertQueue, Sync } from "./components/alert/interfaces";
+import { AlertDuration, AlertQueue } from "./components/alert/interfaces";
 import { NumberingSystem } from "./utils/locale";
 import { AlertMessages } from "./components/alert/assets/alert/t9n";
 import { HeadingLevel } from "./components/functional/Heading";
@@ -111,7 +111,7 @@ export { ActionBarMessages } from "./components/action-bar/assets/action-bar/t9n
 export { Columns } from "./components/action-group/interfaces";
 export { ActionGroupMessages } from "./components/action-group/assets/action-group/t9n";
 export { ActionPadMessages } from "./components/action-pad/assets/action-pad/t9n";
-export { AlertDuration, AlertQueue, Sync } from "./components/alert/interfaces";
+export { AlertDuration, AlertQueue } from "./components/alert/interfaces";
 export { NumberingSystem } from "./utils/locale";
 export { AlertMessages } from "./components/alert/assets/alert/t9n";
 export { HeadingLevel } from "./components/functional/Heading";
@@ -510,6 +510,10 @@ export namespace Components {
         "setFocus": () => Promise<void>;
     }
     interface CalciteAlert {
+        /**
+          * This internal property, managed by the AlertManager, is used to inform the component if it is the active open Alert.
+         */
+        "active": boolean;
         /**
           * When `true`, the component closes automatically. Recommended for passive, non-blocking alerts.
          */
@@ -557,6 +561,10 @@ export namespace Components {
           * When `true`, displays and positions the component.
          */
         "open": boolean;
+        /**
+          * This internal property, managed by the AlertManager, is used to inform the component of how many alerts are currently open.
+         */
+        "openAlertCount": number;
         /**
           * Specifies the placement of the component.
          */
@@ -571,6 +579,7 @@ export namespace Components {
         "scale": Scale;
         /**
           * Sets focus on the component's "close" button, the first focusable item.
+          * @returns
          */
         "setFocus": () => Promise<void>;
     }
@@ -6348,8 +6357,6 @@ declare global {
         "calciteAlertClose": void;
         "calciteAlertBeforeOpen": void;
         "calciteAlertOpen": void;
-        "calciteInternalAlertSync": Sync;
-        "calciteInternalAlertRegister": void;
     }
     interface HTMLCalciteAlertElement extends Components.CalciteAlert, HTMLStencilElement {
         addEventListener<K extends keyof HTMLCalciteAlertElementEventMap>(type: K, listener: (this: HTMLCalciteAlertElement, ev: CalciteAlertCustomEvent<HTMLCalciteAlertElementEventMap[K]>) => any, options?: boolean | AddEventListenerOptions): void;
@@ -8411,6 +8418,10 @@ declare namespace LocalJSX {
         "scale"?: Scale;
     }
     interface CalciteAlert {
+        /**
+          * This internal property, managed by the AlertManager, is used to inform the component if it is the active open Alert.
+         */
+        "active"?: boolean;
         /**
           * When `true`, the component closes automatically. Recommended for passive, non-blocking alerts.
          */
@@ -8470,18 +8481,14 @@ declare namespace LocalJSX {
           * Fires when the component is open and animation is complete.
          */
         "onCalciteAlertOpen"?: (event: CalciteAlertCustomEvent<void>) => void;
-        /**
-          * Fires when the component is added to DOM - used to receive initial queue.
-         */
-        "onCalciteInternalAlertRegister"?: (event: CalciteAlertCustomEvent<void>) => void;
-        /**
-          * Fires to sync queue when opened or closed.
-         */
-        "onCalciteInternalAlertSync"?: (event: CalciteAlertCustomEvent<Sync>) => void;
         /**
           * When `true`, displays and positions the component.
          */
         "open"?: boolean;
+        /**
+          * This internal property, managed by the AlertManager, is used to inform the component of how many alerts are currently open.
+         */
+        "openAlertCount"?: number;
         /**
           * Specifies the placement of the component.
          */

packages/calcite-components/src/components/alert/AlertManager.spec.ts

@@ -0,0 +1,54 @@
+import AlertManager, { alertQueueTimeoutMs } from "./AlertManager";
+
+describe("AlertManager", () => {
+  let alertManager: AlertManager;
+  let mockAlert1: HTMLCalciteAlertElement;
+  let mockAlert2: HTMLCalciteAlertElement;
+
+  beforeEach(() => {
+    alertManager = new AlertManager();
+
+    mockAlert1 = {
+      active: false,
+      queue: "last",
+      openAlertCount: 0,
+    } as HTMLCalciteAlertElement;
+
+    mockAlert2 = {
+      active: false,
+      queue: "last",
+      openAlertCount: 0,
+    } as HTMLCalciteAlertElement;
+  });
+
+  it("should activate the first alert after a timeout", async () => {
+    alertManager.registerElement(mockAlert1);
+
+    expect(mockAlert1.active).toBe(false);
+
+    await new Promise((resolve) => setTimeout(resolve, alertQueueTimeoutMs));
+
+    expect(mockAlert1.active).toBe(true);
+  });
+
+  it("should deactivate subsequent alerts", async () => {
+    alertManager.registerElement(mockAlert1);
+    alertManager.registerElement(mockAlert2);
+
+    expect(mockAlert1.active).toBe(false);
+    expect(mockAlert2.active).toBe(false);
+
+    await new Promise((resolve) => setTimeout(resolve, alertQueueTimeoutMs));
+
+    expect(mockAlert1.active).toBe(true);
+    expect(mockAlert2.active).toBe(false);
+  });
+
+  it("should set the openAlertCount correctly", () => {
+    alertManager.registerElement(mockAlert1);
+    alertManager.registerElement(mockAlert2);
+
+    expect(mockAlert1.openAlertCount).toBe(2);
+    expect(mockAlert2.openAlertCount).toBe(2);
+  });
+});

packages/calcite-components/src/components/alert/AlertManager.ts

@@ -0,0 +1,73 @@
+export const alertQueueTimeoutMs = 300;
+
+export default class AlertManager {
+  // --------------------------------------------------------------------------
+  //
+  //  Private Properties
+  //
+  // --------------------------------------------------------------------------
+
+  private registeredElements: HTMLCalciteAlertElement[] = [];
+
+  private queueTimeoutId: number = null;
+
+  // --------------------------------------------------------------------------
+  //
+  //  Public Methods
+  //
+  // --------------------------------------------------------------------------
+
+  registerElement(alert: HTMLCalciteAlertElement): void {
+    const { registeredElements } = this;
+
+    if (!registeredElements.includes(alert)) {
+      switch (alert.queue) {
+        case "immediate":
+          registeredElements.unshift(alert);
+          break;
+        case "next":
+          registeredElements.splice(1, 0, alert);
+          break;
+        case "last":
+          registeredElements.push(alert);
+          break;
+      }
+
+      this.updateAlerts();
+    }
+  }
+
+  unregisterElement(alert: HTMLCalciteAlertElement): void {
+    const { registeredElements } = this;
+
+    const index = registeredElements.indexOf(alert);
+
+    if (index !== -1) {
+      registeredElements.splice(index, 1);
+    }
+
+    alert.active = false;
+    this.updateAlerts();
+  }
+
+  // --------------------------------------------------------------------------
+  //
+  //  Private Methods
+  //
+  // --------------------------------------------------------------------------
+
+  private updateAlerts(): void {
+    window.clearTimeout(this.queueTimeoutId);
+    this.queueTimeoutId = null;
+
+    this.registeredElements.forEach((alert, index) => {
+      alert.openAlertCount = this.registeredElements.length;
+
+      if (index === 0) {
+        this.queueTimeoutId = window.setTimeout(() => (alert.active = true), alertQueueTimeoutMs);
+      } else {
+        alert.active = false;
+      }
+    });
+  }
+}