@tightknitai/block-kitchen 0.6.1-alpha.0 → 0.8.2

package/dist/palette-CTUROcUC.d.ts

@@ -0,0 +1,674 @@
+import { ComponentType, SVGProps } from 'react';
+import { SectionBlock, HeaderBlock, DividerBlock, ContextBlock, ActionsBlock, ImageBlock, RichTextBlock, ImageElement, Button, ViewInputBlock } from 'slack-web-api-client';
+
+/**
+ * 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[];
+/**
+ * Standalone `alert` block variant. The full set of severity-level alert
+ * variants ships in `defaultPalette` under the "Alert" section; this
+ * export is retained for backward compatibility with consumers who
+ * previously spread it onto a custom palette. Shares the `alert_warning`
+ * id with its counterpart in `defaultPalette` — spread after
+ * `defaultPalette` (or omit it entirely) to avoid duplicate-id lookups.
+ */
+declare const extraAlertVariant: PaletteVariant;
+/**
+ * Builds a lookup table mapping a variant id to its definition for a
+ * resolved palette. Used by the DnD drop handler to resolve a
+ * `palette:${id}` drag back to a factory.
+ * @param sections - the palette in use (defaults or a consumer-provided one)
+ * @returns a map keyed by variant id
+ */
+declare function buildVariantById(sections: readonly PaletteSection[]): ReadonlyMap<string, 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' | 'video' | 'plan' | 'task_card';
+/**
+ * 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;
+/**
+ * Slack `video` block payload. Renders an embedded video player with
+ * thumbnail, title, optional description, and provider metadata. Sending
+ * requires the `links.embed:write` OAuth scope and `video_url` to live in
+ * the app's configured unfurl domains. `slack-web-api-client` doesn't ship
+ * this type yet, so we declare it.
+ */
+interface VideoBlock {
+    type: 'video';
+    alt_text: string;
+    title: {
+        type: 'plain_text';
+        text: string;
+        emoji?: boolean;
+    };
+    thumbnail_url: string;
+    video_url: string;
+    author_name?: string;
+    description?: {
+        type: 'plain_text';
+        text: string;
+        emoji?: boolean;
+    };
+    provider_icon_url?: string;
+    provider_name?: string;
+    title_url?: string;
+    block_id?: string;
+}
+/**
+ * Status of a {@link TaskCardBlock} as shown by Slack. `pending`,
+ * `in_progress`, and `complete` render distinct status chips; `error`
+ * renders a failure state.
+ */
+type TaskCardStatus = 'pending' | 'in_progress' | 'complete' | 'error';
+/**
+ * URL source attached to a {@link TaskCardBlock}. Rendered as a labeled
+ * link below the task body so agents can cite which document, ticket, or
+ * page their step consulted.
+ */
+interface UrlSourceElement {
+    type: 'url';
+    url: string;
+    text: string;
+}
+/**
+ * Slack `task_card` block payload. Renders an agent-facing card showing a
+ * tracked task with optional details (rich text), output (rich text), and
+ * cited sources. Valid on message surfaces only.
+ * `slack-web-api-client` doesn't ship this type yet, so we declare it.
+ */
+interface TaskCardBlock {
+    type: 'task_card';
+    task_id: string;
+    title: string;
+    details?: RichTextBlock;
+    output?: RichTextBlock;
+    sources?: UrlSourceElement[];
+    status?: TaskCardStatus;
+    block_id?: string;
+}
+/**
+ * Slack `plan` block payload. Renders a titled checklist of tasks an
+ * agent is executing. Each task is an inline {@link TaskCardBlock}.
+ * Valid on message surfaces only. `slack-web-api-client` doesn't ship
+ * this type yet, so we declare it.
+ */
+interface PlanBlock {
+    type: 'plan';
+    title: string | {
+        type: 'plain_text';
+        text: string;
+        emoji?: boolean;
+    };
+    tasks?: TaskCardBlock[];
+    block_id?: string;
+}
+/**
+ * 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 | VideoBlock | PlanBlock | TaskCardBlock;
+/**
+ * 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.
+     *
+     * 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[];
+    /**
+     * Block types to hide from the palette without rebuilding it. Each
+     * palette section is keyed by a `blockType`; any section whose
+     * `blockType` matches an entry here is filtered out before render.
+     * Convenient when you want the default palette minus a few block
+     * types (e.g. `disabledBlockTypes: ['image', 'table']` for a
+     * text-only builder). For finer-grained control (filtering
+     * individual variants, reordering, or adding custom presets), pass
+     * a custom `palette` array instead.
+     */
+    disabledBlockTypes?: readonly SupportedBlockType[];
+    /**
+     * 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;
+}
+
+export { type AlertBlock as A, type BlockKitchenProps as B, type CardBlock as C, type Template as D, buildVariantById as E, type FeedbackButtonSubobject as F, defaultPalette as G, type HeaderLevel as H, type IconButtonElement as I, extraAlertVariant as J, legacyInputVariants as K, type MarkdownBlock as M, type PaletteSection as P, type SendAsUserStatus as S, type TableBlock as T, type UrlSourceElement as U, type VideoBlock as V, type AlertLevel as a, type BrandPreset as b, type BrandTheme as c, type BrandTokens as d, type BuilderBlock as e, type CarouselBlock as f, type ChannelOption as g, type ContextActionsBlock as h, type ContextActionsElement as i, type FeedbackButtonsElement as j, type IconButtonIcon as k, type InputBlock as l, type PaletteVariant as m, type PlanBlock as n, type PreviewHooks as o, type PreviewSurface as p, type PreviewTheme as q, type SendPayload as r, type SendResult as s, type SupportedBlock as t, type SupportedBlockType as u, type SupportedHeaderBlock as v, type TableCell as w, type TableColumnSetting as x, type TaskCardBlock as y, type TaskCardStatus as z };