@shopify/ui-extensions 2022.10.5 → 2023.4.0

package/package.json

@@ -1,6 +1,10 @@
 {
   "name": "@shopify/ui-extensions",
-  "version": "2022.10.5",
+  "version": "2023.4.0",
+  "scripts": {
+    "docs:admin": "sh ./docs/surfaces/admin/build-docs.sh \"admin\"",
+    "docs:checkout": "sh ./docs/surfaces/checkout/build-docs.sh"
+  },
   "main": "index.js",
   "module": "index.mjs",
   "esnext": "index.esnext",
@@ -9,6 +13,9 @@
     "*": {
       "checkout": [
         "./build/ts/surfaces/checkout.d.ts"
+      ],
+      "admin": [
+        "./build/ts/surfaces/admin.d.ts"
       ]
     }
   },
@@ -21,9 +28,15 @@
     },
     "./checkout": {
       "types": "./build/ts/surfaces/checkout.d.ts",
-      "esnext": "./checkout.esnext",
-      "import": "./checkout.mjs",
-      "require": "./checkout.js"
+      "esnext": "./build/esnext/surfaces/checkout.esnext",
+      "import": "./build/esm/surfaces/checkout.mjs",
+      "require": "./build/cjs/surfaces/checkout.js"
+    },
+    "./admin": {
+      "types": "./build/ts/surfaces/admin.d.ts",
+      "esnext": "./build/esnext/surfaces/admin.esnext",
+      "import": "./build/esm/surfaces/admin.mjs",
+      "require": "./build/cjs/surfaces/admin.js"
     }
   },
   "license": "MIT",
@@ -32,6 +45,10 @@
     "@remote-ui/async-subscription": "^2.1.12",
     "@remote-ui/core": "2.1.x"
   },
