feat(block-kit): add block element examples

block-kit/README.md

@@ -24,3 +24,40 @@ Read the [docs](https://docs.slack.dev/block-kit/) to learn concepts behind thes
 - **[Table](https://docs.slack.dev/reference/block-kit/blocks/table-block)**: Displays structured information in a table. [Implementation](./src/blocks/table.py).
 - **[Task card](https://docs.slack.dev/reference/block-kit/blocks/task-card-block)**: Displays a single task, representing a single action. [Implementation](./src/blocks/task_card.py).
 - **[Video](https://docs.slack.dev/reference/block-kit/blocks/video-block)**: Displays an embedded video player. [Implementation](./src/blocks/video.py).
+
+### Block elements
+
+- **[Broadcast](https://docs.slack.dev/reference/block-kit/block-elements/broadcast-element)**: Displays a broadcast mention such as here, channel, or everyone. [Implementation](./src/block_elements/broadcast.py).
+- **[Button](https://docs.slack.dev/reference/block-kit/block-elements/button-element)**: Allows users a direct path to performing basic actions. [Implementation](./src/block_elements/button.py).
+- **[Channel](https://docs.slack.dev/reference/block-kit/block-elements/channel-element)**: Renders as a mention of a channel. [Implementation](./src/block_elements/channel.py).
+- **[Checkboxes](https://docs.slack.dev/reference/block-kit/block-elements/checkboxes-element)**: Allows users to choose multiple items from a list of options. [Implementation](./src/block_elements/checkboxes.py).
+- **[Color](https://docs.slack.dev/reference/block-kit/block-elements/color-element)**: Displays a color swatch from a hex value. [Implementation](./src/block_elements/color.py).
+- **[Date](https://docs.slack.dev/reference/block-kit/block-elements/date-element)**: Displays a formatted, localized date. [Implementation](./src/block_elements/date.py).
+- **[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/block_elements/date_picker.py).
+- **[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/block_elements/datetime_picker.py).
+- **[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/block_elements/email_input.py).
+- **[Emoji](https://docs.slack.dev/reference/block-kit/block-elements/emoji-element)**: Displays an emoji. [Implementation](./src/block_elements/emoji.py).
+- **[Feedback buttons](https://docs.slack.dev/reference/block-kit/block-elements/feedback-buttons-element)**: Buttons to indicate positive or negative feedback. [Implementation](./src/block_elements/feedback_buttons.py).
+- **[File input](https://docs.slack.dev/reference/block-kit/block-elements/file-input-element)**: Allows user to upload files. [Implementation](./src/block_elements/file_input.py).
+- **[Icon button](https://docs.slack.dev/reference/block-kit/block-elements/icon-button-element)**: An icon button to perform actions. [Implementation](./src/block_elements/icon_button.py).
+- **[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/block_elements/image.py).
+- **[Link](https://docs.slack.dev/reference/block-kit/block-elements/link-element)**: Displays a hyperlink. [Implementation](./src/block_elements/link.py).
+- **[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/block_elements/multi_select_menu.py).
+- **[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/block_elements/number_input.py).
+- **[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/block_elements/overflow_menu.py).
+- **[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/block_elements/plain_text_input.py).
+- **[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/block_elements/radio_buttons.py).
+- **[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/block_elements/rich_text_input.py).
+- **[Rich text list](https://docs.slack.dev/reference/block-kit/block-elements/rich-text-list-element)**: Displays a list of rich text items. [Implementation](./src/block_elements/rich_text_list.py).
+- **[Rich text preformatted](https://docs.slack.dev/reference/block-kit/block-elements/rich-text-preformatted-element)**: Displays a preformatted rich text element. [Implementation](./src/block_elements/rich_text_preformatted.py).
+- **[Rich text quote](https://docs.slack.dev/reference/block-kit/block-elements/rich-text-quote-element)**: Displays a rich text quote block. [Implementation](./src/block_elements/rich_text_quote.py).
+- **[Rich text section](https://docs.slack.dev/reference/block-kit/block-elements/rich-text-section-element)**: A section element that holds rich text elements. [Implementation](./src/block_elements/rich_text_section.py).
+- **[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/block_elements/select_menu.py).
+- **[Team](https://docs.slack.dev/reference/block-kit/block-elements/team-element)**: Renders as a mention of a workspace or team. [Implementation](./src/block_elements/team.py).
+- **[Text](https://docs.slack.dev/reference/block-kit/block-elements/text-element)**: Displays text, optionally with styling. [Implementation](./src/block_elements/text.py).
+- **[Time picker](https://docs.slack.dev/reference/block-kit/block-elements/time-picker-element)**: Allows users to select a time of day. [Implementation](./src/block_elements/time_picker.py).
+- **[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/block_elements/url_input.py).
+- **[URL source](https://docs.slack.dev/reference/block-kit/block-elements/url-source-element)**: Displays a URL source for referencing within a task card block. [Implementation](./src/block_elements/url_source.py).
+- **[User](https://docs.slack.dev/reference/block-kit/block-elements/user-element)**: Renders as a mention of a user. [Implementation](./src/block_elements/user.py).
+- **[Usergroup](https://docs.slack.dev/reference/block-kit/block-elements/usergroup-element)**: Renders as a mention of a user group. [Implementation](./src/block_elements/usergroup.py).
+- **[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/block_elements/workflow_button.py).

block-kit/src/block_elements/broadcast.py

@@ -0,0 +1,24 @@
+from slack_sdk.models.blocks import RichTextBlock
+from slack_sdk.models.blocks.block_elements import (
+    RichTextElementParts,
+    RichTextSectionElement,
+)
+
+
+def example01() -> RichTextBlock:
+    """
+    Displays a broadcast mention such as here, channel, or everyone.
+    https://docs.slack.dev/reference/block-kit/block-elements/broadcast-element/
+
+    A rich text block whose section holds a broadcast element.
+    """
+    block = RichTextBlock(
+        elements=[
+            RichTextSectionElement(
+                elements=[
+                    RichTextElementParts.Broadcast(range="everyone"),
+                ]
+            )
+        ]
+    )
+    return block

block-kit/src/block_elements/button.py

@@ -0,0 +1,76 @@
+from slack_sdk.models.blocks import ActionsBlock, Block, SectionBlock
+from slack_sdk.models.blocks.basic_components import MarkdownTextObject, PlainTextObject
+from slack_sdk.models.blocks.block_elements import ButtonElement
+
+
+def example01() -> ButtonElement:
+    """
+    Allows users a direct path to performing basic actions.
+    https://docs.slack.dev/reference/block-kit/block-elements/button-element/
+
+    A regular interactive button.
+    """
+    element = ButtonElement(
+        text=PlainTextObject(text="Click Me"),
+        value="click_me_123",
+        action_id="button",
+    )
+    return element
+
+
+def example02() -> ButtonElement:
+    """
+    A button with a primary style attribute.
+    """
+    element = ButtonElement(
+        text=PlainTextObject(text="Save"),
+        style="primary",
+        value="click_me_123",
+        action_id="button",
+    )
+    return element
+
+
+def example03() -> ButtonElement:
+    """
+    A link button.
+    """
+    element = ButtonElement(
+        text=PlainTextObject(text="Link Button"),
+        url="https://docs.slack.dev/block-kit",
+    )
+    return element
+
+
+def example04() -> list[Block]:
+    """
+    The button element must be used inside either the section or actions block.
+
+    A section block with a button as an accessory, followed by an actions
+    block holding a primary button and a link button.
+    """
+    blocks: list[Block] = [
+        SectionBlock(
+            text=MarkdownTextObject(text="This is a section block with a button."),
+            accessory=ButtonElement(
+                text=PlainTextObject(text="Click Me"),
+                value="click_me_123",
+                action_id="button",
+            ),
+        ),
+        ActionsBlock(
+            block_id="actionblock789",
+            elements=[
+                ButtonElement(
+                    text=PlainTextObject(text="Primary Button"),
+                    style="primary",
+                    value="click_me_456",
+                ),
+                ButtonElement(
+                    text=PlainTextObject(text="Link Button"),
+                    url="https://api.slack.com/block-kit",
+                ),
+            ],
+        ),
+    ]
+    return blocks

block-kit/src/block_elements/channel.py

@@ -0,0 +1,24 @@
+from slack_sdk.models.blocks import RichTextBlock
+from slack_sdk.models.blocks.block_elements import (
+    RichTextElementParts,
+    RichTextSectionElement,
+)
+
+
+def example01() -> RichTextBlock:
+    """
+    Renders as a mention of a channel.
+    https://docs.slack.dev/reference/block-kit/block-elements/channel-element/
+
+    A rich text block whose section holds a channel mention element.
+    """
+    block = RichTextBlock(
+        elements=[
+            RichTextSectionElement(
+                elements=[
+                    RichTextElementParts.Channel(channel_id="C123ABC456"),
+                ]
+            )
+        ]
+    )
+    return block

block-kit/src/block_elements/checkboxes.py

@@ -0,0 +1,36 @@
+from slack_sdk.models.blocks import SectionBlock
+from slack_sdk.models.blocks.basic_components import (
+    MarkdownTextObject,
+    Option,
+    PlainTextObject,
+)
+from slack_sdk.models.blocks.block_elements import CheckboxesElement
+
+
+def example01() -> SectionBlock:
+    """
+    Allows users to choose multiple items from a list of options.
+    https://docs.slack.dev/reference/block-kit/block-elements/checkboxes-element/
+
+    A section block with a checkboxes element as an accessory.
+    """
+    block = SectionBlock(
+        text=PlainTextObject(text="Check out these charming checkboxes"),
+        accessory=CheckboxesElement(
+            action_id="this_is_an_action_id",
+            initial_options=[
+                Option(value="A1", text=PlainTextObject(text="Checkbox 1")),
+            ],
+            options=[
+                Option(value="A1", text=PlainTextObject(text="Checkbox 1")),
+                Option(
+                    value="A2",
+                    text=PlainTextObject(text="Checkbox 2"),
+                    description=MarkdownTextObject(
+                        text="*A description of option two*"
+                    ),
+                ),
+            ],
+        ),
+    )
+    return block

block-kit/src/block_elements/color.py

@@ -0,0 +1,24 @@
+from slack_sdk.models.blocks import RichTextBlock
+from slack_sdk.models.blocks.block_elements import (
+    RichTextElementParts,
+    RichTextSectionElement,
+)
+
+
+def example01() -> RichTextBlock:
+    """
+    Displays a color swatch from a hex value.
+    https://docs.slack.dev/reference/block-kit/block-elements/color-element/
+
+    A rich text block whose section holds a color element.
+    """
+    block = RichTextBlock(
+        elements=[
+            RichTextSectionElement(
+                elements=[
+                    RichTextElementParts.Color(value="#F405B3"),
+                ]
+            )
+        ]
+    )
+    return block

block-kit/src/block_elements/date.py

@@ -0,0 +1,28 @@
+from slack_sdk.models.blocks import RichTextBlock
+from slack_sdk.models.blocks.block_elements import (
+    RichTextElementParts,
+    RichTextSectionElement,
+)
+
+
+def example01() -> RichTextBlock:
+    """
+    Displays a formatted, localized date.
+    https://docs.slack.dev/reference/block-kit/block-elements/date-element/
+
+    A rich text block whose section holds a date element with a fallback.
+    """
+    block = RichTextBlock(
+        elements=[
+            RichTextSectionElement(
+                elements=[
+                    RichTextElementParts.Date(
+                        timestamp=1720710212,
+                        format="{date_num} at {time}",
+                        fallback="timey",
+                    ),
+                ]
+            )
+        ]
+    )
+    return block

block-kit/src/block_elements/date_picker.py

@@ -0,0 +1,22 @@
+from slack_sdk.models.blocks import SectionBlock
+from slack_sdk.models.blocks.basic_components import MarkdownTextObject, PlainTextObject
+from slack_sdk.models.blocks.block_elements import DatePickerElement
+
+
+def example01() -> SectionBlock:
+    """
+    Allows users to select a date from a calendar style UI.
+    https://docs.slack.dev/reference/block-kit/block-elements/date-picker-element/
+
+    A section block with a date picker as an accessory.
+    """
+    block = SectionBlock(
+        block_id="section1234",
+        text=MarkdownTextObject(text="Pick a date for the deadline."),
+        accessory=DatePickerElement(
+            action_id="datepicker123",
+            initial_date="1990-04-28",
+            placeholder=PlainTextObject(text="Select a date"),
+        ),
+    )
+    return block

block-kit/src/block_elements/datetime_picker.py

@@ -0,0 +1,18 @@
+from slack_sdk.models.blocks import InputBlock
+from slack_sdk.models.blocks.basic_components import PlainTextObject
+from slack_sdk.models.blocks.block_elements import DateTimePickerElement
+
+
+def example01() -> InputBlock:
+    """
+    Allows users to select both a date and a time of day.
+    https://docs.slack.dev/reference/block-kit/block-elements/datetime-picker-element/
+
+    An input block with a datetime picker element.
+    """
+    block = InputBlock(
+        element=DateTimePickerElement(action_id="datetimepicker-action"),
+        hint=PlainTextObject(text="This is some hint text", emoji=True),
+        label=PlainTextObject(text="Start date", emoji=True),
+    )
+    return block

block-kit/src/block_elements/email_input.py

@@ -0,0 +1,21 @@
+from slack_sdk.models.blocks import InputBlock
+from slack_sdk.models.blocks.basic_components import PlainTextObject
+from slack_sdk.models.blocks.block_elements import EmailInputElement
+
+
+def example01() -> InputBlock:
+    """
+    Allows user to enter an email into a single-line field.
+    https://docs.slack.dev/reference/block-kit/block-elements/email-input-element/
+
+    An input block with an email input element.
+    """
+    block = InputBlock(
+        block_id="input123",
+        label=PlainTextObject(text="Email Address"),
+        element=EmailInputElement(
+            action_id="email_text_input-action",
+            placeholder=PlainTextObject(text="Enter an email"),
+        ),
+    )
+    return block

block-kit/src/block_elements/emoji.py

@@ -0,0 +1,28 @@
+from slack_sdk.models.blocks import RichTextBlock
+from slack_sdk.models.blocks.block_elements import (
+    RichTextElementParts,
+    RichTextSectionElement,
+)
+
+
+def example01() -> RichTextBlock:
+    """
+    Displays an emoji.
+    https://docs.slack.dev/reference/block-kit/block-elements/emoji-element/
+
+    A rich text block whose section holds emoji elements separated by text.
+    """
+    block = RichTextBlock(
+        elements=[
+            RichTextSectionElement(
+                elements=[
+                    RichTextElementParts.Emoji(name="basketball"),
+                    RichTextElementParts.Text(text=" "),
+                    RichTextElementParts.Emoji(name="snowboarder"),
+                    RichTextElementParts.Text(text=" "),
+                    RichTextElementParts.Emoji(name="checkered_flag"),
+                ]
+            )
+        ]
+    )
+    return block

block-kit/src/block_elements/feedback_buttons.py

@@ -0,0 +1,33 @@
+from slack_sdk.models.blocks import ContextActionsBlock
+from slack_sdk.models.blocks.basic_components import (
+    FeedbackButtonObject,
+    PlainTextObject,
+)
+from slack_sdk.models.blocks.block_elements import FeedbackButtonsElement
+
+
+def example01() -> ContextActionsBlock:
+    """
+    Buttons to indicate positive or negative feedback.
+    https://docs.slack.dev/reference/block-kit/block-elements/feedback-buttons-element/
+
+    A context actions block holding a feedback buttons element.
+    """
+    block = ContextActionsBlock(
+        elements=[
+            FeedbackButtonsElement(
+                action_id="feedback_buttons_1",
+                positive_button=FeedbackButtonObject(
+                    text=PlainTextObject(text="Good", emoji=None),
+                    value="positive_feedback",
+                    accessibility_label="Mark this response as good",
+                ),
+                negative_button=FeedbackButtonObject(
+                    text=PlainTextObject(text="Bad", emoji=None),
+                    value="negative_feedback",
+                    accessibility_label="Mark this response as bad",
+                ),
+            ),
+        ]
+    )
+    return block