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

ansys/solutions/dash_super_components/folder_selector.py

@@ -0,0 +1,830 @@
+# 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 browsing and selecting a folder."""
+
+from enum import Enum
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+from ansys.solutions.dash_super_components.utils.svg_icons import IconNames, create_base64_svg_src
+
+try:
+    import tkinter
+    from tkinter import filedialog
+
+    TKINTER_AVAILABLE = True
+except Exception:  # ImportError or other import-related exception
+    tkinter = None  # type: ignore[assignment]
+    filedialog = None  # type: ignore[assignment]
+    TKINTER_AVAILABLE = False
+
+from typing import cast
+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]
+from dash.exceptions import PreventUpdate
+
+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]
+    )
+try:
+    from dash_extensions.enrich import set_props
+except ImportError:
+    from dash import set_props
+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.tree import Tree
+from ansys.solutions.dash_super_components.utils import config
+from ansys.solutions.dash_super_components.utils.aio_ids import AIOIds
+from ansys.solutions.dash_super_components.utils.path_validator import PathValidator
+
+
+class FolderSelectorMode(str, Enum):
+    """Enumeration representing the desired technology for generating the folder selector."""
+
+    TKINTER = "tkinter"
+    BOOTSTRAP = "bootstrap"
+
+
+class FolderSelectorStatus:
+    """Represent runtime information about the folder selector."""
+
+    def __init__(
+        self,
+        mode: FolderSelectorMode,
+        browse_from: str,
+        open_folder_selector: bool = False,
+    ):
+        self.mode = mode
+        self.open_folder_selector = open_folder_selector
+        self.browse_from = browse_from
+
+
+def custom_serializer(obj: object) -> Any:
+    """Serialize an object to be dumped."""
+    if isinstance(obj, Enum):
+        return obj.value
+    if isinstance(obj, Path):
+        return str(obj)
+    if isinstance(obj, (FolderSelectorStatus, FolderSelectorMode)):
+        return obj.__dict__
+    raise TypeError(f"Object of type {type(obj).__name__} is not JSON serializable")
+
+
+class FolderSelector(html.Div):
+    """
+    A Dash component for browsing and selecting a directory.
+
+    FolderSelector is based on the Dash All-in-One (AIO) component pattern. It
+    supports two operating modes:
+
+    - **Tkinter** (``FolderSelectorMode.TKINTER``): native OS dialog; requires the
+      ``tkinter`` package.
+    - **Bootstrap** (``FolderSelectorMode.BOOTSTRAP``): browser-based modal with a
+      tree view of the file system; works in headless or remote environments.
+
+    When ``mode`` is not specified, the mode is selected automatically: bootstrap is
+    used when ``tkinter`` is unavailable or when the environment variable
+    ``FOLDER_SELECTOR_REMOTE_DEPLOYMENT`` is set to ``true``, ``1``, or ``yes``;
+    otherwise tkinter is used.
+
+    .. note::
+
+        The component must be placed inside a ``MantineProvider``. For error
+        notifications to work correctly, a ``dmc.NotificationContainer`` must also be
+        present in the application layout.  By default the container ID is
+        ``"notification-container"``; use
+        :func:`~ansys.solutions.dash_super_components.configure` to change it.
+
+    Parameters
+    ----------
+    mode : FolderSelectorMode, optional
+        Operating mode. Use ``FolderSelectorMode.TKINTER`` for a native OS dialog or
+        ``FolderSelectorMode.BOOTSTRAP`` for a browser-based modal. When omitted,
+        the mode is selected automatically (see above).
+    aio_id : str, optional
+        Unique identifier for this component instance. A UUID is generated when not
+        provided.
+    browse_button_props : dict, optional
+        Properties forwarded to the browse :class:`dmc.Button`.
+    clear_button_props : dict, optional
+        Properties forwarded to the clear :class:`dmc.ActionIcon`.
+    style : dict, optional
+        CSS style properties applied to the component container.
+    options : dict, optional
+        Additional configuration options:
+
+        - ``default_path`` (str, optional): Path used as the default selected folder
+          when nothing has been selected or the selection is cleared.
+        - ``browse_from`` (str, optional): Root path for the file tree in Bootstrap
+          mode. Falls back to the ``FOLDER_SELECTOR_BROWSE_FROM`` environment
+          variable, then the current working directory.
+        - ``topmost`` (bool, optional): If ``True``, the tkinter dialog appears in
+          the foreground. Default is ``True``.
+        - ``max_path_length`` (int, optional): Maximum allowed path length.
+          Defaults to the system limit.
+        - ``display_field`` (dict, optional): Dict with an ``enabled`` key (``bool``)
+          controlling whether the selected path is shown below the buttons.
+          Default is ``{"enabled": True}``.
+    value : str, optional
+        Preselected folder path. Populates the selected folder store upon component
+        instantiation.
+    """
+
+    class FolderSelectorIds(AIOIds):
+        """Provides IDs for the subcomponents of :class:`FolderSelector`."""
+
+        @classmethod
+        def _settings(cls, aio_id: str | _Wildcard) -> dict[str, Any]:
+            """Return the ID for the settings store.
+
+            Parameters
+            ----------
+            aio_id : str or _Wildcard
+                The component's unique identifier.
+
+            Returns
+            -------
+            dict[str, Any]
+                The unique ID dictionary for the settings store subcomponent.
+            """
+            return cls.make_id_dict("folder-selector", "settings", aio_id)
+
+        @classmethod
+        def _folder_selector_status(cls, aio_id: str | _Wildcard) -> dict[str, Any]:
+            """Return the ID for the folder selector status store.
+
+            Parameters
+            ----------
+            aio_id : str or _Wildcard
+                The component's unique identifier.
+
+            Returns
+            -------
+            dict[str, Any]
+                The unique ID dictionary for the folder selector status store subcomponent.
+            """
+            return cls.make_id_dict("folder-selector", "folder-selector-status", aio_id)
+
+        @classmethod
+        def _folder_selector_modal(cls, aio_id: str | _Wildcard) -> dict[str, Any]:
+            """Return the ID for the folder selector modal.
+
+            Parameters
+            ----------
+            aio_id : str or _Wildcard
+                The component's unique identifier.
+
+            Returns
+            -------
+            dict[str, Any]
+                The unique ID dictionary for the folder selector modal subcomponent.
+            """
+            return cls.make_id_dict("folder-selector", "folder-selector-modal", aio_id)
+
+        @classmethod
+        def _folder_selector_modal_done_button(cls, aio_id: str | _Wildcard) -> dict[str, Any]:
+            """Return the ID for the modal done button.
+
+            Parameters
+            ----------
+            aio_id : str or _Wildcard
+                The component's unique identifier.
+
+            Returns
+            -------
+            dict[str, Any]
+                The unique ID dictionary for the modal done button subcomponent.
+            """
+            return cls.make_id_dict("folder-selector", "folder-selector-modal-done-button", aio_id)
+
+        @classmethod
+        def browse_button(cls, aio_id: str | _Wildcard) -> dict[str, Any]:
+            """Return the ID for the browse button.
+
+            Parameters
+            ----------
+            aio_id : str or _Wildcard
+                The component's unique identifier.
+
+            Returns
+            -------
+            dict[str, Any]
+                The unique ID dictionary for the browse button subcomponent.
+            """
+            return cls.make_id_dict("folder-selector", "browse-button", aio_id)
+
+        @classmethod
+        def clear_button(cls, aio_id: str | _Wildcard) -> dict[str, Any]:
+            """Return the ID for the clear button.
+
+            Parameters
+            ----------
+            aio_id : str or _Wildcard
+                The component's unique identifier.
+
+            Returns
+            -------
+            dict[str, Any]
+                The unique ID dictionary for the clear button subcomponent.
+            """
+            return cls.make_id_dict("folder-selector", "clear-button", aio_id)
+
+        @classmethod
+        def display_field(cls, aio_id: str | _Wildcard) -> dict[str, Any]:
+            """Return the ID for the display field component.
+
+            Parameters
+            ----------
+            aio_id : str or _Wildcard
+                The component's unique identifier.
+
+            Returns
+            -------
+            dict[str, Any]
+                The unique ID dictionary for the display field subcomponent.
+            """
+            return cls.make_id_dict("folder-selector", "display-field", aio_id)
+
+        @classmethod
+        def selected_folder(cls, aio_id: str | _Wildcard) -> dict[str, Any]:
+            """Return the ID for the selected folder store.
+
+            Parameters
+            ----------
+            aio_id : str or _Wildcard
+                The component's unique identifier.
+
+            Returns
+            -------
+            dict[str, Any]
+                The unique ID dictionary for the selected folder store subcomponent.
+            """
+            return cls.make_id_dict("folder-selector", "selected-folder", aio_id)
+
+    ids = FolderSelectorIds
+
+    def __init__(
+        self,
+        mode: FolderSelectorMode | None = None,
+        aio_id: str | None = None,
+        browse_button_props: dict[str, Any] | None = None,
+        clear_button_props: dict[str, Any] | None = None,
+        style: dict[str, Any] | None = None,
+        options: dict[str, Any] | None = None,
+        value: str | None = None,
+    ):
+        # set basic defaults
+        if aio_id is None:
+            aio_id = str(uuid.uuid4())
+        if browse_button_props is None:
+            browse_button_props = {}
+        if clear_button_props is None:
+            clear_button_props = {}
+        if style is None:
+            style = {}
+        if options is None:
+            options = {}
+
+        # check inputs
+        if mode and not isinstance(mode, FolderSelectorMode):  # type: ignore - user input check
+            raise TypeError(f"mode must be an instance of FolderSelectorMode, got {type(mode)}")
+
+        # extract and populate settings
+        self.aio_id = aio_id
+        self._set_mode(mode)
+
+        display_field_enabled = options.get("display_field", {}).get("enabled", True)
+        internal_settings = {
+            "topmost": options.get("topmost", True),
+            "max_path_length": options.get("max_path_length", PathValidator.max_path_length()),
+            "default_path": options.get("default_path"),
+        }
+
+        folder_selector_status = FolderSelectorStatus(
+            mode=self.mode, browse_from=self._get_browse_from(options)
+        )
+
+        folders_structure = (
+            self.get_folders_structure(folder_selector_status.browse_from)
+            if self.mode == FolderSelectorMode.BOOTSTRAP
+            else None
+        )
+
+        browse_button_default_props = {
+            "children": "Browse",
+            "leftSection": html.Img(
+                src=create_base64_svg_src(IconNames.MDI_FOLDER_SEARCH, color="#4c6ef5"),
+            ),
+            "radius": "xl",
+            "className": "mantine-button",
+            "variant": "outline",
+            "style": {"width": "80%"},
+            "color": "indigo",
+        }
+        self._populate_with_defaults(browse_button_props, browse_button_default_props)
+
+        clear_button_default_props = {
+            "children": html.Img(
+                src=create_base64_svg_src(IconNames.MATERIAL_DELETE, color="#4c6ef5"),
+                width=20,
+            ),
+            "size": "md",
+            "radius": "sm",
+            "variant": "outline",
+            "color": "indigo",
+        }
+        self._populate_with_defaults(clear_button_props, clear_button_default_props)
+
+        super().__init__(
+            [
+                html.Div(
+                    [
+                        dmc.Group(
+                            [
+                                dmc.Button(
+                                    id=self.ids.browse_button(self.aio_id),
+                                    **browse_button_props,
+                                ),
+                                dmc.ActionIcon(
+                                    id=self.ids.clear_button(self.aio_id),
+                                    **clear_button_props,
+                                ),
+                            ],
+                        ),
+                        dmc.Text(
+                            id=self.ids.display_field(self.aio_id),
+                            style={
+                                "display": ("none" if not display_field_enabled else "inline"),
+                            },
+                        ),
+                        dcc.Store(
+                            id=self.ids.selected_folder(self.aio_id),
+                            storage_type="memory",
+                            data=value,
+                        ),
+                        dcc.Store(
+                            id=self.ids._settings(self.aio_id),
+                            storage_type="memory",
+                            data=json.dumps(internal_settings),
+                        ),
+                        dcc.Store(
+                            id=self.ids._folder_selector_status(self.aio_id),
+                            data=json.dumps(
+                                folder_selector_status,
+                                default=custom_serializer,
+                            ),
+                            storage_type="memory",
+                        ),
+                        dmc.Modal(
+                            title="Pick a folder from the server",
+                            id=self.ids._folder_selector_modal(self.aio_id),
+                            zIndex=10000,
+                            children=[
+                                self.generate_tree(self.aio_id, folders_structure),
+                                dmc.Group(
+                                    children=[
+                                        dmc.Button(
+                                            "Done",
+                                            id=self.ids._folder_selector_modal_done_button(
+                                                self.aio_id,
+                                            ),
+                                        ),
+                                    ],
+                                    justify="center",
+                                ),
+                            ],
+                            closeOnClickOutside=False,
+                            closeOnEscape=False,
+                            withCloseButton=False,
+                            size="xl",
+                        ),
+                    ],
+                    style=style,
+                ),
+            ],
+        )
+
+    def _get_browse_from(self, options: dict[str, Any]) -> str:
+        browse_from = (
+            os.environ.get(
+                "FOLDER_SELECTOR_BROWSE_FROM",
+                Path.cwd(),
+            )
+            if "browse_from" not in options
+            else options["browse_from"]
+        )  # this option restricts the FS visibility when mode == BOOTSTRAP
+        # normalize the path - strip trailing slashes and resolve .. and .
+        browse_from = os.path.normpath(browse_from)
+        return browse_from
+
+    def _set_mode(self, mode: FolderSelectorMode | None) -> None:
+        if not TKINTER_AVAILABLE:
+            self.mode = FolderSelectorMode.BOOTSTRAP
+        elif mode:
+            # user provided an enum
+            self.mode = mode
+        else:  # mode is not specified
+            folder_selector_remote_deployment = str(
+                os.environ.get("FOLDER_SELECTOR_REMOTE_DEPLOYMENT", "false"),
+            ).lower() in {"true", "1", "yes"}
+            self.mode = (
+                FolderSelectorMode.TKINTER
+                if not folder_selector_remote_deployment
+                else FolderSelectorMode.BOOTSTRAP
+            )
+
+    def _populate_with_defaults(
+        self, properties: dict[str, Any], default_properties: dict[str, Any]
+    ) -> None:
+        for key, val in default_properties.items():
+            if key not in properties:
+                properties[key] = val
+
+    @staticmethod
+    @callback(
+        Output(ids.selected_folder(MATCH), "data"),
+        Input(ids.selected_folder(MATCH), "data"),
+        State(ids._settings(MATCH), "data"),
+    )
+    def populate_selected_folder_with_default_path(
+        selected_folder: str | None,
+        internal_settings: str,
+    ) -> str | NoUpdate:
+        """Populate the selected_folder store with default_path upon component instantiation."""
+        settings: dict[str, str | int | None] = json.loads(internal_settings)
+        default_path = settings["default_path"]
+        if default_path and not selected_folder:
+            return cast(str, default_path)
+        else:
+            return no_update
+
+    @staticmethod
+    @callback(
+        Output(ids.browse_button(MATCH), "disabled", allow_duplicate=True),
+        Input(ids.browse_button(MATCH), "n_clicks"),
+        prevent_initial_call=True,
+    )
+    def disable_browse_button(n_clicks: int) -> bool | NoUpdate:
+        """Disable browse button."""
+        return True if n_clicks else no_update
+
+    @staticmethod
+    @callback(
+        Output(ids.browse_button(MATCH), "disabled", allow_duplicate=True),
+        Input(ids._folder_selector_status(MATCH), "data"),
+        prevent_initial_call=True,
+    )
+    def enable_browse_button(_data: str) -> bool | NoUpdate:
+        """Enable browse button."""
+        data: FolderSelectorStatus = json.loads(
+            _data,
+            object_hook=lambda o: FolderSelectorStatus(**o),
+        )
+        if not data.open_folder_selector:
+            return False
+        else:
+            return no_update
+
+    @staticmethod
+    @callback(
+        Output(ids._folder_selector_status(MATCH), "data", allow_duplicate=True),
+        Input(ids.browse_button(MATCH), "n_clicks"),
+        State(ids._folder_selector_status(MATCH), "data"),
+        prevent_initial_call=True,
+    )
+    def browse(
+        n_clicks: int,
+        _folder_selector_status: str,
+    ) -> str | NoUpdate:
+        """Browse and enable folder selection."""
+        if n_clicks:
+            folder_selector_status: FolderSelectorStatus = json.loads(
+                _folder_selector_status,
+                object_hook=lambda o: FolderSelectorStatus(**o),
+            )
+            folder_selector_status.open_folder_selector = True
+            return json.dumps(folder_selector_status, default=custom_serializer)
+        else:
+            return no_update
+
+    @staticmethod
+    @callback(
+        Output(ids._folder_selector_status(MATCH), "data", allow_duplicate=True),
+        Output(ids.selected_folder(MATCH), "data", allow_duplicate=True),
+        Output(ids._folder_selector_modal(MATCH), "opened", allow_duplicate=True),
+        Input(ids._folder_selector_status(MATCH), "data"),
+        State(ids._settings(MATCH), "data"),
+        State(ids.browse_button(MATCH), "n_clicks"),
+        prevent_initial_call=True,
+    )
+    def open_folder_selector(
+        _folder_selector_status: str,
+        internal_settings: str,
+        n_clicks: int,
+    ) -> tuple[str | NoUpdate, str | NoUpdate | None, bool | NoUpdate]:
+        """
+        Open a OS-provided or a browser-generated popup.
+
+        The choice is ruled by `FolderSelectorMode`.
+        The final goal is to select a folder from the server's file-system.
+        """
+        settings: dict[str, str | int | None] = json.loads(internal_settings)
+        topmost = cast(bool, settings["topmost"])
+        max_path_length = cast(int, settings["max_path_length"])
+        notification = no_update
+        selected_directory = None
+        folder_selector_status: FolderSelectorStatus = json.loads(
+            _folder_selector_status,
+            object_hook=lambda d: FolderSelectorStatus(**d),
+        )
+        if folder_selector_status.open_folder_selector:
+            if folder_selector_status.mode == FolderSelectorMode.TKINTER:
+                try:
+                    selected_directory = FolderSelector.ask_directory_with_tkinter(
+                        topmost,
+                    )
+                    validation = PathValidator(selected_directory).validate(
+                        max_path_length,
+                    )
+                    if isinstance(validation, Exception):
+                        selected_directory = None
+                        notification = {
+                            "title": "Error during folder selection",
+                            "id": "folder-selector-notify-failure" + "-" + str(n_clicks),
+                            "action": "show",
+                            "color": "red",
+                            "message": f"{str(validation)}.",
+                            "autoClose": False,
+                        }
+                        set_props(
+                            config._config.notification_container_id,
+                            {"sendNotifications": [notification]},
+                        )
+
+                    folder_selector_status.open_folder_selector = False
+                    return (
+                        json.dumps(folder_selector_status, default=custom_serializer),
+                        selected_directory,
+                        no_update,
+                    )
+                except tkinter.TclError:  # type: ignore reportOptionalMemberAccess - tkinter availability is checked before
+                    # Any error related to tkinter availability/operation will be handled here
+                    folder_selector_status.open_folder_selector = False
+
+                    message = "The server either does not support tkinter "
+                    message += "or the tkinter package is not installed "
+                    message += "or it is running in a headless mode. "
+                    message += "Please switch to BOOTSTRAP mode."
+                    notification = {
+                        "title": "Error during folder selection",
+                        "id": "folder-selector-notify-failure" + "-" + str(n_clicks),
+                        "action": "show",
+                        "color": "red",
+                        "message": message,
+                        "autoClose": False,
+                    }
+                    set_props(
+                        config._config.notification_container_id,
+                        {"sendNotifications": [notification]},
+                    )
+                    return (
+                        json.dumps(folder_selector_status, default=custom_serializer),
+                        None,
+                        False,
+                    )
+            else:
+                # open the modal
+                return no_update, no_update, True
+        else:
+            raise PreventUpdate
+
+    @staticmethod
+    @callback(
+        Output(ids._folder_selector_status(MATCH), "data", allow_duplicate=True),
+        Output(ids._folder_selector_modal(MATCH), "opened", allow_duplicate=True),
+        Output(ids.selected_folder(MATCH), "data", allow_duplicate=True),
+        Input(ids._folder_selector_modal_done_button(MATCH), "n_clicks"),
+        State(Tree.ids.selected_item(MATCH), "data"),
+        State(Tree.ids.tree_structure(MATCH), "data"),
+        State(ids._folder_selector_status(MATCH), "data"),
+        prevent_initial_call=True,
+    )
+    def dismiss_modal_and_update_selected_folder(
+        n_clicks: int | None,
+        selected_item_id: dict[str, str] | None,
+        tree_structure: str,
+        _folder_selector_status: str,
+    ) -> tuple[str, bool, str | None | NoUpdate]:
+        """Close the modal and update data storage."""
+        if n_clicks:
+            folder_selector_status: FolderSelectorStatus = json.loads(
+                _folder_selector_status,
+                object_hook=lambda o: FolderSelectorStatus(**o),
+            )
+            folder_selector_status.open_folder_selector = False
+
+            parsed_tree = json.loads(tree_structure)
+            if isinstance(parsed_tree, list):
+                if len(parsed_tree) == 0:  # The tree is empty, no folder can be selected
+                    return (
+                        json.dumps(folder_selector_status, default=custom_serializer),
+                        False,
+                        no_update,
+                    )
+                parsed_tree = parsed_tree[
+                    0
+                ]  # The graph is a tree, so there is only one element in the first level
+
+            selected_folder = no_update
+            notification = no_update
+            if selected_item_id:
+                # translate the navlink id to its corresponding path
+                try:
+                    folder_id = Tree.ids.get_index_from_navlink_item_id(selected_item_id)
+                    selected_folder = FolderSelector.resolve_folder(
+                        folder_id,
+                        parsed_tree,
+                    )
+                except ValueError:
+                    # In case the selected nav item id is not found in the tree structure
+                    # we consider it as an invalid selection:
+                    message = (
+                        "The selected folder path could not be resolved. Please try again or "
+                        "select another folder."
+                    )
+                    notification = {
+                        "title": "Error during folder selection",
+                        "id": "folder-selector-notify-failure" + "-" + str(n_clicks),
+                        "action": "show",
+                        "color": "red",
+                        "message": message,
+                        "autoClose": True,
+                    }
+                    set_props(
+                        config._config.notification_container_id,
+                        {"sendNotifications": [notification]},
+                    )
+
+            return (
+                json.dumps(folder_selector_status, default=custom_serializer),
+                False,
+                selected_folder,
+            )
+        else:
+            raise PreventUpdate
+
+    @staticmethod
+    @callback(
+        Output(ids.display_field(MATCH), "children"),
+        Input(ids.selected_folder(MATCH), "data"),
+    )
+    def update_display_field(
+        selected_folder: str | None,
+    ) -> str | None:
+        """Update the display field when a new folder is selected."""
+        return f"Selected folder: {selected_folder}" if selected_folder else "No folder selected"
+
+    @staticmethod
+    @callback(
+        Output(ids.selected_folder(MATCH), "clear_data", allow_duplicate=True),
+        Input(ids.clear_button(MATCH), "n_clicks"),
+        prevent_initial_call=True,
+    )
+    def clear_selected_folder(n_clicks: int) -> bool:
+        """Clear previously selected folder."""
+        if n_clicks > 0:
+            return True
+        raise PreventUpdate
+
+    @classmethod
+    def generate_tree(cls, aio_id: str, folders_structure: dict[str, Any] | None) -> Tree:
+        """Create a tree to browse and select a folder from the server file system."""
+        return Tree(
+            aio_id=aio_id,
+            items=[folders_structure] if isinstance(folders_structure, dict) else [],
+            default_icon="material-symbols:folder",
+        )
+
+    @classmethod
+    def get_folders_structure(
+        cls,
+        browse_from: str,
+        _as_absolute_path: bool = True,
+    ) -> dict[str, Any]:
+        """
+        Recursively generate the file-system tree starting from `browse_from`.
+
+        Parameters
+        ----------
+        browse_from : str
+            The path from which to start browsing.
+        _as_absolute_path : bool, optional
+            Internal parameter used for recursion. Do not use externally.
+
+        Returns
+        -------
+        dict[str, Any]
+            A dictionary representing the folder structure.
+        """
+        children = sorted(
+            [
+                os.path.normpath(Path(browse_from) / folder.name)
+                for folder in Path(browse_from).glob("*")
+                if folder.is_dir() and not folder.name.startswith(".")
+            ],
+        )
+        return {
+            "id": str(
+                uuid.uuid3(uuid.NAMESPACE_URL, browse_from),
+            ),  # idempotent hash value
+            "text": (browse_from if _as_absolute_path else Path(browse_from).name),  # folder name
+            "children": ([cls.get_folders_structure(child, False) for child in children]),
+        }
+
+    @classmethod
+    def resolve_folder(
+        cls,
+        folder_id: str,
+        tree_structure: dict[str, Any],
+        _prefix: str = "",
+    ) -> str | None:
+        """
+        Traverse the tree to find a path corresponding to the `folder_id`.
+
+        Parameters
+        ----------
+        folder_id : str
+            The unique identifier of the folder to find in the tree.
+        tree_structure : dict[str, Any]
+            The tree structure dictionary to search through.
+        _prefix : str, optional
+            Internal parameter used for recursion. Do not use externally.
+
+        Returns
+        -------
+        str or None
+            The full path to the folder if found, ``None`` otherwise.
+        """
+        if len(_prefix) > 0 and not _prefix.endswith(os.path.sep):
+            _prefix += os.path.sep
+        if tree_structure["id"] == folder_id:
+            return _prefix + tree_structure["text"]
+        for child in tree_structure.get("children", []):
+            found = cls.resolve_folder(folder_id, child, _prefix + tree_structure["text"])
+            if found:
+                return found
+        return None
+
+    @classmethod
+    def ask_directory_with_tkinter(cls, topmost: bool) -> str:
+        """Open a tkinter popup and return user choice on dismiss."""
+        if not TKINTER_AVAILABLE:
+            raise RuntimeError("tkinter is not available in this environment")
+
+        root = tkinter.Tk()  # type: ignore reportOptionalMemberAccess - tkinter availability is checked before
+        try:
+            root.withdraw()
+            if topmost:
+                root.wm_attributes("-topmost", 1)
+            selected_directory = filedialog.askdirectory()  # type: ignore reportOptionalMemberAccess - tkinter availability is checked before
+            return selected_directory
+        finally:
+            root.destroy()