+  "devDependencies": {
+    "@shopify/generate-docs": "0.10.7",
+    "typescript": "^4.9.0"
+  },
   "publishConfig": {
     "access": "public",
     "@shopify:registry": "https://registry.npmjs.org/"

package/src/api.ts

@@ -1,3 +1,76 @@
 export interface StandardApi {
   readonly extensionPoint: string;
 }
+
+/**
+ * This defines the i18n.translate() signature.
+ */
+export interface I18nTranslate {
+  /**
+   * This returns a translated string matching a key in a locale file.
+   *
+   * @example translate("banner.title")
+   */
+  <ReplacementType = string>(
+    key: string,
+    options?: {[placeholderKey: string]: ReplacementType | string | number},
+  ): ReplacementType extends string | number
+    ? string
+    : (string | ReplacementType)[];
+}
+
+export interface I18n {
+  /**
+   * Returns a localized number.
+   *
+   * This function behaves like the standard `Intl.NumberFormat()`
+   * with a style of `decimal` applied. It uses the buyer's locale by default.
+   *
+   * @param options.inExtensionLocale - if true, use the extension's locale
+   */
+  formatNumber: (
+    number: number | bigint,
+    options?: {inExtensionLocale?: boolean} & Intl.NumberFormatOptions,
+  ) => string;
+
+  /**
+   * Returns a localized currency value.
+   *
+   * This function behaves like the standard `Intl.NumberFormat()`
+   * with a style of `currency` applied. It uses the buyer's locale by default.
+   *
+   * @param options.inExtensionLocale - if true, use the extension's locale
+   */
+  formatCurrency: (
+    number: number | bigint,
+    options?: {inExtensionLocale?: boolean} & Intl.NumberFormatOptions,
+  ) => string;
+
+  /**
+   * Returns a localized date value.
+   *
+   * This function behaves like the standard `Intl.DateTimeFormatOptions()` and uses
+   * the buyer's locale by default. Formatting options can be passed in as
+   * options.
+   *
+   * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat0
+   * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat#using_options
+   *
+   * @param options.inExtensionLocale - if true, use the extension's locale
+   */
+  formatDate: (
+    date: Date,
+    options?: {inExtensionLocale?: boolean} & Intl.DateTimeFormatOptions,
+  ) => string;
+
+  /**
+   * Returns translated content in the buyer's locale,
+   * as supported by the extension.
+   *
+   * - `options.count` is a special numeric value used in pluralization.
+   * - The other option keys and values are treated as replacements for interpolation.
+   * - If the replacements are all primitives, then `translate()` returns a single string.
+   * - If replacements contain UI components, then `translate()` returns an array of elements.
+   */
+  translate: I18nTranslate;
+}

package/src/extension.ts

@@ -1,9 +1,24 @@
-import type {RemoteRoot, RemoteComponentType} from '@remote-ui/core';
+import type {
+  RemoteRoot,
+  RemoteChannel,
+  RemoteComponentType,
+} from '@remote-ui/core';
 
 export interface Extension<Api, Result> {
   (api: Api): Result;
 }
 
+export interface RenderExtensionConnection<
+  AllowedComponents extends RemoteComponentType<
+    string,
+    any,
+    any
+  > = RemoteComponentType<any, any, any>,
+> {
+  readonly channel: RemoteChannel;
+  readonly components: AllowedComponents;
+}
+
 export interface RenderExtension<
   Api,
   AllowedComponents extends RemoteComponentType<
@@ -11,6 +26,20 @@ export interface RenderExtension<
     any,
     any
   > = RemoteComponentType<any, any, any>,
+> {
+  (
+    connection: RenderExtensionConnection<AllowedComponents>,
+    api: Api,
+  ): void | Promise<void>;
+}
+
+export interface RenderExtensionWithRemoteRoot<
+  Api,
+  AllowedComponents extends RemoteComponentType<
+    string,
+    any,
+    any
+  > = RemoteComponentType<any, any, any>,
 > {
   (
     root: RemoteRoot<AllowedComponents, AllowedComponents>,

package/src/index.ts

@@ -1,3 +1,2 @@
 export * from './api';
 export * from './extension';
-export * from './extension';

package/src/shared.ts

@@ -0,0 +1,13 @@
+import type {RemoteComponentType} from '@remote-ui/core';
+
+export type ComponentsBuilder<ComponentTypes> = {
+  [K in keyof ComponentTypes]: ComponentTypes[K] extends RemoteComponentType<
+    any,
+    any
+  >
+    ? ComponentTypes[K]
+    : never;
+};
+
+export type AnyComponentBuilder<ComponentTypes> =
+  ComponentsBuilder<ComponentTypes>[keyof ComponentsBuilder<ComponentTypes>];

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

@@ -0,0 +1,19 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'Action Extension API',
+  description: 'This API is available to all action extension types.',
+  isVisualComponent: false,
+  type: 'API',
+  definitions: [
+    {
+      title: 'ActionExtensionApi',
+      description: '',
+      type: 'ActionExtensionApi',
+    },
+  ],
+  category: 'API',
+  related: [],
+};
+
+export default data;

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

@@ -0,0 +1,14 @@
+import type {StandardApi} from '../standard/standard';
+import type {I18n} from '../../../../api';
+import type {ExtensionPoint as AnyExtensionPoint} from '../../extension-points';
+
+export interface ActionExtensionApi<ExtensionPoint extends AnyExtensionPoint>
+  extends StandardApi<ExtensionPoint> {
+  /* Utilities for translating content according to the current `localization` of the admin. */
+  i18n: I18n;
+
+  /**
+   * Closes the extension. This is only available for action extensions.
+   */
+  close: () => void;
+}

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

@@ -0,0 +1,19 @@
+import type {StandardApi} from '../standard/standard';
+import type {I18n} from '../../../../api';
+import type {ExtensionPoint as AnyExtensionPoint} from '../../extension-points';
+
+/* List of enabled query language features during a progressive rollout */
+type CustomerSegmentationFeature =
+  /* Allows merchants to segment on products purchased by tags. For example: products_purchased(tag: 'Red hats') = true */
+  | 'productsPurchasedByTags'
+  /* Enables count aggregates on functions. For example: shopify_email.opened(count_at_least: 5) = true */
+  | 'aggregateFilters';
+
+export interface CustomerSegmentationTemplateApi<
+  ExtensionPoint extends AnyExtensionPoint,
+> extends StandardApi<ExtensionPoint> {
+  /* Utilities for translating content according to the current `localization` of the admin. */
+  i18n: I18n;
+  /** @private */
+  __enabledFeatures: CustomerSegmentationFeature[];
+}

package/src/surfaces/admin/api/extension-targets/extension-targets.doc.ts

@@ -0,0 +1,20 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'Extension Targets',
+  description:
+    'This is a list of all the available extension targets for Admin App Extensions.',
+  isVisualComponent: false,
+  type: 'API',
+  definitions: [
+    {
+      title: 'ExtensionPoints',
+      description: '',
+      type: 'ExtensionPoints',
+    },
+  ],
+  category: 'API',
+  related: [],
+};
+
+export default data;

package/src/surfaces/admin/api/standard/README.md

@@ -0,0 +1 @@
+# Standard admin API

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

@@ -0,0 +1,20 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'Standard API',
+  description: 'This API is available to all extension types.',
+  isVisualComponent: false,
+  type: 'API',
+  definitions: [
+    {
+      title: 'StandardApi',
+      description: '',
+      type: 'StandardApi',
+    },
+  ],
+  category: 'API',
+  // subCategory: 'Standard API',
+  related: [],
+};
+
+export default data;

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

