Update after #18405 api review

Author: almightyju

samples/ControlCatalog/Pages/ComboBoxPage.xaml

@@ -135,12 +135,14 @@
                     </ComboBox.ItemTemplate>
                 </ComboBox>
 
-              <StackPanel Spacing="10">
+              <StackPanel Spacing="5">
                 <ComboBox WrapSelection="{Binding WrapSelection}" PlaceholderText="Editable" 
                           ItemsSource="{Binding Values}" DisplayMemberBinding="{Binding Name}"
-                          IsEditable="True" Text="{Binding TextValue}" ItemTextBinding="{Binding Name}"
+                          IsEditable="True" Text="{Binding TextValue}"
+                          TextSearch.TextBinding="{Binding SearchText, DataType=viewModels:IdAndName}"
                           SelectedItem="{Binding SelectedItem}" />
 
+                <TextBlock Text="Editable text is bound to SearchText. Display is bound to Name" />
                 <TextBlock Text="{Binding TextValue, StringFormat=Text Value: {0}}" />
                 <TextBlock Text="{Binding SelectedItem.Name, StringFormat=Selected Item: {0}}" />
               </StackPanel>

src/Avalonia.Controls/ComboBox.cs

@@ -5,15 +5,14 @@
 using Avalonia.Controls.Primitives;
 using Avalonia.Controls.Shapes;
 using Avalonia.Controls.Templates;
+using Avalonia.Controls.Utils;
 using Avalonia.Data;
 using Avalonia.Input;
-using Avalonia.Interactivity;
 using Avalonia.Layout;
 using Avalonia.Media;
 using Avalonia.Metadata;
 using Avalonia.Reactive;
 using Avalonia.VisualTree;
-using static Avalonia.Controls.AutoCompleteBox;
 
 namespace Avalonia.Controls
 {
@@ -89,12 +88,6 @@ public class ComboBox : SelectingItemsControl
         public static readonly StyledProperty<string?> TextProperty =
             TextBlock.TextProperty.AddOwner<ComboBox>(new(string.Empty, BindingMode.TwoWay));
 
-        /// <summary>
-        /// Defines the <see cref="ItemTextBinding"/> property.
-        /// </summary>
-        public static readonly StyledProperty<IBinding?> ItemTextBindingProperty =
-            AvaloniaProperty.Register<ComboBox, IBinding?>(nameof(ItemTextBinding));
-
         /// <summary>
         /// Defines the <see cref="SelectionBoxItemTemplate"/> property.
         /// </summary>
@@ -118,7 +111,7 @@ public class ComboBox : SelectingItemsControl
 
         private bool _isEditable;
         private TextBox? _inputText;
-        private BindingEvaluator<string>? _textValueBindingEvaluator = null;
+        private BindingEvaluator<string?>? _textValueBindingEvaluator = null;
 
         /// <summary>
         /// Initializes static members of the <see cref="ComboBox"/> class.
@@ -129,7 +122,8 @@ static ComboBox()
             FocusableProperty.OverrideDefaultValue<ComboBox>(true);
             IsTextSearchEnabledProperty.OverrideDefaultValue<ComboBox>(true);
             TextProperty.Changed.AddClassHandler<ComboBox>((x, e) => x.TextChanged(e));
-            ItemTextBindingProperty.Changed.AddClassHandler<ComboBox>((x, e) => x.ItemTextBindingChanged(e));
+            DisplayMemberBindingProperty.Changed.AddClassHandler<ComboBox>((x, e) => x.DisplayMemberBindingChanged(e));
+            TextSearch.TextBindingProperty.Changed.AddClassHandler<ComboBox>((x, e) => x.ItemTextBindingChanged(e));
             //when the items change we need to simulate a text change to validate the text being an item or not and selecting it
             ItemsSourceProperty.Changed.AddClassHandler<ComboBox>((x, e) => x.TextChanged(
                 new AvaloniaPropertyChangedEventArgs<string?>(e.Sender, TextProperty, x.Text, x.Text, e.Priority)));
@@ -236,19 +230,6 @@ public string? Text
             set => SetValue(TextProperty, value);
         }
 
