Add FocusAsync overload with preventScroll parameter #24852 (#28686)

* Add FocusAsync overload with preventScroll parameter #24852

* Add E2E Test for preventScroll parameter  #24852

Co-authored-by: Soshin Konstantin <[email protected]>

Author: KonstantinAlexeevich

src/Components/Web.JS/src/DomWrapper.ts

@@ -4,9 +4,9 @@ export const domFunctions = {
   focus,
 };
 
-function focus(element: HTMLElement): void {
+function focus(element: HTMLElement, preventScroll: boolean): void {
   if (element instanceof HTMLElement) {
-    element.focus();
+    element.focus({ preventScroll });
   } else {
     throw new Error('Unable to focus an invalid element.');
   }

src/Components/Web/src/ElementReferenceExtensions.cs

@@ -17,7 +17,21 @@ public static class ElementReferenceExtensions
         /// </summary>
         /// <param name="elementReference">A reference to the element to focus.</param>
         /// <returns>The <see cref="ValueTask"/> representing the asynchronous focus operation.</returns>
-        public static ValueTask FocusAsync(this ElementReference elementReference)
+        public static ValueTask FocusAsync(this ElementReference elementReference) => elementReference.FocusAsync(preventScroll: false);
+
+        /// <summary>
+        /// Gives focus to an element given its <see cref="ElementReference"/>.
+        /// </summary>
+        /// <param name="elementReference">A reference to the element to focus.</param>
+        /// <param name="preventScroll">
+        /// <para>
+        ///     A <see cref="bool" /> value indicating whether or not the browser should scroll the document to bring the newly-focused element into view.
+        ///     A value of false for preventScroll (the default) means that the browser will scroll the element into view after focusing it.
+        ///     If preventScroll is set to true, no scrolling will occur.
+        /// </para>
+        /// </param>
+        /// <returns>The <see cref="ValueTask"/> representing the asynchronous focus operation.</returns>
+        public static ValueTask FocusAsync(this ElementReference elementReference, bool preventScroll)
         {
             var jsRuntime = elementReference.GetJSRuntime();
 
@@ -26,7 +40,7 @@ public static ValueTask FocusAsync(this ElementReference elementReference)
                 throw new InvalidOperationException("No JavaScript runtime found.");
             }
 
-            return jsRuntime.InvokeVoidAsync(DomWrapperInterop.Focus, elementReference);
+            return jsRuntime.InvokeVoidAsync(DomWrapperInterop.Focus, elementReference, preventScroll);
         }
 
         internal static IJSRuntime GetJSRuntime(this ElementReference elementReference)

src/Components/Web/src/PublicAPI.Shipped.txt

@@ -1,4 +1,4 @@
-#nullable enable
+#nullable enable
 Microsoft.AspNetCore.Components.BindInputElementAttribute
 Microsoft.AspNetCore.Components.BindInputElementAttribute.BindInputElementAttribute(string? type, string? suffix, string? valueAttribute, string? changeAttribute, bool isInvariantCulture, string? format) -> void
 Microsoft.AspNetCore.Components.BindInputElementAttribute.ChangeAttribute.get -> string?
@@ -382,6 +382,7 @@ override Microsoft.AspNetCore.Components.Routing.NavLink.BuildRenderTree(Microso
 override Microsoft.AspNetCore.Components.Routing.NavLink.OnInitialized() -> void
 override Microsoft.AspNetCore.Components.Routing.NavLink.OnParametersSet() -> void
 static Microsoft.AspNetCore.Components.ElementReferenceExtensions.FocusAsync(this Microsoft.AspNetCore.Components.ElementReference elementReference) -> System.Threading.Tasks.ValueTask
+static Microsoft.AspNetCore.Components.ElementReferenceExtensions.FocusAsync(this Microsoft.AspNetCore.Components.ElementReference elementReference, bool preventScroll) -> System.Threading.Tasks.ValueTask
 static Microsoft.AspNetCore.Components.Forms.BrowserFileExtensions.RequestImageFileAsync(this Microsoft.AspNetCore.Components.Forms.IBrowserFile! browserFile, string! format, int maxWith, int maxHeight) -> System.Threading.Tasks.ValueTask<Microsoft.AspNetCore.Components.Forms.IBrowserFile!>
 static Microsoft.AspNetCore.Components.Forms.EditContextFieldClassExtensions.FieldCssClass(this Microsoft.AspNetCore.Components.Forms.EditContext! editContext, in Microsoft.AspNetCore.Components.Forms.FieldIdentifier fieldIdentifier) -> string!
 static Microsoft.AspNetCore.Components.Forms.EditContextFieldClassExtensions.FieldCssClass<TField>(this Microsoft.AspNetCore.Components.Forms.EditContext! editContext, System.Linq.Expressions.Expression<System.Func<TField>!>! accessor) -> string!

src/Components/test/E2ETest/Tests/ComponentRenderingTest.cs

@@ -408,7 +408,12 @@ public void CanUseJsInteropToReferenceElements()
         [Fact]
         public void CanUseFocusExtensionToFocusElement()
         {
+            Browser.Manage().Window.Size = new System.Drawing.Size(100, 300);
             var appElement = Browser.MountTestComponent<ElementFocusComponent>();
+
+            // y scroll position before click
+            var pageYOffsetBefore = getPageYOffset();
+
             var buttonElement = appElement.FindElement(By.Id("focus-button"));
 
             // Make sure the input element isn't focused when the test begins; we don't want
@@ -421,8 +426,51 @@ public void CanUseFocusExtensionToFocusElement()
             // Verify that the input element is focused
             Browser.Equal("focus-input", getFocusedElementId);
 
+            // y scroll position ater click
+            var pageYOffsetAfter = getPageYOffset();
+
+            //  Verify that scroll became
+            Assert.True(pageYOffsetAfter > pageYOffsetBefore);
+
+            // A local helper that gets the ID of the focused element.
+            string getFocusedElementId() => Browser.SwitchTo().ActiveElement().GetAttribute("id");
+
+            // A local helper that gets window.PageYOffset
+            long getPageYOffset() => (long)((IJavaScriptExecutor)Browser).ExecuteScript("return window.pageYOffset");
+        }
+
+        [Fact]
+        public void CanUseFocusExtensionToFocusElementPreventScroll()
+        {
+            Browser.Manage().Window.Size = new System.Drawing.Size(100, 300);
+            var appElement = Browser.MountTestComponent<ElementFocusComponent>();
+
+            // y scroll position before click
+            var pageYOffsetBefore = getPageYOffset();
+
+            var buttonElement = appElement.FindElement(By.Id("focus-button-prevented"));
+
+            // Make sure the input element isn't focused when the test begins; we don't want
+            // the test to pass just because the input started as the focused element
+            Browser.NotEqual("focus-input", getFocusedElementId);
+
+            // Click the button whose callback focuses the input element
+            buttonElement.Click();
+
+            // Verify that the input element is focused
+            Browser.Equal("focus-input", getFocusedElementId);
+
+            // y scroll position ater click
+            var pageYOffsetAfter = getPageYOffset();
+
+            //  Verify that not scrolled
+            Assert.Equal(pageYOffsetAfter, pageYOffsetBefore);
+
             // A local helper that gets the ID of the focused element.
             string getFocusedElementId() => Browser.SwitchTo().ActiveElement().GetAttribute("id");
+
+            // A local helper that gets window.PageYOffset
+            long getPageYOffset() => (long)((IJavaScriptExecutor)Browser).ExecuteScript("return window.pageYOffset");
         }
 
         [Fact]

src/Components/test/testassets/BasicTestApp/ElementFocusComponent.razor

@@ -1,13 +1,16 @@
-@using Microsoft.JSInterop
+@using Microsoft.JSInterop
 
-<button id="focus-button" @onclick="FocusInput">Click to focus!</button>
-<input id="focus-input" @ref="inputReference" />
+<button id="focus-button" @onclick="@(() => FocusInput(false))">Click to focus!</button>
+<hr />
+<button id="focus-button-prevented" @onclick="@(() => FocusInput(true))">Click to focus with preventScroll!</button>
+<hr />
+<input id="focus-input" @ref="inputReference" style="margin-top: 10000px" />
 
 @code {
     private ElementReference inputReference;
 
-    private async Task FocusInput()
+    private async Task FocusInput(bool preventScroll)
     {
-        await inputReference.FocusAsync();
+        await inputReference.FocusAsync(preventScroll);
     }
 }