@shopify/ui-extensions 2024.10.2 → 2025.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shopify/ui-extensions",
-  "version": "2024.10.2",
+  "version": "2025.1.0",
   "scripts": {
     "docs:admin": "bash ./docs/surfaces/admin/build-docs.sh",
     "gen-docs:admin": "bash ./docs/surfaces/admin/create-doc-files.sh \"admin\"",

package/src/shared.ts

@@ -23,6 +23,7 @@ export type ApiVersion =
   | '2024-04'
   | '2024-07'
   | '2024-10'
+  | '2025-01'
   | 'unstable';
 
 /**
@@ -38,7 +39,7 @@ export type ApiVersion =
  *
  * * [`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.
  *
- * * `iframe.sources`: the extension can embed an external URL in an iframe.
+ * * [`iframe.sources`](https://shopify.dev/docs/api/checkout-ui-extensions/configuration#iframe): the extension can embed an external URL in an iframe.
  */
 
 export type Capability =
@@ -858,6 +859,49 @@ export type CountryCode =
   | 'ZW'
   | 'ZZ';
 
+// For instructions on how to update this list see: https://github.com/Shopify/checkout-web/pull/39534
+/**
+ * A union of keys for the localized fields that are required by certain countries.
+ */
+export type LocalizedFieldKey =
+  | 'SHIPPING_CREDENTIAL_BR'
+  | 'SHIPPING_CREDENTIAL_CL'
+  | 'SHIPPING_CREDENTIAL_CN'
+  | 'SHIPPING_CREDENTIAL_CO'
+  | 'SHIPPING_CREDENTIAL_CR'
+  | 'SHIPPING_CREDENTIAL_EC'
+  | 'SHIPPING_CREDENTIAL_ES'
+  | 'SHIPPING_CREDENTIAL_GT'
+  | 'SHIPPING_CREDENTIAL_ID'
+  | 'SHIPPING_CREDENTIAL_KR'
+  | 'SHIPPING_CREDENTIAL_MY'
+  | 'SHIPPING_CREDENTIAL_MX'
+  | 'SHIPPING_CREDENTIAL_PE'
+  | 'SHIPPING_CREDENTIAL_PT'
+  | 'SHIPPING_CREDENTIAL_PY'
+  | 'SHIPPING_CREDENTIAL_TR'
+  | 'SHIPPING_CREDENTIAL_TW'
+  | 'SHIPPING_CREDENTIAL_TYPE_CO'
+  | 'TAX_CREDENTIAL_BR'
+  | 'TAX_CREDENTIAL_CL'
+  | 'TAX_CREDENTIAL_CO'
+  | 'TAX_CREDENTIAL_CR'
+  | 'TAX_CREDENTIAL_EC'
+  | 'TAX_CREDENTIAL_ES'
+  | 'TAX_CREDENTIAL_GT'
+  | 'TAX_CREDENTIAL_ID'
+  | 'TAX_CREDENTIAL_IT'
+  | 'TAX_CREDENTIAL_MX'
+  | 'TAX_CREDENTIAL_MY'
+  | 'TAX_CREDENTIAL_PE'
+  | 'TAX_CREDENTIAL_PT'
+  | 'TAX_CREDENTIAL_PY'
+  | 'TAX_CREDENTIAL_TR'
+  | 'TAX_CREDENTIAL_TYPE_CO'
+  | 'TAX_CREDENTIAL_TYPE_MX'
+  | 'TAX_CREDENTIAL_USE_MX'
+  | 'TAX_EMAIL_IT';
+
 /**
  * Union of supported storefront API versions
  */
@@ -872,6 +916,7 @@ export type StorefrontApiVersion =
   | '2024-04'
   | '2024-07'
   | '2024-10'
+  | '2025-01'
   | 'unstable';
 
 /**

package/src/surfaces/admin/api/action/action.doc.ts

@@ -14,6 +14,7 @@ const data: ReferenceEntityTemplateSchema = {
     },
   ],
   category: 'API',
+  subCategory: 'Target APIs',
   related: [],
 };
 

package/src/surfaces/admin/api/action/action.ts

@@ -1,6 +1,8 @@
 import type {StandardApi} from '../standard/standard';
 import type {ExtensionTarget as AnyExtensionTarget} from '../../extension-targets';
 import type {Data} from '../shared';
+import type {ResourcePickerApi} from '../resource-picker/resource-picker';
+import type {PickerApi} from '../picker/picker';
 
 export interface ActionExtensionApi<ExtensionTarget extends AnyExtensionTarget>
   extends StandardApi<ExtensionTarget> {
@@ -13,4 +15,14 @@ export interface ActionExtensionApi<ExtensionTarget extends AnyExtensionTarget>
    * Information about the currently viewed or selected items.
    */
   data: Data;
+
+  /**
+   * Renders the [Resource Picker](resource-picker), allowing users to select a resource for the extension to use as part of its flow.
+   */
+  resourcePicker: ResourcePickerApi;
+
+  /**
+   * Renders a custom [Picker](picker) dialog allowing users to select values from a list.
+   */
+  picker: PickerApi;
 }

