@ovencord/builders 1.11.1

package/src/components/v2/Section.ts

@@ -0,0 +1,266 @@
+import type {
+	APITextDisplayComponent,
+	APISectionComponent,
+	APIButtonComponentWithCustomId,
+	APIThumbnailComponent,
+	APIButtonComponentWithSKUId,
+	APIButtonComponentWithURL,
+	ButtonStyle,
+} from 'discord-api-types/v10';
+import { 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 { resolveAccessoryComponent, type ButtonBuilder } from '../Components.js';
+import {
+	DangerButtonBuilder,
+	PrimaryButtonBuilder,
+	SecondaryButtonBuilder,
+	SuccessButtonBuilder,
+} from '../button/CustomIdButton.js';
+import { LinkButtonBuilder } from '../button/LinkButton.js';
+import { PremiumButtonBuilder } from '../button/PremiumButton.js';
+import { sectionPredicate } from './Assertions.js';
+import { TextDisplayBuilder } from './TextDisplay.js';
+import { ThumbnailBuilder } from './Thumbnail.js';
+
+export type SectionBuilderAccessory = ButtonBuilder | ThumbnailBuilder;
+
+export interface SectionBuilderData extends Partial<Omit<APISectionComponent, 'accessory' | 'components'>> {
+	accessory?: SectionBuilderAccessory;
+	components: TextDisplayBuilder[];
+}
+
+/**
+ * A builder that creates API-compatible JSON data for sections.
+ */
+export class SectionBuilder extends ComponentBuilder<APISectionComponent> {
+	/**
+	 * @internal
+	 */
+	protected readonly data: SectionBuilderData;
+
+	/**
+	 * The components within this section.
+	 */
+	public get components(): readonly TextDisplayBuilder[] {
+		return this.data.components;
+	}
+
+	/**
+	 * Creates a new section.
+	 *
+	 * @param data - The API data to create this section with
+	 * @example
+	 * Creating a section from an API data object:
+	 * ```ts
+	 * const section = new SectionBuilder({
+	 * 	components: [
+	 * 		{
+	 * 			content: "Some text here",
+	 * 			type: ComponentType.TextDisplay,
+	 * 		},
+	 * 	],
+	 *  accessory: {
+	 *      media: {
+	 *          url: 'https://cdn.discordapp.com/embed/avatars/3.png',
+	 *      },
+	 *  }
+	 * });
+	 * ```
+	 * @example
+	 * Creating a section using setters and API data:
+	 * ```ts
+	 * const section = new SectionBuilder({
+	 * 	components: [
+	 * 		{
+	 * 			content: "# Heading",
+	 * 			type: ComponentType.TextDisplay,
+	 * 		},
+	 * 	],
+	 * })
+	 * 	.setPrimaryButtonAccessory(button);
+	 * ```
+	 */
+	public constructor(data: Partial<APISectionComponent> = {}) {
+		super();
+
+		const { components = [], accessory, ...rest } = data;
+
+		this.data = {
+			...structuredClone(rest),
+			accessory: accessory && resolveAccessoryComponent(accessory),
+			components: components.map((component) => new TextDisplayBuilder(component)),
+			type: ComponentType.Section,
+		};
+	}
+
+	/**
+	 * Adds text display components to this section.
+	 *
+	 * @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;
+	}
+
+	/**
+	 * Sets a primary button component to be the accessory of this section.
+	 *
+	 * @param input - The button to set as the accessory
+	 */
+	public setPrimaryButtonAccessory(
+		input:
+			| PrimaryButtonBuilder
+			| ((builder: PrimaryButtonBuilder) => PrimaryButtonBuilder)
+			| (APIButtonComponentWithCustomId & { style: ButtonStyle.Primary }),
+	): this {
+		const builder = resolveBuilder(input, PrimaryButtonBuilder);
+
+		this.data.accessory = builder;
+		return this;
+	}
+
+	/**
+	 * Sets a secondary button component to be the accessory of this section.
+	 *
+	 * @param input - The button to set as the accessory
+	 */
+	public setSecondaryButtonAccessory(
+		input:
+			| SecondaryButtonBuilder
+			| ((builder: SecondaryButtonBuilder) => SecondaryButtonBuilder)
+			| (APIButtonComponentWithCustomId & { style: ButtonStyle.Secondary }),
+	): this {
+		const builder = resolveBuilder(input, SecondaryButtonBuilder);
+
+		this.data.accessory = builder;
+		return this;
+	}
+
+	/**
+	 * Sets a success button component to be the accessory of this section.
+	 *
+	 * @param input - The button to set as the accessory
+	 */
+	public setSuccessButtonAccessory(
+		input:
+			| SuccessButtonBuilder
+			| ((builder: SuccessButtonBuilder) => SuccessButtonBuilder)
+			| (APIButtonComponentWithCustomId & { style: ButtonStyle.Success }),
+	): this {
+		const builder = resolveBuilder(input, SuccessButtonBuilder);
+
+		this.data.accessory = builder;
+		return this;
+	}
+
+	/**
+	 * Sets a danger button component to be the accessory of this section.
+	 *
+	 * @param input - The button to set as the accessory
+	 */
+	public setDangerButtonAccessory(
+		input:
+			| DangerButtonBuilder
+			| ((builder: DangerButtonBuilder) => DangerButtonBuilder)
+			| (APIButtonComponentWithCustomId & { style: ButtonStyle.Danger }),
+	): this {
+		const builder = resolveBuilder(input, DangerButtonBuilder);
+
+		this.data.accessory = builder;
+		return this;
+	}
+
+	/**
+	 * Sets a SKU id button component to be the accessory of this section.
+	 *
+	 * @param input - The button to set as the accessory
+	 */
+	public setPremiumButtonAccessory(
+		input:
+			| APIButtonComponentWithSKUId
+			| PremiumButtonBuilder
+			| ((builder: PremiumButtonBuilder) => PremiumButtonBuilder),
+	): this {
+		const builder = resolveBuilder(input, PremiumButtonBuilder);
+
+		this.data.accessory = builder;
+		return this;
+	}
+
+	/**
+	 * Sets a URL button component to be the accessory of this section.
+	 *
+	 * @param input - The button to set as the accessory
+	 */
+	public setLinkButtonAccessory(
+		input: APIButtonComponentWithURL | LinkButtonBuilder | ((builder: LinkButtonBuilder) => LinkButtonBuilder),
+	): this {
+		const builder = resolveBuilder(input, LinkButtonBuilder);
+
+		this.data.accessory = builder;
+		return this;
+	}
+
+	/**
+	 * Sets a thumbnail component to be the accessory of this section.
+	 *
+	 * @param input - The thumbnail to set as the accessory
+	 */
+	public setThumbnailAccessory(
+		input: APIThumbnailComponent | ThumbnailBuilder | ((builder: ThumbnailBuilder) => ThumbnailBuilder),
+	): this {
+		const builder = resolveBuilder(input, ThumbnailBuilder);
+
+		this.data.accessory = builder;
+		return this;
+	}
+
+	/**
+	 * Removes, replaces, or inserts text display components for this section.
+	 *
+	 * @param index - The index to start removing, replacing or inserting text display components
+	 * @param deleteCount - The amount of text display components to remove
+	 * @param components - The text display components to insert
+	 */
+	public spliceTextDisplayComponents(
+		index: number,
+		deleteCount: number,
+		...components: RestOrArray<
+			APITextDisplayComponent | TextDisplayBuilder | ((builder: TextDisplayBuilder) => TextDisplayBuilder)
+		>
+	): this {
+		const normalized = normalizeArray(components);
+		const resolved = normalized.map((component) => resolveBuilder(component, TextDisplayBuilder));
+
+		this.data.components.splice(index, deleteCount, ...resolved);
+		return this;
+	}
+
+	/**
+	 * {@inheritDoc ComponentBuilder.toJSON}
+	 */
+	public override toJSON(validationOverride?: boolean): APISectionComponent {
+		const { components, accessory, ...rest } = this.data;
+
+		const data = {
+			...structuredClone(rest),
+			components: components.map((component) => component.toJSON(false)),
+			accessory: accessory?.toJSON(validationOverride),
+		};
+
+		validate(sectionPredicate, data, validationOverride);
+
+		return data as APISectionComponent;
+	}
+}

package/src/components/v2/Separator.ts

@@ -0,0 +1,82 @@
+import type { SeparatorSpacingSize, APISeparatorComponent } from 'discord-api-types/v10';
+import { ComponentType } from 'discord-api-types/v10';
+import { validate } from '../../util/validation.js';
+import { ComponentBuilder } from '../Component.js';
+import { separatorPredicate } from './Assertions.js';
+
+/**
+ * A builder that creates API-compatible JSON data for separators.
+ */
+export class SeparatorBuilder extends ComponentBuilder<APISeparatorComponent> {
+	/**
+	 * @internal
+	 */
+	protected readonly data: Partial<APISeparatorComponent>;
+
+	/**
+	 * Creates a new separator.
+	 *
+	 * @param data - The API data to create this separator with
+	 * @example
+	 * Creating a separator from an API data object:
+	 * ```ts
+	 * const separator = new SeparatorBuilder({
+	 * 	spacing: SeparatorSpacingSize.Small,
+	 *  divider: true,
+	 * });
+	 * ```
+	 * @example
+	 * Creating a separator using setters and API data:
+	 * ```ts
+	 * const separator = new SeparatorBuilder({
+	 * 	spacing: SeparatorSpacingSize.Large,
+	 * })
+	 * 	.setDivider(false);
+	 * ```
+	 */
+	public constructor(data: Partial<APISeparatorComponent> = {}) {
+		super();
+		this.data = {
+			...structuredClone(data),
+			type: ComponentType.Separator,
+		};
+	}
+
+	/**
+	 * Sets whether this separator should show a divider line.
+	 *
+	 * @param divider - Whether to show a divider line
+	 */
+	public setDivider(divider = true) {
+		this.data.divider = divider;
+		return this;
+	}
+
+	/**
+	 * Sets the spacing of this separator.
+	 *
+	 * @param spacing - The spacing to use
+	 */
+	public setSpacing(spacing: SeparatorSpacingSize) {
+		this.data.spacing = spacing;
+		return this;
+	}
+
+	/**
+	 * Clears the spacing of this separator.
+	 */
+	public clearSpacing() {
+		this.data.spacing = undefined;
+		return this;
+	}
+
+	/**
+	 * {@inheritDoc ComponentBuilder.toJSON}
+	 */
+	public override toJSON(validationOverride?: boolean): APISeparatorComponent {
+		const clone = structuredClone(this.data);
+		validate(separatorPredicate, clone, validationOverride);
+
+		return clone as APISeparatorComponent;
+	}
+}

package/src/components/v2/TextDisplay.ts

@@ -0,0 +1,63 @@
+import type { APITextDisplayComponent } from 'discord-api-types/v10';
+import { ComponentType } from 'discord-api-types/v10';
+import { validate } from '../../util/validation.js';
+import { ComponentBuilder } from '../Component.js';
+import { textDisplayPredicate } from './Assertions.js';
+
+/**
+ * A builder that creates API-compatible JSON data for text displays.
+ */
+export class TextDisplayBuilder extends ComponentBuilder<APITextDisplayComponent> {
+	/**
+	 * @internal
+	 */
+	protected readonly data: Partial<APITextDisplayComponent>;
+
+	/**
+	 * Creates a new text display.
+	 *
+	 * @param data - The API data to create this text display with
+	 * @example
+	 * Creating a text display from an API data object:
+	 * ```ts
+	 * const textDisplay = new TextDisplayBuilder({
+	 * 	content: 'some text',
+	 * });
+	 * ```
+	 * @example
+	 * Creating a text display using setters and API data:
+	 * ```ts
+	 * const textDisplay = new TextDisplayBuilder({
+	 * 	content: 'old text',
+	 * })
+	 * 	.setContent('new text');
+	 * ```
+	 */
+	public constructor(data: Partial<APITextDisplayComponent> = {}) {
+		super();
+		this.data = {
+			...structuredClone(data),
+			type: ComponentType.TextDisplay,
+		};
+	}
+
+	/**
+	 * Sets the text of this text display.
+	 *
+	 * @param content - The text to use
+	 */
+	public setContent(content: string) {
+		this.data.content = content;
+		return this;
+	}
+
+	/**
+	 * {@inheritDoc ComponentBuilder.toJSON}
+	 */
+	public override toJSON(validationOverride?: boolean): APITextDisplayComponent {
+		const clone = structuredClone(this.data);
+		validate(textDisplayPredicate, clone, validationOverride);
+
+		return clone as APITextDisplayComponent;
+	}
+}

package/src/components/v2/Thumbnail.ts

@@ -0,0 +1,100 @@
+import type { APIThumbnailComponent } from 'discord-api-types/v10';
+import { ComponentType } from 'discord-api-types/v10';
+import { validate } from '../../util/validation.js';
+import { ComponentBuilder } from '../Component.js';
+import { thumbnailPredicate } from './Assertions.js';
+
+/**
+ * A builder that creates API-compatible JSON data for thumbnails.
+ */
+export class ThumbnailBuilder extends ComponentBuilder<APIThumbnailComponent> {
+	/**
+	 * @internal
+	 */
+	protected readonly data: Partial<APIThumbnailComponent>;
+
+	/**
+	 * Creates a new thumbnail.
+	 *
+	 * @param data - The API data to create this thumbnail with
+	 * @example
+	 * Creating a thumbnail from an API data object:
+	 * ```ts
+	 * const thumbnail = new ThumbnailBuilder({
+	 * 	description: 'some text',
+	 *  media: {
+	 *      url: 'https://cdn.discordapp.com/embed/avatars/4.png',
+	 *  },
+	 * });
+	 * ```
+	 * @example
+	 * Creating a thumbnail using setters and API data:
+	 * ```ts
+	 * const thumbnail = new ThumbnailBuilder({
+	 * 	media: {
+	 *      url: 'attachment://image.png',
+	 *  },
+	 * })
+	 * 	.setDescription('alt text');
+	 * ```
+	 */
+	public constructor(data: Partial<APIThumbnailComponent> = {}) {
+		super();
+
+		const { media, ...rest } = data;
+
+		this.data = {
+			...structuredClone(rest),
+			media: media && { url: media.url },
+			type: ComponentType.Thumbnail,
+		};
+	}
+
+	/**
+	 * 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;
+	}
+
+	/**
+	 * Sets the media URL of this thumbnail.
+	 *
+	 * @param url - The URL to use
+	 */
+	public setURL(url: string) {
+		this.data.media = { url };
+		return this;
+	}
+
+	/**
+	 * {@inheritdoc ComponentBuilder.toJSON}
+	 */
+	public override toJSON(validationOverride?: boolean): APIThumbnailComponent {
+		const clone = structuredClone(this.data);
+		validate(thumbnailPredicate, clone, validationOverride);
+
+		return clone as APIThumbnailComponent;
+	}
+}

package/src/index.ts

@@ -0,0 +1,109 @@
+export * from './components/button/mixins/EmojiOrLabelButtonMixin.js';
+export * from './components/button/Button.js';
+export * from './components/button/CustomIdButton.js';
+export * from './components/button/LinkButton.js';
+export * from './components/button/PremiumButton.js';
+
+export * from './components/fileUpload/FileUpload.js';
+export * from './components/fileUpload/Assertions.js';
+
+export * from './components/label/Label.js';
+export * from './components/label/Assertions.js';
+
+export * from './components/selectMenu/BaseSelectMenu.js';
+export * from './components/selectMenu/ChannelSelectMenu.js';
+export * from './components/selectMenu/MentionableSelectMenu.js';
+export * from './components/selectMenu/RoleSelectMenu.js';
+export * from './components/selectMenu/StringSelectMenu.js';
+export * from './components/selectMenu/StringSelectMenuOption.js';
+export * from './components/selectMenu/UserSelectMenu.js';
+
+export * from './components/textInput/TextInput.js';
+export * from './components/textInput/Assertions.js';
+
+export * from './components/ActionRow.js';
+export * from './components/Assertions.js';
+export * from './components/Component.js';
+export * from './components/Components.js';
+
+export * from './components/v2/Assertions.js';
+export * from './components/v2/Container.js';
+export * from './components/v2/File.js';
+export * from './components/v2/MediaGallery.js';
+export * from './components/v2/MediaGalleryItem.js';
+export * from './components/v2/Section.js';
+export * from './components/v2/Separator.js';
+export * from './components/v2/TextDisplay.js';
+export * from './components/v2/Thumbnail.js';
+
+export * from './interactions/commands/chatInput/mixins/ApplicationCommandNumericOptionMinMaxValueMixin.js';
+export * from './interactions/commands/chatInput/mixins/ApplicationCommandOptionChannelTypesMixin.js';
+export * from './interactions/commands/chatInput/mixins/ApplicationCommandOptionWithAutocompleteMixin.js';
+export * from './interactions/commands/chatInput/mixins/ApplicationCommandOptionWithChoicesMixin.js';
+export * from './interactions/commands/chatInput/mixins/SharedChatInputCommandOptions.js';
+export * from './interactions/commands/chatInput/mixins/SharedSubcommands.js';
+
+export * from './interactions/commands/chatInput/options/ApplicationCommandOptionBase.js';
+export * from './interactions/commands/chatInput/options/boolean.js';
+export * from './interactions/commands/chatInput/options/channel.js';
+export * from './interactions/commands/chatInput/options/integer.js';
+export * from './interactions/commands/chatInput/options/mentionable.js';
+export * from './interactions/commands/chatInput/options/number.js';
+export * from './interactions/commands/chatInput/options/role.js';
+export * from './interactions/commands/chatInput/options/attachment.js';
+export * from './interactions/commands/chatInput/options/string.js';
+export * from './interactions/commands/chatInput/options/user.js';
+
+export * from './interactions/commands/chatInput/Assertions.js';
+export * from './interactions/commands/chatInput/ChatInputCommand.js';
+export { ChatInputCommandBuilder as SlashCommandBuilder } from './interactions/commands/chatInput/ChatInputCommand.js';
+export * from './interactions/commands/chatInput/ChatInputCommandSubcommands.js';
+
+export * from './interactions/commands/contextMenu/Assertions.js';
+export * from './interactions/commands/contextMenu/ContextMenuCommand.js';
+export * from './interactions/commands/contextMenu/MessageCommand.js';
+export * from './interactions/commands/contextMenu/UserCommand.js';
+
+export * from './interactions/commands/Command.js';
+export * from './interactions/commands/SharedName.js';
+export * from './interactions/commands/SharedNameAndDescription.js';
+
+export * from './interactions/modals/Assertions.js';
+export * from './interactions/modals/Modal.js';
+
+export * from './messages/embed/Assertions.js';
+export * from './messages/embed/Embed.js';
+export * from './messages/embed/EmbedAuthor.js';
+export * from './messages/embed/EmbedField.js';
+export * from './messages/embed/EmbedFooter.js';
+
+export * from './messages/poll/Assertions.js';
+export * from './messages/poll/Poll.js';
+export * from './messages/poll/PollAnswer.js';
+export * from './messages/poll/PollAnswerMedia.js';
+export * from './messages/poll/PollMedia.js';
+export * from './messages/poll/PollQuestion.js';
+
+export * from './messages/AllowedMentions.js';
+export * from './messages/Assertions.js';
+export * from './messages/Attachment.js';
+export * from './messages/Message.js';
+export * from './messages/MessageReference.js';
+
+export * from './util/normalizeArray.js';
+export * from './util/resolveBuilder.js';
+export { disableValidators, enableValidators, isValidationEnabled } from './util/validation.js';
+export * from './util/ValidationError.js';
+
+export * from './Assertions.js';
+
+// We expose this type in our public API. We shouldn't assume every user of builders is also using REST
+export type { RawFile } from '@ovencord/util';
+
+/**
+ * The {@link https://github.com/ovencord/ovencord/blob/main/packages/builders#readme | @ovencord/builders} version
+ * that you are currently using.
+ *
+ * @privateRemarks This needs to explicitly be `string` so it is not typed as a "const string" that gets injected by esbuild.
+ */
+export const version = '[VI]{{inject}}[/VI]' as string;