@shopify/ui-extensions 2022.10.5 → 2023.4.0

package/src/surfaces/checkout/extension.ts

@@ -1,8 +1,67 @@
-import {createExtensionRegistrationFunction} from '../../utilities/registration';
+import type {RemoteRoot, RemoteComponentType} from '@remote-ui/core';
 
 import type {ExtensionPoints} from './extension-points';
 
-export * from '../../extension';
-
+/**
+ * Registers your UI Extension to run for the selected extension point.
+ *
+ * @param target The extension point you are registering for.
+ *
+ * @param implementation The function that will be called when Checkout begins rendering
+ * your extension. This function is called with the API checkout provided to your
+ * extension.
+ */
 export const extension = createExtensionRegistrationFunction<ExtensionPoints>();
+
+/**
+ * Registers your UI Extension to run for the selected extension point.
+ *
+ * @param target The extension point you are registering for.
+ *
+ * @param implementation The function that will be called when Checkout begins rendering
+ * your extension. This function is called with the API checkout provided to your
+ * extension.
+ */
 export const extend = extension;
+
+export interface RenderExtension<
+  Api,
+  AllowedComponents extends RemoteComponentType<
+    string,
+    any,
+    any
+  > = RemoteComponentType<any, any, any>,
+> {
+  (
+    root: RemoteRoot<AllowedComponents, AllowedComponents>,
+    api: Api,
+  ): void | Promise<void>;
+}
+
+export interface ExtensionRegistrationFunction<ExtensionPoints> {
+  <Target extends keyof ExtensionPoints>(
+    target: Target,
+    implementation: ExtensionPoints[Target],
+  ): ExtensionPoints[Target];
+}
+
+/**
+ * This function takes an extension function that is expecting a `RemoteRoot` as its
+ * first argument, and returns a new function that accepts a `RemoteChannel` instead.
+ * This is a convenience that allows the raw UI extension API to only expose the simpler
+ * `RemoteChannel` type, while allowing the extension to use the more powerful `RemoteRoot`,
+ * provided by a version of `@remote-ui/core` that the extension controls.
+ */
+export function createExtensionRegistrationFunction<
+  ExtensionPoints,
+>(): ExtensionRegistrationFunction<ExtensionPoints> {
+  const extensionWrapper: ExtensionRegistrationFunction<ExtensionPoints> = (
+    target,
+    implementation,
+  ) => {
+    (globalThis as any).shopify?.extend(target, implementation);
+    return implementation;
+  };
+
+  return extensionWrapper;
+}

package/src/surfaces/checkout/globals.ts

