fix(fab): address review feedback

Remove the surface preset and static elevation override. Apply hover elevation across platforms and restore focus when hiding a focused FAB.

Separate hidden and disabled semantics, and rewrite the migration guide around v5 consumer changes.

Author: likevy

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

@@ -161,21 +161,30 @@ e.g.:
 
 ### FAB
 
-The color presets for `FAB` and `FAB.Extended` now match the MD3 color roles:
-`primary`, `primaryContainer` (default), `secondary`, `secondaryContainer`,
-`tertiary`, `tertiaryContainer`, `surface`, and `branded`.
+To preserve the v5 FAB color treatment, update the `variant` prop:
 
-If you used an earlier 6.x build, replace `tonalPrimary`, `tonalSecondary`, and
-`tonalTertiary` with `primaryContainer`, `secondaryContainer`, and
-`tertiaryContainer`. The old names have been removed without aliases. This also
-applies to the FAB menu trigger's `variant`.
+| v5 | v6 |
+| --- | --- |
+| `primary` | `primaryContainer` |
+| `secondary` | `secondaryContainer` |
+| `tertiary` | `tertiaryContainer` |
 
-Both `surface` and `branded` use `surfaceContainerHigh`. Surface FAB content uses
-`primary`; branded content defaults to `onSurface`. A custom icon source can
-render brand artwork in its own colors.
+If you omit `variant`, no change is needed. Replace `variant="surface"` with
+one of the supported color variants, such as `primaryContainer`.
 
-On web, hovering a FAB raises its elevation from level 3 to level 4. Focused and
-pressed states use level 3. The large FAB icon remains **36dp**.
+For custom colors, replace `color` with `contentColor` and move
+`style.backgroundColor` to `containerColor`:
+
+```diff
+<FAB
+  icon="plus"
+- color="#ffffff"
+- style={{ backgroundColor: '#6750a4', position: 'absolute', bottom: 16, right: 16 }}
++ contentColor="#ffffff"
++ containerColor="#6750a4"
++ style={{ position: 'absolute', bottom: 16, right: 16 }}
+/>
+```
 
 ### TextInput
 

example/src/Examples/FABExample.tsx

@@ -37,7 +37,6 @@ const variants: FabColor[] = [
   'primaryContainer',
   'secondaryContainer',
   'tertiaryContainer',
-  'surface',
   'branded',
   'custom',
 ];
