js-discord-modularcommand 2.4.0 → 2.5.1

package/README.md

@@ -1,69 +1,286 @@
-# JS Discord ModularCommand
+# Discord.js Modular Command
 
-A module to create and manage modular commands in a simple way for Discord.js bots.
+[![npm version](https://img.shields.io/npm/v/js-discord-modularcommand.svg?style=flat-square)](https://www.npmjs.com/package/js-discord-modularcommand)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
 
-## What is it for?
+A powerful and elegant library for creating modular, feature-rich slash commands for your [Discord.js](https://discord.js.org/) bot.
 
-This library simplifies the creation and management of slash commands for [Discord.js](https://discord.js.org/). It allows you to structure your commands in a modular way, making it easier to handle logic, permissions, cooldowns, localizations, and interactive components like buttons and modals.
+`js-discord-modularcommand` simplifies command management by providing a clean, chainable structure for defining commands, handling interactions, and managing localizations. Move away from boilerplate code and focus on what truly matters: your bot's logic.
 
-## How to use it?
+## Features
 
-First, install the package in your project:
+-   **Modular by Design:** Structure each command in its own file for a clean and scalable project architecture.
+-   **Effortless Localization:** Built-in support for multiple languages for command descriptions, options, and in-command responses.
+-   **Interactive Components Made Easy:** Fluent builders for creating and managing Buttons, Modals, and Select Menus with their own handlers, all within the command's context.
+-   **Chainable Configuration:** Use a fluent, chainable API to configure every aspect of your command, from descriptions and options to permissions and cooldowns.
+-   **Simplified Handlers:** The library abstracts away the complexity of handling different interaction types. You just provide the logic.
+
+## Installation
+
+Install the package using npm or your favorite package manager:
 
 ```sh
-npm install js-discord-modularcommand@latest
+npm install js-discord-modularcommand
 ```
 
-Then, you can create your commands in a modular fashion. Here is a basic example of a `ping` command:
+## Getting Started
+
+The core of the library is the `ModularCommand` class. You create an instance of it for each command and chain methods to configure it.
+
+Here is a basic example of a `ping` command:
 
 ```javascript
-// filepath: commands/ping.js
+// filepath: /commands/ping.js
 const { ModularCommand, RegisterCommand } = require('js-discord-modularcommand');
-const { PermissionFlagsBits, Locale } = require('discord.js');
+const { Locale } = require('discord.js');
+
+// 1. Create a new command instance
+const pingCommand = new ModularCommand('ping');
 
-// Create a new command instance
-const PingCommand = new ModularCommand('ping');
+// 2. Configure the command using chainable methods
+pingCommand.setDescription('Replies with Pong!')
 
-// Set the description
-PingCommand.setDescription('Sends a ping message!');
+// Optional: Set a 5-second cooldown
+pingCommand.setCooldown(5)
+
+// Optional: Add localized descriptions for the command itself
+pingCommand.setLocalizationDescription({
+    [Locale.EnglishUS]: 'Replies with Pong!',
+    [Locale.SpanishLATAM]: '¡Responde con Pong!',
+})
+
+// Optional: Define response phrases for different languages
+pingCommand.setLocalizationPhrases({
+    [Locale.EnglishUS]: {
+        'pong_reply': 'Pong! 🏓',
+    },
+    [Locale.SpanishLATAM]: {
+        'pong_reply': '¡Pong! 🏓',
+    }
+})
 
-// Optional: Add a permission check
-PingCommand.setPermissionCheck(async ({ interaction }) => {
-    return interaction.member.permissions.has(PermissionFlagsBits.Administrator);
+// 3. Define the execution logic
+// The 'locale' object contains the phrases for the user's language
+pingCommand.setExecute(async ({ interaction, locale }) => {
+    await interaction.reply({
+        content: locale['pong_reply']
+    });
 });
 
-// Optional: Localization to use with 'locale'
-PingCommand.setLocalizationPhrases({
+// 4. Export the command for the handler
+module.exports = RegisterCommand(pingCommand);
+```
+
+## Advanced Usage: Interactive Components
+
+Easily add interactive components to your commands.
+
+### Buttons
+
+Create buttons and attach specific logic to each one.
+
+```javascript
+// filepath: /commands/vote.js
+const { ModularCommand, RegisterCommand } = require('js-discord-modularcommand');
+const { ButtonStyle, Locale, MessageFlags } = require('discord.js');
+const { ActionRowBuilder } = require('@discordjs/builders');
+
+const voteCommand = new ModularCommand('votecommand');
+
+voteCommand.setDescription('Starts a simple poll.');
+
+voteCommand.setLocalizationPhrases({
     [Locale.EnglishUS]: {
-        response: 'Replies with Pong!',
+        'poll_question': 'What is your favorite color?',
+        'votecommand.yes': 'Green',
+        'votecommand.no': 'Blue',
+        'reply.yes': 'You voted for Green!',
+        'reply.no': 'You voted for Blue!',
     },
     [Locale.SpanishLATAM]: {
-        response: 'Responde con Pong!',
+        'poll_question': '¿Cuál es tu color favorito?',
+        'votecommand.yes': 'Verde',
+        'votecommand.no': 'Azul',
+        'reply.yes': '¡Has votado por el Verde!',
+        'reply.no': '¡Has votado por el Azul!',
     }
 });
 
-// Optional: Set a cooldown (in seconds) by default is 3 seconds
-PingCommand.setCooldown(5);
+// Create and handle the "Yes" button
+const yesButton = voteCommand.addButton('yes', async ({ interaction, locale }) => {
+    await interaction.reply({
+        content: locale['reply.yes'],
+        flags: MessageFlags.Ephemeral
+    });
+});
+
+// Create and handle the "No" button
+const noButton = voteCommand.addButton('no', async ({ interaction, locale }) => {
+    await interaction.reply({
+        content: locale['reply.no'],
+        flags: MessageFlags.Ephemeral
+    });
+});
 
-// Set the command's description
-PingCommand.setDescription('Replies with Pong!');
+// Customize the underlying discord.js button
+yesButton.getButton().setStyle(ButtonStyle.Success);
+noButton.getButton().setStyle(ButtonStyle.Primary);
 
-// Optional: Add more localization descriptions for the command itself
-PingCommand.setLocalizationDescription({
-    [Locale.EnglishUS]: 'Replies with Pong!',
-    [Locale.SpanishLATAM]: 'Responde con Pong!',
+// Main command execution: sends the message with the buttons
+voteCommand.setExecute(async ({ interaction, locale }) => {
+    const row = new ActionRowBuilder();
+
+    row.addComponents(
+        yesButton.build(locale), // .build(locale) applies the correct localization
+        noButton.build(locale)
+    );
+
+    await interaction.reply({
+        content: locale['poll_question'],
+        components: [row]
+    });
+});
+
+module.exports = RegisterCommand(voteCommand);
+```
+
+### Select Menus
+
+Build and handle string select menus seamlessly.
+
+```javascript
+// filepath: /commands/starter.js
+const { ModularCommand, RegisterCommand } = require('js-discord-modularcommand');
+const { ActionRowBuilder } = require('@discordjs/builders');
+const { Locale, MessageFlags } = require('discord.js');
+
+const starterCommand = new ModularCommand('starter');
+
+starterCommand.setDescription('Choose your starter Pokémon.')
+    
+starterCommand.setLocalizationPhrases({
+    [Locale.EnglishUS]: {
+        'select_prompt': 'Please select your starter:',
+        'menuselection.placeholder': 'Make a selection!',
+        'menuselection.bulbasaur.label': 'Bulbasaur',
+        'menuselection.bulbasaur.description': 'The Seed Pokémon.',
+        'menuselection.charmander.label': 'Charmander',
+        'menuselection.charmander.description': 'The Lizard Pokémon.',
+        'menuselection.squirtle.label': 'Squirtle',
+        'menuselection.squirtle.description': 'The Tiny Turtle Pokémon.',
+        'response': 'You chose {selection}!',
+    },
+    [Locale.SpanishLATAM]: {
+        'select_prompt': 'Por favor, elige tu inicial:',
+        'menuselection.placeholder': '¡Haz una selección!',
+        'menuselection.bulbasaur.label': 'Bulbasaur',
+        'menuselection.bulbasaur.description': 'El Pokémon Semilla.',
+        'menuselection.charmander.label': 'Charmander',
+        'menuselection.charmander.description': 'El Pokémon Lagartija.',
+        'menuselection.squirtle.label': 'Squirtle',
+        'menuselection.squirtle.description': 'El Pokémon Agua.',
+        'response': '¡Elegiste a {selection}!',
+    }
+});
+
+const starterMenu = starterCommand.addSelectMenu('menuselection');
+
+// Value must match the key in localization phrases
+starterMenu.addOption('bulbasaur')
+starterMenu.addOption('charmander')
+starterMenu.addOption('squirtle')
+
+starterMenu.setExecute(async ({ interaction, selected, locale }) => {
+    // 'selected' directly gives you the value of the chosen option
+    const selectionLabel = locale[`menuselection.${selected}.label`];
+    await interaction.update({
+        content: locale['response'].replace('{selection}', selectionLabel),
+        components: [] // Remove menu after selection
+    });
 });
 
-// Set the executor function
-PingCommand.setExecute(async ({ interaction, locale }) => {
-    await interaction.reply(locale['response']);
+starterCommand.setExecute(async ({ interaction, locale }) => {
+    const row = new ActionRowBuilder()
+    row.addComponents(starterMenu.build(locale));
+
+    await interaction.reply({
+        content: locale['select_prompt'],
+        components: [row],
+        flags: MessageFlags.Ephemeral
+    });
 });
 
-module.exports = RegisterCommand(PingCommand)
+module.exports = RegisterCommand(starterCommand);
 ```
 
-In your main file, you can load the commands and register their executors with your Discord client.
+### Modals (Pop-up Forms)
+
+Display pop-up forms to collect detailed user input.
+
+```javascript
+// filepath: /commands/feedback.js
+const { ModularCommand, RegisterCommand } = require('js-discord-modularcommand');
+const { TextInputStyle, Locale, MessageFlags } = require('discord.js');
+
+const feedbackCommand = new ModularCommand('feedback');
+
+feedbackCommand.setDescription('Submit feedback about the bot.')
+
+feedbackCommand.setLocalizationPhrases({
+    [Locale.EnglishUS]: {
+        'form.title': 'Feedback Form',
+        'form.subject.label': 'Subject',
+        'form.subject.placeholder': 'e.g., Feature Request',
+        'form.message.label': 'Message',
+        'form.message.placeholder': 'Your detailed feedback here...',
+        'success_reply': 'Thank you for your feedback!',
+    },
+    [Locale.SpanishLATAM]: {
+        'form.title': 'Formulario de Comentarios',
+        'form.subject.label': 'Asunto',
+        'form.subject.placeholder': 'Ej: Solicitud de función',
+        'form.message.label': 'Mensaje',
+        'form.message.placeholder': 'Tus comentarios detallados aquí...',
+        'success_reply': '¡Gracias por tus comentarios!',
+    }
+});
+
+const feedbackModal = feedbackCommand.addModal('form');
+
+// Define text inputs
+const subjectInput = feedbackModal.newTextInput('subject')
+    .setStyle(TextInputStyle.Short)
+    .setRequired(true)
+    .data
+    .custom_id;
+
+const messageInput = feedbackModal.newTextInput('message')
+    .setStyle(TextInputStyle.Paragraph)
+    .setRequired(true)
+    .data
+    .custom_id;
+
+// This function runs when the user submits the modal
+feedbackModal.setExecute(async ({ interaction, args, locale }) => {
+    const subject = args[subjectInput];
+    const message = args[messageInput];
+
+    // Process the data
+    console.log(`New Feedback: ${subject} - ${message}`);
+    await interaction.reply({
+        content: locale['success_reply'],
+        flags: MessageFlags.Ephemeral
+    });
+});
+
+// This function runs when the /feedback command is used, showing the modal
+feedbackCommand.setExecute(async ({ interaction, locale }) => {
+    await interaction.showModal(feedbackModal.build(locale));
+});
+
+module.exports = RegisterCommand(feedbackCommand);
+```
 
 ## License
 
-This project is under the MIT License. See the [LICENSE](LICENSE) file
+This project is licensed under the MIT License. See the `LICENSE` file for details.

package/dist/interaction.d.ts

@@ -23,7 +23,7 @@ type InteractionHandler = (args: InteractionHandlerArgs) => Promise<boolean | un
  * @description Creates a modular command handler function for the Discord client.
  * @param {ClientWithCommands} client The Discord client instance with a commands collection.
  * @param {InteractionHandler} customHandler A custom function to handle interactions before the default logic.
- * @returns {(interaction: BaseInteraction) = Promise<void>} The main interaction handler function.
+ * @returns {(interaction: BaseInteraction) => Promise<void>} The main interaction handler function.
  */
 export default function ModularCommandHandler(client: ClientWithCommands, customHandler: InteractionHandler): (interaction: BaseInteraction) => Promise<void>;
 export {};

package/dist/interaction.js

@@ -15,7 +15,7 @@ const locales_1 = require("./locales");
  * @description Creates a modular command handler function for the Discord client.
  * @param {ClientWithCommands} client The Discord client instance with a commands collection.
  * @param {InteractionHandler} customHandler A custom function to handle interactions before the default logic.
- * @returns {(interaction: BaseInteraction) = Promise<void>} The main interaction handler function.
+ * @returns {(interaction: BaseInteraction) => Promise<void>} The main interaction handler function.
  */
 function ModularCommandHandler(client, customHandler) {
     if (!client.commands) {
@@ -41,12 +41,15 @@ function ModularCommandHandler(client, customHandler) {
             commandName = interaction.customId.split('_')[0];
         }
         else {
-            const errorMessage = locales_1.LOCALE_ERROR[interaction.locale];
+            const errorMessage = locales_1.LOCALE_ERROR[interaction.locale] || 'An unexpected error occurred.';
             if (interaction.replied || interaction.deferred) {
                 await interaction.followUp({ content: errorMessage, flags: discord_js_1.MessageFlags.Ephemeral });
             }
             else {
-                await interaction.reply({ content: errorMessage, flags: discord_js_1.MessageFlags.Ephemeral });
+                // Type guard to ensure reply method exists
+                if ('reply' in interaction) {
+                    await interaction.reply({ content: errorMessage, flags: discord_js_1.MessageFlags.Ephemeral });
+                }
             }
             console.error(`Interaction does not have a commandName or customId: ${interaction.id}`);
             return;
@@ -63,6 +66,9 @@ function ModularCommandHandler(client, customHandler) {
             else if (interaction.isButton() && command.buttonExecute) {
                 await command.buttonExecute(interaction);
             }
+            else if (interaction.isStringSelectMenu() && command.selectMenuExecute) {
+                await command.selectMenuExecute(interaction);
+            }
             else if (interaction.isMessageComponent() && command.componentExecute) {
                 await command.componentExecute(interaction);
             }
@@ -71,12 +77,14 @@ function ModularCommandHandler(client, customHandler) {
             }
         }
         catch (error) {
-            const errorMessage = locales_1.LOCALE_ERROR[interaction.locale];
+            const errorMessage = locales_1.LOCALE_ERROR[interaction.locale] || 'An unexpected error occurred.';
             if (interaction.replied || interaction.deferred) {
                 await interaction.followUp({ content: errorMessage, flags: discord_js_1.MessageFlags.Ephemeral });
             }
             else {
-                await interaction.reply({ content: errorMessage, flags: discord_js_1.MessageFlags.Ephemeral });
+                if ('reply' in interaction) {
+                    await interaction.reply({ content: errorMessage, flags: discord_js_1.MessageFlags.Ephemeral });
+                }
             }
             console.error(`Error handling interaction: ${interaction.id}`, error);
         }

package/dist/modularcommand.d.ts

@@ -6,7 +6,8 @@
 import { LocalizationMap } from 'discord.js';
 import ModularModal from './modularmodal.js';
 import ModularButton from './modularbutton.js';
-import { ButtonExecuteFunction, CommandExecuteFunction, CommandOption, ComponentExecuteFunction, ModalExecuteFunction, PermissionCheckFunction } from './types.js';
+import ModularSelectMenu from './modularselectmenu.js';
+import { ButtonExecuteFunction, CommandExecuteFunction, CommandOption, ComponentExecuteFunction, ModalExecuteFunction, PermissionCheckFunction, SelectMenuExecuteFunction } from './types.js';
 /**
  * @description Represents a modular command that can be registered with Discord.js.
  * It allows for dynamic command creation and execution in a simple way.
@@ -47,7 +48,7 @@ export default class ModularCommand {
     /** (Optional) The function to handle modal submissions. */
     modalExecute?: ModalExecuteFunction;
     /** A record of handlers for specific component custom IDs. */
-    customIdHandlers: Record<string, CommandExecuteFunction | ButtonExecuteFunction | ModalExecuteFunction>;
+    customIdHandlers: Record<string, CommandExecuteFunction | ButtonExecuteFunction | ModalExecuteFunction | SelectMenuExecuteFunction>;
     /** The command's cooldown time in seconds. */
     cooldown: number;
     /** Whether the command is marked as Not Safe For Work (NSFW). */
@@ -64,6 +65,10 @@ export default class ModularCommand {
     buttons: Map<string, ModularButton>;
     /** An array containing all ModularButton instances for easy access. */
     buttonsArray: ModularButton[];
+    /** A map of select menus associated with this command, keyed by the select menu's custom ID. */
+    selectMenus: Map<string, ModularSelectMenu>;
+    /** An array containing all ModularSelectMenu instances for easy access. */
+    selectMenusArray: ModularSelectMenu[];
     constructor(name: string);
     /**
      * Sets the description of the command.
@@ -92,7 +97,6 @@ export default class ModularCommand {
     setLocalizationOptions(localizations: LocalizationMap): this;
     /**
      * Sets the localization phrases for the command.
-     * Accepts a partial record, so not all locales need to be provided.
      * @param {LocalizationMap} localizationPhrases The localization phrases.
      * @returns {ModularCommand} The command instance for chaining.
      */
@@ -136,10 +140,10 @@ export default class ModularCommand {
     /**
      * Adds a custom ID handler for the command.
      * @param {string} customId The custom ID to match.
-     * @param {CommandExecuteFunction | ButtonExecuteFunction | ModalExecuteFunction} handlerFunction The function to execute when the custom ID matches.
+     * @param {CommandExecuteFunction | ButtonExecuteFunction | ModalExecuteFunction | SelectMenuExecuteFunction} handlerFunction The function to execute when the custom ID matches.
      * @returns {ModularCommand} The command instance for chaining.
      */
-    addCustomIDHandler(customId: string, handlerFunction: CommandExecuteFunction | ButtonExecuteFunction | ModalExecuteFunction): this;
+    addCustomIDHandler(customId: string, handlerFunction: CommandExecuteFunction | ButtonExecuteFunction | ModalExecuteFunction | SelectMenuExecuteFunction): this;
     /**
      * Creates a new modal for the command.
      * @param {string} modalId The ID for the modal.
@@ -153,4 +157,10 @@ export default class ModularCommand {
      * @return {ModularButton} The created button instance.
      */
     addButton(customId: string, execute: ButtonExecuteFunction): ModularButton;
+    /**
+     * Creates a new select menu for the command.
+     * @param {string} selectMenuId The ID for the select menu.
+     * @returns {ModularSelectMenu} The created select menu instance.
+     */
+    addSelectMenu(selectMenuId: string): ModularSelectMenu;
 }

package/dist/modularcommand.js

@@ -14,6 +14,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const discord_js_1 = require("discord.js");
 const modularmodal_js_1 = __importDefault(require("./modularmodal.js"));
 const modularbutton_js_1 = __importDefault(require("./modularbutton.js"));
+const modularselectmenu_js_1 = __importDefault(require("./modularselectmenu.js")); // <- ADD THIS
 // =================================================================================================
 // Class: ModularCommand
 // =================================================================================================
@@ -50,7 +51,9 @@ class ModularCommand {
         this.cooldown = 3;
         this.modals = new Map();
         this.buttons = new Map();
+        this.selectMenus = new Map(); // <- ADD THIS
         this.buttonsArray = [];
+        this.selectMenusArray = []; // <- ADD THIS
         this.isNSFW = false;
     }
     /**
@@ -98,7 +101,6 @@ class ModularCommand {
     }
     /**
      * Sets the localization phrases for the command.
-     * Accepts a partial record, so not all locales need to be provided.
      * @param {LocalizationMap} localizationPhrases The localization phrases.
      * @returns {ModularCommand} The command instance for chaining.
      */
@@ -166,7 +168,7 @@ class ModularCommand {
     /**
      * Adds a custom ID handler for the command.
      * @param {string} customId The custom ID to match.
-     * @param {CommandExecuteFunction | ButtonExecuteFunction | ModalExecuteFunction} handlerFunction The function to execute when the custom ID matches.
+     * @param {CommandExecuteFunction | ButtonExecuteFunction | ModalExecuteFunction | SelectMenuExecuteFunction} handlerFunction The function to execute when the custom ID matches.
      * @returns {ModularCommand} The command instance for chaining.
      */
     addCustomIDHandler(customId, handlerFunction) {
@@ -196,5 +198,16 @@ class ModularCommand {
         this.buttonsArray.push(button);
         return button;
     }
+    /**
+     * Creates a new select menu for the command.
+     * @param {string} selectMenuId The ID for the select menu.
+     * @returns {ModularSelectMenu} The created select menu instance.
+     */
+    addSelectMenu(selectMenuId) {
+        const menu = new modularselectmenu_js_1.default(selectMenuId, this);
+        this.selectMenus.set(selectMenuId, menu);
+        this.selectMenusArray.push(menu);
+        return menu;
+    }
 }
 exports.default = ModularCommand;

package/dist/modularselectmenu.d.ts

@@ -0,0 +1,61 @@
+/**
+ * @file Contains the structure and logic for creating modular select menus.
+ * @author vicentefelipechile
+ * @license MIT
+ */
+import { StringSelectMenuBuilder, StringSelectMenuOptionBuilder } from "discord.js";
+import { LocaleKey, SelectMenuExecuteFunction } from "./types";
+import ModularCommand from "./modularcommand";
+/**
+ * @class ModularSelectMenu
+ * @description Represents a modular select menu that can be dynamically created and managed.
+ */
+export default class ModularSelectMenu {
+    /** The Discord.js StringSelectMenuBuilder instance. */
+    selectMenuObject: StringSelectMenuBuilder;
+    /** The unique custom ID for the select menu, formatted as `${command.name}_${selectMenuId}`. */
+    customId: string;
+    /** The base ID for the select menu, used for localization. */
+    selectMenuId: string;
+    /** A map to store the option components of the select menu. */
+    options: Map<string, StringSelectMenuOptionBuilder>;
+    /** The command instance to which this select menu belongs. */
+    command: ModularCommand;
+    /** The function to execute when the select menu is interacted with. */
+    execute: SelectMenuExecuteFunction;
+    /**
+     * @description Creates a new ModularSelectMenu instance.
+     * @param {string} selectMenuId The base ID for the select menu.
+     * @param {ModularCommand} command The command that this select menu is associated with.
+     */
+    constructor(selectMenuId: string, command: ModularCommand);
+    /**
+     * @description Retrieves the underlying StringSelectMenuBuilder instance.
+     * @returns {StringSelectMenuBuilder} The StringSelectMenuBuilder instance.
+     */
+    getSelectMenu(): StringSelectMenuBuilder;
+    /**
+     * @description Retrieves the custom ID of the select menu.
+     * @returns {string} The custom ID of the select menu.
+     */
+    getCustomId(): string;
+    /**
+     * @description Sets the execution function for the select menu's submission event.
+     * @param {SelectMenuExecuteFunction} executeFunction The function to run when the select menu is used.
+     * @returns {this} The current ModularSelectMenu instance for method chaining.
+     */
+    setExecute(executeFunction: SelectMenuExecuteFunction): this;
+    /**
+     * @description Creates a new option for the select menu.
+     * The label and description should be set in your localization files.
+     * @param {string} value The unique value for this option.
+     * @returns {StringSelectMenuOptionBuilder} The created option instance for further configuration (e.g., `setDefault`).
+     */
+    addOption(value: string): StringSelectMenuOptionBuilder;
+    /**
+     * @description Builds the final select menu object, applying localized placeholder, labels, and descriptions.
+     * @param {LocaleKey} locale The localization object containing translated texts.
+     * @returns {StringSelectMenuBuilder} The fully constructed select menu object ready to be sent to a user.
+     */
+    build(locale: LocaleKey): StringSelectMenuBuilder;
+}

package/dist/modularselectmenu.js

@@ -0,0 +1,89 @@
+"use strict";
+/**
+ * @file Contains the structure and logic for creating modular select menus.
+ * @author vicentefelipechile
+ * @license MIT
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const discord_js_1 = require("discord.js");
+/**
+ * @class ModularSelectMenu
+ * @description Represents a modular select menu that can be dynamically created and managed.
+ */
+class ModularSelectMenu {
+    /**
+     * @description Creates a new ModularSelectMenu instance.
+     * @param {string} selectMenuId The base ID for the select menu.
+     * @param {ModularCommand} command The command that this select menu is associated with.
+     */
+    constructor(selectMenuId, command) {
+        /** The function to execute when the select menu is interacted with. */
+        this.execute = async () => { };
+        this.selectMenuId = selectMenuId;
+        this.command = command;
+        this.customId = `${command.name}_${selectMenuId}`;
+        this.selectMenuObject = new discord_js_1.StringSelectMenuBuilder().setCustomId(this.customId);
+        this.options = new Map();
+    }
+    /**
+     * @description Retrieves the underlying StringSelectMenuBuilder instance.
+     * @returns {StringSelectMenuBuilder} The StringSelectMenuBuilder instance.
+     */
+    getSelectMenu() {
+        return this.selectMenuObject;
+    }
+    /**
+     * @description Retrieves the custom ID of the select menu.
+     * @returns {string} The custom ID of the select menu.
+     */
+    getCustomId() {
+        return this.customId;
+    }
+    /**
+     * @description Sets the execution function for the select menu's submission event.
+     * @param {SelectMenuExecuteFunction} executeFunction The function to run when the select menu is used.
+     * @returns {this} The current ModularSelectMenu instance for method chaining.
+     */
+    setExecute(executeFunction) {
+        this.execute = executeFunction;
+        return this;
+    }
+    /**
+     * @description Creates a new option for the select menu.
+     * The label and description should be set in your localization files.
+     * @param {string} value The unique value for this option.
+     * @returns {StringSelectMenuOptionBuilder} The created option instance for further configuration (e.g., `setDefault`).
+     */
+    addOption(value) {
+        const option = new discord_js_1.StringSelectMenuOptionBuilder().setValue(value);
+        this.options.set(value, option);
+        return option;
+    }
+    /**
+     * @description Builds the final select menu object, applying localized placeholder, labels, and descriptions.
+     * @param {LocaleKey} locale The localization object containing translated texts.
+     * @returns {StringSelectMenuBuilder} The fully constructed select menu object ready to be sent to a user.
+     */
+    build(locale) {
+        const placeholderKey = `${this.command.name}.${this.selectMenuId}.placeholder`;
+        if (locale[placeholderKey]) {
+            this.selectMenuObject.setPlaceholder(locale[placeholderKey]);
+        }
+        const builtOptions = [];
+        this.options.forEach((optionBuilder, value) => {
+            const labelKey = `${this.command.name}.${this.selectMenuId}.${value}.label`;
+            const descriptionKey = `${this.command.name}.${this.selectMenuId}.${value}.description`;
+            // Set label from locale, fallback to the value if not found
+            optionBuilder.setLabel(locale[labelKey] || value);
+            if (locale[descriptionKey]) {
+                optionBuilder.setDescription(locale[descriptionKey]);
+            }
+            builtOptions.push(optionBuilder);
+        });
+        if (builtOptions.length > 0) {
+            this.selectMenuObject.setOptions(builtOptions);
+        }
+        return this.selectMenuObject;
+    }
+}
+exports.default = ModularSelectMenu;

package/dist/registercommand.d.ts

@@ -8,7 +8,7 @@ import ModularCommand from "./modularcommand";
 /**
  * @description Registers an array of modular commands, building their final `CommandData` objects.
  * This function processes the command definitions, sets up command builders, and assigns the execution logic.
- * @param {ModularCommand[]} commands An array of ModularCommand instances.
+ * @param {ModularCommand[] | ModularCommand} commands An array of or a single ModularCommand instance.
  * @returns {CommandData[]} An array of command data objects ready for the Discord.js client.
  */
 export default function RegisterCommand(commands: ModularCommand[] | ModularCommand): CommandData[];

package/dist/registercommand.js

@@ -181,13 +181,35 @@ function createButtonExecutor(command) {
         });
     };
 }
+/**
+ * @description Creates the execution function for select menu interactions.
+ * @param {ModularCommand} command The command to create the executor for.
+ * @returns {Function|undefined} The async function or undefined if not needed.
+ */
+function createSelectMenuExecutor(command) {
+    if (command.selectMenus.size === 0)
+        return undefined;
+    return async (interaction) => {
+        const menuObject = command.selectMenus.get(interaction.customId.split('_')[1]);
+        if (!menuObject)
+            return;
+        // The user's selected option value is abstracted into `selected`.
+        await menuObject.execute({
+            interaction,
+            command,
+            locale: getCommandLocale(command, interaction),
+            message: interaction.message,
+            selected: interaction.values[0],
+        });
+    };
+}
 // =================================================================================================
 // Main Registration Function
 // =================================================================================================
 /**
  * @description Registers an array of modular commands, building their final `CommandData` objects.
  * This function processes the command definitions, sets up command builders, and assigns the execution logic.
- * @param {ModularCommand[]} commands An array of ModularCommand instances.
+ * @param {ModularCommand[] | ModularCommand} commands An array of or a single ModularCommand instance.
  * @returns {CommandData[]} An array of command data objects ready for the Discord.js client.
  */
 function RegisterCommand(commands) {
@@ -249,6 +271,7 @@ function RegisterCommand(commands) {
             componentExecute: createComponentExecutor(command),
             modalExecute: createModalExecutor(command),
             buttonExecute: createButtonExecutor(command),
+            selectMenuExecute: createSelectMenuExecutor(command),
             cooldown: command.cooldown,
         };
     });

package/dist/types.d.ts

@@ -3,7 +3,7 @@
  * @author vicentefelipechile
  * @license MIT
  */
-import { ApplicationCommandOptionType as OptionType, APIApplicationCommandOptionChoice, ChatInputCommandInteraction, MessageComponentInteraction, ModalSubmitInteraction, CommandInteraction, ButtonInteraction, SlashCommandBuilder, PartialDMChannel, ThreadChannel, GuildChannel, Collection, Message, Locale, Client, User } from "discord.js";
+import { ApplicationCommandOptionType as OptionType, APIApplicationCommandOptionChoice, ChatInputCommandInteraction, MessageComponentInteraction, ModalSubmitInteraction, StringSelectMenuInteraction, CommandInteraction, ButtonInteraction, SlashCommandBuilder, PartialDMChannel, ThreadChannel, GuildChannel, Collection, Message, Locale, Client, User } from "discord.js";
 import ModularCommand from "./modularcommand";
 /**
  * @interface CommandOption
@@ -36,6 +36,8 @@ export interface CommandData {
     modalExecute?: (interaction: ModalSubmitInteraction) => Promise<void>;
     /** (Optional) Function to handle button interactions. */
     buttonExecute?: (interaction: ButtonInteraction) => Promise<void>;
+    /** (Optional) Function to handle string select menu interactions. */
+    selectMenuExecute?: (interaction: StringSelectMenuInteraction) => Promise<void>;
     /** The command's cooldown time in seconds. */
     cooldown: number;
 }
@@ -103,6 +105,16 @@ export type ModalExecuteParams = BaseExecuteParams<ModalSubmitInteraction> & {
     /** An object with the values of the fields submitted in the modal. */
     args: Record<string, string>;
 };
+/**
+ * @type SelectMenuExecuteParams
+ * @description Parameters for the execution function of a select menu.
+ */
+export type SelectMenuExecuteParams = BaseExecuteParams<StringSelectMenuInteraction> & {
+    /** The message to which the select menu is attached. */
+    message: Message;
+    /** The value selected by the user. */
+    selected: string;
+};
 /**
  * @type CommandExecuteFunction
  * @description Defines the signature for the main execution function of a command.
@@ -123,6 +135,11 @@ export type ButtonExecuteFunction = (params: ButtonExecuteParams) => Promise<voi
  * @description Defines the signature for the function that handles a modal submission.
  */
 export type ModalExecuteFunction = (params: ModalExecuteParams) => Promise<void>;
+/**
+ * @type SelectMenuExecuteFunction
+ * @description Defines the signature for the function that handles select menu interactions.
+ */
+export type SelectMenuExecuteFunction = (params: SelectMenuExecuteParams) => Promise<void>;
 /**
  * @type PermissionCheckFunction
  * @description Defines the signature for a function that checks a user's permissions to execute a command.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "js-discord-modularcommand",
-  "version": "2.4.0",
+  "version": "2.5.1",
   "description": "",
   "keywords": [
     "discord",