[macOS] Fix GesturePlatformManager.CalculatePosition when asked for…

… a relative position (#19371)

* Fix

* Test

* Apply feedback

* Switch Button to BoxView

* - fix tests

* - add upper limit constraints

* - switch to wait for element

* Update src/Controls/samples/Controls.Sample.UITests/Issues/Issue19329.xaml

Co-authored-by: MartyIX <203266+MartyIX@users.noreply.github.com>

* - switch to click for catalyst

* Update src/Controls/tests/UITests/Tests/Issues/Issue19329.cs

Co-authored-by: MartyIX <203266+MartyIX@users.noreply.github.com>

* - add comments

---------

Co-authored-by: Shane Neuville <shneuvil@microsoft.com>
Co-authored-by: Shane Neuville <shane94@hotmail.com>

src/Controls/samples/Controls.Sample.UITests/Issues/Issue19329.xaml

@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
+             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
+             x:Class="Maui.Controls.Sample.Issues.Issue19329">
+    <VerticalStackLayout x:Name="layout" Margin="75,75,75,75" BackgroundColor="LightGray">
+        <Label Text="Tap the bottom red label. The position of the tap should be calculated relative to the upper blue box." />
+        <VerticalStackLayout HeightRequest="80" WidthRequest="80">
+            <BoxView HorizontalOptions="Start" x:Name="UpperBox" AutomationId="UpperBox" Color="CornflowerBlue" WidthRequest="20" HeightRequest="20"/>
+            <Label HorizontalOptions="End" x:Name="TapHere" Text="Tap Here" AutomationId="TapHere" Background="Red" WidthRequest="20" HeightRequest="20">
+                <Label.GestureRecognizers>
+                    <TapGestureRecognizer Tapped="OnTapped" />
+                </Label.GestureRecognizers>
+            </Label>
+        </VerticalStackLayout>
+    </VerticalStackLayout>
+</ContentPage>

src/Controls/samples/Controls.Sample.UITests/Issues/Issue19329.xaml.cs

@@ -0,0 +1,48 @@
+using System;
+using System.Collections.ObjectModel;
+using System.Diagnostics;
+using Microsoft.Maui;
+using Microsoft.Maui.Controls;
+using Microsoft.Maui.Graphics;
+
+namespace Maui.Controls.Sample.Issues
+{
+	[Issue(IssueTracker.Github, 19329, "Pointer gestures should work with relative positions correctly", PlatformAffected.iOS)]
+	public partial class Issue19329 : ContentPage
+	{
+		public Issue19329()
+		{
+			InitializeComponent();
+		}
+
+		private void OnTapped(object sender, TappedEventArgs e)
+		{
+			// Report that the callback was called.
+			layout.Children.Add(new Label { Text = "TapAccepted", AutomationId = "TapAccepted" });
+
+			Point? position = e.GetPosition(relativeTo: UpperBox);
+
+			string result;
+			string automationId;
+
+			if (position is null)
+			{
+				result = "Error: position is null";
+				automationId = "Failure";
+			}
+			else if (position.Value.X >= 60 && position.Value.X <= 80 && position.Value.Y >= 20 && position.Value.Y <= 40)
+			{
+				result = $"Success: relative position is: X={position.Value.X}, Y={position.Value.Y}";
+				automationId = "Success";
+			}
+			else
+			{
+				result = $"Error: relative position is: X={position.Value.X}, Y={position.Value.Y}";
+				automationId = "Failure";
+			}
+
+			// Report the result of the test.
+			layout.Children.Add(new Label { Text = result, AutomationId = automationId });
+		}
+	}
+}

src/Controls/src/Core/Platform/GestureManager/GesturePlatformManager.iOS.cs

@@ -180,7 +180,7 @@ static void ProcessRecognizerHandlerTap(
 			var eventTracker = weakEventTracker.Target as GesturePlatformManager;
 			var virtualView = eventTracker?._handler?.VirtualView as View;
 			var platformRecognizer = weakPlatformRecognizer?.Target as UIGestureRecognizer;
-			var platformView = eventTracker?.PlatformView;
+			var platformView = element?.ToPlatform();
 
 			if (virtualView == null)
 				return null;

src/Controls/tests/UITests/Tests/Issues/Issue19329.cs

@@ -0,0 +1,25 @@
+using NUnit.Framework;
+using UITest.Appium;
+using UITest.Core;
+using System.Drawing;
+
+namespace Microsoft.Maui.AppiumTests.Issues
+{
+	public class Issue19329 : _IssuesUITest
+	{
+		public Issue19329(TestDevice device) : base(device) { }
+
+		public override string Issue => "Pointer gestures should work with relative positions correctly";
+
+		[Test]
+		public void RelativePointerPositionIsComputedCorrectly()
+		{
+			_ = App.WaitForElement("TapHere");
+
+			App.Click("TapHere");
+
+			App.WaitForElement("TapAccepted");
+			App.WaitForElement("Success");
+		}
+	}
+}

src/TestUtils/src/UITest.Appium/HelperExtensions.cs

@@ -14,6 +14,14 @@ public static class HelperExtensions
 	{
 		static TimeSpan DefaultTimeout = TimeSpan.FromSeconds(15);
 
+		/// <summary>
+		/// For desktop, this will perform a mouse click on the target element.
+		/// For mobile, this will tap the element.
+		/// This API works for all platforms whereas TapCoordinates currently doesn't work on Catalyst
+		/// https://github.com/dotnet/maui/issues/19754
+		/// </summary>
+		/// <param name="app">Represents the main gateway to interact with an app.</param>
+		/// <param name="element">Target Element</param>
 		public static void Click(this IApp app, string element)
 		{
 			app.FindElement(element).Click();
@@ -77,6 +85,13 @@ public static void ClearText(this IApp app, string element)
 			app.FindElement(element).Clear();
 		}
 
+		/// <summary>
+		/// For desktop, this will perform a mouse click on the target element.
+		/// For mobile, this will tap the element.
+		/// This API works for all platforms whereas TapCoordinates currently doesn't work on Catalyst
+		/// https://github.com/dotnet/maui/issues/19754
+		/// </summary>
+		/// <param name="element">Target Element</param>
 		public static void Click(this IUIElement element)
 		{
 			element.Command.Execute("click", new Dictionary<string, object>()
@@ -382,6 +397,10 @@ public static void SetOrientationPortrait(this IApp app)
 
 		/// <summary>
 		/// Performs a tap / touch gesture on the given coordinates.
+		/// This API currently doesn't work on Catalyst https://github.com/dotnet/maui/issues/19754
+		/// For Catalyst you'll currently need to use Click instead. 
+		/// Tap is more mobile-specific and provides more flexibility than click. Click is more general and is 
+		/// used for simpler interactions. Depending on the context of your test, you might prefer one over the other.
 		/// </summary>
 		/// <param name="app">Represents the main gateway to interact with an app.</param>
 		/// <param name="x">The x coordinate to tap.</param>