@shopify/ui-extensions 2023.7.2 → 2024.1.0

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

@@ -0,0 +1,36 @@
+import {extension, Select} from '@shopify/ui-extensions/checkout';
+
+export default extension('purchase.checkout.block.render', (root) => {
+  const select = root.createComponent(Select, {
+    label: 'Pickup time',
+    value: '1',
+    options: [
+      {
+        value: '1',
+        label: '9:00 AM',
+      },
+      {
+        value: '2',
+        label: '9:30 AM',
+      },
+      {
+        value: '3',
+        label: '10:00 AM',
+      },
+      {
+        value: '4',
+        label: '10:30 AM',
+      },
+      {
+        value: '5',
+        label: '11:00 AM',
+      },
+      {
+        value: '6',
+        label: '11:30 AM',
+      },
+    ],
+  });
+
+  root.appendChild(select);
+});

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

@@ -31,7 +31,13 @@ export interface TextProps extends VisibilityProps {
    */
   appearance?: Extract<
     Appearance,
-    'accent' | 'subdued' | 'info' | 'success' | 'warning' | 'critical'
+    | 'accent'
+    | 'subdued'
+    | 'info'
+    | 'success'
+    | 'warning'
+    | 'critical'
+    | 'decorative'
   >;
 }
 

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

@@ -22,7 +22,13 @@ export interface TextBlockProps extends IdProps {
    */
   appearance?: Extract<
     Appearance,
-    'accent' | 'subdued' | 'info' | 'success' | 'warning' | 'critical'
+    | 'accent'
+    | 'subdued'
+    | 'info'
+    | 'success'
+    | 'warning'
+    | 'critical'
+    | 'decorative'
   >;
   /**
    * Align text along the main axis.

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

@@ -0,0 +1,48 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'ToggleButton',
+  description:
+    'Options inside a [ToggleButtonGroup](/docs/api/checkout-ui-extensions/components/forms/togglebuttongroup).',
+  thumbnail: 'togglebutton-thumbnail.png',
+  requires: '',
+  isVisualComponent: true,
+  type: '',
+  definitions: [
+    {
+      title: 'ToggleButtonProps',
+      description: '',
+      type: 'ToggleButtonProps',
+    },
+  ],
+  category: 'Components',
+  subCategory: 'Forms',
+  defaultExample: {
+    image: 'togglebutton-default.png',
+    codeblock: {
+      title: 'Basic ToggleButton',
+      tabs: [
+        {
+          title: 'React',
+          code: '../../../../../../ui-extensions-react/src/surfaces/checkout/components/ToggleButton/examples/basic-togglebutton.example.tsx',
+          language: 'tsx',
+        },
+        {
+          title: 'JS',
+          code: './examples/basic-togglebutton.example.ts',
+          language: 'js',
+        },
+      ],
+    },
+  },
+  related: [
+    {
+      name: 'ToggleButtonGroup',
+      subtitle: 'Component',
+      url: 'togglebuttongroup',
+      type: 'Component',
+    },
+  ],
+};
+
+export default data;

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

@@ -0,0 +1,29 @@
+import {createRemoteComponent} from '@remote-ui/core';
+
+export interface ToggleButtonProps {
+  /**
+   * A unique identifier for the toggle button.
+   */
+  id: string;
+  /**
+   * A label used for buyers using assistive technologies. When set, any
+   * `children` supplied to this component will not be announced to screen reader users.
+   */
+  accessibilityLabel?: string;
+  /**
+   * Disables the button, disallowing any interaction.
+   */
+  disabled?: boolean;
+  /**
+   * Callback when button is pressed.
+   */
+  onPress?(): void;
+}
+
+/**
+ * Options inside a `ToggleButtonGroup`.
+ */
+export const ToggleButton = createRemoteComponent<
+  'ToggleButton',
+  ToggleButtonProps
+>('ToggleButton');

package/src/surfaces/checkout/components/ToggleButton/examples/basic-togglebutton.example.ts

@@ -0,0 +1,20 @@
+import {
+  extension,
+  ToggleButtonGroup,
+  ToggleButton,
+} from '@shopify/ui-extensions/checkout';
+
+export default extension('purchase.checkout.block.render', (root) => {
+  const toggleButtonGroup = root.createComponent(
+    ToggleButtonGroup,
+    {
+      value: 'none',
+      onChange: (value) => {
+        console.log(`onChange event with value: ${value}`);
+      },
+    },
+    [root.createComponent(ToggleButton, {id: 'none'}, 'None')],
+  );
+
+  root.appendChild(toggleButtonGroup);
+});

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

