@shopify/ui-extensions 2022.10.5 → 2023.4.0

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

@@ -0,0 +1,42 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'Heading',
+  description:
+    "Use this to display a title. It's similar to the h1-h6 tags in HTML",
+  requires: '',
+  thumbnail: 'heading-thumbnail.png',
+  isVisualComponent: true,
+  type: '',
+  definitions: [
+    {
+      title: 'HeadingProps',
+      description: '',
+      type: 'HeadingProps',
+    },
+  ],
+  category: 'Components',
+  subCategory: 'Titles and text',
+  defaultExample: {
+    image: 'heading-default.png',
+    codeblock: {
+      title: 'TODO: add example title',
+      tabs: [
+        {
+          title: 'React',
+          code: '../../../../../../ui-extensions-react/src/surfaces/admin/components/Heading/examples/basic-Heading.example.tsx',
+          language: 'tsx',
+        },
+        {
+          title: 'JS',
+          code: './examples/basic-Heading.example.ts',
+          language: 'js',
+        },
+      ],
+    },
+  },
+
+  related: [],
+};
+
+export default data;

package/src/surfaces/admin/components/Heading/Heading.ts

@@ -0,0 +1,15 @@
+import {createRemoteComponent} from '@remote-ui/core';
+
+type Level = 1 | 2 | 3 | 4 | 5 | 6;
+
+export interface HeadingProps {
+  /** A unique identifier for the field. */
+  id?: string;
+
+  /** The visual level of the heading. */
+  size?: Level;
+}
+
+export const Heading = createRemoteComponent<'Heading', HeadingProps>(
+  'Heading',
+);

package/src/surfaces/admin/components/Heading/README.md

@@ -0,0 +1,9 @@
+# Heading
+
+Headings communicate the organization of the content on the page.
+
+## Note
+
+:exclamation: The `level` affects the visual level, but not the actual semantic heading HTML element (`<h1>`,`<h2>`, etc) that gets rendered by the browser. :exclamation:
+
+The specific heading element that gets rendered will be dynamically determined by the `HeadingGroup` component.

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

@@ -0,0 +1,7 @@
+import {extend, Heading} from '@shopify/ui-extensions/admin';
+
+extend('Playground', (root) => {
+  const heading = root.createComponent(Heading, undefined, 'Headings are cool');
+
+  root.appendChild(heading);
+});

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

@@ -0,0 +1,42 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'HeadingGroup',
+  description:
+    'This groups headings together, much like the hgroup element in HTML.',
+  requires: '',
+  thumbnail: 'headinggroup-thumbnail.png',
+  isVisualComponent: true,
+  type: '',
+  definitions: [
+    {
+      title: 'HeadingGroupProps',
+      description: '',
+      type: 'HeadingGroupProps',
+    },
+  ],
+  category: 'Components',
+  subCategory: 'Titles and text',
+  defaultExample: {
+    image: 'headinggroup-default.png',
+    codeblock: {
+      title: 'TODO: add example title',
+      tabs: [
+        {
+          title: 'React',
+          code: '../../../../../../ui-extensions-react/src/surfaces/admin/components/HeadingGroup/examples/basic-HeadingGroup.example.tsx',
+          language: 'tsx',
+        },
+        {
+          title: 'JS',
+          code: './examples/basic-HeadingGroup.example.ts',
+          language: 'js',
+        },
+      ],
+    },
+  },
+
+  related: [],
+};
+
+export default data;

package/src/surfaces/admin/components/HeadingGroup/HeadingGroup.ts

@@ -0,0 +1,8 @@
+import {createRemoteComponent} from '@remote-ui/core';
+
+export interface HeadingGroupProps {}
+
+export const HeadingGroup = createRemoteComponent<
+  'HeadingGroup',
+  HeadingGroupProps
+>('HeadingGroup');

package/src/surfaces/admin/components/HeadingGroup/README.md

@@ -0,0 +1,5 @@
+# HeadingGroup
+
+Heading group controls the heading level of headings nested within it, like H1, H2, H3.
+
+Use 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.

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

@@ -0,0 +1,20 @@
+import {
+    extend,
+    HeadingGroup,
+    Heading,
+    BlockStack,
+  } from '@shopify/ui-extensions/admin';
+
+  extend('Checkout::Dynamic::Render', (root) => {
+    const headingGroup = root.createComponent(BlockStack, undefined, [
+      root.createComponent(Heading, undefined, 'Heading <h1>'),
+      root.createComponent(HeadingGroup, undefined, [
+        root.createComponent(Heading, undefined, 'Heading <h2>'),
+        root.createComponent(HeadingGroup, undefined, [
+          root.createComponent(Heading, undefined, 'Heading <h3>'),
+        ]),
+      ]),
+    ]);
+
+    root.appendChild(headingGroup);
+  });

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