@@ -0,0 +1,14 @@
+import type {StandardApi as BaseStandardApi, I18n} from '../../../../api';
+import type {ExtensionPoint as AnyExtensionPoint} from '../../extension-points';
+
+/**
+ * The following APIs are provided to all extension points.
+ */
+export interface StandardApi<ExtensionPoint extends AnyExtensionPoint>
+  extends BaseStandardApi {
+  /**
+   * The identifier of the running extension point.
+   */
+  extensionPoint: ExtensionPoint;
+  i18n: I18n;
+}

package/src/surfaces/admin/api.ts

@@ -0,0 +1,4 @@
+export type {I18n, I18nTranslate} from '../../api';
+export type {StandardApi} from './api/standard/standard';
+export type {CustomerSegmentationTemplateApi} from './api/customer-segmentation-template/customer-segmentation-template';
+export type {ActionExtensionApi} from './api/action/action';

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

@@ -0,0 +1,41 @@
+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.',
+  requires: '',
+  thumbnail: 'appaction-thumbnail.png',
+  isVisualComponent: true,
+  type: '',
+  definitions: [
+    {
+      title: 'AdminActionProps',
+      description: '',
+      type: 'AdminActionProps',
+    },
+  ],
+  category: 'Components',
+  subCategory: 'Other',
+  defaultExample: {
+    image: 'appaction-default.png',
+    codeblock: {
+      title: 'Set the primary and secondary action of the Action modal.',
+      tabs: [
+        {
+          title: 'React',
+          code: '../../../../../../ui-extensions-react/src/surfaces/admin/components/AdminAction/examples/basic-adminaction.example.tsx',
+          language: 'tsx',
+        },
+        {
+          title: 'JS',
+          code: './examples/basic-adminaction.example.ts',
+          language: 'js',
+        },
+      ],
+    },
+  },
+  related: [],
+};
+
+export default data;

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

