Merge branch 'master' into release-1.10

material-components · Jun 28, 2023 · 543c473 · 543c473
2 parents fc6f0a2 + 174a57d
commit 543c473
Show file tree

Hide file tree

Showing 59 changed files with 2,484 additions and 563 deletions.
diff --git a/build.gradle b/build.gradle
@@ -22,7 +22,7 @@ ext {
   targetSdkVersion = 33
 
   androidXVersions = [
-    activity                     : '1.8.0-alpha05',
+    activity                     : '1.8.0-alpha06',
     annotation                   : '1.2.0',
     appCompat                    : '1.6.1',
     cardView                     : '1.0.0',
@@ -58,7 +58,7 @@ ext {
     ? project.property('mavenRepoUrl') : '/tmp/myRepo/')
 
   // Current version of the library (could be in-development/unreleased).
-  mdcLibraryVersion = '1.10.0-alpha04'
+  mdcLibraryVersion = '1.10.0-alpha05'
   mdcLibraryPackage = "com.google.android.material"
   mdcLibraryDir = "com/google/android/material"
 }

diff --git a/catalog/build.gradle b/catalog/build.gradle
@@ -16,7 +16,7 @@ dependencies {
   api 'androidx.constraintlayout:constraintlayout:2.1.0'
   api 'androidx.gridlayout:gridlayout:1.0.0'
   api "androidx.multidex:multidex:2.0.1"
-  api "androidx.activity:activity:1.8.0-alpha05"
+  api "androidx.activity:activity:1.8.0-alpha06"
   api "androidx.recyclerview:recyclerview:1.2.1"
   api 'androidx.window:window:1.0.0-beta04'
   api "androidx.window:window-java:1.0.0-beta04"

diff --git a/catalog/java/io/material/catalog/bottomnav/BottomNavigationDemoFragment.java b/catalog/java/io/material/catalog/bottomnav/BottomNavigationDemoFragment.java
@@ -50,8 +50,6 @@ public abstract class BottomNavigationDemoFragment extends DemoFragment {
       new int[] {
         BadgeDrawable.TOP_END,
         BadgeDrawable.TOP_START,
-        BadgeDrawable.BOTTOM_END,
-        BadgeDrawable.BOTTOM_START
       };
 
   private int numVisibleChildren = 3;

diff --git a/catalog/java/io/material/catalog/bottomnav/res/values/arrays.xml b/catalog/java/io/material/catalog/bottomnav/res/values/arrays.xml
@@ -19,7 +19,5 @@
   <string-array name="cat_bottom_nav_badge_gravity_titles">
     <item>@string/cat_bottom_nav_badge_gravity_top_end</item>
     <item>@string/cat_bottom_nav_badge_gravity_top_start</item>
-    <item>@string/cat_bottom_nav_badge_gravity_bottom_end</item>
-    <item>@string/cat_bottom_nav_badge_gravity_bottom_start</item>
   </string-array>
 </resources>
diff --git a/catalog/java/io/material/catalog/bottomnav/res/values/strings.xml b/catalog/java/io/material/catalog/bottomnav/res/values/strings.xml
@@ -53,8 +53,6 @@
 
   <string name="cat_bottom_nav_badge_gravity_top_end">Top end</string>
   <string name="cat_bottom_nav_badge_gravity_top_start">Top start</string>
-  <string name="cat_bottom_nav_badge_gravity_bottom_end">Bottom end</string>
-  <string name="cat_bottom_nav_badge_gravity_bottom_start">Bottom start</string>
 
   <string name="cat_bottom_nav_badge_gravity_spinner_label">Badge gravity</string>
   <string name="cat_bottom_nav_label_active_bold" translatable="false">Bold active label</string>

diff --git a/catalog/java/io/material/catalog/navigationrail/NavigationRailDemoFragment.java b/catalog/java/io/material/catalog/navigationrail/NavigationRailDemoFragment.java
@@ -50,8 +50,6 @@ public class NavigationRailDemoFragment extends DemoFragment {
       new int[] {
         BadgeDrawable.TOP_END,
         BadgeDrawable.TOP_START,
-        BadgeDrawable.BOTTOM_END,
-        BadgeDrawable.BOTTOM_START
       };
 
   private int numVisibleChildren = 3;

diff --git a/catalog/java/io/material/catalog/navigationrail/res/values/arrays.xml b/catalog/java/io/material/catalog/navigationrail/res/values/arrays.xml
@@ -19,7 +19,5 @@
   <string-array name="cat_navigation_rail_badge_gravity_titles">
     <item>@string/cat_navigation_rail_badge_gravity_top_end</item>
     <item>@string/cat_navigation_rail_badge_gravity_top_start</item>
-    <item>@string/cat_navigation_rail_badge_gravity_bottom_end</item>
-    <item>@string/cat_navigation_rail_badge_gravity_bottom_start</item>
   </string-array>
 </resources>
diff --git a/catalog/java/io/material/catalog/navigationrail/res/values/strings.xml b/catalog/java/io/material/catalog/navigationrail/res/values/strings.xml
@@ -89,10 +89,6 @@
           description="Label for the option that will cause badges to be positioned at the end, above the icon. [CHAR_LIMIT=50]">Top end</string>
   <string name="cat_navigation_rail_badge_gravity_top_start"
           description="Label for the option that will cause badges to be positioned at the start, above the icon. [CHAR_LIMIT=50]">Top start</string>
-  <string name="cat_navigation_rail_badge_gravity_bottom_end"
-          description="Label for the option that will cause badges to be positioned at the end, below the icon. [CHAR_LIMIT=50]">Bottom end</string>
-  <string name="cat_navigation_rail_badge_gravity_bottom_start"
-          description="Label for the option that will cause badges to be positioned at starting, below the icon. [CHAR_LIMIT=50]">Bottom start</string>
   <string name="cat_navigation_rail_label_active_bold"
           description="Label for controlling whether the active label is bold. [CHAR_LIMIT=50]" translatable="false">Bold active label</string>
 

diff --git a/docs/components/BadgeDrawable.md b/docs/components/BadgeDrawable.md
@@ -76,10 +76,11 @@ can specify a `FrameLayout` to display the badge instead.
 
 ### `BadgeDrawable` Gravity Modes
 
-`BadgeDrawable` provides four pre-packaged gravity modes that control how the
-badge aligns with its anchor view. By default (`TOP_END`) badge aligns with the
-top and end edges of the anchor (with some offsets). The other options are
-`TOP_START`, `BOTTOM_START` and `BOTTOM_END`.
+`BadgeDrawable` offers two gravity modes to control how the badge aligns with
+its anchor view. By default, (`TOP_END`) badge aligns with the top and end edges
+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
 
@@ -90,21 +91,22 @@ center, use `setHorizontalOffset(int)` or `setVerticalOffset(int)`
 
 ### `BadgeDrawable` Attributes
 
-| Feature               | Relevant attributes                                                                                                                                      |
-|-----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------|
-| Color                 | `app:backgroundColor` <br> `app:badgeTextColor`                                                                                                          |
-| Width                 | `app:badgeWidth` <br> `app:badgeWithTextWidth`                                                                                                           |
-| Height                | `app:badgeHeight` <br> `app:badgeWithTextHeight`                                                                                                         |
-| Shape                 | `app:badgeShapeAppearance` <br> `app:badgeShapeAppearanceOverlay` <br> `app:badgeWithTextShapeAppearance` <br> `app:badgeWithTextShapeAppearanceOverlay` |
-| Label                 | `app:badgeText` (for text) <br> `app:number` (for numbers)                                                                                               |
-| Label Length          | `app:maxCharacterCount` (for all text) <br> `app:maxNumber` (for numbers only)                                                                           |
-| Label Text Color      | `app:badgeTextColor`                                                                                                                                     |
-| Label Text Appearance | `app:badgeTextAppearance`                                                                                                                                |
-| Badge Gravity         | `app:badgeGravity`                                                                                                                                       |
-| Offset Alignment      | `app:offsetAlignmentMode`                                                                                                                                |
-| Horizontal Padding    | `app:badgeWidePadding`                                                                                                                                   |
-| Vertical Padding      | `app:badgeVerticalPadding`                                                                                                                               |
-| Auto Adjust           | `app:autoAdjustToWithinGrandparentBounds`                                                                                                                |
+| Feature                   | Relevant attributes                                                                                                                                      |
+|-----------------------    |----------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Color                     | `app:backgroundColor` <br> `app:badgeTextColor`                                                                                                          |
+| Width                     | `app:badgeWidth` <br> `app:badgeWithTextWidth`                                                                                                           |
+| Height                    | `app:badgeHeight` <br> `app:badgeWithTextHeight`                                                                                                         |
+| Shape                     | `app:badgeShapeAppearance` <br> `app:badgeShapeAppearanceOverlay` <br> `app:badgeWithTextShapeAppearance` <br> `app:badgeWithTextShapeAppearanceOverlay` |
+| Label                     | `app:badgeText` (for text) <br> `app:number` (for numbers)                                                                                               |
+| Label Length              | `app:maxCharacterCount` (for all text) <br> `app:maxNumber` (for numbers only)                                                                           |
+| Label Text Color          | `app:badgeTextColor`                                                                                                                                     |
+| Label Text Appearance     | `app:badgeTextAppearance`                                                                                                                                |
+| Badge Gravity             | `app:badgeGravity`                                                                                                                                       |
+| Offset Alignment          | `app:offsetAlignmentMode`                                                                                                                                |
+| 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`.
 

diff --git a/docs/components/Carousel.md b/docs/components/Carousel.md
@@ -28,11 +28,7 @@ page.
 
 Carousel is built on top of `RecyclerView`. To learn how to use `RecyclerView` to display a list of items, please see [Create dynamic lists with RecyclerView](https://developer.android.com/develop/ui/views/layout/recyclerview).
 
-## Multi-browse carousels
-
-A multi-browse carousel allows quick browsing of many small items, like a photo thumbnail gallery. A start-aligned, multi-browse carousel is the default carousel.
-
-To turn a horizontal list into a multi-browse carousel, first wrap your `RecyclerView`'s item layout in a `MaskableFrameLayout`. `MaskableFrameLayout` is a `FrameLayout` that is able to mask (clip) itself, and its children, to a percentage of its width. When a mask is set to 0%, the the entire view is visible in its original, "unmaksed" width. As a mask approaches 100%, the edges of the view begin to crop in towards the center, leaving a narrower and narrower sliver of the original view visible. Carousel masks and unmasks items as they are scrolled across the viewport to create a stylized look and feel.
+To turn a horizontal list into a carousel, first wrap your `RecyclerView`'s item layout in a `MaskableFrameLayout`. `MaskableFrameLayout` is a `FrameLayout` that is able to mask (clip) itself, and its children, to a percentage of its width. When a mask is set to 0%, the the entire view is visible in its original, "unmasked" width. As a mask approaches 100%, the edges of the view begin to crop in towards the center, leaving a narrower and narrower sliver of the original view visible. Carousel masks and unmasks items as they are scrolled across the viewport to create a stylized look and feel.
 
 ```xml
 <com.google.android.material.carousel.MaskableFrameLayout
@@ -71,7 +67,56 @@ Next, set your `RecyclerView`s layout manager to a new `CarouselLayoutManager`.
 carouselRecyclerView.setLayoutManager(CarouselLayoutManager())
 ```
 
-These are the basic steps to create a carousel with large items at the start of the list followed by medium and small items, depending on the size of the `RecyclerView` container.
+These are the basic steps to create a carousel. The look of the carousel depends
+on which carousel strategy you are using; you can have a
+[multi-browse strategy](#multi-browse-strategy) or
+[hero strategy](#hero-strategy).
+
+## Multi-browse strategy
+
+![A contained, multi-browse Carousel](assets/carousel/multibrowse.png)
+
+A multi-browse strategy allows quick browsing of many small items, like a photo
+thumbnail gallery. A start-aligned, multi-browse strategy is the default
+strategy for the carousel.
+
+With a multi-browse strategy, large items are at the start of the list followed
+by medium and small items, depending on the size of the `RecyclerView`
+container.
+
+You can use the multi-browse strategy by passing in no arguments to the
+CarouselLayoutManager constructor: `new CarouselLayoutManager()`.
+
+## Hero strategy
+
+![A contained, hero Carousel](assets/carousel/hero.png)
+
+A hero strategy highlights large content, like movies and other media, for more
+considered browsing and selection. It draws attention and focus to a main
+carousel item while hinting at the next item in line.
+
+With a hero strategy, typically there is one large item is at the start of the
+list followed by a small item. When there is one large item, the large item
+takes up the entire size of the `RecyclerView` container, save some space for
+the small item.
+
+There may be more than one large item depending on the dimensions of the
+carousel. On a horizontal carousel, the width of a large item will maximally be
+twice its height, and vice versa for vertical carousels. More large items are
+added when the maximum large item size has been reached. For example, horizontal
+carousels with `match_parent` as the width will have more and more large items
+as the screen size grows.
+
+You can use the hero strategy by passing in the strategy to the
+CarouselLayoutManager constructor: `new CarouselLayoutManager(new
+HeroStrategy())`.
+
+With the hero strategy, it is recommended to use the `CarouselSnapHelper` to snap to the nearest item like so:
+
+```
+SnapHelper snapHelper = new CarouselSnapHelper();
+snapHelper.attachToRecyclerView(carouselRecyclerView);
+```
 
 ## Customizing carousel
 

diff --git a/docs/components/assets/carousel/hero.png b/docs/components/assets/carousel/hero.png
diff --git a/docs/components/assets/carousel/multibrowse.png b/docs/components/assets/carousel/multibrowse.png