onyxcord 2.1.0 → 3.2.1

data/lib/onyxcord/webhooks/view/row_builder.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+class OnyxCord::Webhooks::View
+  class RowBuilder
+    # @!visibility private
+    def initialize(id: nil)
+      @id = id
+      @components = []
+
+      yield self if block_given?
+    end
+
+    # Add a button to this action row.
+    # @param style [Symbol, Integer] The button's style type. See {BUTTON_STYLES}
+    # @param id [Integer, nil] The unique 32-bit ID of the button component. This is not to be confused with the `custom_id`.
+    # @param label [String, nil] The text label for the button. Either a label or emoji must be provided.
+    # @param emoji [#to_h, String, Integer] An emoji ID, or unicode emoji to attach to the button. Can also be an object
+    #   that responds to `#to_h` which returns a hash in the format of `{ id: Integer, name: string }`.
+    # @param custom_id [String] Custom IDs are used to pass state to the events that are raised from interactions.
+    #   There is a limit of 100 characters to each custom_id.
+    # @param disabled [true, false] Whether this button is disabled and shown as greyed out.
+    # @param url [String, nil] The URL, when using a link style button.
+    def button(style:, id: nil, label: nil, emoji: nil, custom_id: nil, disabled: nil, url: nil, sku_id: nil)
+      style = BUTTON_STYLES[style] || style
+
+      emoji = case emoji
+              when Integer, String
+                emoji.to_i.positive? ? { id: emoji } : { name: emoji }
+              else
+                emoji&.to_h
+              end
+
+      @components << { type: COMPONENT_TYPES[:button], id: id, label: label, emoji: emoji, style: style, custom_id: custom_id, disabled: disabled, url: url, sku_id: sku_id }.compact
+    end
+
+    # Add a string select to this action row.
+    # @param custom_id [String] Custom IDs are used to pass state to the events that are raised from interactions.
+    #   There is a limit of 100 characters to each custom_id.
+    # @param id [Integer, nil] The unique 32-bit ID of the string select. This is not to be confused with the `custom_id`.
+    # @param options [Array<Hash>] Options that can be selected in this menu. Can also be provided via the yielded builder.
+    # @param placeholder [String, nil] Default text to show when no entries are selected.
+    # @param min_values [Integer, nil] The minimum amount of values a user must select.
+    # @param max_values [Integer, nil] The maximum amount of values a user can select.
+    # @param disabled [true, false, nil] Grey out the component to make it unusable.
+    # @yieldparam builder [SelectMenuBuilder]
+    def string_select(custom_id:, options: [], id: nil, placeholder: nil, min_values: nil, max_values: nil, disabled: nil)
+      builder = SelectMenuBuilder.new(custom_id, options, placeholder, min_values, max_values, disabled, select_type: :string_select, id: id)
+
+      yield builder if block_given?
+
+      @components << builder.to_h
+    end
+
+    alias_method :select_menu, :string_select
+
+    # Add a user select to this action row.
+    # @param custom_id [String] Custom IDs are used to pass state to the events that are raised from interactions.
+    #   There is a limit of 100 characters to each custom_id.
+    # @param id [Integer, nil] The unique 32-bit ID of the user select. This is not to be confused with the `custom_id`.
+    # @param placeholder [String, nil] Default text to show when no entries are selected.
+    # @param min_values [Integer, nil] The minimum amount of values a user must select.
+    # @param max_values [Integer, nil] The maximum amount of values a user can select.
+    # @param disabled [true, false, nil] Grey out the component to make it unusable.
+    # @param default_values [Array<User, Member, Recipient, Integer, String, Hash>, nil] The users to populate in the select menu by default.
+    def user_select(custom_id:, id: nil, placeholder: nil, min_values: nil, max_values: nil, disabled: nil, default_values: nil)
+      @components << SelectMenuBuilder.new(custom_id, [], placeholder, min_values, max_values, disabled, select_type: :user_select, id: id, default_values: default_values).to_h
+    end
+
+    # Add a role select to this action row.
+    # @param custom_id [String] Custom IDs are used to pass state to the events that are raised from interactions.
+    #   There is a limit of 100 characters to each custom_id.
+    # @param id [Integer, nil] The unique 32-bit ID of the role select. This is not to be confused with the `custom_id`.
+    # @param placeholder [String, nil] Default text to show when no entries are selected.
+    # @param min_values [Integer, nil] The minimum amount of values a user must select.
+    # @param max_values [Integer, nil] The maximum amount of values a user can select.
+    # @param disabled [true, false, nil] Grey out the component to make it unusable.
+    # @param default_values [Array<Role, Integer, String, Hash>, nil] The roles to populate in the select menu by default.
+    def role_select(custom_id:, id: nil, placeholder: nil, min_values: nil, max_values: nil, disabled: nil, default_values: nil)
+      @components << SelectMenuBuilder.new(custom_id, [], placeholder, min_values, max_values, disabled, select_type: :role_select, id: id, default_values: default_values).to_h
+    end
+
+    # Add a mentionable select to this action row.
+    # @param custom_id [String] Custom IDs are used to pass state to the events that are raised from interactions.
+    #   There is a limit of 100 characters to each custom_id.
+    # @param id [Integer, nil] The unique 32-bit ID of the mentionable select. This is not to be confused with the `custom_id`.
+    # @param placeholder [String, nil] Default text to show when no entries are selected.
+    # @param min_values [Integer, nil] The minimum amount of values a user must select.
+    # @param max_values [Integer, nil] The maximum amount of values a user can select.
+    # @param disabled [true, false, nil] Grey out the component to make it unusable.
+    # @param default_values [Array<User, Role, Member, Recipient, Hash>, nil] The mentionable entities to populate in the select menu by default.
+    def mentionable_select(custom_id:, id: nil, placeholder: nil, min_values: nil, max_values: nil, disabled: nil, default_values: nil)
+      @components << SelectMenuBuilder.new(custom_id, [], placeholder, min_values, max_values, disabled, select_type: :mentionable_select, id: id, default_values: default_values).to_h
+    end
+
+    # Add a channel select to this action row.
+    # @param custom_id [String] Custom IDs are used to pass state to the events that are raised from interactions.
+    #   There is a limit of 100 characters to each custom_id.
+    # @param id [Integer, nil] The unique 32-bit ID of the channel select. This is not to be confused with the `custom_id`.
+    # @param placeholder [String, nil] Default text to show when no entries are selected.
+    # @param min_values [Integer, nil] The minimum amount of values a user must select.
+    # @param max_values [Integer, nil] The maximum amount of values a user can select.
+    # @param disabled [true, false, nil] Grey out the component to make it unusable.
+    # @param types [Array<Symbol, Integer>, nil] The channel types to include in the select menu.
+    # @param default_values [Array<Channel, Integer, String, Hash>, nil] The channels to populate in the select menu by default.
+    def channel_select(custom_id:, id: nil, placeholder: nil, min_values: nil, max_values: nil, disabled: nil, types: nil, default_values: nil)
+      builder = SelectMenuBuilder.new(custom_id, [], placeholder, min_values, max_values, disabled, select_type: :channel_select, id: id, default_values: default_values).to_h
+
+      builder[:channel_types] = types.map { |type| OnyxCord::Channel::TYPES[type] || type } if types
+
+      @components << builder
+    end
+
+    # @!visibility private
+    def to_h
+      { type: COMPONENT_TYPES[:action_row], id: @id, components: @components }.compact
+    end
+  end
+
+  # A builder to assist in adding options to select menus.
+end

