"""
This type stub file was generated by pyright.
"""

from functools import cached_property
from typing import Self, TYPE_CHECKING
from graph_sitter.core.autocommit import reader, writer
from graph_sitter.core.interfaces.has_block import HasBlock
from graph_sitter.typescript.detached_symbols.decorator import TSDecorator
from graph_sitter.typescript.symbol_groups.comment_group import TSCommentGroup
from graph_sitter.writer_decorators import ts_apidoc
from graph_sitter.typescript.detached_symbols.jsx.element import JSXElement

if TYPE_CHECKING:
    ...
@ts_apidoc
class TSHasBlock(HasBlock["TSCodeBlock", TSDecorator]):
    """A TypeScript base class that provides block-level code organization and decorator handling capabilities.

    This class extends the concept of block scoping for TypeScript code elements like classes and functions.
    It provides functionality for managing code blocks, decorators, JSX elements, and documentation within
    those blocks. The class supports operations such as retrieving and manipulating docstrings,
    handling JSX components, and managing TypeScript decorators.
    """
    @property
    @reader
    def is_decorated(self) -> bool:
        """Checks if the current symbol has a decorator.

        Determines if the symbol has a preceding decorator node.

        Returns:
            bool: True if the symbol has a decorator node as its previous named sibling,
                False otherwise.
        """
        ...
    
    @property
    @reader
    def decorators(self) -> list[TSDecorator]:
        """Returns a list of decorators associated with this symbol.

        Retrieves all decorators applied to this symbol by looking at both previous named siblings and decorator fields.
        This includes both inline decorators and standalone decorator statements.

        Returns:
            list[TSDecorator]: A list of TSDecorator objects representing all decorators applied to this symbol.
            Returns an empty list if no decorators are found.
        """
        ...
    
    @property
    @reader
    def jsx_elements(self) -> list[JSXElement[Self]]:
        """Returns a list of all JSX elements contained within this symbol.

        Searches through the extended nodes of the symbol for any JSX elements or self-closing JSX elements
        and returns them as a list of JSXElement objects.

        Args:
            None

        Returns:
            list[JSXElement[Self]]: A list of JSXElement objects contained within this symbol.
        """
        ...
    
    @reader
    def get_component(self, component_name: str) -> JSXElement[Self] | None:
        """Returns a specific JSX element from within this symbol's JSX elements.

        Searches through all JSX elements in this symbol's code block and returns the first one that matches
        the given component name.

        Args:
            component_name (str): The name of the JSX component to find.

        Returns:
            JSXElement[Self] | None: The matching JSX element if found, None otherwise.
        """
        ...
    
    @cached_property
    @reader
    def docstring(self) -> TSCommentGroup | None:
        """Retrieves the docstring of a function or class.

        Returns any comments immediately preceding this node as a docstring. For nodes that are children of a HasBlock, it returns consecutive comments that end on the line before the node starts.
        For other nodes, it returns formatted docstring comments.

        Returns:
            TSCommentGroup | None: A CommentGroup representing the docstring if one exists, None otherwise.
        """
        ...
    
    @writer
    def set_docstring(self, docstring: str, auto_format: bool = ..., clean_format: bool = ..., leading_star: bool = ..., force_multiline: bool = ...) -> None:
        """Sets or updates a docstring for a code element.

        Adds a new docstring if none exists, or updates the existing docstring. Handles formatting and placement
        of the docstring according to the specified parameters.

        Args:
            docstring (str): The docstring text to be added or updated.
            auto_format (bool, optional): Whether to automatically format the text into a docstring format. Defaults to True.
            clean_format (bool, optional): Whether to clean existing formatting from the docstring before inserting. Defaults to True.
            leading_star (bool, optional): Whether to add leading "*" to each line of the comment block. Defaults to True.
            force_multiline (bool, optional): Whether to force single line comments to be multi-line. Defaults to False.

        Returns:
            None
        """
        ...
    


