Nomchy/discord.js
1
0
Fork 0
mirror of https://github.com/discordjs/discord.js.git synced 2026-03-15 02:53:31 +01:00
Code Issues Packages Projects Releases Wiki Activity

docs(builders): Add some basic documentation (#9359)

Browse Source
This commit is contained in:
Jiralite
2023-04-10 21:09:51 +01:00
committed by GitHub
parent c0f2dd7131
commit 8073561824
36 changed files with 690 additions and 300 deletions
Download Patch File Download Diff File Expand all files Collapse all files

35
packages/builders/src/components/ActionRow.ts
View File

@@ -18,10 +18,21 @@ import type { StringSelectMenuBuilder } from './selectMenu/StringSelectMenu.js';
import type { UserSelectMenuBuilder } from './selectMenu/UserSelectMenu.js';
import type { TextInputBuilder } from './textInput/TextInput.js';
/**
* The builders that may be used for messages.
*/
export type MessageComponentBuilder =
| ActionRowBuilder<MessageActionRowComponentBuilder>
| MessageActionRowComponentBuilder;
/**
* The builders that may be used for modals.
*/
export type ModalComponentBuilder = ActionRowBuilder<ModalActionRowComponentBuilder> | ModalActionRowComponentBuilder;
/**
* The builders that may be used within an action row for messages.
*/
export type MessageActionRowComponentBuilder =
| ButtonBuilder
| ChannelSelectMenuBuilder
@@ -29,11 +40,19 @@ export type MessageActionRowComponentBuilder =
| RoleSelectMenuBuilder
| StringSelectMenuBuilder
| UserSelectMenuBuilder;
/**
* The builders that may be used within an action row for modals.
*/
export type ModalActionRowComponentBuilder = TextInputBuilder;
/**
* Any builder.
*/
export type AnyComponentBuilder = MessageActionRowComponentBuilder | ModalActionRowComponentBuilder;
/**
* Represents an action row component
* A builder that creates API-compatible JSON data for action rows.
*
* @typeParam T - The types of components this action row holds
*/
@@ -41,16 +60,16 @@ export class ActionRowBuilder<T extends AnyComponentBuilder> extends ComponentBu
APIActionRowComponent<APIMessageActionRowComponent | APIModalActionRowComponent>
> {
/**
* The components within this action row
* The components within this action row.
*/
public readonly components: T[];
/**
* Creates a new action row from API data
* Creates a new action row from API data.
*
* @param data - The API data to create this action row with
* @example
* Creating an action row from an API data object
* Creating an action row from an API data object:
* ```ts
* const actionRow = new ActionRowBuilder({
* components: [
@@ -64,7 +83,7 @@ export class ActionRowBuilder<T extends AnyComponentBuilder> extends ComponentBu
* });
* ```
* @example
* Creating an action row using setters and API data
* Creating an action row using setters and API data:
* ```ts
* const actionRow = new ActionRowBuilder({
* components: [
@@ -87,7 +106,7 @@ export class ActionRowBuilder<T extends AnyComponentBuilder> extends ComponentBu
/**
* Adds components to this action row.
*
* @param components - The components to add to this action row.
* @param components - The components to add
*/
public addComponents(...components: RestOrArray<T>) {
this.components.push(...normalizeArray(components));
@@ -95,9 +114,9 @@ export class ActionRowBuilder<T extends AnyComponentBuilder> extends ComponentBu
}
/**
* Sets the components in this action row
* Sets components for this action row.
*
* @param components - The components to set this row to
* @param components - The components to set
*/
public setComponents(...components: RestOrArray<T>) {
this.components.splice(0, this.components.length, ...normalizeArray(components));

14
packages/builders/src/components/Component.ts
View File

@@ -6,10 +6,13 @@ import type {
ComponentType,
} from 'discord-api-types/v10';
/**
* Any action row component data represented as an object.
*/
export type AnyAPIActionRowComponent = APIActionRowComponent<APIActionRowComponentTypes> | APIActionRowComponentTypes;
/**
* Represents a discord component
* The base component builder that contains common symbols for all sorts of components.
*
* @typeParam DataType - The type of internal API data that is stored within the component
*/
@@ -18,12 +21,12 @@ export abstract class ComponentBuilder<
> implements JSONEncodable<AnyAPIActionRowComponent>
{
/**
* The API data associated with this component
* The API data associated with this component.
*/
public readonly data: Partial<DataType>;
/**
* Serializes this component to an API-compatible JSON object
* Serializes this builder to API-compatible JSON data.
*
* @remarks
* This method runs validations on the data before serializing it.
@@ -31,6 +34,11 @@ export abstract class ComponentBuilder<
*/
public abstract toJSON(): AnyAPIActionRowComponent;
/**
* Constructs a new kind of component.
*
* @param data - The data to construct a component out of
*/
public constructor(data: Partial<DataType>) {
this.data = data;
}

42
packages/builders/src/components/Components.ts
View File

@@ -14,27 +14,63 @@ import { StringSelectMenuBuilder } from './selectMenu/StringSelectMenu.js';
import { UserSelectMenuBuilder } from './selectMenu/UserSelectMenu.js';
import { TextInputBuilder } from './textInput/TextInput.js';
/**
* Components here are mapped to their respective builder.
*/
export interface MappedComponentTypes {
/**
* The action row component type is associated with an {@link ActionRowBuilder}.
*/
[ComponentType.ActionRow]: ActionRowBuilder<AnyComponentBuilder>;
/**
* The button component type is associated with an {@link ButtonBuilder}.
*/
[ComponentType.Button]: ButtonBuilder;
/**
* The string select component type is associated with an {@link StringSelectMenuBuilder}.
*/
[ComponentType.StringSelect]: StringSelectMenuBuilder;
/**
* The text inpiut component type is associated with an {@link TextInputBuilder}.
*/
[ComponentType.TextInput]: TextInputBuilder;
/**
* The user select component type is associated with an {@link UserSelectMenuBuilder}.
*/
[ComponentType.UserSelect]: UserSelectMenuBuilder;
/**
* The role select component type is associated with an {@link RoleSelectMenuBuilder}.
*/
[ComponentType.RoleSelect]: RoleSelectMenuBuilder;
/**
* The mentionable select component type is associated with an {@link MentionableSelectMenuBuilder}.
*/
[ComponentType.MentionableSelect]: MentionableSelectMenuBuilder;
/**
* The channel select component type is associated with an {@link ChannelSelectMenuBuilder}.
*/
[ComponentType.ChannelSelect]: ChannelSelectMenuBuilder;
}
/**
* Factory for creating components from API data
* Factory for creating components from API data.
*
* @param data - The api data to transform to a component class
* @typeParam T - The type of component to use
* @param data - The API data to transform to a component class
*/
export function createComponentBuilder<T extends keyof MappedComponentTypes>(
// eslint-disable-next-line @typescript-eslint/sort-type-union-intersection-members
data: (APIModalComponent | APIMessageComponent) & { type: T },
): MappedComponentTypes[T];
/**
* Factory for creating components from API data.
*
* @typeParam C - The type of component to use
* @param data - The API data to transform to a component class
*/
export function createComponentBuilder<C extends MessageComponentBuilder | ModalComponentBuilder>(data: C): C;
export function createComponentBuilder(
data: APIMessageComponent | APIModalComponent | MessageComponentBuilder,
): ComponentBuilder {
@@ -60,7 +96,7 @@ export function createComponentBuilder(
case ComponentType.ChannelSelect:
return new ChannelSelectMenuBuilder(data);
default:
// @ts-expect-error: This case can still occur if we get a newer unsupported component type
// @ts-expect-error This case can still occur if we get a newer unsupported component type
throw new Error(`Cannot properly serialize component type: ${data.type}`);
}
}

32
packages/builders/src/components/button/Button.ts
View File

@@ -18,15 +18,15 @@ import {
import { ComponentBuilder } from '../Component.js';
/**
* Represents a button component
* A builder that creates API-compatible JSON data for buttons.
*/
export class ButtonBuilder extends ComponentBuilder<APIButtonComponent> {
/**
* Creates a new button from API data
* Creates a new button from API data.
*
* @param data - The API data to create this button with
* @example
* Creating a button from an API data object
* Creating a button from an API data object:
* ```ts
* const button = new ButtonBuilder({
* custom_id: 'a cool button',
@@ -39,7 +39,7 @@ export class ButtonBuilder extends ComponentBuilder<APIButtonComponent> {
* });
* ```
* @example
* Creating a button using setters and API data
* Creating a button using setters and API data:
* ```ts
* const button = new ButtonBuilder({
* style: ButtonStyle.Secondary,
@@ -54,9 +54,9 @@ export class ButtonBuilder extends ComponentBuilder<APIButtonComponent> {
}
/**
* Sets the style of this button
* Sets the style of this button.
*
* @param style - The style of the button
* @param style - The style to use
*/
public setStyle(style: ButtonStyle) {
this.data.style = buttonStyleValidator.parse(style);
@@ -64,12 +64,12 @@ export class ButtonBuilder extends ComponentBuilder<APIButtonComponent> {
}
/**
* Sets the URL for this button
* Sets the URL for this button.
*
* @remarks
* This method is only available to buttons using the `Link` button style.
* Only three types of URL schemes are currently supported: `https://`, `http://` and `discord://`
* @param url - The URL to open when this button is clicked
* Only three types of URL schemes are currently supported: `https://`, `http://`, and `discord://`.
* @param url - The URL to use
*/
public setURL(url: string) {
(this.data as APIButtonComponentWithURL).url = urlValidator.parse(url);
@@ -77,11 +77,11 @@ export class ButtonBuilder extends ComponentBuilder<APIButtonComponent> {
}
/**
* Sets the custom id for this button
* Sets the custom id for this button.
*
* @remarks
* This method is only applicable to buttons that are not using the `Link` button style.
* @param customId - The custom id to use for this button
* @param customId - The custom id to use
*/
public setCustomId(customId: string) {
(this.data as APIButtonComponentWithCustomId).custom_id = customIdValidator.parse(customId);
@@ -89,9 +89,9 @@ export class ButtonBuilder extends ComponentBuilder<APIButtonComponent> {
}
/**
* Sets the emoji to display on this button
* Sets the emoji to display on this button.
*
* @param emoji - The emoji to display on this button
* @param emoji - The emoji to use
*/
public setEmoji(emoji: APIMessageComponentEmoji) {
this.data.emoji = emojiValidator.parse(emoji);
@@ -99,7 +99,7 @@ export class ButtonBuilder extends ComponentBuilder<APIButtonComponent> {
}
/**
* Sets whether this button is disabled
* Sets whether this button is disabled.
*
* @param disabled - Whether to disable this button
*/
@@ -109,9 +109,9 @@ export class ButtonBuilder extends ComponentBuilder<APIButtonComponent> {
}
/**
* Sets the label for this button
* Sets the label for this button.
*
* @param label - The label to display on this button
* @param label - The label to use
*/
public setLabel(label: string) {
this.data.label = buttonLabelValidator.parse(label);

22
packages/builders/src/components/selectMenu/BaseSelectMenu.ts
View File

@@ -2,13 +2,18 @@ import type { APISelectMenuComponent } from 'discord-api-types/v10';
import { customIdValidator, disabledValidator, minMaxValidator, placeholderValidator } from '../Assertions.js';
import { ComponentBuilder } from '../Component.js';
/**
* The base select menu builder that contains common symbols for select menu builders.
*
* @typeParam SelectMenuType - The type of select menu this would be instantiated for.
*/
export class BaseSelectMenuBuilder<
SelectMenuType extends APISelectMenuComponent,
> extends ComponentBuilder<SelectMenuType> {
/**
* Sets the placeholder for this select menu
* Sets the placeholder for this select menu.
*
* @param placeholder - The placeholder to use for this select menu
* @param placeholder - The placeholder to use
*/
public setPlaceholder(placeholder: string) {
this.data.placeholder = placeholderValidator.parse(placeholder);
@@ -16,7 +21,7 @@ export class BaseSelectMenuBuilder<
}
/**
* Sets the minimum values that must be selected in the select menu
* Sets the minimum values that must be selected in the select menu.
*
* @param minValues - The minimum values that must be selected
*/
@@ -26,7 +31,7 @@ export class BaseSelectMenuBuilder<
}
/**
* Sets the maximum values that must be selected in the select menu
* Sets the maximum values that must be selected in the select menu.
*
* @param maxValues - The maximum values that must be selected
*/
@@ -36,9 +41,9 @@ export class BaseSelectMenuBuilder<
}
/**
* Sets the custom id for this select menu
* Sets the custom id for this select menu.
*
* @param customId - The custom id to use for this select menu
* @param customId - The custom id to use
*/
public setCustomId(customId: string) {
this.data.custom_id = customIdValidator.parse(customId);
@@ -46,7 +51,7 @@ export class BaseSelectMenuBuilder<
}
/**
* Sets whether this select menu is disabled
* Sets whether this select menu is disabled.
*
* @param disabled - Whether this select menu is disabled
*/
@@ -55,6 +60,9 @@ export class BaseSelectMenuBuilder<
return this;
}
/**
* {@inheritDoc ComponentBuilder.toJSON}
*/
public toJSON(): SelectMenuType {
customIdValidator.parse(this.data.custom_id);
return {

45
packages/builders/src/components/selectMenu/ChannelSelectMenu.ts
View File

@@ -4,13 +4,16 @@ import { normalizeArray, type RestOrArray } from '../../util/normalizeArray.js';
import { channelTypesValidator, customIdValidator } 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> {
/**
* Creates a new select menu from API data
* Creates a new select menu from API data.
*
* @param data - The API data to create this select menu with
* @example
* Creating a select menu from an API data object
* Creating a select menu from an API data object:
* ```ts
* const selectMenu = new ChannelSelectMenuBuilder({
* custom_id: 'a cool select menu',
@@ -19,39 +22,45 @@ export class ChannelSelectMenuBuilder extends BaseSelectMenuBuilder<APIChannelSe
* });
* ```
* @example
* Creating a select menu using setters and API data
* 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)
* .setMinValues(2);
* ```
*/
public constructor(data?: Partial<APIChannelSelectComponent>) {
super({ ...data, type: ComponentType.ChannelSelect });
}
/**
* Adds channel types to this select menu.
*
* @param types - The channel types to use
*/
public addChannelTypes(...types: RestOrArray<ChannelType>) {
// eslint-disable-next-line no-param-reassign
types = normalizeArray(types);
const normalizedTypes = normalizeArray(types);
this.data.channel_types ??= [];
this.data.channel_types.push(...channelTypesValidator.parse(types));
return this;
}
public setChannelTypes(...types: RestOrArray<ChannelType>) {
// eslint-disable-next-line no-param-reassign
types = normalizeArray(types);
this.data.channel_types ??= [];
this.data.channel_types.splice(0, this.data.channel_types.length, ...channelTypesValidator.parse(types));
this.data.channel_types.push(...channelTypesValidator.parse(normalizedTypes));
return this;
}
/**
* {@inheritDoc ComponentBuilder.toJSON}
* 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, ...channelTypesValidator.parse(normalizedTypes));
return this;
}
/**
* {@inheritDoc BaseSelectMenuBuilder.toJSON}
*/
public override toJSON(): APIChannelSelectComponent {
customIdValidator.parse(this.data.custom_id);

11
packages/builders/src/components/selectMenu/MentionableSelectMenu.ts
View File

@@ -2,13 +2,16 @@ import type { APIMentionableSelectComponent } from 'discord-api-types/v10';
import { ComponentType } from 'discord-api-types/v10';
import { BaseSelectMenuBuilder } from './BaseSelectMenu.js';
/**
* A builder that creates API-compatible JSON data for mentionable select menus.
*/
export class MentionableSelectMenuBuilder extends BaseSelectMenuBuilder<APIMentionableSelectComponent> {
/**
* Creates a new select menu from API data
* Creates a new select menu from API data.
*
* @param data - The API data to create this select menu with
* @example
* Creating a select menu from an API data object
* Creating a select menu from an API data object:
* ```ts
* const selectMenu = new MentionableSelectMenuBuilder({
* custom_id: 'a cool select menu',
@@ -17,12 +20,12 @@ export class MentionableSelectMenuBuilder extends BaseSelectMenuBuilder<APIMenti
* });
* ```
* @example
* Creating a select menu using setters and API data
* Creating a select menu using setters and API data:
* ```ts
* const selectMenu = new MentionableSelectMenuBuilder({
* custom_id: 'a cool select menu',
* })
* .setMinValues(1)
* .setMinValues(1);
* ```
*/
public constructor(data?: Partial<APIMentionableSelectComponent>) {

11
packages/builders/src/components/selectMenu/RoleSelectMenu.ts
View File

@@ -2,13 +2,16 @@ import type { APIRoleSelectComponent } from 'discord-api-types/v10';
import { ComponentType } from 'discord-api-types/v10';
import { BaseSelectMenuBuilder } from './BaseSelectMenu.js';
/**
* A builder that creates API-compatible JSON data for role select menus.
*/
export class RoleSelectMenuBuilder extends BaseSelectMenuBuilder<APIRoleSelectComponent> {
/**
* Creates a new select menu from API data
* Creates a new select menu from API data.
*
* @param data - The API data to create this select menu with
* @example
* Creating a select menu from an API data object
* Creating a select menu from an API data object:
* ```ts
* const selectMenu = new RoleSelectMenuBuilder({
* custom_id: 'a cool select menu',
@@ -17,12 +20,12 @@ export class RoleSelectMenuBuilder extends BaseSelectMenuBuilder<APIRoleSelectCo
* });
* ```
* @example
* Creating a select menu using setters and API data
* Creating a select menu using setters and API data:
* ```ts
* const selectMenu = new RoleSelectMenuBuilder({
* custom_id: 'a cool select menu',
* })
* .setMinValues(1)
* .setMinValues(1);
* ```
*/
public constructor(data?: Partial<APIRoleSelectComponent>) {

62
packages/builders/src/components/selectMenu/StringSelectMenu.ts
View File

@@ -6,20 +6,20 @@ import { BaseSelectMenuBuilder } from './BaseSelectMenu.js';
import { StringSelectMenuOptionBuilder } from './StringSelectMenuOption.js';
/**
* Represents a string select menu component
* A builder that creates API-compatible JSON data for string select menus.
*/
export class StringSelectMenuBuilder extends BaseSelectMenuBuilder<APIStringSelectComponent> {
/**
* The options within this select menu
* The options within this select menu.
*/
public readonly options: StringSelectMenuOptionBuilder[];
/**
* Creates a new select menu from API data
* Creates a new select menu from API data.
*
* @param data - The API data to create this select menu with
* @example
* Creating a select menu from an API data object
* Creating a select menu from an API data object:
* ```ts
* const selectMenu = new StringSelectMenuBuilder({
* custom_id: 'a cool select menu',
@@ -33,7 +33,7 @@ export class StringSelectMenuBuilder extends BaseSelectMenuBuilder<APIStringSele
* });
* ```
* @example
* Creating a select menu using setters and API data
* Creating a select menu using setters and API data:
* ```ts
* const selectMenu = new StringSelectMenuBuilder({
* custom_id: 'a cool select menu',
@@ -52,55 +52,52 @@ export class StringSelectMenuBuilder extends BaseSelectMenuBuilder<APIStringSele
}
/**
* Adds options to this select menu
* Adds options to this select menu.
*
* @param options - The options to add to this select menu
* @returns
* @param options - The options to add
*/
public addOptions(...options: RestOrArray<APISelectMenuOption | StringSelectMenuOptionBuilder>) {
// eslint-disable-next-line no-param-reassign
options = normalizeArray(options);
optionsLengthValidator.parse(this.options.length + options.length);
const normalizedOptions = normalizeArray(options);
optionsLengthValidator.parse(this.options.length + normalizedOptions.length);
this.options.push(
...options.map((option) =>
option instanceof StringSelectMenuOptionBuilder
? option
: new StringSelectMenuOptionBuilder(jsonOptionValidator.parse(option)),
...normalizedOptions.map((normalizedOption) =>
normalizedOption instanceof StringSelectMenuOptionBuilder
? normalizedOption
: new StringSelectMenuOptionBuilder(jsonOptionValidator.parse(normalizedOption)),
),
);
return this;
}
/**
* Sets the options on this select menu
* Sets the options for this select menu.
*
* @param options - The options to set on this select menu
* @param options - The options to set
*/
public setOptions(...options: RestOrArray<APISelectMenuOption | StringSelectMenuOptionBuilder>) {
return this.spliceOptions(0, this.options.length, ...options);
}
/**
* Removes, replaces, or inserts options in the string select menu.
* Removes, replaces, or inserts options for this select menu.
*
* @remarks
* This method behaves similarly
* to {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/slice | Array.prototype.splice}.
*
* It's useful for modifying and adjusting order of the already-existing options of a string select menu.
* to {@link https://developer.mozilla.org/en-US/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
* Remove the first option:
* ```ts
* selectMenu.spliceOptions(0, 1);
* ```
* @example
* Remove the first n option
* Remove the first n option:
* ```ts
* const n = 4
* const n = 4;
* selectMenu.spliceOptions(0, n);
* ```
* @example
* Remove the last option
* Remove the last option:
* ```ts
* selectMenu.spliceOptions(-1, 1);
* ```
@@ -113,30 +110,27 @@ export class StringSelectMenuBuilder extends BaseSelectMenuBuilder<APIStringSele
deleteCount: number,
...options: RestOrArray<APISelectMenuOption | StringSelectMenuOptionBuilder>
) {
// eslint-disable-next-line no-param-reassign
options = normalizeArray(options);
const normalizedOptions = normalizeArray(options);
const clone = [...this.options];
clone.splice(
index,
deleteCount,
...options.map((option) =>
option instanceof StringSelectMenuOptionBuilder
? option
: new StringSelectMenuOptionBuilder(jsonOptionValidator.parse(option)),
...normalizedOptions.map((normalizedOption) =>
normalizedOption instanceof StringSelectMenuOptionBuilder
? normalizedOption
: new StringSelectMenuOptionBuilder(jsonOptionValidator.parse(normalizedOption)),
),
);
optionsLengthValidator.parse(clone.length);
this.options.splice(0, this.options.length, ...clone);
return this;
}
/**
* {@inheritDoc ComponentBuilder.toJSON}
* {@inheritDoc BaseSelectMenuBuilder.toJSON}
*/
public override toJSON(): APIStringSelectComponent {
validateRequiredSelectMenuParameters(this.options, this.data.custom_id);

30
packages/builders/src/components/selectMenu/StringSelectMenuOption.ts
View File

@@ -8,15 +8,15 @@ import {
} from '../Assertions.js';
/**
* Represents an option within a string select menu component
* A builder that creates API-compatible JSON data for string select menu options.
*/
export class StringSelectMenuOptionBuilder implements JSONEncodable<APISelectMenuOption> {
/**
* Creates a new string select menu option from API data
* Creates a new string select menu option from API data.
*
* @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
* Creating a string select menu option from an API data object:
* ```ts
* const selectMenuOption = new SelectMenuOptionBuilder({
* label: 'catchy label',
@@ -24,21 +24,21 @@ export class StringSelectMenuOptionBuilder implements JSONEncodable<APISelectMen
* });
* ```
* @example
* Creating a string select menu option using setters and API data
* Creating a string select menu option using setters and API data:
* ```ts
* const selectMenuOption = new SelectMenuOptionBuilder({
* default: true,
* value: '1',
* })
* .setLabel('woah')
* .setLabel('woah');
* ```
*/
public constructor(public data: Partial<APISelectMenuOption> = {}) {}
/**
* Sets the label of this option
* Sets the label for this option.
*
* @param label - The label to show on this option
* @param label - The label to use
*/
public setLabel(label: string) {
this.data.label = labelValueDescriptionValidator.parse(label);
@@ -46,9 +46,9 @@ export class StringSelectMenuOptionBuilder implements JSONEncodable<APISelectMen
}
/**
* Sets the value of this option
* Sets the value for this option.
*
* @param value - The value of this option
* @param value - The value to use
*/
public setValue(value: string) {
this.data.value = labelValueDescriptionValidator.parse(value);
@@ -56,9 +56,9 @@ export class StringSelectMenuOptionBuilder implements JSONEncodable<APISelectMen
}
/**
* Sets the description of this option
* Sets the description for this option.
*
* @param description - The description of this option
* @param description - The description to use
*/
public setDescription(description: string) {
this.data.description = labelValueDescriptionValidator.parse(description);
@@ -66,7 +66,7 @@ export class StringSelectMenuOptionBuilder implements JSONEncodable<APISelectMen
}
/**
* Sets whether this option is selected by default
* Sets whether this option is selected by default.
*
* @param isDefault - Whether this option is selected by default
*/
@@ -76,9 +76,9 @@ export class StringSelectMenuOptionBuilder implements JSONEncodable<APISelectMen
}
/**
* Sets the emoji to display on this option
* Sets the emoji to display for this option.
*
* @param emoji - The emoji to display on this option
* @param emoji - The emoji to use
*/
public setEmoji(emoji: APIMessageComponentEmoji) {
this.data.emoji = emojiValidator.parse(emoji);
@@ -86,7 +86,7 @@ export class StringSelectMenuOptionBuilder implements JSONEncodable<APISelectMen
}
/**
* {@inheritDoc ComponentBuilder.toJSON}
* {@inheritDoc BaseSelectMenuBuilder.toJSON}
*/
public toJSON(): APISelectMenuOption {
validateRequiredSelectMenuOptionParameters(this.data.label, this.data.value);

11
packages/builders/src/components/selectMenu/UserSelectMenu.ts
View File

@@ -2,13 +2,16 @@ import type { APIUserSelectComponent } from 'discord-api-types/v10';
import { ComponentType } from 'discord-api-types/v10';
import { BaseSelectMenuBuilder } from './BaseSelectMenu.js';
/**
* A builder that creates API-compatible JSON data for user select menus.
*/
export class UserSelectMenuBuilder extends BaseSelectMenuBuilder<APIUserSelectComponent> {
/**
* Creates a new select menu from API data
* Creates a new select menu from API data.
*
* @param data - The API data to create this select menu with
* @example
* Creating a select menu from an API data object
* Creating a select menu from an API data object:
* ```ts
* const selectMenu = new UserSelectMenuBuilder({
* custom_id: 'a cool select menu',
@@ -17,12 +20,12 @@ export class UserSelectMenuBuilder extends BaseSelectMenuBuilder<APIUserSelectCo
* });
* ```
* @example
* Creating a select menu using setters and API data
* Creating a select menu using setters and API data:
* ```ts
* const selectMenu = new UserSelectMenuBuilder({
* custom_id: 'a cool select menu',
* })
* .setMinValues(1)
* .setMinValues(1);
* ```
*/
public constructor(data?: Partial<APIUserSelectComponent>) {

35
packages/builders/src/components/textInput/TextInput.ts
View File

@@ -14,16 +14,19 @@ import {
textInputStyleValidator,
} from './Assertions.js';
/**
* A builder that creates API-compatible JSON data for text inputs.
*/
export class TextInputBuilder
extends ComponentBuilder<APITextInputComponent>
implements Equatable<APITextInputComponent | JSONEncodable<APITextInputComponent>>
{
/**
* Creates a new text input from API data
* Creates a new text input from API data.
*
* @param data - The API data to create this text input with
* @example
* Creating a select menu option from an API data object
* Creating a select menu option from an API data object:
* ```ts
* const textInput = new TextInputBuilder({
* custom_id: 'a cool select menu',
@@ -32,7 +35,7 @@ export class TextInputBuilder
* });
* ```
* @example
* Creating a select menu option using setters and API data
* Creating a select menu option using setters and API data:
* ```ts
* const textInput = new TextInputBuilder({
* label: 'Type something else',
@@ -46,9 +49,9 @@ export class TextInputBuilder
}
/**
* Sets the custom id for this text input
* Sets the custom id for this text input.
*
* @param customId - The custom id of this text input
* @param customId - The custom id to use
*/
public setCustomId(customId: string) {
this.data.custom_id = customIdValidator.parse(customId);
@@ -56,9 +59,9 @@ export class TextInputBuilder
}
/**
* Sets the label for this text input
* Sets the label for this text input.
*
* @param label - The label for this text input
* @param label - The label to use
*/
public setLabel(label: string) {
this.data.label = labelValidator.parse(label);
@@ -66,9 +69,9 @@ export class TextInputBuilder
}
/**
* Sets the style for this text input
* Sets the style for this text input.
*
* @param style - The style for this text input
* @param style - The style to use
*/
public setStyle(style: TextInputStyle) {
this.data.style = textInputStyleValidator.parse(style);
@@ -76,7 +79,7 @@ export class TextInputBuilder
}
/**
* Sets the minimum length of text for this text input
* Sets the minimum length of text for this text input.
*
* @param minLength - The minimum length of text for this text input
*/
@@ -86,7 +89,7 @@ export class TextInputBuilder
}
/**
* Sets the maximum length of text for this text input
* Sets the maximum length of text for this text input.
*
* @param maxLength - The maximum length of text for this text input
*/
@@ -96,9 +99,9 @@ export class TextInputBuilder
}
/**
* Sets the placeholder of this text input
* Sets the placeholder for this text input.
*
* @param placeholder - The placeholder of this text input
* @param placeholder - The placeholder to use
*/
public setPlaceholder(placeholder: string) {
this.data.placeholder = placeholderValidator.parse(placeholder);
@@ -106,9 +109,9 @@ export class TextInputBuilder
}
/**
* Sets the value of this text input
* Sets the value for this text input.
*
* @param value - The value for this text input
* @param value - The value to use
*/
public setValue(value: string) {
this.data.value = valueValidator.parse(value);
@@ -116,7 +119,7 @@ export class TextInputBuilder
}
/**
* Sets whether this text input is required
* Sets whether this text input is required.
*
* @param required - Whether this text input is required
*/