@shopify/ui-extensions 2022.10.5 → 2023.4.0

package/src/surfaces/checkout/components/Modal/examples/basic-modal.example.ts

@@ -0,0 +1,44 @@
+import {
+  extension,
+  Button,
+  Link,
+  Modal,
+  TextBlock,
+} from '@shopify/ui-extensions/checkout';
+
+extension('Checkout::Dynamic::Render', (root, {ui}) => {
+  const modalFragment = root.createFragment();
+  const modal = root.createComponent(
+    Modal,
+    {id: 'my-modal', title: 'Return policy', padding: true},
+    [
+      root.createComponent(
+        TextBlock,
+        undefined,
+        'We have a 30-day return policy, which means you have 30 days after receiving your item to request a return.',
+      ),
+      root.createComponent(
+        TextBlock,
+        undefined,
+        'To be eligible for a return, your item must be in the same condition that you received it, unworn or unused, with tags, and in its original packaging. You’ll also need the receipt or proof of purchase.',
+      ),
+      root.createComponent(
+        Button,
+        {
+          onPress() {
+            ui.overlay.close('my-modal');
+          },
+        },
+        'Close',
+      ),
+    ],
+  );
+  modalFragment.appendChild(modal);
+  const link = root.createComponent(
+    Link,
+    {overlay: modalFragment},
+    'Return policy',
+  );
+
+  root.appendChild(link);
+});

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

@@ -0,0 +1,41 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'PhoneField',
+  description:
+    'A PhoneField is an input field that merchants can type into optimized for phone numbers with a country code base auto-formatting. The country code is required for the initial render of the field but it can be overriden later by the user either by selecting a country in the country selection dropdown or by manually editing the country phone code directly in the text field.',
+  requires: '',
+  isVisualComponent: true,
+  thumbnail: 'phonefield-thumbnail.png',
+  type: '',
+  definitions: [
+    {
+      title: 'PhoneFieldProps',
+      description: '',
+      type: 'PhoneFieldProps',
+    },
+  ],
+  category: 'Components',
+  subCategory: 'Forms',
+  defaultExample: {
+    image: 'phonefield-default.png',
+    codeblock: {
+      title: 'Basic PhoneField',
+      tabs: [
+        {
+          title: 'React',
+          code: '../../../../../../ui-extensions-react/src/surfaces/checkout/components/PhoneField/examples/basic-phonefield.example.tsx',
+          language: 'tsx',
+        },
+        {
+          title: 'JS',
+          code: './examples/basic-phonefield.example.ts',
+          language: 'js',
+        },
+      ],
+    },
+  },
+  related: [],
+};
+
+export default data;

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