@@ -0,0 +1,42 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'Icon',
+  description:
+    'This component renders an icon from a predefined list. Choose the one that suits your needs.',
+  requires: '',
+  thumbnail: 'icon-thumbnail.png',
+  isVisualComponent: true,
+  type: '',
+  definitions: [
+    {
+      title: 'IconProps',
+      description: '',
+      type: 'IconProps',
+    },
+  ],
+  category: 'Components',
+  subCategory: 'Media',
+  defaultExample: {
+    image: 'icon-default.png',
+    codeblock: {
+      title: 'TODO: add example title',
+      tabs: [
+        {
+          title: 'React',
+          code: '../../../../../../ui-extensions-react/src/surfaces/admin/components/Icon/examples/basic-Icon.example.tsx',
+          language: 'tsx',
+        },
+        {
+          title: 'JS',
+          code: './examples/basic-Icon.example.ts',
+          language: 'js',
+        },
+      ],
+    },
+  },
+
+  related: [],
+};
+
+export default data;

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

@@ -0,0 +1,42 @@
+import {createRemoteComponent} from '@remote-ui/core';
+
+export interface IconProps {
+  /*
+   * A label that describes the purpose or contents of the icon. When set,
+   * it will be announced to users using assistive technologies and will
+   * provide them with more context.
+   */
+  accessibilityLabel?: string;
+
+  /*
+   * Set the color of the icon.
+   *
+   * - `inherit` will take the color value from its parent,
+   * giving the link a monochrome appearance.
+   *
+   * @defaultValue 'inherit'
+   */
+  tone?: 'inherit' | 'critical';
+
+  /** A unique identifier for the icon. */
+  id?: string;
+
+  /**
+   * Adjusts the size of the icon.
+   *
+   * @defaultValue 'base'
+   */
+  size?:
+    | 'base'
+    /**
+     * `fill` will take the space available in the container and keep the icon's proportion.
+     */
+    | 'fill';
+
+  /*
+   * Specifies the name of the icon that will be displayed.
+   */
+  name: string;
+}
+
+export const Icon = createRemoteComponent<'Icon', IconProps>('Icon');

package/src/surfaces/admin/components/Icon/README.md

@@ -0,0 +1,3 @@
+# Icon
+
+The Icon component is used to visually communicate core parts of the product and available actions. They can act as wayfinding tools to help users more easily understand where they are in the product, and common interaction patterns that are available.

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

@@ -0,0 +1,7 @@
+import {extend, Icon} from '@shopify/ui-extensions/admin';
+
+extend('Playground', (root) => {
+  const icon = root.createComponent(Icon, {name: 'AppsMajor'});
+
+  root.appendChild(icon);
+});

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

@@ -0,0 +1,41 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'Image',
+  description: 'Use this when you want to display an image.',
+  requires: '',
+  thumbnail: 'image-thumbnail.png',
+  isVisualComponent: true,
+  type: '',
+  definitions: [
+    {
+      title: 'ImageProps',
+      description: '',
+      type: 'ImageProps',
+    },
+  ],
+  category: 'Components',
+  subCategory: 'Media',
+  defaultExample: {
+    image: 'image-default.png',
+    codeblock: {
+      title: 'TODO: add example title',
+      tabs: [
+        {
+          title: 'React',
+          code: '../../../../../../ui-extensions-react/src/surfaces/admin/components/Image/examples/basic-Image.example.tsx',
+          language: 'tsx',
+        },
+        {
+          title: 'JS',
+          code: './examples/basic-Image.example.ts',
+          language: 'js',
+        },
+      ],
+    },
+  },
+
+  related: [],
+};
+
+export default data;

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

