From 2a1791e6e9b1a0ac4838939a31809c8eec14f851 Mon Sep 17 00:00:00 2001
From: Uzair <uzair@writer.com>
Date: Fri, 21 Nov 2025 01:38:58 +0000
Subject: [PATCH] feat(ui): enhance WdsSelect and BuilderFieldsText components
 with dropdown support and placeholder options

- Added WdsSelect component with dropdown functionality and placeholder handling.
- Updated BuilderFieldsText to conditionally render WdsSelect based on input type.
- Introduced isPlaceholder property in WdsDropdownMenu for better UI representation.
- Enhanced styling for placeholder items in WdsDropdownMenuItem.
- Updated changepage.py to include pageKeys as options for the target page key.
---
 .../builder/settings/BuilderFieldsText.vue    |  58 ++++++-
 src/ui/src/wds/WdsDropdownMenu.vue            |   1 +
 src/ui/src/wds/WdsDropdownMenuItem.vue        |   7 +
 src/ui/src/wds/WdsSelect.vue                  | 141 +++++++++++++++---
 src/writer/blocks/changepage.py               |   1 +
 5 files changed, 185 insertions(+), 23 deletions(-)

diff --git a/src/ui/src/builder/settings/BuilderFieldsText.vue b/src/ui/src/builder/settings/BuilderFieldsText.vue
index b1f738f24..dd0e5185b 100644
--- a/src/ui/src/builder/settings/BuilderFieldsText.vue
+++ b/src/ui/src/builder/settings/BuilderFieldsText.vue
@@ -1,7 +1,16 @@
 <template>
 	<div class="BuilderFieldsText" :data-automation-key="props.fieldKey">
 		<template v-if="fieldControl == FieldControl.Text">
+			<WdsSelect
+				v-if="shouldUseDropdown"
+				v-model="selectValue"
+				class="content"
+				:options="selectOptions"
+				:placeholder="defaultValue"
+				default-icon=""
+			/>
 			<BuilderTemplateInput
+				v-else
 				class="content"
 				:component-id="componentId"
 				:input-id="inputId"
@@ -38,6 +47,12 @@ import { Component, FieldControl } from "@/writerTypes";
 import { useComponentFieldViewModel } from "../useComponentFieldViewModel";
 import injectionKeys from "@/injectionKeys";
 import BuilderTemplateInput from "./BuilderTemplateInput.vue";
+import { defineAsyncComponentWithLoader } from "@/utils/defineAsyncComponentWithLoader";
+import type { Option } from "@/wds/WdsSelect.vue";
+
+const WdsSelect = defineAsyncComponentWithLoader({
+	loader: () => import("@/wds/WdsSelect.vue"),
+});
 
 const wf = inject(injectionKeys.core);
 
@@ -78,6 +93,24 @@ const predefinedOptionFns = {
 		});
 		return options;
 	},
+	pageKeys: () => {
+		const pages = wf
+			.getComponents("root", { sortedByPosition: true })
+			.filter((component) => component.type === "page");
+		return pages.reduce((acc, page) => {
+			const key = page.content?.["key"];
+			if (!key) {
+				return acc;
+			}
+			const label =
+				page.content?.["title"] ??
+				page.content?.["name"] ??
+				key ??
+				page.id;
+			acc[key] = label;
+			return acc;
+		}, {});
+	},
 	uiComponentsWithEvents: () => {
 		return wf
 			.getComponents(undefined, { sortedByPosition: true })
@@ -101,7 +134,7 @@ const predefinedOptionFns = {
 	},
 };
 
