Add some DispatcherQueueTimer docs, initial sample, and more unit tests

TODO: Still have the opposite scenario of Trailing to leading which is broken to fix.

Author: michael-hawker

components/Extensions/samples/Dispatcher/KeyboardDebounceSample.xaml

@@ -0,0 +1,14 @@
+<Page
+    x:Class="ExtensionsExperiment.Samples.DispatcherQueueExtensions.KeyboardDebounceSample"
+    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
+    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
+    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
+    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
+    mc:Ignorable="d"
+    Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">
+
+    <StackPanel Spacing="8">
+        <TextBox PlaceholderText="Type here..." TextChanged="TextBox_TextChanged"/>
+        <TextBlock x:Name="ResultText"/>
+    </StackPanel>
+</Page>

components/Extensions/samples/Dispatcher/KeyboardDebounceSample.xaml.cs

@@ -0,0 +1,45 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+using CommunityToolkit.WinUI;
+#if WINAPPSDK
+using DispatcherQueue = Microsoft.UI.Dispatching.DispatcherQueue;
+using DispatcherQueueTimer = Microsoft.UI.Dispatching.DispatcherQueueTimer;
+#else
+using DispatcherQueue = Windows.System.DispatcherQueue;
+using DispatcherQueueTimer = Windows.System.DispatcherQueueTimer;
+#endif
+
+namespace ExtensionsExperiment.Samples.DispatcherQueueExtensions;
+
+[ToolkitSample(id: nameof(KeyboardDebounceSample), "DispatcherQueueTimer Debounce Keyboard", description: "A sample for showing how to use the DispatcherQueueTimer Debounce extension to smooth keyboard input.")]
+[ToolkitSampleNumericOption("Interval", 120, 60, 240)]
+public sealed partial class KeyboardDebounceSample : Page
+{
+    public DispatcherQueueTimer _debounceTimer = DispatcherQueue.GetForCurrentThread().CreateTimer();
+
+    public KeyboardDebounceSample()
+    {
+        InitializeComponent();
+    }
+
+    private void TextBox_TextChanged(object sender, TextChangedEventArgs e)
+    {
+        var interval = this.GeneratedPropertyMetadata?.FirstOrDefault(vm => vm.Name == "Interval")?.Value as double?;
+
+        if (sender is TextBox textBox && interval != null)
+        {
+            _debounceTimer.Debounce(() =>
+                {
+                    ResultText.Text = textBox.Text;
+                },
+                //// i.e. if another keyboard press comes in within 120ms of the last, we'll wait before we fire off the request
+                interval: TimeSpan.FromMilliseconds(interval.Value),
+                //// If we're blanking out or the first character type, we'll start filtering immediately instead to appear more responsive.
+                //// We want to switch back to trailing as the user types more so that we still capture all the input.
+                immediate: textBox.Text.Length <= 1);
+
+        }
+    }
+}

components/Extensions/samples/DispatcherQueueTimerExtensions.md