@@ -1,26 +1,94 @@
-import {createRemoteComponent} from '@remote-ui/core';
-
-import type {TextFieldProps} from '../TextField/TextField';
-
-export interface PhoneFieldProps
-  extends Pick<
-    TextFieldProps<string>,
-    | 'autocomplete'
-    | 'id'
-    | 'icon'
-    | 'accessory'
-    | 'name'
-    | 'label'
-    | 'accessibilityDescription'
-    | 'value'
-    | 'required'
-    | 'error'
-    | 'disabled'
-    | 'readonly'
-    | 'onFocus'
-    | 'onBlur'
-    | 'maxLength'
-  > {
+import {createRemoteComponent, RemoteFragment} from '@remote-ui/core';
+
+import {Autocomplete} from '../shared';
+import {IconSource} from '../Icon/Icon';
+
+export interface PhoneFieldProps {
+  /**
+   * Any content to render at the end of the text field. Commonly used
+   * to display an icon that opens a tooltip providing more information about the field.
+   */
+  accessory?: string | RemoteFragment;
+
+  /**
+   * A detailed description for screen readers.
+   */
+  accessibilityDescription?: string;
+
+  /**
+   * A hint as to the intended content of the field.
+   *
+   * When set to `true`, this property indicates that the field should support
+   * autofill, but you do not have any more semantic information on the intended
+   * contents.
+   *
+   * When set to `false`, you are indicating that this field contains sensitive
+   * information, or contents that are never saved, like one-time codes.
+   *
+   * Alternatively, you can provide an `Autocomplete` object, which describes the
+   * specific data you would like to be entered into this field during autofill.
+   */
+  autocomplete?: Autocomplete | boolean;
+
+  /**
+   * Whether the field can be modified.
+   */
+  disabled?: 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;
+
+  /**
+   * An icon to render at the start or end of the field.
+   * It will render at the start by default.
+   */
+  icon?: IconSource | {source: IconSource; position?: 'start' | 'end'};
+
+  /**
+   * A unique identifier for the field. When no `id` is set,
+   * a globally unique value will be used instead.
+   */
+  id?: string;
+
+  /**
+   * Content to use as the field label. This value is also used as the placeholder
+   * when the field is empty.
+   */
+  label: string;
+
+  /**
+   * Specifies the maximum number of characters allowed.
+   */
+  maxLength?: number;
+
+  /**
+   * An identifier for the field that is unique within the nearest
+   * containing `Form` component.
+   */
+  name?: string;
+
+  /**
+   * Whether the field is read-only.
+   */
+  readonly?: 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;
+
+  /**
+   * The current value for the field. If omitted, the field will be empty. You should
+   * update this value in response to the `onChange` callback.
+   */
+  value?: string;
+
   /**
    * Callback when the buyer has **finished editing** a field or pressed the country dropdown.
    * Unlike `onChange` callbacks you may be familiar with from Polaris or other React component libraries,
@@ -62,6 +130,14 @@ export interface PhoneFieldProps
    * This callback is called with the current formatted value.
    */
   onInput?(value: string): void;
+  /**
+   * Callback when input is focused.
+   */
+  onFocus?(): void;
+  /**
+   * Callback when focus is removed.
+   */
+  onBlur?(): void;
 }
 
 /**

package/src/surfaces/checkout/components/PhoneField/examples/basic-phonefield.example.ts

@@ -1,6 +1,6 @@
-import {extend, PhoneField} from '@shopify/ui-extensions/checkout';
+import {extension, PhoneField} from '@shopify/ui-extensions/checkout';
 
-extend('Checkout::Dynamic::Render', (root) => {
+extension('Checkout::Dynamic::Render', (root) => {
   const phoneField = root.createComponent(PhoneField, {
     label: 'Phone',
     value: '1 (555) 555-5555',

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

@@ -0,0 +1,50 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'Popover',
+  description:
+    'Popovers are similar to tooltips. They are small overlays that open on demand after a user interaction. The difference is that the popover can contain more content, without cluttering the page. They must be specified inside the `overlay` prop of an activator component (`Button`, `Link` or `Pressable`).\n\nThe library takes care of applying the WAI-ARIA Popover Widget pattern automatically for the activator and the popover content.',
+  requires: '',
+  isVisualComponent: true,
+  thumbnail: 'popover-thumbnail.png',
+  type: '',
+  definitions: [
+    {
+      title: 'PopoverProps',
+      description: '',
+      type: 'PopoverProps',
+    },
+  ],
+  category: 'Components',
+  subCategory: 'Overlays',
+  defaultExample: {
+    image: 'popover-default.png',
+    codeblock: {
+      title: 'Basic Popover',
+      tabs: [
+        {
+          title: 'React',
+          code: '../../../../../../ui-extensions-react/src/surfaces/checkout/components/Popover/examples/basic-popover.example.tsx',
+          language: 'tsx',
+        },
+        {
+          title: 'JS',
+          code: './examples/basic-popover.example.ts',
+          language: 'js',
+        },
+      ],
+    },
+  },
+  subSections: [
+    {
+      type: 'Generic',
+      anchorLink: 'best-practices',
+      title: 'Best Practices',
+      sectionContent:
+        'Use popovers if:\n\n- The intent is to ask the customer for information.\n\n- It’s possible to use at most two rows of input fields to get the information.',
+    },
+  ],
+  related: [],
+};
+
+export default data;

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

@@ -0,0 +1,45 @@
+import {createRemoteComponent} from '@remote-ui/core';
+
+import type {Alignment, IdProps, SizingProps, SpacingProps} from '../shared';
+
+export type PopoverPosition =
+  | 'inlineStart'
+  | 'inlineEnd'
+  | 'blockStart'
+  | 'blockEnd';
+
+export interface PopoverProps
+  extends IdProps,
+    Pick<SizingProps, 'maxInlineSize' | 'minInlineSize'>,
+    Pick<SpacingProps, 'padding'> {
+  /**
+   * Position the Popover relative to the activator.
+   * @defaultValue 'blockStart'
+   */
+  position?: PopoverPosition;
+  /**
+   * Align the Popover in the axis determined by the position.
+   * @defaultValue 'center'
+   */
+  alignment?: Alignment;
+  /**
+   * Callback to run when the Popover is opened
+   */
+  onOpen?: () => void;
+  /**
+   * Callback to run when the Popover is closed
+   */
+  onClose?: () => void;
+}
+
+/**
+ * Popovers are similar to tooltips. They are small overlays that open on demand after a user interaction.
+ * The difference is that the popover can contain more content, without cluttering the page.
+ * They must be specified inside the `overlay` prop of an activator component (`Button`, `Link` or `Pressable`).
+ *
+ * The library takes care of applying the WAI-ARIA Popover Widget pattern automatically for the activator
+ * and the popover content.
+ */
+export const Popover = createRemoteComponent<'Popover', PopoverProps>(
+  'Popover',
+);

package/src/surfaces/checkout/components/Popover/examples/basic-popover.example.ts