-        /// <summary>
-        /// Gets or sets the <see cref="T:Avalonia.Data.Binding" /> that
-        /// is used to get the text for editing of an item.
-        /// </summary>
-        /// <value>The <see cref="T:Avalonia.Data.IBinding" /> object used
-        /// when binding to a collection property.</value>
-        [AssignBinding, InheritDataTypeFromItems(nameof(ItemsSource), AncestorType = typeof(ComboBox))]
-        public IBinding? ItemTextBinding
-        {
-            get => GetValue(ItemTextBindingProperty);
-            set => SetValue(ItemTextBindingProperty, value);
-        }
-
         protected override void OnInitialized()
         {
             EnsureTextValueBinderOrThrow();
@@ -592,6 +573,9 @@ private void UpdateFlowDirection()
 
         private void UpdateInputTextFromSelection(object? item)
         {
+            //if we are modifying the text box which has deselected a value we don't want to update the textbox value
+            if (_skipNextTextChanged)
+                return;
             SetCurrentValue(TextProperty, GetItemTextValue(item));
         }
 
@@ -655,22 +639,43 @@ public void Clear()
             SelectedIndex = -1;
         }
 
-        private void ItemTextBindingChanged(AvaloniaPropertyChangedEventArgs e)
+        private void ItemTextBindingChanged(AvaloniaPropertyChangedEventArgs e) 
+            => HandleTextValueBindingValueChanged(e, null);
+
+        private void DisplayMemberBindingChanged(AvaloniaPropertyChangedEventArgs e)
+            => HandleTextValueBindingValueChanged(null, e);
+
+        private void HandleTextValueBindingValueChanged(AvaloniaPropertyChangedEventArgs? textSearchPropChange,
+            AvaloniaPropertyChangedEventArgs? displayMemberPropChange)
         {
-            _textValueBindingEvaluator = e.NewValue is IBinding binding
-                ? new(binding) : null;
+            IBinding? textValueBinding;
+            //prioritise using the TextSearch.TextBindingProperty if possible
+            if (textSearchPropChange == null && TextSearch.GetTextBinding(this) is IBinding textSearchBinding)
+                textValueBinding = textSearchBinding;
+
+            else if (textSearchPropChange != null && textSearchPropChange.NewValue is IBinding eventTextSearchBinding)
+                textValueBinding = eventTextSearchBinding;
+
+            else if (displayMemberPropChange != null && displayMemberPropChange.NewValue is IBinding eventDisplayMemberBinding)
+                textValueBinding = eventDisplayMemberBinding;
+
+            else
+                textValueBinding = null;
 
-            if(IsInitialized)
+            _textValueBindingEvaluator = BindingEvaluator<string?>.TryCreate(textValueBinding);
+            
+            if (IsInitialized)
                 EnsureTextValueBinderOrThrow();
 
-            if(_textValueBindingEvaluator != null)
+            //if the binding is set we want to set the initial value for the selected item so the text box has the correct value
+            if (_textValueBindingEvaluator != null)
                 _textValueBindingEvaluator.Value = GetItemTextValue(SelectedValue);
         }
 
         private void EnsureTextValueBinderOrThrow()
         {
             if (IsEditable && _textValueBindingEvaluator == null)
-                throw new InvalidOperationException($"When {nameof(ComboBox)}.{nameof(IsEditable)} is true you must set the text value binding using {nameof(ItemTextBinding)}");
+                throw new InvalidOperationException($"When {nameof(ComboBox)}.{nameof(IsEditable)} is true you must either set {nameof(ComboBox)}.{nameof(DisplayMemberBinding)} or set the text value binding using attached property {nameof(TextSearch)}.{nameof(TextSearch.TextBindingProperty)}");
         }
 
         private bool _skipNextTextChanged = false;
@@ -706,7 +711,7 @@ private string GetItemTextValue(object? item)
             if (_textValueBindingEvaluator == null)
                 return string.Empty;
 
-            return _textValueBindingEvaluator.GetDynamicValue(item) ?? item?.ToString() ?? string.Empty;
+            return TextSearch.GetEffectiveText(item, _textValueBindingEvaluator);
         }
     }
 }

src/Avalonia.Controls/Utils/BindingEvaluator.cs

@@ -19,6 +19,15 @@ internal sealed class BindingEvaluator<T> : StyledElement, IDisposable
     public static readonly StyledProperty<T> ValueProperty =
         AvaloniaProperty.Register<BindingEvaluator<T>, T>("Value");
 
+    /// <summary>
+    /// Gets or sets the data item value.
+    /// </summary>
+    public T Value
+    {
+        get => GetValue(ValueProperty);
+        set => SetValue(ValueProperty, value);
+    }
+
     public T Evaluate(object? dataContext)
     {
         // Only update the DataContext if necessary
@@ -49,6 +58,7 @@ public void Dispose()
         DataContext = null;
     }
 
+    [return: NotNullIfNotNull(nameof(binding))]
     public static BindingEvaluator<T>? TryCreate(IBinding? binding)
     {
         if (binding is null)