@shopify/ui-extensions 2024.4.2 → 2024.10.0

package/src/surfaces/customer-account/components/Avatar/Avatar.ts

@@ -0,0 +1,46 @@
+import {createRemoteComponent} from '@remote-ui/core';
+import {Size} from '../../../checkout';
+import type {IdProps} from '../shared';
+
+export interface AvatarProps extends IdProps {
+  /**
+   * Initials to display in the avatar.
+   */
+  initials?: string;
+
+  /**
+   * The URL or path to the image.
+   *
+   * Initials will be rendered as a fallback if `src` is not provided, fails to load or does not load quickly.
+   */
+  src?: string;
+
+  /**
+   * Invoked when load of provided image completes successfully.
+   *
+   * @see https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers/onload
+   */
+  onLoad?(): void;
+
+  /**
+   * Invoked on load error of provided image.
+   *
+   * @see https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers/onerror
+   */
+  onError?(): void;
+
+  /**
+   * Size of the avatar.
+   *
+   * @default 'base'
+   */
+  size?: Extract<Size, 'base' | 'large' | 'extraLarge' | 'fill'>;
+
+  /**
+   * An alternative text description that describe the image for the reader
+   * to understand what it is about or identify the user the avatar belongs to.
+   */
+  alt?: string;
+}
+
+export const Avatar = createRemoteComponent<'Avatar', AvatarProps>('Avatar');

package/src/surfaces/customer-account/components/Avatar/examples/basic-Avatar-js.example.ts

@@ -0,0 +1,26 @@
+import {
+  Avatar,
+  InlineStack,
+  extension,
+} from '@shopify/ui-extensions/customer-account';
+
+export default extension('customer-account.page.render', (root, api) => {
+  renderApp(root, api);
+});
+
+async function renderApp(root, api) {
+  const avatar = root.createComponent(Avatar, {
+    alt: 'John Doe',
+  });
+
+  const avatarWithInitials = root.createComponent(Avatar, {
+    initials: 'EW',
+    alt: 'Evan Williams',
+  });
+
+  const inlineStack = root.createComponent(InlineStack, {spacing: 'large500'});
+  inlineStack.append(avatar);
+  inlineStack.append(avatarWithInitials);
+
+  root.append(inlineStack);
+}

package/src/surfaces/customer-account/components/Avatar/index.ts

@@ -0,0 +1 @@
+export {Avatar, type AvatarProps} from './Avatar';

package/src/surfaces/customer-account/components/Card/Card.doc.ts

@@ -0,0 +1,54 @@
+import type {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'Card',
+  description:
+    'Group related content and functionality together in a familiar and consistent style, for customers to scan, read, and get things done.',
+  thumbnail: 'card-thumbnail.png',
+  requires: '',
+  isVisualComponent: true,
+  type: '',
+  definitions: [
+    {
+      title: 'CardProps',
+      description: '',
+      type: 'CardProps',
+    },
+  ],
+  category: 'components',
+  defaultExample: {
+    image: 'card-preview.png',
+    altText:
+      'An example of the card component shows a header that says "Addresses", and a button in the upper-right corner that says "+Add". Under the header, there is a full mailing address labeled as the default address, with a pencil icon for editing it.',
+    codeblock: {
+      title: 'Basic Card',
+      tabs: [
+        {
+          title: 'React',
+          code: '../../../../../../ui-extensions-react/src/surfaces/customer-account/components/Card/examples/basic-Card-react.example.tsx',
+          language: 'tsx',
+        },
+        {
+          title: 'JS',
+          code: './examples/basic-Card-js.example.ts',
+          language: 'js',
+        },
+      ],
+    },
+  },
+  subSections: [
+    {
+      type: 'Generic',
+      anchorLink: 'best-practices',
+      title: 'Best Practices',
+      sectionContent: `
+- Group related information.
+- Use headings that set clear expectations about the card’s purpose.
+- Display information in a way that emphasizes and prioritizes what the customer needs to know first.
+`,
+    },
+  ],
+  related: [],
+};
+
+export default data;

