[Net11] [iOS/MacCatalyst] Migrate FlyoutPage to handler architecture

src/Controls/src/Core/FlyoutPage/FlyoutPage.Mapper.cs

@@ -1,5 +1,8 @@
 using System;
-using Microsoft.Maui.Controls.Compatibility;
+using Microsoft.Maui.Handlers;
+#if IOS || MACCATALYST
+using UIKit;
+#endif
 
 namespace Microsoft.Maui.Controls
 {
@@ -9,9 +12,22 @@ public partial class FlyoutPage
 		internal new static void RemapForControls()
 		{
 			FlyoutViewHandler.Mapper.ReplaceMapping<IFlyoutView, IFlyoutViewHandler>(nameof(FlyoutLayoutBehavior), MapFlyoutLayoutBehavior);
-#if IOS
-			FlyoutViewHandler.Mapper.ReplaceMapping<IFlyoutView, IFlyoutViewHandler>(nameof(PlatformConfiguration.iOSSpecific.Page.PrefersHomeIndicatorAutoHiddenProperty), MapPrefersHomeIndicatorAutoHiddenProperty);
-			FlyoutViewHandler.Mapper.ReplaceMapping<IFlyoutView, IFlyoutViewHandler>(nameof(PlatformConfiguration.iOSSpecific.Page.PrefersStatusBarHiddenProperty), MapPrefersPrefersStatusBarHiddenProperty);
+#if IOS || MACCATALYST
+			// Fill configuration record (Core → Controls bridge)
+			FlyoutViewHandler.ControlsConfiguration = new(
+				OnPresentedChangedByGesture: FlyoutPage.OnPresentedChangedByGesture,
+				OnLayoutBoundsChanged: FlyoutPage.OnLayoutBoundsChanged,
+				OnLeftBarButtonNeedsUpdate: FlyoutPage.OnLeftBarButtonNeedsUpdate,
+				OnHandlerDisconnected: FlyoutPage.OnHandlerDisconnected
+			);
+
+			// iOS-specific property mappers
+			FlyoutViewHandler.Mapper.AppendToMapping(
+				PlatformConfiguration.iOSSpecific.FlyoutPage.ApplyShadowProperty.PropertyName,
+				MapApplyShadow);
+			FlyoutViewHandler.Mapper.AppendToMapping(nameof(IView.FlowDirection), MapFlowDirection);
+			FlyoutViewHandler.Mapper.ReplaceMapping<IFlyoutView, IFlyoutViewHandler>(PlatformConfiguration.iOSSpecific.Page.PrefersHomeIndicatorAutoHiddenProperty.PropertyName, MapPrefersHomeIndicatorAutoHiddenProperty);
+			FlyoutViewHandler.Mapper.ReplaceMapping<IFlyoutView, IFlyoutViewHandler>(PlatformConfiguration.iOSSpecific.Page.PrefersStatusBarHiddenProperty.PropertyName, MapPrefersPrefersStatusBarHiddenProperty);
 #endif
 #if WINDOWS
 			FlyoutViewHandler.Mapper.ReplaceMapping<IFlyoutView, IFlyoutViewHandler>(nameof(PlatformConfiguration.WindowsSpecific.FlyoutPage.CollapseStyleProperty), MapCollapseStyle);
@@ -23,15 +39,21 @@ internal static void MapFlyoutLayoutBehavior(IFlyoutViewHandler handler, IFlyout
 			handler.UpdateValue(nameof(IFlyoutView.FlyoutBehavior));
 		}
 
-#if IOS
+#if IOS || MACCATALYST
 		internal static void MapPrefersHomeIndicatorAutoHiddenProperty(IFlyoutViewHandler handler, IFlyoutView view)
 		{
-			handler.UpdateValue(nameof(PlatformConfiguration.iOSSpecific.Page.PrefersHomeIndicatorAutoHiddenProperty));
+			if (handler is IPlatformViewHandler { ViewController: { } vc })
+			{
+				vc.SetNeedsUpdateOfHomeIndicatorAutoHidden();
+			}
 		}
 
 		internal static void MapPrefersPrefersStatusBarHiddenProperty(IFlyoutViewHandler handler, IFlyoutView view)
 		{
-			handler.UpdateValue(nameof(PlatformConfiguration.iOSSpecific.Page.PrefersStatusBarHiddenProperty));
+			if (handler is IPlatformViewHandler { ViewController: { } vc })
+			{
+				vc.SetNeedsStatusBarAppearanceUpdate();
+			}
 		}
 #endif
 

src/Controls/src/Core/FlyoutPage/FlyoutPage.iOS.cs

@@ -0,0 +1,267 @@
+using System;
+using System.ComponentModel;
+using System.Linq;
+using Microsoft.Maui.Graphics;
+using Microsoft.Maui.Graphics.Platform;
+using Microsoft.Maui.Handlers;
+using Microsoft.Maui.Platform;
+using UIKit;
+
+namespace Microsoft.Maui.Controls
+{
+    public partial class FlyoutPage
+    {
+        // Track the flyout page this specific FlyoutPage instance is subscribed to
+        // for icon/title property changes. Instance-scoped (not static) so multiple
+        // FlyoutPage instances (multi-window, modal FlyoutPage, etc.) don't clobber
+        // each other's subscriptions.
+        WeakReference<Page>? _subscribedFlyout;
+
+        // Cached delegate instance so we can unsubscribe the exact same handler
+        // we subscribed with.
+        PropertyChangedEventHandler? _flyoutPropertyChangedHandler;
+
+
+        internal static void OnPresentedChangedByGesture(IFlyoutView view, bool isPresented)
+        {
+            if (view is FlyoutPage fp)
+            {
+                // Guard: during rotation, ShouldShowSplitMode may still return true while
+                // orientation hasn't settled. Writing false triggers InvalidOperationException
+                // in OnIsPresentedPropertyChanging validation.
+                if (!isPresented && ((IFlyoutPageController)fp).ShouldShowSplitMode)
+                {
+                    return;
+                }
+
+                fp.IsPresented = isPresented;
+            }
+            else
+            {
+                view.IsPresented = isPresented;
+            }
+        }
+
+        internal static void OnLayoutBoundsChanged(IFlyoutView view, Rect flyoutBounds, Rect detailBounds)
+        {
+            if (view is IFlyoutPageController controller)
+            {
+                controller.FlyoutBounds = flyoutBounds;
+                controller.DetailBounds = detailBounds;
+            }
+        }
+
+        internal static void OnLeftBarButtonNeedsUpdate(IFlyoutView view)
+        {
+            if (view is not FlyoutPage fp)
+            {
+                return;
+            }
+
+            fp.SubscribeToFlyoutPropertyChanges();
+
+            if (fp.Detail?.Handler is not IPlatformViewHandler detailHandler)
+            {
+                return;
+            }
+
+            var detailVC = detailHandler.ViewController;
+            if (detailVC is null)
+            {
+                return;
+            }
+
+            // If detail VC is a UINavigationController, use its root VC
+            var targetVC = detailVC is UINavigationController nav
+                ? nav.ViewControllers?.FirstOrDefault() ?? detailVC
+                : detailVC;
+
+            UpdateFlyoutLeftBarButton(targetVC, fp);
+        }
+
+        /// <summary>
+        /// Called when this FlyoutPage's handler is disconnected, so its flyout
+        /// icon/title subscription doesn't outlive the handler.
+        /// </summary>
+        internal static void OnHandlerDisconnected(IFlyoutView view)
+        {
+            if (view is FlyoutPage fp)
+            {
+                fp.UnsubscribeFlyoutPropertyChanges();
+            }
+        }
+
+        void SubscribeToFlyoutPropertyChanges()
+        {
+            var flyout = Flyout;
+            if (flyout is null)
+            {
+                return;
+            }
+
+            // Unsubscribe from this instance's previous flyout if it changed
+            if (_subscribedFlyout is not null && _subscribedFlyout.TryGetTarget(out var oldFlyout))
+            {
+                if (ReferenceEquals(oldFlyout, flyout))
+                {
+                    return; // Already subscribed to this flyout
+                }
+
+                if (_flyoutPropertyChangedHandler is not null)
+                {
+                    oldFlyout.PropertyChanged -= _flyoutPropertyChangedHandler;
+                }
+            }
+
+            _flyoutPropertyChangedHandler = OnFlyoutPagePropertyChanged;
+            flyout.PropertyChanged += _flyoutPropertyChangedHandler;
+            _subscribedFlyout = new WeakReference<Page>(flyout);
+        }
+
+        /// <summary>
+        /// Unsubscribes from the currently-tracked flyout's property changes.
+        /// Called when this FlyoutPage's handler is disconnected.
+        /// </summary>
+        void UnsubscribeFlyoutPropertyChanges()
+        {
+            if (_subscribedFlyout is not null &&
+                _subscribedFlyout.TryGetTarget(out var flyout) &&
+                _flyoutPropertyChangedHandler is not null)
+            {
+                flyout.PropertyChanged -= _flyoutPropertyChangedHandler;
+            }
+
+            _flyoutPropertyChangedHandler = null;
+            _subscribedFlyout = null;
+        }
+
+        void OnFlyoutPagePropertyChanged(object? sender, PropertyChangedEventArgs e)
+        {
+            if (e.PropertyName == Page.IconImageSourceProperty.PropertyName ||
+                e.PropertyName == Page.TitleProperty.PropertyName)
+            {
+                if (sender is Page flyoutPage && flyoutPage.Parent is FlyoutPage fp)
+                {
+                    OnLeftBarButtonNeedsUpdate(fp);
+                }
+            }
+        }
+
+        static void UpdateFlyoutLeftBarButton(UIViewController targetVC, FlyoutPage flyoutPage)
+        {
+            if (!flyoutPage.ShouldShowToolbarButton())
+            {
+                targetVC.NavigationItem.LeftBarButtonItem = null;
+                return;
+            }
+
+            var mauiContext = flyoutPage.FindMauiContext();
+            if (mauiContext is null)
+            {
+                return;
+            }
+
+            // Weak reference prevents a pending async callback from keeping
+            // the page alive after the handler is disconnected (memory leak fix).
+            var weakPage = new WeakReference<FlyoutPage>(flyoutPage);
+
+            EventHandler onItemTapped = (sender, e) =>
+            {
+                if (weakPage.TryGetTarget(out var p))
+                {
+                    p.IsPresented = !p.IsPresented;
+                }
+            };
+
+            flyoutPage.Flyout.IconImageSource.LoadImage(mauiContext, result =>
+            {
+                if (!weakPage.TryGetTarget(out var fp))
+                {
+                    return;
+                }
+
+                var icon = result?.Value;
+
+                if (icon is not null)
+                {
+                    // Scale icon to fit nav bar (max 44pt height)
+                    var originalSize = icon.Size;
+                    if (originalSize.Height > 44)
+                    {
+                        if (fp.Flyout.IconImageSource is not FontImageSource fontImageSource ||
+                            !fontImageSource.IsSet(FontImageSource.SizeProperty))
+                        {
+                            icon = icon.ResizeImageSource(originalSize.Width, 44f, originalSize);
+                        }
+                    }
+
+                    try
+                    {
+                        targetVC.NavigationItem.LeftBarButtonItem =
+                            new UIBarButtonItem(icon, UIBarButtonItemStyle.Plain, onItemTapped);
+                    }
+                    catch (Exception)
+                    {
+                        // UIBarButtonItem creation can throw
+                    }
+                }
+
+                if (icon is null || targetVC.NavigationItem.LeftBarButtonItem is null)
+                {
+                    // Fallback: use Flyout.Title as text button
+                    targetVC.NavigationItem.LeftBarButtonItem =
+                        new UIBarButtonItem(fp.Flyout?.Title ?? string.Empty, UIBarButtonItemStyle.Plain, onItemTapped);
+                }
+
+                // Set AutomationId and VoiceOver label/hint on the hamburger button.
+                if (!string.IsNullOrEmpty(fp.AutomationId))
+                {
+                    targetVC.NavigationItem.LeftBarButtonItem.AccessibilityIdentifier = $"btn_{fp.AutomationId}";
+                }
+
+                // Apply FlyoutPage's SemanticProperties (Description/Hint), if set.
+                var semantics = SemanticProperties.UpdateSemantics(fp, null);
+                if (semantics is not null)
+                {
+                    targetVC.NavigationItem.LeftBarButtonItem.UpdateSemantics(semantics);
+                }
+            });
+        }
+
+
+        internal static void MapApplyShadow(IFlyoutViewHandler handler, IFlyoutView view)
+        {
+            if (handler is FlyoutViewHandler h && h._manager is { } manager && view is BindableObject bo)
+            {
+                var applyShadow = PlatformConfiguration.iOSSpecific.FlyoutPage.GetApplyShadow(bo);
+                manager.UpdateApplyShadow(applyShadow);
+            }
+        }
+
+        internal static void MapFlowDirection(IFlyoutViewHandler handler, IFlyoutView view)
+        {
+            if (handler is FlyoutViewHandler h && h._manager is { } manager && view is IView v)
+            {
+                // Use the effective/inherited flow direction rather than the raw
+                // FlowDirection. A FlyoutPage left at the default MatchParent should
+                // follow an RTL app/window, not be treated as LTR.
+                var flowDirection = (view as IVisualElementController)?.EffectiveFlowDirection.ToFlowDirection()
+                    ?? v.FlowDirection;
+                manager.UpdateFlowDirection(flowDirection);
+
+                // NavigationPage isn't auto-walked by Core's FlowDirection propagation, so
+                // manually re-trigger it on each page in the navigation stack.
+                if (view is FlyoutPage fp && fp.Detail is NavigationPage detailNavPage)
+                {
+                    foreach (var page in detailNavPage.Navigation.NavigationStack)
+                    {
+                    	if (page?.Handler is IElementHandler pageHandler)
+                    	{
+                    		pageHandler.UpdateValue(nameof(IView.FlowDirection));
+                    	}
+                    }
+                }
+            }
+        }
+    }
+}

src/Controls/src/Core/Hosting/AppHostBuilderExtensions.cs

@@ -205,7 +205,7 @@ internal static IMauiHandlersCollection AddControlsHandlers(this IMauiHandlersCo
 #if IOS || MACCATALYST
 		handlersCollection.AddHandler<NavigationPage, NavigationViewHandler>();
 		handlersCollection.AddHandler<TabbedPage, TabbedViewHandler>();
-		handlersCollection.AddHandler(typeof(FlyoutPage), typeof(Handlers.Compatibility.PhoneFlyoutPageRenderer));
+		handlersCollection.AddHandler<FlyoutPage, FlyoutViewHandler>();
 #endif
 
 #if ANDROID || IOS || MACCATALYST || TIZEN

src/Core/src/Handlers/FlyoutView/FlyoutViewHandler.Standard.cs

@@ -4,9 +4,13 @@ namespace Microsoft.Maui.Handlers
 {
 	public partial class FlyoutViewHandler : ViewHandler<IFlyoutView, object>
 	{
-		protected override object CreatePlatformView()
-		{
-			throw new System.NotImplementedException();
-		}
+		protected override object CreatePlatformView() => throw new NotImplementedException();
+
+		public static void MapFlyout(IFlyoutViewHandler handler, IFlyoutView flyoutView) { }
+		public static void MapDetail(IFlyoutViewHandler handler, IFlyoutView flyoutView) { }
+		public static void MapIsPresented(IFlyoutViewHandler handler, IFlyoutView flyoutView) { }
+		public static void MapFlyoutBehavior(IFlyoutViewHandler handler, IFlyoutView flyoutView) { }
+		public static void MapFlyoutWidth(IFlyoutViewHandler handler, IFlyoutView flyoutView) { }
+		public static void MapIsGestureEnabled(IFlyoutViewHandler handler, IFlyoutView flyoutView) { }
 	}
 }

src/Core/src/Handlers/FlyoutView/FlyoutViewHandler.cs

@@ -20,19 +20,17 @@ public partial class FlyoutViewHandler : IFlyoutViewHandler
 		// So we have a separate mapper for them.
 		private static readonly IPropertyMapper<IFlyoutView, IFlyoutViewHandler> FlyoutLayoutMapper = new PropertyMapper<IFlyoutView, IFlyoutViewHandler>()
 		{
-#if ANDROID || WINDOWS || TIZEN
 			[nameof(IFlyoutView.Flyout)] = MapFlyout,
 			[nameof(IFlyoutView.Detail)] = MapDetail,
-#endif
 		};
 
 		public static IPropertyMapper<IFlyoutView, IFlyoutViewHandler> Mapper = new PropertyMapper<IFlyoutView, IFlyoutViewHandler>(ViewHandler.ViewMapper, FlyoutLayoutMapper)
 		{
-#if ANDROID || WINDOWS || TIZEN
 			[nameof(IFlyoutView.IsPresented)] = MapIsPresented,
 			[nameof(IFlyoutView.FlyoutBehavior)] = MapFlyoutBehavior,
 			[nameof(IFlyoutView.FlyoutWidth)] = MapFlyoutWidth,
 			[nameof(IFlyoutView.IsGestureEnabled)] = MapIsGestureEnabled,
+#if ANDROID || WINDOWS || TIZEN
 			[nameof(IToolbarElement.Toolbar)] = MapToolbar,
 #endif
 		};
@@ -58,5 +56,20 @@ public FlyoutViewHandler(IPropertyMapper? mapper, CommandMapper? commandMapper)
 		IFlyoutView IFlyoutViewHandler.VirtualView => VirtualView;
 
 		PlatformView IFlyoutViewHandler.PlatformView => PlatformView;
+
+#if IOS || MACCATALYST
+		/// <summary>
+		/// Configuration record filled by Controls layer via RemapForControls().
+		/// Core handler calls these when gestures/layout change — Controls writes back to FlyoutPage.
+		/// </summary>
+		internal sealed record FlyoutViewHandlerControlsConfiguration(
+			Action<IFlyoutView, bool> OnPresentedChangedByGesture,
+			Action<IFlyoutView, Graphics.Rect, Graphics.Rect> OnLayoutBoundsChanged,
+			Action<IFlyoutView> OnLeftBarButtonNeedsUpdate,
+			Action<IFlyoutView> OnHandlerDisconnected
+		);
+
+		internal static FlyoutViewHandlerControlsConfiguration? ControlsConfiguration { get; set; }
+#endif
 	}
 }