@shopify/ui-extensions 2024.4.2 → 2024.10.0

package/package.json

@@ -1,10 +1,12 @@
 {
   "name": "@shopify/ui-extensions",
-  "version": "2024.4.2",
+  "version": "2024.10.0",
   "scripts": {
-    "docs:admin": "sh ./docs/surfaces/admin/build-docs.sh",
-    "gen-docs:admin": "sh ./docs/surfaces/admin/create-doc-files.sh \"admin\"",
-    "docs:checkout": "sh ./docs/surfaces/checkout/build-docs.sh"
+    "docs:admin": "bash ./docs/surfaces/admin/build-docs.sh",
+    "gen-docs:admin": "bash ./docs/surfaces/admin/create-doc-files.sh \"admin\"",
+    "docs:checkout": "bash ./docs/surfaces/checkout/build-docs.sh",
+    "docs:point-of-sale": "bash ./docs/surfaces/point-of-sale/build-docs.sh",
+    "docs:customer-account": "bash ./docs/surfaces/customer-account/build-docs.sh"
   },
   "main": "index.js",
   "module": "index.mjs",
@@ -65,7 +67,7 @@
     "@remote-ui/core": "^2.2.4"
   },
   "devDependencies": {
-    "@shopify/generate-docs": "0.10.13",
+    "@shopify/generate-docs": "0.16.4",
     "typescript": "^4.9.0"
   },
   "publishConfig": {

package/src/shared.ts

@@ -21,8 +21,34 @@ export type ApiVersion =
   | '2023-10'
   | '2024-01'
   | '2024-04'
+  | '2024-07'
+  | '2024-10'
   | 'unstable';
 
+/**
+ * The capabilities an extension has access to.
+ *
+ * * [`api_access`](https://shopify.dev/docs/api/checkout-ui-extensions/configuration#api-access): the extension can access the Storefront API.
+ *
+ * * [`network_access`](https://shopify.dev/docs/api/checkout-ui-extensions/configuration#network-access): the extension can make external network calls.
+ *
+ * * [`block_progress`](https://shopify.dev/docs/api/checkout-ui-extensions/configuration#block-progress): the extension can block a buyer's progress and the merchant has allowed this blocking behavior.
+ *
+ * * [`collect_buyer_consent.sms_marketing`](https://shopify.dev/docs/api/checkout-ui-extensions/configuration#collect-buyer-consent): the extension can collect buyer consent for SMS marketing.
+ *
+ * * [`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.
+ */
+
+export type Capability =
+  | 'api_access'
+  | 'network_access'
+  | 'block_progress'
+  | 'collect_buyer_consent.sms_marketing'
+  | 'collect_buyer_consent.customer_privacy'
+  | 'iframe.sources';
+
 // To update these type values, see https://github.com/Shopify/checkout-web/pull/8984
 export type CurrencyCode =
   | 'AED'
@@ -844,6 +870,8 @@ export type StorefrontApiVersion =
   | '2023-07'
   | '2024-01'
   | '2024-04'
+  | '2024-07'
+  | '2024-10'
   | 'unstable';
 
 /**

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

@@ -1,6 +1,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';
 
 export interface Navigation {
   /**
@@ -23,4 +24,9 @@ export interface BlockExtensionApi<ExtensionTarget extends AnyExtensionTarget>
    * 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;
+
+  /**
+   * 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.
+   */
+  resourcePicker: ResourcePickerApi;
 }

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

@@ -43,7 +43,7 @@ const supportedDefinitionTypes = [
   'list.weight',
 ] as const;
 
-export type SupportedDefinitionType = typeof supportedDefinitionTypes[number];
+export type SupportedDefinitionType = (typeof supportedDefinitionTypes)[number];
 
 interface MetafieldUpdateChange {
   type: 'updateMetafield';

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

@@ -3,7 +3,7 @@ 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.',
+    'This API is available to 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: [

package/src/surfaces/admin/api/order-routing-rule/metafields.ts

@@ -63,5 +63,5 @@ type MetafieldsChange =
   | MetafieldUpdateChange[]
   | MetafieldRemoveChange[];
 
-export type SupportedDefinitionType = typeof supportedDefinitionTypes[number];
+export type SupportedDefinitionType = (typeof supportedDefinitionTypes)[number];
 export type ApplyMetafieldsChange = (changes: MetafieldsChange[]) => void;

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

@@ -0,0 +1,20 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'Print Action Extension API',
+  description:
+    'This API is available to all print action extension types. Note that the [`AdminPrintAction`](/docs/api/admin-extensions/components/other/adminprintaction) component is required to build admin print action extensions.',
+  isVisualComponent: false,
+  type: 'API',
+  definitions: [
+    {
+      title: 'PrintActionExtensionApi',
+      description: '',
+      type: 'PrintActionExtensionApi',
+    },
+  ],
+  category: 'API',
+  related: [],
+};
+
+export default data;

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