package/src/surfaces/customer-account/components/Card/examples/basic-Card-js.example.ts

@@ -0,0 +1,47 @@
+import {
+  Card,
+  Grid,
+  extension,
+} from '@shopify/ui-extensions/customer-account';
+
+export default extension(
+  'customer-account.page.render',
+  (root, api) => {
+    renderApp(root, api);
+  },
+)
+
+function renderApp(root, api) {
+  const card = root.createComponent(
+    Card,
+    {padding: true},
+    [
+      root.createComponent(Grid, {columns: ['1fr', 'auto'],
+        spacing: "base",
+        minInlineSize: "fill",
+        blockAlignment: "start"}, [
+        root.createComponent('BlockStack', {spacing: 'loose'}, [
+          root.createComponent('Heading', undefined, 'Addresses'),
+          root.createComponent('BlockStack', {spacing: 'base'}, [
+            root.createComponent('Text', {appearance: "subdued"}, 'Default address'),
+            root.createComponent('BlockStack', {spacing: 'extraTight'}, [
+                root.createComponent('TextBlock',{}, 'Kristin Watson'),
+                root.createComponent('TextBlock', {}, '1655 Island Pkwy'),
+                root.createComponent('TextBlock', {}, 'Kamloops BC M7G 672'),
+                root.createComponent('TextBlock', {}, 'Canada'),
+            ]),
+          ]),
+        ]),
+        root.createComponent('BlockStack', {spacing: 'loose'}, [
+          root.createComponent('InlineLayout',  {blockAlignment: "center"}, [
+            root.createComponent('Icon', {source: "plus", size: "small", appearance: "accent"}),
+            root.createComponent('Text', {appearance: "accent"}, 'Add'),
+          ]),
+          root.createComponent('View', {inlineAlignment: "end"}, [
+            root.createComponent('Icon', {source: "pen", size: "small", appearance: "accent"}),
+          ]),
+        ]),
+      ]),
+    ])
+  root.append(card);
+}

package/src/surfaces/customer-account/components/CustomerAccountAction/CustomerAccountAction.doc.ts

@@ -0,0 +1,66 @@
+import type {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'CustomerAccountAction',
+  description:
+    'A modal to complete an order action flow. This component can only be used to populate the [customer-account.order.action.render](/docs/api/customer-account-ui-extensions/unstable/targets/order-action-menu/customer-account-order-action-render) extension target, which renders as a result of the customer clicking the order action button rendered via the [customer-account.order.action.menu-item.render](/docs/api/customer-account-ui-extensions/unstable/targets/order-action-menu/customer-account-order-action-menu-item-render) extension target.',
+  thumbnail: 'customeraccountaction-thumbnail.png',
+  requires: '',
+  isVisualComponent: true,
+  type: '',
+  definitions: [
+    {
+      title: 'CustomerAccountActionProps',
+      description: '',
+      type: 'CustomerAccountActionProps',
+    },
+    {
+      title: 'ButtonProps primaryAction',
+      description:
+        'Supported props for Buttons used inside CustomerAccountAction `primaryAction` prop.<br><br>`children` only support text.',
+      type: 'Docs_CustomerAccountAction_Button_PrimaryAction',
+    },
+    {
+      title: 'ButtonProps secondaryAction',
+      description:
+        'Supported props for Button used inside CustomerAccountAction `secondaryAction` prop.<br><br>`children` only support text.',
+      type: 'Docs_CustomerAccountAction_Button_SecondaryAction',
+    },
+  ],
+  category: 'components',
+  defaultExample: {
+    image: 'customeraccountaction-preview.png',
+    altText:
+      'An example of the CustomerAccountAction component shows a dismissible modal with a header that says "Edit order", a field for adjusting quantities, and a Save button.',
+    codeblock: {
+      title: 'Basic CustomerAccountAction',
+      tabs: [
+        {
+          title: 'React',
+          code: '../../../../../../ui-extensions-react/src/surfaces/customer-account/components/CustomerAccountAction/examples/basic-CustomerAccountAction-react.example.tsx',
+          language: 'tsx',
+        },
+        {
+          title: 'JS',
+          code: './examples/basic-CustomerAccountAction-js.example.ts',
+          language: 'js',
+        },
+      ],
+    },
+  },
+  subSections: [
+    {
+      type: 'Generic',
+      anchorLink: 'best-practices',
+      title: 'Best Practices',
+      sectionContent: `
+- Use CustomerAccountAction to shift focus toward information and functionality needed to confirm or complete an order action.
+- If the order action experience you’re building requires complex forms or large amounts of information, consider building a full-page extension instead.
+- See Polaris for more best practices and content guidelines for designing [Modals](https://polaris.shopify.com/components/overlays/modal#best-practices).
+`,
+    },
+  ],
+  related: [],
+};
+
+export default data;

