@shopify/ui-extensions 2022.10.5 → 2023.4.0

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

@@ -0,0 +1,50 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'Form',
+  description:
+    'The form component should be used to wrap one or more form controls. This component provides an "implicit submit" behavior, where customers can submit the form from any input by pressing "Enter" on their keyboards. This behavior is widely expected, and should be respected as often as possible.\n\nUnlike an HTML `form` element, this component does not support configuring the descendant fields to be submitted via HTTP automatically. Instead, you must provide an `onSubmit` callback that will perform the necessary HTTP requests in JavaScript.',
+  thumbnail: 'form-thumbnail.png',
+  requires: '',
+  isVisualComponent: true,
+  type: '',
+  definitions: [
+    {
+      title: 'FormProps',
+      description: '',
+      type: 'FormProps',
+    },
+  ],
+  category: 'Components',
+  subCategory: 'Forms',
+  defaultExample: {
+    image: 'form-default.png',
+    codeblock: {
+      title: 'Basic Form',
+      tabs: [
+        {
+          title: 'React',
+          code: '../../../../../../ui-extensions-react/src/surfaces/checkout/components/Form/examples/basic-form.example.tsx',
+          language: 'tsx',
+        },
+        {
+          title: 'JS',
+          code: './examples/basic-form.example.ts',
+          language: 'js',
+        },
+      ],
+    },
+  },
+  subSections: [
+    {
+      type: 'Generic',
+      anchorLink: 'best-practices',
+      title: 'Best Practices',
+      sectionContent:
+        '- Wrap around all form input elements.\n\n- Forms can have only one submit button and it must be at the end of the form.',
+    },
+  ],
+  related: [],
+};
+
+export default data;

package/src/surfaces/checkout/components/Form/examples/basic-form.example.ts

