Unstable Release from checkout-web (#2717)

lrsterrett · web-flow · commit 316b82e53b75 · 2025-04-02T09:50:35.000-04:00
* all unstable release changes

* remove remote-dom related api changes mean for next rc release

* reintroduce payment method export until next rc release

* still using yarn

* remove extra line for cleaner diff

* remove everything within components meant for next rc release

* remove shared code changes within components

* conform to public package's linting rules

* add line back for cleaner diff

* remove reference for orderStatusApiEmpty that moved to customer accounts

* add new code changes and doc examples from newer monorepo changes

* add changesets to PR
diff --git a/.changeset/chilled-planes-itch.md b/.changeset/chilled-planes-itch.md
@@ -0,0 +1,6 @@
+---
+'@shopify/ui-extensions-react': minor
+'@shopify/ui-extensions': minor
+---
+
+addition of removeAttribute type to applyAttributeChange api in checkout surface
diff --git a/.changeset/dry-needles-knock.md b/.changeset/dry-needles-knock.md
@@ -0,0 +1,6 @@
+---
+'@shopify/ui-extensions-react': patch
+'@shopify/ui-extensions': patch
+---
+
+addition of isFirstOrder to the orderConfirmation api and ordersCount to the standard api in checkout surface
diff --git a/packages/ui-extensions-react/src/surfaces/checkout/hooks/buyer-journey.ts b/packages/ui-extensions-react/src/surfaces/checkout/hooks/buyer-journey.ts
@@ -42,6 +42,9 @@ export function useBuyerJourneyCompleted<
  *
  * If you do, then you're expected to inform the buyer why navigation was blocked,
  * either by passing validation errors to the checkout UI or rendering the errors in your extension.
+ *
+ * `useBuyerJourneyIntercept()` should be called at the top level of the extension,
+ * not within an embedded or child component, to avoid errors should the child component get destroyed.
  */
 export function useBuyerJourneyIntercept<
   Target extends RenderExtensionTarget = RenderExtensionTarget,
diff --git a/packages/ui-extensions/docs/surfaces/checkout/reference/apis/attributes.doc.ts b/packages/ui-extensions/docs/surfaces/checkout/reference/apis/attributes.doc.ts
@@ -5,6 +5,7 @@ import {
   CHECKOUT_API_PROPERTIES_DESCRIPTION,
   getLinksByTag,
   getHookExample,
+  getExample,
 } from '../helper.docs';
 
 const data: ReferenceEntityTemplateSchema = {
@@ -42,7 +43,11 @@ const data: ReferenceEntityTemplateSchema = {
       type: 'UseAttributeValuesGeneratedType',
     },
   ],
-  defaultExample: getHookExample('attribute-values'),
+  defaultExample: getExample('attribute-values', ['jsx', 'js']),
+  examples: {
+    description: '',
+    examples: [getExample('attributes/attribute-change', ['jsx', 'js'])],
+  },
   related: getLinksByTag('apis'),
 };
 
diff --git a/packages/ui-extensions/docs/surfaces/checkout/reference/apis/buyer-journey.doc.ts b/packages/ui-extensions/docs/surfaces/checkout/reference/apis/buyer-journey.doc.ts
@@ -38,6 +38,7 @@ const data: ReferenceEntityTemplateSchema = {
         Installs a function for intercepting and preventing progress on checkout.
         To block checkout progress, you must set the [block_progress](/docs/api/checkout-ui-extensions/configuration#block-progress) capability in your extension's configuration.
         If you do, then you're expected to inform the buyer why navigation was blocked, either by passing validation errors to the checkout UI or rendering the errors in your extension.
+        \`useBuyerJourneyIntercept()\` should be called at the top level of the extension, not within an embedded or child component, to avoid errors should the child component get destroyed.
       `,
       type: 'UseBuyerJourneyInterceptGeneratedType',
     },
diff --git a/packages/ui-extensions/docs/surfaces/checkout/reference/apis/localized-fields.doc.ts b/packages/ui-extensions/docs/surfaces/checkout/reference/apis/localized-fields.doc.ts
@@ -29,7 +29,7 @@ const data: ReferenceEntityTemplateSchema = {
     {
       title: 'useLocalizedField',
       description:
-        'Returns the requested localized field and re-renders your component if the value changes.',
+        'Returns the current localized fields and re-renders your component if the values change.',
       type: 'UseLocalizedFieldGeneratedType',
     },
   ],
diff --git a/packages/ui-extensions/docs/surfaces/checkout/reference/apis/order.doc.ts b/packages/ui-extensions/docs/surfaces/checkout/reference/apis/order.doc.ts
@@ -4,13 +4,8 @@ import {
   getLinksByTag,
   ORDER_CONFIRMATION_API_PROPERTIES_DESCRIPTION,
   getExample,
-  ORDER_STATUS_API_PROPERTIES_DESCRIPTION,
 } from '../helper.docs';
 
-// added temporarily to keep a note that the order status api docs have been moved to customer accounts
-// can be removed from 2025-01 on
-interface OrderStatusApiEmpty {}
-
 const data: ReferenceEntityTemplateSchema = {
   name: 'Order',
   description:
@@ -25,11 +20,6 @@ const data: ReferenceEntityTemplateSchema = {
       description: ORDER_CONFIRMATION_API_PROPERTIES_DESCRIPTION,
       type: 'OrderConfirmationApi',
     },
-    {
-      title: 'OrderStatusApi',
-      description: ORDER_STATUS_API_PROPERTIES_DESCRIPTION,
-      type: 'OrderStatusApiEmpty',
-    },
   ],
   related: getLinksByTag('apis'),
 };