@@ -0,0 +1,30 @@
+import {
+  extension,
+  Pressable,
+  Popover,
+  View,
+  TextBlock,
+} from '@shopify/ui-extensions/checkout';
+
+extension('Checkout::Dynamic::Render', (root) => {
+  const popoverFragment = root.createFragment();
+  const popover = root.createComponent(Popover, {}, [
+    root.createComponent(View, {maxInlineSize: 200, padding: 'base'}, [
+      root.createComponent(TextBlock, {}, 'A thoughtful way to pay'),
+      root.createComponent(TextBlock, {}, 'Tap don’t type'),
+      root.createComponent(
+        TextBlock,
+        {},
+        'Shop Pay remembers your important details, so you can fill carts, not forms. And everything is encrypted so you can speed safely through checkout.',
+      ),
+    ]),
+  ]);
+  popoverFragment.appendChild(popover);
+  const pressable = root.createComponent(
+    Pressable,
+    {overlay: popoverFragment},
+    'More info',
+  );
+
+  root.appendChild(pressable);
+});

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

@@ -0,0 +1,41 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'Pressable',
+  description:
+    'Pressable is a generic interactive component. It shares the same styling properties as View but also adds pressable behavior, meaning that you can execute some logic in response to user interaction. Use this component for creating interactive elements without the default styling that comes with `Button` and `Link`.',
+  requires: '',
+  thumbnail: 'pressable-thumbnail.png',
+  isVisualComponent: true,
+  type: '',
+  definitions: [
+    {
+      title: 'PressableProps',
+      description: '',
+      type: 'PressableProps',
+    },
+  ],
+  category: 'Components',
+  subCategory: 'Actions',
+  defaultExample: {
+    image: 'pressable-default.png',
+    codeblock: {
+      title: 'Basic Pressable',
+      tabs: [
+        {
+          title: 'React',
+          code: '../../../../../../ui-extensions-react/src/surfaces/checkout/components/Pressable/examples/basic-pressable.example.tsx',
+          language: 'tsx',
+        },
+        {
+          title: 'JS',
+          code: './examples/basic-pressable.example.ts',
+          language: 'js',
+        },
+      ],
+    },
+  },
+  related: [],
+};
+
+export default data;

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

@@ -10,15 +10,18 @@ import type {
   Display,
   ButtonAccessibilityRole,
   OverlayActivatorProps,
+  DisclosureActivatorProps,
+  CornerProps,
+  Opacity,
 } from '../shared';
-import type {ViewProps} from '../View/View';
 
 export interface PressableProps
   extends BorderProps,
+    CornerProps,
     SizingProps,
     SpacingProps,
     OverlayActivatorProps,
