Document new options and update method in shipping address element (#339

)

* Document new shipping address element options
* Add shipping address update method
* Add type testing

tests/types/src/valid.ts

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

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

@@ -122,6 +122,14 @@ 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: Partial<StripeShippingAddressElementOptions>
+  ): StripeShippingAddressElement;
 };
 
 export interface StripeShippingAddressElementOptions {
@@ -148,12 +156,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 +216,6 @@ export interface StripeShippingAddressElementChangeEvent
       postal_code: string;
       country: string;
     };
+    phone?: string;
   };
 }