diff --git a/packages/ui-extensions/docs/surfaces/checkout/reference/examples/attribute-values.example.ts b/packages/ui-extensions/docs/surfaces/checkout/reference/examples/attribute-values.example.ts
@@ -0,0 +1,42 @@
+import {
+  extension,
+  Text,
+} from '@shopify/ui-extensions/checkout';
+
+export default extension(
+  'purchase.checkout.block.render',
+  (root, {attributes}) => {
+    attributes.subscribe(() => {
+      renderUI();
+    });
+
+    function renderUI() {
+      const buyerSelectedFreeTShirt =
+        attributes.current?.find(
+          (attr) =>
+            attr.key ===
+            'buyerSelectedFreeTShirt',
+        )?.value;
+
+      const tshirtSize = attributes.current?.find(
+        (attr) => attr.key === 'tshirtSize',
+      )?.value;
+
+      if (
+        Boolean(buyerSelectedFreeTShirt) === true
+      ) {
+        root.replaceChildren(
+          root.createComponent(
+            Text,
+            undefined,
+            `You selected a free t-shirt, size: ${tshirtSize}`,
+          ),
+        );
+      } else {
+        root.replaceChildren();
+      }
+    }
+
+    renderUI();
+  },
+);
diff --git a/packages/ui-extensions/docs/surfaces/checkout/reference/examples/attributes/attribute-change.example.ts b/packages/ui-extensions/docs/surfaces/checkout/reference/examples/attributes/attribute-change.example.ts
@@ -0,0 +1,73 @@
+import {
+  extension,
+  BlockStack,
+  Button,
+  Text,
+} from '@shopify/ui-extensions/checkout';
+
+export default extension(
+  'purchase.checkout.block.render',
+  (
+    root,
+    {
+      attributes,
+      instructions,
+      applyAttributeChange,
+    },
+  ) => {
+    let giftWrap = false;
+    const text = root.createComponent(Text);
+    const button = root.createComponent(Button, {
+      onPress: async () => {
+        const result = giftWrap
+          ? await applyAttributeChange({
+              type: 'removeAttribute',
+              key: 'giftWrap',
+            })
+          : await applyAttributeChange({
+              type: 'updateAttribute',
+              key: 'giftWrap',
+              value: 'true',
+            });
+        if (result.type === 'error') {
+          console.error(result.message);
+        }
+      },
+    });
+    const blockStack = root.createComponent(
+      BlockStack,
+      {
+        spacing: 'tight',
+      },
+      [text, button],
+    );
+
+    attributes.subscribe(updateUI);
+    instructions.subscribe(updateUI);
+
+    function updateUI() {
+      giftWrap = Boolean(
+        attributes.current?.find(
+          (attr) => attr.key === 'giftWrap',
+        )?.value,
+      );
+
+      text.replaceChildren(
+        `Gift wrapping: ${giftWrap ? 'Added' : 'Not set'}`,
+      );
+      button.updateProps({
+        disabled:
+          !instructions.current?.attributes
+            ?.canUpdateAttributes,
+      });
+      button.replaceChildren(
+        giftWrap
+          ? 'Remove gift wrap'
+          : 'Add gift wrap',
+      );
+    }
+    updateUI();
+
+    root.append(blockstack);
+  },
+);
diff --git a/packages/ui-extensions/docs/surfaces/checkout/reference/examples/attributes/attribute-change.example.tsx b/packages/ui-extensions/docs/surfaces/checkout/reference/examples/attributes/attribute-change.example.tsx
@@ -0,0 +1,60 @@
+import {
+  reactExtension,
+  BlockStack,
+  Button,
+  Text,
+  useAttributeValues,
+  useApplyAttributeChange,
+  useInstructions,
+} from '@shopify/ui-extensions-react/checkout';
+
+export default reactExtension(
+  'purchase.checkout.block.render',
+  () => <Extension />,
+);
+
+function Extension() {
+  const [giftWrapValue] = useAttributeValues([
+    'giftWrap',
+  ]);
+  const giftWrap = Boolean(giftWrapValue);
+  const applyAttributeChange =
+    useApplyAttributeChange();
+  const instructions = useInstructions();
+
+  async function toggleGiftWrap() {
+    const result = giftWrap
+      ? await applyAttributeChange({
+          type: 'removeAttribute',
+          key: 'giftWrap',
+        })
+      : await applyAttributeChange({
+          type: 'updateAttribute',
+          key: 'giftWrap',
+          value: 'true',
+        });
+    if (result.type === 'error') {
+      console.error(result.message);
+    }
+  }
+
+  return (
+    <BlockStack spacing="tight">
+      <Text>
+        Gift wrapping:{' '}
+        {giftWrap ? 'Added' : 'Not set'}
+      </Text>
+      <Button
+        onPress={toggleGiftWrap}
+        disabled={
+          !instructions.attributes
+            .canUpdateAttributes
+        }
+      >
+        {giftWrap
+          ? 'Remove gift wrap'
+          : 'Add gift wrap'}
+      </Button>
+    </BlockStack>
+  );
+}
diff --git a/packages/ui-extensions/docs/surfaces/checkout/reference/helper.docs.ts b/packages/ui-extensions/docs/surfaces/checkout/reference/helper.docs.ts
@@ -10,12 +10,13 @@ export const REQUIRES_PROTECTED_CUSTOMER_DATA_LEVEL_2 =
 
 type NonEmptyArray<T> = [T, ...T[]];
 type ExtensionExampleLanguage = 'js' | 'jsx' | 'toml';
