@ovencord/builders 1.11.1

package/src/components/selectMenu/StringSelectMenu.ts

@@ -0,0 +1,165 @@
+import { ComponentType } from 'discord-api-types/v10';
+import type { APIStringSelectComponent, APISelectMenuOption } 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 { selectMenuStringPredicate } from '../Assertions.js';
+import { BaseSelectMenuBuilder } from './BaseSelectMenu.js';
+import { StringSelectMenuOptionBuilder } from './StringSelectMenuOption.js';
+
+export interface StringSelectMenuData extends Partial<Omit<APIStringSelectComponent, 'options'>> {
+	options: StringSelectMenuOptionBuilder[];
+	required?: boolean;
+}
+
+/**
+ * A builder that creates API-compatible JSON data for string select menus.
+ */
+export class StringSelectMenuBuilder extends BaseSelectMenuBuilder<APIStringSelectComponent> {
+	protected override readonly data: StringSelectMenuData;
+
+	/**
+	 * The options for this select menu.
+	 */
+	public get options(): readonly StringSelectMenuOptionBuilder[] {
+		return this.data.options;
+	}
+
+	/**
+	 * Creates a new string select menu.
+	 *
+	 * @param data - The API data to create this string select menu with
+	 * @example
+	 * Creating a select menu from an API data object:
+	 * ```ts
+	 * const selectMenu = new StringSelectMenuBuilder({
+	 * 	custom_id: 'a cool select menu',
+	 * 	placeholder: 'select an option',
+	 * 	max_values: 2,
+	 * 	options: [
+	 * 		{ label: 'option 1', value: '1' },
+	 * 		{ label: 'option 2', value: '2' },
+	 * 		{ label: 'option 3', value: '3' },
+	 * 	],
+	 * });
+	 * ```
+	 * @example
+	 * Creating a select menu using setters and API data:
+	 * ```ts
+	 * const selectMenu = new StringSelectMenuBuilder({
+	 * 	custom_id: 'a cool select menu',
+	 * })
+	 * 	.setMinValues(1)
+	 * 	.addOptions({
+	 * 		label: 'Catchy',
+	 * 		value: 'catch',
+	 * 	});
+	 * ```
+	 */
+	public constructor(data: Partial<APIStringSelectComponent> = {}) {
+		super();
+
+		const { options = [], ...rest } = data;
+
+		this.data = {
+			...structuredClone(rest),
+			options: options.map((option) => new StringSelectMenuOptionBuilder(option)),
+			type: ComponentType.StringSelect,
+		};
+	}
+
+	/**
+	 * Adds options to this select menu.
+	 *
+	 * @param options - The options to add
+	 */
+	public addOptions(
+		...options: RestOrArray<
+			| APISelectMenuOption
+			| StringSelectMenuOptionBuilder
+			| ((builder: StringSelectMenuOptionBuilder) => StringSelectMenuOptionBuilder)
+		>
+	) {
+		const normalizedOptions = normalizeArray(options);
+		const resolved = normalizedOptions.map((option) => resolveBuilder(option, StringSelectMenuOptionBuilder));
+
+		this.data.options.push(...resolved);
+
+		return this;
+	}
+
+	/**
+	 * Sets the options for this select menu.
+	 *
+	 * @param options - The options to set
+	 */
+	public setOptions(
+		...options: RestOrArray<
+			| APISelectMenuOption
+			| StringSelectMenuOptionBuilder
+			| ((builder: StringSelectMenuOptionBuilder) => StringSelectMenuOptionBuilder)
+		>
+	) {
+		return this.spliceOptions(0, this.options.length, ...normalizeArray(options));
+	}
+
+	/**
+	 * Removes, replaces, or inserts options for this select menu.
+	 *
+	 * @remarks
+	 * This method behaves similarly
+	 * to {@link https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array/slice | Array.prototype.splice()}.
+	 * It's useful for modifying and adjusting the order of existing options.
+	 * @example
+	 * Remove the first option:
+	 * ```ts
+	 * selectMenu.spliceOptions(0, 1);
+	 * ```
+	 * @example
+	 * Remove the first n option:
+	 * ```ts
+	 * const n = 4;
+	 * selectMenu.spliceOptions(0, n);
+	 * ```
+	 * @example
+	 * Remove the last option:
+	 * ```ts
+	 * selectMenu.spliceOptions(-1, 1);
+	 * ```
+	 * @param index - The index to start at
+	 * @param deleteCount - The number of options to remove
+	 * @param options - The replacing option objects or builders
+	 */
+	public spliceOptions(
+		index: number,
+		deleteCount: number,
+		...options: (
+			| APISelectMenuOption
+			| StringSelectMenuOptionBuilder
+			| ((builder: StringSelectMenuOptionBuilder) => StringSelectMenuOptionBuilder)
+		)[]
+	) {
+		const resolved = options.map((option) => resolveBuilder(option, StringSelectMenuOptionBuilder));
+
+		this.data.options ??= [];
+		this.data.options.splice(index, deleteCount, ...resolved);
+
+		return this;
+	}
+
+	/**
+	 * {@inheritDoc ComponentBuilder.toJSON}
+	 */
+	public override toJSON(validationOverride?: boolean): APIStringSelectComponent {
+		const { options, ...rest } = this.data;
+		const data = {
+			...(structuredClone(rest) as APIStringSelectComponent),
+			// selectMenuStringPredicate covers the validation of options
+			options: options.map((option) => option.toJSON(false)),
+		};
+
+		validate(selectMenuStringPredicate, data, validationOverride);
+
+		return data as APIStringSelectComponent;
+	}
+}

