update: PredictiveBackHandler deprecation for CMP What's new 1.10

topics/whats-new/whats-new-compose-110.md

@@ -29,7 +29,7 @@ You can find the full list of changes for this release on [GitHub](https://githu
 * Savedstate library `org.jetbrains.androidx.savedstate:savedstate*:1.4.0`. Based on [Jetpack Savedstate 1.4.0](https://developer.android.com/jetpack/androidx/releases/savedstate#1.4.0)
 * WindowManager Core library `org.jetbrains.androidx.window:window-core:1.5.1`. Based on [Jetpack WindowManager 1.5.1](https://developer.android.com/jetpack/androidx/releases/window#1.5.1)
 
-## Breaking changes
+## Breaking changes and deprecations
 
 ### Deprecated dependency aliases
 
@@ -41,6 +41,63 @@ Specific references are suggested in the corresponding deprecation notices.
 This change should make dependency management for Compose Multiplatform libraries a bit more transparent.
 In the future, we hope to provide a BOM for Compose Multiplatform to simplify setting up compatible versions.
 
+### Deprecated `PredictiveBackHandler()`
+
+The `PredictiveBackHandler()` function was introduced in Compose Multiplatform to bring native Android back navigation
+gesture to other platforms.
+With the release of Navigation 3 the old implementation was made obsolete with the new [Navigation Event](https://developer.android.com/jetpack/androidx/releases/navigationevent)
+library and its APIs.
+Specifically, instead of the `PredictiveBackHandler()` function there is a new `NavigationBackHandler()` function that wraps
+the more general `NavigationEventHandler()` implementation.
+
+The simplest migration can look like this:
+
+<compare type="top-bottom">
+    <code-block lang="kotlin">
+         PredictiveBackHandler(enabled = true) { progress ->
+            try {
+                progress.collect { event ->
+                    // Animate the back gesture progress
+                }
+                // Process the completed back gesture
+            } catch(e: Exception) {
+                // Process the canceled back gesture
+            }
+        }
+    </code-block>
+    <code-block lang="kotlin">
+        // Use an empty state as a stub to satisfy the required argument
+        val navState = rememberNavigationEventState(NavigationEventInfo.None)
+        NavigationBackHandler(
+            state = navState,
+            isBackEnabled = true,
+            onBackCancelled = {
+                // Process the canceled back gesture
+            },
+            onBackCompleted = {
+              // Process the completed back gesture
+            }
+        )
+        LaunchedEffect(navState.transitionState) {
+            val transitionState = navState.transitionState
+            if (transitionState is NavigationEventTransitionState.InProgress) {
+                val progress = transitionState.latestEvent.progress
+                // Animate the back gesture progress
+            }
+        }
+    </code-block>
+</compare>
+
+Here:
+
+* The `state` parameter is mandatory: `NavigationEventInfo` is designed to hold contextual information about the UI state.
+  But if you don't have any information to store for now, you can use `NavigationEventInfo.None` as a stub.
+* The `onBack` parameter is broken up into `onBackCancelled` and `onBackCompleted` so you don't need to track canceled
+  gestures separately.
+* The `NavigationEventState.transitionState` property helps to track the progress of the physical gesture.
+
+For details on the implementation, see the [NavigationEventHandler page in the Navigation Event API reference](https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventHandler).
+
 ### Minimum Kotlin version increased for web
 
 If your project includes a web target, the latest features require upgrading to Kotlin 2.2.20.