feat: new modal components (#1321)

Signed-off-by: vi <[email protected]>
Co-authored-by: Snipy7374 <[email protected]>
Co-authored-by: arielle <[email protected]>

Author: 3 people

changelog/1321.deprecate.rst

@@ -0,0 +1,3 @@
+Using :class:`~ui.ActionRow`\s (or plain :class:`~ui.TextInput`\s, which implicitly get wrapped in action rows) in modals is now deprecated in favor of :class:`ui.Label`.
+- This deprecates :meth:`ui.ActionRow.add_text_input`, :meth:`ui.ActionRow.with_modal_components`.
+- Using :class:`TextInput.label` is also deprecated in favor of ``Label("<text>", TextInput(...))``.

changelog/1321.feature.rst

@@ -0,0 +1,5 @@
+Add support for new components in :class:`~ui.Modal`\s.
+- Add new top-level :class:`ui.Label` component, which wraps other components (currently :class:`~ui.TextInput` and :class:`~ui.StringSelect`) in a modal with a label and description.
+- :class:`ui.StringSelect` can now be used in modals when placed inside a :class:`ui.Label`.
+- The new modal-specific :attr:`ui.StringSelect.required` field can be used to make a select menu optional.
+- The values provided by users on modal submit are available in :attr:`ModalInteraction.values`.

disnake/components.py

@@ -49,6 +49,7 @@
         ComponentType as ComponentTypeLiteral,
         ContainerComponent as ContainerComponentPayload,
         FileComponent as FileComponentPayload,
+        LabelComponent as LabelComponentPayload,
         MediaGalleryComponent as MediaGalleryComponentPayload,
         MediaGalleryItem as MediaGalleryItemPayload,
         MentionableSelectMenu as MentionableSelectMenuPayload,
@@ -89,6 +90,7 @@
     "FileComponent",
     "Separator",
     "Container",
+    "Label",
 )
 
 # miscellaneous components-related type aliases
@@ -135,6 +137,12 @@
     "Separator",
 ]
 
+# valid `Label.component` types
+LabelChildComponent = Union[
+    "TextInput",
+    "StringSelectMenu",
+]
+
 # valid `Message.components` item types (v1/v2)
 MessageTopLevelComponentV1: TypeAlias = "ActionRow[ActionRowMessageComponent]"
 MessageTopLevelComponentV2 = Union[
@@ -164,6 +172,7 @@ class Component:
     - :class:`FileComponent`
     - :class:`Separator`
     - :class:`Container`
+    - :class:`Label`
 
     This class is abstract and cannot be instantiated.
 
@@ -386,6 +395,11 @@ class BaseSelectMenu(Component):
         Only available for auto-populated select menus.
 
         .. versionadded:: 2.10
+    required: :class:`bool`
+        Whether the select menu is required. Only applies to components in modals.
+        Defaults to ``True``.
+
+        .. versionadded:: 2.11
     id: :class:`int`
         The numeric identifier for the component.
         This is always present in components received from the API,
@@ -401,6 +415,7 @@ class BaseSelectMenu(Component):
         "max_values",
         "disabled",
         "default_values",
+        "required",
     )
 
     # FIXME: this isn't pretty; we should decouple __repr__ from slots
@@ -424,6 +439,7 @@ def __init__(self, data: AnySelectMenuPayload) -> None:
         self.default_values: List[SelectDefaultValue] = [
             SelectDefaultValue._from_dict(d) for d in (data.get("default_values") or [])
         ]
+        self.required: bool = data.get("required", True)
 
     def to_dict(self) -> BaseSelectMenuPayload:
         payload: BaseSelectMenuPayload = {
@@ -433,6 +449,7 @@ def to_dict(self) -> BaseSelectMenuPayload:
             "min_values": self.min_values,
             "max_values": self.max_values,
             "disabled": self.disabled,
+            "required": self.required,
         }
 
         if self.placeholder:
@@ -472,6 +489,11 @@ class StringSelectMenu(BaseSelectMenu):
         Whether the select menu is disabled or not.
     options: List[:class:`SelectOption`]
         A list of options that can be selected in this select menu.
+    required: :class:`bool`
+        Whether the select menu is required. Only applies to components in modals.
+        Defaults to ``True``.
+
+        .. versionadded:: 2.11
     id: :class:`int`
         The numeric identifier for the component.
         This is always present in components received from the API,
