github.com/meowstercatel/discordgo@v0.0.0-20250615204139-29b43d676735/components.go (about)

     1  package discordgo
     2  
     3  import (
     4  	"encoding/json"
     5  	"fmt"
     6  )
     7  
     8  // ComponentType is type of component.
     9  type ComponentType uint
    10  
    11  // MessageComponent types.
    12  const (
    13  	ActionsRowComponent            ComponentType = 1
    14  	ButtonComponent                ComponentType = 2
    15  	SelectMenuComponent            ComponentType = 3
    16  	TextInputComponent             ComponentType = 4
    17  	UserSelectMenuComponent        ComponentType = 5
    18  	RoleSelectMenuComponent        ComponentType = 6
    19  	MentionableSelectMenuComponent ComponentType = 7
    20  	ChannelSelectMenuComponent     ComponentType = 8
    21  	SectionComponent               ComponentType = 9
    22  	TextDisplayComponent           ComponentType = 10
    23  	ThumbnailComponent             ComponentType = 11
    24  	MediaGalleryComponent          ComponentType = 12
    25  	FileComponentType              ComponentType = 13
    26  	SeparatorComponent             ComponentType = 14
    27  	ContainerComponent             ComponentType = 17
    28  )
    29  
    30  // MessageComponent is a base interface for all message components.
    31  type MessageComponent interface {
    32  	json.Marshaler
    33  	Type() ComponentType
    34  }
    35  
    36  type unmarshalableMessageComponent struct {
    37  	MessageComponent
    38  }
    39  
    40  // UnmarshalJSON is a helper function to unmarshal MessageComponent object.
    41  func (umc *unmarshalableMessageComponent) UnmarshalJSON(src []byte) error {
    42  	var v struct {
    43  		Type ComponentType `json:"type"`
    44  	}
    45  	err := json.Unmarshal(src, &v)
    46  	if err != nil {
    47  		return err
    48  	}
    49  
    50  	switch v.Type {
    51  	case ActionsRowComponent:
    52  		umc.MessageComponent = &ActionsRow{}
    53  	case ButtonComponent:
    54  		umc.MessageComponent = &Button{}
    55  	case SelectMenuComponent, ChannelSelectMenuComponent, UserSelectMenuComponent,
    56  		RoleSelectMenuComponent, MentionableSelectMenuComponent:
    57  		umc.MessageComponent = &SelectMenu{}
    58  	case TextInputComponent:
    59  		umc.MessageComponent = &TextInput{}
    60  	case SectionComponent:
    61  		umc.MessageComponent = &Section{}
    62  	case TextDisplayComponent:
    63  		umc.MessageComponent = &TextDisplay{}
    64  	case ThumbnailComponent:
    65  		umc.MessageComponent = &Thumbnail{}
    66  	case MediaGalleryComponent:
    67  		umc.MessageComponent = &MediaGallery{}
    68  	case FileComponentType:
    69  		umc.MessageComponent = &FileComponent{}
    70  	case SeparatorComponent:
    71  		umc.MessageComponent = &Separator{}
    72  	case ContainerComponent:
    73  		umc.MessageComponent = &Container{}
    74  	default:
    75  		return fmt.Errorf("unknown component type: %d", v.Type)
    76  	}
    77  	return json.Unmarshal(src, umc.MessageComponent)
    78  }
    79  
    80  // MessageComponentFromJSON is a helper function for unmarshaling message components
    81  func MessageComponentFromJSON(b []byte) (MessageComponent, error) {
    82  	var u unmarshalableMessageComponent
    83  	err := u.UnmarshalJSON(b)
    84  	if err != nil {
    85  		return nil, fmt.Errorf("failed to unmarshal into MessageComponent: %w", err)
    86  	}
    87  	return u.MessageComponent, nil
    88  }
    89  
    90  // ActionsRow is a top-level container component for displaying a row of interactive components.
    91  type ActionsRow struct {
    92  	// Can contain Button, SelectMenu and TextInput.
    93  	// NOTE: maximum of 5.
    94  	Components []MessageComponent `json:"components"`
    95  	// Unique identifier for the component; auto populated through increment if not provided.
    96  	ID int `json:"id,omitempty"`
    97  }
    98  
    99  // MarshalJSON is a method for marshaling ActionsRow to a JSON object.
   100  func (r ActionsRow) MarshalJSON() ([]byte, error) {
   101  	type actionsRow ActionsRow
   102  
   103  	return Marshal(struct {
   104  		actionsRow
   105  		Type ComponentType `json:"type"`
   106  	}{
   107  		actionsRow: actionsRow(r),
   108  		Type:       r.Type(),
   109  	})
   110  }
   111  
   112  // UnmarshalJSON is a helper function to unmarshal Actions Row.
   113  func (r *ActionsRow) UnmarshalJSON(data []byte) error {
   114  	type actionsRow ActionsRow
   115  	var v struct {
   116  		actionsRow
   117  		RawComponents []unmarshalableMessageComponent `json:"components"`
   118  	}
   119  	err := json.Unmarshal(data, &v)
   120  	if err != nil {
   121  		return err
   122  	}
   123  	*r = ActionsRow(v.actionsRow)
   124  
   125  	r.Components = make([]MessageComponent, len(v.RawComponents))
   126  	for i, v := range v.RawComponents {
   127  		r.Components[i] = v.MessageComponent
   128  	}
   129  
   130  	return err
   131  }
   132  
   133  // Type is a method to get the type of a component.
   134  func (r ActionsRow) Type() ComponentType {
   135  	return ActionsRowComponent
   136  }
   137  
   138  // ButtonStyle is style of button.
   139  type ButtonStyle uint
   140  
   141  // Button styles.
   142  const (
   143  	// PrimaryButton is a button with blurple color.
   144  	PrimaryButton ButtonStyle = 1
   145  	// SecondaryButton is a button with grey color.
   146  	SecondaryButton ButtonStyle = 2
   147  	// SuccessButton is a button with green color.
   148  	SuccessButton ButtonStyle = 3
   149  	// DangerButton is a button with red color.
   150  	DangerButton ButtonStyle = 4
   151  	// LinkButton is a special type of button which navigates to a URL. Has grey color.
   152  	LinkButton ButtonStyle = 5
   153  	// PremiumButton is a special type of button with a blurple color that links to a SKU.
   154  	PremiumButton ButtonStyle = 6
   155  )
   156  
   157  // ComponentEmoji represents button emoji, if it does have one.
   158  type ComponentEmoji struct {
   159  	Name     string `json:"name,omitempty"`
   160  	ID       string `json:"id,omitempty"`
   161  	Animated bool   `json:"animated,omitempty"`
   162  }
   163  
   164  // Button represents button component.
   165  type Button struct {
   166  	Label    string          `json:"label"`
   167  	Style    ButtonStyle     `json:"style"`
   168  	Disabled bool            `json:"disabled"`
   169  	Emoji    *ComponentEmoji `json:"emoji,omitempty"`
   170  
   171  	// NOTE: Only button with LinkButton style can have link. Also, URL is mutually exclusive with CustomID.
   172  	URL      string `json:"url,omitempty"`
   173  	CustomID string `json:"custom_id,omitempty"`
   174  	// Identifier for a purchasable SKU. Only available when using premium-style buttons.
   175  	SKUID string `json:"sku_id,omitempty"`
   176  	// Unique identifier for the component; auto populated through increment if not provided.
   177  	ID int `json:"id,omitempty"`
   178  }
   179  
   180  // MarshalJSON is a method for marshaling Button to a JSON object.
   181  func (b Button) MarshalJSON() ([]byte, error) {
   182  	type button Button
   183  
   184  	if b.Style == 0 {
   185  		b.Style = PrimaryButton
   186  	}
   187  
   188  	return Marshal(struct {
   189  		button
   190  		Type ComponentType `json:"type"`
   191  	}{
   192  		button: button(b),
   193  		Type:   b.Type(),
   194  	})
   195  }
   196  
   197  // Type is a method to get the type of a component.
   198  func (Button) Type() ComponentType {
   199  	return ButtonComponent
   200  }
   201  
   202  // SelectMenuOption represents an option for a select menu.
   203  type SelectMenuOption struct {
   204  	Label       string          `json:"label,omitempty"`
   205  	Value       string          `json:"value"`
   206  	Description string          `json:"description"`
   207  	Emoji       *ComponentEmoji `json:"emoji,omitempty"`
   208  	// Determines whenever option is selected by default or not.
   209  	Default bool `json:"default"`
   210  }
   211  
   212  // SelectMenuDefaultValueType represents the type of an entity selected by default in auto-populated select menus.
   213  type SelectMenuDefaultValueType string
   214  
   215  // SelectMenuDefaultValue types.
   216  const (
   217  	SelectMenuDefaultValueUser    SelectMenuDefaultValueType = "user"
   218  	SelectMenuDefaultValueRole    SelectMenuDefaultValueType = "role"
   219  	SelectMenuDefaultValueChannel SelectMenuDefaultValueType = "channel"
   220  )
   221  
   222  // SelectMenuDefaultValue represents an entity selected by default in auto-populated select menus.
   223  type SelectMenuDefaultValue struct {
   224  	// ID of the entity.
   225  	ID string `json:"id"`
   226  	// Type of the entity.
   227  	Type SelectMenuDefaultValueType `json:"type"`
   228  }
   229  
   230  // SelectMenuType represents select menu type.
   231  type SelectMenuType ComponentType
   232  
   233  // SelectMenu types.
   234  const (
   235  	StringSelectMenu      = SelectMenuType(SelectMenuComponent)
   236  	UserSelectMenu        = SelectMenuType(UserSelectMenuComponent)
   237  	RoleSelectMenu        = SelectMenuType(RoleSelectMenuComponent)
   238  	MentionableSelectMenu = SelectMenuType(MentionableSelectMenuComponent)
   239  	ChannelSelectMenu     = SelectMenuType(ChannelSelectMenuComponent)
   240  )
   241  
   242  // SelectMenu represents select menu component.
   243  type SelectMenu struct {
   244  	// Type of the select menu.
   245  	MenuType SelectMenuType `json:"type,omitempty"`
   246  	// CustomID is a developer-defined identifier for the select menu.
   247  	CustomID string `json:"custom_id,omitempty"`
   248  	// The text which will be shown in the menu if there's no default options or all options was deselected and component was closed.
   249  	Placeholder string `json:"placeholder"`
   250  	// This value determines the minimal amount of selected items in the menu.
   251  	MinValues *int `json:"min_values,omitempty"`
   252  	// This value determines the maximal amount of selected items in the menu.
   253  	// If MaxValues or MinValues are greater than one then the user can select multiple items in the component.
   254  	MaxValues int `json:"max_values,omitempty"`
   255  	// List of default values for auto-populated select menus.
   256  	// NOTE: Number of entries should be in the range defined by MinValues and MaxValues.
   257  	DefaultValues []SelectMenuDefaultValue `json:"default_values,omitempty"`
   258  
   259  	Options  []SelectMenuOption `json:"options,omitempty"`
   260  	Disabled bool               `json:"disabled"`
   261  
   262  	// NOTE: Can only be used in SelectMenu with Channel menu type.
   263  	ChannelTypes []ChannelType `json:"channel_types,omitempty"`
   264  
   265  	// Unique identifier for the component; auto populated through increment if not provided.
   266  	ID int `json:"id,omitempty"`
   267  }
   268  
   269  // Type is a method to get the type of a component.
   270  func (s SelectMenu) Type() ComponentType {
   271  	if s.MenuType != 0 {
   272  		return ComponentType(s.MenuType)
   273  	}
   274  	return SelectMenuComponent
   275  }
   276  
   277  // MarshalJSON is a method for marshaling SelectMenu to a JSON object.
   278  func (s SelectMenu) MarshalJSON() ([]byte, error) {
   279  	type selectMenu SelectMenu
   280  
   281  	return Marshal(struct {
   282  		selectMenu
   283  		Type ComponentType `json:"type"`
   284  	}{
   285  		selectMenu: selectMenu(s),
   286  		Type:       s.Type(),
   287  	})
   288  }
   289  
   290  // TextInput represents text input component.
   291  type TextInput struct {
   292  	CustomID    string         `json:"custom_id"`
   293  	Label       string         `json:"label"`
   294  	Style       TextInputStyle `json:"style"`
   295  	Placeholder string         `json:"placeholder,omitempty"`
   296  	Value       string         `json:"value,omitempty"`
   297  	Required    bool           `json:"required"`
   298  	MinLength   int            `json:"min_length,omitempty"`
   299  	MaxLength   int            `json:"max_length,omitempty"`
   300  
   301  	// Unique identifier for the component; auto populated through increment if not provided.
   302  	ID int `json:"id,omitempty"`
   303  }
   304  
   305  // Type is a method to get the type of a component.
   306  func (TextInput) Type() ComponentType {
   307  	return TextInputComponent
   308  }
   309  
   310  // MarshalJSON is a method for marshaling TextInput to a JSON object.
   311  func (m TextInput) MarshalJSON() ([]byte, error) {
   312  	type inputText TextInput
   313  
   314  	return Marshal(struct {
   315  		inputText
   316  		Type ComponentType `json:"type"`
   317  	}{
   318  		inputText: inputText(m),
   319  		Type:      m.Type(),
   320  	})
   321  }
   322  
   323  // TextInputStyle is style of text in TextInput component.
   324  type TextInputStyle uint
   325  
   326  // Text styles
   327  const (
   328  	TextInputShort     TextInputStyle = 1
   329  	TextInputParagraph TextInputStyle = 2
   330  )
   331  
   332  // Section is a top-level layout component that allows you to join text contextually with an accessory.
   333  type Section struct {
   334  	// Unique identifier for the component; auto populated through increment if not provided.
   335  	ID int `json:"id,omitempty"`
   336  	// Array of text display components; max of 3.
   337  	Components []MessageComponent `json:"components"`
   338  	// Can be Button or Thumbnail
   339  	Accessory MessageComponent `json:"accessory"`
   340  }
   341  
   342  // UnmarshalJSON is a method for unmarshaling Section from JSON
   343  func (s *Section) UnmarshalJSON(data []byte) error {
   344  	type section Section
   345  
   346  	var v struct {
   347  		section
   348  		RawComponents []unmarshalableMessageComponent `json:"components"`
   349  		RawAccessory  unmarshalableMessageComponent   `json:"accessory"`
   350  	}
   351  
   352  	err := json.Unmarshal(data, &v)
   353  	if err != nil {
   354  		return err
   355  	}
   356  
   357  	*s = Section(v.section)
   358  	s.Accessory = v.RawAccessory.MessageComponent
   359  	s.Components = make([]MessageComponent, len(v.RawComponents))
   360  	for i, v := range v.RawComponents {
   361  		s.Components[i] = v.MessageComponent
   362  	}
   363  
   364  	return nil
   365  }
   366  
   367  // Type is a method to get the type of a component.
   368  func (Section) Type() ComponentType {
   369  	return SectionComponent
   370  }
   371  
   372  // MarshalJSON is a method for marshaling Section to a JSON object.
   373  func (s Section) MarshalJSON() ([]byte, error) {
   374  	type section Section
   375  
   376  	return Marshal(struct {
   377  		section
   378  		Type ComponentType `json:"type"`
   379  	}{
   380  		section: section(s),
   381  		Type:    s.Type(),
   382  	})
   383  }
   384  
   385  // TextDisplay is a top-level component that allows you to add markdown-formatted text to the message.
   386  type TextDisplay struct {
   387  	Content string `json:"content"`
   388  }
   389  
   390  // Type is a method to get the type of a component.
   391  func (TextDisplay) Type() ComponentType {
   392  	return TextDisplayComponent
   393  }
   394  
   395  // MarshalJSON is a method for marshaling TextDisplay to a JSON object.
   396  func (t TextDisplay) MarshalJSON() ([]byte, error) {
   397  	type textDisplay TextDisplay
   398  
   399  	return Marshal(struct {
   400  		textDisplay
   401  		Type ComponentType `json:"type"`
   402  	}{
   403  		textDisplay: textDisplay(t),
   404  		Type:        t.Type(),
   405  	})
   406  }
   407  
   408  // Thumbnail component can be used as an accessory for a section component.
   409  type Thumbnail struct {
   410  	// Unique identifier for the component; auto populated through increment if not provided.
   411  	ID          int               `json:"id,omitempty"`
   412  	Media       UnfurledMediaItem `json:"media"`
   413  	Description *string           `json:"description,omitempty"`
   414  	Spoiler     bool              `json:"spoiler,omitemoty"`
   415  }
   416  
   417  // Type is a method to get the type of a component.
   418  func (Thumbnail) Type() ComponentType {
   419  	return ThumbnailComponent
   420  }
   421  
   422  // MarshalJSON is a method for marshaling Thumbnail to a JSON object.
   423  func (t Thumbnail) MarshalJSON() ([]byte, error) {
   424  	type thumbnail Thumbnail
   425  
   426  	return Marshal(struct {
   427  		thumbnail
   428  		Type ComponentType `json:"type"`
   429  	}{
   430  		thumbnail: thumbnail(t),
   431  		Type:      t.Type(),
   432  	})
   433  }
   434  
   435  // MediaGallery is a top-level component allows you to group images, videos or gifs into a gallery grid.
   436  type MediaGallery struct {
   437  	// Unique identifier for the component; auto populated through increment if not provided.
   438  	ID int `json:"id,omitempty"`
   439  	// Array of media gallery items; max of 10.
   440  	Items []MediaGalleryItem `json:"items"`
   441  }
   442  
   443  // Type is a method to get the type of a component.
   444  func (MediaGallery) Type() ComponentType {
   445  	return MediaGalleryComponent
   446  }
   447  
   448  // MarshalJSON is a method for marshaling MediaGallery to a JSON object.
   449  func (m MediaGallery) MarshalJSON() ([]byte, error) {
   450  	type mediaGallery MediaGallery
   451  
   452  	return Marshal(struct {
   453  		mediaGallery
   454  		Type ComponentType `json:"type"`
   455  	}{
   456  		mediaGallery: mediaGallery(m),
   457  		Type:         m.Type(),
   458  	})
   459  }
   460  
   461  // MediaGalleryItem represents an item used in MediaGallery.
   462  type MediaGalleryItem struct {
   463  	Media       UnfurledMediaItem `json:"media"`
   464  	Description *string           `json:"description,omitempty"`
   465  	Spoiler     bool              `json:"spoiler"`
   466  }
   467  
   468  // FileComponent is a top-level component that allows you to display an uploaded file as an attachment to the message and reference it in the component.
   469  type FileComponent struct {
   470  	// Unique identifier for the component; auto populated through increment if not provided.
   471  	ID      int               `json:"id,omitempty"`
   472  	File    UnfurledMediaItem `json:"file"`
   473  	Spoiler bool              `json:"spoiler"`
   474  }
   475  
   476  // Type is a method to get the type of a component.
   477  func (FileComponent) Type() ComponentType {
   478  	return FileComponentType
   479  }
   480  
   481  // MarshalJSON is a method for marshaling FileComponent to a JSON object.
   482  func (f FileComponent) MarshalJSON() ([]byte, error) {
   483  	type fileComponent FileComponent
   484  
   485  	return Marshal(struct {
   486  		fileComponent
   487  		Type ComponentType `json:"type"`
   488  	}{
   489  		fileComponent: fileComponent(f),
   490  		Type:          f.Type(),
   491  	})
   492  }
   493  
   494  // SeparatorSpacingSize represents spacing size around the separator.
   495  type SeparatorSpacingSize uint
   496  
   497  // Separator spacing sizes.
   498  const (
   499  	SeparatorSpacingSizeSmall SeparatorSpacingSize = 1
   500  	SeparatorSpacingSizeLarge SeparatorSpacingSize = 2
   501  )
   502  
   503  // Separator is a top-level layout component that adds vertical padding and visual division between other components.
   504  type Separator struct {
   505  	// Unique identifier for the component; auto populated through increment if not provided.
   506  	ID int `json:"id,omitempty"`
   507  
   508  	Divider *bool                 `json:"divider,omitempty"`
   509  	Spacing *SeparatorSpacingSize `json:"spacing,omitempty"`
   510  }
   511  
   512  // Type is a method to get the type of a component.
   513  func (Separator) Type() ComponentType {
   514  	return SeparatorComponent
   515  }
   516  
   517  // MarshalJSON is a method for marshaling Separator to a JSON object.
   518  func (s Separator) MarshalJSON() ([]byte, error) {
   519  	type separator Separator
   520  
   521  	return Marshal(struct {
   522  		separator
   523  		Type ComponentType `json:"type"`
   524  	}{
   525  		separator: separator(s),
   526  		Type:      s.Type(),
   527  	})
   528  }
   529  
   530  // Container is a top-level layout component.
   531  // Containers are visually distinct from surrounding components and have an optional customizable color bar (similar to embeds).
   532  type Container struct {
   533  	// Unique identifier for the component; auto populated through increment if not provided.
   534  	ID          int                `json:"id,omitempty"`
   535  	AccentColor *int               `json:"accent_color,omitempty"`
   536  	Spoiler     bool               `json:"spoiler"`
   537  	Components  []MessageComponent `json:"components"`
   538  }
   539  
   540  // Type is a method to get the type of a component.
   541  func (Container) Type() ComponentType {
   542  	return ContainerComponent
   543  }
   544  
   545  // UnmarshalJSON is a method for unmarshaling Container from JSON
   546  func (c *Container) UnmarshalJSON(data []byte) error {
   547  	type container Container
   548  
   549  	var v struct {
   550  		container
   551  		RawComponents []unmarshalableMessageComponent `json:"components"`
   552  	}
   553  
   554  	err := json.Unmarshal(data, &v)
   555  	if err != nil {
   556  		return err
   557  	}
   558  
   559  	*c = Container(v.container)
   560  	c.Components = make([]MessageComponent, len(v.RawComponents))
   561  	for i, v := range v.RawComponents {
   562  		c.Components[i] = v.MessageComponent
   563  	}
   564  
   565  	return nil
   566  }
   567  
   568  // MarshalJSON is a method for marshaling Container to a JSON object.
   569  func (c Container) MarshalJSON() ([]byte, error) {
   570  	type container Container
   571  
   572  	return Marshal(struct {
   573  		container
   574  		Type ComponentType `json:"type"`
   575  	}{
   576  		container: container(c),
   577  		Type:      c.Type(),
   578  	})
   579  }
   580  
   581  // UnfurledMediaItem represents an unfurled media item.
   582  type UnfurledMediaItem struct {
   583  	URL string `json:"url"`
   584  }
   585  
   586  // UnfurledMediaItemLoadingState is the loading state of the unfurled media item.
   587  type UnfurledMediaItemLoadingState uint
   588  
   589  // Unfurled media item loading states.
   590  const (
   591  	UnfurledMediaItemLoadingStateUnknown        UnfurledMediaItemLoadingState = 0
   592  	UnfurledMediaItemLoadingStateLoading        UnfurledMediaItemLoadingState = 1
   593  	UnfurledMediaItemLoadingStateLoadingSuccess UnfurledMediaItemLoadingState = 2
   594  	UnfurledMediaItemLoadingStateLoadedNotFound UnfurledMediaItemLoadingState = 3
   595  )
   596  
   597  // ResolvedUnfurledMediaItem represents a resolved unfurled media item.
   598  type ResolvedUnfurledMediaItem struct {
   599  	URL         string `json:"url"`
   600  	ProxyURL    string `json:"proxy_url"`
   601  	Width       int    `json:"width"`
   602  	Height      int    `json:"height"`
   603  	ContentType string `json:"content_type"`
   604  }