@kevlid/discordmenus 0.0.2

package/src/menuBuilder.js

@@ -0,0 +1,157 @@
+const { Builder } = require("./builder");
+const { OptionTypes } = require("./utils/types");
+const { CategoryBuilder } = require("./options/category");
+const { StringBuilder } = require("./options/string");
+const { NumberBuilder } = require("./options/number");
+const { BooleanBuilder } = require("./options/boolean");
+const { StringListBuilder, NumberListBuilder, ObjectListBuilder } = require("./options/list");
+const { ObjectBuilder } = require("./options/object");
+const { StringSelectBuilder, UserSelectBuilder, RoleSelectBuilder, MentionableSelectBuilder, ChannelSelectBuilder } = require("./options/selectMenu");
+
+
+class MenuBuilder extends Builder {
+    constructor() {
+        super(OptionTypes.Menu, 2);
+        this.categories = [];
+    }
+
+    #addBuilder(builder) {
+        const latestCategory = this.categories[this.categories.length - 1];
+        if (latestCategory) {
+            latestCategory.addOptions(builder);
+        } else {
+            throw new Error("You need to create a category before adding options");
+        }
+    }
+
+    setGetMethod(method) {
+        if (typeof method !== "function") throw new TypeError("Get method must be a function");
+        this.getMethod = method;
+        return this;
+    }
+
+    setSaveMethod(method) {
+        if (typeof method !== "function") throw new TypeError("Save method must be a function");
+        this.saveMethod = method;
+        return this;
+    }
+
+    setPermissions(permissions) {
+        if (!Array.isArray(permissions)) throw new TypeError("Permissions must be an array");
+        this.permissions = permissions.map(entry => {
+            if (Array.isArray(entry)) {
+                return entry;
+            }
+            return [entry];
+        });
+        return this;
+    }
+
+    createCategory(callback) {
+        const builder = new CategoryBuilder();
+        callback(builder);
+        this.categories.push(builder);
+        return this;
+    }
+
+    addString(callback) {
+        const builder = new StringBuilder();
+        callback(builder);
+        this.#addBuilder(builder);
+        return this;
+    }
+
+    addNumber(callback) {
+        const builder = new NumberBuilder();
+        callback(builder);
+        this.#addBuilder(builder);
+        return this;
+    }
+
+    addBoolean(callback) {
+        const builder = new BooleanBuilder();
+        callback(builder);
+        this.#addBuilder(builder);
+        return this;
+    }
+
+    addStringList(callback) {
+        const builder = new StringListBuilder();
+        callback(builder);
+        this.#addBuilder(builder);
+        return this;
+    }
+
+    addNumberList(callback) {
+        const builder = new NumberListBuilder();
+        callback(builder);
+        this.#addBuilder(builder);
+        return this;
+    }
+
+    addObject(callback) {
+        const builder = new ObjectBuilder();
+        callback(builder);
+        this.#addBuilder(builder);
+        return this;
+    }
+
+    addObjectList(callback) {
+        const builder = new ObjectListBuilder();
+        callback(builder);
+        this.#addBuilder(builder);
+        return this;
+    }
+
+    addStringSelect(callback) {
+        const builder = new StringSelectBuilder();
+        callback(builder);
+        this.#addBuilder(builder);
+        return this;
+    }
+
+    addUserSelect(callback) {
+        const builder = new UserSelectBuilder();
+        callback(builder);
+        this.#addBuilder(builder);
+        return this;
+    }
+
+    addRoleSelect(callback) {
+        const builder = new RoleSelectBuilder();
+        callback(builder);
+        this.#addBuilder(builder);
+        return this;
+    }
+
+    addMentionableSelect(callback) {
+        const builder = new MentionableSelectBuilder();
+        callback(builder);
+        this.#addBuilder(builder);
+        return this;
+    }
+
+    addChannelSelect(callback) {
+        const builder = new ChannelSelectBuilder();
+        callback(builder);
+        this.#addBuilder(builder);
+        return this;
+    }
+
+    build() {
+        const base = super.build();
+        let permissions;
+        if (this.permissions) {
+            permissions = this.permissions;
+        } else {
+            permissions = [];
+        }
+        return {
+            ...base,
+            permissions,
+            categories: this.categories.map(category => category.build()),
+        };
+    }
+}
+
+module.exports = { MenuBuilder };

package/src/menuInstance.js

