@shopify/ui-extensions 2024.1.0 → 2024.4.0

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

@@ -3,7 +3,7 @@ import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
 const data: ReferenceEntityTemplateSchema = {
   name: 'Action Extension API',
   description:
-    'This API is available to all action extension types. Refer to the [tutorial](/docs/apps/admin/admin-actions-and-blocks/build-an-admin-action) for more information.',
+    'This API is available to all action extension types. Refer to the [tutorial](/docs/apps/admin/admin-actions-and-blocks/build-an-admin-action) for more information. Note that the [`AdminAction`](/docs/api/admin-extensions/components/other/adminaction) component is required to build Admin action extensions.',
   isVisualComponent: false,
   type: 'API',
   definitions: [

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

@@ -2,10 +2,25 @@ import type {StandardApi} from '../standard/standard';
 import type {ExtensionTarget as AnyExtensionTarget} from '../../extension-targets';
 import type {Data} from '../shared';
 
+export interface Navigation {
+  /**
+   * Navigate to a specific route.
+   *
+   * @example navigation.navigate('extension://my-admin-action-extension-handle')
+   */
+  navigate: (url: string | URL) => void;
+}
+
 export interface BlockExtensionApi<ExtensionTarget extends AnyExtensionTarget>
   extends StandardApi<ExtensionTarget> {
   /**
    * Information about the currently viewed or selected items.
    */
   data: Data;
+
+  /**
+   * Provides methods to navigate to other features in the Admin. Currently, only navigation from an admin block to an admin action extension *on the same resource page* is supported.
+   * For example, you can navigate from an admin block on the product details page (`admin.product-details.block.render`) to an admin action on the product details page (`admin.product-details.action.render`).
+   */
+  navigation: Navigation;
 }

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

@@ -0,0 +1,34 @@
+interface Metafield {
+  description?: string;
+  id: string;
+  namespace: string;
+  key: string;
+  value: string;
+  type: string;
+}
+
+interface Validation {
+  /**
+   * the validation's gid when active in a shop
+   */
+  id: string;
+  /**
+   * the metafields owned by the validation
+   */
+  metafields: Metafield[];
+}
+
+interface ShopifyFunction {
+  /**
+   * the validation function's unique identifier
+   */
+  id: string;
+}
+
+/**
+ * The object that exposes the validation with its settings.
+ */
+export interface ValidationData {
+  validation?: Validation;
+  shopifyFunction: ShopifyFunction;
+}

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

@@ -0,0 +1,76 @@
+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];
+
+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/checkout-rules/validation-settings.doc.ts

@@ -0,0 +1,25 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'Validation Settings API',
+  description:
+    'This API is available Validation Settings extensions. Refer to the [tutorial](/docs/apps/checkout/validation/create-complex-validation-rules) for more information. Note that the [`FunctionSettings`](/docs/api/admin-extensions/components/forms/functionsettings) component is required to build Validation Settings extensions.',
+  isVisualComponent: false,
+  type: 'API',
+  definitions: [
+    {
+      title: 'applyMetafieldChange',
+      description: 'Applies a change to the validation settings.',
+      type: 'ApplyMetafieldChange',
+    },
+    {
+      title: 'data',
+      description: 'The object that exposes the validation with its settings.',
+      type: 'ValidationData',
+    },
+  ],
+  category: 'API',
+  related: [],
+};
+
+export default data;

package/src/surfaces/admin/api/checkout-rules/validation-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 {ValidationData} from './launch-options';
+
+export interface ValidationSettingsApi<
+  ExtensionTarget extends AnyExtensionTarget,
+> extends StandardApi<ExtensionTarget> {
+  /**
+   * Applies a change to the validation settings.
+   */
+  applyMetafieldChange: ApplyMetafieldChange;
+  data: ValidationData;
+}

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

@@ -9,13 +9,6 @@ export interface Intents {
   launchUrl?: string | URL;
 }
 
-export interface Navigation {
-  /**
-   * A method to navigate to a specific route.
-   */
-  navigate: (url: string | URL) => void;
-}
-
 /**
  * GraphQL error returned by the Shopify Admin API.
  */
