@ovencord/builders 1.11.1

package/src/components/v2/Container.ts

@@ -0,0 +1,254 @@
+import {
+	type APIComponentInMessageActionRow,
+	type APISeparatorComponent,
+	type APIActionRowComponent,
+	type APIFileComponent,
+	type APITextDisplayComponent,
+	type APIContainerComponent,
+	type APIComponentInContainer,
+	type APIMediaGalleryComponent,
+	type APISectionComponent,
+	ComponentType,
+} from 'discord-api-types/v10';
+import { normalizeArray, type RestOrArray } from '../../util/normalizeArray';
+import { resolveBuilder } from '../../util/resolveBuilder';
+import { validate } from '../../util/validation';
+import { ActionRowBuilder } from '../ActionRow.js';
+import { ComponentBuilder } from '../Component.js';
+import { createComponentBuilder } from '../Components';
+import { containerPredicate } from './Assertions';
+import { FileBuilder } from './File.js';
+import { MediaGalleryBuilder } from './MediaGallery';
+import { SectionBuilder } from './Section';
+import { SeparatorBuilder } from './Separator.js';
+import { TextDisplayBuilder } from './TextDisplay';
+
+export type ContainerComponentBuilders =
+	| ActionRowBuilder
+	| FileBuilder
+	| MediaGalleryBuilder
+	| SectionBuilder
+	| SeparatorBuilder
+	| TextDisplayBuilder;
+
+export interface ContainerBuilderData extends Partial<Omit<APIContainerComponent, 'components'>> {
+	components: ContainerComponentBuilders[];
+}
+
+/**
+ * A builder that creates API-compatible JSON data for containers.
+ */
+export class ContainerBuilder extends ComponentBuilder<APIContainerComponent> {
+	/**
+	 * @internal
+	 */
+	protected readonly data: ContainerBuilderData;
+
+	/**
+	 * Gets the components within this container.
+	 */
+	public get components(): readonly ContainerComponentBuilders[] {
+		return this.data.components;
+	}
+
+	/**
+	 * Creates a new container builder.
+	 *
+	 * @param data - The API data to create the container with
+	 */
+	public constructor(data: Partial<APIContainerComponent> = {}) {
+		super();
+
+		const { components = [], ...rest } = data;
+
+		this.data = {
+			...structuredClone(rest),
+			components: components.map((component) => createComponentBuilder(component)),
+			type: ComponentType.Container,
+		};
+	}
+
+	/**
+	 * Sets the accent color of this container.
+	 *
+	 * @param color - The color to use
+	 */
+	public setAccentColor(color: number) {
+		this.data.accent_color = color;
+		return this;
+	}
+
+	/**
+	 * Clears the accent color of this container.
+	 */
+	public clearAccentColor() {
+		this.data.accent_color = undefined;
+		return this;
+	}
+
+	/**
+	 * Sets the spoiler status of this container.
+	 *
+	 * @param spoiler - The spoiler status to use
+	 */
+	public setSpoiler(spoiler = true) {
+		this.data.spoiler = spoiler;
+		return this;
+	}
+
+	/**
+	 * Adds action row components to this container.
+	 *
+	 * @param input - The action row to add
+	 */
+	public addActionRowComponents(
+		...input: RestOrArray<
+			| ActionRowBuilder
+			| APIActionRowComponent<APIComponentInMessageActionRow>
+			| ((builder: ActionRowBuilder) => ActionRowBuilder)
+		>
+	): this {
+		const normalized = normalizeArray(input);
+		const resolved = normalized.map((component) => resolveBuilder(component, ActionRowBuilder));
+
+		this.data.components.push(...resolved);
+		return this;
+	}
+
+	/**
+	 * Adds file components to this container.
+	 *
+	 * @param input - The file components to add
+	 */
+	public addFileComponents(
+		...input: RestOrArray<APIFileComponent | FileBuilder | ((builder: FileBuilder) => FileBuilder)>
+	): this {
+		const normalized = normalizeArray(input);
+		const resolved = normalized.map((component) => resolveBuilder(component, FileBuilder));
+
+		this.data.components.push(...resolved);
+		return this;
+	}
+
+	/**
+	 * Adds media gallery components to this container.
+	 *
+	 * @param input - The media gallery components to add
+	 */
+	public addMediaGalleryComponents(
+		...input: RestOrArray<
+			APIMediaGalleryComponent | MediaGalleryBuilder | ((builder: MediaGalleryBuilder) => MediaGalleryBuilder)
+		>
+	): this {
+		const normalized = normalizeArray(input);
+		const resolved = normalized.map((component) => resolveBuilder(component, MediaGalleryBuilder));
+
+		this.data.components.push(...resolved);
+		return this;
+	}
+
+	/**
+	 * Adds section components to this container.
+	 *
+	 * @param input - The section components to add
+	 */
+	public addSectionComponents(
+		...input: RestOrArray<APISectionComponent | SectionBuilder | ((builder: SectionBuilder) => SectionBuilder)>
+	): this {
+		const normalized = normalizeArray(input);
+		const resolved = normalized.map((component) => resolveBuilder(component, SectionBuilder));
+
+		this.data.components.push(...resolved);
+		return this;
+	}
+
+	/**
+	 * Adds separator components to this container.
+	 *
+	 * @param input - The separator components to add
+	 */
+	public addSeparatorComponents(
+		...input: RestOrArray<APISeparatorComponent | SeparatorBuilder | ((builder: SeparatorBuilder) => SeparatorBuilder)>
+	): this {
+		const normalized = normalizeArray(input);
+		const resolved = normalized.map((component) => resolveBuilder(component, SeparatorBuilder));
+
+		this.data.components.push(...resolved);
+		return this;
+	}
+
+	/**
+	 * Adds text display components to this container.
+	 *
+	 * @param input - The text display components to add
+	 */
+	public addTextDisplayComponents(
+		...input: RestOrArray<
+			APITextDisplayComponent | TextDisplayBuilder | ((builder: TextDisplayBuilder) => TextDisplayBuilder)
+		>
+	): this {
+		const normalized = normalizeArray(input);
+		const resolved = normalized.map((component) => resolveBuilder(component, TextDisplayBuilder));
+
+		this.data.components.push(...resolved);
+		return this;
+	}
+
+	/**
+	 * Removes, replaces, or inserts components for this container
+	 *
+	 * @remarks
+	 * This method behaves similarly
+	 * to {@link https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array/splice | Array.prototype.splice()}.
+	 *
+	 * It's useful for modifying and adjusting order of the already-existing components of a container.
+	 * @example
+	 * Remove the first component:
+	 * ```ts
+	 * container.spliceComponents(0, 1);
+	 * ```
+	 * @example
+	 * Remove the first n components:
+	 * ```ts
+	 * const n = 4;
+	 * container.spliceComponents(0, n);
+	 * ```
+	 * @example
+	 * Remove the last component:
+	 * ```ts
+	 * container.spliceComponents(-1, 1);
+	 * ```
+	 * @param index - The index to start at
+	 * @param deleteCount - The number of components to remove
+	 * @param components - The replacing component objects
+	 */
+	public spliceComponents(
+		index: number,
+		deleteCount: number,
+		...components: RestOrArray<APIComponentInContainer | ContainerComponentBuilders>
+	): this {
+		const normalized = normalizeArray(components);
+		const resolved = normalized.map((component) =>
+			component instanceof ComponentBuilder ? component : createComponentBuilder(component),
+		);
+
+		this.data.components.splice(index, deleteCount, ...resolved);
+		return this;
+	}
+
+	/**
+	 * {@inheritDoc ComponentBuilder.toJSON}
+	 */
+	public override toJSON(validationOverride?: boolean): APIContainerComponent {
+		const { components, ...rest } = this.data;
+
+		const data = {
+			...structuredClone(rest),
+			components: components.map((component) => component.toJSON(false)),
+		};
+
+		validate(containerPredicate, data, validationOverride);
+
+		return data as APIContainerComponent;
+	}
+}

