@shopify/ui-extensions 2023.7.2 → 2024.1.0

package/src/surfaces/checkout/components/Map/examples/basic-map.example.ts

@@ -0,0 +1,13 @@
+import {extension, Map} from '@shopify/ui-extensions/checkout';
+
+export default extension('purchase.checkout.block.render', (root) => {
+  const map = root.createComponent(Map, {
+    apiKey: 'YOUR_API_KEY',
+    accessibilityLabel: 'Map showing pickup locations',
+    latitude: -28.024,
+    longitude: 140.887,
+    zoom: 4,
+  });
+
+  root.appendChild(map);
+});

package/src/surfaces/checkout/components/MapMarker/MapMarker.doc.ts

@@ -0,0 +1,62 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'MapMarker',
+  description:
+    'MapMarker represents a specific location or point of interest on a map.',
+  requires: '',
+  thumbnail: 'mapmarker-thumbnail.png',
+  isVisualComponent: true,
+  type: '',
+  definitions: [
+    {
+      title: 'MapMarkerProps',
+      description: '',
+      type: 'MapMarkerProps',
+    },
+  ],
+  category: 'Components',
+  subCategory: 'Interactive',
+  defaultExample: {
+    image: 'mapmarker-default.png',
+    codeblock: {
+      title: 'Basic MapMarker',
+      tabs: [
+        {
+          title: 'React',
+          code: '../../../../../../ui-extensions-react/src/surfaces/checkout/components/MapMarker/examples/basic-mapmarker.example.tsx',
+          language: 'tsx',
+        },
+        {
+          title: 'JS',
+          code: './examples/basic-mapmarker.example.ts',
+          language: 'js',
+        },
+      ],
+    },
+  },
+  subSections: [
+    {
+      type: 'Generic',
+      anchorLink: 'best-practices',
+      title: 'Best Practices',
+      sectionContent: `- If your markers are interactive, make sure that the selected marker's icon is different from the rest of the non-selected markers.\n\n- If there are a large number of markers obscuring important features of the map, set the markers to clusterable to help increase the readability of the map.`,
+    },
+  ],
+  related: [
+    {
+      name: 'Map',
+      subtitle: 'Component',
+      url: 'map',
+      type: 'Component',
+    },
+    {
+      name: 'MapPopover',
+      subtitle: 'Component',
+      url: 'mappopover',
+      type: 'Component',
+    },
+  ],
+};
+
+export default data;

package/src/surfaces/checkout/components/MapMarker/MapMarker.ts

@@ -0,0 +1,47 @@
+import {createRemoteComponent} from '@remote-ui/core';
+
+import type {OverlayActivatorProps} from '../shared';
+
+export interface MapMarkerProps extends OverlayActivatorProps {
+  /**
+   * The latitude of the marker.
+   */
+  latitude: number;
+  /**
+   * The longitude of the marker.
+   */
+  longitude: number;
+  /**
+   * The accessibility label of the marker.
+   */
+  accessibilityLabel: string;
+  /**
+   * Set to `true` to allow grouping the marker in clusters when zoomed out.
+   */
+  clusterable?: boolean;
+  /**
+   * Callback that is run when the marker is pressed.
+   */
+  onPress?(): void;
+  /**
+   * The URL of the icon to use for the marker.
+   */
+  icon?: string;
+  /**
+   * The block size of the icon.
+   * This property is only used when the `icon` property is set.
+   */
+  blockSize?: number;
+  /**
+   * The inline size of the icon.
+   * This property is only used when the `icon` property is set.
+   */
+  inlineSize?: number;
+}
+
+/**
+ * Use the `MapMarker` component to provide visual representation of single geographic location such as a shipping address or package pickup location.
+ */
+export const MapMarker = createRemoteComponent<'MapMarker', MapMarkerProps>(
+  'MapMarker',
+);

package/src/surfaces/checkout/components/MapMarker/examples/basic-mapmarker.example.ts

@@ -0,0 +1,23 @@
+import {extension, Map, MapMarker} from '@shopify/ui-extensions/checkout';
+
+export default extension('purchase.checkout.block.render', (root) => {
+  const map = root.createComponent(
+    Map,
+    {
+      apiKey: 'YOUR_API_KEY',
+      accessibilityLabel: 'Map',
+      latitude: -28.024,
+      longitude: 140.887,
+      zoom: 4,
+    },
+    [
+      root.createComponent(MapMarker, {
+        latitude: -28.024,
+        longitude: 140.887,
+        accessibilityLabel: 'Map marker for Innamincka, Australia',
+      }),
+    ],
+  );
+
+  root.appendChild(map);
+});

package/src/surfaces/checkout/components/MapPopover/MapPopover.doc.ts

