Add BadgeDrawable documentation. Update Bottom Navigation documentation to include information about badges.

PiperOrigin-RevId: 246309667

Author: wcshi

docs/components/BadgeDrawable.md

@@ -0,0 +1,84 @@
+<!--docs:
+title: "Badge"
+layout: detail
+section: components
+excerpt: "Badges can contain dynamic information, such as a number of pending requests."
+iconId: badge
+path: /catalog/bottom-navigation-view/
+-->
+
+# BadgeDrawable
+
+<!--*
+# Document freshness: For more information, see go/fresh-source.
+freshness: { owner: 'connieshi' reviewed: '2019-05-01' }
+*-->
+
+Badge                                   | Badge with number                              | Badge with a maximum character count
+--------------------------------------- | ---------------------------------------------- | ------------------------------------
+![badge_icon](assets/IconOnlyBadge.png) | ![badge_with_number_8](assets/BadgeNumber.png) | ![badge_with_999+](assets/BadgeNumberLongerThanMaxCharCount.png)
+
+A `BadgeDrawable` represents dynamic information such as a number of pending
+requests in a [`BottomNavigationView`](BottomNavigationView.md) or
+[`TabLayout`](TabLayout.md).
+
+## Design & API Documentation
+
+-   [Material Design guidelines: Chips](https://material.io/design/components/bottom-navigation.html#behavior)
+    <!--{: .icon-list-item.icon-list-item--spec }-->
+-   [Class definition](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/badge/BadgeDrawable.java)
+    <!--{: .icon-list-item.icon-list-item--link }-->
+    <!-- TODO: Add class overview once the javadoc is published on developer.android.com -->
+    <!-- - [Class overview](https://developer.android.com/reference/com/google/android/material/badge/Badge) -->
+    <!--{: .icon-list-item.icon-list-item--link }--> <!--{: .icon-list }-->
+
+## Usage
+
+Create an instance of `BadgeDrawable` by calling `create(Context)` or
+`createFromAttributes(Context, AttributeSet, int, int)}`.
+
+How to add and display a `BadgeDrawable` on top of its anchor view depends on
+the API level:
+
+In API 18+ (APIs supported by
+[ViewOverlay](https://developer.android.com/reference/android/view/ViewOverlay))
+
+1.  Add `BadgeDrawable` as a
+    [ViewOverlay](https://developer.android.com/reference/android/view/ViewOverlay)
+    to the desired anchor view.
+1.  Update the `BadgeDrawable`'s coordinates (center and bounds) based on its
+    anchor view.
+
+Both of the above steps have been encapsulated in a util method:
+
+```java
+  BadgeUtils.attachBadgeDrawable(badgeDrawable, anchor, null);
+```
+
+In Pre API-18
+
+1.  Set `BadgeDrawable` as the foreground of the anchor view's FrameLayout
+    ancestor.
+1.  Update the `BadgeDrawable`'s coordinates (center and bounds) based on its
+    anchor view (relative to its FrameLayout ancestor's coordinate space),
+
+Both of the above steps have been encapsulated in a util method:
+
+```java
+  BadgeUtils.attachBadgeDrawable(badgeDrawable, anchor, anchorFrameLayoutParent);
+```
+
+### BadgeDrawable Attributes
+
+Feature      | Relevant attributes
+------------ | -----------------------------------------------
+Color        | `app:backgroundColor` <br> `app:badgeTextColor`
+Label        | `app:number`
+Label Length | `app:maxCharacterCount`
+
+### Talkback Support
+
+`BadgeDrawable` provides a getter for its content description, which is based on
+the number (if any) being displayed. Users should specify content description:
+`setContentDescriptionNumberless(CharSequence)`
+`setContentDescriptionQuantityStringsResource(@StringRes)`

docs/components/BottomNavigationView.md

@@ -20,27 +20,25 @@ navigate to.
 
 ## Design & API Documentation
 
--   [Material Design guidelines: Bottom
-    Navigation](https://material.io/go/design-bottom-navigation)
+-   [Material Design guidelines: Bottom Navigation](https://material.io/go/design-bottom-navigation)
     <!--{: .icon-list-item.icon-list-item--spec }-->
--   [Class
-    definition](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/bottomnavigation/BottomNavigationView.java)
+-   [Class definition](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/bottomnavigation/BottomNavigationView.java)
     <!--{: .icon-list-item.icon-list-item--link }-->
     <!-- Styles for list items requiring icons instead of standard bullets. -->
--   [Class
-    overview](https://developer.android.com/reference/com/google/android/material/bottomnavigation/BottomNavigationView)
+-   [Class overview](https://developer.android.com/reference/com/google/android/material/bottomnavigation/BottomNavigationView)
     <!--{: .icon-list-item.icon-list-item--link }--> <!--{: .icon-list }-->
 
 ## Usage
 
-1. Create a [menu
-resource](https://developer.android.com/guide/topics/resources/menu-resource.html)
-with up to 5 navigation targets (`BottomNavigationView` does not support more than
-5 items).
-2. Lay out your `BottomNavigationView` below your content.
-3. Set the `app:menu` attribute on your `BottomNavigationView` to your menu
-resource.
-4. Listen for selection events using `setOnNavigationItemSelectedListener(...)`.
+1.  Create a
+    [menu resource](https://developer.android.com/guide/topics/resources/menu-resource.html)
+    with up to 5 navigation targets (`BottomNavigationView` does not support
+    more than 5 items).
+2.  Lay out your `BottomNavigationView` below your content.
+3.  Set the `app:menu` attribute on your `BottomNavigationView` to your menu
+    resource.
+4.  Listen for selection events using
+    `setOnNavigationItemSelectedListener(...)`.
 
 A typical layout file would look something like this:
 
@@ -66,6 +64,31 @@ A typical layout file would look something like this:
 </FrameLayout>
 ```
 
+### Badges
+
+![Bottom Navigation with badges](assets/bottom-navigation-badges.png)
+
+`BottomNavigationView` supports displaying icon and number badges.
+
+Initializes and shows a BadgeDrawable associated with menuItemId. Subsequent
+calls to this method will reuse the existing BadgeDrawable.
+
+```java
+BadgeDrawable badge = bottomNavigationView.showBadge(menuItemId);
+```
+NOTE: Don't forget to remove any BadgeDrawables that are no longer needed.
+
+```java
+bottomNavigationView.removeBadge(menuItemId);
+```
+
+Best Practice: If you only need to temporarily hide the badge(e.g. until the next
+notification is received), the recommended/lightweight alternative is to change
+the visibility of the BadgeDrawable instead.
+
+Please see [`BadgeDrawable`](BadgeDrawable.md) for details on how to update the
+badge content being displayed.
+
 ### Handling States
 
 The `app:itemIconTint` and `app:itemTextColor` take a
@@ -191,8 +214,8 @@ theming attributes.
 There are other navigation patterns you should be aware of:
 
 -   [Hierarchical navigation](https://developer.android.com/training/implementing-navigation/index.html).
-    *See also [Navigation with Back and
-    Up](https://developer.android.com/design/patterns/navigation.html).*
+    *See also
+    [Navigation with Back and Up](https://developer.android.com/design/patterns/navigation.html).*
 -   Swipeable tabs using [TabLayout](TabLayout.md) and
     [ViewPager](https://developer.android.com/reference/android/support/v4/view/ViewPager.html).
 -   Using [NavigationView](NavigationView.md) to display a longer list of