Backport extension APIs to 2023-04 (#1135)

.changeset/kind-carpets-applaud.md

@@ -0,0 +1,5 @@
+---
+'@shopify/ui-extensions-react': minor
+---
+
+Rename `useExtensionData()` to `useExtension()`

.changeset/little-sheep-join.md

@@ -0,0 +1,5 @@
+---
+'@shopify/ui-extensions-react': patch
+---
+
+Allow passing target name to `useApi()` for type inference

.changeset/neat-vans-heal.md

@@ -0,0 +1,5 @@
+---
+'@shopify/ui-extensions': minor
+---
+
+Backported `Extension.target` field for checkout UI extensions

.changeset/odd-crabs-eat.md

@@ -0,0 +1,5 @@
+---
+'@shopify/ui-extensions-react': minor
+---
+
+Make @shopify/ui-extensions a peer dependency for React library

.changeset/pink-poets-confess.md

@@ -0,0 +1,5 @@
+---
+'@shopify/ui-extensions': patch
+---
+
+Preserve generic type argument for `I18nTranslate` function

.changeset/slimy-timers-heal.md

@@ -0,0 +1,5 @@
+---
+'@shopify/ui-extensions-react': patch
+---
+
+Allow React extensions to return asynchronous results

packages/ui-extensions-react/package.json

@@ -45,13 +45,16 @@
   "dependencies": {
     "@remote-ui/async-subscription": "^2.1.12",
     "@remote-ui/react": "4.5.x",
-    "@shopify/ui-extensions": "2023.4.1",
     "@types/react": ">=17.0.0 <18.0.0"
   },
   "peerDependencies": {
+    "@shopify/ui-extensions": "2023.4.x",
     "react": ">=17.0.0 <18.0.0"
   },
   "peerDependenciesMeta": {
+    "@shopify/ui-extensions": {
+      "optional": false
+    },
     "react": {
       "optional": false
     }

packages/ui-extensions-react/src/surfaces/admin/hooks/api.ts

@@ -13,7 +13,7 @@ import {AdminUIExtensionError} from '../errors';
  */
 export function useApi<
   ID extends RenderExtensionTarget = RenderExtensionTarget,
->(): ApiForRenderExtension<ID> {
+>(_id?: ID): ApiForRenderExtension<ID> {
   const api = useContext(ExtensionApiContext);
 
   if (api == null) {

packages/ui-extensions-react/src/surfaces/checkout/hooks/api.ts

@@ -16,9 +16,9 @@ import {ExtensionApiContext} from '../context';
  *
  * For reference, see [ExtensionPoints](https://shopify.dev/docs/api/checkout-ui-extensions/apis/extensionpoints) to determine what API object will be returned by your extension point.
  */
-export function useApi<
-  ID extends RenderExtensionPoint = RenderExtensionPoint,
->(): ApiForRenderExtension<ID> {
+export function useApi<ID extends RenderExtensionPoint = RenderExtensionPoint>(
+  _id?: ID,
+): ApiForRenderExtension<ID> {
   const api = useContext(ExtensionApiContext);
 
   if (api == null) {

packages/ui-extensions-react/src/surfaces/checkout/hooks/extension-data.ts → packages/ui-extensions-react/src/surfaces/checkout/hooks/extension.ts

@@ -8,8 +8,15 @@ import {useApi} from './api';
 /**
  * Returns the metadata about the extension.
  */
-export function useExtensionData<
+export function useExtension<
   ID extends RenderExtensionPoint = RenderExtensionPoint,
 >(): Extension {
   return useApi<ID>().extension;
 }
+
+/**
+ * Returns the metadata about the extension.
+ *
+ * @deprecated Use `useExtension()` instead.
+ */
+export const useExtensionData = useExtension;

packages/ui-extensions-react/src/surfaces/checkout/hooks/index.ts

@@ -26,7 +26,7 @@ export {useTarget} from './target';
 export {useAppMetafields} from './app-metafields';
 export {useShop} from './shop';
 export {useStorage} from './storage';
-export {useExtensionData} from './extension-data';
+export {useExtension, useExtensionData} from './extension';
 export {useSubscription} from './subscription';
 export {useCustomer, useEmail, usePhone} from './buyer-identity';
 export {useTranslate} from './translate';

packages/ui-extensions-react/src/surfaces/checkout/render.tsx

@@ -28,34 +28,41 @@ import {ExtensionApiContext} from './context';
  */
 export function reactExtension<ExtensionPoint extends RenderExtensionPoint>(
   target: ExtensionPoint,
-  render: (api: ApiForRenderExtension<ExtensionPoint>) => ReactElement<any>,
+  render: (
+    api: ApiForRenderExtension<ExtensionPoint>,
+  ) => ReactElement<any> | Promise<ReactElement<any>>,
 ): ExtensionPoints[ExtensionPoint] {
   // TypeScript can’t infer the type of the callback because it’s a big union
   // type. To get around it, we’ll just fake like we are rendering the
   // Checkout::Dynamic::Render extension, since all render extensions have the same general
   // shape (`RenderExtension`).
-  return extension<'Checkout::Dynamic::Render'>(target as any, (root, api) => {
-    return new Promise((resolve, reject) => {
-      try {
-        remoteRender(
-          <ExtensionApiContext.Provider value={api}>
-            <ErrorBoundary>
-              {render(api as ApiForRenderExtension<ExtensionPoint>)}
-            </ErrorBoundary>
-          </ExtensionApiContext.Provider>,
-          root,
-          () => {
-            resolve();
-          },
-        );
-      } catch (error) {
-        // Workaround for https://github.com/Shopify/ui-extensions/issues/325
-        // eslint-disable-next-line no-console
-        console.error(error);
-        reject(error);
-      }
-    });
-  }) as any;
+  return extension<'Checkout::Dynamic::Render'>(
+    target as any,
+    async (root, api) => {
+      const element = await render(
+        api as ApiForRenderExtension<ExtensionPoint>,
+      );
+
+      await new Promise<void>((resolve, reject) => {
+        try {
+          remoteRender(
+            <ExtensionApiContext.Provider value={api}>
+              <ErrorBoundary>{element}</ErrorBoundary>
+            </ExtensionApiContext.Provider>,
+            root,
+            () => {
+              resolve();
+            },
+          );
+        } catch (error) {
+          // Workaround for https://github.com/Shopify/ui-extensions/issues/325
+          // eslint-disable-next-line no-console
+          console.error(error);
+          reject(error);
+        }
+      });
+    },
+  ) as any;
 }
 
 /**

packages/ui-extensions-react/src/surfaces/checkout/tests/react-extension.test.tsx

@@ -54,16 +54,17 @@ describe('render()', () => {
     console.error = consoleError;
   });
 
-  it('calls extension() with the extension point', () => {
-    reactExtension('Checkout::Dynamic::Render', () => <></>);
+  it('calls extension() with the extension point', async () => {
+    await reactExtension('Checkout::Dynamic::Render', () => <></>);
+
     expect(extension).toHaveBeenCalledWith(
       'Checkout::Dynamic::Render',
       expect.any(Function),
     );
   });
 
-  it('reports errors thrown during reconcilation onto global this', () => {
-    reactExtension('Checkout::Dynamic::Render', () => {
+  it('reports errors thrown during reconcilation onto global this', async () => {
+    await reactExtension('Checkout::Dynamic::Render', () => {
       return <Thrown />;
     });
 

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

@@ -10,6 +10,7 @@ import type {
   SellingPlan,
   Attribute,
 } from '../shared';
+import type {ExtensionPoint} from '../../extension-points';
 
 /**
  * A key-value storage object for extension points.
@@ -59,7 +60,18 @@ export type Capability = 'api_access' | 'network_access' | 'block_progress';
 /**
  * Meta information about an extension point.
  */
-export interface Extension {
+export interface Extension<Target extends ExtensionPoint = ExtensionPoint> {
+  /**
+   * The identifier that specifies where in Shopify’s UI your code is being
+   * injected. This will be one of the targets you have included in your
+   * extension’s configuration file.
+   *
+   * @example 'Checkout::Dynamic::Render'
+   * @see https://shopify.dev/docs/api/checkout-ui-extensions/unstable/extension-targets-overview
+   * @see https://shopify.dev/docs/apps/app-extensions/configuration#targets
+   */
+  target: Target;
+
   /**
    * The published version of the running extension point.
    *
@@ -213,12 +225,14 @@ export type Version = string;
  *
  * @example translate("banner.title")
  */
-export type I18nTranslate<ReplacementType = string> = (
-  key: string,
-  options?: {[placeholderKey: string]: ReplacementType | string | number},
-) => ReplacementType extends string | number
-  ? string
-  : (string | ReplacementType)[];
+export interface I18nTranslate {
+  <ReplacementType = string>(
+    key: string,
+    options?: {[placeholderKey: string]: ReplacementType | string | number},
+  ): ReplacementType extends string | number
+    ? string
+    : (string | ReplacementType)[];
+}
 
 export interface I18n {
   /**
@@ -385,9 +399,7 @@ export interface BuyerJourney {
   completed: StatefulRemoteSubscribable<boolean>;
 }
 
-export interface StandardApi<
-  ExtensionPoint extends import('../../extension-points').ExtensionPoint,
-> {
+export interface StandardApi<Target extends ExtensionPoint = ExtensionPoint> {
   /**
    * Methods for interacting with [Web Pixels](https://shopify.dev/docs/apps/marketing), such as emitting an event.
    */
@@ -456,11 +468,16 @@ export interface StandardApi<
   /**
    * Meta information about the extension.
    */
-  extension: Extension;
+  extension: Extension<Target>;
 
   /**
-   * The identifier of the running extension point.
-   * @example 'Checkout::PostPurchase::Render'
+   * The identifier that specifies where in Shopify’s UI your code is being
+   * injected. This will be one of the targets you have included in your
+   * extension’s configuration file.
+   *
+   * @example 'Checkout::Dynamic::Render'
+   * @see https://shopify.dev/docs/api/checkout-ui-extensions/unstable/extension-targets-overview
+   * @see https://shopify.dev/docs/apps/app-extensions/configuration#targets
    */
   extensionPoint: ExtensionPoint;