package/src/surfaces/customer-account/components/CustomerAccountAction/CustomerAccountAction.ts

@@ -0,0 +1,22 @@
+import {createRemoteComponent} from '@remote-ui/core';
+import type {RemoteFragment} from '@remote-ui/core';
+
+export interface CustomerAccountActionProps {
+  /**
+   * Sets the title of the Action container.
+   */
+  title: string;
+  /**
+   * Sets the Primary action button of the container. This component must be a button component.
+   */
+  primaryAction?: RemoteFragment;
+  /**
+   * Sets the Secondary action button of the container. This component must be a button component.
+   */
+  secondaryAction?: RemoteFragment;
+}
+
+export const CustomerAccountAction = createRemoteComponent<
+  'CustomerAccountAction',
+  CustomerAccountActionProps
+>('CustomerAccountAction');

package/src/surfaces/customer-account/components/CustomerAccountAction/examples/basic-CustomerAccountAction-js.example.ts

@@ -0,0 +1,27 @@
+import {
+  Button,
+  CustomerAccountAction,
+  extension
+} from '@shopify/ui-extensions/customer-account';
+
+export default extension(
+  'customer-account.order.action.render',
+  (root, api) => {
+    renderApp(root, api);
+  },
+)
+
+async function renderApp(root, api) {
+  const primaryAction = root.createFragment();
+  await primaryAction.append(root.createComponent(Button, {onPress: () => {api.close()}}, 'Click to close'));
+
+  const customerAccountAction = root.createComponent(
+    CustomerAccountAction,
+    {
+      title: 'Extension title',
+      primaryAction,
+    },
+    root.createComponent('TextBlock', {}, 'Extension content')
+  );
+  root.append(customerAccountAction);
+}

package/src/surfaces/customer-account/components/CustomerAccountAction/index.ts

@@ -0,0 +1,2 @@
+export {CustomerAccountAction} from './CustomerAccountAction';
+export type {CustomerAccountActionProps} from './CustomerAccountAction';

package/src/surfaces/customer-account/components/DropZone/DropZone.doc.ts

