@shopify/ui-extensions 2022.10.5 → 2023.4.0

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

@@ -0,0 +1,52 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+import {getExample} from '../../helper.docs';
+
+const loadingSkeletons = getExample('ui-components/loading-skeletons', [
+  'jsx',
+  'js',
+]);
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'SkeletonImage',
+  description:
+    'SkeletonImage is used to provide a low fidelity representation of an image before it appears on the page.',
+  requires: '',
+  thumbnail: 'skeletonimage-thumbnail.png',
+  isVisualComponent: true,
+  type: '',
+  definitions: [
+    {
+      title: 'SkeletonImageProps',
+      description: '',
+      type: 'SkeletonImageProps',
+    },
+  ],
+  category: 'Components',
+  subCategory: 'Feedback',
+  defaultExample: {
+    image: 'skeletonimage-default.png',
+    codeblock: {
+      title: 'Basic SkeletonImage',
+      tabs: [
+        {
+          title: 'React',
+          code: '../../../../../../ui-extensions-react/src/surfaces/checkout/components/SkeletonImage/examples/basic-skeletonimage.example.tsx',
+          language: 'tsx',
+        },
+        {
+          title: 'JS',
+          code: './examples/basic-skeletonimage.example.ts',
+          language: 'js',
+        },
+      ],
+    },
+  },
+  examples: {
+    description: '',
+    examples: [loadingSkeletons],
+  },
+  related: [],
+};
+
+export default data;

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

@@ -1,18 +1,17 @@
 import {createRemoteComponent} from '@remote-ui/core';
 
 import {MaybeResponsiveConditionalStyle} from '../../style';
+import type {IdProps} from '../shared';
 
