@ovencord/builders 1.11.1

package/src/components/label/Label.ts

@@ -0,0 +1,215 @@
+import type {
+	APIChannelSelectComponent,
+	APIFileUploadComponent,
+	APILabelComponent,
+	APIMentionableSelectComponent,
+	APIRoleSelectComponent,
+	APIStringSelectComponent,
+	APITextInputComponent,
+	APIUserSelectComponent,
+} from 'discord-api-types/v10';
+import { ComponentType } from 'discord-api-types/v10';
+import { resolveBuilder } from '../../util/resolveBuilder.js';
+import { validate } from '../../util/validation.js';
+import { ComponentBuilder } from '../Component.js';
+import { createComponentBuilder } from '../Components.js';
+import { FileUploadBuilder } from '../fileUpload/FileUpload.js';
+import { ChannelSelectMenuBuilder } from '../selectMenu/ChannelSelectMenu.js';
+import { MentionableSelectMenuBuilder } from '../selectMenu/MentionableSelectMenu.js';
+import { RoleSelectMenuBuilder } from '../selectMenu/RoleSelectMenu.js';
+import { StringSelectMenuBuilder } from '../selectMenu/StringSelectMenu.js';
+import { UserSelectMenuBuilder } from '../selectMenu/UserSelectMenu.js';
+import { TextInputBuilder } from '../textInput/TextInput.js';
+import { labelPredicate } from './Assertions.js';
+
+export interface LabelBuilderData extends Partial<Omit<APILabelComponent, 'component'>> {
+	component?:
+		| ChannelSelectMenuBuilder
+		| FileUploadBuilder
+		| MentionableSelectMenuBuilder
+		| RoleSelectMenuBuilder
+		| StringSelectMenuBuilder
+		| TextInputBuilder
+		| UserSelectMenuBuilder;
+}
+
+/**
+ * A builder that creates API-compatible JSON data for labels.
+ */
+export class LabelBuilder extends ComponentBuilder<APILabelComponent> {
+	/**
+	 * @internal
+	 */
+	protected readonly data: LabelBuilderData;
+
+	/**
+	 * Creates a new label.
+	 *
+	 * @param data - The API data to create this label with
+	 * @example
+	 * Creating a label from an API data object:
+	 * ```ts
+	 * const label = new LabelBuilder({
+	 * 	label: "label",
+	 * 	component,
+	 * });
+	 * ```
+	 * @example
+	 * Creating a label using setters and API data:
+	 * ```ts
+	 * const label = new LabelBuilder({
+	 * 	label: 'label',
+	 * 	component,
+	 * }).setContent('new text');
+	 * ```
+	 */
+	public constructor(data: Partial<APILabelComponent> = {}) {
+		super();
+
+		const { component, ...rest } = data;
+
+		this.data = {
+			...structuredClone(rest),
+			component: component ? (createComponentBuilder(component as any) as any) : undefined,
+			type: ComponentType.Label,
+		};
+	}
+
+	/**
+	 * Sets the label for this label.
+	 *
+	 * @param label - The label to use
+	 */
+	public setLabel(label: string) {
+		this.data.label = label;
+		return this;
+	}
+
+	/**
+	 * Sets the description for this label.
+	 *
+	 * @param description - The description to use
+	 */
+	public setDescription(description: string) {
+		this.data.description = description;
+		return this;
+	}
+
+	/**
+	 * Clears the description for this label.
+	 */
+	public clearDescription() {
+		this.data.description = undefined;
+		return this;
+	}
+
+	/**
+	 * Sets a string select menu component to this label.
+	 *
+	 * @param input - A function that returns a component builder or an already built builder
+	 */
+	public setStringSelectMenuComponent(
+		input:
+			| APIStringSelectComponent
+			| StringSelectMenuBuilder
+			| ((builder: StringSelectMenuBuilder) => StringSelectMenuBuilder),
+	): this {
+		this.data.component = resolveBuilder(input, StringSelectMenuBuilder);
+		return this;
+	}
+
+	/**
+	 * Sets a user select menu component to this label.
+	 *
+	 * @param input - A function that returns a component builder or an already built builder
+	 */
+	public setUserSelectMenuComponent(
+		input: APIUserSelectComponent | UserSelectMenuBuilder | ((builder: UserSelectMenuBuilder) => UserSelectMenuBuilder),
+	): this {
+		this.data.component = resolveBuilder(input, UserSelectMenuBuilder);
+		return this;
+	}
+
+	/**
+	 * Sets a role select menu component to this label.
+	 *
+	 * @param input - A function that returns a component builder or an already built builder
+	 */
+	public setRoleSelectMenuComponent(
+		input: APIRoleSelectComponent | RoleSelectMenuBuilder | ((builder: RoleSelectMenuBuilder) => RoleSelectMenuBuilder),
+	): this {
+		this.data.component = resolveBuilder(input, RoleSelectMenuBuilder);
+		return this;
+	}
+
+	/**
+	 * Sets a mentionable select menu component to this label.
+	 *
+	 * @param input - A function that returns a component builder or an already built builder
+	 */
+	public setMentionableSelectMenuComponent(
+		input:
+			| APIMentionableSelectComponent
+			| MentionableSelectMenuBuilder
+			| ((builder: MentionableSelectMenuBuilder) => MentionableSelectMenuBuilder),
+	): this {
+		this.data.component = resolveBuilder(input, MentionableSelectMenuBuilder);
+		return this;
+	}
+
+	/**
+	 * Sets a channel select menu component to this label.
+	 *
+	 * @param input - A function that returns a component builder or an already built builder
+	 */
+	public setChannelSelectMenuComponent(
+		input:
+			| APIChannelSelectComponent
+			| ChannelSelectMenuBuilder
+			| ((builder: ChannelSelectMenuBuilder) => ChannelSelectMenuBuilder),
+	): this {
+		this.data.component = resolveBuilder(input, ChannelSelectMenuBuilder);
+		return this;
+	}
+
+	/**
+	 * Sets a text input component to this label.
+	 *
+	 * @param input - A function that returns a component builder or an already built builder
+	 */
+	public setTextInputComponent(
+		input: APITextInputComponent | TextInputBuilder | ((builder: TextInputBuilder) => TextInputBuilder),
+	): this {
+		this.data.component = resolveBuilder(input, TextInputBuilder);
+		return this;
+	}
+
+	/**
+	 * Sets a file upload component to this label.
+	 *
+	 * @param input - A function that returns a component builder or an already built builder
+	 */
+	public setFileUploadComponent(
+		input: APIFileUploadComponent | FileUploadBuilder | ((builder: FileUploadBuilder) => FileUploadBuilder),
+	): this {
+		this.data.component = resolveBuilder(input, FileUploadBuilder);
+		return this;
+	}
+
+	/**
+	 * {@inheritDoc ComponentBuilder.toJSON}
+	 */
+	public override toJSON(validationOverride?: boolean): APILabelComponent {
+		const { component, ...rest } = this.data;
+
+		const data = {
+			...structuredClone(rest),
+			// The label predicate validates the component.
+			component: component?.toJSON(false),
+		};
+
+		validate(labelPredicate, data, validationOverride);
+
+		return data as APILabelComponent;
+	}
+}