package/src/surfaces/admin/api/block/block.doc.ts

@@ -14,6 +14,7 @@ const data: ReferenceEntityTemplateSchema = {
     },
   ],
   category: 'API',
+  subCategory: 'Target APIs',
   related: [],
 };
 

package/src/surfaces/admin/api/block/block.ts

@@ -2,6 +2,7 @@ import type {StandardApi} from '../standard/standard';
 import type {ExtensionTarget as AnyExtensionTarget} from '../../extension-targets';
 import type {Data} from '../shared';
 import type {ResourcePickerApi} from '../resource-picker/resource-picker';
+import type {PickerApi} from '../picker/picker';
 
 export interface Navigation {
   /**
@@ -26,7 +27,12 @@ export interface BlockExtensionApi<ExtensionTarget extends AnyExtensionTarget>
   navigation: Navigation;
 
   /**
-   * Renders the [Resource Picker](/docs/api/app-bridge-library/apis/resource-picker), allowing users to select a resource for the extension to use as part of its flow.
+   * Renders the [Resource Picker](resource-picker), allowing users to select a resource for the extension to use as part of its flow.
    */
   resourcePicker: ResourcePickerApi;
+
+  /**
+   * Renders a custom [Picker](picker) dialog allowing users to select values from a list.
+   */
+  picker: PickerApi;
 }

package/src/surfaces/admin/api/checkout-rules/launch-options.ts

@@ -6,7 +6,6 @@ interface Metafield {
   value: string;
   type: string;
 }
-
 interface Validation {
   /**
    * the validation's gid when active in a shop

package/src/surfaces/admin/api/checkout-rules/metafields.ts

@@ -1,49 +1,4 @@
-const supportedDefinitionTypes = [
-  'boolean',
-  'collection_reference',
-  'color',
-  'date',
-  'date_time',
-  'dimension',
-  'file_reference',
-  'json',
-  'metaobject_reference',
-  'mixed_reference',
-  'money',
-  'multi_line_text_field',
-  'number_decimal',
-  'number_integer',
-  'page_reference',
-  'product_reference',
-  'rating',
-  'rich_text_field',
-  'single_line_text_field',
-  'product_taxonomy_value_reference',
-  'url',
-  'variant_reference',
-  'volume',
-  'weight',
-  'list.collection_reference',
-  'list.color',
-  'list.date',
-  'list.date_time',
-  'list.dimension',
-  'list.file_reference',
-  'list.metaobject_reference',
-  'list.mixed_reference',
-  'list.number_decimal',
-  'list.number_integer',
-  'list.page_reference',
-  'list.product_reference',
-  'list.rating',
-  'list.single_line_text_field',
-  'list.url',
-  'list.variant_reference',
-  'list.volume',
-  'list.weight',
-] as const;
-
-export type SupportedDefinitionType = (typeof supportedDefinitionTypes)[number];
+import {SupportedDefinitionType} from '../shared';
 
 interface MetafieldUpdateChange {
   type: 'updateMetafield';

package/src/surfaces/admin/api/checkout-rules/validation-settings.doc.ts

@@ -19,6 +19,7 @@ const data: ReferenceEntityTemplateSchema = {
     },
   ],
   category: 'API',
+  subCategory: 'Target APIs',
   related: [],
 };
 

package/src/surfaces/admin/api/customer-segment-template/customer-segment-template.doc.ts

@@ -14,6 +14,7 @@ const data: ReferenceEntityTemplateSchema = {
     },
   ],
   category: 'API',
+  subCategory: 'Target APIs',
   related: [],
 };
 

package/src/surfaces/admin/api/customer-segment-template/customer-segment-template.ts

@@ -2,16 +2,11 @@ import type {StandardApi} from '../standard/standard';
 import type {I18n} from '../../../../api';
 import type {ExtensionTarget as AnyExtensionTarget} from '../../extension-targets';
 
-/* List of enabled query language features during a progressive rollout */
-type CustomerSegmentationFeature =
-  /* Enables templates using filters only available when B2B is enabled. For example: companies IS NOT NULL */
-  'b2bEnabled';
-
 export interface CustomerSegmentTemplateApi<
   ExtensionTarget extends AnyExtensionTarget,
 > extends StandardApi<ExtensionTarget> {
   /* Utilities for translating content according to the current `localization` of the admin. */
   i18n: I18n;
   /** @private */
-  __enabledFeatures: CustomerSegmentationFeature[];
+  __enabledFeatures: string[];
 }

package/src/surfaces/admin/api/discount-function-settings/discount-function-settings.doc.ts

@@ -0,0 +1,27 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'Discount Function Settings API',
+  description:
+    'This API is available to Discount Function Settings extensions. Refer to the [tutorial](/docs/apps/build/discounts/build-ui-extension) for more information. Note that the [`FunctionSettings`](/docs/api/admin-extensions/components/forms/functionsettings) component is required to build Discount Function Settings extensions.',
+  isVisualComponent: false,
+  type: 'API',
+  definitions: [
+    {
+      title: 'applyMetafieldChange',
+      description: 'Applies a change to the discount function settings.',
+      type: 'ApplyMetafieldChange',
+    },
+    {
+      title: 'data',
+      description:
+        'The object exposed to the extension that contains the discount function settings.',
+      type: 'DiscountFunctionSettingsData',
+    },
+  ],
+  category: 'API',
+  subCategory: 'Target APIs',
+  related: [],
+};
+
+export default data;

