@shopify/ui-extensions 2024.4.2 → 2024.10.0

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

@@ -0,0 +1,19 @@
+import {createRemoteComponent} from '@remote-ui/core';
+import type {IdProps} from '../shared';
+
+export interface MenuProps extends IdProps {
+  /**
+   * A label to describe the purpose of the menu that is announced by screen readers.
+   */
+  accessibilityLabel?: string;
+  /**
+   * Callback to run when the Menu is opened
+   */
+  onOpen?: () => void;
+  /**
+   * Callback to run when the Menu is closed
+   */
+  onClose?: () => void;
+}
+
+export const Menu = createRemoteComponent<'Menu', MenuProps>('Menu');

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

@@ -0,0 +1,26 @@
+import {Menu, Button, 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 menuFragment = root.createFragment();
+  const menu = root.createComponent(Menu, {}, [
+    root.createComponent(
+      Button,
+      {onPress: () => console.log('Submit problem')},
+      'Submit problem',
+    ),
+    root.createComponent(Button, {to: 'https://shopify.com'}, 'Request return'),
+    root.createComponent(Button, {appearance: 'critical'}, 'Cancel order'),
+  ]);
+  menuFragment.appendChild(menu);
+  const button = root.createComponent(
+    Button,
+    {overlay: menuFragment},
+    'Manage',
+  );
+
+  root.appendChild(button);
+}

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

@@ -0,0 +1 @@
+export {Menu, type MenuProps} from './Menu';

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

@@ -0,0 +1,76 @@
+import type {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'Page',
+  description:
+    'The outer wrapper of the page—including the page title, subtitle, and page-level actions—displayed in a familiar and consistent style that sets expectations about the purpose of the page.',
+  thumbnail: 'page-thumbnail.png',
+  requires: '',
+  isVisualComponent: true,
+  type: '',
+  definitions: [
+    {
+      title: 'PageProps',
+      description: '',
+      type: 'PageProps',
+    },
+    {
+      title: 'ButtonProps primaryAction',
+      description:
+        'Supported props for Buttons used inside Page `primaryAction` prop.<br><br>`children` only support text.',
+      type: 'Docs_Page_Button_PrimaryAction',
+    },
+    {
+      title: 'ButtonProps secondaryAction',
+      description:
+        'Supported props for Button used inside Page `secondaryAction` prop.<br><br>`children` are not supported.<br>Use `accessibilityLabel` instead.',
+      type: 'Docs_Page_Button_SecondaryAction',
+    },
+  ],
+  category: 'components',
+  defaultExample: {
+    image: 'page-preview.png',
+    altText:
+      'An example of how the Page component is used to structure the page title, description, order action buttons on the Order status page.',
+    codeblock: {
+      title: 'Basic Page',
+      tabs: [
+        {
+          title: 'React',
+          code: '../../../../../../ui-extensions-react/src/surfaces/customer-account/components/Page/examples/basic-Page-react.example.tsx',
+          language: 'tsx',
+        },
+        {
+          title: 'JS',
+          code: './examples/basic-Page-js.example.ts',
+          language: 'js',
+        },
+      ],
+    },
+  },
+  subSections: [
+    {
+      type: 'Generic',
+      anchorLink: 'best-practices',
+      title: 'Best Practices',
+      sectionContent: `
+**Title**
+- Set clear expectations about the purpose and main topic of the page.
+- Aim for 1-3 words.
+- Use sentence case.
+
+**Subtitle**
+- Use to provide additional context or information that enhances the customer’s understanding of the page.
+- Use subtitles sparingly and only when they add useful information that is distinct from the title.
+
+**Buttons**
+- Use for page-level actions only.
+- If there is a single primary action for the page, display it as a primary button. Display all other page-level actions as secondary buttons.
+- See [UX guidelines](/docs/apps/customer-accounts/order-action-menu-extensions/ux-guidelines) to learn more about the button logic for order actions.
+`,
+    },
+  ],
+  related: [],
+};
+
+export default data;

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

