updates localized field hooks

Shopify · Jan 17, 2025 · 6f8bf8b · 6f8bf8b
1 parent 46f5749
commit 6f8bf8b
Show file tree

Hide file tree

Showing 4 changed files with 164 additions and 8 deletions.
diff --git a/packages/ui-extensions-react/src/surfaces/checkout.ts b/packages/ui-extensions-react/src/surfaces/checkout.ts
@@ -361,4 +361,7 @@ export {useDeliverySelectionGroups} from './checkout/hooks/delivery-selection-gr
 export {useCheckoutToken} from './checkout/hooks/checkout-token';
 export {useCustomerPrivacy} from './checkout/hooks/customer-privacy';
 export {useInstructions} from './checkout/hooks/instructions';
-export {useLocalizedFields} from './checkout/hooks/localized-fields';
+export {
+  useLocalizedFields,
+  useLocalizedField,
+} from './checkout/hooks/localized-fields';
diff --git a/packages/ui-extensions-react/src/surfaces/checkout/hooks/localized-fields.ts b/packages/ui-extensions-react/src/surfaces/checkout/hooks/localized-fields.ts
@@ -15,7 +15,7 @@ import {useSubscription} from './subscription';
  */
 export function useLocalizedFields<
   Target extends RenderExtensionTarget = RenderExtensionTarget,
->(keys: LocalizedFieldKey[]): LocalizedField[] | undefined {
+>(keys?: LocalizedFieldKey[]): LocalizedField[] {
   const {localizedFields} = useApi<Target>();
 
   if (!localizedFields) {
@@ -24,7 +24,26 @@ export function useLocalizedFields<
     );
   }
 
-  return useSubscription(localizedFields)?.filter(({key}) =>
-    keys.includes(key),
-  );
+  const localizedFieldsData = useSubscription(localizedFields);
+
+  if (!keys) {
+    return localizedFieldsData;
+  }
+
+  if (!keys.length) {
+    return [];
+  }
+
+  return localizedFieldsData.filter(({key}) => keys.includes(key));
+}
+
+/**
+ * Returns the current localized field or undefined for the specified
+ * localized field key and re-renders your component if the value changes.
+ */
+export function useLocalizedField<
+  Target extends RenderExtensionTarget = RenderExtensionTarget,
+>(key: LocalizedFieldKey): LocalizedField | undefined {
+  const fields = useLocalizedFields<Target>([key]);
+  return fields[0];
 }
diff --git a/packages/ui-extensions-react/src/surfaces/checkout/hooks/tests/localized-fields.test.ts b/packages/ui-extensions-react/src/surfaces/checkout/hooks/tests/localized-fields.test.ts
@@ -1,6 +1,6 @@
 import type {LocalizedField} from '@shopify/ui-extensions/checkout';
 
-import {useLocalizedFields} from '../localized-fields';
+import {useLocalizedFields, useLocalizedField} from '../localized-fields';
 
 import {mount, createMockStatefulRemoteSubscribable} from './mount';
 
@@ -19,7 +19,53 @@ describe('useLocalizedFields', () => {
     );
   });
 
