Compose iOS accessibility support

mpd.tree

@@ -44,7 +44,10 @@
         <toc-element toc-title="Why Compose Multiplatform" href="https://www.jetbrains.com/lp/compose-multiplatform/"/>
         <toc-element id="compose-images-resources.md"/>
         <toc-element id="compose-navigation-routing.md"/>
-        <toc-element id="compose-ios-ui-integration.md" toc-title="Integration with other UI frameworks"/>
+        <toc-element toc-title="iOS specific features">
+            <toc-element id="compose-ios-ui-integration.md" toc-title="Integration with UIKit and SwiftUI"/>
+            <toc-element id="compose-ios-accessibility.md" toc-title="iOS accessibility support"/>
+        </toc-element>
         <toc-element id="compose-android-only-components.md"/>
         <toc-element toc-title="Compose Multiplatform for web" href="https://kotlinlang.org/docs/wasm-get-started.html"/>
         <toc-element id="compose-compatibility-and-versioning.md"/>

topics/compose/compose-ios-accessibility.md

@@ -0,0 +1,106 @@
+[//]: # (title: Support for iOS accessibility features)
+
+Compose Multiplatform accessibility support for iOS allows people with disabilities to interact with Compose Multiplatform UI
+as comfortably as with native UIs:
+* Screen readers and VoiceOver can access the content of the Compose Multiplatform UI.
+* Compose Multiplatform UI supports the same gestures as the native UIs for navigation and interaction.
+
+This is possible because semantics data produced by Compose APIs is now mapped to native objects and properties
+that are consumed by iOS Accessibility Services. For most interfaces built with Material widgets, this should happen
+automatically.
+
+You can also use this semantic data in testing and other automation: properties such as `testTag` will correctly map
+to native accessibility properties such as `accessibilityIdentifier`. This makes semantic data from Compose Multiplatform available
+to Accessibility Services and XCTest framework.
+
+Notable limitations of the current accessibility support:
+* Live regions (announcements about content changes in a specific area) are not supported yet.
+* [UIKit elements inside Compose Multiplatform UI](compose-ios-ui-integration.md#use-uikit-inside-compose-multiplatform)
+are not currently covered by the Compose accessibility API. 
+
+iOS accessibility support is in the early stages of development. If you have trouble with this feature,
+we would appreciate your feedback in the [#compose-ios](https://kotlinlang.slack.com/archives/C0346LWVBJ4/p1678888063176359)
+Slack channel, or as an issue in the [Compose Multiplatform GitHub repo](https://github.com/JetBrains/compose-multiplatform/issues). 
+
+## Customize accessibility tree synchronization
+
+By default, the iOS accessibility tree is synchronized with the UI only when Accessibility Services are running;
+by default, no accessibility logs are written.
+You can customize this behavior, for example, when you want to debug events and interactions:
+activate the option to always synchronize the accessibility tree, so that the tree is rewritten every time the UI updates.
+
+> Always synchronizing the tree can be quite useful for debugging and testing, but be aware that there is a significant
+> overhead associated with this. Synchronizing the tree with the UI regardless of Accessibility Services can degrade
+> the performance of your app.
+>
+> {type="tip"}
+
+Compose Multiplatform [provides APIs](#accessibility-apis) to configure the tree sync behavior:
+modify the `accessibilitySyncOptions` parameter inside the `configure` block of a `ComposeUIViewController` call:
+
+```kotlin
+ ComposeUIViewController(configure = {
+     accessibilitySyncOptions = AccessibilitySyncOptions.Always(object: AccessibilityDebugLogger {
+         override fun log(message: Any?) {
+             if (message == null) {
+                 println()
+             } else {
+                 println("[a11y]: $message")
+             }
+         }
+     })
+ }) {
+    // your @Composable content
+ }
+```
+
+## Accessibility APIs
+
+The following APIs provided by Compose Multiplatform help you customize iOS accessibility behavior.
+
+### AccessibilityDebugLogger
+
+The `AccessibilityDebugLogger` interface contains the logging function to be used for debugging:
+
+```kotlin
+// package androidx.compose.ui.platform
+
+@ExperimentalComposeApi
+interface AccessibilityDebugLogger {
+
+    // Logs the message to the debug logger, or null as a separator of log blobs
+    fun log(message: Any?)
+}
+```
+
+### AccessibilitySyncOptions
+
+The `AccessibilitySyncOptions` class contains available options for synchronizing the accessibility tree:
+
+```kotlin
+// package androidx.compose.ui.platform
+
+@ExperimentalComposeApi
+sealed class AccessibilitySyncOptions {
+
+    // Option to never synchronize the accessibility tree
+    object Never: AccessibilitySyncOptions
+
+    // Option to synchronize the tree only when Accessibility Services are running
+    //
+    // You can include an AccessibilityDebugLogger to log interactions and tree syncing events
+    class WhenRequiredByAccessibilityServices(debugLogger: AccessibilityDebugLogger?)
+
+    // Option to always synchronize the accessibility tree
+    //
+    // You can include an AccessibilityDebugLogger to log interactions and tree syncing events
+    class Always(debugLogger: AccessibilityDebugLogger?)
+}
+```
+
+## What's next?
+
+Try out the project generated by [the Kotlin Multiplatform wizard](https://kmp.jetbrains.com/) in your usual iOS accessibility workflow.
+
+Compose Multiplatform also supports [recourse qualifiers](compose-images-resources.md) that will be helpful when adapting
+a UI to a particular situation.