chore: document updated cartDeliveryAddressesUpdate empty array behavior

Author: fredericoo

.changeset/delivery-address-empty-array-docs.md

@@ -0,0 +1,29 @@
+---
+'@shopify/hydrogen': patch
+---
+
+`cart.updateDeliveryAddresses` mutation now clears all delivery addresses when passed an empty array
+
+## Breaking Behavior Change in Storefront API 2025-10
+
+The `cartDeliveryAddressesUpdate` mutation now clears all delivery addresses when passed an empty array. This behavior was undefined in previous API versions.
+
+## What Changed
+
+**Before (API ≤ 2025-07):**
+Passing an empty array did not update any addresses, essentially a no-op.
+
+**After (API ≥ 2025-10):**
+Passing an empty array explicitly clears all delivery addresses from the cart.
+
+## Usage
+
+```typescript
+context.cart.updateDeliveryAddresses([])
+```
+
+## Migration
+
+If you are relying on `cart.updateDeliveryAddresses([])` in your codebase, verify if the new behavior is compatible with your expectations.
+
+Otherwise, no migration is required.

packages/hydrogen/src/cart/queries/cartDeliveryAddressesUpdateDefault.test.ts

@@ -27,4 +27,15 @@ describe('cartDeliveryAddressesUpdateDefault', () => {
     expect(result.cart).toHaveProperty('id', CART_ID);
     expect(result.userErrors?.[0]).toContain(cartFragment);
   });
+
+  it('should erase all addresses when passing an empty array', async () => {
+    const updateDeliveryAddresses = cartDeliveryAddressesUpdateDefault({
+      storefront: mockCreateStorefrontClient(),
+      getCartId: () => CART_ID,
+    });
+
+    const result = await updateDeliveryAddresses([]);
+
+    expect(result.cart).toHaveProperty('id', CART_ID);
+  });
 });

packages/hydrogen/src/cart/queries/cartDeliveryAddressesUpdateDefault.tsx

@@ -20,15 +20,18 @@ export type CartDeliveryAddressesUpdateFunction = (
 /**
  * Updates delivery addresses in the cart.
  *
- * This function sends a mutation to the storefront API to update one or more delivery addresses in the cart.
- * It returns the result of the mutation, including any errors that occurred.
+ * Pass an empty array to clear all delivery addresses from the cart.
  *
  * @param {CartQueryOptions} options - The options for the cart query, including the storefront API client and cart fragment.
  * @returns {CartDeliveryAddressUpdateFunction} - A function that takes an array of addresses and optional parameters, and returns the result of the API call.
  *
- * @example
+ * @example Clear all delivery addresses
  * const updateAddresses = cartDeliveryAddressesUpdateDefault(cartQueryOptions);
- * const result = await updateAddresses([
+ * await updateAddresses([]);
+ *
+ * @example Update specific delivery addresses
+ * const updateAddresses = cartDeliveryAddressesUpdateDefault(cartQueryOptions);
+ * await updateAddresses([
     {
       "address": {
         "copyFromCustomerAddressId": "gid://shopify/<objectName>/10079785100",