Fixes #4027. Add collection search matcher (#4029)

* Add collection search matcher

* Fix naming

* fix naming

* Move FileDialogCollectionNavigator to its own file (no longer private class)
Add class diagram for collectionNavigation

* Add ICollectionNavigator interface

* Move to separate file IListCollectionNavigator

* Update class diagram

* update class diagram

* Add tests for overriding ICollectionNavigatorMatcher

* xmldoc and nullability warning fixes

* Code Cleanup

* Make requested changes to naming and terminology

* Move to seperate namespace

* Update class diagram and change TreeView to reference the interface not concrete class

* Switch to implicit new

* highlight that this class also works with tree view

* Apply tig patch to ensure keybindings get priority over navigator

See: https://github.com/gui-cs/Terminal.Gui/issues/4027#issuecomment-2810020893

* Apply 'keybinding has priority' fix to TreeView too

* Apply 'keybindngs priority over navigation' fix to TableView

* Remove entire branch for selectively returning false now that it is default when there is a keybinding collision

* Make classes internal and remove 'custom' navigator that was configured in UICatlaogToplevel

* Change logging in collection navigator from Trace to Debug

* Switch to NewKeyDownEvent and directly setting HasFocus

* Remove application top dependency

* Remove references to application

* Remove Application

* Move new tests to parallel

---------

Co-authored-by: Tig <tig@users.noreply.github.com>

Tests/UnitTestsParallelizable/Views/ListViewTests.cs

@@ -0,0 +1,120 @@
+using System.Collections.ObjectModel;
+using Moq;
+
+namespace Terminal.Gui.ViewsTests;
+
+public class ListViewTests
+{
+    [Fact]
+    public void ListViewCollectionNavigatorMatcher_DefaultBehaviour ()
+    {
+        ObservableCollection<string> source = new () { "apricot", "arm", "bat", "batman", "bates hotel", "candle" };
+        ListView lv = new ListView { Source = new ListWrapper<string> (source) };
+
+        // Keys are consumed during navigation
+        Assert.True (lv.NewKeyDownEvent (Key.B));
+        Assert.True (lv.NewKeyDownEvent (Key.A));
+        Assert.True (lv.NewKeyDownEvent (Key.T));
+
+        Assert.Equal ("bat", (string)lv.Source.ToList () [lv.SelectedItem]);
+    }
+
+    [Fact]
+    public void ListViewCollectionNavigatorMatcher_IgnoreKeys ()
+    {
+        ObservableCollection<string> source = new () { "apricot", "arm", "bat", "batman", "bates hotel", "candle" };
+        ListView lv = new ListView { Source = new ListWrapper<string> (source) };
+
+
+        var matchNone = new Mock<ICollectionNavigatorMatcher> ();
+
+        matchNone.Setup (m => m.IsCompatibleKey (It.IsAny<Key> ()))
+                 .Returns (false);
+
+        lv.KeystrokeNavigator.Matcher = matchNone.Object;
+
+        // Keys are ignored because IsCompatibleKey returned false i.e. don't use these keys for navigation
+        Assert.False (lv.NewKeyDownEvent (Key.B));
+        Assert.False (lv.NewKeyDownEvent (Key.A));
+        Assert.False (lv.NewKeyDownEvent (Key.T));
+
+        // assert IsMatch never called
+        matchNone.Verify (m => m.IsMatch (It.IsAny<string> (), It.IsAny<object> ()), Times.Never ());
+    }
+
+    [Fact]
+    public void ListViewCollectionNavigatorMatcher_OverrideMatching ()
+    {
+        ObservableCollection<string> source = new () { "apricot", "arm", "bat", "batman", "bates hotel", "candle" };
+        ListView lv = new ListView { Source = new ListWrapper<string> (source) };
+
+
+        var matchNone = new Mock<ICollectionNavigatorMatcher> ();
+
+        matchNone.Setup (m => m.IsCompatibleKey (It.IsAny<Key> ()))
+                 .Returns (true);
+
+        // Match any string starting with b to "candle" (psych!)
+        matchNone.Setup (m => m.IsMatch (It.IsAny<string> (), It.IsAny<object> ()))
+                 .Returns ((string s, object key) => s.StartsWith ('B') && key?.ToString () == "candle");
+
+        lv.KeystrokeNavigator.Matcher = matchNone.Object;
+        // Keys are consumed during navigation
+        Assert.True (lv.NewKeyDownEvent (Key.B));
+        Assert.Equal (5, lv.SelectedItem);
+        Assert.True (lv.NewKeyDownEvent (Key.A));
+        Assert.Equal (5, lv.SelectedItem);
+        Assert.True (lv.NewKeyDownEvent (Key.T));
+        Assert.Equal (5, lv.SelectedItem);
+
+        Assert.Equal ("candle", (string)lv.Source.ToList () [lv.SelectedItem]);
+    }
+
+    [Fact]
+    public void ListView_CollectionNavigatorMatcher_KeybindingsOverrideNavigator ()
+    {
+        ObservableCollection<string> source = new () { "apricot", "arm", "bat", "batman", "bates hotel", "candle" };
+        ListView lv = new ListView { Source = new ListWrapper<string> (source) };
+
+        lv.SetFocus ();
+
+        lv.KeyBindings.Add (Key.B, Command.Down);
+
+        Assert.Equal (-1, lv.SelectedItem);
+
+        // Keys should be consumed to move down the navigation i.e. to apricot
+        Assert.True (lv.NewKeyDownEvent (Key.B));
+        Assert.Equal (0, lv.SelectedItem);
+
+        Assert.True (lv.NewKeyDownEvent (Key.B));
+        Assert.Equal (1, lv.SelectedItem);
+
+        // There is no keybinding for Key.C so it hits collection navigator i.e. we jump to candle
+        Assert.True (lv.NewKeyDownEvent (Key.C));
+        Assert.Equal (5, lv.SelectedItem);
+    }
+
+    [Fact]
+    public void CollectionNavigatorMatcher_KeybindingsOverrideNavigator ()
+    {
+        ObservableCollection<string> source = new () { "apricot", "arm", "bat", "batman", "bates hotel", "candle" };
+        ListView lv = new ListView { Source = new ListWrapper<string> (source) };
+
+        lv.SetFocus ();
+
+        lv.KeyBindings.Add (Key.B, Command.Down);
+
+        Assert.Equal (-1, lv.SelectedItem);
+
+        // Keys should be consumed to move down the navigation i.e. to apricot
+        Assert.True (lv.NewKeyDownEvent (Key.B));
+        Assert.Equal (0, lv.SelectedItem);
+
+        Assert.True (lv.NewKeyDownEvent (Key.B));
+        Assert.Equal (1, lv.SelectedItem);
+
+        // There is no keybinding for Key.C so it hits collection navigator i.e. we jump to candle
+        Assert.True (lv.NewKeyDownEvent (Key.C));
+        Assert.Equal (5, lv.SelectedItem);
+    }
+}

