Add TrayWindowDismissMode to control auto/manual dismiss behavior in TrayApp

- Introduced `TrayWindowDismissMode` enum to support `AUTO` and `MANUAL` dismiss modes for tray windows.
- Updated `TrayAppState` to manage dismiss mode alongside visibility and size.
- Refactored visibility handlers to respect `TrayWindowDismissMode`, enabling explicit dismiss in `MANUAL` mode.
- Improved focus loss and outside-click behavior to honor dismiss mode settings.
- Enhanced inline comments and streamlined state-handling logic across `TrayApp`.

Author: kdroidFilter

src/commonMain/kotlin/com/kdroid/composetray/tray/api/TrayApp.kt

@@ -290,12 +290,15 @@ fun ApplicationScope.TrayApp(
     // Create or use provided state
     val trayAppState = state ?: rememberTrayAppState(
         initialWindowSize = windowSize ?: DpSize(300.dp, 200.dp),
-        initiallyVisible = visibleOnStart
+        initiallyVisible = visibleOnStart,
+        // Default remains AUTO to keep backward compatibility
+        initialDismissMode = TrayWindowDismissMode.AUTO
     )
 
     // Collect state flows
     val isVisible by trayAppState.isVisible.collectAsState()
     val currentWindowSize by trayAppState.windowSize.collectAsState()
+    val dismissMode by trayAppState.dismissMode.collectAsState()
 
     var shouldShowWindow by remember { mutableStateOf(false) }
 
@@ -351,8 +354,9 @@ fun ApplicationScope.TrayApp(
         dialogState.size = currentWindowSize
     }
 
-    // Helper to request hide with a minimum visible duration guard
-    val requestHide: () -> Unit = {
+    // Helper to request hide with a minimum visible duration guard.
+    // NOTE: This is used for explicit hide (tray click toggle or programmatic hide).
+    val requestHideExplicit: () -> Unit = {
         val now = System.currentTimeMillis()
         val sinceShow = now - lastShownAt
         if (sinceShow >= minVisibleDurationMs) {
@@ -375,8 +379,8 @@ fun ApplicationScope.TrayApp(
             lastPrimaryActionAt = now
 
             if (isVisible) {
-                // Simplified hide logic for primary action
-                requestHide()
+                // Explicit hide (works both in AUTO and MANUAL)
+                requestHideExplicit()
             } else {
                 if (now - lastHiddenAt >= minHiddenDurationMs) {
                     if (os == WINDOWS && (now - lastFocusLostAt) < 300) {
@@ -390,7 +394,7 @@ fun ApplicationScope.TrayApp(
         }
     }
 
-    // FIX: Consolidated visibility handling with position calculation BEFORE showing the window.
+    // Consolidated visibility handling with position calculation BEFORE showing the window.
     LaunchedEffect(isVisible) {
         if (isVisible) {
             if (!shouldShowWindow) {
@@ -406,7 +410,6 @@ fun ApplicationScope.TrayApp(
                     )
                     delay(150)
                 }
-                // If still default after timeout, proceed anyway to avoid invisible window
                 dialogState.position = position
 
                 if (os == WINDOWS) {
@@ -445,7 +448,7 @@ fun ApplicationScope.TrayApp(
 
     // Invisible helper window (Compose requirement on some platforms)
     DialogWindow(
-        onCloseRequest = { },
+        onCloseRequest = { /* noop */ },
         visible = false,
         state = rememberDialogState(
             size = DpSize(1.dp, 1.dp),
@@ -459,7 +462,8 @@ fun ApplicationScope.TrayApp(
 
     // === Main popup window (ALWAYS MOUNTED) ===
     DialogWindow(
-        onCloseRequest = { requestHide() },
+        // Closing the popup via OS/ESC is considered explicit user intent → allowed in MANUAL
+        onCloseRequest = { requestHideExplicit() },
         title = "",
         undecorated = true,
         resizable = false,
@@ -469,8 +473,9 @@ fun ApplicationScope.TrayApp(
         visible = shouldShowWindow,
         state = dialogState,
     ) {
-        // Attach/Detach platform listeners only while window is actually visible
-        DisposableEffect(shouldShowWindow) {
+        // Attach/Detach platform listeners only while window is visible OR when mode changes.
+        // Including dismissMode in the key ensures watchers reconfigure when switching AUTO <-> MANUAL.
+        DisposableEffect(shouldShowWindow, dismissMode) {
             if (!shouldShowWindow) {
                 onDispose { }
                 return@DisposableEffect onDispose { }
@@ -479,43 +484,43 @@ fun ApplicationScope.TrayApp(
             // Mark this as the tray popup (macOS visibility monitor)
             try {
                 window.name = WindowVisibilityMonitor.TRAY_DIALOG_NAME
-            } catch (_: Throwable) {
-            }
+            } catch (_: Throwable) { }
             runCatching { WindowVisibilityMonitor.recompute() }
 
             // Bring to front on open
             invokeLater {
-                try {
+                runCatching {
                     window.toFront()
                     window.requestFocus()
                     window.requestFocusInWindow()
-                } catch (_: Throwable) {
                 }
             }
 
+            // Focus listener: auto-hide only if AUTO mode
             val focusListener = object : WindowFocusListener {
                 override fun windowGainedFocus(e: WindowEvent?) = Unit
                 override fun windowLostFocus(e: WindowEvent?) {
                     lastFocusLostAt = System.currentTimeMillis()
-                    if (os == WINDOWS && lastFocusLostAt < autoHideEnabledAt) {
-                        // Ignore focus loss during startup grace period on Windows
-                        return
+                    if (os == WINDOWS && lastFocusLostAt < autoHideEnabledAt) return
+                    if (dismissMode == TrayWindowDismissMode.AUTO) {
+                        // Auto dismiss on focus loss
+                        requestHideExplicit()
                     }
-                    requestHide()
                 }
             }
 
-            val macWatcher = if (getOperatingSystem() == MACOS) {
+            // Outside click watchers: start them only in AUTO mode
+            val macWatcher = if (dismissMode == TrayWindowDismissMode.AUTO && getOperatingSystem() == MACOS) {
                 MacOutsideClickWatcher(
                     windowSupplier = { window },
-                    onOutsideClick = { invokeLater { requestHide() } }
+                    onOutsideClick = { invokeLater { requestHideExplicit() } }
                 ).also { it.start() }
             } else null
 
-            val linuxWatcher = if (getOperatingSystem() == OperatingSystem.LINUX) {
+            val linuxWatcher = if (dismissMode == TrayWindowDismissMode.AUTO && getOperatingSystem() == OperatingSystem.LINUX) {
                 LinuxOutsideClickWatcher(
                     windowSupplier = { window },
-                    onOutsideClick = { invokeLater { requestHide() } }
+                    onOutsideClick = { invokeLater { requestHideExplicit() } }
                 ).also { it.start() }
             } else null
 
@@ -536,4 +541,4 @@ fun ApplicationScope.TrayApp(
                 .alpha(alpha)
         ) { content() }
     }
-}
+}

src/commonMain/kotlin/com/kdroid/composetray/tray/api/TrayAppState.kt

@@ -1,6 +1,8 @@
 package com.kdroid.composetray.tray.api
 
-import androidx.compose.runtime.*
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.ExperimentalComposeApi
+import androidx.compose.runtime.remember
 import androidx.compose.ui.unit.DpSize
 import androidx.compose.ui.unit.dp
 import kotlinx.coroutines.flow.MutableStateFlow
@@ -9,82 +11,71 @@ import kotlinx.coroutines.flow.asStateFlow
 
 /**
  * State holder for TrayApp that provides programmatic control over the tray window
- * and observability of its state changes.
+ * and observability of its state changes, including window dismiss behavior.
  */
 @ExperimentalTrayAppApi
 class TrayAppState(
     initialWindowSize: DpSize = DpSize(300.dp, 200.dp),
-    initiallyVisible: Boolean = false
+    initiallyVisible: Boolean = false,
+    initialDismissMode: TrayWindowDismissMode = TrayWindowDismissMode.AUTO,
 ) {
     // Internal mutable state
     private val _isVisible = MutableStateFlow(initiallyVisible)
     private val _windowSize = MutableStateFlow(initialWindowSize)
-    
+    private val _dismissMode = MutableStateFlow(initialDismissMode)
+
     // Public observable state flows
     val isVisible: StateFlow<Boolean> = _isVisible.asStateFlow()
     val windowSize: StateFlow<DpSize> = _windowSize.asStateFlow()
-    
-    // Callbacks for visibility changes
+    val dismissMode: StateFlow<TrayWindowDismissMode> = _dismissMode.asStateFlow()
+
+    // Callback for visibility changes
     private var onVisibilityChanged: ((Boolean) -> Unit)? = null
-    
-    /**
-     * Shows the tray window
-     */
+
+    /** Shows the tray window */
     fun show() {
         if (!_isVisible.value) {
             _isVisible.value = true
             onVisibilityChanged?.invoke(true)
         }
     }
-    
-    /**
-     * Hides the tray window
-     */
+
+    /** Hides the tray window (explicit hide, works in any dismiss mode) */
     fun hide() {
         if (_isVisible.value) {
             _isVisible.value = false
             onVisibilityChanged?.invoke(false)
         }
     }
-    
-    /**
-     * Toggles the visibility of the tray window
-     */
+
+    /** Toggles the visibility of the tray window */
     fun toggle() {
         val newVisibility = !_isVisible.value
         _isVisible.value = newVisibility
         onVisibilityChanged?.invoke(newVisibility)
     }
-    
-    /**
-     * Updates the window size
-     * @param size The new window size
-     */
+
+    /** Updates the window size */
     fun setWindowSize(size: DpSize) {
         _windowSize.value = size
     }
-    
-    /**
-     * Updates the window size
-     * @param width The new window width
-     * @param height The new window height
-     */
+
+    /** Updates the window size */
     fun setWindowSize(width: androidx.compose.ui.unit.Dp, height: androidx.compose.ui.unit.Dp) {
         _windowSize.value = DpSize(width, height)
     }
-    
-    /**
-     * Sets a callback to be invoked when visibility changes
-     * @param callback The callback to invoke with the new visibility state
-     */
+
+    /** Updates the dismiss mode (AUTO or MANUAL) */
+    fun setDismissMode(mode: TrayWindowDismissMode) {
+        _dismissMode.value = mode
+    }
+
+    /** Sets a callback to be invoked when visibility changes */
     fun onVisibilityChanged(callback: (Boolean) -> Unit) {
         onVisibilityChanged = callback
     }
-    
-    /**
-     * Internal method to update visibility from within TrayApp
-     * (e.g., when user clicks outside or closes the window)
-     */
+
+    /** Internal method to update visibility from TrayApp internals */
     internal fun updateVisibility(visible: Boolean) {
         if (_isVisible.value != visible) {
             _isVisible.value = visible
@@ -93,21 +84,19 @@ class TrayAppState(
     }
 }
 
-/**
- * Creates and remembers a TrayAppState instance
- * @param initialWindowSize The initial window size
- * @param initiallyVisible Whether the window should be initially visible
- */
+/** Creates and remembers a TrayAppState instance */
 @ExperimentalTrayAppApi
 @Composable
 fun rememberTrayAppState(
     initialWindowSize: DpSize = DpSize(300.dp, 200.dp),
-    initiallyVisible: Boolean = false
+    initiallyVisible: Boolean = false,
+    initialDismissMode: TrayWindowDismissMode = TrayWindowDismissMode.AUTO,
 ): TrayAppState {
     return remember {
         TrayAppState(
             initialWindowSize = initialWindowSize,
-            initiallyVisible = initiallyVisible
+            initiallyVisible = initiallyVisible,
+            initialDismissMode = initialDismissMode
         )
     }
-}
+}

src/commonMain/kotlin/com/kdroid/composetray/tray/api/TrayWindowDismissMode.kt

@@ -0,0 +1,20 @@
+package com.kdroid.composetray.tray.api
+
+/**
+ * Defines how the tray window should be dismissed (hidden)
+ */
+@ExperimentalTrayAppApi
+enum class TrayWindowDismissMode {
+    /**
+     * The window automatically hides when it loses focus or when clicking outside.
+     * This is the traditional behavior for tray popup windows.
+     */
+    AUTO,
+    
+    /**
+     * The window remains visible until explicitly hidden via TrayAppState.hide()
+     * or by clicking the tray icon again.
+     * Focus loss and outside clicks do not dismiss the window.
+     */
+    MANUAL
+}