data/lib/onyxcord/webhooks/view/section_builder.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+class OnyxCord::Webhooks::View
+  class SectionBuilder
+    # Create a section component.
+    # @param id [Integer, nil] The unique 32-bit ID of the section component.
+    # @yieldparam builder [SectionBuilder] Yields the initialized section component.
+    def initialize(id: nil)
+      @id = id
+      @accessory = nil
+      @components = []
+
+      yield self if block_given?
+    end
+
+    # Add a text display component to this section.
+    # @see TextDisplayBuilder#initialize
+    def text_display(...)
+      @components << TextDisplayBuilder.new(...)
+    end
+
+    # Set the thumbnail for the section. This is mutually exclusive with {#button}.
+    # @param url [String] The URL to the thumbnail image.
+    # @param id [Integer, nil] The unique 32-bit ID of the thumbnail component.
+    # @param description [String, nil] The description of the thumbnail.
+    # @param spoiler [true, false] Whether or not to apply a spoiler label to the thumbnail.
+    def thumbnail(url:, id: nil, description: nil, spoiler: false)
+      @accessory = { type: COMPONENT_TYPES[:thumbnail], id: id, media: { url: }, description: description, spoiler: spoiler }.compact
+    end
+
+    # Set the button for the section. This is mutually exclusive with {#thumbnail}.
+    # @param style [Symbol, Integer] The button's style type. See {BUTTON_STYLES}
+    # @param id [Integer, nil] The unique 32-bit ID of the button component. This is not to be confused with the `custom_id`.
+    # @param label [String, nil] The text label for the button. Either a label or emoji must be provided.
+    # @param emoji [#to_h, String, Integer] An emoji ID, or unicode emoji to attach to the button. Can also be an object
+    # that responds to `#to_h` which returns a hash in the format of `{ id: Integer, name: string }`.
+    # @param custom_id [String] Custom IDs are used to pass state to the events that are raised from interactions.
+    # There is a limit of 100 characters to each custom_id.
+    # @param disabled [true, false] Whether this button is disabled and shown as greyed out.
+    # @param url [String, nil] The URL, when using a link style button.
+    def button(style:, id: nil, label: nil, emoji: nil, custom_id: nil, disabled: nil, url: nil, sku_id: nil)
+      style = BUTTON_STYLES[style] || style
+
+      emoji = case emoji
+              when Integer, String
+                emoji.to_i.positive? ? { id: emoji } : { name: emoji }
+              else
+                emoji&.to_h
+              end
+
+      @accessory = { type: COMPONENT_TYPES[:button], id: id, label: label, emoji: emoji, style: style, custom_id: custom_id, disabled: disabled, url: url, sku_id: sku_id }.compact
+    end
+
+    # @!visibility private
+    def to_h
+      { type: COMPONENT_TYPES[:section], id: @id, components: @components.map(&:to_h), accessory: @accessory }.compact
+    end
+  end
+
+  # This builder can be used to construct a container. These are similar to embeds.
+end