package/src/components/selectMenu/BaseSelectMenu.ts

@@ -0,0 +1,89 @@
+import type { JSONEncodable } from '@ovencord/util';
+import type { APISelectMenuComponent } from 'discord-api-types/v10';
+import { ComponentBuilder } from '../Component.js';
+
+/**
+ * The base select menu builder that contains common symbols for select menu builders.
+ *
+ * @typeParam Data - The type of API data that is stored within the builder
+ */
+export abstract class BaseSelectMenuBuilder<Data extends APISelectMenuComponent>
+	extends ComponentBuilder<Data>
+	implements JSONEncodable<APISelectMenuComponent>
+{
+	/**
+	 * @internal
+	 */
+	protected abstract override readonly data: Partial<
+		Pick<Data, 'custom_id' | 'disabled' | 'id' | 'max_values' | 'min_values' | 'placeholder' | 'required'>
+	>;
+
+	/**
+	 * Sets the placeholder for this select menu.
+	 *
+	 * @param placeholder - The placeholder to use
+	 */
+	public setPlaceholder(placeholder: string) {
+		this.data.placeholder = placeholder;
+		return this;
+	}
+
+	/**
+	 * Clears the placeholder for this select menu.
+	 */
+	public clearPlaceholder() {
+		this.data.placeholder = undefined;
+		return this;
+	}
+
+	/**
+	 * Sets the minimum values that must be selected in the select menu.
+	 *
+	 * @param minValues - The minimum values that must be selected
+	 */
+	public setMinValues(minValues: number) {
+		this.data.min_values = minValues;
+		return this;
+	}
+
+	/**
+	 * Sets the maximum values that can be selected in the select menu.
+	 *
+	 * @param maxValues - The maximum values that can be selected
+	 */
+	public setMaxValues(maxValues: number) {
+		this.data.max_values = maxValues;
+		return this;
+	}
+
+	/**
+	 * Sets the custom id for this select menu.
+	 *
+	 * @param customId - The custom id to use
+	 */
+	public setCustomId(customId: string) {
+		this.data.custom_id = customId;
+		return this;
+	}
+
+	/**
+	 * Sets whether this select menu is disabled.
+	 *
+	 * @param disabled - Whether this select menu is disabled
+	 */
+	public setDisabled(disabled = true) {
+		this.data.disabled = disabled;
+		return this;
+	}
+
+	/**
+	 * Sets whether this select menu is required.
+	 *
+	 * @remarks Only for use in modals.
+	 * @param required - Whether this string select menu is required
+	 */
+	public setRequired(required = true) {
+		this.data.required = required;
+		return this;
+	}
+}

