From f3f59bd5b20b856d25b1c9ea480c1cf2278ba124 Mon Sep 17 00:00:00 2001
From: Dong Bin <14807942+rabbitism@users.noreply.github.com>
Date: Mon, 9 Feb 2026 15:00:07 +0800
Subject: [PATCH] Implement PlaceholderText  (#727)

* feat: replace Watermark with PlaceholderText in AutoCompleteBox and related controls

* fix: remove duplicate PlaceholderForeground setter.
---
 .../Pages/AutoCompleteBoxDemo.axaml                | 14 +++++++-------
 .../Pages/NumericUpDownDemo.axaml                  |  6 +++---
 demo/Semi.Avalonia.Demo/Pages/TextBoxDemo.axaml    | 14 +++++++-------
 src/Semi.Avalonia/Controls/AutoCompleteBox.axaml   |  9 ++++++---
 .../Controls/CalendarDatePicker.axaml              |  6 ++++--
 src/Semi.Avalonia/Controls/ComboBox.axaml          |  2 +-
 .../Controls/ManagedFileChooser.axaml              |  2 +-
 src/Semi.Avalonia/Controls/NumericUpDown.axaml     |  4 +++-
 src/Semi.Avalonia/Controls/TextBox.axaml           | 13 +++++++++----
 src/Semi.Avalonia/Themes/Dark/TextBox.axaml        |  1 +
 .../Themes/HighContrast/TextBox.axaml              |  1 +
 src/Semi.Avalonia/Themes/Light/TextBox.axaml       |  1 +
 12 files changed, 44 insertions(+), 29 deletions(-)

diff --git a/demo/Semi.Avalonia.Demo/Pages/AutoCompleteBoxDemo.axaml b/demo/Semi.Avalonia.Demo/Pages/AutoCompleteBoxDemo.axaml
index 614efa4..f2afbb7 100644
--- a/demo/Semi.Avalonia.Demo/Pages/AutoCompleteBoxDemo.axaml
+++ b/demo/Semi.Avalonia.Demo/Pages/AutoCompleteBoxDemo.axaml
@@ -28,7 +28,7 @@
         </StackPanel.Styles>
 
         <AutoCompleteBox
-            Watermark="Please select a State"
+            PlaceholderText="Please select a State"
             ValueMemberBinding="{Binding Name,DataType=vm:StateData}" />
         <AutoCompleteBox
             Classes="Large"
@@ -41,7 +41,7 @@
             ValueMemberBinding="{Binding Name,DataType=vm:StateData}" />
         <AutoCompleteBox
             IsEnabled="False"
-            Watermark="Disabled"
+            PlaceholderText="Disabled"
             ValueMemberBinding="{Binding Name,DataType=vm:StateData}" />
         <AutoCompleteBox
             InnerLeftContent="https://"
@@ -52,16 +52,16 @@
             <AutoCompleteBox
                 Width="100"
                 Classes="Large"
-                Watermark="Large"
+                PlaceholderText="Large"
                 ValueMemberBinding="{Binding Name,DataType=vm:StateData}" />
             <AutoCompleteBox
                 Width="100"
-                Watermark="Default"
+                PlaceholderText="Default"
                 ValueMemberBinding="{Binding Name,DataType=vm:StateData}" />
             <AutoCompleteBox
                 Width="100"
                 Classes="Small"
-                Watermark="Small"
+                PlaceholderText="Small"
                 ValueMemberBinding="{Binding Name,DataType=vm:StateData}" />
         </StackPanel>
 
@@ -69,12 +69,12 @@
             <AutoCompleteBox
                 Width="100"
                 IsEnabled="False"
-                Watermark="Disabled"
+                PlaceholderText="Disabled"
                 ValueMemberBinding="{Binding Name,DataType=vm:StateData}" />
             <AutoCompleteBox
                 Width="100"
                 Classes="Bordered"
-                Watermark="Bordered"
+                PlaceholderText="Bordered"
                 ValueMemberBinding="{Binding Name,DataType=vm:StateData}" />
             <AutoCompleteBox
                 Width="100"
diff --git a/demo/Semi.Avalonia.Demo/Pages/NumericUpDownDemo.axaml b/demo/Semi.Avalonia.Demo/Pages/NumericUpDownDemo.axaml
index b249c23..8c4060b 100644
--- a/demo/Semi.Avalonia.Demo/Pages/NumericUpDownDemo.axaml
+++ b/demo/Semi.Avalonia.Demo/Pages/NumericUpDownDemo.axaml
@@ -28,15 +28,15 @@
             <NumericUpDown
                 Width="100"
                 Classes="Large"
-                Watermark="Large"
+                PlaceholderText="Large"
                 ButtonSpinnerLocation="Left" />
             <NumericUpDown
                 Width="100"
-                Watermark="Default"
+                PlaceholderText="Default"
                 ShowButtonSpinner="False" />
             <NumericUpDown
                 Width="100"
-                Watermark="Small"
+                PlaceholderText="Small"
                 Classes="Small" />
         </StackPanel>
 
diff --git a/demo/Semi.Avalonia.Demo/Pages/TextBoxDemo.axaml b/demo/Semi.Avalonia.Demo/Pages/TextBoxDemo.axaml
index 2ba6d0b..5fc0ae7 100644
--- a/demo/Semi.Avalonia.Demo/Pages/TextBoxDemo.axaml
+++ b/demo/Semi.Avalonia.Demo/Pages/TextBoxDemo.axaml
@@ -23,36 +23,36 @@
                 <TextBox
                     Width="100"
                     Classes="Large"
-                    Watermark="Large" />
+                    PlaceholderText="Large" />
                 <TextBox
                     Width="100"
-                    Watermark="Default" />
+                    PlaceholderText="Default" />
                 <TextBox
                     Width="100"
                     Classes="Small"
-                    Watermark="Small" />
+                    PlaceholderText="Small" />
             </StackPanel>
 
             <StackPanel Orientation="Horizontal">
                 <TextBox
                     Width="100"
                     IsEnabled="False"
-                    Watermark="Disabled" />
+                    PlaceholderText="Disabled" />
                 <TextBox
                     Width="100"
                     Classes="Bordered"
-                    Watermark="Bordered" />
+                    PlaceholderText="Bordered" />
                 <TextBox
                     Width="100"
                     Classes="Bordered"
                     IsEnabled="False" />
             </StackPanel>
-            <TextBox Width="300" Classes="TextArea" Watermark="TextArea TextBox" />
+            <TextBox Width="300" Classes="TextArea" PlaceholderText="TextArea TextBox" />
             <TextBox Width="300" Classes="TextArea ClearButton" Text="TextArea with ClearButton - text should be clearable" />
             <TextBox
                 Width="300"
                 Theme="{StaticResource LooklessTextBox}"
-                Watermark="Lookless TextBox"
+                PlaceholderText="Lookless TextBox"
                 InnerLeftContent="https://"
                 InnerRightContent=".com" />
         </StackPanel>
diff --git a/src/Semi.Avalonia/Controls/AutoCompleteBox.axaml b/src/Semi.Avalonia/Controls/AutoCompleteBox.axaml
index 3d0411c..391be3d 100644
--- a/src/Semi.Avalonia/Controls/AutoCompleteBox.axaml
+++ b/src/Semi.Avalonia/Controls/AutoCompleteBox.axaml
@@ -4,11 +4,12 @@
     <Design.PreviewWith>
         <StackPanel Margin="20" Spacing="20">
             <TextBox Text="Hello" />
-            <AutoCompleteBox Width="100" />
+            <AutoCompleteBox Width="100" PlaceholderText="Hello" />
         </StackPanel>
     </Design.PreviewWith>
     <ControlTheme x:Key="{x:Type AutoCompleteBox}" TargetType="AutoCompleteBox">
         <Setter Property="VerticalAlignment" Value="Center" />
+        <Setter Property="PlaceholderForeground" Value="{DynamicResource TextBoxPlaceholderForeground}" />
         <Setter Property="MinHeight" Value="{DynamicResource AutoCompleteBoxDefaultHeight}" />
         <Setter Property="MaxDropDownHeight" Value="{DynamicResource AutoCompleteMaxDropdownHeight}" />
         <Setter Property="Template">
@@ -23,7 +24,8 @@
                             Theme="{DynamicResource NonErrorTextBox}"
                             InnerLeftContent="{TemplateBinding InnerLeftContent}"
                             InnerRightContent="{TemplateBinding InnerRightContent}"
-                            Watermark="{TemplateBinding Watermark}" />
+                            PlaceholderForeground="{TemplateBinding PlaceholderForeground}"
+                            PlaceholderText="{TemplateBinding PlaceholderText}" />
                         <Popup
                             Name="PART_Popup"
                             MaxHeight="{TemplateBinding MaxDropDownHeight}"
@@ -63,7 +65,8 @@
                             MinHeight="0"
                             Classes="Bordered"
                             DataValidationErrors.Errors="{TemplateBinding (DataValidationErrors.Errors)}"
-                            Watermark="{TemplateBinding Watermark}" />
+                            PlaceholderForeground="{TemplateBinding PlaceholderForeground}"
+                            PlaceholderText="{TemplateBinding PlaceholderText}" />
                         <Popup
                             Name="PART_Popup"
                             MaxHeight="{TemplateBinding MaxDropDownHeight}"
diff --git a/src/Semi.Avalonia/Controls/CalendarDatePicker.axaml b/src/Semi.Avalonia/Controls/CalendarDatePicker.axaml
index 8ceb872..400cda2 100644
--- a/src/Semi.Avalonia/Controls/CalendarDatePicker.axaml
+++ b/src/Semi.Avalonia/Controls/CalendarDatePicker.axaml
@@ -9,6 +9,7 @@
     <ControlTheme x:Key="{x:Type CalendarDatePicker}" TargetType="CalendarDatePicker">
         <Setter Property="Background" Value="{DynamicResource CalendarDatePickerBackground}" />
         <Setter Property="Foreground" Value="{DynamicResource CalendarDatePickerForeground}" />
+        <Setter Property="PlaceholderForeground" Value="{DynamicResource TextBoxPlaceholderForeground}" />
         <Setter Property="BorderBrush" Value="{DynamicResource CalendarDatePickerBorderBrush}" />
         <Setter Property="BorderThickness" Value="{DynamicResource CalendarDatePickerBorderThickness}" />
         <Setter Property="CornerRadius" Value="{DynamicResource CalendarDatePickerCornerRadius}" />
@@ -52,8 +53,9 @@
                                 CornerRadius="{TemplateBinding CornerRadius}"
                                 Foreground="{TemplateBinding Foreground}"
                                 Theme="{DynamicResource NonErrorTextBox}"
-                                UseFloatingWatermark="{TemplateBinding UseFloatingWatermark}"
-                                Watermark="{TemplateBinding Watermark}">
+                                UseFloatingPlaceholder="{TemplateBinding UseFloatingPlaceholder}"
+                                PlaceholderForeground="{TemplateBinding PlaceholderForeground}"
+                                PlaceholderText="{TemplateBinding PlaceholderText}">
                                 <TextBox.Styles>
                                     <Style Selector="TextBox#PART_TextBox:pointerover /template/ Border#PART_ContentPresenterBorder">
                                         <!--  By default the TextBox has its own focused state, override this to disable it here  -->
diff --git a/src/Semi.Avalonia/Controls/ComboBox.axaml b/src/Semi.Avalonia/Controls/ComboBox.axaml
index 9ec3765..2616fb9 100644
--- a/src/Semi.Avalonia/Controls/ComboBox.axaml
+++ b/src/Semi.Avalonia/Controls/ComboBox.axaml
@@ -92,7 +92,7 @@
                             VerticalContentAlignment="{TemplateBinding VerticalContentAlignment}"
                             Foreground="{TemplateBinding Foreground}"
                             Text="{TemplateBinding Text, Mode=TwoWay}"
-                            Watermark="{TemplateBinding PlaceholderText}"
+                            PlaceholderText="{TemplateBinding PlaceholderText}"
                             IsVisible="{TemplateBinding IsEditable}" />
 
                         <Button
diff --git a/src/Semi.Avalonia/Controls/ManagedFileChooser.axaml b/src/Semi.Avalonia/Controls/ManagedFileChooser.axaml
index 93bd08d..40dbd9f 100644
--- a/src/Semi.Avalonia/Controls/ManagedFileChooser.axaml
+++ b/src/Semi.Avalonia/Controls/ManagedFileChooser.axaml
@@ -77,7 +77,7 @@
                             <TextBox
                                 IsVisible="{Binding !SelectingFolder}"
                                 Text="{Binding FileName}"
-                                Watermark="{DynamicResource STRING_CHOOSER_FILE_NAME}" />
+                                PlaceholderText="{DynamicResource STRING_CHOOSER_FILE_NAME}" />
                         </DockPanel>
                         <CheckBox
                             VerticalAlignment="Center"
diff --git a/src/Semi.Avalonia/Controls/NumericUpDown.axaml b/src/Semi.Avalonia/Controls/NumericUpDown.axaml
index 4686973..1908601 100644
--- a/src/Semi.Avalonia/Controls/NumericUpDown.axaml
+++ b/src/Semi.Avalonia/Controls/NumericUpDown.axaml
@@ -6,6 +6,7 @@
         <Setter Property="VerticalContentAlignment" Value="Center" />
         <Setter Property="CornerRadius" Value="{DynamicResource NumericUpDownCornerRadius}" />
         <Setter Property="MinHeight" Value="{DynamicResource NumericUpDownDefaultHeight}" />
+        <Setter Property="PlaceholderForeground" Value="{DynamicResource TextBoxPlaceholderForeground}" />
         <Setter Property="Template">
             <ControlTemplate TargetType="NumericUpDown">
                 <DataValidationErrors>
@@ -38,7 +39,8 @@
                             Theme="{DynamicResource NonErrorTextBox}"
                             InnerLeftContent="{TemplateBinding InnerLeftContent}"
                             InnerRightContent="{TemplateBinding InnerRightContent}"
-                            Watermark="{TemplateBinding Watermark}" />
+                            PlaceholderForeground="{TemplateBinding PlaceholderForeground}"
+                            PlaceholderText="{TemplateBinding PlaceholderText}" />
                     </ButtonSpinner>
                 </DataValidationErrors>
             </ControlTemplate>
diff --git a/src/Semi.Avalonia/Controls/TextBox.axaml b/src/Semi.Avalonia/Controls/TextBox.axaml
index b77b366..682a894 100644
--- a/src/Semi.Avalonia/Controls/TextBox.axaml
+++ b/src/Semi.Avalonia/Controls/TextBox.axaml
@@ -21,6 +21,7 @@
 
     <ControlTheme x:Key="{x:Type TextBox}" TargetType="TextBox">
         <Setter Property="Foreground" Value="{DynamicResource TextBoxForeground}" />
+        <Setter Property="PlaceholderForeground" Value="{DynamicResource TextBoxPlaceholderForeground}" />
         <Setter Property="Background" Value="{DynamicResource TextBoxDefaultBackground}" />
         <Setter Property="BorderBrush" Value="{DynamicResource TextBoxDefaultBorderBrush}" />
         <Setter Property="SelectionBrush" Value="{DynamicResource TextBoxSelectionBackground}" />
@@ -66,8 +67,8 @@
                                         Name="PART_Watermark"
                                         HorizontalAlignment="{TemplateBinding HorizontalContentAlignment}"
                                         VerticalAlignment="{TemplateBinding VerticalContentAlignment}"
-                                        Opacity="0.5"
-                                        Text="{TemplateBinding Watermark}"
+                                        Foreground="{TemplateBinding PlaceholderForeground}"
+                                        Text="{TemplateBinding PlaceholderText}"
                                         TextAlignment="{TemplateBinding TextAlignment}"
                                         TextWrapping="{TemplateBinding TextWrapping}">
                                         <TextBlock.IsVisible>
@@ -254,6 +255,7 @@
 
     <ControlTheme x:Key="NonErrorTextBox" TargetType="TextBox">
         <Setter Property="Foreground" Value="{DynamicResource TextBoxForeground}" />
+        <Setter Property="PlaceholderForeground" Value="{DynamicResource TextBoxPlaceholderForeground}" />
         <Setter Property="Background" Value="{DynamicResource TextBoxDefaultBackground}" />
         <Setter Property="BorderBrush" Value="{DynamicResource TextBoxDefaultBorderBrush}" />
         <Setter Property="SelectionBrush" Value="{DynamicResource TextBoxSelectionBackground}" />
@@ -300,7 +302,8 @@
                                         HorizontalAlignment="{TemplateBinding HorizontalContentAlignment}"
                                         VerticalAlignment="{TemplateBinding VerticalContentAlignment}"
                                         Opacity="0.5"
-                                        Text="{TemplateBinding Watermark}"
+                                        Foreground="{TemplateBinding PlaceholderForeground}"
+                                        Text="{TemplateBinding PlaceholderText}"
                                         TextAlignment="{TemplateBinding TextAlignment}"
                                         TextWrapping="{TemplateBinding TextWrapping}">
                                         <TextBlock.IsVisible>
@@ -487,6 +490,7 @@
 
     <ControlTheme x:Key="LooklessTextBox" TargetType="TextBox">
         <Setter Property="Foreground" Value="{DynamicResource TextBoxForeground}" />
+        <Setter Property="PlaceholderForeground" Value="{DynamicResource TextBoxPlaceholderForeground}" />
         <Setter Property="SelectionBrush" Value="{DynamicResource TextBoxSelectionBackground}" />
         <Setter Property="SelectionForegroundBrush" Value="{DynamicResource TextBoxSelectionForeground}" />
         <Setter Property="CaretBrush" Value="{DynamicResource TextBoxTextCaretBrush}" />
@@ -520,7 +524,8 @@
                                     HorizontalAlignment="{TemplateBinding HorizontalContentAlignment}"
                                     VerticalAlignment="{TemplateBinding VerticalContentAlignment}"
                                     Opacity="0.5"
-                                    Text="{TemplateBinding Watermark}"
+                                    Foreground="{TemplateBinding PlaceholderForeground}"
+                                    Text="{TemplateBinding PlaceholderText}"
                                     TextAlignment="{TemplateBinding TextAlignment}"
                                     TextWrapping="{TemplateBinding TextWrapping}">
                                     <TextBlock.IsVisible>
diff --git a/src/Semi.Avalonia/Themes/Dark/TextBox.axaml b/src/Semi.Avalonia/Themes/Dark/TextBox.axaml
index ed254e8..d6f1885 100644
--- a/src/Semi.Avalonia/Themes/Dark/TextBox.axaml
+++ b/src/Semi.Avalonia/Themes/Dark/TextBox.axaml
@@ -7,6 +7,7 @@
     <StaticResource x:Key="TextBoxPressedBackground" ResourceKey="SemiColorFill2" />
     <StaticResource x:Key="TextBoxFocusBorderBrush" ResourceKey="SemiColorPrimary" />
     <StaticResource x:Key="TextBoxForeground" ResourceKey="SemiColorText0" />
+    <StaticResource x:Key="TextBoxPlaceholderForeground" ResourceKey="SemiColorText2" />
     <StaticResource x:Key="TextBoxInnerForeground" ResourceKey="SemiColorText2" />
     <StaticResource x:Key="TextBoxDisabledBackground" ResourceKey="SemiColorDisabledFill" />
     <StaticResource x:Key="TextBoxDisabledForeground" ResourceKey="SemiColorDisabledText" />
diff --git a/src/Semi.Avalonia/Themes/HighContrast/TextBox.axaml b/src/Semi.Avalonia/Themes/HighContrast/TextBox.axaml
index fa68573..18f3a49 100644
--- a/src/Semi.Avalonia/Themes/HighContrast/TextBox.axaml
+++ b/src/Semi.Avalonia/Themes/HighContrast/TextBox.axaml
@@ -7,6 +7,7 @@
     <StaticResource x:Key="TextBoxPressedBackground" ResourceKey="SemiColorHighlightText" />
     <StaticResource x:Key="TextBoxFocusBorderBrush" ResourceKey="SemiColorHighlight" />
     <StaticResource x:Key="TextBoxForeground" ResourceKey="SemiColorWindowText" />
+    <StaticResource x:Key="TextBoxPlaceholderForeground" ResourceKey="SemiColorWindowText" />
     <StaticResource x:Key="TextBoxInnerForeground" ResourceKey="SemiColorWindowText" />
     <StaticResource x:Key="TextBoxDisabledBackground" ResourceKey="SemiColorWindow" />
     <StaticResource x:Key="TextBoxDisabledForeground" ResourceKey="SemiColorGrayText" />
diff --git a/src/Semi.Avalonia/Themes/Light/TextBox.axaml b/src/Semi.Avalonia/Themes/Light/TextBox.axaml
index d46e735..882f30d 100644
--- a/src/Semi.Avalonia/Themes/Light/TextBox.axaml
+++ b/src/Semi.Avalonia/Themes/Light/TextBox.axaml
@@ -7,6 +7,7 @@
     <StaticResource x:Key="TextBoxPressedBackground" ResourceKey="SemiColorFill2" />
     <StaticResource x:Key="TextBoxFocusBorderBrush" ResourceKey="SemiColorPrimary" />
     <StaticResource x:Key="TextBoxForeground" ResourceKey="SemiColorText0" />
+    <StaticResource x:Key="TextBoxPlaceholderForeground" ResourceKey="SemiColorText2" />
     <StaticResource x:Key="TextBoxInnerForeground" ResourceKey="SemiColorText2" />
     <StaticResource x:Key="TextBoxDisabledBackground" ResourceKey="SemiColorDisabledFill" />
     <StaticResource x:Key="TextBoxDisabledForeground" ResourceKey="SemiColorDisabledText" />