@@ -0,0 +1,51 @@
+import {createRemoteComponent} from '@remote-ui/core';
+import type {RemoteFragment} from '@remote-ui/core';
+
+export interface PageProps {
+  /**
+   * The text to be used as title.
+   */
+  title: string;
+
+  /**
+   * The text to be used as subtitle.
+   */
+  subtitle?: string;
+
+  /**
+   * The action grouping, provided as button(s), that is placed in the primary position of the page.
+   */
+  primaryAction?: RemoteFragment;
+
+  /**
+   * Label for the primary action grouping. If a label is not provided, default text is used.
+   *
+   * @defaultValue "More actions"
+   */
+  primaryActionLabel?: string;
+
+  /**
+   * Accessibility label for the primary action grouping. If an accessibility label is not provided,
+   * default text is used.
+   *
+   * @defaultValue "More actions"
+   */
+  primaryActionAccessibilityLabel?: string;
+
+  /**
+   * The action grouping, provided as button(s), that is placed in the secondary position of the page.
+   */
+  secondaryAction?: RemoteFragment;
+
+  /**
+   * Indicates that the page is in a loading state.
+   *
+   * When `true`, the page shows loading indicators for the UI elements that it is owns.
+   * The page is not responsible for the loading indicators of any content that is passed as `children`.
+   *
+   * @defaultValue false
+   */
+  loading?: boolean;
+}
+
+export const Page = createRemoteComponent<'Page', PageProps>('Page');

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

@@ -0,0 +1,35 @@
+import {
+  Page,
+  Button,
+  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 primaryAction = root.createFragment();
+  await primaryAction.append(root.createComponent(Button, {onPress: () => {console.log("primary action 1")}}, 'Buy again primary 1'));
+  await primaryAction.append(root.createComponent(Button, {onPress: () => {console.log("primary action 2")}}, 'Buy again primary 2'));
+  await primaryAction.append(root.createComponent(Button, {onPress: () => {console.log("primary action 3")}}, 'Buy again primary 3'));
+
+  const secondaryAction = root.createFragment();
+  await secondaryAction.append(root.createComponent(Button, {accessibilityLabel: 'Button', onPress: () => {}}))
+
+  const page = root.createComponent(
+    Page,
+    {
+      title: "Order #1411",
+      subtitle: "Confirmed Oct 5",
+      primaryAction,
+      primaryActionLabel: "Manage",
+      secondaryAction,
+      },
+    root.createComponent('View', {}, "Content")
+  )
+  root.append(page);
+}

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

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

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

@@ -0,0 +1,33 @@
+import {createRemoteComponent} from '@remote-ui/core';
+
+type PolicyType = 'refund';
+
+// The interface is duplicated in the `ui-extensions-react` package because it no longer can be imported
+// More on the PR: https://github.com/Shopify/ui-extensions/pull/1399
+export interface PolicyModalProps {
+  /**
+   * Whether the modal should be rendered.
+   * Modal is a controlled component, so you must keep the state of the `open` prop yourself.
+   */
+  open: boolean;
+  /**
+   * Callback when either the close button, the backdrop, or the `escape` key is pressed.
+   * `onClose` is only called while the modal is open and attempts to be closed,
+   * not when it exits the viewport.
+   * You’ll usually want to use this callback to set the `open` prop to `false`.
+   */
+  onClose: () => void;
+  /**
+   * A title rendered as a `Heading` at the top of the modal.
+   */
+  title: string;
+  /**
+   * Type of policy to render.
+   */
+  type: PolicyType;
+}
+
+export const PolicyModal = createRemoteComponent<
+  'PolicyModal',
+  PolicyModalProps
+>('PolicyModal');

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

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

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

@@ -0,0 +1,62 @@
+import type {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'ResourceItem',
+  description:
+    'Use to represent a specific object within a collection, that a customer can take action on. For example, a list of active subscriptions or redeemable offers, in a style consistent with the order index page.',
+  thumbnail: 'resourceitem-thumbnail.png',
+  requires: '',
+  isVisualComponent: true,
+  type: '',
+  definitions: [
+    {
+      title: 'ResourceItemProps',
+      description: '',
+      type: 'ResourceItemProps',
+    },
+    {
+      title: 'ButtonProps action',
+      description:
+        'Supported props for Buttons used inside ResourceItem `action` prop.<br><br>`children` only support text.',
+      type: 'Docs_ResourceItem_Button_Action',
+    },
+  ],
+  category: 'components',
+  defaultExample: {
+    image: 'resourceitem-preview.png',
+    altText:
+      'An example of how the ResourceItem component is used to represent one order in the grid view of the Order index page.',
+    codeblock: {
+      title: 'ResourceItem',
+      tabs: [
+        {
+          title: 'React',
+          code: '../../../../../../ui-extensions-react/src/surfaces/customer-account/components/ResourceItem/examples/basic-ResourceItem-react.example.tsx',
+          language: 'tsx',
+        },
+        {
+          title: 'JS',
+          code: './examples/basic-ResourceItem-js.example.ts',
+          language: 'js',
+        },
+      ],
+    },
+  },
+  subSections: [
+    {
+      type: 'Generic',
+      anchorLink: 'best-practices',
+      title: 'Best Practices',
+      sectionContent: `
+- Group related information.
+- Structure your content so it’s easy for customers to scan to the most important information.
+- Use images to complement text content.
+- If there is a single primary action for the object, display it as a primary button. Display other object-level actions as secondary buttons.
+- See [UX guidelines](/docs/apps/customer-accounts/order-action-menu-extensions/ux-guidelines) to learn more about the button logic for order actions.
+`,
+    },
+  ],
+  related: [],
+};
+
+export default data;

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

