@lunibee/builders 0.2.0 → 0.2.1

package/README.md

@@ -55,6 +55,13 @@ console.log(embed.toJSON(), buttons.toJSON(), menu.toJSON(), ping.toJSON());
 
 Every builder validates Discord's limits as you set values and serialises with `toJSON()`.
 
+## What's new in 0.2.1
+
+- `ModalBuilder.addTextInputs(...inputs)` wraps each text input in its own row.
+- `componentsV2Message(components, options?)` builds a Components V2 message with the required flag.
+- `EmbedBuilder` setters (`setTitle`, `setDescription`, `setURL`, `setThumbnail`, `setImage`) clear the field with `null`.
+- `TextInputStyle` and `ComponentType` are usable as types; `ModalBuilder.toJSON()` is typed with a required `custom_id` and `title`.
+
 ## What's new in 0.2.0
 
 `toJSON()` validates whole components (required fields, value bounds, action-row rules, button field exclusivity); `ButtonBuilder.setSKUId()` for premium buttons.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunibee/builders",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "type": "module",
   "module": "./src/index.ts",
   "types": "./src/index.ts",

package/src/components.ts

@@ -23,6 +23,11 @@ export const ComponentType = {
     Container: 17,
 } as const;
 export const TextInputStyle = { Short: 1, Paragraph: 2 } as const;