@@ -0,0 +1,12 @@
+import type {StandardApi} from '../standard/standard';
+import type {ExtensionTarget as AnyExtensionTarget} from '../../extension-targets';
+import type {Data} from '../shared';
+
+export interface PrintActionExtensionApi<
+  ExtensionTarget extends AnyExtensionTarget,
+> extends StandardApi<ExtensionTarget> {
+  /**
+   * Information about the currently viewed or selected items.
+   */
+  data: Data;
+}

package/src/surfaces/admin/api/resource-picker/resource-picker.ts

@@ -0,0 +1,240 @@
+type Money = string;
+
+enum CollectionSortOrder {
+  Manual = 'MANUAL',
+  BestSelling = 'BEST_SELLING',
+  AlphaAsc = 'ALPHA_ASC',
+  AlphaDesc = 'ALPHA_DESC',
+  PriceDesc = 'PRICE_DESC',
+  PriceAsc = 'PRICE_ASC',
+  CreatedDesc = 'CREATED_DESC',
+  Created = 'CREATED',
+  MostRelevant = 'MOST_RELEVANT',
+}
+
+enum FulfillmentServiceType {
+  GiftCard = 'GIFT_CARD',
+  Manual = 'MANUAL',
+  ThirdParty = 'THIRD_PARTY',
+}
+
+enum WeightUnit {
+  Kilograms = 'KILOGRAMS',
+  Grams = 'GRAMS',
+  Pounds = 'POUNDS',
+  Ounces = 'OUNCES',
+}
+
+enum ProductVariantInventoryPolicy {
+  Deny = 'DENY',
+  Continue = 'CONTINUE',
+}
+
+enum ProductVariantInventoryManagement {
+  Shopify = 'SHOPIFY',
+  NotManaged = 'NOT_MANAGED',
+  FulfillmentService = 'FULFILLMENT_SERVICE',
+}
+
+enum ProductStatus {
+  Active = 'ACTIVE',
+  Archived = 'ARCHIVED',
+  Draft = 'DRAFT',
+}
+
+interface Image {
+  id: string;
+  altText?: string;
+  originalSrc: string;
+}
+
+interface Resource {
+  /** in GraphQL id format, ie 'gid://shopify/Product/1' */
+  id: string;
+}
+
+interface BaseResource extends Resource {
+  variants?: Resource[];
+}
+
+interface CollectionRule {
+  column: string;
+  condition: string;
+  relation: string;
+}
+
+interface RuleSet {
+  appliedDisjunctively: boolean;
+  rules: CollectionRule[];
+}
+
+interface Collection extends Resource {
+  availablePublicationCount: number;
+  description: string;
+  descriptionHtml: string;
+  handle: string;
+  id: string;
+  image?: Image | null;
+  productsAutomaticallySortedCount: number;
+  productsCount: number;
+  productsManuallySortedCount: number;
+  publicationCount: number;
+  ruleSet?: RuleSet | null;
+  seo: {
+    description?: string | null;
+    title?: string | null;
+  };
+  sortOrder: CollectionSortOrder;
+  storefrontId: string;
+  templateSuffix?: string | null;
+  title: string;
+  updatedAt: string;
+}
+
+interface ProductVariant extends Resource {
+  availableForSale: boolean;
+  barcode?: string | null;
+  compareAtPrice?: Money | null;
+  createdAt: string;
+  displayName: string;
+  fulfillmentService?: {
+    id: string;
+    inventoryManagement: boolean;
+    productBased: boolean;
+    serviceName: string;
+    type: FulfillmentServiceType;
+  };
+  image?: Image | null;
+  inventoryItem: {id: string};
+  inventoryManagement: ProductVariantInventoryManagement;
+  inventoryPolicy: ProductVariantInventoryPolicy;
+  inventoryQuantity?: number | null;
+  position: number;
+  price: Money;
+  product: Partial<Product>;
+  requiresShipping: boolean;
+  selectedOptions: {value?: string | null}[];
+  sku?: string | null;
+  taxable: boolean;
+  title: string;
+  weight?: number | null;
+  weightUnit: WeightUnit;
+  updatedAt: string;
+}
+
+interface Product extends Resource {
+  availablePublicationCount: number;
+  createdAt: string;
+  descriptionHtml: string;
+  handle: string;
+  hasOnlyDefaultVariant: boolean;
+  images: Image[];
+  options: {
+    id: string;
+    name: string;
+    position: number;
+    values: string[];
+  }[];
+  productType: string;
+  publishedAt?: string | null;
+  tags: string[];
+  templateSuffix?: string | null;
+  title: string;
+  totalInventory: number;
+  totalVariants: number;
+  tracksInventory: boolean;
+  variants: Partial<ProductVariant>[];
+  vendor: string;
+  updatedAt: string;
+  status: ProductStatus;
+}
+
+interface ResourceTypes {
+  product: Product;
+  variant: ProductVariant;
+  collection: Collection;
+}
+
+type ResourceSelection<Type extends keyof ResourceTypes> = ResourceTypes[Type];
+
+type WithSelection<T> = T & {
+  /**
+   * @private
+   * @deprecated
+   */
+  selection: T;
+};
+
+type SelectPayload<Type extends keyof ResourceTypes> = WithSelection<
+  ResourceSelection<Type>[]
+>;
+
+interface Filters {
+  /**
+   * Whether to show hidden resources, referring to products that are not published on any sales channels.
+   * @defaultValue true
+   */
+  hidden?: boolean;
+  /**
+   * Whether to show product variants. Only applies to the Product resource type picker.
+   * @defaultValue true
+   */
+  variants?: boolean;
+  /**
+   * Whether to show [draft products](https://help.shopify.com/en/manual/products/details?shpxid=70af7d87-E0F2-4973-8B09-B972AAF0ADFD#product-availability).
+   * Only applies to the Product resource type picker.
+   * Setting this to undefined will show a badge on draft products.
+   * @defaultValue true
+   */
+  draft?: boolean | undefined;
+  /**
+   * Whether to show [archived products](https://help.shopify.com/en/manual/products/details?shpxid=70af7d87-E0F2-4973-8B09-B972AAF0ADFD#product-availability).
+   * Only applies to the Product resource type picker.
+   * Setting this to undefined will show a badge on draft products.
+   * @defaultValue true
+   */
+  archived?: boolean | undefined;
+  /**
+   * GraphQL initial search query for filtering resources available in the picker.
+   * See [search syntax](https://shopify.dev/docs/api/usage/search-syntax) for more information.
+   * This is not displayed in the search bar when the picker is opened.
+   */
+  query?: string;
+}
+
+export interface ResourcePickerOptions {
+  /**
+   * The type of resource you want to pick.
+   */
+  type: 'product' | 'variant' | 'collection';
+  /**
+   *  The action verb appears in the title and as the primary action of the Resource Picker.
+   * @defaultValue 'add'
+   */
+  action?: 'add' | 'select';
+  /**
+   * Filters for what resource to show.
+   */
+  filter?: Filters;
+  /**
+   * Whether to allow selecting multiple items of a specific type or not. If a number is provided, then limit the selections to a maximum of that number of items. When type is Product, the user may still select multiple variants of a single product, even if multiple is false.
+   * @defaultValue false
+   */
+  multiple?: boolean | number;
+  /**
+   * GraphQL initial search query for filtering resources available in the picker. See [search syntax](https://shopify.dev/docs/api/usage/search-syntax) for more information.
+   * This is displayed in the search bar when the picker is opened and can be edited by users.
+   * For most use cases, you should use the `filter.query` option instead which doesn't show the query in the UI.
+   * @defaultValue ''
+   */
+  query?: string;
+  /**
+   * Resources that should be preselected when the picker is opened.
+   * @defaultValue []
+   */
+  selectionIds?: BaseResource[];
+}
+
+export type ResourcePickerApi = (
+  options: ResourcePickerOptions,
+) => Promise<SelectPayload<ResourcePickerOptions['type']> | undefined>;

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