-    Pick<ViewProps, 'opacity'> {
+    DisclosureActivatorProps {
   /**
    * Changes the display of the Pressable.
    *
@@ -116,6 +119,26 @@ export interface PressableProps
    * Position children along the main axis
    */
   inlineAlignment?: MaybeResponsiveConditionalStyle<InlineAlignment>;
+
+  /**
+   * Sets the opacity of the View. The opacity will be applied to the background as well as all
+   * the children of the View. Use carefully as this could decrease the contrast ratio between
+   * the background and foreground elements, resulting in unreadable and inaccessible text.
+   */
+  opacity?: Opacity;
+
+  /**
+   * Sets the overflow behavior of the element.
+   *
+   * `hidden`: clips the content when it is larger than the element’s container.
+   * The element will not be scrollable and the users will not be able
+   * to access the clipped content by dragging or using a scroll wheel.
+   *
+   * `visible`: the content that extends beyond the element’s container is visible.
+   *
+   * @default 'visible'
+   */
+  overflow?: 'hidden' | 'visible';
 }
 
 /**

package/src/surfaces/checkout/components/Pressable/examples/basic-pressable.example.ts

@@ -1,23 +1,23 @@
 import {
-  extend,
+  extension,
   Icon,
   InlineLayout,
   Pressable,
   Text,
 } from '@shopify/ui-extensions/checkout';
 
-extend('Checkout::Dynamic::Render', (root) => {
+extension('Checkout::Dynamic::Render', (root) => {
   const pressable = root.createComponent(
     Pressable,
     {
       border: 'base',
-      borderRadius: 'base',
+      cornerRadius: 'base',
       padding: 'base',
       onPress: () => console.log('onPress event'),
     },
     [
       root.createComponent(InlineLayout, {columns: ['fill', 'auto']}, [
-        root.createComponent(Text, {}, 'Pressable'),
+        root.createComponent(Text, {}, 'Details'),
         root.createComponent(Icon, {source: 'chevronDown', size: 'small'}),
       ]),
     ],

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

@@ -0,0 +1,41 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'ScrollView',
+  description:
+    'ScrollView is a container for long form content, such as order summary line items, that allows for scrolling so customers can expose more content as they view.',
+  requires: '',
+  isVisualComponent: true,
+  thumbnail: 'scrollview-thumbnail.png',
+  type: '',
+  definitions: [
+    {
+      title: 'ScrollViewProps',
+      description: '',
+      type: 'ScrollViewProps',
+    },
+  ],
+  category: 'Components',
+  subCategory: 'Structure',
+  defaultExample: {
+    image: 'scrollview-default.png',
+    codeblock: {
+      title: 'Basic Scrollview',
+      tabs: [
+        {
+          title: 'React',
+          code: '../../../../../../ui-extensions-react/src/surfaces/checkout/components/ScrollView/examples/basic-scrollview.example.tsx',
+          language: 'tsx',
+        },
+        {
+          title: 'JS',
+          code: './examples/basic-scrollview.example.ts',
+          language: 'js',
+        },
+      ],
+    },
+  },
+  related: [],
+};
+
+export default data;

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

@@ -1,6 +1,6 @@
 import {createRemoteComponent} from '@remote-ui/core';
 
-import {BorderProps, SizingProps, SpacingProps} from '../shared';
+import {BorderProps, CornerProps, SizingProps, SpacingProps} from '../shared';
 
 export interface ScrollViewEvent {
   /**
@@ -25,6 +25,7 @@ export interface ScrollViewEvent {
 
 export interface ScrollViewProps
   extends BorderProps,
+    CornerProps,
     SizingProps,
     SpacingProps {
   /**
@@ -65,6 +66,10 @@ export interface ScrollViewProps
    * Callback function that is called when the scroll position reaches one of the edges.
    */
   onScrolledToEdge?: (args: ScrollViewEvent) => void;
+  /**
+   * A unique identifier for the component.
+   */
+  id?: string;
 }
 
 /**

package/src/surfaces/checkout/components/ScrollView/examples/basic-scrollview.example.ts

@@ -1,6 +1,6 @@
-import {extend, ScrollView, View} from '@shopify/ui-extensions/checkout';
+import {extension, ScrollView, View} from '@shopify/ui-extensions/checkout';
 
-extend('Checkout::Dynamic::Render', (root) => {
+extension('Checkout::Dynamic::Render', (root) => {
   const scrollView = root.createComponent(ScrollView, {maxBlockSize: 400}, [
     root.createComponent(
       View,

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

@@ -0,0 +1,50 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'Select',
+  description:
+    'Selects let buyers choose one option from an options menu. Consider select when you have 4 or more options, to avoid cluttering the interface.',
+  requires: '',
+  thumbnail: 'select-thumbnail.png',
+  isVisualComponent: true,
+  type: '',
+  definitions: [
+    {
+      title: 'SelectProps',
+      description: '',
+      type: 'SelectProps',
+    },
+  ],
+  category: 'Components',
+  subCategory: 'Forms',
+  defaultExample: {
+    image: 'select-default.png',
+    codeblock: {
+      title: 'Basic Select',
+      tabs: [
+        {
+          title: 'React',
+          code: '../../../../../../ui-extensions-react/src/surfaces/checkout/components/Select/examples/basic-select.example.tsx',
+          language: 'tsx',
+        },
+        {
+          title: 'JS',
+          code: './examples/basic-select.example.ts',
+          language: 'js',
+        },
+      ],
+    },
+  },
+  subSections: [
+    {
+      type: 'Generic',
+      anchorLink: 'best-practices',
+      title: 'Best Practices',
+      sectionContent:
+        '- Use this component when customers need to choose between four or more predefined options.\n\n- Have a default option selected whenever possible. Use Select as placeholder text if there’s no logical default option.',
+    },
+  ],
+  related: [],
+};
+
+export default data;

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

@@ -2,7 +2,7 @@ import {createRemoteComponent} from '@remote-ui/core';
 
 import {Autocomplete} from '../shared';
 
-interface Option {
+export interface SelectOptionProps {
   /**
    * The value that will be passed to the select’s `onChange` callback
    * when this option is selected.
@@ -43,7 +43,7 @@ export interface SelectProps {
   /**
    * The options a buyer can select from.
    */
-  options: Option[];
+  options: SelectOptionProps[];
   /**
    * Whether the field needs a value. This requirement adds semantic value
    * to the field, but it will not cause an error to appear automatically.

package/src/surfaces/checkout/components/Select/examples/basic-select.example.ts

@@ -1,6 +1,6 @@
-import {extend, Select} from '@shopify/ui-extensions/checkout';
+import {extension, Select} from '@shopify/ui-extensions/checkout';
 
-extend('Checkout::Dynamic::Render', (root) => {
+extension('Checkout::Dynamic::Render', (root) => {
   const select = root.createComponent(Select, {
     label: 'Country',
     value: '2',