feat(ios): add backgroundColor prop to top bar buttons

[IsaacIsrael]

Problem

On iOS 26, React Native Navigation exposes no way to set a solid background color on the circular Liquid Glass platter that UIKit draws behind each bar button item. Apps may want to highlight specific buttons (e.g., a primary action) with a colored background.

Solution

Add a new backgroundColor property to OptionsTopBarButton (TypeScript) and RNNButtonOptions (native) that sets a solid UIColor on the platter container view behind React component bar buttons.

Native changes

• RNNButtonOptions.h/mm — parse, copy, and merge backgroundColor (Color)
• RNNButtonBuilder.mm — pass [button.backgroundColor withDefault:nil] to RNNReactButtonView.buttonBackgroundColor
• RNNReactButtonView.h — new buttonBackgroundColor property
• RNNReactButtonView.mm — syncButtonBackground method targets the _UINavigationBarPlatterSubviewContainerView (self.superview.superview.superview) and applies:
  • backgroundColor (or clearColor when nil — prevents color leaking between buttons)
  • cornerRadius = bounds.height / 2 to maintain the circular shape
  • clipsToBounds = YES
  • Called from both didMoveToWindow (early, prevents flash on push) and layoutSubviews (handles re-layouts)

TypeScript changes

• Options.ts — add backgroundColor?: Color to OptionsTopBarButton

Depends on: #8300

Usage

rightButtons: [{
  id: 'save',
  component: { name: 'SaveButton' },
  backgroundColor: 'yellow',  // fills the circular platter
}]

Test plan

• Set backgroundColor: 'yellow' on a top bar button — verify the entire circular platter is filled
• Navigate to a screen without backgroundColor — verify no color leaks to other buttons
• Navigate back to the colored button — verify it re-applies without visible flash or square shape
• Test with multiple colors (green, red, blue)
• Verify buttons without backgroundColor remain unaffected

Made with Cursor