package/src/components/selectMenu/ChannelSelectMenu.ts

@@ -0,0 +1,115 @@
+import {
+	type APIChannelSelectComponent,
+	type ChannelType,
+	type Snowflake,
+	ComponentType,
+	SelectMenuDefaultValueType,
+} from 'discord-api-types/v10';
+import { type RestOrArray, normalizeArray } from '../../util/normalizeArray.js';
+import { validate } from '../../util/validation.js';
+import { selectMenuChannelPredicate } from '../Assertions.js';
+import { BaseSelectMenuBuilder } from './BaseSelectMenu.js';
+
+/**
+ * A builder that creates API-compatible JSON data for channel select menus.
+ */
+export class ChannelSelectMenuBuilder extends BaseSelectMenuBuilder<APIChannelSelectComponent> {
+	protected override readonly data: Partial<APIChannelSelectComponent>;
+
+	/**
+	 * Creates a new channel select menu.
+	 *
+	 * @param data - The API data to create this channel select menu with
+	 * @example
+	 * Creating a select menu from an API data object:
+	 * ```ts
+	 * const selectMenu = new ChannelSelectMenuBuilder({
+	 * 	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 ChannelSelectMenuBuilder({
+	 * 	custom_id: 'a cool select menu',
+	 * })
+	 * 	.addChannelTypes(ChannelType.GuildText, ChannelType.GuildAnnouncement)
+	 * 	.setMinValues(2);
+	 * ```
+	 */
+	public constructor(data: Partial<APIChannelSelectComponent> = {}) {
+		super();
+		this.data = { ...structuredClone(data), type: ComponentType.ChannelSelect };
+	}
+
+	/**
+	 * Adds channel types to this select menu.
+	 *
+	 * @param types - The channel types to use
+	 */
+	public addChannelTypes(...types: RestOrArray<ChannelType>) {
+		const normalizedTypes = normalizeArray(types);
+		this.data.channel_types ??= [];
+		this.data.channel_types.push(...normalizedTypes);
+		return this;
+	}
+
+	/**
+	 * Sets channel types for this select menu.
+	 *
+	 * @param types - The channel types to use
+	 */
+	public setChannelTypes(...types: RestOrArray<ChannelType>) {
+		const normalizedTypes = normalizeArray(types);
+		this.data.channel_types ??= [];
+		this.data.channel_types.splice(0, this.data.channel_types.length, ...normalizedTypes);
+		return this;
+	}
+
+	/**
+	 * Adds default channels to this auto populated select menu.
+	 *
+	 * @param channels - The channels to add
+	 */
+	public addDefaultChannels(...channels: RestOrArray<Snowflake>) {
+		const normalizedValues = normalizeArray(channels);
+		this.data.default_values ??= [];
+
+		this.data.default_values.push(
+			...normalizedValues.map((id) => ({
+				id,
+				type: SelectMenuDefaultValueType.Channel as const,
+			})),
+		);
+
+		return this;
+	}
+
+	/**
+	 * Sets default channels for this auto populated select menu.
+	 *
+	 * @param channels - The channels to set
+	 */
+	public setDefaultChannels(...channels: RestOrArray<Snowflake>) {
+		const normalizedValues = normalizeArray(channels);
+
+		this.data.default_values = normalizedValues.map((id) => ({
+			id,
+			type: SelectMenuDefaultValueType.Channel as const,
+		}));
+
+		return this;
+	}
+
+	/**
+	 * {@inheritDoc ComponentBuilder.toJSON}
+	 */
+	public override toJSON(validationOverride?: boolean): APIChannelSelectComponent {
+		const clone = structuredClone(this.data);
+		validate(selectMenuChannelPredicate, clone, validationOverride);
+
+		return clone as APIChannelSelectComponent;
+	}
+}