@@ -0,0 +1,80 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+import {getExample} from '../../helper.docs';
+
+const togglebuttongroupTimePicking = getExample(
+  'ui-components/togglebuttongroup-time-picking',
+  ['jsx', 'js'],
+);
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'ToggleButtonGroup',
+  description:
+    '`ToggleButtonGroup` allows you to make a single choice out of the number of options provided. This is similar to the [ChoiceList](/docs/api/checkout-ui-extensions/components/forms/choicelist) component, but without controls such as checkbox or radio button.\n\nYou can utilize our layout components to arrange `ToggleButtonGroup`.',
+  thumbnail: 'togglebuttongroup-thumbnail.png',
+  requires: '',
+  isVisualComponent: true,
+  type: '',
+  definitions: [
+    {
+      title: 'ToggleButtonGroupProps',
+      description: '',
+      type: 'ToggleButtonGroupProps',
+    },
+  ],
+  category: 'Components',
+  subCategory: 'Forms',
+  defaultExample: {
+    image: 'togglebuttongroup-default.png',
+    codeblock: {
+      title: 'Basic ToggleButtonGroup',
+      tabs: [
+        {
+          title: 'React',
+          code: '../../../../../../ui-extensions-react/src/surfaces/checkout/components/ToggleButtonGroup/examples/basic-togglebuttongroup.example.tsx',
+          language: 'tsx',
+        },
+        {
+          title: 'JS',
+          code: './examples/basic-togglebuttongroup.example.ts',
+          language: 'js',
+        },
+      ],
+    },
+  },
+  subSections: [
+    {
+      type: 'Generic',
+      anchorLink: 'best-practices',
+      title: 'Best Practices',
+      sectionContent:
+        'ToggleButtonGroup is a component designed for streamlined single-choice selection, without any additional details associated with the selection. If you need to allow multiple selections or present associated details, it is recommended to use [ChoiceList](/docs/api/checkout-ui-extensions/components/forms/choicelist) instead.',
+      sectionSubContent: [
+        {
+          title: 'Label and order',
+          sectionContent:
+            'Use descriptive and concise labels for each Toggle button, and maintain consistency in the terminology used across options. Arrange the Toggle buttons in a logical order that makes sense to users. Consider factors such as alphabetical order, chronological order, or order of importance, depending on the context.',
+        },
+        {
+          title: 'Number of Toggle buttons',
+          sectionContent:
+            'Avoid overwhelming users with too many Toggle buttons. Ideally, limit the number of choices to a manageable amount, typically between 2 and 7, to prevent decision fatigue and maintain clarity.',
+        },
+      ],
+    },
+  ],
+  examples: {
+    description: '',
+    examples: [togglebuttongroupTimePicking],
+  },
+  related: [
+    {
+      name: 'ToggleButton',
+      subtitle: 'Component',
+      url: 'togglebutton',
+      type: 'Component',
+    },
+  ],
+};
+
+export default data;

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

@@ -0,0 +1,30 @@
+import {createRemoteComponent} from '@remote-ui/core';
+
+export interface ToggleButtonGroupProps<T extends string> {
+  /**
+   * An id of the selected button.
+   */
+  value: T;
+  /**
+   * Whether the button group is disabled.
+   */
+  disabled?: boolean;
+  /**
+   * A callback that is run whenever one of the buttons is pressed. This callback
+   * is called with a string or array of strings indicating the ids of buttons
+   * that should now be selected. When this component is
+   * [controlled](https://reactjs.org/docs/forms.html#controlled-components),
+   * you must store this value in state and reflect it back in the `value` prop.
+   */
+  onChange(value: T): void;
+}
+
+/**
+ * `ToggleButtonGroup` allows you to make a single choice out of the number of options provided.
+ * This is similar to the `ChoiceList` component, but without controls such as checkbox or radio button.
+ * You can utilize our layout components to arrange `ToggleButtonGroup`.
+ */
+export const ToggleButtonGroup = createRemoteComponent<
+  'ToggleButtonGroup',
+  ToggleButtonGroupProps<string>
+>('ToggleButtonGroup');

package/src/surfaces/checkout/components/ToggleButtonGroup/examples/basic-togglebuttongroup.example.ts