package/src/components/selectMenu/StringSelectMenuOption.ts

@@ -0,0 +1,113 @@
+import type { JSONEncodable } from '@ovencord/util';
+import type { APIMessageComponentEmoji, APISelectMenuOption } from 'discord-api-types/v10';
+import { validate } from '../../util/validation.js';
+import { selectMenuStringOptionPredicate } from '../Assertions.js';
+
+/**
+ * A builder that creates API-compatible JSON data for string select menu options.
+ */
+export class StringSelectMenuOptionBuilder implements JSONEncodable<APISelectMenuOption> {
+	private readonly data: Partial<APISelectMenuOption>;
+
+	/**
+	 * Creates a new string select menu option.
+	 *
+	 * @param data - The API data to create this string select menu option with
+	 * @example
+	 * Creating a string select menu option from an API data object:
+	 * ```ts
+	 * const selectMenuOption = new SelectMenuOptionBuilder({
+	 * 	label: 'catchy label',
+	 * 	value: '1',
+	 * });
+	 * ```
+	 * @example
+	 * Creating a string select menu option using setters and API data:
+	 * ```ts
+	 * const selectMenuOption = new SelectMenuOptionBuilder({
+	 * 	default: true,
+	 * 	value: '1',
+	 * })
+	 * 	.setLabel('woah');
+	 * ```
+	 */
+	public constructor(data: Partial<APISelectMenuOption> = {}) {
+		this.data = structuredClone(data);
+	}
+
+	/**
+	 * Sets the label for this option.
+	 *
+	 * @param label - The label to use
+	 */
+	public setLabel(label: string) {
+		this.data.label = label;
+		return this;
+	}
+
+	/**
+	 * Sets the value for this option.
+	 *
+	 * @param value - The value to use
+	 */
+	public setValue(value: string) {
+		this.data.value = value;
+		return this;
+	}
+
+	/**
+	 * Sets the description for this option.
+	 *
+	 * @param description - The description to use
+	 */
+	public setDescription(description: string) {
+		this.data.description = description;
+		return this;
+	}
+
+	/**
+	 * Clears the description for this option.
+	 */
+	public clearDescription() {
+		this.data.description = undefined;
+		return this;
+	}
+
+	/**
+	 * Sets whether this option is selected by default.
+	 *
+	 * @param isDefault - Whether this option is selected by default
+	 */
+	public setDefault(isDefault = true) {
+		this.data.default = isDefault;
+		return this;
+	}
+
+	/**
+	 * Sets the emoji to display for this option.
+	 *
+	 * @param emoji - The emoji to use
+	 */
+	public setEmoji(emoji: APIMessageComponentEmoji) {
+		this.data.emoji = emoji;
+		return this;
+	}
+
+	/**
+	 * Clears the emoji for this option.
+	 */
+	public clearEmoji() {
+		this.data.emoji = undefined;
+		return this;
+	}
+
+	/**
+	 * {@inheritDoc ComponentBuilder.toJSON}
+	 */
+	public toJSON(validationOverride?: boolean): APISelectMenuOption {
+		const clone = structuredClone(this.data);
+		validate(selectMenuStringOptionPredicate, clone, validationOverride);
+
+		return clone as APISelectMenuOption;
+	}
+}