@@ -0,0 +1,27 @@
+---
+title: DispatcherQueueTimerExtensions
+author: michael-hawker
+description: Helpers for executing code at specific times on a UI thread through a DispatcherQueue instance with a DispatcherQueueTimer.
+keywords: dispatcher, dispatcherqueue, DispatcherHelper, DispatcherQueueExtensions, DispatcherQueueTimer, DispatcherQueueTimerExtensions
+dev_langs:
+  - csharp
+category: Extensions
+subcategory: Miscellaneous
+discussion-id: 0
+issue-id: 0
+icon: Assets/Extensions.png
+---
+
+The `DispatcherQueueTimerExtensions` static class provides a collection of extensions methods for [`DispatcherQueueTimer`](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.dispatching.dispatcherqueue) objects that make it easier to execute code on a specific UI thread at a specific time.
+
+## Syntax
+
+The `DispatcherQueueTimerExtensions` static class currently exposes a single extension method, `Debounce`. This is a standard technique used to rate-limit input from a user to not overload requests on an underlying service of query elsewhere.
+
+It can be used in a number of ways, but most simply like so:
+
+> [!SAMPLE KeyboardDebounceSample]
+
+## Examples
+
+You can find more examples in the [unit tests](https://github.com/CommunityToolkit/Windows/blob/rel/8.1.240916/components/Extensions/tests/DispatcherQueueTimerExtensionTests.cs).

components/Extensions/src/Dispatcher/DispatcherQueueTimerExtensions.cs

@@ -20,22 +20,22 @@ public static class DispatcherQueueTimerExtensions
     private static ConcurrentDictionary<DispatcherQueueTimer, Action> _debounceInstances = new ConcurrentDictionary<DispatcherQueueTimer, Action>();
 
     /// <summary>
-    /// <para>Used to debounce (rate-limit) an event.  The action will be postponed and executed after the interval has elapsed.  At the end of the interval, the function will be called with the arguments that were passed most recently to the debounced function.</para>
+    /// <para>Used to debounce (rate-limit) an event.  The action will be postponed and executed after the interval has elapsed.  At the end of the interval, the function will be called with the arguments that were passed most recently to the debounced function. Useful for smoothing keyboard input, for instance.</para>
     /// <para>Use this method to control the timer instead of calling Start/Interval/Stop manually.</para>
     /// <para>A scheduled debounce can still be stopped by calling the stop method on the timer instance.</para>
     /// <para>Each timer can only have one debounced function limited at a time.</para>
     /// </summary>
     /// <param name="timer">Timer instance, only one debounced function can be used per timer.</param>
     /// <param name="action">Action to execute at the end of the interval.</param>
     /// <param name="interval">Interval to wait before executing the action.</param>
-    /// <param name="immediate">Determines if the action execute on the leading edge instead of trailing edge.</param>
+    /// <param name="immediate">Determines if the action execute on the leading edge instead of trailing edge of the interval. Subsequent input will be ignored into the interval has completed. Useful for ignore extraneous extra input like multiple mouse clicks.</param>
     /// <example>
     /// <code>
     /// private DispatcherQueueTimer _typeTimer = DispatcherQueue.GetForCurrentThread().CreateTimer();
     ///
     /// _typeTimer.Debounce(async () =>
     ///     {
-    ///         // Only executes this code after 0.3 seconds have elapsed since last trigger.
+    ///         // Only executes code put here after 0.3 seconds have elapsed since last call to Debounce.
     ///     }, TimeSpan.FromSeconds(0.3));
     /// </code>
     /// </example>

components/Extensions/tests/DispatcherQueueTimerExtensionTests.cs

@@ -83,6 +83,8 @@ public async Task DispatcherQueueTimer_Debounce_Trailing_Interrupt()
             TimeSpan.FromMilliseconds(60));
 
         Assert.AreEqual(true, debounceTimer.IsRunning, "Expected time to be running.");
+        Assert.AreEqual(0, triggeredCount, "Function shouldn't have run yet.");
+        Assert.IsNull(triggeredValue, "Function shouldn't have run yet.");
 
         await Task.Delay(TimeSpan.FromMilliseconds(110));
 
@@ -112,8 +114,17 @@ public async Task DispatcherQueueTimer_Debounce_Immediate()
         Assert.AreEqual(true, debounceTimer.IsRunning, "Expected time to be running.");
         Assert.AreEqual(1, triggeredCount, "Function should have run right away.");
         Assert.AreEqual(value, triggeredValue, "Should have expected immediate set of value");
+
+        await Task.Delay(TimeSpan.FromMilliseconds(80));
+
+        Assert.AreEqual(false, debounceTimer.IsRunning, "Expected to stop the timer.");
     }
 
+    /// <summary>
+    /// Tests the immediate mode of the Debounce function ignoring subsequent inputs that come after the first within the specified time window.
+    /// For instance, this could be useful to ignore extra multiple clicks on a button, but immediately start processing upon the first click.
+    /// </summary>
+    /// <returns></returns>
     [TestCategory("DispatcherQueueTimerExtensions")]
     [UIThreadTestMethod]
     public async Task DispatcherQueueTimer_Debounce_Immediate_Interrupt()
@@ -143,14 +154,85 @@ public async Task DispatcherQueueTimer_Debounce_Immediate_Interrupt()
                 triggeredCount++;
                 triggeredValue = value2;
             },
