[Lists] Add dependency to androidx.customview for ViewDragHelper and added swiped states + settling

PiperOrigin-RevId: 822221345

Author: imhappi

gradle/libs.versions.toml

@@ -16,6 +16,7 @@ androidXCore                         = "1.16.0"
 androidXComposeMaterialIconsCore     = "1.7.8"
 androidXComposeMaterialIconsExtended = "1.7.8"
 androidXComposeMaterial3             = "1.4.0-alpha14"
+androidXCustomView                   = "1.2.0"
 androidXDrawerLayout                 = "1.1.1"
 androidXDynamicAnimation             = "1.1.0"
 androidXEspresso                     = "3.1.0"
@@ -59,6 +60,7 @@ androidx-core = { group = "androidx.core", name = "core", version.ref = "android
 androidx-compose-material-icons-core = { group = "androidx.compose.material", name = "material-icons-core", version.ref = "androidXComposeMaterialIconsCore" }
 androidx-compose-material-icons-extended = { group = "androidx.compose.material", name = "material-icons-extended", version.ref = "androidXComposeMaterialIconsExtended" }
 androidx-compose-material3 = { group = "androidx.compose.material3", name = "material3", version.ref = "androidXComposeMaterial3" }
+androidx-customview = { group = "androidx.customview", name = "customview", version.ref = "androidXCustomView" }
 androidx-drawerlayout = { group = "androidx.drawerlayout", name = "drawerlayout", version.ref = "androidXDrawerLayout" }
 androidx-dynamicanimation = { group = "androidx.dynamicanimation", name = "dynamicanimation", version.ref = "androidXDynamicAnimation" }
 androidx-fragment = { group = "androidx.fragment", name = "fragment", version.ref = "androidXFragment" }

lib/build.gradle

@@ -14,6 +14,7 @@ dependencies {
   api libs.androidx.coordinatorlayout
   api libs.androidx.constraintlayout
   api libs.androidx.core
+  api libs.androidx.customview
   api libs.androidx.drawerlayout
   api libs.androidx.dynamicanimation
   api libs.androidx.fragment

lib/java/com/google/android/material/listitem/ListItemLayout.java

@@ -17,21 +17,30 @@
 
 import com.google.android.material.R;
 
+import static com.google.android.material.listitem.SwipeableListItem.STATE_CLOSED;
+import static com.google.android.material.listitem.SwipeableListItem.STATE_DRAGGING;
+import static com.google.android.material.listitem.SwipeableListItem.STATE_OPEN;
+import static com.google.android.material.listitem.SwipeableListItem.STATE_SETTLING;
 import static com.google.android.material.theme.overlay.MaterialThemeOverlay.wrap;
 import static java.lang.Math.max;
 import static java.lang.Math.min;
 
+import android.animation.TimeInterpolator;
 import android.content.Context;
 import android.util.AttributeSet;
 import android.view.GestureDetector;
 import android.view.GestureDetector.SimpleOnGestureListener;
 import android.view.MotionEvent;
 import android.view.View;
 import android.view.ViewGroup;
+import android.view.animation.Interpolator;
+import android.view.animation.PathInterpolator;
 import android.widget.FrameLayout;
 import androidx.annotation.NonNull;
 import androidx.annotation.Nullable;
 import androidx.customview.widget.ViewDragHelper;
+import com.google.android.material.listitem.SwipeableListItem.StableSwipeState;
+import com.google.android.material.listitem.SwipeableListItem.SwipeState;
 
 /**
  * A container layout for a List item.
@@ -57,6 +66,11 @@ public class ListItemLayout extends FrameLayout {
   private static final int[] MIDDLE_STATE_SET = { android.R.attr.state_middle };
   private static final int[] LAST_STATE_SET = { android.R.attr.state_last };
   private static final int[] SINGLE_STATE_SET = {android.R.attr.state_single};
+  private static final int SETTLING_DURATION = 350;
+  private static final int DEFAULT_SIGNIFICANT_VEL_THRESHOLD = 500;
+  // The overshoot that the user can swipe the reveal view by before it settles
+  // back to the closest stable swipe state.
+  private final int swipeMaxOvershoot;
 
   @Nullable private int[] positionState;
 
@@ -70,6 +84,37 @@ public class ListItemLayout extends FrameLayout {
   @Nullable private View swipeToRevealLayout;
   private boolean originalClipToPadding;
 
+  private int swipeState = STATE_CLOSED;
+  private final StateSettlingTracker stateSettlingTracker = new StateSettlingTracker();
+
+  // Cubic bezier curve approximating a spring with damping = 0.6 and stiffness = 800
+  private static final TimeInterpolator CUBIC_BEZIER_INTERPOLATOR =
+      new PathInterpolator(0.42f, 1.67f, 0.21f, 0.9f);
+
+  private class StateSettlingTracker {
+    @StableSwipeState private int targetSwipeState;
+    private boolean isContinueSettlingRunnablePosted;
+
+    private final Runnable continueSettlingRunnable =
+        () -> {
+          isContinueSettlingRunnablePosted = false;
+          if (viewDragHelper != null && viewDragHelper.continueSettling(true)) {
+            continueSettlingToState(targetSwipeState);
+          } else if (swipeState == STATE_SETTLING) {
+            setSwipeStateInternal(targetSwipeState);
+          }
+          // In other cases, settling has been interrupted by certain UX interactions. Do nothing.
+        };
+
+    private void continueSettlingToState(@StableSwipeState int targetSwipeState) {
+      this.targetSwipeState = targetSwipeState;
+      if (!isContinueSettlingRunnablePosted) {
+        post(continueSettlingRunnable);
+        isContinueSettlingRunnablePosted = true;
+      }
+    }
+  }
+
   public ListItemLayout(@NonNull Context context) {
     this(context, null);
   }
@@ -85,6 +130,8 @@ public ListItemLayout(@NonNull Context context, @Nullable AttributeSet attrs, in
   public ListItemLayout(
       @NonNull Context context, @Nullable AttributeSet attrs, int defStyleAttr, int defStyleRes) {
     super(wrap(context, attrs, defStyleAttr, defStyleRes), attrs, defStyleAttr);
+    context = getContext();
+    swipeMaxOvershoot = getResources().getDimensionPixelSize(R.dimen.m3_list_max_swipe_overshoot);
   }
 
   @Override
@@ -232,12 +279,14 @@ public int clampViewPositionHorizontal(@NonNull View child, int left, int dx) {
                       originalContentViewLeft
                           - ((RevealableListItem) swipeToRevealLayout).getIntrinsicWidth()
                           - lp.leftMargin
-                          - lp.rightMargin);
+                          - lp.rightMargin
+                          - swipeMaxOvershoot);
                 }
 
                 @Override
                 public int getViewHorizontalDragRange(@NonNull View child) {
-                  return ((RevealableListItem) swipeToRevealLayout).getIntrinsicWidth();
+                  return ((RevealableListItem) swipeToRevealLayout).getIntrinsicWidth()
+                      + swipeMaxOvershoot;
                 }
 
                 @Override
@@ -262,6 +311,33 @@ public void onViewPositionChanged(
                   ((RevealableListItem) swipeToRevealLayout)
                       .setRevealedWidth(revealViewDesiredWidth);
                 }
+
+                @Override
+                public void onViewReleased(@NonNull View releasedChild, float xvel, float yvel) {
+                  startSettling(contentView, calculateTargetSwipeState(xvel, releasedChild));
+                }
+
+                private int calculateTargetSwipeState(float xvel, View swipeView) {
+                  if (xvel > DEFAULT_SIGNIFICANT_VEL_THRESHOLD) { // A fast fling to the right
+                    return STATE_CLOSED;
+                  }
+                  if (xvel < -DEFAULT_SIGNIFICANT_VEL_THRESHOLD) { // A fast fling to the left
+                    return STATE_OPEN;
+                  }
+                  if (Math.abs(swipeView.getLeft() - getSwipeRevealViewRevealedOffset())
+                      < Math.abs(swipeView.getLeft() - getSwipeViewClosedOffset())) {
+                    // Settle to the closest point if velocity is not significant
+                    return STATE_OPEN;
+                  }
+                  return STATE_CLOSED;
+                }
+
+                @Override
+                public void onViewDragStateChanged(int state) {
+                  if (state == ViewDragHelper.STATE_DRAGGING) {
+                    setSwipeStateInternal(STATE_DRAGGING);
+                  }
+                }
               });
 
       gestureDetector =
@@ -287,6 +363,64 @@ public boolean onScroll(
     return true;
   }
 
+  private int getSwipeRevealViewRevealedOffset() {
+    if (swipeToRevealLayout == null) {
+      return 0;
+    }
+    LayoutParams lp = (LayoutParams) swipeToRevealLayout.getLayoutParams();
+    return originalContentViewLeft
+        - ((RevealableListItem) swipeToRevealLayout).getIntrinsicWidth()
+        - lp.leftMargin
+        - lp.rightMargin;
+  }
+
+  private int getSwipeViewClosedOffset() {
+    return originalContentViewLeft;
+  }
+
+  private int getOffsetForSwipeState(@StableSwipeState int swipeState) {
+    if (swipeToRevealLayout == null) {
+      throw new IllegalArgumentException(
+          "Cannot get offset for swipe without a SwipeableListItem and a RevealableListItem.");
+    }
+    switch (swipeState) {
+      case STATE_CLOSED:
+        return getSwipeViewClosedOffset();
+      case STATE_OPEN:
+        return getSwipeRevealViewRevealedOffset();
+      default:
+        throw new IllegalArgumentException("Invalid state to get swipe offset: " + swipeState);
+    }
+  }
+
+  private void startSettling(View contentView, @StableSwipeState int targetSwipeState) {
+    if (viewDragHelper == null) {
+      return;
+    }
+    int left = getOffsetForSwipeState(targetSwipeState);
+    // If we are going to the revealed state, we want to settle with a 'bounce' so we use a cubic
+    // bezier interpolator. Otherwise, we are closing and we don't want a bounce.
+    boolean settling =
+        (targetSwipeState == STATE_OPEN)
+            ? viewDragHelper.smoothSlideViewTo(
+                contentView,
+                left,
+                contentView.getTop(),
+                SETTLING_DURATION,
+                (Interpolator) CUBIC_BEZIER_INTERPOLATOR)
+            : viewDragHelper.smoothSlideViewTo(contentView, left, contentView.getTop());
+    if (settling) {
+      setSwipeStateInternal(STATE_SETTLING);
+      stateSettlingTracker.continueSettlingToState(targetSwipeState);
+    } else {
+      setSwipeStateInternal(targetSwipeState);
+    }
+  }
+
+  private void setSwipeStateInternal(@SwipeState int swipeState) {
+    this.swipeState = swipeState;
+  }
+
   @Override
   protected void onLayout(boolean changed, int left, int top, int right, int bottom) {
     super.onLayout(changed, left, top, right, bottom);

lib/java/com/google/android/material/listitem/ListItemRevealLayout.java

@@ -258,6 +258,7 @@ public int getIntrinsicWidth() {
 
   @Override
   public void setRevealedWidth(int revealedWidth) {
+    revealedWidth = max(0, revealedWidth);
     if (this.revealedWidth == revealedWidth) {
       return;
     }

lib/java/com/google/android/material/listitem/SwipeableListItem.java

@@ -15,8 +15,13 @@
  */
 package com.google.android.material.listitem;
 
+import static androidx.annotation.RestrictTo.Scope.LIBRARY_GROUP;
+
+import androidx.annotation.IntDef;
 import androidx.annotation.RestrictTo;
 import androidx.annotation.RestrictTo.Scope;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
 
 /**
  * Interface for the part of a ListItem that is able to be swiped.
@@ -25,4 +30,46 @@
  */
 @RestrictTo(Scope.LIBRARY_GROUP)
 public interface SwipeableListItem {
+  /** The state at which the {@link SwipeableListItem} is being dragged. */
+  public static final int STATE_DRAGGING = 1;
+
+  /** The state at which the {@link SwipeableListItem} is settling to the nearest settling point. */
+  public static final int STATE_SETTLING = 2;
+
+  /**
+   * The state at which the associated {@link RevealableListItem} is closed and nothing is revealed.
+   */
+  public static final int STATE_CLOSED = 3;
+
+  /**
+   * The state at which the associated {@link RevealableListItem} is revealed to its intrinsic
+   * width.
+   */
+  public static final int STATE_OPEN = 4;
+
+  /**
+   * States that the {@link SwipeableListItem} can be in.
+   *
+   * @hide
+   */
+  @RestrictTo(LIBRARY_GROUP)
+  @IntDef({
+    STATE_DRAGGING,
+    STATE_SETTLING,
+    STATE_CLOSED,
+    STATE_OPEN,
+  })
+  @Retention(RetentionPolicy.SOURCE)
+  @interface SwipeState {}
+
+  /**
+   * Stable states that the {@link SwipeableListItem} can be in. These are states that the
+   * {@link SwipeableListItem} can settle to.
+   *
+   * @hide
+   */
+  @RestrictTo(LIBRARY_GROUP)
+  @IntDef({STATE_CLOSED, STATE_OPEN})
+  @Retention(RetentionPolicy.SOURCE)
+  @interface StableSwipeState {}
 }

lib/java/com/google/android/material/listitem/res/values/dimens.xml

@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+    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.
+-->
+
+<resources>
+  <dimen name="m3_list_max_swipe_overshoot">16dp</dimen>
+</resources>