package/src/components/selectMenu/UserSelectMenu.ts

@@ -0,0 +1,89 @@
+import {
+	type APIUserSelectComponent,
+	type Snowflake,
+	ComponentType,
+	SelectMenuDefaultValueType,
+} from 'discord-api-types/v10';
+import { type RestOrArray, normalizeArray } from '../../util/normalizeArray.js';
+import { validate } from '../../util/validation.js';
+import { selectMenuUserPredicate } from '../Assertions.js';
+import { BaseSelectMenuBuilder } from './BaseSelectMenu.js';
+
+/**
+ * A builder that creates API-compatible JSON data for user select menus.
+ */
+export class UserSelectMenuBuilder extends BaseSelectMenuBuilder<APIUserSelectComponent> {
+	protected override readonly data: Partial<APIUserSelectComponent>;
+
+	/**
+	 * Creates a new user select menu.
+	 *
+	 * @param data - The API data to create this user select menu with
+	 * @example
+	 * Creating a select menu from an API data object:
+	 * ```ts
+	 * const selectMenu = new UserSelectMenuBuilder({
+	 * 	custom_id: 'a cool select menu',
+	 * 	placeholder: 'select an option',
+	 * 	max_values: 2,
+	 * });
+	 * ```
+	 * @example
+	 * Creating a select menu using setters and API data:
+	 * ```ts
+	 * const selectMenu = new UserSelectMenuBuilder({
+	 * 	custom_id: 'a cool select menu',
+	 * })
+	 * 	.setMinValues(1);
+	 * ```
+	 */
+	public constructor(data: Partial<APIUserSelectComponent> = {}) {
+		super();
+		this.data = { ...structuredClone(data), type: ComponentType.UserSelect };
+	}
+
+	/**
+	 * Adds default users to this auto populated select menu.
+	 *
+	 * @param users - The users to add
+	 */
+	public addDefaultUsers(...users: RestOrArray<Snowflake>) {
+		const normalizedValues = normalizeArray(users);
+
+		this.data.default_values ??= [];
+		this.data.default_values.push(
+			...normalizedValues.map((id) => ({
+				id,
+				type: SelectMenuDefaultValueType.User as const,
+			})),
+		);
+
+		return this;
+	}
+
+	/**
+	 * Sets default users for this auto populated select menu.
+	 *
+	 * @param users - The users to set
+	 */
+	public setDefaultUsers(...users: RestOrArray<Snowflake>) {
+		const normalizedValues = normalizeArray(users);
+
+		this.data.default_values = normalizedValues.map((id) => ({
+			id,
+			type: SelectMenuDefaultValueType.User as const,
+		}));
+
+		return this;
+	}
+
+	/**
+	 * {@inheritDoc ComponentBuilder.toJSON}
+	 */
+	public override toJSON(validationOverride?: boolean): APIUserSelectComponent {
+		const clone = structuredClone(this.data);
+		validate(selectMenuUserPredicate, clone, validationOverride);
+
+		return clone as APIUserSelectComponent;
+	}
+}

package/src/components/textInput/Assertions.ts

