Unstable Release (checkout) for address-autocomplete.suggest

.changeset/yellow-lions-behave.md

@@ -0,0 +1,7 @@
+---
+'@shopify/ui-extensions': minor
+'@shopify/ui-extensions-react': minor
+---
+
+- Adds `purchase.address-autocomplete.suggest` extension target
+- Adds the `primaryAction` and `secondaryAction` to the `Sheet` component

packages/ui-extensions-react/src/surfaces/checkout/components/Sheet/Sheet.ts

@@ -4,4 +4,6 @@ import type {ReactPropsFromRemoteComponentType} from '@remote-ui/react';
 
 export type SheetProps = ReactPropsFromRemoteComponentType<typeof BaseSheet>;
 
-export const Sheet = createRemoteReactComponent(BaseSheet);
+export const Sheet = createRemoteReactComponent(BaseSheet, {
+  fragmentProps: ['primaryAction', 'secondaryAction'],
+});

packages/ui-extensions/docs/surfaces/checkout/reference/examples/purchase.address-autocomplete.suggest/default.example.ts

@@ -0,0 +1,30 @@
+import {extension} from '@shopify/ui-extensions/checkout';
+
+export default extension(
+  'purchase.address-autocomplete.suggest',
+  async (api) => {
+    const {
+      signal,
+      target: {value, field},
+    } = api;
+
+    const suggestions =
+      await fetchAddressAutocompleteSuggestions(
+        value,
+        signal,
+      );
+
+    async function fetchAddressAutocompleteSuggestions(
+      value,
+      signal,
+    ) {
+      const response = await fetch(
+        `https://myapp.com/api?query=${value}&field=${field}`,
+        {signal},
+      );
+      return response.json();
+    }
+
+    return {suggestions};
+  },
+);

packages/ui-extensions/docs/surfaces/checkout/reference/helper.docs.ts

