diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 5be2ab43..ae030cbc 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -76,6 +76,9 @@ jobs: - name: Verify immutable historical snapshots run: pnpm --filter @slackblocks/docs check:legacy-snapshots + - name: Verify every released version has a docs snapshot + run: pnpm --filter @slackblocks/docs check:release-snapshots + - name: Verify documentation generation is clean run: >- git diff --exit-code -- diff --git a/RELEASING.md b/RELEASING.md index 920030ac..7b74c452 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -48,14 +48,36 @@ These must be in place before the workflows can publish: ## Coordinated release procedure -1. Bump the version in **both** manifests on one branch: +The docs site serves the current package version live (`lastVersion: +"current"`) and lists every earlier release as a frozen snapshot in the version +dropdown. Each release therefore has to freeze the version it is moving *off* +before the new version takes over as current — otherwise that version vanishes +from the dropdown. CI enforces this: the `check:release-snapshots` guard fails +if any released `python/v*` tag other than the current package version is +missing from `docs/versions.json` (or the legacy manifest). + +1. On one branch, freeze the **outgoing** docs version — the value currently in + `python/pyproject.toml`, before you bump it — so it survives as a dropdown + entry once the new version becomes current: + + ```sh + pnpm --filter @slackblocks/docs generate + pnpm --filter @slackblocks/docs exec docusaurus docs:version + ``` + + `generate` populates the gitignored API reference so the snapshot matches a + real build; `docs:version` then copies `docs/docs` into + `docs/versioned_docs/version-` and prepends `` to + `docs/versions.json`. (The very first monorepo release is the exception: its + outgoing `2.0.0` is a legacy version already frozen in the manifest.) +2. Bump the version in **both** manifests on the same branch: - `python/pyproject.toml` (`project.version`) - `typescript/package.json` (`version`) -2. Add a `## [X.Y.Z] — YYYY-MM-DD` section to both `python/CHANGELOG.md` and +3. Add a `## [X.Y.Z] — YYYY-MM-DD` section to both `python/CHANGELOG.md` and `typescript/CHANGELOG.md`. The publish workflows extract this section for the GitHub Release notes. -3. Merge to `master` and wait for CI to pass. -4. Tag and push, Python first (either order works; the guards only require +4. Merge to `master` and wait for CI to pass. +5. Tag and push, Python first (either order works; the guards only require the two manifests to agree): ```sh @@ -63,7 +85,7 @@ These must be in place before the workflows can publish: git tag ts/vX.Y.Z && git push origin ts/vX.Y.Z ``` -5. Each workflow publishes to its registry and then creates a GitHub Release +6. Each workflow publishes to its registry and then creates a GitHub Release for its tag with the changelog section as notes. ## Partial-failure recovery diff --git a/docs/package.json b/docs/package.json index 6d9bc741..f7626196 100644 --- a/docs/package.json +++ b/docs/package.json @@ -6,6 +6,7 @@ "generate:python": "UV_CACHE_DIR=../.uv-cache uv run --project ../python --group docs python scripts/generate_python_reference.py", "generate:legacy": "UV_CACHE_DIR=../.uv-cache uv run --project ../python --group docs python scripts/port_legacy_docs.py generate", "check:legacy-snapshots": "UV_CACHE_DIR=../.uv-cache uv run --project ../python --group docs python scripts/port_legacy_docs.py check", + "check:release-snapshots": "node scripts/check_release_snapshots.mjs", "check:typescript-api": "node scripts/check_typescript_api_docs.mjs", "check:typescript-api-rendering": "node scripts/check_typescript_api_rendering.mjs", "check:legacy-contract": "node scripts/check_legacy_docs.mjs", diff --git a/docs/scripts/check_release_snapshots.mjs b/docs/scripts/check_release_snapshots.mjs new file mode 100644 index 00000000..dd666cd4 --- /dev/null +++ b/docs/scripts/check_release_snapshots.mjs @@ -0,0 +1,97 @@ +#!/usr/bin/env node + +// Every released version must be reachable from the docs site: the current +// package version is served live (lastVersion: "current"), and every earlier +// release must have a frozen snapshot in the version dropdown. That snapshot is +// recorded either in docs/versions.json (Docusaurus-era releases, cut with +// `docusaurus docs:version`) or in docs/legacy/manifest.json (the pre-monorepo +// versions the legacy porter freezes). A release that ships without cutting its +// docs version leaves a gap — this guard fails so the gap is caught in CI +// rather than discovered by a reader. + +import { execFileSync } from "node:child_process"; +import { readFileSync } from "node:fs"; +import { join, resolve } from "node:path"; +import { fileURLToPath } from "node:url"; + +const docsRoot = resolve(fileURLToPath(new URL("..", import.meta.url))); + +function currentVersion() { + const pyproject = readFileSync( + join(docsRoot, "..", "python", "pyproject.toml"), + "utf8", + ); + const match = pyproject.match(/^version = "([^"]+)"$/m); + if (!match) throw new Error("Could not read the Python package version"); + return match[1]; +} + +function snapshottedVersions() { + const versions = new Set( + JSON.parse(readFileSync(join(docsRoot, "versions.json"), "utf8")), + ); + const manifest = JSON.parse( + readFileSync(join(docsRoot, "legacy", "manifest.json"), "utf8"), + ); + for (const entry of manifest.versions) versions.add(entry.version); + return versions; +} + +// Python and TypeScript are released together under the same version number, so +// the `python/v*` tags are the authoritative list of released versions. Plain +// `v*` tags belong to the pre-monorepo 1.x/2.0 line and are covered by the +// legacy manifest instead. +function releasedVersions() { + let output; + try { + output = execFileSync("git", ["tag", "--list", "python/v*"], { + cwd: docsRoot, + encoding: "utf8", + }); + } catch (error) { + console.warn( + `Could not enumerate release tags (${error.message}); skipping the ` + + "released-snapshot guard. This should only happen outside CI, where " + + "docs.yml checks out with fetch-depth: 0.", + ); + return null; + } + return [ + ...new Set( + output + .split("\n") + .map((line) => line.trim()) + .filter(Boolean) + .map((tag) => tag.replace(/^python\/v/, "")), + ), + ]; +} + +const current = currentVersion(); +const released = releasedVersions(); + +if (released === null) { + process.exit(0); +} + +const snapshotted = snapshottedVersions(); +const missing = released + .filter((version) => version !== current) + .filter((version) => !snapshotted.has(version)) + .sort(); + +if (missing.length > 0) { + console.error( + `Released version(s) without a frozen docs snapshot: ${missing.join(", ")}.\n` + + "Freeze each one with `docusaurus docs:version ` (see RELEASING.md) " + + "so it appears in the version dropdown, or confirm it belongs in the legacy " + + "manifest.", + ); + process.exitCode = 1; +} else { + const checked = released.filter((version) => version !== current).length; + console.log( + `Every released version has a docs snapshot ` + + `(${checked} checked; ${current} is the live current version).`, + ); +} diff --git a/docs/versioned_docs/version-2.1.0/contributing.mdx b/docs/versioned_docs/version-2.1.0/contributing.mdx new file mode 100644 index 00000000..80d270aa --- /dev/null +++ b/docs/versioned_docs/version-2.1.0/contributing.mdx @@ -0,0 +1,79 @@ +--- +sidebar_position: 5 +--- + +# Contributing + +`slackblocks` is a monorepo containing two handwritten implementations and one shared conformance contract. A feature is complete when its wire output and validation category agree in Python and TypeScript. + +## Repository layout + +- `spec/` contains the normative fixtures, validation cases, limits, and principles. +- `python/` contains the Python package and its tests. +- `typescript/` contains the ESM TypeScript package and its tests. +- `docs/` contains this Docusaurus site and executable examples. + +## Set up the workspace + +Python development uses [uv](https://docs.astral.sh/uv/): + +```bash +cd python +uv sync --all-groups +``` + +JavaScript development uses the pnpm workspace from the repository root: + +```bash +pnpm install --frozen-lockfile +``` + +## Run the checks + +From `python/`: + +```bash +uv run pytest test/unit test/conformance test/docs +uv run ruff check slackblocks test +uv run mypy slackblocks +uv build --clear +uv run twine check --strict dist/* +``` + +From the repository root: + +```bash +pnpm --filter @nicklambourne/slackblocks typecheck +pnpm --filter @nicklambourne/slackblocks test +pnpm --filter @nicklambourne/slackblocks check:package +pnpm --filter @slackblocks/docs build +``` + +The Python and TypeScript conformance suites both exercise every ID in `spec/manifest.json`. A checked-in `conformance/skiplist.txt` may document an intentional language gap, but unknown failures and stale skips fail the suite. + +## Add or change a Block Kit feature + +1. Add or update canonical JSON in `spec/fixtures/valid/`, register it in `spec/manifest.json`, and link the exact official Slack reference used to validate it. +2. Map every new JSON-producing capability to at least one valid fixture in `spec/coverage.json`. +3. Add invalid behavior to `spec/fixtures/invalid/manifest.json` when the feature introduces a validation rule. Every scalar leaf in `spec/limits.json` must have a matching invalid case. +4. Update `spec/limits.json` for shared scalar constraints. +5. Implement the feature idiomatically in both packages, or record a reason in the affected skip list. +6. Add language-native tests and update the relevant guide or executable example. + +When introducing a cross-language API, serialized JSON and validation outcomes are shared; public naming and construction style are language-native. + +## Documentation + +Run the local site from the repository root: + +```bash +pnpm --filter @slackblocks/docs start +``` + +Narrative pages live in `docs/docs/`. Python and TypeScript API pages are generated during every docs build. Reusable examples live one-per-file under `docs/examples/python/` and `docs/examples/typescript/`; tests execute them and compare their output with `docs/examples/section_hello.json`. + +Use `LanguageContent` with `Python` and `TypeScript` children for language-specific prose or examples. The site-level selector controls which child is shown. + +## Pull requests + +Keep changes scoped, add a regression test for bug fixes, and include fixture changes whenever wire behavior changes. All local checks relevant to the changed package should pass before review. diff --git a/docs/versioned_docs/version-2.1.0/index.mdx b/docs/versioned_docs/version-2.1.0/index.mdx new file mode 100644 index 00000000..13fc96f3 --- /dev/null +++ b/docs/versioned_docs/version-2.1.0/index.mdx @@ -0,0 +1,135 @@ +--- +sidebar_label: Welcome +sidebar_position: 1 +--- + +import LanguageContent, { Python, TypeScript } from '@site/src/components/LanguageContent'; + +# Welcome to `slackblocks`! + +

+ slackblocks logo +

+ +`slackblocks` builds Slack messages with the [Block Kit API](https://api.slack.com/block-kit) in Python and TypeScript — without writing JSON by hand. + +It exists because Block Kit JSON is verbose, easy to get subtly wrong, and unpleasant to maintain in source control. `slackblocks` gives you: + +- **Typed, idiomatic APIs** for Python and TypeScript. +- **Validation as you build** — character limits, required fields, mutually-exclusive options, and element-type restrictions are enforced at construction time, so you find out *before* hitting Slack's API. +- **Drop-in compatibility** with the official Slack SDKs and their plain JSON payloads. +- **Zero runtime dependencies.** + +## Quick Start + +Ready to build your first message? The [Quick Start guide](quick-start) takes you from installation to a validated Slack payload using the language selected in the top navigation. + +## Components + +The [Slack Block Kit API](https://api.slack.com/block-kit) defines several resource types (all defined in JSON) that work together to build block-based messages. + + + + +The Python package mirrors that hierarchy with classes. + +### Objects + +[Objects](reference/python/objects) (e.g. [`Text`](reference/python/objects#text), [`Option`](reference/python/objects#option), [`Confirm`](reference/python/objects#confirm)) are the lowest-level primitives — small composable pieces that populate [Elements](reference/python/elements) and [Blocks](reference/python/blocks). + +For convenience, [`PlainText`](reference/python/objects#plaintext) and [`Markdown`](reference/python/objects#markdown) are thin subclasses of `Text` that you can use anywhere a `Text` is expected — `PlainText("Hi", emoji=True)` reads more naturally than `Text("Hi", type_=TextType.PLAINTEXT, emoji=True)`. + +### Elements + +[Elements](reference/python/elements) are typically interactive UI controls that go *inside* blocks. The [`CheckboxGroup`](reference/python/elements#checkboxgroup) element, for instance, takes one or more [`Option`](reference/python/objects#option) items and presents a checkbox menu. + +### Blocks + +[Blocks](reference/python/blocks) are the core visual unit of a message. Different block classes produce different UI: + +- [`SectionBlock`](reference/python/blocks#sectionblock) — a chunk of markdown text, optionally with an accessory element. +- [`HeaderBlock`](reference/python/blocks#headerblock) — a large bold title. +- [`DividerBlock`](reference/python/blocks#dividerblock) — a visual separator (like an HTML `
`). +- [`MarkdownBlock`](reference/python/blocks#markdownblock) — GitHub-flavored Markdown (Slack 2024+; richer formatting than `mrkdwn`). +- [`RichTextBlock`](reference/python/blocks#richtextblock) — formatted text with inline styling, lists, code blocks, and quotes. +- [`ActionsBlock`](reference/python/blocks#actionsblock) — a row of interactive elements like buttons or menus. +- [`AlertBlock`](reference/python/blocks#alertblock) — a severity-labelled notice for a modal. +- [`CardBlock`](reference/python/blocks#cardblock) and [`CarouselBlock`](reference/python/blocks#carouselblock) — compact linked content, individually or in a scrolling collection. +- [`ContainerBlock`](reference/python/blocks#containerblock) — a titled group of related child blocks. +- [`ContextActionsBlock`](reference/python/blocks#contextactionsblock) — feedback and icon controls beside contextual content. +- [`DataTableBlock`](reference/python/blocks#datatableblock) and [`DataVisualizationBlock`](reference/python/blocks#datavisualizationblock) — structured data as a table or chart. +- [`PlanBlock`](reference/python/blocks#planblock) and [`TaskCardBlock`](reference/python/blocks#taskcardblock) — plans, task state, rich output, and sources. +- [`VideoBlock`](reference/python/blocks#videoblock) — embed a video from a Slack-supported provider. +- [`ImageBlock`](reference/python/blocks#imageblock), [`ContextBlock`](reference/python/blocks#contextblock), [`InputBlock`](reference/python/blocks#inputblock), [`FileBlock`](reference/python/blocks#fileblock), [`TableBlock`](reference/python/blocks#tableblock). + +See [Using Blocks](usage/using_blocks) for examples of all block types side-by-side with their JSON output and Slack rendering. + +### Messages + +[Messages](reference/python/messages) are a convenience wrapper around blocks that can be unpacked directly into the Slack SDK's `chat_postMessage` (and friends). + +- [`Message`](reference/python/messages#message) — a normal channel message. +- [`WebhookMessage`](reference/python/messages#webhookmessage) — for incoming webhooks. +- [`MessageResponse`](reference/python/messages#messageresponse) — replies to slash commands and interactions. + +### Views + +[Views](reference/python/views) are an alternative usage of blocks that build custom UI surfaces in Slack — modal dialogs and the App Home tab — typically used by interactive Slack apps. + +### Utilities + +- [`block_kit_builder_url(payload, team_id=None)`](reference/python/builder#block_kit_builder_url) — turn any block, list of blocks, message, or view into a [Block Kit Builder](https://app.slack.com/block-kit-builder) URL for browser-based preview. +- [`Block.from_dict(data)`](reference/python/blocks#block) — parse a Slack-shaped block payload back into a `slackblocks` object. Per-class `from_dict` parsers are also available on every composition object. + + + + +The TypeScript package exposes data-first factories that return typed, Slack-shaped objects. + +### Composition objects + +Factories such as [`plainText`](reference/typescript/objects#plaintext), [`mrkdwn`](reference/typescript/objects#mrkdwn), and [`option`](reference/typescript/objects#option) create the small values used throughout Block Kit payloads. + +### Elements + +Interactive controls are built with factories such as [`button`](reference/typescript/elements#button), [`checkboxes`](reference/typescript/elements#checkboxes), [`staticSelect`](reference/typescript/elements#staticselect), and [`datePicker`](reference/typescript/elements#datepicker). + +### Blocks + +Every block factory follows the same `Block` naming pattern. Alongside the familiar [`sectionBlock`](reference/typescript/blocks#sectionblock), [`actionsBlock`](reference/typescript/blocks#actionsblock), and [`videoBlock`](reference/typescript/blocks#videoblock), the API includes [`alertBlock`](reference/typescript/blocks#alertblock), [`cardBlock`](reference/typescript/blocks#cardblock), [`carouselBlock`](reference/typescript/blocks#carouselblock), [`containerBlock`](reference/typescript/blocks#containerblock), [`contextActionsBlock`](reference/typescript/blocks#contextactionsblock), [`dataTableBlock`](reference/typescript/blocks#datatableblock), [`dataVisualizationBlock`](reference/typescript/blocks#datavisualizationblock), [`planBlock`](reference/typescript/blocks#planblock), and [`taskCardBlock`](reference/typescript/blocks#taskcardblock). + +### Messages and views + +Use [`message`](reference/typescript/messages#message), [`webhookMessage`](reference/typescript/messages#webhookmessage), and [`messageResponse`](reference/typescript/messages#messageresponse) for message payloads. Use [`modal`](reference/typescript/views#modal) and [`homeTab`](reference/typescript/views#hometab) for Slack views. + +### Utilities + +- [`blockKitBuilderUrl`](reference/typescript/utilities#blockkitbuilderurl) creates a browser preview URL. +- [`validate`](reference/typescript/utilities#validate) and [`assertValid`](reference/typescript/utilities#assertvalid) validate existing Slack-shaped data. + + + + +## Guides + + + + +- [Installation](usage/installation) +- [Using Blocks](usage/using_blocks) +- [Sending Messages](usage/sending_messages) +- [Recipe Book](usage/cookbook) — complete end-to-end recipes for common message patterns. +- [Troubleshooting & FAQ](usage/troubleshooting) +- [Migrating from 1.x to 2.x](usage/migration) — upgrade guide for `1.x` users. +- [Contributing](contributing) — developing and contributing to `slackblocks` itself. + + + + +- [Installation](usage/installation) +- [Sending Messages](usage/sending_messages) +- [Recipe Book](usage/cookbook) — complete end-to-end recipes for common message patterns. +- [Contributing](contributing) — developing and contributing to `slackblocks` itself. + + + diff --git a/docs/versioned_docs/version-2.1.0/quick-start.mdx b/docs/versioned_docs/version-2.1.0/quick-start.mdx new file mode 100644 index 00000000..767ea5aa --- /dev/null +++ b/docs/versioned_docs/version-2.1.0/quick-start.mdx @@ -0,0 +1,73 @@ +--- +sidebar_label: Quick Start +sidebar_position: 2 +--- + +import LanguageContent, { Python, TypeScript } from '@site/src/components/LanguageContent'; + +# Quick Start + +Install `slackblocks` and build your first valid Block Kit message. The language selector in the top navigation controls the instructions and examples on this page. + + + + +## Install the package + +Python 3.10 or newer is required. + +```bash +pip install slackblocks +``` + +## Build a message + +```python +from slackblocks import Message, SectionBlock + +message = Message( + channel="#general", + text="Hello from slackblocks!", + blocks=[SectionBlock("Hello, world!")], +) + +print(message.json()) +``` + +`Message` validates the payload as it is constructed and renders it as Slack-compatible JSON. The `text` value is the plain-text fallback Slack uses for notifications and accessibility. + + + + +## Install the package + +Node.js 20.19 or newer is required. The package is ESM-only. + +```bash +pnpm add @nicklambourne/slackblocks +``` + +## Build a message + +```ts +import { message, sectionBlock } from "@nicklambourne/slackblocks"; + +const payload = message({ + channel: "C0123456", + text: "Hello from slackblocks!", + blocks: [sectionBlock({ text: "Hello, world!" })], +}); + +console.log(JSON.stringify(payload, null, 2)); +``` + +Each factory validates its input and returns a plain Slack-compatible object. Factory inputs use camelCase; the resulting payload uses the snake_case keys expected by Slack. + + + + +## Where to go next + +`slackblocks` constructs payloads but does not send HTTP requests. Continue with [Sending Messages](usage/sending_messages) to connect the payload to Slack, or explore [Using Blocks](usage/using_blocks) to build richer layouts. + +For package-manager alternatives and environment details, see [Installation](usage/installation). diff --git a/docs/versioned_docs/version-2.1.0/reference/_category_.json b/docs/versioned_docs/version-2.1.0/reference/_category_.json new file mode 100644 index 00000000..f5f04783 --- /dev/null +++ b/docs/versioned_docs/version-2.1.0/reference/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "API Reference", + "position": 4 +} diff --git a/docs/versioned_docs/version-2.1.0/reference/index.mdx b/docs/versioned_docs/version-2.1.0/reference/index.mdx new file mode 100644 index 00000000..c10aa5ee --- /dev/null +++ b/docs/versioned_docs/version-2.1.0/reference/index.mdx @@ -0,0 +1,16 @@ +import LanguageContent, { Python, TypeScript } from '@site/src/components/LanguageContent'; + +# API reference + + + + +Looking for the exact class or constructor argument to use? The [Python API reference](/reference/python) covers every public class, function, signature, and docstring in the package. Start with the category that matches the payload you are building, then follow the linked types as you go. + + + + +Need the precise shape of a factory input or returned payload? The [TypeScript API reference](/reference/typescript) brings together every exported factory, interface, type, and validation error. Use it when you know what you want to build and need the exact TypeScript contract. + + + diff --git a/docs/versioned_docs/version-2.1.0/reference/python/attachments.mdx b/docs/versioned_docs/version-2.1.0/reference/python/attachments.mdx new file mode 100644 index 00000000..a3e12f1b --- /dev/null +++ b/docs/versioned_docs/version-2.1.0/reference/python/attachments.mdx @@ -0,0 +1,92 @@ +# Attachments + +## Attachment + +**Class** + +```python +Attachment(blocks: 'Block | list[Block] | None' = None, color: 'str | Color | None' = None, fields: 'Field | list[Field] | None' = None, fallback: 'str | None' = None) +``` + +
+ +Lower priority content can be attached to messages using Attachments. +This is content that doesn't necessarily need to be seen to appreciate +the intent of the message, but perhaps adds further context or additional information. + +See [https://api.slack.com/reference/messaging/attachments](https://api.slack.com/reference/messaging/attachments). + +N.B: `fields` is a deprecated field, included only for legacy purposes. Other legacy +fields, e.g. `author_name` are deliberately omitted as they were never implemented in +`slackblocks`. + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `blocks` | `Block \| list[Block] \| None` | an array of Blocks that define the content of the attachment. | +| `color` | `str \| Color \| None` | the color (in hex format, e.g. #ffffff) of the vertical bar to the left of the
attachment content. Consider using the `Color` enum from this module. | +| `fields` | `Field \| list[Field] \| None` | a list of `Field` objects to be included in what's rendered in the attachment. | +| `fallback` | `str \| None` | A plain text summary of the attachment used in clients that don't show
formatted text (eg. IRC, mobile notifications). | + +

Errors

+ +| Error | When | +| --- | --- | +| `InvalidUsageError` | if the `color` code provided is invalid. | + +
+ +## Color + +**Class** + +```python +Color(*values) +``` + +
+ +Color is a utility class for use with the Slack secondary attachments API. + +Pass these to the `color` argument of +[`Attachment`](#attachment). + +| Value | Preview | +| --- | --- | +| `Color.GOOD` | ![good](https://readme-swatches.vercel.app/4CAF50?style=round) | +| `Color.WARNING` | ![warning](https://readme-swatches.vercel.app/FFEB3B?style=round) | +| `Color.DANGER` | ![danger](https://readme-swatches.vercel.app/F44336?style=round) | +| `Color.RED` | ![red](https://readme-swatches.vercel.app/ff0000?style=round) | +| `Color.BLUE` | ![blue](https://readme-swatches.vercel.app/0000ff?style=round) | +| `Color.YELLOW` | ![yellow](https://readme-swatches.vercel.app/ffff00?style=round) | +| `Color.GREEN` | ![green](https://readme-swatches.vercel.app/00ff00?style=round) | +| `Color.ORANGE` | ![orange](https://readme-swatches.vercel.app/ff8800?style=round) | +| `Color.PURPLE` | ![purple](https://readme-swatches.vercel.app/8800ff?style=round) | +| `Color.BLACK` | ![black](https://readme-swatches.vercel.app/000000?style=round) | + +
+ +## Field + +**Class** + +```python +Field(title: 'str | None' = None, value: 'str | None' = None, short: 'bool | None' = False) +``` + +
+ +Field text objects for use with Slack's secondary attachment API. + +See [https://api.slack.com/reference/messaging/attachments#fields](https://api.slack.com/reference/messaging/attachments#fields). + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `title` | `str \| None` | text shown as a bold heading on the field. | +| `value` | `str \| None` | text (`mrkdwn` or `plaintext`) representing the value of the field. | +| `short` | `bool \| None` | whether the contents of the field is short enough to be presented in
multipe columns. | + +
diff --git a/docs/versioned_docs/version-2.1.0/reference/python/blocks.mdx b/docs/versioned_docs/version-2.1.0/reference/python/blocks.mdx new file mode 100644 index 00000000..9067eb75 --- /dev/null +++ b/docs/versioned_docs/version-2.1.0/reference/python/blocks.mdx @@ -0,0 +1,1122 @@ +# Blocks + +## ActionsBlock + +**Class** + +```python +ActionsBlock(elements: 'list[Element] | None' = None, block_id: 'str | None' = None) -> 'None' +``` + +
+ +A `Block` that is used to hold interactive elements (normally for users to interface with). + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `elements` | `list[Element] \| None` | a list of [Elements](/reference/python/elements)
(up to a maximum of 25). | +| `block_id` | `str \| None` | you can use this field to provide a deterministic identifier for the block. | + +

Errors

+ +| Error | When | +| --- | --- | +| `InvalidUsageError` | if any of the items in `elements` are invalid. | + +
+ +### from_dict + +```python +from_dict(data: 'dict[str, Any]') -> 'ActionsBlock' +``` + +
+ +Parse a Slack ``actions`` block payload. + +Currently raises ``NotImplementedError`` because round-tripping +depends on parsing nested elements; ``Element.from_dict`` will land +in Phase 7.4b. + +
+ +## AlertBlock + +**Class** + +```python +AlertBlock(text: 'TextLike', level: 'AlertLevel' = 'default', block_id: 'str | None' = None) -> 'None' +``` + +
+ +A severity-labelled alert displayed in a modal. + +See: [https://docs.slack.dev/reference/block-kit/blocks/alert-block](https://docs.slack.dev/reference/block-kit/blocks/alert-block). + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `text` | `TextLike` | the text to display in the alert (max 200 chars). Can be a
string or `Text` object. | +| `level` | `AlertLevel` | the severity of the alert, one of `default`, `info`,
`warning`, `error`, or `success`. | +| `block_id` | `str \| None` | you can use this field to provide a deterministic identifier for the block. | + +

Errors

+ +| Error | When | +| --- | --- | +| `InvalidUsageError` | if any of the provided arguments fail validation. | + +
+ +### from_dict + +```python +from_dict(data: 'dict[str, Any]') -> 'AlertBlock' +``` + +
+ +Parse a Slack block payload back into the appropriate ``Block`` subclass. + +Reads ``data["type"]`` and dispatches to the matching subclass's +``from_dict``. + +Block types that currently round-trip: ``AlertBlock``, +``ContextBlock`` (text elements only), ``DividerBlock``, +``FileBlock``, ``HeaderBlock``, ``ImageBlock``, ``MarkdownBlock``, +``SectionBlock`` (without an accessory), and ``VideoBlock``. + +

Errors

+ +| Error | When | +| --- | --- | +| `MissingRequiredError` | if ``data["type"]`` is absent. | +| `TypeMismatchError` | if ``data["type"]`` is not a recognised
block type. | +| `NotImplementedError` | when the block type is recognised but its
round-trip parser depends on a part of the API that is not
yet implemented (currently: ``RichTextBlock`` and any block
containing nested elements, cards, tasks, charts, or
rich text -- ``ActionsBlock``, ``InputBlock``,
``TableBlock``, ``CardBlock``, ``CarouselBlock``,
``ContainerBlock``, ``ContextActionsBlock``,
``DataTableBlock``, ``DataVisualizationBlock``,
``TaskCardBlock``, and ``PlanBlock`` -- see Phase 7.4b
and 7.4c). | + +
+ +## Block + +**Class** + +```python +Block(type_: 'BlockType', block_id: 'str | None' = None) -> 'None' +``` + +
+ +Basis block containing attributes and behaviour common to all blocks. +N.B: Block is an abstract class and cannot be sent directly. + +
+ +### from_dict + +```python +from_dict(data: 'dict[str, Any]') -> 'Block' +``` + +
+ +Parse a Slack block payload back into the appropriate ``Block`` subclass. + +Reads ``data["type"]`` and dispatches to the matching subclass's +``from_dict``. + +Block types that currently round-trip: ``AlertBlock``, +``ContextBlock`` (text elements only), ``DividerBlock``, +``FileBlock``, ``HeaderBlock``, ``ImageBlock``, ``MarkdownBlock``, +``SectionBlock`` (without an accessory), and ``VideoBlock``. + +

Errors

+ +| Error | When | +| --- | --- | +| `MissingRequiredError` | if ``data["type"]`` is absent. | +| `TypeMismatchError` | if ``data["type"]`` is not a recognised
block type. | +| `NotImplementedError` | when the block type is recognised but its
round-trip parser depends on a part of the API that is not
yet implemented (currently: ``RichTextBlock`` and any block
containing nested elements, cards, tasks, charts, or
rich text -- ``ActionsBlock``, ``InputBlock``,
``TableBlock``, ``CardBlock``, ``CarouselBlock``,
``ContainerBlock``, ``ContextActionsBlock``,
``DataTableBlock``, ``DataVisualizationBlock``,
``TaskCardBlock``, and ``PlanBlock`` -- see Phase 7.4b
and 7.4c). | + +
+ +## CardBlock + +**Class** + +```python +CardBlock(hero_image: 'Image | None' = None, icon: 'Image | None' = None, title: 'TextLike | None' = None, subtitle: 'TextLike | None' = None, body: 'TextLike | None' = None, actions: 'Button | list[Button] | None' = None, slack_icon: 'SlackIcon | None' = None, subtext: 'TextLike | None' = None, block_id: 'str | None' = None) -> 'None' +``` + +
+ +A compact card with text, images, and up to three actions. Cards can +stand alone or be grouped in a +[`CarouselBlock`](/reference/python/blocks#carouselblock). + +At least one of `hero_image`, `title`, `actions`, or `body` must be +provided. + +See: [https://docs.slack.dev/reference/block-kit/blocks/card-block](https://docs.slack.dev/reference/block-kit/blocks/card-block). + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `hero_image` | `Image \| None` | an `Image` element displayed prominently at the top
of the card. | +| `icon` | `Image \| None` | an `Image` element displayed as the card's icon. Cannot be
combined with `slack_icon`. | +| `title` | `TextLike \| None` | the card's title (max 150 chars). Can be a string or `Text` object. | +| `subtitle` | `TextLike \| None` | the card's subtitle (max 150 chars). Can be a string or `Text` object. | +| `body` | `TextLike \| None` | the card's body text (max 200 chars). Can be a string or `Text` object. | +| `actions` | `Button \| list[Button] \| None` | up to three `Button` elements presented as card actions. | +| `slack_icon` | `SlackIcon \| None` | a `SlackIcon` naming a Slack-provided icon. Cannot be
combined with `icon`. | +| `subtext` | `TextLike \| None` | additional text displayed at the bottom of the card
(max 200 chars). Can be a string or `Text` object. | +| `block_id` | `str \| None` | you can use this field to provide a deterministic identifier for the block. | + +

Errors

+ +| Error | When | +| --- | --- | +| `InvalidUsageError` | if any of the provided arguments fail validation,
or both `icon` and `slack_icon` are provided. | + +
+ +### from_dict + +```python +from_dict(data: 'dict[str, Any]') -> 'CardBlock' +``` + +
+ +Parse a Slack block payload back into the appropriate ``Block`` subclass. + +Reads ``data["type"]`` and dispatches to the matching subclass's +``from_dict``. + +Block types that currently round-trip: ``AlertBlock``, +``ContextBlock`` (text elements only), ``DividerBlock``, +``FileBlock``, ``HeaderBlock``, ``ImageBlock``, ``MarkdownBlock``, +``SectionBlock`` (without an accessory), and ``VideoBlock``. + +

Errors

+ +| Error | When | +| --- | --- | +| `MissingRequiredError` | if ``data["type"]`` is absent. | +| `TypeMismatchError` | if ``data["type"]`` is not a recognised
block type. | +| `NotImplementedError` | when the block type is recognised but its
round-trip parser depends on a part of the API that is not
yet implemented (currently: ``RichTextBlock`` and any block
containing nested elements, cards, tasks, charts, or
rich text -- ``ActionsBlock``, ``InputBlock``,
``TableBlock``, ``CardBlock``, ``CarouselBlock``,
``ContainerBlock``, ``ContextActionsBlock``,
``DataTableBlock``, ``DataVisualizationBlock``,
``TaskCardBlock``, and ``PlanBlock`` -- see Phase 7.4b
and 7.4c). | + +
+ +## CarouselBlock + +**Class** + +```python +CarouselBlock(elements: 'list[CardBlock]', block_id: 'str | None' = None) -> 'None' +``` + +
+ +A horizontally scrolling group of between 1 and 10 +[`CardBlocks`](/reference/python/blocks#cardblock). + +See: [https://docs.slack.dev/reference/block-kit/blocks/carousel-block](https://docs.slack.dev/reference/block-kit/blocks/carousel-block). + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `elements` | `list[CardBlock]` | a list of between 1 and 10 `CardBlock` objects. | +| `block_id` | `str \| None` | you can use this field to provide a deterministic identifier for the block. | + +

Errors

+ +| Error | When | +| --- | --- | +| `InvalidUsageError` | if any of the items in `elements` are not
`CardBlock` objects, or the number of cards is invalid. | + +
+ +### from_dict + +```python +from_dict(data: 'dict[str, Any]') -> 'CarouselBlock' +``` + +
+ +Parse a Slack block payload back into the appropriate ``Block`` subclass. + +Reads ``data["type"]`` and dispatches to the matching subclass's +``from_dict``. + +Block types that currently round-trip: ``AlertBlock``, +``ContextBlock`` (text elements only), ``DividerBlock``, +``FileBlock``, ``HeaderBlock``, ``ImageBlock``, ``MarkdownBlock``, +``SectionBlock`` (without an accessory), and ``VideoBlock``. + +

Errors

+ +| Error | When | +| --- | --- | +| `MissingRequiredError` | if ``data["type"]`` is absent. | +| `TypeMismatchError` | if ``data["type"]`` is not a recognised
block type. | +| `NotImplementedError` | when the block type is recognised but its
round-trip parser depends on a part of the API that is not
yet implemented (currently: ``RichTextBlock`` and any block
containing nested elements, cards, tasks, charts, or
rich text -- ``ActionsBlock``, ``InputBlock``,
``TableBlock``, ``CardBlock``, ``CarouselBlock``,
``ContainerBlock``, ``ContextActionsBlock``,
``DataTableBlock``, ``DataVisualizationBlock``,
``TaskCardBlock``, and ``PlanBlock`` -- see Phase 7.4b
and 7.4c). | + +
+ +## ContainerBlock + +**Class** + +```python +ContainerBlock(child_blocks: 'list[Block]', title: 'TextLike | None' = None, rich_text_title: 'RichTextBlock | None' = None, subtitle: 'TextLike | None' = None, width: 'ContainerWidth' = 'standard', icon: 'Image | None' = None, is_collapsible: 'bool' = False, default_collapsed: 'bool' = False, has_header_divider: 'bool' = False, block_id: 'str | None' = None) -> 'None' +``` + +
+ +A titled container grouping up to ten supported child blocks. + +One of `title` or `rich_text_title` must be provided. + +See: [https://docs.slack.dev/reference/block-kit/blocks/container-block](https://docs.slack.dev/reference/block-kit/blocks/container-block). + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `child_blocks` | `list[Block]` | a list of between 1 and 10 blocks to display inside
the container. Supported child block types are actions, context,
divider, file, header, image, input, rich text, section, table,
and video blocks. | +| `title` | `TextLike \| None` | the container's title (plaintext only; max 150 chars). | +| `rich_text_title` | `RichTextBlock \| None` | a `RichTextBlock` used as the container's title in
place of `title`. | +| `subtitle` | `TextLike \| None` | the container's subtitle (max 150 chars). Can be a string
or `Text` object. | +| `width` | `ContainerWidth` | the width of the container, one of `narrow`, `standard`,
`wide`, or `full`. | +| `icon` | `Image \| None` | an `Image` element displayed alongside the title. | +| `is_collapsible` | `bool` | whether the container can be collapsed by the user. | +| `default_collapsed` | `bool` | whether the container is initially collapsed
(requires `is_collapsible=True`). | +| `has_header_divider` | `bool` | whether a divider is shown under the header
(only valid on non-collapsible containers). | +| `block_id` | `str \| None` | you can use this field to provide a deterministic identifier for the block. | + +

Errors

+ +| Error | When | +| --- | --- | +| `InvalidUsageError` | if any of the provided arguments fail validation,
or an unsupported child block type is provided. | + +
+ +### from_dict + +```python +from_dict(data: 'dict[str, Any]') -> 'ContainerBlock' +``` + +
+ +Parse a Slack block payload back into the appropriate ``Block`` subclass. + +Reads ``data["type"]`` and dispatches to the matching subclass's +``from_dict``. + +Block types that currently round-trip: ``AlertBlock``, +``ContextBlock`` (text elements only), ``DividerBlock``, +``FileBlock``, ``HeaderBlock``, ``ImageBlock``, ``MarkdownBlock``, +``SectionBlock`` (without an accessory), and ``VideoBlock``. + +

Errors

+ +| Error | When | +| --- | --- | +| `MissingRequiredError` | if ``data["type"]`` is absent. | +| `TypeMismatchError` | if ``data["type"]`` is not a recognised
block type. | +| `NotImplementedError` | when the block type is recognised but its
round-trip parser depends on a part of the API that is not
yet implemented (currently: ``RichTextBlock`` and any block
containing nested elements, cards, tasks, charts, or
rich text -- ``ActionsBlock``, ``InputBlock``,
``TableBlock``, ``CardBlock``, ``CarouselBlock``,
``ContainerBlock``, ``ContextActionsBlock``,
``DataTableBlock``, ``DataVisualizationBlock``,
``TaskCardBlock``, and ``PlanBlock`` -- see Phase 7.4b
and 7.4c). | + +
+ +## ContextActionsBlock + +**Class** + +```python +ContextActionsBlock(elements: 'list[FeedbackButtons | IconButton]', block_id: 'str | None' = None) -> 'None' +``` + +
+ +Up to five feedback or icon actions displayed as contextual controls. + +See: [https://docs.slack.dev/reference/block-kit/blocks/context-actions-block](https://docs.slack.dev/reference/block-kit/blocks/context-actions-block). + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `elements` | `list[FeedbackButtons \| IconButton]` | a list of between 1 and 5 `FeedbackButtons` or
`IconButton` elements. | +| `block_id` | `str \| None` | you can use this field to provide a deterministic identifier for the block. | + +

Errors

+ +| Error | When | +| --- | --- | +| `InvalidUsageError` | if any of the items in `elements` are invalid. | + +
+ +### from_dict + +```python +from_dict(data: 'dict[str, Any]') -> 'ContextActionsBlock' +``` + +
+ +Parse a Slack block payload back into the appropriate ``Block`` subclass. + +Reads ``data["type"]`` and dispatches to the matching subclass's +``from_dict``. + +Block types that currently round-trip: ``AlertBlock``, +``ContextBlock`` (text elements only), ``DividerBlock``, +``FileBlock``, ``HeaderBlock``, ``ImageBlock``, ``MarkdownBlock``, +``SectionBlock`` (without an accessory), and ``VideoBlock``. + +

Errors

+ +| Error | When | +| --- | --- | +| `MissingRequiredError` | if ``data["type"]`` is absent. | +| `TypeMismatchError` | if ``data["type"]`` is not a recognised
block type. | +| `NotImplementedError` | when the block type is recognised but its
round-trip parser depends on a part of the API that is not
yet implemented (currently: ``RichTextBlock`` and any block
containing nested elements, cards, tasks, charts, or
rich text -- ``ActionsBlock``, ``InputBlock``,
``TableBlock``, ``CardBlock``, ``CarouselBlock``,
``ContainerBlock``, ``ContextActionsBlock``,
``DataTableBlock``, ``DataVisualizationBlock``,
``TaskCardBlock``, and ``PlanBlock`` -- see Phase 7.4b
and 7.4c). | + +
+ +## ContextBlock + +**Class** + +```python +ContextBlock(elements: 'list[Element | CompositionObject] | None' = None, block_id: 'str | None' = None) -> 'None' +``` + +
+ +A `ContextBlock` displays contextul message info, including both images and text. + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `elements` | `list[Element \| CompositionObject] \| None` | a list of `Text` objects and `Image` elements. | +| `block_id` | `str \| None` | you can use this field to provide a deterministic identifier for the block. | + +

Errors

+ +| Error | When | +| --- | --- | +| `InvalidUsageError` | when items in `elements` are not `Text` or `Image` or exceed 10 items. | + +
+ +### from_dict + +```python +from_dict(data: 'dict[str, Any]') -> 'ContextBlock' +``` + +
+ +Parse a Slack ``context`` block payload. + +Text elements within the block are parsed back to ``Text``; image +elements raise ``NotImplementedError`` because ``Element.from_dict`` +has not yet shipped (Phase 7.4b). + +
+ +## DataTableBlock + +**Class** + +```python +DataTableBlock(rows: 'list[list[RawText | RawNumber | RichTextBlock]]', caption: 'str', page_size: 'int' = 5, row_header_column_index: 'int' = 0, block_id: 'str | None' = None) -> 'None' +``` + +
+ +A sortable data table containing raw text, raw numbers, or rich text. + +The first row is the header row; header cells cannot contain rich text. + +See: [https://docs.slack.dev/reference/block-kit/blocks/data-table-block](https://docs.slack.dev/reference/block-kit/blocks/data-table-block). + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `rows` | `list[list[RawText \| RawNumber \| RichTextBlock]]` | a list of between 2 and 201 rows (one header row plus up to
200 data rows), each a list of between 1 and 20 `RawText`,
`RawNumber`, or `RichTextBlock` cells. All rows must have the
same number of columns, and the combined cell text cannot
exceed 20,000 characters. | +| `caption` | `str` | a description of the table for accessibility purposes. | +| `page_size` | `int` | the number of rows displayed per page (between 1 and 100). | +| `row_header_column_index` | `int` | the (zero-based) index of the column to
treat as the row header. | +| `block_id` | `str \| None` | you can use this field to provide a deterministic identifier for the block. | + +

Errors

+ +| Error | When | +| --- | --- | +| `InvalidUsageError` | if any of the provided arguments fail validation. | + +
+ +### from_dict + +```python +from_dict(data: 'dict[str, Any]') -> 'DataTableBlock' +``` + +
+ +Parse a Slack block payload back into the appropriate ``Block`` subclass. + +Reads ``data["type"]`` and dispatches to the matching subclass's +``from_dict``. + +Block types that currently round-trip: ``AlertBlock``, +``ContextBlock`` (text elements only), ``DividerBlock``, +``FileBlock``, ``HeaderBlock``, ``ImageBlock``, ``MarkdownBlock``, +``SectionBlock`` (without an accessory), and ``VideoBlock``. + +

Errors

+ +| Error | When | +| --- | --- | +| `MissingRequiredError` | if ``data["type"]`` is absent. | +| `TypeMismatchError` | if ``data["type"]`` is not a recognised
block type. | +| `NotImplementedError` | when the block type is recognised but its
round-trip parser depends on a part of the API that is not
yet implemented (currently: ``RichTextBlock`` and any block
containing nested elements, cards, tasks, charts, or
rich text -- ``ActionsBlock``, ``InputBlock``,
``TableBlock``, ``CardBlock``, ``CarouselBlock``,
``ContainerBlock``, ``ContextActionsBlock``,
``DataTableBlock``, ``DataVisualizationBlock``,
``TaskCardBlock``, and ``PlanBlock`` -- see Phase 7.4b
and 7.4c). | + +
+ +## DataVisualizationBlock + +**Class** + +```python +DataVisualizationBlock(title: 'str', chart: 'Chart', block_id: 'str | None' = None) -> 'None' +``` + +
+ +A pie, bar, area, or line chart rendered by Slack. + +See: [https://docs.slack.dev/reference/block-kit/blocks/data-visualization-block](https://docs.slack.dev/reference/block-kit/blocks/data-visualization-block). + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `title` | `str` | the title displayed above the chart (max 50 chars). | +| `chart` | `Chart` | the chart to render, one of `PieChart`, `BarChart`,
`AreaChart`, or `LineChart`. | +| `block_id` | `str \| None` | you can use this field to provide a deterministic identifier for the block. | + +

Errors

+ +| Error | When | +| --- | --- | +| `InvalidUsageError` | if any of the provided arguments fail validation. | + +
+ +### from_dict + +```python +from_dict(data: 'dict[str, Any]') -> 'DataVisualizationBlock' +``` + +
+ +Parse a Slack block payload back into the appropriate ``Block`` subclass. + +Reads ``data["type"]`` and dispatches to the matching subclass's +``from_dict``. + +Block types that currently round-trip: ``AlertBlock``, +``ContextBlock`` (text elements only), ``DividerBlock``, +``FileBlock``, ``HeaderBlock``, ``ImageBlock``, ``MarkdownBlock``, +``SectionBlock`` (without an accessory), and ``VideoBlock``. + +

Errors

+ +| Error | When | +| --- | --- | +| `MissingRequiredError` | if ``data["type"]`` is absent. | +| `TypeMismatchError` | if ``data["type"]`` is not a recognised
block type. | +| `NotImplementedError` | when the block type is recognised but its
round-trip parser depends on a part of the API that is not
yet implemented (currently: ``RichTextBlock`` and any block
containing nested elements, cards, tasks, charts, or
rich text -- ``ActionsBlock``, ``InputBlock``,
``TableBlock``, ``CardBlock``, ``CarouselBlock``,
``ContainerBlock``, ``ContextActionsBlock``,
``DataTableBlock``, ``DataVisualizationBlock``,
``TaskCardBlock``, and ``PlanBlock`` -- see Phase 7.4b
and 7.4c). | + +
+ +## DividerBlock + +**Class** + +```python +DividerBlock(block_id: 'str | None' = None) -> 'None' +``` + +
+ +A content divider, like an `
` in HTML, to split up different blocks inside of +a message. + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `block_id` | `str \| None` | you can use this field to provide a deterministic identifier for the block. | + +
+ +### from_dict + +```python +from_dict(data: 'dict[str, Any]') -> 'DividerBlock' +``` + +
+ +Parse a Slack ``divider`` block payload. + +
+ +## FileBlock + +**Class** + +```python +FileBlock(external_id: 'str', block_id: 'str | None' = None, source: 'str' = 'remote') -> 'None' +``` + +
+ +Displays a remote file (e.g. a PDF). + +For details on how remote files are exposed to Slack, see +[https://api.slack.com/messaging/files#adding](https://api.slack.com/messaging/files#adding). + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `external_id` | `str` | the ID assigned to the remote file when it was added to Slack. | +| `block_id` | `str \| None` | you can use this field to provide a deterministic identifier for the block. | +| `source` | `str` | always "remote" as per the Slack API (may change in the future). | + +
+ +### from_dict + +```python +from_dict(data: 'dict[str, Any]') -> 'FileBlock' +``` + +
+ +Parse a Slack ``file`` block payload. + +
+ +## HeaderBlock + +**Class** + +```python +HeaderBlock(text: 'str | Text', block_id: 'str | None' = None) -> 'None' +``` + +
+ +A Header Block is a plain-text block that displays in a larger, bold font. + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `text` | `str \| Text` | the text that will be rendered as a heading. | +| `block_id` | `str \| None` | you can use this field to provide a deterministic identifier for the block. | + +
+ +### from_dict + +```python +from_dict(data: 'dict[str, Any]') -> 'HeaderBlock' +``` + +
+ +Parse a Slack ``header`` block payload. + +
+ +## ImageBlock + +**Class** + +```python +ImageBlock(image_url: 'str', alt_text: 'str | None' = ' ', title: 'Text | str | None' = None, block_id: 'str | None' = None) -> 'None' +``` + +
+ +An Image Block contains a single graphic, accessed by URL. + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `image_url` | `str` | the URL pointing to the image file you want to display. | +| `alt_text` | `str \| None` | alternative text for accessibility purposes and when the image fails to load. | +| `title` | `Text \| str \| None` | an optional text title to be presented with the image. | +| `block_id` | `str \| None` | you can use this field to provide a deterministic identifier for the block. | + +

Errors

+ +| Error | When | +| --- | --- | +| `InvalidUsageError` | when one or more of the provided args fails validation. | + +
+ +### from_dict + +```python +from_dict(data: 'dict[str, Any]') -> 'ImageBlock' +``` + +
+ +Parse a Slack ``image`` block payload. + +
+ +## InputBlock + +**Class** + +```python +InputBlock(label: 'TextLike', element: 'Element', dispatch_action: 'bool' = False, block_id: 'str | None' = None, hint: 'TextLike | None' = None, optional: 'bool' = False) -> 'None' +``` + +
+ +A block that collects information from users - it can hold a plain-text +input element, a checkbox element, a radio button element, a select +menu element, a multi-select menu element, or a datepicker. + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `label` | `TextLike` | the name which identifies the input field. | +| `element` | `Element` | an interactive [Element](/reference/python/elements)
(e.g. a text field). | +| `dispatch_action` | `bool` | whether the [Element](/reference/python/elements)
should trigger the sending of a `block_actions` payload. | +| `block_id` | `str \| None` | you can use this field to provide a deterministic identifier for the block. | +| `hint` | `TextLike \| None` | an optional additional guide on what input the user should provide. | +| `optional` | `bool` | whether this input field may be empty when the user submits e.g. the modal. | + +

Errors

+ +| Error | When | +| --- | --- | +| `InvalidUsageError` | when any of the provided arguments fail validation. | + +
+ +### from_dict + +```python +from_dict(data: 'dict[str, Any]') -> 'InputBlock' +``` + +
+ +Parse a Slack ``input`` block payload. + +Currently raises ``NotImplementedError`` because the nested +``element`` requires ``Element.from_dict``, which lands in Phase 7.4b. + +
+ +## MarkdownBlock + +**Class** + +```python +MarkdownBlock(text: 'str', block_id: 'str | None' = None) -> 'None' +``` + +
+ +Displays formatted Markdown text. Unlike the `mrkdwn` text style used in +[`SectionBlock`](/reference/python/blocks#sectionblock), +`MarkdownBlock` uses **GitHub-flavored Markdown** for richer formatting, +including features like tables and code blocks. Added to Slack in 2024 +for AI / agentic app outputs. + +See: [https://api.slack.com/reference/block-kit/blocks#markdown](https://api.slack.com/reference/block-kit/blocks#markdown). + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `text` | `str` | the Markdown-formatted text to display (1-12000 characters). | +| `block_id` | `str \| None` | you can use this field to provide a deterministic identifier
for the block. | + +

Errors

+ +| Error | When | +| --- | --- | +| `LengthError` | if `text` is empty or longer than 12000 characters. | + +
+ +### from_dict + +```python +from_dict(data: 'dict[str, Any]') -> 'MarkdownBlock' +``` + +
+ +Parse a Slack ``markdown`` block payload. + +
+ +## PlanBlock + +**Class** + +```python +PlanBlock(title: 'str', tasks: 'list[TaskCardBlock] | None' = None, block_id: 'str | None' = None) -> 'None' +``` + +
+ +A titled sequence of +[`TaskCardBlocks`](/reference/python/blocks#taskcardblock). + +See: [https://docs.slack.dev/reference/block-kit/blocks/plan-block](https://docs.slack.dev/reference/block-kit/blocks/plan-block). + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `title` | `str` | the title of the plan. | +| `tasks` | `list[TaskCardBlock] \| None` | a list of `TaskCardBlock` objects making up the plan. | +| `block_id` | `str \| None` | you can use this field to provide a deterministic identifier for the block. | + +

Errors

+ +| Error | When | +| --- | --- | +| `InvalidUsageError` | if any of the provided arguments fail validation. | + +
+ +### from_dict + +```python +from_dict(data: 'dict[str, Any]') -> 'PlanBlock' +``` + +
+ +Parse a Slack block payload back into the appropriate ``Block`` subclass. + +Reads ``data["type"]`` and dispatches to the matching subclass's +``from_dict``. + +Block types that currently round-trip: ``AlertBlock``, +``ContextBlock`` (text elements only), ``DividerBlock``, +``FileBlock``, ``HeaderBlock``, ``ImageBlock``, ``MarkdownBlock``, +``SectionBlock`` (without an accessory), and ``VideoBlock``. + +

Errors

+ +| Error | When | +| --- | --- | +| `MissingRequiredError` | if ``data["type"]`` is absent. | +| `TypeMismatchError` | if ``data["type"]`` is not a recognised
block type. | +| `NotImplementedError` | when the block type is recognised but its
round-trip parser depends on a part of the API that is not
yet implemented (currently: ``RichTextBlock`` and any block
containing nested elements, cards, tasks, charts, or
rich text -- ``ActionsBlock``, ``InputBlock``,
``TableBlock``, ``CardBlock``, ``CarouselBlock``,
``ContainerBlock``, ``ContextActionsBlock``,
``DataTableBlock``, ``DataVisualizationBlock``,
``TaskCardBlock``, and ``PlanBlock`` -- see Phase 7.4b
and 7.4c). | + +
+ +## RichTextBlock + +**Class** + +```python +RichTextBlock(elements: 'RichTextObject | list[RichTextObject]', block_id: 'str | None' = None) -> 'None' +``` + +
+ +A RichTextBlock is used to provide easier rich text formatting + than standard markdown text (e.g. in a + [`SectionBlock`](/reference/python/blocks#sectionblock)) + and access to text formatting features not available in traditional + markdown (e.g. strikethrough). See the various rich text elements + you can include [here](/reference/python/rich_text). + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `elements` | `RichTextObject \| list[RichTextObject]` | a single [rich text element](rich_text)
or a list of those elements. | +| `block_id` | `str \| None` | you can use this field to provide a deterministic identifier
for the block. | + +

Errors

+ +| Error | When | +| --- | --- | +| `InvalidUsageError` | if the elements in `elements` are not valid rich
text elements. | + +
+ +### from_dict + +```python +from_dict(data: 'dict[str, Any]') -> 'RichTextBlock' +``` + +
+ +Parse a Slack ``rich_text`` block payload. + +Currently raises ``NotImplementedError`` because the rich-text +object hierarchy has a deeply nested element graph; round-tripping +is deferred to Phase 7.4c. + +
+ +## SectionBlock + +**Class** + +```python +SectionBlock(text: 'TextLike | None' = None, block_id: 'str | None' = None, fields: 'TextLike | list[TextLike] | None' = None, accessory: 'Element | None' = None) -> 'None' +``` + +
+ +A section is one of the most flexible blocks available - +it can be used as a simple text block, or with any of the +available block elements. + +Section blocks can also optionally be given an "accessory," +which is typically one of the interactive +[Elements](/reference/python/elements). + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `text` | `TextLike \| None` | text to include in the block. Can be a string or `Text` object (of either
`mrkdwn` or `plaintext` variety). Defaults to markdown if unspecified. One of either
`text` or `fields` must be provided. | +| `block_id` | `str \| None` | you can use this field to provide a deterministic identifier for the block. | +| `fields` | `TextLike \| list[TextLike] \| None` | a list of text objects. One of either `text` or `fields` must be provided. | +| `accessory` | `Element \| None` | an optional [Element](/reference/python/elements) object
that will take a secondary place in the block (after or to the side of `text`
or `fields`). | + +

Errors

+ +| Error | When | +| --- | --- | +| `InvalidUsageError` | if any of the provided arguments fail validation checks. | + +
+ +### from_dict + +```python +from_dict(data: 'dict[str, Any]') -> 'SectionBlock' +``` + +
+ +Parse a Slack ``section`` block payload. + +Round-trips ``text`` and ``fields``. Raises ``NotImplementedError`` +if an ``accessory`` is present, because the accessory is an +``Element`` and ``Element.from_dict`` is not yet implemented +(Phase 7.4b). + +
+ +## TableBlock + +**Class** + +```python +TableBlock(rows: 'list[list[RawText | RichTextObject]]', column_settings: 'list[ColumnSettings] | None' = None, block_id: 'str | None' = None) -> 'None' +``` + +
+ +A `TableBlock` displays data in a table format. + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `rows` | `list[list[RawText \| RichTextObject]]` | a list of lists of `RawText` or `RichTextObject` objects. | +| `column_settings` | `list[ColumnSettings] \| None` | a list of `ColumnSettings` objects. | +| `block_id` | `str \| None` | you can use this field to provide a deterministic identifier for the block. | + +

Errors

+ +| Error | When | +| --- | --- | +| `InvalidUsageError` | when items in `rows` are not `RawText` or `RichTextObject` objects. | +| `InvalidUsageError` | when the number of column_settings does not match the number of
columns in each row. | +| `InvalidUsageError` | when the number of rows is greater than 100. | +| `InvalidUsageError` | when the number of columns in a row is greater than 20. | +| `InvalidUsageError` | when the number of column_settings is greater than 20. | + +
+ +### from_dict + +```python +from_dict(data: 'dict[str, Any]') -> 'TableBlock' +``` + +
+ +Parse a Slack ``table`` block payload. + +Currently raises ``NotImplementedError`` because table cells may +contain rich-text objects whose round-trip parser is deferred to +Phase 7.4c. + +
+ +## TaskCardBlock + +**Class** + +```python +TaskCardBlock(task_id: 'str', title: 'str', details: 'RichTextBlock | None' = None, output: 'RichTextBlock | None' = None, sources: 'list[URLSource] | None' = None, status: 'TaskStatus | None' = None, block_id: 'str | None' = None) -> 'None' +``` + +
+ +One task, its state, rich-text details or output, and source links. +Task cards can stand alone or be grouped in a +[`PlanBlock`](/reference/python/blocks#planblock). + +See: [https://docs.slack.dev/reference/block-kit/blocks/task-card-block](https://docs.slack.dev/reference/block-kit/blocks/task-card-block). + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `task_id` | `str` | a unique identifier for the task. | +| `title` | `str` | the title of the task. | +| `details` | `RichTextBlock \| None` | a `RichTextBlock` describing the task in detail. | +| `output` | `RichTextBlock \| None` | a `RichTextBlock` containing the output of the task. | +| `sources` | `list[URLSource] \| None` | a list of `URLSource` elements linking to the sources
used by the task. | +| `status` | `TaskStatus \| None` | the state of the task, one of `pending`, `in_progress`,
`complete`, or `error`. | +| `block_id` | `str \| None` | you can use this field to provide a deterministic identifier for the block. | + +

Errors

+ +| Error | When | +| --- | --- | +| `InvalidUsageError` | if any of the provided arguments fail validation. | + +
+ +### from_dict + +```python +from_dict(data: 'dict[str, Any]') -> 'TaskCardBlock' +``` + +
+ +Parse a Slack block payload back into the appropriate ``Block`` subclass. + +Reads ``data["type"]`` and dispatches to the matching subclass's +``from_dict``. + +Block types that currently round-trip: ``AlertBlock``, +``ContextBlock`` (text elements only), ``DividerBlock``, +``FileBlock``, ``HeaderBlock``, ``ImageBlock``, ``MarkdownBlock``, +``SectionBlock`` (without an accessory), and ``VideoBlock``. + +

Errors

+ +| Error | When | +| --- | --- | +| `MissingRequiredError` | if ``data["type"]`` is absent. | +| `TypeMismatchError` | if ``data["type"]`` is not a recognised
block type. | +| `NotImplementedError` | when the block type is recognised but its
round-trip parser depends on a part of the API that is not
yet implemented (currently: ``RichTextBlock`` and any block
containing nested elements, cards, tasks, charts, or
rich text -- ``ActionsBlock``, ``InputBlock``,
``TableBlock``, ``CardBlock``, ``CarouselBlock``,
``ContainerBlock``, ``ContextActionsBlock``,
``DataTableBlock``, ``DataVisualizationBlock``,
``TaskCardBlock``, and ``PlanBlock`` -- see Phase 7.4b
and 7.4c). | + +
+ +## VideoBlock + +**Class** + +```python +VideoBlock(alt_text: 'str', thumbnail_url: 'str', title: 'TextLike', video_url: 'str', author_name: 'str | None' = None, block_id: 'str | None' = None, description: 'TextLike | None' = None, provider_icon_url: 'str | None' = None, provider_name: 'str | None' = None, title_url: 'str | None' = None) -> 'None' +``` + +
+ +Embeds a video. Used to display video content inside a Slack message, +modal, or App Home tab. + +See: [https://api.slack.com/reference/block-kit/blocks#video](https://api.slack.com/reference/block-kit/blocks#video). + +Note: Slack restricts which domains may be embedded. The server-side +whitelist (e.g. YouTube, Vimeo) is enforced by Slack on receipt of the +payload, not by this library; supplying an unsupported URL will result +in a Slack API error rather than an `InvalidUsageError` at construction. + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `alt_text` | `str` | a plain-text summary of the video, used for accessibility
and notifications (max 200 chars). | +| `thumbnail_url` | `str` | a URL pointing to the preview image shown before
playback. Must be HTTPS in production usage. | +| `title` | `TextLike` | the title shown above the video player (plain text, max 200
chars). A `str` is coerced to `TextType.PLAINTEXT` `Text`. | +| `video_url` | `str` | the URL of the video to embed. Must point to a
Slack-supported provider (see Slack's documentation). | +| `author_name` | `str \| None` | optional author name shown beneath the video
(max 50 chars). | +| `block_id` | `str \| None` | an optional deterministic identifier for the block. | +| `description` | `TextLike \| None` | optional plain-text description below the video
(max 200 chars). A `str` is coerced to `TextType.PLAINTEXT`. | +| `provider_icon_url` | `str \| None` | an optional URL to the provider's icon. | +| `provider_name` | `str \| None` | an optional provider name shown alongside the icon
(max 50 chars). | +| `title_url` | `str \| None` | an optional URL to link the title to. | + +

Errors

+ +| Error | When | +| --- | --- | +| `LengthError` | if any length-constrained string exceeds its limit. | + +
+ +### from_dict + +```python +from_dict(data: 'dict[str, Any]') -> 'VideoBlock' +``` + +
+ +Parse a Slack ``video`` block payload. + +
diff --git a/docs/versioned_docs/version-2.1.0/reference/python/builder.mdx b/docs/versioned_docs/version-2.1.0/reference/python/builder.mdx new file mode 100644 index 00000000..4e790383 --- /dev/null +++ b/docs/versioned_docs/version-2.1.0/reference/python/builder.mdx @@ -0,0 +1,54 @@ +# Builder + +## block_kit_builder_url + +**Function** + +```python +block_kit_builder_url(payload: 'Block | list[Block] | Resolvable | dict[str, Any]', team_id: 'str | None' = None) -> 'str' +``` + +
+ +Build a URL that opens ``payload`` in Slack's Block Kit Builder. + +Use this to preview a message, view, or list of blocks in the browser +without manually copying JSON into the Builder. + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `payload` | `Block \| list[Block] \| Resolvable \| dict[str, Any]` | any of:

- A single ``Block`` -- wrapped in ``{"blocks": [block]}``.
- A list of ``Block`` -- wrapped in ``{"blocks": [...]}``.
- Anything with a ``_resolve`` method (``Message``,
``WebhookMessage``, ``MessageResponse``, ``View``,
``ModalView``, ``HomeTabView``, etc.) -- used as-is.
- A raw ``dict`` -- used as-is. This is the escape hatch for
callers building payloads outside the type hierarchy. | +| `team_id` | `str \| None` | optional Slack team ID. When supplied, produces a
workspace-specific Builder URL of the form
``https://app.slack.com/block-kit-builder/T0123#``.
When ``None`` (the default), produces the generic URL. | + +### Returns + +| Type | Description | +| --- | --- | +| `str` | A fully-formed Block Kit Builder URL. | + +### Examples + +Single block:: + + from slackblocks import SectionBlock, block_kit_builder_url + + url = block_kit_builder_url(SectionBlock("Hi")) + +Multiple blocks:: + + url = block_kit_builder_url([ + SectionBlock("Heading"), + DividerBlock(), + ]) + +Existing message:: + + url = block_kit_builder_url(my_message) + +Targeting a specific workspace:: + + url = block_kit_builder_url(my_message, team_id="T0123ABCD") + +
diff --git a/docs/versioned_docs/version-2.1.0/reference/python/elements.mdx b/docs/versioned_docs/version-2.1.0/reference/python/elements.mdx new file mode 100644 index 00000000..da3a1e13 --- /dev/null +++ b/docs/versioned_docs/version-2.1.0/reference/python/elements.mdx @@ -0,0 +1,981 @@ +# Elements + +## Button + +**Class** + +```python +Button(text: 'TextLike', action_id: 'str', url: 'str | None' = None, value: 'str | None' = None, style: 'ButtonStyle | ButtonStyleName | None' = None, confirm: 'ConfirmationDialogue | None' = None, accessibility_label: 'str | None' = None) -> 'None' +``` + +
+ +An interactive element that inserts a button. The button can be a +trigger for anything from opening a simple link to starting a complex +workflow. + +See: [https://api.slack.com/reference/block-kit/block-elements#button](https://api.slack.com/reference/block-kit/block-elements#button). + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `text` | `TextLike` | text on the button (plaintext only; max 75 chars). | +| `action_id` | `str` | an identifier so the source of the action can be known. | +| `url` | `str \| None` | a URL to load in the user's browser when the button is clicked. | +| `value` | `str \| None` | the value sent with the interaction payload. | +| `style` | `ButtonStyle \| ButtonStyleName \| None` | the visual style of the button, one of `primary`, `danger`. | +| `confirm` | `ConfirmationDialogue \| None` | a `ConfirmationDialogue` object that will be presented when
the button is clicked. | +| `accessibility_label` | `str \| None` | a string label for longer descriptive text about
a button element. Used by screen readers (max 75 chars). | + +Raises: + InvalidUsageError: if any of the provided arguments fail validation. + +
+ +## ChannelMultiSelectMenu + +**Class** + +```python +ChannelMultiSelectMenu(action_id: 'str', initial_channels: 'list[str] | None' = None, confirm: 'ConfirmationDialogue | None' = None, max_selected_items: 'int | None' = None, focus_on_load: 'bool' = False, placeholder: 'TextLike | None' = None) -> 'None' +``` + +
+ +This interactive UI element allows users to select multiple channels visible + to the current user in the active workspace. + +See: [https://api.slack.com/reference/block-kit/block-elements#channel_multi_select](https://api.slack.com/reference/block-kit/block-elements#channel_multi_select). + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `action_id` | `str` | an identifier so the source of the action can be known. | +| `initial_channels` | `list[str] \| None` | a list of conversation IDs as strings that will
already be selected when the menu renders. | +| `confirm` | `ConfirmationDialogue \| None` | a `ConfirmationDialogue` object that will be presented when
the menu is used. | +| `max_selected_items` | `int \| None` | the maximum number of items that can be selected
in the menu. | +| `focus_on_load` | `bool` | whether or not the menu will be set to autofocus
within the view object. | +| `placeholder` | `TextLike \| None` | a plain-text `Text` object (max 150 chars) that shows
in the menu when it's initially rendered. | + +

Errors

+ +| Error | When | +| --- | --- | +| `InvalidUsageError` | if any of the provided arguments fail validation. | + +
+ +## ChannelSelectMenu + +**Class** + +```python +ChannelSelectMenu(action_id: 'str', initial_channel: 'str | None' = None, confirm: 'ConfirmationDialogue | None' = None, response_url_enabled: 'bool | None' = False, focus_on_load: 'bool' = False, placeholder: 'TextLike | None' = None) -> 'None' +``` + +
+ +A select menu interactive UI element, sourced with a list of public channels visible + to the current user. + +See: [https://api.slack.com/reference/block-kit/block-elements#channels_select](https://api.slack.com/reference/block-kit/block-elements#channels_select). + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `action_id` | `str` | an identifier so the source of the action can be known. | +| `initial_channel` | `str \| None` | the single (string) user ID that will be initially selected
when first presented to the user. | +| `confirm` | `ConfirmationDialogue \| None` | a `ConfirmationDialogue` object that will be presented when an
option in the overflow menu is selected. | +| `response_url_enabled` | `bool \| None` | When set to true, the view_submission payload from the
menu's parent view will contain a response_url. (This response_url can be
used for message responses). | +| `focus_on_load` | `bool` | whether or not the input will be set to autofocus
within the view object. | +| `placeholder` | `TextLike \| None` | a plain-text `Text` object (max 150 chars) that shows
in the input when it's initially rendered. | + +

Errors

+ +| Error | When | +| --- | --- | +| `InvalidUsageError` | if any of the provided arguments fail validation. | + +
+ +## CheckboxGroup + +**Class** + +```python +CheckboxGroup(action_id: 'str', options: 'Option | list[Option]', initial_options: 'Option | list[Option] | None' = None, confirm: 'ConfirmationDialogue | None' = None, focus_on_load: 'bool' = False) -> 'None' +``` + +
+ +A checkbox group that allows a user to choose multiple items from a list +of possible options. + +See: [https://api.slack.com/reference/block-kit/block-elements#checkboxes](https://api.slack.com/reference/block-kit/block-elements#checkboxes). + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `action_id` | `str` | an identifier so the source of the action can be known. | +| `options` | `Option \| list[Option]` | a list of
[`Option`](/reference/python/objects#option) objects that will form
the content of the checkbox group. | +| `initial_options` | `Option \| list[Option] \| None` | a list of
[`Option`](/reference/python/objects#option) objects that will be
initially selected when first presented to the user. | +| `confirm` | `ConfirmationDialogue \| None` | a `ConfirmationDialogue` object that will be presented when
the checkbox group is used. | +| `focus_on_load` | `bool` | whether or not the checkbox group will be set to autofocus
within the view object. | + +

Errors

+ +| Error | When | +| --- | --- | +| `InvalidUsageError` | if any of the provided arguments fail validation. | + +
+ +## ConversationMultiSelectMenu + +**Class** + +```python +ConversationMultiSelectMenu(action_id: 'str', initial_conversations: 'list[str] | None' = None, default_to_current_conversation: 'bool | None' = False, confirm: 'ConfirmationDialogue | None' = None, max_selected_items: 'int | None' = None, filter: 'ConversationFilter | None' = None, focus_on_load: 'bool | None' = False, placeholder: 'TextLike | None' = None) -> 'None' +``` + +
+ +This interactive UI element allows users to select multiple conversations visible + to the current user in the active workspace. + +See: [https://api.slack.com/reference/block-kit/block-elements#conversation_multi_select](https://api.slack.com/reference/block-kit/block-elements#conversation_multi_select). + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `action_id` | `str` | an identifier so the source of the action can be known. | +| `initial_conversations` | `list[str] \| None` | a list of conversation IDs as strings that will
already be selected when the menu renders. | +| `default_to_current_conversation` | `bool \| None` | Pre-populates the select menu with the
conversation that the user was viewing when they opened the modal
(defaults to `False`). | +| `confirm` | `ConfirmationDialogue \| None` | a `ConfirmationDialogue` object that will be presented when
the menu is used. | +| `max_selected_items` | `int \| None` | the maximum number of items that can be selected
in the menu. | +| `filter` | `ConversationFilter \| None` | a [`Filter`](/reference/python/objects#conversationfilter)
object that filters out conversations that don't match the settings
of the filter. | +| `focus_on_load` | `bool \| None` | whether or not the menu will be set to autofocus
within the view object. | +| `placeholder` | `TextLike \| None` | a plain-text `Text` object (max 150 chars) that shows
in the menu when it's initially rendered. | + +

Errors

+ +| Error | When | +| --- | --- | +| `InvalidUsageError` | if any of the provided arguments fail validation. | + +
+ +## ConversationSelectMenu + +**Class** + +```python +ConversationSelectMenu(action_id: 'str', initial_conversation: 'str | None' = None, default_to_current_conversation: 'bool | None' = False, confirm: 'ConfirmationDialogue | None' = None, response_url_enabled: 'bool | None' = False, filter: 'ConversationFilter | None' = None, focus_on_load: 'bool' = False, placeholder: 'TextLike | None' = None) -> 'None' +``` + +
+ +A select menu interactive UI element, sourced with a list of public and private channels, + DMs, and MPIMs visible to the current user. + +See: [https://api.slack.com/reference/block-kit/block-elements#conversations_select](https://api.slack.com/reference/block-kit/block-elements#conversations_select). + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `action_id` | `str` | an identifier so the source of the action can be known. | +| `initial_conversation` | `str \| None` | the single (string) conversation ID that will be initially
selected when first presented to the user. | +| `default_to_current_conversation` | `bool \| None` | Pre-populates the select menu with the
conversation that the user was viewing when they opened the modal
(defaults to `False`). | +| `confirm` | `ConfirmationDialogue \| None` | a `ConfirmationDialogue` object that will be presented when an
option in the overflow menu is selected. | +| `response_url_enabled` | `bool \| None` | When set to true, the view_submission payload from the
menu's parent view will contain a response_url. (This response_url can be
used for message responses). | +| `filter` | `ConversationFilter \| None` | a [`Filter`](/reference/python/objects#conversationfilter)
object that filters out conversations that don't match the settings
of the filter. | +| `focus_on_load` | `bool` | whether or not the input will be set to autofocus
within the view object. | +| `placeholder` | `TextLike \| None` | a plain-text `Text` object (max 150 chars) that shows
in the input when it's initially rendered. | + +

Errors

+ +| Error | When | +| --- | --- | +| `InvalidUsageError` | if any of the provided arguments fail validation. | + +
+ +## DatePicker + +**Class** + +```python +DatePicker(action_id: 'str', initial_date: 'str | None' = None, confirm: 'ConfirmationDialogue | None' = None, focus_on_load: 'bool' = False, placeholder: 'TextLike | None' = None) -> 'None' +``` + +
+ +Interactive element that allows users to select a date from a calendar. + +See: [https://api.slack.com/reference/block-kit/block-elements#datepicker](https://api.slack.com/reference/block-kit/block-elements#datepicker). + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `action_id` | `str` | an identifier so the source of the action can be known. | +| `initial_date` | `str \| None` | the date (in `YYYY-MM-DD` format) that will appear on the
picker when it first renders. | +| `confirm` | `ConfirmationDialogue \| None` | a `ConfirmationDialogue` object that will be presented when
the date picker is clicked. | +| `focus_on_load` | `bool` | whether or not the date picker will be set to autofocus
within the view object. | +| `placeholder` | `TextLike \| None` | a `TextType.PLAINTEXT` `Text` object that defines what text
will initially appear on the picker. | + +

Errors

+ +| Error | When | +| --- | --- | +| `InvalidUsageError` | if any of the provided arguments fail validation. | + +
+ +## DateTimePicker + +**Class** + +```python +DateTimePicker(action_id: 'str', initial_datetime: 'int | None' = None, confirm: 'ConfirmationDialogue | None' = None, focus_on_load: 'bool' = False) -> 'None' +``` + +
+ +Allows users to select both a date and a time of day. + +Provides the date-time formatted as a Unix timestamp. + +See: [https://api.slack.com/reference/block-kit/block-elements#datetimepicker](https://api.slack.com/reference/block-kit/block-elements#datetimepicker). + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `action_id` | `str` | an identifier so the source of the action can be known. | +| `initial_datetime` | `int \| None` | the initial value the date-time picker will be set to
when it first renders. | +| `confirm` | `ConfirmationDialogue \| None` | a `ConfirmationDialogue` object that will be presented when
the button is date-time picker is used. | +| `focus_on_load` | `bool` | whether or not the datetime picker will be set to autofocus
within the view object. | + +Raises: + InvalidUsageError: if any of the provided arguments fail validation. + +
+ +## Element + +**Class** + +```python +Element(type_: 'ElementType') -> 'None' +``` + +
+ +Basis element containing attributes and behaviour common to all elements. +N.B: Element is an abstract class and cannot be used directly. + +
+ +## EmailInput + +**Class** + +```python +EmailInput(action_id: 'str', initial_value: 'str | None' = None, dispatch_action_config: 'DispatchActionConfiguration | None' = None, focus_on_load: 'bool' = False, placeholder: 'TextLike | None' = None) -> 'None' +``` + +
+ +Allows user to enter an email into a single-line text field. + +See: [https://api.slack.com/reference/block-kit/block-elements#email](https://api.slack.com/reference/block-kit/block-elements#email). + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `action_id` | `str` | an identifier so the source of the action can be known. | +| `initial_value` | `str \| None` | The initial value in the email input when it is loaded. | +| `dispatch_action_config` | `DispatchActionConfiguration \| None` | a `DispatchActionConfiguration` object that
determines when during text input the element returns a
`block_actions` payload. | +| `focus_on_load` | `bool` | whether or not the email input will be set to autofocus
within the view object. | +| `placeholder` | `TextLike \| None` | a `TextType.PLAINTEXT` `Text` object that defines what text
will initially appear in the input field. | + +

Errors

+ +| Error | When | +| --- | --- | +| `InvalidUsageError` | if any of the provided arguments fail validation. | + +
+ +## ExternalMultiSelectMenu + +**Class** + +```python +ExternalMultiSelectMenu(action_id: 'str', min_query_length: 'int | None' = None, initial_options: 'Option | list[Option] | OptionGroup | list[OptionGroup] | None' = None, confirm: 'ConfirmationDialogue | None' = None, max_selected_items: 'int | None' = None, focus_on_load: 'bool' = False, placeholder: 'TextLike | None' = None) -> 'None' +``` + +
+ +An interactive UI element that loads its options from an external data source, + allowing for a dynamic list of options. + +See: [https://api.slack.com/reference/block-kit/block-elements#external_multi_select](https://api.slack.com/reference/block-kit/block-elements#external_multi_select). + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `action_id` | `str` | an identifier so the source of the action can be known. | +| `min_query_length` | `int \| None` | minimum number of characters entered before the query
is dispactched (defaults to 3 if not provided). | +| `initial_options` | `Option \| list[Option] \| OptionGroup \| list[OptionGroup] \| None` | the [`Options`](/reference/python/objects#option)
to be initially selected when the element is first rendered. | +| `confirm` | `ConfirmationDialogue \| None` | a `ConfirmationDialogue` object that will be presented when
the menu is used. | +| `max_selected_items` | `int \| None` | the highest number of items from the list that
can be selected at one time. | +| `focus_on_load` | `bool` | whether or not the menu will be set to autofocus
within the view object. | +| `placeholder` | `TextLike \| None` | a plain-text `Text` object (max 150 chars) that shows
in the menu when it's initially rendered. | + +

Errors

+ +| Error | When | +| --- | --- | +| `InvalidUsageError` | if any of the provided arguments fail validation. | + +
+ +## ExternalSelectMenu + +**Class** + +```python +ExternalSelectMenu(action_id: 'str', initial_option: 'Option | OptionGroup | None' = None, min_query_length: 'int | None' = None, confirm: 'ConfirmationDialogue | None' = None, focus_on_load: 'bool' = False, placeholder: 'TextLike | None' = None) -> 'None' +``` + +
+ +A select menu interactive UI element, sourced with externally provided options. + +**See:** [https://api.slack.com/slackblocks/latest/reference/block-kit/block-elements#external_select](https://api.slack.com/slackblocks/latest/reference/block-kit/block-elements#external_select). + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `action_id` | `str` | an identifier so the source of the action can be known. | +| `initial_option` | `Option \| OptionGroup \| None` | an
[`Option`](/reference/python/objects#option) object that will be
initially selected when first presented to the user. | +| `min_query_length` | `int \| None` | minimum number of characters entered before the query
is dispactched (defaults to 3 if not provided). | +| `confirm` | `ConfirmationDialogue \| None` | a `ConfirmationDialogue` object that will be presented when an
option in the overflow menu is selected. | +| `focus_on_load` | `bool` | whether or not the input will be set to autofocus
within the view object. | +| `placeholder` | `TextLike \| None` | a plain-text `Text` object (max 150 chars) that shows
in the input when it's initially rendered. | + +

Errors

+ +| Error | When | +| --- | --- | +| `InvalidUsageError` | if any of the provided arguments fail validation. | + +
+ +## FeedbackButton + +**Class** + +```python +FeedbackButton(text: 'TextLike', value: 'str', accessibility_label: 'str | None' = None) -> 'None' +``` + +
+ +One of the positive or negative buttons in a +[`FeedbackButtons`](/reference/python/elements#feedbackbuttons) +element. + +See: [https://docs.slack.dev/reference/block-kit/block-elements/feedback-buttons-element](https://docs.slack.dev/reference/block-kit/block-elements/feedback-buttons-element). + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `text` | `TextLike` | the text on the button (plaintext only; max 75 chars). | +| `value` | `str` | the value sent with the interaction payload (max 2000 chars). | +| `accessibility_label` | `str \| None` | a string label for longer descriptive text about
the button. Used by screen readers (max 75 chars). | + +

Errors

+ +| Error | When | +| --- | --- | +| `InvalidUsageError` | if any of the provided arguments fail validation. | + +
+ +## FeedbackButtons + +**Class** + +```python +FeedbackButtons(positive_button: 'FeedbackButton', negative_button: 'FeedbackButton', action_id: 'str | None' = None) -> 'None' +``` + +
+ +A paired positive/negative feedback control for a +[`ContextActionsBlock`](/reference/python/blocks#contextactionsblock). + +See: [https://docs.slack.dev/reference/block-kit/block-elements/feedback-buttons-element](https://docs.slack.dev/reference/block-kit/block-elements/feedback-buttons-element). + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `positive_button` | `FeedbackButton` | a `FeedbackButton` used to indicate positive feedback. | +| `negative_button` | `FeedbackButton` | a `FeedbackButton` used to indicate negative feedback. | +| `action_id` | `str \| None` | an identifier so the source of the action can be known. | + +

Errors

+ +| Error | When | +| --- | --- | +| `InvalidUsageError` | if any of the provided arguments fail validation. | + +
+ +## FileInput + +**Class** + +```python +FileInput(action_id: 'str | None' = None, filetypes: 'str | list[str] | None' = None, max_files: 'int | None' = None) -> 'None' +``` + +
+ +An interactive element that allows users to upload files. + +See: [https://api.slack.com/reference/block-kit/block-elements#file_input](https://api.slack.com/reference/block-kit/block-elements#file_input). + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `action_id` | `str \| None` | an identifier so the source of the action can be known. | +| `filetypes` | `str \| list[str] \| None` | a list of file extensions (as strings) that will be accepted
for upload. | +| `max_files` | `int \| None` | the maximum number of files that can be uploaded (between 1
and 10). | + +

Errors

+ +| Error | When | +| --- | --- | +| `InvalidUsageError` | if any of the provided arguments fail validation. | + +
+ +## IconButton + +**Class** + +```python +IconButton(text: 'TextLike', icon: "Literal['trash']" = 'trash', action_id: 'str | None' = None, value: 'str | None' = None, confirm: 'ConfirmationDialogue | None' = None, accessibility_label: 'str | None' = None, visible_to_user_ids: 'list[str] | None' = None) -> 'None' +``` + +
+ +A compact icon-only action for a +[`ContextActionsBlock`](/reference/python/blocks#contextactionsblock). + +Slack currently supports only the `trash` icon. + +See: [https://docs.slack.dev/reference/block-kit/block-elements/icon-button-element](https://docs.slack.dev/reference/block-kit/block-elements/icon-button-element). + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `text` | `TextLike` | the text describing the button (plaintext only). | +| `icon` | `Literal['trash']` | the icon to show; `trash` is the only icon currently
supported by Slack. | +| `action_id` | `str \| None` | an identifier so the source of the action can be known. | +| `value` | `str \| None` | the value sent with the interaction payload (max 2000 chars). | +| `confirm` | `ConfirmationDialogue \| None` | a `ConfirmationDialogue` object that will be presented when
the button is clicked. | +| `accessibility_label` | `str \| None` | a string label for longer descriptive text about
the button. Used by screen readers (max 75 chars). | +| `visible_to_user_ids` | `list[str] \| None` | a list of (string) user IDs for which the button
is visible (max 10). If not provided, the button is visible to
all users. | + +

Errors

+ +| Error | When | +| --- | --- | +| `InvalidUsageError` | if any of the provided arguments fail validation. | + +
+ +## Image + +**Class** + +```python +Image(alt_text: 'str' = ' ', image_url: 'str | None' = None, slack_file: 'SlackFile | None' = None) -> 'None' +``` + +
+ +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. + +You must provide either one of `image_url` or `slack_file` + +See: [https://api.slack.com/reference/block-kit/block-elements#image](https://api.slack.com/reference/block-kit/block-elements#image). + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `alt_text` | `str` | a plain-text-only summary of the content of the image. | +| `image_url` | `str \| None` | a URL for a publicly hosted image (the user must provide
either `image_url` or `slack_file`). | +| `slack_file` | `SlackFile \| None` | a [`SlackFile`](/reference/python/objects#slackfile)
(the user must provide either `image_url` or `slack_file`). | + +

Errors

+ +| Error | When | +| --- | --- | +| `InvalidUsageError` | if any of the provided arguments fail validation,
or both/neither of `image_url` and `slack_file` are provided. | + +
+ +## NumberInput + +**Class** + +```python +NumberInput(is_decimal_allowed: 'bool', action_id: 'str | None' = None, initial_value: 'str | None' = None, min_value: 'float | int | None' = None, max_value: 'float | int | None' = None, dispatch_action_config: 'DispatchActionConfiguration | None' = None, focus_on_load: 'bool' = False, placeholder: 'TextLike | None' = None) -> 'None' +``` + +
+ +This input elements accepts both integer and decimal numbers. For example, +0.25, 5.5, and -10 are all valid input values. + +See [https://api.slack.com/reference/block-kit/block-elements#number](https://api.slack.com/reference/block-kit/block-elements#number). + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `is_decimal_allowed` | `bool` | whether to accept decimal values as input. | +| `action_id` | `str \| None` | an identifier so the source of the action can be known. | +| `initial_value` | `str \| None` | the initial value in the number input when it is loaded. | +| `min_value` | `float \| int \| None` | minimum accepted value for the input field. | +| `max_value` | `float \| int \| None` | maximum accepted value for the input field. | +| `dispatch_action_config` | `DispatchActionConfiguration \| None` | a `DispatchActionConfiguration` object that
determines when during text input the element returns a
`block_actions` payload. | +| `focus_on_load` | `bool` | whether or not the menu will be set to autofocus
within the view object. | +| `placeholder` | `TextLike \| None` | a plain-text `Text` object (max 150 chars) that shows
in the input when it's initially rendered. | + +

Errors

+ +| Error | When | +| --- | --- | +| `InvalidUsageError` | if any of the provided arguments fail validation. | + +
+ +## OverflowMenu + +**Class** + +```python +OverflowMenu(action_id: 'str', options: 'Option | list[Option]', confirm: 'ConfirmationDialogue | None' = None) -> 'None' +``` + +
+ +Context menu for additional options (think '...'). + +See [https://api.slack.com/reference/block-kit/block-elements#overflow](https://api.slack.com/reference/block-kit/block-elements#overflow). + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `action_id` | `str` | an identifier so the source of the action can be known. | +| `options` | `Option \| list[Option]` | a list of
[`Option`](/reference/python/objects#option) objects that will form
the content of the overflow menu. | +| `confirm` | `ConfirmationDialogue \| None` | a `ConfirmationDialogue` object that will be presented when an
option in the overflow menu is selected. | + +

Errors

+ +| Error | When | +| --- | --- | +| `InvalidUsageError` | if any of the provided arguments fail validation. | + +
+ +## PlainTextInput + +**Class** + +```python +PlainTextInput(action_id: 'str', initial_value: 'str | None' = None, multiline: 'bool' = False, min_length: 'int | None' = None, max_length: 'int | None' = None, dispatch_action_config: 'DispatchActionConfiguration | None' = None, focus_on_load: 'bool' = False, placeholder: 'TextLike | None' = None) -> 'None' +``` + +
+ +A plain-text input, similar to the HTML `` tag, creates a field where a user +can enter freeform data. It can appear as a single-line field or a larger text +area using the multiline flag. + +See: [https://api.slack.com/reference/block-kit/block-elements#input](https://api.slack.com/reference/block-kit/block-elements#input). + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `action_id` | `str` | an identifier so the source of the action can be known. | +| `initial_value` | `str \| None` | the initial value in the plain-text input when it is loaded. | +| `multiline` | `bool` | whether to accept multiple lines of input(defaults to false). | +| `min_length` | `int \| None` | minimum number of characters to accept as input. | +| `max_length` | `int \| None` | maximum number of characters to accept as input. | +| `dispatch_action_config` | `DispatchActionConfiguration \| None` | a `DispatchActionConfiguration` object that
determines when during text input the element returns a
`block_actions` payload. | +| `focus_on_load` | `bool` | whether or not the input will be set to autofocus
within the view object. | +| `placeholder` | `TextLike \| None` | a plain-text `Text` object (max 150 chars) that shows
in the input when it's initially rendered. | + +

Errors

+ +| Error | When | +| --- | --- | +| `InvalidUsageError` | if any of the provided arguments fail validation. | + +
+ +## RadioButtonGroup + +**Class** + +```python +RadioButtonGroup(action_id: 'str', options: 'list[Option]', initial_option: 'Option | None' = None, confirm: 'ConfirmationDialogue | None' = None, focus_on_load: 'bool' = False) -> 'None' +``` + +
+ +A radio button group that allows a user to choose one item from a list of possible options. + +See: [https://api.slack.com/reference/block-kit/block-elements#radio](https://api.slack.com/reference/block-kit/block-elements#radio). + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `action_id` | `str` | an identifier so the source of the action can be known. | +| `options` | `list[Option]` | a list of
[`Option`](/reference/python/objects#option) objects that will form
the content of the radio button group. | +| `initial_option` | `Option \| None` | an
[`Option`](/reference/python/objects#option) object that will be
initially selected when first presented to the user. | +| `confirm` | `ConfirmationDialogue \| None` | a `ConfirmationDialogue` object that will be presented when an
option in the overflow menu is selected. | +| `focus_on_load` | `bool` | whether or not the input will be set to autofocus
within the view object. | + +

Errors

+ +| Error | When | +| --- | --- | +| `InvalidUsageError` | if any of the provided arguments fail validation. | + +
+ +## RichTextInput + +**Class** + +```python +RichTextInput(action_id: 'str', initial_value: 'RichText | None' = None, dispatch_action_config: 'DispatchActionConfiguration | None' = None, focus_on_load: 'bool' = False, placeholder: 'TextLike | None' = None) -> 'None' +``` + +
+ +Allows users to enter formatted text in a WYSIWYG editor, similar to the Slack + messaging experience. + +See: [https://api.slack.com/reference/block-kit/block-elements#rich_text_input](https://api.slack.com/reference/block-kit/block-elements#rich_text_input). + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `action_id` | `str` | an identifier so the source of the action can be known. | +| `initial_value` | `RichText \| None` | The initial value in the rich text input when it is loaded. | +| `dispatch_action_config` | `DispatchActionConfiguration \| None` | a `DispatchActionConfiguration` object that
determines when during text input the element returns a
`block_actions` payload. | +| `focus_on_load` | `bool` | whether or not the menu will be set to autofocus
within the view object. | +| `placeholder` | `TextLike \| None` | a plain-text `Text` object (max 150 chars) that shows
in the menu when it's initially rendered. | + +

Errors

+ +| Error | When | +| --- | --- | +| `InvalidUsageError` | if any of the provided arguments fail validation. | + +
+ +## StaticMultiSelectMenu + +**Class** + +```python +StaticMultiSelectMenu(action_id: 'str', options: 'Option | list[Option]', option_groups: 'OptionGroup | list[OptionGroup] | None' = None, initial_options: 'Option | list[Option] | OptionGroup | list[OptionGroup] | None' = None, confirm: 'ConfirmationDialogue | None' = None, max_selected_items: 'int | None' = None, focus_on_load: 'bool' = False, placeholder: 'TextLike | None' = None) -> 'None' +``` + +
+ +The most basic form of select menu containing a static list of options +passed in when defining the element. + +See: [https://api.slack.com/reference/block-kit/block-elements#static_multi_select](https://api.slack.com/reference/block-kit/block-elements#static_multi_select). + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `action_id` | `str` | an identifier so the source of the action can be known. | +| `options` | `Option \| list[Option]` | a list of [`Options`](/reference/python/objects#option)
(max 100). Only one of `options` or `option_groups` must be
provided. | +| `option_groups` | `OptionGroup \| list[OptionGroup] \| None` | a list of
[`OptionGroups`](/reference/python/objects#optiongroup)
(max 100). Only one of `options` or `option_groups` can be
provided. | +| `initial_options` | `Option \| list[Option] \| OptionGroup \| list[OptionGroup] \| None` | the [`Options`](/reference/python/objects#option)
to be initially selected when the element is first rendered. | +| `confirm` | `ConfirmationDialogue \| None` | a `ConfirmationDialogue` object that will be presented when
the menu is used. | +| `max_selected_items` | `int \| None` | the | +| `focus_on_load` | `bool` | whether or not the menu will be set to autofocus
within the view object. | +| `placeholder` | `TextLike \| None` | a plain-text `Text` object (max 150 chars) that shows
in the menu when it's initially rendered. | + +

Errors

+ +| Error | When | +| --- | --- | +| `InvalidUsageError` | if any of the provided arguments fail validation. | + +
+ +## StaticSelectMenu + +**Class** + +```python +StaticSelectMenu(action_id: 'str', options: 'list[Option] | None' = None, option_groups: 'list[OptionGroup] | None' = None, initial_option: 'Option | OptionGroup | None' = None, confirm: 'ConfirmationDialogue | None' = None, focus_on_load: 'bool' = False, placeholder: 'TextLike | None' = None) -> 'None' +``` + +
+ +A simple select menu interactive UI element, with a static list of options passed in when + defining the element. + +See: [https://api.slack.com/reference/block-kit/block-elements#static_select](https://api.slack.com/reference/block-kit/block-elements#static_select). + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `action_id` | `str` | an identifier so the source of the action can be known. | +| `options` | `list[Option] \| None` | a list of
[`Option`](/reference/python/objects#option) objects that will form
the content of the menu (max 100). | +| `option_groups` | `list[OptionGroup] \| None` | a list of
[`OptionGroups`](/reference/python/objects#optiongroup)
(max 100). Only one of `options` or `option_groups` can be
provided. | +| `initial_option` | `Option \| OptionGroup \| None` | an
[`Option`](/reference/python/objects#option) object that will be
initially selected when first presented to the user. | +| `confirm` | `ConfirmationDialogue \| None` | a `ConfirmationDialogue` object that will be presented when an
option in the overflow menu is selected. | +| `focus_on_load` | `bool` | whether or not the input will be set to autofocus
within the view object. | +| `placeholder` | `TextLike \| None` | a plain-text `Text` object (max 150 chars) that shows
in the input when it's initially rendered. | + +

Errors

+ +| Error | When | +| --- | --- | +| `InvalidUsageError` | if any of the provided arguments fail validation. | + +
+ +## TimePicker + +**Class** + +```python +TimePicker(action_id: 'str', initial_time: 'str | None' = None, confirm: 'ConfirmationDialogue | None' = None, focus_on_load: 'bool' = False, placeholder: 'TextLike | None' = None, timezone: 'str | None' = None) -> 'None' +``` + +
+ +An interactive UI element that allows users to select a time of day. + +See: [https://api.slack.com/reference/block-kit/block-elements#timepicker](https://api.slack.com/reference/block-kit/block-elements#timepicker). + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `action_id` | `str` | an identifier so the source of the action can be known. | +| `initial_time` | `str \| None` | — | +| `confirm` | `ConfirmationDialogue \| None` | a `ConfirmationDialogue` object that will be presented when
the input field is used. | +| `focus_on_load` | `bool` | whether or not the menu will be set to autofocus
within the view object. | +| `placeholder` | `TextLike \| None` | a plain-text `Text` object (max 150 chars) that shows
in the menu when it's initially rendered. | +| `timezone` | `str \| None` | a string in the IANA format, e.g. "America/Chicago". | + +

Errors

+ +| Error | When | +| --- | --- | +| `InvalidUsageError` | if any of the provided arguments fail validation. | + +
+ +## URLInput + +**Class** + +```python +URLInput(action_id: 'str', initial_value: 'str | None' = None, dispatch_action_config: 'DispatchActionConfiguration | None' = None, focus_on_load: 'bool' = False, placeholder: 'TextLike | None' = None) -> 'None' +``` + +
+ +An interactive UI element for collecting URL input from users. + +See: [https://api.slack.com/reference/block-kit/block-elements#url](https://api.slack.com/reference/block-kit/block-elements#url). + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `action_id` | `str` | an identifier so the source of the action can be known. | +| `initial_value` | `str \| None` | the text to populate the input field with when it
is first rendered. | +| `dispatch_action_config` | `DispatchActionConfiguration \| None` | a `DispatchActionConfiguration` object that
determines when during text input the element returns a
`block_actions` payload. | +| `focus_on_load` | `bool` | whether or not the menu will be set to autofocus
within the view object. | +| `placeholder` | `TextLike \| None` | a plain-text `Text` object (max 150 chars) that shows
in the input when it's initially rendered. | + +

Errors

+ +| Error | When | +| --- | --- | +| `InvalidUsageError` | if any of the provided arguments fail validation. | + +
+ +## URLSource + +**Class** + +```python +URLSource(url: 'str', text: 'str') -> 'None' +``` + +
+ +A labelled URL source displayed by a +[`TaskCardBlock`](/reference/python/blocks#taskcardblock). + +See: [https://docs.slack.dev/reference/block-kit/blocks/task-card-block](https://docs.slack.dev/reference/block-kit/blocks/task-card-block). + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `url` | `str` | the URL of the source (max 3000 chars). | +| `text` | `str` | the label displayed for the source. | + +

Errors

+ +| Error | When | +| --- | --- | +| `InvalidUsageError` | if any of the provided arguments fail validation. | + +
+ +## UserMultiSelectMenu + +**Class** + +```python +UserMultiSelectMenu(action_id: 'str', initial_users: 'list[str] | None' = None, confirm: 'ConfirmationDialogue | None' = None, max_selected_items: 'int | None' = None, focus_on_load: 'bool' = False, placeholder: 'TextLike | None' = None) -> 'None' +``` + +
+ +This interactive UI element allows users to select multiple users visible + to the current user in the active workspace. + +See: [https://api.slack.com/reference/block-kit/block-elements#users_multi_select](https://api.slack.com/reference/block-kit/block-elements#users_multi_select). + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `action_id` | `str` | an identifier so the source of the action can be known. | +| `initial_users` | `list[str] \| None` | a list of string user IDs to be initially selected
when the element is first rendered. | +| `confirm` | `ConfirmationDialogue \| None` | a `ConfirmationDialogue` object that will be presented when
the menu is used. | +| `max_selected_items` | `int \| None` | the highest number of items from the list that
can be selected at one time. | +| `focus_on_load` | `bool` | whether or not the menu will be set to autofocus
within the view object. | +| `placeholder` | `TextLike \| None` | a plain-text `Text` object (max 150 chars) that shows
in the menu when it's initially rendered. | + +

Errors

+ +| Error | When | +| --- | --- | +| `InvalidUsageError` | if any of the provided arguments fail validation. | + +
+ +## UserSelectMenu + +**Class** + +```python +UserSelectMenu(action_id: 'str', initial_user: 'str | None' = None, confirm: 'ConfirmationDialogue | None' = None, focus_on_load: 'bool' = False, placeholder: 'TextLike | None' = None) -> 'None' +``` + +
+ +A select menu interactive UI element, sourced automatically with Slack users from the + current workspace visible to the current user. + +See: [https://api.slack.com/reference/block-kit/block-elements#users_select](https://api.slack.com/reference/block-kit/block-elements#users_select). + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `action_id` | `str` | an identifier so the source of the action can be known. | +| `initial_user` | `str \| None` | the single (string) user ID that will be initially selected
when first presented to the user. | +| `confirm` | `ConfirmationDialogue \| None` | a `ConfirmationDialogue` object that will be presented when an
option in the overflow menu is selected. | +| `focus_on_load` | `bool` | whether or not the input will be set to autofocus
within the view object. | +| `placeholder` | `TextLike \| None` | a plain-text `Text` object (max 150 chars) that shows
in the input when it's initially rendered. | + +

Errors

+ +| Error | When | +| --- | --- | +| `InvalidUsageError` | if any of the provided arguments fail validation. | + +
+ +## WorkflowButton + +**Class** + +```python +WorkflowButton(text: 'TextLike', workflow: 'Workflow | None' = None, style: 'ButtonStyleLike | None' = , accessibility_label: 'str | None' = None) -> 'None' +``` + +
+ +An interactive component that allows users to run a link trigger with + customizable inputs. + +See: [https://api.slack.com/reference/block-kit/block-elements#workflow_button](https://api.slack.com/reference/block-kit/block-elements#workflow_button). + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `text` | `TextLike` | the text content that will appear in the button. | +| `workflow` | `Workflow \| None` | a [`Workflow`](/reference/python/objects#workflow) object
that contains details about the workflow that will run when the
button is clicked. | +| `style` | `ButtonStyleLike \| None` | one of `Default`, `Primary`, or `Danger`, determines the
visual style of the button. Consider using the `ButtonStyle`
object for this. | +| `accessibility_label` | `str \| None` | a string label for longer descriptive text about
a button element. Used by screen readers (max 75 chars). | + +

Errors

+ +| Error | When | +| --- | --- | +| `InvalidUsageError` | if any of the provided arguments fail validation. | + +
diff --git a/docs/versioned_docs/version-2.1.0/reference/python/errors.mdx b/docs/versioned_docs/version-2.1.0/reference/python/errors.mdx new file mode 100644 index 00000000..10f7fa4d --- /dev/null +++ b/docs/versioned_docs/version-2.1.0/reference/python/errors.mdx @@ -0,0 +1,116 @@ +# Errors + +## InvalidUsageError + +**Class** + +```python +InvalidUsageError(message: 'str') -> 'None' +``` + +
+ +You have violated the `slackblocks` API or Slack Web API in a way + that has been caught by validation checks. + +All more-specific validation exceptions raised by ``slackblocks`` +subclass this exception, so ``except InvalidUsageError`` catches every +library-raised validation failure. + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `message` | `str` | a custom error message providing details of the API
violation. | + +
+ +## LengthError + +**Class** + +```python +LengthError(message: 'str') -> 'None' +``` + +
+ +A string or list length is outside the allowed bounds for a field. + +Typical sources: a ``Text`` body longer than the Slack-enforced limit, +an option list with too many entries, an ``action_id`` over 255 +characters, etc. + +
+ +## MissingRequiredError + +**Class** + +```python +MissingRequiredError(message: 'str') -> 'None' +``` + +
+ +At least one of a set of arguments was required, but none was provided. + +Typical sources: ``ConversationFilter`` invoked with none of its three +filter fields set; ``SectionBlock`` invoked with neither ``text`` nor +``fields``. + +
+ +## MutualExclusivityError + +**Class** + +```python +MutualExclusivityError(message: 'str') -> 'None' +``` + +
+ +Two arguments that must not both be set were both set. + +Typical sources: passing both ``image_url`` and ``slack_file`` to +``Image``; passing both ``options`` and ``option_groups`` to a +``StaticSelectMenu``; passing both ``url`` and ``id`` to ``SlackFile``. + +
+ +## RangeError + +**Class** + +```python +RangeError(message: 'str') -> 'None' +``` + +
+ +A numeric value is outside the allowed bounds for a field. + +Typical sources: ``NumberInput.min_value > max_value``, integer +arguments outside an enforced ``min_value`` / ``max_value`` range. + +
+ +## TypeMismatchError + +**Class** + +```python +TypeMismatchError(message: 'str') -> 'None' +``` + +
+ +An argument is of the wrong type or an unexpected discrete value. + +Typical sources: passing a non-``Option`` element into a list expected +to hold ``Option`` instances; supplying a colour string that is neither +a hex code nor a ``Color`` enum; supplying a string outside an +enumerated set (e.g. ``ColumnSettings.align='banana'``). + +
diff --git a/docs/versioned_docs/version-2.1.0/reference/python/index.mdx b/docs/versioned_docs/version-2.1.0/reference/python/index.mdx new file mode 100644 index 00000000..dac2c957 --- /dev/null +++ b/docs/versioned_docs/version-2.1.0/reference/python/index.mdx @@ -0,0 +1,16 @@ +# Python API reference + +This is the complete guide to slackblocks' public Python API. Use it to check constructor signatures, accepted values, and class behavior while you build a message, modal, or home tab. + +The 113 documented symbols are grouped by the part of Block Kit they help you create. + +- [Attachments](/reference/python/attachments) +- [Blocks](/reference/python/blocks) +- [Builder](/reference/python/builder) +- [Elements](/reference/python/elements) +- [Errors](/reference/python/errors) +- [Messages](/reference/python/messages) +- [Modals](/reference/python/modals) +- [Composition objects](/reference/python/objects) +- [Rich text](/reference/python/rich_text) +- [Views](/reference/python/views) diff --git a/docs/versioned_docs/version-2.1.0/reference/python/messages.mdx b/docs/versioned_docs/version-2.1.0/reference/python/messages.mdx new file mode 100644 index 00000000..f2f0eff4 --- /dev/null +++ b/docs/versioned_docs/version-2.1.0/reference/python/messages.mdx @@ -0,0 +1,207 @@ +# Messages + +## Message + +**Class** + +```python +Message(channel: 'str', text: 'str | None' = '', blocks: 'list[Block] | Block | None' = None, attachments: 'list[Attachment] | None' = None, thread_ts: 'str | None' = None, mrkdwn: 'bool' = True, unfurl_links: 'bool | None' = None, unfurl_media: 'bool | None' = None) -> 'None' +``` + +
+ +A Slack message object that can be converted to a JSON string for use with +the Slack message API. + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `channel` | `str` | the Slack channel to send the message to, e.g. "#general". | +| `text` | `str \| None` | markdown text to send in the message. If `blocks` are provided
then this is a fallback to display in notifications. | +| `blocks` | `list[Block] \| Block \| None` | a list of [`Blocks`](/reference/python/blocks) to form the contents
of the message instead of the contents of `text`. | +| `attachments` | `list[Attachment] \| None` | a list of
[`Attachments`](/reference/python/attachments#attachment)
that form the secondary contents of the message (deprecated). | +| `thread_ts` | `str \| None` | the timestamp ID of another unthreaded message that will
become the parent message of this message (now a reply in a thread). | +| `mrkdwn` | `bool` | if `True` the contents of `text` will be rendered as markdown
rather than plain text. | +| `unfurl_links` | `bool \| None` | if `True`, links in the message will be automatically
unfurled. | +| `unfurl_media` | `bool \| None` | if `True`, media from links (e.g. images) will
automatically unfurl. | + +Raises: + InvalidUsageException: in the event that the items passed to `blocks` + are not valid [`Blocks`](/reference/python/blocks). + +
+ +### json + +```python +json() -> 'str' +``` + +
+ +No public documentation is available. + +
+ +### keys + +```python +keys() -> 'list[str]' +``` + +
+ +No public documentation is available. + +
+ +### to_dict + +```python +to_dict() -> 'dict[str, Any]' +``` + +
+ +No public documentation is available. + +
+ +## MessageResponse + +**Class** + +```python +MessageResponse(text: 'str | None' = '', blocks: 'list[Block] | Block | None' = None, attachments: 'list[Attachment] | None' = None, thread_ts: 'str | None' = None, mrkdwn: 'bool' = True, replace_original: 'bool' = False, ephemeral: 'bool' = False) -> 'None' +``` + +
+ +A required, immediate response that confirms your app received the payload. + +
+ +### json + +```python +json() -> 'str' +``` + +
+ +No public documentation is available. + +
+ +### keys + +```python +keys() -> 'list[str]' +``` + +
+ +No public documentation is available. + +
+ +### to_dict + +```python +to_dict() -> 'dict[str, Any]' +``` + +
+ +No public documentation is available. + +
+ +## ResponseType + +**Class** + +```python +ResponseType(*values) +``` + +
+ +Types of messages that can be sent via `WebhookMessage`. + +
+ +## WebhookMessage + +**Class** + +```python +WebhookMessage(text: 'str | None' = None, attachments: 'Attachment | list[Attachment] | None' = None, blocks: 'Block | list[Block] | None' = None, response_type: 'ResponseType | str | None' = None, replace_original: 'bool | None' = None, delete_original: 'bool | None' = None, unfurl_links: 'bool | None' = None, unfurl_media: 'bool | None' = None, metadata: 'dict[str, Any] | None' = None, headers: 'dict[str, str] | None' = None) -> 'None' +``` + +
+ +Messages sent via the Slack `WebhookClient` takes different arguments than + those sent via the regular `WebClient`. + +See: [https://github.com/slackapi/python-slack-sdk/blob/7e71b73/slack_sdk/webhook/client.py#L28](https://github.com/slackapi/python-slack-sdk/blob/7e71b73/slack_sdk/webhook/client.py#L28) + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `text` | `str \| None` | markdown text to send in the message. If `blocks` are provided
then this is a fallback to display in notifications. | +| `attachments` | `Attachment \| list[Attachment] \| None` | a list of
[`Attachments`](/reference/python/attachments#attachment)
that form the secondary contents of the message (deprecated). | +| `blocks` | `Block \| list[Block] \| None` | a list of [`Blocks`](/reference/python/blocks) to form the contents
of the message instead of the contents of `text`. | +| `response_type` | `ResponseType \| str \| None` | one of `ResponseType.EPHEMERAL` or `ResponseType.IN_CHANNEL`.
Ephemeral messages are shown only to the requesting user whereas
"in-channel" messages are shown to all channel participants. | +| `replace_original` | `bool \| None` | when `True`, the message triggering this response will be
replaced by this message. Mutually exclusive with `delete_original`. | +| `delete_original` | `bool \| None` | when `True`, the original message triggering this response
will be deleted, and any content of this message will be posted as a
new message. Mutually exclusive with `replace_original`. | +| `unfurl_links` | `bool \| None` | if `True`, links in the message will be automatically
unfurled. | +| `unfurl_media` | `bool \| None` | if `True`, media from links (e.g. images) will
automatically unfurl. | +| `metadata` | `dict[str, Any] \| None` | additional metadata to attach to the message. | +| `headers` | `dict[str, str] \| None` | HTTP request headers to include with the message. | + +

Errors

+ +| Error | When | +| --- | --- | +| `InvalidUsageError` | when any of the passed fields fail validation. | + +
+ +### json + +```python +json() -> 'str' +``` + +
+ +No public documentation is available. + +
+ +### keys + +```python +keys() -> 'list[str]' +``` + +
+ +No public documentation is available. + +
+ +### to_dict + +```python +to_dict() -> 'dict[str, Any]' +``` + +
+ +No public documentation is available. + +
diff --git a/docs/versioned_docs/version-2.1.0/reference/python/modals.mdx b/docs/versioned_docs/version-2.1.0/reference/python/modals.mdx new file mode 100644 index 00000000..65518551 --- /dev/null +++ b/docs/versioned_docs/version-2.1.0/reference/python/modals.mdx @@ -0,0 +1,40 @@ +# Modals + +## Modal + +**Class** + +```python +Modal(title: 'TextLike', blocks: 'Block | list[Block]', close: 'TextLike | None' = None, submit: 'TextLike | None' = None, private_metadata: 'str | None' = None, callback_id: 'str | None' = None, clear_on_close: 'bool | None' = False, notify_on_close: 'bool | None' = False, external_id: 'str | None' = None, submit_disabled: 'bool | None' = False) -> 'None' +``` + +
+ +Kept for backwards compatibility - see + [`ModalView`](/reference/python/views#modalview) + +
+ +### json + +```python +json() -> 'str' +``` + +
+ +No public documentation is available. + +
+ +### to_dict + +```python +to_dict() -> 'dict[str, Any]' +``` + +
+ +No public documentation is available. + +
diff --git a/docs/versioned_docs/version-2.1.0/reference/python/objects.mdx b/docs/versioned_docs/version-2.1.0/reference/python/objects.mdx new file mode 100644 index 00000000..008c8e20 --- /dev/null +++ b/docs/versioned_docs/version-2.1.0/reference/python/objects.mdx @@ -0,0 +1,1260 @@ +# Composition objects + +## AlertLevel + +**Function** + +```python +AlertLevel(*args, **kwargs) +``` + +
+ +No public documentation is available. + +
+ +## AreaChart + +**Class** + +```python +AreaChart(series: 'list[DataSeries]', axis_config: 'AxisConfig') -> 'None' +``` + +
+ +A layered area chart, for use in a +[`DataVisualizationBlock`](/reference/python/blocks#datavisualizationblock). + +See: [https://docs.slack.dev/reference/block-kit/blocks/data-visualization-block](https://docs.slack.dev/reference/block-kit/blocks/data-visualization-block). + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `series` | `list[DataSeries]` | a list of between 1 and 12 uniquely named `DataSeries`
objects. | +| `axis_config` | `AxisConfig` | an `AxisConfig` defining the chart's category labels
and optional axis titles. | + +

Errors

+ +| Error | When | +| --- | --- | +| `InvalidUsageError` | if any of the provided arguments fail validation. | + +
+ +## AxisConfig + +**Class** + +```python +AxisConfig(categories: 'list[str]', x_label: 'str | None' = None, y_label: 'str | None' = None) -> 'None' +``` + +
+ +Category labels and optional axis titles for a bar, area, or line chart. + +See: [https://docs.slack.dev/reference/block-kit/blocks/data-visualization-block](https://docs.slack.dev/reference/block-kit/blocks/data-visualization-block). + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `categories` | `list[str]` | a list of between 1 and 20 unique category labels
(max 20 chars each). | +| `x_label` | `str \| None` | an optional title for the x-axis (max 50 chars). | +| `y_label` | `str \| None` | an optional title for the y-axis (max 50 chars). | + +

Errors

+ +| Error | When | +| --- | --- | +| `InvalidUsageError` | if any of the provided arguments fail validation. | + +
+ +## BarChart + +**Class** + +```python +BarChart(series: 'list[DataSeries]', axis_config: 'AxisConfig') -> 'None' +``` + +
+ +A grouped bar chart, for use in a +[`DataVisualizationBlock`](/reference/python/blocks#datavisualizationblock). + +See: [https://docs.slack.dev/reference/block-kit/blocks/data-visualization-block](https://docs.slack.dev/reference/block-kit/blocks/data-visualization-block). + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `series` | `list[DataSeries]` | a list of between 1 and 12 uniquely named `DataSeries`
objects. | +| `axis_config` | `AxisConfig` | an `AxisConfig` defining the chart's category labels
and optional axis titles. | + +

Errors

+ +| Error | When | +| --- | --- | +| `InvalidUsageError` | if any of the provided arguments fail validation. | + +
+ +## Chart + +**Value** + +```python +Chart +``` + +
+ +Represent a union type + +E.g. for int | str + +
+ +## ChartSegment + +**Class** + +```python +ChartSegment(label: 'str', value: 'int | float') -> 'None' +``` + +
+ +A labelled, positive-valued slice in a +[`PieChart`](/reference/python/objects#piechart). + +See: [https://docs.slack.dev/reference/block-kit/blocks/data-visualization-block](https://docs.slack.dev/reference/block-kit/blocks/data-visualization-block). + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `label` | `str` | the label for the segment (max 20 chars). | +| `value` | `int \| float` | the numeric value of the segment; must be greater than 0. | + +

Errors

+ +| Error | When | +| --- | --- | +| `InvalidUsageError` | if any of the provided arguments fail validation. | + +
+ +## ColumnSettings + +**Class** + +```python +ColumnSettings(align: 'ColumnAlignment | None' = None, is_wrapped: 'bool | None' = None) -> 'None' +``` + +
+ +An object that defines the settings for a column in a `Table` block. + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `align` | `ColumnAlignment \| None` | the alignment of the column, one of `left`, `center`, or `right`. | +| `is_wrapped` | `bool \| None` | whether the text in the column should be wrapped. | + +
+ +## Confirm + +**Class** + +```python +Confirm(*args, **kwargs) -> 'None' +``` + +
+ +Alias for `ConfirmationDialogue` to retain backwards compatibility. + +See: + [`ConfirmationDialogue`](/reference/python/objects#confirmationdialogue). + +
+ +### from_dict + +```python +from_dict(data: 'dict[str, Any]') -> 'ConfirmationDialogue' +``` + +
+ +Parse a Slack ``confirm`` composition object back into an instance. + +

Errors

+ +| Error | When | +| --- | --- | +| `MissingRequiredError` | if any of ``title``, ``text``, ``confirm``,
``deny`` is absent. | + +
+ +## ConfirmationDialogue + +**Class** + +```python +ConfirmationDialogue(title: 'TextLike', text: 'TextLike', confirm: 'TextLike', deny: 'TextLike') -> 'None' +``` + +
+ +An object that defines a dialog that provides a confirmation step +to any interactive element. This dialog will ask the user to confirm +their action by offering confirm and deny buttons. + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `title` | `TextLike` | the text heading presented at the top of the dialogue box (max 100 chars). | +| `text` | `TextLike` | the text explaining the decision being made by the user through
the dialogue box (max 300 chars). | +| `confirm` | `TextLike` | the text inside the confirmation button of the dialogue box (max 30 chars). | +| `deny` | `TextLike` | the text inside the deny button of the dialogue box (max 30 chars). | + +

Errors

+ +| Error | When | +| --- | --- | +| `InvalidUsageError` | if any of the arguments fail to pass validation checks. | + +
+ +### from_dict + +```python +from_dict(data: 'dict[str, Any]') -> 'ConfirmationDialogue' +``` + +
+ +Parse a Slack ``confirm`` composition object back into an instance. + +

Errors

+ +| Error | When | +| --- | --- | +| `MissingRequiredError` | if any of ``title``, ``text``, ``confirm``,
``deny`` is absent. | + +
+ +## ContainerWidth + +**Function** + +```python +ContainerWidth(*args, **kwargs) +``` + +
+ +No public documentation is available. + +
+ +## ConversationFilter + +**Class** + +```python +ConversationFilter(include: 'ConversationType | list[ConversationType] | None' = None, exclude_external_shared_channels: 'bool | None' = None, exclude_bot_users: 'bool | None' = None) -> 'None' +``` + +
+ +Provides a way to filter the list of options in a conversations select menu or +conversations multi-select menu. + +See: [https://api.slack.com/reference/block-kit/composition-objects#filter_conversations](https://api.slack.com/reference/block-kit/composition-objects#filter_conversations). + +At least one of the available arguments _must_ be provided. + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `include` | `ConversationType \| list[ConversationType] \| None` | Which types of conversations to include in the list.
One of more of `im`, `mpim`, `private`, `public`. | +| `exclude_external_shared_channels` | `bool \| None` | whether to remove shared public channels
from the list. See [https://api.slack.com/enterprise/shared-channels](https://api.slack.com/enterprise/shared-channels). | +| `exclude_bot_users` | `bool \| None` | whether to remove bot users from the list of conversations. | + +

Errors

+ +| Error | When | +| --- | --- | +| `InvalidUsageException` | in the event that the user provides none of `include`,
`exclude_external_shared_channels`, or `exclude_bot_users` arguments. | + +
+ +### from_dict + +```python +from_dict(data: 'dict[str, Any]') -> 'ConversationFilter' +``` + +
+ +Parse a Slack ``filter`` composition object. + +At least one of ``include``, ``exclude_external_shared_channels``, +or ``exclude_bot_users`` must be present; otherwise the underlying +constructor raises ``MissingRequiredError``. + +
+ +## DataPoint + +**Class** + +```python +DataPoint(label: 'str', value: 'int | float') -> 'None' +``` + +
+ +One labelled numeric point in an axis-based chart (a +[`BarChart`](/reference/python/objects#barchart), +[`AreaChart`](/reference/python/objects#areachart), or +[`LineChart`](/reference/python/objects#linechart)). + +See: [https://docs.slack.dev/reference/block-kit/blocks/data-visualization-block](https://docs.slack.dev/reference/block-kit/blocks/data-visualization-block). + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `label` | `str` | the label for the data point (max 20 chars); must match one
of the categories in the chart's `AxisConfig`. | +| `value` | `int \| float` | the numeric value of the data point. | + +

Errors

+ +| Error | When | +| --- | --- | +| `InvalidUsageError` | if any of the provided arguments fail validation. | + +
+ +## DataSeries + +**Class** + +```python +DataSeries(name: 'str', data: 'list[DataPoint]') -> 'None' +``` + +
+ +A named series containing between 1 and 20 chart data points. + +See: [https://docs.slack.dev/reference/block-kit/blocks/data-visualization-block](https://docs.slack.dev/reference/block-kit/blocks/data-visualization-block). + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `name` | `str` | the name of the series (max 20 chars). | +| `data` | `list[DataPoint]` | a list of between 1 and 20 `DataPoint` objects; there must
be exactly one point for every category in the chart's
`AxisConfig`. | + +

Errors

+ +| Error | When | +| --- | --- | +| `InvalidUsageError` | if any of the provided arguments fail validation. | + +
+ +## DispatchActionConfiguration + +**Class** + +```python +DispatchActionConfiguration(trigger_actions_on: 'str | list[str] | None' = None) -> 'None' +``` + +
+ +Determines when a plain-text input element will return a `block_action`s interaction payload. + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `trigger_actions_on` | `str \| list[str] \| None` | a list of strings representing interaction types that should return
a `block_actions` payload. One or both of `on_enter_pressed`, `on_character_entered`. | + +

Errors

+ +| Error | When | +| --- | --- | +| `InvalidUsageError` | if an invalid value is provided amongst the options for
`trigger_actions_on`. | + +
+ +### from_dict + +```python +from_dict(data: 'dict[str, Any]') -> 'DispatchActionConfiguration' +``` + +
+ +Parse a Slack ``dispatch_action_config`` composition object. + +
+ +## InputParameter + +**Class** + +```python +InputParameter(name: 'str', value: 'str') -> 'None' +``` + +
+ +Contains information about an input parameter. + +See [https://api.slack.com/automation/workflows#defining-input-parameters](https://api.slack.com/automation/workflows#defining-input-parameters). + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `name` | `str` | the name of the input parameter. | +| `value` | `str` | the value associated with the input parameter. | + +
+ +### from_dict + +```python +from_dict(data: 'dict[str, Any]') -> 'InputParameter' +``` + +
+ +Parse a Slack ``input_parameter`` composition object. + +
+ +## LineChart + +**Class** + +```python +LineChart(series: 'list[DataSeries]', axis_config: 'AxisConfig') -> 'None' +``` + +
+ +A line chart, for use in a +[`DataVisualizationBlock`](/reference/python/blocks#datavisualizationblock). + +See: [https://docs.slack.dev/reference/block-kit/blocks/data-visualization-block](https://docs.slack.dev/reference/block-kit/blocks/data-visualization-block). + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `series` | `list[DataSeries]` | a list of between 1 and 12 uniquely named `DataSeries`
objects. | +| `axis_config` | `AxisConfig` | an `AxisConfig` defining the chart's category labels
and optional axis titles. | + +

Errors

+ +| Error | When | +| --- | --- | +| `InvalidUsageError` | if any of the provided arguments fail validation. | + +
+ +## Markdown + +**Class** + +```python +Markdown(text: 'str', verbatim: 'bool' = False) -> 'None' +``` + +
+ +Convenience wrapper for `Text` with `type_=TextType.MARKDOWN`. + +`Markdown("_italic_", verbatim=True)` is equivalent to +`Text("_italic_", type_=TextType.MARKDOWN, verbatim=True)`. Anywhere a +`Text` or `TextLike` is accepted, a `Markdown` works because `Markdown` +is a subclass of `Text`. The rendered JSON is identical to the +equivalent `Text` call. + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `text` | `str` | the markdown-formatted text to render (1-3000 characters). | +| `verbatim` | `bool` | if `True`, links, channel names, and user names are
rendered verbatim rather than as Slack-style references. | + +

Errors

+ +| Error | When | +| --- | --- | +| `LengthError` | if the provided `text` is empty or too long. | + +
+ +### from_dict + +```python +from_dict(data: 'dict[str, Any]') -> 'Text' +``` + +
+ +Parse a Slack-shaped ``text`` composition object back into a ``Text``. + +Unknown fields are ignored so that future Slack additions do not +break round-tripping. + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `data` | `None` | a dict matching the Slack ``text`` composition-object shape,
e.g. ``{"type": "mrkdwn", "text": "hi", "verbatim": True}``. | + +### Returns + +| Type | Description | +| --- | --- | +| `None` | A ``Text`` instance. | + +

Errors

+ +| Error | When | +| --- | --- | +| `MissingRequiredError` | if ``data["text"]`` is absent. | +| `TypeMismatchError` | if ``data["type"]`` is not one of the
allowable ``TextType`` values. | + +
+ +### to_text + +```python +to_text(text: 'str | Text | None', force_plaintext: 'bool' = False, max_length: 'int | None' = None, allow_none: 'bool' = False) -> 'Text | None' +``` + +
+ +Coerces `str` or `Text` objects into `Text` objects. + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `text` | `None` | the `str` or `Text` object to ensure is in `Text` format. | +| `force_plaintext` | `None` | if `True`, forces the `str` or `Text` object
into a `Text` object with the type `TextType.PLAINTEXT`. | +| `max_length` | `None` | `text` will be checked against this length in addition
to the standard `Text` limit of 3000 characters. | +| `allow_none` | `None` | whether to accept `None` as a valid value for `text`.
The return type narrows based on this value:

- ``allow_none=False`` (the default) -> always returns ``Text``.
- ``allow_none=True`` -> returns ``Text \| None``. | + +
+ +### to_text_nonnull + +```python +to_text_nonnull(text: 'str | Text', force_plaintext: 'bool' = False, max_length: 'int | None' = None) -> 'Text' +``` + +
+ +Coerces `str` or `Text` objects into `Text` objects, but does not allow `None` values. + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `text` | `None` | the `str` or `Text` object to ensure is in `Text` format. | +| `force_plaintext` | `None` | if `True`, forces the `str` or `Text` object
into a `Text` object with the type `TextType.PLAINTEXT`. | +| `max_length` | `None` | `text` will be checked against this length in addition
to the standard `Text` limit of 3000 characters. | + +### Returns + +| Type | Description | +| --- | --- | +| `None` | A `Text` object created from the input. | + +

Errors

+ +| Error | When | +| --- | --- | +| `InvalidUsageError` | if the text length exceeds the specified max_length. | + +
+ +## Option + +**Class** + +```python +Option(text: 'TextLike', value: 'str', description: 'TextLike | None' = None, url: 'str | None' = None) -> 'None' +``` + +
+ +An object that represents a single selectable item in a select menu, multi-select +menu, checkbox group, radio button group, or overflow menu. + +See [https://api.slack.com/reference/block-kit/composition-objects#option](https://api.slack.com/reference/block-kit/composition-objects#option). + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `text` | `TextLike` | the text identifying the option (that the user will see). | +| `value` | `str` | the underlying value of that option (not seen by the user). | +| `description` | `TextLike \| None` | a more detailed explanation of what the option means (user-facing). | +| `url` | `str \| None` | a URL to load in the user's browser when the option is clicked.
Only available in `OverflowMenus`. | + +

Errors

+ +| Error | When | +| --- | --- | +| `InvalidUsageError` | when any of the provided arguments fail validation. | + +
+ +### from_dict + +```python +from_dict(data: 'dict[str, Any]') -> 'Option' +``` + +
+ +Parse a Slack ``option`` composition object back into an ``Option``. + +

Errors

+ +| Error | When | +| --- | --- | +| `MissingRequiredError` | if ``text`` or ``value`` is absent. | + +
+ +## OptionGroup + +**Class** + +```python +OptionGroup(label: 'TextLike', options: 'list[Option]') -> 'None' +``` + +
+ +Provides a way to group options in a select menu or multi-select menu. + +See [https://api.slack.com/reference/block-kit/composition-objects#option_group](https://api.slack.com/reference/block-kit/composition-objects#option_group). + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `label` | `TextLike` | a label shown above the group of options. | +| `options` | `list[Option]` | a list of `Option` objects that will form the contents of the group (max 100). | + +

Errors

+ +| Error | When | +| --- | --- | +| `InvalidUsageError` | if no options are provided or the label is not valid. | + +
+ +### from_dict + +```python +from_dict(data: 'dict[str, Any]') -> 'OptionGroup' +``` + +
+ +Parse a Slack ``option_group`` composition object. + +

Errors

+ +| Error | When | +| --- | --- | +| `MissingRequiredError` | if ``label`` or ``options`` is absent. | + +
+ +## PieChart + +**Class** + +```python +PieChart(segments: 'list[ChartSegment]') -> 'None' +``` + +
+ +A pie chart containing between 1 and 12 segments, for use in a +[`DataVisualizationBlock`](/reference/python/blocks#datavisualizationblock). + +See: [https://docs.slack.dev/reference/block-kit/blocks/data-visualization-block](https://docs.slack.dev/reference/block-kit/blocks/data-visualization-block). + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `segments` | `list[ChartSegment]` | a list of between 1 and 12 `ChartSegment` objects. | + +

Errors

+ +| Error | When | +| --- | --- | +| `InvalidUsageError` | if any of the provided arguments fail validation. | + +
+ +## PlainText + +**Class** + +```python +PlainText(text: 'str', emoji: 'bool' = False) -> 'None' +``` + +
+ +Convenience wrapper for `Text` with `type_=TextType.PLAINTEXT`. + +`PlainText("Hi", emoji=True)` is equivalent to +`Text("Hi", type_=TextType.PLAINTEXT, emoji=True)`. Anywhere a `Text` or +`TextLike` is accepted, a `PlainText` works because `PlainText` is a +subclass of `Text`. The rendered JSON is identical to the equivalent +`Text` call. + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `text` | `str` | the text to render (1-3000 characters). | +| `emoji` | `bool` | if `True`, emoji (e.g. `:smile:`) are escaped into Unicode. | + +

Errors

+ +| Error | When | +| --- | --- | +| `LengthError` | if the provided `text` is empty or too long. | + +
+ +### from_dict + +```python +from_dict(data: 'dict[str, Any]') -> 'Text' +``` + +
+ +Parse a Slack-shaped ``text`` composition object back into a ``Text``. + +Unknown fields are ignored so that future Slack additions do not +break round-tripping. + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `data` | `None` | a dict matching the Slack ``text`` composition-object shape,
e.g. ``{"type": "mrkdwn", "text": "hi", "verbatim": True}``. | + +### Returns + +| Type | Description | +| --- | --- | +| `None` | A ``Text`` instance. | + +

Errors

+ +| Error | When | +| --- | --- | +| `MissingRequiredError` | if ``data["text"]`` is absent. | +| `TypeMismatchError` | if ``data["type"]`` is not one of the
allowable ``TextType`` values. | + +
+ +### to_text + +```python +to_text(text: 'str | Text | None', force_plaintext: 'bool' = False, max_length: 'int | None' = None, allow_none: 'bool' = False) -> 'Text | None' +``` + +
+ +Coerces `str` or `Text` objects into `Text` objects. + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `text` | `None` | the `str` or `Text` object to ensure is in `Text` format. | +| `force_plaintext` | `None` | if `True`, forces the `str` or `Text` object
into a `Text` object with the type `TextType.PLAINTEXT`. | +| `max_length` | `None` | `text` will be checked against this length in addition
to the standard `Text` limit of 3000 characters. | +| `allow_none` | `None` | whether to accept `None` as a valid value for `text`.
The return type narrows based on this value:

- ``allow_none=False`` (the default) -> always returns ``Text``.
- ``allow_none=True`` -> returns ``Text \| None``. | + +
+ +### to_text_nonnull + +```python +to_text_nonnull(text: 'str | Text', force_plaintext: 'bool' = False, max_length: 'int | None' = None) -> 'Text' +``` + +
+ +Coerces `str` or `Text` objects into `Text` objects, but does not allow `None` values. + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `text` | `None` | the `str` or `Text` object to ensure is in `Text` format. | +| `force_plaintext` | `None` | if `True`, forces the `str` or `Text` object
into a `Text` object with the type `TextType.PLAINTEXT`. | +| `max_length` | `None` | `text` will be checked against this length in addition
to the standard `Text` limit of 3000 characters. | + +### Returns + +| Type | Description | +| --- | --- | +| `None` | A `Text` object created from the input. | + +

Errors

+ +| Error | When | +| --- | --- | +| `InvalidUsageError` | if the text length exceeds the specified max_length. | + +
+ +## RawNumber + +**Class** + +```python +RawNumber(value: 'int | float', text: 'str') -> 'None' +``` + +
+ +A numeric cell for a +[`DataTableBlock`](/reference/python/blocks#datatableblock). + +See: [https://docs.slack.dev/reference/block-kit/blocks/data-table-block](https://docs.slack.dev/reference/block-kit/blocks/data-table-block). + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `value` | `int \| float` | the numeric value Slack uses for sorting and display. | +| `text` | `str` | the non-empty text Slack displays in the cell. | + +

Errors

+ +| Error | When | +| --- | --- | +| `InvalidUsageError` | if any of the provided arguments fail validation. | + +
+ +## RawText + +**Class** + +```python +RawText(text: 'str', emoji: 'bool' = False) -> 'None' +``` + +
+ +An object containing some text, formatted as `raw_text` for use in +`Table` blocks. + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `text` | `str` | the text to be rendered in a message. | +| `emoji` | `bool` | only usable with `TextType.PLAINTEXT`, if True: emoji will be
escaped into text format (e.g. `:smile:`). | + +

Errors

+ +| Error | When | +| --- | --- | +| `InvalidUsageException` | if the provided `text` fails validation. | + +
+ +## SlackFile + +**Class** + +```python +SlackFile(url: 'str | None', id: 'str | None') -> 'None' +``` + +
+ +Defines an object containing Slack file information to be used in an image + block or image element. + +This file must be an image and you must provide either the URL or ID (not both). + +See: [https://api.slack.com/reference/block-kit/composition-objects#slack_file](https://api.slack.com/reference/block-kit/composition-objects#slack_file). + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `url` | `str \| None` | the URL can be the `url_private` or the `permalink` of the Slack file
(only one of `url` or `id` can be provided). | +| `id` | `str \| None` | the Slack ID of the file
(only one of `url` or `id` can be provided). | + +

Errors

+ +| Error | When | +| --- | --- | +| `InvalidUsageError` | if both `url` and `id` are provided | + +
+ +### from_dict + +```python +from_dict(data: 'dict[str, Any]') -> 'SlackFile' +``` + +
+ +Parse a Slack ``slack_file`` composition object. + +
+ +## SlackIcon + +**Class** + +```python +SlackIcon(name: 'SlackIconName') -> 'None' +``` + +
+ +A named Slack-provided icon for a +[`CardBlock`](/reference/python/blocks#cardblock). + +See: [https://docs.slack.dev/reference/block-kit/blocks/card-block](https://docs.slack.dev/reference/block-kit/blocks/card-block). + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `name` | `SlackIconName` | the name of a Slack-provided icon, e.g. `bot` or `rocket`
(see `SlackIconName` for the full list of valid names). | + +

Errors

+ +| Error | When | +| --- | --- | +| `TypeMismatchError` | if `name` is not a recognised Slack icon name. | + +
+ +## SlackIconName + +**Function** + +```python +SlackIconName(*args, **kwargs) +``` + +
+ +No public documentation is available. + +
+ +## TaskStatus + +**Function** + +```python +TaskStatus(*args, **kwargs) +``` + +
+ +No public documentation is available. + +
+ +## Text + +**Class** + +```python +Text(text: 'str', type_: 'TextType' = , emoji: 'bool' = False, verbatim: 'bool' = False) -> 'None' +``` + +
+ +An object containing some text, formatted either as `plain_text` or using +Slack's `mrkdwn`. + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `text` | `str` | the text to be rendered in a message (max 3000 characters). | +| `type_` | `TextType` | either `TextType.MARKDOWN` or `TextType.PLAINTEXT`. | +| `emoji` | `bool` | only usable with `TextType.PLAINTEXT`, if True: emoji will be
escaped into text format (e.g. `:smile:`). | +| `verbatim` | `bool` | only usable with `TextType.MARKDOWN`, if True: links, channel
names, user names will not automatically be rendered as links. | + +

Errors

+ +| Error | When | +| --- | --- | +| `InvalidUsageException` | if the provided `text` fails validation. | + +
+ +### from_dict + +```python +from_dict(data: 'dict[str, Any]') -> 'Text' +``` + +
+ +Parse a Slack-shaped ``text`` composition object back into a ``Text``. + +Unknown fields are ignored so that future Slack additions do not +break round-tripping. + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `data` | `dict[str, Any]` | a dict matching the Slack ``text`` composition-object shape,
e.g. ``{"type": "mrkdwn", "text": "hi", "verbatim": True}``. | + +### Returns + +| Type | Description | +| --- | --- | +| `Text` | A ``Text`` instance. | + +

Errors

+ +| Error | When | +| --- | --- | +| `MissingRequiredError` | if ``data["text"]`` is absent. | +| `TypeMismatchError` | if ``data["type"]`` is not one of the
allowable ``TextType`` values. | + +
+ +### to_text + +```python +to_text(text: 'str | Text | None', force_plaintext: 'bool' = False, max_length: 'int | None' = None, allow_none: 'bool' = False) -> 'Text | None' +``` + +
+ +Coerces `str` or `Text` objects into `Text` objects. + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `text` | `str \| Text \| None` | the `str` or `Text` object to ensure is in `Text` format. | +| `force_plaintext` | `bool` | if `True`, forces the `str` or `Text` object
into a `Text` object with the type `TextType.PLAINTEXT`. | +| `max_length` | `int \| None` | `text` will be checked against this length in addition
to the standard `Text` limit of 3000 characters. | +| `allow_none` | `bool` | whether to accept `None` as a valid value for `text`.
The return type narrows based on this value:

- ``allow_none=False`` (the default) -> always returns ``Text``.
- ``allow_none=True`` -> returns ``Text \| None``. | + +
+ +### to_text_nonnull + +```python +to_text_nonnull(text: 'str | Text', force_plaintext: 'bool' = False, max_length: 'int | None' = None) -> 'Text' +``` + +
+ +Coerces `str` or `Text` objects into `Text` objects, but does not allow `None` values. + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `text` | `str \| Text` | the `str` or `Text` object to ensure is in `Text` format. | +| `force_plaintext` | `bool` | if `True`, forces the `str` or `Text` object
into a `Text` object with the type `TextType.PLAINTEXT`. | +| `max_length` | `int \| None` | `text` will be checked against this length in addition
to the standard `Text` limit of 3000 characters. | + +### Returns + +| Type | Description | +| --- | --- | +| `Text` | A `Text` object created from the input. | + +

Errors

+ +| Error | When | +| --- | --- | +| `InvalidUsageError` | if the text length exceeds the specified max_length. | + +
+ +## TextType + +**Class** + +```python +TextType(*values) +``` + +
+ +Allowable types for Slack Text objects. + +MARKDOWN: traditional markdown formatting, see + [https://api.slack.com/reference/surfaces/formatting#basic-formatting](https://api.slack.com/reference/surfaces/formatting#basic-formatting) +PLAINTEXT: simple Unicode text with no formatting (e.g. bold) features. + +N.B: some usages of Text objects only allow the `PLAINTEXT` variety. + +
+ +## Trigger + +**Class** + +```python +Trigger(url: 'str', customizable_input_parameters: 'InputParameter | list[InputParameter] | None') -> 'None' +``` + +
+ +Contains information about a trigger. + +See: [https://api.slack.com/automation/triggers](https://api.slack.com/automation/triggers). + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `url` | `str` | a link trigger URL, see
[https://api.slack.com/automation/triggers/link](https://api.slack.com/automation/triggers/link) | +| `customizable_input_parameters` | `InputParameter \| list[InputParameter] \| None` | a list of `InputParameter` objects
which map to those parameters defined on the Workflow in
which they are provided. | + +

Errors

+ +| Error | When | +| --- | --- | +| `InvalidUsageError` | when any of the items in
`customizable_input_parameters` is not a valid `InputParameter`. | + +
+ +### from_dict + +```python +from_dict(data: 'dict[str, Any]') -> 'Trigger' +``` + +
+ +Parse a Slack ``trigger`` composition object. + +
+ +## Workflow + +**Class** + +```python +Workflow(trigger: 'Trigger') -> 'None' +``` + +
+ +Contains information about a workflow. + +See [https://api.slack.com/automation/workflows](https://api.slack.com/automation/workflows). + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `trigger` | `Trigger` | a `Trigger` object that will initiate the workflow. | + +
+ +### from_dict + +```python +from_dict(data: 'dict[str, Any]') -> 'Workflow' +``` + +
+ +Parse a Slack ``workflow`` composition object. + +
+ +### from_url + +```python +from_url(url: 'str', **input_parameters: 'str') -> 'Workflow' +``` + +
+ +Build a `Workflow` from a trigger URL and input parameters in one call. + +``Workflow.from_url(url, a='1', b='2')`` is equivalent to:: + + Workflow( + trigger=Trigger( + url=url, + customizable_input_parameters=[ + InputParameter(name='a', value='1'), + InputParameter(name='b', value='2'), + ], + ), + ) + +When no input parameters are supplied, the resulting trigger has +``customizable_input_parameters=None`` (the key is omitted from JSON). + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `url` | `str` | the link trigger URL. | +| `**input_parameters` | `str` | zero or more ``name=value`` pairs that become
``InputParameter`` entries on the trigger. | + +### Returns + +| Type | Description | +| --- | --- | +| `Workflow` | A new ``Workflow`` instance. | + +
diff --git a/docs/versioned_docs/version-2.1.0/reference/python/rich_text.mdx b/docs/versioned_docs/version-2.1.0/reference/python/rich_text.mdx new file mode 100644 index 00000000..dce99c71 --- /dev/null +++ b/docs/versioned_docs/version-2.1.0/reference/python/rich_text.mdx @@ -0,0 +1,330 @@ +# Rich text + +## RichText + +**Class** + +```python +RichText(text: 'str', bold: 'bool | None' = None, italic: 'bool | None' = None, strike: 'bool | None' = None, code: 'bool | None' = None) -> 'None' +``` + +
+ +The core unit of the rich text API. Allows for the formatting of text + with visual styles like bolding, italics and strikethroughs. + Combined with higher-level containers like `RichTextSection`, + `RichText` can be used to create complicated and deeply nested + rich text within Slack messages. + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `text` | `str` | the text content to render. | +| `bold` | `bool \| None` | whether to render the given text in bold font. | +| `italic` | `bool \| None` | whether to render the given text in italics. | +| `strike` | `bool \| None` | whether to render the given text with a "strikethrough". | +| `code` | `bool \| None` | whether to render the given text as an inline code snippet
(monospaced). | + +
+ +## RichTextChannel + +**Class** + +```python +RichTextChannel(channel_id: 'str', bold: 'bool | None' = None, italic: 'bool | None' = None, strike: 'bool | None' = None, highlight: 'bool | None' = None, client_highlight: 'bool | None' = None, unlink: 'bool | None' = None) -> 'None' +``` + +
+ +Rich text rendering of a Slack channel (e.g. #general). + +See: [https://api.slack.com/reference/block-kit/blocks#channel-element-type](https://api.slack.com/reference/block-kit/blocks#channel-element-type) + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `channel_id` | `str` | the ID of the channel to render. You can get this from
the channel settings or the URL (if using Slack in the browser). | +| `bold` | `bool \| None` | whether to render the given channel in bold font. | +| `italic` | `bool \| None` | whether to render the given channel in italics. | +| `strike` | `bool \| None` | whether to render the given channel with a "strikethrough". | +| `highlight` | `bool \| None` | whether to give the channel a distinct highlight when rendered. | +| `client_highlight` | `bool \| None` | a Slack-internal rendering hint accompanying
mention-style elements. Rarely needed by app developers; pass
``None`` (the default) unless you have a specific reason to set
it. | +| `unlink` | `bool \| None` | whether to remove the link to the channel from the channel when
rendered. | + +
+ +## RichTextCodeBlock + +**Class** + +```python +RichTextCodeBlock(elements: 'RichTextElement | list[RichTextElement]', border: 'int | None' = None) -> 'None' +``` + +
+ +A rich text element for representing blocks of code in + [`RichTextBlocks`](/reference/python/blocks#richtextblock). + +This is roughly equivalent to the triple-backtick ```code``` syntax in markdown. + +See: [https://api.slack.com/reference/block-kit/blocks#rich_text_preformatted](https://api.slack.com/reference/block-kit/blocks#rich_text_preformatted). + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `elements` | `RichTextElement \| list[RichTextElement]` | one or more rich text primitive objexts
(e.g. [`RichText`](/reference/python/rich_text#richtext)). | +| `border` | `int \| None` | the thickness (in pixels) of the border around the code block. | + +

Errors

+ +| Error | When | +| --- | --- | +| `InvalidUsageError` | if any of the items in `elements` aren't valid rich
text elements. | + +
+ +## RichTextElement + +**Class** + +```python +RichTextElement(type_: 'RichTextElementType') -> 'None' +``` + +
+ +Abstract base class for all rich text element classes. + +These are the primitives that form the basis of rich text objects and +the [`RichTextBlock`](/reference/python/blocks#richtextblock). + +
+ +## RichTextEmoji + +**Class** + +```python +RichTextEmoji(name: 'str') -> 'None' +``` + +
+ +A rich text element for displaying an emoji. + +The emoji can either be one built in to Slack or a custom workspace emoji. + +See: [https://api.slack.com/reference/block-kit/blocks#emoji-element-type](https://api.slack.com/reference/block-kit/blocks#emoji-element-type) + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `name` | `str` | the unique name of the emoji to represent e.g. "wave". | + +

Errors

+ +| Error | When | +| --- | --- | +| `InvalidUsageError` | if the emoji `name` provided is empty. | + +
+ +## RichTextLink + +**Class** + +```python +RichTextLink(url: 'str', text: 'str | None' = None, unsafe: 'bool | None' = None, bold: 'bool | None' = None, italic: 'bool | None' = None, strike: 'bool | None' = None, code: 'bool | None' = None) -> 'None' +``` + +
+ +A rich text primitive to display links in text. + +See: [https://api.slack.com/reference/block-kit/blocks#link-element-type](https://api.slack.com/reference/block-kit/blocks#link-element-type) + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `url` | `str` | the url which the link will point to. | +| `text` | `str \| None` | the text to render with the link. If not provided, the raw URL
will be used. | +| `unsafe` | `bool \| None` | whether the link is "safe". | +| `bold` | `bool \| None` | whether to render the given text in bold font. | +| `italic` | `bool \| None` | whether to render the given text in italics. | +| `strike` | `bool \| None` | whether to render the given text with a "strikethrough". | +| `code` | `bool \| None` | whether to render the given text as an inline code snippet
(monospaced). | + +
+ +## RichTextList + +**Class** + +```python +RichTextList(style: 'str | ListType', elements: 'RichTextSection | list[RichTextSection]', indent: 'int | None' = None, offset: 'int | None' = 0, border: 'int | None' = 0) -> 'None' +``` + +
+ +Renders to a HTML list containing rich text elements. + +See: [https://api.slack.com/reference/block-kit/blocks#rich_text_list](https://api.slack.com/reference/block-kit/blocks#rich_text_list). + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `style` | `str \| ListType` | one of `ListType.BULLET` or `ListType.ORDERED`. | +| `elements` | `RichTextSection \| list[RichTextSection]` | a list of (possibly nested) `RichTextSection` elements.
Each object in this list will be rendered as a list item. | +| `indent` | `int \| None` | indent (in pixels) of each list item. | +| `offset` | `int \| None` | offset (in pixels) of each list item. | +| `border` | `int \| None` | thickness (in pixels) of the (optional) border around the list. | + +

Errors

+ +| Error | When | +| --- | --- | +| `InvalidUsageError` | if style is not a valid `ListType` or any of the
items in `elements` isn't a valid `RichTextSection`. | + +
+ +## RichTextObject + +**Class** + +```python +RichTextObject(type_: 'RichTextObjectType') -> 'None' +``` + +
+ +Abstract class housing shared functionality of RichTextObjects. + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `type_` | `RichTextObjectType` | the type of rich text object this class is, from
`RichTextObjectType`. | + +
+ +## RichTextQuote + +**Class** + +```python +RichTextQuote(elements: 'RichTextElement | list[RichTextElement]', border: 'int | None' = None) -> 'None' +``` + +
+ +A rich text object for representing a block quote. + +Block quotes are presented with a vertical bar to the left hand side of + the text. + +See: [https://api.slack.com/reference/block-kit/blocks#rich_text_quote](https://api.slack.com/reference/block-kit/blocks#rich_text_quote) + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `elements` | `RichTextElement \| list[RichTextElement]` | one or more rich text primitive objexts
(e.g. [`RichText`](/reference/python/rich_text#richtext)). | +| `border` | `int \| None` | the thickness (in pixels) of the border around the code block. | + +
+ +## RichTextSection + +**Class** + +```python +RichTextSection(elements: 'RichTextElement | list[RichTextElement]') -> 'None' +``` + +
+ +The most basic rich text container object, which takes rich text elements + and renders them when `RichTextSection` is passed to a + [`RichTextBlock`](/reference/python/blocks#richtextblock). + +See: [https://api.slack.com/reference/block-kit/blocks#rich_text_section](https://api.slack.com/reference/block-kit/blocks#rich_text_section). + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `elements` | `RichTextElement \| list[RichTextElement]` | one or more rich text elements that will form the content of the section.
e.g. `RichText`, `RichTextLink`. | + +

Errors

+ +| Error | When | +| --- | --- | +| `InvalidUsageError` | if any of the items passed to `elements` isn't a valid
`RichTextObject`. | + +
+ +## RichTextUser + +**Class** + +```python +RichTextUser(user_id: 'str', bold: 'bool | None' = None, italic: 'bool | None' = None, strike: 'bool | None' = None, highlight: 'bool | None' = None, client_highlight: 'bool | None' = None, unlink: 'bool | None' = None) -> 'None' +``` + +
+ +Rich text element for representing users in + [`RichTextBlocks`](/reference/python/blocks#richtextblock). + +See: [https://api.slack.com/reference/block-kit/blocks#user-element-type](https://api.slack.com/reference/block-kit/blocks#user-element-type). + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `user_id` | `str` | the Slack ID of the user in question, you can get these
from users' profiles or Slack client requests. | +| `bold` | `bool \| None` | whether to render the given user in bold font. | +| `italic` | `bool \| None` | whether to render the given user in italics. | +| `strike` | `bool \| None` | whether to render the given user with a "strikethrough". | +| `highlight` | `bool \| None` | whether to give the user a distinct highlight when rendered. | +| `client_highlight` | `bool \| None` | a Slack-internal rendering hint accompanying
mention-style elements. Rarely needed by app developers; pass
``None`` (the default) unless you have a specific reason to set
it. | +| `unlink` | `bool \| None` | whether to remove the link to the user from the channel when
rendered. | + +
+ +## RichTextUserGroup + +**Class** + +```python +RichTextUserGroup(user_group_id: 'str', bold: 'bool | None' = None, italic: 'bool | None' = None, strike: 'bool | None' = None, highlight: 'bool | None' = None, client_highlight: 'bool | None' = None, unlink: 'bool | None' = None) -> 'None' +``` + +
+ +Rich text element for representing groups of users in + [`RichTextBlocks`](/reference/python/blocks#richtextblock)`. + +See: [https://api.slack.com/reference/block-kit/blocks#user-element-type](https://api.slack.com/reference/block-kit/blocks#user-element-type). + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `user_group_id` | `str` | the Slack ID of the user group being represented. | +| `bold` | `bool \| None` | whether to render the given user in bold font. | +| `italic` | `bool \| None` | whether to render the given user in italics. | +| `strike` | `bool \| None` | whether to render the given user with a "strikethrough". | +| `highlight` | `bool \| None` | whether to give the user a distinct highlight when rendered. | +| `client_highlight` | `bool \| None` | a Slack-internal rendering hint accompanying
mention-style elements. Rarely needed by app developers; pass
``None`` (the default) unless you have a specific reason to set
it. | +| `unlink` | `bool \| None` | whether to remove the link to the user from the channel when
rendered. | + +
diff --git a/docs/versioned_docs/version-2.1.0/reference/python/views.mdx b/docs/versioned_docs/version-2.1.0/reference/python/views.mdx new file mode 100644 index 00000000..40b9b370 --- /dev/null +++ b/docs/versioned_docs/version-2.1.0/reference/python/views.mdx @@ -0,0 +1,131 @@ +# Views + +## HomeTabView + +**Class** + +```python +HomeTabView(blocks: 'Block | list[Block]', private_metadata: 'str | None' = None, callback_id: 'str | None' = None, external_id: 'str | None' = None) -> 'None' +``` + +
+ +`HomeTabViews` are used with the `views.publish` Web API method. + +See: [https://api.slack.com/reference/surfaces/views#home](https://api.slack.com/reference/surfaces/views#home). + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `blocks` | `Block \| list[Block]` | A list of blocks that defines the content of the view (max 100). | +| `private_metadata` | `str \| None` | a string (max 3000 chars) that will be sent to your app
in `view_submission`. | +| `callback_id` | `str \| None` | A string that will identify submissions of this view. | +| `external_id` | `str \| None` | A custom identifier that is unique within the views of a
given Slack team. | + +
+ +### to_dict + +```python +to_dict() -> 'dict[str, Any]' +``` + +
+ +No public documentation is available. + +
+ +## ModalView + +**Class** + +```python +ModalView(title: 'TextLike', blocks: 'Block | list[Block]', close: 'TextLike | None' = None, submit: 'TextLike | None' = None, private_metadata: 'str | None' = None, callback_id: 'str | None' = None, clear_on_close: 'bool | None' = False, notify_on_close: 'bool | None' = False, external_id: 'str | None' = None, submit_disabled: 'bool | None' = False) -> 'None' +``` + +
+ +Modal views are used with the `views.open`, `views.update` and `views.push` + Slack Web API methods. + +See: [https://api.slack.com/reference/surfaces/views#modal](https://api.slack.com/reference/surfaces/views#modal) + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `title` | `TextLike` | heading that appears at the top left of the view. | +| `blocks` | `Block \| list[Block]` | a list of blocks (max 100) that define the content of the view. | +| `close` | `TextLike \| None` | the text of the close button (max 24 chars) in the view.
Must be `Text.PLAINTEXT`. | +| `submit` | `TextLike \| None` | the text of the submit button (max 24 chars) in the view.
Must be `Text.PLAINTEXT`. | +| `private_metadata` | `str \| None` | a string (max 3000 chars) that will be sent to your app
in `view_submission`. | +| `callback_id` | `str \| None` | A string that will identify submissions of this view. | +| `clear_on_close` | `bool \| None` | when `True` all views in the model will be cleared when
it is closed. | +| `notify_on_close` | `bool \| None` | when `True` a `view_closed` event will be sent when the
modal is closed. | +| `external_id` | `str \| None` | A custom identifier that is unique within the views of a
given Slack team. | +| `submit_disabled` | `bool \| None` | when `True` disabled submitting the form until one or
more inputs have been provided. Used only for
[`configuaration models`](https://api.slack.com/reference/workflows/configuration-view). | + +
+ +### to_dict + +```python +to_dict() -> 'dict[str, Any]' +``` + +
+ +No public documentation is available. + +
+ +## View + +**Class** + +```python +View(type: 'ViewType', blocks: 'Block | list[Block]', private_metadata: 'str | None' = None, callback_id: 'str | None' = None, external_id: 'str | None' = None) -> 'None' +``` + +
+ +Base class for Slack app surfaces -- the visual areas an app can populate +with blocks. Concrete subclasses are +[`ModalView`](/reference/python/views#modalview) (for +pop-up modals) and +[`HomeTabView`](/reference/python/views#hometabview) +(for the per-user App Home tab). + +See: [https://api.slack.com/reference/surfaces/views](https://api.slack.com/reference/surfaces/views). + +

Arguments

+ +| Argument | Type | Description | +| --- | --- | --- | +| `type` | `ViewType` | one of the `ViewType` enum members. Concrete subclasses set
this for you; in practice you should construct `ModalView` or
`HomeTabView` rather than `View` directly. | +| `blocks` | `Block \| list[Block]` | 1-100 blocks that make up the contents of the view. | +| `private_metadata` | `str \| None` | a string (max 3000 characters) that will be sent
back to your app in any view-related interaction payloads.
Useful for stashing per-view server-side context. | +| `callback_id` | `str \| None` | an identifier (max 255 characters) for distinguishing
this view's submissions from other views your app exposes. | +| `external_id` | `str \| None` | a custom identifier that is unique within the views of
a given Slack team. Slack uses it to find views your app has
previously published. | + +

Errors

+ +| Error | When | +| --- | --- | +| `InvalidUsageError` | if any of the validation checks fail. | + +
+ +### to_dict + +```python +to_dict() -> 'dict[str, Any]' +``` + +
+ +No public documentation is available. + +
diff --git a/docs/versioned_docs/version-2.1.0/reference/typescript/blocks.md b/docs/versioned_docs/version-2.1.0/reference/typescript/blocks.md new file mode 100644 index 00000000..6e9425b2 --- /dev/null +++ b/docs/versioned_docs/version-2.1.0/reference/typescript/blocks.md @@ -0,0 +1,807 @@ +--- +toc_min_heading_level: 2 +toc_max_heading_level: 2 +--- + +# Blocks + +Block factories for messages, modals, and App Home tabs. + +Every factory accepts camelCase input, returns Slack's snake_case wire shape, +and validates the result unless `settings.validate` is `false`. + +## actionsBlock() + +> **actionsBlock**(`input`, `settings?`): [`SlackWire`](utilities.md#slackwire)<`ActionsBlock`> + +Creates a row of interactive elements. + +### Input fields + +Up to 25 buttons, select menus, or other action elements. + +| Input field | Type | Description | +| ------ | ------ | ------ | +| `blockId?` | `string` | Deterministic identifier, up to 255 characters. | +| `elements` | [`JsonObject`](utilities.md#jsonobject)[] | Interactive elements displayed in the row. | + +### Settings + +| Setting | Type | Description | +| ------ | ------ | ------ | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`SlackWire`](utilities.md#slackwire)<`ActionsBlock`> + +A validated Slack `actions` block. + +### Throws + +InvalidUsageError when an element is unsupported or the limit is exceeded. + +*** + +## alertBlock() + +> **alertBlock**(`input`, `settings?`): [`SlackObject`](utilities.md#slackobject)<`"alert"`> + +Creates a severity-labelled notice for a modal. + +### Input fields + +Alert content, severity, and optional block identifier. + +| Input field | Type | Description | +| ------ | ------ | ------ | +| `blockId?` | `string` | Deterministic identifier, up to 255 characters. | +| `level?` | [`AlertLevel`](#alertlevel) | Visual severity. Defaults to `default`. | +| `text` | [`TextLike`](objects.md#textlike) | Alert copy. Strings are converted to mrkdwn text. | + +### Settings + +| Setting | Type | Description | +| ------ | ------ | ------ | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`SlackObject`](utilities.md#slackobject)<`"alert"`> + +A validated Slack `alert` block. + +### Throws + +InvalidUsageError when a field violates Slack's constraints. + +*** + +## AlertLevel + +> **AlertLevel** = `"default"` \| `"info"` \| `"warning"` \| `"error"` \| `"success"` + +Severity shown by an alert block. + +*** + +## cardBlock() + +> **cardBlock**(`input`, `settings?`): [`SlackObject`](utilities.md#slackobject)<`"card"`> + +Creates a compact content card with text, imagery, and optional actions. + +### Input fields + +Card fields. At least one visible content field must be supplied. + +| Input field | Type | Description | +| ------ | ------ | ------ | +| `actions?` | [`JsonObject`](utilities.md#jsonobject)[] | Up to three button actions. | +| `blockId?` | `string` | Deterministic identifier, up to 255 characters. | +| `body?` | [`TextLike`](objects.md#textlike) | Main card copy, up to 200 characters. | +| `heroImage?` | [`JsonObject`](utilities.md#jsonobject) | Large image displayed above the card content. | +| `icon?` | [`JsonObject`](utilities.md#jsonobject) | Small image displayed beside the card heading. | +| `slackIcon?` | [`JsonObject`](utilities.md#jsonobject) | Slack-hosted icon created with `slackIcon`. | +| `subtext?` | [`TextLike`](objects.md#textlike) | Supporting copy displayed below the body. | +| `subtitle?` | [`TextLike`](objects.md#textlike) | Secondary heading, up to 150 characters. | +| `title?` | [`TextLike`](objects.md#textlike) | Primary heading, up to 150 characters. | + +### Settings + +| Setting | Type | Description | +| ------ | ------ | ------ | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`SlackObject`](utilities.md#slackobject)<`"card"`> + +A validated Slack `card` block. + +### Throws + +InvalidUsageError when content is missing or exceeds Slack's limits. + +*** + +## CardBlockInput + +Fields accepted by [cardBlock](#cardblock). + +### Properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `actions?` | [`JsonObject`](utilities.md#jsonobject)[] | Up to three button actions. | +| `blockId?` | `string` | Deterministic identifier, up to 255 characters. | +| `body?` | [`TextLike`](objects.md#textlike) | Main card copy, up to 200 characters. | +| `heroImage?` | [`JsonObject`](utilities.md#jsonobject) | Large image displayed above the card content. | +| `icon?` | [`JsonObject`](utilities.md#jsonobject) | Small image displayed beside the card heading. | +| `slackIcon?` | [`JsonObject`](utilities.md#jsonobject) | Slack-hosted icon created with `slackIcon`. | +| `subtext?` | [`TextLike`](objects.md#textlike) | Supporting copy displayed below the body. | +| `subtitle?` | [`TextLike`](objects.md#textlike) | Secondary heading, up to 150 characters. | +| `title?` | [`TextLike`](objects.md#textlike) | Primary heading, up to 150 characters. | + +*** + +## carouselBlock() + +> **carouselBlock**(`input`, `settings?`): [`SlackObject`](utilities.md#slackobject)<`"carousel"`> + +Creates a horizontally scrolling collection of cards. + +### Input fields + +One to ten card blocks and an optional block identifier. + +| Input field | Type | Description | +| ------ | ------ | ------ | +| `blockId?` | `string` | Deterministic identifier, up to 255 characters. | +| `elements` | [`JsonObject`](utilities.md#jsonobject)[] | Between one and ten objects returned by `cardBlock`. | + +### Settings + +| Setting | Type | Description | +| ------ | ------ | ------ | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`SlackObject`](utilities.md#slackobject)<`"carousel"`> + +A validated Slack `carousel` block. + +### Throws + +InvalidUsageError when the card count is outside Slack's limits. + +*** + +## containerBlock() + +> **containerBlock**(`input`, `settings?`): [`SlackObject`](utilities.md#slackobject)<`"container"`> + +Creates a titled container that groups related child blocks. + +### Input fields + +Child blocks plus optional heading, width, icon, and collapse behavior. + +| Input field | Type | Description | +| ------ | ------ | ------ | +| `blockId?` | `string` | Deterministic identifier, up to 255 characters. | +| `childBlocks` | [`JsonObject`](utilities.md#jsonobject)[] | Up to ten blocks supported by Slack containers. | +| `defaultCollapsed?` | `boolean` | Whether a collapsible container starts collapsed. | +| `hasHeaderDivider?` | `boolean` | Whether Slack draws a divider below the header. | +| `icon?` | [`JsonObject`](utilities.md#jsonobject) | Optional image displayed in the header. | +| `isCollapsible?` | `boolean` | Whether readers can expand and collapse the container. | +| `richTextTitle?` | [`JsonObject`](utilities.md#jsonobject) | Rich-text title block. Mutually exclusive with `title`. | +| `subtitle?` | [`TextLike`](objects.md#textlike) | Optional supporting copy below the title. | +| `title?` | [`TextLike`](objects.md#textlike) | Plain-text title. Mutually exclusive with `richTextTitle`. | +| `width?` | [`ContainerWidth`](#containerwidth) | Container width. Defaults to `standard`. | + +### Settings + +| Setting | Type | Description | +| ------ | ------ | ------ | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`SlackObject`](utilities.md#slackobject)<`"container"`> + +A validated Slack `container` block. + +### Throws + +InvalidUsageError when child content or collapse options are invalid. + +*** + +## ContainerWidth + +> **ContainerWidth** = `"narrow"` \| `"standard"` \| `"wide"` \| `"full"` + +Horizontal width used by a container block. + +*** + +## contextActionsBlock() + +> **contextActionsBlock**(`input`, `settings?`): [`SlackObject`](utilities.md#slackobject)<`"context_actions"`> + +Creates contextual feedback or icon controls. + +### Input fields + +Up to five feedback-buttons or icon-button elements. + +| Input field | Type | Description | +| ------ | ------ | ------ | +| `blockId?` | `string` | Deterministic identifier, up to 255 characters. | +| `elements` | [`JsonObject`](utilities.md#jsonobject)[] | Feedback-buttons or icon-button elements. | + +### Settings + +| Setting | Type | Description | +| ------ | ------ | ------ | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`SlackObject`](utilities.md#slackobject)<`"context_actions"`> + +A validated Slack `context_actions` block. + +### Throws + +InvalidUsageError when an element is unsupported or the limit is exceeded. + +*** + +## contextBlock() + +> **contextBlock**(`input`, `settings?`): [`SlackWire`](utilities.md#slackwire)<`ContextBlock`> + +Creates compact contextual text and images. + +### Input fields + +Up to ten text objects or image elements. + +| Input field | Type | Description | +| ------ | ------ | ------ | +| `blockId?` | `string` | Deterministic identifier, up to 255 characters. | +| `elements` | [`JsonObject`](utilities.md#jsonobject)[] | Text objects and image elements. | + +### Settings + +| Setting | Type | Description | +| ------ | ------ | ------ | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`SlackWire`](utilities.md#slackwire)<`ContextBlock`> + +A validated Slack `context` block. + +### Throws + +InvalidUsageError when an element is unsupported or the limit is exceeded. + +*** + +## dataTableBlock() + +> **dataTableBlock**(`input`, `settings?`): [`SlackObject`](utilities.md#slackobject)<`"data_table"`> + +Creates a sortable data table. + +### Input fields + +Caption, rows, pagination size, and row-header configuration. + +| Input field | Type | Description | +| ------ | ------ | ------ | +| `blockId?` | `string` | Deterministic identifier, up to 255 characters. | +| `caption` | `string` | Accessible table caption. | +| `pageSize?` | `number` | Rows per page, between 1 and 100. Defaults to 5. | +| `rowHeaderColumnIndex?` | `number` | Zero-based column used as the row header. Defaults to 0. | +| `rows` | [`JsonObject`](utilities.md#jsonobject)[][] | Two to 201 equally sized rows containing raw text, raw numbers, or rich text. | + +### Settings + +| Setting | Type | Description | +| ------ | ------ | ------ | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`SlackObject`](utilities.md#slackobject)<`"data_table"`> + +A validated Slack `data_table` block. + +### Throws + +InvalidUsageError when row dimensions, cells, or pagination are invalid. + +*** + +## dataVisualizationBlock() + +> **dataVisualizationBlock**(`input`, `settings?`): [`SlackObject`](utilities.md#slackobject)<`"data_visualization"`> + +Creates a chart rendered by Slack. + +### Input fields + +Chart title, chart object, and optional block identifier. + +| Input field | Type | Description | +| ------ | ------ | ------ | +| `blockId?` | `string` | Deterministic identifier, up to 255 characters. | +| `chart` | [`JsonObject`](utilities.md#jsonobject) | Object returned by `pieChart`, `barChart`, `areaChart`, or `lineChart`. | +| `title` | `string` | Chart heading, up to 50 characters. | + +### Settings + +| Setting | Type | Description | +| ------ | ------ | ------ | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`SlackObject`](utilities.md#slackobject)<`"data_visualization"`> + +A validated Slack `data_visualization` block. + +### Throws + +InvalidUsageError when chart data or labels violate Slack's limits. + +*** + +## dividerBlock() + +> **dividerBlock**(`input?`, `settings?`): [`SlackWire`](utilities.md#slackwire)<`DividerBlock`> + +Creates a visual divider between blocks. + +### Input fields + +Optional deterministic block identifier. + +| Input field | Type | Description | +| ------ | ------ | ------ | +| `blockId?` | `string` | Deterministic identifier, up to 255 characters. | + +### Settings + +| Setting | Type | Description | +| ------ | ------ | ------ | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`SlackWire`](utilities.md#slackwire)<`DividerBlock`> + +A validated Slack `divider` block. + +### Throws + +InvalidUsageError when the block identifier is too long. + +*** + +## fileBlock() + +> **fileBlock**(`input`, `settings?`): [`SlackWire`](utilities.md#slackwire)<`FileBlock`> + +Creates a block that displays a Slack remote file. + +### Input fields + +Remote-file identifier, source, and optional block identifier. + +| Input field | Type | Description | +| ------ | ------ | ------ | +| `blockId?` | `string` | Deterministic identifier, up to 255 characters. | +| `externalId` | `string` | Identifier assigned when the remote file was added to Slack. | +| `source?` | `"remote"` | Remote-file source. Slack currently accepts only `remote`. | + +### Settings + +| Setting | Type | Description | +| ------ | ------ | ------ | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`SlackWire`](utilities.md#slackwire)<`FileBlock`> + +A validated Slack `file` block. + +### Throws + +InvalidUsageError when required file data is missing. + +*** + +## headerBlock() + +> **headerBlock**(`input`, `settings?`): [`SlackWire`](utilities.md#slackwire)<`HeaderBlock`> + +Creates a prominent plain-text heading. + +### Input fields + +Heading text and optional block identifier. + +| Input field | Type | Description | +| ------ | ------ | ------ | +| `blockId?` | `string` | Deterministic identifier, up to 255 characters. | +| `text` | [`TextLike`](objects.md#textlike) | Heading copy. Strings are converted to plain text. | + +### Settings + +| Setting | Type | Description | +| ------ | ------ | ------ | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`SlackWire`](utilities.md#slackwire)<`HeaderBlock`> + +A validated Slack `header` block. + +### Throws + +InvalidUsageError when the heading exceeds Slack's limit. + +*** + +## imageBlock() + +> **imageBlock**(`input`, `settings?`): [`SlackWire`](utilities.md#slackwire)<`ImageBlock`> + +Creates an image block with optional title text. + +### Input fields + +Image URL, accessible alternative, title, and optional block identifier. + +| Input field | Type | Description | +| ------ | ------ | ------ | +| `altText` | `string` | Accessible description of the image. | +| `blockId?` | `string` | Deterministic identifier, up to 255 characters. | +| `imageUrl` | `string` | Public URL of the image. | +| `title?` | [`TextLike`](objects.md#textlike) | Optional plain-text title. | + +### Settings + +| Setting | Type | Description | +| ------ | ------ | ------ | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`SlackWire`](utilities.md#slackwire)<`ImageBlock`> + +A validated Slack `image` block. + +### Throws + +InvalidUsageError when text or URL fields violate Slack's constraints. + +*** + +## inputBlock() + +> **inputBlock**(`input`, `settings?`): [`SlackWire`](utilities.md#slackwire)<`InputBlock`> + +Creates a labelled form control for a modal or App Home tab. + +### Input fields + +Label, input-compatible element, and optional form behavior. + +| Input field | Type | Description | +| ------ | ------ | ------ | +| `blockId?` | `string` | Deterministic identifier, up to 255 characters. | +| `dispatchAction?` | `boolean` | Whether changes dispatch an interaction immediately. | +| `element` | [`JsonObject`](utilities.md#jsonobject) | Input-compatible element such as a text input, picker, or select menu. | +| `hint?` | [`TextLike`](objects.md#textlike) | Optional plain-text help shown below the control. | +| `label` | [`TextLike`](objects.md#textlike) | Plain-text label displayed above the control. | +| `optional?` | `boolean` | Whether the user may submit without completing this input. | + +### Settings + +| Setting | Type | Description | +| ------ | ------ | ------ | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`SlackWire`](utilities.md#slackwire)<`InputBlock`> + +A validated Slack `input` block. + +### Throws + +InvalidUsageError when the element is unsupported or text exceeds Slack's limits. + +*** + +## markdownBlock() + +> **markdownBlock**(`input`, `settings?`): [`SlackWire`](utilities.md#slackwire)<`MarkdownBlock`> + +Creates a block rendered from GitHub-flavored Markdown. + +### Input fields + +Markdown source and optional block identifier. + +| Input field | Type | Description | +| ------ | ------ | ------ | +| `blockId?` | `string` | Deterministic identifier, up to 255 characters. | +| `text` | `string` | GitHub-flavored Markdown source. | + +### Settings + +| Setting | Type | Description | +| ------ | ------ | ------ | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`SlackWire`](utilities.md#slackwire)<`MarkdownBlock`> + +A validated Slack `markdown` block. + +### Throws + +InvalidUsageError when the Markdown source violates Slack's limits. + +*** + +## planBlock() + +> **planBlock**(`input`, `settings?`): [`SlackObject`](utilities.md#slackobject)<`"plan"`> + +Creates a titled sequence of task cards. + +### Input fields + +Plan title, tasks, and optional block identifier. + +| Input field | Type | Description | +| ------ | ------ | ------ | +| `blockId?` | `string` | Deterministic identifier, up to 255 characters. | +| `tasks?` | [`JsonObject`](utilities.md#jsonobject)[] | Task-card blocks. Their outer `type` and `block_id` fields are omitted in the plan. | +| `title` | `string` | Human-readable plan title. | + +### Settings + +| Setting | Type | Description | +| ------ | ------ | ------ | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`SlackObject`](utilities.md#slackobject)<`"plan"`> + +A validated Slack `plan` block. + +### Throws + +InvalidUsageError when task content violates Slack's constraints. + +*** + +## richTextBlock() + +> **richTextBlock**(`input`, `settings?`): [`SlackWire`](utilities.md#slackwire)<`RichTextBlock`> + +Creates a rich-text block from rich-text layout objects. + +### Input fields + +Rich-text sections, lists, quotes, or code blocks. + +| Input field | Type | Description | +| ------ | ------ | ------ | +| `blockId?` | `string` | Deterministic identifier, up to 255 characters. | +| `elements` | [`JsonObject`](utilities.md#jsonobject)[] | Rich-text layout objects. | + +### Settings + +| Setting | Type | Description | +| ------ | ------ | ------ | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`SlackWire`](utilities.md#slackwire)<`RichTextBlock`> + +A validated Slack `rich_text` block. + +### Throws + +InvalidUsageError when an element is not a supported rich-text object. + +*** + +## sectionBlock() + +> **sectionBlock**(`input`, `settings?`): [`SlackWire`](utilities.md#slackwire)<`SectionBlock`> + +Creates a flexible text block with optional fields or an accessory. + +### Input fields + +Section text, fields, accessory, and optional block identifier. + +| Input field | Type | Description | +| ------ | ------ | ------ | +| `accessory?` | [`JsonObject`](utilities.md#jsonobject) | Optional interactive or visual element displayed beside the text. | +| `blockId?` | `string` | Deterministic identifier, up to 255 characters. | +| `fields?` | [`TextLike`](objects.md#textlike)[] | Up to ten text fields displayed in columns. | +| `text?` | [`TextLike`](objects.md#textlike) | Main copy. Strings are converted to mrkdwn text. | + +### Settings + +| Setting | Type | Description | +| ------ | ------ | ------ | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`SlackWire`](utilities.md#slackwire)<`SectionBlock`> + +A validated Slack `section` block. + +### Throws + +InvalidUsageError when text is missing or a field exceeds Slack's limits. + +*** + +## SectionBlockInput + +Fields accepted by [sectionBlock](#sectionblock). + +### Properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `accessory?` | [`JsonObject`](utilities.md#jsonobject) | Optional interactive or visual element displayed beside the text. | +| `blockId?` | `string` | Deterministic identifier, up to 255 characters. | +| `fields?` | [`TextLike`](objects.md#textlike)[] | Up to ten text fields displayed in columns. | +| `text?` | [`TextLike`](objects.md#textlike) | Main copy. Strings are converted to mrkdwn text. | + +*** + +## tableBlock() + +> **tableBlock**(`input`, `settings?`): [`SlackWire`](utilities.md#slackwire)<`TableBlock`> + +Creates a table block from raw-text or rich-text cells. + +### Input fields + +Rows, optional column display settings, and optional block identifier. + +| Input field | Type | Description | +| ------ | ------ | ------ | +| `blockId?` | `string` | Deterministic identifier, up to 255 characters. | +| `columnSettings?` | [`JsonObject`](utilities.md#jsonobject)[] | Optional display settings for each column. | +| `rows` | [`JsonObject`](utilities.md#jsonobject)[][] | Up to 100 equally sized rows of raw-text or rich-text cells. | + +### Settings + +| Setting | Type | Description | +| ------ | ------ | ------ | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`SlackWire`](utilities.md#slackwire)<`TableBlock`> + +A validated Slack `table` block. + +### Throws + +InvalidUsageError when dimensions, cells, or column settings are invalid. + +*** + +## taskCardBlock() + +> **taskCardBlock**(`input`, `settings?`): [`SlackObject`](utilities.md#slackobject)<`"task_card"`> + +Creates one task card for a plan. + +### Input fields + +Task identity, title, rich content, sources, and optional status. + +| Input field | Type | Description | +| ------ | ------ | ------ | +| `blockId?` | `string` | Deterministic identifier, up to 255 characters. | +| `details?` | [`JsonObject`](utilities.md#jsonobject) | Optional rich-text task details. | +| `output?` | [`JsonObject`](utilities.md#jsonobject) | Optional rich-text task output. | +| `sources?` | [`JsonObject`](utilities.md#jsonobject)[] | Optional source links created with `urlSource`. | +| `status?` | [`TaskStatus`](#taskstatus) | Current task lifecycle state. | +| `taskId` | `string` | Stable task identifier. | +| `title` | `string` | Human-readable task title. | + +### Settings + +| Setting | Type | Description | +| ------ | ------ | ------ | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`SlackObject`](utilities.md#slackobject)<`"task_card"`> + +A validated Slack `task_card` block. + +### Throws + +InvalidUsageError when identifiers, content, or source links are invalid. + +*** + +## TaskStatus + +> **TaskStatus** = `"pending"` \| `"in_progress"` \| `"complete"` \| `"error"` + +Lifecycle state shown by a task card. + +*** + +## videoBlock() + +> **videoBlock**(`input`, `settings?`): [`SlackWire`](utilities.md#slackwire)<`VideoBlock`> + +Creates an embedded video block. + +Slack, rather than this library, enforces its provider allowlist when the +payload is submitted. + +### Input fields + +Video URL, thumbnail, accessible text, title, and optional metadata. + +| Input field | Type | Description | +| ------ | ------ | ------ | +| `altText` | `string` | Accessible summary, up to 200 characters. | +| `authorName?` | `string` | Optional author name, up to 50 characters. | +| `blockId?` | `string` | Deterministic identifier, up to 255 characters. | +| `description?` | [`TextLike`](objects.md#textlike) | Optional plain-text description, up to 200 characters. | +| `providerIconUrl?` | `string` | Optional provider icon URL. | +| `providerName?` | `string` | Optional provider name, up to 50 characters. | +| `thumbnailUrl` | `string` | Public preview-image URL. | +| `title` | [`TextLike`](objects.md#textlike) | Plain-text video title, up to 200 characters. | +| `titleUrl?` | `string` | Optional destination when the title is selected. | +| `videoUrl` | `string` | URL of a video hosted by a Slack-supported provider. | + +### Settings + +| Setting | Type | Description | +| ------ | ------ | ------ | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`SlackWire`](utilities.md#slackwire)<`VideoBlock`> + +A validated Slack `video` block. + +### Throws + +InvalidUsageError when a text field violates Slack's constraints. diff --git a/docs/versioned_docs/version-2.1.0/reference/typescript/elements.md b/docs/versioned_docs/version-2.1.0/reference/typescript/elements.md new file mode 100644 index 00000000..dc2210d9 --- /dev/null +++ b/docs/versioned_docs/version-2.1.0/reference/typescript/elements.md @@ -0,0 +1,1500 @@ +--- +toc_min_heading_level: 2 +toc_max_heading_level: 2 +--- + +# Elements + +Interactive and visual element factories used inside Block Kit blocks. + +Factories accept camelCase input and return validated Slack wire objects. + +## button() + +> **button**(`input`, `settings?`): [`SlackObject`](utilities.md#slackobject)<`"button"`> + +Creates an interactive button. + +### Input fields + +Button label, action identifier, and optional behavior. + +| Input field | Type | Description | +| ------ | ------ | ------ | +| `accessibilityLabel?` | `string` | Accessible label when the visible text is insufficient. | +| `actionId` | `string` | Identifier returned when the button is selected. | +| `confirm?` | [`JsonObject`](utilities.md#jsonobject) | Optional confirmation dialog created with `confirmation`. | +| `style?` | `"primary"` \| `"danger"` | Optional visual emphasis. | +| `text` | [`TextLike`](objects.md#textlike) | Plain-text label displayed on the button. | +| `url?` | `string` | Optional URL opened by the button. | +| `value?` | `string` | Optional application-defined value returned with the interaction. | + +### Settings + +| Setting | Type | Description | +| ------ | ------ | ------ | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`SlackObject`](utilities.md#slackobject)<`"button"`> + +A validated Slack `button` element. + +### Throws + +InvalidUsageError when a field violates Slack's constraints. + +*** + +## ButtonInput + +Fields accepted by [button](#button). + +### Properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `accessibilityLabel?` | `string` | Accessible label when the visible text is insufficient. | +| `actionId` | `string` | Identifier returned when the button is selected. | +| `confirm?` | [`JsonObject`](utilities.md#jsonobject) | Optional confirmation dialog created with `confirmation`. | +| `style?` | `"primary"` \| `"danger"` | Optional visual emphasis. | +| `text` | [`TextLike`](objects.md#textlike) | Plain-text label displayed on the button. | +| `url?` | `string` | Optional URL opened by the button. | +| `value?` | `string` | Optional application-defined value returned with the interaction. | + +*** + +## channelMultiSelect() + +> **channelMultiSelect**(`input`, `settings?`): [`SlackObject`](utilities.md#slackobject)<`"multi_channels_select"`> + +Creates a multi-select menu populated with public channels visible to the current user. + +### Input fields + +Channel selection, confirmation, focus, and placeholder behavior. + +| Input field | Type | Description | +| ------ | ------ | ------ | +| `actionId` | `string` | Identifier returned when the selection changes, up to 255 characters. | +| `confirm?` | [`JsonObject`](utilities.md#jsonobject) | Optional confirmation dialog shown before the selection is submitted. | +| `focusOnLoad?` | `boolean` | Whether this element receives focus when its containing view opens. | +| `initialChannels?` | `string`[] | Public channel IDs selected when the menu first loads. | +| `maxSelectedItems?` | `number` | Maximum number of channels that may be selected; the minimum is one. | +| `placeholder?` | [`TextLike`](objects.md#textlike) | Plain-text prompt shown before a selection, up to 150 characters. | + +### Settings + +| Setting | Type | Description | +| ------ | ------ | ------ | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`SlackObject`](utilities.md#slackobject)<`"multi_channels_select"`> + +A validated Slack `multi_channels_select` element. + +### Throws + +InvalidUsageError when an identifier, placeholder, or selection constraint is invalid. + +*** + +## ChannelMultiSelectInput + +Fields accepted by [channelMultiSelect](#channelmultiselect). + +### Properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `actionId` | `string` | Identifier returned when the selection changes, up to 255 characters. | +| `confirm?` | [`JsonObject`](utilities.md#jsonobject) | Optional confirmation dialog shown before the selection is submitted. | +| `focusOnLoad?` | `boolean` | Whether this element receives focus when its containing view opens. | +| `initialChannels?` | `string`[] | Public channel IDs selected when the menu first loads. | +| `maxSelectedItems?` | `number` | Maximum number of channels that may be selected; the minimum is one. | +| `placeholder?` | [`TextLike`](objects.md#textlike) | Plain-text prompt shown before a selection, up to 150 characters. | + +*** + +## channelSelect() + +> **channelSelect**(`input`, `settings?`): [`SlackObject`](utilities.md#slackobject)<`"channels_select"`> + +Creates a single-select menu populated with public channels visible to the current user. + +### Input fields + +Initial channel, response URL, confirmation, and display behavior. + +| Input field | Type | Description | +| ------ | ------ | ------ | +| `actionId` | `string` | Identifier returned when a channel is selected, up to 255 characters. | +| `confirm?` | [`JsonObject`](utilities.md#jsonobject) | Optional confirmation dialog shown before the selection is submitted. | +| `focusOnLoad?` | `boolean` | Whether this element receives focus when its containing view opens. | +| `initialChannel?` | `string` | Public channel ID selected when the menu first loads. | +| `placeholder?` | [`TextLike`](objects.md#textlike) | Plain-text prompt shown before a selection, up to 150 characters. | +| `responseUrlEnabled?` | `boolean` | Include a `response_url` in a parent modal's submission payload. | + +### Settings + +| Setting | Type | Description | +| ------ | ------ | ------ | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`SlackObject`](utilities.md#slackobject)<`"channels_select"`> + +A validated Slack `channels_select` element. + +### Throws + +InvalidUsageError when an identifier, placeholder, or initial selection is invalid. + +*** + +## ChannelSelectInput + +Fields accepted by [channelSelect](#channelselect). + +### Properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `actionId` | `string` | Identifier returned when a channel is selected, up to 255 characters. | +| `confirm?` | [`JsonObject`](utilities.md#jsonobject) | Optional confirmation dialog shown before the selection is submitted. | +| `focusOnLoad?` | `boolean` | Whether this element receives focus when its containing view opens. | +| `initialChannel?` | `string` | Public channel ID selected when the menu first loads. | +| `placeholder?` | [`TextLike`](objects.md#textlike) | Plain-text prompt shown before a selection, up to 150 characters. | +| `responseUrlEnabled?` | `boolean` | Include a `response_url` in a parent modal's submission payload. | + +*** + +## checkboxes() + +> **checkboxes**(`input`, `settings?`): [`SlackObject`](utilities.md#slackobject)<`"checkboxes"`> + +Creates a checkbox group. + +### Input fields + +Action identifier, options, and optional Slack checkbox fields. + +| Input field | Type | Description | +| ------ | ------ | ------ | +| `actionId` | `string` | Identifier returned when the checkbox selection changes, up to 255 characters. | +| `confirm?` | [`JsonObject`](utilities.md#jsonobject) | Optional confirmation dialog shown before the changed selection is submitted. | +| `focusOnLoad?` | `boolean` | Whether this element receives focus when its containing view opens. | +| `initialOptions?` | [`JsonObject`](utilities.md#jsonobject)[] | Options from `options` that are selected when the element first loads. | +| `options` | [`JsonObject`](utilities.md#jsonobject)[] | Up to ten option objects displayed as checkboxes. | + +### Settings + +| Setting | Type | Description | +| ------ | ------ | ------ | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`SlackObject`](utilities.md#slackobject)<`"checkboxes"`> + +A validated Slack `checkboxes` element. + +### Throws + +InvalidUsageError when options or identifiers violate Slack's constraints. + +*** + +## CheckboxesInput + +Fields accepted by [checkboxes](#checkboxes). + +### Properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `actionId` | `string` | Identifier returned when the checkbox selection changes, up to 255 characters. | +| `confirm?` | [`JsonObject`](utilities.md#jsonobject) | Optional confirmation dialog shown before the changed selection is submitted. | +| `focusOnLoad?` | `boolean` | Whether this element receives focus when its containing view opens. | +| `initialOptions?` | [`JsonObject`](utilities.md#jsonobject)[] | Options from `options` that are selected when the element first loads. | +| `options` | [`JsonObject`](utilities.md#jsonobject)[] | Up to ten option objects displayed as checkboxes. | + +*** + +## conversationMultiSelect() + +> **conversationMultiSelect**(`input`, `settings?`): [`SlackObject`](utilities.md#slackobject)<`"multi_conversations_select"`> + +Creates a multi-select menu of public channels, private channels, DMs, and group DMs. + +### Input fields + +Conversation filters, initial selection, confirmation, and display behavior. + +| Input field | Type | Description | +| ------ | ------ | ------ | +| `actionId` | `string` | Identifier returned when the selection changes, up to 255 characters. | +| `confirm?` | [`JsonObject`](utilities.md#jsonobject) | Optional confirmation dialog shown before the selection is submitted. | +| `defaultToCurrentConversation?` | `boolean` | Select the conversation from which the view was opened by default. | +| `filter?` | [`JsonObject`](utilities.md#jsonobject) | Filter controlling which public channels, private channels, DMs, and group DMs appear. | +| `focusOnLoad?` | `boolean` | Whether this element receives focus when its containing view opens. | +| `initialConversations?` | `string`[] | Conversation IDs selected when the menu first loads. | +| `maxSelectedItems?` | `number` | Maximum number of conversations that may be selected; the minimum is one. | +| `placeholder?` | [`TextLike`](objects.md#textlike) | Plain-text prompt shown before a selection, up to 150 characters. | + +### Settings + +| Setting | Type | Description | +| ------ | ------ | ------ | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`SlackObject`](utilities.md#slackobject)<`"multi_conversations_select"`> + +A validated Slack `multi_conversations_select` element. + +### Throws + +InvalidUsageError when an identifier, placeholder, filter, or selection is invalid. + +*** + +## ConversationMultiSelectInput + +Fields accepted by [conversationMultiSelect](#conversationmultiselect). + +### Properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `actionId` | `string` | Identifier returned when the selection changes, up to 255 characters. | +| `confirm?` | [`JsonObject`](utilities.md#jsonobject) | Optional confirmation dialog shown before the selection is submitted. | +| `defaultToCurrentConversation?` | `boolean` | Select the conversation from which the view was opened by default. | +| `filter?` | [`JsonObject`](utilities.md#jsonobject) | Filter controlling which public channels, private channels, DMs, and group DMs appear. | +| `focusOnLoad?` | `boolean` | Whether this element receives focus when its containing view opens. | +| `initialConversations?` | `string`[] | Conversation IDs selected when the menu first loads. | +| `maxSelectedItems?` | `number` | Maximum number of conversations that may be selected; the minimum is one. | +| `placeholder?` | [`TextLike`](objects.md#textlike) | Plain-text prompt shown before a selection, up to 150 characters. | + +*** + +## conversationSelect() + +> **conversationSelect**(`input`, `settings?`): [`SlackObject`](utilities.md#slackobject)<`"conversations_select"`> + +Creates a single-select menu of public channels, private channels, DMs, and group DMs. + +### Input fields + +Conversation filter, initial selection, response URL, and display behavior. + +| Input field | Type | Description | +| ------ | ------ | ------ | +| `actionId` | `string` | Identifier returned when a conversation is selected, up to 255 characters. | +| `confirm?` | [`JsonObject`](utilities.md#jsonobject) | Optional confirmation dialog shown before the selection is submitted. | +| `defaultToCurrentConversation?` | `boolean` | Select the conversation from which the view was opened by default. | +| `filter?` | [`JsonObject`](utilities.md#jsonobject) | Filter controlling which public channels, private channels, DMs, and group DMs appear. | +| `focusOnLoad?` | `boolean` | Whether this element receives focus when its containing view opens. | +| `initialConversation?` | `string` | Conversation ID selected when the menu first loads. | +| `placeholder?` | [`TextLike`](objects.md#textlike) | Plain-text prompt shown before a selection, up to 150 characters. | +| `responseUrlEnabled?` | `boolean` | Include a `response_url` in a parent modal's submission payload. | + +### Settings + +| Setting | Type | Description | +| ------ | ------ | ------ | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`SlackObject`](utilities.md#slackobject)<`"conversations_select"`> + +A validated Slack `conversations_select` element. + +### Throws + +InvalidUsageError when an identifier, placeholder, filter, or selection is invalid. + +*** + +## ConversationSelectInput + +Fields accepted by [conversationSelect](#conversationselect). + +### Properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `actionId` | `string` | Identifier returned when a conversation is selected, up to 255 characters. | +| `confirm?` | [`JsonObject`](utilities.md#jsonobject) | Optional confirmation dialog shown before the selection is submitted. | +| `defaultToCurrentConversation?` | `boolean` | Select the conversation from which the view was opened by default. | +| `filter?` | [`JsonObject`](utilities.md#jsonobject) | Filter controlling which public channels, private channels, DMs, and group DMs appear. | +| `focusOnLoad?` | `boolean` | Whether this element receives focus when its containing view opens. | +| `initialConversation?` | `string` | Conversation ID selected when the menu first loads. | +| `placeholder?` | [`TextLike`](objects.md#textlike) | Plain-text prompt shown before a selection, up to 150 characters. | +| `responseUrlEnabled?` | `boolean` | Include a `response_url` in a parent modal's submission payload. | + +*** + +## datePicker() + +> **datePicker**(`input`, `settings?`): [`SlackObject`](utilities.md#slackobject)<`"datepicker"`> + +Creates a date picker. + +### Input fields + +Action identifier and optional Slack date-picker fields. + +| Input field | Type | Description | +| ------ | ------ | ------ | +| `actionId` | `string` | Identifier returned when a date is selected, up to 255 characters. | +| `confirm?` | [`JsonObject`](utilities.md#jsonobject) | Optional confirmation dialog shown after a date is selected. | +| `focusOnLoad?` | `boolean` | Whether this element receives focus when its containing view opens. | +| `initialDate?` | `string` | Initially selected date in `YYYY-MM-DD` format. | +| `placeholder?` | [`TextLike`](objects.md#textlike) | Plain-text prompt shown before a date is selected, up to 150 characters. | + +### Settings + +| Setting | Type | Description | +| ------ | ------ | ------ | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`SlackObject`](utilities.md#slackobject)<`"datepicker"`> + +A validated Slack `datepicker` element. + +### Throws + +InvalidUsageError when a field violates Slack's constraints. + +*** + +## DatePickerInput + +Fields accepted by [datePicker](#datepicker). + +### Properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `actionId` | `string` | Identifier returned when a date is selected, up to 255 characters. | +| `confirm?` | [`JsonObject`](utilities.md#jsonobject) | Optional confirmation dialog shown after a date is selected. | +| `focusOnLoad?` | `boolean` | Whether this element receives focus when its containing view opens. | +| `initialDate?` | `string` | Initially selected date in `YYYY-MM-DD` format. | +| `placeholder?` | [`TextLike`](objects.md#textlike) | Plain-text prompt shown before a date is selected, up to 150 characters. | + +*** + +## dateTimePicker() + +> **dateTimePicker**(`input`, `settings?`): [`SlackObject`](utilities.md#slackobject)<`"datetimepicker"`> + +Creates a date-and-time picker. + +### Input fields + +Action identifier and optional Slack date-time-picker fields. + +| Input field | Type | Description | +| ------ | ------ | ------ | +| `actionId` | `string` | Identifier returned when a date and time are selected, up to 255 characters. | +| `confirm?` | [`JsonObject`](utilities.md#jsonobject) | Optional confirmation dialog shown after a date and time are selected. | +| `focusOnLoad?` | `boolean` | Whether this element receives focus when its containing view opens. | +| `initialDateTime?` | `number` | Initially selected date and time as a Unix timestamp in seconds. | + +### Settings + +| Setting | Type | Description | +| ------ | ------ | ------ | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`SlackObject`](utilities.md#slackobject)<`"datetimepicker"`> + +A validated Slack `datetimepicker` element. + +### Throws + +InvalidUsageError when a field violates Slack's constraints. + +*** + +## DateTimePickerInput + +Fields accepted by [dateTimePicker](#datetimepicker). + +### Properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `actionId` | `string` | Identifier returned when a date and time are selected, up to 255 characters. | +| `confirm?` | [`JsonObject`](utilities.md#jsonobject) | Optional confirmation dialog shown after a date and time are selected. | +| `focusOnLoad?` | `boolean` | Whether this element receives focus when its containing view opens. | +| `initialDateTime?` | `number` | Initially selected date and time as a Unix timestamp in seconds. | + +*** + +## EmailElementInput + +Fields accepted by [emailInput](#emailinput). + +### Properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `actionId` | `string` | Identifier used to find the submitted email value, up to 255 characters. | +| `dispatchActionConfig?` | [`JsonObject`](utilities.md#jsonobject) | Configuration controlling when typing dispatches a `block_actions` payload. | +| `focusOnLoad?` | `boolean` | Whether this element receives focus when its containing view opens. | +| `initialValue?` | `string` | Email address present when the input first loads. | +| `placeholder?` | [`TextLike`](objects.md#textlike) | Plain-text prompt shown in the empty input, up to 150 characters. | + +*** + +## emailInput() + +> **emailInput**(`input`, `settings?`): [`SlackObject`](utilities.md#slackobject)<`"email_text_input"`> + +Creates an email-address input. + +### Input fields + +Action identifier and optional Slack email-input fields. + +| Input field | Type | Description | +| ------ | ------ | ------ | +| `actionId` | `string` | Identifier used to find the submitted email value, up to 255 characters. | +| `dispatchActionConfig?` | [`JsonObject`](utilities.md#jsonobject) | Configuration controlling when typing dispatches a `block_actions` payload. | +| `focusOnLoad?` | `boolean` | Whether this element receives focus when its containing view opens. | +| `initialValue?` | `string` | Email address present when the input first loads. | +| `placeholder?` | [`TextLike`](objects.md#textlike) | Plain-text prompt shown in the empty input, up to 150 characters. | + +### Settings + +| Setting | Type | Description | +| ------ | ------ | ------ | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`SlackObject`](utilities.md#slackobject)<`"email_text_input"`> + +A validated Slack `email_text_input` element. + +### Throws + +InvalidUsageError when a field violates Slack's constraints. + +*** + +## externalMultiSelect() + +> **externalMultiSelect**(`input`, `settings?`): [`SlackObject`](utilities.md#slackobject)<`"multi_external_select"`> + +Creates a multi-select menu whose options are loaded from the app's configured Options Load URL. + +### Input fields + +Query threshold, initial options, confirmation, and display behavior. + +| Input field | Type | Description | +| ------ | ------ | ------ | +| `actionId` | `string` | Identifier returned when the selection changes, up to 255 characters. | +| `confirm?` | [`JsonObject`](utilities.md#jsonobject) | Optional confirmation dialog shown before the selection is submitted. | +| `focusOnLoad?` | `boolean` | Whether this element receives focus when its containing view opens. | +| `initialOptions?` | [`JsonObject`](utilities.md#jsonobject)[] | Options selected when the menu first loads. | +| `maxSelectedItems?` | `number` | Maximum number of options that may be selected; the minimum is one. | +| `minQueryLength?` | `number` | Minimum typed characters before Slack requests options; defaults to three. | +| `placeholder?` | [`TextLike`](objects.md#textlike) | Plain-text prompt shown before a selection, up to 150 characters. | + +### Settings + +| Setting | Type | Description | +| ------ | ------ | ------ | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`SlackObject`](utilities.md#slackobject)<`"multi_external_select"`> + +A validated Slack `multi_external_select` element. + +### Throws + +InvalidUsageError when an identifier, placeholder, query, or selection is invalid. + +*** + +## ExternalMultiSelectInput + +Fields accepted by [externalMultiSelect](#externalmultiselect). + +### Properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `actionId` | `string` | Identifier returned when the selection changes, up to 255 characters. | +| `confirm?` | [`JsonObject`](utilities.md#jsonobject) | Optional confirmation dialog shown before the selection is submitted. | +| `focusOnLoad?` | `boolean` | Whether this element receives focus when its containing view opens. | +| `initialOptions?` | [`JsonObject`](utilities.md#jsonobject)[] | Options selected when the menu first loads. | +| `maxSelectedItems?` | `number` | Maximum number of options that may be selected; the minimum is one. | +| `minQueryLength?` | `number` | Minimum typed characters before Slack requests options; defaults to three. | +| `placeholder?` | [`TextLike`](objects.md#textlike) | Plain-text prompt shown before a selection, up to 150 characters. | + +*** + +## externalSelect() + +> **externalSelect**(`input`, `settings?`): [`SlackObject`](utilities.md#slackobject)<`"external_select"`> + +Creates a single-select menu whose options are loaded from the app's Options Load URL. + +### Input fields + +Query threshold, initial option, confirmation, and display behavior. + +| Input field | Type | Description | +| ------ | ------ | ------ | +| `actionId` | `string` | Identifier returned when an option is selected, up to 255 characters. | +| `confirm?` | [`JsonObject`](utilities.md#jsonobject) | Optional confirmation dialog shown before the selection is submitted. | +| `focusOnLoad?` | `boolean` | Whether this element receives focus when its containing view opens. | +| `initialOption?` | [`JsonObject`](utilities.md#jsonobject) | Option selected when the menu first loads. | +| `minQueryLength?` | `number` | Minimum typed characters before Slack requests options; defaults to three. | +| `placeholder?` | [`TextLike`](objects.md#textlike) | Plain-text prompt shown before a selection, up to 150 characters. | + +### Settings + +| Setting | Type | Description | +| ------ | ------ | ------ | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`SlackObject`](utilities.md#slackobject)<`"external_select"`> + +A validated Slack `external_select` element. + +### Throws + +InvalidUsageError when an identifier, placeholder, query, or option is invalid. + +*** + +## ExternalSelectInput + +Fields accepted by [externalSelect](#externalselect). + +### Properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `actionId` | `string` | Identifier returned when an option is selected, up to 255 characters. | +| `confirm?` | [`JsonObject`](utilities.md#jsonobject) | Optional confirmation dialog shown before the selection is submitted. | +| `focusOnLoad?` | `boolean` | Whether this element receives focus when its containing view opens. | +| `initialOption?` | [`JsonObject`](utilities.md#jsonobject) | Option selected when the menu first loads. | +| `minQueryLength?` | `number` | Minimum typed characters before Slack requests options; defaults to three. | +| `placeholder?` | [`TextLike`](objects.md#textlike) | Plain-text prompt shown before a selection, up to 150 characters. | + +*** + +## feedbackButton() + +> **feedbackButton**(`input`, `settings?`): [`JsonObject`](utilities.md#jsonobject) + +Creates one choice used by a feedback-buttons element. + +### Input fields + +Choice text, returned value, and optional accessible label. + +| Input field | Type | Description | +| ------ | ------ | ------ | +| `accessibilityLabel?` | `string` | Accessible label when the visible text is insufficient. | +| `text` | [`TextLike`](objects.md#textlike) | Plain-text feedback choice. | +| `value` | `string` | Application-defined value returned with the feedback. | + +### Settings + +| Setting | Type | Description | +| ------ | ------ | ------ | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`JsonObject`](utilities.md#jsonobject) + +A validated feedback-button object. + +### Throws + +InvalidUsageError when a field exceeds Slack's limits. + +*** + +## FeedbackButtonInput + +Fields accepted by [feedbackButton](#feedbackbutton). + +### Properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `accessibilityLabel?` | `string` | Accessible label when the visible text is insufficient. | +| `text` | [`TextLike`](objects.md#textlike) | Plain-text feedback choice. | +| `value` | `string` | Application-defined value returned with the feedback. | + +*** + +## feedbackButtons() + +> **feedbackButtons**(`input`, `settings?`): [`SlackObject`](utilities.md#slackobject)<`"feedback_buttons"`> + +Creates a paired positive/negative feedback control. + +### Input fields + +Positive and negative feedback buttons plus an optional action identifier. + +| Input field | Type | Description | +| ------ | ------ | ------ | +| `actionId?` | `string` | Optional identifier returned with the interaction. | +| `negativeButton` | [`JsonObject`](utilities.md#jsonobject) | Negative choice created with `feedbackButton`. | +| `positiveButton` | [`JsonObject`](utilities.md#jsonobject) | Positive choice created with `feedbackButton`. | + +### Settings + +| Setting | Type | Description | +| ------ | ------ | ------ | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`SlackObject`](utilities.md#slackobject)<`"feedback_buttons"`> + +A validated Slack `feedback_buttons` element. + +### Throws + +InvalidUsageError when either feedback choice is invalid. + +*** + +## fileInput() + +> **fileInput**(`input`, `settings?`): [`SlackObject`](utilities.md#slackobject)<`"file_input"`> + +Creates a file-upload input. + +### Input fields + +Action identifier, allowed extensions, and maximum file count. + +| Input field | Type | Description | +| ------ | ------ | ------ | +| `actionId` | `string` | Identifier returned with submitted files. | +| `filetypes?` | `string`[] | Optional allowed file extensions. | +| `maxFiles?` | `number` | Maximum files accepted, between 1 and 10. | + +### Settings + +| Setting | Type | Description | +| ------ | ------ | ------ | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`SlackObject`](utilities.md#slackobject)<`"file_input"`> + +A validated Slack `file_input` element. + +### Throws + +InvalidUsageError when `maxFiles` is outside 1–10. + +*** + +## iconButton() + +> **iconButton**(`input`, `settings?`): [`SlackObject`](utilities.md#slackobject)<`"icon_button"`> + +Creates a compact icon action for a context-actions block. + +### Input fields + +Accessible text, icon behavior, and optional visibility restrictions. + +| Input field | Type | Description | +| ------ | ------ | ------ | +| `accessibilityLabel?` | `string` | Accessible label when the text is insufficient. | +| `actionId?` | `string` | Optional identifier returned with the interaction. | +| `confirm?` | [`JsonObject`](utilities.md#jsonobject) | Optional confirmation dialog. | +| `icon?` | `"trash"` | Icon name. Slack currently accepts only `trash`. | +| `text` | [`TextLike`](objects.md#textlike) | Plain-text description of the icon action. | +| `value?` | `string` | Optional application-defined interaction value. | +| `visibleToUserIds?` | `string`[] | Up to ten user IDs allowed to see the action. | + +### Settings + +| Setting | Type | Description | +| ------ | ------ | ------ | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`SlackObject`](utilities.md#slackobject)<`"icon_button"`> + +A validated Slack `icon_button` element. + +### Throws + +InvalidUsageError when the icon or visible-user list is invalid. + +*** + +## imageElement() + +> **imageElement**(`input`, `settings?`): [`SlackObject`](utilities.md#slackobject)<`"image"`> + +Creates an image element from a URL or Slack-hosted file. + +### Parameters + +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `input` | [`ImageElementInput`](#imageelementinput) | Accessible text and exactly one image source. | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`SlackObject`](utilities.md#slackobject)<`"image"`> + +A validated Slack `image` element. + +### Throws + +InvalidUsageError when both or neither image source is provided. + +*** + +## ImageElementInput + +> **ImageElementInput** = \{ `altText`: `string`; `imageUrl`: `string`; `slackFile?`: `never`; \} \| \{ `altText`: `string`; `imageUrl?`: `never`; `slackFile`: [`JsonObject`](utilities.md#jsonobject); \} + +URL-backed or Slack-file-backed image fields accepted by [imageElement](#imageelement). + +### Union Members + +#### Type Literal + +\{ `altText`: `string`; `imageUrl`: `string`; `slackFile?`: `never`; \} + +| Name | Type | Description | +| ------ | ------ | ------ | +| `altText` | `string` | Accessible plain-text summary of the image. | +| `imageUrl` | `string` | Public image URL, up to 3,000 characters. | +| `slackFile?` | `never` | A Slack file cannot be combined with `imageUrl`. | + +*** + +#### Type Literal + +\{ `altText`: `string`; `imageUrl?`: `never`; `slackFile`: [`JsonObject`](utilities.md#jsonobject); \} + +| Name | Type | Description | +| ------ | ------ | ------ | +| `altText` | `string` | Accessible plain-text summary of the image. | +| `imageUrl?` | `never` | An image URL cannot be combined with `slackFile`. | +| `slackFile` | [`JsonObject`](utilities.md#jsonobject) | Slack-hosted file reference created with `slackFile`. | + +*** + +## NumberElementInput + +Fields accepted by [numberInput](#numberinput). + +### Properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `actionId` | `string` | Identifier used to find the submitted numeric value, up to 255 characters. | +| `dispatchActionConfig?` | [`JsonObject`](utilities.md#jsonobject) | Configuration controlling when typing dispatches a `block_actions` payload. | +| `focusOnLoad?` | `boolean` | Whether this element receives focus when its containing view opens. | +| `initialValue?` | `string` | Numeric text present when the input first loads. | +| `isDecimalAllowed?` | `boolean` | Whether the input accepts decimal values as well as whole numbers. | +| `maxValue?` | `number` | Maximum accepted value; it cannot be less than `minValue`. | +| `minValue?` | `number` | Minimum accepted value; it cannot exceed `maxValue`. | +| `placeholder?` | [`TextLike`](objects.md#textlike) | Plain-text prompt shown in the empty input, up to 150 characters. | + +*** + +## numberInput() + +> **numberInput**(`input`, `settings?`): [`SlackObject`](utilities.md#slackobject)<`"number_input"`> + +Creates a single-line input for whole or decimal numeric values. + +### Input fields + +Decimal behavior, initial value, range, dispatch, and display settings. + +| Input field | Type | Description | +| ------ | ------ | ------ | +| `actionId` | `string` | Identifier used to find the submitted numeric value, up to 255 characters. | +| `dispatchActionConfig?` | [`JsonObject`](utilities.md#jsonobject) | Configuration controlling when typing dispatches a `block_actions` payload. | +| `focusOnLoad?` | `boolean` | Whether this element receives focus when its containing view opens. | +| `initialValue?` | `string` | Numeric text present when the input first loads. | +| `isDecimalAllowed?` | `boolean` | Whether the input accepts decimal values as well as whole numbers. | +| `maxValue?` | `number` | Maximum accepted value; it cannot be less than `minValue`. | +| `minValue?` | `number` | Minimum accepted value; it cannot exceed `maxValue`. | +| `placeholder?` | [`TextLike`](objects.md#textlike) | Plain-text prompt shown in the empty input, up to 150 characters. | + +### Settings + +| Setting | Type | Description | +| ------ | ------ | ------ | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`SlackObject`](utilities.md#slackobject)<`"number_input"`> + +A validated Slack `number_input` element. + +### Throws + +InvalidUsageError when an identifier, placeholder, or numeric range is invalid. + +*** + +## overflow() + +> **overflow**(`input`, `settings?`): [`SlackObject`](utilities.md#slackobject)<`"overflow"`> + +Creates an overflow menu. + +### Input fields + +Action identifier, two to five options, and optional Slack fields. + +| Input field | Type | Description | +| ------ | ------ | ------ | +| `actionId` | `string` | Identifier returned when an option is selected, up to 255 characters. | +| `confirm?` | [`JsonObject`](utilities.md#jsonobject) | Optional confirmation dialog shown after an option is selected. | +| `options` | [`JsonObject`](utilities.md#jsonobject)[] | Between two and five option objects displayed in the compact menu. | + +### Settings + +| Setting | Type | Description | +| ------ | ------ | ------ | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`SlackObject`](utilities.md#slackobject)<`"overflow"`> + +A validated Slack `overflow` element. + +### Throws + +InvalidUsageError when the option list violates Slack's constraints. + +*** + +## OverflowInput + +Fields accepted by [overflow](#overflow). + +### Properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `actionId` | `string` | Identifier returned when an option is selected, up to 255 characters. | +| `confirm?` | [`JsonObject`](utilities.md#jsonobject) | Optional confirmation dialog shown after an option is selected. | +| `options` | [`JsonObject`](utilities.md#jsonobject)[] | Between two and five option objects displayed in the compact menu. | + +*** + +## PlainTextElementInput + +Fields accepted by [plainTextInput](#plaintextinput). + +### Properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `actionId` | `string` | Identifier used to find the submitted text value, up to 255 characters. | +| `dispatchActionConfig?` | [`JsonObject`](utilities.md#jsonobject) | Configuration controlling when typing dispatches a `block_actions` payload. | +| `focusOnLoad?` | `boolean` | Whether this element receives focus when its containing view opens. | +| `initialValue?` | `string` | Text present when the input first loads. | +| `maxLength?` | `number` | Maximum number of characters the user may enter, between 1 and 3000. | +| `minLength?` | `number` | Minimum number of characters the user must enter, between 0 and 3000. | +| `multiline?` | `boolean` | Whether the input is a multi-line textarea instead of a single line. | +| `placeholder?` | [`TextLike`](objects.md#textlike) | Plain-text prompt shown in the empty input, up to 150 characters. | + +*** + +## plainTextInput() + +> **plainTextInput**(`input`, `settings?`): [`SlackObject`](utilities.md#slackobject)<`"plain_text_input"`> + +Creates a single- or multi-line freeform text input for a modal or App Home tab. + +### Input fields + +Initial text, length limits, multiline, dispatch, and display settings. + +| Input field | Type | Description | +| ------ | ------ | ------ | +| `actionId` | `string` | Identifier used to find the submitted text value, up to 255 characters. | +| `dispatchActionConfig?` | [`JsonObject`](utilities.md#jsonobject) | Configuration controlling when typing dispatches a `block_actions` payload. | +| `focusOnLoad?` | `boolean` | Whether this element receives focus when its containing view opens. | +| `initialValue?` | `string` | Text present when the input first loads. | +| `maxLength?` | `number` | Maximum number of characters the user may enter, between 1 and 3000. | +| `minLength?` | `number` | Minimum number of characters the user must enter, between 0 and 3000. | +| `multiline?` | `boolean` | Whether the input is a multi-line textarea instead of a single line. | +| `placeholder?` | [`TextLike`](objects.md#textlike) | Plain-text prompt shown in the empty input, up to 150 characters. | + +### Settings + +| Setting | Type | Description | +| ------ | ------ | ------ | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`SlackObject`](utilities.md#slackobject)<`"plain_text_input"`> + +A validated Slack `plain_text_input` element. + +### Throws + +InvalidUsageError when an identifier, placeholder, or length constraint is invalid. + +*** + +## radioButtons() + +> **radioButtons**(`input`, `settings?`): [`SlackObject`](utilities.md#slackobject)<`"radio_buttons"`> + +Creates a radio-button group. + +### Input fields + +Action identifier, options, and optional Slack fields. + +| Input field | Type | Description | +| ------ | ------ | ------ | +| `actionId` | `string` | Identifier returned when the selection changes, up to 255 characters. | +| `confirm?` | [`JsonObject`](utilities.md#jsonobject) | Optional confirmation dialog shown before the selection is submitted. | +| `focusOnLoad?` | `boolean` | Whether this element receives focus when its containing view opens. | +| `initialOption?` | [`JsonObject`](utilities.md#jsonobject) | Option from `options` selected when the element first loads. | +| `options` | [`JsonObject`](utilities.md#jsonobject)[] | Up to ten options displayed as radio buttons. | + +### Settings + +| Setting | Type | Description | +| ------ | ------ | ------ | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`SlackObject`](utilities.md#slackobject)<`"radio_buttons"`> + +A validated Slack `radio_buttons` element. + +### Throws + +InvalidUsageError when options or identifiers violate Slack's constraints. + +*** + +## RadioButtonsInput + +Fields accepted by [radioButtons](#radiobuttons). + +### Properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `actionId` | `string` | Identifier returned when the selection changes, up to 255 characters. | +| `confirm?` | [`JsonObject`](utilities.md#jsonobject) | Optional confirmation dialog shown before the selection is submitted. | +| `focusOnLoad?` | `boolean` | Whether this element receives focus when its containing view opens. | +| `initialOption?` | [`JsonObject`](utilities.md#jsonobject) | Option from `options` selected when the element first loads. | +| `options` | [`JsonObject`](utilities.md#jsonobject)[] | Up to ten options displayed as radio buttons. | + +*** + +## RichTextElementInput + +Fields accepted by [richTextInput](#richtextinput). + +### Properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `actionId` | `string` | Identifier used to find the submitted rich-text value, up to 255 characters. | +| `dispatchActionConfig?` | [`JsonObject`](utilities.md#jsonobject) | Configuration controlling when editing dispatches a `block_actions` payload. | +| `focusOnLoad?` | `boolean` | Whether this element receives focus when its containing view opens. | +| `initialValue?` | [`JsonObject`](utilities.md#jsonobject) | Rich-text content present when the editor first loads. | +| `maxLines?` | `number` | Maximum visible editor lines before scrolling, between 1 and 100. | +| `minLines?` | `number` | Minimum visible editor lines before scrolling, between 1 and 100. | +| `placeholder?` | [`TextLike`](objects.md#textlike) | Plain-text prompt shown in the empty editor, up to 150 characters. | + +*** + +## richTextInput() + +> **richTextInput**(`input`, `settings?`): [`SlackObject`](utilities.md#slackobject)<`"rich_text_input"`> + +Creates a rich-text input for a modal or App Home tab. + +### Input fields + +Initial content, dispatch configuration, line limits, and display behavior. + +| Input field | Type | Description | +| ------ | ------ | ------ | +| `actionId` | `string` | Identifier used to find the submitted rich-text value, up to 255 characters. | +| `dispatchActionConfig?` | [`JsonObject`](utilities.md#jsonobject) | Configuration controlling when editing dispatches a `block_actions` payload. | +| `focusOnLoad?` | `boolean` | Whether this element receives focus when its containing view opens. | +| `initialValue?` | [`JsonObject`](utilities.md#jsonobject) | Rich-text content present when the editor first loads. | +| `maxLines?` | `number` | Maximum visible editor lines before scrolling, between 1 and 100. | +| `minLines?` | `number` | Minimum visible editor lines before scrolling, between 1 and 100. | +| `placeholder?` | [`TextLike`](objects.md#textlike) | Plain-text prompt shown in the empty editor, up to 150 characters. | + +### Settings + +| Setting | Type | Description | +| ------ | ------ | ------ | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`SlackObject`](utilities.md#slackobject)<`"rich_text_input"`> + +A validated Slack `rich_text_input` element. + +### Throws + +InvalidUsageError when an identifier, placeholder, content, or line limit is invalid. + +*** + +## staticMultiSelect() + +> **staticMultiSelect**(`input`, `settings?`): [`SlackObject`](utilities.md#slackobject)<`"multi_static_select"`> + +Creates a multi-select menu from options embedded directly in the Block Kit payload. + +### Input fields + +Options or option groups, initial selection, confirmation, and display behavior. + +| Input field | Type | Description | +| ------ | ------ | ------ | +| `actionId` | `string` | Identifier returned when the selection changes, up to 255 characters. | +| `confirm?` | [`JsonObject`](utilities.md#jsonobject) | Optional confirmation dialog shown before the selection is submitted. | +| `focusOnLoad?` | `boolean` | Whether this element receives focus when its containing view opens. | +| `initialOptions?` | [`JsonObject`](utilities.md#jsonobject)[] | Options selected when the menu first loads. | +| `maxSelectedItems?` | `number` | Maximum number of options that may be selected; the minimum is one. | +| `optionGroups?` | [`JsonObject`](utilities.md#jsonobject)[] | Up to 100 groups of options; mutually exclusive with `options`. | +| `options?` | [`JsonObject`](utilities.md#jsonobject)[] | Up to 100 directly supplied options; mutually exclusive with `optionGroups`. | +| `placeholder?` | [`TextLike`](objects.md#textlike) | Plain-text prompt shown before a selection, up to 150 characters. | + +### Settings + +| Setting | Type | Description | +| ------ | ------ | ------ | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`SlackObject`](utilities.md#slackobject)<`"multi_static_select"`> + +A validated Slack `multi_static_select` element. + +### Throws + +InvalidUsageError when options, identifiers, or selection constraints are invalid. + +*** + +## StaticMultiSelectInput + +Fields accepted by [staticMultiSelect](#staticmultiselect). + +### Properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `actionId` | `string` | Identifier returned when the selection changes, up to 255 characters. | +| `confirm?` | [`JsonObject`](utilities.md#jsonobject) | Optional confirmation dialog shown before the selection is submitted. | +| `focusOnLoad?` | `boolean` | Whether this element receives focus when its containing view opens. | +| `initialOptions?` | [`JsonObject`](utilities.md#jsonobject)[] | Options selected when the menu first loads. | +| `maxSelectedItems?` | `number` | Maximum number of options that may be selected; the minimum is one. | +| `optionGroups?` | [`JsonObject`](utilities.md#jsonobject)[] | Up to 100 groups of options; mutually exclusive with `options`. | +| `options?` | [`JsonObject`](utilities.md#jsonobject)[] | Up to 100 directly supplied options; mutually exclusive with `optionGroups`. | +| `placeholder?` | [`TextLike`](objects.md#textlike) | Plain-text prompt shown before a selection, up to 150 characters. | + +*** + +## staticSelect() + +> **staticSelect**(`input`, `settings?`): [`SlackObject`](utilities.md#slackobject)<`"static_select"`> + +Creates a single-select menu from options embedded directly in the Block Kit payload. + +### Input fields + +Options or option groups, initial option, confirmation, and display behavior. + +| Input field | Type | Description | +| ------ | ------ | ------ | +| `actionId` | `string` | Identifier returned when an option is selected, up to 255 characters. | +| `confirm?` | [`JsonObject`](utilities.md#jsonobject) | Optional confirmation dialog shown before the selection is submitted. | +| `focusOnLoad?` | `boolean` | Whether this element receives focus when its containing view opens. | +| `initialOption?` | [`JsonObject`](utilities.md#jsonobject) | Option selected when the menu first loads. | +| `optionGroups?` | [`JsonObject`](utilities.md#jsonobject)[] | Up to 100 groups of options; mutually exclusive with `options`. | +| `options?` | [`JsonObject`](utilities.md#jsonobject)[] | Up to 100 directly supplied options; mutually exclusive with `optionGroups`. | +| `placeholder?` | [`TextLike`](objects.md#textlike) | Plain-text prompt shown before a selection, up to 150 characters. | + +### Settings + +| Setting | Type | Description | +| ------ | ------ | ------ | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`SlackObject`](utilities.md#slackobject)<`"static_select"`> + +A validated Slack `static_select` element. + +### Throws + +InvalidUsageError when options, identifiers, or selection constraints are invalid. + +*** + +## StaticSelectInput + +Fields accepted by [staticSelect](#staticselect). + +### Properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `actionId` | `string` | Identifier returned when an option is selected, up to 255 characters. | +| `confirm?` | [`JsonObject`](utilities.md#jsonobject) | Optional confirmation dialog shown before the selection is submitted. | +| `focusOnLoad?` | `boolean` | Whether this element receives focus when its containing view opens. | +| `initialOption?` | [`JsonObject`](utilities.md#jsonobject) | Option selected when the menu first loads. | +| `optionGroups?` | [`JsonObject`](utilities.md#jsonobject)[] | Up to 100 groups of options; mutually exclusive with `options`. | +| `options?` | [`JsonObject`](utilities.md#jsonobject)[] | Up to 100 directly supplied options; mutually exclusive with `optionGroups`. | +| `placeholder?` | [`TextLike`](objects.md#textlike) | Plain-text prompt shown before a selection, up to 150 characters. | + +*** + +## timePicker() + +> **timePicker**(`input`, `settings?`): [`SlackObject`](utilities.md#slackobject)<`"timepicker"`> + +Creates a time picker. + +### Input fields + +Initial time, timezone, confirmation, and display behavior. + +| Input field | Type | Description | +| ------ | ------ | ------ | +| `actionId` | `string` | Identifier returned when a time is selected, up to 255 characters. | +| `confirm?` | [`JsonObject`](utilities.md#jsonobject) | Optional confirmation dialog shown after a time is selected. | +| `focusOnLoad?` | `boolean` | Whether this element receives focus when its containing view opens. | +| `initialTime?` | `string` | Initially selected time in 24-hour `HH:mm` format. | +| `placeholder?` | [`TextLike`](objects.md#textlike) | Plain-text prompt shown before a time is selected, up to 150 characters. | +| `timezone?` | `string` | IANA timezone displayed as supporting text and returned with interactions. | + +### Settings + +| Setting | Type | Description | +| ------ | ------ | ------ | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`SlackObject`](utilities.md#slackobject)<`"timepicker"`> + +A validated Slack `timepicker` element. + +### Throws + +InvalidUsageError when an identifier, placeholder, time, or timezone is invalid. + +*** + +## TimePickerInput + +Fields accepted by [timePicker](#timepicker). + +### Properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `actionId` | `string` | Identifier returned when a time is selected, up to 255 characters. | +| `confirm?` | [`JsonObject`](utilities.md#jsonobject) | Optional confirmation dialog shown after a time is selected. | +| `focusOnLoad?` | `boolean` | Whether this element receives focus when its containing view opens. | +| `initialTime?` | `string` | Initially selected time in 24-hour `HH:mm` format. | +| `placeholder?` | [`TextLike`](objects.md#textlike) | Plain-text prompt shown before a time is selected, up to 150 characters. | +| `timezone?` | `string` | IANA timezone displayed as supporting text and returned with interactions. | + +*** + +## UrlElementInput + +Fields accepted by [urlInput](#urlinput). + +### Properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `actionId` | `string` | Identifier used to find the submitted URL, up to 255 characters. | +| `dispatchActionConfig?` | [`JsonObject`](utilities.md#jsonobject) | Configuration controlling when typing dispatches a `block_actions` payload. | +| `focusOnLoad?` | `boolean` | Whether this element receives focus when its containing view opens. | +| `initialValue?` | `string` | URL present when the input first loads. | +| `placeholder?` | [`TextLike`](objects.md#textlike) | Plain-text prompt shown in the empty input, up to 150 characters. | + +*** + +## urlInput() + +> **urlInput**(`input`, `settings?`): [`SlackObject`](utilities.md#slackobject)<`"url_text_input"`> + +Creates a URL input. + +### Input fields + +Initial URL, dispatch configuration, and display behavior. + +| Input field | Type | Description | +| ------ | ------ | ------ | +| `actionId` | `string` | Identifier used to find the submitted URL, up to 255 characters. | +| `dispatchActionConfig?` | [`JsonObject`](utilities.md#jsonobject) | Configuration controlling when typing dispatches a `block_actions` payload. | +| `focusOnLoad?` | `boolean` | Whether this element receives focus when its containing view opens. | +| `initialValue?` | `string` | URL present when the input first loads. | +| `placeholder?` | [`TextLike`](objects.md#textlike) | Plain-text prompt shown in the empty input, up to 150 characters. | + +### Settings + +| Setting | Type | Description | +| ------ | ------ | ------ | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`SlackObject`](utilities.md#slackobject)<`"url_text_input"`> + +A validated Slack `url_text_input` element. + +### Throws + +InvalidUsageError when an identifier, placeholder, or initial URL is invalid. + +*** + +## urlSource() + +> **urlSource**(`input`, `settings?`): [`SlackObject`](utilities.md#slackobject)<`"url"`> + +Creates a source link for a task card. + +### Input fields + +Public URL and human-readable link text. + +| Input field | Type | Description | +| ------ | ------ | ------ | +| `text` | `string` | Human-readable source label. | +| `url` | `string` | Public source URL. | + +### Settings + +| Setting | Type | Description | +| ------ | ------ | ------ | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`SlackObject`](utilities.md#slackobject)<`"url"`> + +A validated Slack `url` source element. + +### Throws + +InvalidUsageError when a field violates Slack's constraints. + +*** + +## userMultiSelect() + +> **userMultiSelect**(`input`, `settings?`): [`SlackObject`](utilities.md#slackobject)<`"multi_users_select"`> + +Creates a multi-select menu populated with users visible in the active workspace. + +### Input fields + +Initial users, confirmation, selection limit, and display behavior. + +| Input field | Type | Description | +| ------ | ------ | ------ | +| `actionId` | `string` | Identifier returned when the selection changes, up to 255 characters. | +| `confirm?` | [`JsonObject`](utilities.md#jsonobject) | Optional confirmation dialog shown before the selection is submitted. | +| `focusOnLoad?` | `boolean` | Whether this element receives focus when its containing view opens. | +| `initialUsers?` | `string`[] | User IDs selected when the menu first loads. | +| `maxSelectedItems?` | `number` | Maximum number of users that may be selected; the minimum is one. | +| `placeholder?` | [`TextLike`](objects.md#textlike) | Plain-text prompt shown before a selection, up to 150 characters. | + +### Settings + +| Setting | Type | Description | +| ------ | ------ | ------ | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`SlackObject`](utilities.md#slackobject)<`"multi_users_select"`> + +A validated Slack `multi_users_select` element. + +### Throws + +InvalidUsageError when an identifier, placeholder, or selection constraint is invalid. + +*** + +## UserMultiSelectInput + +Fields accepted by [userMultiSelect](#usermultiselect). + +### Properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `actionId` | `string` | Identifier returned when the selection changes, up to 255 characters. | +| `confirm?` | [`JsonObject`](utilities.md#jsonobject) | Optional confirmation dialog shown before the selection is submitted. | +| `focusOnLoad?` | `boolean` | Whether this element receives focus when its containing view opens. | +| `initialUsers?` | `string`[] | User IDs selected when the menu first loads. | +| `maxSelectedItems?` | `number` | Maximum number of users that may be selected; the minimum is one. | +| `placeholder?` | [`TextLike`](objects.md#textlike) | Plain-text prompt shown before a selection, up to 150 characters. | + +*** + +## userSelect() + +> **userSelect**(`input`, `settings?`): [`SlackObject`](utilities.md#slackobject)<`"users_select"`> + +Creates a single-select menu populated with users visible in the active workspace. + +### Input fields + +Initial user, confirmation, and display behavior. + +| Input field | Type | Description | +| ------ | ------ | ------ | +| `actionId` | `string` | Identifier returned when a user is selected, up to 255 characters. | +| `confirm?` | [`JsonObject`](utilities.md#jsonobject) | Optional confirmation dialog shown before the selection is submitted. | +| `focusOnLoad?` | `boolean` | Whether this element receives focus when its containing view opens. | +| `initialUser?` | `string` | User ID selected when the menu first loads. | +| `placeholder?` | [`TextLike`](objects.md#textlike) | Plain-text prompt shown before a selection, up to 150 characters. | + +### Settings + +| Setting | Type | Description | +| ------ | ------ | ------ | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`SlackObject`](utilities.md#slackobject)<`"users_select"`> + +A validated Slack `users_select` element. + +### Throws + +InvalidUsageError when an identifier, placeholder, or initial user is invalid. + +*** + +## UserSelectInput + +Fields accepted by [userSelect](#userselect). + +### Properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `actionId` | `string` | Identifier returned when a user is selected, up to 255 characters. | +| `confirm?` | [`JsonObject`](utilities.md#jsonobject) | Optional confirmation dialog shown before the selection is submitted. | +| `focusOnLoad?` | `boolean` | Whether this element receives focus when its containing view opens. | +| `initialUser?` | `string` | User ID selected when the menu first loads. | +| `placeholder?` | [`TextLike`](objects.md#textlike) | Plain-text prompt shown before a selection, up to 150 characters. | + +*** + +## workflowButton() + +> **workflowButton**(`input`, `settings?`): [`SlackObject`](utilities.md#slackobject)<`"workflow_button"`> + +Creates a button that launches a Slack workflow. + +### Input fields + +Button label, workflow trigger, and optional interaction behavior. + +| Input field | Type | Description | +| ------ | ------ | ------ | +| `accessibilityLabel?` | `string` | Accessible label when the visible text is insufficient. | +| `actionId?` | `string` | Optional interaction identifier. | +| `confirm?` | [`JsonObject`](utilities.md#jsonobject) | Optional confirmation dialog. | +| `style?` | `"primary"` \| `"danger"` | Optional visual emphasis. | +| `text` | [`TextLike`](objects.md#textlike) | Plain-text label displayed on the button. | +| `workflow` | [`JsonObject`](utilities.md#jsonobject) | Workflow object created with `workflow`. | + +### Settings + +| Setting | Type | Description | +| ------ | ------ | ------ | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`SlackObject`](utilities.md#slackobject)<`"workflow_button"`> + +A validated Slack `workflow_button` element. + +### Throws + +InvalidUsageError when text or identifiers violate Slack's constraints. + +*** + +## WorkflowButtonInput + +Fields accepted by [workflowButton](#workflowbutton). + +### Properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `accessibilityLabel?` | `string` | Accessible label when the visible text is insufficient. | +| `actionId?` | `string` | Optional interaction identifier. | +| `confirm?` | [`JsonObject`](utilities.md#jsonobject) | Optional confirmation dialog. | +| `style?` | `"primary"` \| `"danger"` | Optional visual emphasis. | +| `text` | [`TextLike`](objects.md#textlike) | Plain-text label displayed on the button. | +| `workflow` | [`JsonObject`](utilities.md#jsonobject) | Workflow object created with `workflow`. | diff --git a/docs/versioned_docs/version-2.1.0/reference/typescript/errors.md b/docs/versioned_docs/version-2.1.0/reference/typescript/errors.md new file mode 100644 index 00000000..1fea67e3 --- /dev/null +++ b/docs/versioned_docs/version-2.1.0/reference/typescript/errors.md @@ -0,0 +1,265 @@ +--- +toc_min_heading_level: 2 +toc_max_heading_level: 2 +--- + +# Errors + +Typed validation errors returned by eager construction and explicit validation. + +## ErrorCategory + +> **ErrorCategory** = `"length-exceeded"` \| `"out-of-range"` \| `"mutually-exclusive"` \| `"type-mismatch"` \| `"missing-required"` \| `"invalid-usage"` + +Stable machine-readable category attached to every validation error. + +*** + +## InvalidUsageError + +Base class for invalid Block Kit input. + +Catch this class to handle every slackblocks validation failure, or catch a +subclass when the reason matters to application behavior. + +### Extends + +- `Error` + +### Extended by + +- [`LengthError`](#lengtherror) +- [`OutOfRangeError`](#outofrangeerror) +- [`MutualExclusivityError`](#mutualexclusivityerror) +- [`TypeMismatchError`](#typemismatcherror) +- [`MissingRequiredError`](#missingrequirederror) + +### Constructors + +#### Constructor + +> **new InvalidUsageError**(`path`, `message`): [`InvalidUsageError`](#invalidusageerror) + +Creates a validation error. + +##### Parameters + +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `path` | `string` | Dot-and-index path to the invalid field. | +| `message` | `string` | Human-readable explanation of the constraint. | + +##### Returns + +[`InvalidUsageError`](#invalidusageerror) + +##### Overrides + +`Error.constructor` + +### Properties + +| Property | Modifier | Type | Default value | Description | +| ------ | ------ | ------ | ------ | ------ | +| `category` | `readonly` | [`ErrorCategory`](#errorcategory) | `"invalid-usage"` | Machine-readable failure category. | +| `path` | `readonly` | `string` | `undefined` | Dot-and-index path to the invalid payload field. | + +*** + +## LengthError + +A string, array, or collection exceeded an allowed minimum or maximum length. + +### Extends + +- [`InvalidUsageError`](#invalidusageerror) + +### Constructors + +#### Constructor + +> **new LengthError**(`path`, `message`): [`LengthError`](#lengtherror) + +Creates a validation error. + +##### Parameters + +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `path` | `string` | Dot-and-index path to the invalid field. | +| `message` | `string` | Human-readable explanation of the constraint. | + +##### Returns + +[`LengthError`](#lengtherror) + +##### Inherited from + +[`InvalidUsageError`](#invalidusageerror).[`constructor`](#constructor) + +### Properties + +| Property | Modifier | Type | Description | Overrides | +| ------ | ------ | ------ | ------ | ------ | +| `category` | `readonly` | `"length-exceeded"` | Machine-readable failure category. | [`InvalidUsageError`](#invalidusageerror).[`category`](#property-category) | +| `path` | `readonly` | `string` | Dot-and-index path to the invalid payload field. | - | + +*** + +## MissingRequiredError + +A required field or one-of requirement was not satisfied. + +### Extends + +- [`InvalidUsageError`](#invalidusageerror) + +### Constructors + +#### Constructor + +> **new MissingRequiredError**(`path`, `message`): [`MissingRequiredError`](#missingrequirederror) + +Creates a validation error. + +##### Parameters + +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `path` | `string` | Dot-and-index path to the invalid field. | +| `message` | `string` | Human-readable explanation of the constraint. | + +##### Returns + +[`MissingRequiredError`](#missingrequirederror) + +##### Inherited from + +[`InvalidUsageError`](#invalidusageerror).[`constructor`](#constructor) + +### Properties + +| Property | Modifier | Type | Description | Overrides | +| ------ | ------ | ------ | ------ | ------ | +| `category` | `readonly` | `"missing-required"` | Machine-readable failure category. | [`InvalidUsageError`](#invalidusageerror).[`category`](#property-category) | +| `path` | `readonly` | `string` | Dot-and-index path to the invalid payload field. | - | + +*** + +## MutualExclusivityError + +Fields that cannot be used together were both supplied. + +### Extends + +- [`InvalidUsageError`](#invalidusageerror) + +### Constructors + +#### Constructor + +> **new MutualExclusivityError**(`path`, `message`): [`MutualExclusivityError`](#mutualexclusivityerror) + +Creates a validation error. + +##### Parameters + +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `path` | `string` | Dot-and-index path to the invalid field. | +| `message` | `string` | Human-readable explanation of the constraint. | + +##### Returns + +[`MutualExclusivityError`](#mutualexclusivityerror) + +##### Inherited from + +[`InvalidUsageError`](#invalidusageerror).[`constructor`](#constructor) + +### Properties + +| Property | Modifier | Type | Description | Overrides | +| ------ | ------ | ------ | ------ | ------ | +| `category` | `readonly` | `"mutually-exclusive"` | Machine-readable failure category. | [`InvalidUsageError`](#invalidusageerror).[`category`](#property-category) | +| `path` | `readonly` | `string` | Dot-and-index path to the invalid payload field. | - | + +*** + +## OutOfRangeError + +A numeric value fell outside its allowed range. + +### Extends + +- [`InvalidUsageError`](#invalidusageerror) + +### Constructors + +#### Constructor + +> **new OutOfRangeError**(`path`, `message`): [`OutOfRangeError`](#outofrangeerror) + +Creates a validation error. + +##### Parameters + +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `path` | `string` | Dot-and-index path to the invalid field. | +| `message` | `string` | Human-readable explanation of the constraint. | + +##### Returns + +[`OutOfRangeError`](#outofrangeerror) + +##### Inherited from + +[`InvalidUsageError`](#invalidusageerror).[`constructor`](#constructor) + +### Properties + +| Property | Modifier | Type | Description | Overrides | +| ------ | ------ | ------ | ------ | ------ | +| `category` | `readonly` | `"out-of-range"` | Machine-readable failure category. | [`InvalidUsageError`](#invalidusageerror).[`category`](#property-category) | +| `path` | `readonly` | `string` | Dot-and-index path to the invalid payload field. | - | + +*** + +## TypeMismatchError + +A payload field or nested object has the wrong runtime type. + +### Extends + +- [`InvalidUsageError`](#invalidusageerror) + +### Constructors + +#### Constructor + +> **new TypeMismatchError**(`path`, `message`): [`TypeMismatchError`](#typemismatcherror) + +Creates a validation error. + +##### Parameters + +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `path` | `string` | Dot-and-index path to the invalid field. | +| `message` | `string` | Human-readable explanation of the constraint. | + +##### Returns + +[`TypeMismatchError`](#typemismatcherror) + +##### Inherited from + +[`InvalidUsageError`](#invalidusageerror).[`constructor`](#constructor) + +### Properties + +| Property | Modifier | Type | Description | Overrides | +| ------ | ------ | ------ | ------ | ------ | +| `category` | `readonly` | `"type-mismatch"` | Machine-readable failure category. | [`InvalidUsageError`](#invalidusageerror).[`category`](#property-category) | +| `path` | `readonly` | `string` | Dot-and-index path to the invalid payload field. | - | diff --git a/docs/versioned_docs/version-2.1.0/reference/typescript/index.md b/docs/versioned_docs/version-2.1.0/reference/typescript/index.md new file mode 100644 index 00000000..eed39e2d --- /dev/null +++ b/docs/versioned_docs/version-2.1.0/reference/typescript/index.md @@ -0,0 +1,14 @@ +# TypeScript API reference + +This is the complete guide to slackblocks' public TypeScript API. Use it to find the factory, input type, or validation error you need while building a message, modal, or home tab. + +Most applications start with a factory such as `message()`, `sectionBlock()`, or `modal()`. The interfaces describe their camelCase inputs, while the returned objects use the snake_case fields expected by Slack. + +- [Blocks](blocks.md) +- [Elements](elements.md) +- [Composition Objects](objects.md) +- [Rich Text](rich-text.md) +- [Messages](messages.md) +- [Views](views.md) +- [Utilities](utilities.md) +- [Errors](errors.md) diff --git a/docs/versioned_docs/version-2.1.0/reference/typescript/messages.md b/docs/versioned_docs/version-2.1.0/reference/typescript/messages.md new file mode 100644 index 00000000..a4605b27 --- /dev/null +++ b/docs/versioned_docs/version-2.1.0/reference/typescript/messages.md @@ -0,0 +1,209 @@ +--- +toc_min_heading_level: 2 +toc_max_heading_level: 2 +--- + +# Messages + +Payload factories for Web API messages, webhooks, and interaction responses. + +## attachment() + +> **attachment**(`input`, `settings?`): [`JsonObject`](utilities.md#jsonobject) + +Creates lower-priority supporting content using Slack's legacy secondary-attachment format. + +Attachments can add context beneath a message, while `fallback` supplies a +plain-text summary for notifications and clients that cannot display Block Kit. + +### Input fields + +Attachment blocks plus optional color and fallback text. + +| Input field | Type | Description | +| ------ | ------ | ------ | +| `blocks` | [`JsonObject`](utilities.md#jsonobject)[] | Blocks displayed inside the attachment. | +| `color?` | `string` | Optional side-border color: a `Color` value or a six-digit hex code. | +| `fallback?` | `string` | Plain-text fallback for notifications and clients without Block Kit support. | + +### Settings + +| Setting | Type | Description | +| ------ | ------ | ------ | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`JsonObject`](utilities.md#jsonobject) + +A Slack attachment object. + +### Throws + +InvalidUsageError when the color is not a valid hex code or a nested + block violates a supported Block Kit constraint. + +### See + +https://docs.slack.dev/legacy/legacy-messaging/legacy-secondary-message-attachments + +*** + +## Color + +> `const` **Color**: `object` + +Preset side-border colors for legacy attachments. + +The values mirror the Python `Color` enum: three Slack-recognized aliases +(`good`, `warning`, `danger`) plus common hex colors. + +### Type Declaration + +| Name | Type | Default value | +| ------ | ------ | ------ | +| `BLACK` | `"#000000"` | `"#000000"` | +| `BLUE` | `"#0000ff"` | `"#0000ff"` | +| `DANGER` | `"danger"` | `"danger"` | +| `GOOD` | `"good"` | `"good"` | +| `GREEN` | `"#00ff00"` | `"#00ff00"` | +| `ORANGE` | `"#ff8800"` | `"#ff8800"` | +| `PURPLE` | `"#8800ff"` | `"#8800ff"` | +| `RED` | `"#ff0000"` | `"#ff0000"` | +| `WARNING` | `"warning"` | `"warning"` | +| `YELLOW` | `"#ffff00"` | `"#ffff00"` | + +*** + +## message() + +> **message**(`input`, `settings?`): [`JsonObject`](utilities.md#jsonobject) + +Creates a payload for Slack Web API message methods such as `chat.postMessage`. + +### Input fields + +Destination channel and message content. + +| Input field | Type | Description | +| ------ | ------ | ------ | +| `attachments?` | [`JsonObject`](utilities.md#jsonobject)[] | Optional secondary attachments. | +| `blocks?` | [`JsonObject`](utilities.md#jsonobject)[] | Block Kit blocks displayed in the message. | +| `channel` | `string` | Channel, group, or direct-message conversation identifier. | +| `metadata?` | [`JsonObject`](utilities.md#jsonobject) | Optional message metadata. | +| `mrkdwn?` | `boolean` | Whether Slack parses `text` as mrkdwn. Defaults to `true`. | +| `text?` | `string` | Notification and accessibility fallback text. | +| `unfurlLinks?` | `boolean` | Whether Slack unfurls links. | +| `unfurlMedia?` | `boolean` | Whether Slack unfurls media. | + +### Settings + +| Setting | Type | Description | +| ------ | ------ | ------ | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`JsonObject`](utilities.md#jsonobject) + +A Slack-shaped message payload ready to spread into an SDK call. + +### Throws + +InvalidUsageError when nested Block Kit content is invalid. + +*** + +## MessageInput + +Fields accepted by [message](#message). + +### Properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `attachments?` | [`JsonObject`](utilities.md#jsonobject)[] | Optional secondary attachments. | +| `blocks?` | [`JsonObject`](utilities.md#jsonobject)[] | Block Kit blocks displayed in the message. | +| `channel` | `string` | Channel, group, or direct-message conversation identifier. | +| `metadata?` | [`JsonObject`](utilities.md#jsonobject) | Optional message metadata. | +| `mrkdwn?` | `boolean` | Whether Slack parses `text` as mrkdwn. Defaults to `true`. | +| `text?` | `string` | Notification and accessibility fallback text. | +| `unfurlLinks?` | `boolean` | Whether Slack unfurls links. | +| `unfurlMedia?` | `boolean` | Whether Slack unfurls media. | + +*** + +## messageResponse() + +> **messageResponse**(`input`, `settings?`): [`JsonObject`](utilities.md#jsonobject) + +Creates a response payload for slash commands and interactive requests. + +### Input fields + +Response content, visibility, and replacement behavior. + +| Input field | Type | Description | +| ------ | ------ | ------ | +| `attachments?` | [`JsonObject`](utilities.md#jsonobject)[] | Optional secondary attachments. | +| `blocks?` | [`JsonObject`](utilities.md#jsonobject)[] | Block Kit blocks displayed in the response. | +| `mrkdwn?` | `boolean` | Whether Slack parses `text` as mrkdwn. Defaults to `true`. | +| `replaceOriginal?` | `boolean` | Replace the original interaction message. Defaults to `false`. | +| `responseType?` | `"ephemeral"` \| `"in_channel"` | Response visibility. Defaults to `in_channel`. | +| `text?` | `string` | Notification and accessibility fallback text. | + +### Settings + +| Setting | Type | Description | +| ------ | ------ | ------ | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`JsonObject`](utilities.md#jsonobject) + +A Slack interaction-response payload. + +### Throws + +InvalidUsageError when nested Block Kit content is invalid. + +*** + +## webhookMessage() + +> **webhookMessage**(`input`, `settings?`): [`JsonObject`](utilities.md#jsonobject) + +Creates a payload for an incoming webhook or response URL. + +### Input fields + +Message content, visibility, replacement behavior, and unfurl settings. + +| Input field | Type | Description | +| ------ | ------ | ------ | +| `attachments?` | [`JsonObject`](utilities.md#jsonobject)[] | Optional secondary attachments. | +| `blocks?` | [`JsonObject`](utilities.md#jsonobject)[] | Block Kit blocks displayed in the message. | +| `deleteOriginal?` | `boolean` | Delete the original interaction message. | +| `metadata?` | [`JsonObject`](utilities.md#jsonobject) | Optional message metadata. | +| `replaceOriginal?` | `boolean` | Replace the original interaction message. | +| `responseType?` | `"ephemeral"` \| `"in_channel"` | Response visibility for response URLs. | +| `text?` | `string` | Notification and accessibility fallback text. | +| `unfurlLinks?` | `boolean` | Whether Slack unfurls links. | +| `unfurlMedia?` | `boolean` | Whether Slack unfurls media. | + +### Settings + +| Setting | Type | Description | +| ------ | ------ | ------ | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`JsonObject`](utilities.md#jsonobject) + +A Slack webhook-message payload. + +### Throws + +InvalidUsageError when nested Block Kit content is invalid. diff --git a/docs/versioned_docs/version-2.1.0/reference/typescript/objects.md b/docs/versioned_docs/version-2.1.0/reference/typescript/objects.md new file mode 100644 index 00000000..6a5f27e6 --- /dev/null +++ b/docs/versioned_docs/version-2.1.0/reference/typescript/objects.md @@ -0,0 +1,870 @@ +--- +toc_min_heading_level: 2 +toc_max_heading_level: 2 +--- + +# Composition Objects + +Composition-object factories used as fields inside blocks and elements. + +These helpers cover text, options, confirmations, workflow metadata, files, +table cells, icons, and chart data. + +## areaChart() + +> **areaChart**(`series`, `axis`, `settings?`): [`SlackObject`](utilities.md#slackobject)<`"area"`> + +Creates an area chart. + +### Parameters + +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `series` | [`JsonObject`](utilities.md#jsonobject)[] | One to 12 uniquely named data series. | +| `axis` | [`JsonObject`](utilities.md#jsonobject) | Axis configuration whose categories match every series. | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`SlackObject`](utilities.md#slackobject)<`"area"`> + +A validated Slack `area` chart object. + +### Throws + +InvalidUsageError when series and axis categories do not match. + +*** + +## asText() + +> **asText**(`value`, `kind?`, `settings?`): [`TextObject`](#textobject) + +Converts a string to a text object while preserving existing text objects. + +### Parameters + +| Parameter | Type | Default value | Description | +| ------ | ------ | ------ | ------ | +| `value` | [`TextLike`](#textlike) | `undefined` | String or existing text object. | +| `kind` | `"plain_text"` \| `"mrkdwn"` | `"mrkdwn"` | Text kind used for strings. Defaults to `mrkdwn`. | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | `{}` | Per-call validation settings. | + +### Returns + +[`TextObject`](#textobject) + +A Slack text composition object. + +### Throws + +InvalidUsageError when the text violates Slack's length constraints. + +*** + +## axisConfig() + +> **axisConfig**(`input`, `settings?`): [`JsonObject`](utilities.md#jsonobject) + +Creates category and label configuration for an axis-based chart. + +### Input fields + +Ordered categories and optional axis labels. + +| Input field | Type | Description | +| ------ | ------ | ------ | +| `categories` | `string`[] | Unique category labels, in display order. | +| `xLabel?` | `string` | Optional horizontal-axis label, up to 50 characters. | +| `yLabel?` | `string` | Optional vertical-axis label, up to 50 characters. | + +### Settings + +| Setting | Type | Description | +| ------ | ------ | ------ | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`JsonObject`](utilities.md#jsonobject) + +A validated chart-axis configuration object. + +### Throws + +InvalidUsageError when labels are duplicated or exceed Slack's limits. + +*** + +## AxisConfigInput + +Fields accepted by [axisConfig](#axisconfig). + +### Properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `categories` | `string`[] | Unique category labels, in display order. | +| `xLabel?` | `string` | Optional horizontal-axis label, up to 50 characters. | +| `yLabel?` | `string` | Optional vertical-axis label, up to 50 characters. | + +*** + +## barChart() + +> **barChart**(`series`, `axis`, `settings?`): [`SlackObject`](utilities.md#slackobject)<`"bar"`> + +Creates a grouped bar chart. + +### Parameters + +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `series` | [`JsonObject`](utilities.md#jsonobject)[] | One to 12 uniquely named data series. | +| `axis` | [`JsonObject`](utilities.md#jsonobject) | Axis configuration whose categories match every series. | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`SlackObject`](utilities.md#slackobject)<`"bar"`> + +A validated Slack `bar` chart object. + +### Throws + +InvalidUsageError when series and axis categories do not match. + +*** + +## chartSegment() + +> **chartSegment**(`input`, `settings?`): [`JsonObject`](utilities.md#jsonobject) + +Creates one labelled segment for a pie chart. + +### Input fields + +Segment label and positive value. + +| Input field | Type | Description | +| ------ | ------ | ------ | +| `label` | `string` | Segment label, up to 20 characters. | +| `value` | `number` | Positive finite segment value. | + +### Settings + +| Setting | Type | Description | +| ------ | ------ | ------ | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`JsonObject`](utilities.md#jsonobject) + +A validated chart-segment object. + +### Throws + +InvalidUsageError when the label or value violates chart constraints. + +*** + +## ChartSegmentInput + +Fields accepted by [chartSegment](#chartsegment). + +### Properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `label` | `string` | Segment label, up to 20 characters. | +| `value` | `number` | Positive finite segment value. | + +*** + +## columnSettings() + +> **columnSettings**(`input`, `settings?`): [`JsonObject`](utilities.md#jsonobject) + +Creates display settings for one table column. + +### Input fields + +Horizontal alignment and optional wrapping behavior. + +| Input field | Type | Description | +| ------ | ------ | ------ | +| `align?` | `"left"` \| `"center"` \| `"right"` | Horizontal cell alignment. | +| `isWrapped?` | `boolean` | Whether long cell content wraps. | + +### Settings + +| Setting | Type | Description | +| ------ | ------ | ------ | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`JsonObject`](utilities.md#jsonobject) + +A Slack table column-settings object. + +*** + +## confirmation() + +> **confirmation**(`input`, `settings?`): [`JsonObject`](utilities.md#jsonobject) + +Creates a confirmation dialog for an interactive element. + +### Input fields + +Dialog title, question, and button labels. + +| Input field | Type | Description | +| ------ | ------ | ------ | +| `confirm` | [`TextLike`](#textlike) | Plain-text confirm-button label, up to 30 characters. | +| `deny` | [`TextLike`](#textlike) | Plain-text cancel-button label, up to 30 characters. | +| `text` | [`TextLike`](#textlike) | Confirmation question, up to 300 characters. | +| `title` | [`TextLike`](#textlike) | Plain-text dialog title, up to 100 characters. | + +### Settings + +| Setting | Type | Description | +| ------ | ------ | ------ | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`JsonObject`](utilities.md#jsonobject) + +A validated Slack confirmation object. + +### Throws + +InvalidUsageError when a text field exceeds Slack's limit. + +*** + +## ConfirmationInput + +Fields accepted by [confirmation](#confirmation). + +### Properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `confirm` | [`TextLike`](#textlike) | Plain-text confirm-button label, up to 30 characters. | +| `deny` | [`TextLike`](#textlike) | Plain-text cancel-button label, up to 30 characters. | +| `text` | [`TextLike`](#textlike) | Confirmation question, up to 300 characters. | +| `title` | [`TextLike`](#textlike) | Plain-text dialog title, up to 100 characters. | + +*** + +## conversationFilter() + +> **conversationFilter**(`input`, `settings?`): [`JsonObject`](utilities.md#jsonobject) + +Creates filters for a conversation select menu. + +### Input fields + +Conversation types and optional exclusions. At least one field is required. + +| Input field | Type | Description | +| ------ | ------ | ------ | +| `excludeBotUsers?` | `boolean` | Exclude direct messages with bots. | +| `excludeExternalSharedChannels?` | `boolean` | Exclude externally shared conversations. | +| `include?` | `string`[] | Conversation kinds to include, such as `im`, `mpim`, `private`, or `public`. | + +### Settings + +| Setting | Type | Description | +| ------ | ------ | ------ | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`JsonObject`](utilities.md#jsonobject) + +A validated Slack conversation-filter object. + +### Throws + +MissingRequiredError when no filter field is supplied. + +*** + +## dataPoint() + +> **dataPoint**(`input`, `settings?`): [`JsonObject`](utilities.md#jsonobject) + +Creates one labelled data point for an axis-based chart. + +### Input fields + +Category label and finite value. + +| Input field | Type | Description | +| ------ | ------ | ------ | +| `label` | `string` | Category label, up to 20 characters. | +| `value` | `number` | Finite numeric value. | + +### Settings + +| Setting | Type | Description | +| ------ | ------ | ------ | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`JsonObject`](utilities.md#jsonobject) + +A validated data-point object. + +### Throws + +InvalidUsageError when the label or value violates chart constraints. + +*** + +## DataPointInput + +Fields accepted by [dataPoint](#datapoint). + +### Properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `label` | `string` | Category label, up to 20 characters. | +| `value` | `number` | Finite numeric value. | + +*** + +## dataSeries() + +> **dataSeries**(`input`, `settings?`): [`JsonObject`](utilities.md#jsonobject) + +Creates one named series for an axis-based chart. + +### Input fields + +Series name and ordered data points. + +| Input field | Type | Description | +| ------ | ------ | ------ | +| `data` | [`JsonObject`](utilities.md#jsonobject)[] | Between one and 20 points created with `dataPoint`. | +| `name` | `string` | Unique series name, up to 20 characters. | + +### Settings + +| Setting | Type | Description | +| ------ | ------ | ------ | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`JsonObject`](utilities.md#jsonobject) + +A validated chart-series object. + +### Throws + +InvalidUsageError when the name or point count violates chart constraints. + +*** + +## DataSeriesInput + +Fields accepted by [dataSeries](#dataseries). + +### Properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `data` | [`JsonObject`](utilities.md#jsonobject)[] | Between one and 20 points created with `dataPoint`. | +| `name` | `string` | Unique series name, up to 20 characters. | + +*** + +## dispatchActionConfiguration() + +> **dispatchActionConfiguration**(`input`, `settings?`): [`JsonObject`](utilities.md#jsonobject) + +Creates a dispatch-action configuration for an input element. + +### Input fields + +Interaction events that should dispatch immediately. + +| Input field | Type | Description | +| ------ | ------ | ------ | +| `triggerActionsOn` | `string`[] | Events such as `on_enter_pressed` or `on_character_entered`. | + +### Settings + +| Setting | Type | Description | +| ------ | ------ | ------ | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`JsonObject`](utilities.md#jsonobject) + +A Slack dispatch-action configuration object. + +*** + +## inputParameter() + +> **inputParameter**(`input`, `settings?`): [`JsonObject`](utilities.md#jsonobject) + +Creates a customizable workflow input parameter. + +### Input fields + +Workflow parameter name and value. + +| Input field | Type | Description | +| ------ | ------ | ------ | +| `name` | `string` | Workflow parameter name. | +| `value` | `string` | Value passed to the workflow. | + +### Settings + +| Setting | Type | Description | +| ------ | ------ | ------ | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`JsonObject`](utilities.md#jsonobject) + +A Slack workflow input-parameter object. + +*** + +## lineChart() + +> **lineChart**(`series`, `axis`, `settings?`): [`SlackObject`](utilities.md#slackobject)<`"line"`> + +Creates a line chart. + +### Parameters + +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `series` | [`JsonObject`](utilities.md#jsonobject)[] | One to 12 uniquely named data series. | +| `axis` | [`JsonObject`](utilities.md#jsonobject) | Axis configuration whose categories match every series. | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`SlackObject`](utilities.md#slackobject)<`"line"`> + +A validated Slack `line` chart object. + +### Throws + +InvalidUsageError when series and axis categories do not match. + +*** + +## MarkdownOptions + +Optional behavior for [mrkdwn](#mrkdwn). + +### Properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `verbatim?` | `boolean` | Whether Slack should treat the text literally instead of auto-parsing links and mentions. | + +*** + +## mrkdwn() + +> **mrkdwn**(`text`, `options?`, `settings?`): [`TextObject`](#textobject) + +Creates a Slack mrkdwn composition object. + +### Input fields + +Optional parsing behavior. + +| Input field | Type | Description | +| ------ | ------ | ------ | +| `verbatim?` | `boolean` | Whether Slack should treat the text literally instead of auto-parsing links and mentions. | + +### Settings + +| Setting | Type | Description | +| ------ | ------ | ------ | +| `text` | `string` | Slack mrkdwn content. | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`TextObject`](#textobject) + +A validated Slack `mrkdwn` object. + +### Throws + +InvalidUsageError when the text violates Slack's length constraints. + +*** + +## option() + +> **option**(`input`, `settings?`): [`JsonObject`](utilities.md#jsonobject) + +Creates one option for a select, checkbox, radio, or overflow element. + +### Input fields + +Option label, value, and optional description or URL. + +| Input field | Type | Description | +| ------ | ------ | ------ | +| `description?` | [`TextLike`](#textlike) | Optional plain-text supporting copy, up to 75 characters. | +| `text` | [`TextLike`](#textlike) | Plain-text option label, up to 75 characters. | +| `url?` | `string` | Optional destination URL for overflow menus. | +| `value` | `string` | Application-defined value, up to 150 characters. | + +### Settings + +| Setting | Type | Description | +| ------ | ------ | ------ | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`JsonObject`](utilities.md#jsonobject) + +A validated Slack option object. + +### Throws + +InvalidUsageError when text or values exceed Slack's limits. + +*** + +## optionGroup() + +> **optionGroup**(`input`, `settings?`): [`JsonObject`](utilities.md#jsonobject) + +Creates a labelled group of options for a static select menu. + +### Input fields + +Group label and option list. + +| Input field | Type | Description | +| ------ | ------ | ------ | +| `label` | [`TextLike`](#textlike) | Plain-text group label, up to 75 characters. | +| `options` | [`JsonObject`](utilities.md#jsonobject)[] | Between one and 100 option objects. | + +### Settings + +| Setting | Type | Description | +| ------ | ------ | ------ | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`JsonObject`](utilities.md#jsonobject) + +A validated Slack option-group object. + +### Throws + +InvalidUsageError when the label or option count violates Slack's limits. + +*** + +## OptionGroupInput + +Fields accepted by [optionGroup](#optiongroup). + +### Properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `label` | [`TextLike`](#textlike) | Plain-text group label, up to 75 characters. | +| `options` | [`JsonObject`](utilities.md#jsonobject)[] | Between one and 100 option objects. | + +*** + +## OptionInput + +Fields accepted by [option](#option). + +### Properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `description?` | [`TextLike`](#textlike) | Optional plain-text supporting copy, up to 75 characters. | +| `text` | [`TextLike`](#textlike) | Plain-text option label, up to 75 characters. | +| `url?` | `string` | Optional destination URL for overflow menus. | +| `value` | `string` | Application-defined value, up to 150 characters. | + +*** + +## pieChart() + +> **pieChart**(`segments`, `settings?`): [`SlackObject`](utilities.md#slackobject)<`"pie"`> + +Creates a pie chart. + +### Parameters + +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `segments` | [`JsonObject`](utilities.md#jsonobject)[] | One to 12 segments created with `chartSegment`. | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`SlackObject`](utilities.md#slackobject)<`"pie"`> + +A validated Slack `pie` chart object. + +### Throws + +InvalidUsageError when segment data violates Slack's chart constraints. + +*** + +## plainText() + +> **plainText**(`text`, `options?`, `settings?`): [`TextObject`](#textobject) + +Creates a plain-text composition object. + +### Input fields + +Optional emoji behavior. + +| Input field | Type | Description | +| ------ | ------ | ------ | +| `emoji?` | `boolean` | Whether Slack should render emoji shortcodes. | + +### Settings + +| Setting | Type | Description | +| ------ | ------ | ------ | +| `text` | `string` | Text content. | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`TextObject`](#textobject) + +A validated Slack `plain_text` object. + +### Throws + +InvalidUsageError when the text violates Slack's length constraints. + +*** + +## PlainTextOptions + +Optional behavior for [plainText](#plaintext). + +### Properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `emoji?` | `boolean` | Whether Slack should render emoji shortcodes. | + +*** + +## rawNumber() + +> **rawNumber**(`value`, `text`, `settings?`): [`SlackObject`](utilities.md#slackobject)<`"raw_number"`> + +Creates a sortable numeric cell for a data table. + +### Parameters + +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `value` | `number` | Finite number used for sorting. | +| `text` | `string` | Human-readable cell text. | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`SlackObject`](utilities.md#slackobject)<`"raw_number"`> + +A validated Slack `raw_number` object. + +### Throws + +TypeMismatchError when `value` is not finite. + +*** + +## rawText() + +> **rawText**(`text`, `settings?`): [`SlackObject`](utilities.md#slackobject)<`"raw_text"`> + +Creates an unformatted text cell for a table or data table. + +### Parameters + +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `text` | `string` | Cell content. | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`SlackObject`](utilities.md#slackobject)<`"raw_text"`> + +A validated Slack `raw_text` object. + +### Throws + +InvalidUsageError when the cell text violates Slack's constraints. + +*** + +## slackFile() + +> **slackFile**(`input`, `settings?`): [`JsonObject`](utilities.md#jsonobject) + +Creates a Slack-hosted image reference. + +### Input fields + +Exactly one Slack file ID or Slack file URL. + +| Input field | Type | Description | +| ------ | ------ | ------ | +| `id?` | `string` | Slack file identifier. | +| `url?` | `string` | Slack-hosted file URL. | + +### Settings + +| Setting | Type | Description | +| ------ | ------ | ------ | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`JsonObject`](utilities.md#jsonobject) + +A validated Slack file-reference object. + +### Throws + +InvalidUsageError when both or neither source is supplied. + +*** + +## slackIcon() + +> **slackIcon**(`name`, `settings?`): [`SlackObject`](utilities.md#slackobject)<`"icon"`> + +Creates a Slack-provided icon for a card. + +### Parameters + +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `name` | [`SlackIconName`](#slackiconname) | One of Slack's supported icon names. | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`SlackObject`](utilities.md#slackobject)<`"icon"`> + +A validated Slack `icon` object. + +### Throws + +TypeMismatchError when the icon name is unsupported at runtime. + +*** + +## SlackIconName + +> **SlackIconName** = `"archive"` \| `"book"` \| `"bookmark"` \| `"bot"` \| `"bug"` \| `"calendar"` \| `"call"` \| `"caret-left"` \| `"caret-right"` \| `"check"` \| `"clipboard"` \| `"code"` \| `"comment"` \| `"compass"` \| `"copy"` \| `"cube"` \| `"download"` \| `"edit"` \| `"email"` \| `"eye-closed"` \| `"eye-open"` \| `"file"` \| `"flag"` \| `"folder"` \| `"gear"` \| `"globe"` \| `"heart"` \| `"help"` \| `"image"` \| `"info"` \| `"key"` \| `"lightbulb"` \| `"link"` \| `"map"` \| `"mobile"` \| `"new-window"` \| `"pin"` \| `"plus"` \| `"refine"` \| `"refresh"` \| `"rocket"` \| `"save"` \| `"screen"` \| `"share"` \| `"sparkle"` \| `"star"` \| `"star-filled"` \| `"tag"` \| `"thumbs-down"` \| `"thumbs-up"` \| `"trash"` \| `"upload"` \| `"user"` \| `"warning"` + +Slack-provided icon name accepted by [slackIcon](#slackicon). + +*** + +## TextLike + +> **TextLike** = `string` \| [`TextObject`](#textobject) + +Text accepted by factories: a string or an existing Slack text object. + +*** + +## TextObject + +> **TextObject** = [`SlackObject`](utilities.md#slackobject)<`"plain_text"` \| `"mrkdwn"`> + +A Slack plain-text or mrkdwn composition object. + +*** + +## trigger() + +> **trigger**(`input`, `settings?`): [`JsonObject`](utilities.md#jsonobject) + +Creates a workflow trigger definition. + +### Input fields + +Trigger URL and optional customizable parameters. + +| Input field | Type | Description | +| ------ | ------ | ------ | +| `customizableInputParameters?` | [`JsonObject`](utilities.md#jsonobject)[] | Optional parameters created with `inputParameter`. | +| `url` | `string` | Slack workflow trigger URL. | + +### Settings + +| Setting | Type | Description | +| ------ | ------ | ------ | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`JsonObject`](utilities.md#jsonobject) + +A Slack workflow-trigger object. + +*** + +## workflow() + +> **workflow**(`input`, `settings?`): [`JsonObject`](utilities.md#jsonobject) + +Wraps a trigger for use by a workflow button. + +### Input fields + +Workflow trigger object. + +| Input field | Type | Description | +| ------ | ------ | ------ | +| `trigger` | [`JsonObject`](utilities.md#jsonobject) | Trigger created with `trigger`. | + +### Settings + +| Setting | Type | Description | +| ------ | ------ | ------ | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`JsonObject`](utilities.md#jsonobject) + +A Slack workflow object. diff --git a/docs/versioned_docs/version-2.1.0/reference/typescript/rich-text.md b/docs/versioned_docs/version-2.1.0/reference/typescript/rich-text.md new file mode 100644 index 00000000..d23ed2c8 --- /dev/null +++ b/docs/versioned_docs/version-2.1.0/reference/typescript/rich-text.md @@ -0,0 +1,279 @@ +--- +toc_min_heading_level: 2 +toc_max_heading_level: 2 +--- + +# Rich Text + +Inline and layout factories for Slack rich-text blocks. + +Build inline elements first, combine them in a section, list, quote, or code +block, then pass those layout objects to `richTextBlock`. + +## richText() + +> **richText**(`text`, `style?`, `settings?`): [`SlackObject`](utilities.md#slackobject)<`"text"`> + +Creates a styled rich-text text run. + +### Parameters + +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `text` | `string` | Text content. | +| `style?` | [`RichTextStyle`](#richtextstyle) | Optional inline formatting. | +| `settings?` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`SlackObject`](utilities.md#slackobject)<`"text"`> + +A validated Slack rich-text `text` element. + +*** + +## richTextChannel() + +> **richTextChannel**(`channelId`, `style?`, `settings?`): [`SlackObject`](utilities.md#slackobject)<`"channel"`> + +Creates a rich-text channel mention. + +### Parameters + +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `channelId` | `string` | Slack channel identifier. | +| `style?` | [`RichTextStyle`](#richtextstyle) | Optional inline formatting. | +| `settings?` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`SlackObject`](utilities.md#slackobject)<`"channel"`> + +A validated Slack rich-text `channel` element. + +*** + +## richTextCodeBlock() + +> **richTextCodeBlock**(`elements`, `options?`, `settings?`): [`SlackObject`](utilities.md#slackobject)<`"rich_text_preformatted"`> + +Creates a preformatted rich-text code block. + +### Input fields + +Optional border thickness. + +| Input field | Type | Description | +| ------ | ------ | ------ | +| `border?` | `number` | Optional border thickness. | + +### Settings + +| Setting | Type | Description | +| ------ | ------ | ------ | +| `elements` | [`JsonObject`](utilities.md#jsonobject)[] | Inline rich-text elements displayed as code. | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`SlackObject`](utilities.md#slackobject)<`"rich_text_preformatted"`> + +A validated Slack `rich_text_preformatted` object. + +*** + +## richTextEmoji() + +> **richTextEmoji**(`name`, `settings?`): [`SlackObject`](utilities.md#slackobject)<`"emoji"`> + +Creates a rich-text emoji. + +### Parameters + +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `name` | `string` | Emoji name without surrounding colons. | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`SlackObject`](utilities.md#slackobject)<`"emoji"`> + +A validated Slack rich-text `emoji` element. + +*** + +## richTextLink() + +> **richTextLink**(`input`, `settings?`): [`SlackObject`](utilities.md#slackobject)<`"link"`> + +Creates a rich-text link. + +### Input fields + +Destination URL, optional label, safety flag, and formatting. + +| Input field | Type | Description | +| ------ | ------ | ------ | +| `style?` | [`RichTextStyle`](#richtextstyle) | Optional inline formatting. | +| `text?` | `string` | Optional visible label. Slack displays the URL when omitted. | +| `unsafe?` | `boolean` | Mark a URL as unsafe when mirroring a Slack-provided payload. | +| `url` | `string` | Destination URL. | + +### Settings + +| Setting | Type | Description | +| ------ | ------ | ------ | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`SlackObject`](utilities.md#slackobject)<`"link"`> + +A validated Slack rich-text `link` element. + +*** + +## richTextList() + +> **richTextList**(`input`, `settings?`): [`SlackObject`](utilities.md#slackobject)<`"rich_text_list"`> + +Creates an ordered or bulleted rich-text list. + +### Input fields + +List items, marker style, and optional list layout. + +| Input field | Type | Description | +| ------ | ------ | ------ | +| `border?` | `number` | Optional border thickness. | +| `elements` | [`JsonObject`](utilities.md#jsonobject)[] | Rich-text section objects used as list items. | +| `indent?` | `number` | Nesting depth. | +| `offset?` | `number` | Starting number for an ordered list. | +| `style` | `"bullet"` \| `"ordered"` | List marker style. | + +### Settings + +| Setting | Type | Description | +| ------ | ------ | ------ | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`SlackObject`](utilities.md#slackobject)<`"rich_text_list"`> + +A validated Slack `rich_text_list` object. + +### Throws + +MissingRequiredError when `style` is not provided. + +*** + +## richTextQuote() + +> **richTextQuote**(`elements`, `options?`, `settings?`): [`SlackObject`](utilities.md#slackobject)<`"rich_text_quote"`> + +Creates a rich-text block quote. + +### Input fields + +Optional border thickness. + +| Input field | Type | Description | +| ------ | ------ | ------ | +| `border?` | `number` | Optional border thickness. | + +### Settings + +| Setting | Type | Description | +| ------ | ------ | ------ | +| `elements` | [`JsonObject`](utilities.md#jsonobject)[] | Inline rich-text elements displayed in the quote. | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`SlackObject`](utilities.md#slackobject)<`"rich_text_quote"`> + +A validated Slack `rich_text_quote` object. + +*** + +## richTextSection() + +> **richTextSection**(`elements`, `settings?`): [`SlackObject`](utilities.md#slackobject)<`"rich_text_section"`> + +Creates a paragraph-like rich-text section. + +### Parameters + +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `elements` | [`JsonObject`](utilities.md#jsonobject)[] | Inline rich-text elements in display order. | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`SlackObject`](utilities.md#slackobject)<`"rich_text_section"`> + +A validated Slack `rich_text_section` object. + +*** + +## RichTextStyle + +Inline formatting supported by rich-text text, links, users, and channels. + +### Properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `bold?` | `boolean` | Render the inline content in bold. | +| `code?` | `boolean` | Render the inline content as code. | +| `italic?` | `boolean` | Render the inline content in italics. | +| `strike?` | `boolean` | Render the inline content with a strikethrough. | + +*** + +## richTextUser() + +> **richTextUser**(`userId`, `style?`, `settings?`): [`SlackObject`](utilities.md#slackobject)<`"user"`> + +Creates a rich-text user mention. + +### Parameters + +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `userId` | `string` | Slack user identifier. | +| `style?` | [`RichTextStyle`](#richtextstyle) | Optional inline formatting. | +| `settings?` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`SlackObject`](utilities.md#slackobject)<`"user"`> + +A validated Slack rich-text `user` element. + +*** + +## richTextUserGroup() + +> **richTextUserGroup**(`usergroupId`, `style?`, `settings?`): [`SlackObject`](utilities.md#slackobject)<`"usergroup"`> + +Creates a rich-text user-group mention. + +### Parameters + +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `usergroupId` | `string` | Slack user-group identifier. | +| `style?` | [`RichTextStyle`](#richtextstyle) | Optional inline formatting. | +| `settings?` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`SlackObject`](utilities.md#slackobject)<`"usergroup"`> + +A validated Slack rich-text `usergroup` element. diff --git a/docs/versioned_docs/version-2.1.0/reference/typescript/utilities.md b/docs/versioned_docs/version-2.1.0/reference/typescript/utilities.md new file mode 100644 index 00000000..4ed785a1 --- /dev/null +++ b/docs/versioned_docs/version-2.1.0/reference/typescript/utilities.md @@ -0,0 +1,174 @@ +--- +toc_min_heading_level: 2 +toc_max_heading_level: 2 +--- + +# Utilities + +Types and helpers for building and validating Block Kit payloads. + +## assertValid() + +> **assertValid**(`payload`): `asserts payload is JsonObject` + +Asserts that an object is a valid Block Kit payload. + +Validation walks nested blocks, elements, views, and composition objects and +reports the first failing field through a typed validation error. + +### Parameters + +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `payload` | [`JsonValue`](#jsonvalue) | JSON value to validate. | + +### Returns + +`asserts payload is JsonObject` + +### Throws + +InvalidUsageError when the payload violates a supported Block Kit constraint. + +*** + +## blockKitBuilderUrl() + +> **blockKitBuilderUrl**(`payload`, `teamId?`): `string` + +Builds a Block Kit Builder URL containing a serialized payload. + +### Parameters + +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `payload` | [`JsonObject`](#jsonobject) \| [`JsonObject`](#jsonobject)[] | A complete payload or a list of blocks. | +| `teamId?` | `string` | Optional workspace ID used in the Builder URL. | + +### Returns + +`string` + +A URL that opens the payload in Slack's Block Kit Builder. + +*** + +## BlockKitPayload + +> **BlockKitPayload** = [`JsonObject`](#jsonobject) + +Generic validated Block Kit object. + +*** + +## FactorySettings + +Per-call behavior supported by every public factory. + +### Properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `validate?` | `boolean` | Whether to validate the constructed object immediately. Defaults to `true`. Disable only when intentionally creating an intermediate partial object. | + +*** + +## JsonObject + +Object with JSON-compatible values and Slack-shaped string keys. + +### Indexable + +> \[`key`: `string`\]: [`JsonValue`](#jsonvalue) + +JSON field value by wire-format key. + +*** + +## JsonPrimitive + +> **JsonPrimitive** = `boolean` \| `number` \| `string` \| `null` + +JSON scalar accepted by Slack payloads. + +*** + +## JsonValue + +> **JsonValue** = [`JsonPrimitive`](#jsonprimitive) \| [`JsonObject`](#jsonobject) \| [`JsonValue`](#jsonvalue)[] + +Recursive JSON value accepted by Slack payloads. + +*** + +## SlackCompatibleBlock + +> **SlackCompatibleBlock** = [`SlackWire`](#slackwire)<`KnownBlock`> + +Compatibility helper for call sites that accept Slack's official block types. + +*** + +## SlackObject<Type> {#slackobject} + +> **SlackObject**<`Type`> = [`JsonObject`](#jsonobject) & `object` + +Slack-shaped JSON object whose `type` field is known. + +### Type Declaration + +| Name | Type | Description | +| ------ | ------ | ------ | +| `type` | `Type` | Discriminator identifying the Block Kit object on Slack's wire format. | + +### Type Parameters + +| Type Parameter | +| ------ | +| `Type` *extends* `string` | + +*** + +## SlackWire<Type> {#slackwire} + +> **SlackWire**<`Type`> = `Type` & [`JsonObject`](#jsonobject) + +Official Slack SDK type intersected with its JSON wire representation. + +### Type Parameters + +| Type Parameter | +| ------ | +| `Type` | + +*** + +## validate() + +> **validate**(`payload`): `payload is JsonObject` + +Checks whether a value is a valid Block Kit payload without throwing for validation failures. + +Validation identifies objects by their `type` field, so it enforces required +fields and limits for every typed block, element, view, and rich-text object, +and it validates type-less `options`, `option_groups`, and `confirm` +composition objects contextually through their typed parents. Known +asymmetries with factory validation remain for type-less objects that +appear without a typed parent: standalone confirmation dialogs, options, +option groups, attachments, message payloads, workflow objects, and chart +axis configurations pass unchecked, and one-of rules enforced only by +factory signatures (for example `slackFile` requiring exactly one source) +are not rediscovered from raw JSON. The contents of message metadata +`event_payload` objects are always treated as opaque user data and skipped. + +### Parameters + +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `payload` | `unknown` | Unknown value to validate. | + +### Returns + +`payload is JsonObject` + +`true` for a valid payload; otherwise `false`. diff --git a/docs/versioned_docs/version-2.1.0/reference/typescript/views.md b/docs/versioned_docs/version-2.1.0/reference/typescript/views.md new file mode 100644 index 00000000..41243ac5 --- /dev/null +++ b/docs/versioned_docs/version-2.1.0/reference/typescript/views.md @@ -0,0 +1,82 @@ +--- +toc_min_heading_level: 2 +toc_max_heading_level: 2 +--- + +# Views + +View factories for Slack modals and App Home tabs. + +## homeTab() + +> **homeTab**(`input`, `settings?`): [`SlackObject`](utilities.md#slackobject)<`"home"`> + +Creates an App Home tab view payload. + +### Input fields + +Home-tab blocks and optional application metadata. + +| Input field | Type | Description | +| ------ | ------ | ------ | +| `blocks` | [`JsonObject`](utilities.md#jsonobject)[] | Between one and 100 App Home-compatible blocks. | +| `callbackId?` | `string` | Application-defined callback identifier. | +| `externalId?` | `string` | Application-defined external identifier. | +| `privateMetadata?` | `string` | Opaque application metadata returned with view interactions. | + +### Settings + +| Setting | Type | Description | +| ------ | ------ | ------ | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`SlackObject`](utilities.md#slackobject)<`"home"`> + +A validated Slack `home` view. + +### Throws + +InvalidUsageError when blocks or metadata violate Slack's constraints. + +*** + +## modal() + +> **modal**(`input`, `settings?`): [`SlackObject`](utilities.md#slackobject)<`"modal"`> + +Creates a modal view payload. + +### Input fields + +Modal title, blocks, controls, metadata, and callback behavior. + +| Input field | Type | Description | +| ------ | ------ | ------ | +| `blocks` | [`JsonObject`](utilities.md#jsonobject)[] | Between one and 100 modal-compatible blocks. | +| `callbackId?` | `string` | Application-defined callback identifier. | +| `clearOnClose?` | `boolean` | Close every view above this modal when it closes. | +| `close?` | [`TextLike`](objects.md#textlike) | Optional plain-text close-button label. | +| `externalId?` | `string` | Application-defined external identifier. | +| `notifyOnClose?` | `boolean` | Send a `view_closed` event when the modal closes. | +| `privateMetadata?` | `string` | Opaque application metadata returned with view interactions. | +| `submit?` | [`TextLike`](objects.md#textlike) | Optional plain-text submit-button label. | +| `submitDisabled?` | `boolean` | Keep the submit button disabled until an input changes. | +| `title` | [`TextLike`](objects.md#textlike) | Plain-text modal title, up to 24 characters. | + +### Settings + +| Setting | Type | Description | +| ------ | ------ | ------ | +| `settings` | [`FactorySettings`](utilities.md#factorysettings) | Per-call validation settings. | + +### Returns + +[`SlackObject`](utilities.md#slackobject)<`"modal"`> + +A validated Slack `modal` view. + +### Throws + +InvalidUsageError when blocks or text fields violate Slack's constraints. diff --git a/docs/versioned_docs/version-2.1.0/usage/_category_.json b/docs/versioned_docs/version-2.1.0/usage/_category_.json new file mode 100644 index 00000000..d8659ff3 --- /dev/null +++ b/docs/versioned_docs/version-2.1.0/usage/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Usage", + "position": 3, + "collapsed": false +} diff --git a/docs/versioned_docs/version-2.1.0/usage/compatibility.mdx b/docs/versioned_docs/version-2.1.0/usage/compatibility.mdx new file mode 100644 index 00000000..2428dd91 --- /dev/null +++ b/docs/versioned_docs/version-2.1.0/usage/compatibility.mdx @@ -0,0 +1,74 @@ +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Compatibility + +This page documents which Python versions are supported by each `slackblocks` release line, so you can choose the right line for your runtime. + +Each row in the table maps a major `slackblocks` release line to the oldest Python interpreter that can run it. **Minimum Python** means that version or any newer supported Python version—not that the release only works on that one version. The status in parentheses tells you whether the line receives current feature development or maintenance fixes only. + +Start with the Python version used by your application or deployment environment, then choose the newest `slackblocks` line whose minimum requirement it meets. For example, Python 3.9 requires `slackblocks` 1.x, while Python 3.10 and newer can use 2.x. + +## Support matrix + +| `slackblocks` version | Minimum Python | Notes | +| --- | --- | --- | +| `1.x` (maintenance) | 3.8.1 | The last release line to support Python 3.8 and 3.9. | +| `2.x` (current) | 3.10 | Modern typing (`X \| Y`, `list[X]`), dataclasses with `slots`, `match` statements, and other Python 3.10+ features used internally. | + +If you cannot upgrade Python, pin to the appropriate major version: + + + + +```text +slackblocks>=1,<2 # Python 3.8/3.9 friendly +slackblocks>=2,<3 # Python 3.10+ only +``` + + + + + +```toml +slackblocks = "^1" # Python 3.8/3.9 friendly +slackblocks = "^2" # Python 3.10+ only +``` + + + + + +```toml +"slackblocks>=1,<2" # Python 3.8/3.9 friendly +"slackblocks>=2,<3" # Python 3.10+ only +``` + + + + + +## Why we move forward + +`slackblocks` follows the upstream Python release cycle. Once a Python version reaches its [official end-of-life](https://devguide.python.org/versions/), it stops receiving security patches, and we prefer not to ship new feature work targeting unmaintained runtimes. + +| Python version | EOL date | +| --- | --- | +| 3.8 | 2024-10-07 | +| 3.9 | 2025-10-31 | +| 3.10 | 2026-10 | +| 3.11 | 2027-10 | +| 3.12 | 2028-10 | +| 3.13 | 2029-10 | +| 3.14 | 2030-10 | + +Bugfix releases on existing lines may continue past these dates on a best-effort basis, but new feature work will target supported Pythons. + +## Choosing a version + +- **You're on Python 3.8 or 3.9**: install the latest `1.x`. +- **You're on Python 3.10 or newer**: install the current `2.x` release line. +- **You're starting a new project on a modern Python**: prefer `2.x` to take advantage of the improved typing surface. + +For an upgrade walkthrough from `1.x` to `2.x`, see the +[Migration Guide](migration). diff --git a/docs/versioned_docs/version-2.1.0/usage/cookbook.mdx b/docs/versioned_docs/version-2.1.0/usage/cookbook.mdx new file mode 100644 index 00000000..086e496a --- /dev/null +++ b/docs/versioned_docs/version-2.1.0/usage/cookbook.mdx @@ -0,0 +1,461 @@ +import LanguageContent, { Python, TypeScript } from '@site/src/components/LanguageContent'; + +# Recipe Book + +End-to-end recipes for common Slack messaging patterns. Each example produces a complete, valid `Message` (or `Modal`) you can pass directly to the Slack SDK. + +The reference docs cover *what* each class does in isolation; this page is for *how* to combine them into something useful. + +## Build status notification + +A typical CI/CD success or failure notification: header, summary fields, divider, contextual footer. + + + + +```python +from slackblocks import ( + ContextBlock, + DividerBlock, + HeaderBlock, + Message, + SectionBlock, + Text, +) + + +def build_status_message( + *, + channel: str, + project: str, + branch: str, + commit: str, + author: str, + duration: str, + passed: bool, +) -> Message: + icon = ":white_check_mark:" if passed else ":x:" + status = "passed" if passed else "failed" + + return Message( + channel=channel, + text=f"Build {status} for {project}@{branch}", # plain-text fallback + blocks=[ + HeaderBlock(f"{icon} {project} build {status}"), + SectionBlock( + fields=[ + f"*Branch*\n`{branch}`", + f"*Commit*\n`{commit[:7]}`", + f"*Author*\n{author}", + f"*Duration*\n{duration}", + ], + ), + DividerBlock(), + ContextBlock( + elements=[ + Text(f":calendar: Triggered by push to `{branch}`"), + ], + ), + ], + ) +``` + + + + +```ts +import { + contextBlock, + dividerBlock, + headerBlock, + message, + mrkdwn, + sectionBlock, +} from "@nicklambourne/slackblocks"; + +function buildStatusMessage(input: { + channel: string; + project: string; + branch: string; + commit: string; + author: string; + duration: string; + passed: boolean; +}) { + const icon = input.passed ? ":white_check_mark:" : ":x:"; + const status = input.passed ? "passed" : "failed"; + + return message({ + channel: input.channel, + text: `Build ${status} for ${input.project}@${input.branch}`, + blocks: [ + headerBlock({ text: `${icon} ${input.project} build ${status}` }), + sectionBlock({ + fields: [ + `*Branch*\n\`${input.branch}\``, + `*Commit*\n\`${input.commit.slice(0, 7)}\``, + `*Author*\n${input.author}`, + `*Duration*\n${input.duration}`, + ], + }), + dividerBlock(), + contextBlock({ + elements: [mrkdwn(`:calendar: Triggered by push to \`${input.branch}\``)], + }), + ], + }); +} +``` + + + + +Tips: + +- Always pass a `text=` fallback to `Message` — Slack uses it for desktop and mobile push notifications. +- `SectionBlock` accepts up to 10 `fields`, each up to 2,000 characters. + +## Approval request with action buttons + +A two-button approval flow. The buttons carry `value` and `action_id` so your interaction handler can identify them. + +```python +from slackblocks import ( + ActionsBlock, + Button, + ContextBlock, + HeaderBlock, + Message, + SectionBlock, + Text, +) + + +def approval_request(*, channel: str, request_id: str, requester: str, summary: str) -> Message: + return Message( + channel=channel, + text=f"Approval requested by {requester}", + blocks=[ + HeaderBlock(":hand: Approval needed"), + SectionBlock(text=f"*Requested by:* {requester}\n\n{summary}"), + ActionsBlock( + block_id=f"approval:{request_id}", + elements=[ + Button( + text="Approve", + action_id="approve", + value=request_id, + style="primary", + ), + Button( + text="Reject", + action_id="reject", + value=request_id, + style="danger", + ), + Button( + text="View details", + action_id="details", + url=f"https://approvals.example.com/{request_id}", + ), + ], + ), + ContextBlock( + elements=[Text(f"Request ID: `{request_id}`")], + ), + ], + ) +``` + +When the user clicks a button, Slack will POST an interaction payload to your app. Match on `action_id` (`approve` / `reject` / `details`) and pull the request ID from `block_id` or the button's `value`. + +## Rich-formatted alert + +Use `RichTextBlock` when you want inline bold/italic/code styling without writing markdown by hand. + +```python +from slackblocks import ( + Message, + RichText, + RichTextBlock, + RichTextLink, + RichTextSection, +) + + +def deploy_alert(*, channel: str, service: str, version: str, dashboard_url: str) -> Message: + return Message( + channel=channel, + text=f"Deployed {service} {version}", + blocks=[ + RichTextBlock( + RichTextSection( + elements=[ + RichText(text="Deployed "), + RichText(text=service, bold=True), + RichText(text=" version "), + RichText(text=version, code=True), + RichText(text=". "), + RichTextLink(url=dashboard_url, text="View dashboard"), + RichText(text="."), + ], + ), + ), + ], + ) +``` + +## Confirmation modal + +A modal is opened in response to an interaction `trigger_id` from Slack. + +```python +from slack_sdk import WebClient +from slackblocks import ( + InputBlock, + Modal, + PlainTextInput, + SectionBlock, +) + + +def open_confirmation_modal(client: WebClient, trigger_id: str, target: str) -> None: + modal = Modal( + title="Confirm deletion", + submit="Delete", + close="Cancel", + callback_id="confirm_delete", + private_metadata=target, # round-tripped back to your handler on submit + blocks=[ + SectionBlock(f":warning: This will permanently delete *{target}*."), + InputBlock( + label="Type the name to confirm", + element=PlainTextInput( + action_id="confirmation_text", + placeholder=target, + ), + block_id="confirmation", + ), + ], + ) + + client.views_open(trigger_id=trigger_id, view=modal.to_dict()) +``` + +When the user submits, your `view_submission` handler will receive the input under `state.values["confirmation"]["confirmation_text"]`. + +## Threaded reply + +Pass `thread_ts` (the timestamp of the parent message) to reply in-thread. + +```python +from slackblocks import Message, SectionBlock + +reply = Message( + channel="#general", + thread_ts="1700000000.000100", + blocks=SectionBlock("Reticulating splines... 30% complete."), +) +``` + +## Ephemeral slash-command response + +Reply to a slash command with a message only the invoking user sees: + +```python +from slackblocks import MessageResponse, SectionBlock + +body = MessageResponse( + blocks=SectionBlock(":mag: Searching... I'll DM you when I'm done."), + ephemeral=True, +).json() +# return `body` as the JSON response to Slack's slash-command webhook +``` + +## Multi-column status report (table) + +`TableBlock` is useful for compact tabular output. + +```python +from slackblocks import ( + ColumnSettings, + Message, + RawText, + RichText, + RichTextSection, + TableBlock, +) + + +def header_cell(text: str) -> RichTextSection: + return RichTextSection(elements=[RichText(text=text, bold=True)]) + + +report = Message( + channel="#ops", + text="Daily service report", + blocks=[ + TableBlock( + column_settings=[ + ColumnSettings(align="left"), + ColumnSettings(align="right"), + ColumnSettings(align="right"), + ], + rows=[ + [header_cell("Service"), header_cell("p99 (ms)"), header_cell("Errors")], + [RawText("api"), RawText("142"), RawText("3")], + [RawText("worker"), RawText("89"), RawText("0")], + [RawText("billing"), RawText("310"), RawText("12")], + ], + ), + ], +) +``` + +## Deprecated: colored-bar attachment + +Slack has long deprecated message attachments, but they're still the only way to get the colored vertical bar on the left of a message. `slackblocks` supports them when you really need that styling: + +```python +from slackblocks import ( + Attachment, + Color, + Message, + SectionBlock, +) + +msg = Message( + channel="#alerts", + text="Disk usage warning", + attachments=[ + Attachment( + color=Color.YELLOW, + blocks=[SectionBlock(":warning: `/var` is at 87% capacity on `prod-db-1`.")], + ), + ], +) +``` + +Prefer plain blocks where possible — Slack may drop attachment support in the future. + + +## Preview a message in the browser + +Use `block_kit_builder_url` to build a [Block Kit Builder](https://app.slack.com/block-kit-builder) URL and open it in your browser to verify a message before posting it. Useful while iterating on layout — no Slack credentials needed. + +```python +from slackblocks import ( + block_kit_builder_url, + DividerBlock, + HeaderBlock, + Markdown, + SectionBlock, +) + +blocks = [ + HeaderBlock("Build #482 passed :white_check_mark:"), + SectionBlock(text=Markdown("All 1,247 tests green in 3m 12s.")), + DividerBlock(), + SectionBlock(fields=["*Author*\n@nick", "*Branch*\n`main`"]), +] + +print(block_kit_builder_url(blocks)) +# https://app.slack.com/block-kit-builder/#%7B%22blocks%22%3A%5B...%5D%7D +``` + +`block_kit_builder_url` accepts: + +- A single `Block`, `Element`, or anything else with a `_resolve()` method. +- A list of `Block` objects (wrapped in `{"blocks": [...]}` automatically). +- A `Message`, `WebhookMessage`, `MessageResponse`, or `View`. +- A raw `dict` (escape hatch). + +Pass `team_id="T0123ABCD"` for a workspace-specific URL. + + +## Parse incoming Slack JSON + +If your app handles Slack interactivity payloads or events, you can parse the JSON back into `slackblocks` objects with `Block.from_dict`: + +```python +import json +from slackblocks import Block, SectionBlock + +incoming = json.loads(slack_request_body) + +for raw_block in incoming.get("blocks", []): + block = Block.from_dict(raw_block) + if isinstance(block, SectionBlock): + print("Section text:", block.text.text if block.text else None) +``` + +`Block.from_dict` reads `data["type"]` and dispatches to the right subclass. The composition objects (`Text`, `Option`, `Confirm`, etc.) round-trip fully via their own `from_dict` classmethods. + +In the current release, blocks containing interactive elements (`ActionsBlock`, `InputBlock`, `SectionBlock` with an `accessory`, `ContextBlock` with image elements) raise `NotImplementedError` — this is on the roadmap for a follow-up release. + + +## One-line workflow trigger + +`Workflow.from_url` collapses the most common workflow construction: + +```python +from slackblocks import ( + ActionsBlock, + Message, + SectionBlock, + Workflow, + WorkflowButton, +) + +msg = Message( + channel="#release", + blocks=[ + SectionBlock("Run the release workflow with the parameters below."), + ActionsBlock( + elements=[ + WorkflowButton( + text="Release", + workflow=Workflow.from_url( + "https://slack.com/shortcuts/Ft012KXZK1MZ/...", + env="prod", + retries="3", + ), + ), + ], + ), + ], +) +``` + +Each keyword pair becomes one `InputParameter` on the underlying `Trigger`. Calling `Workflow.from_url(url)` with no parameters omits the `customizable_input_parameters` field. + + +## Typed exception handling + +`InvalidUsageError` is the base type for every validation failure raised by `slackblocks`. As of `2.x`, five subclasses let you `except` for specific failure categories instead of string-matching the message: + +```python +from slackblocks import ( + Button, + LengthError, + MutualExclusivityError, + SlackFile, + Image, +) + +try: + Button(text="x" * 100, action_id="b") +except LengthError as e: + # specifically a length violation, not a missing-required or type-mismatch + log.warning("button text too long: %s", e) + +try: + Image( + image_url="https://x.png", + slack_file=SlackFile(url="https://y.png", id=None), + ) +except MutualExclusivityError as e: + log.error("image source ambiguous: %s", e) +``` + +Existing `except InvalidUsageError` blocks continue to catch every subclass — the new types are purely additive. diff --git a/docs/versioned_docs/version-2.1.0/usage/installation.mdx b/docs/versioned_docs/version-2.1.0/usage/installation.mdx new file mode 100644 index 00000000..fc1c219e --- /dev/null +++ b/docs/versioned_docs/version-2.1.0/usage/installation.mdx @@ -0,0 +1,102 @@ +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import LanguageContent, { Python, TypeScript } from '@site/src/components/LanguageContent'; + +# Installation + +Choose Python or TypeScript from the site navigation. The selection applies across the documentation and is preserved as you move between pages. + + + + +Install the Python package from [PyPI](https://pypi.org/project/slackblocks/): + + + + +```bash +pip install slackblocks +``` + + + + +```bash +poetry add slackblocks +``` + + + + +```bash +pipenv install slackblocks +``` + + + + +```bash +uv add slackblocks +``` + + + + +Python 2.x requires Python 3.10 or newer and has no runtime dependencies. See [Compatibility](compatibility) for the support matrix and 1.x migration guidance. + +Verify the installation: + +```python +from slackblocks import Message, SectionBlock + +print(Message(channel="#general", blocks=SectionBlock("Hello, world!")).json()) +``` + +Pin the current major release with `slackblocks~=2.0`, and uninstall with `pip uninstall slackblocks` (or the equivalent command for your package manager). + + + + +Install the ESM package from npm: + + + + +```bash +pnpm add @nicklambourne/slackblocks +``` + + + + +```bash +npm install @nicklambourne/slackblocks +``` + + + + +```bash +yarn add @nicklambourne/slackblocks +``` + + + + +The package requires Node 20.19 or newer, is ESM-only, and emits no runtime imports beyond your own code. + +Verify the installation in `hello.mjs`: + +```ts +import { message, sectionBlock } from "@nicklambourne/slackblocks"; + +console.log(message({ + channel: "C0123456", + blocks: [sectionBlock({ text: "Hello, world!" })], +})); +``` + +Run it with `node hello.mjs`. Stay on the 2.x release line with `@nicklambourne/slackblocks@^2.1.0`, and uninstall with `pnpm remove @nicklambourne/slackblocks` (or your package manager's equivalent). + + + diff --git a/docs/versioned_docs/version-2.1.0/usage/migration.mdx b/docs/versioned_docs/version-2.1.0/usage/migration.mdx new file mode 100644 index 00000000..5c45ec28 --- /dev/null +++ b/docs/versioned_docs/version-2.1.0/usage/migration.mdx @@ -0,0 +1,253 @@ +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Migrating from 1.x to 2.x + +`slackblocks 2.0` is a major version bump that focuses on cleaning up internal +correctness issues, modernising the type-annotation surface, and adding several +ergonomic helpers. The good news: **for almost all users, upgrading is a +no-op** beyond changing the Python version pin. + +This page covers what actually changes for you and what's worth adopting once +you've upgraded. + +## Quick checklist + +| Step | Action | +| --- | --- | +| 1 | Confirm you are on **Python 3.10 or newer**. If not, stay on `slackblocks ~= 1.2`. | +| 2 | Bump your dependency pin to `slackblocks ~= 2.0` (or `>=2,<3`). | +| 3 | Run your test suite. Existing code should continue to work unchanged. | +| 4 | Optionally adopt the new conveniences below. | + +## Truly breaking changes + +There is exactly one breaking change you might trip over: + +### Python 3.8 and 3.9 are no longer supported + +Both reached upstream end of life +([3.8 EOL Oct 2024](https://devguide.python.org/versions/), +[3.9 EOL Oct 2025](https://devguide.python.org/versions/)) and are not +receiving security patches. + +If you are still on either: + +- **Stay on the `1.x` line** until you can upgrade Python. The 1.x line is + maintained on a best-effort basis for bugfixes; see the + [Compatibility](compatibility) page. +- Pin via your package manager: + + + + +```text +slackblocks>=1,<2 +``` + + + + + +```toml +slackblocks = "^1" +``` + + + + + +```toml +"slackblocks>=1,<2" +``` + + + + + +That's it for breaking changes. Nothing else in the public API was removed +or renamed. + +## What's *not* breaking, but worth adopting + +### `PlainText` and `Markdown` instead of `Text(type_=...)` + +Before: + +```python +from slackblocks import Text, TextType + +heading = Text("Welcome", type_=TextType.PLAINTEXT, emoji=True) +body = Text("**bold**", type_=TextType.MARKDOWN, verbatim=True) +``` + +After: + +```python +from slackblocks import PlainText, Markdown + +heading = PlainText("Welcome", emoji=True) +body = Markdown("**bold**", verbatim=True) +``` + +`PlainText` and `Markdown` are subclasses of `Text`, so anywhere a `Text` or +`TextLike` was accepted before still accepts the new types. The rendered +JSON is byte-identical to the equivalent `Text` calls. + +### `Workflow.from_url(...)` instead of nested `Workflow(trigger=Trigger(...))` + +Before: + +```python +from slackblocks import Workflow, Trigger, InputParameter + +workflow = Workflow( + trigger=Trigger( + url="https://slack.com/shortcuts/...", + customizable_input_parameters=[ + InputParameter(name="env", value="prod"), + InputParameter(name="retries", value="3"), + ], + ), +) +``` + +After: + +```python +from slackblocks import Workflow + +workflow = Workflow.from_url( + "https://slack.com/shortcuts/...", + env="prod", + retries="3", +) +``` + +The verbose form continues to work, so you do not have to migrate. + +### `block_kit_builder_url(...)` for browser preview + +New helper that turns any block, list of blocks, message, view, or raw dict +into a [Block Kit Builder](https://app.slack.com/block-kit-builder) URL. Open +the URL in your browser to see exactly what Slack will render before you +ship. + +```python +from slackblocks import SectionBlock, block_kit_builder_url + +print(block_kit_builder_url(SectionBlock("Hi"))) +# https://app.slack.com/block-kit-builder/#%7B%22blocks%22%3A%5B...%5D%7D +``` + +Pass `team_id="T0123ABCD"` for a workspace-specific URL. + +### Typed exceptions for finer-grained error handling + +`InvalidUsageError` now has five subclasses, raised in well-defined +situations: + +| Subclass | Raised when | +| --- | --- | +| `LengthError` | A string or list violates a min/max-length constraint. | +| `RangeError` | A numeric value violates a min/max-value constraint. | +| `TypeMismatchError` | Wrong type or unexpected discrete value. | +| `MutualExclusivityError` | Two args that must not both be set were both set. | +| `MissingRequiredError` | At least one of a set of args was required. | + +```python +from slackblocks import Button, LengthError + +try: + Button(text="x" * 100, action_id="b") +except LengthError as e: + # specifically a length violation + handle_length(e) +``` + +**Existing `except InvalidUsageError` blocks continue to catch every +subclass** — no change required to upgrade. The new subclasses are purely +additive. + +### Round-tripping incoming Slack JSON with `from_dict` + +If your app receives Slack interactivity payloads or events and wants to +inspect the blocks, you can now parse them back into `slackblocks` objects: + +```python +import json +from slackblocks import Block + +incoming = json.loads(slack_request_body) +block = Block.from_dict(incoming["blocks"][0]) +print(block.text.text) # for a SectionBlock, etc. +``` + +`Block.from_dict` reads `data["type"]` and dispatches to the right subclass. +Composition objects (`Text`, `Option`, `Confirm`, etc.) and the simple +blocks (`DividerBlock`, `FileBlock`, `HeaderBlock`, `MarkdownBlock`, +`ImageBlock`, `SectionBlock`, `ContextBlock`, `VideoBlock`) round-trip fully. + +Blocks that contain interactive elements (`ActionsBlock`, `InputBlock`, +`SectionBlock` with an `accessory`, `ContextBlock` with image elements) +raise `NotImplementedError` for now; these depend on `Element.from_dict` +which is planned for a follow-up release. + +### Two new block types + +Slack added these in 2024; they're now available: + +```python +from slackblocks import MarkdownBlock, VideoBlock + +# Slack's GitHub-flavored markdown block (richer than SectionBlock mrkdwn). +MarkdownBlock(text="# Heading\n\n- item 1\n- item 2") + +# Embed a video from a Slack-supported provider. +VideoBlock( + alt_text="Demo", + thumbnail_url="https://example.com/thumb.png", + title="Getting Started", + video_url="https://example.com/video.mp4", +) +``` + +## Type-checking improvements + +The 2.x series ships with substantially tighter type signatures. If you +type-check your code with mypy, pyright, or Pyre, expect that: + +- `Text.to_text("hi")` is now correctly typed as `Text` (was previously + `Text | None`). Code that did `assert text is not None` after `to_text` + calls can drop the assertion. +- `Button(style="warning")` is now flagged at type-check time — + `style` is `Literal["primary", "danger"] | ButtonStyle | None`. +- `ColumnSettings(align="LEFT")` is similarly flagged at type-check time. +- `ConversationFilter(include=["bogus"])` is flagged. + +These constraints already existed at runtime; the difference is that mypy +now agrees with the runtime behaviour. + +## Internal changes you might notice + +The `_resolve()` method on every block, element, and composition object was +refactored to use a shared `slackblocks._core.resolve()` walker. This is +strictly internal — JSON output is byte-identical to 1.x — but if you have +been subclassing internal classes you may notice the `_resolve` bodies are +much shorter. + +If you are extending `slackblocks` with custom classes: + +- If your custom class has a `_resolve` method that follows the existing + pattern (manual `if self.x is not None: out["x"] = self.x._resolve()`), it + continues to work in 2.x without modification. +- If you want, you can switch to using the new `slackblocks._core.resolve` + / `omit_none` helpers; doing so guarantees recursion into nested + `_resolve` outputs and is much more concise. + +## Reporting issues + +If you hit a real upgrade problem, please [open an issue on +GitHub](https://github.com/nicklambourne/slackblocks/issues/new) — include +your Python version, your `slackblocks` version (old and new), and a +minimal repro. diff --git a/docs/versioned_docs/version-2.1.0/usage/sending_messages.mdx b/docs/versioned_docs/version-2.1.0/usage/sending_messages.mdx new file mode 100644 index 00000000..ff3f26d4 --- /dev/null +++ b/docs/versioned_docs/version-2.1.0/usage/sending_messages.mdx @@ -0,0 +1,243 @@ +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import LanguageContent, { Python, TypeScript } from '@site/src/components/LanguageContent'; + +# Sending Messages + +`slackblocks` produces the JSON payloads that Slack APIs accept; it does **not** make HTTP calls itself. Send those payloads with Slack's official SDK or any HTTP client. + + + + +The trick is the `**` operator: a `slackblocks.Message` is a mapping, so you can unpack it directly into `client.chat_postMessage(...)`. + +## With the modern `slack-sdk` + + + + +```python +from os import environ +from slack_sdk import WebClient +from slackblocks import Message, SectionBlock + + +client = WebClient(token=environ["SLACK_API_TOKEN"]) +block = SectionBlock("Hello, world!") +message = Message(channel="#general", blocks=block) + +response = client.chat_postMessage(**message) +``` + + + + + +```json +{ + "channel": "#general", + "mrkdwn": true, + "blocks": [ + { + "type": "section", + "block_id": "992ceb6b-9ad4-496b-b8e6-1bd8a632e8b3", + "text": { + "type": "mrkdwn", + "text": "Hello, world!" + } + } + ] +} +``` +Note: the `block_id` field is a pseudorandomly generated UUID. Pass an explicit `block_id` to any block constructor if you need deterministic IDs (e.g. for testing or interaction handling). + + + + + +```bash +curl -H "Content-type: application/json" \ + --data '{"channel":"#general","blocks":[{"type":"section","block_id":"992ceb6b-9ad4-496b-b8e6-1bd8a632e8b3","text":{"type":"mrkdwn","text":"Hello, world!"}}]}' \ + -H "Authorization: Bearer ${SLACK_API_TOKEN}" \ + -X POST https://slack.com/api/chat.postMessage +``` + + + + + +![Hello World rendered in Slack](/img/hello_world.png) + + + + + +## With the legacy `slackclient` + +The API is identical — only the import path changes: + +```python +from os import environ +from slack import WebClient # legacy slackclient package +from slackblocks import Message, SectionBlock + + +client = WebClient(token=environ["SLACK_API_TOKEN"]) +message = Message(channel="#general", blocks=SectionBlock("Hello, world!")) + +response = client.chat_postMessage(**message) +``` + +## Other delivery surfaces + +`slackblocks` provides specialized message classes for each Slack delivery surface. They all unpack the same way as `Message`. + +### Incoming webhooks + +```python +from slack_sdk.webhook import WebhookClient +from slackblocks import WebhookMessage, SectionBlock + +webhook = WebhookClient(url="https://hooks.slack.com/services/...") +message = WebhookMessage(blocks=SectionBlock("Build complete :white_check_mark:")) + +webhook.send(**message) +``` + +`WebhookMessage` supports webhook-only options like `response_type`, `replace_original`, and `delete_original`. + +### Slash command / interaction responses + +When responding to a slash command or interactive payload, use `MessageResponse`: + +```python +from slackblocks import MessageResponse, SectionBlock + +response_body = MessageResponse( + blocks=SectionBlock("Got it! Working on that now..."), + ephemeral=True, # only visible to the invoking user +).json() +``` + +### Modals & home tabs + +For modals and home tab views, build a `Modal` (or `HomeTabView`) and pass it to `views_open` / `views_publish`: + +```python +from slack_sdk import WebClient +from slackblocks import Modal, SectionBlock + +client = WebClient(token=environ["SLACK_API_TOKEN"]) +modal = Modal( + title="Confirm action", + blocks=[SectionBlock("Are you sure?")], + submit="Yes", + close="Cancel", +) + +client.views_open(trigger_id=trigger_id, view=modal.to_dict()) +``` + +See [Modals reference](../reference/python/modals) and [Views reference](../reference/python/views) for the full surface. + +## Sending without an SDK + +Because `Message` renders to a plain dict, you can also send it directly: + +```python +import json +import os +import urllib.request + +from slackblocks import Message, SectionBlock + +message = Message(channel="#general", blocks=SectionBlock("Hello, world!")) + +req = urllib.request.Request( + "https://slack.com/api/chat.postMessage", + data=message.json().encode("utf-8"), + headers={ + "Content-Type": "application/json; charset=utf-8", + "Authorization": f"Bearer {os.environ['SLACK_API_TOKEN']}", + }, +) +urllib.request.urlopen(req) +``` + + + + +## With `@slack/web-api` + +Factories return plain Slack-shaped objects, so pass the payload directly to the official client: + +```ts +import { WebClient } from "@slack/web-api"; +import { message, sectionBlock } from "@nicklambourne/slackblocks"; + +const client = new WebClient(process.env.SLACK_API_TOKEN); +const payload = message({ + channel: "C0123456", + blocks: [sectionBlock({ text: "Hello, world!" })], +}); + +await client.chat.postMessage(payload); +``` + +Use a channel ID rather than a display name when possible. Provide a `text` fallback for notifications and accessibility in production messages. + +## Incoming webhooks + +```ts +import { IncomingWebhook } from "@slack/webhook"; +import { sectionBlock, webhookMessage } from "@nicklambourne/slackblocks"; + +const webhook = new IncomingWebhook(process.env.SLACK_WEBHOOK_URL!); +await webhook.send(webhookMessage({ + blocks: [sectionBlock({ text: "Build complete :white_check_mark:" })], +})); +``` + +## Slash-command and interaction responses + +Construct the response body, then return it through your web framework: + +```ts +import { messageResponse, sectionBlock } from "@nicklambourne/slackblocks"; + +const responseBody = messageResponse({ + blocks: [sectionBlock({ text: "Got it! Working on that now..." })], + responseType: "ephemeral", +}); +``` + +## Modals and home tabs + +```ts +import { modal, sectionBlock } from "@nicklambourne/slackblocks"; + +const view = modal({ + title: "Confirm action", + blocks: [sectionBlock({ text: "Are you sure?" })], + submit: "Yes", + close: "Cancel", +}); + +await client.views.open({ trigger_id: triggerId, view }); +``` + +## Sending without an SDK + +```ts +await fetch("https://slack.com/api/chat.postMessage", { + method: "POST", + headers: { + authorization: `Bearer ${process.env.SLACK_API_TOKEN}`, + "content-type": "application/json", + }, + body: JSON.stringify(payload), +}); +``` + + + diff --git a/docs/versioned_docs/version-2.1.0/usage/troubleshooting.mdx b/docs/versioned_docs/version-2.1.0/usage/troubleshooting.mdx new file mode 100644 index 00000000..75de76b2 --- /dev/null +++ b/docs/versioned_docs/version-2.1.0/usage/troubleshooting.mdx @@ -0,0 +1,288 @@ +import LanguageContent, { Python, TypeScript } from '@site/src/components/LanguageContent'; + +# Troubleshooting & FAQ + +Practical answers to common questions, gotchas, and validation errors. + + + + +## Why is my message body coming through with literal `*asterisks*` instead of bold? + +Slack supports two text types: `mrkdwn` (a Slack-flavoured markdown) and `plain_text`. `slackblocks` uses `mrkdwn` by default for `SectionBlock` text, but **`HeaderBlock`, button labels, modal titles, input labels, and tab/option labels are forced to `plain_text` by Slack** — markdown syntax in those fields is rendered literally. + +If you need bold/italic styling in those places, you can't get it. If you need it elsewhere and aren't getting it, double-check you're not accidentally constructing a `Text(type_=TextType.PLAINTEXT, ...)`. + +## Why does my message say `text` is required? + +Slack will warn (or in some cases reject) messages that have `blocks` but no `text` fallback. The `text` field is used for: + +- Desktop and mobile **push notifications**. +- Accessibility readers. +- Clients that don't render Block Kit (rare, but they exist). + +Always pass a short `text=` summary alongside `blocks=`: + +```python +Message( + channel="#general", + text="Build #482 passed", # fallback + blocks=[HeaderBlock("Build #482 passed :white_check_mark:"), ...], +) +``` + +## What is `block_id` for? Should I set it? + +`block_id` is a stable identifier for a block. Slack echoes it back to you in interaction payloads (button clicks, modal submits) so you can correlate which block produced the event. + +- For **non-interactive** messages, you can leave it unset — `slackblocks` generates a random UUID. +- For **interactive** messages and modals, set explicit `block_id`s so your handlers can look up state reliably: + + ```python + ActionsBlock( + block_id="approval:req-123", + elements=[Button(text="Approve", action_id="approve", value="req-123")], + ) + ``` + +The same applies to `action_id` for elements. + +## What does `InvalidUsageError: ... exceeds limit of N characters` mean? + +Slack imposes hard character limits on most fields. `slackblocks` validates these at construction time so you find out before hitting Slack. Common limits: + +| Field | Limit (chars) | +|------------------------------------|---------------| +| `SectionBlock.text` | 3,000 | +| `SectionBlock.fields[i]` | 2,000 | +| `HeaderBlock.text` (`plain_text`) | 150 | +| `Button.text` | 75 | +| `Button.value` | 2,000 | +| `Button.url` | 3,000 | +| `Modal.title` / `submit` / `close` | 24 | +| `action_id` | 255 | +| `private_metadata` | 3,000 | +| `Option.url` | 3,000 | + +If a field exceeds its limit, truncate or split the content. + +## How many blocks can a single message have? + +- Channel messages: **50 blocks** (Slack-side limit). +- Modals and home tabs: **100 blocks**. +- `ContextBlock`: max **10 elements**. +- `ActionsBlock`: max **25 elements**. +- `SectionBlock.fields`: max **10 items**. +- `TableBlock`: max **100 rows × 20 columns**. + +## My buttons / selects don't do anything when clicked. + +`slackblocks` only constructs the *outgoing* payload. Handling button clicks, menu selections, and modal submissions requires: + +1. A public HTTPS endpoint registered as your app's **Interactivity & Shortcuts** URL. +2. An interaction handler that parses the payload Slack POSTs to that URL. + +The [`slack-bolt`](https://slack.dev/bolt-python/) framework is the easiest way to wire this up. + +## Why doesn't markdown work inside a `HeaderBlock`? + +By design — Slack only allows `plain_text` in headers. Use a `SectionBlock` (which supports `mrkdwn`) followed by a `DividerBlock` if you want bold or styled text as a heading. + +## How do I preview a message without actually sending it? + +Use Slack's [Block Kit Builder](https://app.slack.com/block-kit-builder) and paste the JSON output from `message.json()`: + +```python +print(message.json()) +``` + +## How do I send a `slackblocks.Message` with `requests`? + +`Message` renders to a dict, so: + +```python +import os +import requests + +from slackblocks import Message, SectionBlock + +message = Message(channel="#general", blocks=SectionBlock("Hi!")) + +requests.post( + "https://slack.com/api/chat.postMessage", + json=message.to_dict(), + headers={"Authorization": f"Bearer {os.environ['SLACK_API_TOKEN']}"}, +).raise_for_status() +``` + +## Can I use `slackblocks` with async code? + +Yes — `slackblocks` itself is synchronous and side-effect-free, so `Message(...)` construction works identically inside `async def` functions. Use the async `WebClient` from `slack_sdk.web.async_client` to actually send: + +```python +from slack_sdk.web.async_client import AsyncWebClient +from slackblocks import Message, SectionBlock + +async def notify(): + client = AsyncWebClient(token=...) + message = Message(channel="#general", blocks=SectionBlock("Hi!")) + await client.chat_postMessage(**message) +``` + +## How does `slackblocks` compare to the block classes in `slack-sdk`? + +`slack-sdk` ships its own `Block` / `SectionBlock` / etc. classes. `slackblocks` predates them and offers: + +- A more concise API (e.g. `SectionBlock("Hi!")` vs `SectionBlock(text=MarkdownTextObject(text="Hi!"))`). +- Stricter up-front validation with informative `InvalidUsageError` messages. +- Independent release cadence — usable with the legacy `slackclient` or no SDK at all. + +Use whichever you find more ergonomic; they produce equivalent JSON. + +## I'm getting a `pytest` `error` from a Python `DeprecationWarning`. + +`slackblocks`' own test suite turns warnings into errors via `pyproject.toml`. That setting only affects this project's CI — it doesn't propagate to your application. If you're seeing it, it's because you're running the `slackblocks` test suite as part of contributing. + +## Where do I report bugs / request features? + +Use [GitHub Issues](https://github.com/nicklambourne/slackblocks/issues). + + + + +## Why is my message showing literal `*asterisks*` instead of bold text? + +Slack supports `mrkdwn` and `plain_text`. The `sectionBlock()` factory turns a string into `mrkdwn` by default, but Slack requires headers, button labels, modal titles, input labels, and option labels to use `plain_text`. Markdown syntax in those fields is displayed literally. + +If styling is missing from a field that supports it, check that you have not wrapped the value with `plainText()`. Use `mrkdwn()` when you need to choose the text type explicitly. + +## Why does Slack say `text` is required? + +Messages containing blocks should also provide a short plain-text fallback. Slack uses it for push notifications, assistive technology, and clients that cannot render Block Kit. + +```ts +import { headerBlock, message } from "@nicklambourne/slackblocks"; + +const payload = message({ + channel: "C0123456", + text: "Build #482 passed", + blocks: [headerBlock({ text: "Build #482 passed :white_check_mark:" })], +}); +``` + +## What is `blockId` for? Should I set it? + +`blockId` becomes `block_id` in the Slack payload. Slack returns it in interaction payloads, which lets your app identify the block that produced a button click or modal submission. + +You can omit it for non-interactive content. For interactive messages and views, use a stable value that your handlers understand: + +```ts +import { actionsBlock, button } from "@nicklambourne/slackblocks"; + +actionsBlock({ + blockId: "approval:req-123", + elements: [ + button({ text: "Approve", actionId: "approve", value: "req-123" }), + ], +}); +``` + +The same principle applies to `actionId`, which becomes `action_id` on the wire. + +## What do `LengthError` and the other validation errors mean? + +`slackblocks` validates payloads while its factories construct them. An error such as `LengthError`, `RangeError`, or `MissingRequiredError` means the input would violate a known Block Kit rule. The error includes a path so you can find the invalid field before sending anything to Slack. + +Common limits include: + +| Factory field | Limit | +|-------------------------------------|-------| +| `sectionBlock().text` | 3,000 characters | +| `sectionBlock().fields[i]` | 2,000 characters | +| `headerBlock().text` | 150 characters | +| `button().text` | 75 characters | +| `button().value` | 2,000 characters | +| `button().url` | 3,000 characters | +| `modal().title` / `submit` / `close`| 24 characters | +| `actionId` | 255 characters | +| `privateMetadata` | 3,000 characters | +| `option().url` | 3,000 characters | + +If Slack adds a field or raises a limit before the package catches up, pass `{ validate: false }` as the final factory argument for that construction only. + +## How many blocks can a payload contain? + +- Channel messages: **50 blocks**. +- Modals and home tabs: **100 blocks**. +- `contextBlock()`: up to **10 elements**. +- `actionsBlock()`: up to **25 elements**. +- `sectionBlock().fields`: up to **10 items**. +- `tableBlock()`: up to **100 rows × 20 columns**. + +## Why don't my buttons or selects do anything when clicked? + +`slackblocks` only constructs outgoing payloads. Handling interactions requires a public HTTPS endpoint configured as your Slack app's **Interactivity & Shortcuts** request URL, plus code that handles the payload Slack sends there. + +[`@slack/bolt`](https://slack.dev/bolt-js/) is the usual starting point for a TypeScript or JavaScript app. + +## Why doesn't markdown work inside `headerBlock()`? + +Slack only accepts `plain_text` in header blocks. Use `sectionBlock()` followed by `dividerBlock()` when you need styled heading text. + +## How can I preview a message without sending it? + +Generate a Block Kit Builder URL and open it in your browser: + +```ts +import { blockKitBuilderUrl, message, sectionBlock } from "@nicklambourne/slackblocks"; + +const payload = message({ + channel: "C0123456", + text: "Preview message", + blocks: [sectionBlock({ text: "Hello!" })], +}); + +console.log(blockKitBuilderUrl(payload)); +``` + +You can also paste `JSON.stringify(payload, null, 2)` into Slack's [Block Kit Builder](https://app.slack.com/block-kit-builder). + +## How do I send a payload with `fetch()`? + +Factories return plain objects, so no conversion step is required: + +```ts +import { message, sectionBlock } from "@nicklambourne/slackblocks"; + +const payload = message({ + channel: "C0123456", + text: "Hello!", + blocks: [sectionBlock({ text: "Hello!" })], +}); + +const response = await fetch("https://slack.com/api/chat.postMessage", { + method: "POST", + headers: { + authorization: `Bearer ${process.env.SLACK_API_TOKEN}`, + "content-type": "application/json", + }, + body: JSON.stringify(payload), +}); + +if (!response.ok) throw new Error(`Slack returned ${response.status}`); +``` + +## Can I use `slackblocks` in async code? + +Yes. The factories are synchronous, side-effect-free functions that return ordinary objects. Construct the payload wherever it is convenient, then `await` your Slack SDK or HTTP client when you send it. + +## How does this differ from `@slack/types`? + +`@slack/types` supplies TypeScript definitions for Slack payloads. `slackblocks` adds small construction helpers, camelCase inputs, snake_case wire output, and eager validation with path-aware errors. The resulting objects remain compatible with Slack's official types and clients. + +## Where do I report bugs or request features? + +Use [GitHub Issues](https://github.com/nicklambourne/slackblocks/issues). + + + diff --git a/docs/versioned_docs/version-2.1.0/usage/using_blocks.mdx b/docs/versioned_docs/version-2.1.0/usage/using_blocks.mdx new file mode 100644 index 00000000..4d7c0539 --- /dev/null +++ b/docs/versioned_docs/version-2.1.0/usage/using_blocks.mdx @@ -0,0 +1,1679 @@ +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import LanguageContent, { Python, TypeScript } from '@site/src/components/LanguageContent'; + +# Using Blocks + +Blocks are the fundamental visual units of a Slack message. Each block type renders as a different UI component (a section of text, a header, a divider, an image, a row of buttons, and so on). A `Message` is composed of one or more blocks, rendered top-to-bottom. + +This page walks through every block type supported by `slackblocks`, with: + +- A short description of what the block is for. +- The `slackblocks` code to construct it in your selected language. +- The JSON payload that's produced. +- A screenshot of how it looks in Slack. + + + + +For the reverse mapping — looking up a class by name — see the [Blocks reference](../reference/python/blocks). For interactive UI bits (buttons, menus, date pickers) that go *inside* blocks, see [Elements](../reference/python/elements). + + + + +For exact factory inputs and return types, see the [TypeScript API reference](../reference/typescript). Interactive controls such as buttons, menus, and date pickers are documented alongside the other element factories. + + + + +## Section Block + + + + + + + + +```python +from slackblocks import CheckboxGroup, Option, SectionBlock + +SectionBlock( + text="This is a section block with a checkbox accessory.", + block_id="fake_block_id", + accessory=CheckboxGroup( + action_id="checkboxes-action", + options=[ + Option( + text="*Your Only Option*", + value="option_one" + ) + ] + ) +) +``` + + + + +```ts +import { checkboxes, mrkdwn, option, sectionBlock } from "@nicklambourne/slackblocks"; + +sectionBlock({ + text: "This is a section block with a checkbox accessory.", + blockId: "fake_block_id", + accessory: checkboxes({ + actionId: "checkboxes-action", + options: [ + option({ + text: mrkdwn("*Your Only Option*"), + value: "option_one", + }), + ], + }), +}); +``` + + + + + + + +```json +{ + "type": "section", + "block_id": "fake_block_id", + "text": { + "type": "mrkdwn", + "text": "This is a section block with a checkbox accessory." + }, + "accessory": { + "type": "checkboxes", + "options": [ + { + "text": { + "type": "mrkdwn", + "text": "*Your Only Option*" + }, + "value": "option_one" + } + ], + "action_id": "checkboxes-action" + } +} +``` + + + + + +![An example of the UI output of a Section Block](/img/usage/section.png) + + + + + +## Rich Text Block + + + + + + + +```python +from slackblocks import RichTextBlock, RichTextSection, RichText + +RichTextBlock( + RichTextSection( + [ + RichText( + "You 'bout to witness hip-hop in its most purest\n", + bold=True, + ), + RichText( + "Most rawest form, flow almost flawless\n", + strike=True, + ), + RichText( + "Most hardest, most honest known artist\n", + italic=True, + ), + ] + ), + block_id="fake_block_id", +) +``` + + + + +```ts +import { richText, richTextBlock, richTextSection } from "@nicklambourne/slackblocks"; + +richTextBlock({ + blockId: "fake_block_id", + elements: [ + richTextSection([ + richText("You 'bout to witness hip-hop in its most purest\n", { bold: true }), + richText("Most rawest form, flow almost flawless\n", { strike: true }), + richText("Most hardest, most honest known artist\n", { italic: true }), + ]), + ], +}); +``` + + + + + + + +```json +{ + "type": "rich_text", + "block_id": "fake_block_id", + "elements": [ + { + "type": "rich_text_section", + "elements": [ + { + "type": "text", + "text": "You 'bout to witness hip-hop in its most purest\n", + "style": { + "bold": true + } + }, + { + "type": "text", + "text": "Most rawest form, flow almost flawless\n", + "style": { + "strike": true + } + }, + { + "type": "text", + "text": "Most hardest, most honest known artist\n", + "style": { + "italic": true + } + } + ] + } + ] +} +``` + + + + + +![An example of the UI output of a Rich Text Block](/img/usage/rich_text.png) + + + + + +## Header Block + + + + + + + + +```python +from slackblocks import HeaderBlock + +HeaderBlock( + "This is a header block", + block_id="fake_block_id", +) +``` + + + + +```ts +import { headerBlock } from "@nicklambourne/slackblocks"; + +headerBlock({ + text: "This is a header block", + blockId: "fake_block_id", +}); +``` + + + + + + + +```json +{ + "type": "header", + "block_id": "fake_block_id", + "text": { + "type": "plain_text", + "text": "This is a header block" + } +} +``` + + + + + +![An example of the UI output of a Header Block](/img/usage/header.png) + + + + + +## Markdown Block + + +Slack added the `markdown` block type in 2024, primarily for AI / agentic apps. Unlike the `mrkdwn` text inside a [Section Block](#section-block), `MarkdownBlock` renders **GitHub-flavored Markdown**, supporting tables, code blocks, and richer list semantics. + +`text` is required (1 - 12,000 characters). + + + + + + + +```python +from slackblocks import MarkdownBlock + +MarkdownBlock( + text="**Hello!** Markdown blocks support _GitHub-flavored_ syntax.", + block_id="fake_block_id", +) +``` + + + + +```ts +import { markdownBlock } from "@nicklambourne/slackblocks"; + +markdownBlock({ + text: "**Hello!** Markdown blocks support _GitHub-flavored_ syntax.", + blockId: "fake_block_id", +}); +``` + + + + + + + +```json +{ + "type": "markdown", + "block_id": "fake_block_id", + "text": "**Hello!** Markdown blocks support _GitHub-flavored_ syntax." +} +``` + + + + + +See the [Slack reference](https://api.slack.com/reference/block-kit/blocks#markdown) for the supported Markdown features. + + +## Image Block + + + + + + + + +```python +from slackblocks import ImageBlock + +ImageBlock( + image_url="https://api.slack.com/img/blocks/bkb_template_images/beagle.png", + alt_text="a beagle", + title="dog", + block_id="fake_block_id", +) +``` + + + + +```ts +import { imageBlock } from "@nicklambourne/slackblocks"; + +imageBlock({ + imageUrl: "https://api.slack.com/img/blocks/bkb_template_images/beagle.png", + altText: "a beagle", + title: "dog", + blockId: "fake_block_id", +}); +``` + + + + + + + +```json +{ + "type": "image", + "block_id": "fake_block_id", + "image_url": "https://api.slack.com/img/blocks/bkb_template_images/beagle.png", + "alt_text": "a beagle", + "title": { + "type": "plain_text", + "text": "dog" + } +} +``` + + + + + +![An example of the UI output of an Image Block](/img/usage/image.png) + + + + + +## Input Block + + + + + + + + +```python +from slackblocks import InputBlock, Text, TextType, PlainTextInput + +InputBlock( + label=Text("Label", type_=TextType.PLAINTEXT, emoji=True), + hint=Text("Hint", type_=TextType.PLAINTEXT, emoji=True), + element=PlainTextInput(action_id="action"), + block_id="fake_block_id", + optional=True, +) +``` + + + + +```ts +import { inputBlock, plainText, plainTextInput } from "@nicklambourne/slackblocks"; + +inputBlock({ + label: plainText("Label", { emoji: true }), + hint: plainText("Hint", { emoji: true }), + element: plainTextInput({ actionId: "action" }), + blockId: "fake_block_id", + optional: true, +}); +``` + + + + + + + +```json +{ + "type": "input", + "block_id": "fake_block_id", + "label": { + "type": "plain_text", + "text": "Label", + "emoji": true + }, + "element": { + "type": "plain_text_input", + "action_id": "action" + }, + "hint": { + "type": "plain_text", + "text": "Hint", + "emoji": true + }, + "optional": true +} +``` + + + + + +![An example of the UI output of an Input Block](/img/usage/input.png) + + + + + +## Divider Block + + + + + + + + +```python +from slackblocks import DividerBlock + +DividerBlock(block_id="fake_block_id") +``` + + + + +```ts +import { dividerBlock } from "@nicklambourne/slackblocks"; + +dividerBlock({ blockId: "fake_block_id" }); +``` + + + + + + + +```json +{ + "type": "divider", + "block_id": "fake_block_id" +} +``` + + + + + +![An example of the UI output of an Divider Block](/img/usage/divider.png) + + + + + +## File Block + + + + + + + + +```python +from slackblocks import FileBlock + +FileBlock( + external_id="external_id", + block_id="fake_block_id", +) +``` + + + + +```ts +import { fileBlock } from "@nicklambourne/slackblocks"; + +fileBlock({ + externalId: "external_id", + blockId: "fake_block_id", +}); +``` + + + + + + + +```json +{ + "type": "file", + "external_id": "external_id", + "source": "remote", + "block_id": "fake_block_id" +} +``` + + + + + +![An example of the UI output of an File Block](https://a.slack-edge.com/f156a3/img/api/file_upload_remote_file.png) +* Note that this example comes from the Slack Web API docs. + + + + + +## Context Block + + + + + + + + +```python +from slackblocks import ContextBlock, Text + +ContextBlock( + elements=[ + Text("Hello, world!"), + ], + block_id="fake_block_id" +) +``` + + + + +```ts +import { contextBlock, mrkdwn } from "@nicklambourne/slackblocks"; + +contextBlock({ + elements: [mrkdwn("Hello, world!")], + blockId: "fake_block_id", +}); +``` + + + + + + + +```json +{ + "type": "context", + "block_id": "fake_block_id", + "elements": [ + { + "type": "mrkdwn", + "text": "Hello, world!" + } + ] +} +``` + + + + + +![An example of the UI output of a Context Block](/img/usage/context.png) + + + + + +## Actions Block + + + + + + + +```python +from slackblocks import ActionsBlock, CheckboxGroup, Option + +ActionsBlock( + block_id="fake_block_id", + elements=CheckboxGroup( + action_id="actionId-0", + options=[ + Option(text="*a*", value="a", description="*a*"), + Option(text="*b*", value="b", description="*b*"), + Option(text="*c*", value="c", description="*c*"), + ], + ), +) +``` + + + + +```ts +import { actionsBlock, checkboxes, mrkdwn, option, plainText } from "@nicklambourne/slackblocks"; + +actionsBlock({ + blockId: "fake_block_id", + elements: [ + checkboxes({ + actionId: "actionId-0", + options: ["a", "b", "c"].map((value) => + option({ + text: mrkdwn(`*${value}*`), + value, + description: plainText(`*${value}*`), + }), + ), + }), + ], +}); +``` + + + + + + + +```json +{ + "type": "actions", + "block_id": "fake_block_id", + "elements": [ + { + "type": "checkboxes", + "action_id": "actionId-0", + "options": [ + { + "text": { + "type": "mrkdwn", + "text": "*a*" + }, + "value": "a", + "description": { + "type": "plain_text", + "text": "*a*" + } + }, + { + "text": { + "type": "mrkdwn", + "text": "*b*" + }, + "value": "b", + "description": { + "type": "plain_text", + "text": "*b*" + } + }, + { + "text": { + "type": "mrkdwn", + "text": "*c*" + }, + "value": "c", + "description": { + "type": "plain_text", + "text": "*c*" + } + } + ] + } + ] +} +``` + + + + + +![An example of the UI output of an Actions Block](/img/usage/actions.png) + + + + + +## Table Block + + + + + + + +```python +from slackblocks import ( + ColumnSettings, + RawText, + RichText, + RichTextLink, + RichTextSection, + TableBlock, +) + +TableBlock( + block_id="fake_block_id", + column_settings=[ + ColumnSettings(align="right", is_wrapped=True), + ColumnSettings(align="left"), + ], + rows=[ + [ + RichTextSection( + elements=[RichText(text="Header 1", bold=True)], + ), + RichTextSection( + elements=[RichText(text="Header 2", bold=True)], + ), + ], + [ + RawText(text="Datum 1"), + RichTextSection( + elements=[ + RichTextLink( + url="https://slack.com", + text="Datum 2", + ) + ], + ), + ], + ], +) +``` + + + + +```ts +import { + columnSettings, + rawText, + richText, + richTextBlock, + richTextLink, + richTextSection, + tableBlock, +} from "@nicklambourne/slackblocks"; + +tableBlock({ + blockId: "fake_block_id", + columnSettings: [ + columnSettings({ align: "right", isWrapped: true }), + columnSettings({ align: "left" }), + ], + rows: [ + [ + richTextBlock({ + elements: [richTextSection([richText("Header 1", { bold: true })])], + }), + richTextBlock({ + elements: [richTextSection([richText("Header 2", { bold: true })])], + }), + ], + [ + rawText("Datum 1"), + richTextBlock({ + elements: [ + richTextSection([richTextLink({ url: "https://slack.com", text: "Datum 2" })]), + ], + }), + ], + ], +}); +``` + + + + + + + +```json +{ + "type": "table", + "block_id": "fake_block_id", + "rows": [ + [ + { + "type": "rich_text", + "elements": [ + { + "type": "rich_text_section", + "elements": [ + { + "type": "text", + "text": "Header 1", + "style": { + "bold": true + } + } + ] + } + ] + }, + { + "type": "rich_text", + "elements": [ + { + "type": "rich_text_section", + "elements": [ + { + "type": "text", + "text": "Header 2", + "style": { + "bold": true + } + } + ] + } + ] + } + ], + [ + { + "type": "raw_text", + "text": "Datum 1" + }, + { + "type": "rich_text", + "elements": [ + { + "type": "rich_text_section", + "elements": [ + { + "type": "link", + "url": "https://slack.com", + "text": "Datum 2" + } + ] + } + ] + } + ] + ], + "column_settings": [ + { + "align": "right", + "is_wrapped": true + }, + { + "align": "left" + } + ] +} +``` + + + + + +![An example of the UI output of a Table Block](/img/usage/table.png) + + + + + +## Video Block + + +Embeds a video from a Slack-supported provider such as YouTube or Vimeo. Plain strings supplied for `title` and `description` are converted to Slack `plain_text` objects automatically. + +Required: `alt_text`, `thumbnail_url`, `title`, `video_url`. Slack restricts which domains may be embedded — supplying an unsupported URL will produce a Slack API error rather than an `InvalidUsageError` at construction. + + + + + + + +```python +from slackblocks import VideoBlock + +VideoBlock( + alt_text="How to use slackblocks", + block_id="fake_block_id", + thumbnail_url="https://example.com/thumb.png", + title="Getting Started", + video_url="https://example.com/video.mp4", + author_name="The slackblocks docs", + description="A short walkthrough.", + provider_name="example.com", + title_url="https://example.com", +) +``` + + + + +```ts +import { videoBlock } from "@nicklambourne/slackblocks"; + +videoBlock({ + altText: "How to use slackblocks", + blockId: "fake_block_id", + thumbnailUrl: "https://example.com/thumb.png", + title: "Getting Started", + videoUrl: "https://example.com/video.mp4", + authorName: "The slackblocks docs", + description: "A short walkthrough.", + providerName: "example.com", + titleUrl: "https://example.com", +}); +``` + + + + + + + +```json +{ + "type": "video", + "block_id": "fake_block_id", + "alt_text": "How to use slackblocks", + "thumbnail_url": "https://example.com/thumb.png", + "title": { + "type": "plain_text", + "text": "Getting Started" + }, + "video_url": "https://example.com/video.mp4", + "author_name": "The slackblocks docs", + "description": { + "type": "plain_text", + "text": "A short walkthrough." + }, + "provider_name": "example.com", + "title_url": "https://example.com" +} +``` + + + + + +See the [Slack reference](https://api.slack.com/reference/block-kit/blocks#video) for the full list of optional fields and provider requirements. + +## Alert Block + +Alerts add a severity-labelled notice to a modal. + + + + + + + +```python +from slackblocks import AlertBlock + +AlertBlock( + "The deployment needs attention.", + level="warning", + block_id="fake_block_id", +) +``` + + + + +```ts +import { alertBlock } from "@nicklambourne/slackblocks"; + +alertBlock({ + text: "The deployment needs attention.", + level: "warning", + blockId: "fake_block_id", +}); +``` + + + + + + + +```json +{ + "type": "alert", + "block_id": "fake_block_id", + "text": { + "type": "mrkdwn", + "text": "The deployment needs attention." + }, + "level": "warning" +} +``` + + + + +![An example of the UI output of an Alert Block](/img/usage/alert.png) + + + + +## Card Block + +Cards combine text, images, Slack-provided icons, and up to three buttons in a compact panel. + + + + + + + +```python +from slackblocks import Button, CardBlock, SlackIcon + +CardBlock( + title="Build complete", + body="Version 2.1.0 is ready to deploy.", + slack_icon=SlackIcon("rocket"), + actions=Button("Open build", "open_build"), + block_id="fake_block_id", +) +``` + + + + +```ts +import { button, cardBlock, slackIcon } from "@nicklambourne/slackblocks"; + +cardBlock({ + title: "Build complete", + body: "Version 2.1.0 is ready to deploy.", + slackIcon: slackIcon("rocket"), + actions: [button({ text: "Open build", actionId: "open_build" })], + blockId: "fake_block_id", +}); +``` + + + + + + + +```json +{ + "type": "card", + "block_id": "fake_block_id", + "title": { + "type": "mrkdwn", + "text": "Build complete" + }, + "body": { + "type": "mrkdwn", + "text": "Version 2.1.0 is ready to deploy." + }, + "actions": [ + { + "type": "button", + "text": { + "type": "plain_text", + "text": "Open build" + }, + "action_id": "open_build" + } + ], + "slack_icon": { + "type": "icon", + "name": "rocket" + } +} +``` + + + + +![An example of the UI output of a Card Block](/img/usage/card.png) + + + + +## Carousel Block + +A carousel presents between one and ten cards in a horizontally scrolling collection. + + + + + + + +```python +from slackblocks import CardBlock, CarouselBlock + +CarouselBlock([ + CardBlock(title="First result", block_id="card_1"), + CardBlock(title="Second result", block_id="card_2"), +], block_id="fake_block_id") +``` + + + + +```ts +import { cardBlock, carouselBlock } from "@nicklambourne/slackblocks"; + +carouselBlock({ + elements: [ + cardBlock({ title: "First result", blockId: "card_1" }), + cardBlock({ title: "Second result", blockId: "card_2" }), + ], + blockId: "fake_block_id", +}); +``` + + + + + + + +```json +{ + "type": "carousel", + "block_id": "fake_block_id", + "elements": [ + { + "type": "card", + "block_id": "card_1", + "title": { + "type": "mrkdwn", + "text": "First result" + } + }, + { + "type": "card", + "block_id": "card_2", + "title": { + "type": "mrkdwn", + "text": "Second result" + } + } + ] +} +``` + + + + +![An example of the UI output of a Carousel Block](/img/usage/carousel.png) + + + + +## Container Block + +Containers group up to ten related child blocks under a plain-text or rich-text title. + + + + + + + +```python +from slackblocks import ContainerBlock, SectionBlock + +ContainerBlock( + title="Deployment summary", + child_blocks=[ + SectionBlock("All systems operational.", block_id="child_1"), + ], + has_header_divider=True, + block_id="fake_block_id", +) +``` + + + + +```ts +import { containerBlock, sectionBlock } from "@nicklambourne/slackblocks"; + +containerBlock({ + title: "Deployment summary", + childBlocks: [ + sectionBlock({ + text: "All systems operational.", + blockId: "child_1", + }), + ], + width: "standard", + isCollapsible: false, + defaultCollapsed: false, + hasHeaderDivider: true, + blockId: "fake_block_id", +}); +``` + + + + + + + +```json +{ + "type": "container", + "block_id": "fake_block_id", + "title": { + "type": "plain_text", + "text": "Deployment summary" + }, + "child_blocks": [ + { + "type": "section", + "block_id": "child_1", + "text": { + "type": "mrkdwn", + "text": "All systems operational." + } + } + ], + "width": "standard", + "is_collapsible": false, + "default_collapsed": false, + "has_header_divider": true +} +``` + + + + +![An example of the UI output of a Container Block](/img/usage/container.png) + + + + +## Context Actions Block + +Context actions hold feedback controls or compact icon buttons. Slack currently offers the `trash` icon for icon buttons. + + + + + + + +```python +from slackblocks import ContextActionsBlock, FeedbackButton, FeedbackButtons + +ContextActionsBlock([ + FeedbackButtons( + positive_button=FeedbackButton("Good", "positive"), + negative_button=FeedbackButton("Bad", "negative"), + action_id="response_feedback", + ) +], block_id="fake_block_id") +``` + + + + +```ts +import { contextActionsBlock, feedbackButton, feedbackButtons } from "@nicklambourne/slackblocks"; + +contextActionsBlock({ + elements: [ + feedbackButtons({ + actionId: "response_feedback", + positiveButton: feedbackButton({ text: "Good", value: "positive" }), + negativeButton: feedbackButton({ text: "Bad", value: "negative" }), + }), + ], + blockId: "fake_block_id", +}); +``` + + + + + + + +```json +{ + "type": "context_actions", + "block_id": "fake_block_id", + "elements": [ + { + "type": "feedback_buttons", + "positive_button": { + "text": { + "type": "plain_text", + "text": "Good" + }, + "value": "positive" + }, + "negative_button": { + "text": { + "type": "plain_text", + "text": "Bad" + }, + "value": "negative" + }, + "action_id": "response_feedback" + } + ] +} +``` + + + + +![An example of the UI output of a Context Actions Block](/img/usage/context_actions.png) + + + + +## Data Table Block + +Data tables support raw text, sortable raw numbers, and rich-text body cells. They require a header plus at least one data row. + + + + + + + +```python +from slackblocks import DataTableBlock, RawNumber, RawText + +DataTableBlock( + caption="Team scores", + rows=[ + [RawText("Name"), RawText("Score")], + [RawText("Alice"), RawNumber(42, "42")], + ], + block_id="fake_block_id", +) +``` + + + + +```ts +import { dataTableBlock, rawNumber, rawText } from "@nicklambourne/slackblocks"; + +dataTableBlock({ + caption: "Team scores", + rows: [ + [rawText("Name"), rawText("Score")], + [rawText("Alice"), rawNumber(42, "42")], + ], + blockId: "fake_block_id", +}); +``` + + + + + + + +```json +{ + "type": "data_table", + "block_id": "fake_block_id", + "rows": [ + [ + { + "type": "raw_text", + "text": "Name" + }, + { + "type": "raw_text", + "text": "Score" + } + ], + [ + { + "type": "raw_text", + "text": "Alice" + }, + { + "type": "raw_number", + "value": 42, + "text": "42" + } + ] + ], + "page_size": 5, + "caption": "Team scores", + "row_header_column_index": 0 +} +``` + + + + +![An example of the UI output of a Data Table Block](/img/usage/data_table.png) + + + + +## Data Visualization Block + +Slack can render pie charts or axis-based bar, area, and line charts directly from Block Kit data. + + + + + + + +```python +from slackblocks import ChartSegment, DataVisualizationBlock, PieChart + +DataVisualizationBlock( + title="Incidents by severity", + chart=PieChart([ + ChartSegment("High", 3), + ChartSegment("Low", 12), + ]), + block_id="fake_block_id", +) +``` + + + + +```ts +import { chartSegment, dataVisualizationBlock, pieChart } from "@nicklambourne/slackblocks"; + +dataVisualizationBlock({ + title: "Incidents by severity", + chart: pieChart([ + chartSegment({ label: "High", value: 3 }), + chartSegment({ label: "Low", value: 12 }), + ]), + blockId: "fake_block_id", +}); +``` + + + + + + + +```json +{ + "type": "data_visualization", + "block_id": "fake_block_id", + "title": "Incidents by severity", + "chart": { + "type": "pie", + "segments": [ + { + "label": "High", + "value": 3 + }, + { + "label": "Low", + "value": 12 + } + ] + } +} +``` + + + + +![An example of the UI output of a Data Visualization Block](/img/usage/data_visualization.png) + + + + +## Task Card Block + +Task cards show a task's state, optional rich-text details or output, and the URL sources used to produce it. + + + + + + + +```python +from slackblocks import TaskCardBlock, URLSource + +TaskCardBlock( + task_id="weather_1", + title="Fetch weather data", + status="complete", + sources=[URLSource("https://weather.com/", "weather.com")], + block_id="fake_block_id", +) +``` + + + + +```ts +import { taskCardBlock, urlSource } from "@nicklambourne/slackblocks"; + +taskCardBlock({ + taskId: "weather_1", + title: "Fetch weather data", + status: "complete", + sources: [urlSource({ url: "https://weather.com/", text: "weather.com" })], + blockId: "fake_block_id", +}); +``` + + + + + + + +```json +{ + "type": "task_card", + "block_id": "fake_block_id", + "task_id": "weather_1", + "title": "Fetch weather data", + "sources": [ + { + "type": "url", + "url": "https://weather.com/", + "text": "weather.com" + } + ], + "status": "complete" +} +``` + + + + +![An example of the UI output of a Task Card Block](/img/usage/task_card.png) + + + + +## Plan Block + +A plan groups task cards. `slackblocks` automatically renders nested tasks in Slack's plan-specific wire format. + + + + + + + +```python +from slackblocks import PlanBlock, TaskCardBlock + +PlanBlock( + title="Release plan", + tasks=[ + TaskCardBlock("test", "Run the test suite", status="complete"), + TaskCardBlock("deploy", "Deploy the release", status="pending"), + ], + block_id="fake_block_id", +) +``` + + + + +```ts +import { planBlock, taskCardBlock } from "@nicklambourne/slackblocks"; + +planBlock({ + title: "Release plan", + tasks: [ + taskCardBlock({ taskId: "test", title: "Run the test suite", status: "complete" }), + taskCardBlock({ taskId: "deploy", title: "Deploy the release", status: "pending" }), + ], + blockId: "fake_block_id", +}); +``` + + + + + + + +```json +{ + "type": "plan", + "block_id": "fake_block_id", + "title": "Release plan", + "tasks": [ + { + "task_id": "test", + "title": "Run the test suite", + "status": "complete" + }, + { + "task_id": "deploy", + "title": "Deploy the release", + "status": "pending" + } + ] +} +``` + + + + +![An example of the UI output of a Plan Block](/img/usage/plan.png) + + + diff --git a/docs/versioned_sidebars/version-2.1.0-sidebars.json b/docs/versioned_sidebars/version-2.1.0-sidebars.json new file mode 100644 index 00000000..1fd014a2 --- /dev/null +++ b/docs/versioned_sidebars/version-2.1.0-sidebars.json @@ -0,0 +1,8 @@ +{ + "docs": [ + { + "type": "autogenerated", + "dirName": "." + } + ] +} diff --git a/docs/versions.json b/docs/versions.json index e31f8856..cf450dee 100644 --- a/docs/versions.json +++ b/docs/versions.json @@ -1,4 +1,5 @@ [ + "2.1.0", "2.0.0", "1.2.5", "1.2.4",