Module QFlow.hooks

class Navigator:
    def __init__(self, instance: Window | Screen):
        """
        Navigates to a specified screen path, extracting embedded URL query 
        parameters and merging them with additional parameters.
        """
        self.cursor = None

        if isinstance(instance, (App, Window)):
            self.cursor = instance
        else:
            parent: Window = instance.parent()
            self.cursor = parent

        if not self.cursor:
            raise TypeError(f"'{instance}' is not Window or Screen.")

    def navigate(self, screen: str | int, params: dict = {}) -> None:
        """
        This function automatically resolves the correct navigation controller 
        (`setScreen`) depending on whether `self` is a `Window` or a `Screen`. It 
        then parses the `screen` string to separate the base path from any 
        embedded query parameters, merges them into `params`, and triggers the 
        navigation using the cleaned path.

        Args:
            self (Window | Screen): The current UI context (either a Window or 
                a Screen) initiating the navigation.
            screen (str): The target screen route, which can include URL-style 
                query parameters (e.g., "settings/profile?user_id=123&theme=dark").
            params (dict, optional): Additional parameters to pass to the target 
                screen. Defaults to {}. Query parameters extracted from the 
                `screen` string will overwrite or merge into this dictionary.
        """

        if type(screen) == int:
            index = 0
            while (index < -screen):
                self.cursor.goBack()
                index += 1
            return

        parse = urlparse(screen)

        params.update(
            parse_qsl(
                parse.query
            )
        )

        self.cursor.setScreen(parse.path, params)

class Params:
    """
    Manages parameters associated with a specific instance.
    
    This class provides an interface to get, set, and verify the existence
    of parameters stored for a given instance.
    
    Attributes:
        identity (Any): The instance for which parameters are managed.
    """
    
    def __init__(self, instance: Any):
        """
        Initializes the parameter manager for a specific instance.
        
        Args:
            instance (Any): The instance whose parameters will be managed.
        """
        self.identity = instance

    def get(self, name: str = None) -> dict | Any:
        """
        Gets one or all parameters from the instance.
        
        Args:
            name (str, optional): The name of the parameter to get. 
                If None, returns all parameters. Defaults to None.
        
        Returns:
            dict | Any: If name is None, returns a dictionary with all 
                parameters. If name is specified, returns the parameter value 
                or None if it doesn't exist.
        """
        if name is not None:
            return INSTANCEARGS.getArg(instance=self.identity, name=name)
        else:
            return INSTANCEARGS.getArgs(instance=self.identity)
    
    def set(self, name: str = None, value: Any = None, args: dict = None) -> None:
        """
        Sets one or multiple parameters for the instance.
        
        Args:
            name (str, optional): The name of the parameter to set. 
                Ignored if args is specified.
            value (Any, optional): The value of the parameter to set.
                Ignored if args is specified.
            args (dict, optional): Dictionary with multiple parameters to set.
                If provided, takes priority over name and value.
        
        Returns:
            None
        """
        if args:
            INSTANCEARGS.setArgs(instance=self.identity, args=args)
        else: 
            INSTANCEARGS.setArg(instance=self.identity, name=name, value=value)
    
    def exist(self, name: str) -> bool:
        """
        Checks if a parameter exists for the instance.
        
        Args:
            name (str): The name of the parameter to check.
        
        Returns:
            bool: True if the parameter exists, False otherwise.
        """
        return INSTANCEARGS.existArg(instance=self.identity, name=name)
    
    def clear(self) -> None:
        """Clear all parameters"""
        INSTANCEARGS.clearArgs(instance=self.identity)