ansys-solutions-dash-super-components 0.2.dev7__py3-none-any.whl

ansys/solutions/dash_super_components/transaction_supervisor.py

@@ -0,0 +1,587 @@
+# Copyright (C) 2026 ANSYS, Inc. and/or its affiliates.
+# SPDX-License-Identifier: Apache-2.0
+#
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+"""Provides a Dash component for tracking the status of SAF transaction method."""
+
+from datetime import datetime, timedelta
+import time
+from typing import Any
+import uuid
+
+try:
+    # dash >=3.2.0
+    from dash import NoUpdate
+except ImportError:
+    # dash >=2.18.2, <3.2.0
+    from dash._callback import NoUpdate  # pyright: ignore[reportPrivateImportUsage]
+
+try:
+    # dash-extensions < 2.0.5
+    from dash_extensions.enrich import _Wildcard  # pyright: ignore[reportAttributeAccessIssue]
+except ImportError:
+    # dash-extensions >= 2.0.5
+    from dash_extensions.enrich import (
+        Wildcard as _Wildcard,  # pyright: ignore[reportAttributeAccessIssue]
+    )
+from dash_extensions.enrich import (
+    MATCH,
+    Input,
+    Output,
+    State,
+    callback,
+    dcc,
+    html,
+    no_update,
+)
+import dash_mantine_components as dmc
+
+from ansys.solutions.dash_super_components.utils.aio_ids import AIOIds
+from ansys.solutions.dash_super_components.utils.api_requests import GlowAPIRequest
+from ansys.solutions.dash_super_components.utils.svg_icons import IconNames, create_base64_svg_src
+
+TRANSACTION_STATUS_BADGE_PROPERTIES = {
+    "run-required": {
+        "color": "gray",
+    },
+    "running": {
+        "color": "indigo",
+    },
+    "completed": {
+        "color": "lime",
+    },
+    "failed": {
+        "color": "red",
+    },
+}
+
+
+class TransactionSupervisor(html.Div):
+    """
+    A Dash component for monitoring the status of a SAF GLOW transaction method.
+
+    TransactionSupervisor is based on the Dash All-in-One (AIO) component pattern. It polls
+    the GLOW API to track method status in real time and displays elapsed time, started time,
+    and a color-coded status badge.
+
+    .. warning::
+
+        This component requires a SAF-based solution with access to the GLOW API. It must
+        be instantiated inside a callback (not directly in the layout) because it needs the
+        project URL from ``DashClient``.
+
+    To activate monitoring from a callback use::
+
+        TransactionSupervisor.ids.activate_supervision(aio_id)  # Store; set to True
+
+    Parameters
+    ----------
+    url : str
+        The URL of the GLOW API server.
+    step_name : str
+        The name of the GLOW step (StepModel) that contains the method.
+    method_name : str
+        The name of the GLOW transaction method whose status is being monitored.
+    title : str, optional
+        Title displayed in the monitoring card.
+    show : bool, optional
+        Whether to show the monitoring card. Default is ``True``.
+    aio_id : str, optional
+        Unique identifier for this component instance. A UUID is generated when
+        not provided.
+    width : str or int, optional
+        Width of the monitoring card. Default is ``400``.
+    fontsize : str, optional
+        Font size of the text in the card. Default is ``'14px'``.
+    title_fontsize : str, optional
+        Font size of the title in the card. Default is ``'16px'``.
+    orientation : str, optional
+        Layout orientation of the card (``'horizontal'`` or ``'vertical'``).
+        Default is ``'horizontal'``.
+    """
+
+    class TransactionSupervisorIds(AIOIds):
+        """Provides IDs for the subcomponents of :class:`TransactionSupervisor`."""
+
+        @classmethod
+        def _monitoring_data(cls, aio_id: str | _Wildcard) -> dict[str, Any]:
+            """Return the ID for the monitoring data store.
+
+            Parameters
+            ----------
+            aio_id : str or _Wildcard
+                The component's unique identifier.
+
+            Returns
+            -------
+            dict[str, Any]
+                The unique ID dictionary for the monitoring data store subcomponent.
+            """
+            return cls.make_id_dict("transaction-supervisor", "monitoring-data", aio_id)
+
+        @classmethod
+        def _loader(cls, aio_id: str | _Wildcard) -> dict[str, Any]:
+            """Return the ID for the loader store.
+
+            Parameters
+            ----------
+            aio_id : str or _Wildcard
+                The component's unique identifier.
+
+            Returns
+            -------
+            dict[str, Any]
+                The unique ID dictionary for the loader store subcomponent.
+            """
+            return cls.make_id_dict("transaction-supervisor", "loader", aio_id)
+
+        @classmethod
+        def _interval(cls, aio_id: str | _Wildcard) -> dict[str, Any]:
+            """Return the ID for the interval component.
+
+            Parameters
+            ----------
+            aio_id : str or _Wildcard
+                The component's unique identifier.
+
+            Returns
+            -------
+            dict[str, Any]
+                The unique ID dictionary for the interval subcomponent.
+            """
+            return cls.make_id_dict("transaction-supervisor", "interval", aio_id)
+
+        @classmethod
+        def _container(cls, aio_id: str | _Wildcard) -> dict[str, Any]:
+            """Return the ID for the container component.
+
+            Parameters
+            ----------
+            aio_id : str or _Wildcard
+                The component's unique identifier.
+
+            Returns
+            -------
+            dict[str, Any]
+                The unique ID dictionary for the container subcomponent.
+            """
+            return cls.make_id_dict("transaction-supervisor", "container", aio_id)
+
+        @classmethod
+        def activate_supervision(cls, aio_id: str | _Wildcard) -> dict[str, Any]:
+            """Return the ID for the activate supervision store.
+
+            Parameters
+            ----------
+            aio_id : str or _Wildcard
+                The component's unique identifier.
+
+            Returns
+            -------
+            dict[str, Any]
+                The unique ID dictionary for the activate supervision store subcomponent.
+            """
+            return cls.make_id_dict("transaction-supervisor", "activate-supervision", aio_id)
+
+        @classmethod
+        def transaction_status_badge(cls, aio_id: str | _Wildcard) -> dict[str, Any]:
+            """Return the ID for the transaction status badge.
+
+            Parameters
+            ----------
+            aio_id : str or _Wildcard
+                The component's unique identifier.
+
+            Returns
+            -------
+            dict[str, Any]
+                The unique ID dictionary for the transaction status badge subcomponent.
+            """
+            return cls.make_id_dict("transaction-supervisor", "transaction-status-badge", aio_id)
+
+        @classmethod
+        def started_time_label(cls, aio_id: str | _Wildcard) -> dict[str, Any]:
+            """Return the ID for the started time label.
+
+            Parameters
+            ----------
+            aio_id : str or _Wildcard
+                The component's unique identifier.
+
+            Returns
+            -------
+            dict[str, Any]
+                The unique ID dictionary for the started time label subcomponent.
+            """
+            return cls.make_id_dict("transaction-supervisor", "started-time-label", aio_id)
+
+        @classmethod
+        def elapsed_time_label(cls, aio_id: str | _Wildcard) -> dict[str, Any]:
+            """Return the ID for the elapsed time label.
+
+            Parameters
+            ----------
+            aio_id : str or _Wildcard
+                The component's unique identifier.
+
+            Returns
+            -------
+            dict[str, Any]
+                The unique ID dictionary for the elapsed time label subcomponent.
+            """
+            return cls.make_id_dict("transaction-supervisor", "elapsed-time-label", aio_id)
+
+        @classmethod
+        def switch(cls, aio_id: str | _Wildcard) -> dict[str, Any]:
+            """Return the ID for the switch component.
+
+            Parameters
+            ----------
+            aio_id : str or _Wildcard
+                The component's unique identifier.
+
+            Returns
+            -------
+            dict[str, Any]
+                The unique ID dictionary for the switch subcomponent.
+            """
+            return cls.make_id_dict("transaction-supervisor", "switch", aio_id)
+
+    ids = TransactionSupervisorIds
+
+    def __init__(
+        self,
+        url: str,
+        step_name: str,
+        method_name: str,
+        title: str = "Transaction Supervisor",
+        show: bool = True,
+        aio_id: str | None = None,
+        width: str | int = 400,
+        fontsize: str = "14px",
+        title_fontsize: str = "16px",
+        orientation: str = "horizontal",
+    ):
+        self._url = url
+        self._step_name = step_name
+        self._method_name = method_name
+        self._title = title
+        self._show = show
+        self._width = width
+        self._fontsize = fontsize
+        self._orientation = orientation
+        self._title_fontsize = title_fontsize
+        self.aio_id = aio_id if aio_id is not None else str(uuid.uuid4())
+
+        super().__init__(
+            [
+                html.Div(
+                    [
+                        dcc.Store(
+                            id=self.ids._monitoring_data(self.aio_id),
+                            storage_type="session",
+                            data={
+                                "url": url,
+                                "step_name": self._step_name,
+                                "method_name": self._method_name,
+                            },
+                        ),
+                        dcc.Store(
+                            id=self.ids.activate_supervision(self.aio_id),
+                            storage_type="session",
+                            data=False,
+                        ),
+                        dcc.Interval(
+                            id=self.ids._interval(self.aio_id),
+                            interval=1000,
+                            n_intervals=0,
+                            disabled=True,
+                        ),
+                        dmc.Card(
+                            children=[
+                                dmc.CardSection(
+                                    dmc.Group(
+                                        children=[
+                                            html.Div(
+                                                self._title,
+                                                style={
+                                                    "display": "inline-block",
+                                                    "fontSize": self._title_fontsize,
+                                                },
+                                            ),
+                                            dcc.Loading(
+                                                id=self.ids._loader(self.aio_id),
+                                                display="hide",
+                                            ),
+                                            dmc.HoverCard(
+                                                children=[
+                                                    dmc.HoverCardTarget(
+                                                        dmc.Switch(
+                                                            id=self.ids.switch(
+                                                                self.aio_id,
+                                                            ),
+                                                            checked=self._show,
+                                                            offLabel=html.Img(
+                                                                src=create_base64_svg_src(
+                                                                    IconNames.MDI_HIDE,
+                                                                ),
+                                                            ),
+                                                            onLabel=html.Img(
+                                                                src=create_base64_svg_src(
+                                                                    IconNames.MDI_SHOW,
+                                                                    color="#fff",
+                                                                ),
+                                                            ),
+                                                            size="sm",
+                                                        ),
+                                                    ),
+                                                    dmc.HoverCardDropdown(
+                                                        dmc.Text(
+                                                            "Show/Hide monitoring panel.",
+                                                            size="sm",
+                                                        ),
+                                                    ),
+                                                ],
+                                                withArrow=True,
+                                                shadow="md",
+                                            ),
+                                        ],
+                                        justify="space-around",
+                                    ),
+                                    withBorder=True,
+                                    inheritPadding=True,
+                                    py="xs",
+                                ),
+                                html.Div(
+                                    dmc.Grid(
+                                        children=[
+                                            dmc.GridCol(
+                                                html.Div(
+                                                    [
+                                                        html.Div(
+                                                            "Transaction method status :",
+                                                            style={
+                                                                "display": "inline-block",
+                                                                "fontSize": self._fontsize,
+                                                                "marginTop": "5px",
+                                                            },
+                                                        ),
+                                                        html.Div(
+                                                            dmc.Badge(
+                                                                id=self.ids.transaction_status_badge(
+                                                                    self.aio_id,
+                                                                ),
+                                                                style={
+                                                                    "fontSize": self._fontsize,
+                                                                },
+                                                            ),
+                                                            style={
+                                                                "marginLeft": "5px",
+                                                                "display": "inline-block",
+                                                            },
+                                                        ),
+                                                    ],
+                                                    style={"display": "inline-block"},
+                                                ),
+                                                span=(
+                                                    "content"
+                                                    if self._orientation == "horizontal"
+                                                    else 12
+                                                ),
+                                            ),
+                                            dmc.GridCol(
+                                                html.Div(
+                                                    [
+                                                        html.Div(
+                                                            "Started time :",
+                                                            style={
+                                                                "display": "inline-block",
+                                                                "fontSize": self._fontsize,
+                                                                "marginTop": "5px",
+                                                            },
+                                                        ),
+                                                        html.Div(
+                                                            id=self.ids.started_time_label(
+                                                                self.aio_id,
+                                                            ),
+                                                            style={
+                                                                "display": "inline-block",
+                                                                "fontSize": self._fontsize,
+                                                                "marginTop": "5px",
+                                                                "marginLeft": "5px",
+                                                            },
+                                                        ),
+                                                    ],
+                                                    style={"display": "inline-block"},
+                                                ),
+                                                span=(
+                                                    "content"
+                                                    if self._orientation == "horizontal"
+                                                    else 12
+                                                ),
+                                            ),
+                                            dmc.GridCol(
+                                                html.Div(
+                                                    [
+                                                        html.Div(
+                                                            "Elapsed time :",
+                                                            style={
+                                                                "display": "inline-block",
+                                                                "fontSize": self._fontsize,
+                                                                "marginTop": "5px",
+                                                            },
+                                                        ),
+                                                        html.Div(
+                                                            id=self.ids.elapsed_time_label(
+                                                                self.aio_id,
+                                                            ),
+                                                            style={
+                                                                "display": "inline-block",
+                                                                "fontSize": self._fontsize,
+                                                                "marginTop": "5px",
+                                                                "marginLeft": "5px",
+                                                            },
+                                                        ),
+                                                    ],
+                                                    style={"display": "inline-block"},
+                                                ),
+                                                span=(
+                                                    "content"
+                                                    if self._orientation == "horizontal"
+                                                    else 12
+                                                ),
+                                            ),
+                                        ],
+                                        gutter="xs",
+                                    ),
+                                    id=self.ids._container(self.aio_id),
+                                    style={
+                                        "display": "inline-block",
+                                    },
+                                ),
+                            ],
+                            withBorder=True,
+                            shadow="sm",
+                            radius="md",
+                            w=self._width,
+                        ),
+                    ],
+                ),
+            ],
+        )
+
+    @staticmethod
+    @callback(
+        Output(ids._container(MATCH), "style"),
+        Input(ids.switch(MATCH), "checked"),
+    )
+    def show_supervision_card(
+        checked: bool,
+    ) -> dict[str, Any]:
+        """Hide or show the content of the supervision card."""
+        return {"display": "inline-block"} if checked else {"display": "none"}
+
+    @staticmethod
+    @callback(
+        Output(ids._interval(MATCH), "disabled"),
+        Output(ids._monitoring_data(MATCH), "data", allow_duplicate=True),
+        Output(ids._loader(MATCH), "display"),
+        Input(ids.activate_supervision(MATCH), "data"),
+        State(ids._monitoring_data(MATCH), "data"),
+        prevent_initial_call=True,
+    )
+    def start_stop_supervision(
+        supervision_active: bool,
+        data: dict[str, str],
+    ) -> tuple[bool, dict[str, str] | NoUpdate, str]:
+        """Start the monitoring of the transaction method."""
+        if not supervision_active:
+            return True, no_update, "hide"
+
+        # Reset timing data for a new transaction run
+        data["started_time"] = time.strftime("%Y-%m-%d %H:%M:%S", time.gmtime())
+        data["elapsed_time"] = str(timedelta(0))
+        # set the loader display to show
+        loader_display = "show"
+
+        return not supervision_active, data, loader_display
+
+    @staticmethod
+    @callback(
+        Output(ids.started_time_label(MATCH), "children", allow_duplicate=True),
+        Output(ids.elapsed_time_label(MATCH), "children", allow_duplicate=True),
+        Input(ids._monitoring_data(MATCH), "data"),
+    )
+    def update_time_labels(
+        data: dict[str, str],
+    ) -> tuple[str, str]:
+        """Update the started time and elapsed time labels."""
+        started_time = data.get("started_time", "")
+        elapsed_time = data.get("elapsed_time", str(timedelta(0)))
+        return started_time, elapsed_time
+
+    @staticmethod
+    @callback(
+        Output(ids.transaction_status_badge(MATCH), "children"),
+        Output(ids.transaction_status_badge(MATCH), "color"),
+        Output(ids.activate_supervision(MATCH), "data", allow_duplicate=True),
+        Output(ids._monitoring_data(MATCH), "data", allow_duplicate=True),
+        Input(ids._interval(MATCH), "n_intervals"),
+        State(ids._monitoring_data(MATCH), "data"),
+        State(ids.activate_supervision(MATCH), "data"),
+    )
+    def update_supervision_card(
+        n_intervals: int,
+        data: dict[str, str],
+        supervision_active: bool,
+    ) -> tuple[str, str, bool | NoUpdate, dict[str, str] | NoUpdate]:
+        """Update the supervision data and stop supervision when transaction has finished."""
+        glow_api_request = GlowAPIRequest(data["url"])
+        method_status = glow_api_request.get_transaction_method_status(
+            data["step_name"],
+            data["method_name"],
+        )
+        color = TRANSACTION_STATUS_BADGE_PROPERTIES[method_status]["color"]
+
+        if not supervision_active:
+            return (
+                method_status,
+                color,
+                no_update,
+                no_update,
+            )
+
+        # Stop supervision if method has finished
+        supervisor_active = False if method_status.lower() in ["completed", "failed"] else no_update
+
+        current_time = time.strftime("%Y-%m-%d %H:%M:%S", time.gmtime())
+        started_time = data.get("started_time", "")
+        if not started_time:
+            # no started_time found in data (e.g. first time page load when method still "running")
+            elapsed_time = str(timedelta(0))
+        else:
+            elapsed_time = str(
+                datetime.strptime(current_time, "%Y-%m-%d %H:%M:%S")
+                - datetime.strptime(started_time, "%Y-%m-%d %H:%M:%S"),
+            )
+        data["elapsed_time"] = elapsed_time
+
+        return (
+            method_status,
+            color,
+            supervisor_active,
+            data,
+        )