@shopify/ui-extensions 2024.4.2 → 2024.10.0

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

@@ -44,7 +44,14 @@ const data: ReferenceEntityTemplateSchema = {
         '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: [],
+  related: [
+    {
+      name: 'Ui',
+      subtitle: 'API',
+      url: 'ui',
+      type: 'API',
+    },
+  ],
 };
 
 export default data;

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

@@ -35,7 +35,14 @@ const data: ReferenceEntityTemplateSchema = {
       ],
     },
   },
-  related: [],
+  related: [
+    {
+      subtitle: 'Utility',
+      name: 'StyleHelper',
+      url: '/docs/api/checkout-ui-extensions/unstable/components/utilities/stylehelper',
+      type: 'utility',
+    },
+  ],
 };
 
 export default data;

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

@@ -14,29 +14,35 @@ import type {
   CornerProps,
   Opacity,
   BackgroundProps,
+  IdProps,
 } from '../shared';
 
 export interface PressableProps
   extends Pick<BackgroundProps, 'background'>,
     BorderProps,
     CornerProps,
+    IdProps,
     SizingProps,
     SpacingProps,
     OverlayActivatorProps,
     DisclosureActivatorProps {
   /**
-   * Changes the display of the Pressable.
+   * Changes the display of the component.
    *
    *
-   * `inline` follows the direction of words in a sentence based on the document’s writing mode.
+   * `inline` the component starts on the same line as preceding inline content and allows subsequent content to continue on the same line.
    *
-   * `block` follows the direction of paragraphs based on the document’s writing mode.
+   * `block` the component starts on its own new line and fills its parent.
    *
+   * `auto` resets the component to its initial value. The actual value depends on the component and context.
    *
-   * @defaultValue 'block'
+   * `none` hides the component and removes it from the accessibility tree, making it invisible to screen readers.
+   *
+   * @see https://developer.mozilla.org/en-US/docs/Web/CSS/display
+   *
+   * @defaultValue 'auto'
    */
-  display?: Display;
-
+  display?: MaybeResponsiveConditionalStyle<Display>;
   /**
    * A label that describes the purpose or contents of the element. When set,
    * it will be announced to buyers using assistive technologies and will
@@ -60,11 +66,6 @@ export interface PressableProps
    */
   disabled?: boolean;
 
-  /**
-   * A unique identifier for the Pressable.
-   */
-  id?: string;
-
   /**
    * Disables the button while loading. Unlike `Button`, no indicator is rendered while loading.
    */

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

@@ -0,0 +1,89 @@
+import type {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+import {getExample} from '../../helper.docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'Progress',
+  description: 'Use to visually represent the completion of a task or process.',
+  requires: '',
+  isVisualComponent: true,
+  thumbnail: 'progress-thumbnail.png',
+  type: '',
+  definitions: [
+    {
+      title: 'ProgressProps',
+      description: '',
+      type: 'ProgressProps',
+    },
+  ],
+  category: 'Components',
+  subCategory: 'Feedback',
+  defaultExample: {
+    image: 'progress-indeterminate.gif',
+    codeblock: {
+      title: 'Indeterminate state',
+      tabs: [
+        {
+          title: 'React',
+          code: '../../../../../../ui-extensions-react/src/surfaces/checkout/components/Progress/examples/basic-progress.example.tsx',
+          language: 'tsx',
+        },
+        {
+          title: 'JS',
+          code: './examples/basic-progress.example.ts',
+          language: 'js',
+        },
+      ],
+    },
+  },
+  subSections: [
+    {
+      type: 'Generic',
+      anchorLink: 'best-practices',
+      title: 'Best Practices',
+      sectionContent: `
+Use components like [TextBlock](../titles-and-text/textblock) or [Text](../titles-and-text/text), along with the Progress component, to display text indicating the status of the progress bar.
+
+### Loading states
+
+For loading states, add text to reassure the user that the progress bar is not frozen.
+
+![A progress bar with "Loading" text](/assets/templated-apis-screenshots/checkout-ui-extensions/unstable/progress-loading.png)
+
+### Error states
+
+For error states, add text or a [Banner](./banner) to describe the error and next steps. Use the \`critical\` tone property to convey urgency.
+
+![A progress bar with error text that says "There was a problem with the file upload. Please try again."](/assets/templated-apis-screenshots/checkout-ui-extensions/unstable/progress-error.png)
+
+### Visualize a goal
+
+Use the Progress component to visualize a goal that's valuable to the customer.
+
+Here's an example of using a progress bar to show a customer's progress toward the next rewards tier:
+
+![A progress bar in customer accounts, showing that the customer is on their way to reaching the Botanical maven rewards tier.](/assets/templated-apis-screenshots/checkout-ui-extensions/unstable/progress-goal.png)
+
+Here's an example of using a progress bar to show how much more a customer needs to spend to get free shipping:
+
+![A progress bar at checkout, showing that the customer is $43 away from free shipping.](/assets/templated-apis-screenshots/checkout-ui-extensions/unstable/progress-free-shipping.png)
+      `,
+    },
+  ],
+  examples: {
+    description: '',
+    examples: [
+      getExample('ui-components/progress-determinate-state', ['jsx', 'js']),
+    ],
+  },
+  related: [
+    {
+      name: 'Spinner',
+      subtitle: 'Component',
+      url: 'spinner',
+      type: 'Component',
+    },
+  ],
+};
+
+export default data;

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

@@ -0,0 +1,44 @@
+import {createRemoteComponent} from '@remote-ui/core';
+
+import type {IdProps} from '../shared';
+
+type Tone = 'auto' | 'critical';
+
+export interface ProgressProps extends IdProps {
+  /**
+   * Specify how much of the task that has been completed.
+   * It must be a valid floating point number between 0 and max, or between 0 and 1 if max is omitted.
+   * When undefined, the progress bar is indeterminate;
+   * this indicates that an activity is ongoing with no indication of how long it is expected to take.
+   *
+   * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/progress#value
+   */
+  value?: number;
+
+  /**
+   * Define the maximum limit of the progress element.
+   * It must have a value greater than 0 and be a valid floating point number.
+   *
+   * @defaultValue 1
+   * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/progress#max
+   */
+  max?: number;
+
+  /**
+   * Set the color of the progress bar.
+   *
+   * @defaultValue 'auto'
+   */
+  tone?: Tone;
+
+  /**
+   * A label to use for the Progress that will be used for buyers using assistive technologies like screen readers.
+   * It will also be used to replace the animated loading indicator when buyers prefer reduced motion.
+   *
+   */
+  accessibilityLabel?: string;
+}
+
+export const Progress = createRemoteComponent<'Progress', ProgressProps>(
+  'Progress',
+);

package/src/surfaces/checkout/components/Progress/examples/basic-progress.example.ts

@@ -0,0 +1,9 @@
+import {extension, Progress} from '@shopify/ui-extensions/checkout';
+
+export default extension('purchase.checkout.block.render', (root) => {
+  const baseProgress = root.createComponent(Progress, {
+    accessibilityLabel: 'Loading',
+  });
+
+  root.appendChild(baseProgress);
+});

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

@@ -0,0 +1,60 @@
+import type {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+import {getExample} from '../../helper.docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'QRCode',
+  description: 'Used to quickly access scannable data.',
+  requires: '',
+  isVisualComponent: true,
+  thumbnail: 'qrcode-thumbnail.png',
+  type: '',
+  definitions: [
+    {
+      title: 'QRCodeProps',
+      description: '',
+      type: 'QRCodeProps',
+    },
+  ],
+  category: 'Components',
+  subCategory: 'Other',
+  defaultExample: {
+    image: 'qrcode-default.png',
+    codeblock: {
+      title: 'Basic QR Code',
+      tabs: [
+        {
+          title: 'React',
+          code: '../../../../../../ui-extensions-react/src/surfaces/checkout/components/QRCode/examples/basic-qrcode.example.tsx',
+          language: 'tsx',
+        },
+        {
+          title: 'JS',
+          code: './examples/basic-qrcode.example.ts',
+          language: 'js',
+        },
+      ],
+    },
+  },
+  subSections: [
+    {
+      type: 'Generic',
+      anchorLink: 'best-practices',
+      title: 'Best Practices',
+      sectionContent: `
+- Always test that the QR code is scannable from a smartphone.
+- Include a square logo if that’s what your customers are familiar with.
+- Increase usability by adding a text description of what the QR code does and provide alternate methods to get to the same destination, like a text input containing the value.`,
+    },
+  ],
+  examples: {
+    description: '',
+    examples: [
+      getExample('ui-components/qrcode-image', ['jsx', 'js']),
+      getExample('ui-components/qrcode-fill-size', ['jsx', 'js']),
+    ],
+  },
+  related: [],
+};
+
+export default data;

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

@@ -0,0 +1,54 @@
+import {createRemoteComponent} from '@remote-ui/core';
+
+import type {IdProps, BorderStyle} from '../shared';
+
+export interface QRCodeProps extends IdProps {
+  /**
+   * The content to be encoded in the QR code, which can be any string such as a URL, email address, plain text, etc.
+   * Specific string formatting can trigger actions on the user’s device when scanned, like opening geolocation
+   * coordinates on a map, opening a preferred app or app store entry, preparing an email, text message, and more.
+   */
+  content?: string;
+
+  /**
+   * URL of an image to be displayed in the center of the QR code.
+   * This is useful for branding or to indicate to the user what scanning the QR code will do.
+   * By default, no image is displayed.
+   */
+  logo?: string;
+
+  /**
+   * The displayed size of the QR code.
+   *
+   * `fill`: the QR code will takes up 100% of the available inline-size and maintain a 1:1 aspect ratio.
+   *
+   * `auto`: the QR code will be displayed at its default size.
+   *
+   * @default 'auto'
+   */
+  size?: 'auto' | 'fill';
+
+  /**
+   * Adjust the border style.
+   *
+   * @default 'base'
+   */
+  border?: Extract<BorderStyle, 'none' | 'base'>;
+
+  /**
+   * A label that describes the purpose or contents of the QR code. When set,
+   * it will be announced to users using assistive technologies and will
+   * provide more context about what the QR code may do when scanned.
+   *
+   * @default 'QR code' (translated to the user’s locale)
+   */
+  accessibilityLabel?: string;
+
+  /**
+   * Invoked when the conversion of `content` to a QR code fails.
+   * If an error occurs, the QR code and its child elements will not be displayed.
+   */
+  onError?: () => void;
+}
+
+export const QRCode = createRemoteComponent<'QRCode', QRCodeProps>('QRCode');

package/src/surfaces/checkout/components/QRCode/examples/basic-qrcode.example.ts

@@ -0,0 +1,9 @@
+import {extension, QRCode} from '@shopify/ui-extensions/checkout';
+
+export default extension('purchase.checkout.block.render', (root) => {
+  const qrCode = root.createComponent(QRCode, {
+    content: 'https://shopify.com',
+  });
+
+  root.appendChild(qrCode);
+});

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

@@ -35,7 +35,14 @@ const data: ReferenceEntityTemplateSchema = {
       ],
     },
   },