-  it('returns empty if no localized fields match the passed keys', () => {
+  it('returns all localized fields if no keys are passed', () => {
+    const localizedFields: LocalizedField[] = [
+      {
+        key: 'TAX_CREDENTIAL_BR',
+        title: 'CPF/CNPJ',
+        value: 'test-value',
+      },
+      {
+        key: 'SHIPPING_CREDENTIAL_BR',
+        title: 'CPF/CNPJ',
+        value: 'test-value',
+      },
+    ];
+
+    const extensionApi = {
+      localizedFields: createMockStatefulRemoteSubscribable(localizedFields),
+    };
+
+    const {value} = mount.hook(() => useLocalizedFields(), {extensionApi});
+
+    expect(value).toStrictEqual(localizedFields);
+  });
+
+  it('returns an empty array if the passed keys array is empty', () => {
+    const localizedFields: LocalizedField[] = [
+      {
+        key: 'TAX_CREDENTIAL_BR',
+        title: 'CPF/CNPJ',
+        value: 'test-value',
+      },
+      {
+        key: 'SHIPPING_CREDENTIAL_BR',
+        title: 'CPF/CNPJ',
+        value: 'test-value',
+      },
+    ];
+
+    const extensionApi = {
+      localizedFields: createMockStatefulRemoteSubscribable(localizedFields),
+    };
+
+    const {value} = mount.hook(() => useLocalizedFields([]), {extensionApi});
+
+    expect(value).toStrictEqual([]);
+  });
+
+  it('returns an empty array if no localized fields match the passed keys', () => {
     const localizedFields: LocalizedField[] = [
       {
         key: 'TAX_CREDENTIAL_BR',
@@ -75,4 +121,92 @@ describe('useLocalizedFields', () => {
 
     expect(value).toMatchObject([localizedFields[0], localizedFields[2]]);
   });
+
+  it('returns an array of localized fields for any matching fields', () => {
+    const localizedFields: LocalizedField[] = [
+      {
+        key: 'TAX_CREDENTIAL_MX',
+        title: 'Tax credential MX',
+        value: 'test-value',
+      },
+      {
+        key: 'SHIPPING_CREDENTIAL_MX',
+        title: 'Shipping credential MX',
+        value: 'test-value',
+      },
+      {
+        key: 'TAX_CREDENTIAL_USE_MX',
+        title: 'Tax credential use MX',
+        value: 'test-value',
+      },
+    ];
+
+    const extensionApi = {
+      localizedFields: createMockStatefulRemoteSubscribable(localizedFields),
+    };
+
+    const {value} = mount.hook(
+      () =>
+        useLocalizedFields([
+          'TAX_CREDENTIAL_MX',
+          'TAX_CREDENTIAL_BR',
+          'TAX_CREDENTIAL_USE_MX',
+        ]),
+      {extensionApi},
+    );
+
+    expect(value).toMatchObject([localizedFields[0], localizedFields[2]]);
+  });
+});
+
+describe('useLocalizedField', () => {
+  it('returns the localized field that matches the passed key', async () => {
+    const localizedFields: LocalizedField[] = [
+      {
+        key: 'TAX_CREDENTIAL_MX',
+        title: 'Tax credential MX',
+        value: 'test-value-1',
+      },
+      {
+        key: 'SHIPPING_CREDENTIAL_MX',
+        title: 'Shipping credential MX',
+        value: 'test-value-2',
+      },
+      {
+        key: 'TAX_CREDENTIAL_USE_MX',
+        title: 'Tax credential use MX',
+        value: 'test-value-3',
+      },
+    ];
+
+    const extensionApi = {
+      localizedFields: createMockStatefulRemoteSubscribable(localizedFields),
+    };
+
+    const {value} = mount.hook(
+      () => useLocalizedField('TAX_CREDENTIAL_USE_MX'),
+      {
+        extensionApi,
+      },
+    );
+
+    expect(value).toStrictEqual(localizedFields[2]);
+  });
+
+  it('returns undefined if no localized field matches the passed key', async () => {
+    const localizedFields: LocalizedField[] = [];
+
+    const extensionApi = {
+      localizedFields: createMockStatefulRemoteSubscribable(localizedFields),
+    };
+
+    const {value} = mount.hook(
+      () => useLocalizedField('TAX_CREDENTIAL_USE_MX'),
+      {
+        extensionApi,
+      },
+    );
+
+    expect(value).toBeUndefined();
+  });
 });
diff --git a/packages/ui-extensions/src/surfaces/checkout/api/standard/standard.ts b/packages/ui-extensions/src/surfaces/checkout/api/standard/standard.ts
@@ -746,7 +746,7 @@ export interface StandardApi<Target extends ExtensionTarget = ExtensionTarget> {
    * The API for reading additional fields that are required in checkout under certain circumstances.
    * For example, some countries require additional fields for customs information or tax identification numbers.
    */
-  localizedFields?: StatefulRemoteSubscribable<LocalizedField[] | undefined>;
+  localizedFields?: StatefulRemoteSubscribable<LocalizedField[]>;
 }
 
 export interface Ui {