Support isClearFocusOnMouseDownEnabled API (JetBrains#2644)

Add the `isClearFocusOnMouseDownEnabled` API, which allows you to adjust
the focus behaviour when clicking on an unfocused element with a mouse
or trackpad.
Update instrumented tests by adding ability to simulate mouse clicks.

Fixes
https://youtrack.jetbrains.com/issue/CMP-9323/Support-isClearFocusOnMouseDownEnabled-API-on-iOS

## Release Notes
### Features - iOS
- Add ability to adjust `isClearFocusOnMouseDownEnabled` in the
`configure` lambda when creating Compose components.

Author: ASalavei

compose/ui/ui/src/iosMain/kotlin/androidx/compose/ui/scene/ComposeContainer.ios.kt

@@ -217,6 +217,7 @@ internal class ComposeContainer(
 
         mediator = ComposeSceneMediator(
             onFocusBehavior = configuration.onFocusBehavior,
+            isClearFocusOnMouseDownEnabled = configuration.isClearFocusOnMouseDownEnabled,
             focusedViewsList = focusedViewsList,
             windowContext = windowContext,
             architectureComponentsOwner = architectureComponentsOwner,
@@ -304,8 +305,7 @@ internal class ComposeContainer(
                     hostCompositionLocals = { ProvideContainerCompositionLocals(it) },
                     layersViewController = layersHolder.getLayersViewController(),
                     initialLayoutDirection = layoutDirection,
-                    onFocusBehavior = configuration.onFocusBehavior,
-                    endEdgeGestureBehavior = configuration.endEdgePanGestureBehavior,
+                    configuration = configuration,
                     onAccessibilityChanged = ::onAccessibilityChanged,
                     focusedViewsList = if (focusable) focusedViewsList.childFocusedViewsList() else null,
                     compositionContext = compositionContext,

compose/ui/ui/src/iosMain/kotlin/androidx/compose/ui/scene/ComposeSceneMediator.ios.kt

@@ -184,6 +184,7 @@ private class SemanticsOwnerListenerImpl(
 
 internal class ComposeSceneMediator(
     private val onFocusBehavior: OnFocusBehavior,
+    private val isClearFocusOnMouseDownEnabled: Boolean,
     focusedViewsList: FocusedViewsList?,
     private val windowContext: PlatformWindowContext,
     private val architectureComponentsOwner: PlatformArchitectureComponentsOwner,
@@ -722,6 +723,8 @@ internal class ComposeSceneMediator(
         override val semanticsOwnerListener get() = this@ComposeSceneMediator.semanticsOwnerListener
         override val dragAndDropManager get() = this@ComposeSceneMediator.dragAndDropManager
         override val windowInsets get() = this@ComposeSceneMediator.windowInsetsManager.windowInsets
+        override val isClearFocusOnMouseDownEnabled: Boolean
+            get() = this@ComposeSceneMediator.isClearFocusOnMouseDownEnabled
 
         override var isKeepScreenOnEnabled: Boolean
             get() = UIKitIdleTimerManager.isIdleTimerDisabled

compose/ui/ui/src/iosMain/kotlin/androidx/compose/ui/scene/UIKitComposeSceneLayer.ios.kt

@@ -29,10 +29,9 @@ import androidx.compose.ui.input.pointer.PointerEventType
 import androidx.compose.ui.navigationevent.UIKitNavigationEventInput
 import androidx.compose.ui.platform.PlatformArchitectureComponentsOwner
 import androidx.compose.ui.platform.PlatformContext
-import androidx.compose.ui.uikit.EndEdgePanGestureBehavior
+import androidx.compose.ui.uikit.ComposeContainerConfiguration
 import androidx.compose.ui.uikit.InterfaceOrientation
 import androidx.compose.ui.uikit.LocalUIViewController
-import androidx.compose.ui.uikit.OnFocusBehavior
 import androidx.compose.ui.uikit.density
 import androidx.compose.ui.uikit.embedSubview
 import androidx.compose.ui.unit.Density
@@ -62,8 +61,7 @@ internal class UIKitComposeSceneLayer(
     private val layersViewController: ComposeLayersViewController,
     private val initialLayoutDirection: LayoutDirection,
     private val onAccessibilityChanged: () -> Unit,
-    onFocusBehavior: OnFocusBehavior,
-    endEdgeGestureBehavior: EndEdgePanGestureBehavior,
+    configuration: ComposeContainerConfiguration,
     private var focusedViewsList: FocusedViewsList?,
     compositionContext: CompositionContext,
     private val ownerProvider: PlatformArchitectureComponentsOwner,
@@ -93,11 +91,12 @@ internal class UIKitComposeSceneLayer(
     private val navigationEventInput = UIKitNavigationEventInput(
         density = interactionView.density,
         getTopLeftOffsetInWindow = { boundsInWindow.topLeft },
-        endEdgePanGestureBehavior = endEdgeGestureBehavior
+        endEdgePanGestureBehavior = configuration.endEdgePanGestureBehavior
     ).also { navigationEventDispatcher.addInput(it) }
 
     private val mediator = ComposeSceneMediator(
-        onFocusBehavior = onFocusBehavior,
+        onFocusBehavior = configuration.onFocusBehavior,
+        isClearFocusOnMouseDownEnabled = configuration.isClearFocusOnMouseDownEnabled,
         focusedViewsList = focusedViewsList,
         windowContext = layersViewController.windowContext,
         architectureComponentsOwner = ownerProvider,

compose/ui/ui/src/iosMain/kotlin/androidx/compose/ui/uikit/ComposeContainerConfiguration.ios.kt

@@ -16,7 +16,9 @@
 
 package androidx.compose.ui.uikit
 
+import androidx.compose.ui.ComposeUiFlags
 import androidx.compose.ui.ExperimentalComposeUiApi
+import androidx.compose.ui.isClearFocusOnMouseDownEnabled
 
 /**
  * Base configuration of the Compose container.
@@ -65,6 +67,12 @@ sealed class ComposeContainerConfiguration {
      */
     @ExperimentalComposeUiApi
     var endEdgePanGestureBehavior: EndEdgePanGestureBehavior = EndEdgePanGestureBehavior.Disabled
+
+    /**
+     * Controls whether a mouse/trackpad clicks on an unfocusable element clear focus.
+     */
+    @ExperimentalComposeUiApi
+    var isClearFocusOnMouseDownEnabled: Boolean = ComposeUiFlags.isClearFocusOnMouseDownEnabled
 }
 
 /**

compose/ui/ui/src/uikitInstrumentedTest/kotlin/androidx/compose/ui/integrations/ComposeSceneMediatorTest.kt

@@ -86,6 +86,7 @@ class ComposeSceneMediatorTest {
     private fun makeMediator(): ComposeSceneMediator {
         val mediator = ComposeSceneMediator(
             onFocusBehavior = OnFocusBehavior.DoNothing,
+            isClearFocusOnMouseDownEnabled = false,
             focusedViewsList = null,
             windowContext = PlatformWindowContext(),
             architectureComponentsOwner = DefaultArchitectureComponentsOwner(),

compose/ui/ui/src/uikitInstrumentedTest/kotlin/androidx/compose/ui/interaction/BasicInteractionTest.kt

@@ -19,14 +19,19 @@ import androidx.compose.foundation.layout.safeDrawingPadding
 import androidx.compose.foundation.layout.size
 import androidx.compose.foundation.text.BasicTextField
 import androidx.compose.foundation.text.input.TextFieldState
+import androidx.compose.foundation.text.input.rememberTextFieldState
 import androidx.compose.foundation.verticalScroll
 import androidx.compose.material.Button
 import androidx.compose.material.Text
 import androidx.compose.material.TextField
+import androidx.compose.runtime.LaunchedEffect
 import androidx.compose.runtime.MutableState
 import androidx.compose.runtime.mutableStateOf
 import androidx.compose.ui.Alignment
 import androidx.compose.ui.Modifier
+import androidx.compose.ui.focus.FocusRequester
+import androidx.compose.ui.focus.focusRequester
+import androidx.compose.ui.focus.onFocusChanged
 import androidx.compose.ui.graphics.Color
 import androidx.compose.ui.input.pointer.PointerEventPass
 import androidx.compose.ui.input.pointer.changedToDown
@@ -303,6 +308,84 @@ class BasicInteractionTest {
         }
     }
 
+    @Test
+    fun testComposePanelClearFocusOnMouseDownEnabledFlag() = runUIKitInstrumentedTest {
+        val focusRequester = FocusRequester()
+        var textFieldIsFocused = false
+
+        setContent(
+            configure = {
+                isClearFocusOnMouseDownEnabled = true
+            }
+        ) {
+            Column {
+                BasicTextField(
+                    state = rememberTextFieldState(),
+                    modifier = Modifier
+                        .focusRequester(focusRequester)
+                        .onFocusChanged {
+                            textFieldIsFocused = it.isFocused
+                        }
+                )
+                Box(Modifier.size(100.dp).testTag("box"))
+            }
+            LaunchedEffect(Unit) {
+                focusRequester.requestFocus()
+            }
+        }
+
+        assertTrue(textFieldIsFocused)
+
+        // No focus changes after tap
+        findNodeWithTag("box").tap()
+        waitForIdle()
+        assertTrue(textFieldIsFocused)
+
+        // Clear focus on a click
+        findNodeWithTag("box").click()
+        waitForIdle()
+        assertFalse(textFieldIsFocused)
+    }
+
+    @Test
+    fun testComposePanelClearFocusOnMouseDownDisabledFlag() = runUIKitInstrumentedTest {
+        val focusRequester = FocusRequester()
+        var textFieldIsFocused = false
+
+        setContent(
+            configure = {
+                isClearFocusOnMouseDownEnabled = false
+            }
+        ) {
+            Column {
+                BasicTextField(
+                    state = rememberTextFieldState(),
+                    modifier = Modifier
+                        .focusRequester(focusRequester)
+                        .onFocusChanged {
+                            textFieldIsFocused = it.isFocused
+                        }
+                )
+                Box(Modifier.size(100.dp).testTag("box"))
+            }
+            LaunchedEffect(Unit) {
+                focusRequester.requestFocus()
+            }
+        }
+
+        assertTrue(textFieldIsFocused)
+
+        // No focus changes after tap
+        findNodeWithTag("box").tap()
+        waitForIdle()
+        assertTrue(textFieldIsFocused)
+
+        // No focus changes after click
+        findNodeWithTag("box").click()
+        waitForIdle()
+        assertTrue(textFieldIsFocused)
+    }
+
     private fun UIKitInstrumentedTest.openToolbar(textFieldTag: String) {
         findNodeWithTag(textFieldTag).tap()
         delay(500)

compose/ui/ui/src/uikitInstrumentedTest/kotlin/androidx/compose/ui/test/UIKitInstrumentedTest.kt

@@ -23,6 +23,7 @@ import androidx.compose.ui.scene.ComposeHostingView
 import androidx.compose.ui.scene.ComposeHostingViewController
 import androidx.compose.ui.test.utils.center
 import androidx.compose.ui.test.utils.getTouchesEvent
+import androidx.compose.ui.test.utils.mouseDown
 import androidx.compose.ui.test.utils.moveToLocationOnWindow
 import androidx.compose.ui.test.utils.resetTouches
 import androidx.compose.ui.test.utils.toCGPoint
@@ -291,15 +292,34 @@ internal class UIKitInstrumentedTest(
             toView = appDelegate.window()
         )
 
-        val targetWindow = window ?: appDelegate.window()!!
+        return getTargetWindow(position, window).touchDown(positionOnWindow.asDpOffset())
+    }
+
+    /**
+     * Simulates a mouse-down event at the specified position on the screen.
+     *
+     * @param position The position on the root hosting controller.
+     * @param window will be used to handle mouse/trackpad click; otherwise,
+     * the window hosting the view will be used.
+     * @return A UITouch object representing the mouse/trackpad interaction.
+     */
+    fun mouseDown(position: DpOffset, window: UIWindow? = null): UITouch {
+        val positionOnWindow = viewController.view.convertPoint(
+            point = position.toCGPoint(),
+            toView = appDelegate.window()
+        )
+
+        return getTargetWindow(position, window).mouseDown(positionOnWindow.asDpOffset())
+    }
+
+    private fun getTargetWindow(position: DpOffset, window: UIWindow? = null): UIWindow {
+        return window ?: appDelegate.window()!!
             .windowScene!!
             .windows
             .findLast {
                 it as UIWindow
                 it.hitTest(position.toCGPoint(), it.getTouchesEvent()) != null
             } as UIWindow
-
-        return targetWindow.touchDown(positionOnWindow.asDpOffset())
     }
 
     /**
@@ -311,6 +331,15 @@ internal class UIKitInstrumentedTest(
         return touchDown(position).up()
     }
 
+    /**
+     * Simulates a click gesture at the specified position on the screen.
+     *
+     * @param position The position on the root hosting controller.
+     */
+    fun click(position: DpOffset) {
+        return mouseDown(position).up()
+    }
+
     /**
      * Simulates a tap gesture for a given AccessibilityTestNode.
      */
@@ -319,6 +348,14 @@ internal class UIKitInstrumentedTest(
         return tap(frame.center())
     }
 
+    /**
+     * Simulates a trackpad click gesture for a given AccessibilityTestNode.
+     */
+    fun AccessibilityTestNode.click() {
+        val frame = frame ?: error("Internal error. Frame is missing.")
+        return click(frame.center())
+    }
+
     fun AccessibilityTestNode.doubleTap() {
         val frame = frame ?: error("Internal error. Frame is missing.")
         tap(frame.center())

compose/ui/ui/src/uikitInstrumentedTest/kotlin/androidx/compose/ui/test/utils/UITouch+Utils.kt

@@ -28,12 +28,28 @@ import kotlinx.cinterop.ExperimentalForeignApi
 import platform.UIKit.UIEvent
 import platform.UIKit.UITouch
 import platform.UIKit.UITouchPhase
+import platform.UIKit.UITouchTypeDirect
+import platform.UIKit.UITouchTypeIndirect
 import platform.UIKit.UIWindow
 
 @OptIn(ExperimentalForeignApi::class)
 internal fun UIWindow.touchDown(location: DpOffset): UITouch {
     return UITouch.touchAtPoint(
         point = location.toCGPoint(),
+        withType = UITouchTypeDirect,
+        inWindow = this,
+        tapCount = 1L,
+        fromEdge = false
+    ).also {
+        it.send()
+    }
+}
+
+@OptIn(ExperimentalForeignApi::class)
+internal fun UIWindow.mouseDown(location: DpOffset): UITouch {
+    return UITouch.touchAtPoint(
+        point = location.toCGPoint(),
+        withType = UITouchTypeIndirect,
         inWindow = this,
         tapCount = 1L,
         fromEdge = false

testutils/testutils-xctest/src/iosMain/objc/CMPTestUtils/UITouch+Test.h

@@ -21,6 +21,7 @@ NS_ASSUME_NONNULL_BEGIN
 @interface UITouch (CMPTest)
 
 + (instancetype)touchAtPoint:(CGPoint)point
+                    withType:(UITouchType)type
                     inWindow:(UIWindow *)window
                     tapCount:(NSInteger)tapCount
                     fromEdge:(BOOL)fromEdge;

testutils/testutils-xctest/src/iosMain/objc/CMPTestUtils/UITouch+Test.m

@@ -86,6 +86,7 @@ - (void)setGestureView:(UIView *)view;
 - (void)_setLocationInWindow:(CGPoint)location resetPrevious:(BOOL)resetPrevious;
 - (void)_setIsFirstTouchForView:(BOOL)firstTouchForView;
 - (void)_setIsTapToClick:(BOOL)tapToClick;
+- (void)_setType:(UITouchType)type;
 
 - (void)_setHidEvent:(IOHIDEventPtr)event;
 - (void)_setEdgeType:(NSInteger)edgeType;
@@ -98,10 +99,15 @@ - (UITouchPhase)phase;
 @implementation UITouch (CMPTest)
 
 + (instancetype)touchAtPoint:(CGPoint)point
+                    withType:(UITouchType)type
                     inWindow:(UIWindow *)window
                     tapCount:(NSInteger)tapCount
                     fromEdge:(BOOL)fromEdge {
-    return [[UITouch alloc] initAtPoint:point inWindow:window tapCount:tapCount fromEdge:fromEdge];
+    return [[UITouch alloc] initAtPoint:point
+                               withType:type
+                               inWindow:window
+                               tapCount:tapCount
+                               fromEdge:fromEdge];
 }
 
 + (UIEvent *)getTouchesEvent {
@@ -112,7 +118,11 @@ + (void)endAllTouches {
     [CMPActiveTouchesHolder.shared.touches removeAllObjects];
 }
 
-- (id)initAtPoint:(CGPoint)point inWindow:(UIWindow *)window tapCount:(NSInteger)tapCount fromEdge:(BOOL)fromEdge {
+- (id)initAtPoint:(CGPoint)point
+         withType:(UITouchType)type
+         inWindow:(UIWindow *)window
+         tapCount:(NSInteger)tapCount
+         fromEdge:(BOOL)fromEdge {
 	self = [super init];
     if (self) {
         UIView *hitTestView = [window hitTest:point withEvent:[[UIApplication sharedApplication] _touchesEvent]];
@@ -122,6 +132,7 @@ - (id)initAtPoint:(CGPoint)point inWindow:(UIWindow *)window tapCount:(NSInteger
         [self setTapCount:tapCount];
         [self _setLocationInWindow:point resetPrevious:YES];
         [self setPhase:UITouchPhaseBegan];
+        [self _setType:type];
         [self _setEdgeType:fromEdge ? 4 : 0];
         [self _setIsFirstTouchForView:YES];