[Predictive Back] Update dev docs

PiperOrigin-RevId: 533443345
material-components · May 22, 2023 · 47c307d · 47c307d
1 parent e4d0fd3
commit 47c307d
Show file tree

Hide file tree

Showing 5 changed files with 197 additions and 7 deletions.
diff --git a/docs/components/BottomSheet.md b/docs/components/BottomSheet.md
@@ -20,6 +20,7 @@ containing supplementary content that are anchored to the bottom of the screen.
 *   [Standard bottom sheet](#standard-bottom-sheet)
 *   [Modal bottom sheet](#modal-bottom-sheet)
 *   [Anatomy and key properties](#anatomy-and-key-properties)
+*   [Predictive Back](#predictive-back)
 *   [Theming](#theming-bottom-sheets)
 
 ## Using bottom sheets
@@ -468,6 +469,81 @@ See the full list of
 and
 [themes and theme overlays](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/bottomsheet/res/values/themes.xml).
 
+## Predictive Back
+
+The modal `BottomSheetDialogFragment` and `BottomSheetDialog` components
+automatically support [Predictive Back](../foundations/PredictiveBack.md) by
+default.
+
+No further integration is required on the app side other than the general
+Predictive Back prerequisites and migration steps mentioned
+[here](../foundations/PredictiveBack.md#usage).
+
+Visit the
+[Predictive Back design guidelines](https://m3.material.io/components/bottom-sheets/guidelines#3d7735e2-73ea-4f3e-bd42-e70161fc1085)
+to see how the component will behave when a user swipes back.
+
+To set up Predictive Back for standard (non-modal) bottom sheets using
+`BottomSheetBehavior`, you can create an AndroidX back callback that forwards
+the system `BackEvent` objects to your `BottomSheetBehavior`:
+
+```java
+OnBackPressedCallback bottomSheetBackCallback = new OnBackPressedCallback(/* enabled= */ false) {
+  @RequiresApi(VERSION_CODES.UPSIDE_DOWN_CAKE)
+  @Override
+  public void handleOnBackStarted(@NonNull BackEvent backEvent) {
+    bottomSheetBehavior.startBackProgress(backEvent);
+  }
+
+  @RequiresApi(VERSION_CODES.UPSIDE_DOWN_CAKE)
+  @Override
+  public void handleOnBackProgressed(@NonNull BackEvent backEvent) {
+    bottomSheetBehavior.updateBackProgress(backEvent);
+  }
+
+  @Override
+  public void handleOnBackPressed() {
+    bottomSheetBehavior.handleBackInvoked();
+  }
+
+  @RequiresApi(VERSION_CODES.UPSIDE_DOWN_CAKE)
+  @Override
+  public void handleOnBackCancelled() {
+    bottomSheetBehavior.cancelBackProgress();
+  }
+};
+```
+
+And then you can add and enable the back callback as follows:
+
+```java
+getOnBackPressedDispatcher().addCallback(this, bottomSheetBackCallback);
+
+bottomSheetBehavior.addBottomSheetCallback(new BottomSheetCallback() {
+  @Override
+  public void onStateChanged(@NonNull View bottomSheet, int newState) {
+    switch (newState) {
+      case BottomSheetBehavior.STATE_EXPANDED:
+      case BottomSheetBehavior.STATE_HALF_EXPANDED:
+        bottomSheetBackCallback.setEnabled(true);
+        break;
+      case BottomSheetBehavior.STATE_COLLAPSED:
+      case BottomSheetBehavior.STATE_HIDDEN:
+        bottomSheetBackCallback.setEnabled(false);
+        break;
+      case BottomSheetBehavior.STATE_DRAGGING:
+      case BottomSheetBehavior.STATE_SETTLING:
+      default:
+        // Do nothing, only change callback enabled for "stable" states.
+        break;
+    }
+  }
+
+  @Override
+  public void onSlide(@NonNull View bottomSheet, float slideOffset) {}
+});
+```
+
 ## Theming bottom sheets
 
 Bottom sheets support

diff --git a/docs/components/NavigationDrawer.md b/docs/components/NavigationDrawer.md
@@ -21,6 +21,7 @@ access to destinations in your app.
 *   [Standard navigation drawer](#standard-navigation-drawer)
 *   [Modal navigation drawer](#modal-navigation-drawer)
 *   [Bottom navigation drawer](#bottom-navigation-drawer)
+*   [Predictive Back](#predictive-back)
 *   [Theming](#theming)
 
 ## Using navigation drawers
@@ -597,6 +598,20 @@ bottomSheetBehavior.addBottomSheetCallback(object : BottomSheetBehavior.BottomSh
 For more information on bottom app bars see the
 [documentation](https://github.com/material-components/material-components-android/tree/master/docs/components/BottomAppBar.md).
 
+## Predictive Back
+
+The `NavigationView` component automatically supports
+[Predictive Back](../foundations/PredictiveBack.md) by default when it is set up
+within a `DrawerLayout`, as mentioned in the sections above.
+
+No further integration is required on the app side other than the general
+Predictive Back prerequisites and migration steps mentioned
+[here](../foundations/PredictiveBack.md#usage).
+
+Visit the
+[Predictive Back design guidelines](https://m3.material.io/components/side-sheets/guidelines#d77245e3-1013-48f8-a9d7-76f484e1be13)
+to see how the component will behave when a user swipes back.
+
 ## Theming
 
 Navigation drawers support

diff --git a/docs/components/Search.md b/docs/components/Search.md
@@ -20,6 +20,7 @@ surface that allows product-specific branding and additional navigation icons.
 *   [Search Bar](#search-bar)
 *   [Search View](#search-view)
 *   [Putting it all together](#putting-it-all-together)
+*   [Predictive Back](#predictive-back)
 
 ## Using search components
 
@@ -350,6 +351,20 @@ as well as the expand and collapse animations. If you can't use a
 `CoordinatorLayout`, instead you can call the `SearchView#setUpWithSearchBar`
 method to achieve the same result.
 
+## Predictive Back
+
+The `SearchView` component automatically supports
+[Predictive Back](../foundations/PredictiveBack.md) by default when it is set up
+with and connected to a `SearchBar`, as mentioned in the sections above.
+
+No further integration is required on the app side other than the general
+Predictive Back prerequisites and migration steps mentioned
+[here](../foundations/PredictiveBack.md#usage).
+
+Visit the
+[Predictive Back design guidelines](https://m3.material.io/components/search/guidelines#3f2d4e47-2cf5-4c33-b6e1-5368ceaade55)
+to see how the component will behave when a user swipes back.
+
 ## API and source code
 
 * [Class definition](https://developer.android.com/reference/com/google/android/material/search/SearchView)

diff --git a/docs/components/SideSheet.md b/docs/components/SideSheet.md
@@ -22,6 +22,7 @@ See [Bottom Sheet documentation](BottomSheet.md) for documentation about
 *   [Modal side sheet](#modal-side-sheet)
 *   [Coplanar side sheet](#coplanar-side-sheet)
 *   [Anatomy and key properties](#anatomy-and-key-properties)
+*   [Predictive Back](#predictive-back)
 *   [Theming](#theming-side-sheets)
 
 ## Using side sheets
@@ -296,6 +297,77 @@ See the full list of
 and
 [themes and theme overlays](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/sidesheet/res/values/themes.xml).
 
+## Predictive Back
+
+The modal `SideSheetDialog` component automatically supports
+[Predictive Back](../foundations/PredictiveBack.md) by default.
+
+No further integration is required on the app side other than the general
+Predictive Back prerequisites and migration steps mentioned
+[here](../foundations/PredictiveBack.md#usage).
+
+Visit the
+[Predictive Back design guidelines](https://m3.material.io/components/side-sheets/guidelines#d77245e3-1013-48f8-a9d7-76f484e1be13)
+to see how the component will behave when a user swipes back.
+
+To set up Predictive Back for standard or coplanar (non-modal) side sheets using
+`SideSheetBehavior`, you can create an AndroidX back callback that forwards
+the system `BackEvent` objects to your `SideSheetBehavior`:
+
+```java
+OnBackPressedCallback sideSheetBackCallback = new OnBackPressedCallback(/* enabled= */ false) {
+  @RequiresApi(VERSION_CODES.UPSIDE_DOWN_CAKE)
+  @Override
+  public void handleOnBackStarted(@NonNull BackEvent backEvent) {
+    sideSheetBehavior.startBackProgress(backEvent);
+  }
+
+  @RequiresApi(VERSION_CODES.UPSIDE_DOWN_CAKE)
+  @Override
+  public void handleOnBackProgressed(@NonNull BackEvent backEvent) {
+    sideSheetBehavior.updateBackProgress(backEvent);
+  }
+
+  @Override
+  public void handleOnBackPressed() {
+    sideSheetBehavior.handleBackInvoked();
+  }
+
+  @RequiresApi(VERSION_CODES.UPSIDE_DOWN_CAKE)
+  @Override
+  public void handleOnBackCancelled() {
+    sideSheetBehavior.cancelBackProgress();
+  }
+};
+```
+
+And then you can add and enable the back callback as follows:
+
+```java
+getOnBackPressedDispatcher().addCallback(this, sideSheetBackCallback);
+
+sideSheetBehavior.addCallback(new SideSheetCallback() {
+  @Override
+  public void onStateChanged(@NonNull View sideSheet, int newState) {
+    switch (newState) {
+      case SideSheetBehavior.STATE_EXPANDED:
+      case SideSheetBehavior.STATE_SETTLING:
+        sideSheetBackCallback.setEnabled(true);
+        break;
+      case SideSheetBehavior.STATE_HIDDEN:
+        sideSheetBackCallback.setEnabled(false);
+        break;
+      case SideSheetBehavior.STATE_DRAGGING:
+      default:
+        break;
+    }
+  }
+
+  @Override
+  public void onSlide(@NonNull View sideSheet, float slideOffset) {}
+});
+```
+
 ## Theming side sheets
 
 Side sheets support

diff --git a/docs/foundations/PredictiveBack.md b/docs/foundations/PredictiveBack.md
@@ -23,8 +23,21 @@ within the app itself.
 
 ## Design & API documentation
 
--   Material Design guidelines: Predictive Back (coming soon)
+-   [Material Design guidelines: Predictive Back](https://m3.material.io/foundations/interaction/gestures#22462fb2-fbe8-4e0c-b3e7-9278bd18ea0d)
+-   [Android design guidelines](https://developer.android.com/design/ui/mobile/guides/patterns/predictive-back)
 -   [Framework & AndroidX Predictive Back developer guide](https://developer.android.com/guide/navigation/predictive-back-gesture)
+-   [Android 14 Predictive Back developer guide](https://developer.android.com/about/versions/14/features/predictive-back)
+
+## Talks
+
+-   [What's New in Android (Google I/O 2023)](https://youtu.be/qXhjN66O7Bk?t=1193)
+-   [What's New in Material Design (Google I/O 2023)](https://youtu.be/vnDhq8W98O4?t=156)
+-   [Building for the Future of Android (Google I/O 2023)](https://www.youtube.com/watch?v=WMMPXayjP8g&t=333s)
+
+## Blog Posts
+
+-   [Second Beta of Android 14](https://android-developers.googleblog.com/2023/05/android-14-beta-2.html)
+-   [Google I/O 2023: What's new in Jetpack](https://android-developers.googleblog.com/2023/05/whats-new-in-jetpack-io-2023.html)
 
 ## Usage
 
@@ -38,8 +51,7 @@ registering callbacks to handle back pressed on Android T and above. More
 details on this general back migration can be found at the
 [Framework & AndroidX Predictive Back developer guide](https://developer.android.com/guide/navigation/predictive-back-gesture).
 
-2. Upgrade to MDC-Android library version **1.10.0-alpha01 (coming soon)** or
-above.
+2. Upgrade to MDC-Android library version **1.10.0-alpha03** or above.
 
 Once completing these steps, you will get most of the predictive back animations
 within Material Components for free on Android U devices. See the section below
@@ -51,9 +63,9 @@ special considerations for each component.
 The following Material Components support predictive back behavior and
 animations:
 
-- Search bar
-- Bottom sheet
-- Side sheet (support coming soon)
-- Navigation drawer
+- [Search bar](../components/Search.md#predictive-back) (automatically for `SearchView` set up with `SearchBar`)
+- [Bottom sheet](../components/BottomSheet.md#predictive-back) (automatically for modal, standard requires integration)
+- [Side sheet](../components/SideSheet.md#predictive-back) (automatically for modal, standard and coplanar require integration)
+- [Navigation drawer](../components/NavigationDrawer.md#predictive-back) (automatically for `NavigationView` within `DrawerLayout`)
 - Navigation bar / Bottom navigation view (support coming soon)
 - Navigation rail (support coming soon)