package/src/components/selectMenu/MentionableSelectMenu.ts

@@ -0,0 +1,126 @@
+import {
+	type APIMentionableSelectComponent,
+	type APISelectMenuDefaultValue,
+	type Snowflake,
+	ComponentType,
+	SelectMenuDefaultValueType,
+} from 'discord-api-types/v10';
+import { type RestOrArray, normalizeArray } from '../../util/normalizeArray.js';
+import { validate } from '../../util/validation.js';
+import { selectMenuMentionablePredicate } from '../Assertions.js';
+import { BaseSelectMenuBuilder } from './BaseSelectMenu.js';
+
+/**
+ * A builder that creates API-compatible JSON data for mentionable select menus.
+ */
+export class MentionableSelectMenuBuilder extends BaseSelectMenuBuilder<APIMentionableSelectComponent> {
+	protected override readonly data: Partial<APIMentionableSelectComponent>;
+
+	/**
+	 * Creates a new mentionable select menu.
+	 *
+	 * @param data - The API data to create this mentionable select menu with
+	 * @example
+	 * Creating a select menu from an API data object:
+	 * ```ts
+	 * const selectMenu = new MentionableSelectMenuBuilder({
+	 * 	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 MentionableSelectMenuBuilder({
+	 * 	custom_id: 'a cool select menu',
+	 * })
+	 * 	.setMinValues(1);
+	 * ```
+	 */
+	public constructor(data: Partial<APIMentionableSelectComponent> = {}) {
+		super();
+		this.data = { ...structuredClone(data), type: ComponentType.MentionableSelect };
+	}
+
+	/**
+	 * Adds default roles to this auto populated select menu.
+	 *
+	 * @param roles - The roles to add
+	 */
+	public addDefaultRoles(...roles: RestOrArray<Snowflake>) {
+		const normalizedValues = normalizeArray(roles);
+		this.data.default_values ??= [];
+
+		this.data.default_values.push(
+			...normalizedValues.map((id) => ({
+				id,
+				type: SelectMenuDefaultValueType.Role as const,
+			})),
+		);
+
+		return this;
+	}
+
+	/**
+	 * 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;
+	}
+
+	/**
+	 * Adds default values to this auto populated select menu.
+	 *
+	 * @param values - The values to add
+	 */
+	public addDefaultValues(
+		...values: RestOrArray<
+			| APISelectMenuDefaultValue<SelectMenuDefaultValueType.Role>
+			| APISelectMenuDefaultValue<SelectMenuDefaultValueType.User>
+		>
+	) {
+		const normalizedValues = normalizeArray(values);
+		this.data.default_values ??= [];
+		this.data.default_values.push(...normalizedValues);
+		return this;
+	}
+
+	/**
+	 * Sets default values for this auto populated select menu.
+	 *
+	 * @param values - The values to set
+	 */
+	public setDefaultValues(
+		...values: RestOrArray<
+			| APISelectMenuDefaultValue<SelectMenuDefaultValueType.Role>
+			| APISelectMenuDefaultValue<SelectMenuDefaultValueType.User>
+		>
+	) {
+		const normalizedValues = normalizeArray(values);
+		this.data.default_values = normalizedValues;
+		return this;
+	}
+
+	/**
+	 * {@inheritDoc ComponentBuilder.toJSON}
+	 */
+	public override toJSON(validationOverride?: boolean): APIMentionableSelectComponent {
+		const clone = structuredClone(this.data);
+		validate(selectMenuMentionablePredicate, clone, validationOverride);
+
+		return clone as APIMentionableSelectComponent;
+	}
+}