data/lib/onyxcord/webhooks/view/select_menu_builder.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+class OnyxCord::Webhooks::View
+  class SelectMenuBuilder
+    # @!visibility private
+    def initialize(custom_id, options = [], placeholder = nil, min_values = nil, max_values = nil, disabled = nil, select_type: :string_select, id: nil, required: nil, default_values: nil)
+      @id = id
+      @custom_id = custom_id
+      @options = options
+      @placeholder = placeholder
+      @min_values = min_values
+      @max_values = max_values
+      @disabled = disabled
+      @select_type = select_type
+      @required = required
+      @default_values = process_defaults(default_values)
+    end
+
+    # Add an option to this select menu.
+    # @param label [String] The title of this option.
+    # @param value [String] The value that this option represents.
+    # @param description [String, nil] An optional description of the option.
+    # @param emoji [#to_h, String, Integer] An emoji ID, or unicode emoji to attach to the button. Can also be an object
+    #   that responds to `#to_h` which returns a hash in the format of `{ id: Integer, name: string }`.
+    # @param default [true, false, nil] Whether this is the default selected option.
+    def option(label:, value:, description: nil, emoji: nil, default: nil)
+      emoji = case emoji
+              when Integer, String
+                emoji.to_i.positive? ? { id: emoji } : { name: emoji }
+              else
+                emoji&.to_h
+              end
+
+      @options << { label: label, value: value, description: description, emoji: emoji, default: default }
+    end
+
+    # @!visibility private
+    def to_h
+      {
+        type: COMPONENT_TYPES[@select_type],
+        id: @id,
+        options: @options,
+        placeholder: @placeholder,
+        min_values: @min_values,
+        max_values: @max_values,
+        custom_id: @custom_id,
+        disabled: @disabled,
+        required: @required,
+        default_values: @default_values
+      }.compact
+    end
+
+    private
+
+    # @!visibility private
+    def process_defaults(default_values)
+      if @select_type == :mentionable_select
+        default_values&.map do |default_value|
+          case default_value
+          when OnyxCord::Recipient, OnyxCord::User, OnyxCord::Member
+            { id: default_value.id, type: :user }
+          when OnyxCord::Role
+            { id: default_value.id, type: :role }
+          when Hash
+            default_value
+          else
+            raise TypeError, "Unsupported type: #{default_value.class}"
+          end
+        end
+      else
+        default_values&.map { |id| id.is_a?(Hash) ? id : { id: id.resolve_id, type: @select_type[..-8] } }
+      end
+    end
+  end
+
+  # A text display component allows you to send message content.
+end

data/lib/onyxcord/webhooks/view/separator_builder.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+class OnyxCord::Webhooks::View
+  class SeparatorBuilder
+    # Create a separator component.
+    # @param divider [true, false] Whether or not the separator should act as a visible barrier.
+    # @param id [Integer, nil] The unique 32-bit ID of the separator component.
+    # @param spacing [Symbol, Integer] The size of the separator component's padding. See {SEPARATOR_SIZES}.
+    def initialize(divider:, id: nil, spacing: nil)
+      @id = id
+      @divider = divider
+      @spacing = SEPARATOR_SIZES[spacing] || spacing
+    end
+
+    # @!visibility private
+    def to_h
+      { type: COMPONENT_TYPES[:separator], id: @id, divider: @divider, spacing: @spacing }.compact
+    end
+  end
+
+  # A file component lets you send a file via an attachment://<filename> reference.
+end

data/lib/onyxcord/webhooks/view/text_display_builder.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+class OnyxCord::Webhooks::View
+  class TextDisplayBuilder
+    # Create a text display component.
+    # @param content [String] The content of the text display component.
+    # @param id [Integer, nil] The unique 32-bit ID of the text display component.
+    def initialize(content:, id: nil)
+      @id = id
+      @content = content
+    end
+
+    # @!visibility private
+    def to_h
+      { type: COMPONENT_TYPES[:text_display], id: @id, content: @content }.compact
+    end
+  end
+
+  # A separator allows you to add a barrier between components.
+end