district.js 0.5.0 → 0.6.0

package/README.md

@@ -110,6 +110,34 @@ client.on("interactionCreate", (i) => {
 });
 ```
 
+## Select menus & modals
+
+```js
+import { ActionRowBuilder, StringSelectMenuBuilder, ButtonBuilder, ModalBuilder, TextInputBuilder } from "district.js";
+
+// Dropdown
+const menu = new ActionRowBuilder().addComponents(
+  new StringSelectMenuBuilder().setCustomId("role").setPlaceholder("Pick a role")
+    .addOptions({ label: "Dev", value: "dev" }, { label: "Design", value: "design" }),
+);
+await channel.send({ content: "Choose:", components: [menu] });
+
+// Modal (opens instantly on click; only the submit is delivered to the bot)
+const modal = new ModalBuilder().setCustomId("feedback").setTitle("Feedback")
+  .addComponents(new TextInputBuilder().setCustomId("msg").setLabel("Your message").setStyle("paragraph"));
+const row = new ActionRowBuilder().addComponents(
+  new ButtonBuilder().setLabel("Give feedback").setStyle("primary").setModal(modal),
+);
+await channel.send({ components: [row] });
+
+client.on("interactionCreate", (i) => {
+  if (i.isSelectMenu() && i.customId === "role") i.reply(`You picked ${i.values[0]}`);
+  if (i.isModalSubmit() && i.customId === "feedback") i.reply(`Thanks: ${i.field("msg")}`);
+});
+```
+
+> Because District delivers interactions asynchronously, modals are attached to a button and shown **instantly, client-side**; only the submitted values are sent back to your bot.
+
 ## Slash commands
 
 Register the command in the portal (name + handler URL), then:

package/dist/components.d.ts

@@ -1,4 +1,17 @@
 export type ButtonStyle = "primary" | "secondary" | "success" | "danger" | "link";
+export interface TextInputData {
+    custom_id: string;
+    label: string;
+    style: "short" | "paragraph";
+    placeholder?: string;
+    required?: boolean;
+    max_length?: number;
+}
+export interface ModalData {
+    custom_id: string;
+    title: string;
+    fields: TextInputData[];
+}
 export interface ButtonData {
     type: "button";
     style: ButtonStyle;
@@ -7,10 +20,27 @@ export interface ButtonData {
     url?: string;
     emoji?: string;
     disabled?: boolean;
+    /** A modal shown (instantly, client-side) when the button is clicked. */
+    modal?: ModalData;
+}
+export interface SelectOption {
+    label: string;
+    value: string;
+    description?: string;
+}
+export interface SelectData {
+    type: "select";
+    custom_id: string;
+    options: SelectOption[];
+    placeholder?: string;
+    min_values?: number;
+    max_values?: number;
+    disabled?: boolean;
 }
+export type ComponentData = ButtonData | SelectData;
 export interface ActionRowData {
     type: "action_row";
-    components: ButtonData[];
+    components: ComponentData[];
 }
 export declare class ButtonBuilder {
     data: Partial<ButtonData>;
@@ -22,12 +52,43 @@ export declare class ButtonBuilder {
     setUrl(url: string): this;
     setEmoji(emoji: string): this;
     setDisabled(disabled?: boolean): this;
+    /** Attach a modal — clicking the button opens it instantly; submit fires a
+     *  modal_submit interaction with the field values. */
+    setModal(modal: ModalBuilder | ModalData): this;
     toJSON(): ButtonData;
 }
+export declare class StringSelectMenuBuilder {
+    data: SelectData;
+    setCustomId(id: string): this;
+    setPlaceholder(text: string): this;
+    setMinValues(n: number): this;
+    setMaxValues(n: number): this;
+    setDisabled(disabled?: boolean): this;
+    addOptions(...options: SelectOption[]): this;
+    toJSON(): SelectData;
+}
+export declare class TextInputBuilder {
+    data: Partial<TextInputData>;
+    setCustomId(id: string): this;
+    setLabel(label: string): this;
+    setStyle(style: "short" | "paragraph"): this;
+    setPlaceholder(text: string): this;
+    setRequired(required?: boolean): this;
+    setMaxLength(n: number): this;
+    toJSON(): TextInputData;
+}
+export declare class ModalBuilder {
+    data: ModalData;
+    setCustomId(id: string): this;
+    setTitle(title: string): this;
+    /** Add text inputs to the modal (up to 5). */
+    addComponents(...inputs: (TextInputBuilder | TextInputData)[]): this;
+    toJSON(): ModalData;
+}
 export declare class ActionRowBuilder {
     data: ActionRowData;
-    /** Add up to 5 buttons to this row. */
-    addComponents(...buttons: (ButtonBuilder | ButtonData)[]): this;
+    /** Add up to 5 buttons, or a single select menu. */
+    addComponents(...components: (ButtonBuilder | StringSelectMenuBuilder | ComponentData)[]): this;
     toJSON(): ActionRowData;
 }
 export type ComponentResolvable = ActionRowBuilder | ActionRowData;

package/dist/components.js

@@ -12,14 +12,58 @@ export class ButtonBuilder {
     setUrl(url) { this.data.url = url; this.data.style = "link"; return this; }
     setEmoji(emoji) { this.data.emoji = emoji; return this; }
     setDisabled(disabled = true) { this.data.disabled = disabled; return this; }
+    /** Attach a modal — clicking the button opens it instantly; submit fires a
+     *  modal_submit interaction with the field values. */
+    setModal(modal) {
+        this.data.modal = modal instanceof ModalBuilder ? modal.toJSON() : modal;
+        if (!this.data.custom_id)
+            this.data.custom_id = this.data.modal.custom_id;
+        return this;
+    }
+    toJSON() { return this.data; }
+}
+export class StringSelectMenuBuilder {
+    data = { type: "select", custom_id: "", options: [] };
+    setCustomId(id) { this.data.custom_id = id; return this; }
+    setPlaceholder(text) { this.data.placeholder = text; return this; }
+    setMinValues(n) { this.data.min_values = n; return this; }
+    setMaxValues(n) { this.data.max_values = n; return this; }
+    setDisabled(disabled = true) { this.data.disabled = disabled; return this; }
+    addOptions(...options) {
+        this.data.options.push(...options);
+        return this;
+    }
+    toJSON() { return this.data; }
+}
+export class TextInputBuilder {
+    data = { style: "short", required: true };
+    setCustomId(id) { this.data.custom_id = id; return this; }
+    setLabel(label) { this.data.label = label; return this; }
+    setStyle(style) { this.data.style = style; return this; }
+    setPlaceholder(text) { this.data.placeholder = text; return this; }
+    setRequired(required = true) { this.data.required = required; return this; }
+    setMaxLength(n) { this.data.max_length = n; return this; }
+    toJSON() { return this.data; }
+}
+export class ModalBuilder {
+    data = { custom_id: "", title: "", fields: [] };
+    setCustomId(id) { this.data.custom_id = id; return this; }
+    setTitle(title) { this.data.title = title; return this; }
+    /** Add text inputs to the modal (up to 5). */
+    addComponents(...inputs) {
+        for (const i of inputs)
+            this.data.fields.push(i instanceof TextInputBuilder ? i.toJSON() : i);
+        return this;
+    }
     toJSON() { return this.data; }
 }
 export class ActionRowBuilder {
     data = { type: "action_row", components: [] };
-    /** Add up to 5 buttons to this row. */
-    addComponents(...buttons) {
-        for (const b of buttons)
-            this.data.components.push(b instanceof ButtonBuilder ? b.toJSON() : b);
+    /** Add up to 5 buttons, or a single select menu. */
+    addComponents(...components) {
+        for (const c of components) {
+            this.data.components.push(c instanceof ButtonBuilder || c instanceof StringSelectMenuBuilder ? c.toJSON() : c);
+        }
         return this;
     }
     toJSON() { return this.data; }

package/dist/index.d.ts

@@ -2,7 +2,7 @@ export { Client, type ClientEvents } from "./client.js";
 export { REST, DistrictAPIError, DEFAULT_API_BASE } from "./rest.js";
 export { ClientUser, Message, TextChannel, Interaction, User, Space, SpaceMember, Role, Attachment, Ban, Invite, Webhook, type ClientContext, type MessageContent, } from "./structures.js";
 export { EmbedBuilder, resolveEmbed, type EmbedData, type EmbedField, type EmbedResolvable } from "./embed.js";
-export { ButtonBuilder, ActionRowBuilder, resolveComponent, type ButtonStyle, type ButtonData, type ActionRowData, type ComponentResolvable, } from "./components.js";
+export { ButtonBuilder, ActionRowBuilder, StringSelectMenuBuilder, ModalBuilder, TextInputBuilder, resolveComponent, type ButtonStyle, type ButtonData, type SelectData, type SelectOption, type ComponentData, type ModalData, type TextInputData, type ActionRowData, type ComponentResolvable, } from "./components.js";
 export { Collection } from "./collection.js";
 export { PermissionsBitField, type PermissionResolvable, type PermissionFlagName } from "./permissions.js";
 export { Formatters } from "./formatters.js";

package/dist/index.js

@@ -8,7 +8,7 @@ export { Client } from "./client.js";
 export { REST, DistrictAPIError, DEFAULT_API_BASE } from "./rest.js";
 export { ClientUser, Message, TextChannel, Interaction, User, Space, SpaceMember, Role, Attachment, Ban, Invite, Webhook, } from "./structures.js";
 export { EmbedBuilder, resolveEmbed } from "./embed.js";
-export { ButtonBuilder, ActionRowBuilder, resolveComponent, } from "./components.js";
+export { ButtonBuilder, ActionRowBuilder, StringSelectMenuBuilder, ModalBuilder, TextInputBuilder, resolveComponent, } from "./components.js";
 export { Collection } from "./collection.js";
 export { PermissionsBitField } from "./permissions.js";
 export { Formatters } from "./formatters.js";

package/dist/structures.d.ts

@@ -205,14 +205,18 @@ export declare class Role {
 }
 export declare class Interaction {
     private client;
-    /** "command" (slash command) or "component" (button click). */
-    type: "command" | "component";
+    /** "command" (slash), "component" (button/select), or "modal_submit". */
+    type: "command" | "component" | "modal_submit";
     commandName: string;
     commandId: string;
-    /** The clicked button's customId (component interactions). */
+    /** The component/modal customId that triggered this. */
     customId: string;
-    /** The message the component is on (component interactions). */
+    /** The message the component is on. */
     messageId: string | null;
+    /** Selected values (select-menu interactions). */
+    values: string[];
+    /** Submitted field values keyed by input customId (modal submits). */
+    fields: Record<string, string>;
     spaceId: string;
     channelId: string;
     userId: string;
@@ -227,11 +231,21 @@ export declare class Interaction {
         channel_id: string;
         user_id: string;
         args?: Record<string, unknown>;
+        data?: {
+            values?: string[];
+            fields?: Record<string, string>;
+        };
     });
-    /** True if this is a button click. */
-    isButton(): boolean;
     /** True if this is a slash command. */
     isCommand(): boolean;
+    /** True if this is a button click (component with no selected values). */
+    isButton(): boolean;
+    /** True if this is a select-menu choice. */
+    isSelectMenu(): boolean;
+    /** True if this is a submitted modal. */
+    isModalSubmit(): boolean;
+    /** Get a submitted modal field value by its input customId. */
+    field(customId: string): string | undefined;
     /** Respond to the command by posting a message in its channel. */
     reply(content: MessageContent): Promise<Message>;
 }

package/dist/structures.js

@@ -376,34 +376,46 @@ export class Role {
 }
 export class Interaction {
     client;
-    /** "command" (slash command) or "component" (button click). */
+    /** "command" (slash), "component" (button/select), or "modal_submit". */
     type;
     commandName;
     commandId;
-    /** The clicked button's customId (component interactions). */
+    /** The component/modal customId that triggered this. */
     customId;
-    /** The message the component is on (component interactions). */
+    /** The message the component is on. */
     messageId;
+    /** Selected values (select-menu interactions). */
+    values;
+    /** Submitted field values keyed by input customId (modal submits). */
+    fields;
     spaceId;
     channelId;
     userId;
     args;
     constructor(client, raw) {
         this.client = client;
-        this.type = raw.type === "component" ? "component" : "command";
+        this.type = raw.type === "component" ? "component" : raw.type === "modal_submit" ? "modal_submit" : "command";
         this.commandName = raw.command ?? "";
         this.commandId = raw.command_id ?? "";
         this.customId = raw.custom_id ?? "";
         this.messageId = raw.message_id ?? null;
+        this.values = Array.isArray(raw.data?.values) ? raw.data.values : [];
+        this.fields = raw.data?.fields && typeof raw.data.fields === "object" ? raw.data.fields : {};
         this.spaceId = raw.space_id;
         this.channelId = raw.channel_id;
         this.userId = raw.user_id;
         this.args = raw.args ?? {};
     }
-    /** True if this is a button click. */
-    isButton() { return this.type === "component"; }
     /** True if this is a slash command. */
     isCommand() { return this.type === "command"; }
+    /** True if this is a button click (component with no selected values). */
+    isButton() { return this.type === "component" && this.values.length === 0; }
+    /** True if this is a select-menu choice. */
+    isSelectMenu() { return this.type === "component" && this.values.length > 0; }
+    /** True if this is a submitted modal. */
+    isModalSubmit() { return this.type === "modal_submit"; }
+    /** Get a submitted modal field value by its input customId. */
+    field(customId) { return this.fields[customId]; }
     /** Respond to the command by posting a message in its channel. */
     async reply(content) {
         const p = toPayload(content);

package/dist/types.d.ts

@@ -146,7 +146,7 @@ export type DistrictEvent = {
     emoji: string;
 } | {
     event: "interaction.create";
-    type?: "command" | "component";
+    type?: "command" | "component" | "modal_submit";
     command?: string;
     command_id?: string;
     custom_id?: string;
@@ -155,6 +155,10 @@ export type DistrictEvent = {
     channel_id: string;
     user_id: string;
     args?: Record<string, unknown>;
+    data?: {
+        values?: string[];
+        fields?: Record<string, string>;
+    };
 };
 export interface ReactionEvent {
     spaceId: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "district.js",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "A powerful Node.js module for building District bots — post, react, run slash commands, and receive events.",
   "type": "module",
   "main": "./dist/index.js",