package/src/surfaces/admin/api/discount-function-settings/discount-function-settings.ts

@@ -0,0 +1,15 @@
+import type {StandardApi} from '../standard/standard';
+import type {ExtensionTarget as AnyExtensionTarget} from '../../extension-targets';
+
+import {ApplyMetafieldChange} from './metafields';
+import {DiscountFunctionSettingsData} from './launch-options';
+
+export interface DiscountFunctionSettingsApi<
+  ExtensionTarget extends AnyExtensionTarget,
+> extends StandardApi<ExtensionTarget> {
+  /**
+   * Applies a change to the discount function settings.
+   */
+  applyMetafieldChange: ApplyMetafieldChange;
+  data: DiscountFunctionSettingsData;
+}

package/src/surfaces/admin/api/discount-function-settings/launch-options.ts

@@ -0,0 +1,29 @@
+interface Metafield {
+  description?: string;
+  id: string;
+  namespace: string;
+  key: string;
+  value: string;
+  type: string;
+}
+
+export enum DiscountClass {
+  Product = 'PRODUCT',
+  Order = 'ORDER',
+  Shipping = 'SHIPPING',
+}
+
+interface Discount {
+  /**
+   * the discount's gid
+   */
+  id: string;
+}
+
+/**
+ * The object that exposes the validation with its settings.
+ */
+export interface DiscountFunctionSettingsData {
+  id: Discount;
+  metafields: Metafield[];
+}

package/src/surfaces/admin/api/discount-function-settings/metafields.ts

@@ -0,0 +1,31 @@
+import {SupportedDefinitionType} from '../shared';
+
+interface MetafieldUpdateChange {
+  type: 'updateMetafield';
+  key: string;
+  namespace?: string;
+  value: string | number;
+  valueType?: SupportedDefinitionType;
+}
+
+interface MetafieldRemoveChange {
+  type: 'removeMetafield';
+  key: string;
+  namespace: string;
+}
+
+type MetafieldChange = MetafieldUpdateChange | MetafieldRemoveChange;
+interface MetafieldChangeResultError {
+  type: 'error';
+  message: string;
+}
+interface MetafieldChangeSuccess {
+  type: 'success';
+}
+type MetafieldChangeResult =
+  | MetafieldChangeSuccess
+  | MetafieldChangeResultError;
+
+export type ApplyMetafieldChange = (
+  change: MetafieldChange,
+) => Promise<MetafieldChangeResult>;

