[NavigationRail][Docs] Update navigation rail docs to include mentions of the expanded nav rail

PiperOrigin-RevId: 699270265

Author: imhappi

docs/components/NavigationRail.md

@@ -44,7 +44,7 @@ A typical layout will look similar to this:
 ```
 
 **Note:** The width of a `NavigationRailView` will be 80dp wide by default.The
-width of the rail can be changed by setting the `android:layout_width`attribute
+width of the rail can be changed by setting the `android:layout_width` attribute
 to a specific DP value.
 
 In `navigation_rail_menu.xml` inside a `menu` resource directory:
@@ -74,11 +74,48 @@ In `navigation_rail_menu.xml` inside a `menu` resource directory:
 </menu>
 ```
 
-**Note:** `NavigationRailView` displays three to no more than seven app
-destinations, and can include a header view. Each destination is represented by
-an icon and a text label.
+`NavigationRailView` displays three to no more than seven app
+destinations when collapsed, and can include a header view. Each destination is
+represented by an icon and a text label.
 
-In code:
+You can also define submenus for the Navigation Rail like below:
+
+```xml
+<menu xmlns:android="http://schemas.android.com/apk/res/android">
+    <item
+        android:id="@+id/submenu_1"
+        android:title="@string/subheader_1_name">
+        <menu>
+            <item
+                android:id="@+id/timer"
+                android:enabled="true"
+                android:icon="@drawable/icon_sand_clock"
+                android:title="@string/timer_destination_label"/>
+            <item
+                android:id="@+id/stopwatch"
+                android:enabled="true"
+                android:icon="@drawable/icon_stop_watch"
+                android:title="@string/stopwatch_destination_label"/>
+        </menu>
+    </item>
+    <item
+        android:id="@+id/alarms"
+        android:enabled="true"
+        android:icon="@drawable/icon_alarms"
+        android:title="@string/alarms_destination_label"/>
+    <item
+        android:id="@+id/schedule"
+        android:enabled="true"
+        android:icon="@drawable/icon_clock"
+        android:title="@string/schedule_destination_label"/>
+</menu>
+```
+
+Navigation rails are collapsed by default. When collapsed, only menu items that
+are not under a submenu will be shown, up to a limit of 7. There is no limit of
+items shown when expanded.
+
+You will need to set listeners for the menu items in code:
 
 ```kt
 // Listeners are defined on the super class NavigationBarView
@@ -188,6 +225,22 @@ The following methods can be used to manipulate the header view at runtime.
 -------------------------------- | ---------------
 `@Nullable view getHeaderView()` | Returns an instance of the header view associated with the Navigation Rail, null if none was currently attached.
 
+### Expanding the Navigation Rail
+
+You can call `navigationRailView.expand()` and `navigationRailView.collapse()` to expand and collapse the navigation rail.
+
+When collapsed, only menu items not under a submenu will be shown, up to a limit of 7.
+
+When expanded, all menu items will be shown, including submenu items.
+
+Navigation rails are collapsed by default which animates into the expanded navigation rail when expanded. If the content beside
+the navigation rail takes into account the size of the navigation rail (ie., through setting constraints in `ConstraintLayout` or layout weights) then the content will also be animated to shrink. This animation is taken care of by a [ChangeBounds Transition](https://developer.android.com/reference/android/transition/ChangeBounds); any animations during the expansion of the navigation rail should be 'turned off' as
+it could result in a strange animation due to the `Transition`.
+
+Collapsed Navigation Rail                                                  | Expanded Navigation Rail
+-------------------------------------------------------------------------- | ------------------------
+![Collapsed navigation rail](assets/navigationrail/collapsed_nav_rail.png) | ![Expanded navigation rail](assets/navigationrail/expanded_nav_rail.png)
+
 ### Adding badges
 
 Rail icons can include badges on the upper right corner of the icon. Badges