@@ -0,0 +1,67 @@
+import type {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'DropZone',
+  description: `Dropzone allows file uploads through drag-and-drop functionality into a designated area on a page, or by activating a button. At present, Dropzone does not offer image upload preview capabilities. The use of object URLs directly in an image component is not possible due to the extension and host operating on separate domains.
+    \n Any element focused within the Dropzone component, including child elements such as the 'Add file' button, will initiate the file selector when the Enter or Spacebar key is pressed.
+    `,
+  thumbnail: 'dropzone-thumbnail.png',
+  requires: '',
+  isVisualComponent: true,
+  type: '',
+  definitions: [
+    {
+      title: 'DropZoneProps',
+      description: '',
+      type: 'DropZoneProps',
+    },
+  ],
+  category: 'components',
+  defaultExample: {
+    image: 'dropzone-preview.png',
+    altText:
+      'An image showcasing the DropZone component with a button to add files with error and dragged over states.',
+    codeblock: {
+      title: 'DropZone',
+      tabs: [
+        {
+          title: 'React',
+          code: '../../../../../../ui-extensions-react/src/surfaces/customer-account/components/DropZone/examples/basic-DropZone-react.example.tsx',
+          language: 'tsx',
+        },
+        {
+          title: 'JS',
+          code: './examples/basic-DropZone-js.example.ts',
+          language: 'js',
+        },
+      ],
+    },
+  },
+  subSections: [
+    {
+      type: 'Generic',
+      anchorLink: 'best-practices',
+      title: 'Best Practices',
+      sectionContent: `
+### File storage
+
+File storage for uploads must be implemented separately. Metafields and [the Customer Account API](https://shopify.dev/docs/api/customer/latest/mutations/metafieldsSet) can be utilized to store references to files alongside the relevant objects.
+
+### Mobile
+
+Remember that the drag and drop feature won't be effective on mobile devices. Adding a button can offer additional context and guide users through the next steps.
+
+<img src='/assets/templated-apis-screenshots/customer-account-ui-extensions/unstable/dropzone-mobile-example.png' alt="An example showing DropZone with custom content optimized for mobile devices" />
+
+### Minimum size
+
+To prevent cut-off text and spacing issues, the minimum size of a Dropzone should be 100px x 100px.
+
+<img src='/assets/templated-apis-screenshots/customer-account-ui-extensions/unstable/dropzone-minimum-size.png' alt="An example showing DropZone with correct minimum size" />
+      `,
+    },
+  ],
+  related: [],
+};
+
+export default data;

package/src/surfaces/customer-account/components/DropZone/DropZone.ts

@@ -0,0 +1,76 @@
+import {createRemoteComponent} from '@remote-ui/core';
+import {IdProps} from '../shared';
+
+export interface DropZoneProps extends IdProps {
+  /**
+   * Whether the field can be modified.
+   */
+  disabled?: boolean;
+
+  /**
+   * Whether the field needs a value. This requirement adds semantic value
+   * to the field, but it will not cause an error to appear automatically.
+   * If you want to present an error when this field is empty, you can do
+   * so with the `error` prop.
+   */
+  required?: boolean;
+
+  /**
+   * Indicate an error to the user. The field will be given a specific stylistic treatment
+   * to communicate problems that have to be resolved immediately.
+   */
+  error?: string | boolean;
+
+  /**
+   * Content to use as the field label.
+   */
+  label?: string;
+
+  /**
+   * An identifier for the field that is unique within the nearest
+   * containing `Form` component.
+   */
+  name?: string;
+
+  /**
+   * A string representing the types of files that are accepted by the dropzone.
+   * This string is a comma-separated list of unique file type specifiers which can be one of the following:
+   * - A file extension starting with a period (".") character (e.g. .jpg, .pdf, .doc)
+   * - A valid MIME type string with no extensions
+   *
+   * If left empty, the dropzone will accept all files.
+   *
+   * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/accept
+   */
+  accept?: string;
+
+  /**
+   * A label that describes the purpose or contents of the item. When set,
+   * it will be announced to buyers using assistive technologies and will
+   * provide them with more context.
+   */
+  accessibilityLabel?: string;
+
+  /**
+   * Defines if the user can select or drop multiple files at once.
+   *
+   * @default false
+   */
+  multiple?: boolean;
+
+  /**
+   * Callback when files are dropped or selected.
+   * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/drop_event
+   */
+  onInput?(files: File[]): void;
+
+  /**
+   * Callback when rejected files are dropped. Files are rejected based on the `accept` prop.
+   *
+   */
+  onDropRejected?(files: File[]): void;
+}
+
+export const DropZone = createRemoteComponent<'DropZone', DropZoneProps>(
+  'DropZone',
+);