-type ExtensionCodeTabConfig = {
-  [key in ExtensionExampleLanguage]: {
+type ExtensionCodeTabConfig = Record<
+  ExtensionExampleLanguage,
+  {
     title: string;
     fileExtension: 'ts' | 'tsx' | 'toml';
-  };
-};
+  }
+>;
 const codeExampleTabConfig: ExtensionCodeTabConfig = {
   js: {
     title: 'JavaScript',
@@ -485,6 +486,14 @@ The contents of the token are signed using your shared app secret.  The optional
         tabs: getExtensionCodeTabs('attribute-values'),
       },
     },
+    'attributes/attribute-change': {
+      description:
+        'You can add or remove cart and checkout attributes by using the `applyAttributeChange` API.',
+      codeblock: {
+        title: 'Applying changes to attributes',
+        tabs: getExtensionCodeTabs('attributes/attribute-change'),
+      },
+    },
     'ui-close-overlay': {
       description: '',
       codeblock: {
@@ -883,6 +892,3 @@ export const CHECKOUT_API_PROPERTIES_DESCRIPTION =
 
 export const ORDER_CONFIRMATION_API_PROPERTIES_DESCRIPTION =
   'The API object provided to `purchase.thank-you` extension targets.';
-
-export const ORDER_STATUS_API_PROPERTIES_DESCRIPTION =
-  '> Note: This documentation has moved to customer accounts. Refer to [Order API](/docs/api/customer-account-ui-extensions/apis/order)';
diff --git a/packages/ui-extensions/docs/surfaces/checkout/staticPages/error-handling.doc.ts b/packages/ui-extensions/docs/surfaces/checkout/staticPages/error-handling.doc.ts
@@ -27,7 +27,7 @@ const data: LandingTemplateSchema = {
       anchorLink: 'third-party-libraries',
       title: 'Third party libraries',
       sectionContent: `
-You can use error reporting libraries like [Bugsnag](https://www.bugsnag.com/) or [Sentry](https://sentry.io/). However, they might require extra configuration because UI extensions run inside of a [Web Worker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API).
+You can use error reporting libraries like [Bugsnag](https://www.bugsnag.com/) or [Sentry](https://sentry.io/). However, they might require extra configuration because UI extensions run inside of a [Web Worker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API). You should also consider using [source maps](https://shopify.dev/docs/apps/build/checkout/test-checkout-ui-extensions#troubleshooting-with-source-maps) to help debug errors.
 
 > Tip:
 > You must request [network access](/api/checkout-ui-extensions/configuration#network-access) to transmit errors to a third party service.
diff --git a/packages/ui-extensions/src/shared.ts b/packages/ui-extensions/src/shared.ts
@@ -24,6 +24,7 @@ export type ApiVersion =
   | '2024-07'
   | '2024-10'
   | '2025-01'
+  | '2025-04'
   | 'unstable';
 
 /**
@@ -917,6 +918,7 @@ export type StorefrontApiVersion =
   | '2024-07'
   | '2024-10'
   | '2025-01'
+  | '2025-04'
   | 'unstable';
 
 /**
diff --git a/packages/ui-extensions/src/surfaces/checkout/api/checkout/checkout.ts b/packages/ui-extensions/src/surfaces/checkout/api/checkout/checkout.ts
@@ -76,7 +76,23 @@ export interface AttributeUpdateChange {
   value: string;
 }
 
-export type AttributeChange = AttributeUpdateChange;
+/**
+ * Removes an attribute on the order if an attribute with the
+ * provided key already exists.
+ */
+export interface AttributeRemoveChange {
+  /**
+   * The type of the `AttributeRemoveChange` API.
+   */
+  type: 'removeAttribute';
+
+  /**
+   * Key of the attribute to remove
+   */
+  key: string;
+}
+
+export type AttributeChange = AttributeUpdateChange | AttributeRemoveChange;
 
 /**
  * The returned result of a successful update to an attribute.
diff --git a/packages/ui-extensions/src/surfaces/checkout/api/order-confirmation/order-confirmation.ts b/packages/ui-extensions/src/surfaces/checkout/api/order-confirmation/order-confirmation.ts
@@ -12,6 +12,11 @@ export interface OrderConfirmation {
    * For orders created in 2024 and onwards, the number will always be present. For orders created before that date, the number might not be present.
    */
   number?: string;
+
+  /**
+   * Whether this is the customer's first order.
+   */
+  isFirstOrder: boolean;
 }
 
 export interface OrderConfirmationApi {
diff --git a/packages/ui-extensions/src/surfaces/checkout/api/standard/standard.ts b/packages/ui-extensions/src/surfaces/checkout/api/standard/standard.ts
@@ -1407,6 +1407,12 @@ export interface Customer {
    * @private
    */
   storeCreditAccounts: StoreCreditAccount[];
+  /**
+   * The number of previous orders made by this customer.
+   *
+   * {% include /apps/checkout/privacy-icon.md %} Requires level 1 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).
+   */
+  ordersCount: number;
 }
 
 /**
diff --git a/packages/ui-extensions/src/surfaces/checkout/components/Chat/examples/app-bridge-communication.example.js b/packages/ui-extensions/src/surfaces/checkout/components/Chat/examples/app-bridge-communication.example.js
@@ -3,7 +3,7 @@
 let buyerFirstName;
 
 // In the hosted application Javascript, listen for messages from the UI extension.
-shopify.extension.port.onMessage = async (event) => {
+shopify.extension.port.onmessage = async (event) => {
   // if the message's data has a ping action, respond with a pong
   if (event.data.action === 'ping') {
     buyerFirstName = event.data.buyer.firstName;
diff --git a/packages/ui-extensions/src/surfaces/checkout/helper.docs.ts b/packages/ui-extensions/src/surfaces/checkout/helper.docs.ts

Original file line number	Diff line number	Diff line change
`@@ -29,7 +29,7 @@ const data: ReferenceEntityTemplateSchema = {`
`29`	`29`	`{`
`30`	`30`	`title: 'useLocalizedField',`
`31`	`31`	`description:`
`32`		`- 'Returns the requested localized field and re-renders your component if the value changes.',`
	`32`	`+ 'Returns the current localized fields and re-renders your component if the values change.',`
`33`	`33`	`type: 'UseLocalizedFieldGeneratedType',`
`34`	`34`	`},`
`35`	`35`	`],`