Expose UIBarButtonItem.axisBehavior on v5 iOS header items

[juliusmarminge]

I propose an optional axisBehavior on v5 Stack.HeaderConfig iOS leading/trailing native and custom items, matching UIBarButtonItem.axisBehavior:

axisBehavior?: 'automatic' | 'horizontalOnly' | 'verticalPreferred';

automatic leaves UIKit to infer supported axes from the item contents. horizontalOnly permits only horizontal bars, so UIKit may hide the item when no horizontal bar is present. verticalPreferred supports both axes and prefers vertical placement when both are available. Removing the option, including after an explicit value, restores automatic.

The exact availability evidence is the installed Xcode 27.1 UIKit header, build 27A9269. It declares the property and enum in iOS 27.1, and marks both explicit cases unavailable on tvOS and visionOS. Apple’s primary presentation demonstrates the two preferences. The axisBehavior API page currently returns an error, so this proposal makes no broader SDK stability claim. Builds with older SDKs and runtimes below iOS 27.1 would ignore this option, as would other platforms.

This is an item preference, independent of device detection, bar visibility, pinned groups, or search placement. The implementation would use existing item invalidation and factory construction, preserving identifiers and menu state. Main currently creates left/right bar-button arrays and has no v5 pinned/group API; this proposal does not change that model.

I plan a focused draft with a complete FabricExample scenario for native symbols and custom views, updates/removal/reset, separators, and identifier-matched push/pop, plus real base/head captures on a dedicated simulator. React Navigation main has no v5 adapter. A companion patch against its v5 adoption draft would forward the same option; that downstream adoption remains an integration gate.

Would this UIKit-matching item preference fit the v5 header API direction?