chrxmaticc-framework 1.2.1 → 1.3.0

package/core/ChrxComponentsV3.js

@@ -0,0 +1,652 @@
+/**
+ * core/ChrxComponentsV3.js
+ * Components V3 — every Discord component simplified into clean Chrx builders.
+ *
+ * Includes:
+ * - ChrxButton
+ * - ChrxSelectMenu
+ * - ChrxPagination
+ * - ChrxContextMenu
+ * - ChrxMenu
+ * - ChrxForm
+ * - ChrxConfirm
+ */
+
+const {
+  ButtonBuilder,
+  ButtonStyle,
+  ActionRowBuilder,
+  StringSelectMenuBuilder,
+  StringSelectMenuOptionBuilder,
+  ContextMenuCommandBuilder,
+  ApplicationCommandType,
+  EmbedBuilder,
+  ComponentType,
+} = require("discord.js");
+
+// ── Style map ─────────────────────────────────────────────────────────────
+const BUTTON_STYLE_MAP = {
+  primary:   ButtonStyle.Primary,
+  secondary: ButtonStyle.Secondary,
+  success:   ButtonStyle.Success,
+  danger:    ButtonStyle.Danger,
+  link:      ButtonStyle.Link,
+  blurple:   ButtonStyle.Primary,
+  grey:      ButtonStyle.Secondary,
+  gray:      ButtonStyle.Secondary,
+  green:     ButtonStyle.Success,
+  red:       ButtonStyle.Danger,
+};
+
+// ═════════════════════════════════════════════════════════════════════════════
+// ChrxButton
+// ═════════════════════════════════════════════════════════════════════════════
+
+class ChrxButton {
+  /**
+   * @param {object} options
+   * @param {string}   options.label            Button label
+   * @param {string}   [options.style]          "primary"|"secondary"|"success"|"danger"|"link" (default: primary)
+   * @param {string}   [options.id]             Custom ID (not needed for link buttons)
+   * @param {string}   [options.url]            URL for link buttons
+   * @param {string}   [options.emoji]          Emoji for button
+   * @param {boolean}  [options.disabled]       Disable the button
+   * @param {Function} [options.onClick]        Handler (interaction) => void
+   */
+  constructor(options = {}) {
+    if (!options.label) throw new Error("[ChrxButton] label is required.");
+
+    this._options = options;
+    this._handler = options.onClick ?? null;
+
+    const btn = new ButtonBuilder().setLabel(options.label);
+
+    if (options.style === "link" || options.url) {
+      btn.setStyle(ButtonStyle.Link).setURL(options.url);
+    } else {
+      btn.setStyle(BUTTON_STYLE_MAP[options.style ?? "primary"] ?? ButtonStyle.Primary);
+      btn.setCustomId(options.id ?? `chrx-btn-${Math.random().toString(36).slice(2, 9)}`);
+    }
+
+    if (options.emoji)    btn.setEmoji(options.emoji);
+    if (options.disabled) btn.setDisabled(true);
+
+    this._button = btn;
+    this.customId = options.id;
+  }
+
+  /**
+   * Build into an ActionRow ready to send.
+   */
+  toRow() {
+    return new ActionRowBuilder().addComponents(this._button);
+  }
+
+  /**
+   * Send the button with a message and listen for clicks.
+   * Auto cleans up the collector after timeout.
+   *
+   * @param {import("discord.js").CommandInteraction} interaction
+   * @param {object} [options]
+   * @param {string}  [options.content]    Message content
+   * @param {object}  [options.embed]      EmbedBuilder to attach
+   * @param {boolean} [options.ephemeral]
+   * @param {number}  [options.timeout]    Collector timeout in ms (default: 60000)
+   */
+  async send(interaction, options = {}) {
+    const payload = {
+      components: [this.toRow()],
+      ephemeral: options.ephemeral ?? false,
+    };
+    if (options.content) payload.content = options.content;
+    if (options.embed)   payload.embeds  = [options.embed];
+
+    const reply = await interaction.reply({ ...payload, fetchReply: true });
+
+    if (!this._handler) return;
+
+    const collector = reply.createMessageComponentCollector({
+      componentType: ComponentType.Button,
+      time: options.timeout ?? 60000,
+    });
+
+    collector.on("collect", async (i) => {
+      if (i.customId !== (this._options.id ?? this._button.data.custom_id)) return;
+      try {
+        await this._handler(i);
+      } catch (err) {
+        console.error("[ChrxButton] onClick error:", err);
+        i.reply({ content: err.message || "❌ Something went wrong.", ephemeral: true }).catch(() => {});
+      }
+    });
+
+    collector.on("end", () => {
+      reply.edit({ components: [] }).catch(() => {});
+    });
+  }
+}
+
+// ═════════════════════════════════════════════════════════════════════════════
+// ChrxSelectMenu
+// ═════════════════════════════════════════════════════════════════════════════
+
+class ChrxSelectMenu {
+  /**
+   * @param {object} options
+   * @param {string}   options.id              Custom ID
+   * @param {string}   options.placeholder     Placeholder text
+   * @param {object[]} options.options         Menu options
+   * @param {string}   options.options[].label
+   * @param {string}   options.options[].value
+   * @param {string}   [options.options[].description]
+   * @param {string}   [options.options[].emoji]
+   * @param {boolean}  [options.options[].default]
+   * @param {number}   [options.min]           Min selections (default: 1)
+   * @param {number}   [options.max]           Max selections (default: 1)
+   * @param {Function} [options.onSelect]      Handler (interaction, values) => void
+   */
+  constructor(options = {}) {
+    if (!options.id)          throw new Error("[ChrxSelectMenu] id is required.");
+    if (!options.placeholder) throw new Error("[ChrxSelectMenu] placeholder is required.");
+    if (!options.options?.length) throw new Error("[ChrxSelectMenu] options are required.");
+
+    this._options = options;
+    this._handler = options.onSelect ?? null;
+
+    const menu = new StringSelectMenuBuilder()
+      .setCustomId(options.id)
+      .setPlaceholder(options.placeholder)
+      .setMinValues(options.min ?? 1)
+      .setMaxValues(options.max ?? 1)
+      .addOptions(
+        options.options.map((opt) => {
+          const o = new StringSelectMenuOptionBuilder()
+            .setLabel(opt.label)
+            .setValue(opt.value);
+          if (opt.description) o.setDescription(opt.description);
+          if (opt.emoji)       o.setEmoji(opt.emoji);
+          if (opt.default)     o.setDefault(true);
+          return o;
+        })
+      );
+
+    this._menu = menu;
+  }
+
+  toRow() {
+    return new ActionRowBuilder().addComponents(this._menu);
+  }
+
+  /**
+   * Send the select menu and listen for selections.
+   */
+  async send(interaction, options = {}) {
+    const payload = {
+      components: [this.toRow()],
+      ephemeral: options.ephemeral ?? false,
+    };
+    if (options.content) payload.content = options.content;
+    if (options.embed)   payload.embeds  = [options.embed];
+
+    const reply = await interaction.reply({ ...payload, fetchReply: true });
+
+    if (!this._handler) return;
+
+    const collector = reply.createMessageComponentCollector({
+      componentType: ComponentType.StringSelect,
+      time: options.timeout ?? 60000,
+    });
+
+    collector.on("collect", async (i) => {
+      if (i.customId !== this._options.id) return;
+      try {
+        await this._handler(i, i.values);
+      } catch (err) {
+        console.error("[ChrxSelectMenu] onSelect error:", err);
+        i.reply({ content: err.message || "❌ Something went wrong.", ephemeral: true }).catch(() => {});
+      }
+    });
+
+    collector.on("end", () => {
+      reply.edit({ components: [] }).catch(() => {});
+    });
+  }
+}
+
+// ═════════════════════════════════════════════════════════════════════════════
+// ChrxPagination
+// ═════════════════════════════════════════════════════════════════════════════
+
+class ChrxPagination {
+  /**
+   * Auto paginated embed system with next/prev buttons.
+   *
+   * @param {object} options
+   * @param {EmbedBuilder[]} options.pages      Array of EmbedBuilders
+   * @param {number}  [options.timeout]         Collector timeout ms (default: 120000)
+   * @param {boolean} [options.ephemeral]
+   * @param {boolean} [options.showPageNumber]  Show "Page X/Y" in footer (default: true)
+   */
+  constructor(options = {}) {
+    if (!options.pages?.length) throw new Error("[ChrxPagination] pages array is required.");
+    this._options = options;
+    this._page    = 0;
+  }
+
+  _getButtons(page, total) {
+    const prev = new ButtonBuilder()
+      .setCustomId("chrx-page-prev")
+      .setLabel("◀")
+      .setStyle(ButtonStyle.Secondary)
+      .setDisabled(page === 0);
+
+    const next = new ButtonBuilder()
+      .setCustomId("chrx-page-next")
+      .setLabel("▶")
+      .setStyle(ButtonStyle.Secondary)
+      .setDisabled(page === total - 1);
+
+    const counter = new ButtonBuilder()
+      .setCustomId("chrx-page-counter")
+      .setLabel(`${page + 1} / ${total}`)
+      .setStyle(ButtonStyle.Primary)
+      .setDisabled(true);
+
+    return new ActionRowBuilder().addComponents(prev, counter, next);
+  }
+
+  _getPage(index) {
+    const page  = this._options.pages[index];
+    const total = this._options.pages.length;
+    if (this._options.showPageNumber !== false) {
+      page.setFooter({ text: `Page ${index + 1} of ${total}` });
+    }
+    return page;
+  }
+
+  /**
+   * Send the paginated embed.
+   */
+  async send(interaction) {
+    const total = this._options.pages.length;
+    const reply = await interaction.reply({
+      embeds: [this._getPage(0)],
+      components: total > 1 ? [this._getButtons(0, total)] : [],
+      ephemeral: this._options.ephemeral ?? false,
+      fetchReply: true,
+    });
+
+    if (total <= 1) return;
+
+    const collector = reply.createMessageComponentCollector({
+      componentType: ComponentType.Button,
+      time: this._options.timeout ?? 120000,
+    });
+
+    collector.on("collect", async (i) => {
+      if (i.user.id !== interaction.user.id) {
+        return i.reply({ content: "❌ These controls aren't for you.", ephemeral: true });
+      }
+
+      if (i.customId === "chrx-page-prev") this._page = Math.max(0, this._page - 1);
+      if (i.customId === "chrx-page-next") this._page = Math.min(total - 1, this._page + 1);
+
+      await i.update({
+        embeds: [this._getPage(this._page)],
+        components: [this._getButtons(this._page, total)],
+      });
+    });
+
+    collector.on("end", () => {
+      reply.edit({ components: [] }).catch(() => {});
+    });
+  }
+}
+
+// ═════════════════════════════════════════════════════════════════════════════
+// ChrxContextMenu
+// ═════════════════════════════════════════════════════════════════════════════
+
+class ChrxContextMenu {
+  /**
+   * Right click context menu command.
+   *
+   * @param {object} options
+   * @param {string}   options.name    Context menu name
+   * @param {string}   options.type   "user" | "message"
+   * @param {Function} options.run    Handler (interaction) => void
+   */
+  constructor(options = {}) {
+    if (!options.name) throw new Error("[ChrxContextMenu] name is required.");
+    if (!options.type) throw new Error("[ChrxContextMenu] type is required. Use 'user' or 'message'.");
+    if (!options.run)  throw new Error("[ChrxContextMenu] run function is required.");
+
+    const builder = new ContextMenuCommandBuilder()
+      .setName(options.name)
+      .setType(
+        options.type === "user"
+          ? ApplicationCommandType.User
+          : ApplicationCommandType.Message
+      );
+
+    this.data    = builder;
+    this.execute = async (interaction) => {
+      try {
+        await options.run(interaction);
+      } catch (err) {
+        console.error(`[ChrxContextMenu] Error in "${options.name}":`, err);
+        const msg = { content: err.message || "❌ Something went wrong.", ephemeral: true };
+        if (interaction.replied || interaction.deferred) {
+          interaction.followUp(msg).catch(() => {});
+        } else {
+          interaction.reply(msg).catch(() => {});
+        }
+      }
+    };
+  }
+}
+
+// ═════════════════════════════════════════════════════════════════════════════
+// ChrxMenu
+// ═════════════════════════════════════════════════════════════════════════════
+
+class ChrxMenu {
+  /**
+   * Full interactive menu — combines embed, buttons and select menus together.
+   *
+   * @param {object} options
+   * @param {object}   options.embed              Embed options for ChrxEmbedBuilder.build()
+   * @param {object[]} [options.buttons]          Array of ChrxButton-like option objects
+   * @param {object}   [options.select]           ChrxSelectMenu-like option object
+   * @param {number}   [options.timeout]          Collector timeout ms (default: 60000)
+   * @param {boolean}  [options.ephemeral]
+   */
+  constructor(options = {}) {
+    if (!options.embed) throw new Error("[ChrxMenu] embed is required.");
+    this._options = options;
+  }
+
+  async send(interaction) {
+    const { EmbedBuilder } = require("discord.js");
+    const embed = new EmbedBuilder();
+
+    if (this._options.embed.title)       embed.setTitle(this._options.embed.title);
+    if (this._options.embed.desc)        embed.setDescription(this._options.embed.desc);
+    if (this._options.embed.color)       embed.setColor(this._options.embed.color);
+    if (this._options.embed.footer)      embed.setFooter({ text: this._options.embed.footer });
+    if (this._options.embed.thumbnail)   embed.setThumbnail(this._options.embed.thumbnail);
+    if (this._options.embed.timestamp)   embed.setTimestamp();
+
+    const rows = [];
+
+    // ── Buttons ───────────────────────────────────────────────────────────
+    if (this._options.buttons?.length) {
+      const btnRow = new ActionRowBuilder();
+      const handlers = {};
+
+      for (const btnOpt of this._options.buttons) {
+        const btn = new ButtonBuilder()
+          .setLabel(btnOpt.label)
+          .setStyle(BUTTON_STYLE_MAP[btnOpt.style ?? "primary"] ?? ButtonStyle.Primary)
+          .setCustomId(btnOpt.id ?? `chrx-menu-btn-${Math.random().toString(36).slice(2, 7)}`);
+
+        if (btnOpt.emoji)    btn.setEmoji(btnOpt.emoji);
+        if (btnOpt.disabled) btn.setDisabled(true);
+
+        handlers[btnOpt.id] = btnOpt.onClick;
+        btnRow.addComponents(btn);
+      }
+
+      rows.push(btnRow);
+
+      const reply = await interaction.reply({
+        embeds: [embed],
+        components: rows,
+        ephemeral: this._options.ephemeral ?? false,
+        fetchReply: true,
+      });
+
+      const collector = reply.createMessageComponentCollector({
+        time: this._options.timeout ?? 60000,
+      });
+
+      collector.on("collect", async (i) => {
+        const handler = handlers[i.customId];
+        if (handler) {
+          try {
+            await handler(i);
+          } catch (err) {
+            i.reply({ content: err.message || "❌ Error.", ephemeral: true }).catch(() => {});
+          }
+        }
+      });
+
+      collector.on("end", () => {
+        reply.edit({ components: [] }).catch(() => {});
+      });
+
+      return;
+    }
+
+    // ── Select only ───────────────────────────────────────────────────────
+    if (this._options.select) {
+      const menu = new ChrxSelectMenu(this._options.select);
+      rows.push(menu.toRow());
+      await interaction.reply({
+        embeds: [embed],
+        components: rows,
+        ephemeral: this._options.ephemeral ?? false,
+      });
+      return;
+    }
+
+    // ── Embed only ────────────────────────────────────────────────────────
+    await interaction.reply({
+      embeds: [embed],
+      ephemeral: this._options.ephemeral ?? false,
+    });
+  }
+}
+
+// ═════════════════════════════════════════════════════════════════════════════
+// ChrxForm
+// ═════════════════════════════════════════════════════════════════════════════
+
+class ChrxForm {
+  /**
+   * Combines a modal AND processes the response in one block.
+   * No need to set up onModalSubmit separately.
+   *
+   * @param {object} options
+   * @param {string}   options.id       Modal ID
+   * @param {string}   options.title    Modal title
+   * @param {object[]} options.inputs   Same as ChrxModalBuilder inputs
+   * @param {Function} options.onSubmit (interaction, values) => void
+   *                   values is an object keyed by input id e.g. { answer: "yes" }
+   */
+  constructor(options = {}) {
+    if (!options.id)       throw new Error("[ChrxForm] id is required.");
+    if (!options.title)    throw new Error("[ChrxForm] title is required.");
+    if (!options.inputs?.length) throw new Error("[ChrxForm] inputs are required.");
+    if (!options.onSubmit) throw new Error("[ChrxForm] onSubmit is required.");
+
+    this._options = options;
+    this._modal   = null;
+
+    // Build the modal
+    const {
+      ModalBuilder,
+      TextInputBuilder,
+      TextInputStyle,
+      ActionRowBuilder,
+    } = require("discord.js");
+
+    const STYLE_MAP = {
+      short:     TextInputStyle.Short,
+      paragraph: TextInputStyle.Paragraph,
+      long:      TextInputStyle.Paragraph,
+    };
+
+    const modal = new ModalBuilder()
+      .setCustomId(options.id)
+      .setTitle(options.title);
+
+    const rows = options.inputs.map((input) => {
+      const textInput = new TextInputBuilder()
+        .setCustomId(input.id)
+        .setLabel(input.label)
+        .setStyle(STYLE_MAP[input.type ?? "short"] ?? TextInputStyle.Short);
+
+      if (input.required)    textInput.setRequired(input.required);
+      if (input.placeholder) textInput.setPlaceholder(input.placeholder);
+      if (input.value)       textInput.setValue(input.value);
+      if (input.minLength)   textInput.setMinLength(input.minLength);
+      if (input.maxLength)   textInput.setMaxLength(input.maxLength);
+
+      return new ActionRowBuilder().addComponents(textInput);
+    });
+
+    modal.addComponents(...rows);
+    this._modal = modal;
+  }
+
+  /**
+   * Show the form and handle submission automatically.
+   * @param {import("discord.js").CommandInteraction} interaction
+   */
+  async show(interaction) {
+    await interaction.showModal(this._modal);
+
+    try {
+      const submitted = await interaction.awaitModalSubmit({
+        time: 300000, // 5 minutes to fill out the form
+        filter: (i) => i.customId === this._options.id && i.user.id === interaction.user.id,
+      });
+
+      // Build values object keyed by input id
+      const values = {};
+      for (const input of this._options.inputs) {
+        values[input.id] = submitted.fields.getTextInputValue(input.id);
+      }
+
+      try {
+        await this._options.onSubmit(submitted, values);
+      } catch (err) {
+        console.error(`[ChrxForm] onSubmit error:`, err);
+        const msg = { content: err.message || "❌ Something went wrong.", ephemeral: true };
+        if (submitted.replied || submitted.deferred) {
+          submitted.followUp(msg).catch(() => {});
+        } else {
+          submitted.reply(msg).catch(() => {});
+        }
+      }
+    } catch {
+      // User didn't submit in time — silently ignore
+    }
+  }
+}
+
+// ═════════════════════════════════════════════════════════════════════════════
+// ChrxConfirm
+// ═════════════════════════════════════════════════════════════════════════════
+
+class ChrxConfirm {
+  /**
+   * Yes/No confirmation prompt in two lines.
+   *
+   * @param {object} options
+   * @param {string}   options.question          Question to ask
+   * @param {Function} options.onConfirm         Called when user clicks Yes
+   * @param {Function} [options.onCancel]        Called when user clicks No
+   * @param {string}   [options.confirmLabel]    Yes button label (default: "Confirm")
+   * @param {string}   [options.cancelLabel]     No button label (default: "Cancel")
+   * @param {string}   [options.color]           Embed color (default: #5865F2)
+   * @param {boolean}  [options.ephemeral]
+   * @param {number}   [options.timeout]         ms before auto cancel (default: 30000)
+   */
+  constructor(options = {}) {
+    if (!options.question)  throw new Error("[ChrxConfirm] question is required.");
+    if (!options.onConfirm) throw new Error("[ChrxConfirm] onConfirm is required.");
+    this._options = options;
+  }
+
+  /**
+   * Send the confirmation prompt.
+   */
+  async send(interaction) {
+    const confirmId = `chrx-confirm-yes-${Math.random().toString(36).slice(2, 7)}`;
+    const cancelId  = `chrx-confirm-no-${Math.random().toString(36).slice(2, 7)}`;
+
+    const embed = new EmbedBuilder()
+      .setColor(this._options.color ?? "#5865F2")
+      .setDescription(`❓ ${this._options.question}`);
+
+    const row = new ActionRowBuilder().addComponents(
+      new ButtonBuilder()
+        .setCustomId(confirmId)
+        .setLabel(this._options.confirmLabel ?? "Confirm")
+        .setStyle(ButtonStyle.Success),
+      new ButtonBuilder()
+        .setCustomId(cancelId)
+        .setLabel(this._options.cancelLabel ?? "Cancel")
+        .setStyle(ButtonStyle.Danger)
+    );
+
+    const reply = await interaction.reply({
+      embeds: [embed],
+      components: [row],
+      ephemeral: this._options.ephemeral ?? false,
+      fetchReply: true,
+    });
+
+    const collector = reply.createMessageComponentCollector({
+      componentType: ComponentType.Button,
+      time: this._options.timeout ?? 30000,
+      max: 1,
+    });
+
+    collector.on("collect", async (i) => {
+      if (i.user.id !== interaction.user.id) {
+        return i.reply({ content: "❌ This isn't your confirmation.", ephemeral: true });
+      }
+
+      try {
+        if (i.customId === confirmId) {
+          await this._options.onConfirm(i);
+        } else {
+          if (this._options.onCancel) {
+            await this._options.onCancel(i);
+          } else {
+            await i.update({ embeds: [embed.setDescription("❌ Cancelled.").setColor("#ED4245")], components: [] });
+          }
+        }
+      } catch (err) {
+        console.error("[ChrxConfirm] Error:", err);
+        i.reply({ content: err.message || "❌ Something went wrong.", ephemeral: true }).catch(() => {});
+      }
+    });
+
+    collector.on("end", (collected) => {
+      if (collected.size === 0) {
+        reply.edit({
+          embeds: [embed.setDescription("⏱ Confirmation timed out.").setColor("#ED4245")],
+          components: [],
+        }).catch(() => {});
+      }
+    });
+  }
+}
+
+// ═════════════════════════════════════════════════════════════════════════════
+// Exports
+// ═════════════════════════════════════════════════════════════════════════════
+
+module.exports = {
+  ChrxButton,
+  ChrxSelectMenu,
+  ChrxPagination,
+  ChrxContextMenu,
+  ChrxMenu,
+  ChrxForm,
+  ChrxConfirm,
+};

