djs-builder 0.7.4 → 0.7.6

package/README.md

@@ -392,6 +392,1057 @@ console.log(
 
 ---
 
+<details>
+<summary>CreateModal 🔳</summary>
+
+**🔳 CreateModal – Easily create Discord Modals with Text Inputs, Menus, Files, and Labels ✨**
+
+`CreateModal` is a powerful utility to build Discord **Modals**. It supports:
+
+- **Text Inputs** 📝
+- **Select Menus** 🎯 (`string`, `role`, `user`, `channel`)
+- **File Uploads** 📎
+- **Text Displays** 🏷️
+
+---
+
+### 📌 Example Usage:
+
+```js
+const { CreateModal } = require("djs-builder");
+
+const modal = CreateModal({
+  id: "myModal",
+  title: "User Information",
+  components: [
+    {
+      type: "textInput",
+      components: [
+        {
+          label: "Your Name",
+          id: "name",
+          style: 1, // 1: Short, 2: Paragraph
+          placeholder: "Enter your name",
+          required: true,
+          minLength: 2,
+          maxLength: 50,
+        },
+      ],
+    },
+    {
+      type: "menu",
+      components: {
+        type: "string",
+        options: {
+          id: "favoriteColor",
+          placeholder: "Choose your favorite color",
+          min: 1,
+          max: 1,
+          data: [
+            {
+              label: "Red",
+              value: "red",
+              description: "A bold color",
+              emoji: "🔴",
+              default: false,
+            },
+            {
+              label: "Blue",
+              value: "blue",
+              description: "A calm color",
+              emoji: "🔵",
+            },
+          ],
+          label: "label",
+          value: "value",
+          description: "description",
+          emoji: "emoji",
+          disabled: false,
+        },
+      },
+    },
+    {
+      type: "file",
+      components: {
+        id: "avatar",
+        label: "Upload Avatar",
+        description: "Optional avatar image",
+      },
+    },
+    {
+      type: "label",
+      components: {
+        label: "Thank you for your input!",
+      },
+    },
+  ],
+});
+
+// Show the modal
+await interaction.showModal(modal);
+```
+
+---
+
+### 📔 Examples for Each Component Type:
+
+#### 🔹 Text Input Example:
+
+```js
+{
+  type: "textInput",
+  components: [
+    {
+      label: "Your Age",
+      id: "age",
+      style: 1, // Short input
+      placeholder: "Enter your age",
+      required: true,
+      minLength: 1,
+      maxLength: 3,
+      value: "18", // Pre-filled
+    },
+  ],
+},
+```
+
+#### 🔹 Menu Example:
+
+```js
+{
+  type: "menu",
+  components: {
+    type: "string",
+    options: {
+      id: "country",
+      placeholder: "Select your country",
+      min: 1,
+      max: 1,
+      data: [
+        {
+          name: "USA",
+          id: "usa",
+          desc: "United States",
+          icon: "🇺🇸",
+          default: true, // This option is pre-selected
+        },
+        {
+          name: "Canada",
+          id: "canada",
+          desc: "Canada",
+          icon: "🇨🇦",
+        },
+      ],
+      label: "name", // Maps to 'name' field in data
+      value: "id",   // Maps to 'id' field in data
+      description: "desc", // Maps to 'desc' field
+      emoji: "icon", // Maps to 'icon' field
+      disabled: false,
+    },
+  },
+},
+```
+
+#### 🔹 File Example:
+
+```js
+{
+  type: "file",
+  components: {
+    id: "document",
+    label: "Upload Document",
+    description: "Upload a PDF or image",
+  },
+},
+```
+
+#### 🔹 Label Example:
+
+```js
+{
+  type: "label",
+  components: {
+    label: "Please fill out the form above.",
+  },
+},
+```
+
+---
+
+### �📖 Explanation
+
+#### 🔹 Text Input
+
+- `label` → Label for the input field
+- `id` → customId for the input
+- `style` → 1: Short, 2: Paragraph
+- `placeholder` → Placeholder text
+- `required` → true/false
+- `minLength` / `maxLength` → Min/Max characters
+- `value` → Pre-filled value
+
+#### 🔹 Menu
+
+Same as CreateRow select menus.
+
+- `type` → `"string" | "user" | "role" | "channel"`
+- `id` → customId for menu
+- `placeholder` → Text shown before selection
+- `min` / `max` → Min/Max selectable values
+- `data` → Options array (for string select only)
+
+  - `label` → Visible text (maps to the field specified in `label` key)
+  - `value` → Internal value (maps to the field specified in `value` key)
+  - `description` → Short description (maps to the field specified in `description` key)
+  - `emoji` → Option emoji (maps to the field specified in `emoji` key)
+  - `default` → Pre-selected option (true/false in data array)
+
+- `label` → Key in data to use as label (e.g., "name")
+- `value` → Key in data to use as value (e.g., "id")
+- `description` → Key in data to use as description (e.g., "desc")
+- `emoji` → Key in data to use as emoji (e.g., "icon")
+- `disabled` → Disable menu completely
+- `defaultValues` → Pre-selected user/role/channel options (for non-string menus)
+- `channelTypes` → Restrict selectable channel types (for channel menu)
+
+#### 🔹 File
+
+- `id` → customId for the file upload
+- `label` → Label
+- `description` → Description
+
+#### 🔹 Label
+
+- `label` → Text to display
+
+---
+
+### 🔹 Notes
+
+- Supports multiple components in one modal
+- Fully customizable with Discord.js ModalBuilder
+
+</details>
+
+---
+
+<details>
+<summary>CreateComponents 🧩</summary>
+
+**🧩 CreateComponents – Build Advanced Discord UI Components with Containers, Sections & Media ✨**
+
+`CreateComponents` is a powerful utility to build Discord's **new UI components**. It supports:
+
+- **Text Displays** 📝
+- **Separators** ➖
+- **Media Galleries** 🖼️
+- **File Attachments** 📎
+- **Buttons** 🔘
+- **Select Menus** 🎯 (`string`, `role`, `user`, `channel`)
+- **Sections with Accessories** 📦 (Thumbnails & Buttons)
+- **Containers** 📦 (Group all components together)
+
+---
+
+### 📌 Example Usage (Array Mode):
+
+```js
+const { CreateComponents } = require("djs-builder");
+
+const components = await CreateComponents("array", [
+  {
+    type: "text",
+    content: "Welcome to our server! 🎉",
+  },
+  {
+    type: "separator",
+    divider: true,
+    spacing: 1, // 1: Small, 2: Large
+  },
+  {
+    type: "media",
+    links: [
+      "https://example.com/image1.png",
+      {
+        url: "https://example.com/image2.png",
+        description: "A cool image",
+        spoiler: true,
+      },
+    ],
+  },
+  {
+    type: "button",
+    components: [
+      {
+        id: "btn_1",
+        style: 1, // 1: Primary, 2: Secondary, 3: Success, 4: Danger, 5: Link
+        label: "Click Me!",
+        emoji: "🚀",
+      },
+      {
+        id: "btn_2",
+        style: 3,
+        label: "Confirm",
+      },
+    ],
+  },
+]);
+
+// Send the components
+await channel.send({ components });
+```
+
+---
+
+### 📌 Example Usage (Container Mode):
+
+```js
+const { CreateComponents } = require("djs-builder");
+
+const components = await CreateComponents("container", [
+  {
+    type: "text",
+    content: "# 📢 Server Announcement\nWelcome everyone!",
+  },
+  {
+    type: "separator",
+    divider: true,
+  },
+  {
+    type: "section",
+    content: "Check out our latest updates and news!",
+    accessory: {
+      type: "thumbnail",
+      url: "https://example.com/thumbnail.png",
+      description: "News Image",
+    },
+  },
+  {
+    type: "section",
+    content: "**Click below to get your roles!**",
+    accessory: {
+      type: "button",
+      id: "get_roles",
+      style: 1,
+      label: "Get Roles",
+      emoji: "🎭",
+    },
+  },
+  {
+    type: "media",
+    links: ["https://example.com/banner.png"],
+  },
+  {
+    type: "button",
+    components: [
+      { id: "rules", style: 2, label: "📜 Rules", emoji: "📜" },
+      { id: "help", style: 2, label: "❓ Help", emoji: "❓" },
+      { style: 5, label: "🌐 Website", url: "https://example.com" },
+    ],
+  },
+]);
+
+// Send with container
+await channel.send({ components, flags: 32768 }); // flags for components v2
+```
+
+---
+
+### 📜 Examples for Each Component Type:
+
+---
+
+<details>
+<summary>🔹 Text Component Examples</summary>
+
+#### 📌 Simple Text:
+
+```js
+{
+  type: "text",
+  content: "Hello World! 👋",
+}
+```
+
+#### 📌 Text with Markdown:
+
+```js
+{
+  type: "text",
+  content: "# 📢 Announcement\n**Important:** Server maintenance tonight!",
+}
+```
+
+#### 📌 Text with Multiple Lines:
+
+```js
+{
+  type: "text",
+  content: `## 🎮 Game Stats
+  
+**Player:** Ahmed
+**Level:** 50
+**XP:** 12,500 / 15,000
+**Rank:** Diamond 💎`,
+}
+```
+
+#### 📌 Text with Emojis & Formatting:
+
+```js
+{
+  type: "text",
+  content: ">>> 💡 **Tip:** Use `/help` to see all commands!\n\n*This message will auto-delete in 30 seconds*",
+}
+```
+
+</details>
+
+---
+
+<details>
+<summary>➖ Separator Component Examples</summary>
+
+**➖ Separator – Add spacing and dividers between components**
+
+The separator component allows you to add visual breaks between other components with customizable spacing and divider lines.
+
+---
+
+### 📖 Separator Options
+
+| Option    | Type      | Default | Description                                        |
+| --------- | --------- | ------- | -------------------------------------------------- |
+| `type`    | `string`  | —       | Must be `"separator"`                              |
+| `divider` | `boolean` | `false` | Show a horizontal dividing line                    |
+| `spacing` | `number`  | `1`     | Spacing size: `1` (Small) or `2` (Large)           |
+
+---
+
+#### 📌 Simple Divider Line:
+
+```js
+{
+  type: "separator",
+  divider: true,
+}
+```
+**Result:** A thin horizontal line appears between components.
+
+---
+
+#### 📌 Separator without Line (Spacing Only):
+
+```js
+{
+  type: "separator",
+  divider: false,
+  spacing: 2, // Large spacing
+}
+```
+**Result:** Empty space without any visible line - useful for visual grouping.
+
+---
+
+#### 📌 Small Spacing with Divider:
+
+```js
+{
+  type: "separator",
+  divider: true,
+  spacing: 1, // Small spacing (default)
+}
+```
+**Result:** A divider line with minimal padding above and below.
+
+---
+
+#### 📌 Large Spacing with Divider:
+
+```js
+{
+  type: "separator",
+  divider: true,
+  spacing: 2, // Large spacing
+}
+```
+**Result:** A divider line with more padding - creates stronger visual separation.
+
+---
+
+### 💡 When to Use Each Option:
+
+| Scenario                              | `divider` | `spacing` |
+| ------------------------------------- | --------- | --------- |
+| Separate major sections               | `true`    | `2`       |
+| Separate sub-sections                 | `true`    | `1`       |
+| Group related items visually          | `false`   | `1`       |
+| Create breathing room between content | `false`   | `2`       |
+| Minimal separation                    | `false`   | `1`       |
+
+</details>
+
+---
+
+<details>
+<summary>🖼️ Media Gallery Examples</summary>
+
+**🖼️ Media Gallery – Display images in a beautiful gallery format**
+
+The media component creates an image gallery that can display one or multiple images. Each image can be a simple URL string or a detailed object with additional options.
+
+
+---
+
+### 📌 Format 1: Simple String URLs
+
+The simplest way - just pass image URLs as strings:
+
+```js
+{
+  type: "media",
+  links: ["https://example.com/image.png"],
+}
+```
+
+---
+
+### 📌 Format 2: Object with Full Options
+
+For more control, use objects with url, description, and spoiler:
+
+```js
+{
+  type: "media",
+  links: [
+    {
+      url: "https://example.com/image.png",
+      description: "A beautiful sunset",
+      spoiler: false,
+    },
+  ],
+}
+```
+
+---
+
+### 📌 Single Image with Spoiler:
+
+```js
+{
+  type: "media",
+  links: [
+    {
+      url: "https://example.com/spoiler.png",
+      description: "⚠️ Spoiler Alert!",
+      spoiler: true,
+    },
+  ],
+}
+```
+
+---
+
+### 📌 Multiple Images (Simple Strings):
+
+```js
+{
+  type: "media",
+  links: [
+    "https://example.com/image1.png",
+    "https://example.com/image2.png",
+    "https://example.com/image3.png",
+    "https://example.com/image4.png",
+  ],
+}
+```
+**Result:** A 2x2 gallery grid of images.
+
+---
+
+### 📌 Mixed Format (Strings + Objects):
+
+You can mix simple strings with detailed objects in the same array:
+
+```js
+{
+  type: "media",
+  links: [
+    // Simple string - just the URL
+    "https://example.com/public-image.png",
+    
+    // Object with description
+    {
+      url: "https://example.com/special-image.png",
+      description: "Limited Edition Art",
+    },
+    
+    // Object with spoiler
+    {
+      url: "https://example.com/secret-image.png",
+      description: "Secret Content",
+      spoiler: true,
+    },
+    
+    // Another simple string
+    "https://example.com/another-image.png",
+  ],
+}
+```
+
+---
+
+### 📌 Meme/Artwork Gallery with Spoilers:
+
+```js
+{
+  type: "media",
+  links: [
+    {
+      url: "https://example.com/meme1.png",
+      description: "Funny meme #1",
+      spoiler: false,
+    },
+    {
+      url: "https://example.com/meme2.png",
+      description: "Funny meme #2",
+      spoiler: false,
+    },
+    {
+      url: "https://example.com/nsfw-meme.png",
+      description: "⚠️ Slightly inappropriate",
+      spoiler: true, // Hidden behind blur
+    },
+  ],
+}
+```
+
+---
+
+### 💡 Tips for Media Galleries:
+
+| Images Count | Display Layout         |
+| ------------ | ---------------------- |
+| 1 image      | Full width single image |
+| 2 images     | Side by side           |
+| 3 images     | 1 large + 2 small      |
+| 4+ images    | Grid layout            |
+
+- Use `description` for accessibility and context
+- Use `spoiler: true` for sensitive/spoiler content
+- Mix formats freely - strings for quick images, objects for detailed ones
+- Images are displayed in the order provided
+
+</details>
+
+---
+
+<details>
+<summary>📎 File Component Examples</summary>
+
+#### 📌 Simple File Attachment:
+
+```js
+{
+  type: "file",
+  url: "attachment://document.pdf",
+}
+```
+
+
+
+#### 📌 Full Example with File:
+
+```js
+const { CreateComponents } = require("djs-builder");
+const { AttachmentBuilder } = require("discord.js");
+
+const file = new AttachmentBuilder("./myfile.txt", { name: "myfile.txt" });
+
+const components = await CreateComponents("container", [
+  {
+    type: "text",
+    content: "📄 **Here is your requested file:**",
+  },
+  {
+    type: "file",
+    url: "attachment://myfile.txt",
+  },
+]);
+
+await channel.send({ components, files: [file], flags: 32768 });
+```
+
+</details>
+
+---
+
+<details>
+<summary>🔘 Button Component Examples</summary>
+
+#### 📌 Button with Emoji:
+
+```js
+{
+  type: "button",
+  components: [
+    {
+      id: "like_btn",
+      style: 3, // Success (Green)
+      label: "Like",
+      emoji: "👍",
+    },
+  ],
+}
+```
+
+#### 📌 Multiple Buttons in Row:
+
+```js
+{
+  type: "button",
+  components: [
+    { id: "btn_yes", style: 3, label: "Yes", emoji: "✅" },
+    { id: "btn_no", style: 4, label: "No", emoji: "❌" },
+    { id: "btn_maybe", style: 2, label: "Maybe", emoji: "🤔" },
+  ],
+}
+```
+
+#### 📌 All Button Styles:
+
+```js
+{
+  type: "button",
+  components: [
+    { id: "primary", style: 1, label: "Primary", emoji: "🔵" },    // Blue
+    { id: "secondary", style: 2, label: "Secondary", emoji: "⚪" }, // Gray
+    { id: "success", style: 3, label: "Success", emoji: "🟢" },    // Green
+    { id: "danger", style: 4, label: "Danger", emoji: "🔴" },      // Red
+    { style: 5, label: "Link", emoji: "🔗", url: "https://discord.com" }, // Link
+  ],
+}
+```
+
+
+</details>
+
+---
+
+<details>
+<summary>🎯 Menu Component Examples</summary>
+
+#### 📌 String Select Menu (Basic):
+
+```js
+{
+  type: "menu",
+  components: {
+    type: "string",
+    options: {
+      id: "color_select",
+      placeholder: "🎨 Choose a color",
+      data: [
+        { name: "Red", id: "red", icon: "🔴" },
+        { name: "Blue", id: "blue", icon: "🔵" },
+        { name: "Green", id: "green", icon: "🟢" },
+      ],
+      label: "name",
+      value: "id",
+      emoji: "icon",
+    },
+  },
+}
+```
+
+#### 📌 String Select with Description:
+
+```js
+{
+  type: "menu",
+  components: {
+    type: "string",
+    options: {
+      id: "role_select",
+      placeholder: "🎭 Select your role",
+      data: [
+        { name: "Gamer", id: "gamer", desc: "For gaming enthusiasts", icon: "🎮" },
+        { name: "Artist", id: "artist", desc: "For creative people", icon: "🎨" },
+        { name: "Developer", id: "dev", desc: "For coders & programmers", icon: "💻" },
+        { name: "Music Lover", id: "music", desc: "For music fans", icon: "🎵" },
+      ],
+      label: "name",
+      value: "id",
+      description: "desc",
+      emoji: "icon",
+    },
+  },
+}
+```
+
+#### 📌 String Select with Min/Max:
+
+```js
+{
+  type: "menu",
+  components: {
+    type: "string",
+    options: {
+      id: "games_select",
+      placeholder: "🎮 Select your favorite games (2-4)",
+      min: 2,
+      max: 4,
+      data: [
+        { name: "Minecraft", id: "mc", icon: "⛏️" },
+        { name: "Fortnite", id: "fn", icon: "🔫" },
+        { name: "Valorant", id: "val", icon: "🎯" },
+        { name: "League of Legends", id: "lol", icon: "⚔️" },
+        { name: "Rocket League", id: "rl", icon: "🚗" },
+      ],
+      label: "name",
+      value: "id",
+      emoji: "icon",
+    },
+  },
+}
+```
+
+
+#### 📌 User Select (Multiple):
+
+```js
+{
+  type: "menu",
+  components: {
+    type: "user",
+    options: {
+      id: "users_select",
+      placeholder: "👥 Select users to invite (1-5)",
+      min: 1,
+      max: 5,
+    },
+  },
+}
+```
+
+#### 📌 Role Select Menu:
+
+```js
+{
+  type: "menu",
+  components: {
+    type: "role",
+    options: {
+      id: "role_select",
+      placeholder: "🎭 Select a role",
+      min: 1,
+      max: 1,
+    },
+  },
+}
+```
+
+
+#### 📌 Channel Select Menu:
+
+```js
+{
+  type: "menu",
+  components: {
+    type: "channel",
+    options: {
+      id: "channel_select",
+      placeholder: "📢 Select a channel",
+      min: 1,
+      max: 1,
+    },
+  },
+}
+```
+
+#### 📌 Channel Select with Type Filter:
+
+```js
+const { ChannelType } = require("discord.js");
+
+{
+  type: "menu",
+  components: {
+    type: "channel",
+    options: {
+      id: "text_channel_select",
+      placeholder: "💬 Select a text channel",
+      channelTypes: [ChannelType.GuildText, ChannelType.GuildAnnouncement],
+    },
+  },
+}
+```
+
+#### 📌 Menu with Default Values (User/Role/Channel):
+
+```js
+{
+  type: "menu",
+  components: {
+    type: "user",
+    options: {
+      id: "user_select_default",
+      placeholder: "👤 Select users",
+      min: 1,
+      max: 3,
+      defaultValues: [
+        { id: "123456789012345678", type: "user" },
+        { id: "987654321098765432", type: "user" },
+      ],
+    },
+  },
+}
+```
+
+</details>
+
+---
+
+<details>
+<summary>📦 Section Component Examples</summary>
+
+
+#### 📌 Section with Thumbnail (Product):
+
+```js
+{
+  type: "section",
+  content: "🛒 **iPhone 15 Pro**\n💰 Price: $999\n⭐ Rating: 4.8/5\n📦 In Stock: Yes",
+  accessory: {
+    type: "thumbnail",
+    url: "https://example.com/iphone.png",
+    description: "iPhone 15 Pro Image",
+  },
+}
+```
+
+#### 📌 Section with Button :
+
+```js
+{
+  type: "section",
+  content: "🎁 **Daily Reward**\nClick to claim your daily reward!\n💎 **+100 Coins**",
+  accessory: {
+    type: "button",
+    id: "claim_daily",
+    style: 3, 
+    label: "Claim",
+    emoji: "🎁",
+  },
+}
+```
+
+
+
+
+</details>
+
+---
+
+
+### 📖 Component Types Explanation
+
+#### 🔹 Text
+
+- `type` → `"text"`
+- `content` → The text content to display (supports Markdown)
+
+#### 🔹 Separator
+
+- `type` → `"separator"`
+- `divider` → Show a dividing line (true/false)
+- `spacing` → Spacing size (1: Small, 2: Large)
+
+#### 🔹 Media Gallery
+
+- `type` → `"media"`
+- `links` → Array of image URLs or objects with:
+  - `url` → Image URL
+  - `description` → Alt text for the image
+  - `spoiler` → Hide behind spoiler (true/false)
+
+#### 🔹 File
+
+- `type` → `"file"`
+- `url` → File URL or attachment reference
+- `spoiler` → Hide behind spoiler (true/false)
+
+#### 🔹 Button
+
+- `type` → `"button"`
+- `components` → Array of button objects:
+  - `id` → customId (required for non-link buttons)
+  - `style` → 1: Primary, 2: Secondary, 3: Success, 4: Danger, 5: Link
+  - `label` → Button text
+  - `emoji` → Button emoji
+  - `disabled` → Disable button (true/false)
+  - `url` → URL for link buttons (style: 5)
+
+#### 🔹 Menu
+
+- `type` → `"menu"`
+- `components` → Object containing:
+  - `type` → `"string" | "user" | "role" | "channel"`
+  - `options` → Menu configuration:
+    - `id` → customId
+    - `placeholder` → Placeholder text
+    - `min` / `max` → Min/Max selectable values
+    - `data` → Options array (for string select)
+    - `label` → Key in data for label
+    - `value` → Key in data for value
+    - `emoji` → Key in data for emoji
+    - `description` → Key in data for description
+    - `channelTypes` → Channel types filter (for channel menu)
+    - `defaultValues` → Pre-selected values
+
+#### 🔹 Section
+
+- `type` → `"section"`
+- `content` → Text content for the section
+- `accessory` → Side component:
+  - **Button Accessory:**
+    - `type` → `"button"`
+    - `id` → customId
+    - `style` → Button style
+    - `label` → Button text
+    - `emoji` → Button emoji
+    - `url` → URL (for link buttons)
+  - **Thumbnail Accessory:**
+    - `type` → `"thumbnail"`
+    - `url` → Image URL
+    - `description` → Image description
+
+---
+
+### 🔹 Mode Differences
+
+| Feature          | `"array"` Mode          | `"container"` Mode        |
+| ---------------- | ----------------------- | ------------------------- |
+| Return Type      | Array of components     | Single ContainerBuilder   |
+| Usage            | Standard messages       | Components V2 messages    |
+| Sections Support | ✅                      | ✅                        |
+| Grouping         | Individual components   | All grouped in container  |
+| Flags Required   | ❌                      | ✅ (flags: 32768)         |
+
+---
+
+### 🔹 Notes
+
+- Use `"container"` mode for Discord's **Components V2** (newer UI)
+- Use `"array"` mode for standard component arrays
+- Sections can have either a **button** or **thumbnail** as accessory, not both
+- Media galleries support multiple images in a single component
+- All components are fully customizable 🎨
+
+</details>
+
+---
+
 <details>
 <summary>Wait ⏰</summary>