@@ -0,0 +1,334 @@
+const { renderNavigation, renderContainer, renderOption } = require("./render/page");
+const { renderModal, renderTextInput } = require("./render/modal");
+const { renderListPage, renderListTextInput, renderObjectListItemPage, renderObjectListItemTextInput } = require("./render/list");
+const { renderObjectPage, renderObjectTextInput, renderObjectListPage, renderObjectListTextInput } = require("./render/object");
+const { OptionTypes } = require("./utils/types");
+const { PageRenderOverhead, OptionRenderCost, MaxComponents, ComponentsV2MessageFlags } = require("./utils/constants");
+const { validateComponents } = require("./utils/componentsValidate");
+const { arrayClone, normalizeObjectListItems, objectListItemsNeedReshape } = require("./utils/helpers");
+
+class MenuInstance {
+    constructor(builder, options = {}) {
+        this.key = builder.key;
+        this.title = builder.title;
+        this.pages = [];
+        this.permissions = builder.permissions ?? [];
+
+        if (builder.getMethod && !options.get) {
+            options.get = builder.getMethod;
+            builder.getMethod = null;
+        }
+        if (builder.saveMethod && !options.save) {
+            options.save = builder.saveMethod;
+            builder.saveMethod = null;
+        }
+        if (!options.get) {
+            throw new Error("You must provide a get function in the options");
+        }
+        if (typeof options.get !== "function") {
+            throw new TypeError("get must be a function");
+        }
+        if (!options.save) {
+            throw new Error("You must provide a save function in the options");
+        }
+        if (typeof options.save !== "function") {
+            throw new TypeError("save must be a function");
+        }
+
+        this.getData = options.get;
+        this.saveData = options.save;
+        this.builder = builder;
+    }
+
+    async get(key, ctx = {}) {
+        return this.getData(key, ctx);
+    }
+
+    async save(key, value, ctx = {}) {
+        return this.saveData(key, value, ctx);
+    }
+
+    ensureBuilt() {
+        if (this.pages.length === 0) {
+            this.build();
+        }
+    }
+
+    build() {
+        const built = this.builder.build();
+        this.pages = [];
+
+        for (const category of built.categories) {
+            const categoryPages = [];
+            let currentCost = 0;
+
+            const newPage = () => {
+                currentCost = PageRenderOverhead;
+                return { title: built.title, description: category.title, options: [] };
+            };
+
+            let currentPage = newPage();
+
+            for (const option of category.options) {
+                if (currentCost + OptionRenderCost > MaxComponents) {
+                    categoryPages.push(currentPage);
+                    currentPage = newPage();
+                }
+                currentPage.options.push(option);
+                currentCost += OptionRenderCost;
+            }
+
+            if (currentPage.options.length > 0) {
+                categoryPages.push(currentPage);
+            }
+            if (categoryPages.length > 0) {
+                this.pages.push(categoryPages);
+            }
+        }
+
+        for (const categoryPages of this.pages) {
+            for (const page of categoryPages) {
+                if (page.options) {
+                    validateComponents(page.options);
+                }
+            }
+        }
+    }
+
+    getOption(category, index, optionKey) {
+        const categoryPages = this.pages[category];
+        if (!categoryPages) {
+            return null;
+        }
+        const page = categoryPages[index];
+        if (!page) {
+            return null;
+        }
+        return page.options.find(o => o.key === optionKey) ?? null;
+    }
+
+    getNavigationTargets(category, index) {
+        const categoryPages = this.pages[category];
+        const hasPrevCategory = category > 0;
+        const hasNextCategory = category < this.pages.length - 1;
+        const hasPrevPage = index > 0;
+        const hasNextPage = index < categoryPages.length - 1;
+
+        let previousCategory = null;
+        if (hasPrevCategory) {
+            previousCategory = { cat: category - 1, page: 0 };
+        }
+        let nextCategory = null;
+        if (hasNextCategory) {
+            nextCategory = { cat: category + 1, page: 0 };
+        }
+
+        let previousPage = null;
+        if (hasPrevPage) {
+            previousPage = { cat: category, page: index - 1 };
+        } else if (hasPrevCategory) {
+            previousPage = { cat: category - 1, page: this.pages[category - 1].length - 1 };
+        }
+
+        let nextPage = null;
+        if (hasNextPage) {
+            nextPage = { cat: category, page: index + 1 };
+        } else if (hasNextCategory) {
+            nextPage = { cat: category + 1, page: 0 };
+        }
+
+        return { previousCategory, nextCategory, previousPage, nextPage };
+    }
+
+    async renderPage({ category = 0, index = 0, userId, guildId } = {}) {
+        this.ensureBuilt();
+
+        if (category < 0 || category >= this.pages.length) {
+            throw new RangeError(`Category ${category} out of range (0-${this.pages.length - 1})`);
+        }
+        const categoryPages = this.pages[category];
+        if (index < 0 || index >= categoryPages.length) {
+            throw new RangeError(`Page ${index} out of range in category ${category} (0-${categoryPages.length - 1})`);
+        }
+
+        const page = categoryPages[index];
+        const ctx = { guildId, userId };
+        const navigation = renderNavigation(this.key, userId, this.getNavigationTargets(category, index), category, index);
+        const optionComponents = [];
+        for (const option of page.options) {
+            const value = await this.get(option.key, ctx);
+            optionComponents.push(...renderOption(this.key, option, value, userId, category, index));
+        }
+        const container = renderContainer({
+            title: page.title,
+            description: page.description,
+            components: optionComponents,
+        });
+        return {
+            flags: ComponentsV2MessageFlags,
+            components: [container, navigation],
+        };
+    }
+
+    async renderModal(optionKey, { category = 0, index = 0, guildId, userId } = {}) {
+        this.ensureBuilt();
+        const categoryPages = this.pages[category];
+        if (!categoryPages) {
+            throw new RangeError(`Category ${category} does not exist`);
+        }
+        const page = categoryPages[index];
+        if (!page) {
+            throw new RangeError(`Page ${index} does not exist in category ${category}`);
+        }
+        const option = page.options.find(o => o.key === optionKey);
+        if (!option) {
+            throw new Error(`Option "${optionKey}" not found on page ${category}:${index}`);
+        }
+        const currentValue = await this.get(option.key, { guildId, userId });
+        return renderModal(this.key, this.title, [renderTextInput(option, currentValue)], { category, page: index });
+    }
+
+    async renderListPage(optionKey, listPage, { category = 0, index = 0, userId, guildId } = {}) {
+        this.ensureBuilt();
+        const option = this.getOption(category, index, optionKey);
+        if (!option) {
+            throw new Error(`Option "${optionKey}" not found on page ${category}:${index}`);
+        }
+        let items = await this.get(option.key, { guildId, userId }) ?? [];
+        if (option.itemType === OptionTypes.Object) {
+            const props = option.itemConfig.properties;
+            if (objectListItemsNeedReshape(props, items)) {
+                items = normalizeObjectListItems(props, arrayClone(items));
+                await this.save(option.key, items, { guildId, userId });
+            }
+        }
+        return renderListPage(this.key, option, items, listPage, userId, category, index);
+    }
+
+    async renderListModal(optionKey, itemIndex, { category = 0, index = 0, sub = 0, guildId, userId } = {}) {
+        this.ensureBuilt();
+        const option = this.getOption(category, index, optionKey);
+        if (!option) {
+            throw new Error(`Option "${optionKey}" not found on page ${category}:${index}`);
+        }
+        const items = await this.get(option.key, { guildId, userId }) ?? [];
+        const currentValue = itemIndex != null ? items[itemIndex] : null;
+        return renderModal(
+            this.key,
+            this.title,
+            [renderListTextInput(option, currentValue, itemIndex)],
+            { category, page: index, sub, item: itemIndex ?? -1 },
+        );
+    }
+
+    async renderObjectPage(objectKey, { category = 0, index = 0, userId, guildId, objectPage = 0 } = {}) {
+        this.ensureBuilt();
+        const option = this.getOption(category, index, objectKey);
+        if (!option) {
+            throw new Error(`Object "${objectKey}" not found on page ${category}:${index}`);
+        }
+        const objectValue = await this.get(option.key, { guildId, userId }) ?? {};
+        return renderObjectPage(this.key, option, objectValue, userId, category, index, objectPage);
+    }
+
+    async renderObjectModal(objectKey, subKey, { category = 0, index = 0, guildId, userId, objectPage = 0 } = {}) {
+        this.ensureBuilt();
+        const option = this.getOption(category, index, objectKey);
+        if (!option) {
+            throw new Error(`Object "${objectKey}" not found on page ${category}:${index}`);
+        }
+        const subOption = option.options.find(o => o.key === subKey);
+        if (!subOption) {
+            throw new Error(`Sub-option "${subKey}" not found in Object "${objectKey}"`);
+        }
+        const objectValue = await this.get(objectKey, { guildId, userId }) ?? {};
+        const currentValue = objectValue[subKey] != null ? objectValue[subKey] : null;
+        return renderModal(
+            this.key,
+            this.title,
+            [renderObjectTextInput(objectKey, subOption, currentValue)],
+            { category, page: index, op: objectPage },
+        );
+    }
+
+    async renderObjectListPage(objectKey, subKey, listPage, { category = 0, index = 0, userId, guildId, objectPage = 0 } = {}) {
+        this.ensureBuilt();
+        const option = this.getOption(category, index, objectKey);
+        if (!option) {
+            throw new Error(`Object "${objectKey}" not found on page ${category}:${index}`);
+        }
+        const subOption = option.options.find(o => o.key === subKey);
+        if (!subOption) {
+            throw new Error(`Sub-option "${subKey}" not found in Object "${objectKey}"`);
+        }
+        const objectValue = await this.get(objectKey, { guildId, userId }) ?? {};
+        const items = Array.isArray(objectValue[subKey]) ? objectValue[subKey] : [];
+        return renderObjectListPage(this.key, option, subOption, items, listPage, userId, category, index, objectPage);
+    }
+
+    async renderListObjectItemPage(optionKey, itemIndex, { category = 0, index = 0, userId, guildId, listPage = 0 } = {}) {
+        this.ensureBuilt();
+        const option = this.getOption(category, index, optionKey);
+        if (!option) {
+            throw new Error(`Option "${optionKey}" not found on page ${category}:${index}`);
+        }
+        let items = await this.get(option.key, { guildId, userId }) ?? [];
+        if (option.itemType === OptionTypes.Object) {
+            const props = option.itemConfig.properties;
+            if (objectListItemsNeedReshape(props, items)) {
+                items = normalizeObjectListItems(props, arrayClone(items));
+                await this.save(option.key, items, { guildId, userId });
+            }
+        }
+        const safeIndex = items.length <= 0 ? 0 : Math.max(0, Math.min(itemIndex, items.length - 1));
+        const currentItem = items[safeIndex] ?? null;
+        return renderObjectListItemPage(this.key, option, safeIndex, currentItem, userId, category, index, listPage, items.length);
+    }
+
+    async renderListObjectItemModal(optionKey, propertyKey, itemIndex, { category = 0, index = 0, sub = 0, guildId, userId } = {}) {
+        this.ensureBuilt();
+        const option = this.getOption(category, index, optionKey);
+        if (!option) {
+            throw new Error(`Option "${optionKey}" not found on page ${category}:${index}`);
+        }
+        const property = option.itemConfig.properties.find(p => p.key === propertyKey);
+        if (!property) {
+            throw new Error(`Property "${propertyKey}" not found in ObjectList "${optionKey}"`);
+        }
+        const items = await this.get(option.key, { guildId, userId }) ?? [];
+        const currentItem = items[itemIndex] ?? null;
+        const currentValue =
+            currentItem != null && typeof currentItem === "object"
+                ? currentItem[propertyKey] ?? null
+                : null;
+        return renderModal(
+            this.key,
+            this.title,
+            [renderObjectListItemTextInput(option, property, currentValue)],
+            { category, page: index, sub, item: itemIndex },
+        );
+    }
+
+    async renderObjectListModal(objectKey, subKey, itemIndex, { category = 0, index = 0, sub = 0, guildId, userId, objectPage = 0 } = {}) {
+        this.ensureBuilt();
+        const option = this.getOption(category, index, objectKey);
+        if (!option) {
+            throw new Error(`Object "${objectKey}" not found on page ${category}:${index}`);
+        }
+        const subOption = option.options.find(o => o.key === subKey);
+        if (!subOption) {
+            throw new Error(`Sub-option "${subKey}" not found in Object "${objectKey}"`);
+        }
+        const objectValue = await this.get(objectKey, { guildId, userId }) ?? {};
+        const items = Array.isArray(objectValue[subKey]) ? objectValue[subKey] : [];
+        const currentValue = itemIndex != null ? items[itemIndex] : null;
+        return renderModal(
+            this.key,
+            this.title,
+            [renderObjectListTextInput(objectKey, subOption, currentValue, itemIndex)],
+            { category, page: index, sub, item: itemIndex ?? -1, op: objectPage },
+        );
+    }
+}
+
+module.exports = { MenuInstance };