package/src/surfaces/customer-account/components/DropZone/examples/basic-DropZone-js.example.ts

@@ -0,0 +1,13 @@
+import {DropZone, extension} from '@shopify/ui-extensions/customer-account';
+
+export default extension('customer-account.page.render', (root, api) => {
+  renderApp(root, api);
+});
+
+async function renderApp(root, api) {
+  const dropZone = root.createComponent(DropZone, {
+    accept: 'image/*',
+  });
+
+  root.append(dropZone);
+}

package/src/surfaces/customer-account/components/DropZone/index.ts

@@ -0,0 +1,2 @@
+export {DropZone} from './DropZone';
+export type {DropZoneProps} from './DropZone';

package/src/surfaces/customer-account/components/ImageGroup/ImageGroup.doc.ts

@@ -0,0 +1,53 @@
+import type {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'ImageGroup',
+  description:
+    'Display up to 4 images in a grid or stacked layout. For example, images of products in a wishlist or subscription. When there are more than 4 images, the component indicates how many more images are not displayed.',
+  thumbnail: 'imagegroup-thumbnail.png',
+  requires: '',
+  isVisualComponent: true,
+  type: '',
+  definitions: [
+    {
+      title: 'ImageGroupProps',
+      description: '',
+      type: 'ImageGroupProps',
+    },
+  ],
+  category: 'components',
+  defaultExample: {
+    image: 'imagegroup-preview.png',
+    altText:
+      'An example of the ImageGroup component shows 3 circular images of plants displayed in a row, each one slightly overlapping the previous image—in a horizontal stacked pattern. To the right, there is another group of 3 images of plants, arranged in a 2x2 grid. There is one square image in the upper-left quadrant, one square image in the lower-left quadrant, and the entire right half of the grid is occupied by one image.',
+    codeblock: {
+      title: 'Basic ImageGroup',
+      tabs: [
+        {
+          title: 'React',
+          code: '../../../../../../ui-extensions-react/src/surfaces/customer-account/components/ImageGroup/examples/basic-ImageGroup-react.example.tsx',
+          language: 'tsx',
+        },
+        {
+          title: 'JS',
+          code: './examples/basic-ImageGroup-js.example.ts',
+          language: 'js',
+        },
+      ],
+    },
+  },
+  subSections: [
+    {
+      type: 'Generic',
+      anchorLink: 'best-practices',
+      title: 'Best Practices',
+      sectionContent: `
+- Use with the [ResourceItem](/docs/api/customer-account-ui-extension/unstable/components/resourceitem) component
+- Optimize image file sizes and consider lazy loading for performance.
+`,
+    },
+  ],
+  related: [],
+};
+
+export default data;

package/src/surfaces/customer-account/components/ImageGroup/ImageGroup.ts

@@ -0,0 +1,35 @@
+import {createRemoteComponent} from '@remote-ui/core';
+
+export interface ImageGroupProps {
+  /**
+   * Changes the layout of the images.
+   *
+   * @default "grid"
+   */
+  variant?: 'grid' | 'inline-stack';
+
+  /**
+   * A label that describes the purpose or contents of the image group. When set,
+   * it will be announced to users using assistive technologies and will
+   * provide them with more context.
+   */
+  accessibilityLabel?: string;
+
+  /**
+   * Indicates that the image group is in a loading state.
+   *
+   * When `true`, the image group show a loading indicator.
+   *
+   * @defaultValue false
+   */
+  loading?: boolean;
+
+  /**
+   * Indicates the total number of items that could be displayed in the image group. It is used to determine the remaining number to show when all the available image slots have been filled.
+   */
+  totalItems?: number;
+}
+
+export const ImageGroup = createRemoteComponent<'ImageGroup', ImageGroupProps>(
+  'ImageGroup',
+);

package/src/surfaces/customer-account/components/ImageGroup/examples/basic-ImageGroup-js.example.ts

