chore: document updated cartDeliveryAddressesUpdate empty array behavior

[fredericoo]

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

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

[fredericoo]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• chore: document updated cartDeliveryAddressesUpdate empty array behavior #3393 👈 (View in Graphite)
• update SFAPI and CAAPI to 2025-10 #3352 : 4 other dependent PRs (#3284 , #3398 , #3400 and 1 other)
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[shopify]

Oxygen deployed a preview of your 01-20-chore_document_updated_cartdeliveryaddressesupdate_empty_array_behavior branch. Details:

Storefront	Status	Preview link	Deployment details	Last update (UTC)
Skeleton (skeleton.hydrogen.shop)	✅ Successful (Logs)	Preview deployment	Inspect deployment	January 22, 2026 5:16 PM

Learn more about Hydrogen's GitHub integration.

[kdaviduik]

i'd be okay with 🔥 nuking this test, but I also won't scream if we leave it in