Feature: Implement modals (#2087)

* Implement Modals (#428)

* Socket Modal Support

* fix shareded client support

* Properly use `HasResponded` instead of `_hasResponded`

* `ModalBuilder` and `TextInputBuilder` validation.

* make orginisation more consistant.

* Rest Modals.

* Docs + add missing methods

* fix message signatures and missing abstract members

* modal changes

* um?????

* update modal docs

* update docs - again for some reason

* cleanup

* fix message signatures

* add modal commands support to interaction service

* Fix _hasResponded

* update to new unsupported standard.

* Sending modals with Interaction service.

* fix spelling in ComponentBuilder

* sending IModals when responding to interactions

* interaction service modals

* fix rest modals

* spelling and minor improvements.

* improve interaction service modal proformance

* use precompiled lambda for interaction service modals

* respect user compiled lambda choice

* changes to modals in the interaction service (more)

* support compiled lambdas in modal properties.

* modal interactions tweaks

* fix inline doc

* more modal docs

* configure responce to faild modal component

* init

* solve runtime errors

* solve build errors

* add default value parsing

* make modal info caching static

* make ModalUtils static

* add inline docs

* fix build errors

* code cleanup

* Introduce Required and Label properties as seperate attributes.

* replace internal dictionary of ModalInfo with a list

* change input building logic of modals

* update RespondWithModalAsync method

* add initial value parameter back to ModalTextInput and fix optional modal field

* add missing inline docs

* dispose the reference modal instance after building

* code cleanup on modalcommandbuilder

* Update docs/guides/int_basics/message-components/text-input.md

Co-authored-by: Jared L <48422312+lhjt@users.noreply.github.com>

* Update docs/guides/int_basics/message-components/text-input.md

Co-authored-by: Jared L <48422312+lhjt@users.noreply.github.com>

* Update docs/guides/int_basics/modals/intro.md

Co-authored-by: Jared L <48422312+lhjt@users.noreply.github.com>

* Update docs/guides/int_basics/modals/intro.md

Co-authored-by: Jared L <48422312+lhjt@users.noreply.github.com>

* Update docs/guides/int_basics/modals/intro.md

Co-authored-by: Jared L <48422312+lhjt@users.noreply.github.com>

* Update docs/guides/int_basics/modals/intro.md

Co-authored-by: Jared L <48422312+lhjt@users.noreply.github.com>

* Update docs/guides/int_basics/modals/intro.md

Co-authored-by: Jared L <48422312+lhjt@users.noreply.github.com>

* Update docs/guides/int_basics/modals/intro.md

Co-authored-by: Jared L <48422312+lhjt@users.noreply.github.com>

* Update docs/guides/int_basics/modals/intro.md

Co-authored-by: Jared L <48422312+lhjt@users.noreply.github.com>

* Update docs/guides/int_framework/intro.md

Co-authored-by: Jared L <48422312+lhjt@users.noreply.github.com>

* Update docs/guides/int_framework/intro.md

Co-authored-by: Jared L <48422312+lhjt@users.noreply.github.com>

* Update docs/guides/int_framework/samples/intro/modal.cs

Co-authored-by: Jared L <48422312+lhjt@users.noreply.github.com>

* Update src/Discord.Net.Core/Entities/Interactions/MessageComponents/IComponentInteractionData.cs

Co-authored-by: Jared L <48422312+lhjt@users.noreply.github.com>

* Update src/Discord.Net.Core/Entities/Interactions/MessageComponents/TextInputComponent.cs

Co-authored-by: Jared L <48422312+lhjt@users.noreply.github.com>

* Update src/Discord.Net.Core/Entities/Interactions/Modals/IModalInteraction.cs

Co-authored-by: Jared L <48422312+lhjt@users.noreply.github.com>

* Update src/Discord.Net.Core/Entities/Interactions/Modals/ModalBuilder.cs

Co-authored-by: Jared L <48422312+lhjt@users.noreply.github.com>

* Update src/Discord.Net.Core/Entities/Interactions/Modals/ModalBuilder.cs

Co-authored-by: Jared L <48422312+lhjt@users.noreply.github.com>

* Update src/Discord.Net.Core/Entities/Interactions/Modals/ModalBuilder.cs

Co-authored-by: Jared L <48422312+lhjt@users.noreply.github.com>

* Update src/Discord.Net.Core/Entities/Interactions/Modals/ModalBuilder.cs

Co-authored-by: Jared L <48422312+lhjt@users.noreply.github.com>

* Update src/Discord.Net.Core/Entities/Interactions/Modals/ModalBuilder.cs

Co-authored-by: Jared L <48422312+lhjt@users.noreply.github.com>

* Update src/Discord.Net.Core/Entities/Interactions/Modals/ModalBuilder.cs

Co-authored-by: Jared L <48422312+lhjt@users.noreply.github.com>

* Update src/Discord.Net.Interactions/Attributes/Commands/ModalInteractionAttribute.cs

Co-authored-by: Jared L <48422312+lhjt@users.noreply.github.com>

* Update src/Discord.Net.Interactions/Attributes/Modals/RequiredInputAttribute.cs

Co-authored-by: Jared L <48422312+lhjt@users.noreply.github.com>

* Update src/Discord.Net.Interactions/InteractionServiceConfig.cs

Co-authored-by: Jared L <48422312+lhjt@users.noreply.github.com>

* Update src/Discord.Net.WebSocket/Entities/Interaction/MessageComponents/SocketMessageComponentData.cs

Co-authored-by: Jared L <48422312+lhjt@users.noreply.github.com>

* Update src/Discord.Net.WebSocket/Entities/Interaction/Modals/SocketModalData.cs

Co-authored-by: Jared L <48422312+lhjt@users.noreply.github.com>

* update interaction service modal docs

* implements ExitOnMissingmModalField config option and adds Type field to modal info

* Add WithValue to text input builders

* Fix rare NRE on component enumeration

* Fix RequestOptions being required in some methods

* Use 'OfType' instead of 'Where'

* Remove android unsported warning

* Change publicity of properties in IInputComponeontBuilder.cs

Co-authored-by: Cenk Ergen <57065323+Cenngo@users.noreply.github.com>
Co-authored-by: Jared L <48422312+lhjt@users.noreply.github.com>

* Remove complex parameter ref

Co-authored-by: CottageDwellingCat <80918250+CottageDwellingCat@users.noreply.github.com>
Co-authored-by: Cenk Ergen <57065323+Cenngo@users.noreply.github.com>
Co-authored-by: Jared L <48422312+lhjt@users.noreply.github.com>

docs/guides/int_basics/message-components/text-input.md

@@ -0,0 +1,46 @@
+---
+uid: Guides.MessageComponents.TextInputs
+title: Text Input Components
+---
+
+# Text Input Components
+
+> [!WARNING]
+> Text input components can only be used in 
+> [modals](../modals/intro.md).
+
+Text input components are a type of MessageComponents that can only be 
+used in modals. Texts inputs can be longer (the `Paragraph`) style or 
+shorter (the `Short` style). Text inputs have a variable min and max 
+length.
+
+![A modal with short and paragraph text inputs](images/image7.png)
+
+## Creating text inputs
+Text input components can be built using the `TextInputBuilder`.
+The simplest text input can built with:
+```cs
+var tb = new TextInputBuilder()
+    .WithLabel("My Text")
+    .WithCustomId("text_input");
+```
+
+and would produce a component that looks like:
+
+![basic text input component](images/image8.png)
+
+Additional options can be specified to control the placeholder, style, 
+and min/max length of the input:
+```cs
+var tb = new TextInputBuilder()
+    .WithLabel("Labeled")
+    .WithCustomId("text_input")
+	.WithStyle(TextInputStyle.Paragraph)
+	.WithMinLength(6);
+	.WithMaxLength(42)
+	.WithRequired(true)
+	.WithPlaceholder("Consider this place held.");
+```
+
+![more advanced text input](images/image9.png)
+

docs/guides/int_basics/modals/intro.md

@@ -0,0 +1,135 @@
+---
+uid: Guides.Modals.Intro
+title: Getting Started with Modals
+---
+# Modals
+
+## Getting started with modals
+This guide will show you how to use modals and give a few examples of
+valid use cases. If your question is not covered by this guide ask in the
+[Discord.Net Discord Server](https://discord.gg/dnet).
+
+### What is a modal?
+Modals are forms bots can send when responding to interactions. Modals 
+are sent to Discord as an array of message components and converted 
+into the form layout by user's clients. Modals are required to have a
+custom id, title, and at least one component. 
+
+![Screenshot of a modal](images/image2.png)
+
+When users submit modals, your client fires the ModalSubmitted event. 
+You can get the components of the modal from the `Data.Components` property
+on the SocketModal:
+
+![Screenshot of modal data](images/image1.png) 
+
+### Using modals
+
+Lets create a simple modal with an entry field for users to
+tell us their favorite food. We can start by creating a slash
+command that will respond with the modal.
+```cs
+[SlashCommand("food", "Tell us about your favorite food!")]
+public async Task FoodPreference()
+{
+    // send a modal
+}
+```
+
+Now that we have our command set up, we need to build a modal.
+We can use the aptly named `ModalBuilder` for that:
+
+| Method          | Description                               |
+| --------------- | ----------------------------------------- |
+| `WithTitle`     | Sets the modal's title.                   |
+| `WithCustomId`  | Sets the modal's custom id.               |
+| `AddTextInput`  | Adds a `TextInputBuilder` to the modal.   |
+| `AddComponents` | Adds multiple components to the modal.    |
+| `Build`         | Builds the `ModalBuilder` into a `Modal`. |
+
+We know we need to add a text input to the modal, so let's look at that
+method's parameters.
+
+| Parameter     | Description                                |
+| ------------- | ------------------------------------------ |
+| `label`       | Sets the input's label.                    |
+| `customId`    | Sets the input's custom id.                |
+| `style`       | Sets the input's style.                    |
+| `placeholder` | Sets the input's placeholder.              |
+| `minLength`   | Sets the minimum input length.             |
+| `maxLength`   | Sets the maximum input length.             |
+| `required`    | Sets whether or not the modal is required. |
+| `value`       | Sets the input's default value.            |
+
+To make a basic text input we would only need to set the `label` and
+`customId`, but in this example we will also use the `placeholder` 
+parameter. Next we can build our modal:
+
+```cs
+var mb = new ModalBuilder()
+    .WithTitle("Fav Food")
+    .WithCustomId("food_menu")
+    .AddTextInput("What??", "food_name", placeholder:"Pizza")
+    .AddTextInput("Why??", "food_reason", TextInputStyle.Paragraph, 
+        "Kus it's so tasty");
+```
+
+Now that we have a ModalBuilder we can update our command to respond
+with the modal.
+
+```cs
+[SlashCommand("food", "Tell us about your favorite food!")]
+public async Task FoodPreference()
+{
+    var mb = new ModalBuilder()
+    .WithTitle("Fav Food")
+    .WithCustomId("food_menu")
+    .AddTextInput("What??", "food_name", placeholder:"Pizza")
+    .AddTextInput("Why??", "food_reason", TextInputStyle.Paragraph, 
+        "Kus it's so tasty");
+    
+    await Context.Interaction.RespondWithModalAsync(mb.Build());
+}
+```
+
+When we run the command, our modal should pop up:
+
+![screenshot of the above modal](images/image3.png) 
+
+### Respond to modals
+
+> [!WARNING]
+> Modals can not be sent when respoding to a modal.
+
+Once a user has submitted the modal, we need to let everyone know what
+their favorite food is. We can start by hooking a task to the client's
+`ModalSubmitted` event.
+```cs
+_client.ModalSubmitted += async modal =>
+{
+    // Get the values of components.
+    List<SocketMessageComponentData> components =
+        modal.Data.Components.ToList();
+    string food = components
+        .Where(x => x.CustomId == "food_name").First().Value;
+    string reason = components
+        .Where(x => x.CustomId == "food_reason").First().Value;
+
+    // Build the message to send.
+    string message = "hey @everyone; I just learned " + 
+        $"{modal.User.Mention}'s favorite food is " +
+        $"{food} because {reason}.";
+
+    // Specify the AllowedMentions so we don't actually ping everyone.
+    AllowedMentions mentions = new AllowedMentions();
+    mentions.AllowedTypes = AllowedMentionTypes.Users;
+
+    // Respond to the modal.
+    await modal.RespondAsync(message, allowedMentions:mentions);
+}
+```
+
+Now responding to the modal should inform everyone of our tasty 
+choices.
+
+![Response of the modal submitted event](images/image4.png)

docs/guides/int_framework/intro.md

@@ -198,6 +198,18 @@ Autocomplete commands must be parameterless methods. A valid Autocomplete comman
 
 Alternatively, you can use the [AutocompleteHandlers] to simplify this workflow.
 
+## Modals
+
+Modal commands last parameter must be an implementation of `IModal`.
+A Modal implementation would look like this:
+
+[!code-csharp[Modal Command](samples/intro/modal.cs)]
+
+> [!NOTE]
+> If you are using Modals in the interaction service it is **highly 
+> recommended** that you enable `PreCompiledLambdas` in your config
+> to prevent performance issues. 
+
 ## Interaction Context
 
 Every command module provides its commands with an execution context.

docs/guides/int_framework/samples/intro/modal.cs

@@ -0,0 +1,36 @@
+// Registers a command that will respond with a modal.
+[SlashCommand("food", "Tell us about your favorite food.")]
+public async Task Command()
+    => await Context.Interaction.RespondWithModalAsync<FoodModal>("food_menu");
+
+// Defines the modal that will be sent.
+public class FoodModal : IModal
+{
+    public string Title => "Fav Food";
+    // Strings with the ModalTextInput attribute will automatically become components.
+    [InputLabel("What??")]
+    [ModalTextInput("food_name", placeholder: "Pizza", maxLength: 20)]
+    public string Food { get; set; }
+
+    // Additional paremeters can be specified to further customize the input.
+    [InputLabel("Why??")]
+    [ModalTextInput("food_reason", TextInputStyle.Paragraph, "Kuz it's tasty", maxLength: 500)]
+    public string Reason { get; set; }
+}
+
+// Responds to the modal.
+[ModalInteraction("food_menu")]
+public async Task ModalResponce(FoodModal modal)
+{
+    // Build the message to send.
+    string message = "hey @everyone, I just learned " +
+        $"{Context.User.Mention}'s favorite food is " +
+        $"{modal.Food} because {modal.Reason}.";
+
+    // Specify the AllowedMentions so we don't actually ping everyone.
+    AllowedMentions mentions = new();
+    mentions.AllowedTypes = AllowedMentionTypes.Users;
+
+    // Respond to the modal.
+    await RespondAsync(message, allowedMentions: mentions, ephemeral: true);
+}

docs/guides/toc.yml

@@ -91,8 +91,14 @@
       topicUid: Guides.MessageComponents.Buttons
     - name: Select menus
       topicUid: Guides.MessageComponents.SelectMenus
+    - name: Text Input
+      topicUid: Guides.MessageComponents.TextInputs
     - name: Advanced Concepts
       topicUid: Guides.MessageComponents.Advanced
+- name: Modal Basics 
+  items:
+    - name: Introduction
+      topicUid: Guides.Modals.Intro
 - name: Guild Events
   items:
     - name: Introduction