-  related: [],
+  related: [
+    {
+      subtitle: 'Utility',
+      name: 'StyleHelper',
+      url: '/docs/api/checkout-ui-extensions/unstable/components/utilities/stylehelper',
+      type: 'utility',
+    },
+  ],
 };
 
 export default data;

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

@@ -4,9 +4,11 @@ import type {
   BackgroundProps,
   BorderProps,
   CornerProps,
+  IdProps,
   SizingProps,
   SpacingProps,
 } from '../shared';
+import type {MaybeResponsiveConditionalStyle} from '../../style/types';
 
 export interface ScrollViewEvent {
   /**
@@ -33,8 +35,15 @@ export interface ScrollViewProps
   extends Pick<BackgroundProps, 'background'>,
     BorderProps,
     CornerProps,
+    IdProps,
     SizingProps,
     SpacingProps {
+  /**
+   * A label that describes the purpose or contents of the element. When set,
+   * it will be announced to buyers using assistive technologies and will
+   * provide them with more context.
+   */
+  accessibilityLabel?: string;
   /**
    * Provides a hint to the user that the area is scrollable.
    *
@@ -56,7 +65,23 @@ export interface ScrollViewProps
    */
   direction?: 'block' | 'inline';
   /**
-   * Scroll to a specific position or to an element.
+   * Scroll to a specific position or to an element when the component is first rendered.
+   *
+   * This property allows you to set an initial scroll position or scroll to a specific element
+   * when the `ScrollView` component mounts. Note that this action will only be performed once,
+   * during the initial render of the component.
+   *
+   * @example
+   * // Scroll to 100 pixels from the top on initial render
+   * <ScrollView scrollTo={100} />
+   *
+   * // Scroll to a specific element on initial render
+   * const elementRef = useRef(null);
+   * <ScrollView scrollTo={elementRef.current} />
+   *
+   * @note
+   * This property will only take effect on the first render. Subsequent updates to this property
+   * will not trigger additional scroll actions.
    */
   scrollTo?: number | HTMLElement;
   /**
@@ -74,9 +99,18 @@ export interface ScrollViewProps
    */
   onScrolledToEdge?: (args: ScrollViewEvent) => void;
   /**
-   * A unique identifier for the component.
+   * Changes the display of the component.
+   *
+   *
+   * `auto` the component's initial value. The actual value depends on the component and context.
+   *
+   * `none` hides the component and removes it from the accessibility tree, making it invisible to screen readers.
+   *
+   * @see https://developer.mozilla.org/en-US/docs/Web/CSS/display
+   *
+   * @defaultValue 'auto'
    */
-  id?: string;
+  display?: MaybeResponsiveConditionalStyle<'auto' | 'none'>;
 }
 
 /**

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

@@ -44,6 +44,10 @@ export interface SelectProps {
    * The options a buyer can select from.
    */
   options: SelectOptionProps[];
