feat(modal)- Return closable instance

.changeset/sharp-ladybugs-clap.md

@@ -0,0 +1,7 @@
+---
+"@siemens/ix-angular": patch
+"@siemens/ix-react": patch
+"@siemens/ix-vue": patch
+---
+
+Add dismissModal function to allow programmatic closing of **ix-modal**s.

packages/angular-standalone-test-app/src/app/app.routes.ts

@@ -947,6 +947,11 @@ export const routes: Routes = [
             (m) => m.default
           ),
       },
+      {
+        path: 'modal-close',
+        loadComponent: () =>
+          import('../preview-examples/modal-close').then((m) => m.default),
+      },
       {
         path: 'modal-by-template',
         loadComponent: () =>

packages/angular-standalone-test-app/src/preview-examples/modal-close.ts

@@ -0,0 +1,35 @@
+/*
+ * 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.
+ */
+
+import { Component } from '@angular/core';
+import { IxButton } from '@siemens/ix-angular/standalone';
+
+import { ModalService } from '@siemens/ix-angular';
+import ModalByInstanceExample from './modal-by-instance-content';
+
+@Component({
+  standalone: true,
+  selector: 'app-example',
+  imports: [IxButton],
+  template:
+    '<ix-button (click)="openModal()">Show modal (auto-dismiss)</ix-button>',
+})
+export default class ModalClose {
+  constructor(private readonly modalService: ModalService) {}
+
+  async openModal() {
+    const modalInstance = await this.modalService.open({
+      content: ModalByInstanceExample,
+      data: 'Some data',
+    });
+    setTimeout(() => {
+      this.modalService.close(modalInstance, 'closed after 5 seconds');
+    }, 5000);
+  }
+}

packages/angular-test-app/src/app/app-routing.module.ts

@@ -162,6 +162,7 @@ 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 ModalClose from '../preview-examples/modal-close';
 import ModalByInstanceContent from '../preview-examples/modal-by-instance-content';
 import ModalByTemplate from '../preview-examples/modal-by-template';
 import ModalFormIxButtonSubmit from '../preview-examples/modal-form-ix-button-submit';
@@ -777,6 +778,10 @@ const routes: Routes = [
         path: 'modal-by-instance',
         component: ModalByInstance,
       },
+      {
+        path: 'modal-close',
+        component: ModalClose,
+      },
       {
         path: 'modal-by-template',
         component: ModalByTemplate,

packages/angular-test-app/src/app/app.module.ts

@@ -173,6 +173,7 @@ 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';
+import ModalClose from '../preview-examples/modal-close';
 import ModalFormIxButtonSubmit from '../preview-examples/modal-form-ix-button-submit';
 import ModalSizes from '../preview-examples/modal-sizes';
 import NumberInput from '../preview-examples/number-input';
@@ -400,6 +401,7 @@ import WorkflowVertical from '../preview-examples/workflow-vertical';
     ModalByInstanceContent,
     ModalByInstance,
     ModalByTemplate,
+    ModalClose,
     ModalFormIxButtonSubmit,
     ModalSizes,
     PaginationAdvanced,

packages/angular-test-app/src/preview-examples/modal-close.ts

@@ -0,0 +1,32 @@
+/*
+ * 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.
+ */
+
+import { Component } from '@angular/core';
+import { ModalService } from '@siemens/ix-angular';
+import ModalByInstanceExample from './modal-by-instance-content';
+
+@Component({
+  standalone: false,
+  selector: 'app-example',
+  template:
+    '<ix-button (click)="openModal()">Show modal (auto-dismiss)</ix-button>',
+})
+export default class ModalClose {
+  constructor(private readonly modalService: ModalService) {}
+
+  async openModal() {
+    const modalInstance = await this.modalService.open({
+      content: ModalByInstanceExample,
+      data: 'Some data',
+    });
+    setTimeout(() => {
+      this.modalService.close(modalInstance, 'closed after 5 seconds');
+    }, 5000);
+  }
+}

packages/angular/common/src/providers/modal/modal.service.spec.ts

@@ -103,3 +103,37 @@ test('should create modal by component typ', async () => {
     modalElement: { type: 'html-element' },
   });
 });
+
+test('should close modal instance with reason and mark as closed', () => {
+  const closeModalMock = jest.fn(function (
+    this: { closed?: boolean },
+    reason?: any
+  ) {
+    if (typeof reason !== 'undefined') {
+      this.closed = true;
+    }
+  });
+  const instance = {
+    htmlElement: {
+      closeModal: closeModalMock,
+      closed: false,
+    },
+  };
+  const modalService = new ModalService({} as any, {} as any, {} as any);
+  const reason = 'user-dismissed';
+  modalService.close(instance, reason);
+  expect(closeModalMock).toHaveBeenCalledWith(reason);
+  expect(instance.htmlElement.closed).toBe(true);
+});
+
+test('should throw TypeError if instance cannot be closed', () => {
+  const instance = {
+    htmlElement: {},
+  };
+  const modalService = new ModalService({} as any, {} as any, {} as any);
+
+  expect(() => modalService.close(instance)).toThrow(TypeError);
+  expect(() => modalService.close(instance)).toThrow(
+    'Invalid modal instance: cannot close'
+  );
+});

packages/angular/common/src/providers/modal/modal.service.ts

@@ -36,6 +36,17 @@ export class ModalService {
     private injector: Injector
   ) {}
 
