Merge pull request #4163 from CommunityToolkit/shweaver/token-selection-mode

Added support for limiting max tokens in TokenizingTextBox

Author: michael-hawker

Microsoft.Toolkit.Uwp.SampleApp/SamplePages/TokenizingTextBox/TokenizingTextBoxXaml.bind

@@ -30,16 +30,20 @@
       <RowDefinition/>
     </Grid.RowDefinitions>
     <StackPanel>
-      <TextBlock FontSize="32" Text="Select Actions"
-                 Margin="0,0,0,4"/>
+      <TextBlock FontSize="32" Margin="0,0,0,4">
+        <Run Text="Select up to" />
+        <Run Text="{Binding MaximumTokens, ElementName=TokenBox, Mode=OneWay}" />
+        <Run Text="actions" />
+      </TextBlock>
       <controls:TokenizingTextBox
           x:Name="TokenBox"
           PlaceholderText="Add Actions"
           QueryIcon="{ui:SymbolIconSource Symbol=Setting}"
           MaxHeight="104"
           HorizontalAlignment="Stretch"
           TextMemberPath="Text"
-          TokenDelimiter=",">
+          TokenDelimiter=","
+          MaximumTokens="3">
         <controls:TokenizingTextBox.SuggestedItemTemplate>
           <DataTemplate>
             <StackPanel Orientation="Horizontal">

Microsoft.Toolkit.Uwp.UI.Controls.Input/TokenizingTextBox/TokenizingTextBox.Properties.cs

@@ -157,6 +157,37 @@ private static void TextPropertyChanged(DependencyObject d, DependencyPropertyCh
             typeof(TokenizingTextBox),
             new PropertyMetadata(false));
 
+        /// <summary>
+        /// Identifies the <see cref="MaximumTokens"/> property.
+        /// </summary>
+        public static readonly DependencyProperty MaximumTokensProperty = DependencyProperty.Register(
+            nameof(MaximumTokens),
+            typeof(int),
+            typeof(TokenizingTextBox),
+            new PropertyMetadata(null, OnMaximumTokensChanged));
+
+        private static void OnMaximumTokensChanged(DependencyObject d, DependencyPropertyChangedEventArgs e)
+        {
+            if (d is TokenizingTextBox ttb && ttb.ReadLocalValue(MaximumTokensProperty) != DependencyProperty.UnsetValue && e.NewValue is int newMaxTokens)
+            {
+                var tokenCount = ttb._innerItemsSource.ItemsSource.Count;
+                if (tokenCount > 0 && tokenCount > newMaxTokens)
+                {
+                    int tokensToRemove = tokenCount - Math.Max(newMaxTokens, 0);
+
+                    // Start at the end, remove any extra tokens.
+                    for (var i = tokenCount; i > tokenCount - tokensToRemove; --i)
+                    {
+                        var token = ttb._innerItemsSource.ItemsSource[i - 1];
+
+                        // Force remove the items. No warning and no option to cancel.
+                        ttb._innerItemsSource.Remove(token);
+                        ttb.TokenItemRemoved?.Invoke(ttb, token);
+                    }
+                }
+            }
+        }
+
         /// <summary>
         /// Gets or sets the Style for the contained AutoSuggestBox template part.
         /// </summary>
@@ -303,5 +334,14 @@ public string SelectedTokenText
                 return PrepareSelectionForClipboard();
             }
         }
+
+        /// <summary>
+        /// Gets or sets the maximum number of token results allowed at a time.
+        /// </summary>
+        public int MaximumTokens
+        {
+            get => (int)GetValue(MaximumTokensProperty);
+            set => SetValue(MaximumTokensProperty, value);
+        }
     }
-}
+}

Microsoft.Toolkit.Uwp.UI.Controls.Input/TokenizingTextBox/TokenizingTextBox.cs