package/src/components/v2/File.ts

@@ -0,0 +1,81 @@
+import { ComponentType, type APIFileComponent } from 'discord-api-types/v10';
+import { validate } from '../../util/validation.js';
+import { ComponentBuilder } from '../Component.js';
+import { filePredicate } from './Assertions.js';
+
+/**
+ * A builder that creates API-compatible JSON data for files.
+ */
+export class FileBuilder extends ComponentBuilder<APIFileComponent> {
+	/**
+	 * @internal
+	 */
+	protected readonly data: Partial<APIFileComponent>;
+
+	/**
+	 * Creates a new file.
+	 *
+	 * @param data - The API data to create this file with
+	 * @example
+	 * Creating a file from an API data object:
+	 * ```ts
+	 * const file = new FileBuilder({
+	 * 	spoiler: true,
+	 * 	file: {
+	 * 		url: 'attachment://file.png',
+	 * 	},
+	 * });
+	 * ```
+	 * @example
+	 * Creating a file using setters and API data:
+	 * ```ts
+	 * const file = new FileBuilder({
+	 * 	file: {
+	 * 		url: 'attachment://image.jpg',
+	 * 	},
+	 * })
+	 * 	.setSpoiler(false);
+	 * ```
+	 */
+	public constructor(data: Partial<APIFileComponent> = {}) {
+		super();
+
+		const { file, ...rest } = data;
+
+		this.data = {
+			...structuredClone(rest),
+			file: file && { url: file.url },
+			type: ComponentType.File,
+		};
+	}
+
+	/**
+	 * Sets the spoiler status of this file.
+	 *
+	 * @param spoiler - The spoiler status to use
+	 */
+	public setSpoiler(spoiler = true) {
+		this.data.spoiler = spoiler;
+		return this;
+	}
+
+	/**
+	 * Sets the media URL of this file.
+	 *
+	 * @param url - The URL to use
+	 */
+	public setURL(url: string) {
+		this.data.file = { url };
+		return this;
+	}
+
+	/**
+	 * {@inheritDoc ComponentBuilder.toJSON}
+	 */
+	public override toJSON(validationOverride?: boolean): APIFileComponent {
+		const clone = structuredClone(this.data);
+		validate(filePredicate, clone, validationOverride);
+
+		return clone as APIFileComponent;
+	}
+}