+  public close<TReason = any>(
+    instance: { htmlElement: any },
+    reason?: TReason
+  ): void {
+    if (typeof instance?.htmlElement?.closeModal === 'function') {
+      instance.htmlElement.closeModal(reason);
+    } else {
+      throw new TypeError('Invalid modal instance: cannot close');
+    }
+  }
+
   public async open<TData = any, TReason = any>(config: ModalConfig<TData>) {
     const context: ModalContext<TData> = {
       close: null,

packages/angular/src/providers/modal/modal.service.ts

@@ -41,4 +41,11 @@ export class ModalService extends BaseModalService {
   ): Promise<ModalInstance<TReason>> {
     return super.open(config);
   }
+
+  public close<TReason = any>(
+    instance: ModalInstance<TReason>,
+    reason?: TReason
+  ): void {
+    super.close(instance, reason);
+  }
 }

packages/angular/standalone/src/providers/modal.ts

@@ -37,4 +37,11 @@ export class ModalService extends BaseModalService {
     defineCustomElement();
     return super.open(config);
   }
+
+  public close<TReason = any>(
+    instance: ModalInstance<TReason>,
+    reason?: TReason
+  ): void {
+    super.close(instance, reason);
+  }
 }

packages/html-test-app/src/preview-examples/modal-close.html

@@ -0,0 +1,96 @@
+<!--
+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.
+-->
+
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Modal example</title>
+  </head>
+  <body>
+    <ix-button>Show modal (auto-dismiss)</ix-button>
+    <template id="modal-example-template">
+      <ix-modal-header>Message headline</ix-modal-header>
+      <ix-modal-content>Message text lorem ipsum</ix-modal-content>
+      <ix-modal-footer>
+        <ix-button outline data-cancel>Cancel</ix-button>
+        <ix-button data-okay>OK</ix-button>
+      </ix-modal-footer>
+    </template>
+
+    <script type="module">
+      import { showModal, closeModal, dismissModal } from '@siemens/ix';
+
+      function createExampleModal() {
+        const name = 'modal-example';
+        window.customElements.define(
+          name,
+          class extends HTMLElement {
+            isInitalRender = false;
+
+            constructor() {
+              super();
+            }
+
+            connectedCallback() {
+              if (this.isInitalRender) {
+                return;
+              }
+
+              this.isInitalRender = true;
+              this.firstRender();
+            }
+
+            firstRender() {
+              const modalTemplate = document.getElementById(
+                'modal-example-template'
+              );
+              const template = modalTemplate.content.cloneNode(true);
+
+              const cancelButton = template.querySelector('[data-cancel]');
+              const okayButton = template.querySelector('[data-okay]');
+
+              cancelButton.addEventListener('click', () => {
+                dismissModal(this);
+              });
+              okayButton.addEventListener('click', () => {
+                closeModal(this);
+              });
+
+              this.append(template);
+            }
+          }
+        );
+
+        return name;
+      }
+
+      (async function () {
+        const exampleModalName = createExampleModal();
+
+        await window.customElements.whenDefined('ix-button');
+        const button = document.querySelector('ix-button');
+
+        button.addEventListener('click', async () => {
+          const customModal = document.createElement(exampleModalName);
+
+          const modal = await showModal({
+            content: customModal,
+          });
+
+          setTimeout(() => {
+            closeModal(customModal, 'closed after 5 seconds');
+          }, 5000);
+        });
+      })();
+    </script>
+    <script type="module" src="./init.js"></script>
+  </body>
+</html>

packages/react-test-app/src/main.tsx

@@ -161,6 +161,7 @@ import Message from './preview-examples/message';
 import MessageBar from './preview-examples/message-bar';
 import MessageBarRemoval from './preview-examples/message-bar-removal.tsx';
 import Modal from './preview-examples/modal';
+import ModalClose from './preview-examples/modal-close.tsx';
 import ModalFormIxButtonSubmit from './preview-examples/modal-form-ix-button-submit.tsx';
 import ModalSizes from './preview-examples/modal-sizes';
 import NumberInput from './preview-examples/number-input';
@@ -597,6 +598,7 @@ ReactDOM.createRoot(document.getElementById('root') as HTMLElement).render(
         />
 
         <Route path="/preview/modal" element={<Modal />} />
+        <Route path="/preview/modal-close" element={<ModalClose />} />
         <Route
           path="/preview/pagination-advanced"
           element={<PaginationAdvanced />}

packages/react-test-app/src/preview-examples/modal-close.tsx

@@ -0,0 +1,63 @@
+/*
+ * 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.
+ */
+
+import {
+  IxButton,
+  IxModalContent,
+  IxModalFooter,
+  IxModalHeader,
+  Modal,
+  ModalRef,
+  showModal,
+  dismissModal,
+} from '@siemens/ix-react';
+import { useRef } from 'react';
+
+function CustomModal() {
+  const modalRef = useRef<ModalRef>(null);
+
+  const close = () => {
+    modalRef.current?.close('close payload!');
+  };
+  const dismiss = () => {
+    modalRef.current?.dismiss('dismiss payload');
+  };
+
+  return (
+    <Modal ref={modalRef}>
+      <IxModalHeader onCloseClick={() => dismiss()}>
+        Message headline
+      </IxModalHeader>
+      <IxModalContent>Message text lorem ipsum</IxModalContent>
+      <IxModalFooter>
+        <IxButton outline onClick={() => dismiss()}>
+          Cancel
+        </IxButton>
+        <IxButton onClick={() => close()}>OK</IxButton>
+      </IxModalFooter>
+    </Modal>
+  );
+}
+
+export default () => {
+  async function show() {
+    const modalInstance = await showModal({
+      content: <CustomModal />,
+    });
+    setTimeout(() => {
+      dismissModal(modalInstance);
+    }, 5000);
+  }
+
+  return (
+    <>
+      <IxButton onClick={show}>Show modal (auto-dismiss)</IxButton>
+    </>
+  );
+};