Document new options and update method in shipping address element

tests/types/src/invalid.ts

@@ -4,13 +4,15 @@ import {
   StripeCardElement,
   StripeIbanElement,
   StripePaymentElement,
+  StripeShippingAddressElement,
 } from '../../../types';
 
 declare const stripe: Stripe;
 declare const elements: StripeElements;
 declare const cardElement: StripeCardElement;
 declare const ibanElement: StripeIbanElement;
 declare const paymentElement: StripePaymentElement;
+declare const shippingAddressElement: StripeShippingAddressElement;
 
 elements.update({
   // @ts-expect-error: `clientSecret` is not updatable
@@ -41,6 +43,13 @@ paymentElement.on('change', (e) => {
   }
 });
 
+shippingAddressElement.update({
+  // @ts-expect-error: Argument of type '{ defaultValues: { allowedCountries: string[]; }; }' is not assignable to parameter of type 'StripeShippingAddressElementUpdateOptions'.
+  defaultValues: {
+    name: 'foo bar',
+  },
+});
+
 stripe
   .confirmPayment({elements, confirmParams: {return_url: ''}})
   .then((res) => {

tests/types/src/valid.ts

@@ -507,6 +507,14 @@ const shippingAddressElement = elements.create('shippingAddress', {
     },
   },
   disableAutocomplete: true,
+  fields: {
+    phone: 'always',
+  },
+  validation: {
+    phone: {
+      required: 'always',
+    },
+  },
 });
 
 shippingAddressElement
@@ -525,6 +533,15 @@ shippingAddressElement
     }) => {}
   );
 
+shippingAddressElement.update({
+  fields: {
+    phone: 'never',
+  },
+  validation: {
+    phone: undefined,
+  },
+});
+
 const retrievedShippingAddressElement: StripeShippingAddressElement | null = elements.getElement(
   'shippingAddress'
 );

types/stripe-js/elements/shipping-address.d.ts

@@ -122,6 +122,32 @@ export type StripeShippingAddressElement = StripeElementBase & {
     eventType: 'loaderstart',
     handler?: (event: {elementType: 'shippingAddress'}) => any
   ): StripeShippingAddressElement;
+
+  /**
+   * Updates the options the `ShippingAddressElement` was initialized with.
+   * Updates are merged into the existing configuration.
+   */
+  update(
+    options: StripeShippingAddressElementUpdateOptions
+  ): StripeShippingAddressElement;
+};
+
+export type StripeShippingAddressElementUpdateOptions = {
+  /**
+   * Control which additional fields to display in the shippingAddress Element.
+   */
+  fields?: {
+    phone?: 'always' | 'never' | 'auto';
+  };
+
+  /**
+   * Specify validation rules for the above additional fields.
+   */
+  validation?: {
+    phone?: {
+      required: 'always' | 'never' | 'auto';
+    };
+  };
 };
 
 export interface StripeShippingAddressElementOptions {
@@ -148,12 +174,29 @@ export interface StripeShippingAddressElementOptions {
       postal_code?: string | null;
       country: string;
     };
+    phone?: string | null;
   };
 
   /**
    * Whether or not ShippingAddressElement provides autocomplete suggestions
    */
   disableAutocomplete?: boolean;
+
+  /**
+   * Control which additional fields to display in the shippingAddress Element.
+   */
+  fields?: {
+    phone?: 'always' | 'never' | 'auto';
+  };
+
+  /**
+   * Specify validation rules for the above additional fields.
+   */
+  validation?: {
+    phone?: {
+      required: 'always' | 'never' | 'auto';
+    };
+  };
 }
 
 export interface StripeShippingAddressElementChangeEvent
@@ -191,5 +234,6 @@ export interface StripeShippingAddressElementChangeEvent
       postal_code: string;
       country: string;
     };
+    phone?: string;
   };
 }