@@ -531,6 +553,11 @@ class UserSelectMenu(BaseSelectMenu):
         If set, the number of items must be within the bounds set by ``min_values`` and ``max_values``.
 
         .. versionadded:: 2.10
+    required: :class:`bool`
+        Whether the select menu is required. Only applies to components in modals.
+        Defaults to ``True``.
+
+        .. versionadded:: 2.11
     id: :class:`int`
         The numeric identifier for the component.
         This is always present in components received from the API,
@@ -577,6 +604,11 @@ class RoleSelectMenu(BaseSelectMenu):
         If set, the number of items must be within the bounds set by ``min_values`` and ``max_values``.
 
         .. versionadded:: 2.10
+    required: :class:`bool`
+        Whether the select menu is required. Only applies to components in modals.
+        Defaults to ``True``.
+
+        .. versionadded:: 2.11
     id: :class:`int`
         The numeric identifier for the component.
         This is always present in components received from the API,
@@ -623,6 +655,11 @@ class MentionableSelectMenu(BaseSelectMenu):
         If set, the number of items must be within the bounds set by ``min_values`` and ``max_values``.
 
         .. versionadded:: 2.10
+    required: :class:`bool`
+        Whether the select menu is required. Only applies to components in modals.
+        Defaults to ``True``.
+
+        .. versionadded:: 2.11
     id: :class:`int`
         The numeric identifier for the component.
         This is always present in components received from the API,
@@ -672,6 +709,11 @@ class ChannelSelectMenu(BaseSelectMenu):
         If set, the number of items must be within the bounds set by ``min_values`` and ``max_values``.
 
         .. versionadded:: 2.10
+    required: :class:`bool`
+        Whether the select menu is required. Only applies to components in modals.
+        Defaults to ``True``.
+
+        .. versionadded:: 2.11
     id: :class:`int`
         The numeric identifier for the component.
         This is always present in components received from the API,
@@ -861,6 +903,10 @@ class TextInput(Component):
         The style of the text input.
     label: Optional[:class:`str`]
         The label of the text input.
+
+        .. deprecated:: 2.11
+            Deprecated in favor of :class:`Label`.
+
     custom_id: :class:`str`
         The ID of the text input that gets received during an interaction.
     placeholder: Optional[:class:`str`]
@@ -902,7 +948,7 @@ def __init__(self, data: TextInputPayload) -> None:
         self.style: TextInputStyle = try_enum(
             TextInputStyle, data.get("style", TextInputStyle.short.value)
         )
-        self.label: Optional[str] = data.get("label")
+        self.label: Optional[str] = data.get("label")  # deprecated
         self.placeholder: Optional[str] = data.get("placeholder")
         self.value: Optional[str] = data.get("value")
         self.required: bool = data.get("required", True)
@@ -914,7 +960,7 @@ def to_dict(self) -> TextInputPayload:
             "type": self.type.value,
             "id": self.id,
             "style": self.style.value,
-            "label": cast("str", self.label),
+            "label": self.label,
             "custom_id": self.custom_id,
             "required": self.required,
         }
@@ -1420,6 +1466,65 @@ def accent_color(self) -> Optional[Colour]:
         return self.accent_colour
 
 
