discordcn 0.0.1a3__tar.gz → 0.0.1a4__tar.gz

{discordcn-0.0.1a3 → discordcn-0.0.1a4}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: discordcn
-Version: 0.0.1a3
+Version: 0.0.1a4
 Summary: An unofficial, community-driven implementation for Discord app interface patterns.
 Project-URL: Homepage, https://github.com/nicebots-xyz/discordcn-py
-Project-URL: source_archive, https://github.com/nicebots-xyz/discordcn-py/archive/3d2717cc3b78e67dfbbef52df1bc92f0406e734d.zip
+Project-URL: source_archive, https://github.com/nicebots-xyz/discordcn-py/archive/b4a168d863738ba6dfaa0f6dfa823336eebd447f.zip
 Author-email: Paillat-dev <me@paillat.dev>
 License-Expression: MIT
 License-File: LICENSE

{discordcn-0.0.1a3 → discordcn-0.0.1a4}/pyproject.toml

@@ -77,7 +77,8 @@ extend-ignore = [
     "ISC003", #  explicit-string-concatenation conflicts with basedpyright reportImplicitStringConcatenation
     "TRY003", # raise-vanilla-args
     "COM812", # missing-trailing-comma conflicts with formatter
-    "ANN401"# any-type we allow Any
+    "ANN401", # any-type we allow Any
+    "PLR0913" # too-many-arguments 5+ args is fine
 ]
 pydocstyle.convention = "google"
 

{discordcn-0.0.1a3 → discordcn-0.0.1a4}/src/discordcn/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.0.1a3'
-__version_tuple__ = version_tuple = (0, 0, 1, 'a3')
+__version__ = version = '0.0.1a4'
+__version_tuple__ = version_tuple = (0, 0, 1, 'a4')
 
 __commit_id__ = commit_id = None

{discordcn-0.0.1a3 → discordcn-0.0.1a4}/src/discordcn/pycord/__init__.py

@@ -12,6 +12,7 @@ from .interfaces import (
     PageIndicatorButton,
     PaginatorControls,
     PaginatorControlsBase,
+    PaginatorIndicatorModal,
     PaginatorInterface,
     PaginatorInterfaceBase,
 )
@@ -23,6 +24,7 @@ __all__ = (
     "PageIndicatorButton",
     "PaginatorControls",
     "PaginatorControlsBase",
+    "PaginatorIndicatorModal",
     "PaginatorInterface",
     "PaginatorInterfaceBase",
 )

{discordcn-0.0.1a3 → discordcn-0.0.1a4}/src/discordcn/pycord/interfaces/__init__.py

@@ -7,6 +7,7 @@ from .paginator import (
     PageIndicatorButton,
     PaginatorControls,
     PaginatorControlsBase,
+    PaginatorIndicatorModal,
     PaginatorInterface,
     PaginatorInterfaceBase,
 )
@@ -18,6 +19,7 @@ __all__ = (
     "PageIndicatorButton",
     "PaginatorControls",
     "PaginatorControlsBase",
+    "PaginatorIndicatorModal",
     "PaginatorInterface",
     "PaginatorInterfaceBase",
 )

{discordcn-0.0.1a3 → discordcn-0.0.1a4}/src/discordcn/pycord/interfaces/paginator.py

@@ -11,6 +11,7 @@ from collections.abc import Sequence
 from typing import Any, Generic, TypeVar
 
 import discord
+from discord import Interaction
 from typing_extensions import Self, override
 
 from discordcn.pycord._utils import maybe_awaitable
@@ -23,12 +24,12 @@ T = TypeVar("T", bound="PaginatorInterfaceBase")
 class PaginatorInterfaceBase(ABC, discord.ui.DesignerView):
     """ABC defining the interface for paginator views.
 
-    This ABC specifies the minimum requirements for a view to be
-    compatible with paginator controls, ensuring consistent behavior across
-    different paginator implementations.
+    This ABC specifies the minimum requirements for a view to be compatible
+    with paginator controls, ensuring consistent behavior across different
+    paginator implementations.
 
     Attributes:
-        page: The current page index (0-based).
+        page (int): The current page index (0-based).
     """
 
     page: int
