Components refactor

guide/.vuepress/sidebar.ts

@@ -72,12 +72,12 @@ export default {
 			]
 		},
 		{
-			text: 'Message Components',
+			text: 'Interactive Components',
 			children: [
-				'/message-components/action-rows.md',
-				'/message-components/buttons.md',
-				'/message-components/select-menus.md',
-				'/message-components/interactions.md',
+				'/interactive-components/action-rows.md',
+				'/interactive-components/buttons.md',
+				'/interactive-components/select-menus.md',
+				'/interactive-components/interactions.md',
 			]
 		},
 		{
@@ -94,7 +94,7 @@ export default {
 				'/popular-topics/audit-logs.md',
 				'/popular-topics/canvas.md',
 				'/popular-topics/collectors.md',
-				'/popular-topics/components-v2.md',
+				'/popular-topics/display-components.md',
 				'/popular-topics/embeds.md',
 				'/popular-topics/errors.md',
 				'/popular-topics/formatters.md',

guide/additional-info/changes-in-v13.md

@@ -75,7 +75,7 @@ In addition to the `interactionCreate` event covered in the above guide, this re
 discord.js now has support for message components!
 This introduces the `MessageActionRow`, `MessageButton`, and `MessageSelectMenu` classes, as well as associated interactions and collectors. 
 
-Refer to the [message components](/message-components/buttons.md) section of this guide to get started.
+Refer to the [message components](/interactive-components/buttons.md) section of this guide to get started.
 
 ## Threads
 
@@ -1136,7 +1136,7 @@ A Collection of Roles which are managed by the integration.
 
 Provides gateway support for slash command and message component interactions. 
 
-For more information refer to the [slash commands](/interactions/slash-commands.md#replying-to-slash-commands) and [message components](/message-components/buttons) sections of the guide.
+For more information refer to the [slash commands](/interactions/slash-commands.md#replying-to-slash-commands) and [message components](/interactive-components/buttons) sections of the guide.
 
 ### InteractionCollector
 

guide/creating-your-bot/command-deployment.md

@@ -134,7 +134,7 @@ You've successfully sent a response to a slash command! However, this is only th
 * utilising the different [Response methods](/slash-commands/response-methods.md) that can be used for slash commands.
 * expanding on these examples with additional validated option types in [Advanced command creation](/slash-commands/advanced-creation.md).
 * adding formatted [Embeds](/popular-topics/embeds.md) to your responses.
-* enhancing the command functionality with [Buttons](/message-components/buttons) and [Select Menus](/message-components/select-menus).
+* enhancing the command functionality with [Buttons](/interactive-components/buttons) and [Select Menus](/interactive-components/select-menus).
 * prompting the user for more information with [Modals](/interactions/modals.md).
 
 #### Resulting code

guide/message-components/buttons.md → guide/interactive-components/buttons.md

@@ -3,7 +3,7 @@
 The first type of interactive component we'll cover creating is a Button. Buttons are available in a variety of styles and can be used to provide permanent interfaces, temporary confirmation workflows, and other forms of additional interaction with your bot.
 
 ::: tip
-This page is a follow-up to the [slash commands](/slash-commands/advanced-creation) section and [action rows](/message-components/action-rows) page. Please carefully read those pages first so that you can understand the methods used here.
+This page is a follow-up to the [slash commands](/slash-commands/advanced-creation) section and [action rows](/interactive-components/action-rows) page. Please carefully read those pages first so that you can understand the methods used here.
 :::
 
 ## Building buttons
@@ -169,4 +169,4 @@ const button = new ButtonBuilder()
 
 #### Next steps
 
-That's everything you need to know about building and sending buttons! From here you can learn about the other type of message component, [select menus](/message-components/select-menus), or have your bot start listening to [component interactions](/message-components/interactions) from your buttons. 
+That's everything you need to know about building and sending buttons! From here you can learn about the other type of message component, [select menus](/interactive-components/select-menus), or have your bot start listening to [component interactions](/interactive-components/interactions) from your buttons. 

guide/message-components/interactions.md → guide/interactive-components/interactions.md

@@ -7,7 +7,7 @@ Every button click or select menu selection on a component sent by your bot fire
 - Creating a permanent component handler in the <DocsLink path="Client:Class#interactionCreate" /> event.
 
 ::: tip
-This page is a follow-up to the [slash commands](/slash-commands/advanced-creation) section, and assumes you have created either [buttons](/message-components/buttons) or [select menus](/message-components/select-menus) as detailed in this guide. Please carefully read those pages first so that you can understand the methods used here.
+This page is a follow-up to the [slash commands](/slash-commands/advanced-creation) section, and assumes you have created either [buttons](/interactive-components/buttons) or [select menus](/interactive-components/select-menus) as detailed in this guide. Please carefully read those pages first so that you can understand the methods used here.
 :::
 
 ## Responding to component interactions
@@ -32,7 +32,7 @@ Once `deferUpdate()` has been called, future messages can be sent by calling `fo
 
 ## Awaiting components
 
-If you followed our [buttons](/message-components/buttons) guide, the confirmation workflow for the `ban` command is a good example of a situation where your bot is expecting to receive a single response, from either the Confirm or Cancel button.
+If you followed our [buttons](/interactive-components/buttons) guide, the confirmation workflow for the `ban` command is a good example of a situation where your bot is expecting to receive a single response, from either the Confirm or Cancel button.
 
 Begin by adding `withResponse` to the options, and then calling <DocsLink path="Message:Class#awaitMessageComponent" type="method" /> on the message. This method returns a [Promise](/additional-info/async-await.md) that resolves when any interaction passes its filter (if one is provided), or throws if none are received before the timeout. If this happens, remove the components and notify the user.
 
@@ -82,7 +82,7 @@ try {
 
 ## Component collectors
 
-For situations where you want to collect multiple interactions, the Collector approach is better suited than awaiting singular interactions. Following on from the [select menus](/message-components/select-menus) guide, you're going to extend that example to use an <DocsLink path="InteractionCollector:Class"/> to listen for multiple <DocsLink path="StringSelectMenuInteraction:Class"/>s.
+For situations where you want to collect multiple interactions, the Collector approach is better suited than awaiting singular interactions. Following on from the [select menus](/interactive-components/select-menus) guide, you're going to extend that example to use an <DocsLink path="InteractionCollector:Class"/> to listen for multiple <DocsLink path="StringSelectMenuInteraction:Class"/>s.
 
 Begin by adding `withResponse` to the options, and then calling <DocsLink path="Message:Class#createMessageComponentCollector" type="method" /> on this instance. This method returns an InteractionCollector that will fire its <DocsLink path="InteractionCollector:Class#collect" /> event whenever an interaction passes its filter (if one is provided).
 

guide/message-components/select-menus.md → guide/interactive-components/select-menus.md

@@ -3,7 +3,7 @@
 Select menus are one of the `MessageComponent` classes, which can be sent via messages or interaction responses.
 
 ::: tip
-This page is a follow-up to the [slash commands](/slash-commands/advanced-creation.md) section and [action rows](/message-components/action-rows.md) page. Please carefully read those pages first so that you can understand the methods used here.
+This page is a follow-up to the [slash commands](/slash-commands/advanced-creation.md) section and [action rows](/interactive-components/action-rows.md) page. Please carefully read those pages first so that you can understand the methods used here.
 :::
 
 ## Building string select menus

guide/popular-topics/components-v2.md → guide/popular-topics/display-components.md

@@ -1,23 +1,29 @@
-# Components V2
+# Display Components 
 
-While you might be familiar with [embeds](/popular-topics/embeds.md) in Discord, there are more ways to style and format your messages using **Components V2 (CV2)**, a comprehensive set of layout and content components.
+While you might be familiar with [embeds](/popular-topics/embeds.md) in Discord, there are more ways to style and format your apps messages using **display components**, a comprehensive set of layout and content elements.
 
-To use the CV2 components, you need to pass in the `IsComponentsV2` message flag from the <DocsLink path="MessageFlags:Enum" /> enum when sending a message. The flag should only be added to the message's `flags` field when the message contains CV2 components, unlike the `Ephemeral` message flag that can be added when you defer an interaction response.
+To use the display components, you need to pass the `IsComponentsV2` message flag (<DocsLink path="MessageFlags:Enum" />) when sending a message. You only need to use this flag when sending a message using the display components system, not when deffering interaction responses.
 
 ::: warning
-Once a message is sent or edited with the `IsComponentsV2` message flag, the flag **cannot** be removed from that message.
+Opting into using this system by passing the `IsComponentsV2` comes with a set of caveats:
+- You **cannot** send `content`, `poll`, `embeds`, or `stickers`.
+- You **cannot** opt out of using display components when editing a message
+- You **can** opt into using display components when editing a message while explicitly setting `content`, `poll`, `embeds`, and `stickers` to null.
+- Messages can have up to **40** total components (nested components count!)
+- The amount of text across all text display components **cannot** exceed 4000 characters.
+- All attached files have to explicitly be referenced in a component (refer to the [Thumbnail](/popular-topics/display-components#thumbnail), [Media Gallery](/popular-topics/display-components#media-gallery), and [file](/popular-topics/display-components#file) sections).
 :::
 
-All components have an `id` field (which should not be confused with the `custom_id` field for interactive components), which is an optional 32-bit integer identifier for a component presented in a message. It is used to identify non-interactive components in the response from an interaction. More information about these can be found [here](https://discord.com/developers/docs/components/reference#anatomy-of-a-component).
+All components can be passed an optional, unique, `id` field holding a 32-bit integer identifier to later identify them in interaction responses. Do not confuse this with the `custom_id` field for interactive components! You can find more information about this [on the discord api documentation](https://discord.com/developers/docs/components/reference#anatomy-of-a-component). Discord will automatically populate the `id` of components that don't have the `id` specified in the payload sequentially starting from `1`. The `id` value `0` is treated as empty. The order components are automatically filled in is an implementation detail and not officially document. If you want to work with the `id` (for example to find and replace the content of a specific component lateron), you should explicitly specify it. 
 
-In the following section, we will explain all CV2 components in detail, how they work together with interactive components, and the limitations Discord has set when using CV2 components in your message.
+In the following sections, we will explain all available display component types in detail and show you some examples on how you can use them.
 
 ## Text Display
 
-A Text Display is a content component for adding markdown-formatted text to your message. This component is very similar to the `content` field of a message, but by using multiple Text Display components, you gain greater control over the layout of your message. You can use the <DocsLink path="TextDisplayBuilder:Class" /> class to easily create a Text Display component.
+Text Display components let you add markdown-formatted text to your message and directly replace the `content` field when opting to use display components. You can use the <DocsLink path="TextDisplayBuilder:Class" /> class to easily create a Text Display component.
 
-::: tip
-In addition to the available markdown in Text Display components, you can also mention users and roles. In components, mentioned users and roles _will_ receive notifications, unlike when adding mentions to embeds. You can add the `allowedMentions` field to your message payload to control who will be notified.
+::: danger
+Sending user and role mentions in text display components **will notify users and roles**! You can and should control mentions with the `allowedMentions` message option.
 :::
 
 The example below shows how you can send a Text Display component in a channel.
@@ -38,9 +44,7 @@ await channel.send({
 
 ## Section
 
-A Section is a layout component that places between one and three left-aligned Text Display components next to a right-aligned accessory (Thumbnail or Button component). At least one Text Display and the accessory are required. You can use the <DocsLink path="SectionBuilder:Class" /> class to easily create a Section component.
-
-The example below shows how you can send a Section component in a channel containing three Text Display components with a Button component on the right, next to the text.
+Sections represent text (one to three Text Display components) with an accessory. The accessory can either be an image (thumbnail) or button. If you do not want to send an accessory, use a [Text Display](/popular-topics/display-components.md#text-display) component instead. You can use the <DocsLink path="SectionBuilder:Class" /> class to easily create a Section component:
 
 ```js
 const { SectionBuilder, ButtonStyle, MessageFlags } = require('discord.js');
@@ -71,9 +75,7 @@ await channel.send({
 
 ## Thumbnail
 
-A Thumbnail is a content component that is visually similar to the `thumbnail` field inside an embed. Thumbnails are added an accessory inside a [Section](/popular-topics/components-v2.md#section) component, support alt text for accessibility, and can be marked as a spoiler. You can use the <DocsLink path="ThumbnailBuilder:Class" /> class to easily create a Thumbnail component.
-
-The example below shows how you can send a Thumbnail component as a Section component accessory in a channel.
+A Thumbnail is a display component that is visually similar to the `thumbnail` field inside an embed. Thumbnails are added as accessory inside a [Section](/popular-topics/display-components.md#section) component, support alt text for accessibility, and can be marked as a spoiler. You can use the <DocsLink path="ThumbnailBuilder:Class" /> class to easily create a Thumbnail component:
 
 ```js
 const { AttachmentBuilder, SectionBuilder, MessageFlags } = require('discord.js');
@@ -100,13 +102,11 @@ await channel.send({
 
 ![Thumbnail component preview](./images/thumbnail-preview.png)
 
-For more information how to set up custom attachments to use in your Thumbnail component URL, you can look at the guide for [attaching images in embeds](/popular-topics/embeds.md#attaching-images).
+For more information about using attachments in components refer to the guide on [attaching images in embeds](/popular-topics/embeds.md#attaching-images).
 
 ## Media Gallery
 
-A Media Gallery is a content component that can display up to 10 media attachments formatted in a structured gallery. Each attachment in the Media Gallery component can have an optional alt text (description) and can be marked as a spoiler. You can use the <DocsLink path="MediaGalleryBuilder:Class" /> and <DocsLink path="MediaGalleryItemBuilder:Class" /> classes to easily create a Media Gallery component and its items.
-
-The example below shows how you can send a Media Gallery component in a channel.
+A Media Gallery is a display component that can display a grid of up to 10 media attachments. Each media item can have an optional alt text (description) and can be marked as spoiler. You can use the <DocsLink path="MediaGalleryBuilder:Class" /> and <DocsLink path="MediaGalleryItemBuilder:Class" /> classes to easily create a Media Gallery component and its items:
 
 ```js
 const { AttachmentBuilder, MediaGalleryBuilder, MessageFlags } = require('discord.js');
@@ -135,9 +135,7 @@ await channel.send({
 
 ## File
 
-A File is a content component that can display a single uploaded file attachment within the body of the message. By using multiple File components, you can upload and display multiple files in a single message. File components cannot have alt text (description), unlike a Thumbnail or Media Gallery component, but can be marked as a spoiler. You can use the <DocsLink path="FileBuilder:Class" /> class to easily create a File component.
-
-The example below shows how you can send a File component in a channel.
+A File is a display component that can display a single uploaded file within the body of the message. By using multiple File components, you can upload and display multiple files in a single message. File components cannot have alt texts (description), unlike a Thumbnail or Media Gallery component, but can be marked as a spoiler. You can use the <DocsLink path="FileBuilder:Class" /> class to easily create a File component:
 
 ```js
 const { AttachmentBuilder, FileBuilder, MessageFlags } = require('discord.js');
@@ -186,7 +184,7 @@ await channel.send({
 
 ## Container
 
-A Container is a layout component which groups its child components inside a visually distinct rounded box with an optional accent color on the left, just like embeds. However, unlike embeds, not specifying a color will make the left side of the Container component match the background color. You can also mark the Container component as a spoiler, which blurs all content inside the container. You can use the <DocsLink path="ContainerBuilder:Class" /> class to easily create a Container component.
+A Container is a layout component which groups its child components inside a visually distinct rounded box with an optional accent color on the left, similar to the message embed look. Unlike embeds, not specifying a color will make the left side of the Container component match the background color. You can mark Container components as spoiler, which blurs all content inside the container. You can use the <DocsLink path="ContainerBuilder:Class" /> class to easily create a Container component.
 
 The example below shows how to send a Container component in a channel. It contains:
 - a Text Display component;
@@ -238,13 +236,3 @@ await channel.send({
 
 ![Container component preview](./images/container-preview.png)
 
-## Limitations
-
-There are a few limits set by the Discord API to be aware of when using Components V2 in your messages. These limits are:
-
-- To use any of the components listed under [New components](/popular-topics/components-v2.md#new-components) you must set the `IsComponentsV2` message flag in your message payload.
-- Setting the `IsComponentsV2` message flag will disable the `content` and `embeds` fields. You can use [Text Display](/popular-topics/components-v2.md#text-display) and [Container](/popular-topics/components-v2.md#container) components as replacements.
-- Setting the `IsComponentsV2` message flag will disable the `poll` and `stickers` fields, and there are no CV2 replacements for these fields you can use.
-- When upgrading a message to a CV2 flagged message by editing the message with the `IsComponentsV2` flag, all mentioned fields in the message object (`content`, `embeds`, `poll` and `stickers`) need to be set to `null`.
-- Attachments won't show by default, they must be set through the available media components ([Thumbnail](/popular-topics/components-v2.md#thumbnail), [Media Gallery](/popular-topics/components-v2.md#media-gallery) and [File](/popular-topics/components-v2.md#file)).
-- Messages allow up to 40 total components.