@@ -0,0 +1,76 @@
+import {
+  extension,
+  ToggleButtonGroup,
+  ToggleButton,
+  InlineLayout,
+  View,
+  BlockStack,
+  Text,
+} from '@shopify/ui-extensions/checkout';
+
+export default extension('purchase.checkout.block.render', (root) => {
+  const toggleButtonGroup = root.createComponent(
+    ToggleButtonGroup,
+    {
+      value: 'none',
+      onChange: (value) => {
+        console.log(`onChange event with value: ${value}`);
+      },
+    },
+    [
+      root.createComponent(InlineLayout, {spacing: 'base'}, [
+        root.createComponent(
+          ToggleButton,
+          {id: 'none'},
+          root.createComponent(
+            View,
+            {
+              blockAlignment: 'center',
+              inlineAlignment: 'center',
+              minBlockSize: 'fill',
+            },
+            'None',
+          ),
+        ),
+        root.createComponent(
+          ToggleButton,
+          {id: 'points-100'},
+          root.createComponent(
+            BlockStack,
+            {inlineAlignment: 'center', spacing: 'none'},
+            [
+              root.createComponent(Text, undefined, '100'),
+              root.createComponent(Text, {appearance: 'subdued'}, 'points'),
+            ],
+          ),
+        ),
+        root.createComponent(
+          ToggleButton,
+          {id: 'points-200'},
+          root.createComponent(
+            BlockStack,
+            {inlineAlignment: 'center', spacing: 'none'},
+            [
+              root.createComponent(Text, undefined, '200'),
+              root.createComponent(Text, {appearance: 'subdued'}, 'points'),
+            ],
+          ),
+        ),
+        root.createComponent(
+          ToggleButton,
+          {id: 'points-300'},
+          root.createComponent(
+            BlockStack,
+            {inlineAlignment: 'center', spacing: 'none'},
+            [
+              root.createComponent(Text, undefined, '300'),
+              root.createComponent(Text, {appearance: 'subdued'}, 'points'),
+            ],
+          ),
+        ),
+      ]),
+    ],
+  );
+
+  root.appendChild(toggleButtonGroup);
+});

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

