@W-19718906 bug: duplicate bonus products when store pickup for same product

[sf-shikhar-prasoon]

Description

This is to fix a bug where Bonus products showing up twice if the same product is added as store pickup

The bug was discovered by Jainam first (slack thread)

Please refer to the slack thread or work item for a video demo of the bug.

Types of Changes

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Documentation update
• Breaking change (could cause existing functionality to not work as expected)
• Other changes (non-breaking changes that does not fit any of the above)

Breaking changes include:

• Removing a public function or component or prop
• Adding a required argument to a function
• Changing the data type of a function parameter or return value
• Adding a new peer dependency to package.json

Changes

Our Solution: Capacity-Based Sequential Allocation

We implemented a sophisticated distribution system that:

1. Calculates individual item capacity based on promotion rules and item quantities
2. Distributes bonus products proportionally across qualifying cart items
3. Uses first-come-first-served allocation based on cart item position
4. Prevents duplication by tracking which bonus products have been allocated

Key Features Implemented

New Distribution Function: getBonusProductsForSpecificCartItem()

• Handles capacity calculation per cart item
• Allocates bonus products sequentially across qualifying items
• Respects promotion capacity limits

Updated Cart Display: Modified CartProductListWithGroupedBonusProducts

• Uses new distribution function instead of global product lookup
• Maintains existing "Select Bonus Products" button behavior

Comprehensive Testing: Added 6 new test scenarios covering:

• Equal distribution (2 suits, 4 ties → 2+2)
• Unequal distribution (2 suits, 3 ties → 2+1)
• Quantity multipliers (suit qty=2 gets 4 ties capacity)
• Single item edge cases
• Empty cart scenarios

Expected Results

• Cart: 2 suits, 3 ties → Suit A: 2 ties, Suit B: 1 tie + "Select Bonus Products" button
• Cart: 2 suits, 4 ties → Suit A: 2 ties, Suit B: 2 ties (no buttons needed)
• Cart: 4 suits, 4 ties → Suit A (qty=2): 2-3 ties, Suit B (qty=2): 1-2 ties + buttons as needed

The implementation preserves all existing functionality while correctly distributing bonus products across cart items to eliminate the duplication
bug. Global capacity calculations remain accurate for button text display.

How to Test-Drive This PR

• MRT Env: https://cc-sharks-shikhar-test-2.mobify-storefront-staging.com/
• Please refer to the slack thread or work item for a video demo of the bug. (slack thread)

Checklists

General

• Changes are covered by test cases
• CHANGELOG.md updated with a short description of changes (not required for documentation updates)

Accessibility Compliance

You must check off all items in one of the follow two lists:

• There are no changes to UI

or...

• Changes were tested with a Screen Reader (iOS VoiceOver or Android Talkback) and had no issues
• Changes comply with WCAG 2.0 guidelines levels A and AA
• Changes to common UI patterns and interactions comply with WAI-ARIA best practices

Localization

• Changes include a UI text update in the Retail React App (which requires translation)

[cc-prodsec]

🎉 Snyk checks have passed. No issues have been found so far.

✅ security/snyk check is complete. No issues have been found. (View Details)

✅ license/snyk check is complete. No issues have been found. (View Details)

[shethj]

I see another issue with the code.
See https://salesforce-internal.slack.com/archives/C08RM5UV613/p1758667949037929?thread_ts=1758657795.219949&cid=C08RM5UV613

[shethj]

https://salesforce-internal.slack.com/archives/C08RM5UV613/p1758667949037929?thread_ts=1758657795.219949&cid=C08RM5UV613

We have another non-edge case bug.