feat: implement cv2 layout parsing (#50)

* refactor!: make get/set manager work on class level

* refactor!: update component (de)registration logic

* refactor: make component invocation work with changes

* feat(docs): add changelog entries

* chore: bump dev dependencies

* chore: fix pyright issues

* feat: make parse_message_components cv2-compatible

* docs(examples): add cv2 example (wip)

* feat: implement v2 component parsing into manager

* feat!: implement component layout updating

* fix(ci): make pre-commit actually use config???

* docs(example): clean up example

* refactor: break out disnake types into separate file

* feat(docs): add changelog entries

* chore(docs): oopsie

* fix: use new layout methods in row example

* fix: make count chars actually store all possible count chars

* feat: implement cv2 id fields on rich components

* fish(mael): i'm

Author: Sharp-Eyes

.pre-commit-config.yaml

@@ -29,9 +29,10 @@ repos:
     rev: v0.9.6
     hooks:
       - id: ruff
-        args: [--fix, --exit-non-zero-on-fix]
+        args: [--fix, --exit-non-zero-on-fix, --config, pyproject.toml]
         name: Running ruff in all files.
       - id: ruff-format
+        args: [--config, pyproject.toml]
 
   - repo: https://github.com/ariebovenberg/slotscheck
     rev: v0.19.1

changelog/50.breaking.0.rst

@@ -0,0 +1 @@
+Modify :meth:`ComponentManager.parse_message_components` to take components directly and return a sequence of disnake UI components to support parsing v2 components.

changelog/50.breaking.1.rst

@@ -0,0 +1 @@
+Remove ``ComponentManager.finalise_components`` in favour of :meth:`ComponentManager.update_layout`.

changelog/50.feature.rst

@@ -0,0 +1 @@
+Add :meth:`ComponentManager.update_layout` to update a disnake UI component layout in-place with rich components (v1 and v2 compatible).

examples/row.py

@@ -4,9 +4,10 @@
 import typing
 
 import disnake
-import disnake_compass
 from disnake.ext import commands
 
+import disnake_compass
+
 DEFAULT_OPTION = disnake.SelectOption(
     label="Please enable some options.",
     value="placeholder",
@@ -32,9 +33,7 @@ def parse_options(self) -> typing.Sequence[disnake.SelectOption]:
 
         return [disnake.SelectOption(label=option) for option in self.options]
 
-    def update_select(
-        self, components: typing.Sequence[disnake_compass.api.RichComponent]
-    ):
+    def update_select(self, components: typing.Sequence[disnake_compass.api.RichComponent]):
         select: DynamicSelectMenu | None = None
         options: list[disnake.SelectOption] = []
 
@@ -57,7 +56,7 @@ async def callback(self, interaction: disnake.MessageInteraction[disnake.Client]
         # Get all components on the message for easier re-sending.
         # Both of these lists will automagically contain self so that any
         # changes immediately reflect without extra effort.
-        rows, components = await manager.parse_message_components(interaction.message)
+        layout, components = await manager.parse_message_components(interaction.message.components)
 
         # Toggle style for the clicked button.
         self.style = (
@@ -71,8 +70,8 @@ async def callback(self, interaction: disnake.MessageInteraction[disnake.Client]
         self.update_select(components)
 
         # Re-send and update all components.
-        finalised = await manager.finalise_components(rows)
-        await interaction.response.edit_message(components=finalised)
+        await manager.update_layout(layout, components)
+        await interaction.response.edit_message(components=layout)
 
 
 @manager.register()
@@ -93,9 +92,7 @@ def set_options(self, options: typing.List[disnake.SelectOption]):
             self.max_values = 1
             self.disabled = True
 
-    async def callback(
-        self, interaction: disnake.MessageInteraction[disnake.Client]
-    ) -> None:
+    async def callback(self, interaction: disnake.MessageInteraction[disnake.Client]) -> None:
         selection = (
             "\n".join(f"- {value}" for value in interaction.values)
             if interaction.values
@@ -109,16 +106,22 @@ async def callback(
 async def test_components(
     interaction: disnake.CommandInteraction[disnake.Client],
 ) -> None:
-    layout = await manager.finalise_components(
+    # TODO: Maybe a utility method to turn a sequence of rich components into a
+    #       sequence of UI components?
+    layout = [
         [
-            [
-                OptionsToggleButton(label="numbers", options=["1", "2", "3", "4", "5"]),
-                OptionsToggleButton(label="letters", options=["a", "b", "c", "d", "e"]),
-                OptionsToggleButton(label="symbols", options=["*", "&", "#", "+", "-"]),
-            ],
-            [DynamicSelectMenu()],
+            await OptionsToggleButton(
+                label="numbers", options=["1", "2", "3", "4", "5"]
+            ).as_ui_component(),
+            await OptionsToggleButton(
+                label="letters", options=["a", "b", "c", "d", "e"]
+            ).as_ui_component(),
+            await OptionsToggleButton(
+                label="symbols", options=["*", "&", "#", "+", "-"]
+            ).as_ui_component(),
         ],
-    )
+        [await DynamicSelectMenu().as_ui_component()],
+    ]
 
     await interaction.response.send_message(components=layout)
 

examples/v2.py

@@ -0,0 +1,113 @@
+"""An example showcasing a simple cv2-style paginator powered by disnake-compass."""
+
+import os
+
+import disnake
+import disnake_compass
+from disnake.ext import commands
+
+bot = commands.InteractionBot()
+
+manager = disnake_compass.get_manager()
+manager.add_to_client(bot)
+
+
+@manager.register()
+class PageAdvanceButton(disnake_compass.RichButton):
+    increment: int
+
+    async def callback(self, inter: disnake.MessageInteraction[disnake.Client]) -> None:
+        _, components = await manager.parse_message_components(inter.message.components)
+
+        # Find and increment the page tracker...
+        for component in components:
+            if isinstance(component, PageTrackerButton):
+                component.increment(self.increment)
+                break
+        else:
+            # Unreachable, a page tracker should always be sent alongside
+            # any page advancing buttons.
+            raise RuntimeError
+
+        new_page = await create_paginator(component.page, component.pages)
+        await inter.response.edit_message(components=new_page)
+
+
+@manager.register()
+class PageTrackerButton(disnake_compass.RichButton):
+    disabled: bool = True
+
+    page: int
+    pages: int
+
+    def __attrs_post_init__(self) -> None:
+        self.update_label()
+
+    def increment(self, inc: int):
+        self.page = (self.page + inc) % self.pages
+        self.update_label()
+
+    def update_label(self):
+        self.label = f"{self.page + 1} / {self.pages}"
+
+    async def callback(self, _: disnake.MessageInteraction[disnake.Client]) -> None:
+        raise NotImplementedError  # This button is always disabled.
+
+
+def create_paginator_content(page_number: int):
+    if page_number == 0:
+        return disnake.ui.Section(
+            disnake.ui.TextDisplay(
+                "Welcome aboard, greenhorn!\nYou are able-bodied and ready for the voyage, I trust?"
+            ),
+            accessory=disnake.ui.Thumbnail(
+                "https://limbuscompany.wiki.gg/images/The_Pequod_Captain_Ishmael_Idle_Sprite.png"
+            ),
+        )
+
+    if page_number == 1:
+        return disnake.ui.Section(
+            disnake.ui.TextDisplay("Of course. Has my compass ever led you astray?"),
+            accessory=disnake.ui.Thumbnail(
+                "https://limbuscompany.wiki.gg/images/The_Pequod_Captain_Ishmael_Evade_Sprite.png"
+            ),
+        )
+
+    if page_number == 2:
+        return disnake.ui.Section(
+            disnake.ui.TextDisplay("I'm Fishmael"),
+            accessory=disnake.ui.Thumbnail(
+                "https://media.tenor.com/mINH1nt-0zgAAAAd/fishmael-limbus-company.gif"
+            ),
+        )
+
+    msg = f"Unknown page number: {page_number}"
+    raise ValueError(msg)
+
+
+async def create_paginator_controls(page_number: int, pages: int):
+    return disnake.ui.ActionRow(
+        await PageAdvanceButton(label="<", increment=-1).as_ui_component(),
+        await PageTrackerButton(page=page_number, pages=pages).as_ui_component(),
+        await PageAdvanceButton(label=">", increment=1).as_ui_component(),
+    )
+
+
+async def create_paginator(page_number: int, pages: int):
+    assert page_number < pages
+
+    return disnake.ui.Container(
+        disnake.ui.TextDisplay("## Compass"),
+        disnake.ui.Separator(),
+        create_paginator_content(page_number),
+        disnake.ui.Separator(),
+        await create_paginator_controls(page_number, pages),
+    )
+
+
+@bot.slash_command()
+async def test_v2(inter: disnake.CommandInteraction[disnake.Client]):
+    await inter.response.send_message(components=[await create_paginator(0, 3)])
+
+
+bot.run(os.getenv("EXAMPLE_TOKEN"))

src/disnake_compass/api/component.py

@@ -115,6 +115,7 @@ class RichButton(RichComponent, typing.Protocol):
     A disabled button is greyed out on discord, and cannot be pressed.
     Disabled buttons can therefore not cause any interactions, either.
     """
+    id: int
 
     async def as_ui_component(  # noqa: D102
         self, manager: ComponentManager | None = None, /
@@ -151,6 +152,7 @@ class RichSelect(RichComponent, typing.Protocol):
     A disabled select is greyed out on discord, and cannot be used.
     Disabled selects can therefore not cause any interactions, either.
     """
+    id: int
 
     async def as_ui_component(  # noqa: D102
         self, manager: ComponentManager | None = None, /
@@ -241,6 +243,17 @@ def get_identifier(self, custom_id: str, /) -> tuple[str, typing.Sequence[str]]:
         """
         ...
 
+    def lookup_identifier(self, component_type: type[RichComponent], /) -> str:
+        """Look up the identifier of an already registered component type.
+
+        Parameters
+        ----------
+        component_type
+            The component type for which to look up the registered identifier.
+
+        """
+        ...
+
     async def make_custom_id(self, component: RichComponent, /) -> str:
         """Make a custom id from the provided component.
 
@@ -278,7 +291,7 @@ def register_component(
             The component class to register.
         identifier
             The identifier with which to register this component class.
-            
+
         Returns
         -------
         :class:`type`\[:data:`.ComponentT`]

src/disnake_compass/api/disnake_compat.py

@@ -0,0 +1,31 @@
+"""Re-exports of some disnake internal types related to components."""
+
+import typing
+
+import disnake
+
+# NOTE: Keep up to date with disnake types...
+
+ActionRowMessageComponent = disnake.ui.Button[typing.Any] | disnake.ui.Select[typing.Any]
+MessageTopLevelComponentV2 = (
+    disnake.ui.Section
+    | disnake.ui.TextDisplay
+    | disnake.ui.MediaGallery
+    | disnake.ui.File
+    | disnake.ui.Separator
+    | disnake.ui.Container
+)
+ModalTopLevelComponent_ = disnake.ui.TextDisplay | disnake.ui.Label
+ActionRowChildT = typing.TypeVar("ActionRowChildT", bound=disnake.ui.WrappedComponent)
+NonActionRowChildT = typing.TypeVar(
+    "NonActionRowChildT",
+    bound=MessageTopLevelComponentV2 | ModalTopLevelComponent_,
+)
+AnyUIComponentInput = ActionRowChildT | disnake.ui.ActionRow[ActionRowChildT] | NonActionRowChildT
+ComponentInput = (
+    AnyUIComponentInput[ActionRowChildT, NonActionRowChildT]
+    | typing.Sequence[
+        AnyUIComponentInput[ActionRowChildT, NonActionRowChildT] | typing.Sequence[ActionRowChildT]
+    ]
+)
+MessageComponents = ComponentInput[ActionRowMessageComponent, MessageTopLevelComponentV2]

src/disnake_compass/impl/component/button.py

@@ -52,6 +52,7 @@ class RichButton(
     style: disnake.ButtonStyle = fields.internal(default=disnake.ButtonStyle.secondary)
     emoji: _AnyEmoji | None = fields.internal(default=None)
     disabled: bool = fields.internal(default=False)
+    id: int = fields.internal(default=0)
 
     async def as_ui_component(  # noqa: D102
         self, manager: component_api.ComponentManager | None = None, /
@@ -64,4 +65,5 @@ async def as_ui_component(  # noqa: D102
             disabled=self.disabled,
             emoji=self.emoji,
             custom_id=await self.make_custom_id(manager),
+            id=self.id,
         )

src/disnake_compass/impl/component/select.py

@@ -38,6 +38,7 @@ class BaseSelect(
     min_values: int = fields.internal(default=1)
     max_values: int = fields.internal(default=1)
     disabled: bool = fields.internal(default=False)
+    id: int = fields.internal(default=0)
 
 
 class RichStringSelect(BaseSelect, typing.Protocol):
@@ -81,6 +82,7 @@ async def as_ui_component(  # noqa: D102
             disabled=self.disabled,
             options=self.options,
             custom_id=await self.make_custom_id(manager),
+            id=self.id,
         )
 
 
@@ -116,6 +118,7 @@ async def as_ui_component(  # noqa: D102
             max_values=self.max_values,
             disabled=self.disabled,
             custom_id=await self.make_custom_id(manager),
+            id=self.id,
         )
 
 
@@ -151,6 +154,7 @@ async def as_ui_component(  # noqa: D102
             max_values=self.max_values,
             disabled=self.disabled,
             custom_id=await self.make_custom_id(manager),
+            id=self.id,
         )
 
 
@@ -186,6 +190,7 @@ async def as_ui_component(  # noqa: D102
             max_values=self.max_values,
             disabled=self.disabled,
             custom_id=await self.make_custom_id(manager),
+            id=self.id,
         )
 
 
@@ -230,4 +235,5 @@ async def as_ui_component(  # noqa: D102
             max_values=self.max_values,
             disabled=self.disabled,
             custom_id=await self.make_custom_id(manager),
+            id=self.id,
         )