@@ -0,0 +1,120 @@
+import {createRemoteComponent} from '@remote-ui/core';
+import type {AccessibilityRole} from '../shared';
+
+export type ImageProps = (ImageAccessibilityLabelProp | ImageAltProp) &
+  (ImageSourceProp | ImageSrcProp) & {
+    /**
+     * Sets the semantic meaning of the component’s content. When set,
+     * the role will be used by assistive technologies to help users
+     * navigate the page.
+     */
+    accessibilityRole?: Extract<AccessibilityRole, 'decorative'>;
+
+    /**
+     * Defines a unique identifier which must be unique in the whole document.
+     *
+     * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id
+     */
+    id?: string;
+
+    /**
+     * Determines the loading behavior of the image:
+     * - `eager`: Immediately loads the image, irrespective of its position within the visible viewport.
+     * - `lazy`: Delays loading the image until it approaches a specified distance from the viewport.
+     *
+     * @defaultValue `eager`
+     * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#loading
+     */
+    loading?: 'eager' | 'lazy';
+
+    /**
+     * Invoked when load completes successfully.
+     *
+     * @see https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers/onload
+     */
+    onLoad?(): void;
+
+    /**
+     * Invoked on load error.
+     *
+     * @see https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers/onerror
+     */
+    onError?(): void;
+  };
+
+interface ImageAccessibilityLabelProp {
+  /**
+   * An alternative text description that describe the image for the reader to
+   * understand what it is about. It is extremely useful for both users using
+   * assistive technology and sighted users. A well written `description`
+   * provides people with visual impairments the ability to participate in
+   * consuming non-text content. When a screen readers encounters an `Image`,
+   * the description is read and announced aloud. If an image fails to load,
+   * potentially due to a poor connection, the `description` is displayed on
+   * screen instead. This has the benefit of letting a sighted user know an
+   * image was meant to load here, but as an alternative, they’re still able to
+   * consume the text content. Read
+   * [considerations when writing alternative text](https://ux.shopify.com/considerations-when-writing-alt-text-a9c1985a8204)
+   * to learn more.
+   *
+   * An `alt` property is available as an alias for this for compatibility with the HTML
+   * specification. When both are specified, `accessibilityLabel` takes precedence.
+   *
+   * @defaultValue `''`
+   * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#alt
+   */
+  accessibilityLabel: string;
+  alt?: never;
+}
+
+interface ImageAltProp {
+  /**
+   * An alternative text description that describe the image for the reader to
+   * understand what it is about. It is extremely useful for both users using
+   * assistive technology and sighted users. A well written `description`
+   * provides people with visual impairments the ability to participate in
+   * consuming non-text content. When a screen readers encounters an `Image`,
+   * the description is read and announced aloud. If an image fails to load,
+   * potentially due to a poor connection, the `description` is displayed on
+   * screen instead. This has the benefit of letting a sighted user know an
+   * image was meant to load here, but as an alternative, they’re still able to
+   * consume the text content. Read
+   * [considerations when writing alternative text](https://ux.shopify.com/considerations-when-writing-alt-text-a9c1985a8204)
+   * to learn more.
+   *
+   * This property is an alias for `accessibilityLabel` for compatibility with the HTML
+   * specification. When both are specified `accessibilityLabel` takes precedence.
+   *
+   * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#alt
+   */
+  alt: string;
+  accessibilityLabel?: never;
+}
+
+interface ImageSrcProp {
+  /**
+   * The image source (either a remote URL or a local file resource).
+   *
+   * This property is available as an alias for `source` for compatibility with the HTML
+   * specification. When both are specified, `source` takes precedence.
+   *
+   * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#src
+   */
+  src: string;
+  source?: never;
+}
+
+interface ImageSourceProp {
+  /**
+   * The image source (either a remote URL or a local file resource).
+   *
+   * A `src` property is available as an alias for this for compatibility with the HTML
+   * specification. When both are specified, `source` takes precedence.
+   *
+   * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#src
+   */
+  source: string;
+  src?: never;
+}
+
+export const Image = createRemoteComponent<'Image', ImageProps>('Image');

package/src/surfaces/admin/components/Image/README.md

@@ -0,0 +1,20 @@
+# Image
+
+The Image component is used to embed an image into the document and control its presentation. It should be used for large format, responsive images.
+
+## Examples
+
+### Basic usage
+
+```tsx
+export function MyComponent() {
+  return (
+    <Image
+      // or accessibilityLabel
+      alt="A red shirt"
+      // or source
+      src="https://cdn.shopify.com/s/files/1/0757/9955/files/empty-state.svg"
+    />
+  );
+}
+```

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

@@ -0,0 +1,10 @@
+import {extend, Image} from '@shopify/ui-extensions/admin';
+
+extend('Playground', (root) => {
+  const image = root.createComponent(Image, {
+    source:
+      'https://shopify.dev/assets/api/ui-extensions/admin/components/image-example-code.png',
+  });
+
+  root.appendChild(image);
+});

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