package/src/menuManager.js

@@ -0,0 +1,83 @@
+const { MenuInstance } = require("./menuInstance");
+const { decodeId } = require("./utils/customIds");
+const { EphemeralMessageFlag } = require("./utils/constants");
+const { InteractionTypes, ResponseTypes } = require("./utils/types");
+const { handleComponent } = require("./handle/component");
+const { handleModal } = require("./handle/modal");
+const { normalizeInteraction } = require("./utils/adapters");
+
+class MenuManager {
+    constructor() {
+        this.menus = new Map();
+    }
+
+    async registerMenu(menu, options = {}) {
+        if (this.menus.has(menu.key)) {
+            throw new Error(`Menu with key ${menu.key} already exists`);
+        }
+        const instance = new MenuInstance(menu, options);
+        try {
+            instance.build();
+        } catch (e) {
+            throw new Error(`Failed to build menu with key ${menu.key}: ${e.message}`);
+        }
+        this.menus.set(menu.key, instance);
+    }
+
+    async renderMenu(key, { category = 0, index = 0, userId, guildId } = {}) {
+        const menu = this.menus.get(key);
+        if (!menu) {
+            throw new Error(`Menu with key ${key} does not exist`);
+        }
+        return menu.renderPage({ category, index, userId, guildId });
+    }
+
+    menuFromCustomId(customId) {
+        const { menu_key } = decodeId(customId);
+        const menu = this.menus.get(menu_key);
+        if (!menu) {
+            throw new Error(`Menu with key ${menu_key} does not exist`);
+        }
+        return { menu, menu_key };
+    }
+
+    async handleComponent(interaction) {
+        const normalized = normalizeInteraction(interaction);
+        const customId = normalized?.data?.custom_id;
+        if (!customId) {
+            throw new Error("Invalid interaction payload: missing custom_id");
+        }
+        const { menu, menu_key } = this.menuFromCustomId(customId);
+        return handleComponent(normalized, menu, menu_key, this.renderMenu.bind(this));
+    }
+
+    async handleModal(interaction) {
+        const normalized = normalizeInteraction(interaction);
+        const customId = normalized?.data?.custom_id;
+        if (!customId) {
+            throw new Error("Invalid interaction payload: missing custom_id");
+        }
+        const { menu, menu_key } = this.menuFromCustomId(customId);
+        return handleModal(normalized, menu, menu_key, this.renderMenu.bind(this));
+    }
+
+    async handleInteraction(interaction) {
+        try {
+            const normalized = normalizeInteraction(interaction);
+            if (normalized.type === InteractionTypes.MessageComponent) {
+                return await this.handleComponent(normalized);
+            }
+            if (normalized.type === InteractionTypes.ModalSubmit) {
+                return await this.handleModal(normalized);
+            }
+            throw new Error(`Unknown interaction type "${normalized.type}"`);
+        } catch (e) {
+            return {
+                type: ResponseTypes.ChannelMessageWithSource,
+                data: { flags: EphemeralMessageFlag, content: `Error: ${e.message}` },
+            };
+        }
+    }
+}
+
+module.exports = { MenuManager };

