feat: add Button selected toggle state (MD3 expressive)

Add a `selected?: boolean` prop. When `true`, the button flips its
`shape` (round ↔ square) so the selected/unselected pair contrasts, and
for `outlined`/`text` modes adopts a filled tonal-selected appearance
(`secondaryContainer` background, `onSecondaryContainer` label, no
border). `accessibilityState.selected` is set so screen readers announce
the toggle state. Other modes keep their colors and only flip the shape.

The `selected` flag is threaded through `getButtonColors` and its
sub-helpers.

Author: azizbecha

src/components/Button/Button.tsx

@@ -77,6 +77,19 @@ export type Props = $Omit<
    * `borderRadius` in `style`.
    */
   shape?: ButtonShape;
+  /**
+   * Whether this button is in the selected state (Material Design 3
+   * expressive toggle). When `true`:
+   *
+   * - The `shape` is flipped: `'round'` becomes `'square'` and vice versa.
+   * - For `outlined` and `text` modes, the button adopts a filled
+   *   `secondaryContainer` appearance (matches `contained-tonal`).
+   * - `accessibilityState.selected` is set so screen readers announce the
+   *   toggle state.
+   *
+   * Other modes only flip the shape.
+   */
+  selected?: boolean;
   /**
    * @deprecated Deprecated in v5.x - use `buttonColor` or `textColor` instead.
    * Custom text color for flat button, or background color for contained button.
@@ -230,6 +243,7 @@ const Button = (
     mode = 'text',
     size,
     shape,
+    selected,
     dark,
     loading,
     icon,
@@ -355,8 +369,17 @@ const Button = (
     return radiusStyles;
   }, [style]);
 
-  const borderRadius = shape
-    ? getButtonShapeRadius({ size, shape })
+  // When the button is `selected`, flip the requested shape so the
+  // unselected/selected pair contrasts visually (round ↔ square).
+  const effectiveShape: ButtonShape | undefined = shape
+    ? selected
+      ? shape === 'round'
+        ? 'square'
+        : 'round'
+      : shape
+    : undefined;
+  const borderRadius = effectiveShape
+    ? getButtonShapeRadius({ size, shape: effectiveShape })
     : theme.shapes.corner.largeIncreased;
 
   const {
@@ -375,8 +398,9 @@ const Button = (
         mode,
         disabled,
         dark,
+        selected,
       }),
-    [customButtonColor, customTextColor, theme, mode, disabled, dark]
+    [customButtonColor, customTextColor, theme, mode, disabled, dark, selected]
   );
 
   const rippleColor = React.useMemo(
@@ -484,7 +508,7 @@ const Button = (
         accessibilityLabel={accessibilityLabel}
         accessibilityHint={accessibilityHint}
         accessibilityRole={accessibilityRole}
-        accessibilityState={{ disabled }}
+        accessibilityState={{ disabled, selected }}
         accessible={accessible}
         hitSlop={hitSlop}
         disabled={disabled}

src/components/Button/utils.tsx

@@ -152,6 +152,7 @@ type BaseProps = {
   isMode: (mode: ButtonMode) => boolean;
   theme: InternalTheme;
   disabled?: boolean;
+  selected?: boolean;
 };
 
 const isDark = ({
@@ -177,6 +178,7 @@ const getButtonBackgroundColor = ({
   theme,
   disabled,
   customButtonColor,
+  selected,
 }: BaseProps & {
   customButtonColor?: string;
 }) => {
@@ -192,6 +194,12 @@ const getButtonBackgroundColor = ({
     return colors.onSurface;
   }
 
+  // Selected toggle (only outlined/text adopt a filled "tonal-selected" look;
+  // contained / contained-tonal / elevated already render filled).
+  if (selected && (isMode('outlined') || isMode('text'))) {
+    return colors.secondaryContainer;
+  }
+
   if (isMode('elevated')) {
     return colors.surfaceContainerLow;
   }
@@ -214,6 +222,7 @@ const getButtonTextColor = ({
   customTextColor,
   backgroundColor,
   dark,
+  selected,
 }: BaseProps & {
   customTextColor?: string;
   backgroundColor: string;
@@ -228,6 +237,11 @@ const getButtonTextColor = ({
     return theme.colors.onSurface;
   }
 
+  // Selected toggle for outlined/text mirrors the contained-tonal label color.
+  if (selected && (isMode('outlined') || isMode('text'))) {
+    return colors.onSecondaryContainer;
+  }
+
   if (typeof dark === 'boolean') {
     if (
       isMode('contained') ||
@@ -253,15 +267,26 @@ const getButtonTextColor = ({
   return colors.primary;
 };
 
-const getButtonBorderColor = ({ isMode, theme }: BaseProps) => {
+const getButtonBorderColor = ({ isMode, theme, selected }: BaseProps) => {
+  // A selected outlined toggle drops its outline (the filled background takes
+  // over as the visual affordance).
+  if (selected && isMode('outlined')) {
+    return 'transparent';
+  }
   if (isMode('outlined')) {
     return theme.colors.outlineVariant;
   }
 
   return 'transparent';
 };
 
-const getButtonBorderWidth = ({ isMode }: Omit<BaseProps, 'disabled'>) => {
+const getButtonBorderWidth = ({
+  isMode,
+  selected,
+}: Omit<BaseProps, 'disabled' | 'theme'>) => {
+  if (selected && isMode('outlined')) {
+    return 0;
+  }
   if (isMode('outlined')) {
     return 1;
   }
@@ -276,13 +301,15 @@ export const getButtonColors = ({
   customTextColor,
   disabled,
   dark,
+  selected,
 }: {
   theme: InternalTheme;
   mode: ButtonMode;
   customButtonColor?: string;
   customTextColor?: string;
   disabled?: boolean;
   dark?: boolean;
+  selected?: boolean;
 }) => {
   const isMode = (modeToCompare: ButtonMode) => {
     return mode === modeToCompare;
@@ -293,6 +320,7 @@ export const getButtonColors = ({
     theme,
     disabled,
     customButtonColor,
+    selected,
   });
 
   const textColor = getButtonTextColor({
@@ -302,11 +330,12 @@ export const getButtonColors = ({
     customTextColor,
     backgroundColor,
     dark,
+    selected,
   });
 
-  const borderColor = getButtonBorderColor({ isMode, theme });
+  const borderColor = getButtonBorderColor({ isMode, theme, selected });
 
-  const borderWidth = getButtonBorderWidth({ isMode, theme });
+  const borderWidth = getButtonBorderWidth({ isMode, selected });
 
   const textOpacity = disabled ? stateOpacity.disabled : stateOpacity.enabled;
 

src/components/__tests__/Button.test.tsx

@@ -935,6 +935,75 @@ describe('shape prop', () => {
   });
 });
 
+describe('selected prop', () => {
+  it('sets accessibilityState.selected', () => {
+    const { getByTestId } = render(
+      <Button testID="button" selected onPress={() => {}} label="X" />
+    );
+
+    expect(getByTestId('button').props.accessibilityState).toMatchObject({
+      selected: true,
+    });
+  });
+
+  it('flips a round button into the square radius when selected', () => {
+    const { getByTestId } = render(
+      <Button testID="button" size="large" shape="round" selected label="X" />
+    );
+
+    expect(getByTestId('button-container')).toHaveStyle({ borderRadius: 28 });
+  });
+
+  it('flips a square button into the round radius when selected', () => {
+    const { getByTestId } = render(
+      <Button testID="button" shape="square" selected label="X" />
+    );
+
+    expect(getByTestId('button-container')).toHaveStyle({ borderRadius: 9999 });
+  });
+
+  it('gives an outlined button the tonal-selected appearance', () => {
+    expect(
+      getButtonColors({
+        theme: getTheme(),
+        mode: 'outlined',
+        selected: true,
+      })
+    ).toMatchObject({
+      backgroundColor: getTheme().colors.secondaryContainer,
+      textColor: getTheme().colors.onSecondaryContainer,
+      borderColor: 'transparent',
+      borderWidth: 0,
+    });
+  });
+
+  it('gives a text-mode button the tonal-selected appearance', () => {
+    expect(
+      getButtonColors({
+        theme: getTheme(),
+        mode: 'text',
+        selected: true,
+      })
+    ).toMatchObject({
+      backgroundColor: getTheme().colors.secondaryContainer,
+      textColor: getTheme().colors.onSecondaryContainer,
+    });
+  });
+
+  it('does not change contained colors when selected', () => {
+    expect(
+      getButtonColors({
+        theme: getTheme(),
+        mode: 'contained',
+        selected: true,
+      })
+    ).toMatchObject({
+      backgroundColor: getTheme().colors.primary,
+      textColor: getTheme().colors.onPrimary,
+    });
+  });
+});
+
 it('animated value changes correctly', () => {
   const value = new Animated.Value(1);
   const { getByTestId } = render(