@@ -0,0 +1,41 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'InlineStack',
+  description:
+    "Use this to organize layout elements along the horizontal axis of the page. It's great for horizontal alignment.",
+  requires: '',
+  thumbnail: 'inlinestack-thumbnail.png',
+  isVisualComponent: true,
+  type: '',
+  definitions: [
+    {
+      title: 'InlineStackProps',
+      description: '',
+      type: 'InlineStackProps',
+    },
+  ],
+  category: 'Components',
+  subCategory: 'Structure',
+  defaultExample: {
+    image: 'inlinestack-default.png',
+    codeblock: {
+      title: 'Laying out elements in a row',
+      tabs: [
+        {
+          title: 'React',
+          code: '../../../../../../ui-extensions-react/src/surfaces/admin/components/InlineStack/examples/basic-inlinestack.example.tsx',
+          language: 'tsx',
+        },
+        {
+          title: 'JS',
+          code: './examples/basic-inlinestack.example.ts',
+          language: 'js',
+        },
+      ],
+    },
+  },
+  related: [],
+};
+
+export default data;

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

@@ -0,0 +1,28 @@
+import {createRemoteComponent} from '@remote-ui/core';
+
+import {
+  AccessibilityRoleProps,
+  GlobalProps,
+  SizingProps,
+  PaddingProps,
+  GapProps,
+} from '../shared';
+
+export interface InlineStackProps
+  extends AccessibilityRoleProps,
+    GapProps,
+    GlobalProps,
+    SizingProps,
+    PaddingProps {
+  /**
+   * 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;
+}
+
+export const InlineStack = createRemoteComponent<
+  'InlineStack',
+  InlineStackProps
+>('InlineStack');

package/src/surfaces/admin/components/InlineStack/examples/basic-inlinestack.example.ts

@@ -0,0 +1,18 @@
+import {extension, InlineStack} from '@shopify/ui-extensions/admin';
+
+export default extension('Playground', (root) => {
+  const inlineStack = root.createComponent(
+    InlineStack,
+    {
+      gap: 'base',
+    },
+    [
+      root.createText('Child 1'),
+      root.createText('Child 2'),
+      root.createText('Child 3'),
+      root.createText('Child 4'),
+    ],
+  );
+
+  root.appendChild(inlineStack);
+});

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

@@ -0,0 +1,103 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'Link',
+  description:
+    'This is an interactive component that directs users to a specified URL. It even supports custom protocols.',
+  requires: '',
+  thumbnail: 'link-thumbnail.png',
+  isVisualComponent: true,
+  type: '',
+  definitions: [
+    {
+      title: 'LinkProps',
+      description: '',
+      type: 'LinkProps',
+    },
+  ],
+  category: 'Components',
+  subCategory: 'Actions',
+  defaultExample: {
+    image: 'link-default.png',
+    codeblock: {
+      title: 'TODO: add example title',
+      tabs: [
+        {
+          title: 'React',
+          code: '../../../../../../ui-extensions-react/src/surfaces/admin/components/Link/examples/app-link.example.tsx',
+          language: 'tsx',
+        },
+        {
+          title: 'JS',
+          code: './examples/app-link.example.ts',
+          language: 'js',
+        },
+      ],
+    },
+  },
+  examples: {
+    description: '',
+    examples: [
+      {
+        description: 'TODO: add description',
+        image: 'external-link.png',
+        codeblock: {
+          tabs: [
+            {
+              title: 'React',
+              code: '../../../../../../ui-extensions-react/src/surfaces/admin/components/Link/examples/external-link.example.tsx',
+              language: 'typescript',
+            },
+            {
+              title: 'JS',
+              code: './examples/external-link.example.ts',
+              language: 'typescript',
+            },
+          ],
+          title: 'TODO: add example title',
+        },
+      },
+      {
+        description: 'TODO: add description',
+        image: 'relative-link.png',
+        codeblock: {
+          tabs: [
+            {
+              title: 'React',
+              code: '../../../../../../ui-extensions-react/src/surfaces/admin/components/Link/examples/relative-link.example.tsx',
+              language: 'typescript',
+            },
+            {
+              title: 'JS',
+              code: './examples/relative-link.example.ts',
+              language: 'typescript',
+            },
+          ],
+          title: 'TODO: add example title',
+        },
+      },
+      {
+        description: 'TODO: add description',
+        image: 'shopify-section-link.png',
+        codeblock: {
+          tabs: [
+            {
+              title: 'React',
+              code: '../../../../../../ui-extensions-react/src/surfaces/admin/components/Link/examples/shopify-section-link.example.tsx',
+              language: 'typescript',
+            },
+            {
+              title: 'JS',
+              code: './examples/shopify-section-link.example.ts',
+              language: 'typescript',
+            },
+          ],
+          title: 'TODO: add example title',
+        },
+      },
+    ],
+  },
+  related: [],
+};
+
+export default data;