From b6b7a97bdba2dce82fb38d059837b1b42322f48f Mon Sep 17 00:00:00 2001
From: Vedanshu <vedanshu@urumi.ai>
Date: Wed, 29 Jul 2026 23:05:23 +0000
Subject: [PATCH] fix(blocks): render the option label in a select trigger

Block Kit's select passed its options only as children, so Kumo had no
value-to-label map to hand Base UI. The trigger serialized the raw value,
and rendered nothing at all when the value was "", null or absent, since
Base UI counts an empty string as "no value".

Pass the options as `items` too, which is the documented way to make the
selected value render as a label, and add an optional `placeholder` for
the unselected state, mirroring Kumo's own prop. The placeholder defaults
to the label of an option whose value is "" -- the usual "All ..." filter
entry, which Base UI would otherwise hide behind the placeholder -- and
to "Select..." when there is none.

The popup still renders the same children, so option order, keys and the
submitted values are unchanged.
---
 .changeset/fix-block-kit-select-label.md      |   5 +
 .../plugins/creating-plugins/block-kit.mdx    |   6 +-
 packages/blocks/src/builders.ts               |   3 +-
 packages/blocks/src/elements/select.tsx       |  14 ++
 packages/blocks/src/types.ts                  |   5 +
 packages/blocks/src/validation.ts             |   6 +
 packages/blocks/tests/select-element.test.tsx | 137 ++++++++++++++++++
 packages/blocks/tests/validation.test.ts      |  19 +++
 .../creating-plugins/references/block-kit.md  |   6 +-
 9 files changed, 198 insertions(+), 3 deletions(-)
 create mode 100644 .changeset/fix-block-kit-select-label.md
 create mode 100644 packages/blocks/tests/select-element.test.tsx