@@ -0,0 +1,28 @@
+import {createRemoteComponent} from '@remote-ui/core';
+import type {RemoteFragment} from '@remote-ui/core';
+
+export interface AdminActionProps {
+  /**
+   * Sets the title of the Action container.
+   */
+  title?: string;
+
+  /**
+   * Sets the Primary action button of the container. This component must a button component.
+   */
+  primaryAction?: RemoteFragment;
+
+  /**
+   * Sets the Secondary action button of the container. This component must a button component.
+   */
+  secondaryAction?: RemoteFragment;
+
+  children: any;
+}
+/**
+ * AdminAction is a component used by Admin Action extensions to configure a primary and secondary action and title.
+ */
+export const AdminAction = createRemoteComponent<
+  'AdminAction',
+  AdminActionProps
+>('AdminAction');

package/src/surfaces/admin/components/AdminAction/examples/basic-adminaction.example.ts

@@ -0,0 +1,16 @@
+import {extension, AdminAction, Button} from '@shopify/ui-extensions/admin';
+
+export default extension('Playground', (root) => {
+  const adminAction = root.createComponent(AdminAction, {
+    title: 'My App Action',
+    primaryAction: root.createFragment(
+      root.createComponent(Button, {onPress: () => {}}, 'Action')
+    ),
+    secondaryAction: root.createFragment(
+      root.createComponent(Button, {onPress: () => {}}, 'Secondary')
+    )
+  }, 'Modal content');
+
+  root.appendChild(adminAction);
+  root.mount();
+});

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

@@ -0,0 +1,41 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'AdminBlock',
+  description:
+    'This component is similar to the AdminBlock, providing a deeper integration with the container your UI is rendered into. However, this only applies to Block Extensions which render inline on a resource page.',
+  requires: '',
+  thumbnail: 'appblock-thumbnail.png',
+  isVisualComponent: true,
+  type: '',
+  definitions: [
+    {
+      title: 'AdminBlockProps',
+      description: '',
+      type: 'AdminBlockProps',
+    },
+  ],
+  category: 'Components',
+  subCategory: 'Other',
+  defaultExample: {
+    image: 'appblock-default.png',
+    codeblock: {
+      title: 'Simple AdminBlock implementation',
+      tabs: [
+        {
+          title: 'React',
+          code: '../../../../../../ui-extensions-react/src/surfaces/admin/components/AdminBlock/examples/basic-adminblock.example.tsx',
+          language: 'tsx',
+        },
+        {
+          title: 'JS',
+          code: './examples/basic-adminblock.example.ts',
+          language: 'js',
+        },
+      ],
+    },
+  },
+  related: [],
+};
+
+export default data;

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

@@ -0,0 +1,19 @@
+import {createRemoteComponent} from '@remote-ui/core';
+
+export interface AdminBlockProps {
+  /**
+   * The title to display at the top of the app block. If not provided, the name of the extension will be used.
+   */
+  title?: string;
+
+  /**
+   * The summary to display when the app block is collapsed. If not provided, no summary will be displayed. No summary is shown when the app block is expanded.
+   */
+  summary?: string;
+
+  children: any;
+}
+
+export const AdminBlock = createRemoteComponent<'AdminBlock', AdminBlockProps>(
+  'AdminBlock',
+);

package/src/surfaces/admin/components/AdminBlock/examples/basic-adminblock.example.ts

@@ -0,0 +1,11 @@
+import {extension, AdminBlock, Button} from '@shopify/ui-extensions/admin';
+
+export default extension('Playground', (root) => {
+  const adminBlock = root.createComponent(AdminBlock, {
+    title: 'My App Block',
+    summary: '',
+  }, '5 items active');
+
+  root.appendChild(adminBlock);
+  root.mount();
+});

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

