slack_block_kit 0.1.0 → 0.2.0

data/lib/slack/block_kit/element/channels_select.rb

@@ -3,14 +3,34 @@
 module Slack
   module BlockKit
     module Element
+      # A select menu, just as with a standard HTML <select> tag, creates a drop
+      # down menu with a list of options for a user to choose. The select menu
+      # also includes type-ahead functionality, where a user can type a part or
+      # all of an option string to filter the list.
+      #
+      # This select menu will populate its options with a list of public
+      # channels visible to the current user in the active workspace.
+      #
+      # https://api.slack.com/reference/messaging/block-elements#channel-select
       class ChannelsSelect
         TYPE = 'channels_select'
 
-        def initialize(placeholder:, action_id:, initial_channel: nil, confirm: nil)
-          @placeholder = placeholder
+        attr_accessor :confirm
+
+        def initialize(placeholder:, action_id:, initial: nil, emoji: nil)
+          @placeholder = Composition::PlainText.new(text: placeholder, emoji: emoji)
           @action_id = action_id
-          @initial_conversation = initial_channel
-          @confirm = confirm
+          @initial_channel = initial
+
+          yield(self) if block_given?
+        end
+
+        def confirmation_dialog
+          @confirm = Composition::ConfirmationDialog.new
+
+          yield(@confirm) if block_given?
+
+          self
         end
 
         def as_json(*)
@@ -18,9 +38,9 @@ module Slack
             type: TYPE,
             placeholder: @placeholder.as_json,
             action_id: @action_id,
-            initial_conversation: @initial_channel,
+            initial_channel: @initial_channel,
             confirm: @confirm&.as_json
-          }
+          }.compact
         end
       end
     end

data/lib/slack/block_kit/element/conversations_select.rb

@@ -3,14 +3,35 @@
 module Slack
   module BlockKit
     module Element
+      # A select menu, just as with a standard HTML <select> tag, creates a drop
+      # down menu with a list of options for a user to choose. The select menu
+      # also includes type-ahead functionality, where a user can type a part or
+      # all of an option string to filter the list.
+      #
+      # This select menu will populate its options with a list of public and
+      # private channels, DMs, and MPIMs visible to the current user in the
+      # active workspace.
+      #
+      # https://api.slack.com/reference/messaging/block-elements#conversation-select
       class ConversationsSelect
         TYPE = 'conversations_select'
 
-        def initialize(placeholder:, action_id:, initial_conversation: nil, confirm: nil)
-          @placeholder = placeholder
+        attr_accessor :confirm
+
+        def initialize(placeholder:, action_id:, initial: nil, emoji: nil)
+          @placeholder = Composition::PlainText.new(text: placeholder, emoji: emoji)
           @action_id = action_id
-          @initial_conversation = initial_conversation
-          @confirm = confirm
+          @initial_conversation = initial
+
+          yield(self) if block_given?
+        end
+
+        def confirmation_dialog
+          @confirm = Composition::ConfirmationDialog.new
+
+          yield(@confirm) if block_given?
+
+          self
         end
 
         def as_json(*)

data/lib/slack/block_kit/element/date_picker.rb

@@ -3,14 +3,34 @@
 module Slack
   module BlockKit
     module Element
+      # An element which lets users easily select a date from a calendar style
+      # UI.
+      #
+      # Date picker elements can be used inside of section and actions blocks.
+      #
+      # https://api.slack.com/reference/messaging/block-elements#datepicker
       class DatePicker
         TYPE = 'datepicker'
 
-        def initialize(action_id:, placeholder: nil, initial_date: nil, confirm: nil)
+        def initialize(action_id:, placeholder: nil, initial: nil, emoji: nil)
           @action_id = action_id
-          @placeholder = placeholder
-          @initial_date = initial_date
-          @confirm = confirm
+          @initial_date = initial
+          if placeholder
+            @placeholder = Composition::PlainText.new(
+              text: placeholder,
+              emoji: emoji
+            )
+          end
+
+          yield(self) if block_given?
+        end
+
+        def confirmation_dialog
+          @confirm = Composition::ConfirmationDialog.new
+
+          yield(@confirm) if block_given?
+
+          self
         end
 
         def as_json(*)

data/lib/slack/block_kit/element/external_select.rb

@@ -3,15 +3,41 @@
 module Slack
   module BlockKit
     module Element
