mud_server.admin_gradio.ui.state
================================

.. py:module:: mud_server.admin_gradio.ui.state

.. autoapi-nested-parse::

   UI state builders for Gradio interface.

   This module provides functions that build Gradio UI state updates based on
   application state. It encapsulates the complex tuple structures returned by
   various UI operations.

   By separating UI state management from API logic, we:
   - Make API functions testable without Gradio dependencies
   - Centralize UI update patterns for consistency
   - Make it easier to modify the UI layout without changing API code

   State Building Pattern:
       UI state builders return tuples in a fixed order matching the Gradio
       component structure. Each builder documents its return tuple structure.



Functions
---------

.. autoapisummary::

   mud_server.admin_gradio.ui.state.build_logged_in_state
   mud_server.admin_gradio.ui.state.build_logged_out_state
   mud_server.admin_gradio.ui.state.build_login_failed_state
   mud_server.admin_gradio.ui.state.is_admin_role
   mud_server.admin_gradio.ui.state.update_session_state
   mud_server.admin_gradio.ui.state.clear_session_state


Module Contents
---------------

.. py:function:: build_logged_in_state(session_state, message, has_admin_access = False)

   Build UI state for successful login.

   When a user logs in successfully, we:
   - Clear password fields for security
   - Show game-related tabs
   - Show admin tabs if user has admin/superuser role
   - Keep login tab visible to show success message

   :param session_state: Updated session state dictionary
   :param message: Success message to display
   :param has_admin_access: Whether user has admin or superuser role

   :returns:

             Tuple of (session_state, message, clear_username, clear_password,
                       login_tab, register_tab, game_tab, settings_tab, db_tab,
                       ollama_tab, help_tab)


.. py:function:: build_logged_out_state(session_state, message)

   Build UI state for logged out user.

   When a user is logged out (or logout fails), we:
   - Clear sensitive fields
   - Hide all game and admin tabs
   - Show only login and register tabs

   :param session_state: Updated session state dictionary
   :param message: Message to display (success or error)

   :returns:

             Tuple of (session_state, message, blank, login_tab, register_tab,
                       game_tab, settings_tab, db_tab, ollama_tab, help_tab)


.. py:function:: build_login_failed_state(session_state, error_message)

   Build UI state for failed login attempt.

   When login fails, we:
   - Clear password field for security (but preserve username)
   - Keep login/register tabs visible
   - Keep all other tabs hidden
   - Display error message

   :param session_state: Current session state (unchanged)
   :param error_message: Error message to display

   :returns:

             Tuple of (session_state, error_message, preserve_username, clear_password,
                       login_tab, register_tab, game_tab, settings_tab, db_tab,
                       ollama_tab, help_tab)


.. py:function:: is_admin_role(role)

   Check if a role has admin access.

   :param role: User role string

   :returns: True if role is admin or superuser, False otherwise

   .. admonition:: Examples

      >>> is_admin_role("admin")
      True
      >>> is_admin_role("superuser")
      True
      >>> is_admin_role("player")
      False
      >>> is_admin_role("worldbuilder")
      False


.. py:function:: update_session_state(session_state, session_id, username, role, logged_in = True)

   Update session state with login information.

   This is a pure function that creates a new session state dictionary
   with updated values.

   :param session_state: Current session state dictionary
   :param session_id: New session ID from backend
   :param username: Username that logged in
   :param role: User's role (player/worldbuilder/admin/superuser)
   :param logged_in: Login status (default: True)

   :returns: Updated session state dictionary

   .. admonition:: Examples

      >>> state = {}
      >>> new_state = update_session_state(state, "abc123", "alice", "player")
      >>> new_state["session_id"]
      'abc123'
      >>> new_state["username"]
      'alice'
      >>> new_state["logged_in"]
      True


.. py:function:: clear_session_state(session_state)

   Clear session state on logout.

   This is a pure function that resets all session fields to None/False.

   :param session_state: Current session state dictionary

   :returns: Cleared session state dictionary

   .. admonition:: Examples

      >>> state = {"session_id": "abc", "username": "alice", "role": "player", "logged_in": True}
      >>> cleared = clear_session_state(state)
      >>> cleared["logged_in"]
      False
      >>> cleared["session_id"] is None
      True