@@ -78,6 +78,17 @@ private void ItemsSource_PropertyChanged(DependencyObject sender, DependencyProp
             if (ItemsSource != null && ItemsSource.GetType() != typeof(InterspersedObservableCollection))
             {
                 _innerItemsSource = new InterspersedObservableCollection(ItemsSource);
+
+                if (ReadLocalValue(MaximumTokensProperty) != DependencyProperty.UnsetValue && _innerItemsSource.ItemsSource.Count >= MaximumTokens)
+                {
+                    // Reduce down to below the max as necessary.
+                    var endCount = MaximumTokens > 0 ? MaximumTokens : 0;
+                    for (var i = _innerItemsSource.ItemsSource.Count - 1; i >= endCount; --i)
+                    {
+                        _innerItemsSource.Remove(_innerItemsSource[i]);
+                    }
+                }
+
                 _currentTextEdit = _lastTextEdit = new PretokenStringContainer(true);
                 _innerItemsSource.Insert(_innerItemsSource.Count, _currentTextEdit);
                 ItemsSource = _innerItemsSource;
@@ -279,18 +290,16 @@ void WaitForLoad(object s, RoutedEventArgs eargs)
                 }
                 else
                 {
-                    // TODO: It looks like we're setting selection and focus together on items? Not sure if that's what we want...
-                    // If that's the case, don't think this code will ever be called?
-
-                    //// TODO: Behavior question: if no items selected (just focus) does it just go to our last active textbox?
-                    //// Community voted that typing in the end box made sense
-
+                    // If no items are selected, send input to the last active string container.
+                    // This code is only fires during an edgecase where an item is in the process of being deleted and the user inputs a character before the focus has been redirected to a string container.
                     if (_innerItemsSource[_innerItemsSource.Count - 1] is ITokenStringContainer textToken)
                     {
                         var last = ContainerFromIndex(Items.Count - 1) as TokenizingTextBoxItem; // Should be our last text box
-                        var position = last._autoSuggestTextBox.SelectionStart;
-                        textToken.Text = last._autoSuggestTextBox.Text.Substring(0, position) + args.Character +
-                                         last._autoSuggestTextBox.Text.Substring(position);
+                        var text = last._autoSuggestTextBox.Text;
+                        var selectionStart = last._autoSuggestTextBox.SelectionStart;
+                        var position = selectionStart > text.Length ? text.Length : selectionStart;
+                        textToken.Text = text.Substring(0, position) + args.Character +
+                                         text.Substring(position);
 
                         last._autoSuggestTextBox.SelectionStart = position + 1; // Set position to after our new character inserted
 
@@ -433,6 +442,12 @@ public async Task ClearAsync()
 
         internal async Task AddTokenAsync(object data, bool? atEnd = null)
         {
+            if (ReadLocalValue(MaximumTokensProperty) != DependencyProperty.UnsetValue && (MaximumTokens <= 0 || MaximumTokens <= _innerItemsSource.ItemsSource.Count))
+            {
+                // No tokens for you
+                return;
+            }
+
             if (data is string str && TokenItemAdding != null)
             {
                 var tiaea = new TokenItemAddingEventArgs(str);

Microsoft.Toolkit.Uwp.UI.Controls.Input/TokenizingTextBox/TokenizingTextBoxItem.AutoSuggestBox.cs

@@ -4,10 +4,12 @@
 
 using Windows.Foundation;
 using Windows.System;
+using Windows.UI;
 using Windows.UI.Xaml;
 using Windows.UI.Xaml.Controls;
 using Windows.UI.Xaml.Data;
 using Windows.UI.Xaml.Input;
+using Windows.UI.Xaml.Media;
 
 namespace Microsoft.Toolkit.Uwp.UI.Controls
 {
@@ -16,9 +18,11 @@ namespace Microsoft.Toolkit.Uwp.UI.Controls
     /// </summary>
     [System.Diagnostics.CodeAnalysis.SuppressMessage("StyleCop.CSharp.ReadabilityRules", "SA1124:Do not use regions", Justification = "Organization")]
     [TemplatePart(Name = PART_AutoSuggestBox, Type = typeof(AutoSuggestBox))] //// String case
+    [TemplatePart(Name = PART_TokensCounter, Type = typeof(TextBlock))]
     public partial class TokenizingTextBoxItem
     {
         private const string PART_AutoSuggestBox = "PART_AutoSuggestBox";
+        private const string PART_TokensCounter = "PART_TokensCounter";
 
         private AutoSuggestBox _autoSuggestBox;
 
@@ -231,6 +235,8 @@ private void AutoSuggestBox_GotFocus(object sender, RoutedEventArgs e)
         #region Inner TextBox
         private void OnASBLoaded(object sender, RoutedEventArgs e)
         {
+            UpdateTokensCounter(this);
+
             // Local function for Selection changed
             void AutoSuggestTextBox_SelectionChanged(object box, RoutedEventArgs args)
             {
@@ -329,6 +335,44 @@ private void AutoSuggestTextBox_PreviewKeyDown(object sender, KeyRoutedEventArgs
                 Owner.SelectAllTokensAndText();
             }
         }
+
+        private void UpdateTokensCounter(TokenizingTextBoxItem ttbi)
+        {
+            var maxTokensCounter = (TextBlock)_autoSuggestBox?.FindDescendant(PART_TokensCounter);
+            if (maxTokensCounter == null)
+            {
+                return;
+            }
+
+            void OnTokenCountChanged(TokenizingTextBox ttb, object value = null)
+            {
+                var itemsSource = ttb.ItemsSource as InterspersedObservableCollection;
+                var currentTokens = itemsSource.ItemsSource.Count;
+                var maxTokens = ttb.MaximumTokens;
+
+                maxTokensCounter.Text = $"{currentTokens}/{maxTokens}";
+                maxTokensCounter.Visibility = Visibility.Visible;
+
+                maxTokensCounter.Foreground = (currentTokens >= maxTokens)
+                    ? new SolidColorBrush(Colors.Red)
+                    : _autoSuggestBox.Foreground;
+            }
+
+            ttbi.Owner.TokenItemAdded -= OnTokenCountChanged;
+            ttbi.Owner.TokenItemRemoved -= OnTokenCountChanged;
+
+            if (Content is ITokenStringContainer str && str.IsLast && ttbi?.Owner != null && ttbi.Owner.ReadLocalValue(TokenizingTextBox.MaximumTokensProperty) != DependencyProperty.UnsetValue)
+            {
+                ttbi.Owner.TokenItemAdded += OnTokenCountChanged;
+                ttbi.Owner.TokenItemRemoved += OnTokenCountChanged;
+                OnTokenCountChanged(ttbi.Owner);
+            }
+            else
+            {
+                maxTokensCounter.Visibility = Visibility.Collapsed;
+                maxTokensCounter.Text = string.Empty;
+            }
+        }
         #endregion
     }
 }

Microsoft.Toolkit.Uwp.UI.Controls.Input/TokenizingTextBox/TokenizingTextBoxItem.AutoSuggestBox.xaml

@@ -137,6 +137,7 @@
                             <ColumnDefinition Width="*" />
                             <ColumnDefinition Width="Auto" />
                             <ColumnDefinition Width="Auto" />
+                            <ColumnDefinition Width="Auto" />
                         </Grid.ColumnDefinitions>
                         <Grid.RowDefinitions>
                             <RowDefinition Height="Auto" />
@@ -176,7 +177,7 @@
                                       ZoomMode="Disabled" />
                         <ContentControl x:Name="PlaceholderTextContentPresenter"
                                         Grid.Row="1"
-                                        Grid.ColumnSpan="3"
+                                        Grid.ColumnSpan="2"
                                         Margin="{TemplateBinding BorderThickness}"
                                         Padding="{TemplateBinding Padding}"
                                         Content="{TemplateBinding PlaceholderText}"
@@ -194,9 +195,15 @@
                                 IsTabStop="False"
                                 Style="{StaticResource TokenizingTextBoxDeleteButtonStyle}"
                                 Visibility="Collapsed" />
+
+                        <TextBlock Name="PART_TokensCounter"
+                                   Grid.Row="1"
+                                   Grid.Column="2" 
+                                   Margin="0,4,0,0" />
+
                         <Button x:Name="QueryButton"
                                 Grid.Row="1"
-                                Grid.Column="2"
+                                Grid.Column="3"
                                 Width="{TemplateBinding Height}"
                                 MinWidth="30"
                                 VerticalAlignment="Stretch"

Microsoft.Toolkit.Uwp.UI.Controls.Input/TokenizingTextBox/TokenizingTextBoxItem.cs

@@ -4,7 +4,6 @@
 
 using Windows.Foundation;
 using Windows.System;
-using Windows.UI.Core;
 using Windows.UI.Xaml;
 using Windows.UI.Xaml.Controls;
 using Windows.UI.Xaml.Controls.Primitives;

UnitTests/UnitTests.UWP/UI/Controls/Test_TokenizingTextBox_General.cs

@@ -63,5 +63,57 @@ public void Test_Clear()
 
             Assert.AreEqual(tokenBox.Items.Count, 5, "Cancelled Clear Failed ");
         }
+
+        [TestCategory("Test_TokenizingTextBox_General")]
+        [UITestMethod]
+        public void Test_MaximumTokens()
+        {
+            var maxTokens = 2;
+
+            var treeRoot = XamlReader.Load(
+$@"<Page
+    xmlns=""http://schemas.microsoft.com/winfx/2006/xaml/presentation""
+    xmlns:x=""http://schemas.microsoft.com/winfx/2006/xaml""
+    xmlns:controls=""using:Microsoft.Toolkit.Uwp.UI.Controls"">
+
+    <controls:TokenizingTextBox x:Name=""tokenboxname"" MaximumTokens=""{maxTokens}"">
+    </controls:TokenizingTextBox>
+
+</Page>") as FrameworkElement;
+
+            Assert.IsNotNull(treeRoot, "Could not load XAML tree.");
+
+            var tokenBox = treeRoot.FindChild("tokenboxname") as TokenizingTextBox;
+
+            Assert.IsNotNull(tokenBox, "Could not find TokenizingTextBox in tree.");
+
+            // Items includes the text fields as well, so we can expect at least one item to exist initially, the input box.
+            // Use the starting count as an offset.
+            var startingItemsCount = tokenBox.Items.Count;
+
+            // Add two items.
+            tokenBox.AddTokenItem("TokenItem1");
+            tokenBox.AddTokenItem("TokenItem2");
+
+            // Make sure we have the appropriate amount of items and that they are in the appropriate order.
+            Assert.AreEqual(startingItemsCount + maxTokens, tokenBox.Items.Count, "Token Add failed");
+            Assert.AreEqual("TokenItem1", tokenBox.Items[0]);
+            Assert.AreEqual("TokenItem2", tokenBox.Items[1]);
+
+            // Attempt to add an additional item, beyond the maximum.
+            tokenBox.AddTokenItem("TokenItem3");
+
+            // Check that the number of items did not change, because the maximum number of items are already present.
+            Assert.AreEqual(startingItemsCount + maxTokens, tokenBox.Items.Count, "Token Add succeeded, where it should have failed.");
+            Assert.AreEqual("TokenItem1", tokenBox.Items[0]);
+            Assert.AreEqual("TokenItem2", tokenBox.Items[1]);
+
+            // Reduce the maximum number of tokens.
+            tokenBox.MaximumTokens = 1;
+
+            // The last token should be removed to account for the reduced maximum.
+            Assert.AreEqual(startingItemsCount + 1, tokenBox.Items.Count);
+            Assert.AreEqual("TokenItem1", tokenBox.Items[0]);
+        }
     }
 }