+      # A select menu, just as with a standard HTML <select> tag, creates a drop
+      # down menu with a list of options for a user to choose. The select menu
+      # also includes type-ahead functionality, where a user can type a part or
+      # all of an option string to filter the list.
+      #
+      # This select menu will load its options from an external data source,
+      # allowing for a dynamic list of options.
+      #
+      # Each time a select menu of this type is opened or the user starts typing
+      # in the typeahead field, we'll send a request to your specified URL. Your
+      # app should return an HTTP 200 OK response, along with an
+      # application/json post body with an object containing either an options
+      # array, or an option_groups array.
+      #
+      # https://api.slack.com/reference/messaging/block-elements#external-select
       class ExternalSelect
         TYPE = 'external_select'
 
-        def initialize(placeholder:, action_id:, initial_option: nil, min_query_length: nil, confirm: nil)
-          @placeholder = placeholder
+        attr_accessor :confirm
+
+        def initialize(placeholder:, action_id:, initial: nil, min_query_length: nil, emoji: nil)
+          @placeholder = Composition::PlainText.new(text: placeholder, emoji: emoji)
           @action_id = action_id
-          @initial_option = initial_option
+          @initial_option = initial
           @min_query_length = min_query_length
-          @confirm = confirm
+
+          yield(self) if block_given?
+        end
+
+        def confirmation_dialog
+          @confirm = Composition::ConfirmationDialog.new
+
+          yield(@confirm) if block_given?
+
+          self
         end
 
         def as_json(*)

data/lib/slack/block_kit/element/image.rb

@@ -3,6 +3,11 @@
 module Slack
   module BlockKit
     module Element
+      # An element to insert an image - this element can be used in section and
+      # context blocks only. If you want a block with only an image in it,
+      # you're looking for the image block. (Slack::BlockKit::Layout::Image)
+      #
+      # https://api.slack.com/reference/messaging/block-elements#image
       class Image
         TYPE = 'image'
 

data/lib/slack/block_kit/element/overflow_menu.rb

@@ -3,13 +3,45 @@
 module Slack
   module BlockKit
     module Element
+      # This is like a cross between a button and a select menu - when a user
+      # clicks on this overflow button, they will be presented with a list of
+      # options to choose from. Unlike the select menu, there is no typeahead
+      # field, and the button always appears with an ellipsis ("…") rather than
+      # customisable text.
+      #
+      # As such, it is usually used if you want a more compact layout than a
+      # select menu, or to supply a list of less visually important actions
+      # after a row of buttons.
+      #
+      # https://api.slack.com/reference/messaging/block-elements#overflow
       class OverflowMenu
         TYPE = 'overflow'
 
-        def initialize(action_id:, options:, confirm: nil)
+        attr_accessor :options, :confirm
+
+        def initialize(action_id:)
           @action_id = action_id
-          @options = options
-          @confirm = confirm
+          @options = []
+
+          yield(self) if block_given?
+        end
+
+        def option(value:, text:, emoji: nil)
+          @options << Composition::Option.new(
+            value: value,
+            text: text,
+            emoji: emoji
+          )
+
+          self
+        end
+
+        def confirmation_dialog
+          @confirm = Composition::ConfirmationDialog.new
+
+          yield(@confirm) if block_given?
+
+          self
         end
 
         def as_json(*)

data/lib/slack/block_kit/element/static_select.rb

@@ -3,16 +3,65 @@
 module Slack
   module BlockKit
     module Element
+      # A select menu, just as with a standard HTML <select> tag, creates a drop
+      # down menu with a list of options for a user to choose. The select menu
+      # also includes type-ahead functionality, where a user can type a part or
+      # all of an option string to filter the list.
+      #
+      # This is the simplest form of select menu, with a static list of options
+      # passed in when defining the element.
+      #
+      # https://api.slack.com/reference/messaging/block-elements#static-select
       class StaticSelect
         TYPE = 'static_select'
 
-        def initialize(placeholder:, action_id:, options:, option_groups:, initial_option: nil, confirm: nil)
-          @placeholder = placeholder
+        attr_accessor :confirm, :options, :option_groups, :initial_option
+
+        def initialize(placeholder:, action_id:, emoji: nil)
+          @placeholder = Composition::PlainText.new(text: placeholder, emoji: emoji)
           @action_id = action_id
-          @options = options
-          @option_groups = option_groups
-          @initial_option = initial_option
-          @confirm = confirm
+
+          yield(self) if block_given?
+        end
+
+        def confirmation_dialog
+          @confirm = Composition::ConfirmationDialog.new
+
+          yield(@confirm) if block_given?
+
+          self
+        end
+
+        def option(value:, text:, emoji: nil)
+          @options ||= []
+          @options << Composition::Option.new(
+            value: value,
+            text: text,
+            emoji: emoji
+          )
+
+          self
+        end
+
+        def option_group(label:, emoji: nil)
+          option_group = Composition::OptionGroup.new(label: label, emoji: emoji)
+
+          yield(option_group) if block_given?
+
+          @option_groups ||= []
+          @option_groups << option_group
+
+          self
+        end
+
+        def initial(value:, text:, emoji: nil)
+          @initial_option = Composition::Option.new(
+            value: value,
+            text: text,
+            emoji: emoji
+          )
+
+          self
         end
 
         def as_json(*)