@@ -65,12 +66,10 @@ class PaginatorControlsBase(ABC, discord.ui.ActionRow[T], Generic[T]):
 class PageButton(discord.ui.Button[PaginatorInterfaceBase]):
     """Navigation button for jumping to a specific page.
 
-    This button updates the parent view's page index and refreshes the UI
-    when clicked. It is designed to work with any view implementing
-    PaginatorInterfaceBase.
+    Updates the parent view's page index and refreshes the UI when clicked.
 
     Attributes:
-        page: The target page index this button navigates to.
+        page (int): The target page index this button navigates to.
     """
 
     def __init__(self, page: int, **kwargs: Any) -> None:
@@ -78,9 +77,8 @@ class PageButton(discord.ui.Button[PaginatorInterfaceBase]):
 
         Args:
             page: The target page index (0-based) to navigate to when clicked.
-            **kwargs: Additional keyword arguments passed to the parent
-                discord.ui.Button constructor (e.g., ``emoji``, ``style``,
-                ``disabled``).
+            **kwargs: Additional keyword arguments passed to discord.ui.Button
+                (e.g., ``emoji``, ``style``, ``disabled``).
         """
         super().__init__(**kwargs)
         self.page: int = page
@@ -94,6 +92,9 @@ class PageButton(discord.ui.Button[PaginatorInterfaceBase]):
 
         Args:
             interaction: The interaction object from the button click.
+
+        Raises:
+            TypeError: If the button is not attached to a view.
         """
         if self.view is None:
             msg = "This button is not attached to a view."
@@ -107,54 +108,143 @@ class PageButton(discord.ui.Button[PaginatorInterfaceBase]):
             await interaction.response.edit_message(view=v)
 
 
+class PaginatorIndicatorModal(discord.ui.DesignerModal):
+    """Modal for direct page navigation input.
+
+    Allows users to jump to a specific page by entering a page number.
+
+    Attributes:
+        view (PaginatorInterfaceBase): The parent paginator view.
+        input (discord.ui.TextInput): The text input field for page number.
+        invalid (str): Error message shown for invalid page numbers.
+    """
+
+    def __init__(
+        self, modal_title: str, label_title: str, label_description: str, invalid: str, view: PaginatorInterfaceBase
+    ) -> None:
+        """Initialize the page navigation modal.
+
+        Args:
+            modal_title: The title displayed at the top of the modal.
+            label_title: The label text for the input field.
+            label_description: The description text for the input field.
+            invalid: Error message shown when an invalid page number is entered.
+            view: The parent paginator view.
+        """
+        self.view: PaginatorInterfaceBase = view
+        self.input: discord.ui.TextInput = discord.ui.TextInput(
+            style=discord.InputTextStyle.short, max_length=len(str(view.max_page))
+        )
+        self.invalid: str = invalid
+        label: discord.ui.Label[Self] = discord.ui.Label(
+            label=label_title, description=label_description, item=self.input
+        )
+        super().__init__(label, title=modal_title)
+
+    @override
+    async def callback(self, interaction: Interaction) -> None:
+        """Handle modal submission.
+
+        Validates the page number and navigates to the specified page if valid.
+
+        Args:
+            interaction: The interaction object from the modal submission.
+        """
+        await interaction.response.defer()
+        page = self.input.value
+        if not page or not page.isdigit() or (int_page := int(page) - 1) > self.view.max_page:
+            await interaction.respond(self.invalid, ephemeral=True)
+            return
+        self.view.page = int_page
+        await maybe_awaitable(self.view.update())
+        await interaction.edit(view=self.view)
+
+
 class PageIndicatorButton(discord.ui.Button[PaginatorInterfaceBase]):