@@ -141,9 +140,7 @@ const FABExample = () => {
         <ChipRow
           label="Color"
           options={
-            type === 'menu'
-              ? variants.filter((v) => v !== 'surface' && v !== 'branded')
-              : variants
+            type === 'menu' ? variants.filter((v) => v !== 'branded') : variants
           }
           value={variant}
           onChange={setVariant}
@@ -154,10 +151,7 @@ const FABExample = () => {
           options={types}
           value={type}
           onChange={(nextType) => {
-            if (
-              nextType === 'menu' &&
-              (variant === 'surface' || variant === 'branded')
-            ) {
+            if (nextType === 'menu' && variant === 'branded') {
               setVariant('primaryContainer');
             }
             setType(nextType);
@@ -234,10 +228,7 @@ const FABExample = () => {
           alignment={position}
           trigger={{
             icon: 'pencil',
-            variant:
-              activeVariant === 'surface' || activeVariant === 'branded'
-                ? undefined
-                : activeVariant,
+            variant: activeVariant === 'branded' ? undefined : activeVariant,
             containerColor: activeContainerColor,
             size,
             visible: showFab,

src/components/FAB/Extended.tsx

@@ -39,11 +39,6 @@ export type Props = {
   label: string;
   /**
    * Role-color preset. Defaults to `primaryContainer`.
-   * Choose `primary`, `primaryContainer`, `secondary`, `secondaryContainer`,
-   * `tertiary`, `tertiaryContainer`, `surface`, or `branded`.
-   * `surface` and `branded` use `surfaceContainerHigh`; `surface` uses primary
-   * content, while `branded` uses on-surface content. Pass a custom icon source
-   * to preserve brand artwork colors.
    */
   variant?: Variant;
   /**

src/components/FAB/FAB.tsx

@@ -22,11 +22,6 @@ export type Props = {
   icon: IconSource;
   /**
    * Role-color preset. Defaults to `primaryContainer`.
-   * Choose `primary`, `primaryContainer`, `secondary`, `secondaryContainer`,
-   * `tertiary`, `tertiaryContainer`, `surface`, or `branded`.
-   * `surface` and `branded` use `surfaceContainerHigh`; `surface` uses primary
-   * content, while `branded` uses on-surface content. Pass a custom icon source
-   * to preserve brand artwork colors.
    */
   variant?: Variant;
   /**

src/components/FAB/Menu.tsx

@@ -55,7 +55,7 @@ export type MenuItemProps = {
   testID?: string;
 };
 
-type MenuVariant = Exclude<Variant, 'surface' | 'branded'>;
+type MenuVariant = Exclude<Variant, 'branded'>;
 
 export type MenuTriggerProps = {
   /**
@@ -457,7 +457,6 @@ const MorphingTrigger = ({
       testID={testID}
     >
       <Shell
-        elevation={Tokens.stateElevation.enabled}
         size={size}
         variant={triggerVariant}
         containerColor={triggerContainerColor}

src/components/FAB/Shell.tsx

@@ -29,7 +29,7 @@ import { getDimensions, resolveColors } from './utils';
 import { useInternalTheme } from '../../core/theming';
 import { useReduceMotion } from '../../theme/accessibility/ReduceMotionContext';
 import { toRawSpring } from '../../theme/tokens/sys/motion';
-import type { Elevation, ThemeProp } from '../../theme/types';
+import type { ThemeProp } from '../../theme/types';
 import type { ShapeToken } from '../../theme/utils/shape';
 import type { IconSource } from '../Icon';
 import Surface from '../Surface';
@@ -77,11 +77,6 @@ export type ShellProps = {
    * Trailing-padding override.
    */
   trailing?: number;
-  /**
-   * Resting elevation level. Defaults to the FAB's enabled-state elevation.
-   * Pass `0` to disable the shadow entirely.
-   */
-  elevation?: Elevation;
   /**
    * When `false`, the shell animates out (scale + alpha) and stops accepting
    * touches.
@@ -194,7 +189,6 @@ const Shell = ({
   iconSize,
   leading,
   trailing,
-  elevation,
   visible = true,
   onPress,
   'aria-label': ariaLabel = label,
@@ -219,21 +213,17 @@ const Shell = ({
   const theme = useInternalTheme(themeOverrides);
   const [hovered, setHovered] = React.useState(false);
   const [pressed, setPressed] = React.useState(false);
-  const [focused, setFocused] = React.useState(false);
   const touchableRef = React.useRef<View>(null);
+  const previousFocusedElement = React.useRef<HTMLElement | null>(null);
 
-  // Explicit elevations (including flat menu items) keep their own treatment.
   const resolvedElevation =
-    elevation ??
-    (Platform.OS === 'web' && visible && onPress
+    visible && onPress
       ? pressed
         ? Tokens.stateElevation.pressed
-        : focused
-          ? Tokens.stateElevation.focus
-          : hovered
-            ? Tokens.stateElevation.hover
-            : Tokens.stateElevation.enabled
-      : Tokens.stateElevation.enabled);
+        : hovered
+          ? Tokens.stateElevation.hover
+          : Tokens.stateElevation.enabled
+      : Tokens.stateElevation.enabled;
 
   const dimensions = React.useMemo(
     () => getDimensions({ theme, size, shape, iconSize, leading, trailing }),
@@ -317,16 +307,32 @@ const Shell = ({
   const { focusedSV, onFocus, onBlur } = useFocusRing();
 
   React.useEffect(() => {
-    if (!visible || !onPress) {
-      if (Platform.OS === 'web') {
-        touchableRef.current?.blur();
+    if (!visible) {
+      if (Platform.OS === 'web' && typeof document !== 'undefined') {
+        const target: unknown = touchableRef.current;
+        if (
+          target instanceof HTMLElement &&
+          target === document.activeElement
+        ) {
+          if (previousFocusedElement.current?.isConnected) {
+            previousFocusedElement.current.focus({ preventScroll: true });
+          }
+          // The previous element may have been removed or become unfocusable.
+          if (target === document.activeElement) target.blur();
+        }
       }
       setHovered(false);
       setPressed(false);
-      setFocused(false);
       onBlur();
     }
-  }, [visible, onPress, onBlur]);
+  }, [visible, onBlur]);
+
+  React.useEffect(() => {
+    if (!onPress) {
+      setHovered(false);
+      setPressed(false);
+    }
+  }, [onPress]);
 
   const focusRingStyle = useAnimatedStyle(
     () => ({
@@ -359,19 +365,26 @@ const Shell = ({
           borderless
           background={background}
           onPress={visible ? onPress : undefined}
-          disabled={!onPress || !visible}
+          disabled={!onPress}
+          accessible={visible}
+          focusable={visible && !!onPress}
+          tabIndex={visible ? undefined : -1}
           onHoverIn={() => setHovered(true)}
           onHoverOut={() => setHovered(false)}
           onPressIn={() => setPressed(true)}
           onPressOut={() => setPressed(false)}
-          onFocus={() => {
-            setFocused(true);
+          onFocus={(event) => {
+            if (Platform.OS === 'web') {
+              const previous =
+                'relatedTarget' in event.nativeEvent
+                  ? event.nativeEvent.relatedTarget
+                  : null;
+              previousFocusedElement.current =
+                previous instanceof HTMLElement ? previous : null;
+            }
             onFocus();
           }}
-          onBlur={() => {
-            setFocused(false);
-            onBlur();
-          }}
+          onBlur={onBlur}
           aria-label={ariaLabel}
           role="button"
           aria-checked={ariaChecked}

src/components/FAB/tokens.ts

@@ -15,7 +15,6 @@ export type Variant =
   | 'primaryContainer'
   | 'secondaryContainer'
   | 'tertiaryContainer'
-  | 'surface'
   | 'branded';
 
 export type Size = 'default' | 'medium' | 'large';
@@ -70,7 +69,7 @@ const stateElevation = {
 } as const satisfies Record<string, Elevation>;
 
 const variants = {
-  surface: { container: 'surfaceContainerHigh', content: 'primary' },
+  // Branded artwork has no prescribed icon color; onSurface is a fallback.
   branded: { container: 'surfaceContainerHigh', content: 'onSurface' },
   primary: { container: 'primary', content: 'onPrimary' },
   secondary: { container: 'secondary', content: 'onSecondary' },

src/components/__tests__/FAB.test.tsx

@@ -10,7 +10,6 @@ import {
   shadow,
 } from '../../theme/tokens/sys/elevation';
 import FAB from '../FAB';
-import Shell from '../FAB/Shell';
 
 afterEach(() => {
   jest.restoreAllMocks();
@@ -150,20 +149,12 @@ it.each(['icon', 'extended'] as const)(
   }
 );
 
-it('keeps an explicit shell elevation of zero on hover', async () => {
-  jest.replaceProperty(Platform, 'OS', 'web');
-  await render(<Shell icon="plus" onPress={() => {}} elevation={0} />);
-  await fireEvent(screen.getByTestId('fab-shell'), 'hoverIn');
-  const [flatShadow] = shadow(0, getTheme().colors.shadow);
-  expect(screen.getByTestId('fab-shell-container')).toHaveStyle(flatShadow);
-});
-
 it('does not enable a FAB without an action when adding interaction handlers', async () => {
   await render(<FAB icon="plus" aria-label="Create" />);
   expect(screen.getByRole('button', { name: 'Create' })).toBeDisabled();
 });
 
-it('hides an invisible FAB from accessibility and disables its action', async () => {
+it('hides an invisible FAB from accessibility and keyboard navigation without marking it disabled', async () => {
   const onPress = jest.fn();
   await render(
     <FAB icon="plus" aria-label="Create" onPress={onPress} visible={false} />
@@ -172,7 +163,10 @@ it('hides an invisible FAB from accessibility and disables its action', async ()
   const fab = screen.getByTestId('floating-action-button', {
     includeHiddenElements: true,
   });
-  expect(fab).toBeDisabled();
+  expect(fab).not.toBeDisabled();
+  expect(fab).toHaveProp('accessible', false);
+  expect(fab).toHaveProp('focusable', false);
+  expect(fab).toHaveProp('tabIndex', -1);
   await userEvent.press(fab);
   expect(onPress).not.toHaveBeenCalled();
 });
@@ -190,7 +184,7 @@ it('clears interaction elevation when a FAB is hidden and shown again', async ()
   );
 });
 
-it('keeps the menu trigger at its existing elevation on web', async () => {
+it('uses the shared FAB hover elevation for the menu trigger', async () => {
   jest.replaceProperty(Platform, 'OS', 'web');
   await render(
     <FAB.Menu
@@ -204,22 +198,40 @@ it('keeps the menu trigger at its existing elevation on web', async () => {
     />
   );
   await fireEvent(screen.getByTestId('fab-shell'), 'hoverIn');
-  const [restingShadow] = shadow(3, getTheme().colors.shadow);
-  expect(screen.getByTestId('fab-shell-container')).toHaveStyle(restingShadow);
+  const [hoverShadow] = shadow(4, getTheme().colors.shadow);
+  expect(screen.getByTestId('fab-shell-container')).toHaveStyle(hoverShadow);
 });
 
 it.each(['ios', 'android'] as const)(
-  'keeps native elevation unchanged on hover on %s',
+  'applies hover elevation alongside focus and restores it after press on %s',
   async (platform) => {
     jest.replaceProperty(Platform, 'OS', platform);
     await render(<FAB icon="plus" onPress={() => {}} />);
-    await fireEvent(screen.getByTestId('floating-action-button'), 'hoverIn');
+    const fab = screen.getByTestId('floating-action-button');
+    const container = screen.getByTestId('floating-action-button-container');
     const [restingShadow] = shadow(3, getTheme().colors.shadow);
-    expect(screen.getByTestId('floating-action-button-container')).toHaveStyle(
+    const [hoverShadow] = shadow(4, getTheme().colors.shadow);
+    const restingStyle =
       platform === 'android'
         ? { elevation: androidElevationLevels[3] }
-        : restingShadow
-    );
+        : restingShadow;
+    const hoverStyle =
+      platform === 'android'
+        ? { elevation: androidElevationLevels[4] }
+        : hoverShadow;
+
+    await fireEvent(fab, 'focus', { nativeEvent: {} });
+    expect(container).toHaveStyle(restingStyle);
+    await fireEvent(fab, 'hoverIn');
+    expect(container).toHaveStyle(hoverStyle);
+    await fireEvent(fab, 'focus', { nativeEvent: {} });
+    expect(container).toHaveStyle(hoverStyle);
+    await fireEvent(fab, 'pressIn');
+    expect(container).toHaveStyle(restingStyle);
+    await fireEvent(fab, 'pressOut');
+    expect(container).toHaveStyle(hoverStyle);
+    await fireEvent(fab, 'hoverOut');
+    expect(container).toHaveStyle(restingStyle);
   }
 );
 

src/components/__tests__/FABUtils.test.tsx

@@ -5,7 +5,7 @@ import { getDimensions, resolveColors } from '../FAB/utils';
 
 describe('resolveColors', () => {
   it.each([false, true])(
-    'resolves every MD3 color variant (dark=%s)',
+    'resolves every FAB color preset (dark=%s)',
     (dark) => {
       const theme = getTheme(dark);
       const variants = {
@@ -15,7 +15,6 @@ describe('resolveColors', () => {
         secondaryContainer: ['secondaryContainer', 'onSecondaryContainer'],
         tertiary: ['tertiary', 'onTertiary'],
         tertiaryContainer: ['tertiaryContainer', 'onTertiaryContainer'],
-        surface: ['surfaceContainerHigh', 'primary'],
         branded: ['surfaceContainerHigh', 'onSurface'],
       } as const;
 
@@ -26,7 +25,6 @@ describe('resolveColors', () => {
         'secondaryContainer',
         'tertiary',
         'tertiaryContainer',
-        'surface',
         'branded',
       ] as const;
       for (const variant of variantNames) {