diff --git a/.changeset/fix-block-kit-select-label.md b/.changeset/fix-block-kit-select-label.md
new file mode 100644
index 0000000000..309295e00e
--- /dev/null
+++ b/.changeset/fix-block-kit-select-label.md
@@ -0,0 +1,5 @@
+---
+"@emdash-cms/blocks": patch
+---
+
+Fixes Block Kit `select` fields displaying the raw option value — or nothing at all — instead of the selected option's label. Adds an optional `placeholder` for the unselected state, defaulting to the label of an option whose `value` is `""` and otherwise to `Select...`. Submitted values are unchanged.
diff --git a/docs/src/content/docs/plugins/creating-plugins/block-kit.mdx b/docs/src/content/docs/plugins/creating-plugins/block-kit.mdx
index 79ffd1a0bd..c23d1de00f 100644
--- a/docs/src/content/docs/plugins/creating-plugins/block-kit.mdx
+++ b/docs/src/content/docs/plugins/creating-plugins/block-kit.mdx
@@ -99,10 +99,14 @@ The route handler takes two arguments: `routeCtx` (with `input`, `request`, `req
 | `button`        | Action button with optional confirmation dialog |
 | `text_input`    | Single-line or multiline text input          |
 | `number_input`  | Numeric input with min/max                   |
-| `select`        | Dropdown select                              |
+| `select`        | Dropdown select with optional `placeholder`  |
 | `toggle`        | On/off switch                                |
 | `secret_input`  | Masked input for API keys and tokens         |
 
+A `select` renders the label of the selected option. When nothing is selected it renders its
+`placeholder`, which defaults to the label of an option whose `value` is `""` (the usual "All"
+entry) and otherwise to `Select...`.
+
 ## Builder helpers
 
 The `@emdash-cms/blocks` package exports builder helpers for cleaner code:
diff --git a/packages/blocks/src/builders.ts b/packages/blocks/src/builders.ts
index ce71b2d027..21260c9206 100644
--- a/packages/blocks/src/builders.ts
+++ b/packages/blocks/src/builders.ts
@@ -210,7 +210,7 @@ function select(
 	actionId: string,
 	label: string,
 	options: Array<{ label: string; value: string }>,
-	opts?: { initialValue?: string },
+	opts?: { initialValue?: string; placeholder?: string },
 ): SelectElement {
 	return {
 		type: "select",
@@ -220,6 +220,7 @@ function select(
 		...(opts?.initialValue !== undefined && {
 			initial_value: opts.initialValue,
 		}),
+		...(opts?.placeholder !== undefined && { placeholder: opts.placeholder }),
 	};
 }
 
diff --git a/packages/blocks/src/elements/select.tsx b/packages/blocks/src/elements/select.tsx
index 36cf63796e..3489d44666 100644
--- a/packages/blocks/src/elements/select.tsx
+++ b/packages/blocks/src/elements/select.tsx
@@ -3,6 +3,8 @@ import { useCallback } from "react";
 
 import type { BlockInteraction, SelectElement } from "../types.js";
 
+const DEFAULT_PLACEHOLDER = "Select...";
+
 export function SelectElementComponent({
 	element,
 	onAction,
@@ -27,9 +29,21 @@ export function SelectElementComponent({
 		[onChange, onAction, element.action_id],
 	);
 
+	// An empty-string value counts as "no value" to the underlying Select, which
+	// then shows the placeholder. An option declaring `value: ""` *is* that empty
+	// state, so its label is the placeholder text unless the element sets one.
+	const placeholder =
+		element.placeholder ??
+		element.options.find((opt) => opt.value === "")?.label ??
+		DEFAULT_PLACEHOLDER;
+
+	// `items` is what the trigger resolves its label from; without it the trigger
+	// renders the raw selected value. The children still render the popup.
 	return (
 		<Select
 			label={element.label}
+			items={element.options}
+			placeholder={placeholder}
 			defaultValue={element.initial_value}
 			onValueChange={handleValueChange}
 		>
diff --git a/packages/blocks/src/types.ts b/packages/blocks/src/types.ts
index 5105a9734b..b4936483fc 100644
--- a/packages/blocks/src/types.ts
+++ b/packages/blocks/src/types.ts
@@ -43,6 +43,11 @@ export interface SelectElement {
 	label: string;
 	options: Array<{ label: string; value: string }>;
 	initial_value?: string;
+	/**
+	 * Text shown in the trigger when nothing is selected. Defaults to the label of
+	 * an option whose `value` is `""`, or `"Select..."`.
+	 */
+	placeholder?: string;
 	/** Plugin route that returns `{ items: Array<{ id, name }> }` to populate options dynamically */
 	optionsRoute?: string;
 }
diff --git a/packages/blocks/src/validation.ts b/packages/blocks/src/validation.ts
index 9f39163b74..f0cbec59f5 100644
--- a/packages/blocks/src/validation.ts
+++ b/packages/blocks/src/validation.ts
@@ -269,6 +269,12 @@ function validateElement(value: unknown, path: string, errors: ValidationError[]
 			if (value.initial_value !== undefined) {
 				validateInitialValueInOptions(value.initial_value, selectValidValues, path, errors);
 			}
+			if (value.placeholder !== undefined && typeof value.placeholder !== "string") {
+				errors.push({
+					path: `${path}.placeholder`,
+					message: "Field 'placeholder' must be a string",
+				});
+			}
 			break;
 		}
 		case "toggle": {
diff --git a/packages/blocks/tests/select-element.test.tsx b/packages/blocks/tests/select-element.test.tsx
new file mode 100644
index 0000000000..bd15ee5b67
--- /dev/null
+++ b/packages/blocks/tests/select-element.test.tsx
@@ -0,0 +1,137 @@
+import { cleanup, fireEvent, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { SelectElementComponent } from "../src/elements/select.js";
+import type { SelectElement } from "../src/types.js";
+
+// Deliberately not mocking @cloudflare/kumo: the trigger label and the empty
+// state come out of the real Select, so a mock would assert nothing.
+
+afterEach(cleanup);
+
+const OPTIONS = [
+	{ label: "Published", value: "pub_1" },
+	{ label: "Draft", value: "dft_2" },
+];
+
+function renderSelect(element: Partial<SelectElement>) {
+	const onAction = vi.fn();
+	const onChange = vi.fn();
+	render(
+		<SelectElementComponent
+			element={{
+				type: "select",
+				action_id: "status",
+				label: "Status",
+				options: OPTIONS,
+				...element,
+			}}
+			onAction={onAction}
+			onChange={onChange}
+		/>,
+	);
+	return { onAction, onChange };
+}
+
+function trigger() {
+	return screen.getByRole("combobox");
+}
+
+/** Base UI only commits a click that follows a pointer press on the option. */
+function pick(name: string) {
+	fireEvent.click(trigger());
+	const option = screen.getByRole("option", { name });
+	fireEvent.pointerDown(option);
+	fireEvent.click(option);
+}
+
+describe("select element", () => {
+	it("renders the label of the selected option, not its value", () => {
+		renderSelect({ initial_value: "pub_1" });
+
+		expect(trigger().textContent).toContain("Published");
+		expect(trigger().textContent).not.toContain("pub_1");
+	});
+
+	it("renders the label of the option picked by the user", () => {
+		renderSelect({ initial_value: "pub_1" });
+
+		pick("Draft");
+
+		expect(trigger().textContent).toContain("Draft");
+		expect(trigger().textContent).not.toContain("dft_2");
+	});
+
+	it("renders a placeholder when nothing is selected", () => {
+		renderSelect({ placeholder: "Any status" });
+
+		expect(trigger().textContent).toContain("Any status");
+	});
+
+	it("renders a default placeholder when the element has none", () => {
+		renderSelect({});
+
+		expect(trigger().textContent).toContain("Select...");
+	});
+
+	it("renders the label of an empty-value option as the empty state", () => {
+		renderSelect({
+			options: [{ label: "All statuses", value: "" }, ...OPTIONS],
+			initial_value: "",
+		});
+
+		expect(trigger().textContent).toContain("All statuses");
+	});
+
+	it("prefers an explicit placeholder over an empty-value option's label", () => {
+		renderSelect({
+			options: [{ label: "All statuses", value: "" }, ...OPTIONS],
+			initial_value: "",
+			placeholder: "Filter by status",
+		});
+
+		expect(trigger().textContent).toContain("Filter by status");
+	});
+
+	it("submits the option value unchanged", () => {
+		const { onChange } = renderSelect({ initial_value: "pub_1" });
+
+		pick("Draft");
+
+		expect(onChange).toHaveBeenCalledWith("status", "dft_2");
+	});
+
+	it("submits an empty-string option value unchanged", () => {
+		const { onChange } = renderSelect({
+			options: [{ label: "All statuses", value: "" }, ...OPTIONS],
+			initial_value: "pub_1",
+		});
+
+		pick("All statuses");
+
+		expect(onChange).toHaveBeenCalledWith("status", "");
+	});
+
+	it("reports the value through onAction when no onChange is given", () => {
+		const onAction = vi.fn();
+		render(
+			<SelectElementComponent
+				element={{
+					type: "select",
+					action_id: "status",
+					label: "Status",
+					options: OPTIONS,
+				}}
+				onAction={onAction}
+			/>,
+		);
+
+		pick("Draft");
+
+		expect(onAction).toHaveBeenCalledWith({
+			type: "block_action",
+			action_id: "status",
+			value: "dft_2",
+		});
+	});
+});
diff --git a/packages/blocks/tests/validation.test.ts b/packages/blocks/tests/validation.test.ts
index e5ac96e162..b2850412aa 100644
--- a/packages/blocks/tests/validation.test.ts
+++ b/packages/blocks/tests/validation.test.ts
@@ -335,6 +335,25 @@ describe("validateBlocks", () => {
 			expect(result.errors[0]!.message).toContain("must not be empty");
 		});
 
+		it("select with non-string placeholder", () => {
+			const result = validateBlocks([
+				{
+					type: "actions",
+					elements: [
+						{
+							type: "select",
+							action_id: "sel",
+							label: "Pick",
+							options: [{ label: "One", value: "1" }],
+							placeholder: 42,
+						},
+					],
+				},
+			]);
+			expect(result.valid).toBe(false);
+			expect(result.errors[0]!.path).toBe("blocks[0].elements[0].placeholder");
+		});
+
 		it("select option missing label/value", () => {
 			const result = validateBlocks([
 				{
diff --git a/skills/creating-plugins/references/block-kit.md b/skills/creating-plugins/references/block-kit.md
index 8f3f3cebf2..f3f892e7c0 100644
--- a/skills/creating-plugins/references/block-kit.md
+++ b/skills/creating-plugins/references/block-kit.md
@@ -83,7 +83,7 @@ routes: {
 | `button`       | Action button with optional confirmation dialog |
 | `text_input`   | Single-line or multiline text input             |
 | `number_input` | Numeric input with min/max                      |
-| `select`       | Dropdown select                                 |
+| `select`       | Dropdown select with optional `placeholder`     |
 | `toggle`       | On/off switch                                   |
 | `secret_input` | Masked input for API keys and tokens            |
 | `checkbox`     | Multi-select checkboxes                         |
@@ -91,6 +91,10 @@ routes: {
 | `date_input`   | Date picker                                     |
 | `combobox`     | Searchable dropdown select                      |
 
+A `select` renders the label of the selected option. When nothing is selected it renders its
+`placeholder`, which defaults to the label of an option whose `value` is `""` (the usual "All"
+entry) and otherwise to `Select...`.
+
 ## Block Syntax
 
 ### Header