-    """Non-interactive button displaying the current page number.
+    """Button displaying the current page number.
+
+    Shows the current page position in the format "X/Y". Can optionally be
+    made interactable to open a modal for direct page navigation.
 
-    This button serves as a visual indicator of the current page position
-    and is always disabled to prevent interaction. It displays text in the
-    format "Page X/Y".
+    Attributes:
+        disabled (bool): Whether the button is disabled.
+        modal_title (str): Title for the page navigation modal.
+        label_title (str): Label title for the modal input field.
+        label_description (str): Description for the modal input field.
+        invalid (str): Error message for invalid page input.
     """
 
-    def __init__(self, *, label: str) -> None:
+    def __init__(
+        self,
+        *,
+        label: str,
+        interactable: bool,
+        modal_title: str,
+        label_title: str,
+        label_description: str,
+        invalid: str,
+    ) -> None:
         """Initialize a page indicator button.
 
         Args:
-            label: The text to display on the button (typically "Page X/Y").
+            label: The text to display on the button (typically "X/Y" format).
+            interactable: Whether clicking the button should open a navigation modal.
+            modal_title: Title for the page navigation modal.
+            label_title: Label for the modal's input field.
+            label_description: Description for the modal's input field.
+            invalid: Error message shown for invalid page numbers.
         """
         super().__init__(style=discord.ButtonStyle.secondary, label=label)
-        self.disabled: bool = True
+        self.disabled: bool = not interactable
+        self.modal_title: str = modal_title
+        self.label_title: str = label_title
+        self.label_description: str = label_description
+        self.invalid: str = invalid
 
     @override
     async def callback(self, interaction: discord.Interaction) -> None:
-        """Handle button click interactions (no-op).
+        """Handle button click interactions.
 
-        This callback defers the interaction invisibly since the button is
-        disabled and should never be clicked.
+        Opens a modal for direct page navigation when clicked.
 
         Args:
             interaction: The interaction object from the button click.
+
+        Raises:
+            TypeError: If the button is not attached to a view.
         """
-        await interaction.response.defer(invisible=True)
+        if self.view is None:
+            msg = "This button is not attached to a view."
+            raise TypeError(msg)
+
+        await interaction.response.send_modal(
+            PaginatorIndicatorModal(  # pyright: ignore[reportArgumentType]
+                modal_title=self.modal_title,
+                label_title=self.label_title,
+                label_description=self.label_description,
+                invalid=self.invalid,
+                view=self.view,
+            )
+        )
 
 
 class PaginatorControls(PaginatorControlsBase[T], Generic[T]):
     """Navigation controls row for paginator interfaces.
 
-    This action row contains five elements:
-        - First page button (⏮️): Jump to page 0
-        - Previous page button (◀️): Go back one page
-        - Page indicator: Display current page position (non-interactive)
-        - Next page button (▶️): Advance one page
-        - Last page button (⏭️): Jump to the final page
-
-    Buttons are automatically disabled when they would navigate beyond valid
-    page boundaries (e.g., previous/first buttons on page 0).
-
-    Attributes:
-        FIRST_EMOJI: The emoji to use for the "first page" button.
-        LEFT_EMOJI: The emoji to use for the "previous page" button.
-        RIGHT_EMOJI: The emoji to use for the "next page" button.
-        LAST_EMOJI: The emoji to use for the "last page" button.
+    Provides five navigation elements: first page, previous page, page indicator,
+    next page, and last page. Buttons are automatically disabled when they would
+    navigate beyond valid page boundaries.
+
+    Class Attributes:
+        FIRST_EMOJI (EmojiType): Emoji for the "first page" button.
+        LEFT_EMOJI (EmojiType): Emoji for the "previous page" button.
+        RIGHT_EMOJI (EmojiType): Emoji for the "next page" button.
+        LAST_EMOJI (EmojiType): Emoji for the "last page" button.
+        INTERACTABLE_INDICATOR (bool): Whether the page indicator opens a navigation modal.
+        MODAL_TITLE (str): Title for the page navigation modal.
+        MODAL_LABEL_TITLE (str): Label for the modal's input field.
+        MODAL_LABEL_DESCRIPTION (str): Description for the modal's input field.
+        MODAL_INVALID (str): Error message for invalid page input.
     """
 
     FIRST_EMOJI: EmojiType = discord.PartialEmoji(name="⏮️")