+  /**
+   * A short hint that describes the expected value of the field when no value is set.
+   */
+  placeholder?: string;
   /**
    * Whether the field needs a value. This requirement adds semantic value
    * to the field, but it will not cause an error to appear automatically.
@@ -56,7 +60,7 @@ export interface SelectProps {
    */
   disabled?: boolean;
   /**
-   * Whether the field is read only
+   * Whether the field is read only.
    */
   readonly?: boolean;
   /**
@@ -80,6 +84,14 @@ export interface SelectProps {
    * specific data you would like to be entered into this field during autocomplete.
    */
   autocomplete?: Autocomplete | boolean;
+  /**
+   * Callback when focus is removed.
+   */
+  onBlur?(): void;
+  /**
+   * Callback when input is focused.
+   */
+  onFocus?(): void;
   /**
    * A callback that is run whenever the selected option changes. This callback
    * is called with the string `value` of the selected `option`. This component

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

@@ -63,7 +63,14 @@ const data: ReferenceEntityTemplateSchema = {
       getExample('ui-components/sheet-layout-content', ['jsx', 'js']),
     ],
   },
-  related: [],
+  related: [
+    {
+      name: 'Ui',
+      subtitle: 'API',
+      url: 'ui',
+      type: 'API',
+    },
+  ],
 };
 
 export default data;

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

@@ -44,7 +44,14 @@ const data: ReferenceEntityTemplateSchema = {
         '| Value | Description |\n| --- | --- |\n| <code>"accent"</code> | Conveys emphasis and draws attention to the element. |\n| <code>"monochrome"</code> | Takes the color of its parent.|',
     },
   ],
-  related: [],
+  related: [
+    {
+      name: 'Progress',
+      subtitle: 'Component',
+      url: 'progress',
+      type: 'Component',
+    },
+  ],
 };
 
 export default data;

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

@@ -0,0 +1,80 @@
+import type {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+import {getExample} from '../../helper.docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'Switch',
+  description:
+    'Use a switch to represent an on or off state that takes effect immediately when tapped.',
+  requires: '',
+  isVisualComponent: true,
+  thumbnail: 'switch-thumbnail.png',
+  type: '',
+  definitions: [
+    {
+      title: 'SwitchProps',
+      description: '',
+      type: 'SwitchProps',
+    },
+  ],
+  category: 'Components',
+  subCategory: 'Forms',
+  defaultExample: {
+    image: 'switch-default.png',
+    codeblock: {
+      title: 'Basic Switch',
+      tabs: [
+        {
+          title: 'React',
+          code: '../../../../../../ui-extensions-react/src/surfaces/checkout/components/Switch/examples/basic-switch.example.tsx',
+          language: 'tsx',
+        },
+        {
+          title: 'JS',
+          code: './examples/basic-switch.example.ts',
+          language: 'js',
+        },
+      ],
+    },
+  },
+  subSections: [
+    {
+      type: 'Generic',
+      anchorLink: 'best-practices',
+      title: 'Best Practices',
+      sectionContent: `
+- The outcome of a switch should take effect immediately when tapped.
+- Use for independent settings, like turning on a stand-alone feature.
+- Most of the time no call-to-action should be needed as the switch should take effect immediately, but if the experience needs one, use “done” instead of “submit” or “apply”.
+
+### Content
+The label should be a noun. Try explaining the setting out loud to test the name. The name should make sense when you insert it into these statements:
+
+- You can turn [setting_label] on or off in settings.
+- [setting_label] is on.
+- [setting_label] is off.
+
+### Switch vs checkbox
+- If the experience requires multiple connected inputs, like a survey, use a checkbox instead of a switch.
+- If the experience requires an error state, like agreeing to terms and conditions, use a checkbox instead of a switch. Both on and off options for a switch should always be valid.
+- If you’re unsure, default to a checkbox as it’s the more familiar web pattern.
+
+<img src="/assets/landing-pages/templated-apis/checkout-ui-extensions/ui-components/switch-checkbox-example.png" />
+      `,
+    },
+  ],
+  examples: {
+    description: '',
+    examples: [getExample('ui-components/switch-custom-label', ['jsx', 'js'])],
+  },
+  related: [
+    {
+      name: 'Checkbox',
+      subtitle: 'Component',
+      url: 'checkbox',
+      type: 'Component',
+    },
+  ],
+};
+
+export default data;

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

@@ -0,0 +1,50 @@
+import {createRemoteComponent} from '@remote-ui/core';
+
+import type {IdProps, DisclosureActivatorProps} from '../shared';
+
+export interface SwitchProps extends IdProps, DisclosureActivatorProps {
+  /**
+   * An identifier for the field that is unique within the nearest
+   * containing `Form` component.
+   */
+  name?: string;
+
+  /**
+   * Whether the switch is active.
+   */
+  checked?: boolean;
+
+  /**
+   * Visual content to use as the switch label.
+   */
+  label?: string;
+
+  /**
+   * Whether the switch is selected. This prop is an alias for `checked`,
+   * and can be useful in form libraries that provide a normalized API for
+   * dealing with both `boolean` and `string` values. If both `value` and
+   * `checked` are set, `checked` takes precedence.
+   */
+  value?: boolean;
+
+  /**
+   * Whether the switch can be changed.
+   */
+  disabled?: boolean;
+
+  /**
+   * A label used for buyers using assistive technologies.
+   */
+  accessibilityLabel?: string;
+
+  /**
+   * A callback that is run whenever the switch is changed. This callback
+   * is called with a boolean indicating whether the switch should now be
+   * active or inactive. This component is [controlled](https://reactjs.org/docs/forms.html#controlled-components),
+   * so you must store this value in state and reflect it back in the
+   * `checked` or `value` props.
+   */
+  onChange?(value: boolean): void;
+}
+
+export const Switch = createRemoteComponent<'Switch', SwitchProps>('Switch');

