add autocomplete changes and other doc changes

.changeset/hungry-beans-complain.md

@@ -0,0 +1,5 @@
+---
+'@shopify/ui-extensions': minor
+---
+
+Adds `selectedCountryCode` to `AddressAutocompleteSuggestionApi`.

packages/ui-extensions-react/src/surfaces/checkout/components/ConsentCheckbox/examples/basic-consent-checkbox.example.tsx

@@ -1,4 +1,5 @@
 import React from 'react';
+
 import {
   reactExtension,
   ConsentCheckbox,

packages/ui-extensions-react/src/surfaces/checkout/components/ConsentCheckbox/examples/with-consent-phone-field-consent-checkbox.example.tsx

@@ -1,4 +1,5 @@
 import React from 'react';
+
 import {
   reactExtension,
   BlockStack,

packages/ui-extensions-react/src/surfaces/checkout/components/ConsentPhoneField/examples/basic-consent-phone-field.example.tsx

@@ -1,4 +1,5 @@
 import React from 'react';
+
 import {
   reactExtension,
   ConsentPhoneField,

packages/ui-extensions-react/src/surfaces/checkout/components/ConsentPhoneField/examples/with-consent-checkbox-consent-phone-field.example.tsx

@@ -1,4 +1,5 @@
 import React from 'react';
+
 import {
   reactExtension,
   BlockStack,

packages/ui-extensions-react/src/surfaces/checkout/components/Select/examples/time-picking-select.example.tsx

@@ -1,4 +1,5 @@
 import React from 'react';
+
 import {
   reactExtension,
   Select,

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

@@ -9,23 +9,26 @@ import {
 const data: ReferenceEntityTemplateSchema = {
   name: 'purchase.address-autocomplete.format-suggestion',
   description: `
-  An extension target that formats the selected address suggestion provided by a [\`purchase.address-autocomplete.suggest\`](/docs/api/checkout-ui-extensions/unstable/targets/utility/purchase-address-autocomplete-suggest) target. This formatted address is used to auto-populate the fields of the address form.
+  An extension target that formats the selected address suggestion provided by a [\`purchase.address-autocomplete.suggest\`](/docs/api/checkout-ui-extensions/unstable/targets/address/purchase-address-autocomplete-suggest) target. This formatted address is used to auto-populate the fields of the address form.
 
-  It must return a [\`formattedAddress\`](/docs/api/checkout-ui-extensions/unstable/targets/utility/purchase-address-autocomplete-format-suggestion#addressautocompleteformatsuggestionoutput-propertydetail-formattedaddress).
+  It must return a [\`formattedAddress\`](/docs/api/checkout-ui-extensions/unstable/targets/address/purchase-address-autocomplete-format-suggestion#addressautocompleteformatsuggestionoutput-propertydetail-formattedaddress).
 
   > Caution:
+  > This extension target is only necessary if the corresponding [\`purchase.address-autocomplete.suggest\`](/docs/api/checkout-ui-extensions/unstable/targets/address/purchase-address-autocomplete-suggest) target does not provide a \`formattedAddress\` for the suggestions. If a formatted address is provided with each suggestion, then this target will not be called.
+  >
+  > If the [\`purchase.address-autocomplete.suggest\`](/docs/api/checkout-ui-extensions/unstable/targets/address/purchase-address-autocomplete-suggest) target is not implemented, then this target will not work.
+
+  > Note:
   > - This target does not support rendering UI components.
   > - This extension can only be developed as a JavaScript extension using the \`ui-extensions\` library.
-  > - This extension target is only necessary if the corresponding [\`purchase.address-autocomplete.suggest\`](/docs/api/checkout-ui-extensions/unstable/targets/utility/purchase-address-autocomplete-suggest) target does not provide a \`formattedAddress\` for the suggestions.
-  > - If the [\`purchase.address-autocomplete.suggest\`](/docs/api/checkout-ui-extensions/unstable/targets/utility/purchase-address-autocomplete-suggest) target provides a \`formattedAddress\` for its suggestions, this target will not be called.
-  > - If the [\`purchase.address-autocomplete.suggest\`](/docs/api/checkout-ui-extensions/unstable/targets/utility/purchase-address-autocomplete-suggest) target is not implemented, this target will not work.
+  > - The [app extension configuration](/docs/apps/app-extensions/configuration) \`shopify.extension.toml\` file is shared between this extension target and [\`purchase.address-autocomplete.suggest\`](/docs/api/checkout-ui-extensions/unstable/targets/address/purchase-address-autocomplete-suggest). This includes extension settings specified in the configuration file.
   `,
-  subCategory: 'Utility',
+  subCategory: 'Address',
   defaultExample: getExample(
     'purchase.address-autocomplete.format-suggestion/default',
     ['js'],
   ),
-  related: getLinksByTag('targets'),
+  related: getLinksByTag('targets', 'Tutorials'),
   ...ADDRESS_AUTOCOMPLETE_FORMAT_SUGGESTION_API,
 };
 

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

@@ -9,23 +9,24 @@ import {
 const data: ReferenceEntityTemplateSchema = {
   name: 'purchase.address-autocomplete.suggest',
   description: `
-  An extension target that provides address autocomplete suggestions for address forms within checkout. These suggestions are shown to buyers as they interact with autocomplete fields of the delivery address, billing address, and pickup point address forms.
+  An extension target that provides address autocomplete suggestions for address forms at checkout. Suggestions are presented to customers for delivery, billing, and pickup point addresses.
 
-  It must return a list of address [\`suggestions\`](/docs/api/checkout-ui-extensions/unstable/targets/utility/purchase-address-autocomplete-suggest#addressautocompletesuggestoutput-propertydetail-suggestions).
+  The extension target must return a list of address [\`suggestions\`](/docs/api/checkout-ui-extensions/unstable/targets/address/purchase-address-autocomplete-suggest#addressautocompletesuggestoutput-propertydetail-suggestions).
 
-  > Tip:
-  > - If a formatted address is provided with each suggestion, it will be used to auto-populate the fields in the address form when the buyer selects a suggested address.
-  > - Optionally, you can implement the [\`purchase.address-autocomplete.format-suggest\`](/docs/api/checkout-ui-extensions/unstable/targets/utility/purchase-address-autocomplete-format-suggestion) extension target to format an address based on the address suggestion selected by the buyer.
+  If a formatted address is provided with each suggestion, then it will be used to auto-populate the fields in the address form when the customer selects a suggested address.
 
-  > Caution:
+  Optionally, you can implement the [\`purchase.address-autocomplete.format-suggestion\`](/docs/api/checkout-ui-extensions/unstable/targets/address/purchase-address-autocomplete-format-suggestion) extension target to format an address based on the address suggestion selected by the customer.
+
+  > Note:
   > - This target does not support rendering UI components.
   > - This extension can only be developed as a JavaScript extension using the \`ui-extensions\` library.
+  > - The [app extension configuration](/docs/apps/app-extensions/configuration) \`shopify.extension.toml\` file is shared between this extension target and [\`purchase.address-autocomplete.format-suggestion\`](/docs/api/checkout-ui-extensions/unstable/targets/address/purchase-address-autocomplete-format-suggestion). This includes extension settings specified in the configuration file.
   `,
-  subCategory: 'Utility',
+  subCategory: 'Address',
   defaultExample: getExample('purchase.address-autocomplete.suggest/default', [
     'js',
   ]),
-  related: getLinksByTag('targets'),
+  related: getLinksByTag('targets', 'Tutorials'),
   ...ADDRESS_AUTOCOMPLETE_SUGGEST_API,
 };
 

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

@@ -29,19 +29,20 @@ export interface AddressAutocompleteSuggestion {
   id?: string;
 
   /**
-   * If provided, this will be used to highlight the substrings
+   * A list of substrings that matched the original search query.
+   *
+   * If `matchedSubstrings` are provided, then they will be used to highlight the substrings
    * of the suggestions that matched the original search query.
    *
    * @example [{offset: 0, length: 4}]
    */
   matchedSubstrings?: MatchedSubstring[];
 
   /**
-   * If provided, the autocomplete field will use the formatted address to
-   * auto-fill the remaining address fields.
+   * The formatted address that will auto-fill the remaining address fields.
    *
-   * If this value is returned for every suggestion, there is no need to implement
-   * the `purchase.address-autocomplete.format-suggestion` extension target.
+   * If this value is returned for every suggestion, then the
+   * `purchase.address-autocomplete.format-suggestion` extension target is not needed.
    */
   formattedAddress?: AutocompleteAddress;
 }

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

@@ -43,48 +43,48 @@ export interface AddressAutocompleteStandardApi<
   appMetafields: AppMetafieldEntry[];
 
   /**
-   * Methods for interacting with [Web Pixels](https://shopify.dev/docs/apps/marketing), such as emitting an event.
+   * The methods for interacting with [Web Pixels](https://shopify.dev/docs/apps/marketing), such as emitting an event.
    */
   analytics: Analytics;
 
   /**
-   * Custom attributes left by the customer to the merchant, either in their cart or during checkout.
+   * The custom attributes left by the customer to the merchant, either in their cart or during checkout.
    */
   attributes: Attribute[] | undefined;
 
   /**
-   * The proposed buyer billing address. The address updates when the field is
+   * The proposed customer billing address. The address updates when the field is
    * committed (on change) rather than every keystroke.
    *
    * {% include /apps/checkout/privacy-icon.md %} Requires access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).
    */
   billingAddress?: MailingAddress | undefined;
 
   /**
-   * A stable id that represents the current checkout.
+   * A stable ID that represents the current checkout.
    *
    * Matches the `token` field in the [WebPixel checkout payload](https://shopify.dev/docs/api/pixels/customer-events#checkout)
-   * and the `checkout_token` field in the [Admin REST API Order resource](https://shopify.dev/docs/api/admin-rest/unstable/resources/order#resource-object).
+   * and the `checkout_token` field in the [REST Admin API `Order` resource](https://shopify.dev/docs/api/admin-rest/unstable/resources/order#resource-object).
    */
   checkoutToken: CheckoutToken | undefined;
 
   /**
-   * Meta information about the extension.
+   * The meta information about the extension.
    */
   extension: Extension<Target>;
 
   /**
    * Utilities for translating content and formatting values according to the current
    * [`localization`](https://shopify.dev/docs/api/checkout-ui-extensions/apis/localization)
-   * of the checkout.
+   * Type 'RunnableExtensionInstance<keyof RunnableExtensionTargets>' is not assignable to type 'ExtensionInstance<Target>'.
    *
-   * See [localization examples](https://shopify.dev/docs/api/checkout-ui-extensions/apis/localization#examples)
+   * Refer to [`localization` examples](https://shopify.dev/docs/api/checkout-ui-extensions/apis/localization#examples)
    * for more information.
    */
   i18n: I18n;
 
   /**
-   * Details about the location, language, and currency of the buyer. For utilities to easily
+   * The details about the location, language, and currency of the customer. For utilities to easily
    * format and translate content based on these details, you can use the
    * [`i18n`](https://shopify.dev/docs/api/checkout-ui-extensions/apis/localization#standardapi-propertydetail-i18n)
    * object instead.
@@ -95,8 +95,7 @@ export interface AddressAutocompleteStandardApi<
    * The metafields that apply to the current checkout.
    *
    * Metafields are stored locally on the client and are applied to the order object after the checkout completes.
-   *
-   * These metafields are shared by all extensions running on checkout, and
+   * They are shared by all extensions running on checkout, and
    * persist for as long as the customer is working on this checkout.
    *
    * Once the order is created, you can query these metafields using the
@@ -105,50 +104,58 @@ export interface AddressAutocompleteStandardApi<
   metafields: Metafield[];
 
   /**
-   * Used to query the Storefront GraphQL API with a prefetched token.
+   * The method used to query the Storefront GraphQL API with a prefetched token.
    *
-   * See [storefront api access examples](https://shopify.dev/docs/api/checkout-ui-extensions/apis/storefront-api) for more information.
+   * Refer to [Storefront API access examples](https://shopify.dev/docs/api/checkout-ui-extensions/apis/storefront-api) for more information.
    */
   query: <Data = unknown, Variables = Record<string, unknown>>(
     query: string,
     options?: {variables?: Variables; version?: StorefrontApiVersion},
   ) => Promise<{data?: Data; errors?: GraphQLError[]}>;
 
   /**
-   * Provides access to session tokens, which can be used to verify token claims on your app's server.
+   * The session token providing a set of claims as a signed JSON Web Token (JWT).
+   *
+   * The token has a TTL of 5 minutes.
    *
-   * See [session token examples](https://shopify.dev/docs/api/checkout-ui-extensions/apis/session-token) for more information.
+   * If the previous token expires, this value will reflect a new session token with a new signature and expiry.
+   *
+   * Refer to [session token examples](https://shopify.dev/docs/api/checkout-ui-extensions/apis/session-token) for more information.
    */
   sessionToken: SessionToken;
 
   /**
    * The settings matching the settings definition written in the
    * [`shopify.extension.toml`](https://shopify.dev/docs/api/checkout-ui-extensions/configuration) file.
    *
-   *  See [settings examples](https://shopify.dev/docs/api/checkout-ui-extensions/apis/settings) for more information.
+   *  Refer to [settings examples](https://shopify.dev/docs/api/checkout-ui-extensions/apis/settings#examples) for more information.
    *
-   * > Note: When an extension is being installed in the editor, the settings will be empty
+   * > Note: The settings are empty when an extension is being installed in the [checkout editor](https://help.shopify.com/en/manual/checkout-settings/checkout-extensibility/checkout-editor).
+
    */
   settings: ExtensionSettings;
 
   /**
-   * The proposed buyer shipping address. During the information step,
+   * The proposed customer shipping address. During the information step,
    * the address updates when the field is committed (on change) rather than every keystroke.
-   * An address value is only present if delivery is required. Otherwise, the subscribable value is undefined.
+   *
+   * > Note: An address value is only present if delivery is required. Otherwise, the subscribable value is undefined.
    *
    * {% include /apps/checkout/privacy-icon.md %} Requires access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).
    */
   shippingAddress?: MailingAddress | undefined;
 
-  /** Shop where the checkout is taking place. */
+  /** The shop where the checkout is taking place. */
   shop: Shop;
 
   /**
-   * Key-value storage for the extension.
-   * Uses `localStorage` and should persist across the buyer's current checkout session.
-   * However, data persistence isn't guaranteed and storage is reset when the buyer starts a new checkout.
+   * The key-value storage for the extension.
+   *
+   * It uses `localStorage` and should persist across the customer's current checkout session.
+   *
+   * > Caution: Data persistence isn't guaranteed and storage is reset when the customer starts a new checkout.
    *
-   * Data is shared across all activated extension targets of this extension. In versions `<=2023-07`,
+   * Data is shared across all activated extension targets of this extension. In versions 2023-07 and earlier,
    * each activated extension target had its own storage.
    */
   storage: Storage;
@@ -181,33 +188,33 @@ interface Extension<
    *
    * * [`network_access`](https://shopify.dev/docs/api/checkout-ui-extensions/configuration#network-access): the extension can make external network calls.
    *
-   * * [`block_progress`](https://shopify.dev/docs/api/checkout-ui-extensions/configuration#block-progress): the extension can block a buyer's progress and the merchant has allowed this blocking behavior.
+   * * [`block_progress`](https://shopify.dev/docs/api/checkout-ui-extensions/configuration#block-progress): the extension can block a customer's progress and the merchant has allowed this blocking behavior.
    *
-   * * [`collect_buyer_consent.sms_marketing`](https://shopify.dev/docs/api/checkout-ui-extensions/configuration#collect-buyer-consent): the extension can collect buyer consent for SMS marketing.
+   * * [`collect_buyer_consent.sms_marketing`](https://shopify.dev/docs/api/checkout-ui-extensions/configuration#collect-buyer-consent): the extension can collect customer consent for SMS marketing.
    *
-   * * [`collect_buyer_consent.customer_privacy`](https://shopify.dev/docs/api/checkout-ui-extensions/configuration#collect-buyer-consent): the extension can register buyer consent decisions that will be honored on Shopify-managed services.
+   * * [`collect_buyer_consent.customer_privacy`](https://shopify.dev/docs/api/checkout-ui-extensions/configuration#collect-buyer-consent): the extension can register customer consent decisions that will be honored on Shopify-managed services.
    */
   capabilities: Capability[];
 
   /**
-   * Information about the editor where the extension is being rendered.
+   * The information about the editor where the extension is being rendered.
    *
-   * The value is undefined if the extension is not running in an editor.
+   * If the value is undefined, then the extension is not running in an editor.
    */
   editor?: Editor;
 
   /**
-   * Whether your extension is currently rendered to the screen.
+   * A Boolean to show whether your extension is currently rendered to the screen.
    *
    * Shopify might render your extension before it's visible in the UI,
    * typically to pre-render extensions that will appear on a later step of the
    * checkout.
    *
-   * Your extension might also continue to run after the buyer has navigated away
+   * Your extension might also continue to run after the customer has navigated away
    * from where it was rendered. The extension continues running so that
-   * your extension is immediately available to render if the buyer navigates back.
+   * your extension is immediately available to render if the customer navigates back.
    *
-   * If the extension is not capable of rendering UI components, this value will always be false.
+   * If the extension is not capable of rendering UI components, then the value will always be false.
    */
   rendered: boolean;
 
@@ -238,7 +245,7 @@ interface Extension<
 
 interface Localization {
   /**
-   * The currency that the buyer sees for money amounts in the checkout.
+   * The currency that the customer sees for money amounts in the checkout.
    */
   currency: Currency;
 
@@ -248,35 +255,35 @@ interface Localization {
   timezone: Timezone;
 
   /**
-   * The language the buyer sees in the checkout.
+   * The language the customer sees in the checkout.
    */
   language: Language;
 
   /**
-   * This is the buyer's language, as supported by the extension.
-   * If the buyer's actual language is not supported by the extension,
-   * this is the fallback locale used for translations.
+   * This is the customer's language, as supported by the extension.
+   * If the customer's actual language is not supported by the extension,
+   * then this is the language that is used for translations.
    *
-   * For example, if the buyer's language is 'fr-CA' but your extension
+   * For example, if the customer's language is 'fr-CA' but your extension
    * only supports translations for 'fr', then the `isoCode` for this
    * language is 'fr'. If your extension does not provide french
-   * translations at all, this value is the default locale for your
+   * translations at all, then this value is the default locale for your
    * extension (that is, the one matching your .default.json file).
    */
   extensionLanguage: Language;
 
   /**
    * The country context of the checkout. This value carries over from the
    * context of the cart, where it was used to contextualize the storefront
-   * experience. The value is undefined if unknown.
+   * experience. If the country is unknown, then the value is undefined.
    */
   country: Country | undefined;
 
   /**
    * The [market](https://shopify.dev/docs/apps/markets) context of the
    * checkout. This value carries over from the context of the cart, where it
-   * was used to contextualize the storefront experience. The value is undefined
-   * if unknown.
+   * was used to contextualize the storefront experience. If the market is unknown,
+   * then the value is undefined.
    */
   market: Market | undefined;
 }