@@ -0,0 +1,41 @@
+import {createRemoteComponent} from '@remote-ui/core';
+import type {RemoteFragment} from '@remote-ui/core';
+import {LinkProps} from '../shared-checkout-components';
+
+export interface ResourceItemProps
+  extends Pick<LinkProps, 'accessibilityLabel' | 'to' | 'onPress'> {
+  /**
+   * The action grouping for the item, provided as buttons.
+   */
+  action?: RemoteFragment;
+
+  /**
+   * Label for the action grouping. If a label is not provided, default text is used.
+   *
+   * @defaultValue "More actions"
+   */
+  actionLabel?: string;
+
+  /**
+   * Accessibility label for the action grouping. If an accessibility label is not provided,
+   * default text is used.
+   *
+   * @defaultValue "More actions"
+   */
+  actionAccessibilityLabel?: string;
+
+  /**
+   * Indicates that the item is in a loading state.
+   *
+   * When `true`, the item shows loading indicators for the UI elements that it is owns.
+   * The item is not responsible for the loading indicators of any content that is passed as `children`.
+   *
+   * @defaultValue false
+   */
+  loading?: boolean;
+}
+
+export const ResourceItem = createRemoteComponent<
+  'ResourceItem',
+  ResourceItemProps
+>('ResourceItem');

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

@@ -0,0 +1,59 @@
+import {
+  ResourceItem,
+  Button,
+  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 actionFragment = root.createFragment();
+
+  const primaryButton = root.createComponent(Button, {
+    kind: 'primary',
+    onPress: () => {},
+  });
+
+  primaryButton.append(root.createText('Pay now'))
+
+  const secondButton = root.createComponent(Button, {
+    kind: 'secondary',
+    onPress: () => {},
+  });
+
+  secondButton.append(root.createText('Second button'))
+
+  const thirdButton = root.createComponent(Button, {
+    kind: 'secondary',
+    onPress: () => {},
+  });
+
+  thirdButton.append(root.createText('Third button'))
+
+  actionFragment.append(primaryButton);
+  actionFragment.append(secondButton);
+  actionFragment.append(thirdButton);
+
+  const resourceItem = root.createComponent(
+    ResourceItem,
+    {
+      accessibilityLabel: 'Resource Item',
+      onPress: () => {},
+      actionLabel: 'Manage',
+      action: actionFragment,
+    },
+    'Content',
+  );
+
+  const view = root.createComponent(View, {maxInlineSize: 300});
+  view.append(resourceItem);
+
+  root.append(view);
+}

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

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

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

@@ -1,2 +1,11 @@
 export * from './Card';
+export * from './CustomerAccountAction';
+export * from './DropZone';
+export * from './Page';
+export * from './Avatar';
+export * from './Menu';
+/* @internal */
+export * from './PolicyModal';
+export * from './ResourceItem';
+export * from './ImageGroup';
 export * from './shared-checkout-components';

package/src/surfaces/customer-account/components/shared-checkout-components.ts

@@ -78,15 +78,21 @@ export {
   type PressableProps,
   ProductThumbnail,
   type ProductThumbnailProps,
+  Progress,
+  type ProgressProps,
   Popover,
   type PopoverProps,
   type PopoverPosition,
+  QRCode,
+  type QRCodeProps,
   ScrollView,
   type ScrollViewProps,
   type ScrollViewEvent,
   Select,
   type SelectProps,
   type SelectOptionProps,
+  Sheet,
+  type SheetProps,
   SkeletonImage,
   type SkeletonImageProps,
   SkeletonText,
@@ -97,6 +103,8 @@ export {
   type SpinnerProps,
   Stepper,
   type StepperProps,
+  Switch,
+  type SwitchProps,
   Tag,
   type TagProps,
   Text,

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

@@ -0,0 +1,6 @@
+export interface IdProps {
+  /**
+   * A unique identifier for the component.
+   */
+  id?: string;
+}