feat: components v2

Author: socram03

src/builders/ActionRow.ts

@@ -7,13 +7,13 @@ import {
 } from '../types';
 import { BaseComponentBuilder } from './Base';
 import { fromComponent } from './index';
-import type { BuilderComponents, FixedComponents } from './types';
+import type { ActionBuilderComponents, FixedComponents } from './types';
 
 /**
  * Represents an Action Row component in a message.
  * @template T - The type of components in the Action Row.
  */
-export class ActionRow<T extends BuilderComponents> extends BaseComponentBuilder<
+export class ActionRow<T extends ActionBuilderComponents = ActionBuilderComponents> extends BaseComponentBuilder<
 	APIActionRowComponent<APIActionRowComponentTypes>
 > {
 	/**
@@ -50,8 +50,8 @@ export class ActionRow<T extends BuilderComponents> extends BaseComponentBuilder
 	 * @example
 	 * actionRow.setComponents([buttonComponent1, buttonComponent2]);
 	 */
-	setComponents(component: FixedComponents<T>[]): this {
-		this.components = [...component];
+	setComponents(...component: RestOrArray<FixedComponents<T>>): this {
+		this.components = component.flat() as FixedComponents<T>[];
 		return this;
 	}
 

src/builders/Button.ts

@@ -1,17 +1,14 @@
 import { type EmojiResolvable, resolvePartialEmoji } from '../common';
 import { type APIButtonComponent, type APIMessageComponentEmoji, type ButtonStyle, ComponentType } from '../types';
+import { BaseComponentBuilder } from './Base';
 
 /**
  * Represents a button component.
  * @template Type - The type of the button component.
  */
-export class Button {
-	/**
-	 * Creates a new Button instance.
-	 * @param data - The initial data for the button.
-	 */
-	constructor(public data: Partial<APIButtonComponent> = {}) {
-		this.data.type = ComponentType.Button;
+export class Button extends BaseComponentBuilder<APIButtonComponent> {
+	constructor(data: Partial<APIButtonComponent> = {}) {
+		super({ type: ComponentType.Button, ...data });
 	}
 
 	/**
@@ -76,12 +73,4 @@ export class Button {
 		(this.data as Extract<APIButtonComponent, { sku_id?: string }>).sku_id = skuId;
 		return this;
 	}
-
-	/**
-	 * Converts the Button instance to its JSON representation.
-	 * @returns The JSON representation of the Button instance.
-	 */
-	toJSON() {
-		return { ...this.data } as Partial<APIButtonComponent>;
-	}
 }

src/builders/Container.ts

@@ -0,0 +1,100 @@
+import { type ActionRow, fromComponent } from '.';
+import { type ColorResolvable, type RestOrArray, resolveColor } from '../common';
+import { type APIContainerComponent, ComponentType } from '../types';
+import { BaseComponentBuilder } from './Base';
+import type { File } from './File';
+import type { MediaGallery } from './MediaGallery';
+import type { Section } from './Section';
+import type { Separator } from './Separator';
+import type { TextDisplay } from './TextDisplay';
+
+/**
+ * Represents the possible component types that can be added to a Container.
+ */
+export type ContainerBuilderComponents = ActionRow | TextDisplay | Section | MediaGallery | Separator | File;
+
+/**
+ * Represents a container component builder.
+ * Containers group other components together.
+ * @example
+ * ```ts
+ * const container = new Container()
+ *  .addComponents(
+ *      new TextDisplay('This is text inside a container!'),
+ *      new ActionRow().addComponents(new Button().setLabel('Click me!'))
+ *  )
+ *  .setColor('Blue');
+ * ```
+ */
+export class Container extends BaseComponentBuilder<APIContainerComponent> {
+	/**
+	 * The components held within this container.
+	 */
+	components: ContainerBuilderComponents[];
+
+	/**
+	 * Constructs a new Container.
+	 * @param data Optional initial data for the container.
+	 */
+	constructor({ components, ...data }: Partial<APIContainerComponent> = {}) {
+		super({ ...data, type: ComponentType.Container });
+		this.components = (components?.map(fromComponent) ?? []) as ContainerBuilderComponents[];
+	}
+
+	/**
+	 * Adds components to the container.
+	 * @param components The components to add. Can be a single component, an array of components, or multiple components as arguments.
+	 * @returns The updated Container instance.
+	 */
+	addComponents(...components: RestOrArray<ContainerBuilderComponents>) {
+		this.components = this.components.concat(components.flat());
+		return this;
+	}
+
+	/**
+	 * Sets the components for the container, replacing any existing components.
+	 * @param components The components to set. Can be a single component, an array of components, or multiple components as arguments.
+	 * @returns The updated Container instance.
+	 */
+	setComponents(...components: RestOrArray<ContainerBuilderComponents>) {
+		this.components = components.flat();
+		return this;
+	}
+
+	/**
+	 * Sets whether the container's content should be visually marked as a spoiler.
+	 * @param spoiler Whether the content is a spoiler (defaults to true).
+	 * @returns The updated Container instance.
+	 */
+	setSpoiler(spoiler = true) {
+		this.data.spoiler = spoiler;
+		return this;
+	}
+
+	/**
+	 * Sets the accent color for the container.
+	 * @param color The color resolvable (e.g., hex code, color name, integer).
+	 * @returns The updated Container instance.
+	 */
+	setColor(color: ColorResolvable) {
+		this.data.accent_color = resolveColor(color);
+		return this;
+	}
+
+	/**
+	 * Sets the ID for the container.
+	 * @param id The ID to set.
+	 * @returns The updated Container instance.
+	 */
+	setId(id: number) {
+		this.data.id = id;
+		return this;
+	}
+
+	toJSON() {
+		return {
+			...this.data,
+			components: this.components.map(c => c.toJSON()),
+		} as APIContainerComponent;
+	}
+}

src/builders/File.ts

@@ -0,0 +1,52 @@
+import { type APIFileComponent, ComponentType } from '../types';
+import { BaseComponentBuilder } from './Base';
+
+/**
+ * Represents a file component builder.
+ * Used to display files within containers.
+ * @example
+ * ```ts
+ * const file = new File()
+ *  .setMedia('https://example.com/image.png')
+ *  .setSpoiler();
+ * ```
+ */
+export class File extends BaseComponentBuilder<APIFileComponent> {
+	/**
+	 * Constructs a new File component.
+	 * @param data Optional initial data for the file component.
+	 */
+	constructor(data: Partial<APIFileComponent> = {}) {
+		super({ type: ComponentType.File, ...data });
+	}
+
+	/**
+	 * Sets the ID for the file component.
+	 * @param id The ID to set.
+	 * @returns The updated File instance.
+	 */
+	setId(id: number) {
+		this.data.id = id;
+		return this;
+	}
+
+	/**
+	 * Sets the media URL for the file.
+	 * @param url The URL of the file to display.
+	 * @returns The updated File instance.
+	 */
+	setMedia(url: string) {
+		this.data.file = { url };
+		return this;
+	}
+
+	/**
+	 * Sets whether the file should be visually marked as a spoiler.
+	 * @param spoiler Whether the file is a spoiler (defaults to true).
+	 * @returns The updated File instance.
+	 */
+	setSpoiler(spoiler = true) {
+		this.data.spoiler = spoiler;
+		return this;
+	}
+}

src/builders/MediaGallery.ts

@@ -0,0 +1,112 @@
+import type { RestOrArray } from '../common';
+import { type APIMediaGalleryComponent, type APIMediaGalleryItems, ComponentType } from '../types';
+import { BaseComponentBuilder } from './Base';
+
+/**
+ * Represents a media gallery component builder.
+ * Used to display a collection of media items.
+ * @example
+ * ```ts
+ * const gallery = new MediaGallery()
+ *  .addItems(
+ *      new MediaGalleryItem().setMedia('https://example.com/image1.png').setDescription('Image 1'),
+ *      new MediaGalleryItem().setMedia('https://example.com/image2.jpg').setSpoiler()
+ *  );
+ * ```
+ */
+export class MediaGallery extends BaseComponentBuilder<APIMediaGalleryComponent> {
+	items: MediaGalleryItem[];
+	/**
+	 * Constructs a new MediaGallery.
+	 * @param data Optional initial data for the media gallery.
+	 */
+	constructor({ items, ...data }: Partial<APIMediaGalleryComponent> = {}) {
+		super({ type: ComponentType.MediaGallery, ...data });
+		this.items = (items?.map(i => new MediaGalleryItem(i)) ?? []) as MediaGalleryItem[];
+	}
+	/**
+	 * Sets the ID for the media gallery component.
+	 * @param id The ID to set.
+	 * @returns The updated MediaGallery instance.
+	 */
+	setId(id: number) {
+		this.data.id = id;
+		return this;
+	}
+
+	/**
+	 * Adds items to the media gallery.
+	 * @param items The items to add. Can be a single item, an array of items, or multiple items as arguments.
+	 * @returns The updated MediaGallery instance.
+	 */
+	addItems(...items: RestOrArray<MediaGalleryItem>) {
+		this.items = this.items.concat(items.flat());
+		return this;
+	}
+
+	/**
+	 * Sets the items for the media gallery, replacing any existing items.
+	 * @param items The items to set. Can be a single item, an array of items, or multiple items as arguments.
+	 * @returns The updated MediaGallery instance.
+	 */
+	setItems(...items: RestOrArray<MediaGalleryItem>) {
+		this.items = items.flat();
+		return this;
+	}
+
+	toJSON() {
+		return {
+			...this.data,
+			items: this.items.map(i => i.toJSON()),
+		} as APIMediaGalleryComponent;
+	}
+}
+
+/**
+ * Represents an item within a MediaGallery.
+ */
+export class MediaGalleryItem {
+	/**
+	 * Constructs a new MediaGalleryItem.
+	 * @param data Optional initial data for the media gallery item.
+	 */
+	constructor(public data: Partial<APIMediaGalleryItems>) {}
+
+	/**
+	 * Sets the media URL for this gallery item.
+	 * @param url The URL of the media.
+	 * @returns The updated MediaGalleryItem instance.
+	 */
+	setMedia(url: string) {
+		this.data.media = { url };
+		return this;
+	}
+
+	/**
+	 * Sets the description for this gallery item.
+	 * @param desc The description text.
+	 * @returns The updated MediaGalleryItem instance.
+	 */
+	setDescription(desc: string) {
+		this.data.description = desc;
+		return this;
+	}
+
+	/**
+	 * Sets whether this gallery item should be visually marked as a spoiler.
+	 * @param spoiler Whether the item is a spoiler (defaults to true).
+	 * @returns The updated MediaGalleryItem instance.
+	 */
+	setSpoiler(spoiler = true) {
+		this.data.spoiler = spoiler;
+		return this;
+	}
+
+	/**
+	 * Converts this MediaGalleryItem instance to its JSON representation.
+	 * @returns The JSON representation of the item data.
+	 */
+	toJSON() {
+		return { ...this.data };
+	}
+}

src/builders/Section.ts

@@ -0,0 +1,55 @@
+import { type Button, fromComponent } from '.';
+import type { RestOrArray } from '../common';
+import { type APISectionComponent, ComponentType } from '../types';
+import { BaseComponentBuilder } from './Base';
+import type { TextDisplay } from './TextDisplay';
+import type { Thumbnail } from './Thumbnail';
+
+export class Section<
+	Ac extends Button | Thumbnail = Button | Thumbnail,
+> extends BaseComponentBuilder<APISectionComponent> {
+	components: TextDisplay[];
+	accessory!: Ac;
+	constructor({ components, accessory, ...data }: Partial<APISectionComponent> = {}) {
+		super({ type: ComponentType.Section, ...data });
+		this.components = (components?.map(component => fromComponent(component)) ?? []) as TextDisplay[];
+		if (accessory) this.accessory = fromComponent(accessory) as Ac;
+	}
+
+	/**
+	 * Adds components to this section.
+	 * @param components The components to add
+	 * @example section.addComponents(new TextDisplay().content('Hello'));
+	 */
+	addComponents(...components: RestOrArray<TextDisplay>) {
+		this.components = this.components.concat(components.flat());
+		return this;
+	}
+
+	/**
+	 * Sets the components for this section.
+	 * @param components The components to set
+	 * @example section.setComponents(new TextDisplay().content('Hello'));
+	 */
+	setComponents(...components: RestOrArray<TextDisplay>) {
+		this.components = components.flat();
+		return this;
+	}
+
+	setAccessory(accessory: Ac) {
+		this.accessory = accessory;
+		return this;
+	}
+
+	/**
+	 * Converts this section to JSON.
+	 * @returns The JSON representation of this section
+	 */
+	toJSON() {
+		return {
+			...this.data,
+			components: this.components.map(component => component.toJSON()),
+			accessory: this.accessory.toJSON(),
+		} as APISectionComponent;
+	}
+}