@@ -0,0 +1,15 @@
+import { ComponentType, TextInputStyle } from 'discord-api-types/v10';
+import { z } from 'zod';
+import { customIdPredicate, idPredicate } from '../../Assertions.js';
+
+export const textInputPredicate = z.object({
+	id: idPredicate,
+	type: z.literal(ComponentType.TextInput),
+	custom_id: customIdPredicate,
+	style: z.nativeEnum(TextInputStyle),
+	min_length: z.number().min(0).max(4_000).optional(),
+	max_length: z.number().min(1).max(4_000).optional(),
+	placeholder: z.string().max(100).optional(),
+	value: z.string().min(0).max(4_000).optional(),
+	required: z.boolean().optional(),
+});

package/src/components/textInput/TextInput.ts

@@ -0,0 +1,154 @@
+import { ComponentType, type TextInputStyle, type APITextInputComponent } from 'discord-api-types/v10';
+import { validate } from '../../util/validation.js';
+import { ComponentBuilder } from '../Component.js';
+import { textInputPredicate } from './Assertions.js';
+
+/**
+ * A builder that creates API-compatible JSON data for text inputs.
+ */
+export class TextInputBuilder extends ComponentBuilder<APITextInputComponent> {
+	/**
+	 * @internal
+	 */
+	protected readonly data: Partial<APITextInputComponent>;
+
+	/**
+	 * Creates a new text input.
+	 *
+	 * @param data - The API data to create this text input with
+	 * @example
+	 * Creating a text input from an API data object:
+	 * ```ts
+	 * const textInput = new TextInputBuilder({
+	 * 	custom_id: 'a cool text input',
+	 * 	placeholder: 'Type something',
+	 * 	style: TextInputStyle.Short,
+	 * });
+	 * ```
+	 * @example
+	 * Creating a text input using setters and API data:
+	 * ```ts
+	 * const textInput = new TextInputBuilder({
+	 * 	placeholder: 'Type something else',
+	 * })
+	 * 	.setCustomId('woah')
+	 * 	.setStyle(TextInputStyle.Paragraph);
+	 * ```
+	 */
+	public constructor(data: Partial<APITextInputComponent> = {}) {
+		super();
+		this.data = { ...structuredClone(data), type: ComponentType.TextInput };
+	}
+
+	/**
+	 * Sets the custom id for this text input.
+	 *
+	 * @param customId - The custom id to use
+	 */
+	public setCustomId(customId: string) {
+		this.data.custom_id = customId;
+		return this;
+	}
+
+	/**
+	 * Sets the style for this text input.
+	 *
+	 * @param style - The style to use
+	 */
+	public setStyle(style: TextInputStyle) {
+		this.data.style = style;
+		return this;
+	}
+
+	/**
+	 * Sets the minimum length of text for this text input.
+	 *
+	 * @param minLength - The minimum length of text for this text input
+	 */
+	public setMinLength(minLength: number) {
+		this.data.min_length = minLength;
+		return this;
+	}
+
+	/**
+	 * Clears the minimum length of text for this text input.
+	 */
+	public clearMinLength() {
+		this.data.min_length = undefined;
+		return this;
+	}
+
+	/**
+	 * Sets the maximum length of text for this text input.
+	 *
+	 * @param maxLength - The maximum length of text for this text input
+	 */
+	public setMaxLength(maxLength: number) {
+		this.data.max_length = maxLength;
+		return this;
+	}
+
+	/**
+	 * Clears the maximum length of text for this text input.
+	 */
+	public clearMaxLength() {
+		this.data.max_length = undefined;
+		return this;
+	}
+
+	/**
+	 * Sets the placeholder for this text input.
+	 *
+	 * @param placeholder - The placeholder to use
+	 */
+	public setPlaceholder(placeholder: string) {
+		this.data.placeholder = placeholder;
+		return this;
+	}
+
+	/**
+	 * Clears the placeholder for this text input.
+	 */
+	public clearPlaceholder() {
+		this.data.placeholder = undefined;
+		return this;
+	}
+
+	/**
+	 * Sets the value for this text input.
+	 *
+	 * @param value - The value to use
+	 */
+	public setValue(value: string) {
+		this.data.value = value;
+		return this;
+	}
+
+	/**
+	 * Clears the value for this text input.
+	 */
+	public clearValue() {
+		this.data.value = undefined;
+		return this;
+	}
+
+	/**
+	 * Sets whether this text input is required.
+	 *
+	 * @param required - Whether this text input is required
+	 */
+	public setRequired(required = true) {
+		this.data.required = required;
+		return this;
+	}
+
+	/**
+	 * {@inheritDoc ComponentBuilder.toJSON}
+	 */
+	public toJSON(validationOverride?: boolean): APITextInputComponent {
+		const clone = structuredClone(this.data);
+		validate(textInputPredicate, clone, validationOverride);
+
+		return clone as APITextInputComponent;
+	}
+}