data/lib/slack/block_kit/element/users_select.rb

@@ -3,14 +3,34 @@
 module Slack
   module BlockKit
     module Element
+      # A select menu, just as with a standard HTML <select> tag, creates a drop
+      # down menu with a list of options for a user to choose. The select menu
+      # also includes type-ahead functionality, where a user can type a part or
+      # all of an option string to filter the list.
+      #
+      # This select menu will populate its options with a list of Slack users
+      # visible to the current user in the active workspace.
+      #
+      # https://api.slack.com/reference/messaging/block-elements#users-select
       class UsersSelect
         TYPE = 'users_select'
 
-        def initialize(placeholder:, action_id:, initial_user: nil, confirm: nil)
-          @placeholder = placeholder
+        attr_accessor :confirm
+
+        def initialize(placeholder:, action_id:, initial: nil, emoji: nil)
+          @placeholder = Composition::PlainText.new(text: placeholder, emoji: emoji)
           @action_id = action_id
-          @initial_user = initial_user
-          @confirm = confirm
+          @initial_user = initial
+
+          yield(self) if block_given?
+        end
+
+        def confirmation_dialog
+          @confirm = Composition::ConfirmationDialog.new
+
+          yield(@confirm) if block_given?
+
+          self
         end
 
         def as_json(*)

data/lib/slack/block_kit/layout/actions.rb

@@ -3,12 +3,125 @@
 module Slack
   module BlockKit
     module Layout
+      # A block that is used to hold interactive elements.
+      #
+      # https://api.slack.com/reference/messaging/blocks#actions
       class Actions
         TYPE = 'actions'
 
-        def initialize(elements:, block_id: nil)
-          @elements = elements
+        attr_accessor :elements
+
+        def initialize(block_id: nil)
           @block_id = block_id
+          @elements = []
+
+          yield(self) if block_given?
+        end
+
+        def button(text:, action_id:, emoji: nil, url: nil, value: nil)
+          element = Element::Button.new(
+            text: text,
+            action_id: action_id,
+            emoji: emoji,
+            url: url,
+            value: value
+          )
+
+          yield(element) if block_given?
+
+          append(element)
+        end
+
+        def channel_select(placeholder:, action_id:, initial: nil, emoji: nil)
+          element = Element::ChannelsSelect.new(
+            placeholder: placeholder,
+            action_id: action_id,
+            initial: initial,
+            emoji: emoji
+          )
+
+          yield(element) if block_given?
+
+          append(element)
+        end
+
+        def converstation_select(placeholder:, action_id:, initial: nil, emoji: nil)
+          element = Element::ConversationsSelect.new(
+            placeholder: placeholder,
+            action_id: action_id,
+            initial: initial,
+            emoji: emoji
+          )
+
+          yield(element) if block_given?
+
+          append(element)
+        end
+
+        def date_picker(action_id:, placeholder: nil, initial: nil, emoji: nil)
+          element = Element::DatePicker.new(
+            placeholder: placeholder,
+            action_id: action_id,
+            initial: initial,
+            emoji: emoji
+          )
+
+          yield(element) if block_given?
+
+          append(element)
+        end
+
+        def external_select(placeholder:, action_id:, initial: nil, min_query_length: nil, emoji: nil)
+          element = Element::ExternalSelect.new(
+            placeholder: placeholder,
+            action_id: action_id,
+            initial: initial,
+            min_query_length: min_query_length,
+            emoji: emoji
+          )
+
+          yield(element) if block_given?
+
+          append(element)
+        end
+
+        def overflow_menu(action_id:)
+          element = Element::OverflowMenu.new(action_id: action_id)
+
+          yield(element) if block_given?
+
+          append(element)
+        end
+
+        def static_select(placeholder:, action_id:, emoji: nil)
+          element = Element::StaticSelect.new(
+            placeholder: placeholder,
+            action_id: action_id,
+            emoji: emoji
+          )
+
+          yield(element) if block_given?
+
+          append(element)
+        end
+
+        def users_select(placeholder:, action_id:, initial: nil, emoji: nil)
+          element = Element::UsersSelect.new(
+            placeholder: placeholder,
+            action_id: action_id,
+            emoji: emoji,
+            initial: initial
+          )
+
+          yield(element) if block_given?
+
+          append(element)
+        end
+
+        def append(element)
+          @elements << element
+
+          self
         end
 
         def as_json(*)