@tightknitai/block-kitchen 0.6.1-alpha.0

package/dist/index.d.ts

@@ -0,0 +1,659 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { SectionBlock, HeaderBlock, DividerBlock, ContextBlock, ActionsBlock, ImageBlock, RichTextBlock, ImageElement, Button, ViewInputBlock } from 'slack-web-api-client';
+import { ComponentType, SVGProps } from 'react';
+
+/**
+ * Brand theme resolver for the BlockKitchen chrome.
+ *
+ * Consumers can already brand the builder by overriding the shadcn/ui
+ * CSS custom properties declared in `styles.src.css` (the lower-level
+ * contract). This module wraps that contract in a typed, ergonomic prop
+ * — a preset name and/or a `Partial<BrandTokens>` map — and resolves it
+ * to the `cssVarName -> value` pairs that `BrandThemeScope` then writes
+ * to a scoped `<style>` block around the builder.
+ *
+ * Scope is intentionally limited to the builder chrome. The Slack
+ * preview is rendered by `slack-blocks-to-jsx` under its own
+ * `#slack_blocks_to_jsx` CSS namespace and does not consume these vars,
+ * so brand tokens never leak into Slack content rendering.
+ */
+/**
+ * Tokens consumers may override. Mirrors the shadcn/ui token set
+ * already defined in `src/styles.src.css`. Color values are HSL
+ * component strings ("231.7 48.6% 54.1%") — matching the existing
+ * `hsl(var(--token, ...))` contract. `radius` takes a CSS length
+ * such as `"0.5rem"`.
+ */
+type BrandTokens = Partial<{
+    background: string;
+    foreground: string;
+    card: string;
+    cardForeground: string;
+    popover: string;
+    popoverForeground: string;
+    primary: string;
+    primaryForeground: string;
+    secondary: string;
+    secondaryForeground: string;
+    muted: string;
+    mutedForeground: string;
+    accent: string;
+    accentForeground: string;
+    destructive: string;
+    destructiveForeground: string;
+    border: string;
+    input: string;
+    ring: string;
+    radius: string;
+}>;
+/**
+ * Curated preset names. `'default'` is a no-op (relies on the
+ * `styles.src.css` fallbacks). The other entries each define their own
+ * color palette and `radius`, demonstrating that brand presets can vary
+ * stylistic axes beyond color. Adding more later is non-breaking —
+ * extend the string union and add an entry to `PRESETS`.
+ */
+type BrandPreset = 'default' | 'slack' | 'ocean' | 'sunset' | 'mono' | 'cyberpunk';
+/**
+ * Brand theme shape.
+ *
+ * - `preset` seeds the token map (currently a no-op for `'default'`).
+ * - `tokens` applies in both light and dark.
+ * - `light`/`dark` apply only when the matching dark-mode class is
+ *   present on an ancestor (or on the scope itself).
+ *
+ * Merge precedence (later wins): preset → tokens → light/dark.
+ */
+interface BrandTheme {
+    preset?: BrandPreset;
+    tokens?: BrandTokens;
+    light?: BrandTokens;
+    dark?: BrandTokens;
+}
+
+/**
+ * One pre-built block example shown as a draggable item in the palette.
+ * Modeled on Slack's real Block Kit Builder ("All selects", "Datepickers",
+ * "Filtered conversation", etc).
+ */
+interface PaletteVariant {
+    /** Stable id used as the DnD draggable id (`palette:${id}`). */
+    id: string;
+    /** Visible label shown next to the `+` icon. */
+    label: string;
+    /** Builds a fresh block payload when this variant is dropped. */
+    factory: () => SupportedBlock;
+}
+/**
+ * One section in the palette. Sections group related variants under a
+ * single heading + icon, matching Slack's Block Kit Builder sidebar
+ * (Agents, Markdown, Section, Actions, Input, Structure, Rich Text,
+ * Image, Card and Carousel, Table).
+ *
+ * Variant ids must be unique across the entire palette — the drag-drop
+ * variant lookup keys by id, so a duplicate would shadow the earlier one.
+ */
+interface PaletteSection {
+    /** Visible heading for the section. */
+    name: string;
+    /** Lucide icon component rendered next to the section heading. */
+    icon: ComponentType<SVGProps<SVGSVGElement>>;
+    variants: PaletteVariant[];
+}
+/**
+ * The built-in palette. Mirrors Slack's real Block Kit Builder: related
+ * variants (e.g. every select type) are combined into single showcase
+ * `actions` blocks ("All selects", "Datepickers") rather than each
+ * variant being its own row. The full set of single-element `input`
+ * variants is still available via {@link legacyInputVariants}.
+ */
+declare const defaultPalette: readonly PaletteSection[];
+/**
+ * The single-element `input`-block variants that used to ship in
+ * `defaultPalette` before it was consolidated to mirror Slack's Block
+ * Kit Builder. Kept reachable so consumers who referenced these ids via
+ * the `palette` prop can spread them back into a custom palette.
+ *
+ * @example
+ * ```tsx
+ * import { defaultPalette, legacyInputVariants } from '@tightknitai/block-kitchen';
+ * import { TextCursorInput } from 'lucide-react';
+ *
+ * const palette = [
+ *   ...defaultPalette,
+ *   { name: 'All inputs', icon: TextCursorInput, variants: [...legacyInputVariants] }
+ * ];
+ * ```
+ *
+ * Note: some ids here (`input_plain_text`, `input_date`, etc.) collide
+ * with curated ids in the new `defaultPalette`. `buildVariantById`
+ * keeps the last entry for a given id, so spread `legacyInputVariants`
+ * after `defaultPalette` to use the legacy factory.
+ */
+declare const legacyInputVariants: readonly PaletteVariant[];
+/**
+ * Modal-only `alert` block variant. Dropped from `defaultPalette` to
+ * match Slack's Block Kit Builder sidebar (which doesn't list it), but
+ * kept reachable so consumers who want it back can re-add via a custom
+ * palette section.
+ */
+declare const extraAlertVariant: PaletteVariant;
+
+/**
+ * The Slack Block Kit block types supported by the builder in v1.
+ */
+type SupportedBlockType = 'section' | 'header' | 'divider' | 'context' | 'actions' | 'image' | 'markdown' | 'rich_text' | 'table' | 'alert' | 'card' | 'carousel' | 'context_actions' | 'input';
+/**
+ * Slack `markdown` block payload. Renders standard markdown (GFM)
+ * via `slack-blocks-to-jsx`'s react-markdown integration.
+ * `slack-web-api-client` doesn't ship this type yet, so we declare
+ * the minimal shape ourselves.
+ */
+interface MarkdownBlock {
+    type: 'markdown';
+    text: string;
+    block_id?: string;
+}
+/**
+ * One cell in a {@link TableBlock} row. Slack accepts either a raw text
+ * cell or a rich-text cell; the visual editor only emits raw text in v1
+ * but preserves rich-text cells on edit.
+ */
+type TableCell = {
+    type: 'raw_text';
+    text: string;
+} | {
+    type: 'rich_text';
+    elements: unknown[];
+};
+/**
+ * Per-column setting in a {@link TableBlock}. May be null to skip a
+ * column. Matches Slack's `table_column_setting` schema.
+ */
+type TableColumnSetting = null | {
+    align?: 'left' | 'center' | 'right';
+    is_wrapped?: boolean;
+};
+/**
+ * Slack `table` block payload. Up to 100 rows, 20 cells per row.
+ * `slack-web-api-client` doesn't ship this type, so we declare it.
+ */
+interface TableBlock {
+    type: 'table';
+    rows: TableCell[][];
+    column_settings?: TableColumnSetting[];
+    block_id?: string;
+}
+/**
+ * Severity level for an {@link AlertBlock}. Controls the icon and color
+ * accent rendered by Slack. Defaults to `default` when omitted.
+ */
+type AlertLevel = 'default' | 'info' | 'warning' | 'error' | 'success';
+/**
+ * Slack `alert` block payload. Single-line status notification with an
+ * optional severity level. Per Slack's surface compatibility rules, alert
+ * blocks render on modal surfaces only (not messages or home tabs).
+ * `slack-web-api-client` doesn't ship this type yet, so we declare it.
+ */
+interface AlertBlock {
+    type: 'alert';
+    text: {
+        type: 'plain_text' | 'mrkdwn';
+        text: string;
+        emoji?: boolean;
+        verbatim?: boolean;
+    };
+    level?: AlertLevel;
+    block_id?: string;
+}
+/**
+ * Slack `card` block payload. Renders a media-rich card with optional
+ * hero image, icon, title, subtitle, body, and action buttons. At least
+ * one of `hero_image`, `title`, `actions`, or `body` is required.
+ * `slack-web-api-client` doesn't ship this type yet, so we declare it.
+ */
+interface CardBlock {
+    type: 'card';
+    block_id?: string;
+    hero_image?: ImageElement;
+    icon?: ImageElement;
+    title?: {
+        type: 'plain_text' | 'mrkdwn';
+        text: string;
+        emoji?: boolean;
+        verbatim?: boolean;
+    };
+    subtitle?: {
+        type: 'plain_text' | 'mrkdwn';
+        text: string;
+        emoji?: boolean;
+        verbatim?: boolean;
+    };
+    body?: {
+        type: 'plain_text' | 'mrkdwn';
+        text: string;
+        emoji?: boolean;
+        verbatim?: boolean;
+    };
+    actions?: Button[];
+}
+/**
+ * Slack `carousel` block payload. A horizontally scrollable group of
+ * 1-10 {@link CardBlock} elements. `slack-web-api-client` doesn't ship
+ * this type yet, so we declare it.
+ */
+interface CarouselBlock {
+    type: 'carousel';
+    elements: CardBlock[];
+    block_id?: string;
+}
+/**
+ * Sub-button used inside a {@link FeedbackButtonsElement}.
+ */
+interface FeedbackButtonSubobject {
+    text: {
+        type: 'plain_text';
+        text: string;
+        emoji?: boolean;
+    };
+    value: string;
+    accessibility_label?: string;
+}
+/**
+ * `feedback_buttons` element. Pair of positive/negative buttons used
+ * inside a {@link ContextActionsBlock} (e.g. "Good Response" / "Bad
+ * Response" thumbs).
+ */
+interface FeedbackButtonsElement {
+    type: 'feedback_buttons';
+    positive_button: FeedbackButtonSubobject;
+    negative_button: FeedbackButtonSubobject;
+    action_id?: string;
+}
+/**
+ * Slack icon names valid on an {@link IconButtonElement}. Slack only
+ * ships `trash` today; widen as Slack adds more.
+ */
+type IconButtonIcon = 'trash';
+/**
+ * `icon_button` element. Compact icon-with-label button used inside a
+ * {@link ContextActionsBlock} (e.g. a "Remove" trash-icon button).
+ */
+interface IconButtonElement {
+    type: 'icon_button';
+    icon: IconButtonIcon;
+    text: {
+        type: 'plain_text';
+        text: string;
+        emoji?: boolean;
+    };
+    action_id?: string;
+    value?: string;
+    accessibility_label?: string;
+}
+/**
+ * Element accepted by a {@link ContextActionsBlock}.
+ */
+type ContextActionsElement = FeedbackButtonsElement | IconButtonElement;
+/**
+ * Slack `context_actions` block payload. Renders a row of contextual
+ * action buttons (1-5 elements) attached to a message. Only valid on
+ * the message surface; the validator already encodes that.
+ * `slack-web-api-client` doesn't ship this type yet, so we declare it.
+ */
+interface ContextActionsBlock {
+    type: 'context_actions';
+    elements: ContextActionsElement[];
+    block_id?: string;
+}
+/**
+ * Slack `input` block payload. Aliased to `ViewInputBlock` from
+ * `slack-web-api-client`, which is the superset that accepts every
+ * supported input element (including `rich_text_input` and `file_input`).
+ * Surface compatibility (input is valid on modal and home tab; some
+ * elements are modal-only) is enforced by the validator, not the type.
+ */
+type InputBlock = ViewInputBlock;
+/**
+ * Header heading level shown in the preview. Slack's API has no
+ * `level` field on header blocks, so this is a builder-only extension
+ * that round-trips on the block payload but is otherwise cosmetic.
+ */
+type HeaderLevel = 1 | 2 | 3 | 4;
+/**
+ * Header block as edited by the builder. Extends Slack's HeaderBlock
+ * with an optional {@link HeaderLevel}.
+ */
+type SupportedHeaderBlock = HeaderBlock & {
+    level?: HeaderLevel;
+};
+/**
+ * Discriminated union of supported block payload shapes.
+ * Subset of {@link AnyMessageBlock} from `slack-web-api-client`,
+ * plus a header `level` extension.
+ */
+type SupportedBlock = SectionBlock | SupportedHeaderBlock | DividerBlock | ContextBlock | ActionsBlock | ImageBlock | MarkdownBlock | RichTextBlock | TableBlock | AlertBlock | CardBlock | CarouselBlock | ContextActionsBlock | InputBlock;
+/**
+ * A block as represented inside the builder's working state.
+ * `id` is an ephemeral client-side identifier used by DnD and selection.
+ * It is stripped before serialization to Slack.
+ */
+interface BuilderBlock {
+    id: string;
+    block: SupportedBlock;
+}
+/**
+ * Channel record returned by {@link BlockKitchenProps.loadChannels}.
+ */
+interface ChannelOption {
+    id: string;
+    name: string;
+}
+/**
+ * User-token status returned by {@link BlockKitchenProps.loadSendAsUserStatus}.
+ * If `canSendAsUser` is false, `oauthUrl` is required so the UI can show a
+ * "Sign in with Slack" link.
+ */
+interface SendAsUserStatus {
+    canSendAsUser: boolean;
+    oauthUrl?: string;
+}
+/**
+ * Payload passed to {@link BlockKitchenProps.onSend}.
+ */
+interface SendPayload {
+    channelId: string;
+    blocks: SupportedBlock[];
+    sendAsUser: boolean;
+}
+/**
+ * Result returned from {@link BlockKitchenProps.onSend}.
+ * `error` is a human-readable message; the dialog renders it as-is.
+ */
+interface SendResult {
+    ok: boolean;
+    error?: string;
+}
+/**
+ * Hooks forwarded to `slack-blocks-to-jsx`'s `<Message>` so the consumer can
+ * resolve user mentions, channel mentions, custom emojis, and links to
+ * application-specific UI. See the upstream library for the full hook shape.
+ * Marked as `unknown`-keyed at this layer to avoid leaking the upstream
+ * library's internal types into our public API.
+ */
+type PreviewHooks = Record<string, unknown>;
+/**
+ * Light or dark theme for the rendered Slack preview. Wired to
+ * `slack-blocks-to-jsx`'s `theme` prop and `data-theme` attribute.
+ */
+type PreviewTheme = 'light' | 'dark';
+/**
+ * Which Slack surface the preview is approximating. Affects the
+ * chrome rendered around the block list (message header, modal frame,
+ * or app home tab).
+ */
+type PreviewSurface = 'message' | 'modal' | 'app_home';
+/**
+ * A reusable block layout the user can apply as a starting point.
+ * Consumed by the standalone `<TemplatePicker>` component, which renders
+ * a categorized grid of template cards (modeled on Slack's own Block
+ * Kit Builder templates page) and emits the selected one. The picker
+ * is decoupled from {@link BlockKitchen} — wire `onSelect` to whatever
+ * state owns the draft blocks (e.g. lift `initialBlocks` into your own
+ * state and reset it from the handler).
+ */
+interface Template {
+    /** Stable identifier used as the React key and for persistence. */
+    id: string;
+    /** Display name shown on the template card. */
+    name: string;
+    /** Optional one-line description shown under the name on the card. */
+    description?: string;
+    /**
+     * Which Slack surface this template was authored for. The picker can
+     * filter to a single surface via its `surface` prop; the field is also
+     * available to consumers who render templates in their own UI.
+     */
+    surface: PreviewSurface;
+    /**
+     * Optional category name used to group templates into sections in the
+     * picker (e.g. `"Approvals"`, `"Notifications"`, `"Onboarding"`).
+     * Templates without a category fall into a trailing "Other" section
+     * when at least one other template specifies one; otherwise the grid
+     * is rendered flat without section headers.
+     */
+    category?: string;
+    /** Block payloads applied to the draft when the template is selected. */
+    blocks: SupportedBlock[];
+}
+/**
+ * Props for the top-level {@link BlockKitchen} component.
+ * The package is integration-agnostic: every I/O concern is brokered
+ * through these props. The component never makes a network call itself.
+ */
+interface BlockKitchenProps {
+    /**
+     * Workspace name shown in the preview chrome to mimic a Slack message header.
+     * Cosmetic only.
+     */
+    workspaceName?: string;
+    /**
+     * Initial draft blocks. If omitted the builder starts empty.
+     */
+    initialBlocks?: SupportedBlock[];
+    /**
+     * Fires whenever the draft state changes. Use to persist the draft
+     * (URL search param, localStorage, etc).
+     */
+    onChange?: (blocks: SupportedBlock[]) => void;
+    /**
+     * Optional hooks forwarded to the underlying `<Message>` component for
+     * resolving user / channel / emoji directives. If omitted, those
+     * directives render with the library's defaults.
+     */
+    previewHooks?: PreviewHooks;
+    /**
+     * Returns channels available to send to. Called when the send dialog opens.
+     */
+    loadChannels: () => Promise<ChannelOption[]>;
+    /**
+     * Returns whether the current user can post as themselves and, if not, an
+     * OAuth URL to start the install flow.
+     */
+    loadSendAsUserStatus: () => Promise<SendAsUserStatus>;
+    /**
+     * Called when the user submits the send dialog. Should return
+     * `{ ok: true }` on success or `{ ok: false, error }` on failure.
+     */
+    onSend: (payload: SendPayload) => Promise<SendResult>;
+    /**
+     * The palette shown on the left-hand side. When omitted, the built-in
+     * `defaultPalette` is used. Pass a custom array (typically built by
+     * spreading and filtering `defaultPalette`, plus your own sections) to
+     * curate the variants and pre-configured presets your users can drag
+     * onto the surface. An empty array renders an empty palette.
+     *
+     * The `defaultPalette` mirrors Slack's Block Kit Builder, which
+     * consolidates related variants into single showcase entries (e.g.
+     * **All selects** is one `actions` block with every select type). If
+     * you previously relied on the long flat list of single-element
+     * `input` variants (`input_users_select`, `input_multi_users_select`,
+     * `input_radio_buttons`, etc.), import `legacyInputVariants` and
+     * spread them into a custom section. The modal-only `alert` block was
+     * also dropped from the default; reach for `extraAlertVariant` to
+     * keep it.
+     *
+     * Variant ids must be unique across the array — the drag-drop lookup
+     * keys by id, so duplicates would shadow each other. The palette is
+     * also expected to be referentially stable across renders (wrap in
+     * `useMemo` or define at module scope).
+     */
+    palette?: readonly PaletteSection[];
+    /**
+     * Whether the palette renders a quick-search input above the section
+     * list. Defaults to `true`. Set `false` for compact palettes (e.g.
+     * when you've passed a small custom `palette`) where scanning by eye
+     * is faster than typing.
+     */
+    showPaletteSearch?: boolean;
+    /**
+     * Placeholder text for the palette search input. Defaults to
+     * `'Search blocks…'`. Useful for localization.
+     */
+    paletteSearchPlaceholder?: string;
+    /**
+     * Controls which palette section headers are expanded on first paint.
+     * - `true` (default) — every section starts open
+     * - `false` — every section starts closed (Slack-style)
+     * - array of section names — only sections whose `name` is in the
+     *   list start open (e.g. `['Section', 'Actions']`); matched
+     *   case-sensitively against `PaletteSection.name` so consumer-defined
+     *   sections are addressable too.
+     *
+     * After mount, each section owns its own collapse state, so users can
+     * still toggle headers freely. An active palette search overrides the
+     * collapse state for matching sections.
+     */
+    defaultOpenSections?: boolean | readonly string[];
+    /**
+     * Which Slack preview surfaces the toolbar exposes. Defaults to
+     * `['message']`, which locks the preview to Message and hides the
+     * surface dropdown. Pass two or more to show the dropdown with those
+     * options; the first entry becomes the initial selection.
+     */
+    allowedSurfaces?: readonly PreviewSurface[];
+    /**
+     * Whether the toolbar exposes the light/dark theme dropdown.
+     * Defaults to `true`. When `false`, the theme is locked to
+     * {@link PreviewTheme} `'light'`.
+     */
+    showThemeControl?: boolean;
+    /**
+     * Customizes or hides the "Docs" link in the toolbar.
+     * - `undefined` (default) — links to the Slack Block Kit reference docs
+     * - `false` — hides the link entirely
+     * - `{ href }` — overrides the URL (label defaults to `'Docs'`)
+     * - `{ href, label }` — overrides both
+     *
+     * Useful when embedding Block Kitchen inside a product that ships its
+     * own documentation, or for localizing the label.
+     */
+    docsLink?: false | {
+        href?: string;
+        label?: string;
+    };
+    /**
+     * Initial preview theme. Defaults to `'light'`. Pass the host app's
+     * current theme (e.g. from `next-themes` or your own theme hook) so
+     * the preview opens matched to the consuming app's appearance. The
+     * user can still override via the toolbar dropdown if
+     * {@link BlockKitchenProps.showThemeControl} is `true`.
+     */
+    defaultPreviewTheme?: PreviewTheme;
+    /**
+     * Branding tokens applied to the builder chrome (toolbar, palette,
+     * popover editors, send dialog, JSON drawer, issues sheet). The
+     * Slack preview itself is rendered by `slack-blocks-to-jsx` with its
+     * native Slack styling regardless — use {@link BlockKitchenProps.defaultPreviewTheme}
+     * for preview light/dark.
+     *
+     * Pass a preset name as sugar for `{ preset }`, or an object with
+     * `tokens` (applied in both modes) and optional `light`/`dark`
+     * overrides. The existing CSS-variable override path (importing the
+     * stylesheet and setting `--primary`, etc. on your own selector)
+     * continues to work; this prop is a typed shortcut on top of it.
+     *
+     * @example
+     * ```tsx
+     * <BlockKitchen
+     *   theme={{
+     *     tokens: { primary: '262 83% 58%', radius: '0.75rem' },
+     *     dark: { primary: '263 70% 65%' }
+     *   }}
+     *   {...rest}
+     * />
+     * ```
+     */
+    theme?: BrandTheme | BrandPreset;
+}
+
+/**
+ * Top-level Slack Block Kit builder component.
+ * Renders the toolbar, palette, preview surface, popover editors, send
+ * dialog, and View-JSON drawer. Integration-agnostic: all I/O is brokered
+ * through props.
+ * @param props - {@link BlockKitchenProps}
+ * @returns the rendered Block Kit Builder
+ */
+declare function BlockKitchen(props: BlockKitchenProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Standalone, page-sized picker that displays {@link Template}s as a
+ * grid of cards with live block previews, organized into category
+ * sections — modeled on Slack's own Block Kit Builder templates page.
+ * Pure UI: wire `onSelect` to whatever state owns the draft blocks
+ * (e.g. lifted `initialBlocks` on {@link BlockKitchen}, your own
+ * store, a router-driven URL param).
+ *
+ * Compose alongside {@link BlockKitchen} however fits your layout
+ * (route, modal, slide-over, tab). This component intentionally does
+ * not own its own dialog so the consumer controls placement and
+ * dismissal.
+ *
+ * @param props - picker props
+ * @param props.templates - templates to show. Order is preserved within
+ *   each category section.
+ * @param props.onSelect - called when the user clicks a template card.
+ * @param props.surface - optional surface filter. When set, only
+ *   templates whose {@link Template.surface} matches are shown.
+ * @param props.theme - preview theme used inside the card thumbnails.
+ *   Defaults to `'light'`.
+ * @param props.heading - optional heading rendered above the grid. When
+ *   omitted, no heading is rendered.
+ * @param props.emptyLabel - text shown when no templates match the
+ *   surface filter. Defaults to `"No templates available."`.
+ * @param props.className - additional classes merged onto the root.
+ */
+declare function TemplatePicker({ templates, onSelect, surface, theme, heading, emptyLabel, className }: {
+    templates: readonly Template[];
+    onSelect: (template: Template) => void;
+    surface?: PreviewSurface;
+    theme?: PreviewTheme;
+    heading?: string;
+    emptyLabel?: string;
+    className?: string;
+}): react_jsx_runtime.JSX.Element;
+
+/**
+ * Strip builder-only fields from blocks so they conform to Slack's
+ * Block Kit schema, and scrub dangerous URI schemes from any
+ * `url`/`image_url` fields. Currently removes the cosmetic `level`
+ * field from header blocks (a builder-only extension Slack would
+ * reject) and routes every URL/image-url through the allowlist in
+ * `lib/url-safety.ts` so a payload that round-trips through the
+ * builder cannot carry `javascript:`/`data:text/html` URIs to a
+ * downstream consumer or to the Slack API.
+ * @param blocks - the working draft blocks
+ * @returns blocks with builder-only fields removed and URLs scrubbed
+ */
+declare function toSlackBlocks(blocks: SupportedBlock[]): SupportedBlock[];
+
+/**
+ * Encodes a block list to a base64url string suitable for use as a URL
+ * search param. The consumer chooses where to put it (search param, hash,
+ * localStorage, etc).
+ * Returns an empty string for an empty list so the consumer can omit the
+ * param entirely.
+ * @param blocks - the blocks to encode
+ * @returns base64url-encoded JSON, or '' if blocks is empty
+ */
+declare function encodeBlocksToString(blocks: SupportedBlock[]): string;
+/**
+ * Decodes a string produced by {@link encodeBlocksToString} back to a
+ * block list. Returns null on any decode/parse error.
+ * @param encoded - the encoded string
+ * @returns decoded blocks, or null if input is empty/invalid
+ */
+declare function decodeBlocksFromString(encoded: string | undefined | null): SupportedBlock[] | null;
+
+export { type AlertBlock, type AlertLevel, BlockKitchen, type BlockKitchenProps, type BrandPreset, type BrandTheme, type BrandTokens, type BuilderBlock, type CardBlock, type CarouselBlock, type ChannelOption, type ContextActionsBlock, type ContextActionsElement, type FeedbackButtonSubobject, type FeedbackButtonsElement, type HeaderLevel, type IconButtonElement, type IconButtonIcon, type InputBlock, type MarkdownBlock, type PaletteSection, type PaletteVariant, type PreviewHooks, type PreviewSurface, type PreviewTheme, type SendAsUserStatus, type SendPayload, type SendResult, type SupportedBlock, type SupportedBlockType, type SupportedHeaderBlock, type TableBlock, type TableCell, type TableColumnSetting, type Template, TemplatePicker, decodeBlocksFromString, defaultPalette, encodeBlocksToString, extraAlertVariant, legacyInputVariants, toSlackBlocks };