package/src/surfaces/admin/api/picker/examples/direct-api.js

@@ -0,0 +1,73 @@
+const r = await fetch('shopify:admin/api/graphql.json', {
+  method: 'POST',
+  body: JSON.stringify({
+    query: `
+      query GetOrders($first: Int!) {
+        orders(first: $first) {
+          edges {
+            node {
+              id
+              name
+              customer {
+                displayName
+              }
+              originalTotalPriceSet {
+                shopMoney {
+                  amount
+                }
+              }
+              displayFulfillmentStatus
+              displayFinancialStatus
+              unpaid
+            }
+          }
+        }
+      }
+    `,
+    variables: {first: 10},
+  }),
+});
+const {data} = await r.json();
+const orderData = data.orders.edges;
+
+const selected = await picker({
+  heading: 'Select orders',
+  multiple: true,
+  headers: [
+    {title: 'Order'},
+    {title: 'Customer'},
+    {title: 'Total', type: 'number'},
+  ],
+  items: orderData.map((order) => {
+    const {
+      id,
+      name,
+      customer,
+      originalTotalPriceSet: {shopMoney},
+      displayFulfillmentStatus,
+      displayFinancialStatus,
+    } = order.node;
+
+    return {
+      id,
+      heading: name,
+      data: [customer.displayName, `$${shopMoney.amount}`],
+      badges: [
+        {
+          content: displayFulfillmentStatus,
+          tone: displayFulfillmentStatus === 'FULFILLED' ? '' : 'attention',
+          progress:
+            displayFulfillmentStatus === 'FULFILLED'
+              ? 'complete'
+              : 'incomplete',
+        },
+        {
+          content: displayFinancialStatus,
+          tone: displayFinancialStatus === 'PENDING' ? 'warning' : '',
+          progress:
+            displayFinancialStatus === 'PENDING' ? 'incomplete' : 'complete',
+        },
+      ],
+    };
+  }),
+});

package/src/surfaces/admin/api/picker/examples/disabled.js

@@ -0,0 +1,16 @@
+const pickerInstance = await picker({
+  heading: 'Disabled items',
+  items: [
+    {
+      id: '1',
+      heading: 'Item 1',
+      disabled: true,
+    },
+    {
+      id: '2',
+      heading: 'Item 2',
+    },
+  ],
+});
+
+const selected = await pickerInstance.selected;

package/src/surfaces/admin/api/picker/examples/minimal.js

@@ -0,0 +1,16 @@
+const pickerInstance = await picker({
+  heading: 'Select an item',
+  headers: [{title: 'Main heading'}],
+  items: [
+    {
+      id: '1',
+      heading: 'Item 1',
+    },
+    {
+      id: '2',
+      heading: 'Item 2',
+    },
+  ],
+});
+
+const selected = await pickerInstance.selected;

package/src/surfaces/admin/api/picker/examples/multiple-limit.js

@@ -0,0 +1,21 @@
+const pickerInstance = await picker({
+  heading: 'Select items (up to 2)',
+  multiple: 2,
+  headers: [{title: 'Main heading'}],
+  items: [
+    {
+      id: '1',
+      heading: 'Item 1',
+    },
+    {
+      id: '2',
+      heading: 'Item 2',
+    },
+    {
+      id: '3',
+      heading: 'Item 3',
+    },
+  ],
+});
+
+const selected = await pickerInstance.selected;

package/src/surfaces/admin/api/picker/examples/multiple-true.js

@@ -0,0 +1,21 @@
+const pickerInstance = await picker({
+  heading: 'Select items',
+  multiple: true,
+  headers: [{title: 'Main heading'}],
+  items: [
+    {
+      id: '1',
+      heading: 'Item 1',
+    },
+    {
+      id: '2',
+      heading: 'Item 2',
+    },
+    {
+      id: '3',
+      heading: 'Item 3',
+    },
+  ],
+});
+
+const selected = await pickerInstance.selected;

package/src/surfaces/admin/api/picker/examples/preselected.js

@@ -0,0 +1,16 @@
+const pickerInstance = await picker({
+  heading: 'Preselected items',
+  items: [
+    {
+      id: '1',
+      heading: 'Item 1',
+      selected: true,
+    },
+    {
+      id: '2',
+      heading: 'Item 2',
+    },
+  ],
+});
+
+const selected = await pickerInstance.selected;