@@ -0,0 +1,38 @@
+import {
+  Image,
+  ImageGroup,
+  View,
+  extension,
+} from '@shopify/ui-extensions/customer-account';
+
+export default extension(
+  'customer-account.page.render',
+  (root, api) => {
+    renderApp(root, api);
+  },
+)
+
+function renderApp(root, api) {
+  const firstImage = root.createComponent(Image, {
+    source: "../assets/flower.jpg"
+  });
+
+  const secondeImage = root.createComponent(Image, {
+    source: "../assets/flower.jpg"
+  });
+
+  const thirdImage = root.createComponent(Image, {
+    source: "../assets/flower.jpg"
+  });
+
+  const imageGroup = root.createComponent(ImageGroup);
+
+  imageGroup.append(firstImage);
+  imageGroup.append(secondeImage);
+  imageGroup.append(thirdImage);
+
+  const view = root.createComponent(View, {maxInlineSize: 300});
+  view.append(imageGroup);
+
+  root.append(view);
+}

package/src/surfaces/customer-account/components/ImageGroup/index.ts

@@ -0,0 +1,2 @@
+export {ImageGroup} from './ImageGroup';
+export type {ImageGroupProps} from './ImageGroup';

package/src/surfaces/customer-account/components/Menu/Menu.doc.ts

@@ -0,0 +1,80 @@
+import type {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'Menu',
+  description:
+    'Use a menu to display a list of actions in a popover. Actions can open a modal, trigger an event, or link to an external page.',
+  thumbnail: 'menu-thumbnail.png',
+  requires: '',
+  isVisualComponent: true,
+  type: '',
+  definitions: [
+    {
+      title: 'MenuProps',
+      description: '',
+      type: 'MenuProps',
+      filePath: 'components/Menu/Menu.ts',
+    },
+    {
+      title: 'ButtonProps children',
+      description:
+        'The Menu component exclusively accepts Button elements with restricted props as its children. The `appearance` prop will always be set to monochrome by default.',
+      type: 'Docs_Menu_Button_Action',
+    },
+  ],
+  category: 'components',
+  defaultExample: {
+    image: 'menu-default.png',
+    altText: 'An example of a Menu with three actions.',
+    codeblock: {
+      title: 'Basic Menu',
+      tabs: [
+        {
+          title: 'React',
+          code: '../../../../../../ui-extensions-react/src/surfaces/customer-account/components/Menu/examples/basic-Menu-react.example.tsx',
+          language: 'tsx',
+        },
+        {
+          title: 'JS',
+          code: './examples/basic-Menu-js.example.ts',
+          language: 'js',
+        },
+      ],
+    },
+  },
+  subSections: [
+    {
+      type: 'Generic',
+      anchorLink: 'best-practices',
+      title: 'Best Practices',
+      sectionContent: `
+### Consolidate actions into one menu
+
+- Use the menu component in the upper-right corner of full-page extensions, to be consistent with the **Order status** page.
+- Use menus to consolidate page-level actions, instead of adding multiple buttons around the page.
+
+![The “Don’t do” example shows 3 separate action buttons on a subscription page. The “Do” example shows the same 3 actions consolidated into one menu.](/assets/templated-apis-screenshots/customer-account-ui-extensions/unstable/menu-dont-do.png)
+
+### Content guidelines
+
+When writing button labels:
+- Aim for 2 words (verb and noun).
+- Lead with a strong verb that encourages action.
+- Avoid unnecessary words and articles such as “the,” “an,” or “a.”
+- Use sentence case.
+
+![A button that follows the content guidelines says “Skip order”. A button that does not meet the content guidelines says “Skip this order”.](/assets/templated-apis-screenshots/customer-account-ui-extensions/unstable/menu-labels.png)
+`,
+    },
+  ],
+  related: [
+    {
+      name: 'Popover',
+      subtitle: 'Component',
+      url: '../../../checkout-ui-extensions/unstable/components/overlays/popover',
+      type: 'Component',
+    },
+  ],
+};
+
+export default data;