-export interface SkeletonImageProps {
+export interface SkeletonImageProps extends IdProps {
   /**
    * Adjust the block size of the skeleton.
    */
   blockSize?: MaybeResponsiveConditionalStyle<number | `${number}%` | 'fill'>;
-
   /**
    * Adjust the inline size of the skeleton.
    */
   inlineSize?: MaybeResponsiveConditionalStyle<number | `${number}%` | 'fill'>;
-
   /**
    * Displays the skeleton at the specified aspect ratio (fills the width of the
    * parent container and sets the height accordingly).

package/src/surfaces/checkout/components/SkeletonImage/examples/basic-skeletonimage.example.ts

@@ -1,6 +1,6 @@
-import {extend, SkeletonImage} from '@shopify/ui-extensions/checkout';
+import {extension, SkeletonImage} from '@shopify/ui-extensions/checkout';
 
-extend('Checkout::Dynamic::Render', (root) => {
+extension('Checkout::Dynamic::Render', (root) => {
   const skeletonImage = root.createComponent(SkeletonImage, {
     inlineSize: 300,
     blockSize: 300,

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

@@ -0,0 +1,52 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+import {getExample} from '../../helper.docs';
+
+const loadingSkeletons = getExample('ui-components/loading-skeletons', [
+  'jsx',
+  'js',
+]);
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'SkeletonText',
+  description:
+    'SkeletonText is used to provide a low fidelity representation of text content before it appears on the page. \n\nOptionally you can use any text content inside `SkeletonText` to be used as a base for the rendered skeleton',
+  requires: '',
+  isVisualComponent: true,
+  thumbnail: 'skeletontext-thumbnail.png',
+  type: '',
+  definitions: [
+    {
+      title: 'SkeletonTextProps',
+      description: '',
+      type: 'SkeletonTextProps',
+    },
+  ],
+  category: 'Components',
+  subCategory: 'Feedback',
+  defaultExample: {
+    image: 'skeletontext-default.png',
+    codeblock: {
+      title: 'Basic SkeletonText',
+      tabs: [
+        {
+          title: 'React',
+          code: '../../../../../../ui-extensions-react/src/surfaces/checkout/components/SkeletonText/examples/basic-skeletontext.example.tsx',
+          language: 'tsx',
+        },
+        {
+          title: 'JS',
+          code: './examples/basic-skeletontext.example.ts',
+          language: 'js',
+        },
+      ],
+    },
+  },
+  examples: {
+    description: '',
+    examples: [loadingSkeletons],
+  },
+  related: [],
+};
+
+export default data;

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

@@ -1,10 +1,10 @@
 import {createRemoteComponent} from '@remote-ui/core';
 
-import type {Size} from '../shared';
-import type {TextProps} from '../Text/Text';
+import type {IdProps, TextSize, Size} from '../shared';
 
-export interface SkeletonTextProps extends Pick<TextProps, 'size'> {
+export interface SkeletonTextProps extends IdProps {
   /**
+   * @private
    * Use to emphasize a word or a group of words.
    */
   emphasis?: 'bold';
@@ -12,6 +12,10 @@ export interface SkeletonTextProps extends Pick<TextProps, 'size'> {
    * Adjust the length of the text when no children are passed.
    */
   inlineSize?: Extract<Size, 'small' | 'base' | 'large'>;
+  /**
+   * Size of the text the skeleton replaces.
+   */
+  size?: TextSize;
 }
 
 /**

package/src/surfaces/checkout/components/SkeletonText/examples/basic-skeletontext.example.ts

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

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

@@ -0,0 +1,41 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'SkeletonTextBlock',
+  description:
+    'SkeletonTextBlock is used to provide a low fidelity representation of a block of text before it appears on the page. \n\nOptionally you can use any text content inside `SkeletonTextBlock` to be used as a base for the rendered skeleton',
+  requires: '',
+  isVisualComponent: true,
+  thumbnail: 'skeletontextblock-thumbnail.png',
+  type: '',
+  definitions: [
+    {
+      title: 'SkeletonTextBlockProps',
+      description: '',
+      type: 'SkeletonTextBlockProps',
+    },
+  ],
+  category: 'Components',
+  subCategory: 'Feedback',
+  defaultExample: {
+    image: 'skeletontextblock-default.png',
+    codeblock: {
+      title: 'Basic SkeletonTextBlock',
+      tabs: [
+        {
+          title: 'React',
+          code: '../../../../../../ui-extensions-react/src/surfaces/checkout/components/SkeletonTextBlock/examples/basic-skeletontextblock.example.tsx',
+          language: 'tsx',
+        },
+        {
+          title: 'JS',
+          code: './examples/basic-skeletontextblock.example.ts',
+          language: 'js',
+        },
+      ],
+    },
+  },
+  related: [],
+};
+
+export default data;

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

@@ -1,9 +1,10 @@
 import {createRemoteComponent} from '@remote-ui/core';
 
-import type {TextBlockProps} from '../TextBlock/TextBlock';
+import type {IdProps, TextSize} from '../shared';
 
-export interface SkeletonTextBlockProps extends Pick<TextBlockProps, 'size'> {
+export interface SkeletonTextBlockProps extends IdProps {
   /**
+   * @private
    * Use to emphasize a word or a group of words.
    */
   emphasis?: 'bold';
@@ -13,6 +14,10 @@ export interface SkeletonTextBlockProps extends Pick<TextBlockProps, 'size'> {
    * @defaultValue 1
    */
   lines?: number;
+  /**
+   * Size of the text the skeleton replaces.
+   */
+  size?: TextSize;
 }
 
 /**

package/src/surfaces/checkout/components/SkeletonTextBlock/examples/basic-skeletontextblock.example.ts

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

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

@@ -0,0 +1,50 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'Spinner',
+  description:
+    'Spinner is used to notify buyers that their action is being processed. The Spinner is usually used when sending or receiving data from a server.',
+  requires: '',
+  thumbnail: 'spinner-thumbnail.png',
+  isVisualComponent: true,
+  type: '',
+  definitions: [
+    {
+      title: 'SpinnerProps',
+      description: '',
+      type: 'SpinnerProps',
+    },
+  ],
+  category: 'Components',
+  subCategory: 'Feedback',
+  defaultExample: {
+    image: 'spinner-default.png',
+    codeblock: {
+      title: 'Basic Spinner',
+      tabs: [
+        {
+          title: 'React',
+          code: '../../../../../../ui-extensions-react/src/surfaces/checkout/components/Spinner/examples/basic-spinner.example.tsx',
+          language: 'tsx',
+        },
+        {
+          title: 'JS',
+          code: './examples/basic-spinner.example.ts',
+          language: 'js',
+        },
+      ],
+    },
+  },
+  subSections: [
+    {
+      type: 'Generic',
+      anchorLink: 'appearance',
+      title: 'Appearance',
+      sectionContent:
+        '| 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: [],
+};
+
+export default data;

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

@@ -1,8 +1,8 @@
 import {createRemoteComponent} from '@remote-ui/core';
 
-import type {Size, Appearance} from '../shared';
+import type {Appearance, IdProps, Size} from '../shared';
 
-export interface SpinnerProps {
+export interface SpinnerProps extends IdProps {
   /**
    * Adjusts the size of the icon.
    *

package/src/surfaces/checkout/components/Spinner/examples/basic-spinner.example.ts

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

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

@@ -0,0 +1,50 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'Stepper',
+  description:
+    'Use a stepper to increase or decrease a value, like changing the quantity from 1 to 2.',
+  requires: '',
+  thumbnail: 'stepper-thumbnail.png',
+  isVisualComponent: true,
+  type: '',
+  definitions: [
+    {
+      title: 'StepperProps',
+      description: '',
+      type: 'StepperProps',
+    },
+  ],
+  category: 'Components',
+  subCategory: 'Forms',
+  defaultExample: {
+    image: 'stepper-default.png',
+    codeblock: {
+      title: 'Basic Stepper',
+      tabs: [
+        {
+          title: 'React',
+          code: '../../../../../../ui-extensions-react/src/surfaces/checkout/components/Stepper/examples/basic-stepper.example.tsx',
+          language: 'tsx',
+        },
+        {
+          title: 'JS',
+          code: './examples/basic-stepper.example.ts',
+          language: 'js',
+        },
+      ],
+    },
+  },
+  subSections: [
+    {
+      type: 'Generic',
+      anchorLink: 'best-practices',
+      title: 'Best Practices',
+      sectionContent:
+        '- Use this component when customers are likely to choose a number within a small range, such as when changing a quantity from one to three.\n\n- If there’s no default number, then consider choosing another component such as a TextField or Select.',
+    },
+  ],
+  related: [],
+};
+
+export default data;

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

@@ -1,31 +1,41 @@
 import {createRemoteComponent} from '@remote-ui/core';
 
-import type {TextFieldProps} from '../TextField/TextField';
-import type {IconSource} from '../Icon/Icon';
-
-export interface StepperProps
-  extends Pick<
-    TextFieldProps<number | undefined>,
-    | 'id'
-    | 'name'
-    | 'label'
-    | 'prefix'
-    | 'accessibilityDescription'
-    | 'required'
-    | 'error'
-    | 'disabled'
-    | 'readonly'
-    | 'value'
-    | 'onFocus'
-    | 'onBlur'
-    | 'onInput'
-    | 'onChange'
-  > {
+import {IconSource} from '../Icon/Icon';
+
+export interface StepperProps {
+  /**
+   * A detailed description for screen readers.
+   */
+  accessibilityDescription?: string;
+
+  /**
+   * 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;
+
+  /**
+   * Content to use as the field label. This value is also used as the placeholder
+   * when the field is empty.
+   */
+  label: string;
+
   /**
    * An icon to render at the start of the field.
    */
   icon?: IconSource;
 
+  /**
+   * A unique identifier for the field. When no `id` is set,
+   * a globally unique value will be used instead.
+   */
+  id?: string;
+
   /**
    * The highest decimal or integer to be accepted for the stepper field.
    * When used with `step` the value will round down to the max number.
@@ -44,6 +54,30 @@ export interface StepperProps
    */
   min?: number;
 
+  /**
+   * An identifier for the field that is unique within the nearest
+   * containing `Form` component.
+   */
+  name?: string;
+
+  /**
+   * Text content to render before the value.
+   */
+  prefix?: 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 amount the value can increase or decrease by. This can be an integer or decimal.
    * If a `max` or `min` is specified with `step` when increasing/decreasing the value
@@ -53,6 +87,64 @@ export interface StepperProps
    * @defaultValue 1
    */
   step?: number;
+
+  /**
+   * 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?: number | undefined;
+
+  /**
+   * Callback when input is focused.
+   */
+  onFocus?(): void;
+
+  /**
+   * Callback when focus is removed.
+   */
+  onBlur?(): void;
+
+  /**
+   * Callback when the buyer has **finished editing** a field. Unlike `onChange`
+   * callbacks you may be familiar with from Polaris or other React component libraries,
+   * this callback is **not** run on every change to the input. Text fields are
+   * “partially controlled” components, which means that while the buyer edits the
+   * field, its state is controlled by the component. Once the buyer has signalled that
+   * they have finished editing the field (typically, by blurring the field), `onChange`
+   * is called if the input actually changed from the most recent `value` property. At
+   * that point, you are expected to store this “committed value” in state, and reflect
+   * it in the text field’s `value` property.
+   *
+   * This state management model is important given how UI Extensions are rendered. UI Extension components
+   * run on a separate thread from the UI, so they can’t respond to input synchronously.
+   * A pattern popularized by [controlled React components](https://reactjs.org/docs/forms.html#controlled-components)
+   * is to have the component be the source of truth for the input `value`, and update
+   * the `value` on every user input. The delay in responding to events from a UI
+   * extension is only a few milliseconds, but attempting to strictly store state with
+   * this delay can cause issues if a user types quickly, or if the buyer is using a
+   * lower-powered device. Having the UI thread take ownership for “in progress” input,
+   * and only synchronizing when the user is finished with a field, avoids this risk.
+   *
+   * It can still sometimes be useful to be notified when the user makes any input in
+   * the field. If you need this capability, you can use the `onInput` prop. However,
+   * never use that property to create tightly controlled state for the `value`.
+   *
+   * This callback is called with the current value of the field. If the value of a field
+   * is the same as the current `value` prop provided to the field, the `onChange` callback
+   * will not be run.
+   */
+  onChange?(value: number | undefined): void;
+
+  /**
+   * Callback when the user makes any changes in the field. As noted in the documentation
+   * for `onChange`, you **must not** use this to update `state` — use the `onChange`
+   * callback for that purpose. Use the `onInput` prop when you need to do something
+   * as soon as the buyer makes a change, like clearing validation errors that apply to
+   * the field as soon as the user begins making the necessary adjustments.
+   *
+   * This callback is called with the current value of the field.
+   */
+  onInput?(value: number | undefined): void;
 }
 
 /**

package/src/surfaces/checkout/components/Stepper/examples/basic-stepper.example.ts

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

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

@@ -0,0 +1,41 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'Tag',
+  description:
+    'A Tag is used to help label, organize or categorize objects. It is commonly used in Checkout to display the discounts applied to a cart.',
+  requires: '',
+  thumbnail: 'tag-thumbnail.png',
+  isVisualComponent: true,
+  type: '',
+  definitions: [
+    {
+      title: 'TagProps',
+      description: '',
+      type: 'TagProps',
+    },
+  ],
+  category: 'Components',
+  subCategory: 'Other',
+  defaultExample: {
+    image: 'tag-default.png',
+    codeblock: {
+      title: 'Basic Tag',
+      tabs: [
+        {
+          title: 'React',
+          code: '../../../../../../ui-extensions-react/src/surfaces/checkout/components/Tag/examples/basic-tag.example.tsx',
+          language: 'tsx',
+        },
+        {
+          title: 'JS',
+          code: './examples/basic-tag.example.ts',
+          language: 'js',
+        },
+      ],
+    },
+  },
+  related: [],
+};
+
+export default data;

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

@@ -1,8 +1,9 @@
 import {createRemoteComponent} from '@remote-ui/core';
 
-import type {IconSource} from '../Icon/Icon';
+import {IconSource} from '../Icon/Icon';
+import type {IdProps} from '../shared';
 
-export interface TagProps {
+export interface TagProps extends IdProps {
   children?: string;
   /**
    * Icon source
@@ -10,8 +11,7 @@ export interface TagProps {
   icon?: IconSource;
   /**
    * 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/Tag/examples/basic-tag.example.ts

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