feat: modals (#235)

Co-authored-by: Brooke <46959407+nimajnebec@users.noreply.github.com>

Author: brooke-ec

.changeset/four-buses-knock.md

@@ -0,0 +1,5 @@
+---
+"jellycommands": minor
+---
+
+feat: add modal component

packages/docs/astro.config.mjs

@@ -88,10 +88,23 @@ export default defineConfig({
 								},
 							],
 						},
+						{
+							label: 'Modals',
+							items: [
+								{
+									label: 'Creating Modals',
+									link: '/components/modals',
+								},
+							],
+						},
 						{
 							label: 'Props',
 							link: '/components/props',
 						},
+						{
+							label: 'Custom Ids',
+							link: '/components/custom-ids',
+						},
 						{
 							label: 'Deferring Interactions',
 							link: '/components/deferring',

packages/docs/src/assets/docs/modal-failed.png

@@ -99,73 +99,4 @@ Now when we click the button we see that it sends our "Hello World" response!
 
 ![the button works]($assets/docs/working-button.png)
 
-## Custom Id
-
-Each button needs to be given a "custom id" when you create it, so when you handle a button press you can use the correct handler. The simplest example, as we saw above, is just to use a static custom id.
-
-```js {4}
-import { button } from 'jellycommands';
-
-export default button({
-	id: 'test',
-
-	async run({ interaction }) {},
-});
-```
-
-Unlike commands, we don't need to tell Discord about the buttons before we use them. They are effectively created every time you reply to an interaction with them. This means that our custom ids can be dynamic! This can simplify some interactions since we can store some information on the id. In order to make this possible the `id` option on a button component can also be regex or a function.
-
-### Regex
-
-This regex will be used to see if we have found a match for the button interaction. It should always start with `^` and `$` to ensure it's matching the whole id rather than just a section of it, and not be global.
-
-```js
-import { button } from 'jellycommands';
-
-export default button({
-	id: /^page_\d+$/,
-
-	async run({ interaction }) {
-		console.log(interaction.customId);
-	},
-});
-```
-
-### Matcher Function
-
-This function is passed the custom id, and then should return a boolean that indicates whether a match has been found.
-
-```js
-import { button } from 'jellycommands';
-
-export default button({
-	id: (customId) => {
-		return customId.startsWith('page_');
-	},
-
-	async run({ interaction }) {
-		console.log(interaction.customId);
-	},
-});
-```
-
-### Deferring
-
-By default Discord requires you to respond to a button within 3 seconds, otherwise it marks the interaction as failed. Often it'll take longer than 3 seconds to respond, so you need to "defer" your reply. If you defer your command you need to use `followUp` instead of reply:
-
-```js {6,10} ins="followUp" del="reply"
-import { button } from 'jellycommands';
-
-export default button({
-	id: 'test',
-
-	defer: true,
-
-	async run({ interaction }) {
-		await interaction.reply('Hello World');
-		await interaction.followUp('Hello World');
-	},
-});
-```
-
-[Read more on deferring](/components/deferring).
+The "custom id" system is very powerful, allowing for dynamic matching to store arbitrary data. [Learn more about custom ids](/components/custom-ids).

packages/docs/src/assets/docs/working-modal.png

@@ -0,0 +1,73 @@
+---
+title: Custom Ids
+description: Learn how to leverage custom ids with modals and buttons.
+---
+
+Buttons and modals need to be given a "custom id" when you create them, so that the correct handler is used. The simplest way to do this is just to use a static custom id.
+
+```js {4}
+import { button } from 'jellycommands';
+
+export default button({
+	id: 'test',
+
+	async run({ interaction }) {},
+});
+```
+
+Unlike commands, we don't need to tell Discord about buttons and modals before we use them. They are effectively created every time you reply to an interaction with them. This means that our custom ids can be dynamic! This can simplify some interactions since we can store some information on the id. In order to make this possible the `id` option on a button component can also be regex or a function.
+
+### Regex
+
+This regex will be used to see if we have found a match for the button interaction. It should always start with `^` and `$` to ensure it's matching the whole id rather than just a section of it, and not be global.
+
+```js
+import { button } from 'jellycommands';
+
+export default button({
+	id: /^page_\d+$/,
+
+	async run({ interaction }) {
+		console.log(interaction.customId);
+	},
+});
+```
+
+### Matcher Function
+
+This function is passed the custom id, and then should return a boolean that indicates whether a match has been found.
+
+```js
+import { modal } from 'jellycommands';
+
+export default modal({
+	id: (customId) => {
+		return customId.startsWith('page_');
+	},
+
+	async run({ interaction }) {
+		console.log(interaction.customId);
+	},
+});
+```
+
+### Deferring
+
+By default Discord requires you to respond to an interaction within 3 seconds, otherwise it marks the interaction as failed. Often it'll take longer than 3 seconds to respond, so you need to "defer" your reply. If you defer your command you need to use `followUp` instead of reply:
+
+```js {6,10} ins="followUp" del="reply"
+import { button } from 'jellycommands';
+
+export default button({
+	id: 'test',
+
+	defer: true,
+
+	async run({ interaction }) {
+		await interaction.reply('Hello World');
+		await interaction.followUp('Hello World');
+	},
+});
+```
+
+[Read more on deferring](/components/deferring).

packages/docs/src/content/docs/components/buttons/index.mdx

@@ -0,0 +1,114 @@
+---
+title: Modals
+description: Learn about how to create modals with JellyCommands.
+---
+
+import { Tabs, TabItem } from '@astrojs/starlight/components';
+
+A modal component can be used to respond to modal submissions. You'll need to create and send these modals yourself, so let's get started by creating a simple slash command to do so:
+
+<Tabs>
+  <TabItem label="TypeScript">
+    ```ts {2-7,14-18,20-21,23-27,29-30}
+    import { command } from 'jellycommands';
+    import {
+        TextInputBuilder,
+        TextInputStyle,
+        ModalBuilder,
+        ActionRowBuilder,
+    } from 'discord.js';
+
+    export default command({
+        name: 'test-modal',
+        description: 'Shows a modal with a text input',
+
+        async run({ interaction }) {
+            // Create a text input component with the builder
+            const nameInput = new TextInputBuilder()
+                .setCustomId('nameInput')
+                .setLabel('Whats your name?')
+                .setStyle(TextInputStyle.Short);
+
+            // All components need to be in a "row"
+            const row = new ActionRowBuilder<TextInputBuilder>()).addComponents(nameInput);
+
+            // Create the actual modal
+            const modal = new ModalBuilder()
+                .setCustomId('test')
+                .setTitle('Whats Your Name?')
+                .addComponents(row);
+
+            // Send the modal
+            interaction.showModal(modal);
+        },
+    });
+    ```
+
+  </TabItem>
+
+  <TabItem label="JavaScript">
+    ```js {2-7,14-18,20-23,25-29,31-32}
+    import { command } from 'jellycommands';
+    import {
+        TextInputBuilder,
+        TextInputStyle,
+        ModalBuilder,
+        ActionRowBuilder,
+    } from 'discord.js';
+
+    export default command({
+        name: 'test-modal',
+        description: 'Shows a modal with a text input',
+
+        async run({ interaction }) {
+            // Create a text input component with the builder
+            const nameInput = new TextInputBuilder()
+                .setCustomId('nameInput')
+                .setLabel('Whats your name?')
+                .setStyle(TextInputStyle.Short);
+
+            // All components need to be in a "row"
+            const row = /** @type {ActionRowBuilder<TextInputBuilder>} */ (
+                new ActionRowBuilder()
+            ).addComponents(nameInput);
+
+            // Create the actual modal
+            const modal = new ModalBuilder()
+                .setCustomId('test')
+                .setTitle('Whats Your Name?')
+                .addComponents(row);
+
+            // Send the modal
+            interaction.showModal(modal);
+        },
+    });
+    ```
+
+  </TabItem>
+</Tabs>
+
+On running this command, your modal is opened! However, you'll notice that when you submit the modal it fails:
+
+!["Something went wrong" message on the modal created earlier]($assets/docs/modal-failed.png)
+
+This is where the JellyCommands comes in, it allows us to create a modal component that can respond to these submissions. All we need is the modal's "custom id", which you might have noticed us setting in the above example. From here we can read the value of the text input using [`interaction.fields.getTextInputValue`](https://discordjs.guide/interactions/modals.html#extracting-data-from-modal-submissions).
+
+```ts
+import { modal } from 'jellycommands';
+
+export default modal({
+	id: 'test',
+
+	async run({ interaction }) {
+		interaction.reply({
+			content: `Hello, ${interaction.fields.getTextInputValue('nameInput')}`,
+		});
+	},
+});
+```
+
+Now when we submit the modal we see that it sends our response!
+
+![the modal works]($assets/docs/working-modal.png)
+
+The "custom id" system is very powerful, allowing for dynamic matching to store arbitrary data. [Learn more about custom ids](/components/custom-ids).

packages/docs/src/content/docs/components/custom-ids.mdx

@@ -6,6 +6,7 @@ import { z } from 'zod';
 export interface ButtonOptions extends BaseComponentOptions {
 	/**
 	 * The customId of the button, or a regex/function to match against
+	 * @see https://jellycommands.dev/components/custom-ids
 	 */
 	id: string | RegExp | ((id: string) => MaybePromise<boolean>);
 

packages/docs/src/content/docs/components/modals/index.mdx

@@ -0,0 +1,42 @@
+import { type ModalOptions, modalSchema } from './options';
+import type { JellyCommands } from '../../JellyCommands';
+import type { ModalSubmitInteraction } from 'discord.js';
+import { Component, isComponent } from '../components';
+import type { MaybePromise } from '../../utils/types';
+import { MODALS_COMPONENT_ID } from './plugin';
+import { parseSchema } from '../../utils/zod';
+
+export type ModalCallback = (context: {
+	client: JellyCommands;
+	props: Props;
+	interaction: ModalSubmitInteraction;
+}) => MaybePromise<any>;
+
+/**
+ * Represents a modal.
+ * @see https://jellycommands.dev/components/modals
+ */
+export class Modal extends Component<ModalOptions> {
+	public readonly options: ModalOptions;
+
+	constructor(
+		_options: ModalOptions,
+		public readonly run: ModalCallback,
+	) {
+		super(MODALS_COMPONENT_ID, 'Modal');
+		this.options = parseSchema('modal', modalSchema, _options);
+	}
+
+	static is(item: any): item is Modal {
+		return isComponent(item) && item.id === MODALS_COMPONENT_ID;
+	}
+}
+
+/**
+ * Creates a modal.
+ * @see https://jellycommands.dev/components/modals
+ */
+export const modal = (options: ModalOptions & { run: ModalCallback }) => {
+	const { run, ...rest } = options;
+	return new Modal(rest, run);
+};

packages/jellycommands/src/components/buttons/options.ts

@@ -0,0 +1,41 @@
+import type { InteractionDeferReplyOptions } from 'discord.js';
+import type { BaseComponentOptions } from '../components';
+import type { MaybePromise } from '../../utils/types';
+import { z } from 'zod';
+
+export interface ModalOptions extends BaseComponentOptions {
+	/**
+	 * The customId of the modal, or a regex/function to match against
+	 * @see https://jellycommands.dev/components/custom-ids
+	 */
+	id: string | RegExp | ((id: string) => MaybePromise<boolean>);
+
+	/**
+	 * Should the interaction be defered?
+	 */
+	defer?: boolean | InteractionDeferReplyOptions;
+}
+
+export const modalSchema = z.object({
+	id: z.union([
+		z.string(),
+		z.instanceof(RegExp),
+		// todo test this
+		z
+			.function()
+			.args(z.string().optional())
+			.returns(z.union([z.boolean(), z.promise(z.boolean())])),
+	]),
+
+	defer: z
+		.union([
+			z.boolean().default(false),
+			z.object({
+				ephemeral: z.boolean().optional(),
+				fetchReply: z.boolean().optional(),
+			}),
+		])
+		.optional(),
+
+	disabled: z.boolean().default(false).optional(),
+});