-const options = computed(() => {
+const options = computed<Record<string, string>>(() => {
 	const component = wf.getComponentById(props.componentId);
 	const componentDefinition = wf.getComponentDefinition(component.type);
 	const field = componentDefinition.fields[props.fieldKey];
@@ -116,12 +149,35 @@ const options = computed(() => {
 	return field.options;
 });
 
+const selectOptions = computed<Option[]>(() =>
+	Object.entries(options.value ?? {}).map(([value, label]) => ({
+		value,
+		label,
+	})),
+);
+
+const shouldUseDropdown = computed(
+	() => props.type === "template" && selectOptions.value.length > 0,
+);
+
 const inputType = computed(() =>
 	["state", "state-template"].includes(props.type) ? "state" : "template",
 );
 
 const inputValue = computed(() => parseContentValue(fieldViewModel.value));
 
+const selectValue = computed<string | undefined>({
+	get: () => {
+		const value = inputValue.value;
+		return selectOptions.value.some((option) => option.value === value)
+			? value
+			: undefined;
+	},
+	set(value) {
+		fieldViewModel.value = transformToContentValue(value ?? "");
+	},
+});
+
 const handleInput = (ev: Event) => {
 	fieldViewModel.value = transformToContentValue(
 		(ev.target as HTMLInputElement).value,
diff --git a/src/ui/src/wds/WdsDropdownMenu.vue b/src/ui/src/wds/WdsDropdownMenu.vue
index e50086385..ec33cadb9 100644
--- a/src/ui/src/wds/WdsDropdownMenu.vue
+++ b/src/ui/src/wds/WdsDropdownMenu.vue
@@ -89,6 +89,7 @@ export type WdsDropdownMenuOption = {
 	label: string;
 	detail?: string;
 	shortcut?: string;
+	isPlaceholder?: boolean;
 	/**
 	 * A font icon or an array of image URL
 	 */
diff --git a/src/ui/src/wds/WdsDropdownMenuItem.vue b/src/ui/src/wds/WdsDropdownMenuItem.vue
index edb1e1e99..d99427799 100644
--- a/src/ui/src/wds/WdsDropdownMenuItem.vue
+++ b/src/ui/src/wds/WdsDropdownMenuItem.vue
@@ -49,6 +49,7 @@ const iconStyle = computed(() => {
 			'WdsDropdownMenuItem--selected': selected,
 			'WdsDropdownMenuItem--hideIcon': hideIcons,
 			'WdsDropdownMenuItem--danger': option.variant === 'danger',
+			'WdsDropdownMenuItem--placeholder': option.isPlaceholder,
 		}"
 		:style
 		:data-automation-key="option.value"
@@ -153,6 +154,12 @@ const iconStyle = computed(() => {
 .WdsDropdownMenuItem--danger {
 	color: var(--wdsColorOrange5);
 }
+.WdsDropdownMenuItem--placeholder {
+	color: var(--wdsColorGray4);
+}
+.WdsDropdownMenuItem--placeholder .WdsDropdownMenuItem__detail {
+	color: var(--wdsColorGray3);
+}
 
 .WdsDropdownMenuItem__detail,
 .WdsDropdownMenuItem__label,
diff --git a/src/ui/src/wds/WdsSelect.vue b/src/ui/src/wds/WdsSelect.vue
index 11c6eeea6..510e93b8a 100644
--- a/src/ui/src/wds/WdsSelect.vue
+++ b/src/ui/src/wds/WdsSelect.vue
@@ -3,6 +3,9 @@
 		<!-- use a `<div>` instead of button because Firefox has an issue with draggable `<button>` https://bugzilla.mozilla.org/show_bug.cgi?id=568313 -->
 		<div
 			class="WdsSelect__trigger"
+			:class="{
+				'WdsSelect__trigger--placeholder': isPlaceholderSelected,
+			}"
 			role="button"
 			tabindex="0"
 			@click="isOpen = !isOpen"
@@ -34,10 +37,10 @@
 					@close="handleRemoveValue(option.value)"
 				/>
 				<p
-					v-if="selectedOptions.length === 0 && placeholder"
+					v-if="selectedOptions.length === 0"
 					class="WdsSelect__trigger__multiSelectLabel__placeholder"
 				>
-					{{ placeholder }}
+					{{ placeholderLabel }}
 				</p>
 			</div>
 			<div
@@ -46,7 +49,7 @@
 				data-writer-tooltip-strategy="overflow"
 				:data-writer-tooltip="currentLabel"
 			>
-				{{ currentLabel ?? placeholder }}
+				{{ currentLabel ?? placeholderLabel }}
 			</div>
 			<div class="WdsSelect__trigger__arrow">
 				<WdsIcon :name="isOpen ? 'chevron-up' : 'chevron-down'" />
@@ -60,7 +63,7 @@
 				:enable-multi-selection="enableMultiSelection"
 				:hide-icons="hideIcons"
 				:loading="loading"
-				:options="options"
+				:options="selectOptions"
 				:selected="currentValue"
 				:style="floatingStyles"
 				@select="onSelect"
@@ -102,6 +105,7 @@ const props = defineProps({
 	enableSearch: { type: Boolean, required: false },
 	enableMultiSelection: { type: Boolean, required: false },
 	loading: { type: Boolean, required: false },
+	required: { type: Boolean, required: false, default: false },
 });
 
 const currentValue = defineModel({
@@ -129,35 +133,84 @@ const { floatingStyles, update: updateFloatingStyle } = useFloating(
 	},
 );
 
+const PLACEHOLDER_VALUE = "";
+const placeholderLabel = computed(
+	() => props.placeholder ?? "Select an option...",
+);
+
+const shouldInjectPlaceholder = computed(
+	() => !props.required && !props.enableMultiSelection,
+);
+
+const selectOptions = computed<WdsDropdownMenuOption[]>(() => {
+	const normalized = (props.options ?? []).map((option) => ({
+		...option,
+		label:
+			option.label ??
+			(option.value !== undefined ? String(option.value) : ""),
+	}));
+
+	const hasEmptyValueOption = normalized.some(
+		(option) => option.value === PLACEHOLDER_VALUE,
+	);
+
+	const shouldAddPlaceholder =
+		shouldInjectPlaceholder.value && !hasEmptyValueOption;
+
+	if (!shouldAddPlaceholder) {
+		return normalized;
+	}
+
+	return [
+		{
+			value: PLACEHOLDER_VALUE,
+			label: placeholderLabel.value,
+			isPlaceholder: true,
+		},
+		...normalized.filter((option) => !option.isPlaceholder),
+	];
+});
+
 const currentValueArray = computed(() => {
-	if (!currentValue.value) return [];
-	const array = Array.isArray(currentValue.value)
-		? currentValue.value
-		: [currentValue.value];
-	return array.filter(Boolean);
+	const value = currentValue.value;
+	if (value === undefined || value === null) return [];
+	const array = Array.isArray(value) ? value : [value];
+	return array.filter((v) => v !== undefined && v !== null) as string[];
 });
 
+function findOption(value: string | undefined) {
+	if (value === undefined) return undefined;
+	return selectOptions.value.find((option) => option.value === value);
+}
+
 const selectedOptions = computed<WdsDropdownMenuOption[]>(() =>
 	currentValueArray.value.map(
-		(v) =>
-			props.options.find((o) => o.value === v) ?? { value: v, label: v },
+		(value) =>
+			findOption(value) ?? {
+				value,
+				label: String(value),
+			},
 	),
 );
 
-const hasUnknowOptionSelected = computed(() => {
-	return (
-		currentValue.value &&
-		!props.options.some((o) => o.value === currentValue.value)
-	);
-});
+const hasUnknowOptionSelected = computed(() =>
+	currentValueArray.value.some((value) => !findOption(value)),
+);
 
 const currentLabel = computed(() => {
-	if (hasUnknowOptionSelected.value) return String(currentValue.value);
+	if (hasUnknowOptionSelected.value) {
+		return Array.isArray(currentValue.value)
+			? currentValue.value.filter(Boolean).join(" / ")
+			: String(currentValue.value ?? "");
+	}
+
+	const labels = selectedOptions.value.map((o) => o.label).filter(Boolean);
+	if (!labels.length) return undefined;
 
-	return selectedOptions.value
-		.map((o) => o.label)
-		.sort()
-		.join(" / ");
+	const sortedLabels = [...labels].sort((a, b) => a.localeCompare(b));
+	return props.enableMultiSelection
+		? sortedLabels.join(" / ")
+		: sortedLabels[0];
 });
 
 const currentIcon = computed(() => {
@@ -170,6 +223,47 @@ const currentIcon = computed(() => {
 	);
 });
 
+const isPlaceholderSelected = computed(() => {
+	if (props.enableMultiSelection || props.required) return false;
+	return findOption(
+		typeof currentValue.value === "string" ? currentValue.value : undefined,
+	)?.isPlaceholder;
+});
+
+watch(
+	[
+		selectOptions,
+		() => props.required,
+		() => props.enableMultiSelection,
+		() => currentValue.value,
+	],
+	ensureValidSelection,
+	{ immediate: true },
+);
+
+function ensureValidSelection() {
+	if (props.enableMultiSelection) return;
+
+	const options = selectOptions.value;
+	if (!options.length) return;
+
+	const current = currentValue.value;
+	const asString = typeof current === "string" ? current : undefined;
+	const hasCurrentSelection =
+		asString !== undefined && Boolean(findOption(asString));
+
+	if (props.required) {
+		if (!hasCurrentSelection || asString === "") {
+			currentValue.value = options[0].value;
+		}
+		return;
+	}
+
+	if (!hasCurrentSelection) {
+		currentValue.value = PLACEHOLDER_VALUE;
+	}
+}
+
 // close the dropdown when clicking outside
 const hasFocus = useFocusWithin(trigger);
 watch(
@@ -244,6 +338,9 @@ function handleRemoveValue(value: string) {
 	font-weight: 300;
 	cursor: pointer;
 }
+.WdsSelect__trigger--placeholder .WdsSelect__trigger__label {
+	color: var(--wdsColorGray4);
+}
 
 .WdsSelect__trigger__multiSelectLabel {
 	flex-grow: 1;
diff --git a/src/writer/blocks/changepage.py b/src/writer/blocks/changepage.py
index e381ddc7f..bff7e28cd 100644
--- a/src/writer/blocks/changepage.py
+++ b/src/writer/blocks/changepage.py
@@ -20,6 +20,7 @@ def register(cls, type: str):
                             "name": "Page key",
                             "type": "Text",
                             "desc": "The identifying key of the target page.",
+                            "options": "pageKeys",
                         },
                     },
                     "outs": {