package/src/components/v2/MediaGallery.ts

@@ -0,0 +1,128 @@
+import { type APIMediaGalleryItem, type APIMediaGalleryComponent, ComponentType } from 'discord-api-types/v10';
+import { normalizeArray, type RestOrArray } from '../../util/normalizeArray.js';
+import { resolveBuilder } from '../../util/resolveBuilder.js';
+import { validate } from '../../util/validation.js';
+import { ComponentBuilder } from '../Component.js';
+import { mediaGalleryPredicate } from './Assertions.js';
+import { MediaGalleryItemBuilder } from './MediaGalleryItem.js';
+
+export interface MediaGalleryBuilderData extends Partial<Omit<APIMediaGalleryComponent, 'items'>> {
+	items: MediaGalleryItemBuilder[];
+}
+
+/**
+ * A builder that creates API-compatible JSON data for media galleries.
+ */
+export class MediaGalleryBuilder extends ComponentBuilder<APIMediaGalleryComponent> {
+	/**
+	 * @internal
+	 */
+	protected readonly data: MediaGalleryBuilderData;
+
+	/**
+	 * The items in this media gallery.
+	 */
+	public get items(): readonly MediaGalleryItemBuilder[] {
+		return this.data.items;
+	}
+
+	/**
+	 * Creates a new media gallery.
+	 *
+	 * @param data - The API data to create this container with
+	 * @example
+	 * Creating a media gallery from an API data object:
+	 * ```ts
+	 * const mediaGallery = new MediaGalleryBuilder({
+	 * 	items: [
+	 * 		{
+	 * 			description: "Some text here",
+	 * 			media: {
+	 * 				url: 'https://cdn.discordapp.com/embed/avatars/2.png',
+	 * 			},
+	 * 		},
+	 * 	],
+	 * });
+	 * ```
+	 * @example
+	 * Creating a media gallery using setters and API data:
+	 * ```ts
+	 * const mediaGallery = new MediaGalleryBuilder({
+	 * 	items: [
+	 * 		{
+	 * 			description: "alt text",
+	 * 			media: {
+	 * 				url: 'https://cdn.discordapp.com/embed/avatars/5.png',
+	 * 			},
+	 * 		},
+	 * 	],
+	 * })
+	 * 	.addItems(item2, item3);
+	 * ```
+	 */
+	public constructor(data: Partial<APIMediaGalleryComponent> = {}) {
+		super();
+
+		const { items = [], ...rest } = data;
+
+		this.data = {
+			...structuredClone(rest),
+			items: items.map((item) => new MediaGalleryItemBuilder(item)),
+			type: ComponentType.MediaGallery,
+		};
+	}
+
+	/**
+	 * Adds a media gallery item to this media gallery.
+	 *
+	 * @param input - The items to add
+	 */
+	public addItems(
+		...input: RestOrArray<
+			APIMediaGalleryItem | MediaGalleryItemBuilder | ((builder: MediaGalleryItemBuilder) => MediaGalleryItemBuilder)
+		>
+	): this {
+		const normalized = normalizeArray(input);
+		const resolved = normalized.map((item) => resolveBuilder(item, MediaGalleryItemBuilder));
+
+		this.data.items.push(...resolved);
+		return this;
+	}
+
+	/**
+	 * Removes, replaces, or inserts media gallery items for this media gallery.
+	 *
+	 * @param index - The index to start removing, replacing or inserting items
+	 * @param deleteCount - The amount of items to remove
+	 * @param items - The items to insert
+	 */
+	public spliceItems(
+		index: number,
+		deleteCount: number,
+		...items: RestOrArray<
+			APIMediaGalleryItem | MediaGalleryItemBuilder | ((builder: MediaGalleryItemBuilder) => MediaGalleryItemBuilder)
+		>
+	) {
+		const normalized = normalizeArray(items);
+		const resolved = normalized.map((item) => resolveBuilder(item, MediaGalleryItemBuilder));
+
+		this.data.items.splice(index, deleteCount, ...resolved);
+		return this;
+	}
+
+	/**
+	 * {@inheritDoc ComponentBuilder.toJSON}
+	 */
+	public override toJSON(validationOverride?: boolean): APIMediaGalleryComponent {
+		const { items, ...rest } = this.data;
+
+		const data = {
+			...structuredClone(rest),
+			items: items.map((item) => item.toJSON(false)),
+		};
+
+		validate(mediaGalleryPredicate, data, validationOverride);
+
+		return data as APIMediaGalleryComponent;
+	}
+}

