fix(core/message-bar): add animation complete event (#1688)

Co-authored-by: Lukas Maurer <lukas.maurer@siemens.com>
siemens · Feb 14, 2025 · 5a12c6a · 5a12c6a
1 parent de4f68d
commit 5a12c6a
Show file tree

Hide file tree

Showing 27 changed files with 420 additions and 83 deletions.
diff --git a/.changeset/pretty-guests-jog.md b/.changeset/pretty-guests-jog.md
@@ -0,0 +1,8 @@
+---
+'@siemens/ix-angular': minor
+'@siemens/ix': minor
+'@siemens/ix-vue': minor
+---
+
+`ix-message-bar`: Event `closedChange` can now be prevented via `event.preventDefault()`. 
+An additional event is added to get notified after the close animation of the `ix-message-bar` is finished.
diff --git a/packages/angular-test-app/src/app/app-routing.module.ts b/packages/angular-test-app/src/app/app-routing.module.ts
@@ -151,6 +151,7 @@ import MenuCategory from '../preview-examples/menu-category';
 import MenuWithBottomTabs from '../preview-examples/menu-with-bottom-tabs';
 import Message from '../preview-examples/message';
 import MessageBar from '../preview-examples/message-bar';
+import MessageBarRemoval from '../preview-examples/message-bar-removal';
 import ModalByInstance from '../preview-examples/modal-by-instance';
 import ModalByInstanceContent from '../preview-examples/modal-by-instance-content';
 import ModalByTemplate from '../preview-examples/modal-by-template';
@@ -716,6 +717,10 @@ const routes: Routes = [
         path: 'message-bar',
         component: MessageBar,
       },
+      {
+        path: 'message-bar-removal',
+        component: MessageBarRemoval,
+      },
       {
         path: 'modal-by-instance-content',
         component: ModalByInstanceContent,

diff --git a/packages/angular-test-app/src/app/app.module.ts b/packages/angular-test-app/src/app/app.module.ts
@@ -159,6 +159,7 @@ import MenuCategory from '../preview-examples/menu-category';
 import MenuWithBottomTabs from '../preview-examples/menu-with-bottom-tabs';
 import Message from '../preview-examples/message';
 import MessageBar from '../preview-examples/message-bar';
+import MessageBarRemoval from '../preview-examples/message-bar-removal';
 import ModalByInstance from '../preview-examples/modal-by-instance';
 import ModalByInstanceContent from '../preview-examples/modal-by-instance-content';
 import ModalByTemplate from '../preview-examples/modal-by-template';
@@ -372,6 +373,7 @@ import WorkflowVertical from '../preview-examples/workflow-vertical';
     MenuWithBottomTabs,
     Message,
     MessageBar,
+    MessageBarRemoval,
     ModalByInstanceContent,
     ModalByInstance,
     ModalByTemplate,

diff --git a/packages/angular-test-app/src/preview-examples/message-bar-removal.html b/packages/angular-test-app/src/preview-examples/message-bar-removal.html
@@ -0,0 +1,24 @@
+<!--
+SPDX-FileCopyrightText: 2025 Siemens AG
+
+SPDX-License-Identifier: MIT
+
+This source code is licensed under the MIT license found in the
+LICENSE file in the root directory of this source tree.
+-->
+
+<div class="message-bar">
+  <ix-message-bar
+    *ngIf="messageBarVisible"
+    (closeAnimationCompleted)="handleCloseAnimationCompleted()"
+  >
+    Message text
+  </ix-message-bar>
+
+  <ix-button
+    *ngIf="!messageBarVisible"
+    (click)="handleShowMessage()"
+  >
+    Show message bar
+  </ix-button>
+</div>
diff --git a/packages/angular-test-app/src/preview-examples/message-bar-removal.ts b/packages/angular-test-app/src/preview-examples/message-bar-removal.ts
@@ -0,0 +1,27 @@
+/*
+ * SPDX-FileCopyrightText: 2024 Siemens AG
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import { Component } from '@angular/core';
+
+@Component({
+  selector: 'app-message-bar-single-removal',
+  templateUrl: './message-bar-removal.html',
+  styleUrls: ['./message-bar.css']
+})
+export default class MessageBarRemoval {
+  messageBarVisible = true;
+
+  handleCloseAnimationCompleted() {
+    this.messageBarVisible = false;
+  }
+
+  handleShowMessage() {
+    this.messageBarVisible = true;
+  }
+}
diff --git a/packages/angular-test-app/src/preview-examples/message-bar.html b/packages/angular-test-app/src/preview-examples/message-bar.html
@@ -0,0 +1,19 @@
+<!--
+SPDX-FileCopyrightText: 2025 Siemens AG
+
+SPDX-License-Identifier: MIT
+
+This source code is licensed under the MIT license found in the
+LICENSE file in the root directory of this source tree.
+-->
+
+<div class="message-bar">
+  <ix-message-bar dismissible="false">Message text</ix-message-bar>
+  <ix-message-bar dismissible="false" type="warning">Message text</ix-message-bar>
+  <ix-message-bar dismissible="false" type="danger">
+    <div class="d-flex align-items-center justify-content-between">
+      Message text
+      <ix-button>Action</ix-button>
+    </div>
+  </ix-message-bar>
+</div>
diff --git a/packages/angular-test-app/src/preview-examples/message-bar.ts b/packages/angular-test-app/src/preview-examples/message-bar.ts
@@ -11,18 +11,7 @@ import { Component } from '@angular/core';
 
 @Component({
   selector: 'app-example',
-  template: `
-    <div class="message-bar">
-      <ix-message-bar>Message text</ix-message-bar>
-      <ix-message-bar type="warning">Message text</ix-message-bar>
-      <ix-message-bar type="danger">
-        <div class="d-flex align-items-center justify-content-between">
-          Message text
-          <ix-button>Action</ix-button>
-        </div>
-      </ix-message-bar>
-    </div>
-  `,
+  templateUrl: './message-bar.html',
   styleUrls: ['./message-bar.css'],
 })
 export default class MessageBar {}
diff --git a/packages/angular/src/components.ts b/packages/angular/src/components.ts
@@ -1812,7 +1812,7 @@ export class IxMessageBar {
   constructor(c: ChangeDetectorRef, r: ElementRef, protected z: NgZone) {
     c.detach();
     this.el = r.nativeElement;
-    proxyOutputs(this, this.el, ['closedChange']);
+    proxyOutputs(this, this.el, ['closedChange', 'closeAnimationCompleted']);
   }
 }
 
@@ -1822,6 +1822,10 @@ export declare interface IxMessageBar extends Components.IxMessageBar {
    * An event emitted when the close button is clicked
    */
   closedChange: EventEmitter<CustomEvent<any>>;
+  /**
+   * An event emitted when the close animation is completed
+   */
+  closeAnimationCompleted: EventEmitter<CustomEvent<any>>;
 }
 
 

diff --git a/packages/core/component-doc.json b/packages/core/component-doc.json
@@ -13934,6 +13934,20 @@
       ],
       "methods": [],
       "events": [
+        {
+          "event": "closeAnimationCompleted",
+          "detail": "any",
+          "bubbles": true,
+          "complexType": {
+            "original": "any",
+            "resolved": "any",
+            "references": {}
+          },
+          "cancelable": true,
+          "composed": true,
+          "docs": "An event emitted when the close animation is completed",
+          "docsTags": []
+        },
         {
           "event": "closedChange",
           "detail": "any",

diff --git a/packages/core/src/components.d.ts b/packages/core/src/components.d.ts
@@ -4435,6 +4435,7 @@ declare global {
     };
     interface HTMLIxMessageBarElementEventMap {
         "closedChange": any;
+        "closeAnimationCompleted": any;
     }
     interface HTMLIxMessageBarElement extends Components.IxMessageBar, HTMLStencilElement {
         addEventListener<K extends keyof HTMLIxMessageBarElementEventMap>(type: K, listener: (this: HTMLIxMessageBarElement, ev: IxMessageBarCustomEvent<HTMLIxMessageBarElementEventMap[K]>) => any, options?: boolean | AddEventListenerOptions): void;
@@ -7231,6 +7232,10 @@ declare namespace LocalJSX {
           * If true, close button is enabled and alert can be dismissed by the user
          */
         "dismissible"?: boolean;
+        /**
+          * An event emitted when the close animation is completed
+         */
+        "onCloseAnimationCompleted"?: (event: IxMessageBarCustomEvent<any>) => void;
         /**
           * An event emitted when the close button is clicked
          */

diff --git a/packages/core/src/components/message-bar/message-bar.tsx b/packages/core/src/components/message-bar/message-bar.tsx
@@ -40,6 +40,11 @@ export class MessageBar {
    */
   @Event() closedChange!: EventEmitter;
 
+  /**
+   * An event emitted when the close animation is completed
+   */
+  @Event() closeAnimationCompleted!: EventEmitter;
+
   @State() icon?: 'error' | 'warning' | 'info';
 
   @State() color?: NotificationColor;
@@ -66,16 +71,20 @@ export class MessageBar {
   }
 
   private closeAlert(el: HTMLElement) {
-    anime({
-      targets: el,
-      duration: MessageBar.duration,
-      opacity: [1, 0],
-      easing: 'easeOutSine',
-      complete: () => {
-        el.classList.add('d-none');
-      },
-    });
-    this.closedChange.emit();
+    const { defaultPrevented } = this.closedChange.emit();
+
+    if (!defaultPrevented) {
+      anime({
+        targets: el,
+        duration: MessageBar.duration,
+        opacity: [1, 0],
+        easing: 'easeOutSine',
+        complete: () => {
+          el.classList.add('d-none');
+          this.closeAnimationCompleted.emit();
+        },
+      });
+    }
   }
 
   render() {

diff --git a/packages/documentation/docs/controls/_message_bar_code.mdx b/packages/documentation/docs/controls/_message_bar_code.mdx
@@ -0,0 +1,36 @@
+import Props from './../auto-generated/ix-message-bar/props.md';
+import Events from './../auto-generated/ix-message-bar/events.md';
+import Playground from '@site/src/components/PlaygroundV3';
+
+## Development
+
+### Examples
+
+#### Basic
+The message bar Web Component only provides the visual appearance of the message bar.
+To fully utilize the message bar, you need to implement a mechanism to remove it from the DOM when it is no longer needed.
+This typically involves handling the close event and updating the state of your application to reflect the removal of the message bar.
+
+<Playground
+  name="message-bar"
+  height="14rem"
+>
+</Playground>
+
+#### Dismissible
+
+<Playground
+  name="message-bar-removal"
+  height="14rem"
+>
+</Playground>
+
+## API
+
+### Properties
+
+<Props />
+
+### Events
+
+<Events />
diff --git a/packages/documentation/docs/controls/_toast_styleguide.md b/packages/documentation/docs/controls/_toast_styleguide.md
@@ -41,11 +41,11 @@ Toasts are small pop-ups that provide simple feedback on a process. They are UI
 - Do use toasts to instantly inform a user about the outcome of an action
 - Do include shortcuts to undo an action immediately after it's taken
 - Do stick with a consistent position for toasts within the same app and avoid interchanging their positions
-- Don’t use toasts for high-priority or critical alerts that prevent the user from continuing their work (use a [modal](modal.md) or a [message bar](messagebar.md) instead)
+- Don’t use toasts for high-priority or critical alerts that prevent the user from continuing their work (use a [modal](modal.md) or a [message bar](message-bar.mdx) instead)
 - Don’t edit or reuse icons or icon colors from the four predefined toast types when creating custom toasts
 
 ### Related patterns
 
 - [Modal](modal.md)
-- [Message bar](messagebar.md)
+- [Message bar](message-bar.mdx)
 - [Drawer](drawer.md)
diff --git a/packages/documentation/docs/controls/application-frame/_popover-news_styleguide.md b/packages/documentation/docs/controls/application-frame/_popover-news_styleguide.md
@@ -23,11 +23,11 @@ Unlike a modal, popover news does not prevent users from navigating and interact
 ### Dos and Don’ts
 
 - Do use popover news for "nice to know" information
-- Don‘t use popover news for essential information a user must read, instead use a [modal](../modal.md) or a [message bar](../messagebar.md)
+- Don‘t use popover news for essential information a user must read, instead use a [modal](../modal.md) or a [message bar](../message-bar.mdx)
 - Don‘t use popover news for system feedback or messages, instead use a [modal](../modal.md) or a [toast message](../toast.md)
 
 ### Related patterns
 
 - [Toast message](../toast.md)
 - [Modal](../modal.md)
-- [Message bar](../messagebar.md)
+- [Message bar](../message-bar.mdx)
diff --git a/packages/documentation/docs/controls/message-bar.mdx b/packages/documentation/docs/controls/message-bar.mdx
@@ -0,0 +1,5 @@
+import DocsCode from './\_message_bar_code.mdx';
+
+# Message bar
+
+<DocsCode />
diff --git a/packages/documentation/docs/controls/messagebar.md b/packages/documentation/docs/controls/messagebar.md
diff --git a/packages/documentation/docs/migration/uxt.md b/packages/documentation/docs/migration/uxt.md
@@ -75,27 +75,27 @@ If you're facing any other problems, please raise an issue in GitHub [raising an
 
 As some of the components are named differently in Industrial Experience, please consult this list of the most important component name differences to help make your migration easier:
 
-| **User Experience Toolkit**                      | **Industrial Experience**                                             |
-| ------------------------------------------------ | --------------------------------------------------------------------- |
-| App bar                                          | [Nav menu](../controls/application-frame/application-menu.md)         |
-| Badge                                            | [Pill](../controls/pill.md), [chip](../controls/chip.md)                                                            |
-| Busy indicator                                   | [Spinner](../controls/spinner.md)                                                               |
+| **User Experience Toolkit**                      | **Industrial Experience**                                                                              |
+| ------------------------------------------------ |--------------------------------------------------------------------------------------------------------|
+| App bar                                          | [Nav menu](../controls/application-frame/application-menu.md)                                          |
+| Badge                                            | [Pill](../controls/pill.md), [chip](../controls/chip.md)                                               |
+| Busy indicator                                   | [Spinner](../controls/spinner.md)                                                                      |
 | Button<br/>- primary<br/>- secondary<br/>- ghost | [Button](../controls/buttons/button.md)<br/>- primary filled<br/>- primary outline<br/>- primary ghost |
-| Card grid                                        | [Layout grid](../controls/layout-grid.md)                                                           |
-| Container                                        | [Card](../controls/card.md)                                                                  |
-| Dialog                                           | [Modal](../controls/modal.md)                                                                 |
-| Dropzone                                         | [Upload](../controls/upload.md)                                                                |
-| List                                             | [Event list](../controls/event-list.md)                                                            |
-| Stepper                                          | [Workflow](../controls/workflow.md)                                                              |
-| Menu                                             | [Dropdown button](../controls/buttons/dropdown-button.md)                                                       |
-| Message                                          | [Message bar](../controls/messagebar.md)                                                           |
-| Notification                                     | [Toast](../controls/toast.md)                                                                 |
-| Pager                                            | [Pagination](../controls/pagination.md)                                                            |
-| Popover                                          | [Tooltip](../controls/tooltip.md), [dropdown](../controls/dropdown.md)                                                     |
-| Switch                                           | [Toggle](../controls/toggle.mdx)                                                                |
-| Context region                                   | [Pane](../controls/panes.md) (inline right)                                                   |
-| Item region                                      | [Pane](../controls/panes.md) (floating right)                                                 |
-| Leading region                                   | [Pane](../controls/panes.md) (inline left)                                                    |
+| Card grid                                        | [Layout grid](../controls/layout-grid.md)                                                              |
+| Container                                        | [Card](../controls/card.md)                                                                            |
+| Dialog                                           | [Modal](../controls/modal.md)                                                                          |
+| Dropzone                                         | [Upload](../controls/upload.md)                                                                        |
+| List                                             | [Event list](../controls/event-list.md)                                                                |
+| Stepper                                          | [Workflow](../controls/workflow.md)                                                                    |
+| Menu                                             | [Dropdown button](../controls/buttons/dropdown-button.md)                                              |
+| Message                                          | [Message bar](../controls/message-bar.mdx)                                                             |
+| Notification                                     | [Toast](../controls/toast.md)                                                                          |
+| Pager                                            | [Pagination](../controls/pagination.md)                                                                |
+| Popover                                          | [Tooltip](../controls/tooltip.md), [dropdown](../controls/dropdown.md)                                 |
+| Switch                                           | [Toggle](../controls/toggle.mdx)                                                                       |
+| Context region                                   | [Pane](../controls/panes.md) (inline right)                                                            |
+| Item region                                      | [Pane](../controls/panes.md) (floating right)                                                          |
+| Leading region                                   | [Pane](../controls/panes.md) (inline left)                                                             |
 
 ## System icons