@@ -98,6 +98,7 @@ export function getExamples(
     ...createExample(
       'customer-account.order-status.customer-information.render-after/default',
     ),
+    ...createExample('purchase.address-autocomplete.suggest/default'),
     ...createExample('purchase.cart-line-item.line-components.render/default'),
     ...createExample('purchase.checkout.actions.render-before/default'),
     ...createExample('purchase.checkout.block.render/default'),
@@ -597,6 +598,27 @@ const CUSTOMER_ACCOUNT_STANDARD_API_DEFINITION = {
   type: 'CustomerAccountStandardApi',
 };
 
+const ADDRESS_AUTOCOMPLETE_STANDARD_API_DEFINITION = {
+  title: 'AddressAutocompleteStandardApi',
+  description:
+    'The base API object provided to this and other `purchase.address-autocomplete` extension targets.',
+  type: 'AddressAutocompleteStandardApi',
+};
+
+const ADDRESS_AUTOCOMPLETE_SUGGEST_API_DEFINITION = {
+  title: 'AddressAutocompleteSuggestApi',
+  description:
+    'The API object provided to the `purchase.address-autocomplete.suggest` extension target.',
+  type: 'AddressAutocompleteSuggestApi',
+};
+
+const ADDRESS_AUTOCOMPLETE_SUGGEST_API_OUTPUT_DEFINITION = {
+  title: 'AddressAutocompleteSuggestApiOutput',
+  description:
+    'The API object returned by the `purchase.address-autocomplete.suggest` extension target.',
+  type: 'AddressAutocompleteSuggestApiOutput',
+};
+
 const CART_LINE_ITEM_API_DEFINITION = {
   title: 'CartLineItemApi',
   description:
@@ -670,6 +692,15 @@ export const CHECKOUT_API = {
   ...COMMON_API,
 };
 
+export const ADDRESS_AUTOCOMPLETE_SUGGEST_API = {
+  definitions: [
+    ADDRESS_AUTOCOMPLETE_SUGGEST_API_DEFINITION,
+    ADDRESS_AUTOCOMPLETE_SUGGEST_API_OUTPUT_DEFINITION,
+    ADDRESS_AUTOCOMPLETE_STANDARD_API_DEFINITION,
+  ],
+  ...COMMON_API,
+};
+
 export const CART_LINE_ITEM_API = {
   subCategory: 'Order Summary',
   definitions: [CART_LINE_ITEM_API_DEFINITION, STANDARD_API_DEFINITION],

packages/ui-extensions/docs/surfaces/checkout/reference/targets/purchase.address-autocomplete.suggest.doc.ts

@@ -0,0 +1,24 @@
+import type {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+import {
+  ADDRESS_AUTOCOMPLETE_SUGGEST_API,
+  getExample,
+  getLinksByTag,
+} from '../helper.docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'purchase.address-autocomplete.suggest',
+  description: `
+  An extension target used to provide address autocomplete suggestions. It accepts input and must return address suggestions.
+
+  > Caution: This target does not support rendering UI components.
+  `,
+  subCategory: 'Utility',
+  defaultExample: getExample('purchase.address-autocomplete.suggest/default', [
+    'js',
+  ]),
+  related: getLinksByTag('targets'),
+  ...ADDRESS_AUTOCOMPLETE_SUGGEST_API,
+};
+
+export default data;

packages/ui-extensions/src/extension.ts

@@ -44,5 +44,5 @@ export interface RenderExtensionWithRemoteRoot<
 }
 
 export interface RunnableExtension<Api, Output> {
-  (api: Api): Output | Promise<Output>;
+  (api: Api): Output;
 }

packages/ui-extensions/src/surfaces/checkout.ts

@@ -140,10 +140,15 @@ export type {PickupLocationItemApi} from './checkout/api/pickup/pickup-location-
 export type {ShippingOptionItemApi} from './checkout/api/shipping/shipping-option-item';
 export type {ShippingOptionListApi} from './checkout/api/shipping/shipping-option-list';
 export type {
-  AddressAutocompleteSuggestion,
   AddressAutocompleteSuggestApi,
+  AddressAutocompleteSuggestApiOutput,
+  AddressAutocompleteFormatSuggestionApi,
+  AddressAutocompleteFormatSuggestionApiOutput,
+  AddressAutocompleteSuggestion,
 } from './checkout/api/address-autocomplete/address-autocomplete';
 
+export type {AddressAutocompleteStandardApi} from './checkout/api/address-autocomplete/standard';
+
 export type {
   PaymentMethodAttributesResult,
   PaymentMethodAttributesResultSuccess,

packages/ui-extensions/src/surfaces/checkout/api/address-autocomplete/address-autocomplete.ts

@@ -1,36 +1,50 @@
 import type {MailingAddress} from '../shared';
 
 export interface AddressAutocompleteSuggestApi {
-  target: {
-    /**
-     * The input that the user has typed so far into the address field.
-     *
-     * @example "123 M"
-     */
-    value: string;
+  /**
+   * The signal that the extension should listen to for cancellation requests.
+   *
+   * If the signal is aborted, the extension should cancel any ongoing requests.
+   * The signal will be aborted either when the buyer navigates away from the
+   * address field or when the debounced query value changes.
+   *
+   * Pass this signal to any asynchronous operations that need to be cancelled,
+   * like `fetch`.
+   */
+  signal: AbortSignal;
+
+  /**
+   * The current state of the address field that the buyer is interacting with.
+   *
+   * {% include /apps/checkout/privacy-icon.md %} Requires access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).
+   */
+  target: Target;
+}
 
-    /**
-     * The address field that the buyer is interacting with.
-     *
-     * @example "address1"
-     */
-    field: AutocompleteAddress;
+interface Target {
+  /**
+   * The current value of the `field` the buyer is interacting with.
+   *
+   * @example "123 M"
+   */
+  value: string;
 
-    /**
-     * An AbortSignal that may be used to cancel in-flight network requests.
-     * This signal is sent when the buyer has stopped interacting with the address field.
-     */
-    signal: AbortSignal;
-  };
+  /**
+   * The `MailingAddress` field that the buyer is interacting with.
+   *
+   * @example "address1"
+   */
+  field: 'address1' | 'zip';
 }
+
 export interface AddressAutocompleteSuggestion {
   /**
    * The human-readable autocomplete suggestion text. This text is
    * shown to the buyer as-is. No attempts will be made to parse it.
    *
    * @example "123 Main St, Toronto, ON, CA"
    */
-  description: string;
+  label: string;
 
   /**
    * Optional.
@@ -66,22 +80,43 @@ export interface AddressAutocompleteSuggestion {
 
 interface MatchedSubstring {
   /**
-   * The start location of the matched substring in the suggestion description text.
+   * The start location of the matched substring in the suggestion label text.
    */
   offset: number;
   /**
-   * The length of the matched substring in the suggestion description text.
+   * The length of the matched substring in the suggestion label text.
    */
   length: number;
 }
 
+export interface AddressAutocompleteSuggestApiOutput {
+  /**
+   * An array of address autocomplete suggestions to show to the buyer.
+   */
+  suggestions: AddressAutocompleteSuggestion[];
+}
+
 /**
  * A partial mailing address with only fields relevant to address autocomplete.
  * All fields are optional
  */
-type AutocompleteAddress = Partial<
-  Pick<
+interface AutocompleteAddress
+  extends Pick<
     MailingAddress,
     'address1' | 'address2' | 'city' | 'provinceCode' | 'zip' | 'countryCode'
-  >
->;
+  > {}
+export interface AddressAutocompleteFormatSuggestionApi {
+  /**
+   * The selected autocomplete suggestion that the buyer selected during checkout.
+   */
+  target: {
+    selectedSuggestion: AddressAutocompleteSuggestion;
+  };
+}
+
+export interface AddressAutocompleteFormatSuggestionApiOutput {
+  /**
+   * The formatted address that will be used to populate the native address fields.
+   */
+  formattedAddress: AutocompleteAddress;
+}