fix(systray): highlight status item and ensure popup appears above other windows on macOS

Fixes #4910

This commit addresses two issues with the systray-menu example on macOS:

1. System tray icon not in selected state upon clicking:
   - Added systemTraySetHighlight() function to control the NSStatusBarButton highlight state
   - Set highlight:YES before showing menus via popUpStatusItemMenu
   - Added onAttachedWindowShown/Hidden hooks for managing highlight with attached windows
   - Note: For attached windows, the highlight may briefly flash due to macOS
     NSStatusBarButton behavior where mouse-up clears highlight state

2. Popup doesn't display on top of other windows:
   - Set window level to NSPopUpMenuWindowLevel when positioning systray popup windows
   - Call orderFrontRegardless to ensure the window appears in front

The fix adds onAttachedWindowShown() and onAttachedWindowHidden() to the
systemTrayImpl interface to allow platform-specific handling when the
attached window visibility changes.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: leaanthony

v3/pkg/application/application_server.go

@@ -461,6 +461,8 @@ func (t *serverSystemTray) positionWindow(w Window, o int) error { return errors
 func (t *serverSystemTray) openMenu()                         {}
 func (t *serverSystemTray) Show()                             {}
 func (t *serverSystemTray) Hide()                             {}
+func (t *serverSystemTray) onAttachedWindowHidden()           {}
+func (t *serverSystemTray) onAttachedWindowShown()            {}
 
 // newWindowImpl creates a webview window implementation for server mode.
 func newWindowImpl(parent *WebviewWindow) *serverWebviewWindow {

v3/pkg/application/systemtray.go

@@ -39,6 +39,8 @@ type systemTrayImpl interface {
 	openMenu()
 	Show()
 	Hide()
+	onAttachedWindowHidden()
+	onAttachedWindowShown()
 }
 
 type SystemTray struct {
@@ -109,6 +111,8 @@ func (s *SystemTray) Run() {
 		// Setup listener
 		s.attachedWindow.Window.OnWindowEvent(events.Common.WindowLostFocus, func(event *WindowEvent) {
 			s.attachedWindow.Window.Hide()
+			// Notify impl that attached window was hidden (e.g., to update highlight state on macOS)
+			s.impl.onAttachedWindowHidden()
 			// Special handler for Windows
 			if runtime.GOOS == "windows" {
 				// We don't do this unless the window has already been shown
@@ -322,10 +326,13 @@ func (s *SystemTray) defaultClickHandler() {
 
 	if s.attachedWindow.Window.IsVisible() {
 		s.attachedWindow.Window.Hide()
+		// onAttachedWindowHidden is called via WindowLostFocus event handler
 	} else {
 		s.attachedWindow.hasBeenShown = true
 		_ = s.PositionWindow(s.attachedWindow.Window, s.attachedWindow.Offset)
 		s.attachedWindow.Window.Show().Focus()
+		// Set highlight after window is shown (important for macOS)
+		s.impl.onAttachedWindowShown()
 	}
 }
 

v3/pkg/application/systemtray_android.go

@@ -100,3 +100,11 @@ func (s *androidSystemTray) Show() {
 func (s *androidSystemTray) Hide() {
 	// Android doesn't have system tray
 }
+
+func (s *androidSystemTray) onAttachedWindowHidden() {
+	// Android doesn't have system tray
+}
+
+func (s *androidSystemTray) onAttachedWindowShown() {
+	// Android doesn't have system tray
+}

v3/pkg/application/systemtray_darwin.go

@@ -72,6 +72,18 @@ func (s *macosSystemTray) openMenu() {
 	C.showMenu(s.nsStatusItem, s.nsMenu)
 }
 
+func (s *macosSystemTray) setHighlight(highlight bool) {
+	C.systemTraySetHighlight(s.nsStatusItem, C.bool(highlight))
+}
+
+func (s *macosSystemTray) onAttachedWindowHidden() {
+	s.setHighlight(false)
+}
+
+func (s *macosSystemTray) onAttachedWindowShown() {
+	s.setHighlight(true)
+}
+
 type button int
 
 const (

v3/pkg/application/systemtray_darwin.h

@@ -17,6 +17,7 @@ NSImage* imageFromBytes(const unsigned char *bytes, int length);
 void systemTraySetIcon(void* nsStatusItem, void* nsImage, int position, bool isTemplate);
 void systemTrayDestroy(void* nsStatusItem);
 void showMenu(void* nsStatusItem, void *nsMenu);
+void systemTraySetHighlight(void* nsStatusItem, bool highlight);
 void systemTrayGetBounds(void* nsStatusItem, NSRect *rect, void **screen);
 NSRect NSScreen_frame(void* screen);
 void windowSetScreen(void* window, void* screen, int yOffset);

v3/pkg/application/systemtray_darwin.m

@@ -140,10 +140,32 @@ void systemTrayDestroy(void* nsStatusItem) {
 	});
 }
 
+void systemTraySetHighlight(void* nsStatusItem, bool highlight) {
+	NSStatusItem *statusItem = (NSStatusItem *)nsStatusItem;
+	if (highlight) {
+		// Use dispatch_after to set highlight AFTER mouse up event clears it
+		// This is a known workaround for NSStatusBarButton highlight persistence
+		dispatch_after(dispatch_time(DISPATCH_TIME_NOW, (int64_t)(0.05 * NSEC_PER_SEC)), dispatch_get_main_queue(), ^{
+			[statusItem.button highlight:YES];
+		});
+	} else {
+		// For turning off highlight, do it immediately
+		if ([NSThread isMainThread]) {
+			[statusItem.button highlight:NO];
+		} else {
+			dispatch_async(dispatch_get_main_queue(), ^{
+				[statusItem.button highlight:NO];
+			});
+		}
+	}
+}
+
 void showMenu(void* nsStatusItem, void *nsMenu) {
 	// Show the menu on the main thread
 	dispatch_async(dispatch_get_main_queue(), ^{
 		NSStatusItem *statusItem = (NSStatusItem *)nsStatusItem;
+		// Highlight the button before showing the menu
+		[statusItem.button highlight:YES];
 		[statusItem popUpStatusItemMenu:(NSMenu *)nsMenu];
         // Post a mouse up event so the statusitem defocuses
         NSEvent *event = [NSEvent mouseEventWithType:NSEventTypeLeftMouseUp
@@ -201,25 +223,25 @@ int statusBarHeight() {
 void systemTrayPositionWindow(void* nsStatusItem, void* nsWindow, int offset) {
     // Get the status item's button
     NSStatusBarButton *button = [(NSStatusItem*)nsStatusItem button];
-    
+
     // Get the frame in screen coordinates
     NSRect frame = [button.window convertRectToScreen:button.frame];
-    
+
     // Get the screen that contains the status item
     NSScreen *screen = [button.window screen];
     if (screen == nil) {
         screen = [NSScreen mainScreen];
     }
-    
+
     // Get screen's backing scale factor (DPI)
     CGFloat scaleFactor = [screen backingScaleFactor];
-    
+
     // Get the window's frame
     NSRect windowFrame = [(NSWindow*)nsWindow frame];
-    
+
     // Calculate the horizontal position (centered under the status item)
     CGFloat windowX = frame.origin.x + (frame.size.width - windowFrame.size.width) / 2;
-    
+
     // If the window would go off the right edge of the screen, adjust it
     if (windowX + windowFrame.size.width > screen.frame.origin.x + screen.frame.size.width) {
         windowX = screen.frame.origin.x + screen.frame.size.width - windowFrame.size.width;
@@ -228,17 +250,23 @@ void systemTrayPositionWindow(void* nsStatusItem, void* nsWindow, int offset) {
     if (windowX < screen.frame.origin.x) {
         windowX = screen.frame.origin.x;
     }
-    
+
     // Get screen metrics
     NSRect screenFrame = [screen frame];
     NSRect visibleFrame = [screen visibleFrame];
-    
+
     // Calculate the vertical position
     CGFloat scaledOffset = offset * scaleFactor;
     CGFloat windowY = visibleFrame.origin.y + visibleFrame.size.height - windowFrame.size.height - scaledOffset;
-    
+
     // Set the window's frame
     windowFrame.origin.x = windowX;
     windowFrame.origin.y = windowY;
     [(NSWindow*)nsWindow setFrame:windowFrame display:YES animate:NO];
+
+    // Set window level to popup menu level so it appears above other windows
+    [(NSWindow*)nsWindow setLevel:NSPopUpMenuWindowLevel];
+
+    // Bring window to front
+    [(NSWindow*)nsWindow orderFrontRegardless];
 }

v3/pkg/application/systemtray_ios.go

@@ -100,4 +100,12 @@ func (s *iosSystemTray) Show() {
 
 func (s *iosSystemTray) Hide() {
 	// iOS doesn't have system tray
+}
+
+func (s *iosSystemTray) onAttachedWindowHidden() {
+	// iOS doesn't have system tray
+}
+
+func (s *iosSystemTray) onAttachedWindowShown() {
+	// iOS doesn't have system tray
 }

v3/pkg/application/systemtray_linux.go

@@ -751,6 +751,14 @@ func (s *linuxSystemTray) Hide() {
 	// No-op
 }
 
+func (s *linuxSystemTray) onAttachedWindowHidden() {
+	// No-op - Linux doesn't need special handling when attached window is hidden
+}
+
+func (s *linuxSystemTray) onAttachedWindowShown() {
+	// No-op - Linux doesn't need special handling when attached window is shown
+}
+
 // tooltip is our data for a tooltip property.
 // Param names need to match the generated code...
 type tooltip = struct {

v3/pkg/application/systemtray_windows.go

@@ -588,6 +588,14 @@ func (s *windowsSystemTray) Hide() {
 	}
 }
 
+func (s *windowsSystemTray) onAttachedWindowHidden() {
+	// No-op - Windows doesn't need special handling when attached window is hidden
+}
+
+func (s *windowsSystemTray) onAttachedWindowShown() {
+	// No-op - Windows doesn't need special handling when attached window is shown
+}
+
 func (s *windowsSystemTray) show() (w32.NOTIFYICONDATA, error) {
 	nid := s.newNotifyIconData()
 	nid.UFlags = w32.NIF_ICON | w32.NIF_MESSAGE