@@ -49,11 +42,6 @@ export interface StandardApi<ExtensionTarget extends AnyExtensionTarget> {
    */
   intents: Intents;
 
-  /**
-   * Provides methods to navigate to other features in the Admin.
-   */
-  navigation: Navigation;
-
   /**
    * Used to query the Admin GraphQL API
    */

package/src/surfaces/admin/api.ts

@@ -1,8 +1,10 @@
 export type {I18n, I18nTranslate} from '../../api';
-export type {StandardApi, Navigation, Intents} from './api/standard/standard';
+export type {StandardApi, Intents} from './api/standard/standard';
+export type {Navigation} from './api/block/block';
 export type {CustomerSegmentTemplateApi} from './api/customer-segment-template/customer-segment-template';
 export type {ActionExtensionApi} from './api/action/action';
 export type {BlockExtensionApi} from './api/block/block';
 export type {ProductDetailsConfigurationApi} from './api/product-configuration/product-details-configuration';
 export type {ProductVariantDetailsConfigurationApi} from './api/product-configuration/product-variant-details-configuration';
 export type {OrderRoutingRuleApi} from './api/order-routing-rule/order-routing-rule';
+export type {ValidationSettingsApi} from './api/checkout-rules/validation-settings';

package/src/surfaces/admin/components/AdminAction/AdminAction.doc.ts

@@ -3,7 +3,7 @@ import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
 const data: ReferenceEntityTemplateSchema = {
   name: 'AdminAction',
   description:
-    'AdminAction is a component used by Admin Action extensions to configure a primary and secondary action and title.',
+    'AdminAction is a component used by Admin action extensions to configure a primary and secondary action and title. Use of this component is required in order to use Admin action extensions.',
   requires: '',
   thumbnail: 'adminaction-thumbnail.png',
   isVisualComponent: true,

package/src/surfaces/admin/components/Badge/Badge.doc.ts

@@ -24,12 +24,12 @@ const data: ReferenceEntityTemplateSchema = {
       tabs: [
         {
           title: 'React',
-          code: '../../../../../../ui-extensions-react/src/surfaces/admin/components/Badge/examples/basic-Badge.example.tsx',
+          code: '../../../../../../ui-extensions-react/src/surfaces/admin/components/Badge/examples/basic-badge.example.tsx',
           language: 'tsx',
         },
         {
           title: 'JS',
-          code: './examples/basic-Badge.example.ts',
+          code: './examples/basic-badge.example.ts',
           language: 'js',
         },
       ],

package/src/surfaces/admin/components/Banner/Banner.doc.ts

@@ -24,12 +24,12 @@ const data: ReferenceEntityTemplateSchema = {
       tabs: [
         {
           title: 'React',
-          code: '../../../../../../ui-extensions-react/src/surfaces/admin/components/Banner/examples/basic-Banner.example.tsx',
+          code: '../../../../../../ui-extensions-react/src/surfaces/admin/components/Banner/examples/basic-banner.example.tsx',
           language: 'tsx',
         },
         {
           title: 'JS',
-          code: './examples/basic-Banner.example.ts',
+          code: './examples/basic-banner.example.ts',
           language: 'js',
         },
       ],

package/src/surfaces/admin/components/BlockStack/BlockStack.doc.ts

@@ -24,12 +24,12 @@ const data: ReferenceEntityTemplateSchema = {
       tabs: [
         {
           title: 'React',
-          code: '../../../../../../ui-extensions-react/src/surfaces/admin/components/BlockStack/examples/basic-BlockStack.example.tsx',
+          code: '../../../../../../ui-extensions-react/src/surfaces/admin/components/BlockStack/examples/basic-blockstack.example.tsx',
           language: 'tsx',
         },
         {
           title: 'JS',
-          code: './examples/basic-BlockStack.example.ts',
+          code: './examples/basic-blockstack.example.ts',
           language: 'js',
         },
       ],

package/src/surfaces/admin/components/Box/Box.doc.ts

@@ -24,12 +24,12 @@ const data: ReferenceEntityTemplateSchema = {
       tabs: [
         {
           title: 'React',
-          code: '../../../../../../ui-extensions-react/src/surfaces/admin/components/Box/examples/basic-Box.example.tsx',
+          code: '../../../../../../ui-extensions-react/src/surfaces/admin/components/Box/examples/basic-box.example.tsx',
           language: 'tsx',
         },
         {
           title: 'JS',
-          code: './examples/basic-Box.example.ts',
+          code: './examples/basic-box.example.ts',
           language: 'js',
         },
       ],

package/src/surfaces/admin/components/Button/Button.doc.ts

@@ -24,12 +24,12 @@ const data: ReferenceEntityTemplateSchema = {
       tabs: [
         {
           title: 'React',
-          code: '../../../../../../ui-extensions-react/src/surfaces/admin/components/Button/examples/basic-Button.example.tsx',
+          code: '../../../../../../ui-extensions-react/src/surfaces/admin/components/Button/examples/basic-button.example.tsx',
           language: 'tsx',
         },
         {
           title: 'JS',
-          code: './examples/basic-Button.example.ts',
+          code: './examples/basic-button.example.ts',
           language: 'js',
         },
       ],

package/src/surfaces/admin/components/Checkbox/Checkbox.doc.ts

@@ -24,12 +24,12 @@ const data: ReferenceEntityTemplateSchema = {
       tabs: [
         {
           title: 'React',
-          code: '../../../../../../ui-extensions-react/src/surfaces/admin/components/Checkbox/examples/basic-Checkbox.example.tsx',
+          code: '../../../../../../ui-extensions-react/src/surfaces/admin/components/Checkbox/examples/basic-checkbox.example.tsx',
           language: 'tsx',
         },
         {
           title: 'JS',
-          code: './examples/basic-Checkbox.example.ts',
+          code: './examples/basic-checkbox.example.ts',
           language: 'js',
         },
       ],

package/src/surfaces/admin/components/ChoiceList/ChoiceList.doc.ts

@@ -24,12 +24,12 @@ const data: ReferenceEntityTemplateSchema = {
       tabs: [
         {
           title: 'React',
-          code: '../../../../../../ui-extensions-react/src/surfaces/admin/components/ChoiceList/examples/basic-ChoiceList.example.tsx',
+          code: '../../../../../../ui-extensions-react/src/surfaces/admin/components/ChoiceList/examples/basic-choicelist.example.tsx',
           language: 'tsx',
         },
         {
           title: 'JS',
-          code: './examples/basic-ChoiceList.example.ts',
+          code: './examples/basic-choicelist.example.ts',
           language: 'js',
         },
       ],

package/src/surfaces/admin/components/ColorPicker/ColorPicker.doc.ts

@@ -23,12 +23,12 @@ const data: ReferenceEntityTemplateSchema = {
       tabs: [
         {
           title: 'React',
-          code: '../../../../../../ui-extensions-react/src/surfaces/admin/components/ColorPicker/examples/basic-ColorPicker.example.tsx',
+          code: '../../../../../../ui-extensions-react/src/surfaces/admin/components/ColorPicker/examples/basic-colorpicker.example.tsx',
           language: 'tsx',
         },
         {
           title: 'JS',
-          code: './examples/basic-ColorPicker.example.ts',
+          code: './examples/basic-colorpicker.example.ts',
           language: 'js',
         },
       ],

package/src/surfaces/admin/components/CustomerSegmentTemplate/CustomerSegmentTemplate.doc.ts

@@ -25,12 +25,12 @@ const data: ReferenceEntityTemplateSchema = {
       tabs: [
         {
           title: 'React',
-          code: './examples/CustomerSegmentTemplate.example.tsx',
+          code: '../../../../../../ui-extensions-react/src/surfaces/admin/components/CustomerSegmentTemplate/examples/customersegmenttemplate.example.tsx',
           language: 'tsx',
         },
         {
           title: 'JS',
-          code: './examples/CustomerSegmentTemplate.example.ts',
+          code: './examples/customersegmenttemplate.example.ts',
           language: 'js',
         },
       ],

package/src/surfaces/admin/components/DateField/DateField.doc.ts

@@ -3,7 +3,7 @@ import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
 const data: ReferenceEntityTemplateSchema = {
   name: 'DateField',
   description:
-    'This is a form field that lets merchants select a date. It uses the DatePicker component to let merchants to pick the date.',
+    'This is a form field that lets users select a date using the DatePicker component.',
   requires: '',
   thumbnail: 'datefield-thumbnail.png',
   isVisualComponent: true,
@@ -39,7 +39,7 @@ const data: ReferenceEntityTemplateSchema = {
     description: '',
     examples: [
       {
-        description: 'Use this when merchants need to select multiple dates.',
+        description: 'Use this when users need to select multiple dates.',
         codeblock: {
           title: 'Add a multi-date DateField',
           tabs: [
@@ -57,7 +57,7 @@ const data: ReferenceEntityTemplateSchema = {
         },
       },
       {
-        description: 'Use this when merchants need to select a range of dates.',
+        description: 'Use this when users need to select a range of dates.',
         codeblock: {
           title: 'Add a range DateField',
           tabs: [

package/src/surfaces/admin/components/Divider/Divider.doc.ts

@@ -24,12 +24,12 @@ const data: ReferenceEntityTemplateSchema = {
       tabs: [
         {
           title: 'React',
-          code: '../../../../../../ui-extensions-react/src/surfaces/admin/components/Divider/examples/basic-Divider.example.tsx',
+          code: '../../../../../../ui-extensions-react/src/surfaces/admin/components/Divider/examples/basic-divider.example.tsx',
           language: 'tsx',
         },
         {
           title: 'JS',
-          code: './examples/basic-Divider.example.ts',
+          code: './examples/basic-divider.example.ts',
           language: 'js',
         },
       ],

package/src/surfaces/admin/components/EmailField/EmailField.doc.ts

@@ -23,12 +23,12 @@ const data: ReferenceEntityTemplateSchema = {
       tabs: [
         {
           title: 'React',
-          code: '../../../../../../ui-extensions-react/src/surfaces/admin/components/EmailField/examples/basic-EmailField.example.tsx',
+          code: '../../../../../../ui-extensions-react/src/surfaces/admin/components/EmailField/examples/basic-emailfield.example.tsx',
           language: 'tsx',
         },
         {
           title: 'JS',
-          code: './examples/basic-EmailField.example.ts',
+          code: './examples/basic-emailfield.example.ts',
           language: 'js',
         },
       ],

package/src/surfaces/admin/components/Form/Form.doc.ts

@@ -24,12 +24,12 @@ const data: ReferenceEntityTemplateSchema = {
       tabs: [
         {
           title: 'React',
-          code: '../../../../../../ui-extensions-react/src/surfaces/admin/components/Form/examples/basic-Form.example.tsx',
+          code: '../../../../../../ui-extensions-react/src/surfaces/admin/components/Form/examples/basic-form.example.tsx',
           language: 'tsx',
         },
         {
           title: 'JS',
-          code: './examples/basic-Form.example.ts',
+          code: './examples/basic-form.example.ts',
           language: 'js',
         },
       ],

package/src/surfaces/admin/components/FunctionSettings/FunctionSettings.doc.ts

@@ -0,0 +1,57 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'FunctionSettings',
+  description:
+    'FunctionSettings should be used when configuring the metafield configuration of a Shopify Function. It provides a structure for various input fields and controls, such as text fields, checkboxes, and selections. It also integrates with the native Contextual Save Bar to handle form submission and reset actions.',
+  requires: '',
+  thumbnail: 'form-thumbnail.png',
+  isVisualComponent: true,
+  type: '',
+  definitions: [
+    {
+      title: 'FunctionSettingsProps',
+      description: '',
+      type: 'FunctionSettingsProps',
+    },
+  ],
+  category: 'Components',
+  subCategory: 'Forms',
+  defaultExample: {
+    image: 'form-default.png',
+    codeblock: {
+      title: 'Simple function settings form implementation',
+      tabs: [
+        {
+          title: 'React',
+          code: '../../../../../../ui-extensions-react/src/surfaces/admin/components/FunctionSettings/examples/basic-functionsettings.example.tsx',
+          language: 'tsx',
+        },
+        {
+          title: 'JS',
+          code: './examples/basic-functionsettings.example.ts',
+          language: 'js',
+        },
+      ],
+    },
+  },
+  related: [
+    {
+      type: 'component',
+      name: 'TextField',
+      url: '/docs/api/admin-extensions/components/forms/textfield',
+    },
+    {
+      type: 'component',
+      name: 'NumberField',
+      url: '/docs/api/admin-extensions/components/forms/numberfield',
+    },
+    {
+      type: 'component',
+      name: 'ChoiceList',
+      url: '/docs/api/admin-extensions/components/forms/choicelist',
+    },
+  ],
+};
+
+export default data;

package/src/surfaces/admin/components/FunctionSettings/FunctionSettings.ts

@@ -0,0 +1,52 @@
+import {createRemoteComponent} from '@remote-ui/core';
+
+export interface FunctionSettingsProps {
+  /**
+   * A unique identifier for the form.
+   */
+  id?: string;
+
+  /**
+   * An optional callback function that will be run by the admin when the user
+   * commits their changes in the admin-rendered part of the function settings
+   * experience. If this function returns a promise, the admin will wait for the
+   * promise to resolve before committing any changes to Shopify’s servers. If
+   * the promise rejects, the admin will abort the changes and display an error,
+   * using the `message` property of the error you reject with.
+   */
+  onSave?(): void | Promise<void>;
+
+  /**
+   * An optional callback function that will be run by the admin when the
+   * committing the changes to Shopify’s servers fails. The errors you receive
+   * in the `errors` argument will only be those that were caused by data your
+   * extension provided; network errors and user errors that are out of your
+   * control will not be reported here.
+   *
+   * In the `onError` callback, you should update your extension’s UI to
+   * highlight the fields that caused the errors, and display the error messages
+   * to the user.
+   */
+  onError?(errors: FunctionSettingsError[]): void;
+}
+
+export interface FunctionSettingsError {
+  /**
+   * A unique identifier describing the “class” of error. These will match
+   * the GraphQL error codes as closely as possible. For example the enums
+   * returned by the `metafieldsSet` mutation
+   *
+   * @see https://shopify.dev/docs/api/admin-graphql/latest/enums/MetafieldsSetUserErrorCode
+   */
+  code: string;
+
+  /**
+   * A translated message describing the error.
+   */
+  message: string;
+}
+
+export const FunctionSettings = createRemoteComponent<
+  'FunctionSettings',
+  FunctionSettingsProps
+>('FunctionSettings');

package/src/surfaces/admin/components/FunctionSettings/examples/basic-functionsettings.example.ts

@@ -0,0 +1,47 @@
+import {
+  extension,
+  FunctionSettings,
+  TextField,
+  Section,
+} from '@shopify/ui-extensions/admin';
+
+export default extension(
+  'admin.settings.validation.render',
+  async (root, api) => {
+    // Use Direct API access to fetch initial
+    // metafields from the server if we are
+    // rendering against a pre-existing `Validation`
+    const initialSettings = api.data.validation
+      ? await fetchSettings(api.data.validation.id)
+      : {};
+
+    const textField = root.createComponent(TextField, {
+      value: initialSettings.name,
+      label: 'Name',
+      name: 'name',
+      onChange(value) {
+        textField.updateProps({value, error: undefined});
+        api.applyMetafieldsChange({
+          type: 'updateMetafield',
+          namespace: '$app:my_namespace',
+          key: 'name',
+          value,
+          valueType: 'single_line_text_field',
+        });
+      },
+    });
+
+    const section = root.createComponent(Section, {
+      heading: 'Settings',
+    });
+
+    const settings = root.createComponent(FunctionSettings, {
+      onError(errors) {
+        textField.updateProps({error: errors[0]?.message});
+      },
+    });
+
+    section.append(textField);
+    settings.append(section);
+  },
+);

package/src/surfaces/admin/components/Heading/Heading.doc.ts

@@ -24,12 +24,12 @@ const data: ReferenceEntityTemplateSchema = {
       tabs: [
         {
           title: 'React',
-          code: '../../../../../../ui-extensions-react/src/surfaces/admin/components/Heading/examples/basic-Heading.example.tsx',
+          code: '../../../../../../ui-extensions-react/src/surfaces/admin/components/Heading/examples/basic-heading.example.tsx',
           language: 'tsx',
         },
         {
           title: 'JS',
-          code: './examples/basic-Heading.example.ts',
+          code: './examples/basic-heading.example.ts',
           language: 'js',
         },
       ],

package/src/surfaces/admin/components/Heading/Heading.ts

@@ -6,7 +6,12 @@ export interface HeadingProps {
   /** A unique identifier for the field. */
   id?: string;
 
-  /** The visual level of the heading. */
+  /**
+   * The visual size of the heading.
+   *
+   * There are no guarantee that the level set will render the same level in the HTML `<h*>` element.
+   * The heading level that gets rendered is determined by the parent `HeadingGroup` or `Section` component.
+   */
   size?: Level;
 }