Tests/UnitTestsParallelizable/Views/TableViewTests.cs

@@ -0,0 +1,45 @@
+using System;
+using System.Collections.Generic;
+using System.Data;
+using System.Linq;
+using System.Text;
+using System.Threading.Tasks;
+using JetBrains.Annotations;
+
+namespace Terminal.Gui.ViewsTests;
+
+[TestSubject (typeof (TableView))]
+public class TableViewTests
+{
+    [Fact]
+    public void TableView_CollectionNavigatorMatcher_KeybindingsOverrideNavigator ()
+    {
+        var dt = new DataTable ();
+        dt.Columns.Add ("blah");
+
+        dt.Rows.Add ("apricot");
+        dt.Rows.Add ("arm");
+        dt.Rows.Add ("bat");
+        dt.Rows.Add ("batman");
+        dt.Rows.Add ("bates hotel");
+        dt.Rows.Add ("candle");
+
+        var tableView = new TableView ();
+        tableView.Table = new DataTableSource (dt);
+        tableView.HasFocus = true;
+        tableView.KeyBindings.Add (Key.B, Command.Down);
+
+        Assert.Equal (0, tableView.SelectedRow);
+
+        // Keys should be consumed to move down the navigation i.e. to apricot
+        Assert.True (tableView.NewKeyDownEvent (Key.B));
+        Assert.Equal (1, tableView.SelectedRow);
+
+        Assert.True (tableView.NewKeyDownEvent (Key.B));
+        Assert.Equal (2, tableView.SelectedRow);
+
+        // There is no keybinding for Key.C so it hits collection navigator i.e. we jump to candle
+        Assert.True (tableView.NewKeyDownEvent (Key.C));
+        Assert.Equal (5, tableView.SelectedRow);
+    }
+}

Tests/UnitTestsParallelizable/Views/TreeViewTests.cs

@@ -0,0 +1,40 @@
+using JetBrains.Annotations;
+
+namespace Terminal.Gui.ViewsTests;
+
+[TestSubject (typeof (TreeView))]
+public class TreeViewTests
+{
+
+    [Fact]
+    public void TreeView_CollectionNavigatorMatcher_KeybindingsOverrideNavigator ()
+    {
+        var tree = new TreeView ();
+        tree.AddObjects ([
+                             new TreeNode(){ Text="apricot" },
+                             new TreeNode(){ Text="arm" },
+                             new TreeNode(){ Text="bat" },
+                             new TreeNode(){ Text="batman" },
+                             new TreeNode(){ Text="bates hotel" },
+                             new TreeNode(){ Text="candle" },
+                         ]);
+
+        tree.SetFocus ();
+
+        tree.KeyBindings.Add (Key.B, Command.Down);
+
+        Assert.Equal ("apricot", tree.SelectedObject.Text);
+
+        // Keys should be consumed to move down the navigation i.e. to apricot
+        Assert.True (tree.NewKeyDownEvent (Key.B));
+        Assert.NotNull (tree.SelectedObject);
+        Assert.Equal ("arm", tree.SelectedObject.Text);
+
+        Assert.True (tree.NewKeyDownEvent (Key.B));
+        Assert.Equal ("bat", tree.SelectedObject.Text);
+
+        // There is no keybinding for Key.C so it hits collection navigator i.e. we jump to candle
+        Assert.True (tree.NewKeyDownEvent (Key.C));
+        Assert.Equal ("candle", tree.SelectedObject.Text);
+    }
+}