package/src/components/v2/Assertions.ts

@@ -0,0 +1,82 @@
+import { ComponentType, SeparatorSpacingSize } from 'discord-api-types/v10';
+import { z } from 'zod';
+import { idPredicate } from '../../Assertions.js';
+import { actionRowPredicate } from '../Assertions.js';
+
+const unfurledMediaItemPredicate = z.object({
+	url: z.string().url().refine((url) => url.startsWith('http:') || url.startsWith('https:') || url.startsWith('attachment:'), { message: 'URL must use http, https, or attachment protocol' }),
+});
+
+export const thumbnailPredicate = z.object({
+	type: z.literal(ComponentType.Thumbnail),
+	id: idPredicate,
+	media: unfurledMediaItemPredicate,
+	description: z.string().min(1).max(1_024).nullish(),
+	spoiler: z.boolean().optional(),
+});
+
+const unfurledMediaItemAttachmentOnlyPredicate = z.object({
+	url: z.string().url().refine((url) => url.startsWith('attachment:'), { message: 'URL must use attachment protocol' }),
+});
+
+export const filePredicate = z.object({
+	type: z.literal(ComponentType.File),
+	id: idPredicate,
+	file: unfurledMediaItemAttachmentOnlyPredicate,
+	spoiler: z.boolean().optional(),
+});
+
+export const separatorPredicate = z.object({
+	type: z.literal(ComponentType.Separator),
+	id: idPredicate,
+	divider: z.boolean().optional(),
+	spacing: z.nativeEnum(SeparatorSpacingSize).optional(),
+});
+
+export const textDisplayPredicate = z.object({
+	type: z.literal(ComponentType.TextDisplay),
+	id: idPredicate,
+	content: z.string().min(1).max(4_000),
+});
+
+export const mediaGalleryItemPredicate = z.object({
+	id: idPredicate,
+	media: unfurledMediaItemPredicate,
+	description: z.string().min(1).max(1_024).nullish(),
+	spoiler: z.boolean().optional(),
+});
+
+export const mediaGalleryPredicate = z.object({
+	type: z.literal(ComponentType.MediaGallery),
+	id: idPredicate,
+	items: z.array(mediaGalleryItemPredicate).min(1).max(10),
+});
+
+export const sectionPredicate = z.object({
+	type: z.literal(ComponentType.Section),
+	id: idPredicate,
+	components: z.array(textDisplayPredicate).min(1).max(3),
+	accessory: z.union([
+		z.object({ type: z.literal(ComponentType.Button) }),
+		z.object({ type: z.literal(ComponentType.Thumbnail) }),
+	]),
+});
+
+export const containerPredicate = z.object({
+	type: z.literal(ComponentType.Container),
+	id: idPredicate,
+	components: z
+		.array(
+			z.union([
+				actionRowPredicate,
+				filePredicate,
+				mediaGalleryPredicate,
+				sectionPredicate,
+				separatorPredicate,
+				textDisplayPredicate,
+			]),
+		)
+		.min(1),
+	spoiler: z.boolean().optional(),
+	accent_color: z.number().int().min(0).max(0xffffff).nullish(),
+});