[Badge] Allow text strings in badges

Resolves #2978 GIT_ORIGIN_REV_ID=39c9f60cff607fba1e9ca57ae8bc155c5919e503 Co-authored-by: imhappi PiperOrigin-RevId: 520368686
material-components · Mar 29, 2023 · c1ef52b · c1ef52b
1 parent 2c23d2a
commit c1ef52b
Show file tree

Hide file tree

Showing 9 changed files with 231 additions and 66 deletions.
diff --git a/docs/components/BadgeDrawable.md b/docs/components/BadgeDrawable.md
@@ -96,16 +96,21 @@ center, use `setHorizontalOffset(int)` or `setVerticalOffset(int)`
 | 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:number`                                                                                                     |
+| Label                 | `app:badgeText` (for text) <br> `app:number` (for numbers)                                                       |
 | Label Length          | `app:maxCharacterCount`                                                                                          |
 | Label Text Color      | `app:badgeTextColor`                                                                                             |
 | Label Text Appearance | `app:badgeTextAppearance`                                                                                        |
 | Badge Gravity         | `app:badgeGravity`                                                                                               |
 | Offset Alignment      | `app:offsetAlignmentMode`                                                                                        |
 
+**Note:** If both `app:badgeText` and `app:number` are specified, the badge label will be `app:badgeText`.
+
 ### Talkback Support
 
-`BadgeDrawable` provides a getter for its content description, which is based on
-the number (if any) displayed. Users should specify content description:
-`setContentDescriptionNumberless(CharSequence)`
-`setContentDescriptionQuantityStringsResource(@StringRes)`
+`BadgeDrawable` provides a getter for its content description, which is based on the displayed
+number or text (if any). To specify the content description, the developer is provided
+with the following methods:
+-   `setContentDescriptionForText(CharSequence)`
+-   `setContentDescriptionQuantityStringsResource(@PluralsRes int)`
+-   `setContentDescriptionExceedsMaxBadgeNumberStringResource(@StringRes int)`
+-   `setContentDescriptionNumberless(CharSequence)`
diff --git a/docs/components/BottomNavigation.md b/docs/components/BottomNavigation.md
@@ -146,8 +146,8 @@ calls to this method will reuse the existing `BadgeDrawable`:
 ```kt
 var badge = bottomNavigation.getOrCreateBadge(menuItemId)
 badge.isVisible = true
-// An icon only badge will be displayed unless a number is set:
-badge.number = 99
+// An icon only badge will be displayed unless a number or text is set:
+badge.number = 99  // or badge.text = "New"
 ```
 
 As a best practice, if you need to temporarily hide the badge, for instance
@@ -158,7 +158,7 @@ until the next notification is received, change the visibility of
 val badgeDrawable = bottomNavigation.getBadge(menuItemId)
     if (badgeDrawable != null) {
         badgeDrawable.isVisible = false
-        badgeDrawable.clearNumber()
+        badgeDrawable.clearNumber()  // or badgeDrawable.clearText()
     }
 ```
 

diff --git a/docs/components/NavigationRail.md b/docs/components/NavigationRail.md
@@ -190,8 +190,8 @@ calls to this method will reuse the existing `BadgeDrawable`:
 ```kt
 var badge = navigationRail.getOrCreateBadge(menuItemId)
 badge.isVisible = true
-// An icon only badge will be displayed unless a number is set:
-badge.number = 99
+// An icon only badge will be displayed unless a number or text is set:
+badge.number = 99  // or badge.text = "New"
 ```
 
 As best practice, if you need to temporarily hide the badge, for example until
@@ -201,7 +201,7 @@ the next notification is received, change the visibility of `BadgeDrawable`:
 val badgeDrawable = navigationRail.getBadge(menuItemId)
     if (badgeDrawable != null) {
         badgeDrawable.isVisible = false
-        badgeDrawable.clearNumber()
+        badgeDrawable.clearNumber()  // or badgeDrawable.clearText()
     }
 ```
 

diff --git a/docs/components/Tabs.md b/docs/components/Tabs.md
@@ -115,9 +115,14 @@ badge states:
 
 ```kt
 val badge = tab.getOrCreateBadge()
+
+// For badges with a number
 badge.setContentDescriptionNumberless(contentDescription)
 badge.setContentDescriptionQuantityStringsResource(R.string.content_description)
 badge.setContentDescriptionExceedsMaxBadgeNumberStringResource(R.string.content_description)
+
+// For badges with a text
+badge.setContentDescriptionForText(contentDescription)
 ```
 
 ### Using tabs with ViewPager