@@ -162,6 +252,12 @@ class PaginatorControls(PaginatorControlsBase[T], Generic[T]):
     RIGHT_EMOJI: EmojiType = discord.PartialEmoji(name="▶️")
     LAST_EMOJI: EmojiType = discord.PartialEmoji(name="⏭️")
 
+    INTERACTABLE_INDICATOR: bool = True
+    MODAL_TITLE: str = "Page Navigation"
+    MODAL_LABEL_TITLE: str = "Page Number:"
+    MODAL_LABEL_DESCRIPTION: str = "Input a page number to jump to that page."
+    MODAL_INVALID: str = "Please input a valid page number."
+
     def __init__(
         self,
         view: T,
@@ -194,6 +290,11 @@ class PaginatorControls(PaginatorControlsBase[T], Generic[T]):
         self.add_item(
             PageIndicatorButton(
                 label=f"{view.page + 1}/{view.max_page + 1}",
+                interactable=self.INTERACTABLE_INDICATOR,
+                modal_title=self.MODAL_TITLE,
+                label_title=self.MODAL_LABEL_TITLE,
+                label_description=self.MODAL_LABEL_DESCRIPTION,
+                invalid=self.MODAL_INVALID,
             ),
         )
         self.add_item(
@@ -217,19 +318,16 @@ class PaginatorControls(PaginatorControlsBase[T], Generic[T]):
 class PaginatorInterface(PaginatorInterfaceBase):
     """Multi-page view with automatic navigation controls.
 
-    This view manages navigation between multiple pages of UI components,
-    automatically displaying the appropriate page content and navigation
-    controls. Each page is defined as a sequence of view items (buttons,
-    selects, etc.) that are dynamically loaded when navigating between pages.
-
-    The paginator automatically appends navigation controls to the bottom of
-    each page, allowing users to move between pages using first/previous/next/last
-    buttons and see their current position.
+    Manages navigation between multiple pages of UI components, automatically
+    displaying the appropriate page content and navigation controls. Each page
+    is dynamically loaded when navigating between pages.
 
     Attributes:
-        pages: The sequence of pages, where each page is a sequence of view items.
-        page: The current page index (0-based).
-        controls: The paginator controls class to use for navigation.
+        pages (Sequence[Sequence[discord.ui.ViewItem[discord.ui.DesignerView]]]):
+            The sequence of pages, where each page is a sequence of view items.
+        page (int): The current page index (0-based).
+        controls (type[PaginatorControlsBase[Self]]): The paginator controls
+            class to use for navigation.
     """
 
     def __init__(
@@ -258,7 +356,7 @@ class PaginatorInterface(PaginatorInterfaceBase):
         """The maximum page index (0-based).
 
         Returns:
-            The index of the last page, equal to ``len(pages) - 1``.
+            The index of the last page.
         """
         return len(self.pages) - 1
 
@@ -273,7 +371,8 @@ class PaginatorInterface(PaginatorInterfaceBase):
         self.clear_items()
         for item in self.pages[self.page]:
             self.add_item(item)
-        self.add_item(self.controls(self))
+        if len(self.pages) > 1:
+            self.add_item(self.controls(self))
 
 
 __all__ = (
@@ -281,6 +380,7 @@ __all__ = (
     "PageIndicatorButton",
     "PaginatorControls",
     "PaginatorControlsBase",
+    "PaginatorIndicatorModal",
     "PaginatorInterface",
     "PaginatorInterfaceBase",
 )