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

ansys/solutions/dash_super_components/transaction_method_status_badge.py

@@ -0,0 +1,366 @@
+# 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.
+
+
+"""``dmc.Button`` that displays and updates SAF transaction method status."""
+
+import copy
+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.status_badge_properties import (
+    STATUS_BADGE_PROPERTIES,
+)
+from ansys.solutions.dash_super_components.utils.svg_icons import (
+    IconNames,
+    create_base64_svg_src,
+)
+
+
+class TransactionMethodStatusBadge(html.Div):
+    """
+    A Dash component that displays and updates the status of a SAF transaction method.
+
+    TransactionMethodStatusBadge is based on the Dash All-in-One (AIO) component pattern.
+    It renders a compact button badge that periodically polls the GLOW API and reflects the
+    current status of the specified method with
+    color-coded states.
+
+    .. 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::
+
+        TransactionMethodStatusBadge.ids.activate_monitoring(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 to monitor.
+    stop_monitoring_on_termination : bool, optional
+        If ``True``, monitoring stops automatically when the method reaches a terminal
+        state (completed, failed, aborted). Default is ``True``.
+    button_properties : dict, optional
+        Additional properties forwarded to the status badge :class:`dmc.Button`.
+    label_properties : dict, optional
+        Additional properties forwarded to the label :class:`dmc.Text` component.
+    interval_properties : dict, optional
+        Additional properties forwarded to the :class:`dcc.Interval` polling component.
+    aio_id : str, optional
+        Unique identifier for this component instance. A UUID is generated if not provided.
+    """
+
+    class TransactionMethodStatusBadgeIds(AIOIds):
+        """Provides IDs for the subcomponents of :class:`TransactionMethodStatusBadge`."""
+
+        @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-method-status-badge", "interval", aio_id)
+
+        @classmethod
+        def _data_storage(cls, aio_id: str | _Wildcard) -> dict[str, Any]:
+            """Return the ID for the data storage component.
+
+            Parameters
+            ----------
+            aio_id : str or _Wildcard
+                The component's unique identifier.
+
+            Returns
+            -------
+            dict[str, Any]
+                The unique ID dictionary for the data storage subcomponent.
+            """
+            return cls.make_id_dict("transaction-method-status-badge", "data-storage", aio_id)
+
+        @classmethod
+        def label(cls, aio_id: str | _Wildcard) -> dict[str, Any]:
+            """Return the ID for the label component.
+
+            Parameters
+            ----------
+            aio_id : str or _Wildcard
+                The component's unique identifier.
+
+            Returns
+            -------
+            dict[str, Any]
+                The unique ID dictionary for the label subcomponent.
+            """
+            return cls.make_id_dict("transaction-method-status-badge", "label", aio_id)
+
+        @classmethod
+        def status_badge(cls, aio_id: str | _Wildcard) -> dict[str, Any]:
+            """Return the ID for the button component.
+
+            Parameters
+            ----------
+            aio_id : str or _Wildcard
+                The component's unique identifier.
+
+            Returns
+            -------
+            dict[str, Any]
+                The unique ID dictionary for the button subcomponent.
+            """
+            return cls.make_id_dict("transaction-method-status-badge", "button", aio_id)
+
+        @classmethod
+        def activate_monitoring(cls, aio_id: str | _Wildcard) -> dict[str, Any]:
+            """Return the ID for the activate monitoring component.
+
+            Parameters
+            ----------
+            aio_id : str or _Wildcard
+                The component's unique identifier.
+
+            Returns
+            -------
+            dict[str, Any]
+                The unique ID dictionary for the activate monitoring subcomponent.
+            """
+            return cls.make_id_dict(
+                "transaction-method-status-badge", "activate-monitoring", aio_id
+            )
+
+    ids = TransactionMethodStatusBadgeIds
+
+    def __init__(
+        self,
+        url: str,
+        step_name: str,
+        method_name: str,
+        stop_monitoring_on_termination: bool = True,
+        button_properties: dict[str, Any] | None = None,
+        label_properties: dict[str, Any] | None = None,
+        interval_properties: dict[str, Any] | None = None,
+        aio_id: str | None = None,
+    ):
+        button_properties = {} if button_properties is None else copy.deepcopy(button_properties)
+        label_properties = {} if label_properties is None else copy.deepcopy(label_properties)
+        interval_properties = (
+            {} if interval_properties is None else copy.deepcopy(interval_properties)
+        )
+
+        if aio_id is None:
+            aio_id = str(uuid.uuid4())
+
+        self.aio_id = aio_id
+
+        default_label_properties = {
+            "style": {
+                "fontSize": "15px",
+                "textAlign": "left",
+                "display": "block" if label_properties else "none",
+            },
+        }
+
+        default_button_properties = {
+            "loading": False,
+            "size": "compact-xs",
+            "radius": "xl",
+        }
+
+        default_interval_properties = {
+            "interval": 5000,
+        }
+
+        data = {
+            "url": url,
+            "step_name": step_name,
+            "method_name": method_name,
+            "stop_monitoring_on_termination": stop_monitoring_on_termination,
+        }
+
+        # Merge label properties, handling the style dict specially
+        for key, value in default_label_properties.items():
+            if key not in label_properties:
+                label_properties[key] = value
+            elif key == "style" and isinstance(label_properties[key], dict):
+                # Merge style dicts: defaults first, then user overrides
+                merged_style = copy.deepcopy(value)
+                merged_style.update(label_properties[key])
+                label_properties[key] = merged_style
+
+        # properties in default_button_properties can be overwritten:
+        for key, value in default_button_properties.items():
+            if key not in button_properties:
+                button_properties[key] = value
+
+        # button properties "children", "color", "variant" and "leftSection" are fully controlled by
+        # the component - will be overwritten by correct values in the callbacks:
+        button_properties["children"] = ""
+        button_properties["color"] = "gray"
+        button_properties["variant"] = "outline"
+        button_properties["leftSection"] = None
+
+        # properties in default_interval_properties can be overwritten:
+        for key, value in default_interval_properties.items():
+            if key not in interval_properties:
+                interval_properties[key] = value
+
+        # interval property "disabled" is fully controlled by the component:
+        interval_properties["disabled"] = True
+
+        super().__init__(
+            [
+                html.Div(
+                    [
+                        html.Div(id=self.ids.label(aio_id), **label_properties),
+                        dmc.Button(id=self.ids.status_badge(aio_id), **button_properties),
+                    ],
+                    style={
+                        "display": "flex",
+                        "flexDirection": "column",
+                        "alignItems": "left",
+                    },
+                ),
+                dcc.Interval(id=self.ids._interval(aio_id), **interval_properties),
+                dcc.Store(
+                    id=self.ids._data_storage(aio_id),
+                    storage_type="session",
+                    data=data,
+                ),
+                dcc.Store(
+                    id=self.ids.activate_monitoring(aio_id),
+                    storage_type="session",
+                    data=False,
+                ),
+            ],
+        )
+
+    @staticmethod
+    @callback(
+        Output(ids._interval(MATCH), "disabled", allow_duplicate=True),
+        Input(ids.activate_monitoring(MATCH), "data"),
+        prevent_initial_call=True,
+    )
+    def activate_deactivate_monitoring(
+        activate_monitoring: bool,
+    ) -> bool:
+        """Activate the monitoring."""
+        return not activate_monitoring
+
+    @staticmethod
+    @callback(
+        Output(ids.status_badge(MATCH), "children"),
+        Output(ids.status_badge(MATCH), "color"),
+        Output(ids.status_badge(MATCH), "variant"),
+        Output(ids.status_badge(MATCH), "leftSection"),
+        Output(ids.activate_monitoring(MATCH), "data", allow_duplicate=True),
+        Input(ids._interval(MATCH), "n_intervals"),
+        Input(ids._interval(MATCH), "disabled"),
+        State(ids._data_storage(MATCH), "data"),
+        State(ids.activate_monitoring(MATCH), "data"),
+    )
+    def update_badge(
+        n_intervals: int,
+        interval_disabled: bool,
+        data_storage: dict[str, Any],
+        monitoring_active: bool,
+    ) -> tuple[str, str, str, html.Img | None, bool | NoUpdate]:
+        """Update button status."""
+        glow_api_request = GlowAPIRequest(data_storage["url"])
+        method_status = glow_api_request.get_transaction_method_status(
+            data_storage["step_name"],
+            data_storage["method_name"],
+        )
+
+        button_children = method_status.upper()
+        color = STATUS_BADGE_PROPERTIES[method_status.lower()]["color"]
+
+        if not monitoring_active:
+            variant = "outline"
+            left_section = None
+            activate_monitoring = no_update
+            return (
+                button_children,
+                color,
+                variant,
+                left_section,
+                activate_monitoring,
+            )
+
+        stop_monitoring_on_termination = data_storage["stop_monitoring_on_termination"]
+        variant = "filled"
+        left_section = html.Img(src=create_base64_svg_src(IconNames.EOS_LOADING))
+
+        if (
+            method_status.lower() in ["completed", "failed"] and stop_monitoring_on_termination
+        ):  # stop monitoring
+            variant = "outline"
+            left_section = None
+            activate_monitoring = False
+        else:
+            # method needs to be monitored (is running/will be running shortly, or monitoring
+            # shouldn't be stopped)
+            activate_monitoring = no_update
+
+        return (
+            button_children,
+            color,
+            variant,
+            left_section,
+            activate_monitoring,
+        )