@@ -20,6 +20,13 @@ export interface GraphQLError {
   };
 }
 
+interface Auth {
+  /**
+   * Retrieves a Shopify OpenID Connect ID token for the current user.
+   */
+  idToken: () => Promise<string | null>;
+}
+
 /**
  * The following APIs are provided to all extension targets.
  */
@@ -31,6 +38,11 @@ export interface StandardApi<ExtensionTarget extends AnyExtensionTarget> {
     target: ExtensionTarget;
   };
 
+  /**
+   * Provides methods for authenticating calls to an app backend.
+   */
+  auth: Auth;
+
   /**
    * Utilities for translating content according to the current localization of the admin.
    * More info - https://shopify.dev/docs/apps/checkout/best-practices/localizing-ui-extensions

package/src/surfaces/admin/api.ts

@@ -4,6 +4,7 @@ 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 {PrintActionExtensionApi} from './api/print-action/print-action';
 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';

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

@@ -0,0 +1,52 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'AdminPrintAction',
+  description:
+    'AdminPrintAction is a component used by admin print action extensions to denote a URL to print. Admin print action extensions require the use of this component.',
+  requires: '',
+  thumbnail: 'adminprintaction-thumbnail.png',
+  isVisualComponent: true,
+  type: '',
+  definitions: [
+    {
+      title: 'AdminPrintActionProps',
+      description: '',
+      type: 'AdminPrintActionProps',
+    },
+  ],
+  category: 'Components',
+  subCategory: 'Other',
+  defaultExample: {
+    image: 'adminprintaction-default.png',
+    codeblock: {
+      title: 'Set the source URL of the print action extension.',
+      tabs: [
+        {
+          title: 'React',
+          code: '../../../../../../ui-extensions-react/src/surfaces/admin/components/AdminPrintAction/examples/basic-adminprintaction.example.tsx',
+          language: 'tsx',
+        },
+        {
+          title: 'JS',
+          code: './examples/basic-adminprintaction.example.ts',
+          language: 'js',
+        },
+      ],
+    },
+  },
+  related: [
+    {
+      type: 'component',
+      name: 'AdminAction',
+      url: '/docs/api/admin-extensions/components/other/adminaction',
+    },
+    {
+      type: 'component',
+      name: 'AdminBlock',
+      url: '/docs/api/admin-extensions/components/other/adminblock',
+    },
+  ],
+};
+
+export default data;

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

@@ -0,0 +1,18 @@
+import {createRemoteComponent} from '@remote-ui/core';
+
+export interface AdminPrintActionProps {
+  /**
+   * Sets the src URL of the preview and the document to print.
+   * If not provided, the preview will show an empty state and the print button will be disabled.
+   * HTML, PDFs and images are supported.
+   */
+  src?: string;
+}
+
+/**
+ * AdminPrintAction is a component used by Admin Print Action extensions to configure a src document to preview and print.
+ */
+export const AdminPrintAction = createRemoteComponent<
+  'AdminPrintAction',
+  AdminPrintActionProps
+>('AdminPrintAction');

