feat: Initial code for menu in header items

[kmichalikk]

Closes https://github.com/software-mansion/react-native-screens-labs/issues/1178

Description

This PR adds some initial configuration for displaying nested header menus.

Changes

• added menu prop for InlineHeaderItems
• the menu can be given type "menu" | "menuItem", a title and a children for submenus

Before & after - visual documentation

Test plan

Added SFT test-stack-header-menu-ios. It includes only basic features and will be extended in the future.

Checklist

• Included code example that can be used to test this change.
• For visual changes, included screenshots / GIFs / recordings documenting the change.
• For API changes, updated relevant public types.
• Ensured that CI passes

[Copilot]

Pull request overview

This PR introduces an initial (experimental) nested header-menu configuration for the gamma iOS stack header items, wiring a new menu prop from JS types through Fabric props into native iOS menu construction, and adds a Single Feature Test scenario to exercise basic nested menu rendering.

Changes:

• Added a menu prop to gamma stack header inline items (including Fabric native props) plus new TypeScript menu shape types.
• Implemented iOS-side mapping from JS dictionaries into native menu data objects and a coordinator that builds UIMenu / UIAction trees.
• Added an iOS-only SFT scenario (test-stack-header-menu-ios) and registered it in the stack-v5 scenario index.

Reviewed changes

Copilot reviewed 18 out of 18 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
src/fabric/gamma/stack/StackHeaderItemIOSNativeComponent.ts	Adds menu prop to Fabric native component props (UnsafeMixed).
src/components/gamma/stack/header/StackHeaderConfig.ios.types.ts	Extends inline header item types to accept an optional menu.
src/components/gamma/stack/header/ios/StackHeaderMenu.ios.types.ts	New TS types describing nested menu structures.
src/components/gamma/stack/header/ios/StackHeaderItem.ios.types.ts	Extends stack header item props with optional menu.
ios/gamma/stack/header/RNSStackHeaderMenuMapper.h	Declares native mapper that parses JS dictionaries into menu data.
ios/gamma/stack/header/RNSStackHeaderMenuMapper.mm	Implements parsing/validation of menu dictionaries into native data objects.
ios/gamma/stack/header/RNSStackHeaderMenuData.h	Defines native menu/menuItem data models and protocol for menu elements.
ios/gamma/stack/header/RNSStackHeaderMenuData.mm	Implements native menu/menuItem data model initializers.
ios/gamma/stack/header/RNSStackHeaderMenuCoordinator.h	Declares coordinator that applies native menus to bar button items.
ios/gamma/stack/header/RNSStackHeaderMenuCoordinator.mm	Builds UIMenu/UIAction trees and applies them to UIBarButtonItem.
ios/gamma/stack/header/RNSStackHeaderItemDataProviding.h	Extends header item data protocol with a menu property.
ios/gamma/stack/header/RNSStackHeaderItemComponentView.h	Exposes menu property on the component view implementing the protocol.
ios/gamma/stack/header/RNSStackHeaderItemComponentView.mm	Converts Fabric menu prop to native menu data and triggers invalidation.
ios/gamma/stack/header/RNSStackHeaderContentFactory.mm	Applies a parsed menu to the produced UIBarButtonItem.
apps/src/tests/single-feature-tests/stack-v5/test-stack-header-menu-ios/scenario.md	Adds manual test steps for nested header menu behavior on iOS.
apps/src/tests/single-feature-tests/stack-v5/test-stack-header-menu-ios/scenario-description.ts	Registers scenario metadata for the new SFT.
apps/src/tests/single-feature-tests/stack-v5/test-stack-header-menu-ios/index.tsx	Adds SFT implementation exercising nested menus and dynamic item counts.
apps/src/tests/single-feature-tests/stack-v5/index.ts	Registers the new iOS header-menu SFT in the stack-v5 suite.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.