@@ -10,6 +10,6 @@ export interface ShopifyGlobal {
 
 declare global {
   interface WorkerGlobalScope {
-    readonly shopify: ShopifyGlobal;
+    readonly le_shopify: ShopifyGlobal;
   }
 }

package/src/surfaces/checkout/helper.docs.ts

@@ -0,0 +1,103 @@
+import {CodeTabType, ExampleType} from '@shopify/generate-docs';
+
+const examplePath = '../../../../../docs/surfaces/checkout/reference/examples';
+
+type NonEmptyArray<T> = [T, ...T[]];
+type ExtensionExampleLanguage = 'js' | 'jsx';
+type ExtensionCodeTabConfig = {
+  [key in ExtensionExampleLanguage]: {
+    title: string;
+    fileExtension: 'ts' | 'tsx';
+  };
+};
+const codeExampleTabConfig: ExtensionCodeTabConfig = {
+  js: {
+    title: 'JavaScript',
+    fileExtension: 'ts',
+  },
+  jsx: {
+    title: 'React',
+    fileExtension: 'tsx',
+  },
+};
+
+/**
+ * Returns all examples available, specified with a key for reference.
+ */
+export function getExamples(
+  languages: NonEmptyArray<ExtensionExampleLanguage>,
+): {
+  [key: string]: ExampleType;
+} {
+  if (!languages || languages.length === 0) {
+    throw new HelperDocsError(
+      'You must define at least one extension code language context you wish to retrieve the example(s) for.',
+    );
+  }
+  /**
+   * Provides the code tab for the requested languages in "JavaScript" and "React".
+   */
+  function getExtensionCodeTabs(name: string): CodeTabType[] {
+    return languages.map((language) => {
+      return {
+        code: `${examplePath}/${name}.example.${codeExampleTabConfig[language].fileExtension}`,
+        language,
+        title: codeExampleTabConfig[language].title,
+      };
+    });
+  }
+
+  // Add new examples here that can be shared across multiples pages.
+  return {
+    'ui-components/checkbox-links': {
+      description:
+        'To provide buyers with additional information or references, couple it with link components seamlessly within checkbox components. This can be done by including links as part of the checkbox label in the checkbox. This will provide an easy way to access relevant content that buyers may need.',
+      image: 'checkbox-links.png',
+      codeblock: {
+        title: 'Embedding links in checkbox components',
+        tabs: getExtensionCodeTabs('ui-components/checkbox-links'),
+      },
+    },
+    'ui-components/disclosure-and-alignment': {
+      description:
+        'Use the Disclosure component to simplify the user experience and reveal interfaces only when the customer requests it. It also demonstrates how a combination of inline and block layout components can improve the readability of information. By employing these strategies, users can easily scan and comprehend the content, making for a better user experience overall.',
+      image: 'disclosure-and-alignment.gif',
+      codeblock: {
+        title:
+          'Strategies for simplifying layout and aligning content using Disclosure and Inline/Block Layout components.',
+        tabs: getExtensionCodeTabs('ui-components/disclosure-and-alignment'),
+      },
+    },
+    'ui-components/loading-skeletons': {
+      description:
+        'When adding content to a layout, incorporate a skeleton loader that renders the approximate size and position of the content during loading. This will provide a seamless transition from skeleton loaders to the content, and prevent any layout shift when the resulting content loads.',
+      image: 'loading-skeletons.gif',
+      codeblock: {
+        title:
+          'Using skeleton loaders to prevent layout shifts on content load.',
+        tabs: getExtensionCodeTabs('ui-components/loading-skeletons'),
+      },
+    },
+  };
+}
+
+/**
+ * Returns a specific `Example` by name, as specified in `getExamples()`.
+ * Specify whether you want to include both `js` and `jsx`examples or just one.
+ */
+export function getExample(
+  name: string,
+  languages: NonEmptyArray<ExtensionExampleLanguage> = ['js'],
+): ExampleType {
+  const example = getExamples(languages)[name];
+  if (!example) {
+    throw new HelperDocsError(
+      `Could not find a matching example with the name "${name}". Does it exist within the file "docs/reference/helper.docs.ts" in getExamples()?`,
+    );
+  }
+  return example;
+}
+
+class HelperDocsError extends Error {
+  name = 'HelperDocsError';
+}

package/src/surfaces/checkout/shared.ts

@@ -1,14 +1,6 @@
-import type {RemoteComponentType} from '@remote-ui/core';
+import type {ComponentsBuilder, AnyComponentBuilder} from '../../shared';
 
 type ComponentTypes = typeof import('./components');
 
-export type Components = {
-  [K in keyof ComponentTypes]: ComponentTypes[K] extends RemoteComponentType<
-    any,
-    any
-  >
-    ? ComponentTypes[K]
-    : never;
-};
-
-export type AnyComponent = Components[keyof Components];
+export type Components = ComponentsBuilder<ComponentTypes>;
+export type AnyComponent = AnyComponentBuilder<ComponentTypes>;

package/src/surfaces/checkout/style/examples/.eslintrc.js

@@ -0,0 +1,8 @@
+// See the root .eslintrc for more overrides.
+module.exports = {
+  rules: {
+    'react/react-in-jsx-scope': 'off',
+    'react/jsx-no-undef': 'off',
+    'no-alert': 'off',
+  },
+};

package/src/surfaces/checkout/style/examples/defaultstyle.example.tsx

@@ -0,0 +1,9 @@
+<Grid
+  columns={Style.default('fill').when({viewportInlineSize: {min: 'small'}}, [
+    '30%',
+    '70%',
+  ])}
+>
+  <View>Content</View>
+  <View>Content</View>
+</Grid>;

package/src/surfaces/checkout/style/examples/simplecondition.example.tsx

@@ -0,0 +1,9 @@
+<Pressable
+  onPress={() => alert('press')}
+  border={Style.default(['base', 'dotted']).when(
+    {viewportInlineSize: {min: 'small'}},
+    ['base', 'dotted', 'none', 'base'],
+  )}
+>
+  Content
+</Pressable>;

package/src/surfaces/checkout/style/examples/style.example.ts

@@ -0,0 +1,18 @@
+import {Style, View, extension} from '@shopify/ui-extensions/checkout';
+
+extension('Checkout::Dynamic::Render', (root) => {
+  const view = root.createComponent(
+    View,
+    {
+      border: 'base',
+      padding: 'base',
+      maxInlineSize: Style.default(200)
+        .when({viewportInlineSize: {min: 'small'}}, 300)
+        .when({viewportInlineSize: {min: 'medium'}}, 400)
+        .when({viewportInlineSize: {min: 'large'}}, 800),
+    },
+    'Responsive Content',
+  );
+
+  root.appendChild(view);
+});

package/src/surfaces/checkout/style/examples/style.example.tsx

@@ -0,0 +1,16 @@
+import {Style, View} from '@shopify/checkout-ui-extensions-react';
+
+reactExtension('Checkout::Dynamic::Render', () => <Extension />);
+
+function Extension() {
+  return (
+    <View
+      maxInlineSize={Style.default(200)
+        .when({viewportInlineSize: {min: 'small'}}, 300)
+        .when({viewportInlineSize: {min: 'medium'}}, 400)
+        .when({viewportInlineSize: {min: 'large'}}, 800)}
+    >
+      Responsive Content
+    </View>
+  );
+}

package/src/surfaces/checkout/style/index.ts

@@ -0,0 +1,16 @@
+export {
+  Style,
+  isConditionalStyle,
+  isConditionalStyleWithDefault,
+} from './style';
+export type {
+  AtLeastOne,
+  Conditions,
+  ConditionalStyle,
+  ConditionalValue,
+  InteractiveConditions,
+  MaybeConditionalStyle,
+  MaybeResponsiveConditionalStyle,
+  ResolutionCondition,
+  ViewportSizeCondition,
+} from './types';

package/src/surfaces/checkout/style/memoize.ts

@@ -74,6 +74,8 @@ function createLruCache(maxSize: number, equals: EqualityFn): Cache {
 
   function put(key: unknown, value: unknown) {
     if (get(key) === NOT_FOUND) {
+      // eslint-disable-next-line no-warning-comments
+      // TODO Is unshift slow?
       entries.unshift({key, value});
       if (entries.length > maxSize) {
         entries.pop();

package/src/surfaces/checkout/style/style.doc.ts

@@ -0,0 +1,166 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'StyleHelper',
+  description:
+    'This is a helper for authoring conditional values for property styles.\n\nWrite complex conditional styles based on one or more conditions, such as viewport sizes and interactive states, in a concise and expressive way.',
+  requires: '',
+  isVisualComponent: false,
+  type: '',
+  definitions: [
+    {
+      title: 'StyleHelper',
+      description: '',
+      type: 'DocsStyle',
+    },
+  ],
+  category: 'Components',
+  subCategory: 'utilities',
+  defaultExample: {
+    codeblock: {
+      tabs: [
+        {
+          title: 'React',
+          code: './examples/style.example.tsx',
+          language: 'tsx',
+        },
+        {
+          title: 'JS',
+          code: './examples/style.example.ts',
+          language: 'js',
+        },
+      ],
+      title: 'Import the Style helper',
+    },
+  },
+  examples: {
+    description: 'This section provides examples of conditions.',
+    examples: [
+      {
+        description:
+          'Default styling can be combined with specific conditions. In this example, the Grid’s children will be stacked by default and side by side on viewports above the <code>small</code> breakpoint.',
+        codeblock: {
+          title: 'Default Style With Conditions',
+          tabs: [
+            {
+              title: 'React',
+              code: './examples/defaultstyle.example.tsx',
+              language: 'tsx',
+            },
+          ],
+        },
+      },
+      {
+        description:
+          'Using simple conditional styling enables you to specify a styling change when a condition is met. In this example, the View’s padding will be <code>loose</code> on hover.',
+        codeblock: {
+          title: 'Simple Condition',
+          tabs: [
+            {
+              title: 'React',
+              code: './examples/simplecondition.example.tsx',
+              language: 'tsx',
+            },
+          ],
+        },
+      },
+    ],
+  },
+  subSections: [
+    {
+      type: 'Generic',
+      anchorLink: 'conditions',
+      title: 'Conditions',
+      sectionContent:
+        'The following conditions are supported for conditional styles.\n\nMultiple conditions can be set on the same `when` method.\n\n \n\n| Name | Type | Description |\n| --- | --- | --- |\n| <code>"hover"</code> | <code>true</code> | This condition is met when an element is hovered on with the cursor (mouse pointer). |\n| <code>"focus"</code> | <code>true</code> | This condition is met when an element is clicked, tapped on or selected using the Tab key.|\n| <code>viewportInlineSize</code> | <code>{min: "small" &#124; "medium" &#124; "large"}</code> | This condition is met when the device matches the minimum width.|',
+    },
+  ],
+  related: [
+    {
+      name: 'BlockLayout',
+      subtitle: 'Component',
+      url: 'blocklayout',
+      type: 'Component',
+    },
+    {
+      name: 'BlockSpacer',
+      subtitle: 'Component',
+      url: 'blockspacer',
+      type: 'Component',
+    },
+    {
+      name: 'BlockStack',
+      subtitle: 'Component',
+      url: 'blockstack',
+      type: 'Component',
+    },
+    {
+      name: 'Grid',
+      subtitle: 'Component',
+      url: 'grid',
+      type: 'Component',
+    },
+    {
+      name: 'GridItem',
+      subtitle: 'Component',
+      url: 'griditem',
+      type: 'Component',
+    },
+    {
+      name: 'Image',
+      subtitle: 'Component',
+      url: 'image',
+      type: 'Component',
+    },
+    {
+      name: 'InlineLayout',
+      subtitle: 'Component',
+      url: 'inlinelayout',
+      type: 'Component',
+    },
+    {
+      name: 'InlineSpacer',
+      subtitle: 'Component',
+      url: 'inlinespacer',
+      type: 'Component',
+    },
+    {
+      name: 'InlineStack',
+      subtitle: 'Component',
+      url: 'inlinestack',
+      type: 'Component',
+    },
+    {
+      name: 'List',
+      subtitle: 'Component',
+      url: 'list',
+      type: 'Component',
+    },
+    {
+      name: 'Pressable',
+      subtitle: 'Component',
+      url: 'pressable',
+      type: 'Component',
+    },
+    {
+      name: 'ScrollView',
+      subtitle: 'Component',
+      url: 'scrollview',
+      type: 'Component',
+    },
+    {
+      name: 'SkeletonImage',
+      subtitle: 'Component',
+      url: 'skeletonimage',
+      type: 'Component',
+    },
+    {
+      name: 'View',
+      subtitle: 'Component',
+      url: 'view',
+      type: 'Component',
+    },
+  ],
+};
+
+export default data;

package/src/surfaces/checkout/style/style.ts

@@ -80,6 +80,11 @@ const when: WhenFunction = function when<
   ) as WhenReturnType<T, TContext, AcceptedConditions>;
 };
 
+export interface DocsStyle {
+  default: <T>(defaultValue: T) => ConditionalStyle<T>;
+  when: <T>(conditions: Conditions, value: T) => ConditionalStyle<T>;
+}
+
 /**
  * Style is a helper for authoring conditional values for prop styles.
  * Write complex conditional styles based on one or more conditions (viewport

package/src/surfaces/checkout/style/types.ts

@@ -56,6 +56,11 @@ export interface ConditionalStyle<
   conditionals: ConditionalValue<T, AcceptedConditions>[];
 }
 
+/**
+ * A type that represents a value that can be a conditional style.
+ * We highly recommend using the Style helper which simplifies the creation of conditional styles.
+ * To learn more check out the [conditional styles](/api/checkout-ui-extensions/components/utilities/stylehelper) documentation.
+ */
 export type MaybeConditionalStyle<
   T,
   AcceptedConditions extends BaseConditions = Conditions,

package/src/utilities/registration.ts

@@ -1,3 +1,10 @@
+import {createRemoteRoot} from '@remote-ui/core';
+import type {
+  RenderExtensionConnection,
+  RenderExtension,
+  RenderExtensionWithRemoteRoot,
+} from '../extension';
+
 export interface ExtensionRegistrationFunction<ExtensionPoints> {
   <Target extends keyof ExtensionPoints>(
     target: Target,
@@ -5,6 +12,18 @@ export interface ExtensionRegistrationFunction<ExtensionPoints> {
   ): ExtensionPoints[Target];
 }
 
+export interface ExtensionRegistrationFunctionWithRoot<ExtensionPoints> {
+  <Target extends keyof ExtensionPoints>(
+    target: Target,
+    implementation: ExtensionPoints[Target] extends RenderExtension<
+      infer Api,
+      infer Components
+    >
+      ? RenderExtensionWithRemoteRoot<Api, Components>
+      : ExtensionPoints[Target],
+  ): ExtensionPoints[Target];
+}
+
 /**
  * This function takes an extension function that is expecting a `RemoteRoot` as its
  * first argument, and returns a new function that accepts a `RemoteChannel` instead.
@@ -14,13 +33,46 @@ export interface ExtensionRegistrationFunction<ExtensionPoints> {
  */
 export function createExtensionRegistrationFunction<
   ExtensionPoints,
->(): ExtensionRegistrationFunction<ExtensionPoints> {
-  const extensionWrapper: ExtensionRegistrationFunction<ExtensionPoints> = (
-    target,
-    implementation,
-  ) => {
-    (globalThis as any).shopify?.extend(target, implementation);
-    return implementation;
+>(): ExtensionRegistrationFunctionWithRoot<ExtensionPoints> {
+  const extensionWrapper: ExtensionRegistrationFunctionWithRoot<
+    ExtensionPoints
+  > = (target, implementation) => {
+    async function extension(...args: any[]) {
+      // Rendering extensions have two arguments. Non-rendering extensions don’t have
+      // a `RemoteChannel` that needs to be normalized, so we can just pass the arguments
+      // through.
+      if (args.length === 1) {
+        return (implementation as any)(...args);
+      }
+
+      const [{channel, components}, api] = args as [
+        RenderExtensionConnection,
+        any,
+      ];
+
+      const root = createRemoteRoot(channel, {
+        components,
+        strict: true,
+      });
+
+      let renderResult = (implementation as any)(root, api);
+
+      if (
+        typeof renderResult === 'object' &&
+        renderResult != null &&
+        'then' in renderResult
+      ) {
+        renderResult = await renderResult;
+      }
+
+      root.mount();
+
+      return renderResult;
+    }
+
+    (globalThis as any).shopify?.extend(target, extension);
+
+    return extension as any;
   };
 
   return extensionWrapper;

package/build/ts/surfaces/checkout/api/cart-line-details/render-after.d.ts

@@ -1,9 +0,0 @@
-import type { StatefulRemoteSubscribable } from '@remote-ui/async-subscription';
-import type { PresentmentCartLine, StandardApi } from '../standard/standard';
-export interface CartLineDetailsRenderAfterApi extends StandardApi<'Checkout::CartLineDetails::RenderAfter'> {
-    /**
-     * The cart line the extension is attached to.
-     */
-    target: StatefulRemoteSubscribable<PresentmentCartLine>;
-}
-//# sourceMappingURL=render-after.d.ts.map

package/build/ts/surfaces/checkout/api/cart-line-details/render-after.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"render-after.d.ts","sourceRoot":"","sources":["../../../../../../src/surfaces/checkout/api/cart-line-details/render-after.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,0BAA0B,EAAC,MAAM,+BAA+B,CAAC;AAE9E,OAAO,KAAK,EAAC,mBAAmB,EAAE,WAAW,EAAC,MAAM,sBAAsB,CAAC;AAE3E,MAAM,WAAW,6BACf,SAAQ,WAAW,CAAC,wCAAwC,CAAC;IAC7D;;OAEG;IACH,MAAM,EAAE,0BAA0B,CAAC,mBAAmB,CAAC,CAAC;CACzD"}

package/src/surfaces/checkout/api/cart-line-details/README.md

@@ -1 +0,0 @@
-# Checkout cart line details API