package/core/ChrxEmbedBuilder.js

@@ -0,0 +1,127 @@
+/**
+ * core/ChrxEmbedBuilder.js
+ * Simple and Advanced embed builder.
+ *
+ * Simple mode  → key/value syntax (title, desc, color)
+ * AdvancedEmbed → parses raw JSON or HTML-like string into a full embed
+ */
+
+const { EmbedBuilder } = require("discord.js");
+
+class ChrxEmbedBuilder {
+  /**
+   * Simple mode — just pass title, desc, color etc.
+   * @param {object} options
+   * @param {string} [options.title]
+   * @param {string} [options.desc]
+   * @param {string} [options.color]
+   * @param {string} [options.thumbnail]
+   * @param {string} [options.image]
+   * @param {string} [options.footer]
+   * @param {boolean} [options.timestamp]
+   * @param {object[]} [options.fields]  [{ name, value, inline? }]
+   */
+  static build(options = {}) {
+    const embed = new EmbedBuilder();
+
+    if (options.title)     embed.setTitle(options.title);
+    if (options.desc)      embed.setDescription(options.desc);
+    if (options.color)     embed.setColor(options.color);
+    if (options.thumbnail) embed.setThumbnail(options.thumbnail);
+    if (options.image)     embed.setImage(options.image);
+    if (options.footer)    embed.setFooter({ text: options.footer });
+    if (options.timestamp) embed.setTimestamp();
+    if (options.fields)    embed.addFields(options.fields);
+
+    return embed;
+  }
+
+  /**
+   * AdvancedEmbed — reads raw JSON string or HTML-like string and parses it.
+   * Supports both:
+   *   - JSON: { "title": "Hi", "desc": "ok bro", "color": "#5865F2", ... }
+   *   - HTML-like: <title>Hi</title><desc>ok bro</desc><color>#5865F2</color>
+   *
+   * @param {string|object} input  Raw JSON string, HTML-like string, or plain object
+   * @returns {EmbedBuilder}
+   */
+  static advanced(input) {
+    let data = {};
+
+    if (typeof input === "object") {
+      // Already a plain object
+      data = input;
+
+    } else if (typeof input === "string") {
+      // Try JSON first
+      try {
+        data = JSON.parse(input);
+      } catch {
+        // Fall back to HTML-like tag parser
+        data = ChrxEmbedBuilder._parseHTML(input);
+      }
+    }
+
+    return ChrxEmbedBuilder.build(data);
+  }
+
+  /**
+   * Parse HTML-like tag syntax into a plain object.
+   * Supports: <title> <desc> <color> <thumbnail> <image> <footer> <timestamp> <field>
+   *
+   * Example input:
+   * <title>Hello!</title>
+   * <desc>This is my embed</desc>
+   * <color>#5865F2</color>
+   * <field name="Field 1" value="Value 1" inline="true"/>
+   */
+  static _parseHTML(html) {
+    const data = {};
+
+    const extract = (tag) => {
+      const match = html.match(new RegExp(`<${tag}[^>]*>(.*?)<\\/${tag}>`, "si"));
+      return match ? match[1].trim() : null;
+    };
+
+    data.title     = extract("title")     || undefined;
+    data.desc      = extract("desc")      || extract("description") || undefined;
+    data.color     = extract("color")     || undefined;
+    data.thumbnail = extract("thumbnail") || undefined;
+    data.image     = extract("image")     || undefined;
+    data.footer    = extract("footer")    || undefined;
+    data.timestamp = html.includes("<timestamp") ? true : undefined;
+
+    // Parse <field name="x" value="y" inline="true"/> tags
+    const fieldRegex = /<field\s+name="([^"]+)"\s+value="([^"]+)"(?:\s+inline="(true|false)")?[^/]*\/>/gi;
+    const fields = [];
+    let fieldMatch;
+    while ((fieldMatch = fieldRegex.exec(html)) !== null) {
+      fields.push({
+        name: fieldMatch[1],
+        value: fieldMatch[2],
+        inline: fieldMatch[3] === "true",
+      });
+    }
+    if (fields.length > 0) data.fields = fields;
+
+    return data;
+  }
+}
+
+/**
+ * EmbedTrigger — fires a ChrxEmbedBuilder embed in a reply/send.
+ * Drop this anywhere in a ChrxCommandBuilder run() function.
+ *
+ * @param {import("discord.js").CommandInteraction} interaction
+ * @param {EmbedBuilder} embed
+ * @param {object} [options]
+ * @param {boolean} [options.ephemeral]
+ */
+async function EmbedTrigger(interaction, embed, options = {}) {
+  if (interaction.replied || interaction.deferred) {
+    return interaction.followUp({ embeds: [embed], ephemeral: options.ephemeral ?? false });
+  }
+  return interaction.reply({ embeds: [embed], ephemeral: options.ephemeral ?? false });
+}
+
+module.exports = { ChrxEmbedBuilder, EmbedTrigger };

