Implement iOS/macOS secondary ToolbarItems - Shell (#30480)

* Implement iOS/macOS secondary ToolbarItems - shell

* Update ToolbarItemExtensions.cs

Author: kubaflo

src/Controls/src/Core/Compatibility/Handlers/Shell/iOS/ShellPageRendererTracker.cs

@@ -353,22 +353,67 @@ protected virtual void UpdateToolbarItems()
 
 			var shellToolbarItems = _context?.Shell?.ToolbarItems;
 			List<UIBarButtonItem>? primaries = null;
+			List<UIMenuElement>? secondaries = null;
+
 			if (Page.ToolbarItems.Count > 0) // Display toolbar items defined on the current page
 			{
 				foreach (var item in System.Linq.Enumerable.OrderBy(Page.ToolbarItems, x => x.Priority))
 				{
-					(primaries = primaries ?? new List<UIBarButtonItem>()).Add(item.ToUIBarButtonItem(false, true));
+					if (item.Order == ToolbarItemOrder.Secondary)
+					{
+						(secondaries ??= []).Add(item.ToSecondarySubToolbarItem().PlatformAction);
+					}
+					else
+					{
+						(primaries ??= []).Add(item.ToUIBarButtonItem());
+					}
 				}
 			}
 			else if (shellToolbarItems != null && shellToolbarItems.Count > 0) // If the page has no toolbar items use the ones defined for the shell
 			{
 				foreach (var item in System.Linq.Enumerable.OrderBy(shellToolbarItems, x => x.Priority))
 				{
-					(primaries = primaries ?? new List<UIBarButtonItem>()).Add(item.ToUIBarButtonItem(false, true));
+					if (item.Order == ToolbarItemOrder.Secondary)
+					{
+						(secondaries ??= []).Add(item.ToSecondarySubToolbarItem().PlatformAction);
+					}
+					else
+					{
+						(primaries ??= []).Add(item.ToUIBarButtonItem());
+					}
 				}
 			}
 
-			primaries?.Reverse();
+			if (primaries is not null && primaries.Count > 0)
+			{
+				primaries.Reverse();
+			}
+
+			if (secondaries is not null && secondaries.Count > 0)
+			{
+				UIImage? secondaryIcon = null;
+				if (ViewController?.ParentViewController is ShellSectionRenderer ssr)
+				{
+					secondaryIcon = ssr.GetSecondaryToolbarMenuButtonImage();
+				}
+				else
+				{
+					// Shouldn't happen, but just in case let's add a fallback to the default icon
+					secondaryIcon = UIImage.GetSystemImage("ellipsis.circle");
+				}
+
+				var menu = UIMenu.Create(string.Empty, null, UIMenuIdentifier.Edit, UIMenuOptions.DisplayInline, secondaries.ToArray());
+				var menuButton = new UIBarButtonItem(secondaryIcon, menu)
+				{
+					AccessibilityIdentifier = "SecondaryToolbarMenuButton"
+				};
+
+				// Since we are adding secondary items under a primary button,
+				// make sure that primaries is initialized
+				primaries ??= [];
+
+				primaries.Insert(0, menuButton);
+			}
 
 			NavigationItem.SetRightBarButtonItems(primaries is null ? Array.Empty<UIBarButtonItem>() : primaries.ToArray(), false);
 

src/Controls/src/Core/Compatibility/Handlers/Shell/iOS/ShellSectionRenderer.cs

@@ -324,6 +324,19 @@ protected override void Dispose(bool disposing)
 			base.Dispose(disposing);
 		}
 
+		/// <summary>
+		/// Override this method to provide a custom image for the secondary toolbar menu button.
+		/// The default implementation uses the "ellipsis.circle" system image.
+		/// This image is used for the menu button that appears when there are secondary toolbar items
+		/// </summary>
+		/// <returns>The image to use for the secondary toolbar menu button.</returns>
+		public virtual UIImage GetSecondaryToolbarMenuButtonImage()
+		{
+			// Use the ellipsis.circle system image for the menu button by default
+			// as per the iOS design guidelines: https://developer.apple.com/design/human-interface-guidelines/pull-down-buttons
+			return UIImage.GetSystemImage("ellipsis.circle");
+		}
+
 		protected virtual void HandleShellPropertyChanged(object sender, PropertyChangedEventArgs e)
 		{
 			if (e.Is(VisualElement.FlowDirectionProperty))

src/Controls/src/Core/Compatibility/iOS/Extensions/ToolbarItemExtensions.cs

@@ -29,15 +29,20 @@ public static UIBarButtonItem ToUIBarButtonItem(this ToolbarItem item, bool forc
 
 		internal static SecondarySubToolbarItem ToSecondarySubToolbarItem(this ToolbarItem item)
 		{
+			var weakItem = new WeakReference<ToolbarItem>(item);
+
 			var action = UIAction.Create(item.Text, null, null, _ =>
 			{
-				if (item is IMenuItemController menuItemController)
-				{
-					menuItemController.Activate();
-				}
-				else
+				if (weakItem.TryGetTarget(out var targetItem))
 				{
-					item.Command?.Execute(item.CommandParameter);
+					if (targetItem is IMenuItemController menuItemController)
+					{
+						menuItemController.Activate();
+					}
+					else
+					{
+						targetItem.Command?.Execute(targetItem.CommandParameter);
+					}
 				}
 			});
 

src/Controls/src/Core/PublicAPI/net-ios/PublicAPI.Unshipped.txt

@@ -368,3 +368,4 @@ virtual Microsoft.Maui.Controls.Platform.Compatibility.ShellPageRendererTracker.
 virtual Microsoft.Maui.Controls.Platform.Compatibility.ShellPageRendererTracker.UpdateSearchVisibility(UIKit.UISearchController! searchController) -> void
 ~virtual Microsoft.Maui.Controls.PropertyChangingEventHandler.Invoke(object sender, Microsoft.Maui.Controls.PropertyChangingEventArgs e) -> void
 ~virtual Microsoft.Maui.Controls.VisualElement.ComputeConstraintForView(Microsoft.Maui.Controls.View view) -> void
+~virtual Microsoft.Maui.Controls.Platform.Compatibility.ShellSectionRenderer.GetSecondaryToolbarMenuButtonImage() -> UIKit.UIImage

src/Controls/src/Core/PublicAPI/net-maccatalyst/PublicAPI.Unshipped.txt

@@ -368,3 +368,4 @@ virtual Microsoft.Maui.Controls.Platform.Compatibility.ShellPageRendererTracker.
 virtual Microsoft.Maui.Controls.Platform.Compatibility.ShellPageRendererTracker.UpdateSearchVisibility(UIKit.UISearchController! searchController) -> void
 ~virtual Microsoft.Maui.Controls.PropertyChangingEventHandler.Invoke(object sender, Microsoft.Maui.Controls.PropertyChangingEventArgs e) -> void
 ~virtual Microsoft.Maui.Controls.VisualElement.ComputeConstraintForView(Microsoft.Maui.Controls.View view) -> void
+~virtual Microsoft.Maui.Controls.Platform.Compatibility.ShellSectionRenderer.GetSecondaryToolbarMenuButtonImage() -> UIKit.UIImage