@@ -0,0 +1,42 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'BlockStack',
+  description:
+    "This structures layout elements along the vertical axis of the page. It's useful for vertical alignment.",
+  requires: '',
+  thumbnail: 'blockstack-thumbnail.png',
+  isVisualComponent: true,
+  type: '',
+  definitions: [
+    {
+      title: 'BlockStackProps',
+      description: '',
+      type: 'BlockStackProps',
+    },
+  ],
+  category: 'Components',
+  subCategory: 'Structure',
+  defaultExample: {
+    image: 'blockstack-default.png',
+    codeblock: {
+      title: 'Laying out elements in a column',
+      tabs: [
+        {
+          title: 'React',
+          code: '../../../../../../ui-extensions-react/src/surfaces/admin/components/BlockStack/examples/basic-BlockStack.example.tsx',
+          language: 'tsx',
+        },
+        {
+          title: 'JS',
+          code: './examples/basic-BlockStack.example.ts',
+          language: 'js',
+        },
+      ],
+    },
+  },
+
+  related: [],
+};
+
+export default data;

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

@@ -0,0 +1,27 @@
+import {createRemoteComponent} from '@remote-ui/core';
+
+import {
+  AccessibilityRoleProps,
+  GlobalProps,
+  SizingProps,
+  PaddingProps,
+  GapProps,
+} from '../shared';
+
+export interface BlockStackProps
+  extends AccessibilityRoleProps,
+    Pick<GapProps, 'gap' | 'blockGap' | 'rowGap'>,
+    GlobalProps,
+    SizingProps,
+    PaddingProps {
+  /**
+   * A label that describes the purpose or contents of the element. When set,
+   * it will be announced to buyers using assistive technologies and will
+   * provide them with more context.
+   */
+  accessibilityLabel?: string;
+}
+
+export const BlockStack = createRemoteComponent<'BlockStack', BlockStackProps>(
+  'BlockStack',
+);

package/src/surfaces/admin/components/BlockStack/examples/basic-blockstack.example.ts

@@ -0,0 +1,24 @@
+import {
+  extension,
+  BlockStack,
+} from '@shopify/ui-extensions/admin';
+
+export default extension(
+  'Playground',
+  (root) => {
+    const blockStack = root.createComponent(
+      BlockStack,
+      {
+        gap: 'base',
+      },
+      [
+        root.createText('Child 1'),
+        root.createText('Child 2'),
+        root.createText('Child 3'),
+        root.createText('Child 4'),
+      ],
+    );
+
+    root.appendChild(blockStack);
+  },
+);

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

@@ -0,0 +1,42 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'Box',
+  description:
+    'This is your foundational structural element for composing UI. It can be styled using predefined tokens. Use it to build your layout.',
+  requires: '',
+  thumbnail: 'box-thumbnail.png',
+  isVisualComponent: true,
+  type: '',
+  definitions: [
+    {
+      title: 'BoxProps',
+      description: '',
+      type: 'BoxProps',
+    },
+  ],
+  category: 'Components',
+  subCategory: 'Structure',
+  defaultExample: {
+    image: 'box-default.png',
+    codeblock: {
+      title: 'Use Box to build your layout',
+      tabs: [
+        {
+          title: 'React',
+          code: '../../../../../../ui-extensions-react/src/surfaces/admin/components/Box/examples/basic-Box.example.tsx',
+          language: 'tsx',
+        },
+        {
+          title: 'JS',
+          code: './examples/basic-Box.example.ts',
+          language: 'js',
+        },
+      ],
+    },
+  },
+
+  related: [],
+};
+
+export default data;

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

@@ -0,0 +1,13 @@
+import {createRemoteComponent} from '@remote-ui/core';
+import type {
+  AccessibilityRoleProps,
+  PaddingProps,
+  SizingProps,
+} from '../shared';
+
+export interface BoxProps
+  extends AccessibilityRoleProps,
+    SizingProps,
+    PaddingProps {}
+
+export const Box = createRemoteComponent<'Box', BoxProps>('Box');

package/src/surfaces/admin/components/Box/examples/basic-box.example.ts

@@ -0,0 +1,11 @@
+import {extend, Box} from '@shopify/ui-extensions/admin';
+
+extend('Playground', (root) => {
+  const box = root.createComponent(
+    Box,
+    {border: 'base', padding: 'base'},
+    'Box',
+  );
+
+  root.appendChild(box);
+});