package/src/options/boolean.js

@@ -0,0 +1,38 @@
+const { Builder } = require("../builder");
+const { OptionTypes } = require("../utils/types");
+
+class BooleanBuilder extends Builder {
+    constructor() {
+        super(OptionTypes.Boolean);
+        this.preview = false;
+        this.trueLabel = "True";
+        this.falseLabel = "False";
+    }
+
+    setTrueLabel(label) {
+        label = String(label);
+        if (typeof label !== "string") throw new TypeError("True label must be a string");
+        this.trueLabel = label;
+        return this;
+    }
+
+    setFalseLabel(label) {
+        label = String(label);
+        if (typeof label !== "string") throw new TypeError("False label must be a string");
+        this.falseLabel = label;
+        return this;
+    }
+
+    build() {
+        const base = super.build();
+        return {
+            ...base,
+            trueLabel: this.trueLabel,
+            falseLabel: this.falseLabel,
+        };
+    }
+}
+
+module.exports = {
+    BooleanBuilder
+}

package/src/options/category.js

@@ -0,0 +1,27 @@
+const { Builder } = require("../builder");
+const { OptionTypes } = require("../utils/types");
+
+class CategoryBuilder extends Builder {
+    constructor() {
+        super(OptionTypes.Category);
+        this.options = [];
+    }
+
+    addOptions(...options) {
+        for (const option of options) {
+            this.options.push(option);
+        }
+    }
+
+    build() {
+        const base = super.build();
+        return {
+            ...base,
+            options: this.options.map(option => option.build())
+        }
+    }
+}
+
+module.exports = {
+    CategoryBuilder
+}