package/src/components/selectMenu/RoleSelectMenu.ts

@@ -0,0 +1,89 @@
+import {
+	type APIRoleSelectComponent,
+	type Snowflake,
+	ComponentType,
+	SelectMenuDefaultValueType,
+} from 'discord-api-types/v10';
+import { type RestOrArray, normalizeArray } from '../../util/normalizeArray.js';
+import { validate } from '../../util/validation.js';
+import { selectMenuRolePredicate } from '../Assertions.js';
+import { BaseSelectMenuBuilder } from './BaseSelectMenu.js';
+
+/**
+ * A builder that creates API-compatible JSON data for role select menus.
+ */
+export class RoleSelectMenuBuilder extends BaseSelectMenuBuilder<APIRoleSelectComponent> {
+	protected override readonly data: Partial<APIRoleSelectComponent>;
+
+	/**
+	 * Creates a new role select menu.
+	 *
+	 * @param data - The API data to create this role select menu with
+	 * @example
+	 * Creating a select menu from an API data object:
+	 * ```ts
+	 * const selectMenu = new RoleSelectMenuBuilder({
+	 * 	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 RoleSelectMenuBuilder({
+	 * 	custom_id: 'a cool select menu',
+	 * })
+	 * 	.setMinValues(1);
+	 * ```
+	 */
+	public constructor(data: Partial<APIRoleSelectComponent> = {}) {
+		super();
+		this.data = { ...structuredClone(data), type: ComponentType.RoleSelect };
+	}
+
+	/**
+	 * Adds default roles to this auto populated select menu.
+	 *
+	 * @param roles - The roles to add
+	 */
+	public addDefaultRoles(...roles: RestOrArray<Snowflake>) {
+		const normalizedValues = normalizeArray(roles);
+		this.data.default_values ??= [];
+
+		this.data.default_values.push(
+			...normalizedValues.map((id) => ({
+				id,
+				type: SelectMenuDefaultValueType.Role as const,
+			})),
+		);
+
+		return this;
+	}
+
+	/**
+	 * Sets default roles for this auto populated select menu.
+	 *
+	 * @param roles - The roles to set
+	 */
+	public setDefaultRoles(...roles: RestOrArray<Snowflake>) {
+		const normalizedValues = normalizeArray(roles);
+
+		this.data.default_values = normalizedValues.map((id) => ({
+			id,
+			type: SelectMenuDefaultValueType.Role as const,
+		}));
+
+		return this;
+	}
+
+	/**
+	 * {@inheritDoc ComponentBuilder.toJSON}
+	 */
+	public override toJSON(validationOverride?: boolean): APIRoleSelectComponent {
+		const clone = structuredClone(this.data);
+		validate(selectMenuRolePredicate, clone, validationOverride);
+
+		return clone as APIRoleSelectComponent;
+	}
+}