/*
* Copyright 2021 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.
*/
package androidx.compose.material3
import androidx.compose.animation.animateColorAsState
import androidx.compose.animation.core.animateFloatAsState
import androidx.compose.animation.core.tween
import androidx.compose.foundation.background
import androidx.compose.foundation.indication
import androidx.compose.foundation.interaction.Interaction
import androidx.compose.foundation.interaction.MutableInteractionSource
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.RowScope
import androidx.compose.foundation.layout.WindowInsets
import androidx.compose.foundation.layout.WindowInsetsSides
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.only
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.windowInsetsPadding
import androidx.compose.foundation.selection.selectable
import androidx.compose.foundation.selection.selectableGroup
import androidx.compose.material.ripple.rememberRipple
import androidx.compose.material3.tokens.NavigationBarTokens
import androidx.compose.runtime.Composable
import androidx.compose.runtime.CompositionLocalProvider
import androidx.compose.runtime.Stable
import androidx.compose.runtime.State
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.setValue
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.draw.alpha
import androidx.compose.ui.draw.clip
import androidx.compose.ui.geometry.Offset
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.layout.Layout
import androidx.compose.ui.layout.MeasureResult
import androidx.compose.ui.layout.MeasureScope
import androidx.compose.ui.layout.Placeable
import androidx.compose.ui.layout.layoutId
import androidx.compose.ui.layout.onSizeChanged
import androidx.compose.ui.platform.LocalDensity
import androidx.compose.ui.semantics.Role
import androidx.compose.ui.semantics.clearAndSetSemantics
import androidx.compose.ui.unit.Constraints
import androidx.compose.ui.unit.Dp
import androidx.compose.ui.unit.dp
import kotlin.math.roundToInt
/**
* Material Design bottom navigation bar.
*
* Navigation bars offer a persistent and convenient way to switch between primary destinations in
* an app.
*
* 
*
* [NavigationBar] should contain three to five [NavigationBarItem]s, each representing a singular
* destination.
*
* A simple example looks like:
* @sample androidx.compose.material3.samples.NavigationBarSample
*
* See [NavigationBarItem] for configuration specific to each item, and not the overall
* [NavigationBar] component.
*
* @param modifier the [Modifier] to be applied to this navigation bar
* @param containerColor the color used for the background of this navigation bar. Use
* [Color.Transparent] to have no color.
* @param contentColor the preferred color for content inside this navigation bar. Defaults to
* either the matching content color for [containerColor], or to the current [LocalContentColor] if
* [containerColor] is not a color from the theme.
* @param tonalElevation when [containerColor] is [ColorScheme.surface], a translucent primary color
* overlay is applied on top of the container. A higher tonal elevation value will result in a
* darker color in light theme and lighter color in dark theme. See also: [Surface].
* @param windowInsets a window insets of the navigation bar.
* @param content the content of this navigation bar, typically 3-5 [NavigationBarItem]s
*/
@Composable
fun NavigationBar(
modifier: Modifier = Modifier,
containerColor: Color = NavigationBarDefaults.containerColor,
contentColor: Color = MaterialTheme.colorScheme.contentColorFor(containerColor),
tonalElevation: Dp = NavigationBarDefaults.Elevation,
windowInsets: WindowInsets = NavigationBarDefaults.windowInsets,
content: @Composable RowScope.() -> Unit
) {
Surface(
color = containerColor,
contentColor = contentColor,
tonalElevation = tonalElevation,
modifier = modifier
) {
Row(
modifier = Modifier
.fillMaxWidth()
.windowInsetsPadding(windowInsets)
.height(NavigationBarHeight)
.selectableGroup(),
horizontalArrangement = Arrangement.spacedBy(NavigationBarItemHorizontalPadding),
content = content
)
}
}
/**
* Material Design navigation bar item.
*
* Navigation bars offer a persistent and convenient way to switch between primary destinations in
* an app.
*
* The recommended configuration for a [NavigationBarItem] depends on how many items there are
* inside a [NavigationBar]:
*
* - Three destinations: Display icons and text labels for all destinations.
* - Four destinations: Active destinations display an icon and text label. Inactive destinations
* display icons, and text labels are recommended.
* - Five destinations: Active destinations display an icon and text label. Inactive destinations
* use icons, and use text labels if space permits.
*
* A [NavigationBarItem] always shows text labels (if it exists) when selected. Showing text
* labels if not selected is controlled by [alwaysShowLabel].
*
* @param selected whether this item is selected
* @param onClick called when this item is clicked
* @param icon icon for this item, typically an [Icon]
* @param modifier the [Modifier] to be applied to this item
* @param enabled controls the enabled state of this item. When `false`, this component will not
* respond to user input, and it will appear visually disabled and disabled to accessibility
* services.
* @param label optional text label for this item
* @param alwaysShowLabel whether to always show the label for this item. If `false`, the label will
* only be shown when this item is selected.
* @param colors [NavigationBarItemColors] that will be used to resolve the colors used for this
* item in different states. See [NavigationBarItemDefaults.colors].
* @param interactionSource the [MutableInteractionSource] representing the stream of [Interaction]s
* for this item. You can create and pass in your own `remember`ed instance to observe
* [Interaction]s and customize the appearance / behavior of this item in different states.
*/
@Composable
fun RowScope.NavigationBarItem(
selected: Boolean,
onClick: () -> Unit,
icon: @Composable () -> Unit,
modifier: Modifier = Modifier,
enabled: Boolean = true,
label: @Composable (() -> Unit)? = null,
alwaysShowLabel: Boolean = true,
colors: NavigationBarItemColors = NavigationBarItemDefaults.colors(),
interactionSource: MutableInteractionSource = remember { MutableInteractionSource() }
) {
val styledIcon = @Composable {
val iconColor by colors.iconColor(selected = selected, enabled = enabled)
// If there's a label, don't have a11y services repeat the icon description.
val clearSemantics = label != null && (alwaysShowLabel || selected)
Box(modifier = if (clearSemantics) Modifier.clearAndSetSemantics {} else Modifier) {
CompositionLocalProvider(LocalContentColor provides iconColor, content = icon)
}
}
val styledLabel: @Composable (() -> Unit)? = label?.let {
@Composable {
val style = MaterialTheme.typography.fromToken(NavigationBarTokens.LabelTextFont)
val textColor by colors.textColor(selected = selected, enabled = enabled)
CompositionLocalProvider(LocalContentColor provides textColor) {
ProvideTextStyle(style, content = label)
}
}
}
var itemWidth by remember { mutableStateOf(0) }
Box(
modifier
.selectable(
selected = selected,
onClick = onClick,
enabled = enabled,
role = Role.Tab,
interactionSource = interactionSource,
indication = null,
)
.weight(1f)
.onSizeChanged {
itemWidth = it.width
},
contentAlignment = Alignment.Center
) {
val animationProgress: Float by animateFloatAsState(
targetValue = if (selected) 1f else 0f,
animationSpec = tween(ItemAnimationDurationMillis)
)
// The entire item is selectable, but only the indicator pill shows the ripple. To achieve
// this, we re-map the coordinates of the item's InteractionSource into the coordinates of
// the indicator.
val deltaOffset: Offset
with(LocalDensity.current) {
val indicatorWidth = NavigationBarTokens.ActiveIndicatorWidth.roundToPx()
deltaOffset = Offset(
(itemWidth - indicatorWidth).toFloat() / 2,
IndicatorVerticalOffset.toPx()
)
}
val offsetInteractionSource = remember(interactionSource, deltaOffset) {
MappedInteractionSource(interactionSource, deltaOffset)
}
// The indicator has a width-expansion animation which interferes with the timing of the
// ripple, which is why they are separate composables
val indicatorRipple = @Composable {
Box(
Modifier
.layoutId(IndicatorRippleLayoutIdTag)
.clip(NavigationBarTokens.ActiveIndicatorShape.toShape())
.indication(offsetInteractionSource, rememberRipple())
)
}
val indicator = @Composable {
Box(
Modifier
.layoutId(IndicatorLayoutIdTag)
.background(
color = colors.indicatorColor.copy(alpha = animationProgress),
shape = NavigationBarTokens.ActiveIndicatorShape.toShape(),
)
)
}
NavigationBarItemBaselineLayout(
indicatorRipple = indicatorRipple,
indicator = indicator,
icon = styledIcon,
label = styledLabel,
alwaysShowLabel = alwaysShowLabel,
animationProgress = animationProgress
)
}
}
/** Defaults used in [NavigationBar]. */
object NavigationBarDefaults {
/** Default elevation for a navigation bar. */
val Elevation: Dp = NavigationBarTokens.ContainerElevation
/** Default color for a navigation bar. */
val containerColor: Color @Composable get() = NavigationBarTokens.ContainerColor.toColor()
/**
* Default window insets to be used and consumed by navigation bar
*/
val windowInsets: WindowInsets
@Composable
get() = WindowInsets.systemBarsForVisualComponents
.only(WindowInsetsSides.Horizontal + WindowInsetsSides.Bottom)
}
/** Defaults used in [NavigationBarItem]. */
object NavigationBarItemDefaults {
/**
* Creates a [NavigationBarItemColors] with the provided colors according to the Material
* specification.
*
* @param selectedIconColor the color to use for the icon when the item is selected.
* @param selectedTextColor the color to use for the text label when the item is selected.
* @param indicatorColor the color to use for the indicator when the item is selected.
* @param unselectedIconColor the color to use for the icon when the item is unselected.
* @param unselectedTextColor the color to use for the text label when the item is unselected.
* @param disabledIconColor the color to use for the icon when the item is disabled.
* @param disabledTextColor the color to use for the text label when the item is disabled.
* @return the resulting [NavigationBarItemColors] used for [NavigationBarItem]
*/
@Composable
fun colors(
selectedIconColor: Color = NavigationBarTokens.ActiveIconColor.toColor(),
selectedTextColor: Color = NavigationBarTokens.ActiveLabelTextColor.toColor(),
indicatorColor: Color = NavigationBarTokens.ActiveIndicatorColor.toColor(),
unselectedIconColor: Color = NavigationBarTokens.InactiveIconColor.toColor(),
unselectedTextColor: Color = NavigationBarTokens.InactiveLabelTextColor.toColor(),
disabledIconColor: Color = unselectedIconColor.copy(alpha = DisabledAlpha),
disabledTextColor: Color = unselectedTextColor.copy(alpha = DisabledAlpha),
): NavigationBarItemColors = NavigationBarItemColors(
selectedIconColor = selectedIconColor,
selectedTextColor = selectedTextColor,
selectedIndicatorColor = indicatorColor,
unselectedIconColor = unselectedIconColor,
unselectedTextColor = unselectedTextColor,
disabledIconColor = disabledIconColor,
disabledTextColor = disabledTextColor,
)
@Deprecated(
"Use overload with disabledIconColor and disabledTextColor",
level = DeprecationLevel.HIDDEN
)
@Composable
fun colors(
selectedIconColor: Color = NavigationBarTokens.ActiveIconColor.toColor(),
selectedTextColor: Color = NavigationBarTokens.ActiveLabelTextColor.toColor(),
indicatorColor: Color = NavigationBarTokens.ActiveIndicatorColor.toColor(),
unselectedIconColor: Color = NavigationBarTokens.InactiveIconColor.toColor(),
unselectedTextColor: Color = NavigationBarTokens.InactiveLabelTextColor.toColor(),
): NavigationBarItemColors = NavigationBarItemColors(
selectedIconColor = selectedIconColor,
selectedTextColor = selectedTextColor,
selectedIndicatorColor = indicatorColor,
unselectedIconColor = unselectedIconColor,
unselectedTextColor = unselectedTextColor,
disabledIconColor = unselectedIconColor.copy(alpha = DisabledAlpha),
disabledTextColor = unselectedTextColor.copy(alpha = DisabledAlpha),
)
}
@Stable
class NavigationBarItemColors internal constructor(
private val selectedIconColor: Color,
private val selectedTextColor: Color,
private val selectedIndicatorColor: Color,
private val unselectedIconColor: Color,
private val unselectedTextColor: Color,
private val disabledIconColor: Color,
private val disabledTextColor: Color,
) {
/**
* Represents the icon color for this item, depending on whether it is [selected].
*
* @param selected whether the item is selected
* @param enabled whether the item is enabled
*/
@Composable
internal fun iconColor(selected: Boolean, enabled: Boolean): State {
val targetValue = when {
!enabled -> disabledIconColor
selected -> selectedIconColor
else -> unselectedIconColor
}
return animateColorAsState(
targetValue = targetValue,
animationSpec = tween(ItemAnimationDurationMillis)
)
}
/**
* Represents the text color for this item, depending on whether it is [selected].
*
* @param selected whether the item is selected
* @param enabled whether the item is enabled
*/
@Composable
internal fun textColor(selected: Boolean, enabled: Boolean): State {
val targetValue = when {
!enabled -> disabledTextColor
selected -> selectedTextColor
else -> unselectedTextColor
}
return animateColorAsState(
targetValue = targetValue,
animationSpec = tween(ItemAnimationDurationMillis)
)
}
/** Represents the color of the indicator used for selected items. */
internal val indicatorColor: Color
get() = selectedIndicatorColor
override fun equals(other: Any?): Boolean {
if (this === other) return true
if (other == null || other !is NavigationBarItemColors) return false
if (selectedIconColor != other.selectedIconColor) return false
if (unselectedIconColor != other.unselectedIconColor) return false
if (selectedTextColor != other.selectedTextColor) return false
if (unselectedTextColor != other.unselectedTextColor) return false
if (selectedIndicatorColor != other.selectedIndicatorColor) return false
if (disabledIconColor != other.disabledIconColor) return false
if (disabledTextColor != other.disabledTextColor) return false
return true
}
override fun hashCode(): Int {
var result = selectedIconColor.hashCode()
result = 31 * result + unselectedIconColor.hashCode()
result = 31 * result + selectedTextColor.hashCode()
result = 31 * result + unselectedTextColor.hashCode()
result = 31 * result + selectedIndicatorColor.hashCode()
result = 31 * result + disabledIconColor.hashCode()
result = 31 * result + disabledTextColor.hashCode()
return result
}
}
/**
* Base layout for a [NavigationBarItem].
*
* @param indicatorRipple indicator ripple for this item when it is selected
* @param indicator indicator for this item when it is selected
* @param icon icon for this item
* @param label text label for this item
* @param alwaysShowLabel whether to always show the label for this item. If false, the label will
* only be shown when this item is selected.
* @param animationProgress progress of the animation, where 0 represents the unselected state of
* this item and 1 represents the selected state. This value controls other values such as indicator
* size, icon and label positions, etc.
*/
@Composable
private fun NavigationBarItemBaselineLayout(
indicatorRipple: @Composable () -> Unit,
indicator: @Composable () -> Unit,
icon: @Composable () -> Unit,
label: @Composable (() -> Unit)?,
alwaysShowLabel: Boolean,
animationProgress: Float,
) {
Layout({
indicatorRipple()
if (animationProgress > 0) {
indicator()
}
Box(Modifier.layoutId(IconLayoutIdTag)) { icon() }
if (label != null) {
Box(
Modifier
.layoutId(LabelLayoutIdTag)
.alpha(if (alwaysShowLabel) 1f else animationProgress)
.padding(horizontal = NavigationBarItemHorizontalPadding / 2)
) { label() }
}
}) { measurables, constraints ->
val iconPlaceable =
measurables.first { it.layoutId == IconLayoutIdTag }.measure(constraints)
val totalIndicatorWidth = iconPlaceable.width + (IndicatorHorizontalPadding * 2).roundToPx()
val animatedIndicatorWidth = (totalIndicatorWidth * animationProgress).roundToInt()
val indicatorHeight = iconPlaceable.height + (IndicatorVerticalPadding * 2).roundToPx()
val indicatorRipplePlaceable =
measurables
.first { it.layoutId == IndicatorRippleLayoutIdTag }
.measure(
Constraints.fixed(
width = totalIndicatorWidth,
height = indicatorHeight
)
)
val indicatorPlaceable =
measurables
.firstOrNull { it.layoutId == IndicatorLayoutIdTag }
?.measure(
Constraints.fixed(
width = animatedIndicatorWidth,
height = indicatorHeight
)
)
val labelPlaceable =
label?.let {
measurables
.first { it.layoutId == LabelLayoutIdTag }
.measure(
// Measure with loose constraints for height as we don't want the label to
// take up more space than it needs
constraints.copy(minHeight = 0)
)
}
if (label == null) {
placeIcon(iconPlaceable, indicatorRipplePlaceable, indicatorPlaceable, constraints)
} else {
placeLabelAndIcon(
labelPlaceable!!,
iconPlaceable,
indicatorRipplePlaceable,
indicatorPlaceable,
constraints,
alwaysShowLabel,
animationProgress
)
}
}
}
/**
* Places the provided [Placeable]s in the center of the provided [constraints].
*/
private fun MeasureScope.placeIcon(
iconPlaceable: Placeable,
indicatorRipplePlaceable: Placeable,
indicatorPlaceable: Placeable?,
constraints: Constraints
): MeasureResult {
val width = constraints.maxWidth
val height = constraints.maxHeight
val iconX = (width - iconPlaceable.width) / 2
val iconY = (height - iconPlaceable.height) / 2
val rippleX = (width - indicatorRipplePlaceable.width) / 2
val rippleY = (height - indicatorRipplePlaceable.height) / 2
return layout(width, height) {
indicatorPlaceable?.let {
val indicatorX = (width - it.width) / 2
val indicatorY = (height - it.height) / 2
it.placeRelative(indicatorX, indicatorY)
}
iconPlaceable.placeRelative(iconX, iconY)
indicatorRipplePlaceable.placeRelative(rippleX, rippleY)
}
}
/**
* Places the provided [Placeable]s in the correct position, depending on [alwaysShowLabel] and
* [animationProgress].
*
* When [alwaysShowLabel] is true, the positions do not move. The [iconPlaceable] will be placed
* near the top of the item and the [labelPlaceable] will be placed near the bottom, according to
* the spec.
*
* When [animationProgress] is 1 (representing the selected state), the positions will be the same
* as above.
*
* Otherwise, when [animationProgress] is 0, [iconPlaceable] will be placed in the center, like in
* [placeIcon], and [labelPlaceable] will not be shown.
*
* When [animationProgress] is animating between these values, [iconPlaceable] and [labelPlaceable]
* will be placed at a corresponding interpolated position.
*
* [indicatorRipplePlaceable] and [indicatorPlaceable] will always be placed in such a way that to
* share the same center as [iconPlaceable].
*
* @param labelPlaceable text label placeable inside this item
* @param iconPlaceable icon placeable inside this item
* @param indicatorRipplePlaceable indicator ripple placeable inside this item
* @param indicatorPlaceable indicator placeable inside this item, if it exists
* @param constraints constraints of the item
* @param alwaysShowLabel whether to always show the label for this item. If true, icon and label
* positions will not change. If false, positions transition between 'centered icon with no label'
* and 'top aligned icon with label'.
* @param animationProgress progress of the animation, where 0 represents the unselected state of
* this item and 1 represents the selected state. Values between 0 and 1 interpolate positions of
* the icon and label.
*/
private fun MeasureScope.placeLabelAndIcon(
labelPlaceable: Placeable,
iconPlaceable: Placeable,
indicatorRipplePlaceable: Placeable,
indicatorPlaceable: Placeable?,
constraints: Constraints,
alwaysShowLabel: Boolean,
animationProgress: Float,
): MeasureResult {
val height = constraints.maxHeight
// Label should be `ItemVerticalPadding` from the bottom
val labelY = height - labelPlaceable.height - NavigationBarItemVerticalPadding.roundToPx()
// Icon (when selected) should be `ItemVerticalPadding` from the top
val selectedIconY = NavigationBarItemVerticalPadding.roundToPx()
val unselectedIconY =
if (alwaysShowLabel) selectedIconY else (height - iconPlaceable.height) / 2
// How far the icon needs to move between unselected and selected states.
val iconDistance = unselectedIconY - selectedIconY
// The interpolated fraction of iconDistance that all placeables need to move based on
// animationProgress.
val offset = (iconDistance * (1 - animationProgress)).roundToInt()
val containerWidth = constraints.maxWidth
val labelX = (containerWidth - labelPlaceable.width) / 2
val iconX = (containerWidth - iconPlaceable.width) / 2
val rippleX = (containerWidth - indicatorRipplePlaceable.width) / 2
val rippleY = selectedIconY - IndicatorVerticalPadding.roundToPx()
return layout(containerWidth, height) {
indicatorPlaceable?.let {
val indicatorX = (containerWidth - it.width) / 2
val indicatorY = selectedIconY - IndicatorVerticalPadding.roundToPx()
it.placeRelative(indicatorX, indicatorY + offset)
}
if (alwaysShowLabel || animationProgress != 0f) {
labelPlaceable.placeRelative(labelX, labelY + offset)
}
iconPlaceable.placeRelative(iconX, selectedIconY + offset)
indicatorRipplePlaceable.placeRelative(rippleX, rippleY + offset)
}
}
private const val IndicatorRippleLayoutIdTag: String = "indicatorRipple"
private const val IndicatorLayoutIdTag: String = "indicator"
private const val IconLayoutIdTag: String = "icon"
private const val LabelLayoutIdTag: String = "label"
private val NavigationBarHeight: Dp = NavigationBarTokens.ContainerHeight
private const val ItemAnimationDurationMillis: Int = 100
/*@VisibleForTesting*/
internal val NavigationBarItemHorizontalPadding: Dp = 8.dp
/*@VisibleForTesting*/
internal val NavigationBarItemVerticalPadding: Dp = 16.dp
private val IndicatorHorizontalPadding: Dp =
(NavigationBarTokens.ActiveIndicatorWidth - NavigationBarTokens.IconSize) / 2
private val IndicatorVerticalPadding: Dp =
(NavigationBarTokens.ActiveIndicatorHeight - NavigationBarTokens.IconSize) / 2
private val IndicatorVerticalOffset: Dp = 12.dp