Allow specifying AWT AccessibleRole directly (#2577)

Author: m-sasha

compose/ui/ui/src/desktopMain/kotlin/androidx/compose/ui/platform/a11y/ComposeAccessible.kt

@@ -21,6 +21,7 @@ import androidx.compose.ui.geometry.Rect
 import androidx.compose.ui.node.Nodes
 import androidx.compose.ui.node.requireCoordinator
 import androidx.compose.ui.semantics.AccessibilityAction
+import androidx.compose.ui.semantics.DesktopSemanticsProperties
 import androidx.compose.ui.semantics.ProgressBarRangeInfo
 import androidx.compose.ui.semantics.Role
 import androidx.compose.ui.semantics.SemanticsActions
@@ -311,12 +312,11 @@ internal class ComposeAccessible(
         }
 
         override fun getAccessibleValue(): AccessibleValue? {
-            val role = semanticsConfig.getOrNull(SemanticsProperties.Role)
             // On macOS/VoiceOver, the a11y system appears to inspect the value we return here for
             // checkboxes and radio buttons. On Windows, it looks at getAccessibleStateSet instead.
             return when {
                 toggleableState != null -> ToggleableAccessibleValue(this)
-                role == Role.RadioButton -> RadioButtonAccessibleValue(this)
+                computeAccessibleRole() == AccessibleRole.RADIO_BUTTON -> RadioButtonAccessibleValue(this)
                 progressBarRangeInfo != null -> ProgressBarAccessibleValue(this)
                 else -> null
             }
@@ -420,19 +420,26 @@ internal class ComposeAccessible(
 
         // -----------------------------------
 
-        override fun getAccessibleRole(): AccessibleRole {
-            AccessibilityController.AccessibilityUsage.notifyInUse()
-            val fromSemanticRole = when (semanticsConfig.getOrNull(SemanticsProperties.Role)) {
+        private fun computeAccessibleRole(): AccessibleRole {
+            // AWT role takes precedence
+            semanticsConfig.getOrNull(DesktopSemanticsProperties.AwtRole)?.let {
+                return it
+            }
+
+            // Check semantics role
+            val role = semanticsConfig.getOrNull(SemanticsProperties.Role)
+            val accessibleRole = when (role) {
                 Role.Button -> AccessibleRole.PUSH_BUTTON
                 Role.Checkbox, Role.Switch -> AccessibleRole.CHECK_BOX
                 Role.RadioButton -> AccessibleRole.RADIO_BUTTON
                 Role.Tab -> AccessibleRole.PAGE_TAB
                 Role.DropdownList -> AccessibleRole.COMBO_BOX
                 else -> null
             }
+            if (accessibleRole != null) return accessibleRole
 
+            // Guess role from other semantics properties
             return when {
-                fromSemanticRole != null -> fromSemanticRole
                 isPassword -> AccessibleRole.PASSWORD_TEXT
                 setText != null -> AccessibleRole.TEXT
                 scrollBy != null -> AccessibleRole.SCROLL_PANE
@@ -449,6 +456,11 @@ internal class ComposeAccessible(
             }
         }
 
+        override fun getAccessibleRole(): AccessibleRole {
+            AccessibilityController.AccessibilityUsage.notifyInUse()
+            return computeAccessibleRole()
+        }
+
         override fun getAccessibleStateSet(): AccessibleStateSet {
             return AccessibleStateSet().apply {
                 // can we support these
@@ -480,12 +492,12 @@ internal class ComposeAccessible(
                 if (canCollapse)
                     add(AccessibleState.EXPANDED)
 
-                when (semanticsConfig.getOrNull(SemanticsProperties.Role)) {
+                when (computeAccessibleRole()) {
                     // Note that this is not executed on macOS (for checkboxes or radio buttons),
                     // where the system inspects the value returned by getAccessibleValue instead.
-                    Role.Checkbox, Role.Switch -> addCheckedStateForCheckboxOrSwitch()
-                    Role.RadioButton -> addCheckedStateForRadioButton()
-                    else -> {  // Default case, for other (possibly null) roles
+                    AccessibleRole.CHECK_BOX -> addCheckedStateForCheckboxOrSwitch()
+                    AccessibleRole.RADIO_BUTTON -> addCheckedStateForRadioButton()
+                    else -> {  // Default case for other roles
                         addDefaultStateForToggleableState()
 
                         if (selected != null)

compose/ui/ui/src/desktopMain/kotlin/androidx/compose/ui/semantics/SemanticsProperties.desktop.kt

@@ -0,0 +1,42 @@
+/*
+ * Copyright 2025 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package androidx.compose.ui.semantics
+
+import androidx.compose.ui.ExperimentalComposeUiApi
+import javax.accessibility.AccessibleRole
+
+
+/**
+ * Extra semantics properties specific to the desktop.
+ */
+internal object DesktopSemanticsProperties {
+
+    /** @see SemanticsPropertyReceiver.awtRole */
+    val AwtRole = AccessibilityKey<AccessibleRole>("AwtRole") { parentValue, _ -> parentValue }
+
+}
+
+/**
+ * Specifies directly the [AccessibleRole] reported to AWT for the element.
+ *
+ * This should only be used for roles that are not supported by Compose's [Role].
+ * Note that this overrides the role specified by [SemanticsPropertyReceiver.role], if any.
+ *
+ * @see SemanticsPropertyReceiver.role
+ */
+@ExperimentalComposeUiApi
+var SemanticsPropertyReceiver.awtRole by DesktopSemanticsProperties.AwtRole

compose/ui/ui/src/desktopTest/kotlin/androidx/compose/ui/platform/AccessibilityTest.kt

@@ -40,6 +40,7 @@ import androidx.compose.ui.platform.a11y.ComposeSceneAccessible
 import androidx.compose.ui.semantics.Role
 import androidx.compose.ui.semantics.SemanticsNode
 import androidx.compose.ui.semantics.SemanticsOwner
+import androidx.compose.ui.semantics.awtRole
 import androidx.compose.ui.semantics.contentDescription
 import androidx.compose.ui.semantics.hideFromAccessibility
 import androidx.compose.ui.semantics.isContainer
@@ -466,6 +467,23 @@ class AccessibilityTest {
         assertNodeWithTagIndexInParentIs("item2", 2)
         assertNodeWithTagIndexInParentIs("item3", 1)
     }
+
+    @Test
+    fun awtRoleIsCorrect() = runDesktopA11yTest {
+        test.setContent {
+            Box(
+                Modifier
+                    .testTag("button")
+                    .size(100.dp)
+                    .semantics {
+                        awtRole = AccessibleRole.PUSH_BUTTON
+                    }
+            )
+        }
+
+        assertThat(test.onNodeWithTag("button").fetchAccessible().accessibleContext?.accessibleRole)
+            .isEqualTo(AccessibleRole.PUSH_BUTTON)
+    }
 }