package/src/surfaces/admin/api/picker/examples/template-picker.js

@@ -0,0 +1,37 @@
+const {picker} = useApi(TARGET);
+
+const pickerInstance = await picker({
+  heading: 'Select a template',
+  multiple: false,
+  headers: [
+    {title: 'Templates'},
+    {title: 'Created by'},
+    {title: 'Times used', type: 'number'},
+  ],
+  items: [
+    {
+      id: '1',
+      heading: 'Full width, 1 column',
+      data: ['Karine Ruby', '0'],
+      badges: [{content: 'Draft', tone: 'info'}, {content: 'Marketing'}],
+    },
+    {
+      id: '2',
+      heading: 'Large graphic, 3 column',
+      data: ['Russell Winfield', '5'],
+      badges: [
+        {content: 'Published', tone: 'success'},
+        {content: 'New feature'},
+      ],
+      selected: true,
+    },
+    {
+      id: '3',
+      heading: 'Promo header, 2 column',
+      data: ['Russel Winfield', '10'],
+      badges: [{content: 'Published', tone: 'success'}],
+    },
+  ],
+});
+
+const selected = await pickerInstance.selected;

package/src/surfaces/admin/api/picker/picker.doc.ts

@@ -0,0 +1,113 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'Picker',
+  overviewPreviewDescription: 'Opens a Picker in your app',
+  description: `The Picker API provides a search-based interface to help users find and select one or more resources that you provide, such as product reviews, email templates, or subscription options, and then returns the selected resource ids to your extension.
+
+> Tip:
+> If you are picking products, product variants, or collections, you should use the [Resource Picker](resource-picker) API instead.`,
+  isVisualComponent: true,
+  category: 'API',
+  thumbnail: 'picker.png',
+  requires:
+    'an Admin [block](/docs/api/admin-extensions/unstable/extension-targets#block-locations), [action](/docs/api/admin-extensions/unstable/extension-targets#action-locations), or [print](/docs/api/admin-extensions/unstable/extension-targets#print-locations) extension.',
+  defaultExample: {
+    image: 'picker.png',
+    codeblock: {
+      title: 'Picker',
+      tabs: [
+        {
+          code: './examples/template-picker.js',
+          language: 'js',
+        },
+      ],
+    },
+  },
+  definitions: [
+    {
+      title: 'picker',
+      description: `The \`picker\` API is a function that accepts an options argument for configuration and returns a Promise that resolves to the picker instance once the picker modal is opened.`,
+      type: 'PickerApi',
+    },
+  ],
+  examples: {
+    description: 'Pickers with different options',
+    examples: [
+      {
+        description:
+          "Minimal required fields picker configuration.\n\nIf you don't provide the required options (`heading` and `items`), the picker will not open and an error will be logged.",
+        codeblock: {
+          title: 'Simple picker',
+          tabs: [
+            {
+              code: './examples/minimal.js',
+              language: 'js',
+            },
+          ],
+        },
+      },
+      {
+        description:
+          'Setting a specific number of selectable items. In this example, the user can select up to 2 items.',
+        codeblock: {
+          title: 'Limited selectable items',
+          tabs: [
+            {
+              code: './examples/multiple-limit.js',
+              language: 'js',
+            },
+          ],
+        },
+      },
+      {
+        description: 'Setting an unlimited number of selectable items.',
+        codeblock: {
+          title: 'Unlimited selectable items',
+          tabs: [
+            {
+              code: './examples/multiple-true.js',
+              language: 'js',
+            },
+          ],
+        },
+      },
+      {
+        description:
+          'Providing preselected items in the picker. These will be selected when the picker opens but can be deselected by the user.',
+        codeblock: {
+          title: 'Preselected items',
+          tabs: [
+            {
+              code: './examples/preselected.js',
+              language: 'js',
+            },
+          ],
+        },
+      },
+      {
+        description:
+          'Providing disabled items in the picker. These will be disabled and cannot be selected by the user.',
+        codeblock: {
+          title: 'Disabled items',
+          tabs: [
+            {
+              code: './examples/disabled.js',
+              language: 'js',
+            },
+          ],
+        },
+      },
+    ],
+  },
+  related: [
+    {
+      name: 'Resource Picker',
+      subtitle: 'APIs',
+      url: 'resource-picker',
+      type: 'pickaxe-3',
+    },
+  ],
+};
+
+export default data;