@@ -1,5 +1,5 @@
 import {
-  extend,
+  extension,
   BlockSpacer,
   Button,
   Form,
@@ -9,7 +9,7 @@ import {
   View,
 } from '@shopify/ui-extensions/checkout';
 
-extend('Checkout::Dynamic::Render', (root) => {
+extension('Checkout::Dynamic::Render', (root) => {
   const fields = root.createComponent(
     Grid,
     {columns: ['50%', '50%'], spacing: 'base'},

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

@@ -0,0 +1,57 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'Grid',
+  description:
+    'Grid is used to lay out content in a matrix of rows and columns.',
+  thumbnail: 'grid-thumbnail.png',
+  requires: '',
+  isVisualComponent: true,
+  type: '',
+  definitions: [
+    {
+      title: 'GridProps',
+      description: '',
+      type: 'GridProps',
+    },
+  ],
+  category: 'Components',
+  subCategory: 'Structure',
+  defaultExample: {
+    image: 'grid-default.png',
+    codeblock: {
+      title: 'Basic Grid',
+      tabs: [
+        {
+          title: 'React',
+          code: '../../../../../../ui-extensions-react/src/surfaces/checkout/components/Grid/examples/basic-grid.example.tsx',
+          language: 'tsx',
+        },
+        {
+          title: 'JS',
+          code: './examples/basic-grid.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: [
+    {
+      name: 'GridItem',
+      subtitle: 'Component',
+      url: 'grid',
+      type: 'Component',
+    },
+  ],
+};
+
+export default data;

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

@@ -5,6 +5,7 @@ import type {
   BlockAlignment,
   BorderProps,
   Columns,
+  CornerProps,
   InlineAlignment,
   Rows,
   SizingProps,
@@ -13,7 +14,11 @@ import type {
   ViewLikeAccessibilityRole,
 } from '../shared';
 
-export interface GridProps extends BorderProps, SizingProps, SpacingProps {
+export interface GridProps
+  extends BorderProps,
+    CornerProps,
+    SizingProps,
+    SpacingProps {
   /**
    * Sizes for each column of the layout.
    *
@@ -85,9 +90,9 @@ export interface GridProps extends BorderProps, SizingProps, SpacingProps {
    *
    * For example:
    *
-   * - In an HTML host a `['listItem', 'separator']` tuple will render: <li role='separator'>
+   * - In an HTML host a `['listItem', 'separator']` tuple will render: `<li role='separator'>`
    *
-   * - In an HTML host a `listItem` string will render: <li>
+   * - In an HTML host a `listItem` string will render: `<li>`
    */
   accessibilityRole?: ViewLikeAccessibilityRole;
   /**
@@ -96,6 +101,22 @@ export interface GridProps extends BorderProps, SizingProps, SpacingProps {
    * provide them with more context.
    */
   accessibilityLabel?: string;
+  /**
+   * 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/Grid/examples/basic-grid.example.ts

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

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

@@ -0,0 +1,57 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'GridItem',
+  description:
+    'GridItem can be used as children of Grid.\n\nIt offers a way to span the element across a number of columns and rows.',
+  thumbnail: 'griditem-thumbnail.png',
+  requires: '',
+  isVisualComponent: true,
+  type: '',
+  definitions: [
+    {
+      title: 'GridItemProps',
+      description: '',
+      type: 'GridItemProps',
+    },
+  ],
+  category: 'Components',
+  subCategory: 'Structure',
+  defaultExample: {
+    image: 'griditem-default.png',
+    codeblock: {
+      title: 'Basic GridItem',
+      tabs: [
+        {
+          title: 'React',
+          code: '../../../../../../ui-extensions-react/src/surfaces/checkout/components/GridItem/examples/basic-griditem.example.tsx',
+          language: 'tsx',
+        },
+        {
+          title: 'JS',
+          code: './examples/basic-griditem.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: [
+    {
+      name: 'Grid',
+      subtitle: 'Component',
+      url: 'grid',
+      type: 'Component',
+    },
+  ],
+};
+
+export default data;

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

@@ -3,12 +3,17 @@ import {createRemoteComponent} from '@remote-ui/core';
 import type {MaybeResponsiveConditionalStyle} from '../../style';
 import type {
   BorderProps,
+  CornerProps,
   SizingProps,
   SpacingProps,
   ViewLikeAccessibilityRole,
 } from '../shared';
 
-export interface GridItemProps extends BorderProps, SizingProps, SpacingProps {
+export interface GridItemProps
+  extends BorderProps,
+    CornerProps,
+    SizingProps,
+    SpacingProps {
   /**
    * Number of columns the item will span across
    */
@@ -25,11 +30,27 @@ export interface GridItemProps extends BorderProps, SizingProps, SpacingProps {
    *
    * For example:
    *
-   * - In an HTML host a `['listItem', 'separator']` tuple will render: <li role='separator'>
+   * - In an HTML host a `['listItem', 'separator']` tuple will render: `<li role='separator'>`
    *
-   * - In an HTML host a `listItem` string will render: <li>
+   * - In an HTML host a `listItem` string will render: `<li>`
    */
   accessibilityRole?: ViewLikeAccessibilityRole;
+  /**
+   * 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/GridItem/examples/basic-griditem.example.ts

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

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

@@ -0,0 +1,69 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'Heading',
+  description:
+    'Headings control the visual style of headings. Use headings to introduce major sections, like Contact information, Shipping address, or Shipping method.\n\nUnlike HTML headings, you don’t explicitly specify the position of the heading in the document outline. Nest headings within the heading group component to control the document outline structure used by assistive technologies.',
+  thumbnail: 'heading-thumbnail.png',
+  requires: '',
+  isVisualComponent: true,
+  type: '',
+  definitions: [
+    {
+      title: 'HeadingProps',
+      description: '',
+      type: 'HeadingProps',
+    },
+  ],
+  category: 'Components',
+  subCategory: 'Titles and text',
+  defaultExample: {
+    image: 'heading-default.png',
+    codeblock: {
+      title: 'Basic Heading',
+      tabs: [
+        {
+          title: 'React',
+          code: '../../../../../../ui-extensions-react/src/surfaces/checkout/components/Heading/examples/basic-heading.example.tsx',
+          language: 'tsx',
+        },
+        {
+          title: 'JS',
+          code: './examples/basic-heading.example.ts',
+          language: 'js',
+        },
+      ],
+    },
+  },
+  subSections: [
+    {
+      type: 'Generic',
+      anchorLink: 'best-practices',
+      title: 'Best Practices',
+      sectionContent:
+        '- Add a heading at the top of each section that clearly describe what’s below.\n\n- Use the heading to highlight the most important concepts or pieces of information that customers need to know.',
+    },
+  ],
+  related: [
+    {
+      name: 'HeadingGroup',
+      subtitle: 'Component',
+      url: 'headinggroup',
+      type: 'Component',
+    },
+    {
+      name: 'Text',
+      subtitle: 'Component',
+      url: 'text',
+      type: 'Component',
+    },
+    {
+      name: 'TextBlock',
+      subtitle: 'Component',
+      url: 'textblock',
+      type: 'Component',
+    },
+  ],
+};
+
+export default data;

package/src/surfaces/checkout/components/Heading/examples/basic-heading.example.ts

@@ -1,6 +1,6 @@
-import {extend, Heading} from '@shopify/ui-extensions/checkout';
+import {extension, Heading} from '@shopify/ui-extensions/checkout';
 
-extend('Checkout::Dynamic::Render', (root) => {
+extension('Checkout::Dynamic::Render', (root) => {
   const heading = root.createComponent(Heading, undefined, 'Store name');
 
   root.appendChild(heading);

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

@@ -0,0 +1,63 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'HeadingGroup',
+  description:
+    'Heading group controls the heading level of headings nested within it, like H1, H2, H3.\n\nUse a heading group whenever you use a heading to ensure the experience is the same for screen reader users. When using a heading, any children related to that heading should be nested within the same heading group.',
+  thumbnail: 'headinggroup-thumbnail.png',
+  requires: '',
+  isVisualComponent: true,
+  type: '',
+  definitions: [],
+  category: 'Components',
+  subCategory: 'Titles and text',
+  defaultExample: {
+    image: 'headinggroup-default.png',
+    codeblock: {
+      title: 'Basic HeadingGroup',
+      tabs: [
+        {
+          title: 'React',
+          code: '../../../../../../ui-extensions-react/src/surfaces/checkout/components/HeadingGroup/examples/basic-headinggroup.example.tsx',
+          language: 'tsx',
+        },
+        {
+          title: 'JS',
+          code: './examples/basic-headinggroup.example.ts',
+          language: 'js',
+        },
+      ],
+    },
+  },
+  subSections: [
+    {
+      type: 'Generic',
+      anchorLink: 'best-practices',
+      title: 'Best Practices',
+      sectionContent:
+        '- Use this component to create a content hierarchy within the document outline.',
+    },
+  ],
+  related: [
+    {
+      name: 'Heading',
+      subtitle: 'Component',
+      url: 'heading',
+      type: 'Component',
+    },
+    {
+      name: 'Text',
+      subtitle: 'Component',
+      url: 'text',
+      type: 'Component',
+    },
+    {
+      name: 'TextBlock',
+      subtitle: 'Component',
+      url: 'textblock',
+      type: 'Component',
+    },
+  ],
+};
+
+export default data;

package/src/surfaces/checkout/components/HeadingGroup/examples/basic-headinggroup.example.ts

@@ -1,11 +1,11 @@
 import {
-  extend,
+  extension,
   HeadingGroup,
   Heading,
   View,
 } from '@shopify/ui-extensions/checkout';
 
-extend('Checkout::Dynamic::Render', (root) => {
+extension('Checkout::Dynamic::Render', (root) => {
   const headingGroup = root.createComponent(View, undefined, [
     root.createComponent(Heading, undefined, 'Heading <h1>'),
     root.createComponent(HeadingGroup, undefined, [

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

@@ -0,0 +1,57 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'Icon',
+  description:
+    'Icons are pictograms or graphic symbols. They can act as wayfinding tools or as a means of communicating functionality.',
+  thumbnail: 'icon-thumbnail.png',
+  requires: '',
+  isVisualComponent: true,
+  type: '',
+  definitions: [
+    {
+      title: 'IconProps',
+      description: '',
+      type: 'IconProps',
+    },
+  ],
+  category: 'Components',
+  subCategory: 'Media',
+  defaultExample: {
+    image: 'icon-default.png',
+    codeblock: {
+      title: 'Basic Icon',
+      tabs: [
+        {
+          title: 'React',
+          code: '../../../../../../ui-extensions-react/src/surfaces/checkout/components/Icon/examples/basic-icon.example.tsx',
+          language: 'tsx',
+        },
+        {
+          title: 'JS',
+          code: './examples/basic-icon.example.ts',
+          language: 'js',
+        },
+      ],
+    },
+  },
+  subSections: [
+    {
+      type: 'Generic',
+      anchorLink: 'icons',
+      title: 'Icons',
+      sectionContent:
+        '<img src="/assets/landing-pages/templated-apis/checkout-ui-extensions/ui-components/icon-all.png" />',
+    },
+    {
+      type: 'Generic',
+      anchorLink: 'appearance',
+      title: 'Appearance',
+      sectionContent:
+        '| Value | Description |\n| --- | --- |\n| <code>"accent"</code> | Conveys emphasis and draws attention to the element. |\n| <code>"interactive"</code> | Conveys that the element is pressable, hoverable or otherwise interactive. |\n| <code>"subdued"</code> | Conveys a subdued or disabled state for the element. |\n| <code>"info"</code> | Conveys that the element is informative or has information. |\n| <code>"success"</code> | Convey a successful interaction. |\n| <code>"warning"</code> | Convey something needs attention or an action needs to be taken. |\n| <code>"critical"</code> | Conveys a problem has arisen. |\n| <code>"monochrome"</code> | Takes the color of its parent.|',
+    },
+  ],
+  related: [],
+};
+
+export default data;

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

@@ -1,6 +1,6 @@
 import {createRemoteComponent} from '@remote-ui/core';
 
-import type {Appearance, Size} from '../shared';
+import type {Appearance, IdProps, Size} from '../shared';
 
 export type IconSource =
   | 'arrowLeft'
@@ -14,21 +14,30 @@ export type IconSource =
   | 'caretDown'
   | 'cart'
   | 'checkmark'
-  | 'chevronDown'
-  | 'chevronUp'
-  | 'chevronRight'
   | 'chevronLeft'
+  | 'chevronRight'
+  | 'chevronUp'
+  | 'chevronDown'
+  | 'clock'
   | 'close'
   | 'critical'
-  | 'discount'
+  | 'delete'
   | 'delivered'
   | 'delivery'
   | 'disabled'
+  | 'discount'
   | 'email'
+  | 'error'
   | 'errorFill'
+  | 'external'
+  | 'filter'
   | 'geolocation'
+  | 'gift'
+  /** @deprecated use gift instead */
+  | 'giftFill'
   | 'grid'
   | 'hamburger'
+  | 'hollowCircle'
   | 'horizontalDots'
   | 'info'
   | 'infoFill'
@@ -40,21 +49,22 @@ export type IconSource =
   | 'minus'
   | 'mobile'
   | 'note'
+  | 'orderBox'
   | 'pen'
-  | 'verticalDots'
   | 'plus'
+  | 'profile'
+  | 'question'
   | 'questionFill'
   | 'reorder'
+  | 'return'
   | 'store'
   | 'success'
   | 'truck'
+  | 'verticalDots'
   | 'warning'
-  | 'warningFill'
-  | 'giftFill'
-  | 'external'
-  | 'profile';
+  | 'warningFill';
 
-export interface IconProps {
+export interface IconProps extends IdProps {
   /**
    * A label that describes the purpose or contents of the icon. When set,
    * it will be announced to buyers using assistive technologies and will
@@ -80,6 +90,8 @@ export interface IconProps {
 
   /**
    * Specifies which icon to display
+   *
+   * Check the list of available icons [here](/docs/api/checkout-ui-extensions/components/media/icon#icons)
    */
   source: IconSource;
 }

package/src/surfaces/checkout/components/Icon/examples/basic-icon.example.ts

@@ -1,6 +1,6 @@
-import {extend, Icon} from '@shopify/ui-extensions/checkout';
+import {extension, Icon} from '@shopify/ui-extensions/checkout';
 
-extend('Checkout::Dynamic::Render', (root) => {
+extension('Checkout::Dynamic::Render', (root) => {
   const icon = root.createComponent(Icon, {source: 'discount'});
 
   root.appendChild(icon);

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

@@ -0,0 +1,49 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'Image',
+  description: 'Image is used for large format, responsive images.',
+  thumbnail: 'image-thumbnail.png',
+  requires: '',
+  isVisualComponent: true,
+  type: '',
+  definitions: [
+    {
+      title: 'ImageProps',
+      description: '',
+      type: 'ImageProps',
+    },
+  ],
+  category: 'Components',
+  subCategory: 'Media',
+  defaultExample: {
+    image: 'image-default.png',
+    codeblock: {
+      title: 'Basic Image',
+      tabs: [
+        {
+          title: 'React',
+          code: '../../../../../../ui-extensions-react/src/surfaces/checkout/components/Image/examples/basic-image.example.tsx',
+          language: 'tsx',
+        },
+        {
+          title: 'JS',
+          code: './examples/basic-image.example.ts',
+          language: 'js',
+        },
+      ],
+    },
+  },
+  subSections: [
+    {
+      type: 'Generic',
+      anchorLink: 'loading',
+      title: 'Loading',
+      sectionContent:
+        '| Value | Description |\n| --- | --- |\n| <code>"eager"</code> | Image is loaded immediately, regardless of whether or not the image is currently within the visible viewport. |\n| <code>"lazy"</code> | Image is loaded when it’s within the visible viewport. |',
+    },
+  ],
+  related: [],
+};
+
+export default data;