package/src/components/v2/MediaGalleryItem.ts

@@ -0,0 +1,85 @@
+import type { JSONEncodable } from '@ovencord/util';
+import type { APIMediaGalleryItem } from 'discord-api-types/v10';
+import { validate } from '../../util/validation.js';
+import { mediaGalleryItemPredicate } from './Assertions.js';
+
+export class MediaGalleryItemBuilder implements JSONEncodable<APIMediaGalleryItem> {
+	private readonly data: Partial<APIMediaGalleryItem>;
+
+	/**
+	 * Creates a new media gallery item.
+	 *
+	 * @param data - The API data to create this media gallery item with
+	 * @example
+	 * Creating a media gallery item from an API data object:
+	 * ```ts
+	 * const item = new MediaGalleryItemBuilder({
+	 * 	description: "Some text here",
+	 * 	media: {
+	 * 		url: 'https://cdn.discordapp.com/embed/avatars/2.png',
+	 * 	},
+	 * });
+	 * ```
+	 * @example
+	 * Creating a media gallery item using setters and API data:
+	 * ```ts
+	 * const item = new MediaGalleryItemBuilder({
+	 * 	media: {
+	 * 		url: 'https://cdn.discordapp.com/embed/avatars/5.png',
+	 * 	},
+	 * })
+	 * 	.setDescription("alt text");
+	 * ```
+	 */
+	public constructor(data: Partial<APIMediaGalleryItem> = {}) {
+		this.data = structuredClone(data);
+	}
+
+	/**
+	 * Sets the source URL of this media gallery item.
+	 *
+	 * @param url - The URL to use
+	 */
+	public setURL(url: string) {
+		this.data.media = { url };
+		return this;
+	}
+
+	/**
+	 * Sets the description of this thumbnail.
+	 *
+	 * @param description - The description to use
+	 */
+	public setDescription(description: string) {
+		this.data.description = description;
+		return this;
+	}
+
+	/**
+	 * Clears the description of this thumbnail.
+	 */
+	public clearDescription() {
+		this.data.description = undefined;
+		return this;
+	}
+
+	/**
+	 * Sets the spoiler status of this thumbnail.
+	 *
+	 * @param spoiler - The spoiler status to use
+	 */
+	public setSpoiler(spoiler = true) {
+		this.data.spoiler = spoiler;
+		return this;
+	}
+
+	/**
+	 * Transforms this object to its JSON format
+	 */
+	public toJSON(validationOverride?: boolean): APIMediaGalleryItem {
+		const clone = structuredClone(this.data);
+		validate(mediaGalleryItemPredicate, clone, validationOverride);
+
+		return clone as APIMediaGalleryItem;
+	}
+}