[Badge] Deprecate autoAdjustToGrandparentBounds attribute since now badges automatically move within first ancestor view that does not clip children

PiperOrigin-RevId: 630215388

Author: imhappi

docs/components/BadgeDrawable.md

@@ -79,7 +79,7 @@ Option 2: If you do not want `BadgeDrawable` to modify your view hierarchy, you
 can specify a `FrameLayout` to display the badge instead.
 
 ```java
-* BadgeUtils.attachBadgeDrawable(badgeDrawable, anchor, anchorFrameLayoutParent);
+BadgeUtils.attachBadgeDrawable(badgeDrawable, anchor, anchorFrameLayoutParent);
 ```
 
 ### `BadgeDrawable` Gravity Modes
@@ -90,13 +90,17 @@ of the anchor (with some offsets). Alternatively, you can use `TOP_START` to
 align the badge with the top and start edges of the anchor. Note that
 `BOTTOM_START` and `BOTTOM_END` are deprecated and not recommended for use.
 
-### `BadgeDrawable` center offsets
+### `BadgeDrawable` placement and offsets
 
 By default, `BadgeDrawable` is aligned with the top and end edges of its anchor
 view (with some offsets if `offsetAlignmentMode` is `legacy`). Call `setBadgeGravity(int)` to change it to one of the
 other supported modes. To adjust the badge's offsets relative to the anchor's
 center, use `setHorizontalOffset(int)` or `setVerticalOffset(int)`
 
+Regardless of offsets, badges are automatically moved to within the bounds of
+its first ancestor view that does not clip its children, to ensure that the
+badge is not clipped if there is enough space.
+
 ### `BadgeDrawable` Attributes
 
 | Feature                   | Relevant attributes                                                                                                                                      |
@@ -114,7 +118,6 @@ center, use `setHorizontalOffset(int)` or `setVerticalOffset(int)`
 | Horizontal Padding        | `app:badgeWidePadding`                                                                                                                                   |
 | Vertical Padding          | `app:badgeVerticalPadding`                                                                                                                               |
 | Large Font Vertical Offset| `app:largeFontVerticalOffsetAdjustment`                                                                                                                  |
-| Auto Adjust               | `app:autoAdjustToWithinGrandparentBounds`                                                                                                                |
 
 **Note:** If both `app:badgeText` and `app:number` are specified, the badge label will be `app:badgeText`.
 

lib/java/com/google/android/material/badge/BadgeDrawable.java

@@ -1078,12 +1078,15 @@ int getAdditionalVerticalOffset() {
   }
 
   /**
-   * Sets whether or not to auto adjust the badge placement to within the badge anchor's
-   * grandparent view.
+   * Sets whether or not to auto adjust the badge placement to within the badge anchor's grandparent
+   * view.
    *
-   * @param autoAdjustToWithinGrandparentBounds whether or not to auto adjust to within
-   * the anchor's grandparent view.
+   * @param autoAdjustToWithinGrandparentBounds whether or not to auto adjust to within the anchor's
+   * grandparent view.
+   * @deprecated Badges now automatically adjust their bounds within the first ancestor view that *
+   * clips its children.
    */
+  @Deprecated
   public void setAutoAdjustToWithinGrandparentBounds(boolean autoAdjustToWithinGrandparentBounds) {
     if (state.isAutoAdjustedToGrandparentBounds() == autoAdjustToWithinGrandparentBounds) {
       return;

lib/java/com/google/android/material/badge/BadgeState.java

@@ -604,10 +604,14 @@ void setNumberLocale(Locale locale) {
     currentState.numberLocale = locale;
   }
 
+  /** Deprecated; badges now adjust to within bounds of first ancestor that clips its children */
+  @Deprecated
   boolean isAutoAdjustedToGrandparentBounds() {
     return currentState.autoAdjustToWithinGrandparentBounds;
   }
 
+  /** Deprecated; badges now adjust to within bounds of first ancestor that clips its children */
+  @Deprecated
   void setAutoAdjustToGrandparentBounds(boolean autoAdjustToGrandparentBounds) {
     overridingState.autoAdjustToWithinGrandparentBounds = autoAdjustToGrandparentBounds;
     currentState.autoAdjustToWithinGrandparentBounds = autoAdjustToGrandparentBounds;

lib/java/com/google/android/material/badge/res-public/values/public.xml

@@ -37,6 +37,8 @@
   <public name="badgeShapeAppearance" type="attr"/>
   <public name="badgeWithTextShapeAppearance" type="attr"/>
   <public name="badgeShapeAppearanceOverlay" type="attr"/>
+  <!-- Deprecated. Badges are automatically moved to within first ancestor
+   that clips its children. -->
   <public name="autoAdjustToWithinGrandparentBounds" type="attr"/>
   <public name="badgeWithTextShapeAppearanceOverlay" type="attr"/>
   <public name="Widget.MaterialComponents.Badge" type="style"/>

lib/java/com/google/android/material/badge/res/values/attrs.xml

@@ -98,7 +98,8 @@
          attribute determines how much to shift the normal vertical offset by. -->
     <attr name="largeFontVerticalOffsetAdjustment" format="dimension"/>
     <!-- Automatically move the badge so it is within the anchor view's
-         grandparent's bounds. -->
+         grandparent's bounds. Deprecated, badges are now automatically moved to
+         within the first ancestor that clips its children. -->
     <attr name="autoAdjustToWithinGrandparentBounds" format="boolean"/>
   </declare-styleable>