feat: Appbar MD3 Expressive improvements

docs/6.x/docs/guides/migration.md

@@ -10,7 +10,7 @@ React Native Paper 6 uses [Reanimated](https://docs.swmansion.com/react-native-r
 
 The following props now accept animated styles returned from `useAnimatedStyle`. They no longer accept `Animated.Value` or `Animated.AnimatedInterpolation` where these were previously supported:
 
-- `Appbar.Action` and `Appbar.BackAction`: `style`
+- `Appbar`: `style`
 - `Badge`: `style`
 - `Banner`: `style`
 - `Button`: `style`
@@ -72,8 +72,6 @@ You can use the component's color prop where available, or override the correspo
 
 Hardcoded default test IDs have been removed for the components listed below:
 
-- `Appbar.Content`: `appbar-content`
-- `Appbar.Header`: `appbar-header`
 - `BottomNavigation`: `bottom-navigation`
 - `BottomNavigation.Bar`: `bottom-navigation-bar`
 - `Button`: `button`
@@ -110,9 +108,62 @@ Some components now accept explicit `testID` props for their interactable elemen
 
 ### Appbar
 
-The `style` props for `Appbar` and `Appbar.Header` no longer accept `Animated.Value` or `Animated.AnimatedInterpolation`. They only accept static styles.
+The Paper 6.x `Appbar` is a big refatctor, which drops the previously used compound component approach.
 
-The `style.elevation` property is no longer supported. Use the `elevated` prop to control Appbar elevation.
+#### Migrating from the compound API
+
+`Appbar.Header`, `Appbar.Content`, `Appbar.Action`, and `Appbar.BackAction` have been removed. Render one `Appbar` and provide its headline, leading button, and trailing actions as props. The former `mode="medium"` and `mode="large"` values are now `variant="medium-flexible"` and `variant="large-flexible"`; centered content uses `headlineAlignment="center"`.
+
+```tsx
+// Before (v5)
+
+const MyComponent = () => (
+  <Appbar.Header>
+    <Appbar.BackAction onPress={() => {}} />
+    <Appbar.Content title="Inbox" />
+    <Appbar.Action icon="search" onPress={() => {}} />
+    <Appbar.Action icon="dots-vertical" onPress={() => {}} />
+  </Appbar.Header>
+);
+
+// After (v6)
+
+const MyComponent = () => (
+  <Appbar
+    variant="small"
+    headline="Inbox"
+    leadingButton={{ type: 'back', onPress: () => {} }}
+    trailingActions={[
+      {
+        key: 'search',
+        icon: 'magnify',
+        'aria-label': 'Search',
+        onPress: () => {},
+      },
+      {
+        key: 'more',
+        icon: 'dots-vertical',
+        'aria-label': 'More options',
+        onPress: () => {},
+      },
+    ]}
+  />
+);
+```
+
+`Appbar`'s props are a single flat type shared by every `variant`. Passing a prop to a variant it doesn't apply to doesn't raise a type error — each prop's own JSDoc states which variant(s) it's usable for:
+
+- Usable only for `small`, `medium-flexible`, and `large-flexible`: `headline`, `subtitle`, `headlineProps`, `subtitleProps`, `headlineImage`, `headlineAlignment`, `contentStyle`, `onHeadlinePress`, `headlinePressableProps`. Omitting `headline` logs a development warning.
+- Usable only for `search`: `searchBar`. Omitting it logs a development warning.
+- Usable for every variant, including `search`: `trailingActions`, using the same shape — a standard array, or a single filled/tonal action — everywhere, though a filled/tonal action isn't intended for `search`.
+
+#### Bottom toolbar support
+
+Material Design 3 drops the bottom bar support contained previously in the `Appbar` scope and moves it to `Toolbars`, hence you can't use the component to construct a bottom bar anymore - for these cases please use the `Toolbar` component.
+
+#### Test IDs
+
+`Appbar` no longer derives internal, implementation-only test IDs (e.g. for its surface, content, or search layout wrappers) from the `testID` prop. Only the `testID` prop itself is set on the root element; the `Searchbar` rendered by the `search` variant accepts its own `testID` through `searchBar.testID`.
 
 ### Surface
 

docs/6.x/docs/guides/react-navigation.md

@@ -136,11 +136,7 @@ Now we will implement `CustomNavigationBar` using `AppBar` component:
 import { Appbar } from 'react-native-paper';
 
 export default function CustomNavigationBar() {
-  return (
-    <Appbar.Header>
-      <Appbar.Content title="My awesome app" />
-    </Appbar.Header>
-  );
+  return <Appbar variant="small" headline="My awesome app" />;
 }
 ```
 
@@ -154,11 +150,7 @@ import { getHeaderTitle } from '@react-navigation/elements';
 export default function CustomNavigationBar({ route, options }) {
   const title = getHeaderTitle(options, route.name);
 
-  return (
-    <Appbar.Header>
-      <Appbar.Content title={title} />
-    </Appbar.Header>
-  );
+  return <Appbar variant="small" headline={title} />;
 }
 ```
 
@@ -179,10 +171,13 @@ export default function CustomNavigationBar({
   const title = getHeaderTitle(options, route.name);
 
   return (
-    <Appbar.Header>
-      {back ? <Appbar.BackAction onPress={navigation.goBack} /> : null}
-      <Appbar.Content title={title} />
-    </Appbar.Header>
+    <Appbar
+      variant="small"
+      headline={title}
+      leadingButton={
+        back ? { type: 'back', onPress: navigation.goBack } : undefined
+      }
+    />
   );
 }
 ```
@@ -194,8 +189,8 @@ export default function CustomNavigationBar({
 Another interesting pattern that can be implemented with `react-native-paper` and `react-navigation` is a "menu" button. Thanks to the `Menu` component we can add a nice looking pop-up to our `Appbar`. To implement this feature we need to make a couple of changes in `CustomNavigationBar`:
 
 - Render a `Menu` component
-- Pass `Appbar.Action` to the anchor prop
-- Add a state to control `Menu` visibility
+- Add a trailing action to `Appbar`
+- Store the action coordinates and menu visibility in state
 
 :::note
 To have properly working `Menu` component, remember to wrap your root component with the `PaperProvider`:
@@ -236,21 +231,41 @@ export default function CustomNavigationBar({
   back,
 }) {
   const [visible, setVisible] = React.useState(false);
+  const [menuAnchor, setMenuAnchor] = React.useState({ x: 0, y: 0 });
   const openMenu = () => setVisible(true);
   const closeMenu = () => setVisible(false);
 
   const title = getHeaderTitle(options, route.name);
 
   return (
-    <Appbar.Header>
-      {back ? <Appbar.BackAction onPress={navigation.goBack} /> : null}
-      <Appbar.Content title={title} />
+    <>
+      <Appbar
+        variant="small"
+        headline={title}
+        leadingButton={
+          back ? { type: 'back', onPress: navigation.goBack } : undefined
+        }
+        trailingActions={
+          back
+            ? []
+            : [
+                {
+                  key: 'more',
+                  icon: 'dots-vertical',
+                  'aria-label': 'More options',
+                  onPress: (event) => {
+                    setMenuAnchor({
+                      x: event.nativeEvent.pageX,
+                      y: event.nativeEvent.pageY,
+                    });
+                    openMenu();
+                  },
+                },
+              ]
+        }
+      />
       {!back ? (
-        <Menu
-          visible={visible}
-          onDismiss={closeMenu}
-          anchor={<Appbar.Action icon="dots-vertical" onPress={openMenu} />}
-        >
+        <Menu visible={visible} onDismiss={closeMenu} anchor={menuAnchor}>
           <Menu.Item
             onPress={() => {
               console.log('Option 1 was pressed');
@@ -272,7 +287,7 @@ export default function CustomNavigationBar({
           />
         </Menu>
       ) : null}
-    </Appbar.Header>
+    </>
   );
 }
 ```

docs/6.x/docs/guides/theming-with-react-navigation.md

@@ -249,24 +249,25 @@ Now that the Context is available at every component, all we need to do is impor
 
 ```js
 import React from 'react';
-import { useTheme, Appbar, TouchableRipple, Switch } from 'react-native-paper';
+import { Appbar } from 'react-native-paper';
 import { PreferencesContext } from './PreferencesContext';
 
 const Header = ({ scene }) => {
-  const theme = useTheme();
   const { toggleTheme, isThemeDark } = React.useContext(PreferencesContext);
 
   return (
-    <Appbar.Header
-      theme={{
-        colors: {
-          primary: theme?.colors.surface,
+    <Appbar
+      variant="small"
+      headline={scene.route?.name}
+      trailingActions={[
+        {
+          key: 'theme',
+          icon: isThemeDark ? 'weather-sunny' : 'weather-night',
+          'aria-label': 'Toggle color theme',
+          onPress: toggleTheme,
         },
-      }}
-    >
-      <Appbar.Content title={scene.route?.name} />
-      <Switch color={'red'} value={isThemeDark} onValueChange={toggleTheme} />
-    </Appbar.Header>
+      ]}
+    />
   );
 };
 ```

docs/component-docs.config.ts

@@ -33,11 +33,11 @@ type ComponentDocsConfig = {
 const pages = {
   ActivityIndicator: 'ActivityIndicator',
   Appbar: {
-    Appbar: 'Appbar/Appbar',
-    AppbarAction: 'Appbar/AppbarAction',
-    AppbarBackAction: 'Appbar/AppbarBackAction',
-    AppbarContent: 'Appbar/AppbarContent',
-    AppbarHeader: 'Appbar/AppbarHeader',
+    source: 'Appbar/Appbar',
+    // The default export is the memoized `MemoizedAppbar`, but the JSDoc
+    // lives on the inner `Appbar` declaration — same pattern as `Portal`
+    // and `Typography/Text` below.
+    component: 'Appbar',
   },
   Avatar: {
     AvatarIcon: 'Avatar/AvatarIcon',

docs/src/data/screenshots.ts

@@ -1,18 +1,14 @@
 export const screenshots = {
   ActivityIndicator: 'screenshots/activity-indicator.gif',
-  Appbar: 'screenshots/appbar.png',
-  'Appbar.Action': 'screenshots/appbar-action-android.png',
-  'Appbar.BackAction': 'screenshots/appbar-backaction-android.png',
-  'Appbar.Content': 'screenshots/appbar-content.png',
-  'Appbar.Header': {
-    small: 'screenshots/appbar-small.png',
-    medium: 'screenshots/appbar-medium.png',
-    large: 'screenshots/appbar-large.png',
-    'center-aligned': 'screenshots/appbar-center-aligned.png',
-  },
   'Avatar.Icon': 'screenshots/avatar-icon.png',
   'Avatar.Image': 'screenshots/avatar-image.png',
   'Avatar.Text': 'screenshots/avatar-text.png',
+  Appbar: {
+    search: 'screenshots/appbar-v6-search.png',
+    small: 'screenshots/appbar-v6-small.png',
+    'medium flexible': 'screenshots/appbar-v6-medium-flexible.png',
+    'large flexible': 'screenshots/appbar-v6-large-flexible.png',
+  },
   Badge: {
     'with text': 'screenshots/badge-1.png',
     'without text': 'screenshots/badge-2.png',

docs/src/data/themeColors.ts

@@ -8,29 +8,20 @@ export const themeColors = {
     default: {
       backgroundColor: 'theme.colors.surface',
     },
-    elevated: {
-      backgroundColor: 'theme.colors.elevation.level2',
+    scrolled: {
+      backgroundColor: 'theme.colors.surfaceContainer',
     },
-  },
-  'Appbar.Action': {
-    'leading icon': {
+    'leading action': {
       iconColor: 'theme.colors.onSurface',
     },
-    'not leading icon': {
+    'trailing action': {
       iconColor: 'theme.colors.onSurfaceVariant',
     },
-  },
-  'Appbar.Content': {
-    '-': {
+    headline: {
       textColor: 'theme.colors.onSurface',
     },
-  },
-  'Appbar.Header': {
-    default: {
-      backgroundColor: 'theme.colors.surface',
-    },
-    elevated: {
-      backgroundColor: 'theme.colors.elevation.level2',
+    subtitle: {
+      textColor: 'theme.colors.onSurfaceVariant',
     },
   },
   Banner: {

docs/src/data/versionRouteFallbacks.json

@@ -1,5 +1,10 @@
 {
   "next": {
+    "/docs/components/Appbar/Appbar": "/6.x/docs/components/Appbar",
+    "/docs/components/Appbar/AppbarAction": "/6.x/docs/components/Appbar",
+    "/docs/components/Appbar/AppbarBackAction": "/6.x/docs/components/Appbar",
+    "/docs/components/Appbar/AppbarContent": "/6.x/docs/components/Appbar",
+    "/docs/components/Appbar/AppbarHeader": "/6.x/docs/components/Appbar",
     "/docs/components/Checkbox/CheckboxAndroid": "/6.x/docs/components/Checkbox/Checkbox",
     "/docs/components/Checkbox/CheckboxIOS": "/6.x/docs/components/Checkbox/Checkbox",
     "/docs/components/FAB/AnimatedFAB": "/6.x/docs/components/FAB/FAB",
@@ -9,6 +14,7 @@
     "/docs/guides/migration-guide-to-5.0": "/6.x/docs/guides/migration"
   },
   "stable": {
+    "/6.x/docs/components/Appbar": "/docs/components/Appbar/Appbar",
     "/6.x/docs/components/FAB/FABExtended": "/docs/components/FAB/FAB",
     "/6.x/docs/components/FAB/FABMenu": "/docs/components/FAB/FAB",
     "/6.x/docs/guides/migration": "/docs/guides/migration-guide-to-5.0",