package/core/ChrxModalBuilder.js

@@ -0,0 +1,151 @@
+/**
+ * core/ChrxModalBuilder.js
+ * Simple modal builder with built in validation and rate limiting.
+ */
+
+const {
+  ModalBuilder,
+  TextInputBuilder,
+  TextInputStyle,
+  ActionRowBuilder,
+} = require("discord.js");
+
+// ── Rate limiter ──────────────────────────────────────────────────────────
+// Tracks how many modals a user has triggered in the last minute
+const modalRateLimit = new Map(); // userId -> { count, resetAt }
+const RATE_LIMIT     = 50;        // max modals per minute per user
+
+function checkRateLimit(userId) {
+  const now  = Date.now();
+  const data = modalRateLimit.get(userId);
+
+  if (!data || now > data.resetAt) {
+    modalRateLimit.set(userId, { count: 1, resetAt: now + 60000 });
+    return true;
+  }
+
+  if (data.count >= RATE_LIMIT) return false;
+
+  data.count++;
+  return true;
+}
+
+// ── Type map ──────────────────────────────────────────────────────────────
+const STYLE_MAP = {
+  short:     TextInputStyle.Short,
+  paragraph: TextInputStyle.Paragraph,
+  long:      TextInputStyle.Paragraph, // alias
+};
+
+class ChrxModalBuilder {
+  /**
+   * @param {object} options
+   * @param {string}   options.name          Internal name (for reference)
+   * @param {string}   options.id            Modal custom ID
+   * @param {string}   options.title         Modal title (max 45 chars)
+   * @param {object[]} options.inputs        Input fields (max 5)
+   * @param {string}   options.inputs[].id       Input custom ID
+   * @param {string}   options.inputs[].label     Input label (max 100 chars)
+   * @param {string}   [options.inputs[].type]    "short" | "paragraph" (default: short)
+   * @param {boolean}  [options.inputs[].required] Required? (default: false)
+   * @param {string}   [options.inputs[].placeholder] Placeholder text
+   * @param {string}   [options.inputs[].value]   Pre-filled value
+   * @param {number}   [options.inputs[].minLength]
+   * @param {number}   [options.inputs[].maxLength]
+   */
+  constructor(options = {}) {
+    if (!options.id)     throw new Error("[ChrxModal] id is required.");
+    if (!options.title)  throw new Error("[ChrxModal] title is required.");
+    if (!options.inputs || options.inputs.length === 0) throw new Error("[ChrxModal] At least one input is required.");
+
+    // ── Validation ────────────────────────────────────────────────────────
+    if (options.title.length > 45) {
+      throw new Error(`[ChrxModal] Title exceeds 45 characters (got ${options.title.length}).`);
+    }
+    if (options.inputs.length > 5) {
+      throw new Error(`[ChrxModal] Maximum 5 inputs allowed (got ${options.inputs.length}).`);
+    }
+    for (const input of options.inputs) {
+      if (!input.id)    throw new Error("[ChrxModal] Every input must have an id.");
+      if (!input.label) throw new Error("[ChrxModal] Every input must have a label.");
+      if (input.label.length > 100) {
+        throw new Error(`[ChrxModal] Input label "${input.label}" exceeds 100 characters.`);
+      }
+    }
+
+    this._options = options;
+    this.name     = options.name ?? options.id;
+  }
+
+  /**
+   * Build and return the raw discord.js Modal.
+   * @returns {ModalBuilder}
+   */
+  build() {
+    const modal = new ModalBuilder()
+      .setCustomId(this._options.id)
+      .setTitle(this._options.title);
+
+    const rows = this._options.inputs.map((input) => {
+      const textInput = new TextInputBuilder()
+        .setCustomId(input.id)
+        .setLabel(input.label)
+        .setStyle(STYLE_MAP[input.type ?? "short"] ?? TextInputStyle.Short);
+
+      if (input.required)    textInput.setRequired(input.required);
+      if (input.placeholder) textInput.setPlaceholder(input.placeholder);
+      if (input.value)       textInput.setValue(input.value);
+      if (input.minLength)   textInput.setMinLength(input.minLength);
+      if (input.maxLength)   textInput.setMaxLength(input.maxLength);
+
+      return new ActionRowBuilder().addComponents(textInput);
+    });
+
+    modal.addComponents(...rows);
+    return modal;
+  }
+}
+
+/**
+ * ModalTrigger — shows a ChrxModalBuilder modal to the user.
+ * Handles rate limiting automatically.
+ *
+ * @param {import("discord.js").CommandInteraction} interaction
+ * @param {ChrxModalBuilder} modal
+ */
+async function ModalTrigger(interaction, modal) {
+  if (!checkRateLimit(interaction.user.id)) {
+    return interaction.reply({
+      content: "⏱ You're triggering too many modals! Slow down.",
+      ephemeral: true,
+    });
+  }
+
+  await interaction.showModal(modal.build());
+}
+
+/**
+ * onModalSubmit — listen for a modal submission by ID.
+ * @param {import("discord.js").Client} client
+ * @param {string} modalId
+ * @param {Function} handler  (interaction) => void
+ */
+function onModalSubmit(client, modalId, handler) {
+  client.on("interactionCreate", async (interaction) => {
+    if (!interaction.isModalSubmit()) return;
+    if (interaction.customId !== modalId) return;
+    try {
+      await handler(interaction);
+    } catch (err) {
+      console.error(`[ChrxModal] Error in modal "${modalId}":`, err);
+      const msg = { content: err.message || "❌ Something went wrong.", ephemeral: true };
+      if (interaction.replied || interaction.deferred) {
+        interaction.followUp(msg).catch(() => {});
+      } else {
+        interaction.reply(msg).catch(() => {});
+      }
+    }
+  });
+}
+
+module.exports = { ChrxModalBuilder, ModalTrigger, onModalSubmit };

