feat(block-kit): add block element examples

block-kit/README.md

@@ -20,3 +20,24 @@ Read the [docs](https://docs.slack.dev/block-kit/) to learn concepts behind thes
 - **[Section](https://docs.slack.dev/reference/block-kit/blocks/section-block)**: Displays text, possibly alongside elements. [Implementation](./src/main/java/blocks/Section.java).
 - **[Video](https://docs.slack.dev/reference/block-kit/blocks/video-block)**: Displays an embedded video player. [Implementation](./src/main/java/blocks/Video.java).
 
+### Block elements
+
+- **[Button](https://docs.slack.dev/reference/block-kit/block-elements/button-element)**: Allows users a direct path to performing basic actions. [Implementation](./src/main/java/blockelements/Button.java).
+- **[Date picker](https://docs.slack.dev/reference/block-kit/block-elements/date-picker-element)**: Allows users to select a date from a calendar style UI. [Implementation](./src/main/java/blockelements/DatePicker.java).
+- **[Datetime picker](https://docs.slack.dev/reference/block-kit/block-elements/datetime-picker-element)**: Allows users to select both a date and a time of day. [Implementation](./src/main/java/blockelements/DatetimePicker.java).
+- **[Email input](https://docs.slack.dev/reference/block-kit/block-elements/email-input-element)**: Allows user to enter an email into a single-line field. [Implementation](./src/main/java/blockelements/EmailInput.java).
+- **[Feedback buttons](https://docs.slack.dev/reference/block-kit/block-elements/feedback-buttons-element)**: Buttons to indicate positive or negative feedback. [Implementation](./src/main/java/blockelements/FeedbackButtons.java).
+- **[File input](https://docs.slack.dev/reference/block-kit/block-elements/file-input-element)**: Allows user to upload files. [Implementation](./src/main/java/blockelements/FileInput.java).
+- **[Icon button](https://docs.slack.dev/reference/block-kit/block-elements/icon-button-element)**: An icon button to perform actions. [Implementation](./src/main/java/blockelements/IconButton.java).
+- **[Image](https://docs.slack.dev/reference/block-kit/block-elements/image-element)**: Displays an image as part of a larger block of content. [Implementation](./src/main/java/blockelements/Image.java).
+- **[Multi-select menu](https://docs.slack.dev/reference/block-kit/block-elements/multi-select-menu-element)**: Allows users to select multiple items from a list of options. [Implementation](./src/main/java/blockelements/MultiSelectMenu.java).
+- **[Number input](https://docs.slack.dev/reference/block-kit/block-elements/number-input-element)**: Allows user to enter a number into a single-line field. [Implementation](./src/main/java/blockelements/NumberInput.java).
+- **[Overflow menu](https://docs.slack.dev/reference/block-kit/block-elements/overflow-menu-element)**: Allows users to press a button to view a list of options. [Implementation](./src/main/java/blockelements/OverflowMenu.java).
+- **[Plain-text input](https://docs.slack.dev/reference/block-kit/block-elements/plain-text-input-element)**: Allows users to enter freeform text data into a single-line or multi-line field. [Implementation](./src/main/java/blockelements/PlainTextInput.java).
+- **[Radio button group](https://docs.slack.dev/reference/block-kit/block-elements/radio-button-group-element)**: Allows users to choose one item from a list of possible options. [Implementation](./src/main/java/blockelements/RadioButtons.java).
+- **[Rich text input](https://docs.slack.dev/reference/block-kit/block-elements/rich-text-input-element)**: Allows users to enter formatted text in a WYSIWYG composer, offering the same messaging writing experience as in Slack. [Implementation](./src/main/java/blockelements/RichTextInput.java).
+- **[Select menu](https://docs.slack.dev/reference/block-kit/block-elements/select-menu-element)**: Allows users to choose an option from a drop down menu. [Implementation](./src/main/java/blockelements/SelectMenu.java).
+- **[Time picker](https://docs.slack.dev/reference/block-kit/block-elements/time-picker-element)**: A time picker element; on desktop a dropdown with free-text entry, on mobile the native time picker UI. [Implementation](./src/main/java/blockelements/TimePicker.java).
+- **[URL input](https://docs.slack.dev/reference/block-kit/block-elements/url-input-element)**: Allows user to enter a URL into a single-line field. [Implementation](./src/main/java/blockelements/UrlInput.java).
+- **[Workflow button](https://docs.slack.dev/reference/block-kit/block-elements/workflow-button-element)**: Allows users to run a link trigger with customizable inputs. [Implementation](./src/main/java/blockelements/WorkflowButton.java).
+

block-kit/src/main/java/blockelements/Button.java

@@ -0,0 +1,62 @@
+package blockelements;
+
+import static com.slack.api.model.block.composition.BlockCompositions.markdownText;
+import static com.slack.api.model.block.composition.BlockCompositions.plainText;
+
+import com.slack.api.model.block.Blocks;
+import com.slack.api.model.block.LayoutBlock;
+import com.slack.api.model.block.element.BlockElements;
+import com.slack.api.model.block.element.ButtonElement;
+import java.util.List;
+
+/**
+ * Allows users a direct path to performing basic actions.
+ * {@link https://docs.slack.dev/reference/block-kit/block-elements/button-element/}
+ */
+public class Button {
+    /**
+     * A regular button.
+     */
+    public static ButtonElement example01() {
+        ButtonElement element = BlockElements.button(
+                b -> b.text(plainText("Click Me")).value("click_me_123").actionId("button"));
+        return element;
+    }
+
+    /**
+     * A button using the primary style.
+     */
+    public static ButtonElement example02() {
+        ButtonElement element = BlockElements.button(b ->
+                b.text(plainText("Save")).style("primary").value("click_me_123").actionId("button"));
+        return element;
+    }
+
+    /**
+     * A button that opens a link.
+     */
+    public static ButtonElement example03() {
+        ButtonElement element =
+                BlockElements.button(b -> b.text(plainText("Link Button")).url("https://docs.slack.dev/block-kit"));
+        return element;
+    }
+
+    /**
+     * Buttons hosted in a section accessory and an actions block.
+     */
+    public static List<LayoutBlock> example04() {
+        List<LayoutBlock> blocks = List.of(
+                Blocks.section(s -> s.text(markdownText("This is a section block with a button."))
+                        .accessory(BlockElements.button(b -> b.text(plainText("Click Me"))
+                                .value("click_me_123")
+                                .actionId("button")))),
+                Blocks.actions(a -> a.blockId("actionblock789")
+                        .elements(List.of(
+                                BlockElements.button(b -> b.text(plainText("Primary Button"))
+                                        .style("primary")
+                                        .value("click_me_456")),
+                                BlockElements.button(b ->
+                                        b.text(plainText("Link Button")).url("https://api.slack.com/block-kit"))))));
+        return blocks;
+    }
+}

block-kit/src/main/java/blockelements/DatePicker.java

@@ -0,0 +1,26 @@
+package blockelements;
+
+import static com.slack.api.model.block.composition.BlockCompositions.markdownText;
+import static com.slack.api.model.block.composition.BlockCompositions.plainText;
+
+import com.slack.api.model.block.Blocks;
+import com.slack.api.model.block.SectionBlock;
+import com.slack.api.model.block.element.BlockElements;
+
+/**
+ * Allows users to select a date from a calendar style UI.
+ * {@link https://docs.slack.dev/reference/block-kit/block-elements/date-picker-element/}
+ */
+public class DatePicker {
+    /**
+     * A section block with a date picker accessory.
+     */
+    public static SectionBlock example01() {
+        SectionBlock block = Blocks.section(s -> s.blockId("section1234")
+                .text(markdownText("Pick a date for the deadline."))
+                .accessory(BlockElements.datePicker(d -> d.actionId("datepicker123")
+                        .initialDate("1990-04-28")
+                        .placeholder(plainText("Select a date")))));
+        return block;
+    }
+}

block-kit/src/main/java/blockelements/DatetimePicker.java

@@ -0,0 +1,24 @@
+package blockelements;
+
+import static com.slack.api.model.block.composition.BlockCompositions.plainText;
+
+import com.slack.api.model.block.Blocks;
+import com.slack.api.model.block.InputBlock;
+import com.slack.api.model.block.element.BlockElements;
+
+/**
+ * Allows users to select both a date and a time of day.
+ * {@link https://docs.slack.dev/reference/block-kit/block-elements/datetime-picker-element/}
+ */
+public class DatetimePicker {
+    /**
+     * An input block with a datetime picker element.
+     */
+    public static InputBlock example01() {
+        InputBlock block =
+                Blocks.input(i -> i.element(BlockElements.datetimePicker(d -> d.actionId("datetimepicker-action")))
+                        .hint(plainText(pt -> pt.text("This is some hint text").emoji(true)))
+                        .label(plainText(pt -> pt.text("Start date").emoji(true))));
+        return block;
+    }
+}

block-kit/src/main/java/blockelements/EmailInput.java

@@ -0,0 +1,24 @@
+package blockelements;
+
+import static com.slack.api.model.block.composition.BlockCompositions.plainText;
+
+import com.slack.api.model.block.Blocks;
+import com.slack.api.model.block.InputBlock;
+import com.slack.api.model.block.element.BlockElements;
+
+/**
+ * Allows user to enter an email into a single-line field.
+ * {@link https://docs.slack.dev/reference/block-kit/block-elements/email-input-element/}
+ */
+public class EmailInput {
+    /**
+     * An input block with an email input element.
+     */
+    public static InputBlock example01() {
+        InputBlock block = Blocks.input(i -> i.blockId("input123")
+                .label(plainText("Email Address"))
+                .element(BlockElements.emailTextInput(
+                        e -> e.actionId("email_text_input-action").placeholder(plainText("Enter an email")))));
+        return block;
+    }
+}

block-kit/src/main/java/blockelements/FeedbackButtons.java

@@ -0,0 +1,34 @@
+package blockelements;
+
+import static com.slack.api.model.block.composition.BlockCompositions.plainText;
+
+import com.slack.api.model.block.Blocks;
+import com.slack.api.model.block.ContextActionsBlock;
+import com.slack.api.model.block.composition.FeedbackButtonObject;
+import com.slack.api.model.block.element.BlockElements;
+import java.util.List;
+
+/**
+ * Buttons to indicate positive or negative feedback.
+ * {@link https://docs.slack.dev/reference/block-kit/block-elements/feedback-buttons-element/}
+ */
+public class FeedbackButtons {
+    /**
+     * A context actions block with a feedback buttons element.
+     */
+    public static ContextActionsBlock example01() {
+        ContextActionsBlock block =
+                Blocks.contextActions(List.of(BlockElements.feedbackButtons(fb -> fb.actionId("feedback_buttons_1")
+                        .positiveButton(FeedbackButtonObject.builder()
+                                .text(plainText("Good"))
+                                .value("positive_feedback")
+                                .accessibilityLabel("Mark this response as good")
+                                .build())
+                        .negativeButton(FeedbackButtonObject.builder()
+                                .text(plainText("Bad"))
+                                .value("negative_feedback")
+                                .accessibilityLabel("Mark this response as bad")
+                                .build()))));
+        return block;
+    }
+}

block-kit/src/main/java/blockelements/FileInput.java

@@ -0,0 +1,26 @@
+package blockelements;
+
+import static com.slack.api.model.block.composition.BlockCompositions.plainText;
+
+import com.slack.api.model.block.Blocks;
+import com.slack.api.model.block.InputBlock;
+import com.slack.api.model.block.element.BlockElements;
+import java.util.List;
+
+/**
+ * Allows user to upload files.
+ * {@link https://docs.slack.dev/reference/block-kit/block-elements/file-input-element/}
+ */
+public class FileInput {
+    /**
+     * An input block with a file input element.
+     */
+    public static InputBlock example01() {
+        InputBlock block = Blocks.input(i -> i.blockId("input_block_id")
+                .label(plainText("Upload Files"))
+                .element(BlockElements.fileInput(f -> f.actionId("file_input_action_id_1")
+                        .filetypes(List.of("jpg", "png"))
+                        .maxFiles(5))));
+        return block;
+    }
+}

block-kit/src/main/java/blockelements/IconButton.java

@@ -0,0 +1,25 @@
+package blockelements;
+
+import static com.slack.api.model.block.composition.BlockCompositions.plainText;
+
+import com.slack.api.model.block.Blocks;
+import com.slack.api.model.block.ContextActionsBlock;
+import com.slack.api.model.block.element.BlockElements;
+import java.util.List;
+
+/**
+ * An icon button to perform actions.
+ * {@link https://docs.slack.dev/reference/block-kit/block-elements/icon-button-element/}
+ */
+public class IconButton {
+    /**
+     * A context actions block with an icon button element.
+     */
+    public static ContextActionsBlock example01() {
+        ContextActionsBlock block = Blocks.contextActions(List.of(BlockElements.iconButton(ib -> ib.icon("trash")
+                .text(plainText("Delete"))
+                .actionId("delete_button")
+                .value("delete_item"))));
+        return block;
+    }
+}

block-kit/src/main/java/blockelements/Image.java

@@ -0,0 +1,51 @@
+package blockelements;
+
+import static com.slack.api.model.block.composition.BlockCompositions.markdownText;
+
+import com.slack.api.model.block.Blocks;
+import com.slack.api.model.block.SectionBlock;
+import com.slack.api.model.block.composition.SlackFileObject;
+import com.slack.api.model.block.element.BlockElements;
+
+/**
+ * Displays an image as part of a larger block of content.
+ * {@link https://docs.slack.dev/reference/block-kit/block-elements/image-element/}
+ */
+public class Image {
+    /**
+     * A section block with an image accessory using image_url.
+     */
+    public static SectionBlock example01() {
+        SectionBlock block = Blocks.section(s -> s.blockId("section567")
+                .text(markdownText("This is a section block with an accessory image."))
+                .accessory(BlockElements.image(
+                        i -> i.imageUrl("https://pbs.twimg.com/profile_images/625633822235693056/lNGUneLX_400x400.jpg")
+                                .altText("cute cat"))));
+        return block;
+    }
+
+    /**
+     * A section block with an image accessory using a slack_file url.
+     */
+    public static SectionBlock example02() {
+        SectionBlock block = Blocks.section(s -> s.blockId("section567")
+                .text(markdownText("This is a section block with an accessory image."))
+                .accessory(BlockElements.image(i -> i.slackFile(SlackFileObject.builder()
+                                .url("https://files.slack.com/files-pri/T0123456-F0123456/xyz.png")
+                                .build())
+                        .altText("Slack file object."))));
+        return block;
+    }
+
+    /**
+     * A section block with an image accessory using a slack_file id.
+     */
+    public static SectionBlock example03() {
+        SectionBlock block = Blocks.section(s -> s.blockId("section567")
+                .text(markdownText("This is a section block with an accessory image."))
+                .accessory(BlockElements.image(i -> i.slackFile(
+                                SlackFileObject.builder().id("F01234567").build())
+                        .altText("Slack file object."))));
+        return block;
+    }
+}

block-kit/src/main/java/blockelements/MultiSelectMenu.java

@@ -0,0 +1,85 @@
+package blockelements;
+
+import static com.slack.api.model.block.composition.BlockCompositions.markdownText;
+import static com.slack.api.model.block.composition.BlockCompositions.plainText;
+
+import com.slack.api.model.block.Blocks;
+import com.slack.api.model.block.SectionBlock;
+import com.slack.api.model.block.composition.OptionObject;
+import com.slack.api.model.block.element.BlockElements;
+import java.util.List;
+
+/**
+ * Allows users to select multiple items from a list of options.
+ * {@link https://docs.slack.dev/reference/block-kit/block-elements/multi-select-menu-element/}
+ */
+public class MultiSelectMenu {
+    /**
+     * A section block with a multi-select menu of static options.
+     */
+    public static SectionBlock example01() {
+        SectionBlock block = Blocks.section(s -> s.blockId("section678")
+                .text(markdownText("Pick items from the list"))
+                .accessory(BlockElements.multiStaticSelect(m -> m.actionId("text1234")
+                        .placeholder(plainText("Select items"))
+                        .options(List.of(
+                                OptionObject.builder()
+                                        .text(plainText("*this is plain_text text*"))
+                                        .value("value-0")
+                                        .build(),
+                                OptionObject.builder()
+                                        .text(plainText("*this is plain_text text*"))
+                                        .value("value-1")
+                                        .build(),
+                                OptionObject.builder()
+                                        .text(plainText("*this is plain_text text*"))
+                                        .value("value-2")
+                                        .build())))));
+        return block;
+    }
+
+    /**
+     * A section block with a multi-select menu of options loaded from an external source.
+     */
+    public static SectionBlock example02() {
+        SectionBlock block = Blocks.section(s -> s.blockId("section678")
+                .text(markdownText("Pick items from the list"))
+                .accessory(BlockElements.multiExternalSelect(m -> m.actionId("text1234")
+                        .placeholder(plainText("Select items"))
+                        .minQueryLength(3))));
+        return block;
+    }
+
+    /**
+     * A section block with a multi-select menu of users.
+     */
+    public static SectionBlock example03() {
+        SectionBlock block = Blocks.section(s -> s.blockId("section678")
+                .text(markdownText("Pick users from the list"))
+                .accessory(BlockElements.multiUsersSelect(
+                        m -> m.actionId("text1234").placeholder(plainText("Select users")))));
+        return block;
+    }
+
+    /**
+     * A section block with a multi-select menu of conversations.
+     */
+    public static SectionBlock example04() {
+        SectionBlock block = Blocks.section(s -> s.blockId("section678")
+                .text(markdownText("Pick conversations from the list"))
+                .accessory(BlockElements.multiConversationsSelect(
+                        m -> m.actionId("text1234").placeholder(plainText("Select conversations")))));
+        return block;
+    }
+
+    /**
+     * A section block with a multi-select menu of channels.
+     */
+    public static SectionBlock example05() {
+        SectionBlock block = Blocks.section(s -> s.blockId("section678")
+                .text(markdownText("Pick channels from the list"))
+                .accessory(BlockElements.multiChannelsSelect(
+                        m -> m.actionId("text1234").placeholder(plainText("Select channels")))));
+        return block;
+    }
+}