[2025-10] Document updated `cartDeliveryAddressesUpdate` empty array behavior

[juanpprieto]

WHY are these changes introduced?

Fixes #3273

Shopify Storefront API 2025-10 changed cartDeliveryAddressesUpdate mutation to explicitly clear all delivery addresses when passed an empty array. This behavior was undefined in previous API versions.

Investigation Summary

Root Cause: API contract evolution + documentation gap (not a code defect)

Key Findings:

• Hydrogen implementation is correct - thin wrapper properly delegates to API
• Zero current impact - skeleton/cookbook don't use this feature
• Tests were using empty arrays but not validating address state
• Empty array clearing is consistent with mutation family semantics

Conclusion: Documentation and test updates only. No code changes required.

WHAT is this pull request doing?

Changes Made (TDD Approach)

1. Added Failing Tests (Commit 40b8ff688)

• Tests requiring documentation of empty array behavior
• Result: 2 failed, 7 passed ❌

2. Updated Documentation (Commit 71b887210)

• JSDoc explains empty array clears addresses (API 2025-10+)
• Added two @example blocks: clear vs update
• Result: All 9 tests passing ✅

3. Added Edge Case Tests (Commit 804c6fa6e)

• 5 comprehensive edge cases
• Result: All 14 tests passing ✅

4. Created Changeset (Commit 2864a669d)

• Comprehensive migration guide
• Before/After code examples
• User-facing documentation

Test Coverage Added

14 tests total (from 2 tests):

• Empty array behavior (2 tests)
• With delivery addresses (2 tests)
• CartFragment override (1 test)
• Mutation structure (2 tests)
• Documentation completeness (2 tests)
• Edge cases (5 tests):
  • Minimal required fields
  • Customer address reference
  • i18n parameters
  • Single vs multiple addresses
  • Full address fields

Documentation Updates

JSDoc Changes:

// BEFORE
/**
 * Updates delivery addresses in the cart.
 */

// AFTER
/**
 * Updates delivery addresses in the cart.
 *
 * Pass an empty array to clear all delivery addresses (API 2025-10+).
 *
 * @example Clear all delivery addresses
 * await updateAddresses([]);
 *
 * @example Update specific addresses
 * await updateAddresses([{...}]);
 */

HOW to test your changes?

Run Tests

cd packages/hydrogen
npm test -- src/cart/queries/cartDeliveryAddressesUpdateDefault.test.ts

Expected: All 14 tests pass

Verify Documentation

# Check JSDoc includes empty array behavior
grep -A 10 "Pass an empty array" packages/hydrogen/src/cart/queries/cartDeliveryAddressesUpdateDefault.tsx

Checklist

• [x] I've read the Contributing Guidelines
• [x] I've considered possible cross-platform impacts (Mac, Linux, Windows)
• [x] I've added a changeset if this PR contains user-facing or noteworthy changes
• [x] I've added tests to cover my changes
• [x] I've added or updated the documentation