+/** One {@link TextInputStyle} value, usable as a type. */
+export type TextInputStyle =
+    (typeof TextInputStyle)[keyof typeof TextInputStyle];
+/** One {@link ComponentType} value, usable as a type. */
+export type ComponentType = (typeof ComponentType)[keyof typeof ComponentType];
 export interface APIComponentEmoji {
     id?: string | null;
     name?: string | null;
@@ -83,8 +88,8 @@ export interface APITextInputComponent {
 }
 export interface APIModalComponent {
     type: 9;
-    custom_id?: string;
-    title?: string;
+    custom_id: string;
+    title: string;
     components: APIActionRowComponent[];
 }
 export type APIActionRowChild =
@@ -435,6 +440,14 @@ export class ModalBuilder {
         this.#components.push(...components);
         return this;
     }
+    /** Adds text inputs, each in its own action row (Discord's modal layout). @param inputs Text inputs, at most 5 per modal. */
+    public addTextInputs(...inputs: TextInputBuilder[]): this {
+        return this.addComponents(
+            ...inputs.map((input) =>
+                new ActionRowBuilder<TextInputBuilder>().addComponents(input),
+            ),
+        );
+    }
     public toJSON(): APIModalComponent {
         if (!this.#custom_id || !this.#title)
             throw new TypeError("Modals require a custom ID and a title.");
@@ -442,8 +455,8 @@ export class ModalBuilder {
             throw new RangeError("Modals require at least one component.");
         return {
             type: 9,
-            ...(this.#custom_id ? { custom_id: this.#custom_id } : {}),
-            ...(this.#title ? { title: this.#title } : {}),
+            custom_id: this.#custom_id,
+            title: this.#title,
             components: this.#components.map((component) => component.toJSON()),
         };
     }
@@ -757,3 +770,31 @@ function assertSelect(data: {
     if ((data.min_values ?? 1) > (data.max_values ?? 1))
         throw new RangeError("min_values cannot exceed max_values.");
 }
+
+/** Discord's flag for a message laid out with Components V2 (containers, text displays...). */
+const IS_COMPONENTS_V2 = 1 << 15;
+
+/**
+ * A message payload laid out with Components V2: the components, and the flag
+ * Discord requires for them. A V2 message cannot also carry `content` or `embeds`.
+ * @param components Top-level components (containers, sections, text displays, action rows...).
+ * @param options Extra message fields, such as `allowed_mentions` or `ephemeral`; `flags` are combined.
+ * @example channel.send(componentsV2Message(new ContainerBuilder().addComponents(new TextDisplayBuilder().setContent("Hi"))))
+ */
+export function componentsV2Message<
+    T extends Record<string, unknown> = Record<string, never>,
+>(
+    components: { toJSON(): APIComponent } | Array<{ toJSON(): APIComponent }>,
+    options?: T & { flags?: number },
+): { components: APIComponent[]; flags: number } & T {
+    const list = Array.isArray(components) ? components : [components];
+    if (!list.length)
+        throw new TypeError(
+            "A Components V2 message needs at least one component.",
+        );
+    return {
+        ...(options ?? ({} as T)),
+        components: list.map((component) => component.toJSON()),
+        flags: (options?.flags ?? 0) | IS_COMPONENTS_V2,
+    };
+}

package/src/embed.ts

@@ -32,22 +32,26 @@ export interface APIEmbed {
 /** Builds compile-time-safe rich embed payloads for Discord API requests. */
 export class EmbedBuilder {
     readonly #data: APIEmbed = {};
-    /** Sets the embed title. @param value Title text. @returns This builder. @throws {RangeError} If title exceeds Discord's limit. */ public setTitle(
-        value: string,
+    /** Sets the embed title. @param value Title text, or null to clear. @returns This builder. @throws {RangeError} If title exceeds Discord's limit. */ public setTitle(
+        value: string | null,
     ): this {
-        this.#data.title = validate(value, 256, "Embed title");
+        if (value === null) delete this.#data.title;
+        else this.#data.title = validate(value, 256, "Embed title");
         return this;
     }
-    /** Sets the embed description. @param value Description text. @returns This builder. @throws {RangeError} If description exceeds Discord's limit. */ public setDescription(
-        value: string,
+    /** Sets the embed description. @param value Description text, or null to clear. @returns This builder. @throws {RangeError} If description exceeds Discord's limit. */ public setDescription(
+        value: string | null,
     ): this {
-        this.#data.description = validate(value, 4096, "Embed description");
+        if (value === null) delete this.#data.description;
+        else
+            this.#data.description = validate(value, 4096, "Embed description");
         return this;
     }
-    /** Sets the embed URL. @param value Absolute URL. @returns This builder. @throws {TypeError} If URL is invalid. */ public setURL(
-        value: string,
+    /** Sets the embed URL. @param value Absolute URL, or null to clear. @returns This builder. @throws {TypeError} If URL is invalid. */ public setURL(
+        value: string | null,
     ): this {
-        this.#data.url = url(value, "Embed URL");
+        if (value === null) delete this.#data.url;
+        else this.#data.url = url(value, "Embed URL");
         return this;
     }
     /** Sets the embed color. @param value RGB integer. @returns This builder. @throws {RangeError} If color is outside 24-bit RGB range. */ public setColor(
@@ -92,16 +96,24 @@ export class EmbedBuilder {
         };
         return this;
     }
-    /** Sets the thumbnail URL. @param value Thumbnail URL or payload. @returns This builder. @throws {TypeError} If URL is invalid. */ public setThumbnail(
-        value: { url: string } | string,
+    /** Sets the thumbnail URL. @param value Thumbnail URL or payload, or null to clear. @returns This builder. @throws {TypeError} If URL is invalid. */ public setThumbnail(
+        value: { url: string } | string | null,
     ): this {
+        if (value === null) {
+            delete this.#data.thumbnail;
+            return this;
+        }
         const valueURL = typeof value === "string" ? value : value.url;
         this.#data.thumbnail = { url: url(valueURL, "Thumbnail URL") };
         return this;
     }
-    /** Sets the image URL. @param value Image URL or payload. @returns This builder. @throws {TypeError} If URL is invalid. */ public setImage(
-        value: { url: string } | string,
+    /** Sets the image URL. @param value Image URL or payload, or null to clear. @returns This builder. @throws {TypeError} If URL is invalid. */ public setImage(
+        value: { url: string } | string | null,
     ): this {
+        if (value === null) {
+            delete this.#data.image;
+            return this;
+        }
         const valueURL = typeof value === "string" ? value : value.url;
         this.#data.image = { url: url(valueURL, "Image URL") };
         return this;

package/src/index.ts

@@ -23,6 +23,7 @@ export {
     SeparatorBuilder,
     ThumbnailBuilder,
     ContentInventoryEntryBuilder,
+    componentsV2Message,
 } from "./components.js";
 export {
     SlashCommandBuilder,