package/index.js

@@ -1,15 +1,25 @@
 /**
- * index.js (not for a discord bot)
- * Main entry point, will ALWAYS export everything.
- * Listen to Project4play / SVJ at SoundCloud NOW! 
+ * index.js
+ * Main entry point — exports everything.
  */
 
-const { ChrxClient } = require("./core/Client");
-const Database = require("./core/Database");
-const XPSystem = require("./core/XPSystem");
-const AIWrapper = require("./core/AIWrapper");
-const MusicManager = require("./core/MusicManager");
-const ChrxCommandBuilder = require("./core/ChrxCommandBuilder");
+const { ChrxClient }         = require("./core/Client");
+const Database               = require("./core/Database");
+const XPSystem               = require("./core/XPSystem");
+const AIWrapper              = require("./core/AIWrapper");
+const MusicManager           = require("./core/MusicManager");
+const ChrxCommandBuilder     = require("./core/ChrxCommandBuilder");
+const { ChrxEmbedBuilder, EmbedTrigger } = require("./core/ChrxEmbedBuilder");
+const { ChrxModalBuilder, ModalTrigger, onModalSubmit } = require("./core/ChrxModalBuilder");
+const {
+  ChrxButton,
+  ChrxSelectMenu,
+  ChrxPagination,
+  ChrxContextMenu,
+  ChrxMenu,
+  ChrxForm,
+  ChrxConfirm,
+} = require("./core/ChrxComponentsV3");
 const {
   parseTime,
   formatTime,
@@ -37,6 +47,22 @@ module.exports = {
   ChrxClient,
   ChrxCommandBuilder,
 
+  // Embed & Modal
+  ChrxEmbedBuilder,
+  EmbedTrigger,
+  ChrxModalBuilder,
+  ModalTrigger,
+  onModalSubmit,
+
+  // Components V3
+  ChrxButton,
+  ChrxSelectMenu,
+  ChrxPagination,
+  ChrxContextMenu,
+  ChrxMenu,
+  ChrxForm,
+  ChrxConfirm,
+
   // Modules
   Database,
   XPSystem,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chrxmaticc-framework",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "A batteries-included Discord bot framework with music, AI, XP and database support.",
   "main": "index.js",
   "files": [