-            TimeSpan.FromMilliseconds(60));
+            TimeSpan.FromMilliseconds(60), true); // Ensure we're interrupting with immediate again
 
         Assert.AreEqual(true, debounceTimer.IsRunning, "Expected time to be running.");
+        Assert.AreEqual(1, triggeredCount, "2nd request coming within first period should have been ignored.");
+        Assert.AreEqual(value, triggeredValue, "Value shouldn't have changed from 2nd request within time bound.");
 
         await Task.Delay(TimeSpan.FromMilliseconds(110));
 
         Assert.AreEqual(false, debounceTimer.IsRunning, "Expected to stop the timer.");
-        Assert.AreEqual(value2, triggeredValue, "Expected to execute the last action.");
-        Assert.AreEqual(2, triggeredCount, "Expected to postpone execution.");
+        Assert.AreEqual(value, triggeredValue, "Expected to execute only the first action.");
+        Assert.AreEqual(1, triggeredCount, "Expected 2nd request to be ignored.");
+    }
+
+    /// <summary>
+    /// Tests where we start with immediately processing a delay, but then want to switch to processing after.
+    /// For instance, maybe we want to ensure we start processing the first letter of a search query to filter initial results.
+    /// But then later want to delay and wait to execute until all the query string is available.
+    /// </summary>
+    /// <returns></returns>
+    [TestCategory("DispatcherQueueTimerExtensions")]
+    [UIThreadTestMethod]
+    public async Task DispatcherQueueTimer_Debounce_Leading_Switch_Trailing_Interrupt_Twice()
+    {
+        var debounceTimer = DispatcherQueue.GetForCurrentThread().CreateTimer();
+
+        var triggeredCount = 0;
+        string? triggeredValue = null;
+
+        var value = "H";
+        debounceTimer.Debounce(
+            () =>
+            {
+                triggeredCount++;
+                triggeredValue = value;
+            },
+            TimeSpan.FromMilliseconds(100), true); // Start off right away
+
+        Assert.AreEqual(true, debounceTimer.IsRunning, "Expected time to be running.");
+        Assert.AreEqual(1, triggeredCount, "Function should have run right away.");
+        Assert.AreEqual(value, triggeredValue, "Function should have set value immediately.");
+
+        // Pragmatic pause
+        await Task.Delay(TimeSpan.FromMilliseconds(30));
+
+        // Now interrupt with more data two times.
+        var value2 = "Hel";
+        debounceTimer.Debounce(
+            () =>
+            {
+                triggeredCount++;
+                triggeredValue = value2;
+            },
+            TimeSpan.FromMilliseconds(100), false); // We want to ensure we catch the latest data now
+
+        Assert.AreEqual(true, debounceTimer.IsRunning, "Expected timer to still to be running.");
+        Assert.AreEqual(1, triggeredCount, "Function should now haven't run again yet.");
+        Assert.AreEqual(value, triggeredValue, "Function should still be the initial value");
+
+        // Pragmatic pause again
+        await Task.Delay(TimeSpan.FromMilliseconds(30));
+
+        var value3 = "Hello";
+        debounceTimer.Debounce(
+            () =>
+            {
+                triggeredCount++;
+                triggeredValue = value3;
+            },
+            TimeSpan.FromMilliseconds(100), false); // We want to ensure we catch the latest data now
+
+        Assert.AreEqual(true, debounceTimer.IsRunning, "Expected timer to still to be running.");
+        Assert.AreEqual(1, triggeredCount, "Function should still now haven't run again yet.");
+        Assert.AreEqual(value, triggeredValue, "Function should still be the initial value x2");
+
+        // Wait to where the timer should have fired and is done
+        await Task.Delay(TimeSpan.FromMilliseconds(120));
+
+        Assert.AreEqual(false, debounceTimer.IsRunning, "Expected timer to stopped at trailing edge to execute latest result.");
+        Assert.AreEqual(value3, triggeredValue, "Expected value to now be the last value provided.");
+        Assert.AreEqual(2, triggeredCount, "Expected to interrupt execution of 2nd request.");
     }
 }