@@ -2,6 +2,7 @@ import {createRemoteComponent} from '@remote-ui/core';
 
 import {MaybeResponsiveConditionalStyle} from '../../style';
 import type {
+  BackgroundProps,
   BlockAlignment,
   BorderProps,
   InlineAlignment,
@@ -101,7 +102,8 @@ export interface Translate {
 }
 
 export interface ViewProps
-  extends BorderProps,
+  extends Pick<BackgroundProps, 'background'>,
+    BorderProps,
     CornerProps,
     SizingProps,
     SpacingProps,

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

@@ -162,8 +162,11 @@ export type CornerRadiusDeprecated = 'tight' | 'loose';
 export interface BackgroundProps {
   /**
    * Adjust the background.
+   *
+   * @defaultValue 'transparent'
    */
   background?: MaybeConditionalStyle<Background>;
+
   /**
    * Sets one or multiple responsive background images.
    */
@@ -277,6 +280,8 @@ export interface SizingProps {
    * `` `${number}%` ``: size in percentages.
    *
    * `fill`: takes all the available space.
+   *
+   * See [MDN explanation of maxBlockSize](https://developer.mozilla.org/en-US/docs/Web/CSS/max-block-size).
    */
   maxBlockSize?: MaybeResponsiveConditionalStyle<
     number | `${number}%` | 'fill'
@@ -290,6 +295,8 @@ export interface SizingProps {
    * `` `${number}%` ``: size in percentages.
    *
    * `fill`: takes all the available space.
+   *
+   * See [MDN explanation of maxInlineSize](https://developer.mozilla.org/en-US/docs/Web/CSS/max-inline-size).
    */
   maxInlineSize?: MaybeResponsiveConditionalStyle<
     number | `${number}%` | 'fill'
@@ -302,7 +309,9 @@ export interface SizingProps {
    *
    * `` `${number}%` ``: size in percentages.
    *
-   * `fill`: takes all the available space.
+   * `fill`: takes all the available space.\
+   *
+   * See [MDN explanation of minInlineSize](https://developer.mozilla.org/en-US/docs/Web/CSS/min-inline-size).
    */
   minInlineSize?: MaybeResponsiveConditionalStyle<
     number | `${number}%` | 'fill'
@@ -316,6 +325,8 @@ export interface SizingProps {
    * `` `${number}%` ``: size in percentages.
    *
    * `fill`: takes all the available space.
+   *
+   * See [MDN explanation of minBlockSize](https://developer.mozilla.org/en-US/docs/Web/CSS/min-block-size).
    */
   minBlockSize?: MaybeResponsiveConditionalStyle<
     number | `${number}%` | 'fill'
@@ -335,7 +346,7 @@ export interface SpacingProps {
    *
    * - [`base`, `none`] means blockStart and blockEnd paddings are `base`, inlineStart and inlineEnd paddings are `none`
    *
-   * - [`base`, `none`, `large200`, `small200`] means blockStart padding is `base`, inlineEnd padding is `none`, blockEnd padding is `large200` and  blockStart padding is `small200`
+   * - [`base`, `none`, `loose`, `tight`] means blockStart padding is `base`, inlineEnd padding is `none`, blockEnd padding is `loose` and  blockStart padding is `tight`
    */
   padding?: MaybeResponsiveConditionalStyle<MaybeShorthandProperty<Spacing>>;
 }
@@ -467,42 +478,32 @@ export type Size =
 
 export type Spacing =
   | 'none'
-  | 'small500'
-  | 'small400'
-  | 'small300'
-  | 'small200'
-  | 'small100'
+  | 'extraTight'
+  | 'tight'
   | 'base'
-  | 'large100'
-  | 'large200'
-  | 'large300'
-  | 'large400'
-  | 'large500'
-  | SpacingDeprecated;
-
-/** @deprecated These values are deprecated and will eventually be removed.
- * Use the new values.
- *
- * `extraTight`: `small400`
- * `tight`: `small200`
- * `loose`: `large200`
- * `extraLoose`: `large500`
- */
-export type SpacingDeprecated = 'extraTight' | 'tight' | 'loose' | 'extraLoose';
+  | 'loose'
+  | 'extraLoose';
 
 export type Alignment = 'start' | 'center' | 'end';
 export type InlineAlignment = 'start' | 'center' | 'end';
 export type BlockAlignment = Alignment | 'baseline';
 
-export type Background = 'transparent' | 'color1' | 'color2' | 'color3';
+export type Background = 'transparent' | 'base' | 'subdued';
 export type BackgroundFit = 'cover' | 'contain';
 export type BackgroundPosition = 'top' | 'bottom' | 'left' | 'right' | 'center';
 export type BackgroundRepeat = 'repeat' | 'noRepeat';
 
 export type Appearance =
+  /** Takes the default color for the element set within the theme*/
+  | 'base'
   /** Conveys emphasis and draws attention to the element.*/
   | 'accent'
-  /** Conveys that the element is pressable, hoverable or otherwise interactive.*/
+  /** Conveys that the element is decorative. It takes the `decorative` color set within the theme.*/
+  | 'decorative'
+  /**
+   * Conveys that the element is pressable, hoverable or otherwise interactive.
+   * @deprecated Use `accent` instead.
+   */
   | 'interactive'
   /** Conveys a subdued or disabled state for the element.*/
   | 'subdued'

package/src/surfaces/checkout/components.ts

@@ -13,6 +13,15 @@ export type {BlockStackProps} from './components/BlockStack/BlockStack';
 export {Button} from './components/Button/Button';
 export type {ButtonProps} from './components/Button/Button';
 
+export {ConsentCheckbox} from './components/ConsentCheckbox/ConsentCheckbox';
+export type {ConsentCheckboxProps} from './components/ConsentCheckbox/ConsentCheckbox';
+
+export {ConsentPhoneField} from './components/ConsentPhoneField/ConsentPhoneField';
+export type {
+  ConsentPhoneFieldProps,
+  ConsentPolicy,
+} from './components/ConsentPhoneField/ConsentPhoneField';
+
 export {Checkbox} from './components/Checkbox/Checkbox';
 export type {CheckboxProps} from './components/Checkbox/Checkbox';
 
@@ -81,15 +90,41 @@ export type {ListProps} from './components/List/List';
 export {ListItem} from './components/ListItem/ListItem';
 export type {ListItemProps} from './components/ListItem/ListItem';
 
+export {LoginWithShop} from './components/LoginWithShop/LoginWithShop';
+export type {LoginWithShopProps} from './components/LoginWithShop/LoginWithShop';
+
+export {Map} from './components/Map/Map';
+export type {
+  MapProps,
+  MapLocation,
+  MapBounds,
+  MapZoom,
+} from './components/Map/Map';
+
+export {MapMarker} from './components/MapMarker/MapMarker';
+export type {MapMarkerProps} from './components/MapMarker/MapMarker';
+
+export {MapPopover} from './components/MapPopover/MapPopover';
+export type {MapPopoverProps} from './components/MapPopover/MapPopover';
+
 export {Modal} from './components/Modal/Modal';
 export type {ModalProps} from './components/Modal/Modal';
 
+export {PaymentIcon} from './components/PaymentIcon/PaymentIcon';
+export type {
+  PaymentIconProps,
+  PaymentMethod,
+} from './components/PaymentIcon/PaymentIcon';
+
 export {PhoneField} from './components/PhoneField/PhoneField';
 export type {PhoneFieldProps} from './components/PhoneField/PhoneField';
 
 export {Pressable} from './components/Pressable/Pressable';
 export type {PressableProps} from './components/Pressable/Pressable';
 
+export {ProductThumbnail} from './components/ProductThumbnail/ProductThumbnail';
+export type {ProductThumbnailProps} from './components/ProductThumbnail/ProductThumbnail';
+
 export {Popover} from './components/Popover/Popover';
 export type {PopoverProps, PopoverPosition} from './components/Popover/Popover';
 
@@ -132,6 +167,12 @@ export type {TextFieldProps} from './components/TextField/TextField';
 export {Tooltip} from './components/Tooltip/Tooltip';
 export type {TooltipProps} from './components/Tooltip/Tooltip';
 
+export {ToggleButton} from './components/ToggleButton/ToggleButton';
+export type {ToggleButtonProps} from './components/ToggleButton/ToggleButton';
+
+export {ToggleButtonGroup} from './components/ToggleButtonGroup/ToggleButtonGroup';
+export type {ToggleButtonGroupProps} from './components/ToggleButtonGroup/ToggleButtonGroup';
+
 export {View} from './components/View/View';
 export type {
   ViewProps,

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

@@ -78,6 +78,40 @@ export function getExamples(
         tabs: getExtensionCodeTabs('ui-components/loading-skeletons'),
       },
     },
+    'ui-components/togglebuttongroup-time-picking': {
+      image: 'togglebuttongroup-time-picking.png',
+      description: `The ToggleButtonGroup component is ideal for a small set of options.  It allows for easy scanning of available choices. Also the component’s big tap target makes it a good choice for enhanced mobile experience. However, in a grid layout, having more than 6 ToggleButtons can get overwhelming and take up too much vertical space. When there are more than 6 choices, consider using the [Select](/docs/api/checkout-ui-extensions/components/forms/select) component instead. `,
+      codeblock: {
+        title: 'Displaying a small set of time choices',
+        tabs: getExtensionCodeTabs(
+          'ui-components/togglebuttongroup-time-picking',
+        ),
+      },
+    },
+    'ui-components/choicelist-survey': {
+      description: `The base variant’s flexibility allows for the creation of Likert scales using the ChoiceList component. By utilizing layout components, you can easily structure rows and columns for this purpose.`,
+      image: 'choicelist-survey.png',
+      codeblock: {
+        title: 'Custom survey using the base variant',
+        tabs: getExtensionCodeTabs('ui-components/choicelist-survey'),
+      },
+    },
+    'ui-components/choicelist-details': {
+      description: `The ChoiceList’s group variant, combined with the details property, allows for the conditional display of information when needed.`,
+      image: 'choicelist-details.png',
+      codeblock: {
+        title: 'Collecting additional information',
+        tabs: getExtensionCodeTabs('ui-components/choicelist-details'),
+      },
+    },
+    'ui-components/choicelist-time-picking': {
+      description: `The ChoiceList component is great for presenting a concise list of options, particularly when showcasing time ranges due to its ample horizontal space. However, if there’s more than 5 choices, use the [Select](/docs/api/checkout-ui-extensions/components/forms/select) component instead.`,
+      image: 'choicelist-time-picking.png',
+      codeblock: {
+        title: 'Displaying a short list of time choices',
+        tabs: getExtensionCodeTabs('ui-components/choicelist-time-picking'),
+      },
+    },
   };
 }