@@ -0,0 +1,62 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'MapPopover',
+  description:
+    'MapPopover provides additional information or context about a specific location or point of interest on a map.',
+  requires: '',
+  thumbnail: 'mappopover-thumbnail.png',
+  isVisualComponent: true,
+  type: '',
+  definitions: [
+    {
+      title: 'MapPopoverProps',
+      description: '',
+      type: 'MapPopoverProps',
+    },
+  ],
+  category: 'Components',
+  subCategory: 'Interactive',
+  defaultExample: {
+    image: 'mappopover-default.png',
+    codeblock: {
+      title: 'Basic MapPopover',
+      tabs: [
+        {
+          title: 'React',
+          code: '../../../../../../ui-extensions-react/src/surfaces/checkout/components/MapPopover/examples/basic-mappopover.example.tsx',
+          language: 'tsx',
+        },
+        {
+          title: 'JS',
+          code: './examples/basic-mappopover.example.ts',
+          language: 'js',
+        },
+      ],
+    },
+  },
+  subSections: [
+    {
+      type: 'Generic',
+      anchorLink: 'best-practices',
+      title: 'Best Practices',
+      sectionContent: `- Use to display relevant details such as the name, address, description, or other pertinent information related to the location.\n\n- Ensure that the content displayed in the map popover is brief, relevant, and easy to understand.\n\n- Maintain visual consistency with the overall design of the checkout. `,
+    },
+  ],
+  related: [
+    {
+      name: 'Map',
+      subtitle: 'Component',
+      url: 'map',
+      type: 'Component',
+    },
+    {
+      name: 'MapMarker',
+      subtitle: 'Component',
+      url: 'mapmarker',
+      type: 'Component',
+    },
+  ],
+};
+
+export default data;

package/src/surfaces/checkout/components/MapPopover/MapPopover.ts

@@ -0,0 +1,21 @@
+import {createRemoteComponent} from '@remote-ui/core';
+
+import {IdProps} from '../shared';
+
+export interface MapPopoverProps extends IdProps {
+  /**
+   * Callback to run when the Popover is closed.
+   */
+  onClose?(): void;
+  /**
+   * Callback to run when the Popover is opened.
+   */
+  onOpen?(): void;
+}
+
+/**
+ * Use the `MapPopover` component to provide additional details about a single geographic location such as a shipping address or package pickup location.
+ */
+export const MapPopover = createRemoteComponent<'MapPopover', MapPopoverProps>(
+  'MapPopover',
+);

package/src/surfaces/checkout/components/MapPopover/examples/basic-mappopover.example.ts

@@ -0,0 +1,36 @@
+import {
+  extension,
+  Map,
+  MapMarker,
+  MapPopover,
+} from '@shopify/ui-extensions/checkout';
+
+export default extension('purchase.checkout.block.render', (root) => {
+  const popoverFragment = root.createFragment();
+  const popover = root.createComponent(
+    MapPopover,
+    {},
+    'Blue Mountains National Park store',
+  );
+  popoverFragment.appendChild(popover);
+  const map = root.createComponent(
+    Map,
+    {
+      apiKey: 'YOUR_API_KEY',
+      accessibilityLabel: 'Map',
+      latitude: -28.024,
+      longitude: 140.887,
+      zoom: 4,
+    },
+    [
+      root.createComponent(MapMarker, {
+        latitude: -28.024,
+        longitude: 140.887,
+        accessibilityLabel: 'Map marker for Innamincka, Australia',
+        overlay: popoverFragment,
+      }),
+    ],
+  );
+
+  root.appendChild(map);
+});

package/src/surfaces/checkout/components/PaymentIcon/PaymentIcon.doc.ts

@@ -0,0 +1,55 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'PaymentIcon',
+  description:
+    'Payment icons can be used for displaying payment-related information or features such as a user’s saved or available payment methods.',
+  thumbnail: 'paymenticon-thumbnail.png',
+  requires: '',
+  isVisualComponent: true,
+  type: '',
+  definitions: [
+    {
+      title: 'PaymentIconProps',
+      description: '',
+      type: 'PaymentIconProps',
+    },
+    {
+      title: 'PaymentMethod',
+      description: '',
+      type: 'PaymentMethod',
+    },
+  ],
+  category: 'Components',
+  subCategory: 'Media',
+  defaultExample: {
+    image: 'paymenticon-default.png',
+    codeblock: {
+      title: 'Basic PaymentIcon',
+      tabs: [
+        {
+          title: 'React',
+          code: '../../../../../../ui-extensions-react/src/surfaces/checkout/components/PaymentIcon/examples/basic-paymenticon.example.tsx',
+          language: 'tsx',
+        },
+        {
+          title: 'JS',
+          code: './examples/basic-paymenticon.example.ts',
+          language: 'js',
+        },
+      ],
+    },
+  },
+  subSections: [
+    {
+      type: 'Generic',
+      anchorLink: 'best-practices',
+      title: 'Best Practices',
+      sectionContent:
+        '- Maintain the interior appearance of the SVG. The branded portion of the payment icon as provided meets the brand guidelines of the payment provider.\n\n- Maintain the border property of the payment icon. It is designed to adapt to merchant branding in Checkout and ensures a consistent appearance across the customer experience.\n\n- The icon size is designed to be displayed consistently across checkout.',
+    },
+  ],
+  related: [],
+};
+
+export default data;