feat(Android, Stack v5): support sending multiple updates via view command

[kligarski]

Description

Adds support for batching updates in one view command.

Note

Currently, I decided to leave an onSelectionChange event per view command. If you check multiple items in one command, you will receive multiple events. We can consider keeping only the last event but this might be problematic with async image loading. We can also consider moving setting checked state to separate view command. Let me know what you think.

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

Changes

• change setToolbarMenuElementOptions to updateToolbarMenuElements that accepts single update object or an array of updates
• handle new format on JS and native side
• add SFT

Visual documentation

view_command_batching.mp4

Test plan

Run test-stack-toolbar-menu-batch-commands-android SFT.

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

Adds Android (Stack v5 / gamma) support for batching multiple toolbar menu element updates into a single Fabric view command, updating the public JS types/imperative ref API and adding a new Single Feature Test scenario to exercise the batching behavior.

Changes:

• Renames the Android header config view command to updateToolbarMenuElements and changes the native command payload to accept an array of { id, ...options } updates.
• Updates the JS imperative ref API/types to accept either a single { id, options } update or an array, normalizing to the native payload shape.
• Updates existing SFTs to the new API and adds a new SFT scenario for batched commands.

Reviewed changes

Copilot reviewed 23 out of 23 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/fabric/gamma/stack/StackHeaderConfigAndroidNativeComponent.ts	Renames the Fabric command and updates the native command parameter type to an array of update objects.
src/components/gamma/stack/index.ts	Re-exports the new StackHeaderToolbarMenuElementUpdateAndroid type.
src/components/gamma/stack/header/StackHeaderConfig.android.types.ts	Introduces the update object type and documents the new batched command API/semantics.
src/components/gamma/stack/header/StackHeaderConfig.android.tsx	Implements the new imperative method, normalizes single vs array updates, and maps to native payload.
apps/src/tests/single-feature-tests/stack-v5/test-stack-toolbar-nested-menu-android/scenario.md	Updates scenario docs to the renamed command.
apps/src/tests/single-feature-tests/stack-v5/test-stack-toolbar-nested-menu-android/index.tsx	Migrates test usage to updateToolbarMenuElements({ id, options }).
apps/src/tests/single-feature-tests/stack-v5/test-stack-toolbar-menu-title-android/scenario.md	Updates scenario docs to the renamed command.
apps/src/tests/single-feature-tests/stack-v5/test-stack-toolbar-menu-title-android/index.tsx	Migrates test usage to the new update object shape.
apps/src/tests/single-feature-tests/stack-v5/test-stack-toolbar-menu-show-as-action-android/scenario.md	Updates scenario docs to the renamed command.
apps/src/tests/single-feature-tests/stack-v5/test-stack-toolbar-menu-show-as-action-android/index.tsx	Migrates test usage to the new update object shape.
apps/src/tests/single-feature-tests/stack-v5/test-stack-toolbar-menu-icon-android/scenario.md	Updates scenario docs to the renamed command.
apps/src/tests/single-feature-tests/stack-v5/test-stack-toolbar-menu-icon-android/scenario-descriptions.ts	Updates scenario description string to the renamed command.
apps/src/tests/single-feature-tests/stack-v5/test-stack-toolbar-menu-icon-android/index.tsx	Migrates test usage to the new update object shape.
apps/src/tests/single-feature-tests/stack-v5/test-stack-toolbar-menu-groups-android/scenario.md	Updates scenario docs to the renamed command.
apps/src/tests/single-feature-tests/stack-v5/test-stack-toolbar-menu-groups-android/index.tsx	Migrates test usage to the new update object shape.
apps/src/tests/single-feature-tests/stack-v5/test-stack-toolbar-menu-commands-android/scenario.md	Updates scenario docs; still needs signature wording adjustment per review comment.
apps/src/tests/single-feature-tests/stack-v5/test-stack-toolbar-menu-commands-android/index.tsx	Migrates test usage to the new update object shape.
apps/src/tests/single-feature-tests/stack-v5/test-stack-toolbar-menu-batch-commands-android/scenario.md	Adds a new SFT scenario documenting expected batched-selection behavior.
apps/src/tests/single-feature-tests/stack-v5/test-stack-toolbar-menu-batch-commands-android/scenario-description.ts	Adds scenario metadata (name/key/details) for the new batched command SFT.
apps/src/tests/single-feature-tests/stack-v5/test-stack-toolbar-menu-batch-commands-android/index.tsx	Implements the new batch-command SFT UI and calls updateToolbarMenuElements with arrays and a single object.
apps/src/tests/single-feature-tests/stack-v5/index.ts	Registers the new batch-commands scenario in the Stack v5 SFT index.
android/src/main/java/com/swmansion/rnscreens/gamma/stack/header/config/StackHeaderConfigViewManager.kt	Implements the new Fabric command handler that parses an array of update maps.
android/src/main/java/com/swmansion/rnscreens/gamma/stack/header/config/StackHeaderConfig.kt	Adds a batch dispatch helper and routes each update through the existing per-item semantics.

---

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

[kmichalikk]

Code & the test looks good and matches the description but I'm not sure about the working of async loads.

I would really like to have some test for this, at least a copy-pasteable code that shows async load (maybe a really high-res icon url) with element before and after icon change all in one batch.

[kligarski]

Moving to draft -> we want to limit the number of onSelectionChange callbacks -> this requires some additional code to handle async image loading as well.