[Toolbar] Add support for navigation button with circle background

PiperOrigin-RevId: 790777821

Author: dsn5ft

catalog/java/io/material/catalog/topappbar/res/layout/cat_topappbar_toolbar_fragment.xml

@@ -50,5 +50,13 @@
         android:elevation="@dimen/design_appbar_elevation"
         app:subtitle="Surface Elevated"
         app:title="Toolbar"/>
+
+    <com.google.android.material.appbar.MaterialToolbar
+      android:layout_width="match_parent"
+      android:layout_height="wrap_content"
+      android:layout_marginTop="32dp"
+      android:theme="@style/ThemeOverlay.Material3.Toolbar.CircleNavigationButton"
+      app:subtitle="Circle Navigation Button"
+      app:title="Toolbar" />
   </LinearLayout>
 </ScrollView>

docs/components/TopAppBar.md

@@ -596,6 +596,22 @@ layout configuration.
 
 <details>
 
+<summary><h3>Adding a circle to the navigation button</h3></summary>
+
+If you would like to add a circle background to the navigation icon, set the
+`android:theme="@style/ThemeOverlay.Material3.Toolbar.CircleNavigationButton"`
+theme overlay on your `Toolbar` or `MaterialToolbar`.
+
+By default, the theme overlay above uses `?attr/colorSurfaceContainer` for the
+circle color. This can be customized by extending the theme overlay and setting
+the `toolbarNavigationButtonCircleColor` attribute.
+
+<img src="assets/topappbar/topappbar_circle_nav_button.png" alt="Top app bar with circle navigation button background." width="600"/>
+
+</details>
+
+<details>
+
 <summary><h3>Applying scrolling behavior to app bars</h3></summary>
 
 When scrolling up, the collapsing top app bar transforms into a regular top app

docs/components/assets/topappbar/topappbar_circle_nav_button.png

@@ -22,6 +22,7 @@
   <public name="collapsingToolbarLayoutMediumSize" type="attr"/>
   <public name="collapsingToolbarLayoutLargeSize" type="attr"/>
   <public name="toolbarSurfaceStyle" type="attr"/>
+  <public name="toolbarNavigationButtonCircleColor" type="attr"/>
   <public name="layout_scrollInterpolator" type="attr"/>
   <public name="layout_scrollEffect" type="attr"/>
   <public name="behavior_overlapTop" type="attr"/>
@@ -64,12 +65,14 @@
   <public name="Widget.Material3.Toolbar" type="style"/>
   <public name="Widget.Material3.Toolbar.Surface" type="style"/>
   <public name="Widget.Material3.Toolbar.OnSurface" type="style"/>
+  <public name="Widget.Material3.Toolbar.Button.Navigation.Circle" type="style"/>
   <public name="Widget.Material3.ActionBar.Solid" type="style"/>
   <public name="Widget.Material3.Light.ActionBar.Solid" type="style"/>
   <public name="Widget.Material3.ActionMode" type="style"/>
   <public name="ThemeOverlay.MaterialComponents.Toolbar.Primary" type="style"/>
   <public name="ThemeOverlay.MaterialComponents.Toolbar.Surface" type="style"/>
   <public name="ThemeOverlay.Material3.Toolbar.Surface" type="style"/>
+  <public name="ThemeOverlay.Material3.Toolbar.CircleNavigationButton" type="style"/>
   <public name="TextAppearance.Design.CollapsingToolbar.Expanded" type="style"/>
   <public name="TextAppearance.Material3.ActionBar.Subtitle" type="style"/>
   <public name="TextAppearance.Material3.ActionBar.Title" type="style"/>

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

@@ -0,0 +1,33 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+  ~ Copyright (C) 2025 The Android Open Source Project
+  ~
+  ~ Licensed under the Apache License, Version 2.0 (the "License");
+  ~ you may not use this file except in compliance with the License.
+  ~ You may obtain a copy of the License at
+  ~
+  ~      http://www.apache.org/licenses/LICENSE-2.0
+  ~
+  ~ Unless required by applicable law or agreed to in writing, software
+  ~ distributed under the License is distributed on an "AS IS" BASIS,
+  ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  ~ See the License for the specific language governing permissions and
+  ~ limitations under the License.
+-->
+<layer-list xmlns:android="http://schemas.android.com/apk/res/android">
+
+  <!-- Circle. -->
+  <item
+    android:width="@dimen/m3_toolbar_button_circle_size"
+    android:height="@dimen/m3_toolbar_button_circle_size"
+    android:gravity="center">
+    <shape android:shape="oval">
+      <solid android:color="?attr/toolbarNavigationButtonCircleColor" />
+    </shape>
+  </item>
+
+  <!-- Ripple, which should be on top of the Circle but below the Icon. -->
+  <item
+    android:drawable="?attr/controlBackground"
+    android:gravity="center" />
+</layer-list>

lib/java/com/google/android/material/appbar/res/drawable/m3_toolbar_navigation_circle_background.xml

@@ -37,6 +37,9 @@
   <!-- Style to use for Surface Toolbars in this theme. -->
   <attr name="toolbarSurfaceStyle" format="reference"/>
 
+  <!-- Color of the circle when using ThemeOverlay.Material3.Toolbar.CircleNavigationButton. -->
+  <attr name="toolbarNavigationButtonCircleColor" format="color"/>
+
   <declare-styleable name="AppBarLayout">
     <!-- Deprecated. Elevation is now controlled via a state list animator. -->
     <attr name="elevation"/>

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

@@ -33,4 +33,5 @@
   <dimen name="m3_appbar_scrim_height_trigger_medium">112dp</dimen>
   <dimen name="m3_appbar_scrim_height_trigger_large">112dp</dimen>
   <dimen name="m3_toolbar_text_size_title">20dp</dimen>
+  <dimen name="m3_toolbar_button_circle_size">40dp</dimen>
 </resources>

lib/java/com/google/android/material/appbar/res/values/dimens.xml

@@ -154,6 +154,15 @@
     <item name="colorControlNormal">@macro/m3_comp_app_bar_trailing_icon_color</item>
   </style>
 
+  <style name="ThemeOverlay.Material3.Toolbar.CircleNavigationButton" parent="">
+    <item name="toolbarNavigationButtonCircleColor">?attr/colorSurfaceContainer</item>
+    <item name="toolbarNavigationButtonStyle">@style/Widget.Material3.Toolbar.Button.Navigation.Circle</item>
+  </style>
+
+  <style name="Widget.Material3.Toolbar.Button.Navigation.Circle" parent="Widget.AppCompat.Toolbar.Button.Navigation">
+    <item name="android:background">@drawable/m3_toolbar_navigation_circle_background</item>
+  </style>
+
   <!-- Style for a M3 ActionBar (inherited from AppCompat due to different
        desired configuration compared to MaterialComponents ActionBars). -->
   <style name="Base.Widget.Material3.ActionBar.Solid" parent="Widget.AppCompat.ActionBar.Solid">