+class Label(Component):
+    """Represents a label from the Discord Bot UI Kit.
+
+    This wraps other components with a label and an optional description,
+    and can only be used in modals.
+
+    .. versionadded:: 2.11
+
+    .. note::
+
+        The user constructible and usable type to create a label is
+        :class:`disnake.ui.Label`, not this one.
+
+    Attributes
+    ----------
+    text: :class:`str`
+        The label text.
+    description: Optional[:class:`str`]
+        The description text for the label.
+    component: Union[:class:`TextInput`, :class:`StringSelectMenu`]
+        The component within the label.
+    id: :class:`int`
+        The numeric identifier for the component.
+        This is always present in components received from the API,
+        and unique within a message.
+    """
+
+    __slots__: Tuple[str, ...] = (
+        "text",
+        "description",
+        "component",
+    )
+
+    __repr_info__: ClassVar[Tuple[str, ...]] = __slots__
+
+    def __init__(self, data: LabelComponentPayload) -> None:
+        self.type: Literal[ComponentType.label] = ComponentType.label
+        self.id = data.get("id", 0)
+
+        self.text: str = data["label"]
+        self.description: Optional[str] = data.get("description")
+
+        component = _component_factory(data["component"])
+        self.component: LabelChildComponent = component  # type: ignore
+
+    def to_dict(self) -> LabelComponentPayload:
+        payload: LabelComponentPayload = {
+            "type": self.type.value,
+            "id": self.id,
+            "label": self.text,
+            "component": self.component.to_dict(),
+        }
+
+        if self.description is not None:
+            payload["description"] = self.description
+
+        return payload
+
+
 # types of components that are allowed in a message's action rows;
 # see also `ActionRowMessageComponent` type alias
 VALID_ACTION_ROW_MESSAGE_COMPONENT_TYPES: Final = (
@@ -1467,6 +1572,7 @@ def handle_media_item_input(value: MediaItemInput) -> UnfurledMediaItem:
     ComponentType.file.value: FileComponent,
     ComponentType.separator.value: Separator,
     ComponentType.container.value: Container,
+    ComponentType.label.value: Label,
 }
 
 

disnake/enums.py

@@ -1265,6 +1265,11 @@ class ComponentType(Enum):
     container = 17
     """Represents a Components V2 container component.
 
+    .. versionadded:: 2.11
+    """
+    label = 18
+    """Represents a label component.
+
     .. versionadded:: 2.11
     """
 

disnake/interactions/base.py

@@ -12,6 +12,7 @@
     List,
     Mapping,
     Optional,
+    Sequence,
     Tuple,
     TypeVar,
     Union,
@@ -75,15 +76,18 @@
     from ..mentions import AllowedMentions
     from ..poll import Poll
     from ..state import ConnectionState
-    from ..types.components import Modal as ModalPayload
+    from ..types.components import (
+        Modal as ModalPayload,
+        ModalTopLevelComponent as ModalTopLevelComponentPayload,
+    )
     from ..types.interactions import (
         ApplicationCommandOptionChoice as ApplicationCommandOptionChoicePayload,
         Interaction as InteractionPayload,
         InteractionDataResolved as InteractionDataResolvedPayload,
     )
     from ..types.snowflake import Snowflake
     from ..types.user import User as UserPayload
-    from ..ui._types import MessageComponents, ModalComponents
+    from ..ui._types import MessageComponents, ModalComponents, ModalTopLevelComponent
     from ..ui.modal import Modal
     from ..ui.view import View
     from .message import MessageInteraction
@@ -1499,11 +1503,18 @@ async def send_modal(
         custom_id: :class:`str`
             The ID of the modal that gets received during an interaction.
             This cannot be mixed with the ``modal`` parameter.
-        components: |components_type|
+        components: |modal_components_type|
             The components to display in the modal. A maximum of 5.
-            Currently only supports :class:`ui.TextInput` (optionally inside :class:`ui.ActionRow`).
+            Currently only supports :class:`.ui.TextInput` and
+            :class:`.ui.StringSelect`, wrapped in :class:`.ui.Label`\\s.
+
             This cannot be mixed with the ``modal`` parameter.
 
+            .. versionchanged:: 2.11
+                Using action rows in modals or passing :class:`.ui.TextInput` directly
+                (which implicitly wraps it in an action row) is deprecated.
+                Use :class:`.ui.TextInput` inside a :class:`.ui.Label` instead.
+
         Raises
         ------
         TypeError
@@ -1533,14 +1544,17 @@ async def send_modal(
         if modal is not None:
             modal_data = modal.to_components()
         elif title and components and custom_id:
-            rows = normalize_components(components)
-            if len(rows) > 5:
+            items: Sequence[ModalTopLevelComponent] = normalize_components(components, modal=True)
+            if len(items) > 5:
                 raise ValueError("Maximum number of components exceeded.")
 
             modal_data = {
                 "title": title,
                 "custom_id": custom_id,
-                "components": [component.to_component_dict() for component in rows],
+                "components": cast(
+                    "List[ModalTopLevelComponentPayload]",
+                    [component.to_component_dict() for component in items],
+                ),
             }
         else:
             raise TypeError("Either modal or title, custom_id, components must be provided")