@shopify/ui-extensions 2022.10.6 → 2023.4.0

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

@@ -7,10 +7,15 @@ import type {
   ViewportSizeCondition,
   AtLeastOne,
 } from '../../style';
-import {BorderProps} from '../shared';
-import type {Fit, AccessibilityRole} from '../shared';
+import type {
+  AccessibilityRole,
+  BorderProps,
+  CornerProps,
+  Fit,
+  IdProps,
+} from '../shared';
 
-export interface ImageProps extends BorderProps {
+export interface ImageProps extends BorderProps, CornerProps, IdProps {
   /**
    * The URL or path to the image. Supports the `resolution` and `viewportInlineSize` conditional styles only.
    */

package/src/surfaces/checkout/components/Image/examples/basic-image.example.ts

@@ -1,6 +1,6 @@
-import {extend, Image} from '@shopify/ui-extensions/checkout';
+import {extension, Image} from '@shopify/ui-extensions/checkout';
 
-extend('Checkout::Dynamic::Render', (root) => {
+extension('Checkout::Dynamic::Render', (root) => {
   const image = root.createComponent(Image, {
     source:
       'https://shopify.dev/assets/api/checkout-extensions/checkout/components/image-example-code.png',

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

@@ -0,0 +1,61 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+import {getExample} from '../../helper.docs';
+
+const disclosureAndAlignment = getExample(
+  'ui-components/disclosure-and-alignment',
+  ['jsx', 'js'],
+);
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'InlineLayout',
+  description:
+    'InlineLayout is used to lay out content over multiple columns.\n\nBy default, all columns are of equal size and fill the available inline space. Content does not wrap on new rows when not enough columns have been explicitly set, instead they are added as new column and fill the remaining inline space.',
+  thumbnail: 'inlinelayout-thumbnail.png',
+  requires: '',
+  isVisualComponent: true,
+  type: '',
+  definitions: [
+    {
+      title: 'InlineLayoutProps',
+      description: '',
+      type: 'InlineLayoutProps',
+    },
+  ],
+  category: 'Components',
+  subCategory: 'Structure',
+  defaultExample: {
+    image: 'inlinelayout-default.png',
+    codeblock: {
+      title: 'Basic InlineLayout',
+      tabs: [
+        {
+          title: 'React',
+          code: '../../../../../../ui-extensions-react/src/surfaces/checkout/components/InlineLayout/examples/basic-inlinelayout.example.tsx',
+          language: 'tsx',
+        },
+        {
+          title: 'JS',
+          code: './examples/basic-inlinelayout.example.ts',
+          language: 'js',
+        },
+      ],
+    },
+  },
+  examples: {
+    description: '',
+    examples: [disclosureAndAlignment],
+  },
+  subSections: [
+    {
+      type: 'Generic',
+      anchorLink: 'accessibility-roles',
+      title: 'Accessibility roles',
+      sectionContent:
+        '| 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: [],
+};
+
+export default data;

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

@@ -1,12 +1,19 @@
 import {createRemoteComponent} from '@remote-ui/core';
 
 import type {MaybeResponsiveConditionalStyle} from '../../style';
-import type {BorderProps, Columns, SizingProps, SpacingProps} from '../shared';
+import type {
+  BorderProps,
+  Columns,
+  CornerProps,
+  SizingProps,
+  SpacingProps,
+} from '../shared';
 import type {GridProps} from '../Grid/Grid';
 
 export interface InlineLayoutProps
   extends Omit<GridProps, 'columns' | 'rows'>,
     BorderProps,
+    CornerProps,
     SizingProps,
     SpacingProps {
   /**

package/src/surfaces/checkout/components/InlineLayout/examples/basic-inlineLayout.example.ts

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

package/src/surfaces/checkout/components/InlineLayout/examples/basic-inlinelayout.example.ts

@@ -0,0 +1,16 @@
+import {extension, InlineLayout, View} from '@shopify/ui-extensions/checkout';
+
+extension('Checkout::Dynamic::Render', (root) => {
+  const inlineLayout = root.createComponent(
+    InlineLayout,
+    {
+      columns: ['20%', 'fill'],
+    },
+    [
+      root.createComponent(View, {border: 'base', padding: 'base'}, '20%'),
+      root.createComponent(View, {border: 'base', padding: 'base'}, 'fill'),
+    ],
+  );
+
+  root.appendChild(inlineLayout);
+});

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

@@ -0,0 +1,41 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'InlineSpacer',
+  description:
+    'InlineSpacer is used to create empty inline space, typically when variable spacing is needed between multiple elements.\n\nNote that you should favor InlineStack when spacing between all elements is the same.',
+  isVisualComponent: true,
+  thumbnail: 'inlinespacer-thumbnail.png',
+  requires: '',
+  type: '',
+  definitions: [
+    {
+      title: 'InlineSpacerProps',
+      description: '',
+      type: 'InlineSpacerProps',
+    },
+  ],
+  category: 'Components',
+  subCategory: 'Structure',
+  defaultExample: {
+    image: 'inlinespacer-default.png',
+    codeblock: {
+      title: 'Basic InlineSpacer',
+      tabs: [
+        {
+          title: 'React',
+          code: '../../../../../../ui-extensions-react/src/surfaces/checkout/components/InlineSpacer/examples/basic-inlinespacer.example.tsx',
+          language: 'tsx',
+        },
+        {
+          title: 'JS',
+          code: './examples/basic-inlinespacer.example.ts',
+          language: 'js',
+        },
+      ],
+    },
+  },
+  related: [],
+};
+
+export default data;

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

@@ -1,9 +1,9 @@
 import {createRemoteComponent} from '@remote-ui/core';
 
 import type {MaybeResponsiveConditionalStyle} from '../../style';
-import type {Spacing} from '../shared';
+import type {IdProps, Spacing} from '../shared';
 
-export interface InlineSpacerProps {
+export interface InlineSpacerProps extends IdProps {
   /**
    * Adjust size of the spacer
    *

package/src/surfaces/checkout/components/InlineSpacer/examples/basic-inlinespacer.example.ts

@@ -1,11 +1,11 @@
 import {
-  extend,
+  extension,
   InlineSpacer,
   InlineStack,
   View,
 } from '@shopify/ui-extensions/checkout';
 
-extend('Checkout::Dynamic::Render', (root) => {
+extension('Checkout::Dynamic::Render', (root) => {
   const inlineSpacer = root.createComponent(InlineStack, {spacing: 'none'}, [
     root.createComponent(View, {border: 'base', padding: 'base'}, 'View'),
     root.createComponent(InlineSpacer, {spacing: 'loose'}),

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

@@ -0,0 +1,50 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'InlineStack',
+  description:
+    'InlineStack is used to lay out a horizontal row of elements. Elements always wrap.',
+  isVisualComponent: true,
+  thumbnail: 'inlinestack-thumbnail.png',
+  requires: '',
+  type: '',
+  definitions: [
+    {
+      title: 'InlineStackProps',
+      description: '',
+      type: 'InlineStackProps',
+    },
+  ],
+  category: 'Components',
+  subCategory: 'Structure',
+  defaultExample: {
+    image: 'inlinestack-default.png',
+    codeblock: {
+      title: 'Basic InlineStack',
+      tabs: [
+        {
+          title: 'React',
+          code: '../../../../../../ui-extensions-react/src/surfaces/checkout/components/InlineStack/examples/basic-inlinestack.example.tsx',
+          language: 'tsx',
+        },
+        {
+          title: 'JS',
+          code: './examples/basic-inlinestack.example.ts',
+          language: 'js',
+        },
+      ],
+    },
+  },
+  subSections: [
+    {
+      type: 'Generic',
+      anchorLink: 'accessibility-roles',
+      title: 'Accessibility roles',
+      sectionContent:
+        '| 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: [],
+};
+
+export default data;

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

@@ -4,6 +4,7 @@ import type {MaybeResponsiveConditionalStyle} from '../../style';
 import type {
   BlockAlignment,
   BorderProps,
+  CornerProps,
   InlineAlignment,
   SizingProps,
   Spacing,
@@ -13,6 +14,7 @@ import type {
 
 export interface InlineStackProps
   extends BorderProps,
+    CornerProps,
     SizingProps,
     SpacingProps {
   /**
@@ -49,9 +51,29 @@ export interface InlineStackProps
   /**
    * Adjust spacing between children
    *
+   * - `base` means the space between rows and columns is `base`.
+   *
+   * - [`base`, `none`] means the space between rows is `base`, space between columns is `none`.
+   *
    * @defaultValue 'base'
    **/
-  spacing?: MaybeResponsiveConditionalStyle<Spacing>;
+  spacing?: MaybeResponsiveConditionalStyle<Spacing | [Spacing, Spacing]>;
+  /**
+   * A unique identifier for the component.
+   */
+  id?: string;
+  /**
+   * 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/InlineStack/examples/basic-inlinestack.example.ts

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

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

@@ -0,0 +1,64 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'Link',
+  description:
+    'Link makes text interactive so customers can perform an action, such as navigating to another location.',
+  requires: '',
+  isVisualComponent: true,
+  thumbnail: 'link-thumbnail.png',
+  type: '',
+  definitions: [
+    {
+      title: 'LinkProps',
+      description: '',
+      type: 'LinkProps',
+    },
+  ],
+  category: 'Components',
+  subCategory: 'Actions',
+  defaultExample: {
+    image: 'link-default.png',
+    codeblock: {
+      title: 'Basic Link',
+      tabs: [
+        {
+          title: 'React',
+          code: '../../../../../../ui-extensions-react/src/surfaces/checkout/components/Link/examples/basic-link.example.tsx',
+          language: 'tsx',
+        },
+        {
+          title: 'JS',
+          code: './examples/basic-link.example.ts',
+          language: 'js',
+        },
+      ],
+    },
+  },
+  subSections: [
+    {
+      type: 'Generic',
+      anchorLink: 'appearance',
+      title: 'Appearance',
+      sectionContent:
+        '| Value | Description |\n| --- | --- |\n| <code>"monochrome"</code> | Takes the color of its parent.|',
+    },
+    {
+      type: 'Generic',
+      anchorLink: 'best-practices',
+      title: 'Best Practices',
+      sectionContent:
+        '- If the link isn’t in a paragraph, then consider using a plain button instead for a larger hit area.\n\n- Use links primarily for navigation and use buttons primarily for actions.\n\n- The HTML that renders for the Button and `Link` components includes style and accessibility information. Use these components intentionally and consistently to provide a more inclusive experience for assistive technology users and a more cohesive visual experience for sighted users.',
+    },
+  ],
+  related: [
+    {
+      name: 'Button',
+      subtitle: 'Component',
+      url: 'button',
+      type: 'Component',
+    },
+  ],
+};
+
+export default data;

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

@@ -1,8 +1,14 @@
 import {createRemoteComponent} from '@remote-ui/core';
 
-import type {Appearance, OverlayActivatorProps} from '../shared';
+import type {
+  Appearance,
+  OverlayActivatorProps,
+  DisclosureActivatorProps,
+} from '../shared';
 
-export interface LinkProps extends OverlayActivatorProps {
+export interface LinkProps
+  extends OverlayActivatorProps,
+    DisclosureActivatorProps {
   /**
    * Destination to navigate to. You must provide either this property, `onPress`,
    * or both.
@@ -27,8 +33,7 @@ export interface LinkProps extends OverlayActivatorProps {
   language?: string;
   /**
    * A label used for buyers using assistive technologies. When set, any
-   * 'children' supplied to this component are hidden from being seen for
-   * accessibility purposes to prevent duplicate content from being read.
+   * `children` supplied to this component will not be announced to screen reader users.
    */
   accessibilityLabel?: string;
   /**

package/src/surfaces/checkout/components/Link/examples/basic-link.example.ts

@@ -1,6 +1,6 @@
-import {extend, Link} from '@shopify/ui-extensions/checkout';
+import {extension, Link} from '@shopify/ui-extensions/checkout';
 
-extend('Checkout::Dynamic::Render', (root) => {
+extension('Checkout::Dynamic::Render', (root) => {
   const link = root.createComponent(
     Link,
     {to: 'https://www.shopify.ca/climate/sustainability-fund'},

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

@@ -0,0 +1,58 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'List',
+  description:
+    'Lists display a set of related content. Each list item usually begins with a bullet or a number.',
+
+  requires: '',
+  thumbnail: 'list-thumbnail.png',
+  isVisualComponent: true,
+  type: '',
+  definitions: [
+    {
+      title: 'ListProps',
+      description: '',
+      type: 'ListProps',
+    },
+  ],
+  category: 'Components',
+  subCategory: 'Other',
+  defaultExample: {
+    image: 'list-default.png',
+    codeblock: {
+      title: 'Basic List',
+      tabs: [
+        {
+          title: 'React',
+          code: '../../../../../../ui-extensions-react/src/surfaces/checkout/components/List/examples/basic-list.example.tsx',
+          language: 'tsx',
+        },
+        {
+          title: 'JS',
+          code: './examples/basic-list.example.ts',
+          language: 'js',
+        },
+      ],
+    },
+  },
+  subSections: [
+    {
+      type: 'Generic',
+      anchorLink: 'best-practices',
+      title: 'Best Practices',
+      sectionContent:
+        '- Use lists to break up chunks of related content to make the information easier for customers to scan.\n\n- Phrase list items consistently. Try to start each item with a noun or a verb and be consistent with each item.\n\n- Use bullets for a text-only list of related items that don’t need to be in a specific order.\n\n- Use numbers for a text-only list of related items when you need to communicate order, priority, or sequence.\n\n- Don’t use a marker when only the semantic value of a list matters, such as with a list of links.',
+    },
+  ],
+  related: [
+    {
+      name: 'ListItem',
+      subtitle: 'Component',
+      url: 'listItem',
+      type: 'Component',
+    },
+  ],
+};
+
+export default data;

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

@@ -1,11 +1,11 @@
 import {createRemoteComponent} from '@remote-ui/core';
 
-import type {Spacing} from '../shared';
+import type {IdProps, Spacing} from '../shared';
 import type {MaybeResponsiveConditionalStyle} from '../../style';
 
 export type Marker = 'none' | 'bullet' | 'number';
 
-export interface ListProps {
+export interface ListProps extends IdProps {
   /**
    * Adjust spacing between list items
    *

package/src/surfaces/checkout/components/List/examples/basic-list.example.ts

@@ -1,6 +1,6 @@
-import {extend, List, ListItem} from '@shopify/ui-extensions/checkout';
+import {extension, List, ListItem} from '@shopify/ui-extensions/checkout';
 
-extend('Checkout::Dynamic::Render', (root) => {
+extension('Checkout::Dynamic::Render', (root) => {
   const list = root.createComponent(List, undefined, [
     root.createComponent(ListItem, undefined, '100% organic cotton'),
     root.createComponent(ListItem, undefined, 'Made in Canada'),

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

@@ -0,0 +1,42 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'ListItem',
+  description:
+    'List items are used as children of the `List` component.\n\nThey usually begins with a bullet or a number.',
+  requires: '',
+  thumbnail: 'listitem-thumbnail.png',
+  isVisualComponent: true,
+  type: '',
+  definitions: [],
+  category: 'Components',
+  subCategory: 'Other',
+  defaultExample: {
+    image: 'listitem-default.png',
+    codeblock: {
+      title: 'Basic ListItem',
+      tabs: [
+        {
+          title: 'React',
+          code: '../../../../../../ui-extensions-react/src/surfaces/checkout/components/ListItem/examples/basic-listitem.example.tsx',
+          language: 'tsx',
+        },
+        {
+          title: 'JS',
+          code: './examples/basic-listitem.example.ts',
+          language: 'js',
+        },
+      ],
+    },
+  },
+  related: [
+    {
+      name: 'List',
+      subtitle: 'Component',
+      url: 'list',
+      type: 'Component',
+    },
+  ],
+};
+
+export default data;

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

@@ -1,6 +1,8 @@
 import {createRemoteComponent} from '@remote-ui/core';
 
-export interface ListItemProps {}
+import type {IdProps} from '../shared';
+
+export interface ListItemProps extends IdProps {}
 
 /**
  * List items are used as children of the `List` component.

package/src/surfaces/checkout/components/ListItem/examples/basic-listitem.example.ts

@@ -1,6 +1,6 @@
-import {extend, List, ListItem} from '@shopify/ui-extensions/checkout';
+import {extension, List, ListItem} from '@shopify/ui-extensions/checkout';
 
-extend('Checkout::Dynamic::Render', (root) => {
+extension('Checkout::Dynamic::Render', (root) => {
   const list = root.createComponent(List, undefined, [
     root.createComponent(ListItem, undefined, '100% organic cotton'),
   ]);

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

@@ -0,0 +1,50 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'Modal',
+  description:
+    'Modals are a special type of overlay that shift focus towards a specific action/set of information before the main flow can proceed. 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 Dialog pattern automatically for the activator and the modal content.',
+  requires: '',
+  thumbnail: 'modal-thumbnail.png',
+  isVisualComponent: true,
+  type: '',
+  definitions: [
+    {
+      title: 'ModalProps',
+      description: '',
+      type: 'ModalProps',
+    },
+  ],
+  category: 'Components',
+  subCategory: 'Overlays',
+  defaultExample: {
+    image: 'modal-default.png',
+    codeblock: {
+      title: 'Basic Modal',
+      tabs: [
+        {
+          title: 'React',
+          code: '../../../../../../ui-extensions-react/src/surfaces/checkout/components/Modal/examples/basic-modal.example.tsx',
+          language: 'tsx',
+        },
+        {
+          title: 'JS',
+          code: './examples/basic-modal.example.ts',
+          language: 'js',
+        },
+      ],
+    },
+  },
+  subSections: [
+    {
+      type: 'Generic',
+      anchorLink: 'best-practices',
+      title: 'Best Practices',
+      sectionContent:
+        'Use modals if:\n\n- The information needed to be shown is not critical in completing the checkout process and information cannot be condensed into one sentence.\n\n- The information the buyer is entering requires less than two rows of input fields.\n\n- The information the buyer is entering is not reliant on information on the page (which is underneath the modal and not visible to them).',
+    },
+  ],
+  related: [],
+};
+
+export default data;

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

@@ -0,0 +1,42 @@
+import {createRemoteComponent} from '@remote-ui/core';
+
+export interface ModalProps {
+  /**
+   * A unique identifier for the Modal. When no `id` is set,
+   * a globally unique value will be used instead.
+   */
+  id?: string;
+  /**
+   * Callback when the modal is closed. That is when either the close button, the backdrop,
+   * or the `escape` key are pressed.
+   */
+  onClose?: () => void;
+  /**
+   * Callback when the modal is opened. This is called at the beginning of the transition
+   * that opens the modal.
+   */
+  onOpen?: () => void;
+  /**
+   * A title rendered at the top of the modal.
+   */
+  title?: string;
+  /**
+   * A label to describe the purpose of the modal that is announced by screen readers.
+   * If not set, it will use the value of `title`.
+   */
+  accessibilityLabel?: string;
+  /**
+   * Adds a default spacing around both header (which holds the `title`) and content of the modal.
+   */
+  padding?: boolean;
+}
+
+/**
+ * Modals are a special type of overlay that shift focus towards a specific action/set of information
+ * before the main flow can proceed.
+ * 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 Dialog pattern automatically for the activator
+ * and the modal content.
+ */
+export const Modal = createRemoteComponent<'Modal', ModalProps>('Modal');