package/src/surfaces/checkout/components/Switch/examples/basic-switch.example.ts

@@ -0,0 +1,9 @@
+import {extension, Switch} from '@shopify/ui-extensions/checkout';
+
+export default extension('purchase.checkout.block.render', (root) => {
+  const baseSwitch = root.createComponent(Switch, {
+    accessibilityLabel: 'my-switch',
+  });
+
+  root.appendChild(baseSwitch);
+});

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

@@ -44,7 +44,14 @@ const data: ReferenceEntityTemplateSchema = {
         '| Value | Description |\n| --- | --- |\n| <code>"main"</code> | Used to indicate the primary content. |\n| <code>"header"</code> | Used to indicate the component is a header. |\n| <code>"footer"</code> | Used to display information such as copyright information, navigation links, and privacy statements. |\n| <code>"section"</code> | Used to indicate a generic section. |\n| <code>"complementary"</code> | Used to designate a supporting section that relates to the main content. |\n| <code>"navigation"</code> | Used to identify major groups of links used for navigating. |\n| <code>"orderedList"</code> | Used to identify a list of ordered items. |\n| <code>"listItem"</code> | Used to identify an item inside a list of items. |\n| <code>"unorderedList"</code> | Used to identify a list of unordered items. |\n| <code>"separator"</code> | Used to indicates the component acts as a divider that separates and distinguishes sections of content. |\n| <code>"status"</code> | Used to define a live region containing advisory information for the user that is not important enough to be an alert. |\n| <code>"alert"</code> | Used for important, and usually time-sensitive, information. |',
     },
   ],
-  related: [],
+  related: [
+    {
+      subtitle: 'Utility',
+      name: 'StyleHelper',
+      url: '/docs/api/checkout-ui-extensions/unstable/components/utilities/stylehelper',
+      type: 'utility',
+    },
+  ],
 };
 
 export default data;