package/src/surfaces/admin/components/AdminPrintAction/examples/basic-adminprintaction.example.ts

@@ -0,0 +1,14 @@
+import {extension, AdminPrintAction, Text} from '@shopify/ui-extensions/admin';
+
+export default extension('Playground', (root) => {
+  const adminPrintAction = root.createComponent(
+    AdminPrintAction,
+    {
+      src: 'https://example.com',
+    },
+    root.createComponent(Text, {fontWeight: 'bold'}, 'Modal content'),
+  );
+
+  root.append(adminPrintAction);
+  root.mount();
+});

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

@@ -4,10 +4,12 @@ import type {
   PaddingProps,
   SizingProps,
 } from '../shared';
+import {DisplayProps} from '../shared/display';
 
 export interface BoxProps
   extends AccessibilityRoleProps,
     SizingProps,
-    PaddingProps {}
+    PaddingProps,
+    DisplayProps {}
 
 export const Box = createRemoteComponent<'Box', BoxProps>('Box');

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

@@ -4,6 +4,14 @@ import type {AccessibilityRole, AnchorProps} from '../shared';
 export type ButtonProps = ButtonBaseProps | ButtonAnchorProps;
 
 interface CommonProps {
+  /**
+   * A label that describes the purpose or contents of the Button. It will be read to users using assistive technologies such as screen readers.
+   *
+   * Use this when using only an icon or the button text is not enough context
+   * for users using assistive technologies.
+   */
+  accessibilityLabel?: string;
+
   /**
    * A unique identifier for the button.
    */

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

@@ -96,7 +96,7 @@ interface ImageAltProp {
 
 interface ImageSrcProp {
   /**
-   * The image source (either a remote URL or a local file resource).
+   * The image source (either a remote URL or a local file resource; blob URLs are not currently supported).
    *
    * This property is available as an alias for `source` for compatibility with the HTML
    * specification. When both are specified, `source` takes precedence.
@@ -109,7 +109,7 @@ interface ImageSrcProp {
 
 interface ImageSourceProp {
   /**
-   * The image source (either a remote URL or a local file resource).
+   * The image source (either a remote URL or a local file resource; blob URLs are not currently supported).
    *
    * A `src` property is available as an alias for this for compatibility with the HTML
    * specification. When both are specified, `source` takes precedence.